@event4u/agent-config 14.19.0 → 14.21.0

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

package/src/scripts/lint_roadmap_blockers.ts

@@ -14,6 +14,19 @@
  *      (`- **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.
+ *   4. An annotation pointing at a USER-DECISION blocker (one whose `Owner:`
+ *      is the maintainer, the user, or the owner) carries an `asked:` field
+ *      recording whether the question was put and, when it was not, why —
+ *      `<!-- blocked-by: <id> | asked: no — <reason> -->`. A decision only the
+ *      user can make, filed in a roadmap without ever being put, is the defect
+ *      road-to-asked-not-parked exists to stop; without this field a marker
+ *      cannot distinguish a declined decision from an unoffered one.
+ *
+ *      HARD, not ratcheted, and it can be: no active roadmap carries a real
+ *      checkbox annotation today, so on the day it ships the rule fires on
+ *      nothing — the same "no backlog to grandfather" argument the `Class:`
+ *      contract above makes. `later/` and `archive/` are outside this gate's
+ *      glob and are untouched by it.
  *
  * Fenced code blocks are stripped before scanning so a roadmap that shows
  * the `## Blockers` shape as a documentation example is not flagged.
@@ -42,7 +55,19 @@ const BLOCKER_HEADING_RE = /^###[ \t]+blocker:[ \t]*(.+?)[ \t]*$/gim;
 // wrapped continuation line or inline-code documentation example of the
 // syntax (as this very lint script's own roadmap step describes it) must
 // not be mistaken for a live cross-reference.
-const BLOCKED_BY_LINE_RE = /^-[ \t]*\[[ xX~-]\].*<!--[ \t]*blocked-by:[ \t]*([a-z0-9-]+)[ \t]*-->/i;
+const BLOCKED_BY_LINE_RE =
+    /^-[ \t]*\[[ xX~-]\].*<!--[ \t]*blocked-by:[ \t]*([a-z0-9-]+)[ \t]*(?:\|[ \t]*asked:[ \t]*(yes|no)[ \t]*(?:[\u2014-][ \t]*([^>]*?))?[ \t]*)?-->/i;
+
+/**
+ * The owners whose blockers are the USER-DECISION class.
+ *
+ * Read off `Owner:` rather than guessed from prose: `terminal-states.md`
+ * defines `blocked` to include "a decision only the user can make", and the
+ * owner field is the only place a roadmap says which blockers those are.
+ * `council`, `implementer` and `agent` are deliberately outside the class —
+ * those are not decisions the user is waiting to be asked.
+ */
+const USER_DECISION_OWNER_RE = /^-[ \t]*\*\*Owner:\*\*[ \t]*(maintainer|user|owner)\b/im;
 
 const REQUIRED_FIELDS: ReadonlyArray<readonly [string, RegExp]> = [
     ['Status', /^-[ \t]*\*\*Status:\*\*/im],
@@ -154,6 +179,7 @@ function _scanBoth(rawText: string): ScanResult {
     const decidability: Violation[] = [];
     const text = _stripFencedCode(rawText);
     const declaredIds = new Set<string>();
+    const userDecisionIds = new Set<string>();
 
     const sectionMatch = BLOCKERS_SECTION_RE.exec(text);
     if (sectionMatch) {
@@ -181,6 +207,9 @@ function _scanBoth(rawText: string): ScanResult {
             declaredIds.add(cur.id);
             const bodyEnd = i + 1 < heads.length ? (heads[i + 1] as { start: number }).start : section.length;
             const body = section.slice(cur.end, bodyEnd);
+            if (USER_DECISION_OWNER_RE.test(body)) {
+                userDecisionIds.add(cur.id);
+            }
             const missing = REQUIRED_FIELDS.filter(([, re]) => !re.test(body)).map(([name]) => name);
             if (missing.length) {
                 violations.push({
@@ -256,6 +285,27 @@ function _scanBoth(rawText: string): ScanResult {
                     `(no matching '### blocker: ${id}' in this file)`,
             });
         }
+        if (userDecisionIds.has(id)) {
+            const asked = m[2] === undefined ? null : (m[2] as string).toLowerCase();
+            const reason = ((m[3] as string | undefined) ?? '').trim();
+            if (asked === null) {
+                violations.push({
+                    line: i + 1,
+                    message:
+                        `blocked-by '${id}' is a user-decision blocker and carries no ` +
+                        'asked: field — write `| asked: yes` when the question was put, ' +
+                        'or `| asked: no — <reason>` when it was not',
+                });
+            } else if (asked === 'no' && reason === '') {
+                violations.push({
+                    line: i + 1,
+                    message:
+                        `blocked-by '${id}' says asked: no with no reason — a marker that ` +
+                        'does not say why the question was never put is the parking lot ' +
+                        'this field exists to end',
+                });
+            }
+        }
     }
     violations.sort((a, b) => a.line - b.line);
     decidability.sort((a, b) => a.line - b.line);