@event4u/agent-config 8.9.0 → 8.11.0

package/src/scripts/consumer_matrix.ts

@@ -0,0 +1,392 @@
+#!/usr/bin/env tsx
+/**
+ * Consumer-proof release matrix — road-to-proof-under-real-conditions Phase 1.
+ *
+ * Exercises the PUBLISHED TARBALL the way a consumer does: pack → fresh
+ * global install (isolated prefix) → `init` into a fresh project → doctor →
+ * conformance → MCP stdio handshake → hook health → projection presence →
+ * uninstall. Optional upgrade leg: install the last published minor from the
+ * registry, then upgrade to the packed tarball and assert doctor stays green.
+ *
+ * Why this exists: the release-PR gate skips source-level matrices (soundly —
+ * a version-bump diff cannot regress source behaviour), but nothing between
+ * merge and tag exercised the tarball shape. Two published minors shipped
+ * without `src/install/` while published code imported from it; `tsx` was
+ * missing from the published package; each manifested only at publish time.
+ * Every leg here asserts exit code + an expected artifact, no LLM calls.
+ *
+ * Usage:
+ *   npx tsx src/scripts/consumer_matrix.ts [--tarball <path>] [--only leg1,leg2]
+ *       [--skip-registry] [--keep-tmp] [--json]
+ *
+ * Without --tarball the script runs `npm pack` itself (requires a built
+ * tree — `npm ci && npm run build` first; CI does this, local carve-out
+ * runs do it once).
+ *
+ * Exit codes: 0 all requested legs green · 1 leg failure · 2 usage/env.
+ */
+
+import { spawnSync, spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const PKG_NAME = '@event4u/agent-config';
+
+interface Ctx {
+    tmpRoot: string;
+    prefix: string; // isolated npm global prefix
+    projectDir: string; // fresh consumer project
+    tarball: string;
+    bin: string; // installed agent-config binary
+    keepTmp: boolean;
+    skipRegistry: boolean;
+    results: LegResult[];
+}
+
+interface LegResult {
+    leg: string;
+    ok: boolean;
+    detail: string;
+    durationMs: number;
+    /** fn ran to completion (a declared skip or an after-failure skip is NOT executed). */
+    executed: boolean;
+}
+
+function log(msg: string): void {
+    process.stderr.write(`${msg}\n`);
+}
+
+function run(
+    cmd: string,
+    args: string[],
+    opts: { cwd?: string; env?: NodeJS.ProcessEnv; timeoutMs?: number } = {},
+): { status: number; stdout: string; stderr: string } {
+    const r = spawnSync(cmd, args, {
+        cwd: opts.cwd ?? REPO_ROOT,
+        env: { ...process.env, ...opts.env },
+        encoding: 'utf8',
+        timeout: opts.timeoutMs ?? 600_000,
+        maxBuffer: 32 * 1024 * 1024,
+    });
+    return { status: r.status ?? 1, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
+}
+
+function fail(msg: string): never {
+    log(`❌  consumer-matrix: ${msg}`);
+    process.exit(1);
+}
+
+/**
+ * Env for running the installed binary against the isolated prefix.
+ * HOME is redirected into the tmp root so the simulation is a FRESH
+ * MACHINE even on a maintainer host: without this, an existing global
+ * install (~/.event4u, ~/.claude, …) trips the cross-scope drift guard
+ * inside `init` and the leg fails on developer machines while passing
+ * on clean CI runners — the opposite of what a consumer gate is for.
+ */
+function binEnv(ctx: Ctx): NodeJS.ProcessEnv {
+    const home = path.join(ctx.tmpRoot, 'home');
+    fs.mkdirSync(home, { recursive: true });
+    return {
+        PATH: `${path.join(ctx.prefix, 'bin')}${path.delimiter}${process.env.PATH ?? ''}`,
+        npm_config_prefix: ctx.prefix,
+        npm_config_cache: path.join(ctx.tmpRoot, 'npm-cache'),
+        HOME: home,
+        // Never let a maintainer checkout leak into the consumer simulation.
+        AGENT_CONFIG_DEV_MODE: '',
+    };
+}
+
+// ── legs ────────────────────────────────────────────────────────────
+
+function legPack(ctx: Ctx): string {
+    if (ctx.tarball) {
+        if (!fs.existsSync(ctx.tarball)) fail(`--tarball not found: ${ctx.tarball}`);
+        return `reused ${path.basename(ctx.tarball)}`;
+    }
+    const r = run('npm', ['pack', '--ignore-scripts', '--silent', '--pack-destination', ctx.tmpRoot]);
+    if (r.status !== 0) throw new Error(`npm pack failed: ${r.stderr.slice(-400)}`);
+    const name = r.stdout.trim().split('\n').pop() ?? '';
+    ctx.tarball = path.join(ctx.tmpRoot, name);
+    if (!fs.existsSync(ctx.tarball)) throw new Error(`packed tarball missing: ${ctx.tarball}`);
+    return path.basename(ctx.tarball);
+}
+
+function legFreshInstall(ctx: Ctx): string {
+    const r = run('npm', ['install', '-g', '--prefix', ctx.prefix, ctx.tarball], { timeoutMs: 900_000 });
+    if (r.status !== 0) throw new Error(`global install failed: ${r.stderr.slice(-600)}`);
+    ctx.bin = path.join(ctx.prefix, 'bin', 'agent-config');
+    if (!fs.existsSync(ctx.bin)) throw new Error(`installed binary missing at ${ctx.bin}`);
+    const v = run(ctx.bin, ['--version'], { env: binEnv(ctx) });
+    if (v.status !== 0) throw new Error(`--version failed (missing runtime dep in tarball?): ${v.stderr.slice(-400)}`);
+    return `bin ok, version ${v.stdout.trim()}`;
+}
+
+function legInit(ctx: Ctx): string {
+    fs.mkdirSync(ctx.projectDir, { recursive: true });
+    run('git', ['init', '-q', '.'], { cwd: ctx.projectDir });
+    // --scope=auto is the working headless consumer invocation. The bare
+    // default ('project default for backward compatibility') hard-fails on
+    // a fresh machine with '--scope=project is reserved for maintainers'
+    // (ADR-020) — a real trap this matrix documents; see
+    // docs/distribution/consumer-matrix.md § Headless default-scope trap.
+    const r = run(ctx.bin, ['init', '--tools=claude-code,cursor,windsurf', '--scope=auto', '--yes'], {
+        cwd: ctx.projectDir,
+        env: binEnv(ctx),
+        timeoutMs: 600_000,
+    });
+    if (r.status !== 0) throw new Error(`init failed: ${(r.stderr + r.stdout).slice(-600)}`);
+    // ADR-020: consumer installs are GLOBAL-only — assert the global trees.
+    const home = path.join(ctx.tmpRoot, 'home');
+    for (const p of ['.claude', '.cursor', '.codeium/windsurf', '.event4u']) {
+        if (!fs.existsSync(path.join(home, p))) throw new Error(`init did not write ~/${p}`);
+    }
+    return 'init --scope=auto wrote global ~/.claude, ~/.cursor, ~/.codeium/windsurf, ~/.event4u';
+}
+
+function legConformance(ctx: Ctx): string {
+    const r = run(ctx.bin, ['conformance'], { cwd: ctx.projectDir, env: binEnv(ctx) });
+    if (r.status !== 0) throw new Error(`conformance exit ${r.status}: ${(r.stdout + r.stderr).slice(-600)}`);
+    return 'conformance green (embeds doctor --ci + installed-and-firing checks)';
+}
+
+async function legMcpHandshake(ctx: Ctx): Promise<string> {
+    // Newline-delimited JSON-RPC per src/cli/mcp/stdio.ts.
+    return await new Promise<string>((resolve, reject) => {
+        const child = spawn(ctx.bin, ['mcp-server'], {
+            cwd: ctx.projectDir,
+            env: { ...process.env, ...binEnv(ctx) },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let out = '';
+        const timer = setTimeout(() => {
+            child.kill();
+            reject(new Error(`no initialize response within 20s; stdout so far: ${out.slice(0, 300)}`));
+        }, 20_000);
+        child.stdout.on('data', (d: Buffer) => {
+            out += d.toString();
+            const line = out.split('\n').find((l) => l.trim().startsWith('{'));
+            if (line) {
+                try {
+                    const msg = JSON.parse(line) as { id?: number; result?: unknown; error?: unknown };
+                    clearTimeout(timer);
+                    child.kill();
+                    if (msg.id === 1 && msg.result && !msg.error) {
+                        resolve('initialize handshake ok');
+                    } else {
+                        reject(new Error(`unexpected first message: ${line.slice(0, 300)}`));
+                    }
+                } catch {
+                    /* partial line — keep buffering */
+                }
+            }
+        });
+        child.on('error', (e) => {
+            clearTimeout(timer);
+            reject(e);
+        });
+        child.on('exit', (code) => {
+            if (out === '') {
+                clearTimeout(timer);
+                reject(new Error(`mcp-server exited (${code}) before responding`));
+            }
+        });
+        child.stdin.write(
+            `${JSON.stringify({
+                jsonrpc: '2.0',
+                id: 1,
+                method: 'initialize',
+                params: {
+                    protocolVersion: '2025-03-26',
+                    capabilities: {},
+                    clientInfo: { name: 'consumer-matrix', version: '0' },
+                },
+            })}\n`,
+        );
+    });
+}
+
+function legHooks(ctx: Ctx): string {
+    const r = run(ctx.bin, ['hooks:doctor'], { cwd: ctx.projectDir, env: binEnv(ctx) });
+    if (r.status !== 0) throw new Error(`hooks:doctor exit ${r.status}: ${(r.stdout + r.stderr).slice(-600)}`);
+    return 'hooks:doctor green';
+}
+
+function legProjections(ctx: Ctx): string {
+    const home = path.join(ctx.tmpRoot, 'home');
+    const missing = ['.cursor/rules', '.codeium/windsurf', '.claude/skills']
+        .filter((p) => !fs.existsSync(path.join(home, p)))
+        .join(', ');
+    if (missing) throw new Error(`global projection trees missing: ${missing}`);
+    return 'cursor + windsurf + claude projection trees present in global scope';
+}
+
+function legUninstall(ctx: Ctx): string {
+    const r = run(ctx.bin, ['uninstall', '--global', '--tools=claude-code,cursor,windsurf', '--force'], {
+        cwd: ctx.projectDir,
+        env: binEnv(ctx),
+    });
+    if (r.status !== 0) throw new Error(`uninstall exit ${r.status}: ${(r.stdout + r.stderr).slice(-600)}`);
+    const lock = path.join(ctx.tmpRoot, 'home', '.event4u', 'agent-config', 'installed.lock');
+    if (fs.existsSync(lock)) throw new Error(`global lockfile still present after uninstall: ${lock}`);
+    return 'uninstall --global green, lockfile removed';
+}
+
+function legUpgrade(ctx: Ctx): string {
+    if (ctx.skipRegistry) return 'skipped (--skip-registry)';
+    // Last published version from the registry (network).
+    const view = run('npm', ['view', PKG_NAME, 'version'], { timeoutMs: 120_000 });
+    if (view.status !== 0) throw new Error(`npm view failed: ${view.stderr.slice(-300)}`);
+    const published = view.stdout.trim();
+    const upPrefix = path.join(ctx.tmpRoot, 'prefix-upgrade');
+    const upProject = path.join(ctx.tmpRoot, 'project-upgrade');
+    fs.mkdirSync(upProject, { recursive: true });
+    const upHome = path.join(ctx.tmpRoot, 'home-upgrade');
+    fs.mkdirSync(upHome, { recursive: true });
+    const env = {
+        PATH: `${path.join(upPrefix, 'bin')}${path.delimiter}${process.env.PATH ?? ''}`,
+        npm_config_prefix: upPrefix,
+        npm_config_cache: path.join(ctx.tmpRoot, 'npm-cache'),
+        HOME: upHome,
+        AGENT_CONFIG_DEV_MODE: '',
+    };
+    let r = run('npm', ['install', '-g', '--prefix', upPrefix, `${PKG_NAME}@${published}`], { timeoutMs: 900_000 });
+    if (r.status !== 0) throw new Error(`registry install of ${published} failed: ${r.stderr.slice(-400)}`);
+    const bin = path.join(upPrefix, 'bin', 'agent-config');
+    r = run(bin, ['init', '--tools=claude-code', '--scope=auto', '--yes'], { cwd: upProject, env, timeoutMs: 600_000 });
+    if (r.status !== 0) throw new Error(`init on ${published} failed: ${(r.stderr + r.stdout).slice(-400)}`);
+    // Upgrade: overwrite the global install with the packed tarball.
+    r = run('npm', ['install', '-g', '--prefix', upPrefix, ctx.tarball], { timeoutMs: 900_000 });
+    if (r.status !== 0) throw new Error(`tarball upgrade failed: ${r.stderr.slice(-400)}`);
+    r = run(bin, ['conformance'], { cwd: upProject, env });
+    if (r.status !== 0) {
+        throw new Error(`conformance red after ${published} → tarball upgrade: ${(r.stdout + r.stderr).slice(-600)}`);
+    }
+    return `upgrade ${published} → packed tarball, conformance green`;
+}
+
+// ── main ────────────────────────────────────────────────────────────
+
+const LEGS: Array<{ name: string; fn: (ctx: Ctx) => string | Promise<string> }> = [
+    { name: 'pack', fn: legPack },
+    { name: 'fresh-install', fn: legFreshInstall },
+    { name: 'init', fn: legInit },
+    { name: 'conformance', fn: legConformance },
+    { name: 'mcp-handshake', fn: legMcpHandshake },
+    { name: 'hooks', fn: legHooks },
+    { name: 'projections', fn: legProjections },
+    { name: 'uninstall', fn: legUninstall },
+    { name: 'upgrade', fn: legUpgrade },
+];
+
+async function main(): Promise<number> {
+    const argv = process.argv.slice(2);
+    const getOpt = (flag: string): string | undefined => {
+        const i = argv.indexOf(flag);
+        return i >= 0 ? argv[i + 1] : undefined;
+    };
+    const only = getOpt('--only')?.split(',').map((s) => s.trim());
+    const unknownLeg = only?.find((l) => !LEGS.some((x) => x.name === l));
+    if (unknownLeg) {
+        log(`❌  unknown leg '${unknownLeg}'. Legs: ${LEGS.map((l) => l.name).join(', ')}`);
+        return 2;
+    }
+
+    const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'consumer-matrix-'));
+    const ctx: Ctx = {
+        tmpRoot,
+        prefix: path.join(tmpRoot, 'prefix'),
+        projectDir: path.join(tmpRoot, 'project'),
+        tarball: getOpt('--tarball') ?? '',
+        bin: '',
+        keepTmp: argv.includes('--keep-tmp'),
+        skipRegistry: argv.includes('--skip-registry'),
+        results: [],
+    };
+    fs.mkdirSync(ctx.prefix, { recursive: true });
+    log(`consumer-matrix · tmp ${tmpRoot} · node ${process.version}`);
+
+    let failed = false;
+    for (const leg of LEGS) {
+        if (only && !only.includes(leg.name)) continue;
+        // Legs after a hard dependency failure cannot run meaningfully.
+        if (failed) {
+            ctx.results.push({
+                leg: leg.name,
+                ok: false,
+                detail: 'skipped (earlier leg failed)',
+                durationMs: 0,
+                executed: false,
+            });
+            continue;
+        }
+        const t0 = Date.now();
+        try {
+            const detail = await leg.fn(ctx);
+            const executed = !detail.startsWith('skipped');
+            ctx.results.push({ leg: leg.name, ok: true, detail, durationMs: Date.now() - t0, executed });
+            log(`  ✅  ${leg.name} — ${detail}`);
+        } catch (err) {
+            ctx.results.push({
+                leg: leg.name,
+                ok: false,
+                detail: (err as Error).message,
+                durationMs: Date.now() - t0,
+                executed: true,
+            });
+            log(`  ❌  ${leg.name} — ${(err as Error).message}`);
+            failed = true;
+        }
+    }
+
+    // Leg-completeness gate (road-to-fable-feedback-5 Phase 6a): a full run
+    // (no --only) must have EXECUTED every expected leg — a silently-skipped
+    // leg can no longer ride a green workflow. The only declared skip is
+    // `upgrade` under an explicit --skip-registry flag.
+    if (!only && !failed) {
+        const declaredSkips = new Set(ctx.skipRegistry ? ['upgrade'] : []);
+        const missing = LEGS.filter((l) => {
+            const r = ctx.results.find((x) => x.leg === l.name);
+            return r === undefined || (!r.executed && !declaredSkips.has(l.name));
+        }).map((l) => l.name);
+        if (missing.length > 0) {
+            log(`❌  leg-completeness gate: expected leg(s) did not execute: ${missing.join(', ')}`);
+            failed = true;
+        }
+    }
+
+    const manifestPath = getOpt('--manifest');
+    if (manifestPath) {
+        const manifest = {
+            ok: !failed,
+            node: process.version,
+            skipRegistry: ctx.skipRegistry,
+            expected: LEGS.map((l) => l.name),
+            results: ctx.results,
+        };
+        fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+        log(`leg manifest written: ${manifestPath}`);
+    }
+
+    if (argv.includes('--json')) {
+        process.stdout.write(`${JSON.stringify({ ok: !failed, results: ctx.results }, null, 2)}\n`);
+    }
+    if (!ctx.keepTmp) {
+        fs.rmSync(tmpRoot, { recursive: true, force: true });
+    } else {
+        log(`kept tmp: ${tmpRoot}`);
+    }
+    return failed ? 1 : 0;
+}
+
+main().then(
+    (code) => process.exit(code),
+    (err) => {
+        log(`❌  consumer-matrix crashed: ${(err as Error).stack ?? err}`);
+        process.exit(2);
+    },
+);

package/src/scripts/council_cli.ts

@@ -24,6 +24,9 @@ import {
     bundle_prompt,
     bundle_roadmap,
 } from './ai_council/bundler.js';
+import { select_chairman } from './ai_council/chairman.js';
+import type { ChairmanCandidate } from './ai_council/chairman.js';
+import { synthesis_template } from './ai_council/prompts.js';
 import type {
     ExternalAIClient} from './ai_council/clients.js';
 import {
@@ -873,6 +876,8 @@ function format_estimate_table(
         consensus_extra_calls?: number;
         peer_review_delta_usd?: number;
         peer_review_extra_calls?: number;
+        chairman_delta_usd?: number;
+        chairman_extra_calls?: number;
     } = {},
 ): string {
     const consensus_delta_usd = opts.consensus_delta_usd ?? 0.0;
@@ -904,6 +909,12 @@ function format_estimate_table(
         );
         total += peer_review_delta_usd;
     }
+    if ((opts.chairman_extra_calls ?? 0) > 0) {
+        rows.push(
+            `  +chairman synthesis: +${opts.chairman_extra_calls} call (~+$${_pyFixed(opts.chairman_delta_usd ?? 0, 4)})`,
+        );
+        total += opts.chairman_delta_usd ?? 0;
+    }
     rows.push(`  TOTAL:  $${_pyFixed(total, 4)}`);
     return rows.join('\n');
 }
@@ -1054,6 +1065,21 @@ function _peer_review_active(ai_cfg: Dict, args: Args): boolean {
     return Boolean(_pyBool(pr_cfg['enabled']));
 }
 
+/** Chairman synthesis delta — one extra call when chairman.mode != host. */
+function _chairman_cost_delta(
+    ai_cfg: Dict,
+    estimates: CostEstimateLike[],
+): [number, number] {
+    const ch = (_isDict(ai_cfg) ? (ai_cfg['chairman'] as Dict) : null) || {};
+    const mode = typeof ch['mode'] === 'string' ? (ch['mode'] as string) : 'host';
+    if (mode === 'host' || estimates.length === 0) {
+        return [0, 0.0];
+    }
+    // Worst-case single call: the most expensive member estimate.
+    const maxUsd = Math.max(...estimates.map((e) => _total_usd(e)));
+    return [1, maxUsd];
+}
+
 function _peer_review_cost_delta(
     ai_cfg: Dict,
     args: Args,
@@ -1071,6 +1097,94 @@ function _peer_review_cost_delta(
     return [extra_calls, extra_usd];
 }
 
+
+interface ChairmanResult {
+    member: string | null;
+    annotation: string;
+    text: string | null;
+    response: CouncilResponse | null;
+}
+
+/** Phase 2 chairman dispatch — optional extra billable pass after consult.
+ *  Gated on `ai_council.chairman.mode != host`; selection per the 2026-07-12
+ *  council decision (provider-difference primary, tier tie-break) via
+ *  `select_chairman`; the synthesis call reuses consult([client]) so the
+ *  projected-spend gate, ledger, and metadata stamping apply unchanged.
+ *  Never a silent substitution: fallbacks carry a visible annotation. */
+function _maybe_run_chairman(
+    ai_cfg: Dict,
+    question: CouncilQuestion,
+    members: ExternalAIClient[],
+    responses: CouncilResponse[],
+    budget: CostBudget,
+    table: PriceTable,
+    project: unknown,
+    args: Args,
+): ChairmanResult | null {
+    const ch = (_isDict(ai_cfg) ? (ai_cfg['chairman'] as Dict) : null) || {};
+    const mode = typeof ch['mode'] === 'string' ? (ch['mode'] as string) : 'host';
+    if (mode === 'host') {
+        return null;
+    }
+    const cfg_member = typeof ch['member'] === 'string' ? (ch['member'] as string) : null;
+    const membersRaw = (_isDict(ai_cfg) ? (ai_cfg['members'] as Dict) : null) || {};
+    const candidates: ChairmanCandidate[] = [];
+    for (const [name, raw] of Object.entries(membersRaw)) {
+        const md = (raw as Dict) || {};
+        if (md['enabled'] !== true) continue;
+        candidates.push({
+            name,
+            tier: typeof md['tier'] === 'number' ? (md['tier'] as number) : null,
+        });
+    }
+    const deliberated = new Set(
+        responses.filter((r) => r.error === null && r.text.trim() !== '').map((r) => r.provider),
+    );
+    const sel = select_chairman(mode, cfg_member, deliberated, candidates);
+    if (sel.member === null) {
+        return { member: null, annotation: sel.annotation, text: null, response: null };
+    }
+    const client = members.find((m) => m.name === sel.member);
+    if (client === undefined) {
+        return {
+            member: null,
+            annotation: `Chairman: host (member '${sel.member}' has no constructed client — host fallback)`,
+            text: null,
+            response: null,
+        };
+    }
+    // Transcript WITH identities (the chairman judges attributed positions) +
+    // the lens synthesis template as the authoring instruction.
+    const transcript = responses
+        .filter((r) => r.error === null && r.text.trim() !== '')
+        .map((r) => `## ${r.provider} - ${r.model}\n\n${r.text.trim()}`)
+        .join('\n\n---\n\n');
+    const synth_prompt =
+        `You are the council CHAIRMAN. You did not deliberate. Author the synthesis ` +
+        `of the attributed member positions below, following the template.\n\n` +
+        `${synthesis_template(question.mode)}\n\n---\n\n${transcript}`;
+    const synthQ = new CouncilQuestion({
+        mode: question.mode,
+        user_prompt: synth_prompt,
+        max_tokens: question.max_tokens,
+    });
+    const out = consult([client], synthQ, budget, {
+        table,
+        project: project as never,
+        original_ask: args.original_ask,
+    });
+    const r = out[0] ?? null;
+    if (r === null || r.error !== null || r.text.trim() === '') {
+        return {
+            member: null,
+            annotation: `Chairman: ${sel.member} (FAILED - host fallback)`,
+            text: null,
+            response: r,
+        };
+    }
+    return { member: sel.member, annotation: sel.annotation, text: r.text, response: r };
+}
+
 function _maybe_run_peer_review(
     ai_cfg: Dict,
     args: Args,
@@ -1204,6 +1318,7 @@ function cmd_estimate(
         return _emit_debate_estimate(args, ai_cfg, members, billable, estimates, advisor_plans, { skipped });
     }
     const [extra_calls, extra_usd] = _consensus_cost_delta(ai_cfg, question.mode, estimates, billable.length);
+    const [ch_calls, ch_usd] = _chairman_cost_delta(ai_cfg, estimates);
     const [pr_extra_calls, pr_extra_usd] = _peer_review_cost_delta(ai_cfg, args, estimates, billable.length);
     _stdout(
         `council:estimate · mode=${question.mode} · members=${members.length} ` +
@@ -1222,6 +1337,8 @@ function cmd_estimate(
             consensus_extra_calls: extra_calls,
             peer_review_delta_usd: pr_extra_usd,
             peer_review_extra_calls: pr_extra_calls,
+            chairman_delta_usd: ch_usd,
+            chairman_extra_calls: ch_calls,
         }) + '\n',
     );
     return 0;
@@ -1720,6 +1837,7 @@ function cmd_run(
         advisor_plans,
     });
     const [extra_calls, extra_usd] = _consensus_cost_delta(ai_cfg, question.mode, estimates, billable.length);
+    const [ch_calls, ch_usd] = _chairman_cost_delta(ai_cfg, estimates);
     const [pr_extra_calls, pr_extra_usd] = _peer_review_cost_delta(ai_cfg, args, estimates, billable.length);
     _stdout(
         `council:run · mode=${question.mode} · members=${members.length} ` +
@@ -1738,6 +1856,8 @@ function cmd_run(
             consensus_extra_calls: extra_calls,
             peer_review_delta_usd: pr_extra_usd,
             peer_review_extra_calls: pr_extra_calls,
+            chairman_delta_usd: ch_usd,
+            chairman_extra_calls: ch_calls,
         }) + '\n',
     );
 
