@event4u/agent-config 9.33.0 → 9.35.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

@@ -347,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 {

package/src/scripts/memory_lookup.ts

@@ -529,8 +529,7 @@ function* _iter_knowledge_entries(): Generator<[string, Record<string, unknown>]
 /**
  * Naive relevance score: max over keys of (glob-match | substring).
  *
- * Good enough for the `absent` path where retrieval is best-effort.
- * The `present` path returns a real score from agent-memory.
+ * Retrieval is best-effort by design — this is the only scoring path.
  *
  * DOCUMENTED FALLBACK (road-to-reachable-code-memory Phase 6 / ADR-129):
  * this is the primary, always-available scorer. It has a known correctness

package/src/scripts/schemas/command.schema.json

@@ -257,6 +257,10 @@
       "type": "boolean",
       "description": "AI OS Product UI allowlist (road-to-ai-os-product-ui.md Phase 1). When true, the command is exposed in the browser /tasks surface and may be spawned by POST /api/v1/task/run. Default false — commands that touch git, secrets, or run destructive migrations must stay false (terminal only). Per-command opt-in, never opt-out."
     },
+    "requires_confirmation": {
+      "type": "boolean",
+      "description": "Optional, additive: the command's action STAGES rather than executes, so an irreversible step waits for an explicit human confirmation naming the exact object (non-destructive-by-default § Never act while asking). Twin of the same key in skill.schema.json's execution block; commands carry no execution block, so it sits top-level. A declaration only — it names the action class, never the object, which exists at stage time and not in frontmatter. Mechanism: stageAction/confirmOnce in work_engine/hooks/builtin/staged_confirmation.ts; enumerate with `agent-config gates --pending`. Nothing BINDS on it yet (blocker confirmation-degraded-host-semantics: 5 of 8 hosts have no pre_tool_use slot)."
+    },
     "auto_detect": {
       "type": "boolean",
       "description": "6.1.0 orchestrator auto-detection opt-in (Step 1, non-interactive-contract). When true, the orchestrator auto-detects its sub-command per the confidence-tiered detection table instead of always showing the menu, honoring the non-interactive-contract (TTY/CI detection, --yes/--json, abort schemas). Per-orchestrator kill-switch: set false to always show the menu; overridable globally via commands.auto_detect in .agent-settings.yml and per-invocation via --no-auto-detect. Only orchestrators (type: orchestrator) carry it."

package/src/scripts/schemas/skill.schema.json

@@ -222,6 +222,10 @@
           },
           "description": "U3 (ecosystem harvest): optional deny-list layered UNDER allowed_tools — defense-in-depth; a tool matching here is refused even if a broad allow pattern would admit it. Supports the scoped-grant syntax (e.g. Bash(git push:*))."
         },
+        "requires_confirmation": {
+          "type": "boolean",
+          "description": "Optional, additive: the skill's action STAGES rather than executes, so an irreversible step waits for an explicit human confirmation naming the exact object (non-destructive-by-default § Never act while asking). A declaration only — it names the action class, never the object, which exists at stage time and not in frontmatter. The mechanism is stageAction/confirmOnce in work_engine/hooks/builtin/staged_confirmation.ts; enumerate what is pending with `agent-config gates --pending`. Nothing BINDS on this flag yet: on 5 of 8 hosts there is no pre_tool_use slot, so a guard would degrade to prose while the flag reads like a control — that decision is deferred behind blocker confirmation-degraded-host-semantics."
+        },
         "command": {
           "type": "array",
           "minItems": 1,

package/src/scripts/self_repair_cli.ts

@@ -37,6 +37,7 @@ import {
     type EgressChoice,
     type EgressRoute,
     egressBlockedReason,
+    NEW_RECORDS_PER_SOURCE_PER_WINDOW,
     patchDeniedReason,
     type PushVia,
     renderReport,
@@ -48,6 +49,7 @@ import {
     listRecords,
     markReleased,
     openRecords,
+    readOverflow,
     readRecord,
 } from './_lib/self_repair_store.js';
 
@@ -400,11 +402,33 @@ export function executeRelease(
     return { published: null, attempts };
 }
 
+/**
+ * The creation cap's drop tally, printed whenever it is non-zero. This is the
+ * half that keeps the cap honest: a bounded store is only an improvement if
+ * "records were refused" is readable, otherwise the bound is indistinguishable
+ * from defects that never happened.
+ */
+function overflowLines(root: string): string {
+    const counts = readOverflow(root);
+    const rows = Object.entries(counts).filter(([, v]) => (v?.dropped ?? 0) > 0);
+    if (rows.length === 0) {
+        return '';
+    }
+    let out = '\n';
+    for (const [source, v] of rows) {
+        out +=
+            `  ! creation cap refused ${v?.dropped ?? 0} new ${source} record(s) ` +
+            `(cap ${NEW_RECORDS_PER_SOURCE_PER_WINDOW} per source per 24h, last ${v?.last_seen ?? '?'})\n`;
+    }
+    return out;
+}
+
 function statusCmd(root: string): number {
     const open = openRecords(root);
     const all = listRecords(root);
     if (all.length === 0) {
-        process.stdout.write('self-repair: no records.\n');
+        const overflow = overflowLines(root);
+        process.stdout.write(`self-repair: no records.\n${overflow}`);
         return EXIT_OK;
     }
     process.stdout.write(`self-repair: ${open.length} open of ${all.length} record(s)\n\n`);
@@ -415,6 +439,7 @@ function statusCmd(root: string): number {
                 `      ${r.evidence}\n`,
         );
     }
+    process.stdout.write(overflowLines(root));
     process.stdout.write('\nRelease one: agent-config self-repair:release <fingerprint>\n');
     return EXIT_OK;
 }