@event4u/agent-config 14.20.0 → 14.22.0

package/src/scripts/hooks/one_question_per_ask_hook.ts

@@ -0,0 +1,191 @@
+#!/usr/bin/env tsx
+/**
+ * PreToolUse guard: one question per structured-ask call.
+ *
+ * road-to-asked-not-parked 5.1. `ask-when-uncertain`'s Iron Law is one
+ * question per turn, and `user-interaction` § question pacing narrows what
+ * "one" means: one decision point, answerable with one reply. A host's native
+ * question picker makes it cheap to violate that — a payload can carry N
+ * questions in one call, and the user then answers a form instead of a
+ * question.
+ *
+ * DENY, NEVER TRUNCATE. Silently keeping the first question and dropping the
+ * rest would hide exactly the decisions the user was owed; the deny message
+ * names the count so the caller can split the ask instead of guessing what
+ * happened.
+ *
+ * WHAT IT SEES, honestly. `_lib/structured_ask.ts` carries no observed
+ * per-host tool, so this guard matches on a name SHAPE and is filtered by the
+ * manifest's per-concern `tools:` key to the same candidate names. On every
+ * host measured today it therefore fires on nothing — the concern exists so
+ * that the first host to ship a picker meets the rule already in force, not
+ * because a violation has been observed.
+ *
+ * ENFORCEMENT REACH, also honestly. `fail_closed: false` and the exit-1 deny
+ * are only a deny where the host both binds `pre_tool_use` AND honours the
+ * dispatcher's verdict. `hook-architecture-v1.md` § Which hosts carry
+ * pre_tool_use is the table; `agent-config hooks:status` answers it for the
+ * host actually running. This file claims no more than that.
+ *
+ * A payload whose shape is not recognised at all (`countStructuredAskQuestions`
+ * returns -1) is ALLOWED. A guard that blocks what it cannot parse would turn
+ * an unknown picker shape into a wedged session, and the failure it guards
+ * against — too many questions — is a shape defect, not a safety one.
+ *
+ * Exit codes (docs/contracts/hook-architecture-v1.md):
+ *   0 — allow
+ *   1 — block (the call carries more than one question)
+ */
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { countStructuredAskQuestions, isStructuredAskTool } from '../_lib/structured_ask.js';
+import { readHookStdin } from './hook_stdin.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+
+type JsonObject = Record<string, unknown>;
+
+function _isObject(v: unknown): v is JsonObject {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+export interface AskCall {
+    readonly tool: string;
+    readonly questions: number;
+}
+
+/** Read (tool name, question count) off a PreToolUse envelope. */
+export function extractAskCall(envelope: JsonObject): AskCall {
+    const payload = _isObject(envelope['payload']) ? envelope['payload'] : envelope;
+    const nameVal =
+        payload['tool_name'] ??
+        payload['toolName'] ??
+        payload['tool'] ??
+        envelope['tool_name'] ??
+        envelope['tool'];
+    const tool = typeof nameVal === 'string' ? nameVal : '';
+    const ti = _isObject(payload['tool_input'])
+        ? payload['tool_input']
+        : _isObject(envelope['tool_input'])
+          ? envelope['tool_input']
+          : null;
+    return { tool, questions: ti === null ? -1 : countStructuredAskQuestions(ti) };
+}
+
+/** The verdict, separated from I/O so the fixtures exercise the decision itself. */
+export function verdict(call: AskCall): { block: boolean; reason: string } {
+    if (call.tool === '' || !isStructuredAskTool(call.tool)) {
+        return { block: false, reason: 'not a structured-ask call' };
+    }
+    if (call.questions < 0) {
+        return { block: false, reason: 'payload shape not recognised — allowed, never guessed' };
+    }
+    if (call.questions <= 1) {
+        return { block: false, reason: 'one question' };
+    }
+    return {
+        block: true,
+        reason:
+            `${call.tool} carries ${String(call.questions)} questions in one call. ` +
+            'One decision per ask: put the first question, wait for the answer, then ' +
+            'the next. The call is denied rather than truncated — dropping the extra ' +
+            'questions would hide the decisions the user is owed.',
+    };
+}
+
+export function main(argv?: string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    for (const a of args) {
+        if (a === '--self-test') {
+            return selfTest();
+        }
+    }
+    const raw = readHookStdin();
+    if (!raw.trim()) {
+        return 0;
+    }
+    let envelope: JsonObject;
+    try {
+        const parsed: unknown = JSON.parse(raw);
+        envelope = _isObject(parsed) ? parsed : {};
+    } catch {
+        return 0;
+    }
+    const v = verdict(extractAskCall(envelope));
+    if (v.block) {
+        process.stderr.write(`one-question-per-ask: BLOCKED — ${v.reason}\n`);
+        return 1;
+    }
+    return 0;
+}
+
+export function selfTest(): number {
+    const cases: Array<[string, JsonObject, boolean]> = [
+        [
+            'two questions in one call is denied',
+            { tool_name: 'AskUserQuestion', tool_input: { questions: [{}, {}] } },
+            true,
+        ],
+        [
+            'four questions is denied',
+            { tool_name: 'AskUserQuestion', tool_input: { questions: [{}, {}, {}, {}] } },
+            true,
+        ],
+        [
+            'one question passes',
+            { tool_name: 'AskUserQuestion', tool_input: { questions: [{}] } },
+            false,
+        ],
+        [
+            'a single-question field passes',
+            { tool_name: 'ask_user_question', tool_input: { question: 'which one?' } },
+            false,
+        ],
+        [
+            'an empty ask passes — malformed, but not this guard\'s failure',
+            { tool_name: 'AskUserQuestion', tool_input: { questions: [] } },
+            false,
+        ],
+        [
+            'an unrecognised payload shape passes rather than wedging the session',
+            { tool_name: 'AskUserQuestion', tool_input: { something: 'else' } },
+            false,
+        ],
+        ['an ordinary tool is never seen', { tool_name: 'Bash', tool_input: { command: 'ls' } }, false],
+        [
+            'a Write with two questions in its body is not an ask call',
+            { tool_name: 'Write', tool_input: { questions: [{}, {}] } },
+            false,
+        ],
+        ['an empty envelope passes', {}, false],
+    ];
+    let failed = 0;
+    for (const [name, envelope, want] of cases) {
+        const got = verdict(extractAskCall(envelope)).block;
+        const ok = got === want;
+        process.stdout.write(
+            `${ok ? '✅' : '❌'}  ${name} — block=${String(got)}` +
+                (ok ? '\n' : ` (wanted ${String(want)})\n`),
+        );
+        if (!ok) failed += 1;
+    }
+    const positives = cases.filter((c) => c[2]).length;
+    if (positives < 2) {
+        process.stderr.write(
+            '❌  one_question_per_ask --self-test: fewer than 2 deny cases — a guard never ' +
+                'seen refuse has unknown sensitivity.\n',
+        );
+        return 1;
+    }
+    process.stdout.write(
+        `\none_question_per_ask --self-test: ${String(cases.length - failed)}/${String(cases.length)} ` +
+            `case(s) behaved (${String(positives)} deny, ${String(cases.length - positives)} allow)\n`,
+    );
+    return failed > 0 ? 1 : 0;
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    process.exit(main());
+}
+
+export { _HERE };

package/src/scripts/hooks/orchestration_record_hook.ts

@@ -16,7 +16,7 @@
  * Fires only on an `Agent` / `Task` tool-use completion (the two names this
  * repo has observed for the subagent-dispatch tool across hosts/versions).
  * Every other tool call is a silent no-op — same tool-filter discipline as
- * `code-graph-nudge` (`tools: [Agent, Task]` in the manifest entry keeps the
+ * `code-graph-context` (`tools: [Agent, Task]` in the manifest entry keeps the
  * dispatcher from paying this concern's cost on unrelated calls).
  *
  * Sync vs async (road-to-orchestrator-first-execution measured: 326 of 370
@@ -89,7 +89,7 @@ export const DISPATCH_TOOL_NAMES: ReadonlySet<string> = new Set(['Agent', 'Task'
  * Unwrap the dispatcher envelope (`{schema_version, platform, event,
  * payload}`) down to the platform-native payload. Falls back to the
  * top-level object for direct/legacy invocation (same shape both
- * `pr_url_reminder_hook.ts` and `code_graph_nudge_hook.ts` handle).
+ * `pr_url_reminder_hook.ts` and `code_graph_context_hook.ts` handle).
  */
 export function unwrapPayload(envelope: JsonObject): JsonObject {
     const inner = envelope['payload'];

package/src/scripts/hooks/rule_inject_hook.ts

@@ -34,7 +34,7 @@
  * NEVER BLOCKS. Every failure path returns 0: unreadable stdin, malformed JSON,
  * missing router, unreadable body, unwritable state. The one non-zero exit is
  * the host's advisory context channel (exit 2 + `decision: "warn"`), the same
- * channel `ui-route-nudge` and `code-graph-nudge` already use on `pre_tool_use`
+ * channel `ui-route-nudge` and `code-graph-context` already use on `pre_tool_use`
  * with `severity: advisory` — a warn there is an injection, not a deny.
  *
  * HOST BOUNDARY, STATED RATHER THAN IMPLIED. `user_prompt_submit` and

package/src/scripts/hooks/skill_route_hook.ts

@@ -140,7 +140,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { readHookStdin } from "./hook_stdin.js";
 import { isSyntheticPrompt } from "../_lib/prompt_shape.js";
-import { OBSERVATION_LOG, readObservationLog, resolveSkillsRoot } from "../_lib/skill_catalogue.js";
+import { OBSERVATION_LOG, readObservationLog, resolveSkillCatalogueRoots } from "../_lib/skill_catalogue.js";
 import { knownBareNames } from "../_lib/skill_catalogue_series.js";
 import { _tokenize, rank, type RankRow } from "../skill_tools/score_skill_relevance.js";
 
@@ -252,13 +252,20 @@ export interface RouteDecision {
  */
 export function routeDecision(
   prompt: string,
-  skillsDir: string | null,
+  // One root, or every readable root. `null` and `[]` are the same answer — no
+  // catalogue was read — and both must stay silent rather than rank nothing and
+  // call that a result.
+  skillsDir: string | readonly string[] | null,
   bareProvider?: () => Set<string> | null,
 ): RouteDecision {
   const silent: RouteDecision = { rows: [], suppressed: 0 };
   if (skillsDir === null) return silent;
+  if (Array.isArray(skillsDir) && skillsDir.length === 0) return silent;
   // Denominator floor BEFORE the catalogue read: a prompt too short to score
-  // meaningfully cannot produce a pointer worth 337 file reads either.
+  // meaningfully cannot produce a pointer worth the read either. The count is
+  // deliberately not stated — it used to say "337 file reads", which was one
+  // root; the union reads every readable root and the figure depends on the
+  // machine's install.
   try {
     if (_tokenize(prompt).size < MIN_TASK_TERMS) return silent;
   } catch {
@@ -346,7 +353,7 @@ export function main(): number {
   const root = _workspaceRoot(env);
   const platform = env["platform"];
   const host = typeof platform === "string" && platform ? platform : null;
-  const { rows, suppressed } = routeDecision(prompt, resolveSkillsRoot(root), () =>
+  const { rows, suppressed } = routeDecision(prompt, resolveSkillCatalogueRoots(root), () =>
     knownBareForHost(root, host),
   );
   if (rows.length === 0) return EXIT_ALLOW; // silence is the default

package/src/scripts/inbox_source_census.ts

@@ -0,0 +1,322 @@
+#!/usr/bin/env tsx
+/**
+ * inbox_source_census — the denominator an inbox run cannot shrink by reading badly.
+ *
+ * THE GAP THIS CLOSES.
+ *
+ * `/analyze:inbox` already ends with a **point ledger**: points extracted in its
+ * Phase 3 against points dispositioned in Phases 4–5b, per bucket, as counts
+ * that must balance. That ledger proves the run answered what it read. It
+ * cannot prove the run read what arrived — a point nobody extracted appears in
+ * neither column, and the ledger balances perfectly without it. Under-extraction
+ * is invisible to the only completeness check the command has.
+ *
+ * Measured shape of the input that exposed it: round `inbox-2026-09-r` arrived
+ * as 12 topic folders, 67 files and ~55,800 lines, where one folder alone held
+ * six revisions of a plan beside a 58 KB transcript. Read per file, the
+ * revisions look like six sources; read as a set, they are one argument whose
+ * later revisions silently drop items the earlier ones carried.
+ *
+ * WHAT THIS COUNTS — AND WHAT IT DELIBERATELY DOES NOT.
+ *
+ * Only what is **mechanical and genre-independent**:
+ *
+ *   1. **Source sets** — files grouped by stem, so a revision family
+ *      (`x.v1/x.v2`, `x.consolidated.v1`, `x-loop-1`, `x-2026-09-06`) reports as
+ *      ONE set with its members ordered, instead of as N unrelated files.
+ *   2. **Anchors** — the four countable structures a source can carry: turn
+ *      separators, headings, checkbox steps, and numbered items. Every class is
+ *      counted on every file; the run picks the ones its genre uses.
+ *   3. **Decision ids** — the `D2` / `E1` / `K7` tokens a source argues in. If
+ *      those do not appear in what the run emits, the emitted plan is
+ *      undecidable by construction and no reader can tell, because the ids left
+ *      with the source.
+ *
+ * It does NOT guess genre, judge relevance, or extract demands. Those are the
+ * reading, and the whole point of a denominator is that it is produced without
+ * one — a census that needed judgement would be as shrinkable as the reading it
+ * is supposed to bound.
+ *
+ * HONEST LIMIT.
+ *
+ * An anchor count is a floor on what must be accounted for, never a target and
+ * never a quality measure. A 400-anchor source can carry three demands and a
+ * 12-anchor transcript can carry twelve. What the number buys is that a run
+ * reporting "41 anchors → 41 accounted" can be challenged by anyone holding the
+ * folder, where a prose summary cannot.
+ *
+ * USAGE.
+ *
+ *   ./scripts-run src/scripts/inbox_source_census --root agents/tmp/<round-id>
+ *   ./scripts-run src/scripts/inbox_source_census --root <dir> --json
+ *
+ * Exit 2 when the root is missing, unreadable, or enumerates zero files — a
+ * census over an empty set is vacuous and must not read as coverage.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+/** Extensions worth counting. Binaries and archives carry no anchors. */
+const TEXT_EXT = new Set(['.md', '.txt', '.markdown', '.mdx']);
+
+/**
+ * Version markers that make two files revisions of one source rather than two
+ * sources. Ordered most-specific first: `consolidated.v2` must not be stripped
+ * to `consolidated` by the bare `.vN` rule.
+ */
+const VERSION_MARKERS: readonly RegExp[] = [
+    /[.-]consolidated[.-]v\d+$/i,
+    /[.-]consolidated$/i,
+    /[.-]loop[.-]?\d+.*$/i,
+    /[.-]v\d+$/i,
+    /[.-]\d{4}-\d{2}-\d{2}$/,
+    /[.-](final|draft|deep|master)$/i,
+];
+
+export interface AnchorCounts {
+    /** `----`-style turn separators — the transcript spine. */
+    separators: number;
+    /** ATX headings, h1 through h4. */
+    headings: number;
+    /** `- [ ]` / `- [x]` / `- [~]` / `- [-]` roadmap steps. */
+    steps: number;
+    /** `1.`-style numbered items and `**bold lead-in**` paragraph openers. */
+    enumerated: number;
+}
+
+export interface FileCensus {
+    file: string;
+    bytes: number;
+    lines: number;
+    anchors: AnchorCounts;
+    /** Sum of the four anchor classes — the file's floor. */
+    total: number;
+}
+
+export interface SourceSet {
+    /** The shared stem the members were grouped under. */
+    stem: string;
+    /** Members, oldest-looking first (lexical on the version marker). */
+    members: FileCensus[];
+    /** True when more than one member shares the stem. */
+    isRevisionSet: boolean;
+}
+
+export interface TopicCensus {
+    topic: string;
+    sets: SourceSet[];
+    decisionIds: string[];
+    fileCount: number;
+    anchorTotal: number;
+}
+
+/**
+ * Strip a trailing version marker to the stem two revisions share.
+ *
+ * Applied repeatedly, most-specific first, so `road-to-x.consolidated.v3`
+ * reduces through `road-to-x.consolidated` to `road-to-x` — otherwise a
+ * `.consolidated` family and a plain `.vN` family of the same plan report as
+ * two sets and the diff obligation never fires on the pair.
+ */
+export function stemOf(filename: string): string {
+    let s = filename.replace(/\.(md|markdown|mdx|txt)$/i, '');
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const re of VERSION_MARKERS) {
+            const next = s.replace(re, '');
+            if (next !== s && next.length > 0) {
+                s = next;
+                changed = true;
+                break;
+            }
+        }
+    }
+    return s;
+}
+
+/** Count the four anchor classes. Fenced code is skipped — a fence is content. */
+export function countAnchors(text: string): AnchorCounts {
+    const out: AnchorCounts = { separators: 0, headings: 0, steps: 0, enumerated: 0 };
+    let inFence = false;
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trimEnd();
+        if (/^\s*(```|~~~)/.test(line)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence) continue;
+        if (/^-{4,}$|^={4,}$|^\*{4,}$/.test(line.trim())) {
+            out.separators += 1;
+            continue;
+        }
+        if (/^#{1,4} \S/.test(line)) {
+            out.headings += 1;
+            continue;
+        }
+        if (/^\s*[-*] \[[ xX~-]\]/.test(line)) {
+            out.steps += 1;
+            continue;
+        }
+        if (/^\s*\d+[.)] \S/.test(line) || /^\*\*[^*]+\*\*/.test(line)) {
+            out.enumerated += 1;
+        }
+    }
+    return out;
+}
+
+/**
+ * Decision / open-question ids the source argues in — `D2`, `E1`, `K7`, `AC3`.
+ *
+ * Deliberately narrow: one to three capitals followed by one or two digits, as
+ * a whole token. A wider pattern matches version strings, HTTP codes and every
+ * `P0` in ordinary prose, and a noisy id set is worse than none — the run would
+ * stop reading the row.
+ */
+export function decisionIds(text: string): string[] {
+    const hits = text.match(/\b[A-Z]{1,3}\d{1,2}\b/g) ?? [];
+    return [...new Set(hits)].sort();
+}
+
+function censusFile(abs: string, rel: string): FileCensus {
+    const text = fs.readFileSync(abs, 'utf-8');
+    const anchors = countAnchors(text);
+    return {
+        file: rel,
+        bytes: Buffer.byteLength(text),
+        lines: text.split(/\r?\n/).length,
+        anchors,
+        total: anchors.separators + anchors.headings + anchors.steps + anchors.enumerated,
+    };
+}
+
+/** Group one topic folder's files into source sets and count its anchors. */
+export function censusTopic(dir: string, topic: string): TopicCensus {
+    const names = fs
+        .readdirSync(dir, { withFileTypes: true })
+        .filter((d) => d.isFile() && TEXT_EXT.has(path.extname(d.name).toLowerCase()))
+        .map((d) => d.name)
+        .sort();
+
+    const byStem = new Map<string, FileCensus[]>();
+    const ids = new Set<string>();
+    for (const name of names) {
+        const abs = path.join(dir, name);
+        const fc = censusFile(abs, name);
+        for (const id of decisionIds(fs.readFileSync(abs, 'utf-8'))) ids.add(id);
+        const stem = stemOf(name);
+        const bucket = byStem.get(stem);
+        if (bucket) bucket.push(fc);
+        else byStem.set(stem, [fc]);
+    }
+
+    const sets: SourceSet[] = [...byStem.entries()]
+        .map(([stem, members]) => ({
+            stem,
+            members: members.sort((a, b) => a.file.localeCompare(b.file)),
+            isRevisionSet: members.length > 1,
+        }))
+        .sort((a, b) => a.stem.localeCompare(b.stem));
+
+    return {
+        topic,
+        sets,
+        decisionIds: [...ids].sort(),
+        fileCount: names.length,
+        anchorTotal: sets.reduce(
+            (n, s) => n + s.members.reduce((m, f) => m + f.total, 0),
+            0,
+        ),
+    };
+}
+
+/** Walk a round root: each immediate subdirectory is a topic, plus the root itself. */
+export function censusRoot(root: string): TopicCensus[] {
+    const out: TopicCensus[] = [];
+    const rootLevel = censusTopic(root, '.');
+    if (rootLevel.fileCount > 0) out.push(rootLevel);
+    for (const d of fs.readdirSync(root, { withFileTypes: true })) {
+        if (!d.isDirectory()) continue;
+        const t = censusTopic(path.join(root, d.name), d.name);
+        if (t.fileCount > 0) out.push(t);
+    }
+    return out;
+}
+
+function render(topics: TopicCensus[], write: (s: string) => unknown): void {
+    let files = 0;
+    let anchors = 0;
+    let revisionSets = 0;
+    for (const t of topics) {
+        write(`\n## ${t.topic}\n`);
+        for (const s of t.sets) {
+            const tag = s.isRevisionSet ? ` — REVISION SET (${String(s.members.length)}), diff consecutive members` : '';
+            write(`  ${s.stem}${tag}\n`);
+            for (const f of s.members) {
+                const a = f.anchors;
+                write(
+                    `    ${f.file}  ${String(f.bytes)}B/${String(f.lines)}L  ` +
+                        `sep ${String(a.separators)} · head ${String(a.headings)} · ` +
+                        `step ${String(a.steps)} · enum ${String(a.enumerated)}  = ${String(f.total)}\n`,
+                );
+            }
+            if (s.isRevisionSet) revisionSets += 1;
+        }
+        if (t.decisionIds.length > 0) write(`  decision ids: ${t.decisionIds.join(' ')}\n`);
+        files += t.fileCount;
+        anchors += t.anchorTotal;
+    }
+    write(
+        `\ntopics ${String(topics.length)} · files ${String(files)} · ` +
+            `revision sets ${String(revisionSets)} · anchors ${String(anchors)}\n` +
+            'Every anchor leaves the run carrying a ledger row or named in one `no-demand` line.\n' +
+            'Every revision set owes a consecutive-member diff (/analyze:inbox Phase 2b).\n',
+    );
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const rootIdx = argv.indexOf('--root');
+    const rootArg = rootIdx === -1 ? undefined : argv[rootIdx + 1];
+    if (rootArg === undefined) {
+        process.stderr.write('usage: inbox_source_census --root <dir> [--json]\n');
+        return 2;
+    }
+    const root = path.resolve(REPO_ROOT, rootArg);
+    let stat: fs.Stats;
+    try {
+        stat = fs.statSync(root);
+    } catch {
+        process.stderr.write(`❌  inbox_source_census: root not readable: ${root}\n`);
+        return 2;
+    }
+    if (!stat.isDirectory()) {
+        process.stderr.write(`❌  inbox_source_census: root is not a directory: ${root}\n`);
+        return 2;
+    }
+
+    const topics = censusRoot(root);
+    const files = topics.reduce((n, t) => n + t.fileCount, 0);
+    if (files === 0) {
+        process.stderr.write(
+            `❌  inbox_source_census: 0 text file(s) under ${root} — a census over an ` +
+                'empty set is vacuous and must not read as coverage.\n',
+        );
+        return 2;
+    }
+
+    if (argv.includes('--json')) {
+        process.stdout.write(`${JSON.stringify({ root, topics }, null, 2)}\n`);
+        return 0;
+    }
+    render(topics, (s) => process.stdout.write(s));
+    return 0;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    process.exit(main());
+}