mdkg 0.3.5 → 0.3.7

package/CHANGELOG.md

@@ -8,9 +8,104 @@ mdkg is pre-v1 public alpha software. Command, graph, cache, bundle, and DAL con
 
 ## Unreleased
 
-### Planned
+## 0.3.7 - 2026-06-20
 
-- No changes yet.
+### Added
+
+- Added `context_refs` and `evidence_refs` as generic semantic reference
+  fields for mdkg work nodes, with indexing, validation, search/show output,
+  pack traversal, SQLite cache support, subgraph projection, and visibility
+  enforcement.
+- Added `mdkg graph refs <id-or-qid> --json` to summarize inbound and outbound
+  scope, context, evidence, blocker, related, and structural references for
+  local graph nodes and read-only subgraph qids.
+- Added richer checkpoint kinds for implementation milestones, test proof, goal
+  closeout, read-only audits, and handoffs. Generated checkpoint bodies now
+  include sections for evidence, validation, known warnings, changed surfaces,
+  boundaries, and follow-up references.
+- Added `mdkg work validate [<id-or-qid>] --type ... --json` for focused
+  SPEC, WORK, WORK_ORDER, RECEIPT, FEEDBACK, DISPUTE, and PROPOSAL semantic
+  mirror diagnostics.
+- Added validation warning categories plus `mdkg validate --changed-only` for
+  changed-file warning review while preserving full-graph error checking.
+- Added `mdkg format --headings --dry-run|--apply --json` to preview or apply
+  recommended heading migrations for historical mdkg Markdown nodes.
+- Added `mdkg db queue contract --json` as the public project DB queue adapter
+  contract covering payload hashing, dedupe, claim ordering, lease-owner
+  settlement, retry/dead-letter behavior, expired lease release, pause/resume,
+  snapshot policies, and stats semantics.
+- Added `mdkg handoff create <id-or-qid>` for sanitized, copy-ready agent
+  handoff prompts built from pack context, goal state, latest checkpoints,
+  required checks, semantic refs, and raw-content warnings.
+- Added packed temp-repo smokes for semantic refs, checkpoint templates,
+  handoffs, and the full integration UX flow.
+
+### Changed
+
+- Completed goals now move the final `active_node` to `last_active_node` when
+  marked done or archived, so historical routing state is preserved without
+  leaving completed goals actionable.
+- `mdkg goal next <done-goal> --json` now returns `node: null` without
+  misleading stale `active_node` warnings for achieved goals.
+- Goal and pack workflows now distinguish executable `scope_refs` from
+  contextual and evidence references, reducing validation noise when goals cite
+  checkpoints, design evidence, prerequisite goals, or external proof refs.
+- README, init assets, command matrix, generated command contract metadata,
+  help targets, and publish-readiness assertions now document the new semantic
+  refs, handoff, workflow validation, checkpoint, queue contract, and warning
+  migration surfaces.
+- Upgrade behavior now migrates legacy achieved goals that still have
+  `active_node` into the new `last_active_node` shape.
+
+### Fixed
+
+- Reduced false-positive operational friction for completed goals and
+  intentional contextual refs without weakening missing-reference or invalid
+  graph-edge validation.
+- Strengthened cross-subgraph blocker diagnostics so read-only external graph
+  nodes are reported as planning context instead of locally actionable work.
+
+### Security
+
+- Handoff generation omits raw node body content for nodes with obvious raw
+  prompt, payload, or secret markers and reports typed raw-marker warnings
+  instead.
+- Workflow validation and checkpoint validation warn on obvious raw secret,
+  prompt, token, or payload markers without turning mdkg into a broad secret
+  scanner or blocking operator review.
+- The public queue contract explicitly states that queue payloads should be
+  compact refs or redacted envelopes, not raw secrets, prompts, provider
+  payloads, or bulky runtime artifacts.
+
+## 0.3.6 - 2026-06-17
+
+### Added
+
+- Added `mdkg mcp serve --stdio` as a local read-only MCP server for status,
+  workspace/subgraph discovery, search, show, bounded in-memory packs, goal
+  current/next, and validation.
+- Added packed `smoke:mcp` coverage that installs mdkg from a tarball in a
+  temp prefix, launches the stdio server, exercises root and subgraph reads,
+  and proves mutation-shaped tool calls fail closed.
+
+### Fixed
+
+- Prepared `0.3.6` graph import hardening after the `0.3.5` publish:
+  `mdkg graph import-template --select-goal --apply` now activates the
+  rewritten imported start goal, pauses competing active root goals, validates,
+  and only then writes selected-goal state.
+
+### Changed
+
+- Extended graph import dry-run/apply receipts with activation and paused-goal
+  details, and made active template imports fail before writing when
+  `--select-goal` is omitted and multiple active root goals would result.
+
+### Security
+
+- The MCP server is stdio-only and exposes no task, goal activation, graph
+  import, queue, event, archive, format, SQL, shell, arbitrary file-read,
+  filesystem mutation, environment, or secret-access tools.
 
 ## 0.3.5 - 2026-06-17
 

