@contorium/mcp 0.8.1

package/README.md

@@ -0,0 +1,97 @@
+# @contorium/mcp
+
+Standard MCP server for **Claude Code · Cursor · Codex · Gemini CLI**.
+
+## Install
+
+```bash
+# global
+npm install -g @contorium/mcp
+
+# or one-shot
+npx @contorium/mcp
+```
+
+Monorepo dev (this repo):
+
+```bash
+cd packages/mcp && npm run build
+npx contorium-mcp --workspace /path/to/project
+```
+
+## Publish to npm
+
+Only **one** npm package is required: `@contorium/mcp`.  
+`@contora/state-core` is **bundled inside** the tarball (no separate `@contora` org needed).
+
+```bash
+npm login                    # once
+npm run publish:npm          # publish @contorium/mcp
+npm run publish:npm:dry-run  # validate tarball without login
+```
+
+## Bootstrap (without starting stdio server)
+
+Pre-sync `.contora` and schedule dashboard before opening the AI host:
+
+```bash
+npx contorium-mcp bootstrap --workspace /path/to/your-project
+# or after global install:
+contorium-mcp bootstrap
+```
+
+## Start (stdio MCP server)
+
+```bash
+npx contorium-mcp
+# or with explicit workspace
+npx contorium-mcp --workspace E:/your-project
+```
+
+**Workspace priority:** `--workspace` → `CONTORIUM_WORKSPACE` → `.mcp.json` → current directory.
+
+## MCP host config
+
+### Cursor / Claude (`.mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "contorium": {
+      "command": "npx",
+      "args": ["@contorium/mcp"],
+      "env": {
+        "CONTORIUM_WORKSPACE": "E:/your-project"
+      }
+    }
+  }
+}
+```
+
+### Codex (`config.toml`)
+
+```toml
+[mcp_servers.contorium]
+command = "npx"
+args = ["@contorium/mcp"]
+env = { CONTORIUM_WORKSPACE = "." }
+```
+
+## Standard tools (MCP v1)
+
+| Tool | Purpose |
+|------|---------|
+| `get_handoff_injection_status` | Semi-auto new-chat prompt |
+| `confirm_handoff_injection` | User confirmed (Y) |
+| `skip_handoff_injection` | User declined (N) |
+| `get_project_handoff` | CHP v1 AI memory (compact / markdown / json) |
+| `get_recent_changes` | File & function updates |
+| `get_understanding_graph` | Call chains + impact |
+| `get_runtime_state` | Bootstrap / dashboard / session |
+
+Legacy tools (`get_project_change`, `get_project_graph`, …) remain available.
+
+## Requirements
+
+- Node.js 18+
+- Optional: `@contora/cli` (`npm i -g @contora/cli`) for dashboard bootstrap when not in monorepo

package/bin/contorium-mcp.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+/**
+
+ * @contorium/mcp — standard npm entry (npx contorium-mcp / npx @contorium/mcp)
+
+ * Workspace: --workspace > CONTORIUM_WORKSPACE > .mcp.json > cwd
+
+ *
+
+ * Subcommands:
+
+ *   contorium-mcp bootstrap [--workspace PATH]  — sync .contora + schedule dashboard (no stdio server)
+
+ *   contorium-mcp                               — start MCP stdio server (default)
+
+ */
+
+const sub = process.argv[2];
+
+if (sub === 'bootstrap') {
+
+  const { runMcpBootstrapCli } = await import('../dist/bootstrapCli.js');
+
+  await runMcpBootstrapCli(process.argv.slice(2));
+
+} else {
+
+  const { startMcpServer } = await import('../dist/server.js');
+
+  await startMcpServer();
+
+}
+

package/dist/autoContext.d.ts

@@ -0,0 +1,2 @@
+/** @deprecated Use readConfirmedHandoffContext from @contora/state-core — only present after user confirms injection. */
+export { readConfirmedHandoffContext as readMcpAutoContext } from '@contora/state-core';

package/dist/autoContext.js

@@ -0,0 +1,2 @@
+/** @deprecated Use readConfirmedHandoffContext from @contora/state-core — only present after user confirms injection. */
+export { readConfirmedHandoffContext as readMcpAutoContext } from '@contora/state-core';

package/dist/bootstrapCli.d.ts

@@ -0,0 +1,2 @@
+/** `contorium-mcp bootstrap` — one-shot runtime sync without starting stdio MCP. */
+export declare function runMcpBootstrapCli(argv: string[]): Promise<void>;

package/dist/bootstrapCli.js

@@ -0,0 +1,21 @@
+import { prepareHandoffInjection, syncWorkspaceState } from '@contora/state-core';
+import { scheduleMcpRuntimeBootstrap } from './dashboardEnsure.js';
+import { findWorkspaceRoot, initWorkspaceFromArgv, resolveWorkspaceRoot } from './paths.js';
+/** `contorium-mcp bootstrap` — one-shot runtime sync without starting stdio MCP. */
+export async function runMcpBootstrapCli(argv) {
+    initWorkspaceFromArgv(argv);
+    const hint = resolveWorkspaceRoot();
+    const root = await findWorkspaceRoot(hint);
+    console.error(`[contorium-mcp] bootstrap workspace: ${root}`);
+    const result = await syncWorkspaceState(root, 'mcp', { forceArtifacts: true });
+    scheduleMcpRuntimeBootstrap(root);
+    const prep = await prepareHandoffInjection(root);
+    console.error(`[contorium-mcp] bootstrap: mode=${result.mode} artifacts=${result.created ? 'created' : 'updated'}`);
+    if (prep.shouldPrompt) {
+        console.error('[contorium-mcp] handoff: pending — new AI chat will auto-prompt (Enter/i · n skip in terminal, [?] in IDE)');
+    }
+    else if (prep.alreadyInjected) {
+        console.error('[contorium-mcp] handoff: already injected for this runtime');
+    }
+    console.error('[contorium-mcp] bootstrap complete — configure MCP host to spawn contorium-mcp for stdio server');
+}

package/dist/conflicts.d.ts

@@ -0,0 +1,19 @@
+export interface McpStateConflictSource {
+    source: string;
+    detail: string;
+}
+export interface McpStateConflict {
+    id: string;
+    type: string;
+    title: string;
+    sources: McpStateConflictSource[];
+    status: string;
+    action: string;
+    detectedAt: number;
+}
+export interface McpConflictsArtifact {
+    version: number;
+    generatedAt: number;
+    conflicts: McpStateConflict[];
+}
+export declare function loadStateConflicts(workspaceRoot: string): Promise<McpConflictsArtifact | null>;

package/dist/conflicts.js

@@ -0,0 +1,49 @@
+import * as fs from 'node:fs/promises';
+import { conflictsFile } from './paths.js';
+export async function loadStateConflicts(workspaceRoot) {
+    const fp = conflictsFile(workspaceRoot);
+    try {
+        const text = await fs.readFile(fp, 'utf8');
+        const o = JSON.parse(text);
+        if (!o || o.version !== 1) {
+            return null;
+        }
+        const conflicts = [];
+        if (Array.isArray(o.conflicts)) {
+            for (const item of o.conflicts) {
+                if (!item || typeof item !== 'object') {
+                    continue;
+                }
+                const c = item;
+                const sources = [];
+                if (Array.isArray(c.sources)) {
+                    for (const s of c.sources) {
+                        if (s && typeof s === 'object' && typeof s.detail === 'string') {
+                            sources.push({
+                                source: String(s.source ?? 'unknown'),
+                                detail: s.detail,
+                            });
+                        }
+                    }
+                }
+                conflicts.push({
+                    id: typeof c.id === 'string' ? c.id : 'conf_unknown',
+                    type: typeof c.type === 'string' ? c.type : 'unknown',
+                    title: typeof c.title === 'string' ? c.title : 'Conflict',
+                    sources,
+                    status: typeof c.status === 'string' ? c.status : 'UNRESOLVED',
+                    action: typeof c.action === 'string' ? c.action : 'Developer review required',
+                    detectedAt: typeof c.detectedAt === 'number' ? c.detectedAt : 0,
+                });
+            }
+        }
+        return {
+            version: 1,
+            generatedAt: typeof o.generatedAt === 'number' ? o.generatedAt : 0,
+            conflicts,
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/dashboardEnsure.d.ts

@@ -0,0 +1,10 @@
+export interface CliSpawnPlan {
+    command: string;
+    args: string[];
+}
+/** Resolve contorium CLI for bootstrap/wake — monorepo dev or global/npx when published. */
+export declare function resolveContoriumSpawn(subcommand: string, workspaceRoot: string, extraArgs?: string[]): CliSpawnPlan;
+/** CRBP — MCP client initialize → bootstrap runtime attach. */
+export declare function scheduleMcpRuntimeBootstrap(workspaceRoot: string): void;
+/** Activity update after bootstrap (file/git events). */
+export declare function scheduleMcpDashboardWake(workspaceRoot: string, detail?: string): void;

package/dist/dashboardEnsure.js

@@ -0,0 +1,41 @@
+import { spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Resolve contorium CLI for bootstrap/wake — monorepo dev or global/npx when published. */
+export function resolveContoriumSpawn(subcommand, workspaceRoot, extraArgs = []) {
+    const root = path.resolve(workspaceRoot);
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const monorepoCli = path.resolve(here, '../../cli/bin/contorium.cjs');
+    if (fs.existsSync(monorepoCli)) {
+        return {
+            command: process.execPath,
+            args: [monorepoCli, subcommand, root, ...extraArgs],
+        };
+    }
+    return {
+        command: process.platform === 'win32' ? 'npx.cmd' : 'npx',
+        args: ['contorium', subcommand, root, ...extraArgs],
+    };
+}
+function spawnDetached(plan) {
+    const useShell = process.platform === 'win32' && !plan.args[0]?.endsWith('.cjs');
+    spawn(plan.command, plan.args, {
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true,
+        shell: useShell,
+    }).unref();
+}
+/** CRBP — MCP client initialize → bootstrap runtime attach. */
+export function scheduleMcpRuntimeBootstrap(workspaceRoot) {
+    spawnDetached(resolveContoriumSpawn('bootstrap', workspaceRoot, ['--source', 'mcp']));
+}
+/** Activity update after bootstrap (file/git events). */
+export function scheduleMcpDashboardWake(workspaceRoot, detail) {
+    const extra = ['--source', 'mcp'];
+    if (detail) {
+        extra.push('--detail', detail);
+    }
+    spawnDetached(resolveContoriumSpawn('dashboard', workspaceRoot, ['wake', ...extra]));
+}

package/dist/intelligence.d.ts

@@ -0,0 +1,16 @@
+export interface McpStateSummary {
+    version: number;
+    generatedAt: number;
+    project_intent: string;
+    current_focus: string;
+    active_domains: string[];
+    active_problem_area: string;
+    activity_clusters: Array<{
+        cluster: string;
+        files: string[];
+        weight: number;
+    }>;
+    next_likely_actions: string[];
+    confidence: number;
+}
+export declare function loadProjectIntelligence(workspaceRoot: string): Promise<McpStateSummary | null>;

package/dist/intelligence.js

@@ -0,0 +1,38 @@
+import * as fs from 'node:fs/promises';
+import { stateSummaryFile } from './paths.js';
+export async function loadProjectIntelligence(workspaceRoot) {
+    const fp = stateSummaryFile(workspaceRoot);
+    try {
+        const text = await fs.readFile(fp, 'utf8');
+        const o = JSON.parse(text);
+        if (!o || typeof o !== 'object' || o.version !== 1) {
+            return null;
+        }
+        return {
+            version: 1,
+            generatedAt: typeof o.generatedAt === 'number' ? o.generatedAt : 0,
+            project_intent: typeof o.project_intent === 'string' ? o.project_intent : '',
+            current_focus: typeof o.current_focus === 'string' ? o.current_focus : '',
+            active_domains: Array.isArray(o.active_domains)
+                ? o.active_domains.filter((x) => typeof x === 'string')
+                : [],
+            active_problem_area: typeof o.active_problem_area === 'string' ? o.active_problem_area : '',
+            activity_clusters: Array.isArray(o.activity_clusters)
+                ? o.activity_clusters
+                    .filter((x) => !!x && typeof x === 'object')
+                    .map((c) => ({
+                    cluster: typeof c.cluster === 'string' ? c.cluster : '',
+                    files: Array.isArray(c.files) ? c.files.filter((f) => typeof f === 'string') : [],
+                    weight: typeof c.weight === 'number' ? c.weight : 0,
+                }))
+                : [],
+            next_likely_actions: Array.isArray(o.next_likely_actions)
+                ? o.next_likely_actions.filter((x) => typeof x === 'string')
+                : [],
+            confidence: typeof o.confidence === 'number' ? o.confidence : 0,
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/intentGraph.d.ts

@@ -0,0 +1,20 @@
+export interface McpIntentGraph {
+    version: number;
+    updatedAt: number;
+    nodes: Array<{
+        id: string;
+        text: string;
+        status: string;
+        confidence: number;
+        relatedFiles: string[];
+        lastUpdated: number;
+        learnedAt: number;
+    }>;
+    edges: Array<{
+        from: string;
+        to: string;
+        type: string;
+    }>;
+}
+export declare function loadIntentGraph(workspaceRoot: string): Promise<McpIntentGraph | null>;
+export declare function activeIntentNodes(graph: McpIntentGraph, max?: number): McpIntentGraph['nodes'];

package/dist/intentGraph.js

@@ -0,0 +1,51 @@
+import * as fs from 'node:fs/promises';
+import { intentGraphFile } from './paths.js';
+export async function loadIntentGraph(workspaceRoot) {
+    const fp = intentGraphFile(workspaceRoot);
+    try {
+        const text = await fs.readFile(fp, 'utf8');
+        const o = JSON.parse(text);
+        if (!o || typeof o !== 'object' || o.version !== 1) {
+            return null;
+        }
+        return {
+            version: 1,
+            updatedAt: typeof o.updatedAt === 'number' ? o.updatedAt : 0,
+            nodes: Array.isArray(o.nodes)
+                ? o.nodes
+                    .filter((x) => !!x && typeof x === 'object')
+                    .map((n) => ({
+                    id: typeof n.id === 'string' ? n.id : '',
+                    text: typeof n.text === 'string' ? n.text : '',
+                    status: typeof n.status === 'string' ? n.status : 'PARTIAL',
+                    confidence: typeof n.confidence === 'number' ? n.confidence : 0,
+                    relatedFiles: Array.isArray(n.relatedFiles)
+                        ? n.relatedFiles.filter((f) => typeof f === 'string')
+                        : [],
+                    lastUpdated: typeof n.lastUpdated === 'number' ? n.lastUpdated : 0,
+                    learnedAt: typeof n.learnedAt === 'number' ? n.learnedAt : 0,
+                }))
+                    .filter((n) => n.id && n.text)
+                : [],
+            edges: Array.isArray(o.edges)
+                ? o.edges
+                    .filter((x) => !!x && typeof x === 'object')
+                    .map((e) => ({
+                    from: typeof e.from === 'string' ? e.from : '',
+                    to: typeof e.to === 'string' ? e.to : '',
+                    type: typeof e.type === 'string' ? e.type : 'RELATED_TO',
+                }))
+                    .filter((e) => e.from && e.to)
+                : [],
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function activeIntentNodes(graph, max = 8) {
+    return graph.nodes
+        .filter((n) => n.status === 'ACTIVE' || n.status === 'WEAKENING' || n.status === 'PARTIAL')
+        .sort((a, b) => b.confidence - a.confidence)
+        .slice(0, max);
+}

package/dist/mcpBootstrap.d.ts

@@ -0,0 +1,8 @@
+/** MCP startup bootstrap. */
+export declare function ensureWorkspaceBootstrapped(workspaceRoot: string): Promise<{
+    bootstrapped: boolean;
+    mode: string;
+}>;
+/** Light sync: 5s poll + watch events dir and git HEAD. */
+export declare function startMcpLightSync(workspaceRoot: string): void;
+export declare function stopMcpLightSync(): void;

package/dist/mcpBootstrap.js

@@ -0,0 +1,81 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { syncWorkspaceState } from '@contora/state-core';
+import { scheduleMcpDashboardWake } from './dashboardEnsure.js';
+import { checkActiveRuntime, confirmHandoffInjection, readHandoffInjectionState, syncInjectionWithRuntime, } from '@contora/state-core';
+const CONTORA_EVENTS = '.contora/events';
+const SYNC_MS = 5_000;
+const DEBOUNCE_MS = 400;
+let syncTimer;
+let debounceTimer;
+let eventsWatcher;
+let gitHeadWatcher;
+function scheduleReactiveSync(workspaceRoot) {
+    if (debounceTimer) {
+        clearTimeout(debounceTimer);
+    }
+    debounceTimer = setTimeout(() => {
+        debounceTimer = undefined;
+        void syncWorkspaceState(workspaceRoot, 'mcp')
+            .then(async () => {
+            scheduleMcpDashboardWake(workspaceRoot, 'mcp-reactive-sync');
+            await syncInjectionWithRuntime(workspaceRoot);
+            const { runtime_id } = await checkActiveRuntime(workspaceRoot);
+            const injection = await readHandoffInjectionState(workspaceRoot);
+            if (runtime_id &&
+                injection?.runtime_id === runtime_id &&
+                injection.status === 'injected') {
+                await confirmHandoffInjection(workspaceRoot, injection.format ?? 'markdown');
+            }
+        })
+            .catch(() => undefined);
+    }, DEBOUNCE_MS);
+}
+/** MCP startup bootstrap. */
+export async function ensureWorkspaceBootstrapped(workspaceRoot) {
+    const result = await syncWorkspaceState(workspaceRoot, 'mcp', { forceArtifacts: true });
+    if (result.created) {
+        console.error('[contorium-mcp] bootstrap: created .contora/state.json (scan-driven)');
+    }
+    return { bootstrapped: result.created, mode: result.mode };
+}
+/** Light sync: 5s poll + watch events dir and git HEAD. */
+export function startMcpLightSync(workspaceRoot) {
+    stopMcpLightSync();
+    const root = path.resolve(workspaceRoot);
+    syncTimer = setInterval(() => {
+        void syncWorkspaceState(root, 'mcp').catch(() => undefined);
+    }, SYNC_MS);
+    syncTimer.unref?.();
+    const eventsDir = path.join(root, CONTORA_EVENTS);
+    try {
+        fs.mkdirSync(eventsDir, { recursive: true });
+        eventsWatcher = fs.watch(eventsDir, () => scheduleReactiveSync(root));
+        eventsWatcher.unref?.();
+    }
+    catch {
+        /* optional */
+    }
+    const gitHead = path.join(root, '.git', 'HEAD');
+    try {
+        gitHeadWatcher = fs.watch(gitHead, () => scheduleReactiveSync(root));
+        gitHeadWatcher.unref?.();
+    }
+    catch {
+        /* not a git repo */
+    }
+}
+export function stopMcpLightSync() {
+    if (syncTimer) {
+        clearInterval(syncTimer);
+        syncTimer = undefined;
+    }
+    if (debounceTimer) {
+        clearTimeout(debounceTimer);
+        debounceTimer = undefined;
+    }
+    eventsWatcher?.close();
+    eventsWatcher = undefined;
+    gitHeadWatcher?.close();
+    gitHeadWatcher = undefined;
+}

package/dist/memoryStore.d.ts

@@ -0,0 +1,18 @@
+export type MemoryEntryType = 'note' | 'decision' | 'architecture';
+export interface MemoryEntry {
+    value: string;
+    type: MemoryEntryType;
+    timestamp: number;
+}
+export interface MemoryFile {
+    version: 1;
+    entries: Record<string, MemoryEntry>;
+}
+export declare function storeMemory(workspaceRoot: string, key: string, value: string, type?: MemoryEntryType): Promise<{
+    success: true;
+    key: string;
+}>;
+export declare function getMemory(workspaceRoot: string, key: string): Promise<MemoryEntry | null>;
+export declare function searchMemory(workspaceRoot: string, query: string): Promise<Array<{
+    key: string;
+} & MemoryEntry>>;

package/dist/memoryStore.js

@@ -0,0 +1,57 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { mcpMemoryFile } from './paths.js';
+function emptyFile() {
+    return { version: 1, entries: {} };
+}
+async function loadFile(workspaceRoot) {
+    const fp = mcpMemoryFile(workspaceRoot);
+    try {
+        const raw = await fs.readFile(fp, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || !parsed.entries || typeof parsed.entries !== 'object') {
+            return emptyFile();
+        }
+        return { version: 1, entries: parsed.entries };
+    }
+    catch {
+        return emptyFile();
+    }
+}
+async function saveFile(workspaceRoot, data) {
+    const fp = mcpMemoryFile(workspaceRoot);
+    await fs.mkdir(path.dirname(fp), { recursive: true });
+    await fs.writeFile(fp, JSON.stringify(data, null, 2), 'utf8');
+}
+export async function storeMemory(workspaceRoot, key, value, type = 'note') {
+    const k = key.trim();
+    if (!k) {
+        throw new Error('key is required');
+    }
+    const file = await loadFile(workspaceRoot);
+    file.entries[k] = {
+        value,
+        type,
+        timestamp: Date.now(),
+    };
+    await saveFile(workspaceRoot, file);
+    return { success: true, key: k };
+}
+export async function getMemory(workspaceRoot, key) {
+    const file = await loadFile(workspaceRoot);
+    return file.entries[key.trim()] ?? null;
+}
+export async function searchMemory(workspaceRoot, query) {
+    const q = query.trim().toLowerCase();
+    if (!q) {
+        return [];
+    }
+    const file = await loadFile(workspaceRoot);
+    const results = [];
+    for (const [key, entry] of Object.entries(file.entries)) {
+        if (key.toLowerCase().includes(q) || entry.value.toLowerCase().includes(q)) {
+            results.push({ key, ...entry });
+        }
+    }
+    return results.sort((a, b) => b.timestamp - a.timestamp).slice(0, 32);
+}

package/dist/paths.d.ts

@@ -0,0 +1,12 @@
+/** Apply CLI --workspace before other resolution (call once at startup). */
+export declare function initWorkspaceFromArgv(argv?: string[]): string;
+/** Workspace root for MCP (priority: startup override → env → .mcp.json → cwd). */
+export declare function resolveWorkspaceRoot(): string;
+export declare function contoraDir(workspaceRoot: string): string;
+export declare function mcpMemoryFile(workspaceRoot: string): string;
+export declare function stateSummaryFile(workspaceRoot: string): string;
+export declare function intentGraphFile(workspaceRoot: string): string;
+export declare function projectStateFile(workspaceRoot: string): string;
+export declare function projectSnapshotFile(workspaceRoot: string): string;
+export declare function conflictsFile(workspaceRoot: string): string;
+export declare function findWorkspaceRoot(startDir: string): Promise<string>;

package/dist/paths.js

@@ -0,0 +1,66 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { resolveMcpStartupConfig, setStartupWorkspace } from './workspaceConfig.js';
+const CONTORA_DATA_DIR = '.contora';
+const LEGACY_DATA_DIR = '.context-recall';
+/** Apply CLI --workspace before other resolution (call once at startup). */
+export function initWorkspaceFromArgv(argv = process.argv.slice(2)) {
+    const config = resolveMcpStartupConfig(argv);
+    if (config.workspaceFromArgv) {
+        setStartupWorkspace(config.workspaceHint);
+    }
+    return config.workspaceHint;
+}
+/** Workspace root for MCP (priority: startup override → env → .mcp.json → cwd). */
+export function resolveWorkspaceRoot() {
+    const config = resolveMcpStartupConfig();
+    return config.workspaceHint;
+}
+export function contoraDir(workspaceRoot) {
+    return path.join(workspaceRoot, CONTORA_DATA_DIR);
+}
+export function mcpMemoryFile(workspaceRoot) {
+    return path.join(contoraDir(workspaceRoot), 'mcp', 'memories.json');
+}
+export function stateSummaryFile(workspaceRoot) {
+    return path.join(contoraDir(workspaceRoot), 'intelligence', 'state-summary.json');
+}
+export function intentGraphFile(workspaceRoot) {
+    return path.join(contoraDir(workspaceRoot), 'intent-graph', 'graph.json');
+}
+export function projectStateFile(workspaceRoot) {
+    return path.join(contoraDir(workspaceRoot), 'state-builder', 'project-state.json');
+}
+export function projectSnapshotFile(workspaceRoot) {
+    return path.join(contoraDir(workspaceRoot), 'state-builder', 'project-snapshot.md');
+}
+export function conflictsFile(workspaceRoot) {
+    return path.join(contoraDir(workspaceRoot), 'state-engine', 'conflicts.json');
+}
+export async function findWorkspaceRoot(startDir) {
+    let dir = path.resolve(startDir);
+    for (let i = 0; i < 12; i++) {
+        const primary = path.join(dir, CONTORA_DATA_DIR, 'state.json');
+        const legacy = path.join(dir, LEGACY_DATA_DIR, 'state.json');
+        try {
+            await fs.access(primary);
+            return dir;
+        }
+        catch {
+            /* continue */
+        }
+        try {
+            await fs.access(legacy);
+            return dir;
+        }
+        catch {
+            /* continue */
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            break;
+        }
+        dir = parent;
+    }
+    return path.resolve(startDir);
+}