@event4u/agent-config 9.22.0 → 9.24.0

package/src/scripts/hook_manifest.yaml

@@ -18,6 +18,7 @@ concerns:
     script: src/scripts/chat_history.ts
     args: [hook-dispatch]
     fail_closed: false
+    severity: advisory
   # Hot-context working-memory cache (road-to-second-brain Phase 1).
   # stop: deterministic, redacted 400-word overwrite of
   # agents/runtime/state/hot-context.md from the chat-history JSONL.
@@ -30,6 +31,7 @@ concerns:
     script: src/scripts/hot_context_hook.ts
     args: []
     fail_closed: false
+    severity: advisory
   # One-shot handoff injection (road-to-agent-handoff-resume Phase 3).
   # session_start only: if `agent-config handoff` wrote
   # agents/runtime/state/handoff-context.md, inject it as spotlighted DATA
@@ -40,18 +42,22 @@ concerns:
     script: src/scripts/handoff_context_hook.ts
     args: []
     fail_closed: false
+    severity: advisory
   roadmap-progress:
     script: src/scripts/roadmap_progress_hook.ts
     args: []
     fail_closed: false
+    severity: advisory
   onboarding-gate:
     script: src/scripts/onboarding_gate_hook.ts
     args: []
     fail_closed: false
+    severity: advisory
   context-hygiene:
     script: src/scripts/context_hygiene_hook.ts
     args: []
     fail_closed: false
+    severity: advisory
   # Phase 5 — Tier-1 hook for the verify-before-complete rule. Records
   # observable evidence of verification commands (tests, quality tools,
   # builds) into agents/runtime/state/verify-before-complete.json. The rule body
@@ -60,6 +66,7 @@ concerns:
     script: src/scripts/before_complete_hook.ts
     args: []
     fail_closed: false
+    severity: advisory
   # Phase 5 — Tier-1 hook for the minimal-safe-diff rule. Counts unique
   # files touched per turn into agents/runtime/state/minimal-safe-diff.json and
   # flips warning=true past hooks.minimal_safe_diff.threshold.
@@ -67,6 +74,7 @@ concerns:
     script: src/scripts/minimal_safe_diff_hook.ts
     args: []
     fail_closed: false
+    severity: advisory
   # road-to-security-pillar.md P3.2 — PostToolUse prompt-injection scanner.
   # Warn-in-context (exit 2), never blocks. Default-OFF: no-ops unless
   # hooks.injection_scan.enabled is true in .agent-settings.yml. The runtime
@@ -75,6 +83,7 @@ concerns:
     script: src/scripts/injection_scan_hook.ts
     args: []
     fail_closed: false
+    severity: advisory
   # road-to-security-hardening Phase 3 — PreToolUse guard turning the
   # git-history-discipline Iron Law into a deterministic gate. Blocks
   # `git … --no-verify` / `-n` and `git -c core.hooksPath=…` (which would
@@ -86,6 +95,7 @@ concerns:
     script: src/scripts/hooks/block_no_verify.ts
     args: []
     fail_closed: true
+    severity: blocking
   # road-to-ai-employee-borrowings Phase 1 — kernel immutability Layer 1.
   # PreToolUse guard: DENIES Write/Edit/NotebookEdit (and cross-platform
   # equivalents) whose target path is a kernel rule file — the source tree
@@ -101,6 +111,7 @@ concerns:
     script: src/scripts/hooks/block_kernel_rule_writes.ts
     args: []
     fail_closed: true
+    severity: blocking
   # road-to-renewal-leverage Phase 2 — "fix the code, not the config".
   # PreToolUse guard over the recorded allowlist-growth antipattern
   # (autonomous-execution § Antipattern): warns as an allowlist grows within a
@@ -115,6 +126,7 @@ concerns:
     script: src/scripts/hooks/block_config_weakening.ts
     args: []
     fail_closed: false
