@event4u/agent-config 8.11.0 → 8.13.0

package/src/scripts/ai_council/orchestrator.ts

@@ -65,7 +65,8 @@ import {
     synthesis_template,
     system_prompt_for,
 } from './prompts.js';
-import { render_vote_tally, tally_stances } from './stance_tally.js';
+import { count_dissenters, dissent_quota_met, is_near_duplicate } from './debate_gates.js';
+import { parse_stance_line, render_vote_tally, tally_stances } from './stance_tally.js';
 
 // ── Python-format / stdlib parity helpers ────────────────────────────────
 //
@@ -419,6 +420,14 @@ export interface ConsultOptions {
      * round's prompt is byte-identical to today.
      */
     stance_tally?: boolean;
+    /**
+     * Phase 1 stance-repair transport (2026-07-12 council policy): confirm per
+     * member in interactive runs; `null`/absent → a missing/unparseable stance
+     * stays a repair-marker in the tally, never an unplanned billable call.
+     */
+    on_stance_repair?: ((member: string) => boolean) | null;
+    /** Receives each stance-repair response so the caller can account its cost. */
+    on_stance_repair_result?: ((r: CouncilResponse) => void) | null;
 }
 
 /**
@@ -515,6 +524,46 @@ export function consult(
         }
     }
 
+    // Phase 1 stance repair: one bounded stance-line-only re-prompt per member
+    // whose final reply lacks a parseable STANCE line — dispatched only through
+    // the on_stance_repair transport, reusing _run_round (spend gate + ledger +
+    // stamping unchanged). The repaired stance line is APPENDED to the member's
+    // final text so the deterministic tally can read it.
+    const on_stance_repair = opts.on_stance_repair ?? null;
+    if (stance_tally && on_stance_repair !== null) {
+        for (let i = 0; i < last_results.length; i++) {
+            const r = last_results[i] as CouncilResponse;
+            if (r.error !== null || r.text.trim() === '' || parse_stance_line(r.text) !== null) {
+                continue;
+            }
+            const member = members[i];
+            if (member === undefined || !on_stance_repair(member.name)) {
+                continue;
+            }
+            const repairQ = new CouncilQuestion({
+                mode: question.mode,
+                user_prompt:
+                    `Your reply is missing the mandatory closing stance line. ` +
+                    `Reply with ONLY that single line for your final position.\n\n${STANCE_LINE_CONTRACT}`,
+                max_tokens: question.max_tokens,
+            });
+            const rr = _run_round([member], repairQ, resolvedBudget, spent, {
+                table,
+                on_overrun,
+                project,
+                original_ask,
+                advisor_plans,
+            });
+            const rep = rr[0];
+            if (rep !== undefined) {
+                opts.on_stance_repair_result?.(rep);
+                if (rep.error === null && parse_stance_line(rep.text) !== null) {
+                    r.text = `${r.text.trim()}\n\n${rep.text.trim()}`;
+                }
+            }
+        }
+    }
+
     return last_results;
 }
 
@@ -895,6 +944,90 @@ function _augment_for_debate_round(
     );
 }
 
+/**
+ * Phase 3 post-round enforcement (2026-07-12 council policy): deterministic
+ * detectors flag members whose round added nothing (novelty near-duplicate of
+ * their own prior round) or when the round collapsed toward agreement (dissent
+ * quota unmet → the most-recently-converged member). At most ONE bounded repair
+ * re-prompt per member per round, dispatched only through the `on_repair`
+ * transport (confirm-interactive / auto-fire under --auto-continue); the repair
+ * call reuses `_run_round`, so the projected-spend gate, ledger, and metadata
+ * stamping apply unchanged. A successful repair REPLACES the member's entry so
+ * downstream rounds/persistence see the repaired reply.
+ */
+function _run_debate_gate_repairs(
+    members: ExternalAIClient[],
+    results: CouncilResponse[],
+    prior: CouncilResponse[],
+    round_question: CouncilQuestion,
+    budget: CostBudget,
+    spent: Spent,
+    round_opts: {
+        table: PriceTable | null;
+        on_overrun: OnOverrunCallback | null;
+        project: ProjectContext | null;
+        original_ask: string;
+        advisor_plans: Map<string, AdvisorPlan> | null;
+    },
+    on_repair: ((member: string, reason: string) => boolean) | null,
+): CouncilResponse[] {
+    const flagged: Array<{ idx: number; reason: string }> = [];
+    const okText = (r: CouncilResponse | undefined): string =>
+        r !== undefined && r.error === null ? r.text : '';
+    for (let i = 0; i < results.length; i++) {
+        const curr = okText(results[i]);
+        const prev = okText(prior[i]);
+        if (curr !== '' && prev !== '' && is_near_duplicate(prev, curr)) {
+            flagged.push({ idx: i, reason: 'novelty: near-duplicate of your own prior round' });
+        }
+    }
+    const texts = results.map((r) => okText(r));
+    if (!dissent_quota_met(texts.filter((t) => t !== ''))) {
+        // Most-recently-converged heuristic: the LAST member with a real reply
+        // that carries no objection marker.
+        for (let i = results.length - 1; i >= 0; i--) {
+            const t = okText(results[i]);
+            if (t !== '' && count_dissenters([t]) === 0 && !flagged.some((f) => f.idx === i)) {
+                flagged.push({ idx: i, reason: 'dissent quota unmet: state a genuine objection or confirm with a named reason' });
+                break;
+            }
+        }
+    }
+    if (flagged.length === 0 || on_repair === null) {
+        return results;
+    }
+    const repaired = new Set<number>();
+    const out = [...results];
+    for (const f of flagged) {
+        if (repaired.has(f.idx)) {
+            continue; // hard cap: <= 1 repair per member per round
+        }
+        const member = members[f.idx];
+        if (member === undefined) {
+            continue;
+        }
+        if (!on_repair(member.name, f.reason)) {
+            continue;
+        }
+        repaired.add(f.idx);
+        const repairQ = new CouncilQuestion({
+            mode: round_question.mode,
+            user_prompt:
+                `${round_question.user_prompt}\n\n---\n\n` +
+                `REPAIR RE-PROMPT (${f.reason}). Your previous reply this round did not ` +
+                `advance the debate. Respond again: either a genuinely updated position ` +
+                `naming the specific flaw that moved you, or an explicit defense with NEW evidence.`,
+            max_tokens: round_question.max_tokens,
+        });
+        const rr = _run_round([member], repairQ, budget, spent, round_opts);
+        const r0 = rr[0];
+        if (r0 !== undefined && r0.error === null && r0.text.trim() !== '') {
+            out[f.idx] = r0;
+        }
+    }
+    return out;
+}
+
 export interface RunDebateOptions {
     budget?: CostBudget | null;
     table?: PriceTable | null;
@@ -914,6 +1047,22 @@ export interface RunDebateOptions {
      * prompt is byte-identical to today.
      */
     debate_gates?: boolean;
+    /**
+     * Phase 3 repair transport, per the 2026-07-12 council policy
+     * (`debate_gates.repair_action`): the CLI passes `() => true` under
+     * `--auto-continue` (auto-fire under the cap) or an interactive one-line
+     * confirm otherwise. `null`/absent → gates detect but never dispatch
+     * (no unplanned spend without an explicit transport).
+     */
+    on_repair?: ((member: string, reason: string) => boolean) | null;
+    /**
+     * Phase 3 restate pass (`ai_council.restate.enabled` / `--restate`): a
+     * pre-round-1 billable call per member collecting a <=50-word restatement
+     * + one alternative framing. Default off -> no extra calls, byte-identical.
+     */
+    restate?: boolean;
+    /** Receives the restate responses (rendering, divergence flags, cost). */
+    on_restate?: ((responses: CouncilResponse[]) => void) | null;
 }
 
 /**
@@ -975,6 +1124,27 @@ export function run_debate(
     const all_rounds: CouncilResponse[][] = [];
     let current_user_prompt = question.user_prompt;
 
+    // Phase 3 restate: one pre-round-1 call per member. Runs BEFORE any debate
+    // spend so a diverging restatement can be flagged before round-2 cost.
+    if (opts.restate === true) {
+        const restateQ = new CouncilQuestion({
+            mode: question.mode,
+            user_prompt:
+                `Before the debate begins: RESTATE the question below in at most 50 words, ` +
+                `then offer ONE alternative framing of it. Do not argue a position yet.\n\n---\n\n` +
+                `${question.user_prompt}`,
+            max_tokens: question.max_tokens,
+        });
+        const restated = _run_round(members, restateQ, budget, spent, {
+            table,
+            on_overrun,
+            project,
+            original_ask,
+            advisor_plans,
+        });
+        opts.on_restate?.(restated);
+    }
+
     for (let round_idx = 0; round_idx < max_rounds; round_idx++) {
         const round_number = round_idx + 1;
         let results: CouncilResponse[];
@@ -1000,6 +1170,23 @@ export function run_debate(
             });
         }
 
+        if (opts.debate_gates === true && round_idx > 0 && all_rounds.length > 0) {
+            results = _run_debate_gate_repairs(
+                members,
+                results,
+                all_rounds[all_rounds.length - 1] as CouncilResponse[],
+                // round_idx > 0 here, so current_user_prompt IS this round's prompt.
+                new CouncilQuestion({
+                    mode: question.mode,
+                    user_prompt: current_user_prompt,
+                    max_tokens: question.max_tokens,
+                }),
+                budget,
+                spent,
+                { table, on_overrun, project, original_ask, advisor_plans },
+                opts.on_repair ?? null,
+            );
+        }
         all_rounds.push(results);
         if (on_round_complete !== null) {
             on_round_complete(round_number, results);

package/src/scripts/ai_team/config.ts

@@ -0,0 +1,162 @@
+/**
+ * ai_team configuration loader — single source of truth for the `/team`
+ * cross-model review family.
+ *
+ * Mirrors the fail-closed validation posture of the council loader
+ * (`src/scripts/ai_council/config.ts`) at a fraction of its surface: the
+ * `ai_team` block has five flat keys and no nested sub-schemas, so this
+ * loader is deliberately lean — defaults, per-key type checks, and hard
+ * unknown-key rejection. Contract: `docs/contracts/ai-team-config.md`.
+ *
+ * Unlike the council (ALWAYS user-global `.ai-council.yml`, ADR-104),
+ * `ai_team` lives in the PROJECT settings cascade (`.agent-settings.yml`
+ * via `load_agent_settings`) — team mode is a per-project posture
+ * (default-off), not a per-developer credential store; the codex CLI
+ * carries the subscription auth itself.
+ *
+ * Validation contract (all enforced at load time, fail-closed):
+ *
+ * 1. `ai_team` absent → defaults (feature off). Non-mapping → error.
+ * 2. Unknown keys under `ai_team` are rejected — a typo must never
+ *    silently disable a gate (`allow_delegate` misspelled = delegation
+ *    stays off AND the load fails loudly).
+ * 3. `enabled`, `allow_delegate`, `suppress_setup_hint` are booleans.
+ * 4. `model` is a non-empty string. `'auto'` = pass no `--model` flag
+ *    (the codex CLI default applies); any other value passes through
+ *    verbatim.
+ * 5. `max_calls_per_day` is a non-negative integer (bools rejected).
+ */
+import { load_agent_settings, type SettingsDict } from '../_lib/agent_settings.js';
+
+/** Raised when the `ai_team` block of `.agent-settings.yml` violates the schema. */
+export class TeamConfigError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'TeamConfigError';
+    }
+}
+
+export interface AiTeamConfig {
+    readonly enabled: boolean;
+    readonly model: string;
+    readonly allow_delegate: boolean;
+    readonly max_calls_per_day: number;
+    readonly suppress_setup_hint: boolean;
+}
+
+/** Shipped defaults — byte-parity with `src/config/agent-settings.template.yml`. */
+export const AI_TEAM_DEFAULTS: AiTeamConfig = Object.freeze({
+    enabled: false,
+    model: 'auto',
+    allow_delegate: false,
+    max_calls_per_day: 50,
+    suppress_setup_hint: false,
+});
+
+/**
+ * Sentinel: `model: 'auto'` means "pass NO --model flag" so the codex
+ * CLI's own default applies (tracks the subscription's strongest model
+ * instead of pinning a stale ID).
+ */
+export const AI_TEAM_MODEL_AUTO = 'auto';
+
+const _KNOWN_KEYS: ReadonlySet<string> = new Set([
+    'enabled',
+    'model',
+    'allow_delegate',
+    'max_calls_per_day',
+    'suppress_setup_hint',
+]);
+
+function _isDict(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function _isBool(value: unknown): value is boolean {
+    return typeof value === 'boolean';
+}
+
+function _requireBool(raw: Record<string, unknown>, key: string, fallback: boolean): boolean {
+    if (!(key in raw)) {
+        return fallback;
+    }
+    const value = raw[key];
+    if (!_isBool(value)) {
+        throw new TeamConfigError(
+            `\`ai_team.${key}\` must be a boolean (got ${JSON.stringify(value)}).`,
+        );
+    }
+    return value;
+}
+
+/**
+ * Validate a raw `ai_team` mapping and return the typed config.
+ *
+ * `raw = null | undefined` (block absent) returns the defaults — the
+ * feature is off, never an error. Every other shape is validated
+ * fail-closed per the module contract above.
+ */
+export function build_ai_team_config(raw: unknown): AiTeamConfig {
+    if (raw === null || raw === undefined) {
+        return AI_TEAM_DEFAULTS;
+    }
+    if (!_isDict(raw)) {
+        throw new TeamConfigError('`ai_team` must be a mapping.');
+    }
+
+    for (const key of Object.keys(raw)) {
+        if (!_KNOWN_KEYS.has(key)) {
+            throw new TeamConfigError(
+                `ai_team.${key}: unknown key; valid: ` +
+                    `[${[..._KNOWN_KEYS].map((k) => `'${k}'`).join(', ')}].`,
+            );
+        }
+    }
+
+    const enabled = _requireBool(raw, 'enabled', AI_TEAM_DEFAULTS.enabled);
+    const allow_delegate = _requireBool(raw, 'allow_delegate', AI_TEAM_DEFAULTS.allow_delegate);
+    const suppress_setup_hint = _requireBool(
+        raw,
+        'suppress_setup_hint',
+        AI_TEAM_DEFAULTS.suppress_setup_hint,
+    );
+
+    let model = AI_TEAM_DEFAULTS.model;
+    if ('model' in raw) {
+        const value = raw['model'];
+        if (typeof value !== 'string' || value.trim() === '') {
+            throw new TeamConfigError(
+                `\`ai_team.model\` must be a non-empty string (got ${JSON.stringify(value)}).`,
+            );
+        }
+        model = value;
+    }
+
+    let max_calls_per_day = AI_TEAM_DEFAULTS.max_calls_per_day;
+    if ('max_calls_per_day' in raw) {
+        const value = raw['max_calls_per_day'];
+        if (_isBool(value) || typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+            throw new TeamConfigError(
+                '`ai_team.max_calls_per_day` must be a non-negative integer ' +
+                    `(got ${JSON.stringify(value)}).`,
+            );
+        }
+        max_calls_per_day = value;
+    }
+
+    return { enabled, model, allow_delegate, max_calls_per_day, suppress_setup_hint };
+}
+
+/**
+ * Load the `ai_team` config from the merged project settings cascade.
+ *
+ * `opts.settings` injects a pre-merged settings dict (test seam — no
+ * filesystem access); otherwise `load_agent_settings` walks the normal
+ * `.agent-settings.yml` cascade from `opts.cwd` (default: process cwd).
+ */
+export function load_ai_team_config(
+    opts: { settings?: SettingsDict | null; cwd?: string | null } = {},
+): AiTeamConfig {
+    const settings = opts.settings ?? load_agent_settings({ cwd: opts.cwd ?? process.cwd() });
+    return build_ai_team_config((settings as Record<string, unknown>)['ai_team']);
+}