code-ai-installer 3.0.0 → 4.0.0

package/dist/mcp/server.js

@@ -0,0 +1,33 @@
+import { TOOL_REGISTRY } from "../shared/index.js";
+import { DEFAULT_HANDLERS } from "./tools/stubs.js";
+/**
+ * Minimal MCP-style dispatch surface.
+ *
+ * Real wiring (stdio / WS / Claude Code transport) lands in pre-req #3.
+ * This class exists so callers can hold a typed dispatcher today.
+ */
+export class CodeAiMcpServer {
+    handlers;
+    constructor(overrides = {}) {
+        this.handlers = { ...DEFAULT_HANDLERS, ...overrides };
+    }
+    /** Replace a single handler — used by prototype to ship one tool at a time. */
+    setHandler(name, handler) {
+        this.handlers[name] =
+            handler;
+    }
+    /**
+     * Dispatch by tool name. Input is validated against the contract; output is
+     * also validated before return so a buggy handler can't ship malformed data.
+     */
+    async call(name, rawInput) {
+        const { input, output } = TOOL_REGISTRY[name];
+        const parsedInput = input.parse(rawInput);
+        const result = await this.handlers[name](parsedInput);
+        return output.parse(result);
+    }
+    /** List every tool name registered in the contracts. */
+    listTools() {
+        return Object.keys(TOOL_REGISTRY);
+    }
+}

package/dist/mcp/stores/index.d.ts

@@ -0,0 +1,15 @@
+import type { DecisionStore } from "../decision_store.js";
+/**
+ * Factory — picks the decision store backend based on `.code-ai/config.json`.
+ *
+ * Safe default: `JsonlStore` (no external deps). Selecting `mempalace` wraps
+ * JsonlStore in MempalaceStore for opt-in mirroring.
+ *
+ * Construct fresh per call: the underlying file I/O is cheap and the runtime
+ * config could change between calls in long-running scenarios (rare but
+ * cheap to handle). For most callers a single store instance per tool call
+ * is fine.
+ */
+export declare function buildDecisionStore(): Promise<DecisionStore>;
+export { JsonlStore } from "./jsonl_store.js";
+export { MempalaceStore } from "./mempalace_store.js";

package/dist/mcp/stores/index.js

@@ -0,0 +1,24 @@
+import { loadCodeAiConfig } from "../config.js";
+import { JsonlStore } from "./jsonl_store.js";
+import { MempalaceStore } from "./mempalace_store.js";
+/**
+ * Factory — picks the decision store backend based on `.code-ai/config.json`.
+ *
+ * Safe default: `JsonlStore` (no external deps). Selecting `mempalace` wraps
+ * JsonlStore in MempalaceStore for opt-in mirroring.
+ *
+ * Construct fresh per call: the underlying file I/O is cheap and the runtime
+ * config could change between calls in long-running scenarios (rare but
+ * cheap to handle). For most callers a single store instance per tool call
+ * is fine.
+ */
+export async function buildDecisionStore() {
+    const cfg = await loadCodeAiConfig();
+    const jsonl = new JsonlStore();
+    if (cfg.decision_store === "mempalace") {
+        return new MempalaceStore(jsonl, cfg.mempalace_command, cfg.mempalace_args);
+    }
+    return jsonl;
+}
+export { JsonlStore } from "./jsonl_store.js";
+export { MempalaceStore } from "./mempalace_store.js";

package/dist/mcp/stores/jsonl_store.d.ts

@@ -0,0 +1,18 @@
+import type { DecisionLogEntry, DecisionLogInput, DecisionReadFilters, DecisionStore } from "../decision_store.js";
+/**
+ * Canonical decision-log backend. Appends JSON lines to
+ * `.code-ai/state/decisions.jsonl` (cwd-relative); reads back with optional
+ * filters.
+ *
+ * This is the baseline implementation lifted from the pre-DEV-099
+ * `record_decision.appendDecisionLog` helper, the `recent_decisions` reader,
+ * and the `audit_trail` decision-log merging code. Behaviour preserved except
+ * for one normalization: new writes emit the `adr_id` field (snake_case) only;
+ * reads tolerate the legacy `adrId` field too.
+ */
+export declare class JsonlStore implements DecisionStore {
+    /** Returns the `.code-ai/state/decisions.jsonl` path for the current cwd. */
+    private logPath;
+    appendDecision(entry: DecisionLogInput): Promise<string>;
+    readDecisions(filters: DecisionReadFilters): Promise<DecisionLogEntry[]>;
+}

