@event4u/agent-config 12.1.0 → 14.0.0

package/src/scripts/lint_design_antipattern_parity.ts

@@ -29,6 +29,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { GateLedger } from './_lib/gate_ledger.js';
 import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
 
 const QUIET = process.argv.includes('--quiet');
@@ -44,6 +45,14 @@ export type Status = (typeof STATUSES)[number];
 export interface ParityFinding {
     kind: string;
     msg: string;
+    /**
+     * The catalog id this finding is about, when it is about one.
+     *
+     * Carried explicitly so the per-target ledger can attribute a failure
+     * without parsing it back out of `msg`. Absent on structural findings
+     * (a missing § Detector status section is about the document, not an id).
+     */
+    id?: string;
 }
 
 const ENTRY_ROW = /^\|\s*((?:V|C|T|L|M|CP)\d+)\s*\|/gm;
@@ -89,7 +98,7 @@ export function parityFindings(catalogMd: string, registryTs: string): ParityFin
     const entries = catalogEntries(catalogMd);
     const seen = new Set<string>();
     for (const id of entries) {
-        if (seen.has(id)) out.push({ kind: 'duplicate-entry', msg: `${id}: appears more than once in the catalog tables` });
+        if (seen.has(id)) out.push({ kind: 'duplicate-entry', id, msg: `${id}: appears more than once in the catalog tables` });
         seen.add(id);
     }
 
@@ -98,13 +107,13 @@ export function parityFindings(catalogMd: string, registryTs: string): ParityFin
     // A — every catalog entry is classified.
     for (const id of seen) {
         if (!rows.has(id)) {
-            out.push({ kind: 'unclassified', msg: `${id}: catalog entry missing from § Detector status` });
+            out.push({ kind: 'unclassified', id, msg: `${id}: catalog entry missing from § Detector status` });
         }
     }
     // B — every classified row names a real entry.
     for (const id of rows.keys()) {
         if (!seen.has(id)) {
-            out.push({ kind: 'orphan-status', msg: `${id}: § Detector status row names an entry that no catalog table defines` });
+            out.push({ kind: 'orphan-status', id, msg: `${id}: § Detector status row names an entry that no catalog table defines` });
         }
     }
     // D + E — status vocabulary and reasons.
@@ -112,12 +121,13 @@ export function parityFindings(catalogMd: string, registryTs: string): ParityFin
         if (!(STATUSES as readonly string[]).includes(row.status)) {
             out.push({
                 kind: 'bad-status',
+                id,
                 msg: `${id}: status '${row.status || '(empty)'}' is not one of ${STATUSES.join(', ')}`,
             });
             continue;
         }
         if (row.status !== 'backed' && row.note === '') {
-            out.push({ kind: 'missing-reason', msg: `${id}: status '${row.status}' carries no reason` });
+            out.push({ kind: 'missing-reason', id, msg: `${id}: status '${row.status}' carries no reason` });
         }
     }
 