@@ -1781,12 +1901,18 @@ function cmd_run(
         max_total_usd: _pyFloat(cost_cfg['max_total_usd'] ?? 0.0, 0.0) || 0.0,
     });
     const rounds = _resolve_rounds(args, ai_cfg);
+    // Phase 1: stance tally — defensive read; malformed/absent block reads as off.
+    const stance_tally_on =
+        _isDict(ai_cfg) &&
+        _isDict(ai_cfg['stance_tally']) &&
+        (ai_cfg['stance_tally'] as Dict)['enabled'] === true;
     const responses = consult(members, question, budget, {
         table,
         project,
         original_ask: args.original_ask,
         rounds,
         advisor_plans,
+        stance_tally: stance_tally_on,
     });
     const persona_labels = build_persona_labels(advisor_plans, billable);
     const peer_review = _maybe_run_peer_review(
@@ -1801,6 +1927,7 @@ function cmd_run(
         { persona_labels },
     );
     const consensus = _maybe_run_consensus(ai_cfg, question, members, responses, budget, table, project, args);
+    const chairman = _maybe_run_chairman(ai_cfg, question, members, responses, budget, table, project, args);
     const estimated_total = estimates.reduce((acc, e) => acc + _total_usd(e), 0.0);
     let actual_total = 0.0;
     const all_responses: CouncilResponse[] = [...responses];
@@ -1811,6 +1938,9 @@ function cmd_run(
         all_responses.push(...consensus.extraction_responses);
         all_responses.push(...consensus.scoring_responses);
     }
+    if (chairman !== null && chairman.response !== null) {
+        all_responses.push(chairman.response);
+    }
     for (const r of all_responses) {
         if (r.error) {
             continue;
@@ -1830,6 +1960,7 @@ function cmd_run(
         rounds,
         cost_usd_estimated: _pyRound(estimated_total, 6),
         cost_usd_actual: _pyRound(actual_total, 6),
+        stance_tally: stance_tally_on,
         responses: _serialise_responses(responses),
     };
     if (peer_review !== null) {
@@ -1838,6 +1969,9 @@ function cmd_run(
     if (consensus !== null) {
         payload['consensus'] = _serialise_consensus(consensus);
     }
+    if (chairman !== null) {
+        payload['chairman'] = { member: chairman.member, annotation: chairman.annotation, text: chairman.text };
+    }
     const out_path = _validate_council_output_path(args.output as string, {
         kind: 'responses',
         subcommand: 'run',
@@ -2129,6 +2263,14 @@ function cmd_debate(
         auto_continue: Boolean(_getattr(args, 'auto_continue', false)),
     });
 
+    // Phase 3: debate gates (anti-conformity directive on round 2+). Read
+    // defensively from the raw ai_council block — a malformed/absent
+    // `debate_gates` reads as off, keeping the debate prompt byte-identical.
+    const debate_gates_on =
+        _isDict(ai_cfg) &&
+        _isDict(ai_cfg['debate_gates']) &&
+        (ai_cfg['debate_gates'] as Dict)['enabled'] === true;
+
     let all_rounds: CouncilResponse[][];
     try {
         all_rounds = run_debate(members, question, {
@@ -2139,6 +2281,7 @@ function cmd_debate(
             max_rounds: rounds,
             on_round_complete: _on_round_complete,
             on_continue,
+            debate_gates: debate_gates_on,
             advisor_plans,
             seed_round_1: seed,
         });
@@ -2190,6 +2333,10 @@ function cmd_render(args: Args): number {
         prose_synthesis: prose,
         consensus,
         peer_review,
+        stance_tally: payload['stance_tally'] === true,
+        chairman: _isDict(payload['chairman'])
+            ? (payload['chairman'] as { member: string | null; annotation: string; text: string | null })
+            : null,
     });
     if (_getattr<string | null>(args, 'output', null)) {
         const out_path = _validate_council_output_path(args.output as string, {