@contorium/mcp 0.8.1

package/node_modules/@contora/state-core/dist/understanding/formatCanonicalExport.js

@@ -0,0 +1,363 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeGraphRef = normalizeGraphRef;
+exports.formatNextActionPlain = formatNextActionPlain;
+exports.formatAiHandoffExecutionBlock = formatAiHandoffExecutionBlock;
+exports.formatCanonicalAiMarkdown = formatCanonicalAiMarkdown;
+function norm(s) {
+    return s.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+function textsSimilar(a, b) {
+    const na = norm(a);
+    const nb = norm(b);
+    if (!na || !nb) {
+        return false;
+    }
+    return na === nb || na.includes(nb) || nb.includes(na);
+}
+function basenamePath(p) {
+    const parts = p.replace(/\\/g, '/').split('/').filter(Boolean);
+    return parts[parts.length - 1] ?? p;
+}
+/** Machine-stable graph ref: fn:name, cls:name, mod:path */
+function normalizeGraphRef(ref) {
+    const t = ref.trim();
+    if (!t) {
+        return t;
+    }
+    const colon = t.indexOf(':');
+    if (colon > 0) {
+        const kind = t.slice(0, colon).toLowerCase();
+        const name = t.slice(colon + 1);
+        if (kind === 'function' || kind === 'fn') {
+            return `fn:${name}`;
+        }
+        if (kind === 'class' || kind === 'cls') {
+            return `cls:${name}`;
+        }
+        if (kind === 'module' || kind === 'mod') {
+            return `mod:${name}`;
+        }
+        return `${kind}:${name}`;
+    }
+    return `fn:${t}`;
+}
+/** Plain next line for canonical export (no [action] tags). */
+function formatNextActionPlain(a) {
+    const target = (a.target || '').trim();
+    const reason = (a.reason || '').trim();
+    if (!reason || norm(reason) === norm(target)) {
+        return target || reason;
+    }
+    if (reason.toLowerCase().startsWith(target.toLowerCase())) {
+        return reason;
+    }
+    if (target.toLowerCase().startsWith(reason.toLowerCase())) {
+        return target;
+    }
+    return target ? `${target}` : reason;
+}
+function listSection(title, items, empty) {
+    if (!items.length) {
+        return empty ? [title, empty] : [];
+    }
+    return [title, ...items.map((i) => `- ${i}`)];
+}
+function formatSnapshotFromBuilt(built) {
+    const lines = [];
+    const goal = built.project_goal.trim();
+    const stage = built.current_stage.trim();
+    if (goal) {
+        lines.push(`goal: ${goal}`);
+    }
+    if (stage) {
+        lines.push(`stage: ${stage}`);
+    }
+    if (built.active_modules.length) {
+        if (lines.length) {
+            lines.push('');
+        }
+        lines.push(...listSection('modules:', built.active_modules.slice(0, 12).map(basenamePath)));
+    }
+    if (built.completed_milestones.length) {
+        lines.push('');
+        lines.push(...listSection('milestones:', built.completed_milestones.slice(0, 8).map((m) => m.slice(0, 120))));
+    }
+    if (built.open_problems.length) {
+        lines.push('');
+        lines.push(...listSection('open_problems:', built.open_problems.slice(0, 6).map((p) => p.slice(0, 160))));
+    }
+    if (built.next_actions.length) {
+        lines.push('');
+        lines.push(...listSection('next_actions:', built.next_actions.slice(0, 6)));
+    }
+    return lines;
+}
+/** Fallback when only legacy snapshot markdown is available. */
+function formatSnapshotFromMarkdown(md) {
+    const lines = md.replace(/\r\n/g, '\n').split('\n');
+    const out = [];
+    let section = '';
+    const buckets = {
+        goal: [],
+        stage: [],
+        modules: [],
+        milestones: [],
+        open_problems: [],
+        next_actions: [],
+    };
+    const pushItem = (key, item) => {
+        const t = item.trim();
+        if (t && !buckets[key].includes(t)) {
+            buckets[key].push(t);
+        }
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const t = lines[i].trim();
+        if (/^goal:?\s*$/i.test(t)) {
+            section = 'goal';
+            continue;
+        }
+        if (/^current stage:?\s*$/i.test(t)) {
+            section = 'stage';
+            continue;
+        }
+        if (/^active modules:?\s*$/i.test(t)) {
+            section = 'modules';
+            continue;
+        }
+        if (/^completed milestones:?\s*$/i.test(t)) {
+            section = 'milestones';
+            continue;
+        }
+        if (/^open problems:?\s*$/i.test(t)) {
+            section = 'open_problems';
+            continue;
+        }
+        if (/^next actions:?\s*$/i.test(t)) {
+            section = 'next_actions';
+            continue;
+        }
+        if (t.startsWith('- ')) {
+            const item = t.slice(2).trim();
+            if (section && section in buckets) {
+                pushItem(section, item);
+            }
+            continue;
+        }
+        if (section === 'goal' && t && !t.startsWith('-')) {
+            pushItem('goal', t.replace(/^goal:\s*/i, ''));
+            section = '';
+            continue;
+        }
+        if (section === 'stage' && t && !t.startsWith('-')) {
+            pushItem('stage', t.replace(/^current stage:\s*/i, ''));
+            section = '';
+            continue;
+        }
+        if (/^goal:\s+/i.test(t)) {
+            pushItem('goal', t.replace(/^goal:\s*/i, ''));
+            continue;
+        }
+        if (/^stage:\s+/i.test(t)) {
+            pushItem('stage', t.replace(/^stage:\s*/i, ''));
+        }
+    }
+    if (buckets.goal[0]) {
+        out.push(`goal: ${buckets.goal[0]}`);
+    }
+    if (buckets.stage[0]) {
+        out.push(`stage: ${buckets.stage[0]}`);
+    }
+    if (buckets.modules.length) {
+        out.push('');
+        out.push(...listSection('modules:', buckets.modules));
+    }
+    if (buckets.milestones.length) {
+        out.push('');
+        out.push(...listSection('milestones:', buckets.milestones));
+    }
+    if (buckets.open_problems.length) {
+        out.push('');
+        out.push(...listSection('open_problems:', buckets.open_problems));
+    }
+    if (buckets.next_actions.length) {
+        out.push('');
+        out.push(...listSection('next_actions:', buckets.next_actions));
+    }
+    return out;
+}
+function deriveExecutionFocus(handoff) {
+    const focus = handoff.current_focus.trim();
+    const goal = handoff.goal.trim();
+    if (focus && !textsSimilar(focus, goal)) {
+        return focus;
+    }
+    const files = new Set();
+    for (const k of handoff.key_changes) {
+        if (k.kind === 'file') {
+            files.add(basenamePath(k.symbol));
+        }
+        else {
+            const f = k.symbol.split('::')[0];
+            if (f) {
+                files.add(basenamePath(f));
+            }
+        }
+    }
+    const fileList = [...files].slice(0, 2);
+    const fnCount = handoff.key_changes.filter((k) => k.kind === 'function').length;
+    if (fileList.length) {
+        const mods = fileList.join(' + ');
+        return fnCount > 0 ? `${mods} modification (${fnCount} symbols)` : `${mods} modification`;
+    }
+    const parts = handoff.summary.split('|').map((p) => p.trim()).filter(Boolean);
+    const last = parts[parts.length - 1];
+    if (last && !/^goal:/i.test(last)) {
+        return last.replace(/^focus:\s*/i, '');
+    }
+    return focus || goal || 'continue current task';
+}
+/** V3.1 execution block — single AI decision entry (no duplicate snapshot lists). */
+function formatAiHandoffExecutionBlock(handoff) {
+    const lines = ['# AI HANDOFF (V3.1)'];
+    const goal = handoff.goal.trim();
+    const focus = deriveExecutionFocus(handoff);
+    const risk = handoff.impact_summary.risk;
+    if (goal) {
+        lines.push(`goal: ${goal}`);
+    }
+    const execFocus = deriveExecutionFocus(handoff);
+    if (execFocus) {
+        lines.push(`focus: ${execFocus}`);
+    }
+    lines.push(`risk: ${risk}`);
+    if (handoff.next_actions.length) {
+        lines.push('next:');
+        const seen = new Set();
+        for (const a of handoff.next_actions.slice(0, 6)) {
+            const plain = formatNextActionPlain(a);
+            const key = norm(plain);
+            if (!plain || seen.has(key)) {
+                continue;
+            }
+            seen.add(key);
+            lines.push(`- ${plain}`);
+        }
+    }
+    return lines.join('\n');
+}
+function collectModifiedSymbols(handoff) {
+    const out = [];
+    const seen = new Set();
+    for (const k of handoff.key_changes) {
+        if (k.kind === 'function' || k.kind === 'class') {
+            const sym = k.symbol.trim();
+            if (sym && !seen.has(sym)) {
+                seen.add(sym);
+                out.push(sym);
+            }
+        }
+    }
+    return out.slice(0, 12);
+}
+function formatCognitiveSnapshotSection(snap) {
+    const lines = ['# COGNITIVE SNAPSHOT'];
+    if (snap.topIntents.length) {
+        lines.push(...listSection('top_intents:', snap.topIntents));
+    }
+    if (snap.topHotspots.length) {
+        lines.push(...listSection('top_hotspots:', snap.topHotspots));
+    }
+    if (snap.topFunctions.length) {
+        lines.push(...listSection('top_functions:', snap.topFunctions));
+    }
+    if (snap.nextActions.length) {
+        lines.push(...listSection('next_graph_actions:', snap.nextActions));
+    }
+    lines.push(`avg_confidence: ${snap.graphSummary.avgConfidence}`);
+    return lines;
+}
+/**
+ * V3.1 canonical markdown for IDE one-click copy (AI Mode).
+ * Layered: snapshot → working context → change/impact/graph → execution handoff → instruction.
+ */
+function formatCanonicalAiMarkdown(input) {
+    const lines = [];
+    lines.push('# TASK ANCHOR');
+    lines.push(input.taskAnchor.trim() || '(not set)');
+    lines.push('');
+    const snapLines = input.built
+        ? formatSnapshotFromBuilt(input.built)
+        : input.snapshotMarkdown?.trim()
+            ? formatSnapshotFromMarkdown(input.snapshotMarkdown)
+            : [];
+    if (snapLines.length) {
+        lines.push('# PROJECT SNAPSHOT');
+        lines.push(...snapLines);
+        lines.push('');
+    }
+    lines.push('# WORKING CONTEXT');
+    lines.push(...listSection('active_files:', input.activeFiles.length ? input.activeFiles : ['(none)']));
+    lines.push('');
+    lines.push(...listSection('recent_git_activity:', input.recentGitActivity.length ? input.recentGitActivity : ['(none)']));
+    lines.push('');
+    if (input.knowledgeSnapshot) {
+        lines.push(...formatCognitiveSnapshotSection(input.knowledgeSnapshot));
+        lines.push('');
+    }
+    const handoff = input.handoff;
+    if (handoff?.key_changes?.length) {
+        const modified = collectModifiedSymbols(handoff);
+        if (modified.length) {
+            lines.push('# CHANGE SET');
+            lines.push(...listSection('modified_symbols:', modified));
+            lines.push('');
+        }
+    }
+    if (handoff?.impact_summary.affected_functions.length) {
+        lines.push('# IMPACT SET');
+        lines.push(...listSection('impacted_symbols:', handoff.impact_summary.affected_functions.slice(0, 12)));
+        lines.push('');
+    }
+    const graphRefs = input.knowledgeSnapshot
+        ? []
+        : (handoff?.context_graph_refs ?? []).map(normalizeGraphRef).filter(Boolean);
+    if (graphRefs.length) {
+        lines.push('# GRAPH REFS');
+        for (const ref of graphRefs.slice(0, 12)) {
+            lines.push(`- ${ref}`);
+        }
+        lines.push('');
+    }
+    if (handoff && (handoff.summary || handoff.current_focus || handoff.next_actions.length)) {
+        lines.push(formatAiHandoffExecutionBlock(handoff));
+        lines.push('');
+    }
+    const recent = input.timeline?.recent ?? [];
+    if (recent.length) {
+        lines.push('# CODE EVOLUTION');
+        for (const e of recent.slice(0, 5)) {
+            const syms = e.changes.map((c) => c.symbol).join(', ') || e.type;
+            lines.push(`- ${e.commit} · ${basenamePath(e.file)} · ${syms} (${e.impact_level})`);
+        }
+        lines.push('');
+    }
+    if (input.insights?.length) {
+        lines.push('# INSIGHTS');
+        for (const line of input.insights.slice(0, 4)) {
+            lines.push(`- ${line}`);
+        }
+        lines.push('');
+    }
+    const notes = (input.notes ?? '').trim();
+    if (notes && notes !== '(none)') {
+        lines.push('# NOTES');
+        lines.push(notes);
+        lines.push('');
+    }
+    lines.push('# INSTRUCTION');
+    lines.push(input.instruction.trim() || '(none)');
+    lines.push('');
+    return lines.join('\n');
+}

package/node_modules/@contora/state-core/dist/understanding/formatHandoff.d.ts

@@ -0,0 +1,20 @@
+import type { HandoffArtifact, HandoffNextAction, ProjectTimeline } from './types.js';
+import type { KnowledgeSnapshot } from './knowledgeGraph/types.js';
+/** Single Next bullet — drops redundant "target: reason" when they repeat or overlap. */
+export declare function formatNextActionBullet(a: HandoffNextAction): string;
+/** CLI handoff markdown — execution block + optional timeline. */
+export declare function formatHandoffMarkdown(handoff: HandoffArtifact, timeline?: ProjectTimeline): string;
+/** Compact JSON export bundle for CLI `contorium export --format json`. */
+export declare function buildUnderstandingExportJson(args: {
+    handoff: HandoffArtifact;
+    timeline?: ProjectTimeline;
+    projectSnapshot?: string;
+    knowledgeSnapshot?: KnowledgeSnapshot;
+}): {
+    version: string;
+    projectSnapshot: string | undefined;
+    cognitiveSnapshot: KnowledgeSnapshot | undefined;
+    handoff: HandoffArtifact;
+    timeline: import("./types.js").TimelineEntry[] | undefined;
+};
+//# sourceMappingURL=formatHandoff.d.ts.map

package/node_modules/@contora/state-core/dist/understanding/formatHandoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatHandoff.d.ts","sourceRoot":"","sources":["../../src/understanding/formatHandoff.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACtF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAOnE,yFAAyF;AACzF,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAqBnE;AAED,kEAAkE;AAClE,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,eAAe,EACxB,QAAQ,CAAC,EAAE,eAAe,GACzB,MAAM,CAgBR;AAED,2EAA2E;AAC3E,wBAAgB,4BAA4B,CAAC,IAAI,EAAE;IACjD,OAAO,EAAE,eAAe,CAAC;IACzB,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CACvC;;;;;;EAQA"}

package/node_modules/@contora/state-core/dist/understanding/formatHandoff.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatNextActionBullet = formatNextActionBullet;
+exports.formatHandoffMarkdown = formatHandoffMarkdown;
+exports.buildUnderstandingExportJson = buildUnderstandingExportJson;
+const formatCanonicalExport_js_1 = require("./formatCanonicalExport.js");
+function normalizeNextText(s) {
+    return s.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+/** Single Next bullet — drops redundant "target: reason" when they repeat or overlap. */
+function formatNextActionBullet(a) {
+    const action = a.action;
+    const target = (a.target || '').trim();
+    const reason = (a.reason || '').trim();
+    const nt = normalizeNextText(target);
+    const nr = normalizeNextText(reason);
+    if (!target && !reason) {
+        return `- [${action}] (unspecified)`;
+    }
+    if (!reason || nr === nt) {
+        return `- [${action}] ${target || reason}`;
+    }
+    if (nr.startsWith(nt) || nt.startsWith(nr)) {
+        const text = reason.length >= target.length ? reason : target;
+        return `- [${action}] ${text}`;
+    }
+    if (reason.toLowerCase().startsWith(target.toLowerCase())) {
+        return `- [${action}] ${reason}`;
+    }
+    return `- [${action}] ${target}: ${reason}`;
+}
+/** CLI handoff markdown — execution block + optional timeline. */
+function formatHandoffMarkdown(handoff, timeline) {
+    const lines = [(0, formatCanonicalExport_js_1.formatAiHandoffExecutionBlock)(handoff)];
+    const recent = timeline?.recent ?? [];
+    if (recent.length) {
+        lines.push('');
+        lines.push('# CODE EVOLUTION');
+        for (const e of recent.slice(0, 5)) {
+            const syms = e.changes.map((c) => c.symbol).join(', ') || e.type;
+            const file = e.file.replace(/\\/g, '/').split('/').pop() ?? e.file;
+            lines.push(`- ${e.commit} · ${file} · ${syms} (${e.impact_level})`);
+        }
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+/** Compact JSON export bundle for CLI `contorium export --format json`. */
+function buildUnderstandingExportJson(args) {
+    return {
+        version: 'v3.1',
+        projectSnapshot: args.projectSnapshot,
+        cognitiveSnapshot: args.knowledgeSnapshot,
+        handoff: args.handoff,
+        timeline: args.timeline?.recent?.slice(0, 5),
+    };
+}

package/node_modules/@contora/state-core/dist/understanding/graphBuilder.d.ts

@@ -0,0 +1,9 @@
+import type { ProjectGraph } from './types.js';
+import type { ChangeArtifact } from './types.js';
+import { type FileExtraction } from './extractor.js';
+export declare function buildChangeNeighborhoodGraph(workspaceRoot: string, changedFiles: string[], now?: number): Promise<{
+    graph: ProjectGraph;
+    extractions: Map<string, FileExtraction>;
+}>;
+export declare function deriveChangeArtifact(changedFiles: string[], extractions: Map<string, FileExtraction>, now?: number): ChangeArtifact;
+//# sourceMappingURL=graphBuilder.d.ts.map

package/node_modules/@contora/state-core/dist/understanding/graphBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphBuilder.d.ts","sourceRoot":"","sources":["../../src/understanding/graphBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAwB,YAAY,EAAE,MAAM,YAAY,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAa,MAAM,YAAY,CAAC;AAE5D,OAAO,EAKL,KAAK,cAAc,EACpB,MAAM,gBAAgB,CAAC;AAUxB,wBAAsB,4BAA4B,CAChD,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,EAAE,EACtB,GAAG,SAAa,GACf,OAAO,CAAC;IAAE,KAAK,EAAE,YAAY,CAAC;IAAC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;CAAE,CAAC,CA8E5E;AAED,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,MAAM,EAAE,EACtB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,EACxC,GAAG,SAAa,GACf,cAAc,CAqBhB"}

package/node_modules/@contora/state-core/dist/understanding/graphBuilder.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildChangeNeighborhoodGraph = buildChangeNeighborhoodGraph;
+exports.deriveChangeArtifact = deriveChangeArtifact;
+const types_js_1 = require("./types.js");
+const extractor_js_1 = require("./extractor.js");
+const symbolValidator_js_1 = require("./symbolValidator.js");
+const MAX_NODES = 240;
+const MAX_NEIGHBOR_FILES = 12;
+function moduleNodeId(file) {
+    return (0, extractor_js_1.nodeId)(file, 'module', file);
+}
+async function buildChangeNeighborhoodGraph(workspaceRoot, changedFiles, now = Date.now()) {
+    const extractions = new Map();
+    const neighborFiles = new Set(changedFiles);
+    for (const file of changedFiles) {
+        const ext = await (0, extractor_js_1.extractFile)(workspaceRoot, file);
+        if (!ext) {
+            continue;
+        }
+        extractions.set(file, (0, symbolValidator_js_1.refineExtraction)(ext));
+        for (const sym of ext.symbols) {
+            if (sym.kind === 'import' && sym.importTarget) {
+                const resolved = (0, extractor_js_1.resolveRelativeImport)(file, sym.importTarget);
+                if (resolved && neighborFiles.size < changedFiles.length + MAX_NEIGHBOR_FILES) {
+                    neighborFiles.add(resolved);
+                }
+            }
+        }
+    }
+    for (const file of neighborFiles) {
+        if (extractions.has(file)) {
+            continue;
+        }
+        const ext = await (0, extractor_js_1.extractFile)(workspaceRoot, file);
+        if (ext) {
+            extractions.set(file, (0, symbolValidator_js_1.refineExtraction)(ext));
+        }
+    }
+    const nodes = [];
+    const edges = [];
+    for (const [file, ext] of extractions) {
+        nodes.push({ id: moduleNodeId(file), kind: 'module', name: file, file });
+        for (const sym of ext.symbols) {
+            const id = (0, extractor_js_1.nodeId)(file, sym.kind, sym.name);
+            if (sym.kind === 'function' || sym.kind === 'class') {
+                nodes.push({ id, kind: sym.kind, name: sym.name, file, line: sym.line });
+                edges.push({ from: moduleNodeId(file), to: id, kind: 'contains' });
+            }
+            else if (sym.kind === 'import') {
+                nodes.push({ id, kind: 'import', name: sym.name, file, line: sym.line });
+                edges.push({ from: moduleNodeId(file), to: id, kind: 'imports' });
+            }
+        }
+    }
+    for (const [file, ext] of extractions) {
+        const localFns = new Set((0, extractor_js_1.symbolNamesByKind)(ext, 'function'));
+        for (const call of ext.calls) {
+            if (!localFns.has(call)) {
+                continue;
+            }
+            const fromCandidates = ext.symbols.filter((s) => s.kind === 'function');
+            for (const caller of fromCandidates) {
+                const fromId = (0, extractor_js_1.nodeId)(file, 'function', caller.name);
+                const toId = (0, extractor_js_1.nodeId)(file, 'function', call);
+                if (fromId !== toId) {
+                    edges.push({ from: fromId, to: toId, kind: 'calls' });
+                }
+            }
+        }
+    }
+    const cappedNodes = nodes.slice(0, MAX_NODES);
+    const nodeIds = new Set(cappedNodes.map((n) => n.id));
+    const cappedEdges = edges.filter((e) => nodeIds.has(e.from) && nodeIds.has(e.to)).slice(0, MAX_NODES * 2);
+    return {
+        graph: {
+            version: 2,
+            generatedAt: now,
+            scope: 'change-neighborhood',
+            nodes: cappedNodes,
+            edges: cappedEdges,
+        },
+        extractions,
+    };
+}
+function deriveChangeArtifact(changedFiles, extractions, now = Date.now()) {
+    const key_changes = [];
+    for (const file of changedFiles) {
+        key_changes.push({ symbol: file, kind: 'file', change_type: 'modified' });
+        const ext = extractions.get(file);
+        if (!ext) {
+            continue;
+        }
+        for (const fn of (0, extractor_js_1.symbolNamesByKind)(ext, 'function')) {
+            key_changes.push({ symbol: `${file}::${fn}`, kind: 'function', change_type: 'modified' });
+        }
+        for (const cls of (0, extractor_js_1.symbolNamesByKind)(ext, 'class')) {
+            key_changes.push({ symbol: `${file}::${cls}`, kind: 'class', change_type: 'modified' });
+        }
+    }
+    return {
+        version: types_js_1.UNDERSTANDING_VERSION,
+        generatedAt: now,
+        changed_files: changedFiles,
+        key_changes,
+    };
+}

package/node_modules/@contora/state-core/dist/understanding/handoffBuilder.d.ts

@@ -0,0 +1,12 @@
+import type { ChangeArtifact, HandoffArtifact, ImpactAnalysis, IntentFusion, ProjectGraph } from './types.js';
+import type { ProjectBuiltState } from '../state-builder/types.js';
+export declare function buildHandoff(args: {
+    goal: string;
+    intent: IntentFusion;
+    change: ChangeArtifact;
+    impact: ImpactAnalysis;
+    graph: ProjectGraph;
+    built?: ProjectBuiltState | null;
+    now?: number;
+}): HandoffArtifact;
+//# sourceMappingURL=handoffBuilder.d.ts.map

package/node_modules/@contora/state-core/dist/understanding/handoffBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoffBuilder.d.ts","sourceRoot":"","sources":["../../src/understanding/handoffBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EAEf,cAAc,EACd,YAAY,EACZ,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAuEnE,wBAAgB,YAAY,CAAC,IAAI,EAAE;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,eAAe,CAsClB"}

package/node_modules/@contora/state-core/dist/understanding/handoffBuilder.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildHandoff = buildHandoff;
+const types_js_1 = require("./types.js");
+function inferAction(text) {
+    const t = text.toLowerCase();
+    if (/fix|bug|error|issue/.test(t)) {
+        return 'fix';
+    }
+    if (/refactor|clean|rename/.test(t)) {
+        return 'refactor';
+    }
+    if (/add|extend|implement|new feature/.test(t)) {
+        return 'extend';
+    }
+    if (/review|check|verify|audit/.test(t)) {
+        return 'review';
+    }
+    return 'continue';
+}
+function buildNextActions(built, impact, goal) {
+    const fromBuilt = (built?.next_actions ?? [])
+        .filter(Boolean)
+        .slice(0, 6)
+        .map((line) => {
+        const trimmed = line.trim();
+        return {
+            action: inferAction(trimmed),
+            target: trimmed,
+            reason: '',
+        };
+    });
+    if (fromBuilt.length) {
+        return fromBuilt;
+    }
+    const out = [];
+    if (impact.risk === 'high') {
+        out.push({
+            action: 'review',
+            target: impact.affected_functions[0] ?? 'changed symbols',
+            reason: 'High impact risk detected in change neighborhood',
+        });
+    }
+    if (goal) {
+        out.push({ action: 'continue', target: 'project goal', reason: goal });
+    }
+    else {
+        out.push({
+            action: 'review',
+            target: 'recent changes',
+            reason: 'Review recent changes and continue the current task',
+        });
+    }
+    return out;
+}
+function graphRefs(graph, change) {
+    const names = new Set(change.key_changes
+        .filter((k) => k.kind !== 'file')
+        .map((k) => k.symbol.split('::').pop() ?? k.symbol));
+    const kindTag = (k) => (k === 'class' ? 'cls' : k === 'function' ? 'fn' : k);
+    return graph.nodes
+        .filter((n) => names.has(n.name))
+        .map((n) => `${kindTag(n.kind)}:${n.name}`)
+        .slice(0, 12);
+}
+function buildHandoff(args) {
+    const now = args.now ?? Date.now();
+    const next_actions = buildNextActions(args.built, args.impact, args.goal);
+    const context_graph_refs = graphRefs(args.graph, args.change);
+    const parts = [];
+    if (args.goal) {
+        parts.push(`Goal: ${args.goal}`);
+    }
+    parts.push(`Focus: ${args.intent.focus}`);
+    const fnChanges = args.change.key_changes.filter((k) => k.kind === 'function');
+    if (fnChanges.length) {
+        parts.push(`Changed: ${fnChanges.slice(0, 5).map((k) => k.symbol).join(', ')}`);
+    }
+    else if (args.change.changed_files.length) {
+        parts.push(`Changed files: ${args.change.changed_files.slice(0, 5).join(', ')}`);
+    }
+    if (args.impact.affected_functions.length) {
+        parts.push(`Impact (${args.impact.risk}): ${args.impact.affected_functions.slice(0, 4).join(', ')}`);
+    }
+    return {
+        version: types_js_1.UNDERSTANDING_VERSION,
+        generatedAt: now,
+        goal: args.goal,
+        current_focus: args.intent.focus,
+        key_changes: args.change.key_changes,
+        impact_summary: {
+            risk: args.impact.risk,
+            affected_modules: args.impact.affected_modules,
+            affected_functions: args.impact.affected_functions,
+            details: args.impact.details,
+        },
+        next_actions,
+        context_graph_refs,
+        summary: parts.join(' | '),
+    };
+}