@event4u/agent-config 14.18.0 → 14.20.0

package/src/scripts/lint_evidence_artifacts.ts

@@ -55,15 +55,38 @@ import { parseHonestNull, parseMarkerLine, parseSkipDeclaration } from './check_
 
 export const EVIDENCE_ROOT = path.join('agents', 'evidence');
 
-/** The five types the contract defines. Anything else is an error, not a warning. */
+/** The 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',
+    'feel',
 ] as const;
 
+/**
+ * The closed method vocabulary a `feel` artifact must name.
+ *
+ * Closed on purpose. An evidence class nothing can emit is a vocabulary entry,
+ * not a control, and the cheapest way to satisfy a perceptual floor is to write
+ * the word "feel" and move on. Requiring one of four named methods makes the
+ * claim falsifiable: each says how the motion was actually looked at.
+ */
+export const FEEL_METHODS = ['slow-motion', 'frame-step', 'device', 'next-day'] as const;
+export type FeelMethod = (typeof FEEL_METHODS)[number];
+
+const FEEL_LINE_RE = new RegExp(
+    String.raw`^\*\*Feel:\*\*\s+(${FEEL_METHODS.join('|')})\s+[\u2014-]\s+(\S.*)$`,
+);
+
+/** The method and outcome a `feel` line declares, or `null` when it declares neither. */
+export function parseFeelLine(line: string): { method: FeelMethod; outcome: string } | null {
+    const m = FEEL_LINE_RE.exec(line.trim());
+    if (m === null) return null;
+    return { method: m[1] as FeelMethod, outcome: (m[2] ?? '').trim() };
+}
+
 export type EvidenceType = (typeof EVIDENCE_TYPES)[number];
 
 /** The explicit marker, for the two types with no pre-existing grammar. */
@@ -202,6 +225,27 @@ export function checkFiles(root: string, files: readonly string[], ledger?: Gate
             });
             continue;
         }
+        // Risk 5 of road-to-one-motion-authority: the floor is the METHOD
+        // token, not the word. An outcome of `unbacked` is legal — a
+        // perceptual check that found nothing is still a check that ran — but
+        // an absent line is not, and neither is a method outside the four.
+        if (res.type === 'feel') {
+            const declared = contents
+                .split('\n')
+                .slice(0, MARKER_SCAN_LINES)
+                .some((l) => parseFeelLine(l) !== null);
+            if (!declared) {
+                ledger?.fail(rel, 'feel artifact with no method line');
+                findings.push({
+                    file: rel,
+                    reason:
+                        'declares `evidence-type: feel` but carries no `**Feel:** <method> — <outcome>` '
+                        + `line naming one of ${FEEL_METHODS.join(' | ')}. An outcome of \`unbacked\` is legal; `
+                        + 'an absent method is not',
+                });
+                continue;
+            }
+        }
         if (res.type === null) {
             ledger?.fail(rel, 'no evidence type declared');
             findings.push({

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);
     }

package/src/scripts/lint_hidden_unicode.ts

@@ -220,9 +220,19 @@ function _cpName(cp: number): string {
 }
 
 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 })) {
         let vs_run = 0;
@@ -260,7 +270,7 @@ export function _scan(sf: sl.ScannedFile): sl.Finding[] {
             );
         }
     }
-    return out;
+    return finish(out);
 }
 
 // ---------------------------------------------------------------------------
@@ -464,12 +474,14 @@ export function _sanitize(filePath: string): string {
 }
 
 interface Args {
+    /** Scan base for the bounded root mode; absent = the package root. */
+    root?: string;
     json: boolean;
     fix: boolean;
 }
 
 function _argError(msg: string): never {
-    process.stderr.write('usage: lint_hidden_unicode [-h] [--json] [--fix]\n');
+    process.stderr.write('usage: lint_hidden_unicode [-h] [--json] [--fix] [--root DIR]\n');
     process.stderr.write(`lint_hidden_unicode: error: ${msg}\n`);
     process.exit(2);
 }
