code-ai-installer 2.5.0 → 4.0.0

package/dist/mcp/tools/load_role.js

@@ -0,0 +1,170 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { RoleFrontmatter, } from "../../shared/index.js";
+import { PERSONA_ROOT, resolveAgentMd } from "../paths.js";
+import { listSkills } from "./list_skills.js";
+const PERSONA_BASE = join(PERSONA_ROOT, "persona-base.md");
+/**
+ * SessionStart loader for an agent role.
+ *
+ * For pre-req #3, persona files live in docs/architecture-redesign/ (not yet
+ * migrated to installer/domains/<domain>/persona/ — awaiting DEN sign-off).
+ * Path is hard-coded here; will become configurable once persona moves into
+ * the installer ship.
+ *
+ * User-layer persona is currently always absent (persona-user-denis.md is
+ * gitignored and not loaded by name match). Future versions read the user
+ * handle from env or config.
+ */
+export async function loadRole(input) {
+    const roleMd = await readFile(resolveAgentMd(input.domain, input.role_name), "utf8");
+    const personaBase = await loadPersonaBase();
+    const personaUser = await loadPersonaUserLayer();
+    const persona = mergePersona(personaBase, personaUser);
+    const skillsForRole = await listSkills({
+        domain: input.domain,
+        owner: input.role_name,
+    });
+    // Prefer real RoleFrontmatter from disk (post-walkthrough). If absent or
+    // invalid, fall back to synthesis from role name + ROLE_TO_GATES table. The
+    // fallback preserves load_role behaviour for un-migrated domains.
+    const parsed = parseRoleFrontmatter(roleMd, input.domain);
+    const role = parsed ?? {
+        name: input.role_name,
+        description: extractFirstHeading(roleMd) ?? `Agent: ${input.role_name}`,
+        domain: input.domain,
+        signs_off_at: inferSignsOffAt(input.role_name),
+        tool_allowlist: `role:${input.role_name}`,
+        budget_lines: 250,
+        schema_version: 1,
+    };
+    const role_body = parsed ? stripFrontmatter(roleMd) : roleMd;
+    return {
+        role,
+        role_body,
+        persona,
+        tool_allowlist: [], // resolved by hook layer from role.tool_allowlist; empty in prototype
+        available_skills: skillsForRole.skills.map((s) => s.name),
+    };
+}
+/**
+ * Parse RoleFrontmatter from agent.md. Returns null on missing frontmatter,
+ * malformed YAML, or zod validation failure — caller falls back to synthesis.
+ *
+ * Also enforces that the frontmatter `domain` matches the requesting domain;
+ * mismatch returns null to prevent cross-domain role load via misplaced file.
+ */
+function parseRoleFrontmatter(raw, expectedDomain) {
+    const stripped = raw.startsWith("") ? raw.slice(1) : raw;
+    const m = stripped.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!m)
+        return null;
+    let yaml;
+    try {
+        yaml = parseYaml(m[1]);
+    }
+    catch {
+        return null;
+    }
+    const parsed = RoleFrontmatter.safeParse(yaml);
+    if (!parsed.success)
+        return null;
+    if (parsed.data.domain !== expectedDomain)
+        return null;
+    return parsed.data;
+}
+function stripFrontmatter(raw) {
+    const stripped = raw.startsWith("") ? raw.slice(1) : raw;
+    const m = stripped.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n+/);
+    return m ? stripped.slice(m[0].length) : stripped;
+}
+async function loadPersonaBase() {
+    const raw = await readFile(PERSONA_BASE, "utf8").catch(() => null);
+    if (!raw)
+        return null;
+    // Persona files in docs/architecture-redesign/ are markdown with section
+    // headings, not yaml. For pre-req #3 we extract sections by heading and
+    // treat each list item as a PersonaProperty with manual provenance.
+    return parsePersonaMarkdown(raw, "base");
+}
+async function loadPersonaUserLayer() {
+    // No automatic user-layer load in prototype — gitignored file, no handle resolution.
+    return null;
+}
+function parsePersonaMarkdown(raw, layer) {
+    const today = new Date().toISOString().slice(0, 10);
+    const sections = ["epistemic_stance", "defaults", "values", "style"];
+    const result = {
+        epistemic_stance: [],
+        defaults: [],
+        values: [],
+        style: [],
+    };
+    for (const section of sections) {
+        const headingRe = new RegExp(`^##\\s+${section.replace(/_/g, "[ _-]")}\\b`, "im");
+        const m = raw.match(headingRe);
+        if (!m || m.index === undefined)
+            continue;
+        const start = m.index + m[0].length;
+        const rest = raw.slice(start);
+        const nextHeading = rest.search(/^##\s+/m);
+        const body = nextHeading === -1 ? rest : rest.slice(0, nextHeading);
+        for (const line of body.split(/\r?\n/)) {
+            const item = line.match(/^\s*[-*]\s+(.+)$/);
+            if (!item)
+                continue;
+            result[section].push({
+                value: item[1].trim(),
+                provenance: [
+                    { source: "manual", ref: "persona-base.md", date: today },
+                ],
+            });
+        }
+    }
+    if (layer === "base") {
+        return {
+            schema_version: 1,
+            layer: "base",
+            ...result,
+        };
+    }
+    return {
+        schema_version: 1,
+        layer: "user",
+        user_handle: "unknown",
+        local_only: true,
+        ...result,
+    };
+}
+function mergePersona(base, user) {
+    const empty = { epistemic_stance: [], defaults: [], values: [], style: [] };
+    const b = base ?? { ...empty };
+    const u = user ?? { ...empty };
+    return {
+        base_version: base ? "1" : "0",
+        user_handle: user?.user_handle ?? null,
+        epistemic_stance: [...b.epistemic_stance, ...u.epistemic_stance],
+        defaults: [...b.defaults, ...u.defaults],
+        values: [...b.values, ...u.values],
+        style: [...b.style, ...u.style],
+    };
+}
+function extractFirstHeading(md) {
+    const m = md.match(/^#\s+(.+)$/m);
+    return m ? m[1].trim() : null;
+}
+function inferSignsOffAt(role) {
+    // Mirror ROLE_TO_GATES from migrate-frontmatter.ts. Hardcoded for prototype.
+    const map = {
+        architect: ["ARCH"],
+        conductor: ["PM", "UX", "ARCH", "DEV", "REV", "OPS", "TEST", "RG"],
+        devops: ["OPS"],
+        product_manager: ["PM"],
+        reviewer: ["REV"],
+        senior_full_stack: ["DEV"],
+        tester: ["TEST"],
+        ux_ui_designer: ["UX"],
+    };
+    return map[role] ?? ["RG"];
+}

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

@@ -0,0 +1,13 @@
+import { type RecentDecisionsInput, type RecentDecisionsOutput } from "../../shared/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 declare function recentDecisions(input: RecentDecisionsInput): Promise<RecentDecisionsOutput>;

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