mdkg 0.3.6 → 0.3.7

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);
+}

package/dist/commands/mcp.js

@@ -464,6 +464,15 @@ function goalNextTool(root, args) {
             warnings,
         };
     }
+    if (loaded.node.status === "done" || String(loaded.node.attributes.goal_state ?? "") === "achieved") {
+        return {
+            command: "mcp.goal_next",
+            goal_source: loaded.source,
+            goal: (0, query_output_1.toNodeSummaryJson)(loaded.node),
+            node: null,
+            warnings,
+        };
+    }
     const statusPreference = config.work.next.status_preference.map((status) => status.toLowerCase());
     const statusRanks = new Set(statusPreference);
     const scope = (0, goal_scope_1.collectGoalScope)(index, loaded.node);

package/dist/commands/pack.js

@@ -25,7 +25,7 @@ const headings_1 = require("../templates/headings");
 const errors_1 = require("../util/errors");
 const output_1 = require("../util/output");
 const qid_1 = require("../util/qid");
-const EDGE_KEYS = new Set(["parent", "epic", "relates", "blocked_by", "blocks", "prev", "next"]);
+const EDGE_KEYS = new Set(["parent", "epic", "relates", "blocked_by", "blocks", "prev", "next", "context_refs", "evidence_refs"]);
 const FORMAT_KEYS = new Set(["md", "json", "toon", "xml"]);
 const SKILL_SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 function normalizeWorkspace(value) {
@@ -183,6 +183,8 @@ function appendSkillsToPack(pack, skillEntries, depth, root) {
         links: skill.links,
         artifacts: [],
         refs: [],
+        context_refs: [],
+        evidence_refs: [],
         aliases: [skill.slug, ...skill.tags],
         attributes: {},
         body: depth === "full" ? loadSkillFullBody(root, skill) : renderSkillMetaBody(skill),

package/dist/commands/query_output.js

@@ -35,6 +35,8 @@ function toNodeSummaryJson(node) {
             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 ?? [])],
         },
         ...(node.source ? { source: node.source } : {}),
     };

package/dist/commands/show.js