+    severity: blocking
   # token-saving Phase 3 — PreToolUse RTK-wrap nudge. DETERMINISTIC: keys off a
   # live `which rtk` probe (not the self-reported flag). When rtk is installed
   # and the agent is about to run a single verbose CLI command that is NOT
@@ -127,6 +139,7 @@ concerns:
     script: src/scripts/hooks/rtk_wrap_hook.ts
     args: []
     fail_closed: false
+    severity: advisory
   # road-to-anti-slop-detector Phase 3 — OPTIONAL PreToolUse anti-slop nudge.
   # Runs the lint_design_slop registry against about-to-be-written UI content
   # and WARNS (exit 2) on P0/P1 aesthetic tells. Never blocks (flags, not
@@ -138,6 +151,7 @@ concerns:
     script: src/scripts/hooks/design_slop_hook.ts
     args: []
     fail_closed: false
+    severity: advisory
   # ADR-124 Phase 4 — OPTIONAL PreToolUse code-graph nudge. When a code-graph
   # source is present and the agent is about to search/read source, WARNS
   # (exit 2) once per session to query the graph first (or rebuild if stale,
@@ -148,6 +162,7 @@ concerns:
     script: src/scripts/hooks/code_graph_nudge_hook.ts
     args: []
     fail_closed: false
+    severity: advisory
   # road-to-reachable-code-memory Phase 4 — session_end learning-sidecar
   # aggregation. Joins the EXISTING session_end concern set (no new platform
   # wiring). Aggregates agents/memory/intake/*.jsonl through the learning
@@ -161,6 +176,7 @@ concerns:
     script: src/scripts/memory_learn_hook.ts
     args: []
     fail_closed: false
+    severity: advisory
   # Phase 2 of road-to-hooks-actually-fire-in-consumers — session_start
   # gate that surfaces the marketplace-install-but-unscaffolded shape.
   # Writes .augment/.first-run-action-needed.md + one stderr line so
@@ -170,6 +186,7 @@ concerns:
     script: src/scripts/first_run_gate_hook.ts
     args: []
     fail_closed: false
+    severity: advisory
   # session-profile-activation Phase 1 — emits a one-line staleness notice
   # when a new session starts with a `runtime.active_packs` overlay carried
   # over from a previous session. Never resets (option a, explicit
@@ -178,6 +195,7 @@ concerns:
     script: src/scripts/profile_staleness_hook.ts
     args: []
     fail_closed: false
+    severity: advisory
   # Defense-in-depth twin of the update-command wrapper refresh
   # (cmd_upgrade / cmd_refresh). On session_start, re-stamps a stale
   # project-local ./agent-config wrapper from the canonical template so
@@ -187,6 +205,7 @@ concerns:
     script: src/scripts/wrapper_freshness_hook.ts
     args: []
     fail_closed: false
+    severity: advisory
   # road-to-install-path-convergence Phase 4 — duplicate-surface probe.
   # Reads src/config/surface-matrix.yml, existence-checks declared duplicate
   # classes, nudges ONCE per day (state: agents/runtime/state/
@@ -196,6 +215,7 @@ concerns:
     script: src/scripts/surface_probe_hook.ts
     args: []
     fail_closed: false
+    severity: advisory
   # road-to-team-mode Phase 4 — managed Review-Gate circuit breaker.
   # Runs AFTER the plugin's own Stop gate: reads the persisted gate job
   # record, counts consecutive BLOCK verdicts per session, injects the
@@ -207,6 +227,7 @@ concerns:
     script: src/scripts/team_review_gate_hook.ts
     args: []
     fail_closed: false
+    severity: advisory
   # Reply-shape backstop for the direct-answers rule (reply-close): a PR
   # created THIS turn must end the reply as the literal last raw URL. This
   # PostToolUse hook fires right after a PR *create* (gh pr create, or a
