codecartographer-pi 0.1.0 → 0.1.2

package/README.md

@@ -44,14 +44,18 @@ That's it. The LLM reads the guide, checks `workflow/status.yaml` for progress,
 
 This branch also packages CodeCartographer for [Pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) without changing `.codecarto/` itself. Pi is an **optional peer dependency** — if you only want the template or the MCP server, you don't need Pi installed.
 
-Install from a local checkout or git URL:
+Install from npm, a local checkout, or a git URL:
 
 ```bash
+pi install npm:codecartographer-pi
+# or, from a local checkout:
 pi install /absolute/path/to/CodeCartographer
-# or
+# or, from a git URL:
 pi install git:github.com/your-user/CodeCartographer
 ```
 
+> **Don't run `npm install codecartographer-pi` for the Pi use case.** Plain `npm install` puts the package on disk but doesn't register it with Pi, so it never appears in the TUI. Use `pi install npm:codecartographer-pi` instead — Pi handles the npm install internally and writes the package into its own `settings.json` (`~/.pi/agent/settings.json` by default). Plain `npm install` is the right command only for the MCP-server use case described below.
+
 For extension development, you can also point Pi directly at the extension entrypoint or place it in an auto-discovered extensions directory and use `/reload`:
 
 ```bash
@@ -84,6 +88,8 @@ What the Pi extension adds:
 
 The same framework is also packaged as a [Model Context Protocol](https://modelcontextprotocol.io) server, so any MCP-compatible host (Claude Code, Claude Desktop, etc.) can drive a CodeCartographer workflow without the Pi runtime. The server imports the same `core/` primitives the Pi extension uses, so phase prompts and validation are byte-identical across both surfaces.
 
+Implements MCP spec revision [`2025-11-25`](https://modelcontextprotocol.io/specification/2025-11-25) via `@modelcontextprotocol/sdk` ≥ 1.29.0. The negotiated `protocolVersion` reflects whatever the connecting client requests; the server accepts every revision the SDK supports (currently `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`, `2024-10-07`).
+
 Install and wire it up:
 
 ```bash

package/{core/index.ts → dist/core/index.d.ts}

@@ -1,7 +1,3 @@
-// Barrel re-export of the CodeCartographer framework core. Both wrappers
-// (extensions/codecarto for Pi, mcp-server for MCP) consume the framework
-// exclusively through this module.
-
 export * from "./types.ts";
 export * from "./utils.ts";
 export * from "./yaml.ts";

package/dist/core/index.js

@@ -0,0 +1,10 @@
+// Barrel re-export of the CodeCartographer framework core. Both wrappers
+// (extensions/codecarto for Pi, mcp-server for MCP) consume the framework
+// exclusively through this module.
+export * from "./types.js";
+export * from "./utils.js";
+export * from "./yaml.js";
+export * from "./status.js";
+export * from "./pipeline.js";
+export * from "./prompts.js";
+export * from "./workspace.js";

package/dist/core/pipeline.d.ts

@@ -0,0 +1,10 @@
+import type { PipelineFile, PipelinePhase, ValidationResult, WorkspaceState } from "./types.ts";
+export declare const PIPELINE_ALIASES: Record<string, string>;
+export declare const DEFAULT_PIPELINE_PATH = "workflow/pipeline-full-with-deep-audit.yaml";
+export declare function getPhaseMap(pipeline: PipelineFile): Map<string, PipelinePhase>;
+export declare function getPipelineLabel(pipelinePath: string): string;
+export declare function getNextEligiblePhase(state: WorkspaceState): PipelinePhase | null;
+export declare function resolvePhase(state: WorkspaceState, phaseId?: string): PipelinePhase | null;
+export declare function resolvePipelineChoice(input: string): string | null;
+export declare function validatePhaseOutput(state: WorkspaceState, phaseId?: string): Promise<ValidationResult>;
+export declare function buildValidationSummary(validation: ValidationResult): string[];

package/dist/core/pipeline.js