@@ -103,6 +103,14 @@ function runShowCommand(options) {
     if (blocksLine) {
         lines.push(blocksLine);
     }
+    const contextRefsLine = maybeLine("context_refs", node.edges.context_refs ?? []);
+    if (contextRefsLine) {
+        lines.push(contextRefsLine);
+    }
+    const evidenceRefsLine = maybeLine("evidence_refs", node.edges.evidence_refs ?? []);
+    if (evidenceRefsLine) {
+        lines.push(evidenceRefsLine);
+    }
     if (!options.metaOnly && body.length > 0) {
         lines.push("");
         lines.push(body);

package/dist/commands/status.js

@@ -229,6 +229,7 @@ function collectStatus(root) {
             selected_exists: selected.state === null ? null : !selectedMissing,
             selected_achieved: selected.state === null ? null : selectedAchieved,
             active_node: selectedNode?.attributes.active_node ?? null,
+            last_active_node: selectedNode?.attributes.last_active_node ?? null,
             goal_state: selectedNode?.attributes.goal_state ?? null,
             status: selectedNode?.status ?? null,
         },

package/dist/commands/task.js

@@ -297,6 +297,7 @@ function runTaskDoneCommandLocked(options) {
             ws: loaded.ws,
             relates: loaded.id,
             scope: loaded.id,
+            kind: options.checkpointKind,
             runId: options.runId,
             note: `checkpoint created from mdkg task done for ${loaded.id}`,
             now,
@@ -309,6 +310,7 @@ function runTaskDoneCommandLocked(options) {
             ws: loaded.ws,
             relates: loaded.id,
             scope: loaded.id,
+            kind: options.checkpointKind,
             runId: options.runId,
             note: `checkpoint created from mdkg task done for ${loaded.id}`,
             now,

package/dist/commands/upgrade.js

@@ -13,6 +13,8 @@ const paths_1 = require("../core/paths");
 const version_1 = require("../core/version");
 const project_db_1 = require("../core/project_db");
 const errors_1 = require("../util/errors");
+const frontmatter_1 = require("../graph/frontmatter");
+const workspace_files_1 = require("../graph/workspace_files");
 const init_manifest_1 = require("./init_manifest");
 const skill_support_1 = require("./skill_support");
 const skill_mirror_1 = require("./skill_mirror");
@@ -273,6 +275,64 @@ function migrateConfigIfNeeded(root, dryRun, summary, changes) {
         writeFile(cfgPath, `${JSON.stringify(nextConfig.config, null, 2)}\n`);
     }
 }
+function migrateClosedGoalActiveNodes(root, dryRun, summary, changes) {
+    const config = (0, config_1.validateConfigSchema)((0, migrate_1.migrateConfig)(JSON.parse(fs_1.default.readFileSync((0, paths_1.configPath)(root), "utf8"))).config);
+    const filesByAlias = (0, workspace_files_1.listWorkspaceDocFilesByAlias)(root, config);
+    let planned = 0;
+    for (const files of Object.values(filesByAlias)) {
+        for (const filePath of files) {
+            const content = fs_1.default.readFileSync(filePath, "utf8");
+            let parsed;
+            try {
+                parsed = (0, frontmatter_1.parseFrontmatter)(content, filePath);
+            }
+            catch {
+                continue;
+            }
+            const frontmatter = { ...parsed.frontmatter };
+            if (frontmatter.type !== "goal") {
+                continue;
+            }
+            const status = typeof frontmatter.status === "string" ? frontmatter.status : "";
+            const goalState = typeof frontmatter.goal_state === "string" ? frontmatter.goal_state : "";
+            const activeNode = typeof frontmatter.active_node === "string" ? frontmatter.active_node : undefined;
+            if (!activeNode || (status !== "done" && goalState !== "achieved")) {
+                continue;
+            }
+            const relativePath = path_1.default.relative(root, filePath).split(path_1.default.sep).join("/");
+            const lastActiveNode = typeof frontmatter.last_active_node === "string" ? frontmatter.last_active_node : undefined;
+            if (lastActiveNode && lastActiveNode !== activeNode) {
+                planned += 1;
+                record(summary, changes, {
+                    path: relativePath,
+                    category: "goal_lifecycle",
+                    action: "conflict",
+                    reason: `closed goal has active_node ${activeNode} but different last_active_node ${lastActiveNode}; local content preserved`,
+                });
+                continue;
+            }
+            planned += 1;
+            record(summary, changes, {
+                path: relativePath,
+                category: "goal_lifecycle",
+                action: "migrate",
+                reason: "move closed goal active_node to last_active_node",
+            });
+            if (!dryRun) {
+                if (!lastActiveNode) {
+                    frontmatter.last_active_node = activeNode;
+                }
+                delete frontmatter.active_node;
+                const frontmatterBlock = ["---", ...(0, frontmatter_1.formatFrontmatter)(frontmatter, frontmatter_1.DEFAULT_FRONTMATTER_KEY_ORDER), "---"].join("\n");
+                const body = parsed.body.length > 0 ? parsed.body : "";
+                writeFile(filePath, body.length > 0 ? `${frontmatterBlock}\n${body}` : frontmatterBlock);
+            }
+        }
+    }
+    if (planned === 0) {
+        summary.unchanged += 1;
+    }
+}
 function isIgnoredBySimpleGitignore(root, relativePath) {
     const ignorePath = path_1.default.join(root, ".gitignore");
     if (!fs_1.default.existsSync(ignorePath)) {
@@ -440,6 +500,7 @@ function runUpgradeCommand(options) {
     const agentWorkspace = isAgentWorkspace(root);
     const managedCurrentFiles = [];
     migrateConfigIfNeeded(root, dryRun, summary, changes);
+    migrateClosedGoalActiveNodes(root, dryRun, summary, changes);
     for (const file of currentManifest.files) {
         if (!shouldIncludeFile(file, agentWorkspace)) {
             continue;