code-ai-installer 3.0.0 → 4.0.1-a

package/dist/mcp/config.d.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { DomainId } from "../shared/index.js";
+/**
+ * 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";
+    }>>;
+    domain: z.ZodDefault<z.ZodEnum<{
+        development: "development";
+        content: "content";
+        analytics: "analytics";
+        product: "product";
+    }>>;
+    mempalace_command: z.ZodDefault<z.ZodString>;
+    mempalace_args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    auditor: z.ZodDefault<z.ZodObject<{
+        approval_gate: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, 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>;
+/**
+ * The active domain for this project — which `pipeline.yaml` the gate tools
+ * (classify_gate, advance_gate, current_gate, sign_off, record_decision,
+ * aggregate_run_metrics) read. Sourced from `.code-ai/config.json`; defaults to
+ * "development" when unset.
+ *
+ * This is an ADDRESS, not a safety control: gate enforcement (no skipping,
+ * sign-off-before-advance, classify-required, circuit breaker) lives in the
+ * tool logic + the domain's `pipeline.yaml`, not in this string. De-hardcoding
+ * the address only makes each project read its OWN pipeline instead of always
+ * development's.
+ */
+export declare function resolveActiveDomain(): Promise<DomainId>;
+export {};

package/dist/mcp/config.js

@@ -0,0 +1,84 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { DomainId } from "../shared/index.js";
+/**
+ * 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"),
+    /**
+     * The active domain — which `domains/<domain>/pipeline.yaml` the gate tools
+     * read. Written by the installer at install time. Defaults to "development"
+     * for backward compatibility: a project with no `domain` field (or no config
+     * file at all) behaves exactly as before this field existed.
+     */
+    domain: DomainId.default("development"),
+    /** 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"]),
+    /** Auditor self-improvement controls (ADR-DEV-124). */
+    auditor: z
+        .object({
+        /**
+         * Approval gate. true (default) = Auditor proposes, a human approves every change.
+         * false = autonomy on: the Auditor may self-approve low/additive changes; destructive
+         * always still needs a human (ADR-DEV-122 matrix). Enforced in review_proposal.
+         */
+        approval_gate: z.boolean().default(true),
+    })
+        .default({ approval_gate: true }),
+});
+/** Empty config defaults — returned when the file is missing or unreadable. */
+const DEFAULT_CONFIG = {
+    decision_store: "jsonl",
+    mempalace_command: "mempalace",
+    mempalace_args: ["mcp"],
+    auditor: { approval_gate: true },
+    domain: "development",
+};
+/**
+ * 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;
+    }
+}
+/**
+ * The active domain for this project — which `pipeline.yaml` the gate tools
+ * (classify_gate, advance_gate, current_gate, sign_off, record_decision,
+ * aggregate_run_metrics) read. Sourced from `.code-ai/config.json`; defaults to
+ * "development" when unset.
+ *
+ * This is an ADDRESS, not a safety control: gate enforcement (no skipping,
+ * sign-off-before-advance, classify-required, circuit breaker) lives in the
+ * tool logic + the domain's `pipeline.yaml`, not in this string. De-hardcoding
+ * the address only makes each project read its OWN pipeline instead of always
+ * development's.
+ */
+export async function resolveActiveDomain() {
+    return (await loadCodeAiConfig()).domain;
+}

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,14 @@
+/**
+ * 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 architectural overview.
+ */
+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,16 @@
+/**
+ * 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 architectural overview.
+ */
+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,38 @@
+import { type DomainId } from "../shared/index.js";
+export declare const INSTALLER_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;
+/**
+ * Universal base-persona markdown for a domain. Shipped inside the package at
+ * `domains/<domain>/persona/persona-base.md` (was `docs/architecture-redesign/`
+ * pre-migration, which never shipped to npm). Same content across domains.
+ */
+export declare function resolvePersonaBase(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;
+/**
+ * Audit run-ledger path. Same cwd-relative convention as resolveTaskStateRoot()
+ * so the Auditor reads the user-install's local history; tests chdir into a tmp
+ * dir. Append-only JSONL, one run scorecard per line.
+ */
+export declare function resolveAuditLedgerPath(): string;
+/** Skill-invocation telemetry log. Same cwd-relative convention as the run ledger. */
+export declare function resolveSkillInvocationsPath(): string;
+/**
+ * Auditor proposal store. Same cwd-relative convention as the run ledger;
+ * append-only JSONL, one proposal per line. Written by propose_change, read by
+ * list_proposals (and later the approval/apply machinery, item 4b).
+ */
+export declare function resolveProposalsPath(): string;

package/dist/mcp/paths.js

@@ -0,0 +1,77 @@
+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 — everything the runtime reads ships under it).
+ *
+ * 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, "..", "..");
+/**
+ * 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);
+}
+/**
+ * Universal base-persona markdown for a domain. Shipped inside the package at
+ * `domains/<domain>/persona/persona-base.md` (was `docs/architecture-redesign/`
+ * pre-migration, which never shipped to npm). Same content across domains.
+ */
+export function resolvePersonaBase(domain) {
+    return join(resolveDomainRoot(domain), "persona", "persona-base.md");
+}
+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");
+}
+/**
+ * Audit run-ledger path. Same cwd-relative convention as resolveTaskStateRoot()
+ * so the Auditor reads the user-install's local history; tests chdir into a tmp
+ * dir. Append-only JSONL, one run scorecard per line.
+ */
+export function resolveAuditLedgerPath() {
+    return join(process.cwd(), ".code-ai", "state", "audit", "runs.jsonl");
+}
+/** Skill-invocation telemetry log. Same cwd-relative convention as the run ledger. */
+export function resolveSkillInvocationsPath() {
+    return join(process.cwd(), ".code-ai", "state", "skill_invocations.jsonl");
+}
+/**
+ * Auditor proposal store. Same cwd-relative convention as the run ledger;
+ * append-only JSONL, one proposal per line. Written by propose_change, read by
+ * list_proposals (and later the approval/apply machinery, item 4b).
+ */
+export function resolveProposalsPath() {
+    return join(process.cwd(), ".code-ai", "state", "audit", "proposals.jsonl");
+}

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/proposal_dedup.d.ts