@@ -477,14 +489,30 @@ function _argError(msg: string): never {
 function parse_args(argv: readonly string[]): Args {
     const out: Args = { json: false, fix: 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_hidden_unicode [-h] [--json] [--fix]\n');
+            process.stdout.write('usage: lint_hidden_unicode [-h] [--json] [--fix] [--root DIR]\n');
             process.exit(0);
         } else if (a === '--json') {
             out.json = true;
         } else if (a === '--fix') {
             out.fix = 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);
         }
@@ -497,11 +525,12 @@ 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[] = [];
     const flagged = new Set<string>();
     let corpusFiles = 0;
-    for (const sf of sl.iter_corpus()) {
+    for (const sf of sl.iter_corpus(sl.DEFAULT_SCAN_ROOTS, ['.md'], scanBase)) {
         corpusFiles += 1;
         const hits = _scan(sf);
         for (const h of hits) {
@@ -540,7 +569,12 @@ export function main(argv: readonly string[] | null = null): number {
     // corpus) and a narrower codepoint set (C0 only). `--fix` does not touch
     // these — rewriting a source file's bytes is the author's call, and the
     // finding names the escape to use.
-    const sourceFiles = _eligibleSourceFiles();
+    // The source pass enumerates TRACKED files via `git ls-files`, which is a
+    // property of the repository and not of the scan base. Under `--root` it
+    // would import this repository's own files into a scan of somebody else's
+    // directory and attribute the findings to it, so bounded mode skips it and
+    // the `.md` corpus under DIR is the whole scan.
+    const sourceFiles = args.root === undefined ? _eligibleSourceFiles() : [];
     for (const h of _scanSourceControlBytes(sourceFiles)) {
         findings.push(h);
     }
@@ -566,6 +600,14 @@ export function main(argv: readonly string[] | null = null): number {
         }
     }
 
+    // Publish what this child inspected so the umbrella can aggregate a real
+    // corpus size rather than a count of children. BOTH passes count: the `.md`
+    // corpus and the raw-control-byte pass over tracked source files, which is a
+    // separate scope this linter genuinely reads.
+    if (args.json) {
+        sl.report_child_scanned(corpusFiles + (sourceFiles === null ? 0 : sourceFiles.length));
+    }
+
     if (args.json) {
         const payload = sl.py_json_dumps_indent2(findings.map((f) => f.toDict()));
         process.stdout.write(payload + '\n');

package/src/scripts/lint_hook_manifest.ts

@@ -13,8 +13,11 @@
  *   - a platform binding referencing an unknown event
  *   - a native_event_aliases block referencing an unknown event or platform
  *   - an orphan `<platform>-dispatcher.sh` trampoline without a manifest block
+ *   - a `host_lowering.yaml` row whose `verified.expires` has passed (or which
+ *     was never verified) while it still carries a blocking binding
  *
- * Soft-warns on placeholder platform blocks and dead concerns.
+ * Soft-warns on placeholder platform blocks, dead concerns, an expired row
+ * carrying no blocking binding, and an incomplete `verified` provenance block.
  *
  * Exit codes:
  *   0 — clean (warnings allowed)
@@ -29,6 +32,8 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { parse as parseYaml } from "yaml";
 
 import { assertScanned, DeadScopeError } from "./_lib/scan_scope.js";
+import { asOf } from "./_lib/as_of.js";
+import { parseHostLowering, type HostLowering } from "./hooks/host_lowering.js";
 import { RE_ARM_EVENTS } from "./_lib/prefix_stable_surfaces.js";
 
 // src/scripts/lint_hook_manifest.ts → two levels up is the repo root.
@@ -44,6 +49,7 @@ const DEFAULT_MANIFEST = path.join(
   "hook_manifest.yaml",
 );
 const HOOKS_DIR = path.join(REPO_ROOT, "src", "scripts", "hooks");
+const DEFAULT_HOST_LOWERING = path.join(HOOKS_DIR, "host_lowering.yaml");
 
 // Canonical event vocabulary — keep in lock-step with
 // docs/contracts/hook-architecture-v1.md and dispatch_hook.EVENT_VOCABULARY.
@@ -635,7 +641,80 @@ export function _check_roles(
   }
 }
 
-export function lint(manifestPath: string, strict: boolean): number {
+/**
+ * A capability fact that cannot expire is a capability fact nobody re-checks.
+ *
+ * Three rounds of corrections to the same host claims is what this gate exists
+ * to stop, so the rule is mechanical rather than editorial: an unverified row —
+ * and an expired one is unverified, by the same definition `host_semantics`
+ * uses — may not carry a blocking binding. Everything softer warns, because a
+ * lapse on an advisory row must not red an unrelated pull request.
+ */
+export function _check_host_lowering(
+  tablePath: string,
+  errors: string[],
+  warnings: string[],
+  today: string = asOf().toISOString().slice(0, 10),
+): void {
+  let table: HostLowering;
+  try {
+    table = parseHostLowering(fs.readFileSync(tablePath, "utf-8"));
+  } catch (exc) {
+    errors.push(
+      `host_lowering: ${tablePath} could not be read or parsed: ` +
+        `${exc instanceof Error ? exc.message : String(exc)}`,
+    );
+    return;
+  }
+  for (const [host, surfaces] of table) {
+    for (const [surface, row] of surfaces) {
+      const blocking = [...row.slots.entries()]
+        .filter(([, s]) => s.block_exit !== null)
+        .map(([slot]) => slot);
+      const expired = row.verified !== null && row.verified.expires < today;
+      const where = `host_lowering ${host}/${surface}`;
+
+      if (row.verified === null) {
+        if (blocking.length > 0) {
+          errors.push(
+            `${where}: carries a blocking binding (${blocking.join(", ")}) with \`verified: null\`. ` +
+              "Establish the row with a live deny probe and a dated `verified` block, or set " +
+              "`block_exit: null` on those slots.",
+          );
+        }
+        continue;
+      }
+      if (expired && blocking.length > 0) {
+        errors.push(
+          `${where}: \`verified.expires\` was ${row.verified.expires} and today is ${today}, ` +
+            `while the row still carries a blocking binding (${blocking.join(", ")}). ` +
+            "Re-establish it with a live deny probe on that host and move `expires` forward, " +
+            "or set `block_exit: null` on those slots — an expired row reads as unverified.",
+        );
+      } else if (expired) {
+        warnings.push(
+          `${where}: \`verified.expires\` was ${row.verified.expires} and today is ${today}. ` +
+            "The row carries no blocking binding, so nothing is degraded; re-establish it " +
+            "before attaching one.",
+        );
+      }
+      for (const field of ["docs_at", "host_version"] as const) {
+        if (row.verified[field] === null) {
+          warnings.push(`${where}: \`verified.${field}\` is null — the row is admissible but not fully cited.`);
+        }
+      }
+    }
+  }
+}
+
+export function lint(
+  manifestPath: string,
+  strict: boolean,
+  hostLoweringPath: string = DEFAULT_HOST_LOWERING,
+  // Threaded so a fixture test can pin the day the verdict is read against.
+  // Left undefined the check resolves it through `asOf()`.
+  today?: string,
+): number {
   if (!_isFile(manifestPath)) {
     process.stderr.write(
       `lint_hook_manifest: file not found: ${manifestPath}\n`,
@@ -664,6 +743,7 @@ export function lint(manifestPath: string, strict: boolean): number {
   _check_aliases(manifest, errors);
   _check_orphan_trampolines(manifest, errors);
   _check_dead_concerns(concernNames, bound, warnings);
+  _check_host_lowering(hostLoweringPath, errors, warnings, today);
 
   for (const w of warnings) {
     process.stderr.write(`warn: ${w}\n`);
@@ -703,17 +783,21 @@ export function lint(manifestPath: string, strict: boolean): number {
 
 export function main(argv: string[]): number {
   let manifest = DEFAULT_MANIFEST;
+  let hostLowering = DEFAULT_HOST_LOWERING;
   let strict = false;
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
     if (a === "--manifest") {
       manifest = argv[i + 1] ?? manifest;
       i += 1;
+    } else if (a === "--host-lowering") {
+      hostLowering = argv[i + 1] ?? hostLowering;
+      i += 1;
     } else if (a === "--strict") {
       strict = true;
     }
   }
-  return lint(manifest, strict);
+  return lint(manifest, strict, hostLowering);
 }
 
 function _isCliEntry(): boolean {

package/src/scripts/lint_instruction_smuggling.ts

@@ -71,9 +71,19 @@ function _strip_inline_code(text: string): string {
 }
 
 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[] = [];
     // prose = lines outside ANY fence; inline-code spans blanked.
     for (const [lineno, text] of sf.iter_lines({ skip_example_fence: true, skip_any_fence: true })) {
@@ -117,15 +127,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_instruction_smuggling [-h] [--json]\n');
+    process.stderr.write('usage: lint_instruction_smuggling [-h] [--json] [--root DIR]\n');
     process.stderr.write(`lint_instruction_smuggling: error: ${msg}\n`);
     process.exit(2);
 }
@@ -133,12 +145,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_instruction_smuggling [-h] [--json]\n');
+            process.stdout.write('usage: lint_instruction_smuggling [-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);
         }
@@ -151,10 +179,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 corpusFiles = 0;
-    for (const sf of sl.iter_corpus()) {
+    for (const sf of sl.iter_corpus(sl.DEFAULT_SCAN_ROOTS, ['.md'], scanBase)) {
         corpusFiles += 1;
         for (const h of _scan(sf)) {
             findings.push(h);
@@ -181,6 +210,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(corpusFiles);
+    }
+
     if (args.json) {
         const payload = sl.py_json_dumps_indent2(findings.map((f) => f.toDict()));
         process.stdout.write(payload + '\n');

package/src/scripts/lint_mcp_config_security.ts

@@ -119,9 +119,19 @@ function _suffix(p: string): string {
 }
 
 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 [start, numbered] of _candidate_chunks(sf)) {
         for (const [lineno, text] of numbered) {
@@ -166,15 +176,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_mcp_config_security [-h] [--json]\n');
+    process.stderr.write('usage: lint_mcp_config_security [-h] [--json] [--root DIR]\n');
     process.stderr.write(`lint_mcp_config_security: error: ${msg}\n`);
     process.exit(2);
 }
@@ -182,12 +194,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_mcp_config_security [-h] [--json]\n');
+            process.stdout.write('usage: lint_mcp_config_security [-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);
         }
@@ -200,13 +228,14 @@ 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[] = [];
     // scan .md (fenced examples) under the default roots PLUS named MCP configs
     // under src/templates (where the shipped claude_desktop_config template lives).
     const roots = [...sl.DEFAULT_SCAN_ROOTS, 'src/templates'];
     let corpusFiles = 0;
-    for (const sf of sl.iter_corpus(roots, ['.md', '.json', '.template'])) {
+    for (const sf of sl.iter_corpus(roots, ['.md', '.json', '.template'], scanBase)) {
         corpusFiles += 1;
         for (const h of _scan(sf)) {
             findings.push(h);
@@ -234,6 +263,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(corpusFiles);
+    }
+
     if (args.json) {
         const payload = sl.py_json_dumps_indent2(findings.map((f) => f.toDict()));
         process.stdout.write(payload + '\n');