@event4u/agent-config 9.16.0 → 9.17.0

package/src/config/agent-settings.template.yml

@@ -321,6 +321,28 @@ personal:
   # See user-types/README.md for the per-id contract.
   user_type: "__USER_TYPE__"
 
+# --- Reply verbosity ---
+verbosity:
+  # Announce intent before tool batches ("Let me check X…") — only honored
+  # when personal.play_by_play is ALSO true (the direct-answers narration
+  # carve-out requires both). Default false = no intent narration.
+  intent_announcements: false
+
+  # Show generated commit messages, PR titles/bodies, branch names before
+  # acting. false = use generated content directly (/commit terse path).
+  preview_artifacts: false
+
+  # Confirmation prompts for routine workflow steps with one obvious answer.
+  # Iron-Law gates (commit-policy, scope-control git-ops, Hard Floor) ALWAYS
+  # ask regardless of this setting.
+  routine_confirmations: false
+
+  # Offer "run AI Council on this?" inside delivery commands.
+  offer_council_in_delivery: false
+
+  # Status blocks after a successful action: off | minimal | full.
+  post_action_reports: minimal
+
 # --- Project / team preferences ---
 project:
   # Path to the PR template file (relative to project root)

package/src/config/evaluator-budgets.json

@@ -8,7 +8,9 @@
         "on_release": "fail",
         "on_main_and_prs": "warn",
         "on_local": "fail",
-        "always_blocking": ["a metric with no measurement supplied"],
+        "always_blocking": [
+            "a metric with no measurement supplied"
+        ],
         "rationale": "road-to-gates-that-can-fail Phase 5. A hard fail on main turns every legitimate command addition into a blocked merge, which is how budgets get quietly raised with a cushion instead of consciously — so budget / regression / drift findings are ADVISORY on main, the nightly and ordinary PRs, and BLOCKING on a release ref. Not a weakening: before the Phase-4 path triggers, this gate ran on release PRs and the nightly only, so the surfaces that now warn never saw it at all. A LOCAL run (no CI env) is strict, because a maintainer running it by hand — including release.ts — wants the strict answer and blocks nobody. A metric with NO measurement is always blocking in either posture: that is a broken harness reporting green on nothing. Implemented in src/scripts/check_evaluator_budgets.ts::detectPosture; override with --posture warn|fail.",
         "delivery": "This posture IS the nightly-visibility route (council 2026-08-02, blocker nightly-visibility-owner), not a second mechanism beside it: the nightly publishes measurement_record below, a later run re-measures and compares, and the contradiction warns on main / fails on release. No notification channel, no auto-managed issue — a one-maintainer channel producing routine noise gets muted, and a muted channel reproduces the original failure."
     },
@@ -25,13 +27,8 @@
         },
         "not_re_measured": "unpacked_size_mb, node_modules_mb, runtime_dep_count, cli_version_cold_ms, mcp_boot_to_initialize_ms. All five require the packed-tarball harness (npm pack of a fully built tree, then a clean `npm install --omit=dev <tarball>` into a scratch project) that evaluator_umbrella.sh runs in CI. They were NOT re-measured in this pass and their values remain the 2026-07-27 acceptance numbers — stated rather than invented. The next nightly writes the real numbers into measurement_record, and the drift check then reports any contradiction with last_measured on the PR that carries it."
     },
