code-ai-installer 2.5.0 → 4.0.0

package/dist/mcp/paths.js

@@ -0,0 +1,53 @@
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+/**
+ * Path resolution for the code-ai MCP runtime (post-DEV-100 consolidation).
+ *
+ * Convention: the MCP runs from inside the `code-ai-installer` package, so we
+ * walk up from this file's location to the installer root (where `domains/`
+ * lives) and to the monorepo root (where `docs/` lives during development).
+ *
+ * Layout reference:
+ *   src layout (vitest, tsx):
+ *     packages/installer/src/mcp/paths.ts
+ *   dist layout (built):
+ *     packages/installer/dist/mcp/paths.js
+ *   Both are exactly 2 levels below the installer root (`src/mcp` or `dist/mcp`).
+ */
+const HERE = dirname(fileURLToPath(import.meta.url));
+// .../packages/installer/{src|dist}/mcp/paths.{ts|js} → .../packages/installer
+export const INSTALLER_ROOT = resolve(HERE, "..", "..");
+// → .../packages → monorepo
+const MONOREPO_ROOT = resolve(INSTALLER_ROOT, "..", "..");
+export const DOCS_ROOT = join(MONOREPO_ROOT, "docs");
+export const PERSONA_ROOT = join(DOCS_ROOT, "architecture-redesign");
+/**
+ * ADR write root. Resolved at call time relative to process.cwd() so the MCP
+ * doesn't pollute the monorepo when invoked from a user project. Tests rely
+ * on this by chdir'ing into a tmp dir before each call.
+ */
+export function resolveAdrRoot() {
+    return join(process.cwd(), "docs", "adr");
+}
+export function resolveDomainRoot(domain) {
+    return join(INSTALLER_ROOT, "domains", domain);
+}
+export function resolveSkillsRoot(domain) {
+    return join(resolveDomainRoot(domain), ".agents", "skills");
+}
+export function resolveAgentsDir(domain) {
+    return join(resolveDomainRoot(domain), "agents");
+}
+export function resolveAgentMd(domain, role) {
+    return join(resolveAgentsDir(domain), `${role}.md`);
+}
+export function resolvePipelineYaml(domain) {
+    return join(resolveDomainRoot(domain), "pipeline.yaml");
+}
+/**
+ * Task state root. Resolved at call time relative to process.cwd() — same
+ * convention as resolveAdrRoot() so the MCP doesn't pollute the host repo.
+ */
+export function resolveTaskStateRoot() {
+    return join(process.cwd(), ".code-ai", "state", "tasks");
+}

package/dist/mcp/pipeline.d.ts

@@ -0,0 +1,9 @@
+import { PipelineYaml, type DomainId, type GateName, type GateConfig, type ModeConfig, type PipelineMode } from "../shared/index.js";
+export declare function loadPipeline(domain: DomainId): Promise<PipelineYaml>;
+/** For tests + future "reload pipeline" tool. */
+export declare function clearPipelineCache(): void;
+export declare function getModeConfig(pipeline: PipelineYaml, mode: PipelineMode): ModeConfig;
+export declare function getGateConfig(pipeline: PipelineYaml, mode: PipelineMode, gate: GateName): GateConfig;
+export declare function getInitialGate(pipeline: PipelineYaml, mode: PipelineMode): GateName;
+/** Returns the next gate in the mode after `from`, or null if `from` is terminal. */
+export declare function getNextGate(pipeline: PipelineYaml, mode: PipelineMode, from: GateName): GateName | null;

package/dist/mcp/pipeline.js

@@ -0,0 +1,48 @@
+import { readFile } from "node:fs/promises";
+import { parse as parseYaml } from "yaml";
+import { PipelineYaml, } from "../shared/index.js";
+import { resolvePipelineYaml } from "./paths.js";
+/**
+ * Loads + caches pipeline.yaml per domain. Cache is per process; the only
+ * invalidation path is restart, which is fine for the prototype — the file is
+ * rewritten via a separate request_decision flow, not in-place.
+ */
+const CACHE = new Map();
+export async function loadPipeline(domain) {
+    const cached = CACHE.get(domain);
+    if (cached)
+        return cached;
+    const raw = await readFile(resolvePipelineYaml(domain), "utf8");
+    const obj = parseYaml(raw);
+    const parsed = PipelineYaml.parse(obj);
+    CACHE.set(domain, parsed);
+    return parsed;
+}
+/** For tests + future "reload pipeline" tool. */
+export function clearPipelineCache() {
+    CACHE.clear();
+}
+export function getModeConfig(pipeline, mode) {
+    const m = pipeline.modes.find((x) => x.mode === mode);
+    if (!m)
+        throw new Error(`pipeline.${pipeline.domain} has no mode '${mode}'`);
+    return m;
+}
+export function getGateConfig(pipeline, mode, gate) {
+    const m = getModeConfig(pipeline, mode);
+    const g = m.gates.find((x) => x.gate === gate);
+    if (!g)
+        throw new Error(`pipeline.${pipeline.domain}.${mode} has no gate '${gate}'`);
+    return g;
+}
+export function getInitialGate(pipeline, mode) {
+    return getModeConfig(pipeline, mode).gates[0].gate;
+}
+/** Returns the next gate in the mode after `from`, or null if `from` is terminal. */
+export function getNextGate(pipeline, mode, from) {
+    const gates = getModeConfig(pipeline, mode).gates;
+    const idx = gates.findIndex((g) => g.gate === from);
+    if (idx < 0)
+        throw new Error(`gate '${from}' not in mode '${mode}'`);
+    return idx + 1 < gates.length ? gates[idx + 1].gate : null;
+}

package/dist/mcp/server.d.ts

@@ -0,0 +1,24 @@
+import type { z } from "zod";
+import { TOOL_REGISTRY, type ToolName } from "../shared/index.js";
+import { type ToolHandler } 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 declare class CodeAiMcpServer {
+    private readonly handlers;
+    constructor(overrides?: Partial<{
+        [N in ToolName]: ToolHandler<N>;
+    }>);
+    /** Replace a single handler — used by prototype to ship one tool at a time. */
+    setHandler<N extends ToolName>(name: N, handler: ToolHandler<N>): void;
+    /**
+     * 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.
+     */
+    call<N extends ToolName>(name: N, rawInput: unknown): Promise<z.infer<(typeof TOOL_REGISTRY)[N]["output"]>>;
+    /** List every tool name registered in the contracts. */
+    listTools(): ToolName[];
+}

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>;