@event4u/agent-config 9.18.0 → 9.19.0

package/src/scripts/_lib/release_highlights.ts

@@ -0,0 +1,279 @@
+/**
+ * Shared release-highlight classifier — one definition of the curated head's
+ * labels and of the span → category derivation.
+ *
+ * Used by BOTH sides on purpose:
+ *
+ * - the generator (`release.ts`) pre-fills the curated head with what it can
+ *   substantiate from the span;
+ * - the gate (`check_release_highlights.ts`) blocks a `_none_` the span
+ *   contradicts.
+ *
+ * Why shared instead of duplicated. Before this module the generator emitted
+ * `_none_` for all five fields while the gate rejected exactly that default
+ * the moment the span carried evidence. Every release of this package touches
+ * `src/rules/` or `src/scripts/schemas/`, so "Behaviour changes" is always
+ * substantiated and every release PR was red on its FIRST run by construction
+ * — 9.17.0 (run 30871194277) and 9.18.0 (run 30909511315) both hit it, on the
+ * same step, for the same reason.
+ *
+ * This is not a weaker gate. The generator no longer manufactures a claim it
+ * cannot support, and the gate keeps full teeth for the failure it was built
+ * for: a human editing a substantiated line back down to `_none_`, which is
+ * exactly what produced the false 9.13.0 and 9.14.0 heads. Machine-written
+ * `_none_` was never that failure; it was noise standing in front of it.
+ */
+import { spawnSync } from 'node:child_process';
+
+/** The five curated labels, in the order an operator reads them. */
+export const HEAD_LABELS: readonly string[] = [
+    'Behaviour changes',
+    'Default changes + migration',
+    'Security and correctness',
+    'Honest nulls',
+    'Known limitations',
+];
+
+export const HEAD_NONE = '_none_';
+
+/**
+ * Prefix marking a head line the generator derived rather than a human wrote.
+ *
+ * Machine-checkable so the gate can warn when one survives to merge, and
+ * readable so the line still says something true to anyone who ships it
+ * unedited. It is not a placeholder token: the line it introduces carries real
+ * evidence (the reason plus the citing SHAs), so nothing here is
+ * wrong-if-shipped — only unpolished-if-unedited.
+ */
+export const DERIVED_MARKER = '_auto-derived, rewrite before merge:_';
+
+/** Cap on cited SHAs per line, so a wide release cannot unbound the head. */
+export const DERIVED_SHA_CAP = 6;
+
+export interface SpanCommit {
+    sha: string;
+    subject: string;
+    body: string;
+    /** `A` / `M` / `D` / `R…` status per touched path. */
+    files: ReadonlyArray<{ status: string; path: string }>;
+    breaking: boolean;
+}
+
+/** One derived hit: the commit that substantiates a label. */
+export interface CategoryHit {
+    sha: string;
+    /** Rendered detail — the subject, plus a removed-surface note when any. */
+    text: string;
+}
+
+/** Public artefact trees whose deletions count as removed public surface. */
+const _PUBLIC_SURFACE_PREFIXES = [
+    'src/skills/',
+    'src/rules/',
+    'src/agent-src/commands/',
+    'src/domains/',
+];
+
+const _RULE_OR_SCHEMA_PREFIXES = ['src/rules/', 'src/scripts/schemas/'];
+
+/**
+ * Why a label fired, in generator-facing prose. Keyed by label; a label absent
+ * here is never derived (`Known limitations` is pure prose, not checkable).
+ */
+const _DERIVED_REASON: Readonly<Record<string, string>> = {
+    'Behaviour changes': 'rule/schema diffs, breaking commits or removed public surface',
+    'Default changes + migration': 'commits naming a default, migration or migrate',
+    'Security and correctness': 'security-scoped commits',
+    'Honest nulls': 'commits carrying an honest-null marker',
+};
+
+/**
+ * Derive evidence per curated label from the span. Rules per label:
+ *
+ * - Security and correctness: conventional scope matching /secur/i, or the
+ *   whole word "security" in the subject.
+ * - Behaviour changes: breaking (`!` / BREAKING CHANGE) commits, diffs
+ *   touching `src/rules/` or `src/scripts/schemas/`, and deletions under the
+ *   public artefact trees (removed public surface).
+ * - Default changes + migration: subject carrying the whole word "default",
+ *   "migration", or "migrate".
+ * - Honest nulls: subject or body carrying an "honest null" marker.
+ * - Known limitations: never derived — pure prose, not gate-checkable.
+ *
+ * Derivation is deliberately conservative: a false red makes every release
+ * annoying, a miss only returns the head to the pre-gate state.
+ */
+export function derive_category_hits(
+    commits: readonly SpanCommit[],
+): Record<string, CategoryHit[]> {
+    const out: Record<string, CategoryHit[]> = {};
+    for (const label of HEAD_LABELS) {
+        out[label] = [];
+    }
+    for (const c of commits) {
+        const scopeMatch = /^\w+\(([^)]*)\)!?:/u.exec(c.subject);
+        const scope = scopeMatch ? scopeMatch[1]! : '';
+        if (/secur/iu.test(scope) || /\bsecurity\b/iu.test(c.subject)) {
+            out['Security and correctness']!.push({ sha: c.sha, text: c.subject });
+        }
+        const removedPublic = c.files.filter(
+            (f) =>
+                f.status.startsWith('D') &&
+                _PUBLIC_SURFACE_PREFIXES.some((p) => f.path.startsWith(p)),
+        );
+        const ruleOrSchema = c.files.some((f) =>
+            _RULE_OR_SCHEMA_PREFIXES.some((p) => f.path.startsWith(p)),
+        );
+        if (c.breaking || ruleOrSchema || removedPublic.length > 0) {
+            const text =
+                removedPublic.length > 0
+                    ? `${c.subject} (removes ${removedPublic.map((f) => f.path).join(', ')})`
+                    : c.subject;
+            out['Behaviour changes']!.push({ sha: c.sha, text });
+        }
+        if (/\b(default|migration|migrate)\b/iu.test(c.subject)) {
+            out['Default changes + migration']!.push({ sha: c.sha, text: c.subject });
+        }
+        if (/honest[ -]null/iu.test(`${c.subject}\n${c.body}`)) {
+            out['Honest nulls']!.push({ sha: c.sha, text: c.subject });
+        }
+    }
+    return out;
+}
+
+/**
+ * String-rendered evidence per label (`<sha7> <detail>`), the shape the gate
+ * reports to a human. Derived from the structured hits so the two can never
+ * disagree.
+ */
+export function derive_categories(commits: readonly SpanCommit[]): Record<string, string[]> {
+    const hits = derive_category_hits(commits);
+    const out: Record<string, string[]> = {};
+    for (const label of HEAD_LABELS) {
+        out[label] = (hits[label] ?? []).map((h) => `${h.sha.slice(0, 7)} ${h.text}`);
+    }
+    return out;
+}
+
+/**
+ * Pre-fill values for the curated head, one line per SUBSTANTIATED label.
+ *
+ * A label with no evidence is omitted, so the caller's `_none_` default still
+ * applies where `_none_` is the true answer. One line per label keeps the
+ * rendered head inside its cap; SHA citations are capped at `DERIVED_SHA_CAP`
+ * with an explicit remainder count rather than a silent truncation.
+ */
+export function render_derived_head_values(
+    hits: Readonly<Record<string, readonly CategoryHit[]>>,
+): Record<string, string> {
+    const out: Record<string, string> = {};
+    for (const label of HEAD_LABELS) {
+        const reason = _DERIVED_REASON[label];
+        const ev = hits[label] ?? [];
+        if (!reason || ev.length === 0) {
+            continue;
+        }
+        const shas = ev.map((h) => h.sha.slice(0, 7));
+        const shown = shas.slice(0, DERIVED_SHA_CAP);
+        const remainder = shas.length - shown.length;
+        const more = remainder > 0 ? ` +${remainder} more` : '';
+        out[label] = `${DERIVED_MARKER} ${reason} in ${shown.join(', ')}${more}.`;
+    }
+    return out;
+}
+
+/** Labels whose curated value is still the generator's unedited draft. */
+export function stale_draft_labels(
+    curated: Readonly<Record<string, string>>,
+): string[] {
+    return HEAD_LABELS.filter((l) => (curated[l] ?? '').includes(DERIVED_MARKER));
+}
+
+// ─── git span collection ────────────────────────────────────────────────────
+
+const _RECORD = '\u001e';
+const _FIELD = '\u001f';
+
+export function parse_git_log(raw: string): SpanCommit[] {
+    const commits: SpanCommit[] = [];
+    for (const record of raw.split(_RECORD)) {
+        if (!record.trim()) {
+            continue;
+        }
+        const [head, ...restLines] = record.split('\n');
+        const parts = (head ?? '').split(_FIELD);
+        if (parts.length < 3) {
+            continue;
+        }
+        const sha = parts[0]!.trim();
+        const subject = parts[1]!;
+        const bodyParts: string[] = [parts.slice(2).join(_FIELD)];
+        const files: Array<{ status: string; path: string }> = [];
+        for (const line of restLines) {
+            const m = /^([A-Z]\d*)\t(.+)$/u.exec(line);
+            if (m) {
+                // Renames carry two paths; the last tab field is the new path,
+                // the first the old — record both so a rename out of a public
+                // tree still counts its origin path.
+                const segs = m[2]!.split('\t');
+                for (const p of segs) {
+                    files.push({ status: m[1]!, path: p });
+                }
+            } else {
+                // %b is multi-line — everything that is not a name-status
+                // line is body continuation (honest-null markers live there).
+                bodyParts.push(line);
+            }
+        }
+        const body = bodyParts.join('\n');
+        commits.push({
+            sha,
+            subject,
+            body,
+            files,
+            breaking: /^\w+(\([^)]*\))?!:/u.test(subject) || /BREAKING CHANGE/u.test(body),
+        });
+    }
+    return commits;
+}
+
+/** `git log` arguments for a span, shared so both callers read one format. */
+export function span_log_args(from: string | null, to: string): string[] {
+    return [
+        'log',
+        from ? `${from}..${to}` : to,
+        '--no-merges',
+        '--name-status',
+        '--format=%x1e%H%x1f%s%x1f%b',
+    ];
+}
+
+/**
+ * Collect the span. Throws on git failure so a caller can decide whether the
+ * derivation is load-bearing (the gate) or best-effort (the generator).
+ */
+export function collect_span_commits(from: string | null, to: string, cwd: string): SpanCommit[] {
+    const r = spawnSync('git', span_log_args(from, to), {
+        encoding: 'utf-8',
+        cwd,
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    if (r.status !== 0) {
+        throw new Error(`git ${span_log_args(from, to).join(' ')} failed: ${r.stderr}`);
+    }
+    return parse_git_log(r.stdout);
+}
+
+/** Latest reachable release tag before `ref`, or null when there is none. */
+export function previous_release_tag(ref: string, cwd: string): string | null {
+    const r = spawnSync(
+        'git',
+        ['describe', '--tags', '--abbrev=0', '--match', '[0-9]*.[0-9]*.[0-9]*', `${ref}^`],
+        { encoding: 'utf-8', cwd },
+    );
+    if (r.status !== 0) {
+        return null;
+    }
+    const tag = r.stdout.trim();
+    return tag === '' ? null : tag;
+}

package/src/scripts/audit_skill_overlap.ts

@@ -499,6 +499,10 @@ export function main(argv: string[] | null = null): number {
         process.stderr.write(`❌  ${exc.message}\n`);
         return 3;
     }
+    // Gate-coverage contract (src/config/gate-coverage.yml rule 1): publish the
+    // asserted count machine-readably. Written to stderr, not stdout, because
+    // this audit's stdout carries the report body consumers read.
+    process.stderr.write(`scanned: ${String(skills.length)}\n`);
     const pairs = find_pairs(skills, args.threshold);
     const outDir = args.outDir ?? REPORT_DIR;
     const outJson = path.join(outDir, OUT_JSON_NAME);

package/src/scripts/check_completion_review.ts

@@ -18,10 +18,15 @@
  *     with the required Reason/Ref content;
  *   - every table-shaped row parses into the six §2.2 cells (`malformed-row`) —
  *     a short row is never silently dropped, or an `open` finding would pass;
+ *   - ``` fences resolve (`unbalanced-fence`) — only a LABELLED, properly-closed
+ *     fence hides content, so no arrangement of bare fences can swallow a row,
+ *     for the same reason;
  *   - severity rows are sorted descending (critical > high > medium > low);
  *   - findings-before-fixes ancestry: the commit that FIRST added the
  *     artifact is an ancestor of every referenced fix commit (§2.5 — the
- *     first-add commit is what counts, so backdating is detected too).
+ *     first-add commit is what counts, so backdating is detected too; it is the
+ *     earliest add of the PATH, so the guarantee covers the artefact's FIRST
+ *     round, and per-round ordering stays convention — §2.5 names that limit).
  *
  * The review binds to the review-SCOPE HASH, never to a commit sha. That
  * definition is owned by `dispatch_r2_reviewer.ts` and imported here so the
@@ -114,6 +119,16 @@ export interface ParsedArtifact {
      * defect class.
      */
     malformedRows: string[];
+    /**
+     * 1-based lines of every stray ``` fence, ascending (§2.2).
+     *
+     * A stray is a BARE ``` (which never delimits a region) or a labelled opener
+     * that is never closed. All of them are reported as one `unbalanced-fence`
+     * violation naming every line — a single number could only ever name the
+     * last. Stray fences skip nothing: the lines around them are parsed, because
+     * no fence arrangement may swallow an `open` row (see {@link scanFences}).
+     */
+    strayFenceLines: number[];
     /** The §5 context manifest, when present and parseable. */
     manifest: ParsedManifest | null;
 }
@@ -181,8 +196,46 @@ const CODE_EXTENSIONS = new Set([
     'erl',
     'dart',
     'r',
+    // Infrastructure-as-code and build definitions. Production behaviour lives
+    // here as much as in application code — this suite ships terraform /
+    // terragrunt / aws-infrastructure skills and an engineering-safety-floor
+    // that treats these files as prod surfaces, so omitting them let an
+    // IaC-only completion claim "no code surface" and take the skip path.
+    'tf',
+    'tfvars',
+    'hcl',
+    'gradle',
+    'cmake',
+    'proto',
+    'bicep',
+]);
+
+/**
+ * Extensionless build / infra files. `isCodePath` decides by extension, so a
+ * `Dockerfile` or `Makefile` (no dot) fell through to "not code" — the same
+ * hole as a missing extension, one step further along.
+ */
+const CODE_BASENAMES = new Set([
+    'dockerfile',
+    'containerfile',
+    'makefile',
+    'jenkinsfile',
+    'vagrantfile',
+    'procfile',
+    'brewfile',
+    'rakefile',
+    'gemfile',
+    'justfile',
 ]);
 
+/**
+ * Tails that turn a {@link CODE_BASENAMES} stem into generated or prose state
+ * rather than code — `Gemfile.lock`, `Makefile.md`. Kept narrow on purpose: an
+ * unknown tail (`Dockerfile.prod`) stays code, so the classification errs broad
+ * exactly as contract §2.4 promises.
+ */
+const GENERATED_TAILS = new Set(['lock', 'md', 'txt', 'json', 'yml', 'yaml', 'bak', 'orig']);
+
 /**
  * Template extensions whose *inner* extension decides. `foo.blade.php` is
  * already caught by `php`; `foo.html.twig` / `foo.j2` are not, so they are
@@ -216,6 +269,18 @@ export function isCodePath(p: string): boolean {
     if (CODE_SUFFIXES.some((s) => base.endsWith(s))) {
         return true;
     }
+    // Extensionless build/infra files (Dockerfile, Makefile, …) plus their
+    // environment variants (`Dockerfile.prod`, `Makefile.local`). A generated
+    // sibling that merely shares the stem is NOT code — `Gemfile.lock` is
+    // dependency state, the same class as the `composer.json` this function
+    // already excludes.
+    const stem = base.includes('.') ? base.slice(0, base.indexOf('.')) : base;
+    if (CODE_BASENAMES.has(stem)) {
+        const tail = base.slice(stem.length + 1);
+        if (tail === '' || !GENERATED_TAILS.has(tail)) {
+            return true;
+        }
+    }
     const dot = base.lastIndexOf('.');
     if (dot <= 0) {
         return false;
@@ -301,6 +366,112 @@ function splitTableRow(line: string): string[] {
 }
 
 const FENCE_RE = /^\s*```/;
+/** A ```-prefixed line split into its backtick run and its info string. */
+const FENCE_PARTS_RE = /^\s*(`{3,})(.*)$/;
+
+export interface FenceScan {
+    /** 0-based indices of lines inside a LABELLED, properly-closed fence — the only lines to skip. */
+    fenced: Set<number>;
+    /**
+     * 1-based line numbers of every stray ``` fence, ascending.
+     *
+     * A stray is a bare ``` that opens nothing (no region is ever delimited by
+     * one) or a labelled opener that is never closed. Empty = fences are sound.
+     */
+    strays: number[];
+}
+
+/** Backtick-run length and info string of a fence line, or null if not a fence. */
+function fenceParts(line: string): { ticks: number; info: string } | null {
+    const m = FENCE_PARTS_RE.exec(line);
+    return m ? { ticks: (m[1] as string).length, info: (m[2] as string).trim() } : null;
+}
+
+/**
+ * Which lines are fenced — and which ``` fences are stray?
+ *
+ * Fenced regions exist for ONE reason: an *illustrative* template row (the §2.2
+ * `| # | Severity | …` example a doc-ish artefact quotes) must not be read as a
+ * live finding. Nothing else justifies making a line invisible, so the
+ * delimiter has to be something no author produces by accident.
+ *
+ * Two earlier shapes both failed OPEN, and they are the same defect:
+ *   - a single `inFence` toggle made every line after an ODD ```-count invisible;
+ *   - POSITIONAL pairing then detected parity but never MIS-pairing — two
+ *     unpaired inner openers (two `~~~`-wrapped illustrations, each holding one
+ *     stray ``` — exactly what `markdown-safe-codeblocks` produces, since the
+ *     outer `~~~` is not a fence to this grammar) paired with EACH OTHER and
+ *     swallowed every line between them, `unterminatedAt` staying `null`.
+ * In both, one earlier well-formed row kept `rows.length > 0`, so the
+ * neither-table-nor-honest-null fallback also stayed quiet and an unreviewed
+ * `open` row PASSED — the same fail-open the §2.2 `malformed-row` rule closes by
+ * a different route. Patching parity, then pairing, then the next arrangement is
+ * a losing game, so the discriminator is fixed instead of the arithmetic:
+ *
+ *   A region is skipped ONLY when it is a properly-closed pair whose OPENING
+ *   fence carries an info string (```` ```markdown ````). A BARE ``` never
+ *   delimits a region: it is recorded as a stray, the lines around it are parsed
+ *   as ordinary content, and the artefact is reported `unbalanced-fence`.
+ *
+ * So no arrangement of bare fences can hide a row — a swallowed `open` finding
+ * needs a deliberate label, which is the authoring act that means "illustration".
+ * Closing follows CommonMark (bare, and at least as many backticks as the
+ * opener), which also makes a ```` ````-wrapped ``` block nest correctly. A
+ * labelled opener with NO bare fence after it anywhere is a stray and skips
+ * nothing.
+ *
+ * KNOWN HOLE, still open — this function does NOT deliver the property the two
+ * paragraphs above imply (blind-pass findings 1-3, 2026-08-04). A labelled
+ * opener is closed by the first later bare fence ANYWHERE in the artefact, even
+ * one the author never meant as its closer: the lines between them are skipped,
+ * a live `open` row among them vanishes from `rows`, and because the opener was
+ * consumed `strays` stays empty so no `unbalanced-fence` fires. Reproduced; an
+ * unreviewed `open` finding passes. The remediation string this file prints for
+ * `unbalanced-fence` leads an author into exactly that arrangement.
+ *
+ * Not patched here on purpose: the obvious guard — a findings-shaped row inside
+ * a fenced region is a violation — fires on every artefact that quotes the
+ * template, including the skeleton `dispatch_r2_reviewer` writes, which carries
+ * an `open` row. The fix is a §2.2 grammar decision (declare illustrative
+ * regions explicitly, or move the safety check off fence pairing), recorded in
+ * the contract as open rather than replaced with a guard that reds every future
+ * artefact.
+ */
+export function scanFences(lines: readonly string[]): FenceScan {
+    const fenced = new Set<number>();
+    const strays: number[] = [];
+    let open: { at: number; ticks: number } | null = null;
+    for (let i = 0; i < lines.length; i++) {
+        const parts = fenceParts(lines[i] as string);
+        if (!parts) {
+            continue;
+        }
+        if (open !== null) {
+            // CommonMark closer: bare, and at least as long as the opener.
+            // Anything else is content inside the open region.
+            if (parts.info === '' && parts.ticks >= open.ticks) {
+                for (let j = open.at + 1; j < i; j++) {
+                    fenced.add(j);
+                }
+                open = null;
+            }
+            continue;
+        }
+        if (parts.info === '') {
+            strays.push(i + 1);
+            continue;
+        }
+        open = { at: i, ticks: parts.ticks };
+    }
+    if (open !== null) {
+        strays.push(open.at + 1);
+    }
+    // No sort: bare strays are only pushed while no opener is open, so they land
+    // in ascending line order, and the unterminated-opener push above is always
+    // the largest index. A sort here was dead code (blind-pass finding 5) —
+    // keeping it would imply an ordering hazard that cannot occur.
+    return { fenced, strays };
+}
 
 export function parseArtifact(text: string): ParsedArtifact {
     const out: ParsedArtifact = {
@@ -311,18 +482,20 @@ export function parseArtifact(text: string): ParsedArtifact {
         rows: [],
         malformedLines: [],
         malformedRows: [],
+        strayFenceLines: [],
         manifest: parseManifest(text),
     };
     const lines = text.split(/\r?\n/);
-    let inFence = false;
+    const fences = scanFences(lines);
+    out.strayFenceLines = fences.strays;
     for (let i = 0; i < lines.length; i++) {
         const raw = lines[i] as string;
         const lineno = i + 1;
-        if (FENCE_RE.test(raw)) {
-            inFence = !inFence;
-            continue;
-        }
-        if (inFence) {
+        // A fence marker line carries no grammar of its own, and a line inside a
+        // LABELLED closed fence is illustrative content. A stray fence (bare, or
+        // an unclosed opener) skips nothing (see scanFences) — the lines around
+        // it are parsed, and the artefact is reported.
+        if (FENCE_RE.test(raw) || fences.fenced.has(i)) {
             continue;
         }
         const trimmed = raw.trim();
@@ -371,7 +544,12 @@ export function parseArtifact(text: string): ParsedArtifact {
             if (first === '#' || second === 'severity') {
                 continue; // header row
             }
-            if (cells.length >= 6) {
+            // EXACTLY six, per contract §2.2 — not `>= 6`. An over-long row is
+            // as malformed as a short one and the surplus is usually the tell:
+            // an unescaped `|` inside a cell (the shape §2.2 requires escaping)
+            // splits one cell into two and shifts Status/Reason-Ref rightwards,
+            // so accepting it silently reads the wrong cell as the status.
+            if (cells.length === 6) {
                 out.rows.push({
                     index: cells[0] ?? '',
                     severity: (cells[1] ?? '').toLowerCase(),
@@ -390,7 +568,7 @@ export function parseArtifact(text: string): ParsedArtifact {
                 // §2.2 template ends in exactly that empty cell. Gate R1 already
                 // reports this class — same name, `malformed_row`.
                 out.malformedRows.push(
-                    `line ${lineno}: findings row has ${String(cells.length)} cell(s), expected 6 ` +
+                    `line ${lineno}: findings row has ${String(cells.length)} cell(s), expected exactly 6 ` +
                         '(`| # | Severity | File:Line | Finding | Status | Reason/Ref |` — the trailing ' +
                         'Reason/Ref cell is required even when empty)',
                 );
@@ -605,6 +783,24 @@ function evaluate(input: EvalInput): Violation[] {
         for (const detail of art.malformedRows) {
             violations.push({ kind: 'malformed-row', file, detail });
         }
+        // §2.2: stray ``` fences — a BARE fence (which delimits nothing) or a
+        // labelled opener left unclosed. The parser swallows no line around them
+        // (so an `open` row still blocks), but an artefact whose fences do not
+        // resolve is malformed in its own right — the reader cannot tell
+        // illustrative content from live rows. ONE violation naming EVERY stray:
+        // a single line number could only ever name the last one.
+        if (art.strayFenceLines.length > 0) {
+            const at = art.strayFenceLines.map((n) => `line ${String(n)}`).join(', ');
+            violations.push({
+                kind: 'unbalanced-fence',
+                file,
+                detail:
+                    `${at}: stray \`\`\` fence — a bare fence delimits no region, and a labelled fence must ` +
+                    'be closed. An artefact whose ``` fences do not resolve is malformed (contract §2.2). ' +
+                    'Label the opener (```markdown) and close it, or inline-escape an illustrative ```; ' +
+                    'the lines around a stray fence are still parsed, so any finding row there is validated too.',
+            });
+        }
     }
 
     for (const { file, art } of relevant) {
@@ -757,6 +953,13 @@ function checkFindingsBeforeFixes(repo: string, artifactAbs: string, rows: reado
     // Earliest add commit: `git log --diff-filter=A` lists newest-first, so the
     // LAST line is the first commit that ever added the file (backdating via a
     // later amend does not move it).
+    //
+    // Scope of the guarantee, per contract §2.5: this resolves the earliest add
+    // of the PATH, not of the current round's artefact — a re-bound (or renamed
+    // and re-added) `<slug>.findings.md` keeps round 1's add. So the check proves
+    // "the review file existed before the fixes of its FIRST round", and
+    // per-round ordering stays agent-carried convention. Deliberate, and named
+    // as a limit in the contract rather than implied away.
     const logRes = gitTry(repo, ['log', '--diff-filter=A', '--format=%H', '--', rel]);
     const addLines = logRes.stdout
         .split('\n')

package/src/scripts/check_gate_coverage.ts

@@ -49,6 +49,7 @@ import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import * as yaml from 'js-yaml';
+import { checkRatchet } from './_lib/gate_baseline.js';
 import { runCountedProbe } from './_lib/counted_probe.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -318,14 +319,76 @@ export function main(argv: readonly string[]): number {
       `⚠️  ${String(pending.length)} gate(s) are listed but NOT enforced — this guard's coverage is partial by declaration.\n`,
     );
   }
+  const hardening = report_hardening_ratchet();
   if (failed.length > 0) {
     process.stdout.write(`❌  ${String(failed.length)} gate(s) failed the coverage floor.\n`);
     return 1;
   }
+  if (hardening !== 0) {
+    return hardening;
+  }
   process.stdout.write('✅  every enforced gate cleared its coverage floor.\n');
   return 0;
 }
 
+/**
+ * Vulnerability ratchet — the count that must not RISE.
+ *
+ * This deliberately measures **defect exposure**, not adoption reach. A
+ * coverage-percentage ratchet ("hardened gates must increase") would be
+ * threshold-lowering in a ratchet's clothes: it tracks how far the fix has
+ * spread and can never regress, so it grades the solution instead of the
+ * problem. The number below is the opposite — how many gates could still exit 0
+ * over a moved root without saying so. It CAN regress (every new gate written
+ * without a scope assertion raises it) and the target stays 0.
+ *
+ * Recorded via the existing violation ratchet (`_lib/gate_baseline.ts`), so the
+ * 56-day non-stagnation clause applies unchanged: a count that never drops
+ * fails, because a frozen baseline is suppression with extra steps.
+ */
+export function report_hardening_ratchet(): number {
+  const unhardened = list_unhardened_gates();
+  const verdict = checkRatchet({
+    gate: 'gate-hardening:unhardened-scan-scope',
+    actual: unhardened.length,
+    repoRoot: REPO_ROOT,
+  });
+  process.stdout.write(`  ${verdict.ok ? '✅' : '❌'} ${verdict.message}\n`);
+  return verdict.ok ? 0 : 1;
+}
+
+/**
+ * Gate scripts that neither assert their scan scope nor publish a count — the
+ * population still able to report success over an empty corpus.
+ *
+ * A gate counts as hardened when it routes through `_lib/scan_scope` (the
+ * assertion that turns a zero scan into a red exit) OR emits the machine-
+ * readable `scanned:` line the coverage guard reads. Either one makes a dead
+ * root visible; neither is satisfiable by a gate that read nothing.
+ */
+export function list_unhardened_gates(dir = path.join(REPO_ROOT, 'src/scripts')): string[] {
+  let entries: string[];
+  try {
+    entries = fs.readdirSync(dir);
+  } catch {
+    return [];
+  }
+  const gates = entries.filter((f) => /^(lint|check|audit)_.*\.ts$/.test(f) && !f.endsWith('.d.ts'));
+  const out: string[] = [];
+  for (const f of gates) {
+    let src: string;
+    try {
+      src = fs.readFileSync(path.join(dir, f), 'utf8');
+    } catch {
+      continue;
+    }
+    const asserts = /assertScanned\(|assertWatchlistResolves\(/.test(src);
+    const emits = /(?:process\.(?:stdout|stderr)\.write|lines\.push)\(\s*`scanned: /.test(src);
+    if (!asserts && !emits) out.push(f.replace(/\.ts$/, ''));
+  }
+  return out.sort();
+}
+
 function spec_is_pending(s: GateSpec): boolean {
   return s.status === 'pending';
 }