feat(enforce): T5 — Rule #2 coverage-tag-verified-against-artifacts (Stop)

tools/enforce-coverage-verify.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * Rule #2 — Coverage tag verified against artifacts (Stop hook).
+ *
+ * Reads transcript at Stop event. Parses `coverage: <channel>:<id>` from last
+ * assistant text. Then:
+ *   - channel=skill / id=X — require Skill tool_use with input.skill === X
+ *   - channel=node — accept any tool_use that produced work (>= 1 mutating tool)
+ *   - channel=direct — accept (Rule #8 handles direct-vs-classifier mismatch)
+ *   - channel=chain / hook / agent — accept (lighter discipline)
+ *   - missing coverage line — block
+ *
+ * Override: "без скилов" / "direct ok" suppress this rule.
+ *
+ * NB: only fires when the assistant ACTUALLY did some work (>=1 tool_use).
+ * Pure conversational turns (no tool calls) pass without coverage requirement.
+ *
+ * Spec: docs/superpowers/specs/2026-05-25-enforce-hard-rules-design.md
+ */
+
+import {
+  readStdin,
+  parseEventJson,
+  readTranscript,
+  lastUserPromptText,
+  lastAssistantText,
+  parseCoverageLine,
+  turnToolUses,
+  findOverride,
+  logOverride,
+  exitDecision,
+} from './enforce-hook-helpers.mjs';
+
+const RULE_KEY = 'coverage-skill-match';
+
+const MUTATING_TOOLS = new Set([
+  'Edit', 'Write', 'MultiEdit', 'NotebookEdit', 'Bash',
+]);
+
+export function decide({
+  toolUses, assistantText, override,
+}) {
+  // Pure conversational turn — skip.
+  const hasMutating = toolUses.some((u) => MUTATING_TOOLS.has(u.name));
+  if (!hasMutating) return { block: false };
+  if (override) return { block: false };
+
+  const cov = parseCoverageLine(assistantText);
+  if (!cov) {
+    return {
+      block: true,
+      message: [
+        `[enforce-coverage-verify] Turn performed mutating tool calls but assistant response has no \`coverage:\` line.`,
+        `Add as first line of next response:`,
+        `  coverage: skill:<name>   (e.g., skill:superpowers:test-driven-development)`,
+        `  coverage: direct:<role>  (e.g., direct:memory-sync, direct:git-recovery)`,
+        ``,
+        `Override: include "без скилов" or "direct ok" in your prompt.`,
+      ].join('\n'),
+    };
+  }
+
+  if (cov.channel === 'skill') {
+    const found = toolUses.some((u) => u.name === 'Skill' && u.input && (u.input.skill === cov.id || u.input.skill === cov.id.replace(/^superpowers:/, '')));
+    if (!found) {
+      return {
+        block: true,
+        message: [
+          `[enforce-coverage-verify] coverage says skill:${cov.id} but the Skill tool was never invoked with that name in this turn.`,
+          `Either invoke the skill via Skill tool, or switch coverage to direct:<role> with justification.`,
+        ].join('\n'),
+      };
+    }
+    return { block: false };
+  }
+
+  // direct / node / chain / hook / agent — accepted at this layer.
+  return { block: false };
+}
+
+async function main() {
+  try {
+    const raw = await readStdin();
+    const event = parseEventJson(raw);
+    const transcript = readTranscript(event.transcript_path);
+    const userPrompt = lastUserPromptText(transcript);
+    const override = findOverride(userPrompt, RULE_KEY);
+    if (override) logOverride(RULE_KEY, override, event.session_id);
+
+    const toolUses = turnToolUses(transcript);
+    const assistantText = lastAssistantText(transcript);
+
+    const result = decide({ toolUses, assistantText, override });
+    exitDecision(result);
+  } catch {
+    exitDecision({ block: false });
+  }
+}
+
+const isCli = process.argv[1] && process.argv[1].replace(/\\/g, '/').endsWith('/enforce-coverage-verify.mjs');
+if (isCli) main();

tools/enforce-coverage-verify.test.mjs

@@ -0,0 +1,74 @@
+import { describe, it, expect } from 'vitest';
+import { decide } from './enforce-coverage-verify.mjs';
+
+describe('enforce-coverage-verify / decide', () => {
+  it('allows turn with no mutating tools (pure conversational)', () => {
+    const r = decide({ toolUses: [{ name: 'Read', input: {} }], assistantText: 'just talking' });
+    expect(r.block).toBe(false);
+  });
+
+  it('blocks mutating turn with no coverage line', () => {
+    const r = decide({
+      toolUses: [{ name: 'Edit', input: { file_path: 'foo.mjs' } }],
+      assistantText: 'just did some work',
+    });
+    expect(r.block).toBe(true);
+    expect(r.message).toMatch(/no.*coverage/);
+  });
+
+  it('blocks when coverage says skill but Skill tool not invoked', () => {
+    const r = decide({
+      toolUses: [{ name: 'Edit', input: { file_path: 'foo.mjs' } }],
+      assistantText: 'coverage: skill:superpowers:test-driven-development\nдалее…',
+    });
+    expect(r.block).toBe(true);
+    expect(r.message).toMatch(/Skill tool was never invoked/);
+  });
+
+  it('allows when coverage says skill and Skill tool invoked with matching name', () => {
+    const r = decide({
+      toolUses: [
+        { name: 'Skill', input: { skill: 'superpowers:test-driven-development' } },
+        { name: 'Edit', input: { file_path: 'foo.mjs' } },
+      ],
+      assistantText: 'coverage: skill:superpowers:test-driven-development\nок',
+    });
+    expect(r.block).toBe(false);
+  });
+
+  it('allows when coverage matches without superpowers: prefix in tool input', () => {
+    const r = decide({
+      toolUses: [
+        { name: 'Skill', input: { skill: 'test-driven-development' } },
+        { name: 'Edit', input: { file_path: 'foo.mjs' } },
+      ],
+      assistantText: 'coverage: skill:superpowers:test-driven-development',
+    });
+    expect(r.block).toBe(false);
+  });
+
+  it('allows direct coverage', () => {
+    const r = decide({
+      toolUses: [{ name: 'Edit', input: { file_path: 'memory/foo.md' } }],
+      assistantText: 'coverage: direct:memory-sync',
+    });
+    expect(r.block).toBe(false);
+  });
+
+  it('allows node coverage', () => {
+    const r = decide({
+      toolUses: [{ name: 'Edit', input: { file_path: 'foo.vue' } }],
+      assistantText: 'coverage: node:#19',
+    });
+    expect(r.block).toBe(false);
+  });
+
+  it('allows when override phrase present', () => {
+    const r = decide({
+      toolUses: [{ name: 'Edit', input: { file_path: 'foo.mjs' } }],
+      assistantText: 'no coverage',
+      override: { phrase: 'без скилов', suppresses: ['coverage-skill-match'] },
+    });
+    expect(r.block).toBe(false);
+  });
+});