package/CLI_COMMAND_MATRIX.md

@@ -1,7 +1,7 @@
 # CLI Command Matrix
 
 as_of: 2026-06-17
-package_version_in_source: 0.3.5
+package_version_in_source: 0.3.6
 source: live help from `src/cli.ts`, runtime command handlers, and `dec-15`..`dec-18`
 status: canonical single-source command and flag reference for mdkg
 
@@ -23,6 +23,7 @@ Primary commands:
 - `list`
 - `search`
 - `pack`
+- `handoff`
 - `skill`
 - `capability`
 - `spec`
@@ -36,6 +37,7 @@ Primary commands:
 - `next`
 - `validate`
 - `status`
+- `mcp`
 - `fix`
 
 Advanced / maintenance commands:
@@ -64,6 +66,7 @@ Fresh init workspaces default to the SQLite access cache backend; existing migra
 Project application database foundation commands are accessed through `mdkg db ...`; `mdkg index` remains the compatibility shortcut for graph index rebuilds.
 Operator health summaries are accessed through read-only `mdkg status ...`; deeper diagnostics remain under `mdkg doctor ...`.
 Repair planning is accessed through read-only `mdkg fix plan ...`; duplicate-ID graph repairs can be applied through `mdkg fix apply --family ids ...` or the convenience `mdkg fix ids --apply ...`. Index/cache and graph-reference findings remain plan/manual-review only.
+Local MCP integration is accessed through `mdkg mcp serve --stdio`; it exposes read-only graph/status/workspace/search/show/pack/goal/validate tools only.
 
 ## Global usage
 
@@ -347,6 +350,10 @@ Allowed formats:
 - `toon`
 - `xml`
 
+Allowed pack edges:
+- `parent`, `epic`, `relates`, `blocked_by`, `blocks`, `prev`, `next`
+- `context_refs` and `evidence_refs` for non-executable semantic references
+
 Profiles:
 - `standard`
 - `concise`
@@ -361,6 +368,26 @@ Visibility:
 - `--visibility internal` includes public/internal records and fails when included records reference private records
 - `--visibility private` records explicit private intent and may include all records
 - visibility filtering does not inspect or redact arbitrary Markdown body text
+- `context_refs` and `evidence_refs` are indexed semantic refs, not executable goal queues; include them with `--edges context_refs,evidence_refs` when a handoff needs background or proof nodes
+
+### `mdkg handoff`
+
+When to use:
+- create a sanitized, copy-ready agent handoff prompt from graph context
+- summarize goal/work state, included pack nodes, latest checkpoint, boundaries, required checks, and next actions
+
+Usage:
+- `mdkg handoff create <id-or-qid> [--ws <alias>] [--depth <n>] [--out <path>] [--json]`
+
+Notes:
+- uses pack traversal with `context_refs` and `evidence_refs`
+- does not copy raw node bodies into the handoff
+- reports raw secret, prompt, token, or payload marker warnings without including raw marker content
+- `--out` must stay inside the repo root
+- the command does not execute work, mutate graph nodes, or generate detailed node content
+
+Receipts:
+- `handoff-created`: `{ action, ok, mdkg_version, target, output_path, content_sha256, raw_marker_warning_count, raw_marker_warnings, latest_checkpoint_qid, included_qids, pack, content }`
 
 ### `mdkg skill`
 