package/dist/mcp/stores/jsonl_store.js

@@ -0,0 +1,85 @@
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * Canonical decision-log backend. Appends JSON lines to
+ * `.code-ai/state/decisions.jsonl` (cwd-relative); reads back with optional
+ * filters.
+ *
+ * This is the baseline implementation lifted from the pre-DEV-099
+ * `record_decision.appendDecisionLog` helper, the `recent_decisions` reader,
+ * and the `audit_trail` decision-log merging code. Behaviour preserved except
+ * for one normalization: new writes emit the `adr_id` field (snake_case) only;
+ * reads tolerate the legacy `adrId` field too.
+ */
+export class JsonlStore {
+    /** Returns the `.code-ai/state/decisions.jsonl` path for the current cwd. */
+    logPath() {
+        return join(process.cwd(), ".code-ai", "state", "decisions.jsonl");
+    }
+    async appendDecision(entry) {
+        const stateDir = join(process.cwd(), ".code-ai", "state");
+        await mkdir(stateDir, { recursive: true });
+        const drawerId = `${entry.adr_id}#${Date.now()}`;
+        const line = JSON.stringify({
+            drawer_id: drawerId,
+            adr_id: entry.adr_id,
+            task_id: entry.task_id,
+            gate: entry.gate,
+            question: entry.question,
+            chosen_option_id: entry.chosen_option_id,
+            signer: entry.signer,
+            timestamp: entry.timestamp,
+        }) + "\n";
+        await appendFile(this.logPath(), line, "utf8");
+        return drawerId;
+    }
+    async readDecisions(filters) {
+        const raw = await readFile(this.logPath(), "utf8").catch(() => "");
+        if (!raw)
+            return [];
+        const out = [];
+        const domainPrefix = filters.domain
+            ? `ADR-${filters.domain.slice(0, 3).toUpperCase()}-`
+            : null;
+        for (const line of raw.split("\n")) {
+            if (line.length === 0)
+                continue;
+            let obj;
+            try {
+                obj = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            // Tolerate legacy `adrId` field name from pre-DEV-099 writes.
+            const adrId = (obj.adr_id ?? obj.adrId);
+            if (!adrId)
+                continue;
+            if (!filters.includePending && adrId.startsWith("ADR-PENDING-"))
+                continue;
+            if (domainPrefix && !adrId.startsWith(domainPrefix))
+                continue;
+            if (filters.task_id && obj.task_id !== filters.task_id)
+                continue;
+            if (filters.signer && obj.signer !== filters.signer)
+                continue;
+            if (filters.since &&
+                typeof obj.timestamp === "string" &&
+                obj.timestamp < filters.since) {
+                continue;
+            }
+            out.push({
+                drawer_id: obj.drawer_id ?? `${adrId}#0`,
+                adr_id: adrId,
+                task_id: obj.task_id ?? "",
+                gate: obj.gate ?? "",
+                question: obj.question ?? "",
+                chosen_option_id: obj.chosen_option_id ?? "",
+                signer: obj.signer ?? "",
+                timestamp: obj.timestamp ?? "",
+            });
+        }
+        out.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+        return out;
+    }
+}

package/dist/mcp/stores/mempalace_store.d.ts

@@ -0,0 +1,29 @@
+import type { DecisionLogEntry, DecisionLogInput, DecisionReadFilters, DecisionStore } from "../decision_store.js";
+/**
+ * Opt-in mirror that wraps a canonical `JsonlStore`. On `appendDecision`:
+ *
+ *   1. Inner JSONL write runs FIRST and MUST succeed (canonical source of truth).
+ *   2. Spawn MemPalace MCP server via StdioClientTransport (per ADR-DEV-099
+ *      gate-1 choice Q1=Variant A — spawn-on-demand, no long-lived connection),
+ *      connect, call `mempalace_add_drawer` + `mempalace_kg_add`, then close.
+ *   3. ANY MemPalace error is caught and logged to stderr. JSONL succeeded;
+ *      data is not lost. Graceful degradation per ADR-DEV-098 Amendment 2026-06-02.
+ *
+ * `readDecisions` delegates to the inner store unchanged — JSONL is canonical.
+ * Future enrichment with MemPalace drawer queries is explicitly deferred.
+ */
+export declare class MempalaceStore implements DecisionStore {
+    private readonly inner;
+    private readonly mempalaceCommand;
+    private readonly mempalaceArgs;
+    constructor(inner: DecisionStore, mempalaceCommand: string, mempalaceArgs: string[]);
+    appendDecision(entry: DecisionLogInput): Promise<string>;
+    readDecisions(filters: DecisionReadFilters): Promise<DecisionLogEntry[]>;
+    /**
+     * Send the decision to MemPalace as a drawer + KG triple. Each invocation
+     * spawns a fresh MemPalace process; latency cost (~500ms-2s) is acceptable
+     * because record_decision is a rare operation.
+     */
+    private mirrorToMempalace;
+    private formatDrawerContent;
+}

package/dist/mcp/stores/mempalace_store.js

@@ -0,0 +1,89 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+/**
+ * Opt-in mirror that wraps a canonical `JsonlStore`. On `appendDecision`:
+ *
+ *   1. Inner JSONL write runs FIRST and MUST succeed (canonical source of truth).
+ *   2. Spawn MemPalace MCP server via StdioClientTransport (per ADR-DEV-099
+ *      gate-1 choice Q1=Variant A — spawn-on-demand, no long-lived connection),
+ *      connect, call `mempalace_add_drawer` + `mempalace_kg_add`, then close.
+ *   3. ANY MemPalace error is caught and logged to stderr. JSONL succeeded;
+ *      data is not lost. Graceful degradation per ADR-DEV-098 Amendment 2026-06-02.
+ *
+ * `readDecisions` delegates to the inner store unchanged — JSONL is canonical.
+ * Future enrichment with MemPalace drawer queries is explicitly deferred.
+ */
+export class MempalaceStore {
+    inner;
+    mempalaceCommand;
+    mempalaceArgs;
+    constructor(inner, mempalaceCommand, mempalaceArgs) {
+        this.inner = inner;
+        this.mempalaceCommand = mempalaceCommand;
+        this.mempalaceArgs = mempalaceArgs;
+    }
+    async appendDecision(entry) {
+        const drawerId = await this.inner.appendDecision(entry);
+        await this.mirrorToMempalace(entry, drawerId).catch((err) => {
+            const message = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[code-ai-mcp] MemPalace mirror failed (decision still recorded in JSONL): ${message}\n`);
+        });
+        return drawerId;
+    }
+    async readDecisions(filters) {
+        return this.inner.readDecisions(filters);
+    }
+    /**
+     * Send the decision to MemPalace as a drawer + KG triple. Each invocation
+     * spawns a fresh MemPalace process; latency cost (~500ms-2s) is acceptable
+     * because record_decision is a rare operation.
+     */
+    async mirrorToMempalace(entry, drawerId) {
+        const transport = new StdioClientTransport({
+            command: this.mempalaceCommand,
+            args: this.mempalaceArgs,
+            stderr: "pipe",
+        });
+        const client = new Client({
+            name: "code-ai-mcp-mempalace-mirror",
+            version: "0.1.0",
+        });
+        try {
+            await client.connect(transport);
+            await client.callTool({
+                name: "mempalace_add_drawer",
+                arguments: {
+                    wing: "wing_codex_product",
+                    room: "decisions",
+                    content: this.formatDrawerContent(entry, drawerId),
+                    added_by: "code-ai-mcp",
+                },
+            });
+            await client.callTool({
+                name: "mempalace_kg_add",
+                arguments: {
+                    subject: entry.task_id,
+                    predicate: "decided",
+                    object: entry.chosen_option_id,
+                    valid_from: entry.timestamp.slice(0, 10),
+                },
+            });
+        }
+        finally {
+            await client.close().catch(() => undefined);
+            await transport.close().catch(() => undefined);
+        }
+    }
+    formatDrawerContent(entry, drawerId) {
+        return [
+            `ADR ${entry.adr_id} — ${entry.question}`,
+            ``,
+            `Task: ${entry.task_id}`,
+            `Gate: ${entry.gate}`,
+            `Chosen option: ${entry.chosen_option_id}`,
+            `Signer: ${entry.signer}`,
+            `Timestamp: ${entry.timestamp}`,
+            `Drawer id: ${drawerId}`,
+        ].join("\n");
+    }
+}

package/dist/mcp/task_state.d.ts

@@ -0,0 +1,123 @@
+import { z } from "zod";
+import { GateName, PipelineMode } from "../shared/index.js";
+/**
+ * Per-task fs-backed state for the gate state machine.
+ * Stored at .code-ai/state/tasks/<task_id>.json (cwd-relative).
+ *
+ * Invariant: every gate is either current, signed (advanced past), or upcoming.
+ * `signoffs` records sign_off events; `classifications` records classify_gate
+ * outcomes. `dev_rollback_count` powers the circuit breaker.
+ */
+export declare const GateSignoff: z.ZodObject<{
+    gate: z.ZodEnum<{
+        PM: "PM";
+        UX: "UX";
+        ARCH: "ARCH";
+        DEV: "DEV";
+        REV: "REV";
+        OPS: "OPS";
+        TEST: "TEST";
+        RG: "RG";
+    }>;
+    signer: z.ZodEnum<{
+        mcp: "mcp";
+        den: "den";
+        system: "system";
+    }>;
+    timestamp: z.ZodString;
+    evidence: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+export type GateSignoff = z.infer<typeof GateSignoff>;
+export declare const GateClassification: z.ZodObject<{
+    gate: z.ZodEnum<{
+        PM: "PM";
+        UX: "UX";
+        ARCH: "ARCH";
+        DEV: "DEV";
+        REV: "REV";
+        OPS: "OPS";
+        TEST: "TEST";
+        RG: "RG";
+    }>;
+    outcome: z.ZodEnum<{
+        auto_resolve: "auto_resolve";
+        fork: "fork";
+        exception: "exception";
+    }>;
+    rationale: z.ZodString;
+    timestamp: z.ZodString;
+}, z.core.$strip>;
+export type GateClassification = z.infer<typeof GateClassification>;
+export declare const TaskState: z.ZodObject<{
+    task_id: z.ZodString;
+    mode: z.ZodEnum<{
+        full: "full";
+        bugfix: "bugfix";
+        hotfix: "hotfix";
+    }>;
+    current_gate: z.ZodEnum<{
+        PM: "PM";
+        UX: "UX";
+        ARCH: "ARCH";
+        DEV: "DEV";
+        REV: "REV";
+        OPS: "OPS";
+        TEST: "TEST";
+        RG: "RG";
+    }>;
+    signoffs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        gate: z.ZodEnum<{
+            PM: "PM";
+            UX: "UX";
+            ARCH: "ARCH";
+            DEV: "DEV";
+            REV: "REV";
+            OPS: "OPS";
+            TEST: "TEST";
+            RG: "RG";
+        }>;
+        signer: z.ZodEnum<{
+            mcp: "mcp";
+            den: "den";
+            system: "system";
+        }>;
+        timestamp: z.ZodString;
+        evidence: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>>>;
+    classifications: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        gate: z.ZodEnum<{
+            PM: "PM";
+            UX: "UX";
+            ARCH: "ARCH";
+            DEV: "DEV";
+            REV: "REV";
+            OPS: "OPS";
+            TEST: "TEST";
+            RG: "RG";
+        }>;
+        outcome: z.ZodEnum<{
+            auto_resolve: "auto_resolve";
+            fork: "fork";
+            exception: "exception";
+        }>;
+        rationale: z.ZodString;
+        timestamp: z.ZodString;
+    }, z.core.$strip>>>;
+    dev_rollback_count: z.ZodDefault<z.ZodNumber>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+    completed_at: z.ZodOptional<z.ZodString>;
+    audit_required_at: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type TaskState = z.infer<typeof TaskState>;
+export declare function readTaskState(taskId: string): Promise<TaskState | null>;
+export declare function writeTaskState(state: TaskState): Promise<void>;
+export declare function createTaskState(args: {
+    task_id: string;
+    mode: PipelineMode;
+    initial_gate: GateName;
+}): Promise<TaskState>;
+/** Returns the most recent classification for the given gate, or null. */
+export declare function latestClassification(state: TaskState, gate: GateName): GateClassification | null;
+/** Returns the most recent sign-off for the given gate, or null. */
+export declare function latestSignoff(state: TaskState, gate: GateName): GateSignoff | null;

package/dist/mcp/task_state.js

@@ -0,0 +1,95 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { ClassificationOutcome, GateName, PipelineMode, Signer, TaskId, } from "../shared/index.js";
+import { resolveTaskStateRoot } from "./paths.js";
+/**
+ * Per-task fs-backed state for the gate state machine.
+ * Stored at .code-ai/state/tasks/<task_id>.json (cwd-relative).
+ *
+ * Invariant: every gate is either current, signed (advanced past), or upcoming.
+ * `signoffs` records sign_off events; `classifications` records classify_gate
+ * outcomes. `dev_rollback_count` powers the circuit breaker.
+ */
+export const GateSignoff = z.object({
+    gate: GateName,
+    signer: Signer,
+    timestamp: z.string(),
+    evidence: z.unknown().optional(),
+});
+export const GateClassification = z.object({
+    gate: GateName,
+    outcome: ClassificationOutcome,
+    rationale: z.string(),
+    timestamp: z.string(),
+});
+export const TaskState = z.object({
+    task_id: TaskId,
+    mode: PipelineMode,
+    current_gate: GateName,
+    signoffs: z.array(GateSignoff).default([]),
+    classifications: z.array(GateClassification).default([]),
+    dev_rollback_count: z.number().int().min(0).default(0),
+    created_at: z.string(),
+    updated_at: z.string(),
+    /** Set when the task reaches a terminal gate (RG signed). */
+    completed_at: z.string().optional(),
+    /**
+     * ISO timestamp set when the circuit breaker REFUSED an advance and the
+     * caller must invoke the audit_role deep audit before continuing. Cleared
+     * when record_decision writes a new ARCH ADR (per reset_on=new_arch_adr).
+     * Surfaces in audit_trail / list_artifacts queries; not in current_gate
+     * output (contract is fixed for v0).
+     */
+    audit_required_at: z.string().optional(),
+});
+function pathFor(taskId) {
+    // TaskId zod is z.string().min(1) — no format guarantee, so sanitize for fs.
+    const safe = taskId.replace(/[^A-Za-z0-9_.-]/g, "_");
+    if (!safe || safe === "." || safe === "..") {
+        throw new Error(`invalid task_id for filesystem use: '${taskId}'`);
+    }
+    return join(resolveTaskStateRoot(), `${safe}.json`);
+}
+export async function readTaskState(taskId) {
+    const raw = await readFile(pathFor(taskId), "utf8").catch(() => null);
+    if (!raw)
+        return null;
+    return TaskState.parse(JSON.parse(raw));
+}
+export async function writeTaskState(state) {
+    await mkdir(resolveTaskStateRoot(), { recursive: true });
+    const next = { ...state, updated_at: new Date().toISOString() };
+    await writeFile(pathFor(state.task_id), JSON.stringify(next, null, 2) + "\n", "utf8");
+}
+export async function createTaskState(args) {
+    const now = new Date().toISOString();
+    const state = TaskState.parse({
+        task_id: args.task_id,
+        mode: args.mode,
+        current_gate: args.initial_gate,
+        signoffs: [],
+        classifications: [],
+        dev_rollback_count: 0,
+        created_at: now,
+        updated_at: now,
+    });
+    await writeTaskState(state);
+    return state;
+}
+/** Returns the most recent classification for the given gate, or null. */
+export function latestClassification(state, gate) {
+    for (let i = state.classifications.length - 1; i >= 0; i--) {
+        if (state.classifications[i].gate === gate)
+            return state.classifications[i];
+    }
+    return null;
+}
+/** Returns the most recent sign-off for the given gate, or null. */
+export function latestSignoff(state, gate) {
+    for (let i = state.signoffs.length - 1; i >= 0; i--) {
+        if (state.signoffs[i].gate === gate)
+            return state.signoffs[i];
+    }
+    return null;
+}

package/dist/mcp/tools/advance_gate.d.ts

@@ -0,0 +1,20 @@
+import { type AdvanceGateInput, type AdvanceGateOutput } from "../../shared/index.js";
+/**
+ * Advances the task from `from_gate` to `to_gate`.
+ *
+ * Preconditions:
+ *   - Task exists and is at from_gate.
+ *   - from_gate has a sign-off (matching its policy).
+ *   - to_gate is the next gate in the mode sequence (no skipping) UNLESS
+ *     to_gate=DEV and we're coming from REV/OPS/TEST — that's a rollback,
+ *     handled separately (see below).
+ *
+ * Rollback semantics: when to_gate=DEV and from_gate ∈ {REV, OPS, TEST}, this
+ * is a Fix Cycle. dev_rollback_count++. If the count reaches the circuit
+ * breaker threshold (default 2), advance_gate REFUSES and the caller must
+ * invoke the architect deep audit instead.
+ *
+ * RG completion: when advancing INTO RG and RG signs, task is marked completed.
+ * Future call resets dev_rollback_count if pipeline.reset_on includes rg_pass.
+ */
+export declare function advanceGate(input: AdvanceGateInput): Promise<AdvanceGateOutput>;

package/dist/mcp/tools/advance_gate.js

@@ -0,0 +1,82 @@
+import { getGateConfig, getNextGate, loadPipeline } from "../pipeline.js";
+import { latestSignoff, readTaskState, writeTaskState } from "../task_state.js";
+const DEFAULT_DOMAIN = "development";
+/**
+ * Advances the task from `from_gate` to `to_gate`.
+ *
+ * Preconditions:
+ *   - Task exists and is at from_gate.
+ *   - from_gate has a sign-off (matching its policy).
+ *   - to_gate is the next gate in the mode sequence (no skipping) UNLESS
+ *     to_gate=DEV and we're coming from REV/OPS/TEST — that's a rollback,
+ *     handled separately (see below).
+ *
+ * Rollback semantics: when to_gate=DEV and from_gate ∈ {REV, OPS, TEST}, this
+ * is a Fix Cycle. dev_rollback_count++. If the count reaches the circuit
+ * breaker threshold (default 2), advance_gate REFUSES and the caller must
+ * invoke the architect deep audit instead.
+ *
+ * RG completion: when advancing INTO RG and RG signs, task is marked completed.
+ * Future call resets dev_rollback_count if pipeline.reset_on includes rg_pass.
+ */
+export async function advanceGate(input) {
+    const pipeline = await loadPipeline(DEFAULT_DOMAIN);
+    const state = await readTaskState(input.task_id);
+    if (!state) {
+        throw new Error(`advance_gate: no task state for ${input.task_id}`);
+    }
+    if (state.current_gate !== input.from_gate) {
+        throw new Error(`advance_gate: task ${input.task_id} is at ${state.current_gate}, not ${input.from_gate}`);
+    }
+    if (state.mode !== input.mode) {
+        throw new Error(`advance_gate: task ${input.task_id} mode is ${state.mode}, not ${input.mode}`);
+    }
+    const fromCfg = getGateConfig(pipeline, state.mode, input.from_gate);
+    const fromSignoff = latestSignoff(state, input.from_gate);
+    if (!fromSignoff) {
+        throw new Error(`advance_gate: gate ${input.from_gate} has no sign-off (sign_off_policy=${fromCfg.sign_off_policy})`);
+    }
+    const isRollbackToDev = input.to_gate === "DEV" && ["REV", "OPS", "TEST"].includes(input.from_gate);
+    if (isRollbackToDev) {
+        const nextCount = state.dev_rollback_count + 1;
+        if (pipeline.circuit_breaker.enabled &&
+            nextCount >= pipeline.circuit_breaker.dev_rollback_threshold) {
+            // Mark task as audit-required and persist BEFORE throwing so downstream
+            // tools (audit_trail, list_artifacts) can see the state.
+            state.audit_required_at = new Date().toISOString();
+            await writeTaskState(state);
+            const skills = pipeline.circuit_breaker.audit_required_skills.join(", ");
+            throw new Error([
+                `advance_gate: circuit breaker tripped — dev_rollback_count would reach ${nextCount} (threshold ${pipeline.circuit_breaker.dev_rollback_threshold}).`,
+                `Recommended: run the audit in a FRESH session (clean-context principle — see wing_codex_product/decisions 2026-05-23, "SUBAGENTS FOR CONSISTENCY CHECKS"). In-session retry from the same Claude that just hit the wall reproduces the blind spot that caused the rollback in the first place.`,
+                `Required next steps:`,
+                `  1) load_role(role_name="${pipeline.circuit_breaker.audit_role}", domain="${pipeline.domain}")`,
+                `  2) Read skills: ${skills}`,
+                `  3) Produce architect audit (root-cause analysis, not patch attempt).`,
+                `  4) record_decision(task_id="${input.task_id}", gate="ARCH", ...) — new ARCH ADR resets dev_rollback_count to 0 via reset_on=new_arch_adr.`,
+                `  5) After reset, re-run sign_off("DEV", "den") + advance_gate(DEV → ${input.from_gate}).`,
+            ].join("\n"));
+        }
+        state.dev_rollback_count = nextCount;
+    }
+    else {
+        const expectedNext = getNextGate(pipeline, state.mode, input.from_gate);
+        if (expectedNext !== input.to_gate) {
+            throw new Error(`advance_gate: invalid transition ${input.from_gate} → ${input.to_gate} (expected ${expectedNext ?? "terminal"})`);
+        }
+    }
+    state.current_gate = input.to_gate;
+    if (state.completed_at === undefined && input.to_gate === "RG") {
+        // entered RG; completion happens when RG itself is signed; left as a marker
+    }
+    // Reset rollback counter on RG entry per reset_on policy (treat RG entry as rg_pass moment for prototype)
+    if (input.to_gate === "RG" && pipeline.circuit_breaker.reset_on.includes("rg_pass")) {
+        state.dev_rollback_count = 0;
+    }
+    await writeTaskState(state);
+    return {
+        task_id: input.task_id,
+        current_gate: input.to_gate,
+        allowed_tools: [],
+    };
+}

package/dist/mcp/tools/audit_trail.d.ts

@@ -0,0 +1,20 @@
+import type { AuditTrailInput, AuditTrailOutput } from "../../shared/index.js";
+/**
+ * Reconstructs the timeline for a task by merging:
+ *   - task_state classifications (kind: "classify_gate")
+ *   - task_state signoffs (kind: "sign_off")
+ *   - audit_required_at (kind: "circuit_breaker_trip")
+ *   - decisions.jsonl entries for this task (kind: "record_decision")
+ *
+ * Events are returned sorted asc by timestamp. Empty if the task doesn't exist.
+ *
+ * Not yet recorded (TODO for full instrumentation):
+ *   - "advance_gate" events — implicit in sign_off→next-gate; would require
+ *     extending TaskState with an explicit transition log.
+ *   - "submit_artifact" events — partially captured via .code-ai/state/
+ *     artifacts/<task_id>.jsonl when gate is provided.
+ *   - "request_decision" events — pending requests are not persisted yet.
+ *     report_exception entries are surfaced via report_exception output, but
+ *     also folded into the audit trail when present.
+ */
+export declare function auditTrail(input: AuditTrailInput): Promise<AuditTrailOutput>;