code-ai-installer 3.0.0 → 4.0.0

package/dist/mcp/tools/recent_decisions.js

@@ -0,0 +1,36 @@
+import { Signer, } from "../../shared/index.js";
+import { buildDecisionStore } from "../stores/index.js";
+/**
+ * Returns the most recent record_decision entries, sorted desc by timestamp.
+ *
+ * Backed by `DecisionStore` (DEV-099) — defaults to `JsonlStore` reading
+ * `.code-ai/state/decisions.jsonl`. When `decision_store: "mempalace"` is set
+ * in `.code-ai/config.json`, `MempalaceStore` is selected but reads still come
+ * from JSONL (canonical) — see `../stores/mempalace_store.ts`.
+ *
+ * Skips `ADR-PENDING-*` entries — those come from request_decision (not yet
+ * resolved). Filters by domain when provided (mapped to ADR id prefix).
+ */
+export async function recentDecisions(input) {
+    const store = await buildDecisionStore();
+    const entries = await store.readDecisions({
+        ...(input.domain ? { domain: input.domain } : {}),
+        ...(input.since ? { since: input.since } : {}),
+    });
+    const out = [];
+    for (const entry of entries) {
+        const signerCheck = Signer.safeParse(entry.signer);
+        if (!signerCheck.success)
+            continue;
+        out.push({
+            adr_id: entry.adr_id,
+            timestamp: entry.timestamp,
+            question: entry.question,
+            chosen_option_id: entry.chosen_option_id,
+            signer: signerCheck.data,
+        });
+    }
+    // Store returns ascending; we want descending for "recent" semantics.
+    out.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+    return { decisions: out.slice(0, input.limit) };
+}

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

@@ -0,0 +1,17 @@
+import { type RecordDecisionInput, type RecordDecisionOutput } from "../../shared/index.js";
+/**
+ * Atomic 3-place ADR write:
+ *   1. docs/adr/ADR-{DOMAIN}-{NNN}.md  — versioned on disk
+ *   2. Decision log entry via DecisionStore — JsonlStore (canonical, always)
+ *      plus MempalaceStore mirror when opted in via `.code-ai/config.json`
+ *   3. KG triple id — subject=task_id, predicate=decided, object=chosen_option_id
+ *
+ * DEV-099 introduced the DecisionStore abstraction; pre-DEV-099 the helper
+ * `appendDecisionLog` was inlined here writing directly to JSONL. The new
+ * factory selects backend per `.code-ai/config.json` — see `../stores/index.ts`.
+ *
+ * If `supersedes` is provided, the new ADR carries a `## Supersedes` block
+ * referencing the prior ADR id; updating the prior ADR's status to "Superseded"
+ * is out of scope here (and would be a follow-up `update_adr` tool).
+ */
+export declare function recordDecision(input: RecordDecisionInput): Promise<RecordDecisionOutput>;

package/dist/mcp/tools/record_decision.js