@@ -622,12 +649,14 @@ JSON receipts:
 When to use:
 - clone or fork a complete mdkg graph into a separate target directory while preserving IDs
 - import a template graph into the current repo with deterministic ID/link rewrites
+- inspect inbound and outbound graph references across local and read-only subgraph qids
 - prepare selected-goal demo handoffs from reusable graph templates
 
 Usage:
 - `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]`
 
 Flags:
 - `--target <path>`
@@ -636,6 +665,7 @@ Flags:
 - `--id-prefix <prefix>`
 - `--dry-run`
 - `--apply`
+- `--ws <alias>`
 - `--json`
 
 Notes:
@@ -647,13 +677,16 @@ Notes:
 - `graph import-template` defaults to dry-run unless `--apply` is supplied
 - same-repo template import rewrites canonical numeric IDs to the next unused ID by type prefix and rewrites structured refs plus safe body-local id/qid mentions
 - colliding semantic template IDs require `--id-prefix`
-- `--select-goal` requires `--start-goal` and writes selected-goal state only after apply validation
+- `--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; it reports `scope_refs`, `context_refs`, `evidence_refs`, blockers, related refs, and structural inbound/outbound links
 - subgraphs remain read-only bundle projections for orchestration context; use `graph clone|fork|import-template` when authored graph state should be created
 
 JSON receipts:
 - `clone`: `{ action: "graph.clone", ok, mode, source, target, source_hash, preserved_ids, files_written, skipped_paths, index, validation, warnings }`
 - `fork`: `{ action: "graph.fork", ok, mode, source, target, source_hash, preserved_ids, files_written, skipped_paths, start_goal?, selected_goal?, index, validation, warnings }`
-- `import-template`: `{ action: "graph.import_template", ok, mode, source, source_hash, preserved_ids: false, rewritten_ids, rewritten_refs, planned_paths, files_written, skipped_paths, start_goal?, selected_goal?, index?, validation?, warnings }`
+- `import-template`: `{ action: "graph.import_template", ok, mode, source, source_hash, preserved_ids: false, rewritten_ids, rewritten_refs, planned_paths, files_written, skipped_paths, start_goal?, selected_goal?, activated_goal?, paused_goals, index?, validation?, warnings }`
+- `refs`: `{ action: "graph.refs", ok, target, outgoing, incoming, warnings }`
 
 ### `mdkg subgraph`
 
@@ -742,6 +775,8 @@ Usage:
 - `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 <...>] [--add-evidence-hashes <sha256:...>] [--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 <workflow-type>] [--json]`
+- `mdkg work validate [<id-or-qid>] [--type spec|work|work_order|receipt|feedback|dispute|proposal] [--json]`
 
 Notes:
 - work commands mutate semantic mirror files only
@@ -755,6 +790,7 @@ Notes:
 - `work order status` is read-only and reports deterministic order state plus linked receipts
 - `work receipt new` accepts URI-style cost/proof/attestation refs, explicit redaction policy, and SHA-256 evidence/input/output hash refs
 - `work receipt verify` is read-only and reports linkage, evidence, archive ref, hash, outcome, and redaction-policy checks; invalid receipts print JSON before exiting nonzero
+- `work validate` is read-only and reports typed diagnostics for SPEC.md, WORK.md, WORK_ORDER.md, RECEIPT.md, FEEDBACK.md, DISPUTE.md, and PROPOSAL.md mirrors; obvious raw secret, prompt, token, or payload markers are warnings, not hard failures
 - `work artifact add` calls `mdkg archive add`, then attaches the resulting `archive://...` ref to the target order or receipt
 - `work order update`, `work receipt update`, and `work artifact add` accept local ids or local qids; subgraph qids are read-only and must be changed in their source workspace
 
@@ -764,6 +800,7 @@ JSON receipts:
 - `order status`: `{ kind: "work_order_status", order, receipt_count, receipts }`
 - `receipt verify`: `{ kind: "work_receipt_verify", ok, receipt, work_order?, checks, errors, warnings }`
 - `artifact add`: `{ action: "artifact_registered", target, archive }`
