mdkg 0.3.6 → 0.3.7

package/dist/graph/validate_graph.js

@@ -19,6 +19,8 @@ function validateEdgeTargets(index, allowMissing, knownSkillSlugs, externalWorks
             ["relates", edges.relates],
             ["blocked_by", edges.blocked_by],
             ["blocks", edges.blocks],
+            ["context_refs", edges.context_refs ?? []],
+            ["evidence_refs", edges.evidence_refs ?? []],
         ];
         if (edges.epic) {
             edgeLists.push(["epic", [edges.epic]]);
@@ -34,6 +36,9 @@ function validateEdgeTargets(index, allowMissing, knownSkillSlugs, externalWorks
         }
         for (const [edgeKey, values] of edgeLists) {
             for (const value of values) {
+                if ((edgeKey === "context_refs" || edgeKey === "evidence_refs") && (0, refs_1.isUriRef)(value)) {
+                    continue;
+                }
                 const targetNode = nodes[value];
                 if (targetNode &&
                     ["epic", "parent", "prev", "next"].includes(edgeKey) &&

package/dist/graph/visibility.js

@@ -88,6 +88,12 @@ function collectNodeStringReferences(node) {
     for (const [index, value] of node.edges.blocks.entries()) {
         values.push({ field: `blocks[${index}]`, value });
     }
+    for (const [index, value] of (node.edges.context_refs ?? []).entries()) {
+        values.push({ field: `context_refs[${index}]`, value });
+    }
+    for (const [index, value] of (node.edges.evidence_refs ?? []).entries()) {
+        values.push({ field: `evidence_refs[${index}]`, value });
+    }
     for (const [index, value] of node.links.entries()) {
         values.push({ field: `links[${index}]`, value });
     }

package/dist/init/AGENT_START.md

@@ -39,7 +39,10 @@ Agent operating prompt:
   node:sqlite queue delivery, internal event/receipt/reducer, writer lease/CAS,
   and queue control migrations. Queue state is delivery infrastructure, not
   canonical event history; use `mdkg db queue ...` to create, pause, enqueue,
-  claim, settle, inspect, and drain local queues. Event rows are durable local
+  claim, settle, inspect, and drain local queues. Use
+  `mdkg db queue contract --json` for the public adapter contract covering
+  payload hashing, dedupe, claim order, lease-owner settlement, retry,
+  dead-letter, release-expired, pause/resume, snapshot policy, and stats. Event rows are durable local
   project DB history; receipts, reducers, writer leases, and materializers are
   internal local helper surfaces, with no public `mdkg db event`,
   `mdkg db reducer`, `mdkg db lease`, or `mdkg db materializer` CLI yet. Use `mdkg db verify` and `mdkg db stats` for

package/dist/init/CLI_COMMAND_MATRIX.md

@@ -17,6 +17,7 @@ Primary commands:
 - `mdkg list`
 - `mdkg search`
 - `mdkg pack`
+- `mdkg handoff create <id-or-qid> [--ws <alias>] [--depth <n>] [--out <path>] [--json]`
 - `mdkg skill`
 - `mdkg capability`
 - `mdkg spec`
@@ -34,6 +35,14 @@ Primary commands:
 - `mdkg fix apply [--family ids] [--target <id-or-qid>] [--base-ref <ref>] [--json]`
 - `mdkg fix ids [--target <id-or-qid>] [--base-ref <ref>] [--apply] [--json]`
 
+Semantic refs:
+- work nodes may use `context_refs` for non-executable background and `evidence_refs` for proof/audit refs
+- semantic refs may point at local ids, subgraph qids, or URI refs
+- use `mdkg pack <id> --edges context_refs,evidence_refs` when a handoff should traverse semantic refs
+- use `mdkg handoff create <id-or-qid> --json` for sanitized copy-ready agent handoff prompts
+- handoffs summarize graph state, latest checkpoint, boundaries, required checks, next actions, and raw-marker warnings without copying raw node bodies
+- executable goal queues still belong in goal `scope_refs`
+
 Operator health:
 - `mdkg status [--json]` is a read-only summary for scripts and agents
 - reports mdkg version/config, git state, graph/index freshness, selected-goal state, project DB verification summary, and generated cache status
@@ -71,6 +80,7 @@ Project database commands:
 - `mdkg db verify [--json]`
 - `mdkg db stats [--json]`
 - `mdkg db queue create|pause|resume|enqueue|claim|ack|fail|dead-letter|release-expired|stats|list|show ... [--json]`
+- `mdkg db queue contract [--json]`
 - `mdkg db snapshot seal [--queue-policy drain|paused] [--json]`
 - `mdkg db snapshot verify [--json]`
 - `mdkg db snapshot status [--json]`
@@ -87,6 +97,9 @@ Project database commands:
   in the configured migration table
 - `mdkg db queue ...` exposes durable local delivery operations backed by
   node:sqlite; queue rows are delivery state, not canonical event history
+- `mdkg db queue contract --json` returns the public adapter contract for
+  payload hashes, dedupe, claim order, lease-owner settlement, retries,
+  dead-letter, release-expired, pause/resume, snapshot policy, and stats
 - paused queues reject enqueue and claim, but ack/fail/dead-letter and
   release-expired remain available so leased work can settle
 - event tables are durable local history for project DB state transitions;
@@ -105,7 +118,9 @@ Project database commands:
 - active `.mdkg/db/runtime/` files and `.mdkg/db` WAL/SHM/journal/lock/temp files are ignored by default
 
 Validation commands:
-- `mdkg validate [--out <path>] [--quiet] [--json]`
+- `mdkg validate [--out <path>] [--quiet] [--changed-only] [--json]`
+- `--changed-only` filters warning presentation to changed `.mdkg` files while full graph errors still run
+- JSON receipts include `warning_diagnostics` with warning ids, categories, severity, paths, refs, and remediation text
 
 Node creation commands:
 - `mdkg new <type> "<title>" [options] [--json]`
@@ -146,11 +161,12 @@ Event log commands:
 Task mutation commands:
 - `mdkg task start <id-or-qid> [--ws <alias>] [--run-id <id>] [--note "<text>"] [--json]`
 - `mdkg task update <id-or-qid> [options] [--json]`
-- `mdkg task done <id-or-qid> [--checkpoint "<title>"] [options] [--json]`
+- `mdkg task done <id-or-qid> [--checkpoint "<title>"] [--checkpoint-kind implementation|test-proof|goal-closeout|audit|handoff] [options] [--json]`
 - task commands support task-like `feat`, `task`, `bug`, `test`, and `spike` nodes
 
 Checkpoint commands:
-- `mdkg checkpoint new <title> [--ws <alias>] [--json]`
+- `mdkg checkpoint new <title> [--kind implementation|test-proof|goal-closeout|audit|handoff] [--ws <alias>] [--json]`
+- checkpoint kinds render bodies with command evidence, pass/fail status, known warnings, changed surfaces, boundaries, and follow-up refs
 
 Agent bootstrap:
 - `mdkg init --agent`
@@ -220,6 +236,7 @@ Graph clone, fork, and template import:
 - `mdkg graph clone <source-bundle-or-mdkg-dir> --target <path> [--json]`
 - `mdkg graph fork <source-bundle-or-mdkg-dir> --target <path> [--start-goal <goal-id>] [--json]`
 - `mdkg graph import-template <source-bundle-or-mdkg-dir> [--start-goal <goal-id>] [--select-goal] [--id-prefix <prefix>] [--dry-run] [--apply] [--json]`
+- `mdkg graph refs <id-or-qid> [--ws <alias>] [--json]`
 - `graph clone` and `graph fork` preserve IDs because the target is a separate graph namespace
 - clone/fork targets must be empty or absent and stay under the current mdkg root
 - live directory sources are never mutated; clone/fork refuses targets nested inside a live source directory
@@ -230,6 +247,7 @@ Graph clone, fork, and template import:
 - colliding semantic template IDs require `--id-prefix`
 - `--select-goal` requires `--start-goal`; on apply it activates the imported start goal, pauses competing active root goals, validates, then writes selected-goal state
 - importing active template goals without `--select-goal` fails before writing when it would create multiple active root goals
+- `graph refs` is read-only and summarizes inbound/outbound scope, context, evidence, blocker, related, and structural refs across local and subgraph qids
 - subgraphs remain read-only bundle projections for orchestration context; use `graph clone|fork|import-template` when authored graph state should be created
 
 Subgraph orchestration:
@@ -263,11 +281,13 @@ Work semantic mirrors:
 - `mdkg work receipt verify <id-or-qid> [--json]`
 - `mdkg work receipt update <id-or-qid> [--receipt-status <status>] [--add-artifacts <...>] [--add-proof-refs <...>] [--add-attestation-refs <...>] [--json]`
 - `mdkg work artifact add <order-or-receipt-id-or-qid> <file> [--id <archive.id>] [--kind source|artifact] [--json]`
+- `mdkg work validate [<id-or-qid>] [--type spec|work|work_order|receipt|feedback|dispute|proposal] [--json]`
 - `work trigger` accepts a `WORK.md` ref directly or a `SPEC.md` capability ref with exactly one resolvable work contract; it creates a submitted order mirror and never executes work
 - example: `mdkg work trigger work.example --id order.example-1 --requester user://example --json`
 - `work trigger --enqueue <queue>` requires a valid project DB plus an explicitly created active queue, creates a submitted order mirror, and enqueues a local delivery message without executing work
 - `work order status` is read-only and reports deterministic order state plus linked receipts
 - `work receipt verify` is read-only and reports linkage, evidence, archive ref, hash, outcome, and redaction-policy checks
+- `work validate` is read-only and reports typed diagnostics for agent workflow mirrors; obvious raw secret, prompt, token, or payload markers are warnings, not hard failures
 - work commands mutate mdkg semantic mirror files only; production order, receipt, feedback, dispute, payment, ledger, marketplace inventory, fulfillment, and execution state remains canonical outside mdkg
 - do not store raw secrets, credentials, live payment state, ledger mutations, or canonical marketplace state in work mirrors
 - `artifact://...` refs identify external/runtime-managed artifacts; `archive://...` refs identify committed mdkg archive sidecars
@@ -299,6 +319,7 @@ Goal nodes:
 - `goal activate` makes one local root goal active, pauses competing local active goals in the same workspace, and writes selected-goal state
 - `goal archive` marks a superseded historical goal archived so it remains readable but not actionable
 - `goal next` is read-only; use `goal claim` to set `active_node`
+- `goal done` preserves the final actionable item as `last_active_node` and removes actionable `active_node`
 - `mdkg goal evaluate` is report-only and never runs commands from `required_checks`
 - skill improvements discovered during normal goal execution should be recorded as candidates or proposals unless the active node is skill-maintenance
 

package/dist/init/README.md

@@ -25,6 +25,7 @@ mdkg new task "..." --status todo --priority 1
 mdkg search "..."
 mdkg show <id>
 mdkg pack <id>
+mdkg handoff create <id-or-qid> --json
 mdkg capability search "..."
 mdkg spec list --json
 mdkg archive list
@@ -36,7 +37,14 @@ mdkg fix plan --json
 mdkg validate
 ```
 
-This repo is already initialized. Use `mdkg upgrade` to preview safe scaffold updates, `mdkg index` to create or refresh generated graph/skill/capability/subgraph and SQLite caches after init, `mdkg new` to create work, `mdkg new goal "..."` plus `mdkg goal activate/current/next/claim/evaluate` for recursive long-running objectives, `mdkg search`/`mdkg show` to inspect graph state, `mdkg capability ...` to inspect cached skill/spec/work/core/design capabilities, `mdkg spec ...` for focused optional SPEC records, `mdkg capability resolve ...` to rank local and subgraph capabilities, `mdkg archive ...` to register source/artifact sidecars, `mdkg work ...` to create work contract/order/receipt semantic mirrors and deterministic trigger/verification records, `mdkg bundle ...` to create full graph snapshot bundles, `mdkg graph ...` to clone/fork/import authored graph templates, `mdkg subgraph ...` to register read-only child graph planning views, `mdkg pack <id>` to build deterministic context, and `mdkg validate` before closeout.
+This repo is already initialized. Use `mdkg upgrade` to preview safe scaffold updates, `mdkg index` to create or refresh generated graph/skill/capability/subgraph and SQLite caches after init, `mdkg new` to create work, `mdkg new goal "..."` plus `mdkg goal activate/current/next/claim/evaluate` for recursive long-running objectives, `mdkg search`/`mdkg show` to inspect graph state, `mdkg capability ...` to inspect cached skill/spec/work/core/design capabilities, `mdkg spec ...` for focused optional SPEC records, `mdkg capability resolve ...` to rank local and subgraph capabilities, `mdkg archive ...` to register source/artifact sidecars, `mdkg work ...` to create work contract/order/receipt semantic mirrors and deterministic trigger/verification records, `mdkg bundle ...` to create full graph snapshot bundles, `mdkg graph ...` to clone/fork/import authored graph templates, `mdkg subgraph ...` to register read-only child graph planning views, `mdkg pack <id>` to build deterministic context, `mdkg handoff create <id-or-qid> --json` to create a sanitized copy-ready agent handoff prompt, and `mdkg validate` before closeout.
+
+`mdkg handoff create` summarizes goal/work state, included pack nodes, latest
+checkpoint, boundaries, required checks, next actions, and raw-content marker
+warnings without copying raw node bodies into the prompt. Use `--out` to write
+the handoff artifact inside the repo root.
+
+For large historical graphs, `mdkg validate --changed-only --json` keeps warning review focused on changed `.mdkg` files while full graph errors still run. `mdkg format --headings --dry-run --json` previews missing recommended heading additions before `--apply`.
 
 Use `mdkg status --json` for a read-only operator summary of Git, graph,
 selected-goal, project DB, and generated-cache health before mutating work. Use
@@ -124,7 +132,11 @@ infrastructure, not canonical event history; use `mdkg db queue ...` to create,
 pause, enqueue, claim, settle, inspect, and drain local queues. Event rows are
 durable local project DB history; receipts, reducers, writer leases, and
 materializers are internal local helper surfaces, with no public `mdkg db event`,
-`mdkg db reducer`, `mdkg db lease`, or `mdkg db materializer` CLI yet. Use `mdkg db verify` for non-mutating health checks and
+`mdkg db reducer`, `mdkg db lease`, or `mdkg db materializer` CLI yet.
+`mdkg db queue contract --json` returns the read-only public adapter contract
+for canonical payload hashing, dedupe keys, oldest-ready claim order,
+lease-owner checked settlement, retry/dead-letter behavior, release-expired,
+pause/resume, snapshot queue policy, and stats. Use `mdkg db verify` for non-mutating health checks and
 `mdkg db stats` for table counts, DB size, migration state, and receipt-file
 counts. Use `mdkg db snapshot seal` to create an opt-in sealed checkpoint under
 `.mdkg/db/state`; the default queue policy is drain, and
@@ -235,6 +247,9 @@ Update and artifact commands accept local ids or local qids; subgraph qids are r
 `mdkg work trigger` creates a deterministic submitted `WORK_ORDER.md` from a
 WORK contract or a SPEC with exactly one resolvable work contract. `mdkg work
 order status` and `mdkg work receipt verify` are read-only review helpers.
+`mdkg work validate [<id-or-qid>] [--type spec|work|work_order|receipt|feedback|dispute|proposal] --json`
+is a read-only focused validator for agent workflow mirrors with typed diagnostics
+and raw secret, prompt, token, or payload marker warnings.
 `mdkg work trigger --enqueue <queue>` optionally writes a local project DB queue
 delivery message after the queue has been explicitly created and is active; it
 still does not execute work.

package/dist/init/init-manifest.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "tool": "mdkg",
-  "mdkg_version": "0.3.6",
+  "mdkg_version": "0.3.7",
   "files": [
     {
       "path": ".mdkg/config.json",
@@ -61,7 +61,7 @@
     {
       "path": ".mdkg/README.md",
       "category": "mdkg_doc",
-      "sha256": "cecb50528b70c0c4e32f8a052a668b5d87d6ac542818229efa848a6b1ac42d62"
+      "sha256": "5a03de7c4602936e6108b3e8f2916ead8320a4020c335ea9cfd083d59eabf083"
     },
     {
       "path": ".mdkg/skills/build-pack-and-execute-task/SKILL.md",
@@ -91,12 +91,12 @@
     {
       "path": ".mdkg/templates/default/bug.md",
       "category": "template",
-      "sha256": "88e3f8d67aa3b2156be2006bd1c8139b7b16b46f2c05a4f4d840b3746a40f9c5"
+      "sha256": "27ed977c67030befccfc469d9db257fadc9ad5331963e259c489ba03754194cb"
     },
     {
       "path": ".mdkg/templates/default/chk.md",
       "category": "template",
-      "sha256": "15f793e422009c76f8bda72c3609157acd7f03762d9c9bdb096c4aa2e2c3fb89"
+      "sha256": "9e32f46665fc7cc582c4695772f5d99799f574229e740fa8892c7b9e75324de9"
     },
     {
       "path": ".mdkg/templates/default/dec.md",
@@ -116,12 +116,12 @@
     {
       "path": ".mdkg/templates/default/epic.md",
       "category": "template",
-      "sha256": "56697b69af027fe08c00866c0c0670f7d7e2a0857803bd4aabb99f4761311879"
+      "sha256": "0f515c046064771e3f9abaa3689634bfae3ffcf2ffe9825e8e3b7dc15c24fc50"
     },
     {
       "path": ".mdkg/templates/default/feat.md",
       "category": "template",
-      "sha256": "99cfdd97b40b119cf899fd766d816c07b7daaafd8ec8e70e6c6de5c0d37f581c"
+      "sha256": "25c04ce41d8cf519d5c3009219eeed48f76c23600c6b7999264831aa92cefc4b"
     },
     {
       "path": ".mdkg/templates/default/feedback.md",
@@ -131,7 +131,7 @@
     {
       "path": ".mdkg/templates/default/goal.md",
       "category": "template",
-      "sha256": "710252d8a2dc35be71661d6988007af127052fa8ad24b1fb00374c975ae117a2"
+      "sha256": "8f984580aefd02b34639fa7f5d2a834662656bbf2e12f14a285f5ae31aff74ce"
     },
     {
       "path": ".mdkg/templates/default/prd.md",
@@ -166,17 +166,17 @@
     {
       "path": ".mdkg/templates/default/spike.md",
       "category": "template",
-      "sha256": "ac805dca7e6edcdad35e24b615dc7399cbae3bed676b9da57e24a393eb425245"
+      "sha256": "56e881fad20bd4fda8ae53cc78ce6f30f4dacd083f4eda40f9f2ba3723d52e0e"
     },
     {
       "path": ".mdkg/templates/default/task.md",
       "category": "template",
-      "sha256": "f6385dd4f56f1c8df164ac3e79d82c5a3fde3f952dc9cdc78c0b8077caa62277"
+      "sha256": "2db6e56298b22e9da9121e2ac31f2fd68e370211218c5bcaae1014a9e63b7cde"
     },
     {
       "path": ".mdkg/templates/default/test.md",
       "category": "template",
-      "sha256": "bdae53e5cb4bd77712da155bbcfc24409ced8162c977e6bc478a9d1e695ddef7"
+      "sha256": "59484d4cf397707d738ccbc2f788c08eab58d3d73f37591f7bde8f1533b828ce"
     },
     {
       "path": ".mdkg/templates/default/work_order.md",
@@ -246,7 +246,7 @@
     {
       "path": "AGENT_START.md",
       "category": "startup_doc",
-      "sha256": "46e734b6eae92eb957c3e29fb4d206e4be3fd6d32dd00e888e01a0dc75979428"
+      "sha256": "d305f0e61c2401814bc51067c8129a3ad131c6217692038bc7ffad012c305451"
     },
     {
       "path": "AGENTS.md",
@@ -261,7 +261,7 @@
     {
       "path": "CLI_COMMAND_MATRIX.md",
       "category": "startup_doc",
-      "sha256": "5321d82b594c1c0aa5574dcffbf21e5a1d3df89566b0f9acfc854fcaac3e13a7"
+      "sha256": "84de4e06dd4d6d2b316e17c37bebcec373f1a9500d7107c8dd0ce5ca15048b7d"
     },
     {
       "path": "llms.txt",

package/dist/init/templates/default/bug.md

@@ -16,6 +16,8 @@ relates: []
 blocked_by: []
 blocks: []
 refs: []
+context_refs: []
+evidence_refs: []
 aliases: []
 skills: []
 created: {{created}}

package/dist/init/templates/default/chk.md

@@ -2,6 +2,7 @@
 id: {{id}}
 type: checkpoint
 title: {{title}}
+checkpoint_kind: {{checkpoint_kind}}
 status: {{status}}
 priority: {{priority}}
 epic: {{epic}}
@@ -16,6 +17,8 @@ relates: []
 blocked_by: []
 blocks: []
 refs: []
+context_refs: []
+evidence_refs: []
 aliases: []
 skills: []
 scope: []

package/dist/init/templates/default/epic.md

@@ -12,6 +12,8 @@ relates: []
 blocked_by: []
 blocks: []
 refs: []
+context_refs: []
+evidence_refs: []
 aliases: []
 skills: []
 created: {{created}}

package/dist/init/templates/default/feat.md

@@ -16,6 +16,8 @@ relates: []
 blocked_by: []
 blocks: []
 refs: []
+context_refs: []
+evidence_refs: []
 aliases: []
 skills: []
 created: {{created}}

package/dist/init/templates/default/goal.md

@@ -8,6 +8,7 @@ goal_state: {{goal_state}}
 goal_condition: {{goal_condition}}
 scope_refs: []
 active_node: {{active_node}}
+last_active_node: {{last_active_node}}
 required_skills: []
 required_checks: []
 max_iterations: {{max_iterations}}
@@ -24,6 +25,8 @@ relates: []
 blocked_by: []
 blocks: []
 refs: []
+context_refs: []
+evidence_refs: []
 aliases: []
 skills: []
 created: {{created}}

package/dist/init/templates/default/spike.md

@@ -16,6 +16,8 @@ relates: []
 blocked_by: []
 blocks: []
 refs: []
+context_refs: []
+evidence_refs: []
 aliases: []
 skills: []
 created: {{created}}

package/dist/init/templates/default/task.md

@@ -16,6 +16,8 @@ relates: []
 blocked_by: []
 blocks: []
 refs: []
+context_refs: []
+evidence_refs: []
 aliases: []
 skills: []
 created: {{created}}

package/dist/init/templates/default/test.md

@@ -16,6 +16,8 @@ relates: []
 blocked_by: []
 blocks: []
 refs: []
+context_refs: []
+evidence_refs: []
 aliases: []
 skills: []
 cases: []

package/dist/pack/export_json.js

@@ -2,18 +2,30 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.exportJson = exportJson;
 function buildFrontmatter(node) {
+    const links = node.links ?? [];
+    const artifacts = node.artifacts ?? [];
+    const refs = node.refs ?? [];
+    const contextRefs = node.context_refs ?? [];
+    const evidenceRefs = node.evidence_refs ?? [];
+    const aliases = node.aliases ?? [];
     const frontmatter = {};
-    if (node.links.length > 0) {
-        frontmatter.links = node.links;
+    if (links.length > 0) {
+        frontmatter.links = links;
     }
-    if (node.artifacts.length > 0) {
-        frontmatter.artifacts = node.artifacts;
+    if (artifacts.length > 0) {
+        frontmatter.artifacts = artifacts;
     }
-    if (node.refs.length > 0) {
-        frontmatter.refs = node.refs;
+    if (refs.length > 0) {
+        frontmatter.refs = refs;
     }
-    if (node.aliases.length > 0) {
-        frontmatter.aliases = node.aliases;
+    if (contextRefs.length > 0) {
+        frontmatter.context_refs = contextRefs;
+    }
+    if (evidenceRefs.length > 0) {
+        frontmatter.evidence_refs = evidenceRefs;
+    }
+    if (aliases.length > 0) {
+        frontmatter.aliases = aliases;
     }
     for (const [key, value] of Object.entries(node.attributes ?? {})) {
         frontmatter[key] = value;

package/dist/pack/export_md.js

@@ -48,6 +48,11 @@ function renderHeader(meta, nodes) {
     return lines;
 }
 function renderNode(node) {
+    const links = node.links ?? [];
+    const artifacts = node.artifacts ?? [];
+    const refs = node.refs ?? [];
+    const contextRefs = node.context_refs ?? [];
+    const evidenceRefs = node.evidence_refs ?? [];
     const lines = [];
     lines.push(`## ${node.qid}`);
     lines.push(`qid: ${node.qid}`);
@@ -60,10 +65,16 @@ function renderNode(node) {
         lines.push(`priority: ${node.priority}`);
     }
     lines.push(`path: ${node.path}`);
-    lines.push(formatList("links", node.links));
-    lines.push(formatList("artifacts", node.artifacts));
-    if (node.refs.length > 0) {
-        lines.push(formatList("refs", node.refs));
+    lines.push(formatList("links", links));
+    lines.push(formatList("artifacts", artifacts));
+    if (refs.length > 0) {
+        lines.push(formatList("refs", refs));
+    }
+    if (contextRefs.length > 0) {
+        lines.push(formatList("context_refs", contextRefs));
+    }
+    if (evidenceRefs.length > 0) {
+        lines.push(formatList("evidence_refs", evidenceRefs));
     }
     for (const [key, value] of Object.entries(node.attributes ?? {})) {
         lines.push(formatAttribute(key, value));

package/dist/pack/export_xml.js

@@ -21,6 +21,9 @@ function listItems(tag, itemTag, items, indent) {
     lines.push(`${indent}</${tag}>`);
     return lines;
 }
+function listValues(items) {
+    return items ?? [];
+}
 function attributeLines(key, value, indent) {
     if (Array.isArray(value)) {
         return listItems(key, "item", value, indent);
@@ -83,10 +86,12 @@ function exportXml(pack) {
         }
         lines.push(`      <path>${escapeXml(node.path)}</path>`);
         lines.push("      <frontmatter>");
-        lines.push(...listItems("links", "link", node.links, "        "));
-        lines.push(...listItems("artifacts", "artifact", node.artifacts, "        "));
-        lines.push(...listItems("refs", "ref", node.refs, "        "));
-        lines.push(...listItems("aliases", "alias", node.aliases, "        "));
+        lines.push(...listItems("links", "link", listValues(node.links), "        "));
+        lines.push(...listItems("artifacts", "artifact", listValues(node.artifacts), "        "));
+        lines.push(...listItems("refs", "ref", listValues(node.refs), "        "));
+        lines.push(...listItems("context_refs", "context_ref", listValues(node.context_refs), "        "));
+        lines.push(...listItems("evidence_refs", "evidence_ref", listValues(node.evidence_refs), "        "));
+        lines.push(...listItems("aliases", "alias", listValues(node.aliases), "        "));
         for (const [key, value] of Object.entries(node.attributes ?? {})) {
             lines.push(...attributeLines(key, value, "        "));
         }

package/dist/pack/metrics.js

@@ -18,6 +18,12 @@ function estimateTokensFromChars(chars) {
     return Math.ceil(chars / 4);
 }
 function renderNodeMetricsText(node) {
+    const links = node.links ?? [];
+    const artifacts = node.artifacts ?? [];
+    const refs = node.refs ?? [];
+    const contextRefs = node.context_refs ?? [];
+    const evidenceRefs = node.evidence_refs ?? [];
+    const aliases = node.aliases ?? [];
     const lines = [];
     lines.push(`qid: ${node.qid}`);
     lines.push(`id: ${node.id}`);
@@ -31,10 +37,12 @@ function renderNodeMetricsText(node) {
         lines.push(`priority: ${node.priority}`);
     }
     lines.push(`path: ${node.path}`);
-    lines.push(`links: ${node.links.join(",")}`);
-    lines.push(`artifacts: ${node.artifacts.join(",")}`);
-    lines.push(`refs: ${node.refs.join(",")}`);
-    lines.push(`aliases: ${node.aliases.join(",")}`);
+    lines.push(`links: ${links.join(",")}`);
+    lines.push(`artifacts: ${artifacts.join(",")}`);
+    lines.push(`refs: ${refs.join(",")}`);
+    lines.push(`context_refs: ${contextRefs.join(",")}`);
+    lines.push(`evidence_refs: ${evidenceRefs.join(",")}`);
+    lines.push(`aliases: ${aliases.join(",")}`);
     if (node.body.length > 0) {
         lines.push("");
         lines.push(node.body);

package/dist/pack/pack.js

@@ -6,7 +6,7 @@ const node_body_1 = require("../graph/node_body");
 const qid_1 = require("../util/qid");
 const order_1 = require("./order");
 const verbose_core_1 = require("./verbose_core");
-const EDGE_KEYS = ["parent", "epic", "relates", "blocked_by", "blocks", "prev", "next"];
+const EDGE_KEYS = ["parent", "epic", "relates", "blocked_by", "blocks", "prev", "next", "context_refs", "evidence_refs"];
 function normalizeEdgeList(edges) {
     const seen = new Set();
     const result = [];
@@ -59,6 +59,12 @@ function getNeighbors(index, qid, edges) {
             case "blocks":
                 neighbors.push(...node.edges.blocks);
                 break;
+            case "context_refs":
+                neighbors.push(...(node.edges.context_refs ?? []));
+                break;
+            case "evidence_refs":
+                neighbors.push(...(node.edges.evidence_refs ?? []));
+                break;
             default:
                 break;
         }
@@ -113,6 +119,8 @@ function buildPackNode(root, index, qid) {
         links: node.links,
         artifacts: node.artifacts,
         refs: node.refs,
+        context_refs: node.edges.context_refs ?? [],
+        evidence_refs: node.edges.evidence_refs ?? [],
         aliases: node.aliases,
         attributes: node.attributes ?? {},
         ...(node.source ? { source: node.source } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdkg",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "Markdown Knowledge Graph",
   "license": "MIT",
   "bin": {
@@ -32,6 +32,10 @@
     "smoke:command-docs": "npm run build && node scripts/smoke-command-docs.js",
     "smoke:spike": "npm run build && node scripts/smoke-spike.js",
     "smoke:goal-lifecycle": "npm run build && node scripts/smoke-goal-lifecycle.js",
+    "smoke:semantic-refs": "npm run build && node scripts/smoke-semantic-refs.js",
+    "smoke:checkpoint-templates": "npm run build && node scripts/smoke-checkpoint-templates.js",
+    "smoke:handoff": "npm run build && node scripts/smoke-handoff.js",
+    "smoke:integration-ux": "npm run build && node scripts/smoke-integration-ux.js",
     "smoke:bundle": "npm run build && node scripts/smoke-bundle.js",
     "smoke:graph-clone": "npm run build && node scripts/smoke-graph-clone.js",
     "smoke:mcp": "npm run build && node scripts/smoke-mcp.js",
@@ -44,7 +48,7 @@
     "cli:check": "npm run build && node scripts/cli_help_snapshot.js --check",
     "cli:contract": "npm run build && node scripts/generate-command-contract.js --check",
     "prepack": "npm run build && node scripts/assert-publish-ready.js",
-    "prepublishOnly": "npm run test && npm run cli:check && npm run cli:contract && node dist/cli.js validate && npm run smoke:consumer && npm run smoke:matrix && npm run smoke:upgrade && npm run smoke:init && npm run smoke:capabilities && npm run smoke:db && npm run smoke:db-queue && npm run smoke:db-queue-cli && npm run smoke:db-events && npm run smoke:db-materializer && npm run smoke:db-snapshot && npm run smoke:archive-work && npm run smoke:work-invocation && npm run smoke:cli-ux-polish && npm run smoke:operator-health && npm run smoke:fix-plan && npm run smoke:branch-conflicts && npm run smoke:id-repair && npm run smoke:command-docs && npm run smoke:spike && npm run smoke:goal-lifecycle && npm run smoke:bundle && npm run smoke:graph-clone && npm run smoke:mcp && npm run smoke:subgraph && npm run smoke:visibility && npm run smoke:sqlite && npm run smoke:parallel && npm run smoke:goal && node scripts/assert-publish-ready.js",
+    "prepublishOnly": "npm run test && npm run cli:check && npm run cli:contract && node dist/cli.js validate && npm run smoke:consumer && npm run smoke:matrix && npm run smoke:upgrade && npm run smoke:init && npm run smoke:capabilities && npm run smoke:db && npm run smoke:db-queue && npm run smoke:db-queue-cli && npm run smoke:db-events && npm run smoke:db-materializer && npm run smoke:db-snapshot && npm run smoke:archive-work && npm run smoke:work-invocation && npm run smoke:cli-ux-polish && npm run smoke:operator-health && npm run smoke:fix-plan && npm run smoke:branch-conflicts && npm run smoke:id-repair && npm run smoke:command-docs && npm run smoke:spike && npm run smoke:goal-lifecycle && npm run smoke:semantic-refs && npm run smoke:checkpoint-templates && npm run smoke:handoff && npm run smoke:integration-ux && npm run smoke:bundle && npm run smoke:graph-clone && npm run smoke:mcp && npm run smoke:subgraph && npm run smoke:visibility && npm run smoke:sqlite && npm run smoke:parallel && npm run smoke:goal && node scripts/assert-publish-ready.js",
     "postinstall": "node scripts/postinstall.js",
     "smoke:subgraph": "npm run build && node scripts/smoke-subgraph.js"
   },