@@ -0,0 +1,160 @@
+// Pipeline alias resolution, DAG walking, and phase-output validation.
+import { readFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { pathExists } from "./utils.js";
+export const PIPELINE_ALIASES = {
+    "full-with-audit": "workflow/pipeline-full-with-audit.yaml",
+    "full-with-deep-audit": "workflow/pipeline-full-with-deep-audit.yaml",
+    full: "workflow/pipeline.yaml",
+    "defect-scan": "workflow/pipeline-defect-scan.yaml",
+    lite: "workflow/pipeline-lite.yaml",
+    "architecture-only": "workflow/pipeline-architecture-only.yaml",
+};
+export const DEFAULT_PIPELINE_PATH = "workflow/pipeline-full-with-deep-audit.yaml";
+export function getPhaseMap(pipeline) {
+    return new Map(pipeline.phases.map((phase) => [phase.id, phase]));
+}
+export function getPipelineLabel(pipelinePath) {
+    const fileName = basename(pipelinePath, ".yaml");
+    if (fileName === "pipeline")
+        return "full";
+    return fileName.replace(/^pipeline-/, "");
+}
+export function getNextEligiblePhase(state) {
+    const phaseMap = getPhaseMap(state.pipeline);
+    for (const phaseId of state.pipeline.phase_order) {
+        const phaseStatus = state.status.phases[phaseId]?.status;
+        if (phaseStatus === "complete")
+            continue;
+        const phase = phaseMap.get(phaseId);
+        if (!phase)
+            continue;
+        const dependencies = phase.depends_on ?? [];
+        const ready = dependencies.every((dependencyId) => state.status.phases[dependencyId]?.status === "complete");
+        if (ready)
+            return phase;
+    }
+    return null;
+}
+export function resolvePhase(state, phaseId) {
+    const trimmed = phaseId?.trim();
+    if (trimmed) {
+        return getPhaseMap(state.pipeline).get(trimmed) ?? null;
+    }
+    return getNextEligiblePhase(state);
+}
+export function resolvePipelineChoice(input) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        return null;
+    if (PIPELINE_ALIASES[trimmed])
+        return PIPELINE_ALIASES[trimmed];
+    return trimmed.endsWith(".yaml") ? trimmed : null;
+}
+export async function validatePhaseOutput(state, phaseId) {
+    const phase = resolvePhase(state, phaseId);
+    if (!phase) {
+        throw new Error(phaseId ? `Unknown phase: ${phaseId}` : "No eligible phase found.");
+    }
+    if (!phase.primary_output) {
+        throw new Error(`Phase ${phase.id} has no primary_output in the active pipeline.`);
+    }
+    const outputPath = join(state.workspaceDir, phase.primary_output);
+    if (!(await pathExists(outputPath))) {
+        return {
+            phaseId: phase.id,
+            primaryOutput: phase.primary_output,
+            outputPath,
+            exists: false,
+            hasValidationBlock: false,
+            overall: "MISSING",
+            rows: [],
+            gaps: [],
+            errors: [`Missing primary output: .codecarto/${phase.primary_output}`],
+        };
+    }
+    const content = await readFile(outputPath, "utf8");
+    const validationHeadingIndex = content.lastIndexOf("## Validation");
+    if (validationHeadingIndex === -1) {
+        return {
+            phaseId: phase.id,
+            primaryOutput: phase.primary_output,
+            outputPath,
+            exists: true,
+            hasValidationBlock: false,
+            overall: "FAIL",
+            rows: [],
+            gaps: [],
+            errors: ["Primary output exists but is missing a ## Validation block."],
+        };
+    }
+    const validationContent = content.slice(validationHeadingIndex);
+    const rows = [];
+    let overall = "FAIL";
+    for (const rawLine of validationContent.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (line.startsWith("|")) {
+            const cells = line
+                .split("|")
+                .slice(1, -1)
+                .map((cell) => cell.trim());
+            if (cells.length >= 4 && cells[0] !== "#" && !/^[-:]+$/.test(cells[0])) {
+                rows.push({
+                    criterion: cells[1] ?? "",
+                    result: cells[2] ?? "",
+                    evidence: cells[3] ?? "",
+                });
+            }
+        }
+        const overallMatch = line.match(/^\*\*Overall:\*\*\s*(.+)$/i);
+        if (overallMatch?.[1]) {
+            const normalizedOverall = overallMatch[1].trim().toUpperCase();
+            if (normalizedOverall === "PASS")
+                overall = "PASS";
+            else if (normalizedOverall === "PASS WITH GAPS")
+                overall = "PASS WITH GAPS";
+            else
+                overall = "FAIL";
+        }
+    }
+    const errors = [];
+    const gaps = rows
+        .filter((row) => row.result.toUpperCase().includes("PARTIAL"))
+        .map((row) => `${row.criterion}: ${row.evidence}`);
+    if (rows.length === 0) {
+        errors.push("Validation block found, but no validation rows could be parsed.");
+    }
+    if (rows.some((row) => row.result.toUpperCase().includes("FAIL"))) {
+        errors.push("One or more validation criteria are marked FAIL.");
+        overall = "FAIL";
+    }
+    if (overall === "FAIL" && errors.length === 0) {
+        errors.push("Validation overall result is FAIL.");
+    }
+    return {
+        phaseId: phase.id,
+        primaryOutput: phase.primary_output,
+        outputPath,
+        exists: true,
+        hasValidationBlock: true,
+        overall,
+        rows,
+        gaps,
+        errors,
+    };
+}
+export function buildValidationSummary(validation) {
+    const lines = [`Validation: ${validation.overall}`];
+    if (!validation.exists) {
+        lines.push(...validation.errors);
+        return lines;
+    }
+    lines.push(`Output: .codecarto/${validation.primaryOutput}`);
+    if (validation.gaps.length > 0) {
+        lines.push(`Gaps: ${validation.gaps.length}`);
+    }
+    if (validation.errors.length > 0) {
+        lines.push(...validation.errors.slice(0, 3));
+    }
+    return lines;
+}