+- `validate` work-validate-receipt: `{ action: "work.validate", ok, type, target?, checked_count, nodes, warning_count, error_count, warnings, errors, diagnostics }`
 
 ### `mdkg goal`
 
@@ -796,7 +833,7 @@ Usage:
 - `mdkg goal archive <goal-id-or-qid> [--ws <alias>] [--json]`
 
 Behavior:
-- `goal show` reports goal condition, goal state, scope refs, active node, required skills, required checks, and source path.
+- `goal show` reports goal condition, goal state, scope refs, active node, last active node, required skills, required checks, and source path.
 - `goal select` writes local ignored selected-goal state so `goal next` can omit the goal id.
 - `goal activate` makes one local root goal active, pauses competing local active goals in the same workspace, and writes selected-goal state.
 - `goal current` shows the selected goal or unique active goal fallback.
@@ -804,7 +841,7 @@ Behavior:
 - `goal next` is read-only and selects feature, task, bug, test, or spike work inside explicit `scope_refs`; epics are recursive containers, not executable returns.
 - `goal claim` mutates only `active_node` after the work item is confirmed inside the goal scope.
 - `goal evaluate` is report-only and never runs commands from `required_checks`.
-- `goal pause`, `goal resume`, and `goal done` update `goal_state`, compatible work status, and `updated`.
+- `goal pause`, `goal resume`, and `goal done` update `goal_state`, compatible work status, and `updated`; done goals move any current `active_node` to `last_active_node` and no longer emit stale active-node routing warnings.
 - `goal archive` marks a superseded historical goal as `status: archived` and `goal_state: archived`; archived goals remain show/search/list readable but are excluded from active routing.
 - subgraph goal qids are read-only; update the source workspace instead.
 
@@ -829,7 +866,7 @@ When to use:
 Usage:
 - `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]`
 
 #### `mdkg task start`
 
@@ -865,12 +902,13 @@ JSON receipt:
 
 Usage:
 - `mdkg task done <id-or-qid> [--ws <alias>] [--add-artifacts <a,...>] [--add-links <l,...>]`
-- `                 [--add-refs <id,...>] [--checkpoint "<title>"] [--run-id <id>] [--note "<text>"] [--json]`
+- `                 [--add-refs <id,...>] [--checkpoint "<title>"] [--checkpoint-kind implementation|test-proof|goal-closeout|audit|handoff] [--run-id <id>] [--note "<text>"] [--json]`
 
 Behavior:
 - supports task-like `feat`, `task`, `bug`, `test`, and `spike` nodes
 - sets `status: done`
 - `--checkpoint` creates a related checkpoint
+- `--checkpoint-kind` selects the evidence template for the related checkpoint
 - if `events.jsonl` is missing for the workspace, prints a short `stderr` reminder about `mdkg event enable`
 
 JSON receipt:
@@ -899,7 +937,9 @@ When to use:
 - run the repo trust gate before calling work done
 
 Usage:
