@event4u/agent-config 14.19.0 → 14.20.0

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

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_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');