@@ -218,6 +239,7 @@ concerns:
     script: src/scripts/pr_url_reminder_hook.ts
     args: []
     fail_closed: false
+    severity: advisory
   # session_start canary injection — deterministic carrier for the
   # session-canary rule (greet-by-name at task start + reply-close markers
   # as a user-observable context-degradation signal). Gated on
@@ -229,6 +251,7 @@ concerns:
     script: src/scripts/session_canary_hook.ts
     args: []
     fail_closed: false
+    severity: advisory
 
 platforms:
   augment:

package/src/scripts/hooks/dispatch_hook.ts

@@ -47,6 +47,7 @@ import {
   setHookStdinOverride,
   clearHookStdinOverride,
 } from "./hook_stdin.js";
+import { emitFor, type Severity } from "./host_semantics.js";
 
 // Free-form JSON values flow through every helper here; a documented
 // alias keeps the surface honest without `any` (ADR-200 § strict TS).
@@ -103,6 +104,19 @@ export function _severity_for(rc: number): string {
   return _SEVERITY_BY_EXIT[rc] ?? "error";
 }
 
+/**
+ * P0.2 (road-to-rule-coherence) — is this concern declared advisory?
+ *
+ * An advisory concern MUST never produce a BLOCK verdict on any host. Four
+ * PreToolUse concerns document themselves as advisory in prose
+ * (`design_slop_hook`: "FLAGS, NEVER A BLOCK") while the transport happily
+ * turned their WARN into a host-level deny. Prose is not enforcement: the
+ * manifest now declares severity and the dispatcher enforces the ceiling.
+ */
+export function _is_advisory(concern: JsonObject): boolean {
+  return String(concern["severity"] ?? "").trim().toLowerCase() === "advisory";
+}
+
 function _now_iso(): string {
   // Python: datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ").
   return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
@@ -976,6 +990,11 @@ export function main(argv?: string[]): number {
   // stdout-injection; harmless surfacing elsewhere). All other events keep
   // the swallow-stdout contract unchanged.
   const context_blocks: string[] = [];
+  // Per-concern message for the host emission (P0.1). Kept OUT of
+  // feedback_entries on purpose: that record is written to disk with a
+  // fixed-field schema (PII-exclusion-by-construction), and a concern's raw
+  // stderr is free-form content. This array is in-memory only.
+  const concern_messages: Array<{ rc: number; text: string }> = [];
   for (const concern of concerns) {
     const concern_started = _now_iso();
     const { rc: rawRcResult, stderr: stderr_text, stdout: stdout_text, duration_ms } =
@@ -992,8 +1011,30 @@ export function main(argv?: string[]): number {
         process.stderr.write(stderr_text);
       }
     }
+    // P0.2 severity ceiling: an advisory concern can never block, on any host.
+    // This covers BOTH the concern emitting EXIT_BLOCK directly and the
+    // fail_closed promotion above turning a crash into a block.
+    if (rc === EXIT_BLOCK && _is_advisory(concern)) {
+      process.stderr.write(
+        `dispatch_hook: concern '${String(concern["name"])}' is declared ` +
+          `severity: advisory but returned BLOCK — downgraded to warn.\n`,
+      );
+      rc = EXIT_WARN;
+    }
     rcs.push(rc);
     const reply = _parse_concern_stdout(stdout_text);
+    // A concern states its reason either as JSON {"reason": …} on stdout
+    // (advisory concerns) or as a formatted stderr line (the block guards, e.g.
+    // `block-no-verify: BLOCKED — …`). Both are captured here so the emission
+    // layer can surface the REAL message instead of a generic label; before
+    // this, a rc=1 block discarded the concern's stderr entirely.
+    const stated =
+      typeof reply["reason"] === "string" && (reply["reason"] as string).trim()
+        ? (reply["reason"] as string).trim()
+        : stderr_text.trim();
+    if (stated) {
+      concern_messages.push({ rc, text: stated });
+    }
     if (
       args.event === "session_start" &&
       rc === EXIT_ALLOW &&
@@ -1021,7 +1062,30 @@ export function main(argv?: string[]): number {
   if (context_blocks.length > 0 && final_rc === EXIT_ALLOW) {
     process.stdout.write(context_blocks.join("\n\n") + "\n");
   }
-  return final_rc;
+
+  // P0.1 host-semantics translation. The internal ladder (0/1/2) is written to
+  // the feedback dir verbatim above — that record is unchanged. What leaves the
+  // process is now the HOST's native contract, because the two languages
+  // disagree: on Claude Code exit 1 does not block and exit 2 does, which
+  // inverted every verdict (see host_semantics.ts for the documented mapping).
+  // Unverified platforms keep the legacy pass-through byte-for-byte.
+  const decidingReasons = concern_messages
+    .filter((m) => m.rc === final_rc)
+    .map((m) => m.text);
+  const emission = emitFor(
+    args.platform,
+    args.event,
+    _severity_for(final_rc) as Severity,
+    decidingReasons,
+    final_rc,
+  );
+  if (emission.stdout) {
+    process.stdout.write(emission.stdout);
+  }
+  if (emission.stderr) {
+    process.stderr.write(emission.stderr);
+  }
+  return emission.exit;
 }
 
 function _isDir(p: string): boolean {

package/src/scripts/hooks/host_semantics.ts

@@ -0,0 +1,140 @@
+/**
+ * host_semantics — translate the dispatcher's internal severity ladder into
+ * each host's NATIVE hook contract.
+ *
+ * WHY THIS EXISTS (road-to-rule-coherence P0.1). The dispatcher speaks one
+ * internal language: `0 allow · 1 block · 2 warn` (`dispatch_hook.EXIT_*`).
+ * Claude Code's hook contract does NOT share that language, and the mismatch
+ * inverted every verdict on that host:
+ *
+ *   - Claude Code treats exit **1** as a NON-blocking error and proceeds with
+ *     the action. So `EXIT_BLOCK = 1` did not block: `block-no-verify` and
+ *     `block-kernel-rule-writes` — both `fail_closed: true` guards — were
+ *     inert on Claude Code.
+ *   - Claude Code treats exit **2** on PreToolUse as a BLOCKING error. So a
+ *     purely advisory `EXIT_WARN = 2` hard-denied the tool call, even though
+ *     `design_slop_hook` documents "FLAGS, NEVER A BLOCK" three times.
+ *   - JSON on stdout is parsed ONLY on exit 0. The old code wrote
+ *     `{"decision":"warn","reason":…}` to stdout AND exited 2, so the reason
+ *     was discarded — the observed symptom was a bare
+ *     `PreToolUse:Edit hook error: … No stderr output`.
+ *
+ * Source: Claude Code hooks documentation — "For most hook events, only exit
+ * code 2 blocks the action. Claude Code treats exit code 1 as a non-blocking
+ * error and proceeds with the action, even though 1 is the conventional Unix
+ * failure code. If your hook is meant to enforce a policy, use `exit 2`." and
+ * "Claude Code only processes JSON on exit 0."
+ *
+ * DESIGN. The pure reducer in `dispatch_hook._reduce` is unchanged — concerns
+ * keep emitting the internal ladder and need no rewrite. Only the final
+ * emission is translated, here, per (platform, event). Hosts whose native
+ * contract has NOT been verified against documentation keep the legacy
+ * pass-through, so this fix cannot silently change behaviour on a host nobody
+ * measured. That is deliberate: a speculative mapping is the same class of bug
+ * this module exists to remove.
+ */
+
+/** Internal severity, mirroring dispatch_hook's EXIT_ALLOW / BLOCK / WARN. */
+export type Severity = "allow" | "warn" | "block";
+
+/** What the dispatcher should actually do on the way out. */
+export interface Emission {
+    /** Process exit code to hand the host. */
+    exit: number;
+    /** Text for stdout (already serialized). Empty = write nothing. */
+    stdout: string;
+    /** Text for stderr. Empty = write nothing. */
+    stderr: string;
+}
+
+/**
+ * Hosts with a documented, verified native hook contract. Anything absent
+ * from this set falls through to the legacy pass-through.
+ */
+export const VERIFIED_PLATFORMS: ReadonlySet<string> = new Set(["claude"]);
+
+/** Internal event name -> Claude Code `hookEventName` for JSON output. */
+const CLAUDE_HOOK_EVENT_NAME: Record<string, string> = {
+    pre_tool_use: "PreToolUse",
+    post_tool_use: "PostToolUse",
+    user_prompt_submit: "UserPromptSubmit",
+    session_start: "SessionStart",
+    session_end: "SessionEnd",
+    stop: "Stop",
+    pre_compact: "PreCompact",
+};
+
+/**
+ * Events where Claude Code honours exit 2 as a real block. Everywhere else
+ * exit 2 either cannot block (PostToolUse: "the tool already ran";
+ * SessionStart: "shows stderr to user only") or is far too blunt, so a block
+ * degrades to visible advisory context instead of a silent no-op.
+ */
+const CLAUDE_BLOCK_CAPABLE_EVENTS: ReadonlySet<string> = new Set([
+    "pre_tool_use",
+    "user_prompt_submit",
+    "stop",
+]);
+
+function _joinReasons(reasons: readonly string[]): string {
+    return reasons.map((r) => r.trim()).filter((r) => r.length > 0).join(" · ");
+}
+
+/**
+ * Build the Claude Code `hookSpecificOutput.additionalContext` envelope.
+ *
+ * Exit 0 + this JSON is the documented way to surface advisory feedback
+ * WITHOUT blocking — the mapping the four advisory PreToolUse concerns
+ * (design-slop, code-graph-nudge, rtk-wrap, block-config-weakening's
+ * advisory path) always intended.
+ */
+export function claudeAdditionalContext(event: string, text: string): string {
+    const hookEventName = CLAUDE_HOOK_EVENT_NAME[event] ?? event;
+    return `${JSON.stringify({
+        hookSpecificOutput: { hookEventName, additionalContext: text },
+    })}\n`;
+}
+
+/**
+ * Translate (platform, event, severity, reasons) into a native emission.
+ *
+ * `legacyExit` is the internal reduced code; unverified platforms get it back
+ * verbatim so their behaviour is byte-identical to before this module landed.
+ */
+export function emitFor(
+    platform: string,
+    event: string,
+    severity: Severity,
+    reasons: readonly string[],
+    legacyExit: number,
+): Emission {
+    if (!VERIFIED_PLATFORMS.has(platform)) {
+        return { exit: legacyExit, stdout: "", stderr: "" };
+    }
+    const reason = _joinReasons(reasons);
+
+    if (severity === "allow") {
+        return { exit: 0, stdout: "", stderr: "" };
+    }
+
+    if (severity === "block") {
+        if (CLAUDE_BLOCK_CAPABLE_EVENTS.has(event)) {
+            // Exit 2 + stderr: the ONLY documented way to make Claude Code
+            // refuse the action and feed the reason back to the model.
+            const label = reason || "blocked by agent-config hook policy";
+            return { exit: 2, stdout: "", stderr: `${label}\n` };
+        }
+        // Not block-capable (post_tool_use, session_start, …). Exit 2 here
+        // would discard stdout and still not block, so surface the reason as
+        // context rather than losing it.
+        const label = reason || "agent-config hook reported a blocking finding";
+        return { exit: 0, stdout: claudeAdditionalContext(event, label), stderr: "" };
+    }
+
+    // severity === "warn" — advisory. NEVER exit 2 on a block-capable event:
+    // that is precisely the inversion this module removes.
+    if (!reason) {
+        return { exit: 0, stdout: "", stderr: "" };
+    }
+    return { exit: 0, stdout: claudeAdditionalContext(event, reason), stderr: "" };
+}

package/src/scripts/lint_framework_leakage.ts

@@ -8,10 +8,13 @@
 // (logical-path matching via strip_source_prefix), JSON/quiet modes, the
 // path-does-not-exist exit(2), and the `_`-prefixed-file skip.
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { artefact_roots, strip_source_prefix } from './_lib/agent_src.js';
+import { GateLedger } from './_lib/gate_ledger.js';
+import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
 
 const SCRIPTS_DIR = path.dirname(fileURLToPath(import.meta.url));
 const REAL_REPO_ROOT = path.dirname(path.dirname(SCRIPTS_DIR));
@@ -295,7 +298,19 @@ export function has_framework_frontmatter(p: string): string | null {
 interface AllowlistEntry {
     file?: string;
     lines?: number[] | '*';
+    /**
+     * Content anchor — a substring of the exempted line.
+     *
+     * Position-keyed entries (`lines: [100]`) are drift-fragile by
+     * construction: inserting a paragraph above line 100 silently re-fires the
+     * ratchet on an entry nobody touched, which this repository has recorded as
+     * a real cost. An anchor keys the exemption to what is actually being
+     * exempted, so the entry survives the edit that moves it. Prefer it for new
+     * entries; `lines` stays supported for the existing ones.
+     */
+    anchor?: string;
     reason?: string;
+    falsifier?: string;
 }
 interface Allowlist {
     entries: AllowlistEntry[];
@@ -313,7 +328,12 @@ function _load_allowlist(): Allowlist {
     }
 }
 
-function _allowlisted(rel_path: string, line_no: number, allowlist: Allowlist): boolean {
+function _allowlisted(
+    rel_path: string,
+    line_no: number,
+    allowlist: Allowlist,
+    line_text = '',
+): boolean {
     const logical = strip_source_prefix(rel_path);
     for (const entry of allowlist.entries ?? []) {
         const entry_file = entry.file;
@@ -326,6 +346,12 @@ function _allowlisted(rel_path: string, line_no: number, allowlist: Allowlist):
         if (lines === '*') {
             return true;
         }
+        // Content anchor before line number: an anchored entry keeps matching
+        // after an insertion moves the line, which a position key cannot.
+        const anchor = entry.anchor;
+        if (typeof anchor === 'string' && anchor !== '' && line_text.includes(anchor)) {
+            return true;
+        }
         if (Array.isArray(lines) && lines.includes(line_no)) {
             return true;
         }
@@ -465,10 +491,12 @@ function* iter_md_files(paths: Iterable<string>): Generator<string> {
             const pb = toPosix(b);
             return pa < pb ? -1 : pa > pb ? 1 : 0;
         });
+        // Underscore-prefixed files are NOT filtered here. They used to be, and
+        // that made them invisible to every count downstream: the generator
+        // dropped them before `scannedFiles` ever saw one. The exclusion is
+        // still applied — in `main`, where the ledger records it as a named
+        // out-of-scope outcome instead of a silent `continue`.
         for (const f of collected) {
-            if (path.basename(f).startsWith('_')) {
-                continue;
-            }
             yield f;
         }
     }
@@ -510,38 +538,122 @@ function parse_args(argv: readonly string[]): { json: boolean; quiet: boolean; p
     return { json, quiet, paths: paths.length > 0 ? paths : _default_paths() };
 }
 
+/**
+ * The allowlist entry that would silence one finding, ready to paste.
+ *
+ * Anchored on the matched token rather than on the line number: a
+ * position-keyed entry re-fires the moment an insertion above moves the line,
+ * on an entry nobody touched, which `check_suppression_hygiene` counts every
+ * run until the existing 18 migrate.
+ */
+export function suppressionKey(rel: string, hit: Hit): string {
+    const anchor = hit.snippet.trim().slice(0, 60);
+    return JSON.stringify({
+        file: rel,
+        anchor,
+        reason: '<why this token is quoted content rather than a mandate>',
+        falsifier: `./scripts-run src/scripts/lint_framework_leakage --paths ${rel}`,
+    });
+}
+
+/**
+ * Prove, against the real CLI, that this gate still rejects what it must.
+ *
+ * The floor is 3 cases with at least 2 rejecting: a clean file alone would be a
+ * suite that only ever passes, which proves nothing about detection.
+ */
+export function selfTest(): number {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'fwl-selftest-'));
+    const write = (rel: string, body: string): string => {
+        const p = path.join(tmp, rel);
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(p, body, 'utf-8');
+        return p;
+    };
+    const run = (target: string): number =>
+        runGateCli(REAL_REPO_ROOT, 'src/scripts/lint_framework_leakage.ts', ['--paths', target, '--quiet'], REAL_REPO_ROOT);
+
+    try {
+        const leak = write('generic/skills/demo/SKILL.md', '# Demo\n\nAlways run `php artisan migrate` here.\n');
+        const clean = write('clean/skills/demo/SKILL.md', '# Demo\n\nRun the project migration command.\n');
+        const framed = write(
+            'framed/skills/demo/SKILL.md',
+            '---\nframework: laravel\n---\n\n# Demo\n\nAlways run `php artisan migrate` here.\n',
+        );
+        return runSelfTest({
+            gate: 'lint_framework_leakage',
+            minCases: 3,
+            minRejectCases: 2,
+            cases: [
+                { name: 'a framework mandate in a generic artefact is rejected', expect: 'reject', run: () => run(leak) },
+                { name: 'a neutral artefact passes', expect: 'accept', run: () => run(clean) },
+                {
+                    name: 'a second family (PHP tooling, not Laravel) is rejected — detection is not one pattern',
+                    expect: 'reject',
+                    run: () =>
+                        run(write('generic2/skills/demo/SKILL.md', '# Demo\n\nRun PHPStan before every commit.\n')),
+                },
+                {
+                    name: 'a `framework:`-declared artefact is exempt',
+                    expect: 'accept',
+                    run: () => run(framed),
+                },
+            ],
+        });
+    } finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+
 export function main(argv?: readonly string[]): number {
-    const args = parse_args(argv ?? process.argv.slice(2));
+    const raw = argv ?? process.argv.slice(2);
+    if (raw.includes('--self-test')) {
+        return selfTest();
+    }
+    const args = parse_args(raw);
 
     const allowlist = _load_allowlist();
     const file_hits: Array<[string, Hit[]]> = [];
     let total_hits = 0;
     let allowlisted_total = 0;
-    // gate-coverage contract (src/config/gate-coverage.yml): files actually
-    // inspected. NOTE the "N files" in the human summary is files WITH HITS —
-    // reading that as coverage is exactly how a blind gate looks healthy.
-    let scannedFiles = 0;
-
-    for (const f of iter_md_files(args.paths)) {
-        scannedFiles += 1;
+    // Every enumerated file is planned up front, so the five exemption branches
+    // below stop being invisible `continue`s. Before the ledger, `scannedFiles`
+    // counted files *enumerated*, not files *judged* — a carve-out and a clean
+    // file were indistinguishable in the published number.
+    const ledger = new GateLedger('lint_framework_leakage');
+    const enumerated = [...iter_md_files(args.paths)];
+    ledger.plan(enumerated.map(relToRepo));
+
+    for (const f of enumerated) {
+        const rel = relToRepo(f);
+        // Partials are fragments included into a parent artefact; the parent is
+        // the unit this gate judges.
+        if (path.basename(f).startsWith('_')) {
+            ledger.outOfScope(rel, 'not_applicable_kind');
+            continue;
+        }
         if (is_carve_out(f)) {
+            ledger.outOfScope(rel, 'declared_exemption');
             continue;
         }
         if (is_inventory_file(f)) {
+            ledger.outOfScope(rel, 'not_applicable_kind');
             continue;
         }
         if (has_framework_frontmatter(f)) {
+            ledger.outOfScope(rel, 'declared_exemption');
             continue;
         }
         // Self-exemption: the neutrality rule itself enumerates the forbidden
         // tokens (frontmatter triggers + fix table) — it can never be clean
         // by construction.
         if (f.endsWith(`${path.sep}framework-neutrality-in-generic-skills.md`)) {
+            ledger.outOfScope(rel, 'declared_exemption');
             continue;
         }
-        const rel = relToRepo(f);
         const raw_hits = scan_file(f);
         if (raw_hits.length === 0) {
+            ledger.complete(rel);
             continue;
         }
         const kept: Hit[] = [];
@@ -549,7 +661,7 @@ export function main(argv?: readonly string[]): number {
             if (h.cross_stack) {
                 continue;
             }
-            if (_allowlisted(rel, h.line, allowlist)) {
+            if (_allowlisted(rel, h.line, allowlist, h.snippet)) {
                 h.allowlisted = true;
                 allowlisted_total += 1;
                 continue;
@@ -560,6 +672,10 @@ export function main(argv?: readonly string[]): number {
         if (kept.length > 0) {
             file_hits.push([f, kept]);
             total_hits += kept.length;
+            ledger.fail(rel, `${String(kept.length)} un-allowlisted leakage hit(s)`);
+        } else {
+            // Every raw hit was cross-stack or allowlisted: the file WAS judged.
+            ledger.complete(rel);
         }
     }
 
@@ -569,6 +685,10 @@ export function main(argv?: readonly string[]): number {
         allowlisted: allowlisted_total,
     };
 
+    // Finalize before either output branch: an unaccounted target must throw
+    // rather than let a formatted result be printed over it.
+    const tally = ledger.finalize();
+
     if (args.json) {
         const out = {
             version: 1,
@@ -576,6 +696,7 @@ export function main(argv?: readonly string[]): number {
                 hits.map((h) => ({ file: relToRepo(p), ...h })),
             ),
             summary,
+            ledger: tally,
         };
         process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
         return total_hits ? 1 : 0;
@@ -590,6 +711,11 @@ export function main(argv?: readonly string[]): number {
                 const lineCol = String(h.line).padStart(4, ' ');
                 const catCol = h.category.padEnd(16, ' ');
                 process.stdout.write(`  L${lineCol}  ${catCol}  /${h.pattern}/  ${h.snippet}\n`);
+                // The suppression key travels WITH the finding, copy-pasteable and
+                // anchor-keyed. Friction in the narrow path is what pushes a
+                // maintainer to the blunt off-switch instead; and an anchor keeps
+                // matching after an edit moves the line, which `lines: [N]` cannot.
+                process.stdout.write(`        suppress: ${suppressionKey(rel, h)}\n`);
             }
         }
     }
@@ -598,7 +724,13 @@ export function main(argv?: readonly string[]): number {
         `\n${total_hits} hits across ${file_hits.length} files ` +
             `(${allowlisted_total} allowlisted)\n`,
     );
-    process.stderr.write(`scanned: ${String(scannedFiles)}\n`);
+    ledger.report();
+    // gate-coverage contract (src/config/gate-coverage.yml): files actually
+    // JUDGED — completed plus failed. It used to be files *enumerated*, which
+    // over-reported coverage by every exempted file (438 published against 368
+    // judged) and is the same "reading M as coverage" trap the human summary
+    // carries. The ledger makes the honest number the cheap one to publish.
+    process.stderr.write(`scanned: ${String(tally.completed + tally.failed)}\n`);
     return total_hits ? 1 : 0;
 }