-- `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
 
 Flags:
 - `--out <path>`
@@ -956,11 +996,12 @@ JSON receipt:
 ### `mdkg checkpoint`
 
 Usage:
-- `mdkg checkpoint new <title> [--ws <alias>] [--json]`
+- `mdkg checkpoint new <title> [--kind implementation|test-proof|goal-closeout|audit|handoff] [--ws <alias>] [--json]`
 - `        [--relates <id,id,...>] [--scope <id,id,...>] [--run-id <id>] [--note "<text>"]`
+- checkpoint kinds render bodies with command evidence, pass/fail status, known warnings, changed surfaces, boundaries, and follow-up refs
 
 JSON receipt:
-- `{ action: "created", checkpoint: { workspace, id, qid, path } }`
+- `{ action: "created", checkpoint: { workspace, id, qid, path, kind } }`
 
 ### `mdkg index`
 
@@ -1000,6 +1041,7 @@ Usage:
 - `mdkg db queue list <queue> [--status ready|leased|acked|dead_letter|all] [--limit <n>] [--json]`
 - `mdkg db queue show <queue> <message-id> [--json]`
 - `mdkg db queue 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]`
@@ -1020,6 +1062,10 @@ Boundaries:
   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 covering
+  canonical payload hashing, dedupe semantics, oldest-ready claim order,
+  lease-owner checked settlement, retry/dead-letter behavior, release-expired,
+  pause/resume, snapshot queue policy, stats, and boundary guidance
 - 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;
@@ -1061,6 +1107,12 @@ Usage:
 
 Usage:
 - `mdkg format`
+- `mdkg format --headings [--dry-run|--apply] [--json]`
+
+Notes:
+- default `mdkg format` normalizes frontmatter in place
+- `mdkg format --headings` defaults to dry-run and returns planned missing-heading additions
+- `mdkg format --headings --apply` appends missing recommended body headings and returns a migration receipt
 
 ### `mdkg status`
 
@@ -1086,6 +1138,34 @@ JSON receipt shape:
 - `generated` reports index, skills, capabilities, and subgraph cache existence/staleness
 - `summary` includes machine-readable warning and error counts plus messages
 
+### `mdkg mcp`
+
+Usage:
+- `mdkg mcp serve --stdio`
+
+When to use:
+- expose one local mdkg root to an MCP-capable agent or orchestrator
+- let an external agent inspect mdkg status, workspace/subgraph aliases, search/show results, in-memory packs, goal current/next, and validation without shelling out to individual CLI commands
+
+Flags:
+- `--stdio`
+- `--root`, `-r <path>`
+
+Boundaries:
+- stdio is the only transport in this release; mdkg opens no HTTP listener
+- bind the server to one graph root with `--root <path>` when launching from outside the repo
+- tool calls are read-only and return MCP `structuredContent` plus text content
+- exposed tools: `mdkg_status`, `mdkg_workspace_list`, `mdkg_search`, `mdkg_show`, `mdkg_pack`, `mdkg_goal_current`, `mdkg_goal_next`, and `mdkg_validate`
+- `mdkg_pack` builds an in-memory bounded pack and does not write `.mdkg/pack`
+- no task, goal activation, graph import, queue, event, archive, format, SQL, shell, arbitrary file-read, filesystem mutation, environment, or secret-access tool is exposed
+- mutation allowlists and broader CLI parity are future design work, not part of this command surface
+- stdout is reserved for newline-delimited JSON-RPC MCP messages; diagnostics must stay off stdout
+
+JSON-RPC receipt shapes:
+- initialize: `{ protocolVersion, capabilities: { tools }, serverInfo, instructions }`
+- `tools/list`: `{ tools: [{ name, title, description, inputSchema, annotations }] }`
+- `tools/call`: MCP tool result with `{ content, structuredContent, isError }`
+
 ### `mdkg fix`
 
 When to use:

package/README.md

@@ -14,7 +14,7 @@ mdkg stays deliberately boring:
 - first-class rebuildable SQLite cache through built-in `node:sqlite`
 - no daemon, hosted index, or vector DB
 
-Current package version in source: `0.3.5`
+Current package version in source: `0.3.6`
 
 mdkg is still pre-v1 public alpha software. The public package is usable, but graph, cache, bundle, and DAL contracts may continue to change quickly while the project converges on a stable v1 surface.
 
@@ -29,9 +29,21 @@ The primary loop is:
 4. build a deterministic pack
 5. validate before closing the loop
 
-If an agent is involved, the default handoff primitive is `mdkg pack <id>`.
+If an agent is involved, use `mdkg pack <id>` for deterministic context and
+`mdkg handoff create <id-or-qid> --json` for a sanitized, copy-ready agent
+handoff prompt. Handoffs summarize 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.
 If a repo needs repeatable procedures, author them as first-class skills under `.mdkg/skills/`.
 
+Work nodes can separate semantic background from executable scope with
+`context_refs` and `evidence_refs`. Use `context_refs` for related plans,
+external docs, subgraph qids, or URI references that explain why work exists.
+Use `evidence_refs` for proof, audit, receipt, checkpoint, archive, or URI
+references. These fields are indexed, validated, shown, and packable, but they
+do not make referenced nodes actionable goal work; keep executable queues in
+goal `scope_refs`.
+
 ## Install
 
 ```bash
@@ -136,6 +148,7 @@ Build deterministic context:
 mdkg pack task-1
 mdkg pack task-1 --profile concise --dry-run --stats
 mdkg pack task-1 --visibility public --dry-run