@@ -0,0 +1,32 @@
+import { type DomainId } from "../shared/index.js";
+export interface SkillMeta {
+    name: string;
+    topic: string[];
+    tech: string[];
+    related: string[];
+}
+export interface DedupOverlap {
+    skill: string;
+    reasons: string[];
+}
+/**
+ * Read each SKILL.md frontmatter in a domain (name + topic/tech/related). Narrow reader — it does
+ * NOT change list_skills' public contract; 4c just needs fields list_skills doesn't surface.
+ * Tolerant: a folder without SKILL.md or with bad frontmatter is skipped.
+ */
+export declare function readDomainSkillMeta(domain: DomainId): Promise<SkillMeta[]>;
+/**
+ * Overlap of an additive (new-skill) proposal against existing domain skills (ADR-DEV-125, Plan A).
+ * Pure + deterministic — callers inject the skill list (readDomainSkillMeta in prod, fixtures in tests).
+ *
+ * A skill is flagged when ANY of:
+ *   - exact name match, OR
+ *   - shares a name token AND a vocab term with the skill's topic/tech, OR
+ *   - near-duplicate name (one name contains the other), OR
+ *   - the skill's related[] already lists the proposed name.
+ */
+export declare function findOverlaps(args: {
+    proposalName: string;
+    text: string;
+    skills: SkillMeta[];
+}): DedupOverlap[];

package/dist/mcp/proposal_dedup.js

@@ -0,0 +1,102 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { SkillFrontmatter, TechSeed, TopicSeed } from "../shared/index.js";
+import { resolveSkillsRoot } from "./paths.js";
+/**
+ * Read each SKILL.md frontmatter in a domain (name + topic/tech/related). Narrow reader — it does
+ * NOT change list_skills' public contract; 4c just needs fields list_skills doesn't surface.
+ * Tolerant: a folder without SKILL.md or with bad frontmatter is skipped.
+ */
+export async function readDomainSkillMeta(domain) {
+    const root = resolveSkillsRoot(domain);
+    const dirs = await readdir(root, { withFileTypes: true }).catch(() => []);
+    const out = [];
+    for (const d of dirs) {
+        if (!d.isDirectory())
+            continue;
+        const raw = await readFile(join(root, d.name, "SKILL.md"), "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;
+        let fm;
+        try {
+            fm = SkillFrontmatter.safeParse(parseYaml(m[1]));
+        }
+        catch {
+            continue;
+        }
+        if (!fm.success)
+            continue;
+        out.push({
+            name: fm.data.name,
+            topic: fm.data.topic ?? [],
+            tech: fm.data.tech ?? [],
+            related: fm.data.related ?? [],
+        });
+    }
+    return out;
+}
+/** Generic kebab tokens that carry no disambiguating signal — ignored in name overlap. */
+const NAME_STOPWORDS = new Set([
+    "workflow", "skill", "review", "guide", "reference", "setup", "and", "the", "a",
+]);
+function nameTokens(name) {
+    return new Set(name
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length > 1 && !NAME_STOPWORDS.has(t)));
+}
+/** Controlled-vocab terms (TechSeed/TopicSeed) that appear as whole tokens in free text. */
+function vocabTermsInText(text) {
+    const tokens = new Set(text.toLowerCase().split(/[^a-z0-9_-]+/).filter(Boolean));
+    const found = new Set();
+    for (const t of [...TechSeed.options, ...TopicSeed.options]) {
+        if (tokens.has(t))
+            found.add(t);
+    }
+    return found;
+}
+/**
+ * Overlap of an additive (new-skill) proposal against existing domain skills (ADR-DEV-125, Plan A).
+ * Pure + deterministic — callers inject the skill list (readDomainSkillMeta in prod, fixtures in tests).
+ *
+ * A skill is flagged when ANY of:
+ *   - exact name match, OR
+ *   - shares a name token AND a vocab term with the skill's topic/tech, OR
+ *   - near-duplicate name (one name contains the other), OR
+ *   - the skill's related[] already lists the proposed name.
+ */
+export function findOverlaps(args) {
+    const pTokens = nameTokens(args.proposalName);
+    const pVocab = vocabTermsInText(args.text);
+    const pNameLc = args.proposalName.toLowerCase();
+    const overlaps = [];
+    for (const s of args.skills) {
+        const sNameLc = s.name.toLowerCase();
+        if (sNameLc === pNameLc) {
+            overlaps.push({ skill: s.name, reasons: ["exact name match"] });
+            continue;
+        }
+        const reasons = [];
+        const sTokens = nameTokens(s.name);
+        const sharedName = [...pTokens].filter((t) => sTokens.has(t));
+        const sMeta = new Set([...s.topic, ...s.tech]);
+        const sharedVocab = [...pVocab].filter((v) => sMeta.has(v));
+        if (sharedName.length > 0 && sharedVocab.length > 0) {
+            reasons.push(`shares name token(s) [${sharedName.join(", ")}] and topic/tech [${sharedVocab.join(", ")}]`);
+        }
+        if (pNameLc.includes(sNameLc) || sNameLc.includes(pNameLc)) {
+            reasons.push("near-duplicate name (one contains the other)");
+        }
+        if (s.related.includes(args.proposalName)) {
+            reasons.push("already referenced in this skill's related[]");
+        }
+        if (reasons.length > 0)
+            overlaps.push({ skill: s.name, reasons });
+    }
+    return overlaps;
+}

