code-ai-installer 3.0.0 → 4.0.1-a

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/README.md

@@ -1,7 +1,7 @@
 <div align="center">
   <h1>🤖 Code-AI Installer</h1>
-  <p><b>The ultimate CLI tool to orchestrate AI Agents, Skills, and Workflows across multiple AI Coding Assistants.</b></p>
-  
+  <p><b>Write a gated, multi-agent pipeline once — deploy it to any AI coding assistant, and run it through a bundled MCP orchestration server.</b></p>
+
   [![npm version](https://img.shields.io/npm/v/code-ai-installer.svg)](https://www.npmjs.com/package/code-ai-installer)
   [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
   [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20-green.svg)](https://nodejs.org)
@@ -9,149 +9,165 @@
 
 <br/>
 
-**Code-AI Installer** (`code-ai`) is a powerful, production-ready CLI that injects your `.agents/`, `.agents/skills/`, and `.agents/workflows/` directly into the specific environment layouts required by different AI tools. Write your agentic pipelines once, and deploy them universally to Copilot, Codex, Claude, Qwen, or Google Antigravity.
+**Code-AI Installer** ships two things in one npm package:
+
+1. **`code-ai`** — a production-ready CLI that injects your `.agents/`, `.agents/skills/`, and `.agents/workflows/` into the exact environment layout each AI tool expects. Author your agentic pipelines once, deploy them to Copilot, Codex, Claude, Qwen, Kimi, or Google Antigravity.
+2. **`code-ai-mcp`** — a bundled MCP (Model Context Protocol) server that turns those agents and skills into a **governed, gate-by-gate pipeline**: each stage produces an artifact, gets classified, and waits for a human sign-off before the next stage runs. Auto-registered for Claude via `.mcp.json`.
+
+> The agents, the skills, and the MCP server are one product: the agents assume the MCP gate tools exist, and the MCP server assumes the installer registered it. `npm install -g code-ai-installer` brings the whole thing.
 
 ---
 
 ## ✨ Features
 
-- 🚀 **Interactive Wizard**: Out-of-the-box interactive CLI to easily pick targets, agents, and skills.
-- 🌍 **Multi-AI Support**: Automatically adapts instructions, reasoning hints, and files for Copilot, GPT Codex, Claude, Qwen 3.5, and Google Antigravity.
-- 📦 **Standalone & Global**: Bundled with base templates—run it from anywhere on your machine!
-- 🛡️ **Bulletproof Safety**: Default `dry-run` mode, automatic backups to `.code-ai-installer/backups/`, and built-in rollbacks.
-- 🧠 **Smart Transformation**: Normalizes markdown content. Automatically translates target-native AI hints (e.g., mapping `codex reasoning` to `claude thinking` or `gemini reasoning`).
-- 🌐 **Localization**: First-class support for English (`en`) and Russian (`ru`).
+- 🚪 **Gate-based pipeline** — agents don't free-run. Work advances through ordered gates (classify → produce → human sign-off → advance), enforced by the MCP server's state machine, with a circuit breaker on repeated rollbacks.
+- 🧰 **Bundled MCP server** — `code-ai-mcp` exposes 31 tools (gate machine, skill fetch with telemetry, artifact/decision log, audit + action tools). Auto-wired into Claude's `.mcp.json` at install time.
+- 🔭 **Self-improving Auditor** — a meta-agent reads aggregate run metrics after ≥3 completed runs and *proposes* (never forces) tweaks to skills/agents; the human approves.
+- 🚀 **Interactive wizard** — pick target, domain, agents, and skills from a guided CLI.
+- 🌍 **Multi-AI support** — adapts instructions, reasoning hints, and file layout for Copilot, GPT Codex, Claude, Qwen 3.5, Moonshot Kimi, and Google Antigravity.
+- 🛡️ **Bulletproof safety** — default `dry-run`, automatic backups, built-in rollbacks.
+- 🧠 **Smart transformation** — normalizes markdown and translates native AI hints (e.g. maps `codex reasoning` to `claude thinking` / `gemini reasoning`).
+- 🌐 **Localization** — first-class English (`en`) and Russian (`ru`).
 
 ---
 
 ## 🏛️ Domain Architecture
 
-Code-AI Installer comes pre-bundled with dedicated professional systems separated by **Domains** to cleanly isolate workflows based on your project needs. You can choose which domain to deploy during installation:
+Code-AI ships dedicated, self-contained professional systems separated by **domain**, each with its own roles, skills, and gate pipeline. Pick one per project at install time.
+
+| Domain | Gates | What it is |
+|---|:---:|---|
+| 💻 **`development`** | 8 | End-to-end web app delivery: PM → UX → Architecture → Dev → Review → Ops → Test → Release Gate. Roles: Product Manager, UX/UI Designer, Architect, Senior Full-Stack, Reviewer, DevOps, QA Tester. |
+| 📝 **`content`** | 6 | Digital content production: Strategist → Researcher → Copywriter → Visual Concept → Reviewer → Release Gate. |
+| 📊 **`analytics`** | 8 | Business analysis modeled adversarially (Analysts vs Critics with a Mediator): Interviewer → Researcher → Data Analyst → Strategist → Mediator → Designer → Layouter → Release Gate. Strategic frameworks (SWOT, PEST, Porter, BCG, Blue Ocean, Ansoff, Unit Economics, Cohort, …). |
+| 📦 **`product`** | 10 | B2B SaaS product management: Discovery → Product Strategist → PM → UX Designer → Tech Lead → Data Analyst → Mediator → Designer → Layouter → Release Gate. |
+
+Every domain also carries a meta **Auditor** beside the pipeline. Each skill declares structured metadata (`type`, `owners`, `gates`, `triggers`) so the MCP server can surface the right skill at the right gate. Large reference libraries are split into a lean workflow skill + a `*-reference` companion.
+
+---
+
+## 🚪 The MCP Gate Pipeline
 
-- 💻 **Software Development Domain** (`development`): An 8-gate robust agentic pipeline tailored for end-to-end web app development. Includes roles like Product Manager, UX/UI Designer, Architect, Senior Full Stack Developer, Reviewer, DevOps, and QA Tester.
-- 📝 **Content Production Domain** (`content`): A creative pipeline dedicated to producing digital content (social media, blogs, visuals). Orchestrates roles such as Content Strategist, Copywriter, Researcher, and Visual Concept Designer.
-- 📊 **Business Analytics Domain** (`analytics`): An adversarial analytical pipeline with two competing teams (Analysts vs Critics) and a Mediator — plus Designer and Layouter for PDF reports. Strategic frameworks (SWOT, PEST, Porter's Five Forces, BCG, Blue Ocean, Ansoff, Unit Economics, Cohort, etc.).
-- 📦 **Product Management Domain** (`product`): A B2B SaaS product management pipeline — discovery → strategy → prioritization → PRD → UX → release → measurement. Dual adversarial axes: Customer-Champion vs Business-Champion on strategy, Build-Camp vs Cut-Camp on prioritization. Includes Discovery, Product Strategist, PM, UX Designer, Tech Lead, Data Analyst, Mediator, Designer, Layouter.
+When you install for **Claude**, the installer registers `code-ai-mcp` in your project's `.mcp.json`. From then on, the agents drive the work *through the server*, not by free-form prompting:
 
-*(You can select your target domain during the interactive installation process!)*
+1. **`current_gate` / `classify_gate`** — the conductor reads where the run is and classifies the gate outcome (`auto_resolve` / `fork` / `exception`).
+2. **`get_skill`** — the active role fetches the skills it owns at this gate (the fetch is logged as telemetry for the Auditor).
+3. **`submit_artifact` / `verify_claim`** — the role produces its deliverable; structured frontmatter and budgets are validated.
+4. **`sign_off` → `advance_gate`** — a human (or, where wired, an auto-check) signs the gate; only then does the pipeline move on. A circuit breaker halts repeated dev rollbacks and escalates to an architecture audit.
+5. **`record_decision` / `audit_trail`** — ADR-style decisions and exceptions are logged per run.
+
+After enough completed runs, the **Auditor** calls `aggregate_run_metrics` and files `propose_change` suggestions (reviewed via `review_proposal`) — a build → run → measure → improve loop for the toolkit itself.
+
+> MCP is currently a **Claude-specific** capability. Other targets receive the agent/skill markdown and run them as plain instructions.
 
 ---
 
 ## 🎯 Supported AI Targets
 
-- `vscode-copilot` / `copilot`
-- `gpt-codex` / `codex`
-- `claude`
-- `qwen-3.5` / `qwen`
-- `google-antigravity` / `antigravity`
-- `moonshot-kimi` / `kimi` (Kimi CLI + Kimi Code for VS Code)
+| CLI target (and aliases) | Tool |
+|---|---|
+| `vscode-copilot` / `copilot` | VS Code Copilot |
+| `gpt-codex` / `codex` | GPT Codex |
+| `claude` | Claude (Claude Code) — **MCP server auto-wired** |
+| `qwen-3.5` / `qwen` | Qwen 3.5 |
+| `google-antigravity` / `antigravity` | Google Antigravity |
+| `moonshot-kimi` / `kimi` | Moonshot Kimi (Kimi CLI + Kimi Code for VS Code) |
 
 ---
 
 ## 🔧 Installation
 
-### 1. Global Installation (Recommended)
-
-Install the CLI globally to run it in any of your projects:
+### Global (recommended)
 
 ```bash
-# via npm
 npm install -g code-ai-installer
-
-# via pnpm, yarn, or bun
-pnpm add -g code-ai-installer
-yarn global add code-ai-installer
-bun add -g code-ai-installer
+# or: pnpm add -g code-ai-installer / yarn global add code-ai-installer / bun add -g code-ai-installer
 ```
 
-Verify the installation:
+Verify:
 ```bash
 code-ai --help
 ```
 
-### 2. Local Installation (For Development)
+### From source (for development / contributing)
+
+This is an npm-workspaces monorepo; the published package lives in `packages/installer`.
 
-If you are cloning this repository to build or contribute:
 ```bash
-git clone https://github.com/denish12/codex-ai-agent-and-skills.git
-cd codex-ai-agent-and-skills
+git clone https://github.com/denish12/code-ai-monorepo.git
+cd code-ai-monorepo
 npm install
 npm run build
-npm install -g .
+npm install -g ./packages/installer
 ```
 
 ---
 
 ## 🚀 Usage
 
-### The Interactive Wizard
-Just run `code-ai` inside your project directory to trigger the fully interactive guide:
+### Interactive wizard
+
+Run `code-ai` inside your project to launch the guided installer (it also offers to wire the MCP server for Claude):
+
 ```bash
 code-ai
 ```
 
-### CLI Commands & Flags
+### CLI commands & flags
 
 ```bash
-# List all supported targets
+# List supported targets
 code-ai targets
 
-# List available agents and skills (--domain required since v3.0.0)
+# List agents and skills in a domain (--domain required since v3.0.0)
 code-ai list --domain development
 code-ai list --domain content --lang en
 
-# Check system health and compatibility for a specific target + domain
+# Health-check a target + domain
 code-ai doctor --target claude --domain development
 
-# Run a safe Dry-Run installation preview (Default)
+# Dry-run preview (default — writes nothing)
 code-ai install --target claude --domain development --agents conductor,reviewer --skills board
 
-# Apply Installation (actually write files)
+# Apply for real
 code-ai install --target gpt-codex --domain analytics --agents all --skills all --apply
 
-# Overwrite existing files securely
+# Overwrite existing files
 code-ai install --target claude --domain content --agents all --skills all --overwrite --apply
 
-# Strict Mode (Enforces explicit target hints in agent files)
-code-ai install --target claude --domain product --agents all --skills all --strict-hints --apply
+# For Claude: skip the optional MemPalace memory server (code-ai-mcp is still wired)
+code-ai install --target claude --domain product --agents all --skills all --no-mempalace --apply
 
-# Uninstall / Clean up AI assets securely
+# Uninstall / clean up AI assets
 code-ai uninstall --target claude --apply
 ```
 
 ---
 
-## ⚠️ Migrating from v2.x to v3.0.0
-
-**v3.0.0 is a breaking release.** The legacy root layout (`AGENTS.md` + `agents/` + `.agents/` at package root) was removed. The CLI now exclusively reads from the `domains/<id>/` layout.
+## 🏗️ What gets generated?
 
-| Change | Before (v2.x) | After (v3.0.0) |
-|---|---|---|
-| Required flag | `--domain` optional | `--domain <name>` required (or `cwd` must contain a `domains/` directory) |
-| EN locale path | `locales/en/` | `domains/<id>/locales/en/` |
-| `--project-dir` accepts | legacy root or `domains/` layout | `domains/` layout only |
-| Bundled files | 11 entries incl. root `AGENTS.md` | 4 entries: `dist`, `LICENSE`, `README.md`, `domains` |
+Depending on `--target`, `code-ai` restructures your project:
 
-**To migrate**: add `--domain development` (or `content`, `analytics`, `product`) to every CLI call. If you used a custom source via `--project-dir`, restructure it to contain `domains/<id>/domain.json` instead of a flat `AGENTS.md` + `agents/` layout.
+1. **Orchestration entry** — `AGENTS.md` (plus tool aliases like `CLAUDE.md`, `CODEX.md`, `GEMINI.md`, `QWEN.md`, `KIMI.md`).
+2. **Agents** — roles copied into the target's layout (e.g. `.claude/agents/<role>.md`, `.github/copilot-instructions.md`).
+3. **Skills & workflows** — the execution skillsets, with per-tool metadata sidecars.
+4. **MCP wiring (Claude only)** — `.mcp.json` registering `code-ai-mcp` (run as `npx -p code-ai-installer code-ai-mcp`), plus an optional [MemPalace](https://www.npmjs.com/package/mempalace) memory server when present, and a `.code-ai/config.json` that records the active domain and decision-store backend.
 
 ---
 
-## 🏗️ What Gets Generated?
+## 🧬 Versions & migration
 
-Depending on the chosen `--target`, `code-ai` restructures your environment intelligently:
+`code-ai-installer` is on **v4.0.0**.
 
-1. **Root Orchestration Rules**: Generates `AGENTS.md` (and alias files like `CLAUDE.md`, `CODEX.md`, `GEMINI.md`, etc.).
-2. **Agents**: Copies roles to target-specific directories (e.g., `.gemini/agents/<agent>/prompt.md`, `.github/copilot-instructions.md`).
-3. **Skills & Workflows**: Deploys the necessary execution skillsets and custom workflows specific to the target AI.
-4. **Configuration**: Generates workspace settings (e.g., `.qwen/settings.json`).
+- **v4.0.0** — consolidated the previously separate `code-ai-mcp` and types packages into this single package with **two bins** (`code-ai` + `code-ai-mcp`). Installing the CLI now also delivers the MCP server; for Claude it is auto-registered in `.mcp.json`. Existing 3.x CLI behavior is unchanged.
+- **v3.0.0 (breaking)** — removed the legacy flat root layout (`AGENTS.md` + `agents/` + `.agents/` at package root); the CLI now reads exclusively from `domains/<id>/`. **Migrating from v2.x:** add `--domain <development|content|analytics|product>` to every CLI call. If you used a custom `--project-dir`, restructure it to `domains/<id>/` instead of a flat layout.
 
 ---
 
 ## 🤝 Contributing
 
-Contributions, issues, and feature requests are welcome!  
-Feel free to check out the [issues page](https://github.com/denish12/codex-ai-agent-and-skills/issues).
+Contributions, issues, and feature requests are welcome — see the [issues page](https://github.com/denish12/code-ai-monorepo/issues).
 
 ## 📄 License
 
-This project is [MIT](https://opensource.org/licenses/MIT) licensed.
+[MIT](https://opensource.org/licenses/MIT).

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,20 @@ 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,
+                ...(domainId ? { domain: domainId } : {}),
+            });
+            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 +424,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 +479,19 @@ async function runInteractiveWizard() {
         if (result.backupDir) {
             info(`Backup: ${result.backupDir}`);
         }
+        if (target === "claude") {
+            info(text.mempalaceSetupHeader);
+            const report = await setupMcp({
+                destinationDir,
+                wantMempalace,
+                dryRun: false,
+                ...(selectedDomainId ? { domain: selectedDomainId } : {}),
+            });
+            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/audit_ledger.d.ts

@@ -0,0 +1,12 @@
+import { RunScorecard } from "./scorecard.js";
+import type { TaskState } from "./task_state.js";
+/** Append one scorecard as a JSON line to the run ledger (creates dir if needed). */
+export declare function appendScorecard(card: RunScorecard): Promise<void>;
+/** Read all scorecards from the ledger. Malformed / partial lines are skipped. */
+export declare function readLedger(): Promise<RunScorecard[]>;
+/**
+ * Build + append a scorecard for a completed run. Called from sign_off when RG
+ * is signed. Best-effort by contract: callers MUST NOT let a ledger failure
+ * break a sign-off (telemetry is never load-bearing for the gate).
+ */
+export declare function recordRunScorecard(state: TaskState): Promise<void>;

package/dist/mcp/audit_ledger.js

@@ -0,0 +1,82 @@
+import { mkdir, readFile, appendFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { resolveAuditLedgerPath } from "./paths.js";
+import { RunScorecard, buildScorecard } from "./scorecard.js";
+import { readSkillInvocations } from "./skill_invocations.js";
+/** Append one scorecard as a JSON line to the run ledger (creates dir if needed). */
+export async function appendScorecard(card) {
+    const path = resolveAuditLedgerPath();
+    await mkdir(dirname(path), { recursive: true });
+    await appendFile(path, JSON.stringify(card) + "\n", "utf8");
+}
+/** Read all scorecards from the ledger. Malformed / partial lines are skipped. */
+export async function readLedger() {
+    const raw = await readFile(resolveAuditLedgerPath(), "utf8").catch(() => "");
+    if (!raw)
+        return [];
+    const cards = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            cards.push(RunScorecard.parse(JSON.parse(line)));
+        }
+        catch {
+            continue; // tolerate hand-edits / schema drift; surfacing tool, not enforcer
+        }
+    }
+    return cards;
+}
+/**
+ * Count exceptions (grouped by gate) and decisions for a task from the jsonl
+ * side logs. Plain reads — no DecisionStore/MemPalace dependency in the hot path.
+ */
+async function readSideCounts(taskId) {
+    const stateDir = join(process.cwd(), ".code-ai", "state");
+    const exceptions_by_gate = {};
+    const rawExc = await readFile(join(stateDir, "exceptions.jsonl"), "utf8").catch(() => "");
+    for (const line of rawExc.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const o = JSON.parse(line);
+            if (o.task_id !== taskId)
+                continue;
+            const g = typeof o.gate === "string" ? o.gate : "unknown";
+            exceptions_by_gate[g] = (exceptions_by_gate[g] ?? 0) + 1;
+        }
+        catch {
+            continue;
+        }
+    }
+    let decisions_count = 0;
+    const rawDec = await readFile(join(stateDir, "decisions.jsonl"), "utf8").catch(() => "");
+    for (const line of rawDec.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const o = JSON.parse(line);
+            if (o.task_id === taskId && !String(o.adr_id ?? "").startsWith("ADR-PENDING-")) {
+                decisions_count++;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    const skillEvents = await readSkillInvocations(taskId);
+    return {
+        exceptions_by_gate,
+        decisions_count,
+        skill_invocations: skillEvents.map((e) => ({ skill: e.skill, gate: e.gate })),
+    };
+}
+/**
+ * Build + append a scorecard for a completed run. Called from sign_off when RG
+ * is signed. Best-effort by contract: callers MUST NOT let a ledger failure
+ * break a sign-off (telemetry is never load-bearing for the gate).
+ */
+export async function recordRunScorecard(state) {
+    const extras = await readSideCounts(state.task_id);
+    await appendScorecard(buildScorecard(state, extras));
+}

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,127 @@
+#!/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. Pass task_id (+ optional gate) to log the fetch as a skill invocation for Auditor telemetry; omit for plain lookups.",
+    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.",
+    audit_budget_compliance: "Audit budget_lines compliance for agent.md and SKILL.md across a domain. Surfaces schema-cap violations (declared > schema max) and budget violations (actual lines > declared budget). Pass domain='*' to scan all domains. Read-only; scans both RU and EN locales.",
+    audit_bilocale_parity: "Audit RU/EN locale parity for agent.md and SKILL.md across a domain. Pairs each file with its sibling in the other locale and surfaces declared-budget mismatches (ru budget_lines != en), actual line-count mismatches (ru lines != en — the design-intake drift class), and orphans (file present in one locale only). Pass domain='*' to scan all domains. Read-only.",
+    aggregate_run_metrics: "Aggregate completed-run scorecards from the local audit ledger (.code-ai/state/audit/runs.jsonl) into deterministic per-agent (gate→role), per-workflow (mode), and per-skill (invocation frequency) statistics. min_runs (default 3) guards small samples. Read-only; the Auditor's data foundation — numbers only, no judgment.",
+    propose_change: "Record an Auditor proposal (a draft change to an agent/skill) as a pending entry in the local proposal store (.code-ai/state/audit/proposals.jsonl). Carries change_kind (edit_minor/add_asset/destructive → risk tier), rationale, evidence, threshold_met, and the inline draft. Pure surfacing — writes nothing to the asset; inert until approved/applied (item 4b).",
+    list_proposals: "List stored Auditor proposals, newest first, with optional filters (status / risk / domain). Read-only.",
+    review_proposal: "Authorize a proposal status transition (approve/reject a pending one; mark an approved one applied) and get a mandatory report. Enforces the autonomy matrix + .code-ai/config.json approval gate: decided_by='auditor_auto' may approve only low/additive AND only when the gate is OFF; destructive (high) and gate-ON always require den. Auto-adding a new skill also runs an additive-dedup guard — if it overlaps an existing skill it is routed to den, not auto-added. Authorization only — the byte write into the asset is a separate submit_artifact/edit step (see next_step).",
+    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 };