@event4u/agent-config 14.19.0 → 14.21.0

package/src/scripts/lint_agent_security.ts

@@ -26,8 +26,10 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { runCountedProbe } from "./_lib/counted_probe.js";
-import { assertWatchlistResolves, DeadScopeError } from "./_lib/scan_scope.js";
+import { runCountedProbe, type ProbeResult } from "./_lib/counted_probe.js";
+import { assertWatchlistResolves, DeadScopeError, reportScanned } from "./_lib/scan_scope.js";
+import { runGateCli, runSelfTest } from "./_lib/gate_self_test.js";
+import os from "node:os";
 
 const _HERE = path.dirname(fileURLToPath(import.meta.url));
 
@@ -50,26 +52,162 @@ const LINTERS: ReadonlyArray<[string, string]> = [
   ["dangerous-frontmatter", "lint_skill_frontmatter_safety.ts"],
 ];
 
-function _run(script: string): [number, Finding[]] {
-  // Spawn the child linter's `.ts` twin via the repo-local tsx binary
-  // (capture_output=True, text=True equivalent). Mirrors the retired Python implementation's
-  // `subprocess.run([sys.executable, HERE/<child>.py, "--json"])`, now that the
-  // children are TypeScript and the `.py` originals are deleted.
-  // Bounded read: a truncated `--json` payload would fail to parse and be
-  // swallowed as zero findings — a security aggregate reporting clean because
-  // it lost the answer. `runCountedProbe` throws on overflow instead.
-  const proc = runCountedProbe(tsxBin, [path.join(_HERE, script), "--json"]);
-  let findings: Finding[];
+/**
+ * How one child linter is executed.
+ *
+ * A seam, not a policy: the production runner is `_spawnChild` below and is the
+ * default everywhere. It exists so the failure corpus can drive each way a
+ * child can fail to ANSWER — non-zero with empty stdout, zero with unparsable
+ * stdout, and a spawn that never happened — without planting a broken linter in
+ * the tree. The four ways are not reproducible any other way: a real child that
+ * crashes on demand is a child that has to be able to crash in production.
+ */
+export type ChildRunResult = ProbeResult | { readonly skipped: SkipReason };
+export type ChildRunner = (script: string) => ChildRunResult;
+
+// Spawn the child linter's `.ts` twin via the repo-local tsx binary
+// (capture_output=True, text=True equivalent). Mirrors the retired Python implementation's
+// `subprocess.run([sys.executable, HERE/<child>.py, "--json"])`, now that the
+// children are TypeScript and the `.py` originals are deleted.
+// Bounded read: a truncated `--json` payload would fail to parse and be
+// swallowed as zero findings — a security aggregate reporting clean because
+// it lost the answer. `runCountedProbe` throws on overflow instead.
+function _spawnChild(root: string | null): ChildRunner {
+  return (script) =>
+    runCountedProbe(tsxBin, [
+      path.join(_HERE, script),
+      "--json",
+      ...(root === null ? [] : ["--root", root]),
+    ]);
+}
+
+/**
+ * The closed set of terminal outcomes a child run can have.
+ *
+ * Closed is the whole point. Before this, a child had one outcome — "here are
+ * its findings" — and every way of not answering collapsed into an empty
+ * findings array indistinguishable from a clean run. Three states make the
+ * distinction expressible, and `failed` is the one that blocks.
+ */
+export type ChildOutcome =
+  | {
+      readonly kind: "completed";
+      readonly findings: Finding[];
+      readonly exitCode: number;
+      /** Artifacts this child reported inspecting. See `CHILD_SCANNED` below. */
+      readonly scanned: number;
+    }
+  | { readonly kind: "failed"; readonly detail: string; readonly exitCode: number | null }
+  | { readonly kind: "skipped"; readonly reason: SkipReason };
+
+/**
+ * Skip reasons, as a RUNNER CONSTANT rather than configuration.
+ *
+ * A configurable skip list is a fail-open switch with a settings file in front
+ * of it: whoever can add a reason can silence a child. Keeping the set here
+ * means adding one is a reviewed code change in the gate itself.
+ *
+ * NO CHILD PRODUCES A SKIP TODAY, and that is stated rather than implied — all
+ * five apply on every platform this suite runs on. The state exists because the
+ * alternative to having it is the pressure this repair creates: once a
+ * non-completing child blocks, a genuinely non-applicable child would have to
+ * be expressed as `failed`, and the fix for that would be to weaken `failed`.
+ * A legal non-failing terminal state is what stops that. It is exercised
+ * through the runner seam in the failure corpus, so the branch is not dead.
+ */
+export const SKIP_REASONS = {
+  PLATFORM_NOT_APPLICABLE: "not applicable on this platform",
+} as const;
+export type SkipReason = (typeof SKIP_REASONS)[keyof typeof SKIP_REASONS];
+
+/**
+ * The child `--json` contract, stated so a violation of it is nameable:
+ *
+ *   exit 0  — ran, here is the findings array (possibly empty)
+ *   exit 1  — ran, here is the findings array (non-empty)
+ *   anything else, or a non-array payload, or unparsable stdout, or no run at
+ *   all — the child did not answer.
+ *
+ * Exit 1 with an EMPTY array is a violation and not a nit: every child returns
+ * its dead-scope code (1 or 2) with nothing on stdout, which is precisely the
+ * "the corpus moved and I read nothing" case that used to score as clean.
+ */
+function _classify(res: ChildRunResult): ChildOutcome {
+  // The execution layer decides WHETHER a child applies here; the reason it may
+  // give comes from `SKIP_REASONS` above, so a new reason is a reviewed code
+  // change in this file rather than a value someone can supply.
+  if ("skipped" in res) {
+    return { kind: "skipped", reason: res.skipped };
+  }
+  const proc = res;
+  // spawnSync reports null when the process was signalled or never spawned.
+  if (proc.status === null) {
+    return {
+      kind: "failed",
+      exitCode: null,
+      detail: `the child never ran (${proc.failure ?? "no exit status reported"})`,
+    };
+  }
+  let parsed: unknown;
   try {
-    const parsed: unknown = JSON.parse((proc.stdout ?? "") || "[]");
-    findings = Array.isArray(parsed) ? (parsed as Finding[]) : [];
+    parsed = JSON.parse((proc.stdout ?? "") || "[]");
   } catch {
-    findings = [];
+    return {
+      kind: "failed",
+      exitCode: proc.status,
+      detail:
+        `exited ${String(proc.status)} and its stdout was not JSON — a crashed child that ` +
+        "printed a diagnostic used to be read as zero findings",
+    };
+  }
+  if (!Array.isArray(parsed)) {
+    return {
+      kind: "failed",
+      exitCode: proc.status,
+      detail:
+        `exited ${String(proc.status)} and its stdout parsed but was not a findings array — ` +
+        "a JSON error object used to be read as zero findings",
+    };
+  }
+  const findings = parsed as Finding[];
+  if (proc.status !== 0 && !(proc.status === 1 && findings.length > 0)) {
+    return {
+      kind: "failed",
+      exitCode: proc.status,
+      detail:
+        `exited ${String(proc.status)} with ${String(findings.length)} finding(s), which is outside ` +
+        "the --json contract (0 = clean, 1 = findings; every other code means it could not run)",
+    };
+  }
+  // A child that ran but did not say what it read leaves the aggregate unable to
+  // publish a real corpus size — the same class of unknown as a crashed child,
+  // so it gets the same verdict rather than a silent zero.
+  const scanned = _childScanned(proc.stderr ?? "");
+  if (scanned === null) {
+    return {
+      kind: "failed",
+      exitCode: proc.status,
+      detail:
+        `exited ${String(proc.status)} without reporting what it inspected — an aggregate ` +
+        "corpus size cannot be published from a child that did not state one",
+    };
+  }
+  return { kind: "completed", findings, exitCode: proc.status, scanned };
+}
+
+/** Read a child's `scanned: <N>` line off its stderr. `null` = it printed none. */
+function _childScanned(stderr: string): number | null {
+  for (const line of stderr.split("\n")) {
+    const m = /^scanned: (\d+)$/.exec(line.trim());
+    if (m) {
+      return Number.parseInt(m[1] as string, 10);
+    }
   }
-  // Python returncode of a normally-exited process is its exit code; spawnSync
-  // reports null when the process was signalled / failed to spawn.
-  const returncode = proc.status ?? 1;
-  return [returncode, findings];
+  return null;
+}
+
+function _run(script: string, runChild: ChildRunner): ChildOutcome {
+  return _classify(runChild(script));
 }
 
 function _is_fail(f: Finding): boolean {
@@ -84,7 +222,7 @@ interface SarifReport {
   runs: unknown[];
 }
 
-function _sarif(all_findings: Finding[]): SarifReport {
+function _sarif(all_findings: Finding[], outcomes: ReadonlyArray<[string, string, ChildOutcome]>): SarifReport {
   const results: unknown[] = [];
   for (const f of all_findings) {
     const lineRaw = f["line"];
@@ -109,6 +247,21 @@ function _sarif(all_findings: Finding[]): SarifReport {
       ],
     });
   }
+  // Execution state rides in SARIF's OWN `invocations` array — the schema
+  // already models "did this tool run and with what exit code", so a parallel
+  // metadata block beside it would be a second, unread copy of the same fact.
+  // One invocation per child, in the order the children ran.
+  //
+  // `executionSuccessful` is the field a SARIF consumer reads to decide whether
+  // an empty `results` array means "clean" or "never looked". That is exactly
+  // the question this whole repair is about, so it is the field that carries it.
+  const invocations = outcomes.map(([, script, outcome]) => ({
+    commandLine: `${script} --json`,
+    executionSuccessful: outcome.kind === "completed",
+    ...(outcome.kind === "skipped" || outcome.exitCode === null
+      ? {}
+      : { exitCode: outcome.exitCode }),
+  }));
   return {
     $schema: "https://json.schemastore.org/sarif-2.1.0.json",
     version: "2.1.0",
@@ -121,6 +274,7 @@ function _sarif(all_findings: Finding[]): SarifReport {
             rules: LINTERS.map(([cid]) => ({ id: cid })),
           },
         },
+        invocations,
         results,
       },
     ],