@@ -0,0 +1,150 @@
+import { mkdir, readdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { resolveAdrRoot } from "../paths.js";
+import { loadPipeline } from "../pipeline.js";
+import { readTaskState, writeTaskState } from "../task_state.js";
+import { buildDecisionStore } from "../stores/index.js";
+const DEFAULT_DOMAIN = "development";
+/**
+ * Atomic 3-place ADR write:
+ *   1. docs/adr/ADR-{DOMAIN}-{NNN}.md  — versioned on disk
+ *   2. Decision log entry via DecisionStore — JsonlStore (canonical, always)
+ *      plus MempalaceStore mirror when opted in via `.code-ai/config.json`
+ *   3. KG triple id — subject=task_id, predicate=decided, object=chosen_option_id
+ *
+ * DEV-099 introduced the DecisionStore abstraction; pre-DEV-099 the helper
+ * `appendDecisionLog` was inlined here writing directly to JSONL. The new
+ * factory selects backend per `.code-ai/config.json` — see `../stores/index.ts`.
+ *
+ * If `supersedes` is provided, the new ADR carries a `## Supersedes` block
+ * referencing the prior ADR id; updating the prior ADR's status to "Superseded"
+ * is out of scope here (and would be a follow-up `update_adr` tool).
+ */
+export async function recordDecision(input) {
+    await mkdir(resolveAdrRoot(), { recursive: true });
+    const domainSlug = inferDomainSlug(input.task_id);
+    const adrId = await allocateAdrId(domainSlug);
+    const adrPath = join(resolveAdrRoot(), `${adrId}.md`);
+    const today = new Date().toISOString().slice(0, 10);
+    const chosen = input.options.find((o) => o.id === input.chosen_option_id);
+    if (!chosen) {
+        throw new Error(`chosen_option_id ${input.chosen_option_id} not in options[]`);
+    }
+    const body = renderAdr({
+        adrId,
+        today,
+        task_id: input.task_id,
+        gate: input.gate,
+        question: input.question,
+        options: input.options,
+        chosen,
+        rationale: input.rationale,
+        signer: input.signer,
+        supersedes: input.supersedes,
+    });
+    await writeFile(adrPath, body, "utf8");
+    const store = await buildDecisionStore();
+    const drawerId = await store.appendDecision({
+        adr_id: adrId,
+        task_id: input.task_id,
+        gate: input.gate,
+        question: input.question,
+        chosen_option_id: input.chosen_option_id,
+        signer: input.signer,
+        timestamp: new Date().toISOString(),
+    });
+    const kgTripleId = `t_${input.task_id}_decided_${input.chosen_option_id}_${shortHash(adrId)}`;
+    // Circuit breaker reset path (reset_on=new_arch_adr).
+    // When a new ARCH ADR is recorded against a task whose circuit breaker had
+    // tripped (or is just rolling), zero the dev_rollback_count and clear the
+    // audit_required_at marker. Silent no-op if task state doesn't exist.
+    await maybeResetCircuitBreaker(input.task_id, input.gate);
+    return {
+        adr_id: adrId,
+        adr_path: adrPath,
+        drawer_id: drawerId,
+        kg_triple_id: kgTripleId,
+    };
+}
+async function maybeResetCircuitBreaker(taskId, gate) {
+    if (gate !== "ARCH")
+        return;
+    const state = await readTaskState(taskId).catch(() => null);
+    if (!state)
+        return;
+    let pipeline;
+    try {
+        pipeline = await loadPipeline(DEFAULT_DOMAIN);
+    }
+    catch {
+        return; // No pipeline → nothing to reset against.
+    }
+    if (!pipeline.circuit_breaker.reset_on.includes("new_arch_adr"))
+        return;
+    if (state.dev_rollback_count === 0 && state.audit_required_at === undefined)
+        return;
+    state.dev_rollback_count = 0;
+    state.audit_required_at = undefined;
+    await writeTaskState(state);
+}
+async function allocateAdrId(domainSlug) {
+    const prefix = `ADR-${domainSlug}-`;
+    let max = 0;
+    try {
+        const entries = await readdir(resolveAdrRoot());
+        for (const f of entries) {
+            const m = f.match(new RegExp(`^${prefix}(\\d+)\\.md$`));
+            if (m)
+                max = Math.max(max, Number(m[1]));
+        }
+    }
+    catch {
+        // dir didn't exist; treat as zero
+    }
+    const next = String(max + 1).padStart(3, "0");
+    return `${prefix}${next}`;
+}
+function inferDomainSlug(taskId) {
+    // Convention: task_id looks like "DEV-2026-05-24-001" or "<domain>-<...>".
+    // Fallback to DEV for unrecognized.
+    const m = taskId.match(/^([A-Z]+)-/);
+    return m ? m[1] : "DEV";
+}
+function renderAdr(a) {
+    const optionsList = a.options
+        .map((o) => `- **${o.id}**${o.label ? ` — ${o.label}` : ""}${o.description ? `\n  ${o.description}` : ""}${o.tradeoffs.length > 0 ? `\n  Tradeoffs: ${o.tradeoffs.join("; ")}` : ""}`)
+        .join("\n");
+    const supersedesBlock = a.supersedes
+        ? `\n\n## Supersedes\n${a.supersedes}\n`
+        : "";
+    return `# ${a.adrId}: ${a.question}
+
+- **Status:** Accepted
+- **Date:** ${a.today}
+- **Task:** ${a.task_id}
+- **Gate:** ${a.gate}
+- **Signer:** ${a.signer}
+
+## Question
+
+${a.question}
+
+## Options Considered
+
+${optionsList}
+
+## Decision
+
+Chose **${a.chosen.id}**${a.chosen.label ? `: ${a.chosen.label}` : ""}.
+
+## Rationale
+
+${a.rationale}
+${supersedesBlock}`;
+}
+function shortHash(s) {
+    let h = 0;
+    for (let i = 0; i < s.length; i++)
+        h = (h * 31 + s.charCodeAt(i)) | 0;
+    return Math.abs(h).toString(16).slice(0, 8);
+}

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

@@ -0,0 +1,21 @@
+import { type RegenerateManifestInput, type RegenerateManifestOutput } from "../../shared/index.js";
+/**
+ * Regenerates the `skills:` block of AGENTS.yaml from the union of all
+ * SKILL.md frontmatter on disk. The skill list is the structural source of
+ * truth — direct edits to AGENTS.yaml are no longer the path; you edit the
+ * skill (add/rename/delete folder) and run this tool.
+ *
+ * Scope of v1 (this implementation):
+ *   - AGENTS.yaml `skills:` block is fully regenerated, sorted alphabetically
+ *   - AGENTS.md is NOT mutated — its sections by topic carry hand-written
+ *     comments ("условно, только если Wix iFrame...") and per-section grouping
+ *     that frontmatter alone can't reconstruct. The diff includes a section
+ *     listing skills present on disk but not referenced anywhere in AGENTS.md
+ *     (drift surface), so the caller knows what to fix manually.
+ *   - The `agents_md_path` is returned for output-shape conformance only;
+ *     `applied` reflects only whether AGENTS.yaml was rewritten.
+ *
+ * The diff is a unified-diff-ish text: "+ name" for added, "- name" for
+ * removed, against the current AGENTS.yaml `skills:` block.
+ */
+export declare function regenerateManifest(input: RegenerateManifestInput): Promise<RegenerateManifestOutput>;

package/dist/mcp/tools/regenerate_manifest.js

@@ -0,0 +1,153 @@
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { SkillFrontmatter, } from "../../shared/index.js";
+import { resolveDomainRoot, resolveSkillsRoot } from "../paths.js";
+/**
+ * Regenerates the `skills:` block of AGENTS.yaml from the union of all
+ * SKILL.md frontmatter on disk. The skill list is the structural source of
+ * truth — direct edits to AGENTS.yaml are no longer the path; you edit the
+ * skill (add/rename/delete folder) and run this tool.
+ *
+ * Scope of v1 (this implementation):
+ *   - AGENTS.yaml `skills:` block is fully regenerated, sorted alphabetically
+ *   - AGENTS.md is NOT mutated — its sections by topic carry hand-written
+ *     comments ("условно, только если Wix iFrame...") and per-section grouping
+ *     that frontmatter alone can't reconstruct. The diff includes a section
+ *     listing skills present on disk but not referenced anywhere in AGENTS.md
+ *     (drift surface), so the caller knows what to fix manually.
+ *   - The `agents_md_path` is returned for output-shape conformance only;
+ *     `applied` reflects only whether AGENTS.yaml was rewritten.
+ *
+ * The diff is a unified-diff-ish text: "+ name" for added, "- name" for
+ * removed, against the current AGENTS.yaml `skills:` block.
+ */
+export async function regenerateManifest(input) {
+    const domainRoot = resolveDomainRoot(input.domain);
+    const agentsYamlPath = join(domainRoot, "AGENTS.yaml");
+    const agentsMdPath = join(domainRoot, "AGENTS.md");
+    const onDisk = await collectSkillsFromDisk(input.domain);
+    const current = await readSkillsFromAgentsYaml(agentsYamlPath);
+    const orphans = await detectAgentsMdOrphans(agentsMdPath, onDisk);
+    const diff = computeDiff(current, onDisk, orphans);
+    let applied = false;
+    if (input.apply && diff.length > 0) {
+        const rawYaml = await readFile(agentsYamlPath, "utf8");
+        const next = rewriteSkillsBlock(rawYaml, onDisk);
+        if (next !== rawYaml) {
+            await writeFile(agentsYamlPath, next, "utf8");
+            applied = true;
+        }
+    }
+    return {
+        agents_yaml_path: agentsYamlPath,
+        agents_md_path: agentsMdPath,
+        diff,
+        applied,
+    };
+}
+/**
+ * Walk packages/installer/domains/<domain>/.agents/skills/<name>/SKILL.md and
+ * return the alphabetically-sorted list of skill names that have valid
+ * frontmatter. A folder without SKILL.md, or with malformed frontmatter, is
+ * silently skipped — `run_drift_audit` is the place to surface that.
+ */
+async function collectSkillsFromDisk(domain) {
+    const root = resolveSkillsRoot(domain);
+    const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+    const out = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const file = join(root, entry.name, "SKILL.md");
+        const raw = await readFile(file, "utf8").catch(() => null);
+        if (!raw)
+            continue;
+        const stripped = raw.startsWith("") ? raw.slice(1) : raw;
+        const m = stripped.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+        if (!m)
+            continue;
+        try {
+            const fm = SkillFrontmatter.safeParse(parseYaml(m[1]));
+            if (!fm.success)
+                continue;
+            if (fm.data.name !== entry.name)
+                continue;
+            out.push(fm.data.name);
+        }
+        catch {
+            continue;
+        }
+    }
+    out.sort((a, b) => a.localeCompare(b));
+    return out;
+}
+async function readSkillsFromAgentsYaml(file) {
+    const raw = await readFile(file, "utf8").catch(() => "");
+    if (!raw)
+        return [];
+    let parsed;
+    try {
+        parsed = parseYaml(raw);
+    }
+    catch {
+        return [];
+    }
+    const skills = parsed?.skills;
+    return Array.isArray(skills) ? [...skills].sort() : [];
+}
+/**
+ * Skills referenced as `$skill-name` in AGENTS.md body. Returns skills on
+ * disk but absent from every section — that's the drift caller needs to
+ * fix manually before B.2.
+ */
+async function detectAgentsMdOrphans(agentsMdPath, onDisk) {
+    const raw = await readFile(agentsMdPath, "utf8").catch(() => "");
+    if (!raw)
+        return onDisk;
+    const referenced = new Set();
+    for (const m of raw.matchAll(/\$([a-z][a-z0-9-]*)/g)) {
+        referenced.add(m[1]);
+    }
+    return onDisk.filter((s) => !referenced.has(s));
+}
+function computeDiff(current, next, orphans) {
+    const currentSet = new Set(current);
+    const nextSet = new Set(next);
+    const added = next.filter((s) => !currentSet.has(s));
+    const removed = current.filter((s) => !nextSet.has(s));
+    if (added.length === 0 && removed.length === 0 && orphans.length === 0) {
+        return "";
+    }
+    const lines = ["AGENTS.yaml skills: diff"];
+    for (const a of added)
+        lines.push(`+ ${a}`);
+    for (const r of removed)
+        lines.push(`- ${r}`);
+    if (orphans.length > 0) {
+        lines.push("");
+        lines.push("AGENTS.md drift (on disk but not referenced as $skill-name in any section):");
+        for (const o of orphans)
+            lines.push(`! ${o}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Replace the `skills:` block in AGENTS.yaml with the alphabetically-sorted
+ * skill list while preserving every other line in the file (header, roles,
+ * triggers, indentation choice). The current AGENTS.yaml uses flow-list
+ * entries `  - "name"` — we preserve that exact style.
+ */
+function rewriteSkillsBlock(rawYaml, names) {
+    const lines = rawYaml.split("\n");
+    const startIdx = lines.findIndex((l) => /^skills:\s*$/.test(l));
+    if (startIdx === -1) {
+        throw new Error("regenerate_manifest: AGENTS.yaml has no top-level `skills:` block");
+    }
+    let endIdx = startIdx + 1;
+    while (endIdx < lines.length && /^\s+-\s+/.test(lines[endIdx])) {
+        endIdx++;
+    }
+    const block = ["skills:", ...names.map((n) => `  - "${n}"`)];
+    return [...lines.slice(0, startIdx), ...block, ...lines.slice(endIdx)].join("\n");
+}

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

@@ -0,0 +1,11 @@
+import type { ReportExceptionInput, ReportExceptionOutput } from "../../shared/index.js";
+/**
+ * The exception channel of the silent-by-default pipeline. When an auto-check
+ * fails (vocab violation, missing artifact, line cap breach, drift...), the
+ * caller surfaces it here. We append a structured entry to
+ * .code-ai/state/exceptions.jsonl and tell the caller it was surfaced to DEN.
+ *
+ * For v1 every exception surfaces to "den". The hook layer is responsible for
+ * waking DEN (toast / push) — MCP only records.
+ */
+export declare function reportException(input: ReportExceptionInput): Promise<ReportExceptionOutput>;

package/dist/mcp/tools/report_exception.js

@@ -0,0 +1,31 @@
+import { mkdir, appendFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * The exception channel of the silent-by-default pipeline. When an auto-check
+ * fails (vocab violation, missing artifact, line cap breach, drift...), the
+ * caller surfaces it here. We append a structured entry to
+ * .code-ai/state/exceptions.jsonl and tell the caller it was surfaced to DEN.
+ *
+ * For v1 every exception surfaces to "den". The hook layer is responsible for
+ * waking DEN (toast / push) — MCP only records.
+ */
+export async function reportException(input) {
+    const stateDir = join(process.cwd(), ".code-ai", "state");
+    await mkdir(stateDir, { recursive: true });
+    const path = join(stateDir, "exceptions.jsonl");
+    const timestamp = new Date().toISOString();
+    const exceptionId = `EXC-${input.task_id}-${input.gate}-${Date.now()}`;
+    const entry = {
+        exception_id: exceptionId,
+        task_id: input.task_id,
+        gate: input.gate,
+        what_failed: input.what_failed,
+        breakdown: input.breakdown,
+        timestamp,
+    };
+    await appendFile(path, JSON.stringify(entry) + "\n", "utf8");
+    return {
+        exception_id: exceptionId,
+        surfaced_to: "den",
+    };
+}

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

@@ -0,0 +1,33 @@
+import { type RequestDecisionInput, type RequestDecisionOutput } from "../../shared/index.js";
+import { recordDecision } from "./record_decision.js";
+/**
+ * Passthrough decision channel.
+ *
+ * MCP can't prompt the user directly mid-tool-call, so this tool is split into
+ * two parts:
+ *   1. Caller invokes request_decision with question + options. The tool
+ *      validates input but does NOT record an ADR yet. It returns a structured
+ *      "pending" envelope that Claude (the LLM) relays to DEN in chat.
+ *   2. After DEN replies in chat, Claude calls record_decision with the chosen
+ *      option_id + rationale, which writes the ADR atomically (3 places).
+ *
+ * The returned object satisfies the RequestDecisionOutput contract by emitting
+ * a synthetic adr_id like `PENDING-<task_id>-<gate>-<hash>` that Claude is
+ * expected to discard. When the real ADR is written via record_decision, that
+ * tool returns the actual ADR id.
+ *
+ * Future replacement: if Claude Code (or the MCP transport) gains an
+ * `elicitation` primitive, this tool can be reworked to actually block on user
+ * input. The contract above stays valid; only the body changes.
+ */
+export declare function requestDecision(input: RequestDecisionInput): Promise<RequestDecisionOutput>;
+/**
+ * Convenience: convert request_decision output into a record_decision input
+ * once Claude has surfaced the question to DEN and received an answer.
+ * Not part of the MCP surface — use as a helper from the LLM relay flow.
+ */
+export declare function commitRequestedDecision(args: {
+    input: RequestDecisionInput;
+    chosen_option_id: string;
+    rationale: string;
+}): Promise<ReturnType<typeof recordDecision>>;

package/dist/mcp/tools/request_decision.js

@@ -0,0 +1,53 @@
+import { recordDecision } from "./record_decision.js";
+/**
+ * Passthrough decision channel.
+ *
+ * MCP can't prompt the user directly mid-tool-call, so this tool is split into
+ * two parts:
+ *   1. Caller invokes request_decision with question + options. The tool
+ *      validates input but does NOT record an ADR yet. It returns a structured
+ *      "pending" envelope that Claude (the LLM) relays to DEN in chat.
+ *   2. After DEN replies in chat, Claude calls record_decision with the chosen
+ *      option_id + rationale, which writes the ADR atomically (3 places).
+ *
+ * The returned object satisfies the RequestDecisionOutput contract by emitting
+ * a synthetic adr_id like `PENDING-<task_id>-<gate>-<hash>` that Claude is
+ * expected to discard. When the real ADR is written via record_decision, that
+ * tool returns the actual ADR id.
+ *
+ * Future replacement: if Claude Code (or the MCP transport) gains an
+ * `elicitation` primitive, this tool can be reworked to actually block on user
+ * input. The contract above stays valid; only the body changes.
+ */
+export async function requestDecision(input) {
+    const hash = simpleHash(`${input.task_id}|${input.gate}|${input.question}`).toUpperCase();
+    const safeTask = input.task_id.toUpperCase().replace(/[^A-Z0-9-]/g, "");
+    return {
+        chosen_option_id: "__pending__",
+        signer: "den",
+        adr_id: `ADR-PENDING-${safeTask}-${input.gate}-${hash}`,
+        timestamp: new Date().toISOString(),
+    };
+}
+/**
+ * Convenience: convert request_decision output into a record_decision input
+ * once Claude has surfaced the question to DEN and received an answer.
+ * Not part of the MCP surface — use as a helper from the LLM relay flow.
+ */
+export async function commitRequestedDecision(args) {
+    return recordDecision({
+        task_id: args.input.task_id,
+        gate: args.input.gate,
+        question: args.input.question,
+        options: args.input.options,
+        chosen_option_id: args.chosen_option_id,
+        rationale: args.rationale,
+        signer: "den",
+    });
+}
+function simpleHash(s) {
+    let h = 0;
+    for (let i = 0; i < s.length; i++)
+        h = (h * 31 + s.charCodeAt(i)) | 0;
+    return Math.abs(h).toString(16).slice(0, 6);
+}

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

@@ -0,0 +1,14 @@
+import { type SignOffInput, type SignOffOutput } from "../../shared/index.js";
+/**
+ * Records a sign-off event for the task's current gate. Validates that:
+ *   1. Task exists and is at the named gate.
+ *   2. Signer matches sign_off_policy:
+ *        sign_off_policy=den            → signer must be "den"
+ *        sign_off_policy=mcp_auto_pass  → signer must be "mcp"
+ *        sign_off_policy=either         → signer must be "den" or "mcp"
+ *   3. Gate has a classification recorded if classify_required=true.
+ *
+ * Does NOT advance the gate — that's advance_gate's job. sign_off only
+ * records evidence; advance_gate gates on it.
+ */
+export declare function signOff(input: SignOffInput): Promise<SignOffOutput>;

package/dist/mcp/tools/sign_off.js

@@ -0,0 +1,58 @@
+import { getGateConfig, loadPipeline } from "../pipeline.js";
+import { readTaskState, writeTaskState } from "../task_state.js";
+const DEFAULT_DOMAIN = "development";
+/**
+ * Records a sign-off event for the task's current gate. Validates that:
+ *   1. Task exists and is at the named gate.
+ *   2. Signer matches sign_off_policy:
+ *        sign_off_policy=den            → signer must be "den"
+ *        sign_off_policy=mcp_auto_pass  → signer must be "mcp"
+ *        sign_off_policy=either         → signer must be "den" or "mcp"
+ *   3. Gate has a classification recorded if classify_required=true.
+ *
+ * Does NOT advance the gate — that's advance_gate's job. sign_off only
+ * records evidence; advance_gate gates on it.
+ */
+export async function signOff(input) {
+    const pipeline = await loadPipeline(DEFAULT_DOMAIN);
+    const state = await readTaskState(input.task_id);
+    if (!state) {
+        throw new Error(`sign_off: no task state for ${input.task_id} (call current_gate or classify_gate first)`);
+    }
+    if (state.current_gate !== input.gate) {
+        throw new Error(`sign_off: task ${input.task_id} is at gate ${state.current_gate}, not ${input.gate}`);
+    }
+    const gateCfg = getGateConfig(pipeline, state.mode, input.gate);
+    switch (gateCfg.sign_off_policy) {
+        case "den":
+            if (input.signer !== "den") {
+                throw new Error(`sign_off: gate ${input.gate} requires signer 'den' (policy=den), got '${input.signer}'`);
+            }
+            break;
+        case "mcp_auto_pass":
+            if (input.signer !== "mcp") {
+                throw new Error(`sign_off: gate ${input.gate} requires signer 'mcp' (policy=mcp_auto_pass), got '${input.signer}'`);
+            }
+            break;
+        case "either":
+            if (input.signer !== "den" && input.signer !== "mcp") {
+                throw new Error(`sign_off: gate ${input.gate} requires signer 'den' or 'mcp' (policy=either), got '${input.signer}'`);
+            }
+            break;
+    }
+    if (gateCfg.classify_required) {
+        const hasClassification = state.classifications.some((c) => c.gate === input.gate);
+        if (!hasClassification) {
+            throw new Error(`sign_off: gate ${input.gate} requires classify_gate first (classify_required=true)`);
+        }
+    }
+    const timestamp = new Date().toISOString();
+    state.signoffs.push({
+        gate: input.gate,
+        signer: input.signer,
+        timestamp,
+        evidence: input.evidence,
+    });
+    await writeTaskState(state);
+    return { signed: true, signer: input.signer, timestamp };
+}

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

@@ -0,0 +1,17 @@
+import type { z } from "zod";
+import { TOOL_REGISTRY, type ToolName } from "../../shared/index.js";
+/**
+ * Typed handler signature derived from the I/O contracts in the shared types module (src/shared).
+ */
+export type ToolHandler<N extends ToolName> = (input: z.infer<(typeof TOOL_REGISTRY)[N]["input"]>) => Promise<z.infer<(typeof TOOL_REGISTRY)[N]["output"]>>;
+/** Thrown by every stub until the real implementation lands. */
+export declare class NotImplementedError extends Error {
+    constructor(tool: ToolName);
+}
+/**
+ * Default handler registry — every tool starts as a NotImplementedError stub.
+ * Real implementations replace entries here as they land (pre-req #3 baseline prototype).
+ */
+export declare const DEFAULT_HANDLERS: {
+    [N in ToolName]: ToolHandler<N>;
+};

package/dist/mcp/tools/stubs.js

@@ -0,0 +1,65 @@
+import { TOOL_REGISTRY } from "../../shared/index.js";
+import { listSkills } from "./list_skills.js";
+import { loadRole } from "./load_role.js";
+import { requestDecision } from "./request_decision.js";
+import { recordDecision } from "./record_decision.js";
+import { currentGate } from "./current_gate.js";
+import { classifyGate } from "./classify_gate.js";
+import { signOff } from "./sign_off.js";
+import { advanceGate } from "./advance_gate.js";
+import { submitArtifact } from "./submit_artifact.js";
+import { getSkill } from "./get_skill.js";
+import { regenerateManifest } from "./regenerate_manifest.js";
+import { reportException } from "./report_exception.js";
+import { recentDecisions } from "./recent_decisions.js";
+import { auditTrail } from "./audit_trail.js";
+import { listArtifacts } from "./list_artifacts.js";
+import { getArtifact } from "./get_artifact.js";
+import { verifyClaim } from "./verify_claim.js";
+/** Thrown by every stub until the real implementation lands. */
+export class NotImplementedError extends Error {
+    constructor(tool) {
+        super(`tool not yet implemented: ${tool}`);
+        this.name = "NotImplementedError";
+    }
+}
+/** Build a stub handler that validates input then throws NotImplementedError. */
+function stub(name) {
+    const schema = TOOL_REGISTRY[name].input;
+    return async (raw) => {
+        schema.parse(raw);
+        throw new NotImplementedError(name);
+    };
+}
+/**
+ * Default handler registry — every tool starts as a NotImplementedError stub.
+ * Real implementations replace entries here as they land (pre-req #3 baseline prototype).
+ */
+export const DEFAULT_HANDLERS = {
+    load_role: loadRole,
+    list_skills: listSkills,
+    get_skill: getSkill,
+    request_decision: requestDecision,
+    record_decision: recordDecision,
+    classify_gate: classifyGate,
+    advance_gate: advanceGate,
+    current_gate: currentGate,
+    sign_off: signOff,
+    submit_artifact: submitArtifact,
+    verify_claim: verifyClaim,
+    report_exception: reportException,
+    get_artifact: getArtifact,
+    list_artifacts: listArtifacts,
+    audit_trail: auditTrail,
+    recent_decisions: recentDecisions,
+    regenerate_manifest: regenerateManifest,
+    run_drift_audit: stub("run_drift_audit"),
+    run_tests: stub("run_tests"),
+    apply_diff: stub("apply_diff"),
+    git_commit: stub("git_commit"),
+    check_lint: stub("check_lint"),
+    build: stub("build"),
+    dependency_supply_chain: stub("dependency_supply_chain"),
+    docker_compose: stub("docker_compose"),
+    e2e_playwright: stub("e2e_playwright"),
+};