package/dist/core/prompts.d.ts

@@ -0,0 +1,9 @@
+import type { CarryForwardEntry, OpenQuestionEntry, PipelinePhase, ValidationResult, WorkspaceState } from "./types.ts";
+export declare function describeEntry(entry: OpenQuestionEntry | CarryForwardEntry): string;
+export declare function collectRoutedCarryForward(state: WorkspaceState, targetPhaseId: string): CarryForwardEntry[];
+export declare function buildPhasePrompt(state: WorkspaceState, phase: PipelinePhase, forced: boolean): Promise<string>;
+export declare function closeoutFileName(date: string, phaseOrModule: string): string;
+export declare function buildThreadLogEntry(phaseOrModule: string, validation: ValidationResult, timestamp: string): string;
+export declare function ensureCloseoutStub(workspaceDir: string, phaseOrModule: string, timestamp: string): Promise<string | null>;
+export declare function listSkillNames(workspaceDir: string): Promise<string[]>;
+export declare function buildSkillPrompt(state: WorkspaceState, skillName: string): Promise<string>;

package/dist/core/prompts.js

@@ -0,0 +1,166 @@
+// Prompt builders + closeout/thread-log helpers. The phase prompt is the
+// single biggest fidelity surface — both Pi and the MCP server emit
+// byte-identical text by importing buildPhasePrompt from here.
+import { copyFile, mkdir, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { dateOnly, pathExists } from "./utils.js";
+export function describeEntry(entry) {
+    const parts = [];
+    if (entry.id)
+        parts.push(entry.id);
+    if (entry.kind)
+        parts.push(`(${entry.kind})`);
+    if (entry.description)
+        parts.push(entry.description);
+    else if (entry.deferred_reason)
+        parts.push(entry.deferred_reason);
+    return parts.join(" ").trim() || "(unlabeled entry)";
+}
+export function collectRoutedCarryForward(state, targetPhaseId) {
+    const routed = [];
+    for (const phase of Object.values(state.status.phases)) {
+        for (const entry of phase.carry_forward ?? []) {
+            if (entry.target_phase === targetPhaseId)
+                routed.push(entry);
+        }
+    }
+    return routed;
+}
+export async function buildPhasePrompt(state, phase, forced) {
+    const lines = [
+        `Read .codecarto/GUIDE.md and continue the CodeCartographer workflow for the phase \`${phase.id}\`.`,
+        `Work on this phase only. The analyzed source code is the repository outside .codecarto/.`,
+        "",
+        "Required reads before analysis:",
+        "- .codecarto/GUIDE.md",
+        "- .codecarto/workflow/status.yaml",
+    ];
+    const primaryOutput = phase.primary_output ? `.codecarto/${phase.primary_output}` : undefined;
+    if (primaryOutput) {
+        lines.push(`- ${primaryOutput} if it already exists (continue instead of duplicating work)`);
+    }
+    if (phase.skill_path)
+        lines.push(`- .codecarto/${phase.skill_path}`);
+    if (phase.output_template)
+        lines.push(`- .codecarto/${phase.output_template}`);
+    const staticReads = new Set(["GUIDE.md", "workflow/status.yaml"]);
+    const phaseReads = (phase.required_reads ?? []).filter((path) => path && !staticReads.has(path));
+    for (const path of phaseReads) {
+        lines.push(`- .codecarto/${path}`);
+    }
+    const conventionsPath = join(state.workspaceDir, "CONVENTIONS.md");
+    if (await pathExists(conventionsPath)) {
+        lines.push("- .codecarto/CONVENTIONS.md (cross-cutting patterns the orchestrator has promoted)");
+    }
+    const decisionsPath = join(state.workspaceDir, "DECISIONS.md");
+    if (await pathExists(decisionsPath)) {
+        lines.push("- .codecarto/DECISIONS.md (numbered project decisions; new entries are appended in your closeout)");
+    }
+    const routed = collectRoutedCarryForward(state, phase.id);
+    if (routed.length > 0) {
+        lines.push("", `Items routed to \`${phase.id}\` for closure (carry_forward from earlier phases):`);
+        for (const entry of routed) {
+            lines.push(`- ${describeEntry(entry)}`);
+        }
+        lines.push("Close each item by editing your phase output to address it, then remove the entry from the source phase's carry_forward in workflow/status.yaml.");
+    }
+    if (phase.id === "reimplementation-spec") {
+        lines.push("");
+        lines.push("Strategic Alignment Hook (run BEFORE producing the spec):");
+        lines.push("- Confirm with the user whether this spec should be language-agnostic or opinionated:");
+        lines.push("    - language-agnostic → use templates/reimplementation-spec.md (default).");
+        lines.push("    - opinionated (target stack locked) → use templates/reimplementation-spec-opinionated.md.");
+        lines.push("- Record the chosen variant in the spec front-matter and in your validation block.");
+    }
+    lines.push("", "Rules:");
+    lines.push("- Do not modify source files outside .codecarto/.");
+    lines.push("- Follow the active pipeline and validation protocol.");
+    lines.push("- Update findings under .codecarto/findings/ for this phase.");
+    lines.push("- Distinguish open_questions (genuinely unknown) from carry_forward (routed to a specific later phase) when updating workflow/status.yaml — see GUIDE.md \"Open Questions vs Carry-Forward\".");
+    if (forced) {
+        lines.push("- The user explicitly requested this phase even if it is not the next eligible phase.");
+    }
+    if (phase.depends_on && phase.depends_on.length > 0) {
+        const unmet = phase.depends_on.filter((dependencyId) => state.status.phases[dependencyId]?.status !== "complete");
+        if (unmet.length > 0) {
+            lines.push(`- Warning: dependencies not complete yet: ${unmet.join(", ")}`);
+        }
+    }
+    if (phase.handoff_requirements && phase.handoff_requirements.length > 0) {
+        lines.push("", "Handoff requirements (from the active pipeline):");
+        for (const requirement of phase.handoff_requirements) {
+            lines.push(`- ${requirement}`);
+        }
+    }
+    if (primaryOutput) {
+        lines.push("", `Primary output target: ${primaryOutput}`);
+    }
+    return lines.join("\n");
+}
+export function closeoutFileName(date, phaseOrModule) {
+    return `${date}-${phaseOrModule}.md`;
+}
+export function buildThreadLogEntry(phaseOrModule, validation, timestamp) {
+    const date = dateOnly(timestamp);
+    const file = closeoutFileName(date, phaseOrModule);
+    return `- ${date} — ${phaseOrModule} — Validation: ${validation.overall} — [closeout](closeouts/${file})\n`;
+}
+export async function ensureCloseoutStub(workspaceDir, phaseOrModule, timestamp) {
+    const date = dateOnly(timestamp);
+    const closeoutsDir = join(workspaceDir, "closeouts");
+    const closeoutPath = join(closeoutsDir, closeoutFileName(date, phaseOrModule));
+    if (await pathExists(closeoutPath))
+        return null;
+    const templatePath = join(workspaceDir, "templates", "closeout-template.md");
+    if (!(await pathExists(templatePath)))
+        return null;
+    await mkdir(closeoutsDir, { recursive: true });
+    await copyFile(templatePath, closeoutPath);
+    return closeoutPath;
+}
+export async function listSkillNames(workspaceDir) {
+    const skillsDir = join(workspaceDir, "skills");
+    if (!(await pathExists(skillsDir)))
+        return [];
+    try {
+        const entries = await readdir(skillsDir, { withFileTypes: true });
+        const names = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const skillFile = join(skillsDir, entry.name, "SKILL.md");
+            if (await pathExists(skillFile))
+                names.push(entry.name);
+        }
+        return names.sort();
+    }
+    catch {
+        return [];
+    }
+}
+export async function buildSkillPrompt(state, skillName) {
+    const lines = [
+        `Read .codecarto/GUIDE.md and run the post-pipeline skill \`${skillName}\`.`,
+        "This is post-pipeline work. The pipeline is `complete`. Do not change `current_phase` or `phase_order` in workflow/status.yaml.",
+        "",
+        "Required reads before starting:",
+        "- .codecarto/GUIDE.md",
+        "- .codecarto/workflow/status.yaml",
+        `- .codecarto/skills/${skillName}/SKILL.md`,
+    ];
+    const conventionsPath = join(state.workspaceDir, "CONVENTIONS.md");
+    if (await pathExists(conventionsPath)) {
+        lines.push("- .codecarto/CONVENTIONS.md (cross-cutting patterns the orchestrator has promoted)");
+    }
+    const decisionsPath = join(state.workspaceDir, "DECISIONS.md");
+    if (await pathExists(decisionsPath)) {
+        lines.push("- .codecarto/DECISIONS.md (numbered project decisions; new entries are appended in your closeout)");
+    }
+    lines.push("", "Rules:");
+    lines.push("- Do not modify source files outside .codecarto/.");
+    lines.push("- Follow the SKILL.md instructions exactly; the skill enforces its own discipline (see GUIDE.md).");
+    lines.push("- Update only the artifacts the skill calls for. Do NOT touch phase status entries.");
+    lines.push("- On completion, write a closeout at .codecarto/closeouts/<YYYY-MM-DD>-<skill-or-module>.md and append a one-line index entry to THREAD_LOG.md.");
+    lines.push("- If your work resolves entries in any phase's open_questions or carry_forward, remove only those resolved entries.");
+    return lines.join("\n");
+}