@@ -126,7 +136,7 @@ export function parityFindings(catalogMd: string, registryTs: string): ParityFin
     const registry = new Set(registryCatalogIds(registryTs));
     for (const id of backed) {
         if (!registry.has(id)) {
-            out.push({ kind: 'backed-without-rule', msg: `${id}: marked backed but no registry rule declares that catalogId` });
+            out.push({ kind: 'backed-without-rule', id, msg: `${id}: marked backed but no registry rule declares that catalogId` });
         }
     }
     for (const id of registry) {
@@ -134,6 +144,7 @@ export function parityFindings(catalogMd: string, registryTs: string): ParityFin
             const known = rows.get(id);
             out.push({
                 kind: 'rule-without-backed',
+                id,
                 msg: known
                     ? `${id}: a registry rule declares this catalogId but § Detector status marks it '${known.status}'`
                     : `${id}: a registry rule declares this catalogId and no catalog entry carries it`,
@@ -167,8 +178,31 @@ export function main(): number {
     const registryTs = fs.readFileSync(REGISTRY, 'utf-8');
     const findings = parityFindings(catalogMd, registryTs);
 
+    const rows = statusRows(catalogMd);
     const entries = catalogEntries(catalogMd).length;
-    const backed = [...statusRows(catalogMd).values()].filter((r) => r.status === 'backed').length;
+    const backed = [...rows.values()].filter((r) => r.status === 'backed').length;
+
+    // Per-target completeness accounting. The target is a catalog ID, and the
+    // planned set is the UNION of the three places an id can appear — catalog
+    // tables, the § Detector status table, and the rule registry — because this
+    // gate's whole subject is parity BETWEEN those sets. Planning only the
+    // catalog would leave an orphan status row or a registry-only id
+    // unaccounted, which is the direction the gate exists to catch.
+    const ledger = new GateLedger('lint_design_antipattern_parity');
+    const targets = [
+        ...new Set([
+            ...catalogEntries(catalogMd),
+            ...rows.keys(),
+            ...registryCatalogIds(registryTs),
+        ]),
+    ].sort();
+    ledger.plan(targets);
+    const failedIds = new Set(findings.map((f) => f.id).filter((v): v is string => v !== undefined));
+    for (const id of targets) {
+        if (failedIds.has(id)) ledger.fail(id, 'parity finding');
+        else ledger.complete(id);
+    }
+    ledger.report();
 
     if (findings.length === 0) {
         _print(`✅  catalog ↔ rule parity OK — ${entries} entries classified, ${backed} detector-backed`);

package/src/scripts/lint_evidence_artifacts.ts

@@ -0,0 +1,359 @@
+/**
+ * Evidence artifacts declare what kind of evidence they are
+ * (road-to-release-review-p0 Phase 2).
+ *
+ * The contract is `docs/contracts/evidence-artifact-types.md`; this is its
+ * check. Read that document first — in particular its scope section, because
+ * the single most important property of this linter is what it deliberately
+ * does NOT do.
+ *
+ * **It is forward-looking, and there is no baseline file.** Measured by
+ * `--all` at the time of writing: 332 tracked markdown artifacts under
+ * `agents/evidence/`, 188 already resolving a type and 144 not.
+ * `check_completion_review` already refused to make one marker field required
+ * on the stated ground that it "would have been a migration event for the
+ * whole evidence corpus", and that reasoning is adopted rather than
+ * overturned. So the gate fires only on files ADDED relative to a base ref. A
+ * ratchet baseline was the obvious alternative and was rejected: it would mean
+ * committing a 144-entry suppression list, and a new baseline file in this
+ * repo trips two suppression gates of its own — paying a governance cost to
+ * enforce a rule the scope decision says should not be enforced retroactively.
+ *
+ * **Not registered in `gate-coverage.yml`, and the reason is the manifest's
+ * own.** A diff-scoped gate legitimately scans 0 on most runs, so it can carry
+ * no honest `min_scanned` floor, and `min_scanned: 0` is precisely the
+ * false-count shape that file rejects. `check_rule_projection_integrity` is
+ * the worked precedent: NOT registered, with the reason, ledger half
+ * discharged. This gate follows it — it adopts `_lib/gate_ledger.ts` below, so
+ * `check_gate_completeness` counts it as an adopter rather than a gap.
+ *
+ * **A declaration is read wherever the author already wrote one.** Three of
+ * the five types are pre-existing line grammars owned by
+ * `check_completion_review.ts`, and this linter imports those parsers rather
+ * than re-implementing them. Re-declaring an artifact that already carries
+ * `<!-- completion-review: v1 … -->` under a second `evidence-type:` marker
+ * would be the ambiguity the contract exists to remove.
+ *
+ * Modes:
+ *   --new-only <base-ref>   gate: fail on an ADDED artifact with no type
+ *   --all                   report: corpus census, always exit 0
+ *   --quiet                 verdict line only
+ *
+ * Exit 0 = clean (or report mode). Exit 1 = an added artifact carries no
+ * resolvable type. Exit 2 = the linter could not run (bad ref, no git).
+ */
+
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { GateLedger } from './_lib/gate_ledger.js';
+import { resolveBaseRef } from './_lib/ratchet_base_ref.js';
+import { reportScanned } from './_lib/scan_scope.js';
+import { parseHonestNull, parseMarkerLine, parseSkipDeclaration } from './check_completion_review.js';
+
+export const EVIDENCE_ROOT = path.join('agents', 'evidence');
+
+/** The five types the contract defines. Anything else is an error, not a warning. */
+export const EVIDENCE_TYPES = [
+    'original-review',
+    'current-binding',
+    'declared-skip',
+    'honest-null',
+    'analysis',
+] as const;
+
+export type EvidenceType = (typeof EVIDENCE_TYPES)[number];
+
+/** The explicit marker, for the two types with no pre-existing grammar. */
+const TYPE_MARKER_RE = /^<!--\s*evidence-type:\s*([a-z-]+)\s*-->$/;
+
+/** How many leading lines are scanned for the marker. A type belongs at the top. */
+const MARKER_SCAN_LINES = 40;
+
+export interface TypeResolution {
+    readonly type: EvidenceType | null;
+    /** Which declaration produced it — named so a reader can check the claim. */
+    readonly via: 'marker' | 'completion-review' | 'honest-null' | 'skip' | 'review-input-path' | null;
+    /** Set when a marker was present but named something outside the set. */
+    readonly invalidMarker: string | null;
+}
+
+/**
+ * Resolve one artifact's declared type.
+ *
+ * Order matters and encodes the contract: the pre-existing grammars are
+ * checked FIRST, so an artifact that already declares itself through
+ * `check_completion_review`'s vocabulary is never asked for a second marker.
+ * The path rule is last and is the contract's one acknowledged exception.
+ */
+export function resolveEvidenceType(relPath: string, contents: string): TypeResolution {
+    // BOTH scans share one window. They did not: the grammar scan walked the
+    // whole file while the marker scan stopped at 40 lines, so a quoted
+    // `completion-review` line deep in a prose artifact silently overrode an
+    // explicit `evidence-type:` marker its author had written at the top
+    // (R2 finding 8). A declaration belongs near the top of the file either
+    // way, and one window makes the precedence readable instead of positional.
+    const lines = contents.split('\n').slice(0, MARKER_SCAN_LINES);
+
+    for (const raw of lines) {
+        const line = raw.trim();
+        if (line === '') {
+            continue;
+        }
+        if (parseMarkerLine(line) !== null) {
+            return { type: 'current-binding', via: 'completion-review', invalidMarker: null };
+        }
+        if (parseHonestNull(line) !== null) {
+            return { type: 'honest-null', via: 'honest-null', invalidMarker: null };
+        }
+        if (parseSkipDeclaration(line) !== null) {
+            return { type: 'declared-skip', via: 'skip', invalidMarker: null };
+        }
+    }
+
+    for (const raw of lines) {
+        const m = TYPE_MARKER_RE.exec(raw.trim());
+        if (m === null) {
+            continue;
+        }
+        const value = m[1] as string;
+        if ((EVIDENCE_TYPES as readonly string[]).includes(value)) {
+            return { type: value as EvidenceType, via: 'marker', invalidMarker: null };
+        }
+        // A misspelled type reads as untyped to every consumer, which is the
+        // state the contract exists to end — so it is louder than absence,
+        // not quieter.
+        return { type: null, via: null, invalidMarker: value };
+    }
+
+    // The contract's single filename-derived case. Safe because the directory
+    // is written by `dispatch_r2_reviewer.ts` and by nothing else, so the path
+    // IS the declaration rather than a heuristic about one.
+    // Split on `/`, never `path.sep`. Every caller feeds paths from
+    // `git diff --name-only` / `git ls-files`, and git emits `/`-separated
+    // paths on every platform — so on Windows `path.sep` (`\`) made the whole
+    // path one segment and this branch could never match (R2 finding 10).
+    // `\` is accepted too so a hand-built Windows path still resolves.
+    if (relPath.split(/[/\\]/).some((seg) => seg.endsWith('.review-input'))) {
+        return { type: 'original-review', via: 'review-input-path', invalidMarker: null };
+    }
+
+    return { type: null, via: null, invalidMarker: null };
+}
+
+function _git(root: string, args: readonly string[]): string {
+    return execFileSync('git', [...args], { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+}
+
+/** Markdown files ADDED under `agents/evidence/` relative to `baseRef`. */
+export function addedEvidenceFiles(root: string, baseRef: string): string[] {
+    const out = _git(root, [
+        'diff',
+        '--name-only',
+        '--diff-filter=A',
+        `${baseRef}...HEAD`,
+        '--',
+        `${EVIDENCE_ROOT}/`,
+    ]);
+    return out
+        .split('\n')
+        .map((s) => s.trim())
+        .filter((s) => s !== '' && s.endsWith('.md'));
+}
+
+/** Every markdown artifact in the corpus, for the census mode. */
+export function allEvidenceFiles(root: string): string[] {
+    const out = _git(root, ['ls-files', '--', `${EVIDENCE_ROOT}/`]);
+    return out
+        .split('\n')
+        .map((s) => s.trim())
+        .filter((s) => s !== '' && s.endsWith('.md'));
+}
+
+export interface Finding {
+    readonly file: string;
+    readonly reason: string;
+}
+
+export function checkFiles(root: string, files: readonly string[], ledger?: GateLedger): Finding[] {
+    const findings: Finding[] = [];
+    ledger?.plan([...files]);
+    for (const rel of files) {
+        let contents: string;
+        try {
+            contents = fs.readFileSync(path.join(root, rel), 'utf8');
+        } catch {
+            // A file listed by git but unreadable on disk is not this
+            // linter's finding to report — a deleted-then-re-added path in a
+            // dirty tree hits this and is somebody else's gate.
+            ledger?.outOfScope(rel, 'no_applicable_files');
+            continue;
+        }
+        const res = resolveEvidenceType(rel, contents);
+        if (res.invalidMarker !== null) {
+            ledger?.fail(rel, `invalid evidence-type: ${res.invalidMarker}`);
+            findings.push({
+                file: rel,
+                reason:
+                    `evidence-type: ${res.invalidMarker} is not one of ` +
+                    `${EVIDENCE_TYPES.join(' | ')}`,
+            });
+            continue;
+        }
+        if (res.type === null) {
+            ledger?.fail(rel, 'no evidence type declared');
+            findings.push({
+                file: rel,
+                reason:
+                    'no evidence type declared — add `<!-- evidence-type: analysis -->` ' +
+                    '(or the type that fits) per docs/contracts/evidence-artifact-types.md',
+            });
+            continue;
+        }
+        ledger?.complete(rel);
+    }
+    return findings;
+}
+
+function _argValue(flag: string): string | null {
+    const i = process.argv.indexOf(flag);
+    if (i === -1) {
+        return null;
+    }
+    const v = process.argv[i + 1];
+    return v === undefined || v.startsWith('--') ? null : v;
+}
+
+export function main(): number {
+    const quiet = process.argv.includes('--quiet');
+    const root = process.cwd();
+    const out = (s: string): void => {
+        if (!quiet) {
+            process.stdout.write(`${s}\n`);
+        }
+    };
+
+    if (process.argv.includes('--all')) {
+        let files: string[];
+        try {
+            files = allEvidenceFiles(root);
+        } catch (exc) {
+            process.stdout.write(`lint_evidence_artifacts: cannot list ${EVIDENCE_ROOT} — ${String(exc)}\n`);
+            return 2;
+        }
+        const ledger = new GateLedger('lint_evidence_artifacts');
+        const findings = checkFiles(root, files, ledger);
+        ledger.report();
+        // Census mode reads the whole corpus, so a zero here IS blindness —
+        // no `allowEmpty`, deliberately. The gate mode below is the opposite
+        // case and says so on its own line.
+        reportScanned({
+            gate: 'lint_evidence_artifacts --all',
+            scanned: files.length,
+            units: 'evidence artifacts',
+            roots: [EVIDENCE_ROOT],
+        });
+        const typed = files.length - findings.length;
+        out(`lint_evidence_artifacts — census over ${String(files.length)} artifact(s)`);
+        out(`  typed    ${String(typed)}`);
+        out(`  untyped  ${String(findings.length)}`);
+        // Report mode, never a gate: the pre-existing untyped corpus is a
+        // deliberate scope exclusion, so publishing the number is the point
+        // and failing on it would contradict the contract.
+        process.stdout.write(
+            `lint_evidence_artifacts: census — ${String(typed)} typed, ${String(findings.length)} untyped (report only)\n`,
+        );
+        return 0;
+    }
+
+    // A bare invocation IS the gate, resolving its own base. Requiring an
+    // explicit ref would have made the roadmap's own `verify:` annotation exit
+    // 2 on a usage error, and a check whose default invocation is a usage
+    // error is a check nobody runs. `--new-only <ref>` stays as the override.
+    //
+    // `resolveBaseRef` rather than a hardcoded `origin/main`: `actions/checkout`
+    // performs a shallow PR-merge fetch, so a PR build frequently has no
+    // `origin/main` remote-tracking ref at all. That ladder already handles it
+    // and is the repo's one answer to this question.
+    const baseRef = _argValue('--new-only') ?? resolveBaseRef(root);
+    if (baseRef === null) {
+        // Fail rather than compare against an assumed-empty base — the same
+        // default `resolveBaseRef`'s own docstring names. An unresolvable base
+        // would otherwise make every artifact look un-added and the gate would
+        // pass by scanning nothing.
+        process.stdout.write(
+            'lint_evidence_artifacts: no base ref resolved — pass --new-only <ref>, ' +
+                'set RATCHET_BASE_REF, or run --all for the census\n',
+        );
+        return 2;
+    }
+
+    let files: string[];
+    try {
+        files = addedEvidenceFiles(root, baseRef);
+    } catch (exc) {
+        process.stdout.write(`lint_evidence_artifacts: cannot diff against ${baseRef} — ${String(exc)}\n`);
+        return 2;
+    }
+
+    const ledger = new GateLedger('lint_evidence_artifacts');
+    const findings = checkFiles(root, files, ledger);
+    ledger.report();
+    // A run that scans nothing exits green, and SAYS SO — silent green over an
+    // empty set is how a gate stops measuring anything without anyone
+    // noticing. The `allowEmpty` reason is `EMPTY_VALID` rather than
+    // `OPTIONAL_INPUT`: this gate measures a DIFF, not a corpus, so "no
+    // evidence artifact was added on this branch" genuinely is the success
+    // state and stays true even if `agents/evidence/` were deleted entirely.
+    reportScanned({
+        gate: 'lint_evidence_artifacts',
+        scanned: files.length,
+        units: 'added evidence artifacts',
+        roots: [EVIDENCE_ROOT],
+        allowEmpty:
+            'EMPTY_VALID: the scope is the set of artifacts ADDED since the base ref; ' +
+            'a branch that adds none has nothing to type, and zero is the pass.',
+    });
+    if (files.length === 0) {
+        process.stdout.write(
+            `lint_evidence_artifacts: ✅ no evidence artifact added since ${baseRef} — nothing to check\n`,
+        );
+        return 0;
+    }
+    out(`lint_evidence_artifacts — ${String(files.length)} added artifact(s) since ${baseRef}`);
+    if (findings.length === 0) {
+        process.stdout.write(
+            `lint_evidence_artifacts: ✅ all ${String(files.length)} added artifact(s) declare a type\n`,
+        );
+        return 0;
+    }
+    process.stdout.write(`lint_evidence_artifacts: ❌ ${String(findings.length)} untyped artifact(s)\n`);
+    for (const f of findings) {
+        process.stdout.write(`  ${f.file}\n    ${f.reason}\n`);
+    }
+    return 1;
+}
+
+const _HERE = fileURLToPath(import.meta.url);
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exit(main());
+}

package/src/scripts/lint_harvest_provenance.ts

@@ -49,6 +49,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { GateLedger } from './_lib/gate_ledger.js';
 import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
 
 const _FILE = fileURLToPath(import.meta.url);
@@ -432,7 +433,40 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     const text = fs.readFileSync(ledgerPath, 'utf-8');
     const { records, findings } = lintLedgerText(text, REPO);
     const citations = [...collectCitations(REPO), ...collectPersonaSources(REPO)];
-    const allFindings = [...findings, ...findOrphanCitations(citations, records)];
+    const orphans = findOrphanCitations(citations, records);
+    const allFindings = [...findings, ...orphans];
+
+    // Per-target completeness accounting over the two populations this gate
+    // reasons about: the ledger's own rows, and the citations that point at
+    // them. Both are legitimately EMPTY today, and that is exactly why the
+    // accounting is worth having — a green line over zero rows and a green line
+    // over a hundred checked rows read identically without it, which is the
+    // failure the success message above already tries to talk its way out of in
+    // prose. The ledger states it structurally instead.
+    const ledger = new GateLedger('lint_harvest_provenance');
+    const known = new Set(records.map((r) => r.harvest_id));
+    // The row population is every PARSED ledger line, not `records`: a row that
+    // fails validation or uniqueness is `continue`d and never reaches `records`,
+    // so planning `records` would plan exactly the rows that passed and account
+    // for none of the ones that did not — an accounting that can only ever read
+    // 100 %. Lines are the stable key; a Finding already carries one.
+    const { parsed } = parseLedgerText(text);
+    const badLines = new Set(findings.filter((f) => f.line > 0).map((f) => f.line));
+    ledger.plan([
+        ...parsed.map((r) => `row:${String(r.line)}`),
+        ...citations.map((c) => `citation:${c.id}@${c.file}`),
+    ]);
+    for (const r of parsed) {
+        const id = `row:${String(r.line)}`;
+        if (badLines.has(r.line)) ledger.fail(id, 'ledger-row finding');
+        else ledger.complete(id);
+    }
+    for (const c of citations) {
+        const id = `citation:${c.id}@${c.file}`;
+        if (known.has(c.id)) ledger.complete(id);
+        else ledger.fail(id, 'orphan citation — no ledger row carries this harvest id');
+    }
+    ledger.report();
 
     if (allFindings.length > 0) {
         for (const f of allFindings) {

package/src/scripts/lint_roadmap_blockers.ts

@@ -9,6 +9,11 @@
  *      (Status, Owner, Blocks, What to do, Resolved when).
  *   2. Every inline `<!-- blocked-by: <id> -->` annotation resolves to a
  *      `### blocker: <id>` entry declared in the SAME file.
+ *   3. An entry that declares `- **Class:**` declares a class the taxonomy
+ *      knows (0-3), and a class-0 or class-1 entry says HOW it runs
+ *      (`- **Run:**`). A gate that claims to be executable without naming the
+ *      command is the same defect as a decision with no option set: it reads
+ *      as actionable and is not.
  *
  * Fenced code blocks are stripped before scanning so a roadmap that shows
  * the `## Blockers` shape as a documentation example is not flagged.
@@ -63,6 +68,36 @@ const DECIDABILITY_FIELDS: ReadonlyArray<readonly [string, RegExp]> = [
     ['If you do nothing', /^-[ \t]*\*\*If you do nothing:\*\*[ \t]*\S/im],
 ];
 
+/**
+ * The gate taxonomy's four classes, as authored in the blocker entry.
+ *
+ * `Class` is deliberately OPTIONAL and its absence means class 3 — human-only.
+ * Making the safe class the default is what keeps a misclassification a
+ * reviewed edit rather than a runtime judgment: nothing an author forgets to
+ * write can become executable by omission.
+ */
+const CLASS_FIELD_RE = /^-[ \t]*\*\*Class:\*\*[ \t]*(.*)$/im;
+const RUN_FIELD_RE = /^-[ \t]*\*\*Run:\*\*[ \t]*(\S.*)$/im;
+const KNOWN_CLASSES: ReadonlySet<string> = new Set(['0', '1', '2', '3']);
+/** The classes whose whole claim is that an agent can execute them. */
+const RUNNABLE_CLASSES: ReadonlySet<string> = new Set(['0', '1']);
+
+/**
+ * The authored class, or `''` when the entry declares none.
+ *
+ * Only the leading token is read, so `- **Class:** 1 — budget-preauthorized`
+ * parses as `1`: the taxonomy name is documentation for the reader and must
+ * not have to be spelled identically in every entry to stay valid.
+ */
+function _blockerClass(body: string): string {
+    const m = CLASS_FIELD_RE.exec(body);
+    if (!m) {
+        return '';
+    }
+    const raw = ((m[1] as string) ?? '').trim();
+    return raw === '' ? '' : (raw.split(/[\s—–-]/)[0] as string);
+}
+
 /** `What to do:` body — everything up to the next field marker. */
 const WHAT_TO_DO_SLICE_RE =
     /^-[ \t]*\*\*What to do:\*\*([\s\S]*?)(?=^-[ \t]*\*\*[A-Z]|^###[ \t]|$(?![\s\S]))/im;
@@ -157,6 +192,33 @@ function _scanBoth(rawText: string): ScanResult {
             // made would be churn, and the ratchet would never reach zero.
             const isResolved = /^-[ \t]*\*\*Status:\*\*[ \t]*resolved/im.test(body);
             if (!isResolved) {
+                // The class/run contract is HARD rather than ratcheted, and it
+                // can be: `Class:` is a new opt-in field, so on the day it
+                // ships no entry in the tree declares one and the rule fires on
+                // nothing. There is no backlog to grandfather — the "strict
+                // gate reds ~283 files" failure the decidability half had to
+                // avoid simply does not arise here.
+                const cls = _blockerClass(body);
+                if (cls !== '') {
+                    const at = _lineAt(text, sectionStart + cur.start);
+                    if (!KNOWN_CLASSES.has(cls)) {
+                        violations.push({
+                            line: at,
+                            message:
+                                `blocker '${cur.id}' declares unknown class '${cls}' ` +
+                                '(expected 0 auto-run, 1 budget-preauthorized, ' +
+                                '2 consent-once, or 3 human-only)',
+                        });
+                    } else if (RUNNABLE_CLASSES.has(cls) && !RUN_FIELD_RE.test(body)) {
+                        violations.push({
+                            line: at,
+                            message:
+                                `blocker '${cur.id}' is class ${cls} but declares no ` +
+                                '**Run:** command — a gate that claims to be runnable ' +
+                                'must say how',
+                        });
+                    }
+                }
                 const gaps = DECIDABILITY_FIELDS.filter(([, re]) => !re.test(body)).map(
                     ([name]) => name,
                 );
@@ -358,6 +420,9 @@ export {
     ROADMAP_GLOB,
     REQUIRED_FIELDS,
     DECIDABILITY_FIELDS,
+    KNOWN_CLASSES,
+    RUNNABLE_CLASSES,
+    _blockerClass,
     _hasExecutableSubstance,
     _scan,
     _scanBoth,

package/src/scripts/lint_roadmap_complexity.ts

@@ -445,7 +445,13 @@ function _check_external_population_gates(text: string, warnings: string[]): voi
 
 function _check_execution_mode(fm: string, problems: string[]): void {
     if (!fm || !/^execution:/m.test(fm)) {
-        return; // absent field = interactive default — valid
+        // Absent is VALID and stays valid — but it no longer means "interactive".
+        // Since road-to-user-out-of-the-loop Phase 1, an absent field is DERIVED
+        // by the `roadmap-process-loop § 3a` ladder from the invocation form, so
+        // the old comment here named a default that no longer exists. Nothing to
+        // check either way: this linter validates a declared value, and there is
+        // no declaration to validate.
+        return;
     }
     const m = EXEC_MODE_PAT.exec(fm);
     if (m === null) {