mdkg 0.3.5 → 0.3.7

package/dist/commands/graph.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.runGraphCloneCommand = runGraphCloneCommand;
 exports.runGraphForkCommand = runGraphForkCommand;
 exports.runGraphImportTemplateCommand = runGraphImportTemplateCommand;
+exports.runGraphRefsCommand = runGraphRefsCommand;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const bundle_1 = require("./bundle");
@@ -14,15 +15,124 @@ const validate_1 = require("./validate");
 const config_1 = require("../core/config");
 const workspace_path_1 = require("../core/workspace_path");
 const indexer_1 = require("../graph/indexer");
+const index_cache_1 = require("../graph/index_cache");
 const frontmatter_1 = require("../graph/frontmatter");
 const errors_1 = require("../util/errors");
 const qid_1 = require("../util/qid");
 const atomic_1 = require("../util/atomic");
 const zip_1 = require("../util/zip");
 const lock_1 = require("../util/lock");
+const date_1 = require("../util/date");
+const refs_1 = require("../util/refs");
 function writeJson(value) {
     console.log(JSON.stringify(value, null, 2));
 }
+function toStringList(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((item) => typeof item === "string");
+}
+function summarizeNode(node) {
+    return {
+        qid: node.qid,
+        id: node.id,
+        workspace: node.ws,
+        type: node.type,
+        title: node.title,
+        status: node.status,
+        path: node.path,
+        read_only: Boolean(node.source?.read_only ?? node.source?.imported),
+        source: node.source,
+    };
+}
+function summarizeRef(index, value, ws) {
+    if ((0, refs_1.isUriRef)(value)) {
+        return {
+            ref: value,
+            kind: "uri",
+            exists: true,
+        };
+    }
+    const resolved = (0, qid_1.resolveQid)(index, value, ws);
+    if (resolved.status !== "ok") {
+        return {
+            ref: value,
+            kind: "missing",
+            exists: false,
+        };
+    }
+    const node = index.nodes[resolved.qid];
+    if (!node) {
+        return {
+            ref: value,
+            kind: "missing",
+            exists: false,
+            qid: resolved.qid,
+        };
+    }
+    return {
+        ref: value,
+        kind: "node",
+        exists: true,
+        qid: node.qid,
+        node: summarizeNode(node),
+    };
+}
+function summarizeRefs(index, values, ws) {
+    return [...new Set(values)].sort().map((value) => summarizeRef(index, value, ws));
+}
+function compactOutgoing(node) {
+    return {
+        scope_refs: toStringList(node.attributes.scope_refs),
+        epic: node.edges.epic ? [node.edges.epic] : [],
+        parent: node.edges.parent ? [node.edges.parent] : [],
+        prev: node.edges.prev ? [node.edges.prev] : [],
+        next: node.edges.next ? [node.edges.next] : [],
+        relates: node.edges.relates,
+        blocked_by: node.edges.blocked_by,
+        blocks: node.edges.blocks,
+        context_refs: node.edges.context_refs ?? [],
+        evidence_refs: node.edges.evidence_refs ?? [],
+    };
+}
+function incomingScopeRefs(index, targetQid) {
+    const sources = [];
+    for (const node of Object.values(index.nodes)) {
+        for (const ref of toStringList(node.attributes.scope_refs)) {
+            const resolved = (0, qid_1.resolveQid)(index, ref, node.ws);
+            if (resolved.status === "ok" && resolved.qid === targetQid) {
+                sources.push(node.qid);
+            }
+        }
+    }
+    return sources.sort();
+}
+function buildGraphRefsReceipt(index, node, warnings) {
+    const outgoingRaw = compactOutgoing(node);
+    const incomingRaw = {
+        scope_refs: incomingScopeRefs(index, node.qid),
+        epic: index.reverse_edges.epic?.[node.qid] ?? [],
+        parent: index.reverse_edges.parent?.[node.qid] ?? [],
+        prev: index.reverse_edges.prev?.[node.qid] ?? [],
+        next: index.reverse_edges.next?.[node.qid] ?? [],
+        relates: index.reverse_edges.relates?.[node.qid] ?? [],
+        blocked_by: index.reverse_edges.blocked_by?.[node.qid] ?? [],
+        blocks: index.reverse_edges.blocks?.[node.qid] ?? [],
+        context_refs: index.reverse_edges.context_refs?.[node.qid] ?? [],
+        evidence_refs: index.reverse_edges.evidence_refs?.[node.qid] ?? [],
+    };
+    const outgoing = Object.fromEntries(Object.entries(outgoingRaw).map(([key, values]) => [key, summarizeRefs(index, values, node.ws)]));
+    const incoming = Object.fromEntries(Object.entries(incomingRaw).map(([key, values]) => [key, summarizeRefs(index, values, node.ws)]));
+    return {
+        action: "graph.refs",
+        ok: true,
+        target: summarizeNode(node),
+        outgoing,
+        incoming,
+        warnings,
+    };
+}
 function toPosixPath(value) {
     return value.split(path_1.default.sep).join("/");
 }
