code-ai-installer 3.0.0 → 4.0.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Denis Harchenko
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Denis Harchenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.js

@@ -9,6 +9,7 @@ import { listDomains, resolveDomainSourceRoot, normalizeDomain, resolveDomainAwa
 import { runDoctor } from "./doctor.js";
 import { runInstall, runUninstall } from "./installer.js";
 import { error, info, success, warn } from "./logger.js";
+import { setupMcp } from "./mcp_setup.js";
 import { getPlatformAdapters } from "./platforms/adapters.js";
 import { resolveSourceRoot } from "./sourceResolver.js";
 import { printBanner } from "./banner.js";
@@ -41,6 +42,8 @@ const WIZARD_TEXT = {
         doctorFailed: "Doctor checks failed. Fix issues and run again.",
         dryRunMode: "Preview mode selected (no file writes).",
         previewCompleted: "Preview completed.",
+        mempalaceUsePrompt: "Use MemPalace for long-term decision memory? Recommended — installer will install MemPalace (via uv/pipx/pip) and register it in .mcp.json.",
+        mempalaceSetupHeader: "MCP auto-setup for Claude Code:",
     },
     ru: {
         cancelled: "Установка отменена.",
@@ -66,6 +69,8 @@ const WIZARD_TEXT = {
         doctorFailed: "Doctor не пройден. Исправь ошибки и запусти снова.",
         dryRunMode: "Выбран preview-режим без записи файлов.",
         previewCompleted: "Preview completed.",
+        mempalaceUsePrompt: "Использовать MemPalace для долгосрочной памяти решений? (рекомендуется — установщик поставит MemPalace через uv/pipx/pip и зарегистрирует в .mcp.json)",
+        mempalaceSetupHeader: "Авто-настройка MCP для Claude Code:",
     },
 };
 program
@@ -165,6 +170,8 @@ program
     .option("--overwrite", "Overwrite existing files", false)
     .option("--strict-hints", "Require explicit target-native hints in agent/skill files", false)
     .option("--apply", "Execute file writes (default is dry-run)", false)
+    .option("--with-mempalace", "Set up MemPalace MCP mirror for decisions (target=claude only). Default: true.", true)
+    .option("--no-mempalace", "Skip MemPalace setup even for target=claude")
     .action(async (options) => {
     try {
         const target = normalizeTarget(options.target);
@@ -210,6 +217,19 @@ program
         if (result.backupDir) {
             info(`Backup: ${result.backupDir}`);
         }
+        if (target === "claude" && !dryRun) {
+            const text = WIZARD_TEXT[language];
+            info(text.mempalaceSetupHeader);
+            const report = await setupMcp({
+                destinationDir,
+                wantMempalace: options.withMempalace,
+                dryRun: false,
+            });
+            for (const notice of report.notices)
+                info(`  ${notice}`);
+            info(`  .mcp.json: ${report.mcpJsonAction} at ${report.mcpJsonPath}`);
+            info(`  .code-ai/config.json: written at ${report.configPath} (decision_store=${report.mempalaceUsed ? "mempalace" : "jsonl"})`);
+        }
         if (dryRun) {
             success("Dry-run completed.");
         }
@@ -403,6 +423,18 @@ async function runInteractiveWizard() {
         },
     ]);
     const target = targetAnswer.target;
+    let wantMempalace = false;
+    if (target === "claude") {
+        const mempalaceAnswer = await prompts({
+            type: "toggle",
+            name: "useMempalace",
+            message: text.mempalaceUsePrompt,
+            initial: true,
+            active: "yes",
+            inactive: "no",
+        });
+        wantMempalace = Boolean(mempalaceAnswer.useMempalace);
+    }
     info(text.runDoctor);
     const doctor = await runDoctor(sourceRoot, destinationDir, target);
     for (const line of doctor.info) {
@@ -446,6 +478,18 @@ async function runInteractiveWizard() {
         if (result.backupDir) {
             info(`Backup: ${result.backupDir}`);
         }
+        if (target === "claude") {
+            info(text.mempalaceSetupHeader);
+            const report = await setupMcp({
+                destinationDir,
+                wantMempalace,
+                dryRun: false,
+            });
+            for (const notice of report.notices)
+                info(`  ${notice}`);
+            info(`  .mcp.json: ${report.mcpJsonAction} at ${report.mcpJsonPath}`);
+            info(`  .code-ai/config.json: written at ${report.configPath} (decision_store=${report.mempalaceUsed ? "mempalace" : "jsonl"})`);
+        }
         success("Install completed.");
     }
 }

package/dist/mcp/cli.d.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * code-ai-mcp — stdio MCP server entry point.
+ *
+ * Exposes every tool in TOOL_REGISTRY (the shared types module (src/shared)) through the
+ * Model Context Protocol so Claude Code can call them as native tools.
+ *
+ * The 17 wired handlers dispatch into CodeAiMcpServer; the 9 NotImplementedError
+ * stubs surface as structured tool errors (isError: true) rather than crashing
+ * the server.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type ToolName } from "../shared/index.js";
+/**
+ * One-line description per tool. Not stored in the shared types module (src/shared) because the
+ * registry there is pure I/O contracts; descriptions live with the transport
+ * because that's where they get surfaced to MCP clients.
+ */
+declare const TOOL_DESCRIPTIONS: Record<ToolName, string>;
+declare function buildServer(): McpServer;
+export { buildServer, TOOL_DESCRIPTIONS };

package/dist/mcp/cli.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+/**
+ * code-ai-mcp — stdio MCP server entry point.
+ *
+ * Exposes every tool in TOOL_REGISTRY (the shared types module (src/shared)) through the
+ * Model Context Protocol so Claude Code can call them as native tools.
+ *
+ * The 17 wired handlers dispatch into CodeAiMcpServer; the 9 NotImplementedError
+ * stubs surface as structured tool errors (isError: true) rather than crashing
+ * the server.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { TOOL_REGISTRY } from "../shared/index.js";
+import { CodeAiMcpServer } from "./server.js";
+import { NotImplementedError } from "./tools/stubs.js";
+const SERVER_INFO = {
+    name: "code-ai-mcp",
+    version: "0.0.0",
+};
+/**
+ * One-line description per tool. Not stored in the shared types module (src/shared) because the
+ * registry there is pure I/O contracts; descriptions live with the transport
+ * because that's where they get surfaced to MCP clients.
+ */
+const TOOL_DESCRIPTIONS = {
+    load_role: "Load an agent role: frontmatter, body, merged persona, and the role's skill list. Use at SessionStart for an agent.",
+    list_skills: "List skills in a domain. Optional filters: type, gate, tech, topic, owner.",
+    get_skill: "Fetch a skill's frontmatter + body by name.",
+    request_decision: "Open a pending decision envelope. Returns a synthetic ADR-PENDING id; Claude relays the question to DEN in chat, then commits the answer via record_decision.",
+    record_decision: "Commit a chosen decision: writes ADR file, decision log entry, and KG triple. Resets the circuit breaker on new ARCH ADR.",
+    classify_gate: "Record the current gate's classification (auto_resolve / fork / exception) with a rationale.",
+    advance_gate: "Advance task from from_gate to to_gate after sign-off. Enforces gate sequence; trips the circuit breaker on dev_rollback_count threshold.",
+    current_gate: "Return the task's current gate, allowed tools, and required handoff fields. Auto-creates task state on first touch.",
+    sign_off: "Record a sign-off event for the current gate. Validates signer against the gate's sign_off_policy (den / mcp_auto_pass / either).",
+    submit_artifact: "Write an artifact (skill / role / ADR / handoff / diary / working_report / plan / spec). Enforces line caps + frontmatter validation + path safety.",
+    verify_claim: "Verify a code-checkable claim. Wired: owners_present, no_orphan_skills, vocab_valid. Pending Phase 2: tests_pass, build_succeeds, lint_clean, custom.",
+    report_exception: "Append an exception record for DEN review (gate failed, breakdown of errors, optional evidence).",
+    get_artifact: "Fetch a previously-submitted artifact by (task_id, gate). format: raw or summary.",
+    list_artifacts: "List artifacts indexed for a task.",
+    audit_trail: "Reconstruct the timeline of events for a task: classifications, sign-offs, decisions, artifacts, exceptions. Sorted by timestamp.",
+    recent_decisions: "Read recent ADR decisions from the decision log with optional domain/signer/since filters.",
+    regenerate_manifest: "Regenerate AGENTS.yaml skills list from disk SKILL.md frontmatter. Detects AGENTS.md drift (skills on disk but not referenced).",
+    run_drift_audit: "[stub] Detect drift between SKILL.md frontmatter and AGENTS.md references.",
+    run_tests: "[stub] Run the test suite for a target (vitest / pytest).",
+    apply_diff: "[stub] Apply a unified diff to a file with safety checks.",
+    git_commit: "[stub] Stage and commit changes through a typed contract instead of raw shell.",
+    check_lint: "[stub] Run the linter for a target (eslint / ruff).",
+    build: "[stub] Run the build for a target (tsc / esbuild).",
+    dependency_supply_chain: "[stub] Check supply chain (npm audit, Socket integration, license check).",
+    docker_compose: "[stub] Run docker compose up/down for a target.",
+    e2e_playwright: "[stub] Run Playwright end-to-end suite.",
+};
+function buildServer() {
+    const dispatch = new CodeAiMcpServer();
+    const mcp = new McpServer(SERVER_INFO);
+    for (const toolName of Object.keys(TOOL_REGISTRY)) {
+        const { input, output } = TOOL_REGISTRY[toolName];
+        mcp.registerTool(toolName, {
+            description: TOOL_DESCRIPTIONS[toolName],
+            inputSchema: input,
+            outputSchema: output,
+        }, 
+        // The SDK validates `args` against inputSchema before calling us. We
+        // re-validate inside dispatch.call (server.ts) — cheap and keeps the
+        // in-process API contract sturdy when called outside the MCP path.
+        async (args) => {
+            try {
+                const result = await dispatch.call(toolName, args);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                    structuredContent: result,
+                };
+            }
+            catch (err) {
+                return errorResult(toolName, err);
+            }
+        });
+    }
+    return mcp;
+}
+function errorResult(toolName, err) {
+    if (err instanceof NotImplementedError) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: `Tool '${toolName}' is not yet implemented (Phase 2 stub). See ADR-DEV-098 roadmap.`,
+                },
+            ],
+        };
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+        isError: true,
+        content: [{ type: "text", text: `Tool '${toolName}' failed: ${message}` }],
+    };
+}
+async function main() {
+    const mcp = buildServer();
+    const transport = new StdioServerTransport();
+    await mcp.connect(transport);
+}
+// Allow importing buildServer in tests without starting the stdio loop.
+const isDirectRun = (() => {
+    try {
+        const argv1 = process.argv[1] ?? "";
+        return argv1.endsWith("cli.js") || argv1.endsWith("cli.ts");
+    }
+    catch {
+        return false;
+    }
+})();
+if (isDirectRun) {
+    main().catch((err) => {
+        console.error("code-ai-mcp fatal:", err);
+        process.exit(1);
+    });
+}
+export { buildServer, TOOL_DESCRIPTIONS };