+mdkg pack task-1 --edges context_refs,evidence_refs --format json
 ```
 
 Create a full `.mdkg` graph snapshot bundle for root or child orchestration:
@@ -167,9 +180,11 @@ mdkg graph import-template templates/website-template-mdkg --start-goal goal-1 -
 ```
 
 `graph clone` and `graph fork` preserve IDs; `graph import-template` rewrites
-canonical numeric IDs and internal links to avoid same-repo collisions. Subgraphs
-remain read-only planning views; use `mdkg graph ...` when authored graph state
-should be created.
+canonical numeric IDs and internal links to avoid same-repo collisions. With
+`--select-goal --apply`, import-template activates the rewritten imported start
+goal, pauses competing active root goals, validates the graph, and then writes
+selected-goal state. Subgraphs remain read-only planning views; use
+`mdkg graph ...` when authored graph state should be created.
 
 Register a child repo bundle as a read-only subgraph planning view:
 
@@ -206,10 +221,27 @@ Materialized trees are generated local state, ignored by graph indexing/search/v
 
 Subgraph nodes are projected under the subgraph alias, for example `child_repo:task-1`. They are available to `list`, `search`, `show`, `pack`, capability discovery, and `capability resolve`, but remain read-only; mutate the child repo and sync its root-owned bundle snapshot to change subgraph content. Root-authored relationship and reference fields can point at configured subgraph qids such as `child_repo:work.example`; local ownership fields such as `epic`, `parent`, `prev`, and `next` stay local-only. Stale subgraphs warn during planning reads and fail `mdkg subgraph verify`. Public or internal subgraphs must be backed by public bundle profiles; private subgraphs stay private planning context.
 
+Use `mdkg graph refs <id-or-qid> --json` to inspect inbound and outbound scope, context, evidence, blocker, related, and structural links for local or read-only subgraph qids without mutating either graph.
+
+Launch a local read-only MCP server when an MCP-capable agent should inspect a
+specific mdkg graph without receiving mutation tools:
+
+```bash
+mdkg mcp serve --stdio --root /path/to/repo
+```
+
+The MCP surface is stdio-only in this release. It exposes read-only tools for
+status, workspace/subgraph listing, search, show, in-memory pack generation,
+goal current/next, and validation. It does not expose task updates, goal
+activation, graph import, queue, event, archive, format, SQL, shell, arbitrary
+file reads, filesystem mutation, environment variables, or secret access.
+Future mutation allowlists remain design work.
+
 Validate before handoff or commit:
 
 ```bash
 mdkg validate
+mdkg handoff create <id-or-qid> --out .mdkg/handoffs/example.md
 ```
 
 Discover cached capability surfaces:
@@ -264,8 +296,11 @@ Update structured task state and evidence while keeping body and narrative edits
 mdkg task start task-1 --run-id run_local_1
 mdkg task update task-1 --add-artifacts tests://unit.txt --add-tags release
 mdkg task done task-1 --checkpoint "release readiness milestone"
+mdkg task done task-1 --checkpoint "goal complete" --checkpoint-kind goal-closeout
 ```
 
+Checkpoint kinds are `implementation`, `test-proof`, `goal-closeout`, `audit`, and `handoff`; generated checkpoint bodies include command evidence, pass/fail status, known warnings, changed surfaces, boundaries, and follow-up refs.
+
 Ensure and append baseline event memory:
 
 ```bash
@@ -330,6 +365,7 @@ These are the commands new users and agents should learn first:
 - `mdkg task`
 - `mdkg validate`
 - `mdkg status`
+- `mdkg mcp`
 - `mdkg fix`
 
 Advanced / maintenance commands still exist, but they are not the first-run story:
@@ -342,6 +378,11 @@ Advanced / maintenance commands still exist, but they are not the first-run stor
 - `mdkg fix plan --json`
 - `mdkg workspace`
 
+For large historical graphs, use `mdkg validate --changed-only --json` to keep
+warning review focused on changed `.mdkg` files while full graph errors still
+run. Use `mdkg format --headings --dry-run --json` to review missing recommended
+heading additions before applying them with `--apply`.
+
 ## Operator health
 
 Use `mdkg status --json` for a read-only operator summary before mutating a