@@ -176,6 +286,85 @@ function writeSelectedGoal(targetRoot, qid, id, ws) {
     (0, atomic_1.atomicWriteFile)(statePath, `${JSON.stringify(state, null, 2)}\n`);
     return rel(targetRoot, statePath);
 }
+function qidForRoot(id) {
+    return `root:${id}`;
+}
+function idFromRootQid(qid) {
+    const [workspace, id] = qid.split(":");
+    if (workspace !== "root" || !id) {
+        throw new errors_1.UsageError(`invalid root qid: ${qid}`);
+    }
+    return id;
+}
+function ensureStatusAllowed(config, status) {
+    const normalized = status.toLowerCase();
+    const allowed = new Set(config.work.status_enum.map((value) => value.toLowerCase()));
+    if (!allowed.has(normalized)) {
+        throw new errors_1.UsageError(`goal status ${normalized} is not allowed by work.status_enum`);
+    }
+    return normalized;
+}
+function isActiveGoalStatus(status, goalState) {
+    return status === "progress" && goalState === "active";
+}
+function isClosedGoalStatus(status, goalState) {
+    return status === "done" || status === "archived" || goalState === "achieved" || goalState === "archived";
+}
+function activeLocalRootGoals(root) {
+    const config = (0, config_1.loadConfig)(root);
+    const index = (0, indexer_1.buildIndex)(root, config);
+    return Object.values(index.nodes)
+        .filter((node) => !node.source?.imported)
+        .filter((node) => node.ws === "root" && node.type === "goal")
+        .filter((node) => isActiveGoalStatus(node.status, String(node.attributes.goal_state ?? "")))
+        .sort((a, b) => a.qid.localeCompare(b.qid));
+}
+function localGoalLifecycleReceipt(node, status, goalState, planned) {
+    return {
+        workspace: node.ws,
+        id: node.id,
+        qid: node.qid,
+        path: node.path,
+        previous_status: node.status ?? "",
+        previous_goal_state: String(node.attributes.goal_state ?? ""),
+        status,
+        goal_state: goalState,
+        source: "local",
+        planned,
+    };
+}
+function importedGoalLifecycleReceipt(plan, status, goalState, planned) {
+    return {
+        workspace: "root",
+        id: plan.to_id,
+        qid: qidForRoot(plan.to_id),
+        path: plan.target_path,
+        previous_status: plan.status ?? "",
+        previous_goal_state: plan.goal_state ?? "",
+        status,
+        goal_state: goalState,
+        source: "imported",
+        planned,
+    };
+}
+function readNodeFile(root, nodePath) {
+    const filePath = path_1.default.join(root, nodePath);
+    const parsed = (0, frontmatter_1.parseFrontmatter)(fs_1.default.readFileSync(filePath, "utf8"), nodePath);
+    return { filePath, frontmatter: { ...parsed.frontmatter }, body: parsed.body };
+}
+function writeRenderedNodeFile(filePath, frontmatter, body) {
+    (0, atomic_1.atomicWriteFile)(filePath, renderNode(frontmatter, body));
+}
+function pauseLocalGoals(root, goals, config) {
+    const today = (0, date_1.formatDate)(new Date());
+    for (const goal of goals.filter((item) => item.source === "local")) {
+        const loaded = readNodeFile(root, goal.path);
+        loaded.frontmatter.status = ensureStatusAllowed(config, "blocked");
+        loaded.frontmatter.goal_state = "paused";
+        loaded.frontmatter.updated = today;
+        writeRenderedNodeFile(loaded.filePath, loaded.frontmatter, loaded.body);
+    }
+}
 function isWorkMarkdownPath(value) {
     const normalized = value.replace(/\\/g, "/");
     return normalized.startsWith(".mdkg/work/") && normalized.endsWith(".md");
@@ -340,14 +529,41 @@ function planImportTemplate(options) {
             from_id: node.id,
             to_id: toId,
             type: node.type,
+            status: typeof frontmatter.status === "string" ? frontmatter.status : undefined,
+            goal_state: typeof frontmatter.goal_state === "string" ? frontmatter.goal_state : undefined,
             title: typeof frontmatter.title === "string" ? frontmatter.title : undefined,
             content: renderNode(frontmatter, body),
         };
     });
     const startGoalToId = options.startGoal ? (idMap.get(options.startGoal) ?? options.startGoal) : undefined;