package/dist/mcp/proposal_store.d.ts

@@ -0,0 +1,18 @@
+import { ProposalRecord, ProposalReviewEvent } from "../shared/index.js";
+type ProposalRecordT = ReturnType<typeof ProposalRecord.parse>;
+type ProposalReviewEventT = ReturnType<typeof ProposalReviewEvent.parse>;
+/** Append one proposal as a JSON line (creates the audit dir if needed). */
+export declare function appendProposal(record: ProposalRecordT): Promise<void>;
+/** Append a status-transition event (event-sourcing; never rewrites the original record). */
+export declare function appendReviewEvent(event: ProposalReviewEventT): Promise<void>;
+/**
+ * All proposals with their EFFECTIVE status (latest review event folded in). The on-disk
+ * record is never mutated — folding happens on read. list_proposals consumes this.
+ */
+export declare function readProposals(): Promise<ProposalRecordT[]>;
+/**
+ * Next sequential id, derived from the count of base proposal RECORDS (not raw lines, so
+ * review events never inflate the counter): prop-0001, prop-0002, …
+ */
+export declare function nextProposalId(): Promise<string>;
+export {};

package/dist/mcp/proposal_store.js

@@ -0,0 +1,74 @@
+import { mkdir, readFile, appendFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { ProposalRecord, ProposalReviewEvent } from "../shared/index.js";
+import { resolveProposalsPath } from "./paths.js";
+/** Append one proposal as a JSON line (creates the audit dir if needed). */
+export async function appendProposal(record) {
+    const path = resolveProposalsPath();
+    await mkdir(dirname(path), { recursive: true });
+    await appendFile(path, JSON.stringify(record) + "\n", "utf8");
+}
+/** Append a status-transition event (event-sourcing; never rewrites the original record). */
+export async function appendReviewEvent(event) {
+    const path = resolveProposalsPath();
+    await mkdir(dirname(path), { recursive: true });
+    await appendFile(path, JSON.stringify(event) + "\n", "utf8");
+}
+/**
+ * Read+classify every line as a base proposal record or a review event. A line that parses
+ * as neither is skipped (tolerant, like the run ledger). Records are tried first; a review
+ * event lacks the record's required fields so it can never be misread as a record.
+ */
+async function readEntries() {
+    const raw = await readFile(resolveProposalsPath(), "utf8").catch(() => "");
+    const records = [];
+    const events = [];
+    if (!raw)
+        return { records, events };
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const rec = ProposalRecord.safeParse(obj);
+        if (rec.success) {
+            records.push(rec.data);
+            continue;
+        }
+        const ev = ProposalReviewEvent.safeParse(obj);
+        if (ev.success)
+            events.push(ev.data);
+        // else: skip
+    }
+    return { records, events };
+}
+/**
+ * All proposals with their EFFECTIVE status (latest review event folded in). The on-disk
+ * record is never mutated — folding happens on read. list_proposals consumes this.
+ */
+export async function readProposals() {
+    const { records, events } = await readEntries();
+    const latest = new Map();
+    for (const e of events) {
+        const prev = latest.get(e.id);
+        if (!prev || e.reviewed_at >= prev.reviewed_at)
+            latest.set(e.id, e);
+    }
+    return records.map((r) => {
+        const e = latest.get(r.id);
+        return e ? { ...r, status: e.status } : r;
+    });
+}
+/**
+ * Next sequential id, derived from the count of base proposal RECORDS (not raw lines, so
+ * review events never inflate the counter): prop-0001, prop-0002, …
+ */
+export async function nextProposalId() {
+    const { records } = await readEntries();
+    return `prop-${String(records.length + 1).padStart(4, "0")}`;
+}