package/dist/core/status.d.ts

@@ -0,0 +1,12 @@
+import type { NormalizedStatus, OpenQuestionEntry, PipelineFile, StatusFile, StatusPhase } from "./types.ts";
+export declare const LOCK_RETRY_MS = 125;
+export declare const LOCK_TIMEOUT_MS = 5000;
+export declare const STALE_LOCK_MS = 60000;
+export declare function ensureArray(value: unknown): string[];
+export declare function ensureEntryArray<T extends OpenQuestionEntry>(value: unknown, allowTargetPhase?: boolean): T[];
+export declare function ensurePhaseRecord(value: unknown): Record<string, StatusPhase>;
+export declare function createEmptyStatus(projectName: string, pipelinePath: string, pipeline: PipelineFile): NormalizedStatus;
+export declare function normalizeStatus(status: StatusFile, pipeline: PipelineFile, pipelinePath: string, cwd: string): NormalizedStatus;
+export declare function acquireLock(lockPath: string): Promise<{
+    release: () => Promise<void>;
+}>;

package/dist/core/status.js

@@ -0,0 +1,143 @@
+// Status normalization, atomic writes, and file-lock primitives. Pure
+// framework logic shared by every wrapper.
+import { open, rm, stat } from "node:fs/promises";
+import { basename } from "node:path";
+import { sleep } from "./utils.js";
+export const LOCK_RETRY_MS = 125;
+export const LOCK_TIMEOUT_MS = 5000;
+export const STALE_LOCK_MS = 60_000;
+export function ensureArray(value) {
+    return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+}
+function coerceEntry(value, allowTargetPhase) {
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (!trimmed)
+            return null;
+        return { description: trimmed };
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const raw = value;
+    const entry = {};
+    if (typeof raw.id === "string" && raw.id.trim())
+        entry.id = raw.id.trim();
+    if (typeof raw.kind === "string" && raw.kind.trim())
+        entry.kind = raw.kind.trim();
+    if (typeof raw.description === "string" && raw.description.trim())
+        entry.description = raw.description.trim();
+    if (typeof raw.deferred_reason === "string" && raw.deferred_reason.trim())
+        entry.deferred_reason = raw.deferred_reason.trim();
+    if (allowTargetPhase && typeof raw.target_phase === "string" && raw.target_phase.trim())
+        entry.target_phase = raw.target_phase.trim();
+    return Object.keys(entry).length > 0 ? entry : null;
+}
+export function ensureEntryArray(value, allowTargetPhase = false) {
+    if (!Array.isArray(value))
+        return [];
+    const result = [];
+    for (const item of value) {
+        const coerced = coerceEntry(item, allowTargetPhase);
+        if (coerced)
+            result.push(coerced);
+    }
+    return result;
+}
+export function ensurePhaseRecord(value) {
+    if (!value || typeof value !== "object")
+        return {};
+    const record = value;
+    const result = {};
+    for (const [phaseId, phaseValue] of Object.entries(record)) {
+        const phase = (phaseValue ?? {});
+        result[phaseId] = {
+            status: typeof phase.status === "string" ? phase.status : "pending",
+            owner_notes: ensureArray(phase.owner_notes),
+            outputs_present: ensureArray(phase.outputs_present),
+            open_questions: ensureEntryArray(phase.open_questions, false),
+            carry_forward: ensureEntryArray(phase.carry_forward, true),
+        };
+    }
+    return result;
+}
+export function createEmptyStatus(projectName, pipelinePath, pipeline) {
+    const phases = {};
+    for (const phaseId of pipeline.phase_order) {
+        phases[phaseId] = {
+            status: "pending",
+            owner_notes: [],
+            outputs_present: [],
+            open_questions: [],
+            carry_forward: [],
+        };
+    }
+    const firstPhase = pipeline.phase_order[0] ?? "complete";
+    const phaseMap = new Map(pipeline.phases.map((phase) => [phase.id, phase]));
+    const firstPhaseConfig = phaseMap.get(firstPhase);
+    return {
+        project_name: projectName,
+        pipeline: pipelinePath,
+        current_phase: firstPhase,
+        last_updated: "",
+        phases,
+        next_actions: firstPhaseConfig?.primary_output
+            ? [`Begin ${firstPhase} phase by producing ${firstPhaseConfig.primary_output}`]
+            : ["Begin the first pending phase."],
+    };
+}
+export function normalizeStatus(status, pipeline, pipelinePath, cwd) {
+    const phases = ensurePhaseRecord(status.phases);
+    for (const phaseId of pipeline.phase_order) {
+        if (!phases[phaseId]) {
+            phases[phaseId] = {
+                status: "pending",
+                owner_notes: [],
+                outputs_present: [],
+                open_questions: [],
+                carry_forward: [],
+            };
+        }
+    }
+    return {
+        project_name: status.project_name?.trim() || basename(cwd),
+        pipeline: status.pipeline?.trim() || pipelinePath,
+        current_phase: status.current_phase?.trim() || pipeline.phase_order[0] || "complete",
+        last_updated: status.last_updated?.trim() || "",
+        phases,
+        next_actions: ensureArray(status.next_actions),
+    };
+}
+export async function acquireLock(lockPath) {
+    const startedAt = Date.now();
+    while (true) {
+        try {
+            const handle = await open(lockPath, "wx");
+            await handle.writeFile(`${process.pid}\n${new Date().toISOString()}\n`, "utf8");
+            await handle.close();
+            return {
+                release: async () => {
+                    await rm(lockPath, { force: true }).catch(() => undefined);
+                },
+            };
+        }
+        catch (error) {
+            const nodeError = error;
+            if (nodeError.code !== "EEXIST")
+                throw error;
+            try {
+                const lockStat = await stat(lockPath);
+                if (Date.now() - lockStat.mtimeMs > STALE_LOCK_MS) {
+                    await rm(lockPath, { force: true }).catch(() => undefined);
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+            if (Date.now() - startedAt > LOCK_TIMEOUT_MS) {
+                throw new Error(`Timed out waiting for lock: ${lockPath}`);
+            }
+            await sleep(LOCK_RETRY_MS);
+        }
+    }
+}

package/dist/core/types.d.ts

@@ -0,0 +1,77 @@
+export type PhaseStatusValue = "pending" | "complete" | "partial" | "in-progress";
+export declare const OPEN_QUESTION_KINDS: readonly ["needs-runtime-test", "needs-maintainer-decision", "needs-spec-ruling", "defer-to-phase", "needs-fixture-capture"];
+export type EntryKind = (typeof OPEN_QUESTION_KINDS)[number] | string;
+export type OpenQuestionEntry = {
+    id?: string;
+    kind?: EntryKind;
+    description?: string;
+    deferred_reason?: string;
+};
+export type CarryForwardEntry = OpenQuestionEntry & {
+    target_phase?: string;
+};
+export type StatusPhase = {
+    status: PhaseStatusValue | string;
+    owner_notes: string[];
+    outputs_present: string[];
+    open_questions: OpenQuestionEntry[];
+    carry_forward: CarryForwardEntry[];
+};
+export type StatusFile = {
+    project_name?: string;
+    pipeline?: string;
+    current_phase?: string;
+    last_updated?: string;
+    phases?: Record<string, StatusPhase>;
+    next_actions?: string[];
+};
+export type SecondaryOutput = {
+    path: string;
+    mode?: string;
+};
+export type PipelinePhase = {
+    id: string;
+    purpose?: string;
+    skill_path?: string;
+    output_template?: string;
+    depends_on?: string[];
+    primary_output?: string;
+    secondary_outputs?: SecondaryOutput[];
+    required_reads?: string[];
+    completion_criteria?: string[];
+    handoff_requirements?: string[];
+};
+export type PipelineFile = {
+    workflow_name?: string;
+    workflow_version?: number;
+    workflow_goal?: string;
+    source_location?: string;
+    validation_protocol?: string;
+    phase_order: string[];
+    phases: PipelinePhase[];
+};
+export type NormalizedStatus = Required<Pick<StatusFile, "project_name" | "pipeline" | "current_phase" | "last_updated" | "phases" | "next_actions">>;
+export type WorkspaceState = {
+    cwd: string;
+    workspaceDir: string;
+    statusPath: string;
+    pipelinePath: string;
+    status: NormalizedStatus;
+    pipeline: PipelineFile;
+};
+export type ValidationOverall = "PASS" | "PASS WITH GAPS" | "FAIL" | "MISSING";
+export type ValidationResult = {
+    phaseId: string;
+    primaryOutput: string;
+    outputPath: string;
+    exists: boolean;
+    hasValidationBlock: boolean;
+    overall: ValidationOverall;
+    rows: Array<{
+        criterion: string;
+        result: string;
+        evidence: string;
+    }>;
+    gaps: string[];
+    errors: string[];
+};

package/dist/core/types.js

@@ -0,0 +1,10 @@
+// Shared schema types for the CodeCartographer framework.
+// Both the Pi extension and the MCP server import from here so the schema
+// has a single source of truth.
+export const OPEN_QUESTION_KINDS = [
+    "needs-runtime-test",
+    "needs-maintainer-decision",
+    "needs-spec-ruling",
+    "defer-to-phase",
+    "needs-fixture-capture",
+];

package/dist/core/utils.d.ts

@@ -0,0 +1,8 @@
+export declare function sleep(ms: number): Promise<void>;
+export declare function pathExists(path: string): Promise<boolean>;
+export declare function canonicalPath(path: string): Promise<string>;
+export declare function normalizeForComparison(path: string): string;
+export declare function isWithinPath(path: string, root: string): boolean;
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+export declare function uniqueStrings(items: string[]): string[];
+export declare function dateOnly(timestamp: string): string;