@event4u/agent-config 14.6.0 → 14.8.0

package/src/scripts/ai_council/cli_help.ts

@@ -0,0 +1,55 @@
+/**
+ * Sub-help rendering for the council CLI.
+ *
+ * Lives here rather than in `council_cli.ts` for a measured reason: that file
+ * sits ~2,500 lines above the 1,500-line source ceiling, and
+ * `check_source_size_budget` is a shrink-only ratchet — every line added there
+ * is a new violation, so a 45-line help renderer reds the build. Extraction is
+ * the documented response; raising the baseline is not.
+ *
+ * WHAT IT FIXES. `council run --help` printed `usage: agent-config council run
+ * [-h] ...` and no flag list at all. Measured 2026-08-20: a first council run
+ * cost six calls, two of them spent discovering `--confirm` and `--output` by
+ * grepping the CLI source. The information was available at runtime all along —
+ * the parser's own spec table carries it — it simply was not printed.
+ *
+ * Rendered from those specs rather than hand-listed on purpose: a hand-written
+ * flag list is a second source of truth that drifts the first time a flag is
+ * added.
+ */
+
+/** The shape `council_cli`'s spec table exposes, narrowed to what help needs. */
+export interface HelpSpec {
+    readonly positionals: readonly string[];
+    readonly opts: readonly { readonly flag: string; readonly takesValue: boolean; readonly choices?: readonly string[] | null }[];
+    readonly requiredOpts: readonly string[];
+}
+
+/**
+ * `usageLine` first (its exact text is asserted elsewhere and must not move),
+ * then positionals, then every flag with its value shape and a `[required]`
+ * marker where the parser demands one.
+ */
+export function renderSubHelp(_cmd: string, usageLine: string, spec: HelpSpec): string {
+    const lines: string[] = [usageLine.trimEnd()];
+    if (spec.positionals.length > 0) {
+        lines.push('', 'positional arguments:');
+        for (const p of spec.positionals) {
+            lines.push(`  ${p}`);
+        }
+    }
+    if (spec.opts.length > 0) {
+        lines.push('', 'options:');
+        const required = new Set(spec.requiredOpts);
+        for (const o of spec.opts) {
+            const value = o.takesValue
+                ? o.choices && o.choices.length > 0
+                    ? ` {${o.choices.join(',')}}`
+                    : ' VALUE'
+                : '';
+            lines.push(`  ${o.flag}${value}${required.has(o.flag) ? '   [required]' : ''}`);
+        }
+    }
+    lines.push('');
+    return lines.join('\n');
+}

package/src/scripts/audit_adr_coverage.ts

@@ -16,12 +16,19 @@
  *   --regen-area-readme <area>  rewrite docs/adrs/<area>/README.md. Idempotent.
  *
  * Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