-    if (options.startGoal && !plans.some((plan) => plan.to_id === startGoalToId && plan.type === "goal")) {
+    const startGoalPlan = startGoalToId
+        ? plans.find((plan) => plan.to_id === startGoalToId && plan.type === "goal")
+        : undefined;
+    if (options.startGoal && !startGoalPlan) {
         throw new errors_1.NotFoundError(`start goal not found in imported template graph: ${options.startGoal}`);
     }
+    if (options.selectGoal && startGoalPlan && isClosedGoalStatus(startGoalPlan.status, startGoalPlan.goal_state)) {
+        throw new errors_1.UsageError(`cannot select achieved or archived imported start goal: ${options.startGoal}`);
+    }
+    const localActiveGoals = activeLocalRootGoals(options.root);
+    const importedActiveGoals = plans
+        .filter((plan) => plan.type === "goal")
+        .filter((plan) => isActiveGoalStatus(plan.status, plan.goal_state));
+    if (!options.selectGoal && localActiveGoals.length + importedActiveGoals.length > 1) {
+        throw new errors_1.UsageError("import-template would create multiple active root goals; use --select-goal --start-goal <goal-id> or pause active goals before importing");
+    }
+    const activatedGoal = options.selectGoal && startGoalPlan
+        ? importedGoalLifecycleReceipt(startGoalPlan, "progress", "active", !options.apply)
+        : undefined;
+    const pausedGoals = options.selectGoal && startGoalPlan
+        ? [
+            ...localActiveGoals.map((node) => localGoalLifecycleReceipt(node, "blocked", "paused", !options.apply)),
+            ...importedActiveGoals
+                .filter((plan) => plan.to_id !== startGoalPlan.to_id)
+                .map((plan) => importedGoalLifecycleReceipt(plan, "blocked", "paused", !options.apply)),
+        ]
+        : [];
+    const warnings = pausedGoals.length > 0 ? [`paused ${pausedGoals.length} competing active goal(s)`] : [];
     const mode = options.apply ? "import_template_applied" : "import_template_dry_run";
     return {
         action: "graph.import_template",
@@ -383,7 +599,9 @@ function planImportTemplate(options) {
         ...(options.selectGoal && startGoalToId
             ? { selected_goal: { qid: `root:${startGoalToId}`, path: ".mdkg/state/selected-goal.json", planned: !options.apply } }
             : {}),
-        warnings: [],
+        ...(activatedGoal ? { activated_goal: activatedGoal } : {}),
+        paused_goals: pausedGoals,
+        warnings,
     };
 }
 function applyImportTemplate(options, receipt) {
@@ -439,6 +657,17 @@ function applyImportTemplate(options, receipt) {
                 frontmatter[field] = rewriteFrontmatterValue(value, idMap, node.sourcePath, field, ignoredRewrites);
             }
             const body = rewriteStringValue(node.parsed.body, idMap, node.sourcePath, "body", ignoredRewrites);
+            if (frontmatter.type === "goal" && options.selectGoal) {
+                if (qidForRoot(toId) === applyPlan.activated_goal?.qid) {
+                    frontmatter.status = ensureStatusAllowed(config, "progress");
+                    frontmatter.goal_state = "active";
+                }
+                else if (isActiveGoalStatus(String(frontmatter.status ?? ""), String(frontmatter.goal_state ?? ""))) {
+                    frontmatter.status = ensureStatusAllowed(config, "blocked");
+                    frontmatter.goal_state = "paused";
+                }
+                frontmatter.updated = (0, date_1.formatDate)(new Date());
+            }
             const targetPath = targetPathForImport(node.sourcePath, node.id, toId, usedPaths);
             contentByTarget.set(targetPath, renderNode(frontmatter, body));
         }
@@ -451,22 +680,24 @@ function applyImportTemplate(options, receipt) {
             fs_1.default.mkdirSync(path_1.default.dirname(targetAbs), { recursive: true });
             (0, atomic_1.atomicWriteFile)(targetAbs, content);
         }
+        pauseLocalGoals(options.root, applyPlan.paused_goals, config);
         const indexReceipt = (0, index_1.rebuildDerivedIndexCaches)({ root: options.root });
+        const validation = (0, validate_1.collectValidateReceipt)({ root: options.root, quiet: true });
+        if (validation.error_count > 0) {
+            throw new errors_1.ValidationError(`imported graph validation failed with ${validation.error_count} error(s)`);
+        }
         if (options.selectGoal && options.startGoal) {
             const selected = applyPlan.selected_goal?.qid;
             if (!selected) {
                 throw new errors_1.UsageError("--select-goal could not resolve imported start goal");
             }
-            const [, id] = selected.split(":");
-            if (!id) {
-                throw new errors_1.UsageError(`invalid selected goal qid: ${selected}`);
-            }
+            const id = idFromRootQid(selected);
             writeSelectedGoal(options.root, selected, id, "root");
             applyPlan.selected_goal = { qid: selected, path: ".mdkg/state/selected-goal.json", planned: false };
-        }
-        const validation = (0, validate_1.collectValidateReceipt)({ root: options.root, quiet: true });
-        if (validation.error_count > 0) {
-            throw new errors_1.ValidationError(`imported graph validation failed with ${validation.error_count} error(s)`);
+            if (applyPlan.activated_goal) {
+                applyPlan.activated_goal.planned = false;
+            }
+            applyPlan.paused_goals = applyPlan.paused_goals.map((goal) => ({ ...goal, planned: false }));
         }
         return {
             ...applyPlan,
@@ -580,3 +811,42 @@ function runGraphImportTemplateCommand(options) {
         console.log(`selected_goal: ${receipt.selected_goal.qid}${receipt.selected_goal.planned ? " (planned)" : ""}`);
     }
 }
+function runGraphRefsCommand(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    const { index, warnings } = (0, index_cache_1.loadIndex)({ root: options.root, config });
+    const resolved = (0, qid_1.resolveQid)(index, options.id, options.ws);
+    if (resolved.status !== "ok") {
+        throw new errors_1.NotFoundError((0, qid_1.formatResolveError)("node", options.id, resolved, options.ws));
+    }
+    const node = index.nodes[resolved.qid];
+    if (!node) {
+        throw new errors_1.NotFoundError(`node not found: ${options.id}`);
+    }
+    const receipt = buildGraphRefsReceipt(index, node, warnings);
+    if (options.json) {
+        writeJson(receipt);
+        return;
+    }
+    console.log(`graph refs: ${node.qid}`);
+    if (node.source?.imported) {
+        console.log(`source: subgraph:${node.source.subgraph_alias} read-only`);
+    }
+    for (const [direction, lanes] of Object.entries({ outgoing: receipt.outgoing, incoming: receipt.incoming })) {
+        console.log(`${direction}:`);
+        for (const [lane, refs] of Object.entries(lanes)) {
+            if (refs.length === 0) {
+                continue;
+            }
+            console.log(`  ${lane}:`);
+            for (const ref of refs) {
+                const target = ref.node
+                    ? `${ref.node.qid}${ref.node.read_only ? " (read-only)" : ""}`
+                    : ref.ref;
+                console.log(`    - ${target}`);
+            }
+        }
+    }
+    for (const warning of warnings) {
+        console.error(`warning: ${warning}`);
+    }
+}

package/dist/commands/handoff.js

@@ -0,0 +1,295 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runHandoffCreateCommand = runHandoffCreateCommand;
+const crypto_1 = __importDefault(require("crypto"));
+const path_1 = __importDefault(require("path"));
+const config_1 = require("../core/config");
+const index_cache_1 = require("../graph/index_cache");
+const pack_1 = require("../pack/pack");
+const metrics_1 = require("../pack/metrics");
+const atomic_1 = require("../util/atomic");
+const errors_1 = require("../util/errors");
+const qid_1 = require("../util/qid");
+const version_1 = require("../core/version");
+const RAW_CONTENT_MARKERS = [
+    { id: "raw_prompt", pattern: /\bRAW_PROMPT_MARKER\b/i, description: "raw prompt marker" },
+    { id: "raw_payload", pattern: /\bRAW_PAYLOAD_MARKER\b/i, description: "raw payload marker" },
+    { id: "raw_secret", pattern: /\bRAW_SECRET_MARKER\b|BEGIN [A-Z ]*PRIVATE KEY|secret\s*=/i, description: "raw secret marker" },
+];
+function normalizeWorkspace(value) {
+    if (!value || value === "all") {
+        return undefined;
+    }
+    return value;
+}
+function outputPath(root, out) {
+    if (!out) {
+        return undefined;
+    }
+    const resolved = path_1.default.resolve(root, out);
+    const rootWithSep = root.endsWith(path_1.default.sep) ? root : `${root}${path_1.default.sep}`;
+    if (resolved !== root && !resolved.startsWith(rootWithSep)) {
+        throw new errors_1.UsageError("--out must stay within the repo root");
+    }
+    return resolved;
+}
+function sha256(value) {
+    return `sha256:${crypto_1.default.createHash("sha256").update(value).digest("hex")}`;
+}
+function listAttribute(node, key) {
+    const value = "attributes" in node ? node.attributes[key] : undefined;
+    return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function stringAttribute(node, key) {
+    const value = "attributes" in node ? node.attributes[key] : undefined;
+    return typeof value === "string" ? value : undefined;
+}
+function collectRawMarkerWarnings(pack) {
+    const warnings = [];
+    for (const node of pack.nodes) {
+        for (const marker of RAW_CONTENT_MARKERS) {
+            if (marker.pattern.test(node.body)) {
+                warnings.push({
+                    qid: node.qid,
+                    path: node.path,
+                    marker_id: marker.id,
+                    message: `${marker.description} detected; handoff omitted raw body content for this node`,
+                });
+            }
+        }
+    }
+    return warnings;
+}
+function nodeLine(node) {
+    const parts = [`${node.qid}`, node.type, node.title];
+    const state = [node.status, node.priority !== undefined ? `p${node.priority}` : undefined].filter(Boolean).join("/");
+    if (state) {
+        parts.push(state);
+    }
+    parts.push(node.path);
+    return `- ${parts.join(" | ")}`;
+}
+function renderList(values, empty = "- none") {
+    if (values.length === 0) {
+        return [empty];
+    }
+    return values.map((value) => `- ${value}`);
+}
+function renderNodeRefs(node) {
+    const lines = [];
+    if (node.refs.length > 0) {
+        lines.push(`  refs: ${node.refs.join(", ")}`);
+    }
+    if (node.context_refs.length > 0) {
+        lines.push(`  context_refs: ${node.context_refs.join(", ")}`);
+    }
+    if (node.evidence_refs.length > 0) {
+        lines.push(`  evidence_refs: ${node.evidence_refs.join(", ")}`);
+    }
+    return lines;
+}
+function renderHandoff(params) {
+    const { rootNode, indexNode, pack, rawWarnings } = params;
+    const stats = (0, metrics_1.measurePack)(pack);
+    const lines = [];
+    const requiredChecks = listAttribute(indexNode, "required_checks");
+    const requiredSkills = listAttribute(indexNode, "required_skills");
+    const goalCondition = stringAttribute(indexNode, "goal_condition");
+    const activeNode = stringAttribute(indexNode, "active_node");
+    const lastActiveNode = stringAttribute(indexNode, "last_active_node");
+    const latestCheckpoint = pack.meta.latest_checkpoint_qid
+        ? pack.nodes.find((node) => node.qid === pack.meta.latest_checkpoint_qid)
+        : undefined;
+    lines.push("# mdkg Agent Handoff");
+    lines.push("");
+    lines.push("Use this handoff as a sanitized graph summary. Inspect source files before mutating durable state.");
+    lines.push("");
+    lines.push("## Target");
+    lines.push(`- qid: ${rootNode.qid}`);
+    lines.push(`- type: ${rootNode.type}`);
+    lines.push(`- title: ${rootNode.title}`);
+    if (rootNode.status) {
+        lines.push(`- status: ${rootNode.status}`);
+    }
+    if (rootNode.priority !== undefined) {
+        lines.push(`- priority: ${rootNode.priority}`);
+    }
+    lines.push(`- path: ${rootNode.path}`);
+    if (goalCondition) {
+        lines.push(`- goal_condition: ${goalCondition}`);
+    }
+    if (activeNode) {
+        lines.push(`- active_node: ${activeNode}`);
+    }
+    if (lastActiveNode) {
+        lines.push(`- last_active_node: ${lastActiveNode}`);
+    }
+    lines.push("");
+    lines.push("## Boundaries");
+    lines.push("- mdkg is durable semantic memory and graph state, not raw execution trace storage.");
+    lines.push("- Do not include raw secrets, credentials, model prompts, provider payloads, cookies, tokens, or bulky runtime artifacts in mdkg nodes or handoffs.");
+    lines.push("- Use refs, hashes, redacted summaries, archive links, artifact links, and checkpoints for evidence.");
+    lines.push("- Treat subgraph nodes as read-only planning context unless you are operating in the owning repo.");
+    lines.push("- Run validation before closing work or handing execution to another agent.");
+    lines.push("");
+    lines.push("## Recommended Next Steps");
+    if (rootNode.type === "goal") {
+        lines.push(`- Run \`mdkg goal current --json\` and \`mdkg goal next ${rootNode.id} --json\` to confirm routing.`);
+        lines.push("- Claim one actionable local node before implementation with `mdkg goal claim <goal-id> <work-id> --json`.");
+    }
+    else {
+        lines.push(`- Run \`mdkg show ${rootNode.id} --json\` and \`mdkg pack ${rootNode.id}\` to refresh local context.`);
+        lines.push("- Use `mdkg task start|update|done` for lifecycle updates when the node is task-like.");
+    }
+    lines.push("- Keep detailed implementation notes in Markdown body sections, not CLI flags.");
+    lines.push("");
+    lines.push("## Required Checks");
+    lines.push(...renderList(requiredChecks));
+    lines.push("");
+    lines.push("## Required Skills");
+    lines.push(...renderList(requiredSkills));
+    lines.push("");
+    lines.push("## Latest Checkpoint");
+    if (latestCheckpoint) {
+        lines.push(nodeLine(latestCheckpoint));
+    }
+    else {
+        lines.push("- none");
+    }
+    lines.push("");
+    lines.push("## Included Graph Context");
+    for (const node of pack.nodes) {
+        lines.push(nodeLine(node));
+        lines.push(...renderNodeRefs(node));
+    }
+    lines.push("");
+    lines.push("## Raw Content Warnings");
+    if (rawWarnings.length === 0) {
+        lines.push("- none");
+    }
+    else {
+        for (const warning of rawWarnings) {
+            lines.push(`- ${warning.qid} (${warning.path}): ${warning.marker_id} - ${warning.message}`);
+        }
+    }
+    lines.push("");
+    lines.push("## Pack Summary");
+    lines.push(`- generated_at: ${pack.meta.generated_at}`);
+    lines.push(`- node_count: ${pack.nodes.length}`);
+    lines.push(`- tokens_estimate: ${stats.totals.tokens_estimate}`);
+    lines.push(`- truncated: max_nodes=${pack.meta.truncated.max_nodes} max_bytes=${pack.meta.truncated.max_bytes}`);
+    if (pack.meta.truncated.dropped.length > 0) {
+        lines.push(`- dropped: ${pack.meta.truncated.dropped.join(", ")}`);
+    }
+    lines.push("");
+    lines.push("## Handoff Prompt");
+    lines.push("Continue from the target above. Preserve the boundaries, verify current repo state, use mdkg commands for structured lifecycle changes, and record validation evidence before closeout.");
+    lines.push("");
+    return lines.join("\n");
+}
+function runHandoffCreateCommand(options) {
+    if (!options.id) {
+        throw new errors_1.UsageError("mdkg handoff create requires <id-or-qid>");
+    }
+    const config = (0, config_1.loadConfig)(options.root);
+    const ws = normalizeWorkspace(options.ws);
+    if (ws && !config.workspaces[ws] && !config.subgraphs[ws]) {
+        throw new errors_1.NotFoundError(`workspace not found: ${ws}`);
+    }
+    const { index, stale, rebuilt, warnings } = (0, index_cache_1.loadIndex)({
+        root: options.root,
+        config,
+        useCache: true,
+        allowReindex: true,
+    });
+    if (stale && !rebuilt) {
+        console.error("warning: index is stale; run mdkg index to refresh");
+    }
+    for (const warning of warnings) {
+        console.error(`warning: ${warning}`);
+    }
+    const resolved = (0, qid_1.resolveQid)(index, options.id, ws);
+    if (resolved.status !== "ok") {
+        throw new errors_1.NotFoundError((0, qid_1.formatResolveError)("id", options.id, resolved, ws));
+    }
+    const indexNode = index.nodes[resolved.qid];
+    if (!indexNode) {
+        throw new errors_1.NotFoundError(`node not found: ${resolved.qid}`);
+    }
+    const depth = options.depth ?? config.pack.default_depth;
+    if (!Number.isInteger(depth) || depth < 0) {
+        throw new errors_1.UsageError("--depth must be a non-negative integer");
+    }
+    const buildResult = (0, pack_1.buildPack)({
+        root: options.root,
+        index,
+        rootQid: resolved.qid,
+        depth,
+        edges: ["parent", "epic", "relates", "blocked_by", "blocks", "context_refs", "evidence_refs"],
+        verbose: false,
+        maxNodes: config.pack.limits.max_nodes,
+        verboseCoreListPath: path_1.default.resolve(options.root, config.pack.verbose_core_list_path),
+        wsHint: ws,
+        includeLatestCheckpoint: true,
+    });
+    for (const warning of buildResult.warnings) {
+        console.error(`warning: ${warning}`);
+    }
+    const rootNode = buildResult.pack.nodes[0];
+    if (!rootNode) {
+        throw new errors_1.NotFoundError(`node not found: ${resolved.qid}`);
+    }
+    const rawWarnings = collectRawMarkerWarnings(buildResult.pack);
+    const content = renderHandoff({
+        rootNode,
+        indexNode,
+        pack: buildResult.pack,
+        rawWarnings,
+    });
+    const contentHash = sha256(content);
+    const outPath = outputPath(options.root, options.out);
+    if (outPath) {
+        (0, atomic_1.atomicWriteFile)(outPath, content);
+    }
+    const receipt = {
+        action: "handoff-created",
+        ok: true,
+        mdkg_version: (0, version_1.readPackageVersion)(),
+        target: {
+            qid: rootNode.qid,
+            id: rootNode.id,
+            type: rootNode.type,
+            title: rootNode.title,
+            path: rootNode.path,
+            status: rootNode.status,
+        },
+        output_path: outPath ? path_1.default.relative(options.root, outPath).split(path_1.default.sep).join("/") : null,
+        content_sha256: contentHash,
+        raw_marker_warning_count: rawWarnings.length,
+        raw_marker_warnings: rawWarnings,
+        latest_checkpoint_qid: buildResult.pack.meta.latest_checkpoint_qid ?? null,
+        included_qids: buildResult.pack.nodes.map((node) => node.qid),
+        pack: {
+            node_count: buildResult.pack.nodes.length,
+            generated_at: buildResult.pack.meta.generated_at,
+            truncated: buildResult.pack.meta.truncated,
+        },
+        content,
+    };
+    if (options.json) {
+        console.log(JSON.stringify(receipt, null, 2));
+        return;
+    }
+    if (outPath) {
+        console.log(`handoff written: ${outPath}`);
+        console.log(`sha256: ${contentHash}`);
+        if (rawWarnings.length > 0) {
+            console.log(`raw marker warnings: ${rawWarnings.length}`);
+        }
+        return;
+    }
+    console.log(content);
+}