@event4u/agent-config 7.0.2 → 7.2.0

package/src/scripts/_lib/verify_budget.ts

@@ -0,0 +1,54 @@
+/**
+ * Verification-budget model (Phase 4).
+ *
+ * Pure, no-I/O. Decides HOW a delegated sub-task's output is verified so the
+ * cross-model judge Iron Law and verify-before-complete are preserved WITHOUT
+ * double-costing every trivial delegation. Contract:
+ * `src/agent-src/contexts/execution/verify-budget.md`.
+ *
+ * - Trivial (below the change-size floor, read-only / no file writes) →
+ *   `deterministic` verification (diff + dry-run + structural checks, no LLM).
+ * - Otherwise → `judge` (full cross-model judge per subagent-orchestration).
+ * - A required verification that did not run is a SURFACED safety gap, never a
+ *   silent pass.
+ */
+
+export type VerifyMode = 'deterministic' | 'judge' | 'none';
+
+/** Max changed-line count (inclusive) that still counts as trivial. */
+export const TRIVIAL_CHANGE_FLOOR = 20;
+
+export interface VerifyInputs {
+    /** Changed lines the sub-task produced. */
+    change_size: number;
+    /** Did the sub-task write/modify files? */
+    file_writes: boolean;
+    /** Was the sub-task read-only (query/analysis, no mutation)? */
+    read_only: boolean;
+}
+
+/**
+ * Select the verification mode for a completed sub-task.
+ * Trivial + non-mutating → deterministic; anything else → judge.
+ */
+export function selectVerifyMode(inp: VerifyInputs): VerifyMode {
+    if (inp.read_only) return 'deterministic';
+    const trivial = inp.change_size <= TRIVIAL_CHANGE_FLOOR && !inp.file_writes;
+    return trivial ? 'deterministic' : 'judge';
+}
+
+/**
+ * Detect a verification safety gap: a mode was required but the recorded mode
+ * was `none`. Returns a human-readable gap string, or null when clean.
+ * The orchestrator surfaces a non-null result — it is never a silent pass.
+ */
+export function verificationGap(required: VerifyMode, recorded: VerifyMode): string | null {
+    if (required === 'none') return null;
+    if (recorded === 'none') {
+        return `verification gap: '${required}' required but none recorded`;
+    }
+    if (required === 'judge' && recorded === 'deterministic') {
+        return `verification gap: non-trivial change verified deterministically (judge required)`;
+    }
+    return null;
+}

package/src/scripts/ai_council/advisors.ts

@@ -2,8 +2,10 @@
  * Thinking-style advisors — replace-mode call planning (Phase 6).
  *
  * TypeScript twin of `src/scripts/ai_council/advisors.py` (ADR-200 —
- * Python→TS migration, Phase 1). When `agents/settings/.ai-council.yml`
- * enables an advisor (e.g. `contrarian` bound to `member: anthropic`), the
+ * Python→TS migration, Phase 1). When the user-global
+ * `~/.event4u/agent-config/settings/.ai-council.yml` (always global —
+ * ADR-104) enables an advisor (e.g. `contrarian` bound to
+ * `member: anthropic`), the
  * orchestrator REPLACES the matching plain-member call with an
  * advisor-persona call on the same provider. Same total call count as a
  * plain run; bounded extra cost beyond the persona-prompt token delta.

package/src/scripts/ai_council/clients.ts

@@ -287,12 +287,18 @@ function _curlJsonPost(url: string, extraHeaders: string[], body: unknown): unkn
     for (const h of extraHeaders) {
         args.push('-H', h);
     }