+ *
+ * Record metadata is read by `read_adr_meta`: the shared frontmatter reader
+ * (`_lib/adr_frontmatter`) when a `---` block is present, the transitional
+ * blockquote header otherwise. The seven per-area records carried only the
+ * blockquote until 2026-08-21, so both paths have to work while the two
+ * surfaces overlap.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { readAdrFrontmatterScalars } from './_lib/adr_frontmatter.js';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -89,10 +96,26 @@ export function unlistedAreaDirs(adrsRoot: string): string[] {
 
 // ^(\d{4})-([a-z0-9-]+)\.md$
 const NAMED = /^(\d{4})-([a-z0-9-]+)\.md$/;
-// ^---\n(.*?)\n---  (DOTALL)
-const FM = /^---\n([\s\S]*?)\n---/;
-// ^([a-z_]+):\s*(.+?)\s*$  (MULTILINE)
-const FIELD = /^([a-z_]+):[ \t]*(.+?)[ \t]*$/gm;
+
+/**
+ * Metadata keys this script recognises in the transitional blockquote header.
+ *
+ * An allowlist rather than "every `Key: value` pair in a blockquote", because
+ * the blockquote block also carries prose that happens to contain colons — the
+ * `Roadmap:` pointer, a `Contract:` link, and (on `memory/0001`) a whole
+ * supersession banner. Harvesting those would put link markup into the README
+ * table. Keys are matched case-insensitively with spaces folded to `_`.
+ */
+const BLOCKQUOTE_KEYS = new Set([
+    'adr',
+    'area',
+    'status',
+    'date',
+    'decision',
+    'supersedes',
+    'superseded_by',
+    'type',
+]);
 
 interface AdrEntry {
     num: string;
@@ -129,24 +152,87 @@ function _globMdSorted(dir: string): string[] {
     return out;
 }
 
+/**
+ * Read the leading `---` frontmatter block, `{}` when there is none.
+ *
+ * Delegates to the one shared reader (`_lib/adr_frontmatter`) rather than
+ * keeping this script's own regex: the tree carried three divergent ADR
+ * frontmatter parsers plus this one, and the two nested axes (`provenance`,
+ * `evidence`) are exactly the shape a `^([a-z_]+):\s*(.+?)$` regex reads as
+ * absent.
+ *
+ * What is preserved: the `{}`-on-absent return, and the scalar keys this
+ * script's callers read.
+ *
+ * What changed, stated because "preserved" was claimed for it and is false:
+ * the removed `_stripChars(v, ' "\'')` stripped repeated and unbalanced quote
+ * and space characters from both ends (Python `str.strip` semantics), while the
+ * shared reader's `stripQuotes` is `/^["'](.*)["']$/` — exactly one balanced
+ * pair. Two inputs now differ: `key: "value` keeps its opening quote (was
+ * `value`), and `key: ''v''` yields `'v'` (was `v`). No record in the corpus
+ * exercises either shape today, and the old behaviour is deliberately NOT
+ * restored — one shared reader beats a bug-compatible local copy.
+ */
 export function parse_fm(text: string): Record<string, string> {
-    const m = FM.exec(text);
-    if (!m) {
-        return {};
-    }
+    return readAdrFrontmatterScalars(text) ?? {};
+}
+
+/**
+ * Read the transitional blockquote metadata header.
+ *
+ * The seven per-area records predate the frontmatter contract and carry their
+ * metadata as a blockquote line instead:
+ *
+ * ```
+ * > Area: `router` · Status: accepted · Date: 2026-05-16 · Type: retrospective
+ * ```
+ *
+ * Two shapes have to be handled and both occur in the tree. Several fields
+ * share one line separated by `·`, so the split is on the separator first and
+ * the first `:` second. And the value is often wrapped in backticks
+ * (`` `router` ``), which are stripped — a table cell showing `` `accepted` ``
+ * would not match what the frontmatter path produces for the same record.
+ *
+ * Scanning stops at the first `## ` heading: everything above it is the
+ * metadata header, everything below is body prose whose blockquotes are
+ * quotations, not metadata.
+ */
+export function parse_blockquote_meta(text: string): Record<string, string> {
     const out: Record<string, string> = {};
-    const body = m[1] as string;
-    FIELD.lastIndex = 0;
-    let fm: RegExpExecArray | null;
-    while ((fm = FIELD.exec(body)) !== null) {
-        const k = fm[1] as string;
-        const v = fm[2] as string;
-        // v.strip(" \"'") — strip leading/trailing space, double- and single-quote.
-        out[k] = _stripChars(v, ' "\'');
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        if (line.startsWith('## ')) break;
+        if (!line.startsWith('>')) continue;
+        for (const part of line.replace(/^>\s*/, '').split('·')) {
+            const idx = part.indexOf(':');
+            if (idx <= 0) continue;
+            const key = part.slice(0, idx).trim().toLowerCase().replace(/\s+/g, '_');
+            if (!BLOCKQUOTE_KEYS.has(key)) continue;
+            const value = _stripChars(part.slice(idx + 1), ' "\'`');
+            if (value === '') continue;
+            // First occurrence wins — a later body line never overwrites the header.
+            if (!(key in out)) out[key] = value;
+        }
     }
     return out;
 }
 
+/**
+ * One record's metadata: frontmatter when present, the blockquote header
+ * otherwise.
+ *
+ * Frontmatter wins outright rather than merging. During the transition a record
+ * carries both, and the blockquote is explicitly the human-readable duplicate —
+ * merging would make the authoritative surface depend on which of the two
+ * happened to mention a field, and a stale duplicate would then be able to
+ * contribute a value the frontmatter had already corrected.
+ */
+export function read_adr_meta(text: string): Record<string, string> {
+    const fm = readAdrFrontmatterScalars(text);
+    if (fm !== null && Object.keys(fm).length > 0) return fm;
+    return parse_blockquote_meta(text);
+}
+
 /** Mirror Python `str.strip(chars)`. */
 function _stripChars(s: string, chars: string): string {
     let start = 0;
@@ -193,7 +279,7 @@ export function scan_area(area: string): [AdrEntry[], string[]] {
             errs.push(`${area}/${base}: filename does not match NNNN-<slug>.md`);
             continue;
         }
-        const fm = parse_fm(fs.readFileSync(p, 'utf-8'));
+        const fm = read_adr_meta(fs.readFileSync(p, 'utf-8'));
         adrs.push({ num: m[1] as string, slug: m[2] as string, path: base, ...fm });
     }
     // Gap check.

package/src/scripts/before_complete_hook.ts

@@ -29,7 +29,14 @@
  *   - post_tool_use → inspect tool + command, record verifications
  *   - stop                                → record stop fired (claim-done window)
  *
- * Output: `agents/state/verify-before-complete.json`
+ * Output: `agents/state/verify-before-complete/<sha256(session_id)>.json`
+ *   — ONE FILE PER SESSION. It was one file per project root until 2026-08-20,
+ *   which under this repo's worktree workflow (`CLAUDE_PROJECT_DIR` resolves to
+ *   the PARENT checkout) meant one file across every concurrent run: a
+ *   neighbour's CI witness and verification counters became this run's, and the
+ *   in-file session-boundary reset in `_update` turned into the damage rather
+ *   than the defense, because two live runs then clear each other in a loop.
+ *   Consumers address it via `statePathFor`, never a path literal.
  *   {
  *     "schema_version": 1,
  *     "session_id": "<str>",
@@ -49,14 +56,79 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
-import { atomic_write_json } from "./hooks/state_io.js";
+import {
+  has_stable_session_id,
+  prune_legacy_state_file,
+  prune_stale_session_states,
+  session_state_file,
+  update_json_under_lock,
+} from "./hooks/state_io.js";
 import { readHookStdin } from "./hooks/hook_stdin.js";
 
 // NOTE: the Python docstring says `agents/runtime/state/`, but the code
 // constant is `agents/state/`. Replicated verbatim — latent docstring/code
 // divergence in the retired Python implementation (ADR-200 § replicate latent bugs).
+//
+// PRE-SPLIT PATH. Nothing reads it after the per-session split below;
+// `prune_legacy_state_file` removes it once this version owns the tree. Kept
+// exported because `prune_legacy_state_file` needs to name the path it deletes,
+// and because a reader that still resolves it should get a compile-visible
+// symbol rather than a silently stale path literal. It is NOT kept for an
+// "older bundle still writing during an upgrade" — that phrasing was copied
+// here unchecked and is corrected at `state_io.prune_legacy_state_file`, which
+// carries the measured deployment shape and the one narrow window that remains.
 export const STATE_FILE = path.join("agents", "state", "verify-before-complete.json");
 
+/**
+ * Per-SESSION state, one file each.
+ *
+ * WHY, in one sentence: the single file above is shared by every concurrent
+ * session under one project root — which in this repo's worktree workflow is
+ * the PARENT checkout — so a neighbouring run's CI witness and verification
+ * counters became this run's.
+ *
+ * The in-file session-boundary reset in `_update` is NOT the fix and is the
+ * reason this was easy to miss. It is written for SEQUENTIAL sessions: notice a
+ * foreign `session_id`, clear the session-scoped counters, carry on. Under
+ * CONCURRENT sessions that same code is the damage — each run reads the other's
+ * id, resets, and writes, so two sessions erase each other's verification
+ * evidence in a loop. The direction of the loss is toward FORGETTING a
+ * verification that did happen, which then reads as "not verified this turn".
+ *
+ * The reset stays, but NOT for the reasons this comment first gave. It said the
+ * reset "still covers the id-less bucket and a legacy file", and a cross-model
+ * review (2026-08-20, both seats) showed neither is reachable: an id-less
+ * envelope returns from `run()` before `_update` is ever called, and the legacy
+ * file is never LOADED any more — only deleted. Writing an unreachable
+ * justification next to retained code is how dead logic survives review, so the
+ * real one is stated instead.
+ *
+ * Its one reachable case is a file at THIS session's digest path carrying
+ * somebody else's `session_id` — a copy, a restore, a hand-edit, or a buggy
+ * writer. That is integrity recovery on the producer side, and it pairs with the
+ * consumer side refusing the same file outright (`owns_session_state`). Both
+ * halves are needed: the producer cannot refuse to run, and the consumer cannot
+ * repair. `before_complete_session_isolation.test.ts` reaches it directly.
+ *
+ * Rationale, the digest-not-sanitiser property, and the claim-then-revalidate
+ * prune all live once in `hooks/state_io.ts` § Per-session concern state — this
+ * is the second concern to need them, which is what made sharing them right.
+ */
+export const STATE_DIR = path.join("agents", "state", "verify-before-complete");
+
+/**
+ * Days after which an untouched session's state is pruned.
+ *
+ * Matches the language hook and the council session-artefact window — a
+ * convention match, not a measurement, and stated as such.
+ */
+export const STATE_RETENTION_DAYS = 7;
+
+/** Path of one session's state file. */
+export function statePathFor(session_id: string): string {
+  return session_state_file(STATE_DIR, session_id);
+}
+
 // Tool names across platforms whose `command` / `tool_input.command` field
 // carries a shell command we can inspect. Edit tools are deliberately
 // excluded — they cannot run verification.
@@ -125,26 +197,6 @@ function _empty_state(): StateDict {
   };
 }
 
-function _load_state(target: string): StateDict {
-  let isFile = false;
-  try {
-    isFile = fs.statSync(target).isFile();
-  } catch {
-    isFile = false;
-  }
-  if (!isFile) {
-    return _empty_state();
-  }
-  try {
-    const decoded = JSON.parse(fs.readFileSync(target, "utf-8")) as unknown;
-    if (typeof decoded === "object" && decoded !== null && !Array.isArray(decoded)) {
-      return { ..._empty_state(), ...(decoded as StateDict) };
-    }
-  } catch {
-    // fall through
-  }
-  return _empty_state();
-}
 
 /** Return [tool_name, command_text] from a tool-event payload. */
 function _extract_command(payload: StateDict): [string | null, string | null] {
@@ -424,19 +476,92 @@ export function run(
   }
 
   const event = (envelope["event"] || "") as string;
-  const target = path.join(consumer_root, STATE_FILE);
-  let state = _load_state(target);
-  state = _update(state, event, envelope);
+  const session_id = typeof envelope["session_id"] === "string" ? envelope["session_id"] : "";
+
+  // No stable identity → persist NOTHING. Sanitising an empty id into a shared
+  // literal is the original cross-session defect restored in the one case with
+  // no guard left (see `state_io` § has_stable_session_id).
+  //
+  // What that costs, and it is worse than the word this comment first used: on a
+  // host that sends no `session_id` this concern records no evidence at all, so
+  // `readCiSettled` returns "nothing observed" and the turn-end gate's completion
+  // detector never fires. The first version called that "the SAFE direction —
+  // under-refusing". A cross-model review (2026-08-20, both seats) rejected the
+  // word: for a BLOCKING gate, not refusing is fail-OPEN. A premature completion
+  // claim over unsettled CI passes unchallenged. This is DEGRADED ENFORCEMENT, and
+  // naming it "safe" hides the loss behind a reassuring adjective.
+  //
+  // It is still the right call among the options available, which is a different
+  // claim and the only one the evidence supports: the alternative is one shared
+  // file whose contents belong to whichever concurrent run wrote last, i.e. a
+  // gate that refuses or clears on somebody else's evidence. A gate that goes
+  // quiet is recoverable; a gate that acts on a foreign witness is not.
+  // Every host this suite binds `post_tool_use` on sends a `session_id`
+  // (`hook_manifest.yaml` platforms × `native_event_aliases`), so the degraded
+  // path is a fallback rather than a supported mode — but it is not verified per
+  // host, and this comment does not claim it is.
+  if (!has_stable_session_id(session_id)) {
+    if (verbose) {
+      process.stderr.write(
+        "verify-before-complete-hook: no session_id — running stateless, nothing recorded\n",
+      );
+    }
+    return 0;
+  }
 
-  try {
-    atomic_write_json(target, state);
-  } catch {
+  const target = path.join(consumer_root, statePathFor(session_id));
+
+  // LOAD → UPDATE → PUBLISH under ONE lock, not three separate steps.
+  //
+  // This was `_load_state` / `_update` / `atomic_write_json`, which makes the
+  // publish atomic and leaves the transaction racy. A cross-model review
+  // (2026-08-20, both seats) named the interleaving, and this host runs tool
+  // calls in parallel, so it is reachable rather than theoretical: two
+  // `post_tool_use` invocations for the SAME session both load the counter at
+  // N, both compute N+1, both publish N+1, and one verification is lost. The
+  // per-session split does nothing about it — the two failures are independent,
+  // and closing the cross-session one made this one easier to mistake for
+  // solved.
+  //
+  // `state` is captured for the verbose line below; the value that lands is the
+  // one computed inside the lock, from state read inside the lock.
+  let state: StateDict = {};
+  // Three-state result (state_io § Three states, not two). This mutator NEVER
+  // returns null, so `skipped` is unreachable here — but it is handled with
+  // `written` rather than lumped with `failed`, because the two have opposite
+  // meanings for this caller: a decline means the state needed no change, a
+  // failure means the state on disk is not what this run computed. Writing
+  // `!== "written"` would have made a future mutator that learns to decline
+  // silently stop recording, which is the failure this API change exists to
+  // make impossible to write by accident.
+  const outcome = update_json_under_lock<StateDict>(target, (loaded) => {
+    // `_empty_state()` UNDER the loaded value, which is what the `_load_state`
+    // this replaced did (`{ ..._empty_state(), ...decoded }`). Dropping it would
+    // have been a silent regression that the suite could not see: `_asInt`
+    // treats a missing counter as 0 and the `=== true` guards treat a missing
+    // flag as false, so every assertion would still pass while `schema_version`
+    // and an explicit `ci_last: null` vanished from a freshly created file.
+    state = _update({ ..._empty_state(), ...loaded } as StateDict, event, envelope);
+    return state;
+  });
+  if (outcome === "failed") {
     if (verbose) {
       process.stderr.write("verify-before-complete-hook: state write failed\n");
     }
     return 0;
   }
 
+  // Housekeeping on the once-per-turn events only — never on `post_tool_use`,
+  // which fires many times per turn, and never before the write above.
+  if (event === "session_start" || event === "user_prompt_submit") {
+    prune_legacy_state_file(path.join(consumer_root, STATE_FILE));
+    prune_stale_session_states(
+      path.join(consumer_root, STATE_DIR),
+      Date.now(),
+      STATE_RETENTION_DAYS,
+    );
+  }
+
   if (verbose) {
     process.stderr.write(
       `verify-before-complete-hook: event=${event} ` +

package/src/scripts/bench_ab_v2_complexity.ts

@@ -35,6 +35,7 @@ import { fileURLToPath } from 'node:url';
 
 import { parse as parseYaml } from 'yaml';
 
+import { PinnedRepoError, pristine_tree_for } from './_lib/bench_ab_pinned_repo.js';
 import { medianComplexityPerChangedFunction } from './_lib/bench_ab_complexity.js';
 import { changed_files, diff_line_counts } from './_lib/bench_ab_scoring_v2.js';
 
@@ -63,15 +64,15 @@ function _dictOr(v: unknown): Dict {
  * trial to `skipped_reason: 'task id not in the corpus'`, which is a reportable
  * state, rather than aborting a re-score that may still cover most of the report.
  */
-function loadCorpusFixtures(corpusPath: string | null): Map<string, string> {
-    const byId = new Map<string, string>();
+function loadCorpusFixtures(corpusPath: string | null): Map<string, Dict> {
+    const byId = new Map<string, Dict>();
     if (!corpusPath || !fs.existsSync(corpusPath)) return byId;
     try {
         const corpus = _dictOr(parseYaml(fs.readFileSync(corpusPath, 'utf8'), { version: '1.1' }));
         const tasks = Array.isArray(corpus['tasks']) ? (corpus['tasks'] as Dict[]) : [];
         for (const t of tasks) {
-            if (t['id'] !== undefined && t['fixture'] !== undefined) {
-                byId.set(String(t['id']), String(t['fixture']));
+            if (t['id'] !== undefined && (t['fixture'] !== undefined || t['repo'] !== undefined)) {
+                byId.set(String(t['id']), t);
             }
         }
     } catch {
@@ -109,7 +110,7 @@ export async function rescoreReport(
 
     for (const rec of records) {
         const taskId = String(rec['id'] ?? '<unknown>');
-        const fixtureRel = byId.get(taskId) ?? null;
+        const corpusTask = byId.get(taskId) ?? null;
         const arms = _dictOr(rec['arms']);
         for (const [arm, runsRaw] of Object.entries(arms)) {
             const runs = Array.isArray(runsRaw) ? (runsRaw as Dict[]) : [];
@@ -134,12 +135,31 @@ export async function rescoreReport(
                     out.push(row);
                     continue;
                 }
-                if (fixtureRel === null) {
+                if (corpusTask === null) {
                     row.skipped_reason = 'task id not in the corpus';
                     out.push(row);
                     continue;
                 }
-                const fixture = path.join(fixturesRoot, fixtureRel);
+                // Delta #9: a pinned task's pristine tree is a local cache entry, and
+                // this re-scorer is `offlineOnly` on purpose — a cold cache reports
+                // "not materialised" rather than fetching a repository during what is
+                // meant to be an offline re-score of a finished sweep. A malformed pin
+                // is reported per trial, never thrown: one bad corpus entry must not
+                // abort a re-score that still covers every other trial.
+                let fixture: string | null;
+                try {
+                    fixture = pristine_tree_for(corpusTask, { fixturesRoot, offlineOnly: true });
+                } catch (err) {
+                    row.skipped_reason =
+                        err instanceof PinnedRepoError ? `invalid pin: ${err.message}` : 'invalid corpus task';
+                    out.push(row);
+                    continue;
+                }
+                if (fixture === null) {
+                    row.skipped_reason = 'pinned repo not materialised locally';
+                    out.push(row);
+                    continue;
+                }
                 if (!fs.existsSync(fixture)) {
                     row.skipped_reason = 'fixture missing on disk';
                     out.push(row);