@event4u/agent-config 9.32.0 → 9.34.0

package/src/scripts/lint_handoffs.ts

@@ -360,6 +360,91 @@ export function validate_handoff_artifact(text: string): string[] {
     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;
+}
+
 export function main(argv?: readonly string[]): number {
     let skills_dir = SKILLS_DIR;
     // Positional-only: flags are NOT paths. Before this filter the CI invocation
@@ -373,14 +458,19 @@ export function main(argv?: readonly string[]): number {
         // 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);
-        if (missing.length === 0) {
+        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`);
         }
-        process.stderr.write(`❌  ${missing.length} missing HANDOFF field(s)\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) {

package/src/scripts/lint_hedge_words.ts

@@ -0,0 +1,317 @@
+#!/usr/bin/env tsx
+/**
+ * Hedge-word lint — diff-scoped, ADVISORY, with a declared escalation trigger.
+ *
+ * `bench_honesty_score.ts` has measured hedging in agent OUTPUT since it was
+ * written (`HEDGE_WORDS`, `countHedgeWords`). Nothing has ever looked at the
+ * hedging in this package's own authored prose, which is where a hedge does the
+ * most damage: a rule that says a gate "should probably" fire is a rule nobody
+ * can be held to. This linter closes that half, reusing the same lexicon rather
+ * than restating a second list that would drift from it.
+ *
+ * ── Why diff-scoped, not corpus-wide ────────────────────────────────────────
+ * ADR-218:93 settled the question for prose-shape tooling outright: the wanted
+ * instrument is "one that watches diffs, not one that counts the corpus". A
+ * corpus count over 116 rules and 289 skills produces a number nobody can act
+ * on — every reading is dominated by prose written years apart under different
+ * conventions, and no single commit can move it.
+ *
+ * ── Why ADVISORY, and what would change that ────────────────────────────────
+ * `check_suppression_hygiene.ts` states the rule this gate is measured against:
+ * a gate whose corpus has findings on day one ships advisory; a gate whose
+ * corpus is already clean ships enforced, "because shipping it advisory would
+ * have been a hedge rather than a stage". This one has findings on day one and,
+ * unlike the `scripts/`-directory predicate, its false-positive class is NOT
+ * empty and cannot be made empty: hedging is legitimate — required, even — in
+ * this tree's own calibrated-honesty prose. "May", "typically" and "in doubt"
+ * appear in the very rules that teach an agent not to overclaim, and flagging
+ * them would be the gate arguing against the house style it exists to protect.
+ *
+ * So it ships advisory WITH A STAGE, not advisory forever. The escalation
+ * trigger is declared here, before any data, so that a later maintainer inherits
+ * a condition rather than a judgement call:
+ *
+ *   ADVISORY → ERROR when ALL THREE hold, and not before:
+ *     (a) at least 30 merged PRs have been measured by this gate;
+ *     (b) across a sample of at least 50 of the findings those PRs produced, a
+ *         human read classifies ≤ 10% as legitimate calibrated hedging — i.e.
+ *         the check is mostly right about the prose it flags;
+ *     (c) a maintainer records the measured rate and the resulting per-diff
+ *         threshold in `docs/CLAIMS.md`, so the number that starts failing
+ *         builds is itself bound to evidence.
+ *
+ *   If (b) fails — the FP rate stays above 10% — the honest outcome is that this
+ *   check STAYS advisory permanently, or is removed. It does not get a lowered
+ *   bar. That branch is pre-authorised here so that missing the threshold is a
+ *   publishable result rather than an awkward conversation.
+ *
+ * ── Carve-outs (modelled on lint_provenance_vocabulary's quote-the-ban) ─────
+ * A line that NAMES a hedge word rather than using one — the word inside
+ * backticks or double quotes — is exempt; without it, a rule teaching an agent
+ * which words to avoid would be flagged for listing them. Fenced code and
+ * indented blocks are skipped: a hedge in a code comment is a different surface
+ * with a different reviewer. The lexicon-bearing sources need no exemption list:
+ * they are `.ts`, and only `.md` is ever read.
+ *
+ * Scan surfaces: added (`+`) lines in `src/**\/*.md` and `docs/**\/*.md`.
+ *
+ * Exit codes: 0 always, in the advisory stage — including when findings exist.
+ * A non-zero exit is reserved for a usage error or a git failure, so that
+ * wiring this into a pipeline today cannot redden a build.
+ *
+ * Usage:
+ *     ./scripts-run src/scripts/lint_hedge_words
+ *     ./scripts-run src/scripts/lint_hedge_words --base origin/main
+ *     git diff origin/main | ./scripts-run src/scripts/lint_hedge_words --stdin
+ */
+import { spawnSync } from 'node:child_process';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { HEDGE_WORDS } from './bench_honesty_score.js';
+import { reportScanned } from './_lib/scan_scope.js';
+import { readStdinText } from './_lib/stdin.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+/** Prose surfaces this gate reads. Code and generated trees are out of scope. */
+const SCAN_ROOTS = ['src/', 'docs/'] as const;
+
+export interface HedgeFinding {
+    file: string;
+    /** The added line, trimmed — line numbers are not recoverable from a `+` line alone. */
+    line: string;
+    words: string[];
+}
+
+export interface HedgeReport {
+    findings: HedgeFinding[];
+    filesScanned: number;
+    addedProseLines: number;
+    addedWords: number;
+}
+
+function escapeRegExp(s: string): string {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+const HEDGE_RES: readonly { word: string; re: RegExp }[] = HEDGE_WORDS.map((w) => ({
+    word: w,
+    re: new RegExp(`\\b${escapeRegExp(w)}\\b`, 'g'),
+}));
+
+/**
+ * Spans where a hedge word is being NAMED, not used: backticked code spans and
+ * quoted strings. Mirrors `lint_provenance_vocabulary`'s carve-out for a line
+ * that quotes the ban it enforces.
+ *
+ * The straight single quote is deliberately NOT a delimiter here. Prose is full
+ * of apostrophes, and `'[^']*'` cannot tell `it's … that's` from a quoted span —
+ * it matches across the middle and blanks the text between two contractions,
+ * which silently drops hedges AND shrinks the word denominator the reported rate
+ * divides by. Backticks and double quotes carry the carve-out; a hedge word
+ * inside single quotes is rare enough to be worth a false positive.
+ */
+const QUOTED_SPAN = /`[^`]*`|"[^"]*"|“[^”]*”|«[^»]*»/g;
+
+function stripQuotedSpans(line: string): string {
+    return line.replace(QUOTED_SPAN, ' ');
+}
+
+/**
+ * True for a line whose surface is code rather than prose.
+ *
+ * The comment alternatives are anchored to two characters (`/*`, `*/`) rather
+ * than to a bare `*`. A lone leading asterisk is a markdown bullet far more often
+ * than a comment continuation, and in the only surface this gate reads — `.md`
+ * under `src/` and `docs/` — treating it as code skips most of the prose,
+ * including this suite's own `* `-bulleted sections.
+ */
+function isCodeSurface(line: string): boolean {
+    if (/^\s{4,}\S/.test(line)) return true; // indented block
+    if (/^\s*(?:```|~~~)/.test(line)) return true; // fence marker
+    if (/^\s*(?:\/\/|\/\*|\*\/|#!)/.test(line)) return true; // comment
+    if (/^\s*<!--/.test(line)) return true; // html comment / verify marker
+    return false;
+}
+
+function inScope(file: string): boolean {
+    if (!file.endsWith('.md')) return false;
+    return SCAN_ROOTS.some((r) => file.startsWith(r));
+}
+
+/**
+ * Scan a unified diff for hedge words in added prose.
+ *
+ * Pure over the diff string — no filesystem access — so the whole gate is
+ * testable from a fixture diff without a repo.
+ */
+export function scanDiff(diffText: string): HedgeReport {
+    const findings: HedgeFinding[] = [];
+    const files = new Set<string>();
+    let curFile: string | null = null;
+    // Fence state is tracked across ADDED lines only, because a unified diff is
+    // all this gate sees. A hunk that adds prose INSIDE an already-open fence
+    // therefore reads as prose. Known and accepted: reconstructing true fence
+    // state needs the whole file, which would make the gate file-scoped rather
+    // than diff-scoped — the axis ADR-218 already settled the other way.
+    let inFence = false;
+    let addedProseLines = 0;
+    let addedWords = 0;
+
+    for (const raw of diffText.split('\n')) {
+        if (raw.startsWith('+++ b/')) {
+            curFile = raw.slice(6);
+            inFence = false;
+            if (inScope(curFile)) files.add(curFile);
+            continue;
+        }
+        if (raw.startsWith('@@')) {
+            // A hunk boundary loses fence context; assume prose rather than
+            // silently swallowing a whole file because one fence opened above.
+            inFence = false;
+            continue;
+        }
+        if (!raw.startsWith('+') || raw.startsWith('+++')) continue;
+        if (curFile === null || !inScope(curFile)) continue;
+
+        const line = raw.slice(1);
+        if (/^\s*(?:```|~~~)/.test(line)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence || isCodeSurface(line)) continue;
+
+        const prose = stripQuotedSpans(line);
+        if (prose.trim() === '') continue;
+        addedProseLines += 1;
+        addedWords += prose.trim().split(/\s+/).length;
+
+        const lower = prose.toLowerCase();
+        const hits: string[] = [];
+        for (const { word, re } of HEDGE_RES) {
+            re.lastIndex = 0;
+            if (re.test(lower)) hits.push(word);
+        }
+        if (hits.length > 0) {
+            findings.push({ file: curFile, line: line.trim(), words: hits });
+        }
+    }
+
+    return { findings, filesScanned: files.size, addedProseLines, addedWords };
+}
+
+function baseRef(argv: string[]): string {
+    const i = argv.indexOf('--base');
+    if (i !== -1 && i + 1 < argv.length) return argv[i + 1]!;
+    return 'origin/main';
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    if (argv.includes('-h') || argv.includes('--help')) {
+        process.stdout.write(
+            'usage: lint_hedge_words [--base <ref>] [--stdin] [--quiet]\n' +
+                '  Advisory: reports hedge words in added prose. Always exits 0 on findings.\n',
+        );
+        return 0;
+    }
+    const quiet = argv.includes('--quiet');
+
+    let diffText: string;
+    if (argv.includes('--stdin')) {
+        diffText = readStdinText();
+    } else {
+        const base = baseRef(argv);
+        const proc = spawnSync('git', ['diff', base, '--', ...SCAN_ROOTS], {
+            cwd: REPO_ROOT,
+            encoding: 'utf-8',
+            maxBuffer: 64 * 1024 * 1024,
+        });
+        if (proc.error) {
+            process.stderr.write(`lint_hedge_words: git diff failed: ${proc.error.message}\n`);
+            return 2;
+        }
+        if (proc.status !== 0 && proc.status !== 1) {
+            // Base ref absent (shallow clone, detached CI checkout) — a missing
+            // base is not a finding, and inventing one would be worse.
+            process.stdout.write(
+                `lint_hedge_words: base ref '${base}' unavailable — advisory scan skipped.\n`,
+            );
+            return 0;
+        }
+        diffText = proc.stdout ?? '';
+    }
+
+    const report = scanDiff(diffText);
+
+    // Scope assertion + the machine-readable count, via the shared helper rather
+    // than a hand-written `scanned:` line: `check_gate_coverage`'s ratchet treats
+    // an emitted count with no assertion behind it as decoration, and it is right
+    // to — a diff-scoped gate is exactly the shape that can print `scanned: 0`
+    // out of a dead root forever. `EMPTY_VALID` is the honest prefix here: a diff
+    // that touches no prose under src/ or docs/ HAS zero hedged lines, and the
+    // reason survives the operational test — if the scan roots were deleted, "a
+    // diff with no prose in it" would still mean what it says.
+    const scanScope = {
+        gate: 'lint_hedge_words',
+        scanned: report.filesScanned,
+        units: 'changed prose file(s)',
+        roots: SCAN_ROOTS,
+        allowEmpty: 'EMPTY_VALID: a diff that changes no prose under src/ or docs/ has no hedged lines to report; the gate is diff-scoped by ADR-218 and its corpus is the diff, not a tree.',
+    } as const;
+
+    if (report.addedProseLines === 0) {
+        if (!quiet) {
+            process.stdout.write('lint_hedge_words: no added prose under src/ or docs/ — nothing to read.\n');
+            reportScanned(scanScope);
+        }
+        return 0;
+    }
+
+    // Lines, not occurrences. `bench_honesty_score` publishes `hedge_per_100_words`
+    // over hedge-word HITS; this counts hedged LINES, so it carries a different
+    // name. Two metrics sharing one name is how an escalation trigger ends up
+    // reading a number that was never the one it was calibrated against.
+    const hedgedLinesPer100 = (report.findings.length / report.addedWords) * 100;
+    if (report.findings.length > 0 && !quiet) {
+        process.stdout.write(
+            `lint_hedge_words (ADVISORY): ${report.findings.length} hedged line(s) ` +
+                `in ${report.filesScanned} file(s):\n`,
+        );
+        for (const f of report.findings) {
+            const clipped = f.line.length > 140 ? `${f.line.slice(0, 137)}…` : f.line;
+            process.stdout.write(`    ${f.file} · [${f.words.join(', ')}] ${clipped}\n`);
+        }
+        process.stdout.write(
+            '\n    Not every hit is a defect: calibrated hedging is house style in honesty\n' +
+                '    prose. Read each one; this gate never fails a build in its current stage.\n' +
+                '    Escalation trigger: see the header of src/scripts/lint_hedge_words.ts.\n',
+        );
+    } else if (!quiet) {
+        process.stdout.write('lint_hedge_words (ADVISORY): no hedged lines in added prose.\n');
+    }
+
+    if (!quiet) {
+        process.stdout.write(
+            `hedged_lines: ${report.findings.length} · added_prose_lines: ${report.addedProseLines} ` +
+                `· added_words: ${report.addedWords} · hedged_lines_per_100_words: ${hedgedLinesPer100.toFixed(2)}\n`,
+        );
+        reportScanned(scanScope);
+    }
+    return 0;
+}
+
+/* c8 ignore start */
+function isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    return pathToFileURL(path.resolve(process.argv[1])).href === pathToFileURL(_FILEPATH()).href;
+}
+function _FILEPATH(): string {
+    return _HERE;
+}
+if (isCliEntry()) {
+    process.exit(main());
+}
+/* c8 ignore stop */

package/src/scripts/lint_mcp_config_security.ts

@@ -239,7 +239,7 @@ export function main(argv: readonly string[] | null = null): number {
         process.stdout.write(payload + '\n');
         return findings.some((f) => f.is_fail) ? 1 : 0;
     }
-    return sl.report(findings, { check_label: 'mcp-config-security' });
+    return sl.report(findings, { check_label: 'mcp-config-security', scanned_roots: roots });
 }
 
 function _isCliEntry(): boolean {

package/src/scripts/lint_skill_frontmatter_safety.ts

@@ -47,6 +47,19 @@ const _RE_PERMISSION_MODE = /^\s*permissionMode:\s*['"]?bypassPermissions/;
 //   Python: re.match(r"\s*allowed-tools:\s*(.+)$", text)
 const _RE_ALLOWED_TOOLS = /^\s*allowed-tools:\s*(.+)$/;
 
+// Subagent definitions grant tools under a TOP-LEVEL `tools:` key (subagent-v1,
+// `src/scripts/schemas/subagent.schema.json`), not under `execution.allowed_tools`
+// and not as `allowed-tools`. Both other spellings were already read here; this
+// one was not, and `src/subagents` was not a scan root either — so the two
+// over-broad-grant checks below had never inspected a subagent definition.
+// Top-level anchored (no leading whitespace) so a nested `tools:` inside some
+// other block cannot be mistaken for a grant; the key is unused by skills,
+// commands and domain artefacts, so the anchor costs no coverage.
+const _RE_TOOLS_KEY = /^tools:\s*(.*)$/;
+// A YAML block-sequence item under it (`  - Bash`). Inline flow (`tools: [Bash]`)
+// is captured by the key regex's own trailing group.
+const _RE_SEQ_ITEM = /^\s+-\s*(.+)$/;
+
 /** Mirror Python `str.strip("'\"")` — strip any leading/trailing `'` or `"`. */
 function _stripQuotes(s: string): string {
     let lo = 0;
@@ -151,6 +164,44 @@ export function _scan(sf: sl.ScannedFile): sl.Finding[] {
         }
     }
 
+    // Top-level `tools:` — the subagent-v1 grant key. Collect the inline value
+    // plus any block-sequence items that follow, and run the same two checks the
+    // other two spellings get. A subagent is never an execution skill (no
+    // `execution:` block), so the bare-Bash arm applies by construction.
+    for (let i = 0; i < body.length; i += 1) {
+        const [lineno, text] = body[i] as [number, string];
+        const key = _RE_TOOLS_KEY.exec(text);
+        if (!key) {
+            continue;
+        }
+        const grants: string[] = [];
+        const inline = (key[1] ?? '').trim();
+        if (inline !== '') {
+            grants.push(inline);
+        }
+        for (let j = i + 1; j < body.length; j += 1) {
+            const [, next] = body[j] as [number, string];
+            const item = _RE_SEQ_ITEM.exec(next);
+            if (!item) {
+                break;
+            }
+            grants.push(_stripQuotes((item[1] as string).trim()));
+        }
+        const joined = grants.join(', ');
+        if (joined !== '' && (_WILDCARD_TOOL.test(joined) || _BARE_BASH.test(joined))) {
+            out.push(
+                new sl.Finding(
+                    sf.rel,
+                    lineno,
+                    CHECK,
+                    'HIGH',
+                    'wildcard / bare-Bash tool grant (over-broad)',
+                    sf.weight,
+                ),
+            );
+        }
+    }
+
     if (Object.keys(ex).length === 0) {
         return out;
     }
@@ -258,7 +309,10 @@ export function main(argv: readonly string[] | null = null): number {
     const args = parse_args(argv ?? process.argv.slice(2));
 
     const findings: sl.Finding[] = [];
-    const roots = ['src/skills', 'src/agent-src', 'src/domains'];
+    // `src/subagents` is the fourth root, added because its omission is what made
+    // the over-broad-grant checks blind: the only artefact in the tree granting a
+    // bare shell lives there, and the gate had never read it.
+    const roots = ['src/skills', 'src/agent-src', 'src/domains', 'src/subagents'];
     let scanned = 0;
     for (const sf of sl.iter_corpus(roots, ['.md'])) {
         scanned += 1;
@@ -293,7 +347,7 @@ export function main(argv: readonly string[] | null = null): number {
         process.stdout.write(payload + '\n');
         return findings.some((f) => f.is_fail) ? 1 : 0;
     }
-    return sl.report(findings, { check_label: 'dangerous-frontmatter' });
+    return sl.report(findings, { check_label: 'dangerous-frontmatter', scanned_roots: roots });
 }
 
 function _isCliEntry(): boolean {