@@ -149,10 +303,13 @@ function _pyJsonDumpsIndent2(obj: unknown): string {
 interface ParsedArgs {
   sarif: string | null;
   quiet: boolean;
+  /** Bounded scan base, forwarded verbatim to every child. Null = the package root. */
+  root: string | null;
+  selfTest: boolean;
 }
 
 function parse_args(argv: string[]): ParsedArgs {
-  const out: ParsedArgs = { sarif: null, quiet: false };
+  const out: ParsedArgs = { sarif: null, quiet: false, root: null, selfTest: false };
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i] as string;
     if (a === "--sarif" || a.startsWith("--sarif=")) {
@@ -170,11 +327,28 @@ function parse_args(argv: string[]): ParsedArgs {
         i += 1;
         out.sarif = next;
       }
+    } else if (a === "--root" || a.startsWith("--root=")) {
+      const eq = a.indexOf("=");
+      if (eq !== -1) {
+        out.root = a.slice(eq + 1);
+      } else {
+        const next = argv[i + 1];
+        if (next === undefined) {
+          process.stderr.write(
+            "lint_agent_security: error: argument --root: expected one argument\n",
+          );
+          process.exit(2);
+        }
+        i += 1;
+        out.root = next;
+      }
+    } else if (a === "--self-test") {
+      out.selfTest = true;
     } else if (a === "--quiet") {
       out.quiet = true;
     } else if (a === "-h" || a === "--help") {
       process.stdout.write(
-        "usage: lint_agent_security [-h] [--sarif PATH] [--quiet]\n",
+        "usage: lint_agent_security [-h] [--sarif PATH] [--quiet] [--root DIR] [--self-test]\n",
       );
       process.exit(0);
     }
@@ -182,8 +356,17 @@ function parse_args(argv: string[]): ParsedArgs {
   return out;
 }
 
-export function main(argv: string[] | null = null): number {
+export interface MainOptions {
+  /** Override how child linters are executed. Test seam; production uses `_spawnChild`. */
+  readonly runChild?: ChildRunner;
+}
+
+export function main(argv: string[] | null = null, opts: MainOptions = {}): number {
   const args = parse_args(argv ?? process.argv.slice(2));
+  if (args.selfTest) {
+    return _selfTest();
+  }
+  const runChild = opts.runChild ?? _spawnChild(args.root);
 
   // This runner owns no corpus of its own — it guards five named child linters,
   // so its scope is that watch list. `_run` swallows an unparseable child
@@ -204,9 +387,26 @@ export function main(argv: string[] | null = null): number {
   }
 
   const all_findings: Finding[] = [];
+  const outcomes: Array<[string, string, ChildOutcome]> = [];
+  const notCompleted: string[] = [];
   let blocking = 0;
+  let totalScanned = 0;
   for (const [check, script] of LINTERS) {
-    const [, findings] = _run(script);
+    const outcome = _run(script, runChild);
+    outcomes.push([check, script, outcome]);
+    if (outcome.kind === "failed") {
+      // Named on the line, because "one child failed" sends a reader to five
+      // linters. The exit code stays on the line for the same reason.
+      notCompleted.push(check);
+      process.stdout.write(`  ❌ ${check}: did not complete — ${outcome.detail}\n`);
+      continue;
+    }
+    if (outcome.kind === "skipped") {
+      process.stdout.write(`  ⏭️ ${check}: skipped — ${outcome.reason}\n`);
+      continue;
+    }
+    const findings = outcome.findings;
+    totalScanned += outcome.scanned;
     all_findings.push(...findings);
     const fails = findings.filter((f) => _is_fail(f)).length;
     const warns = findings.length - fails;
@@ -218,11 +418,50 @@ export function main(argv: string[] | null = null): number {
   if (args.sarif) {
     const out = args.sarif;
     fs.mkdirSync(path.dirname(out), { recursive: true });
-    fs.writeFileSync(out, _pyJsonDumpsIndent2(_sarif(all_findings)), "utf-8");
+    fs.writeFileSync(out, _pyJsonDumpsIndent2(_sarif(all_findings, outcomes)), "utf-8");
     process.stdout.write(`  SARIF → ${args.sarif}\n`);
   }
 
+  // Publish what the scan actually read, on EVERY path including the red one.
+  // The umbrella owns no corpus of its own — this number is the SUM of the five
+  // children's own reported counts, so it is artifact INSPECTIONS rather than
+  // distinct artifacts (a file two children read counts twice). That is the
+  // stronger collapse detector: a distinct-union figure would stay high while
+  // one child's corpus went missing, which is the failure this line exists to
+  // make visible. `src/config/gate-coverage.yml` carries the floor.
+  reportScanned({
+    gate: "lint_agent_security",
+    scanned: totalScanned,
+    units: "artifact inspection(s) across the five child linters",
+    roots: LINTERS.map(([cid]) => cid),
+    ...(notCompleted.length > 0
+      ? {
+          allowEmpty:
+            "WATCHLIST_DRIVEN: a child that did not complete reports no count. Zero here means " +
+            "every child failed, which this run is already exiting 1 for and naming — the scope " +
+            "is not dead, the children are.",
+        }
+      : {}),
+  });
+
   process.stdout.write("\n");
+  // A child that did not answer is reported BEFORE findings and fails on its
+  // own. The two are independent verdicts: findings say the corpus is dirty,
+  // a non-completing child says the verdict is unknown, and an unknown verdict
+  // is not a pass. Both can hold at once, and both print.
+  if (notCompleted.length > 0) {
+    process.stdout.write(
+      `❌  agent-security: ${notCompleted.length} of ${LINTERS.length} child linter(s) did not complete ` +
+        `(${notCompleted.join(", ")}). A child that did not answer is not a clean scan — ` +
+        "run it directly for its own diagnostic.\n",
+    );
+    if (blocking) {
+      process.stdout.write(
+        `❌  agent-security: ${blocking} blocking finding(s) from the children that did complete.\n`,
+      );
+    }
+    return 1;
+  }
   if (blocking) {
     process.stdout.write(
       `❌  agent-security: ${blocking} blocking finding(s). ` +
@@ -237,6 +476,58 @@ export function main(argv: string[] | null = null): number {
   return 0;
 }
 
+/**
+ * `--self-test` — prove, on demand, that the shipped binary still rejects.
+ *
+ * The two rejecting cases are the two ways this gate is supposed to go red, and
+ * they are different failures rather than one failure twice:
+ *
+ *  - EMPTY SCOPE. Every child asserts its own corpus is non-empty, so an empty
+ *    root makes all five exit non-zero with nothing on stdout — which, since the
+ *    fail-closed repair, is a run failure the umbrella names. This is also the
+ *    negative control the coverage floor owes: the run publishes `scanned: 0`,
+ *    and 0 is below any floor above zero, so `check_gate_coverage` reds on it.
+ *  - A PLANTED PAYLOAD. A zero-width joiner inside a `.md` file under an
+ *    otherwise clean root, which a child must flag as a blocking finding.
+ *
+ * The accepting case is the same root without the payload. Without it, a gate
+ * that returned non-zero unconditionally would score two rejections and look
+ * healthy.
+ */
+function _selfTest(): number {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "lint-agent-security-selftest-"));
+  const mk = (name: string, body: string): string => {
+    const dir = path.join(tmp, name, "src", "skills", "candidate");
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, "SKILL.md"), body, "utf-8");
+    return path.join(tmp, name);
+  };
+  const cleanRoot = mk("clean", "---\ntitle: candidate\n---\n\nOrdinary prose with nothing hidden in it.\n");
+  // U+200D ZERO WIDTH JOINER between two words — invisible, and exactly the
+  // hidden-instruction carrier class this umbrella exists to catch.
+  const payloadRoot = mk("payload", "---\ntitle: candidate\n---\n\nOrdinary\u200dprose with something hidden in it.\n");
+  const emptyRoot = path.join(tmp, "empty");
+  fs.mkdirSync(emptyRoot, { recursive: true });
+
+  const run = (root: string): number =>
+    runGateCli(REPO_ROOT, "src/scripts/lint_agent_security.ts", ["--root", root], REPO_ROOT);
+
+  try {
+    return runSelfTest({
+      gate: "lint_agent_security",
+      minCases: 3,
+      minRejectCases: 2,
+      cases: [
+        { name: "empty scope — every child reads nothing and the aggregate refuses", expect: "reject", run: () => run(emptyRoot) },
+        { name: "planted zero-width joiner — a child flags it and the aggregate blocks", expect: "reject", run: () => run(payloadRoot) },
+        { name: "clean root — the same scope without the payload still passes", expect: "accept", run: () => run(cleanRoot) },
+      ],
+    });
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
 function _isCliEntry(): boolean {
     if (process.argv[1] === undefined) {
         return false;

package/src/scripts/lint_confusables.ts

@@ -55,9 +55,19 @@ const _TOKEN = TOKEN_RE;
 export const _classify_token = classifyToken;
 
 export function _scan(sf: sl.ScannedFile): sl.Finding[] {
-    if (sf.pragma_allows(CHECK)) {
-        return [];
+    // A BOUND pragma suppresses only the matches it fingerprints, so the scan
+    // runs and its output is filtered at the end. An UNBOUND one keeps the old
+    // whole-file bail and reports itself.
+    const pragmaForm = sf.pragma_form(CHECK);
+    if (pragmaForm === 'legacy') {
+        return [sl.legacy_pragma_finding(sf, CHECK)];
     }
+    // EVERY exit from this function goes through `finish`. Wrapping only the
+    // terminal `return` is the defect that shipped for one commit here: this
+    // scan has an early return for an artifact with no `execution:` block, and a
+    // bound pragma silently did not apply to exactly those artifacts.
+    const finish = (hits: sl.Finding[]): sl.Finding[] =>
+        pragmaForm === 'bound' ? sf.filter_bound_pragma(CHECK, hits) : hits;
     const out: sl.Finding[] = [];
     for (const [lineno, text] of sf.iter_lines({ skip_example_fence: true })) {
         const tokens = text.match(_TOKEN);
@@ -78,15 +88,17 @@ export function _scan(sf: sl.ScannedFile): sl.Finding[] {
             }
         }
     }
-    return out;
+    return finish(out);
 }
 
 interface Args {
+    /** Scan base for the bounded root mode; absent = the package root. */
+    root?: string;
     json: boolean;
 }
 
 function _argError(msg: string): never {
-    process.stderr.write('usage: lint_confusables [-h] [--json]\n');
+    process.stderr.write('usage: lint_confusables [-h] [--json] [--root DIR]\n');
     process.stderr.write(`lint_confusables: error: ${msg}\n`);
     process.exit(2);
 }
@@ -94,12 +106,28 @@ function _argError(msg: string): never {
 function parse_args(argv: readonly string[]): Args {
     const out: Args = { json: false };
     const extra: string[] = [];
+    let rootPending = false;
     for (const a of argv) {
+        if (rootPending) {
+            out.root = a;
+            rootPending = false;
+            continue;
+        }
         if (a === '-h' || a === '--help') {
-            process.stdout.write('usage: lint_confusables [-h] [--json]\n');
+            process.stdout.write('usage: lint_confusables [-h] [--json] [--root DIR]\n');
             process.exit(0);
         } else if (a === '--json') {
             out.json = true;
+        } else if (a === '--root' || a.startsWith('--root=')) {
+            // Bounded root mode. Absent, this linter's own default roots stand;
+            // present, the same relative roots resolve against DIR instead. Used by
+            // the scout to scan a quarantined candidate, and by --self-test fixtures.
+            const eq = a.indexOf('=');
+            if (eq !== -1) {
+                out.root = a.slice(eq + 1);
+            } else {
+                rootPending = true;
+            }
         } else {
             extra.push(a);
         }
@@ -112,10 +140,11 @@ function parse_args(argv: readonly string[]): Args {
 
 export function main(argv: readonly string[] | null = null): number {
     const args = parse_args(argv ?? process.argv.slice(2));
+    const scanBase = args.root === undefined ? sl.ROOT : path.resolve(args.root);
 
     const findings: sl.Finding[] = [];
     let scanned = 0;
-    for (const sf of sl.iter_corpus()) {
+    for (const sf of sl.iter_corpus(sl.DEFAULT_SCAN_ROOTS, ['.md'], scanBase)) {
         // Counted on the corpus walk, not on `_scan`'s return: `iter_corpus`
         // skips a root that does not exist, so every root moving at once yields
         // zero files and the report line still says "clean (scanned <roots>)".
@@ -143,6 +172,13 @@ export function main(argv: readonly string[] | null = null): number {
         throw exc;
     }
 
+    // Publish what this child inspected so the umbrella can aggregate a real
+    // corpus size rather than a count of children. Same number the assertion
+    // above just accepted, so the published figure cannot drift from it.
+    if (args.json) {
+        sl.report_child_scanned(scanned);
+    }
+
     if (args.json) {
         const payload = sl.py_json_dumps_indent2(findings.map((f) => f.toDict()));
         process.stdout.write(payload + '\n');

package/src/scripts/lint_handoffs.ts

@@ -821,119 +821,6 @@ function _pyRepr(s: string): string {
     return `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
 }
 
-// ── HANDOFF.md artifact validation (workflow-contracts Phase 2) ─────────
-// SEPARATE concern from the cross-wing skill-handoff lint above: this
-// validates the OPTIONAL standing workflow-resume artifact
-// (agents/runtime/state/HANDOFF.md, written by /agent-handoff --file).
-// Same file on purpose — one linter owns everything named "handoff";
-// the naming reconciliation is this comment.
-
-export const HANDOFF_ARTIFACT_REQUIRED = [
-    'Mode',
-    'Contract received',
-    'Contract owed',
-    'Decisions',
-    'Open questions',
-    'Next command',
-] as const;
-
-/** Returns missing required section headings ([] = valid). */
-export function validate_handoff_artifact(text: string): string[] {
-    const missing: string[] = [];
-    for (const heading of HANDOFF_ARTIFACT_REQUIRED) {
-        const re = new RegExp(`^##\\s+${heading}\\s*$`, 'mi');
-        if (!re.test(text)) {
-            missing.push(heading);
-        }
-    }
-    return missing;
-}
-
-/**
- * The body of a `## <heading>` section, up to the next heading of the same or a
- * higher level. Fenced blocks are stripped first so a `##` inside a code fence
- * cannot end the section early — a resume artefact routinely quotes commands.
- */
-export function handoff_section_body(text: string, heading: string): string | null {
-    const withoutFences = text.replace(/^```[\s\S]*?^```\s*$/gm, '');
-    const start = new RegExp(`^##\\s+${heading}\\s*$`, 'mi').exec(withoutFences);
-    if (start === null) {
-        return null;
-    }
-    const rest = withoutFences.slice(start.index + start[0].length);
-    const next = /^#{1,2}\s+\S/m.exec(rest);
-    return next === null ? rest : rest.slice(0, next.index);
-}
-
-// An explicit "there are none" answer. Kept as a closed list rather than a
-// heuristic so the escape cannot be widened by accident: a section saying
-// nothing and a section saying "none" are different facts, and only the first is
-// a defect.
-const _NO_OPEN_QUESTIONS = new Set(['none', 'keine', 'n/a', 'na', 'no open questions', 'nothing']);
-
-/**
- * Strip list markers, checkbox glyphs, emphasis and trailing sentence
- * punctuation. The trailing strip is skipped when it would empty the line: a
- * line that is ONLY punctuation (`...`) is a placeholder to name, not an empty
- * section to report as blank, and the two findings say different things.
- */
-function _bareLine(line: string): string {
-    const stripped = line
-        .trim()
-        .replace(/^[-*+]\s*/, '')
-        .replace(/^\[[ x~-]\]\s*/i, '')
-        .replace(/[*_`]/g, '')
-        .trim()
-        .toLowerCase();
-    const trimmed = stripped.replace(/[.!]+$/, '').trim();
-    return trimmed.length > 0 ? trimmed : stripped;
-}
-
-/**
- * Shape check on the one required section whose emptiness is the defect rather
- * than a style nit. `validate_handoff_artifact` only tests that the heading
- * exists, so `## Open questions` followed by nothing passed while carrying
- * nothing — and a resume artefact whose open questions are blank hands the next
- * session a false all-clear.
- *
- * **The step this implements claimed the false-positive class was empty because
- * one `?`-terminated line is required. It is not, and the counterexample ships
- * in this repo:** `tests/scripts/lint_handoffs_artifact.test.ts` carries
- * `## Open questions` / `- none`, which is an honest answer and would be forced
- * to grow a fake question. So the check accepts EITHER a real question OR an
- * explicit none-marker, and fires only on a section that answers neither —
- * blank, or a bare placeholder. That keeps the defect the step names without
- * turning a truthful "none" into a lint error.
- *
- * Returns a finding string, or null when the shape holds. A MISSING section is
- * not this check's business — `validate_handoff_artifact` already reports it.
- */
-export function validate_handoff_open_questions(text: string): string | null {
-    const body = handoff_section_body(text, 'Open questions');
-    if (body === null) {
-        return null;
-    }
-    const lines = body
-        .split('\n')
-        .map((l) => l.trim())
-        .filter((l) => l.length > 0);
-    if (lines.some((l) => l.length > 1 && l.endsWith('?'))) {
-        return null;
-    }
-    const bare = lines.map(_bareLine).filter((l) => l.length > 0);
-    if (bare.some((l) => _NO_OPEN_QUESTIONS.has(l))) {
-        return null;
-    }
-    if (bare.length === 0) {
-        return 'section `## Open questions` is empty — carry a `?`-terminated question, or state `none`';
-    }
-    const placeholder = new Set(['tbd', 'todo', 'wip', '...', '…', '?']);
-    if (bare.every((l) => placeholder.has(l))) {
-        return 'section `## Open questions` carries only a placeholder — carry a `?`-terminated question, or state `none`';
-    }
-    return null;
-}
-
 /** `git rev-parse HEAD`, or null outside a repository. */
 function _headCommit(): string | null {
     try {
@@ -978,25 +865,6 @@ export function main(argv?: readonly string[]): number {
         process.stdout.write(JSON.stringify(census, null, 2) + '\n');
         return 0;
     }
-    if (args.length > 0 && String(args[0]).endsWith('HANDOFF.md')) {
-        // artifact mode — validate the workflow-resume file's required fields
-        const text = fs.readFileSync(_resolve(args[0] as string), 'utf-8');
-        const missing = validate_handoff_artifact(text);
-        const shape = validate_handoff_open_questions(text);
-        if (missing.length === 0 && shape === null) {
-            if (!QUIET) process.stdout.write('✅  HANDOFF artifact: all required fields present\n');
-            return 0;
-        }
-        for (const m of missing) {
-            process.stdout.write(`${args[0]}:1:handoff-artifact-missing-field: missing required section \`## ${m}\`\n`);
-        }
-        if (shape !== null) {
-            process.stdout.write(`${args[0]}:1:handoff-artifact-empty-section: ${shape}\n`);
-        }
-        const problems = missing.length + (shape === null ? 0 : 1);
-        process.stderr.write(`❌  ${problems} HANDOFF artifact problem(s)\n`);
-        return 1;
-    }
     if (args.length > 0) {
         skills_dir = _resolve(args[0] as string);
     }