+    // `--connect-timeout` fast-fails a dead host; `--max-time` lets curl abort
+    // itself cleanly (surfacing a real `curl exited` error with stderr) ~10s
+    // before the `spawnSync` timeout would kill it with an opaque ETIMEDOUT.
+    // A full 16k-token generation legitimately runs several minutes, so the
+    // ceiling is 300s, not 120s (the old value timed out long Anthropic calls).
+    args.push('--connect-timeout', '30', '--max-time', '290');
     args.push('-w', '\n%{http_code}', '--data-binary', '@-');
     const r = spawnSync('curl', args, {
         input: JSON.stringify(body),
         encoding: 'utf8',
         maxBuffer: 64 * 1024 * 1024,
-        timeout: 120_000,
+        timeout: 300_000,
     });
     if (r.error) {
         throw new Error(`curl spawn failed: ${(r.error as Error).message}`);

package/src/scripts/ai_council/config.ts

@@ -6,8 +6,9 @@
  * surface and validation behaviour byte-for-byte: same exported
  * snake_case names, same defaults, same error messages, same precedence.
  *
- * Reads `agents/settings/.ai-council.yml` per the contract in
- * `docs/contracts/ai-council-config.md`. Replaces the fragmented
+ * Reads the user-global `~/.event4u/agent-config/settings/.ai-council.yml`
+ * per the contract in `docs/contracts/ai-council-config.md` (council
+ * config is ALWAYS user-global — ADR-104). Replaces the fragmented
  * `.agent-settings.yml` `ai_council` block (Phase 0 migration).
  *
  * Validation contract (8 rules, all enforced at load time):
@@ -93,7 +94,7 @@ export type PathLike = string;
 
 // ── error type ─────────────────────────────────────────────────────
 
-/** Raised when `agents/settings/.ai-council.yml` violates the schema. */
+/** Raised when the user-global `.ai-council.yml` violates the schema. */
 export class CouncilConfigError extends Error {
     constructor(message: string) {
         super(message);
@@ -562,8 +563,10 @@ export const COUNCIL_CONFIG_USER_GLOBAL_REL = 'settings/.ai-council.yml';
 
 /**
  * Env var pinning the council config to an explicit absolute path, ahead
- * of the project → user-global search. Mirrors `EVENT4U_CONFIG_HOME` but
- * targets the config file itself (tests / power users).
+ * of the user-global default. Mirrors `EVENT4U_CONFIG_HOME` but targets
+ * the config file itself (tests / power users). This is the ONLY escape
+ * from the user-global location — it is an explicit absolute path, never
+ * a "search the project" path.
  */
 export const COUNCIL_CONFIG_ENV = 'AI_COUNCIL_CONFIG';
 
@@ -598,14 +601,24 @@ function _isAbsoluteLikePython(p: string): boolean {
 /**
  * Resolve which `.ai-council.yml` the council reads.
  *
+ * **The council config is ALWAYS user-global.** It is a per-developer
+ * facility configured once and works in every project, worktree, and
+ * CWD — including consumer repos that carry no council file of their
+ * own. The project tree is NEVER searched for council config (ADR-104,
+ * superseding the project-local override kept by ADR-093).
+ *
  * Precedence (first match wins):
  *
  * 1. `$AI_COUNCIL_CONFIG` — explicit absolute override (tests / power
- *    users). Honoured even when the target is absent.
- * 2. Project-local `<project_root>/agents/settings/.ai-council.yml`.
- * 3. User-global `~/.event4u/agent-config/settings/.ai-council.yml`
+ *    users). Honoured even when the target is absent. This is an
+ *    explicit path, not a project search.
+ * 2. User-global `~/.event4u/agent-config/settings/.ai-council.yml`
  *    (with the legacy `~/.config/agent-config/` read-fallback).
  *
+ * `project_root` is accepted for signature stability with callers but is
+ * NOT consulted for config resolution — the council never reads
+ * `<project_root>/agents/settings/.ai-council.yml`.
+ *
  * Always returns a path (never `null`): when nothing exists yet it
  * returns the user-global write target.
  */
@@ -613,20 +626,12 @@ export function resolve_config_path(
     project_root: PathLike,
     options: { env?: user_global_paths.EnvMap | null } = {},
 ): PathLike {
+    void project_root; // intentionally unused — council config is always user-global (ADR-104).
     const env_map = options.env != null ? options.env : process.env;
     const override = env_map[COUNCIL_CONFIG_ENV];
     if (override) {
         return _expanduser(override);
     }
-    const project_path = path.join(
-        project_root,
-        'agents',
-        'settings',
-        COUNCIL_CONFIG_RELNAME,
-    );
-    if (fs.existsSync(project_path)) {
-        return project_path;
-    }
     const found = user_global_paths.resolve_with_fallback(
         COUNCIL_CONFIG_USER_GLOBAL_REL,
         { env: options.env ?? null },

package/src/scripts/bench_ab_v2_run.ts

@@ -67,14 +67,20 @@ type Dict = Record<string, unknown>;
 interface ArmSpec {
     setting_sources: string | null;
     inject: string | null; // None | "rdp" | "placebo"
+    recursive?: boolean; // ADR-106 D₂ arm: depth-bounded attempt→critic→re-attempt loop
 }
 
 // Arm -> (setting_sources, inject) where inject ∈ {None, "rdp", "placebo"}.
+// `package-recursive` (ADR-106's D₂) reuses the real-plugin `package` config but
+// runs the recursion loop instead of a single --print. It only executes when
+// explicitly selected (`--arms package-recursive`); the four default arms are
+// untouched, so existing runs and their golden-parity outputs are unchanged.
 const ARMS: Record<string, ArmSpec> = {
     vanilla: { setting_sources: 'project,local', inject: null },
     package: { setting_sources: null, inject: null },
     'package-rdp': { setting_sources: null, inject: 'rdp' },
     placebo: { setting_sources: 'project,local', inject: 'placebo' },
+    'package-recursive': { setting_sources: null, inject: null, recursive: true },
 };
 
 /**
@@ -165,10 +171,14 @@ interface RunOneOpts {
     timeout: number;
     placebo_chars: number;
     sp_dir: string;
+    max_depth?: number | null; // recursion arm only — hard cap on correction rounds (default 1)
 }
 
 export function run_one(task: Dict, arm: string, opts: RunOneOpts): Dict {
     const spec = ARMS[arm] as ArmSpec;
+    if (spec.recursive) {
+        return run_one_recursive(task, opts);
+    }
     const [clone, fixture] = reset_fixture(task);
     const sp_text = injected_text(spec.inject, opts.placebo_chars);
     let sp_file: string | null = null;
@@ -198,6 +208,123 @@ export function run_one(task: Dict, arm: string, opts: RunOneOpts): Dict {
     };
 }
 
+export interface RecursiveAttempt {
+    run: Dict;
+    score: scoring.ScoreResultV2;
+    output?: string; // pair-capture: changed-file contents at this depth (for human-preference judging)
+}
+
+/**
+ * ADR-106 D₂ arm — depth-bounded recursive self-verification.
+ *
+ * Loop: attempt → critic verdict → conditional re-attempt, depth = hard compute
+ * cap. The critic is the DETERMINISTIC v2 scorer (accept iff the attempt is both
+ * capability- AND discipline-passing) — cheapest critic, no extra model call,
+ * fully testable. A model-based / cross-vendor critic is a later option (see
+ * road-to-recursive-verification.md Phase 4).
+ *
+ * `attemptFn(depth, priorVerdict)` is an injectable seam: the default runs the
+ * real `package`-config agent (prior verdict threaded as the system prompt on
+ * re-attempts) and scores it; tests inject a scripted attemptFn to exercise the
+ * loop control flow with NO live model call.
+ *
+ * Verifies the loop's CONTROL FLOW (stop conditions, depth cap, verdict
+ * threading). Whether recursion actually lifts capability/discipline is the
+ * empirical question the live `bench:ab` run answers — not asserted here.
+ */
+export function run_one_recursive(
+    task: Dict,
+    opts: RunOneOpts,
+    attemptFn?: (depth: number, priorVerdict: string | null) => RecursiveAttempt,
+    onAttempt?: (depth: number, attempt: RecursiveAttempt) => void,
+): Dict {
+    const maxDepth = Math.max(0, opts.max_depth ?? 1);
+    const makeAttempt =
+        attemptFn ??
+        ((depth: number, priorVerdict: string | null): RecursiveAttempt => {
+            const [clone, fixture] = reset_fixture(task);
+            let sp_file: string | null = null;
+            if (priorVerdict) {
+                sp_file = path.join(opts.sp_dir, `.sp-recursive-${depth}.txt`);
+                fs.writeFileSync(sp_file, priorVerdict, { encoding: 'utf-8' });
+            }
+            const run = v1.run_live(task, clone, opts.timeout, {
+                sysprompt_file: sp_file,
+                setting_sources: (ARMS['package'] as ArmSpec).setting_sources,
+                max_budget: opts.max_budget,
+                model: opts.model,
+            }) as unknown as Dict;
+            const score = scoring.score_task_v2(task, {
+                fixture_root: fixture,
+                clone_root: clone,
+                transcript: String(run['transcript'] ?? ''),
+            });
+            // Capture the attempt's output (changed-file contents) for the
+            // human-preference pair, before the next depth resets the clone.
+            const output = score.files_changed
+                .map((f: string) => {
+                    try {
+                        return `--- ${f} ---\n${fs.readFileSync(path.join(clone, f), 'utf-8')}`;
+                    } catch {
+                        return `--- ${f} --- (unreadable)`;
+                    }
+                })
+                .join('\n\n')
+                .slice(0, 4000);
+            return { run, score, output };
+        });
+
+    const accepts = (s: scoring.ScoreResultV2): boolean => Boolean(s.capability_pass) && Boolean(s.discipline_pass);
+
+    let depth = 0;
+    let prior: RecursiveAttempt | null = null;
+    let attempt = makeAttempt(0, null);
+    onAttempt?.(0, attempt);
+    let stop_reason: string;
+    let last_verdict_len = 0;
+    for (;;) {
+        const s = attempt.score;
+        if (accepts(s)) {
+            stop_reason = 'accept';
+            break;
+        }
+        if (depth >= maxDepth) {
+            stop_reason = 'max_depth';
+            break;
+        }
+        if (
+            prior !== null &&
+            s.discipline_score === prior.score.discipline_score &&
+            Boolean(s.capability_pass) === Boolean(prior.score.capability_pass)
+        ) {
+            stop_reason = 'no_progress';
+            break;
+        }
+        depth += 1;
+        const verdict =
+            `Prior attempt (depth ${depth - 1}) did not pass: ` +
+            `capability=${s.capability_pass}, discipline=${s.discipline_score}. ` +
+            `Revise to satisfy the unmet acceptance criteria; change only what the task requires.`;
+        last_verdict_len = verdict.length;
+        prior = attempt;
+        attempt = makeAttempt(depth, verdict);
+        onAttempt?.(depth, attempt);
+    }
+
+    const { run, score } = attempt;
+    return {
+        errored: _pyBool(run['errored']),
+        reason: run['reason'] ?? null,
+        capability_pass: score.capability_pass,
+        discipline_score: new PyFloat(score.discipline_score),
+        discipline_pass: score.discipline_pass,
+        metrics: trajectory_metrics(run, score),
+        injected_chars: last_verdict_len,
+        depth_reached: depth,
+        stop_reason,
+    };
+}
+
 export function main(argv: string[] | null = null): number {
     const args = parse_args(argv ?? process.argv.slice(2));
 

package/src/scripts/bench_ab_v2_stats.ts

@@ -41,6 +41,11 @@ const COMPARISONS: Array<[string, string, string]> = [
     ['package', 'vanilla', 'package lift'],
     ['package-rdp', 'package', 'RDP lift'],
     ['package', 'placebo', 'attribution (content vs length)'],
+    // ADR-106: recursion's NOVEL lift over rules-only (D₂ − D₁). The analyse()
+    // loop is arm-guarded (`arms.includes(t) && arms.includes(b)`), so this row
+    // renders ONLY when a `package-recursive` arm is present — existing runs
+    // (no such arm) are byte-identical, golden parity preserved.
+    ['package-recursive', 'package', 'recursion novel lift (D₂ − D₁)'],
 ];
 
 // ── CPython math.erf / math.comb ports ────────────────────────────────────
@@ -333,6 +338,40 @@ export function compare(records: Dict[], arm_t: string, arm_b: string): Dict {
     };
 }
 
+/**
+ * Recursion's NOVEL discipline lift over rules-only (ADR-106).
+ *
+ * Compares the `package-recursive` arm (D₂ = rules + recursion) against
+ * `package` (D₁ = rules only) via the existing pure `compare()`, so recursion's
+ * marginal lift `D₂ − D₁` is a measured fact, never an assumed redundancy.
+ *
+ * ADDITIVE: does NOT touch the rendered COMPARISONS path — existing CLI output
+ * (and its golden-parity tests) are unaffected. Returns `null` when no
+ * `package-recursive` arm is present in the records, so a future renderer can
+ * skip the block cleanly for non-recursion runs.
+ *
+ * NOTE (Phase 2b live-integration, NOT done here): wiring this into the rendered
+ * stats output (a guarded COMPARISONS entry + a golden-parity fixture refresh)
+ * and producing the `package-recursive` arm itself (a multi-call recursion loop
+ * the single-`--print` runner does not yet support) require the live bench and
+ * are deferred to the supervised Phase 3 session.
+ */
+export const RECURSIVE_ARM = 'package-recursive';
+export const RECURSIVE_BASELINE_ARM = 'package';
+
+export function recursiveNovelLift(records: Dict[]): Dict | null {
+    const hasRecursion = records.some((rec) => {
+        const runs = _dictOr(rec['arms'])[RECURSIVE_ARM];
+        return Array.isArray(runs) && runs.length > 0;
+    });
+    if (!hasRecursion) return null;
+    return {
+        label: 'recursion novel lift (D₂ − D₁)',
+        arms: [RECURSIVE_ARM, RECURSIVE_BASELINE_ARM],
+        ...compare(records, RECURSIVE_ARM, RECURSIVE_BASELINE_ARM),
+    };
+}
+
 export function mean_tokens_by_arm(records: Dict[], arms: string[]): Dict {
     // Mean total tokens per arm over non-errored runs (the cost axis, L10).
     // Truncated/errored runs are excluded — their token count is capped by the

package/src/scripts/check_council_config_location.ts

@@ -9,11 +9,12 @@
  * and the same `<!-- council-config-allowed -->` escape pragma. No behaviour
  * changes — latent bugs replicated.
  *
- * Per ADR-093 the council reads a dedicated `.ai-council.yml` — resolved
- * project-local (`agents/settings/.ai-council.yml`) first, else user-global
- * (`~/.event4u/agent-config/settings/.ai-council.yml`). Keys are top-level in
- * that file; the legacy `ai_council.*` block under `.agent-settings.yml` was
- * removed in Phase 0.
+ * Per ADR-104 (superseding ADR-093) the council reads a dedicated
+ * `.ai-council.yml` resolved ALWAYS from the user-global location
+ * (`~/.event4u/agent-config/settings/.ai-council.yml`) — the project tree
+ * is never searched (the only escape is the explicit `$AI_COUNCIL_CONFIG`
+ * path). Keys are top-level in that file; the legacy `ai_council.*` block
+ * under `.agent-settings.yml` was removed in Phase 0.
  *
  * What it flags, in the council command/skill surfaces + the config contract:
  *

package/src/scripts/check_trunk_drift.ts

@@ -0,0 +1,67 @@
+/**
+ * Pre-PR trunk-drift check (road-to-product-clarity Phase 4b).
+ *
+ * Fails when the current branch is behind origin/main — i.e. origin/main is NOT
+ * an ancestor of HEAD — so a PR is never opened on a stale base (the recurring
+ * divergence this session hit). Advisory by default: run it in the /create-pr
+ * pre-flight or wire into CI per your branch-protection policy.
+ *
+ *   git merge-base --is-ancestor origin/main HEAD   → exit 0 = up to date
+ *
+ * Pure core (`driftVerdict`) is unit-testable without git.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import * as path from 'node:path';
+
+export type DriftInput = {
+    /** True when origin/main is an ancestor of HEAD (branch contains trunk tip). */
+    trunkIsAncestor: boolean;
+    /** Commits HEAD is behind origin/main (0 when up to date). */
+    behind: number;
+};
+
+export type DriftVerdict = { ok: boolean; message: string };
+
+/** Pure decision — no git. */
+export function driftVerdict(i: DriftInput): DriftVerdict {
+    if (i.trunkIsAncestor) {
+        return { ok: true, message: '✅  branch is up to date with origin/main' };
+    }
+    return {
+        ok: false,
+        message: `❌  branch is ${i.behind} commit(s) behind origin/main — rebase/merge before opening a PR`,
+    };
+}
+
+function _git(args: string[]): string {
+    return execFileSync('git', args, { encoding: 'utf-8' }).trim();
+}
+
+export function main(): number {
+    let input: DriftInput;
+    try {
+        _git(['fetch', 'origin', 'main', '--quiet']);
+        let isAncestor = true;
+        try {
+            execFileSync('git', ['merge-base', '--is-ancestor', 'origin/main', 'HEAD'], { stdio: 'ignore' });
+        } catch {
+            isAncestor = false;
+        }
+        const behind = Number(_git(['rev-list', '--count', 'HEAD..origin/main']) || '0');
+        input = { trunkIsAncestor: isAncestor, behind };
+    } catch (e) {
+        process.stdout.write(`⚠️  trunk-drift check skipped (no origin/main or git error): ${String(e)}\n`);
+        return 0; // advisory — never block on a missing remote
+    }
+    const v = driftVerdict(input);
+    process.stdout.write(`${v.message}\n`);
+    return v.ok ? 0 : 1;
+}
+
+const _HERE = fileURLToPath(import.meta.url);
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+    process.exit(main());
+}
+void _HERE;