package/dist/mcp/config.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+/**
+ * Runtime configuration read from `.code-ai/config.json` (cwd-relative).
+ *
+ * Selected by the installer at install time (`code-ai install --target=claude`)
+ * or by a human editing the file. Defaults are safe: with no file present,
+ * the store factory uses `JsonlStore` and `mempalace_command` defaults to
+ * the binary on PATH.
+ *
+ * Designed under ADR-DEV-099 — see `./stores/index.ts` for the factory that
+ * consumes this config to build the right `DecisionStore` backend.
+ */
+declare const CodeAiConfigSchema: z.ZodObject<{
+    decision_store: z.ZodDefault<z.ZodEnum<{
+        mempalace: "mempalace";
+        jsonl: "jsonl";
+    }>>;
+    mempalace_command: z.ZodDefault<z.ZodString>;
+    mempalace_args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type CodeAiConfig = z.infer<typeof CodeAiConfigSchema>;
+/**
+ * Load `.code-ai/config.json` relative to `process.cwd()`. Returns safe
+ * defaults on any failure (missing file, malformed JSON, validation error).
+ * Failure is silent — the caller proceeds with `JsonlStore`.
+ */
+export declare function loadCodeAiConfig(): Promise<CodeAiConfig>;
+export {};

package/dist/mcp/config.js

@@ -0,0 +1,48 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+/**
+ * Runtime configuration read from `.code-ai/config.json` (cwd-relative).
+ *
+ * Selected by the installer at install time (`code-ai install --target=claude`)
+ * or by a human editing the file. Defaults are safe: with no file present,
+ * the store factory uses `JsonlStore` and `mempalace_command` defaults to
+ * the binary on PATH.
+ *
+ * Designed under ADR-DEV-099 — see `./stores/index.ts` for the factory that
+ * consumes this config to build the right `DecisionStore` backend.
+ */
+const CodeAiConfigSchema = z.object({
+    decision_store: z.enum(["jsonl", "mempalace"]).default("jsonl"),
+    /** Override the binary name for the MemPalace MCP server. */
+    mempalace_command: z.string().min(1).default("mempalace"),
+    /** Optional extra args appended after the `mcp` subcommand. */
+    mempalace_args: z.array(z.string()).default(["mcp"]),
+});
+/** Empty config defaults — returned when the file is missing or unreadable. */
+const DEFAULT_CONFIG = {
+    decision_store: "jsonl",
+    mempalace_command: "mempalace",
+    mempalace_args: ["mcp"],
+};
+/**
+ * Load `.code-ai/config.json` relative to `process.cwd()`. Returns safe
+ * defaults on any failure (missing file, malformed JSON, validation error).
+ * Failure is silent — the caller proceeds with `JsonlStore`.
+ */
+export async function loadCodeAiConfig() {
+    const path = join(process.cwd(), ".code-ai", "config.json");
+    const raw = await readFile(path, "utf8").catch(() => null);
+    if (!raw)
+        return DEFAULT_CONFIG;
+    try {
+        const parsed = JSON.parse(raw);
+        const result = CodeAiConfigSchema.safeParse(parsed);
+        if (!result.success)
+            return DEFAULT_CONFIG;
+        return result.data;
+    }
+    catch {
+        return DEFAULT_CONFIG;
+    }
+}

package/dist/mcp/decision_store.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Abstraction over decision-log storage backends.
+ *
+ * Two implementations live under `./stores/`:
+ *   - `JsonlStore` — canonical append-only log at `.code-ai/state/decisions.jsonl`.
+ *     Always available. Zero external dependencies. Source of truth in every
+ *     deployment.
+ *   - `MempalaceStore` — opt-in mirror layered above `JsonlStore`. When enabled,
+ *     also writes to a separately-spawned MemPalace MCP server via the SDK
+ *     client transport. Reads come from JSONL canonically; MemPalace
+ *     enrichment of reads is deferred.
+ *
+ * Selection is per-deployment via `.code-ai/config.json` (`decision_store` field).
+ * See `./config.ts` and `./stores/index.ts` for the runtime factory.
+ *
+ * Designed under ADR-DEV-099 as the hybrid opt-in replacement for the original
+ * DEV-098 "MemPalace bridge" framing (which silently assumed MemPalace is
+ * universally available — corrected by ADR-DEV-098 Amendment 2026-06-02).
+ */
+export interface DecisionLogEntry {
+    /** Stable id for this log entry — `${adr_id}#${ms_epoch}` shape. */
+    drawer_id: string;
+    /** ADR identifier (e.g. `ADR-DEV-099`). Reader also tolerates legacy `adrId`. */
+    adr_id: string;
+    task_id: string;
+    gate: string;
+    question: string;
+    chosen_option_id: string;
+    signer: string;
+    /** ISO-8601 timestamp. */
+    timestamp: string;
+}
+/** Input shape for `appendDecision` — `drawer_id` is computed by the store. */
+export type DecisionLogInput = Omit<DecisionLogEntry, "drawer_id">;
+export interface DecisionReadFilters {
+    /** Exact task match. */
+    task_id?: string;
+    /** Domain id; matched against the ADR id prefix (`ADR-{DOMAIN3}-...`). */
+    domain?: string;
+    /** Exact signer match. */
+    signer?: string;
+    /** Lower-bound ISO timestamp (inclusive). */
+    since?: string;
+    /**
+     * Include `ADR-PENDING-*` entries from `request_decision` flow.
+     * Defaults to `false` — those are not yet resolved decisions.
+     */
+    includePending?: boolean;
+}
+export interface DecisionStore {
+    /**
+     * Append a new decision log entry and return the assigned `drawer_id`.
+     * Canonical writes (JSONL) MUST succeed for this method to resolve.
+     * Optional mirroring (MemPalace) is best-effort and never causes a throw.
+     */
+    appendDecision(entry: DecisionLogInput): Promise<string>;
+    /**
+     * Read decision entries matching the filters. Sorted ascending by timestamp.
+     * Empty array if the log is missing or empty.
+     */
+    readDecisions(filters: DecisionReadFilters): Promise<DecisionLogEntry[]>;
+}

package/dist/mcp/decision_store.js

@@ -0,0 +1,20 @@
+/**
+ * Abstraction over decision-log storage backends.
+ *
+ * Two implementations live under `./stores/`:
+ *   - `JsonlStore` — canonical append-only log at `.code-ai/state/decisions.jsonl`.
+ *     Always available. Zero external dependencies. Source of truth in every
+ *     deployment.
+ *   - `MempalaceStore` — opt-in mirror layered above `JsonlStore`. When enabled,
+ *     also writes to a separately-spawned MemPalace MCP server via the SDK
+ *     client transport. Reads come from JSONL canonically; MemPalace
+ *     enrichment of reads is deferred.
+ *
+ * Selection is per-deployment via `.code-ai/config.json` (`decision_store` field).
+ * See `./config.ts` and `./stores/index.ts` for the runtime factory.
+ *
+ * Designed under ADR-DEV-099 as the hybrid opt-in replacement for the original
+ * DEV-098 "MemPalace bridge" framing (which silently assumed MemPalace is
+ * universally available — corrected by ADR-DEV-098 Amendment 2026-06-02).
+ */
+export {};

package/dist/mcp/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * code-ai-mcp — Claude Code MCP server for code-ai.
+ *
+ * Status: API-surface skeleton (pre-req #2 of dev-domain migration plan).
+ * All tool I/O contracts are typed and validated; handlers are NotImplementedError
+ * stubs until pre-req #3 (baseline prototype) wires the first four:
+ *   load_role, list_skills, request_decision, record_decision.
+ *
+ * See README.md for the full tool surface, and ../../docs/architecture-redesign/
+ * for the architectural plan this package implements.
+ */
+export declare const VERSION = "0.0.0";
+export { CodeAiMcpServer } from "./server.js";
+export { DEFAULT_HANDLERS, NotImplementedError, type ToolHandler, } from "./tools/stubs.js";
+export { TOOL_REGISTRY, type ToolName } from "../shared/index.js";

package/dist/mcp/index.js

@@ -0,0 +1,17 @@
+/**
+ * code-ai-mcp — Claude Code MCP server for code-ai.
+ *
+ * Status: API-surface skeleton (pre-req #2 of dev-domain migration plan).
+ * All tool I/O contracts are typed and validated; handlers are NotImplementedError
+ * stubs until pre-req #3 (baseline prototype) wires the first four:
+ *   load_role, list_skills, request_decision, record_decision.
+ *
+ * See README.md for the full tool surface, and ../../docs/architecture-redesign/
+ * for the architectural plan this package implements.
+ */
+export const VERSION = "0.0.0";
+export { CodeAiMcpServer } from "./server.js";
+export { DEFAULT_HANDLERS, NotImplementedError, } from "./tools/stubs.js";
+// Re-export the shared contracts so consumers don't need to depend on the shared types module (src/shared)
+// directly when all they need is the tool surface.
+export { TOOL_REGISTRY } from "../shared/index.js";

package/dist/mcp/paths.d.ts

@@ -0,0 +1,20 @@
+import { type DomainId } from "../shared/index.js";
+export declare const INSTALLER_ROOT: string;
+export declare const DOCS_ROOT: string;
+export declare const PERSONA_ROOT: string;
+/**
+ * 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 declare function resolveAdrRoot(): string;
+export declare function resolveDomainRoot(domain: DomainId): string;
+export declare function resolveSkillsRoot(domain: DomainId): string;
+export declare function resolveAgentsDir(domain: DomainId): string;
+export declare function resolveAgentMd(domain: DomainId, role: string): string;
+export declare function resolvePipelineYaml(domain: DomainId): string;
+/**
+ * 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 declare function resolveTaskStateRoot(): string;

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[];
+}