@@ -461,6 +502,12 @@ rows are durable local project DB history; receipts, reducers, writer leases,
 and materializers remain internal helper surfaces in this release, with no
 public `mdkg db event`, `mdkg db reducer`, `mdkg db lease`, or
 `mdkg db materializer` CLI yet.
+`mdkg db queue contract --json` is the read-only public adapter contract for
+downstream integrations. It documents canonical payload hashing, dedupe keys,
+oldest-ready claim order, lease-owner checked ack/fail/dead-letter, retry
+delay, expired lease reclaim, max-attempt dead-letter behavior, pause/resume,
+snapshot queue policy, and stats without exposing raw SQL or making queue rows
+canonical runtime history.
 `mdkg work trigger --enqueue <queue>` can bridge a submitted work order mirror
 into an explicitly created active project DB queue; it writes local delivery
 state only and never executes work.
@@ -488,7 +535,7 @@ Goal nodes are durable recursive objective contracts. Use `mdkg new goal "<objec
 
 `goal` is work-like but distinct from `task`: it can have status, priority, graph links, skills, explicit `scope_refs`, and structured goal fields, but normal `mdkg next` does not select goals. Use `mdkg goal activate <goal-id>` to make one local root goal active, pause competing local active goals, and select it for future `goal next` calls. Use `mdkg goal select <goal-id>` only when you want to change the local ignored selected-goal pointer without changing lifecycle state. `mdkg goal next <goal-id>` remains available for explicit selection. Epics organize goal scope recursively but are not returned as executable work.
 
-Use `mdkg goal claim [goal-id] <work-id>` to durably set `active_node` after choosing the next scoped item. `goal next` is read-only. Use `mdkg goal pause|resume|done` to update goal state after review, and `mdkg goal archive` for superseded historical roadmap goals that should remain readable but non-actionable.
+Use `mdkg goal claim [goal-id] <work-id>` to durably set `active_node` after choosing the next scoped item. `goal next` is read-only. Use `mdkg goal pause|resume|done` to update goal state after review; closing a goal moves the final `active_node` to `last_active_node` so completed goals keep history without staying actionable. Use `mdkg goal archive` for superseded historical roadmap goals that should remain readable but non-actionable.
 
 Required checks are stored as report-only guidance. Agents should run the checks themselves, record evidence in the goal or active work item, then use `mdkg goal evaluate` to summarize the current evidence state. During normal goal execution, skill improvements should be recorded as improvement candidates or proposal nodes; edit `SKILL.md` files only when the active node is explicit skill-maintenance work.
 
@@ -528,7 +575,7 @@ Use `mdkg new spec|work|work_order|receipt|feedback|dispute|proposal "<title>"`
 
 Relational templates contain editable placeholder refs. `spec` and `work` scaffold as validation-clean standalone docs; `work_order`, `receipt`, `feedback`, `dispute`, and `proposal` need real refs before strict `mdkg validate` passes.
 
-For executable or purchasable capability mirrors, prefer the lifecycle helpers under `mdkg work ...`. They create and update `WORK.md`, `WORK_ORDER.md`, and `RECEIPT.md` semantic mirror files only. `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 for deterministic closeout. `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. Production order state, receipt state, feedback, disputes, payments, ledgers, marketplace inventory, fulfillment records, and execution state remain canonical outside mdkg, such as in Postgres or another application database. Do not store raw secrets, credentials, live payment state, ledger mutations, canonical marketplace state, or bulky raw payloads in these mirrors.
+For executable or purchasable capability mirrors, prefer the lifecycle helpers under `mdkg work ...`. They create and update `WORK.md`, `WORK_ORDER.md`, and `RECEIPT.md` semantic mirror files only. `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 for deterministic closeout. `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; it returns typed diagnostics and warns on obvious raw secret, prompt, token, or payload markers. `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. Production order state, receipt state, feedback, disputes, payments, ledgers, marketplace inventory, fulfillment records, and execution state remain canonical outside mdkg, such as in Postgres or another application database. Do not store raw secrets, credentials, live payment state, ledger mutations, canonical marketplace state, or bulky raw payloads in these mirrors.
 
 ## Archive sidecars