+    "removed_2026_08_04": "unpacked_size_mb (max 28) — removed by maintainer decision at the 9.17.0 release: the gate turned every legitimate payload addition into a blocked release (measured 28.22 vs max 28 with all functional gates green), and the maintainer judged tarball size not worth gating. evaluator_umbrella.sh still MEASURES and records unpacked_size_mb as evidence; only the budget enforcement is gone. ADR-204 review_trigger (a) fired and was resolved this way.",
     "budgets": {
-        "unpacked_size_mb": {
-            "max": 28,
-            "last_measured": 26.05,
-            "last_measured_at": "2026-07-27",
-            "method": "npm pack --json → dist.unpackedSize / 1e6 — includes the Phase-1 precompiled bundles (dist/hooks/dispatch.js + dist/mcp/server.mjs, ~2.1 MB) that bought the 23x hook-latency win and the tsx removal, plus dist/cli-delegate/ (~1.40 MB, ADR-204) which finished that removal for the consumer command surface. This gate is the ONLY size trip-wire on those bundles by design: a dedicated per-bundle budget key would need its own measurement wired into evaluator_umbrella.sh, and an unwired key fails check_evaluator_budgets with 'no measurement supplied' instead of guarding anything. ADR-204 projected 27.45 against max 28 without packing — the next real measurement here is the confirming one, and headroom is thin"
-        },
         "node_modules_mb": {
             "max": 140,
             "last_measured": 127,
@@ -61,11 +58,11 @@
             "deterministic": false
         },
         "cli_help_command_count": {
-            "max": 81,
-            "last_measured": 81,
-            "last_measured_at": "2026-08-03",
+            "max": 82,
+            "last_measured": 82,
+            "last_measured_at": "2026-08-04",
             "method": "registry enumeration — count of `{ name: '...', disposition` entries in src/cli/registry.ts (NOT --help prose parsing; methods historically disagreed 74 vs 76 vs 79)",
-            "baseline_note": "80 → 81 on 2026-08-03 (release 9.15.0 gate). This RECORDS growth that already shipped through its own reviewed PR; it does not authorize new surface. The +1 is f02db54c2 (fix(cli): register routing:doctor in the CLI registry) — the command existed, only its registry entry was missing, and the registering PR did not move this budget. The gate did its job again: breach WARNS on main and BLOCKS on release, which is the conscious-decision point rather than a silently raised cap. Re-measured 2026-08-03 via the pinned method: 81. Headroom stays zero by design — the next registry addition must move this number in its own PR."
+            "baseline_note": "80 → 81 on 2026-08-03 (release 9.15.0 gate). This RECORDS growth that already shipped through its own reviewed PR; it does not authorize new surface. The +1 is f02db54c2 (fix(cli): register routing:doctor in the CLI registry) — the command existed, only its registry entry was missing, and the registering PR did not move this budget. The gate did its job again: breach WARNS on main and BLOCKS on release, which is the conscious-decision point rather than a silently raised cap. Re-measured 2026-08-03 via the pinned method: 81. Headroom stays zero by design — the next registry addition must move this number in its own PR. 81 → 82 on 2026-08-04: the `handoff` subcommand (road-to-agent-handoff-resume Phase 4) registers in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 82."
         },
         "mcp_public_tool_count": {
             "max": 19,

package/src/config/gate-coverage.yml

@@ -260,6 +260,36 @@ gates:
       failure direction was false-positive rather than false-green, but the
       cause was the same dead root.
 
+  - id: lint_abstraction_thresholds
+    argv: []
+    min_scanned: 400
+    corpus: "src/rules + src/skills + src/agent-src/commands + docs/guidelines .md (533 at baseline)"
+    status: enforced
+    note: >
+      A collapse below the floor would mean the gate stopped reading the tree
+      that states extraction thresholds, so a bare or diverging threshold
+      (ADR-213 drift) could land while the gate still printed green.
+
+  - id: lint_profile_personas
+    argv: []
+    min_scanned: 5
+    corpus: "src/agent-src/profiles/*.yml (6 seed profiles at baseline)"
+    status: enforced
+    note: >
+      Fewer than 5 profiles scanned would mean the gate stopped reading the
+      seed-profile dir, so a defaults.personas id that resolves to no persona
+      file could land while the gate still printed green.
+
+  - id: lint_token_budget_discipline
+    argv: []
+    min_scanned: 200
+    corpus: "src/skills/*/SKILL.md (288 at baseline)"
+    status: enforced
+    note: >
+      A collapse below the floor would mean the gate stopped reading the skills
+      tree, so a rich-tagged skill without its justification section (or a cap
+      breach) could land while the gate still printed green.
+
   - id: lint_framework_leakage
     argv: []
     min_scanned: 350

package/src/scripts/_cli/cmd_handoff.ts

@@ -0,0 +1,405 @@
+#!/usr/bin/env node
+/**
+ * `agent-config handoff` — pick a recent session, generate a handoff,
+ * seed a fresh session (road-to-agent-handoff-resume Phase 4).
+ *
+ * Default TTY flow: numbered picker over the unified session list
+ * (chat-history primary; Claude-transcript + Codex-session adapters),
+ * then the Phase-2 deterministic generator writes
+ * `agents/runtime/state/handoff-context.md`, which the Phase-3
+ * session_start hook injects into the NEXT session exactly once.
+ *
+ * Flags:
+ *   --list             print the sessions and exit
+ *   --json             with --list: machine-readable output
+ *   --session <id>     skip the picker (exact id or unique prefix)
+ *   --print            emit the handoff to stdout instead of the state
+ *                      file (legacy copy-paste mode)
+ *   --launch <host>    spawn a fresh interactive host session after
+ *                      generating (claude: hook-seeded; codex: handoff as
+ *                      initial prompt — no hook surface there)
+ *   --llm              narrative-polish seam; v1: clear not-implemented error
+ *   --root <path>      repo root override (default: cwd)
+ *
+ * Exit codes: 0 ok · 1 no sessions / session not found · 2 invocation error
+ */
+
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import process from 'node:process';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import {
+    build_handoff,
+    handoff_target_path,
+    LlmPolishNotImplementedError,
+    write_handoff,
+} from './handoff_generate.js';
+import { list_handoff_sessions } from './handoff_sessions.js';
+import type { HandoffSession } from './handoff_sessions.js';
+
+const PROG = 'agent-config handoff';
+const USAGE = `usage: ${PROG} [--list] [--json] [--session <id>] [--print] [--launch <host>] [--llm] [--root <path>]`;
+
+const _HELP = `${USAGE}
+
+Pick a recent session, generate a deterministic handoff, and seed a fresh
+session with it. Without flags (in a TTY): numbered picker, then the handoff
+lands in agents/runtime/state/handoff-context.md and auto-injects into the
+next session on hook-capable hosts.
+
+options:
+  --list             print the recent sessions and exit
+  --json             with --list: JSON output
+  --session <id>     generate for this session id (exact or unique prefix)
+  --print            print the handoff to stdout (no state file)
+  --launch <host>    start a fresh interactive session (claude | codex)
+  --llm              optional LLM polish — not implemented in v1
+  --root <path>      repo root (default: current directory)
+  -h, --help         show this help
+
+exit codes:
+  0  handoff generated (or list printed)
+  1  no sessions found / session id not found
+  2  invocation error (bad flag, non-TTY without --session, unsupported host)
+`;
+
+class ArgparseExit extends Error {
+    constructor(public readonly code: number) {
+        super(`exit ${code}`);
+    }
+}
+
+// ---------------------------------------------------------------------
+// launch adapter table (v1: claude + codex live, gemini stubbed)
+// ---------------------------------------------------------------------
+
+export interface LaunchAdapter {
+    supports_launch: boolean;
+    /** 'hook' = state file + session_start injection; 'initial-prompt' = argv. */
+    seeding: 'hook' | 'initial-prompt';
+    build_argv: (handoffText: string) => string[];
+}
+
+export const LAUNCH_ADAPTERS: Record<string, LaunchAdapter> = {
+    claude: {
+        supports_launch: true,
+        seeding: 'hook',
+        build_argv: () => ['claude'],
+    },
+    codex: {
+        // Codex is a bundle host without hooks — seed via the initial prompt.
+        supports_launch: true,
+        seeding: 'initial-prompt',
+        build_argv: (handoffText: string) => ['codex', handoffText],
+    },
+    gemini: {
+        supports_launch: false,
+        seeding: 'hook',
+        build_argv: () => ['gemini'],
+    },
+};
+
+// ---------------------------------------------------------------------
+// options + seams
+// ---------------------------------------------------------------------
+
+export interface Opts {
+    list: boolean;
+    json: boolean;
+    session: string | null;
+    print: boolean;
+    launch: string | null;
+    llm: boolean;
+    root: string | null;
+}
+
+type Runner = (cmd: string[]) => number;
+
+export interface MainOptions {
+    out?: (text: string) => void;
+    err?: (text: string) => void;
+    /** TTY availability override (default: stdin AND stdout are TTYs). */
+    isTTY?: boolean;
+    /** Picker input; returns the raw line or null on read failure. */
+    readLine?: (prompt: string) => string | null;
+    /** Interactive child spawn (default: spawnSync stdio-inherit). */
+    runner?: Runner;
+}
+
+function _default_runner(cmd: string[]): number {
+    const r = spawnSync(cmd[0] as string, cmd.slice(1), { stdio: 'inherit' });
+    if (r.error) {
+        process.stderr.write(`${PROG}: cannot run ${cmd[0]}: ${String(r.error)}\n`);
+        return 127;
+    }
+    return r.status ?? 1;
+}
+
+/**
+ * Synchronous /dev/tty line read (never fd 0 — EAGAIN under go-task
+ * `interactive: true` silently auto-aborts a fd-0 prompt).
+ */
+function _tty_read_line(prompt: string): string | null {
+    try {
+        process.stdout.write(prompt);
+        const fd = fs.openSync('/dev/tty', 'rs');
+        try {
+            const buf = Buffer.alloc(1);
+            let line = '';
+            for (;;) {
+                let n = 0;
+                try {
+                    n = fs.readSync(fd, buf, 0, 1, null);
+                } catch (exc) {
+                    const code = (exc as NodeJS.ErrnoException).code;
+                    if (code === 'EAGAIN' || code === 'EINTR') continue;
+                    return null;
+                }
+                if (n === 0) break;
+                const ch = buf.toString('utf-8');
+                if (ch === '\n') break;
+                line += ch;
+            }
+            return line;
+        } finally {
+            fs.closeSync(fd);
+        }
+    } catch {
+        return null;
+    }
+}
+
+// ---------------------------------------------------------------------
+// arg parsing (hand-rolled, house style — no commander in _cli/)
+// ---------------------------------------------------------------------
+
+function _argError(err: (t: string) => void, message: string): never {
+    err(`${USAGE}\n${PROG}: error: ${message}\n`);
+    throw new ArgparseExit(2);
+}
+
+export function _parse(argv: string[], err: (t: string) => void): Opts {
+    const opts: Opts = {
+        list: false,
+        json: false,
+        session: null,
+        print: false,
+        launch: null,
+        llm: false,
+        root: null,
+    };
+    let i = 0;
+    const takeValue = (flag: string): string => {
+        const arg = argv[i] as string;
+        const eq = arg.indexOf('=');
+        if (eq >= 0) return arg.slice(eq + 1);
+        i += 1;
+        const value = argv[i];
+        if (value === undefined) _argError(err, `argument ${flag}: expected one argument`);
+        return value;
+    };
+    while (i < argv.length) {
+        const arg = argv[i] as string;
+        const flag = arg.includes('=') ? arg.slice(0, arg.indexOf('=')) : arg;
+        switch (flag) {
+            case '-h':
+            case '--help':
+                process.stdout.write(_HELP);
+                throw new ArgparseExit(0);
+            case '--list':
+                opts.list = true;
+                break;
+            case '--json':
+                opts.json = true;
+                break;
+            case '--print':
+                opts.print = true;
+                break;
+            case '--llm':
+                opts.llm = true;
+                break;
+            case '--session':
+                opts.session = takeValue('--session');
+                break;
+            case '--launch':
+                opts.launch = takeValue('--launch');
+                break;
+            case '--root':
+                opts.root = takeValue('--root');
+                break;
+            default:
+                _argError(err, `unrecognized arguments: ${arg}`);
+        }
+        i += 1;
+    }
+    return opts;
+}
+
+// ---------------------------------------------------------------------
+// rendering
+// ---------------------------------------------------------------------
+
+function _fmt_date(iso: string | null): string {
+    if (!iso) return 'unknown-date';
+    return iso.slice(0, 16).replace('T', ' ');
+}
+
+export function render_session_line(s: HandoffSession, index: number): string {
+    const branch = s.branch ? ` · ${s.branch}` : '';
+    return `${String(index + 1).padStart(2)}. ${_fmt_date(s.endedAt ?? s.startedAt)} · ${s.source}${branch} · ${s.summary}`;
+}
+
+function _render_list(sessions: HandoffSession[], json: boolean): string {
+    if (json) return JSON.stringify(sessions, null, 2) + '\n';
+    return sessions.map((s, i) => render_session_line(s, i)).join('\n') + '\n';
+}
+
+// ---------------------------------------------------------------------
+// main
+// ---------------------------------------------------------------------
+
+export function main(argv: string[] | null = null, options: MainOptions = {}): number {
+    const out = options.out ?? ((t: string): void => void process.stdout.write(t));
+    const err = options.err ?? ((t: string): void => void process.stderr.write(t));
+    const isTTY = options.isTTY ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    const readLine = options.readLine ?? _tty_read_line;
+    const runner = options.runner ?? _default_runner;
+
+    let opts: Opts;
+    try {
+        opts = _parse(argv ?? process.argv.slice(2), err);
+    } catch (exc) {
+        if (exc instanceof ArgparseExit) return exc.code;
+        throw exc;
+    }
+
+    // The bash dispatcher strips a global `--root` and exports it as
+    // AGENT_CONFIG_PROJECT_ROOT instead — honor both channels.
+    const envRoot =
+        process.env.AGENT_CONFIG_ROOT_OVERRIDE === '1'
+            ? process.env.AGENT_CONFIG_PROJECT_ROOT || null
+            : null;
+    const root = path.resolve(opts.root ?? envRoot ?? process.cwd());
+    const sessions = list_handoff_sessions({ cwd: root });
+
+    if (opts.list) {
+        if (sessions.length === 0) {
+            out('no recent sessions found for this repo\n');
+            return 1;
+        }
+        out(_render_list(sessions, opts.json));
+        return 0;
+    }
+
+    if (sessions.length === 0) {
+        err(`${PROG}: no recent sessions found for this repo\n`);
+        return 1;
+    }
+
+    if (opts.launch && !(opts.launch in LAUNCH_ADAPTERS)) {
+        err(`${USAGE}\n${PROG}: error: unknown --launch host '${opts.launch}' (claude | codex)\n`);
+        return 2;
+    }
+    const adapter = opts.launch ? (LAUNCH_ADAPTERS[opts.launch] as LaunchAdapter) : null;
+    if (opts.launch && adapter && !adapter.supports_launch) {
+        err(`${PROG}: --launch ${opts.launch} is not supported yet (hook injection already works there)\n`);
+        return 2;
+    }
+
+    // resolve the session — flag, or picker in a TTY
+    let picked: HandoffSession | undefined;
+    if (opts.session) {
+        const matches = sessions.filter((s) => s.id === opts.session || s.id.startsWith(opts.session as string));
+        if (matches.length === 0) {
+            err(`${PROG}: session '${opts.session}' not found — run --list\n`);
+            return 1;
+        }
+        if (matches.length > 1) {
+            err(`${PROG}: session prefix '${opts.session}' is ambiguous (${matches.length} matches)\n`);
+            return 2;
+        }
+        picked = matches[0];
+    } else if (isTTY) {
+        out('Recent sessions:\n');
+        out(_render_list(sessions, false));
+        const raw = readLine(`Pick a session [1-${sessions.length}]: `);
+        const n = Number((raw ?? '').trim());
+        if (!Number.isInteger(n) || n < 1 || n > sessions.length) {
+            err(`${PROG}: invalid selection\n`);
+            return 2;
+        }
+        picked = sessions[n - 1];
+    } else {
+        out(_render_list(sessions, false));
+        err(`${PROG}: non-interactive invocation needs --session <id> (list above)\n`);
+        return 2;
+    }
+    if (!picked) return 2;
+
+    let text: string;
+    try {
+        text = build_handoff(picked, { cwd: root, llm: opts.llm });
+    } catch (exc) {
+        if (exc instanceof LlmPolishNotImplementedError) {
+            err(`${PROG}: ${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
+
+    if (opts.print) {
+        out(text);
+        return 0;
+    }
+
+    if (adapter && adapter.seeding === 'initial-prompt') {
+        // no state file on this path — nothing would consume it
+        out(`launching ${opts.launch} with the handoff as initial prompt…\n`);
+        return runner(adapter.build_argv(text));
+    }
+
+    // Only the most recent handoff persists — a second `handoff` run before
+    // the next session start replaces the unconsumed file (by design; the
+    // hook consumes exactly one).
+    const existed = fs.existsSync(handoff_target_path(root));
+    const target = write_handoff(text, { cwd: root });
+    if (existed) out('note: replaced an unconsumed handoff — only the most recent one persists.\n');
+    out(`handoff written: ${target}\n`);
+    out('start a new session — the handoff will be injected automatically (hook-capable hosts).\n');
+
+    if (adapter) {
+        out(`launching ${opts.launch}…\n`);
+        return runner(adapter.build_argv(text));
+    }
+    return 0;
+}
+
+// ---------------------------------------------------------------------
+// entry guard (symlink-safe; same shape as cmd_analyze_session.ts —
+// under the cli-delegate bundle the argv-URL compare matches the bundle)
+// ---------------------------------------------------------------------
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // Symlinked invocation (installed projection, /var → /private/var):
+    // compare realpaths so the entry guard still fires.
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exitCode = main();
+}