mdkg 0.3.6 → 0.3.8

package/CHANGELOG.md

@@ -8,6 +8,99 @@ mdkg is pre-v1 public alpha software. Command, graph, cache, bundle, and DAL con
 
 ## Unreleased
 
+## 0.3.8 - 2026-06-25
+
+### Added
+
+- Planned and began a warning-scale UX hardening lane for large multi-repo
+  mdkg orchestration runs.
+- Added bounded validation warning summaries, summary-mode output, and a clean
+  JSON receipt artifact path for warning-heavy validation workflows.
+- Added heading formatter summary-mode output for large recommended-heading
+  migration previews.
+- Added a packed warning UX smoke to prepublish automation so high-volume
+  warning output regressions are caught before release.
+
+### Changed
+
+- Renamed the reusable capability surface to canonical `MANIFEST.md`
+  terminology across scaffolds, help, command references, init assets, and
+  skills. `SPEC.md` and `mdkg spec ...` remain explicit legacy aliases for one
+  compatibility release, with manifest-first warnings and migration guidance.
+- Improved strict doctor, subgraph, and handoff remediation guidance for
+  multi-repo operators.
+- Updated repo-local skill guidance for child-first commit and root subgraph
+  refresh sequencing.
+
+## 0.3.7 - 2026-06-20
+
+### 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

package/CLI_COMMAND_MATRIX.md

@@ -1,7 +1,7 @@
 # CLI Command Matrix
 
-as_of: 2026-06-17
-package_version_in_source: 0.3.6
+as_of: 2026-06-21
+package_version_in_source: 0.3.8
 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
 
@@ -12,6 +12,18 @@ This file is the one place humans and LLMs should check for the live mdkg comman
 Verification commands:
 - `npm run cli:snapshot`
 - `npm run cli:check`
+- `npm run docs:check`
+- `npm run smoke:mdkg-dev`
+- `npm run smoke:mdkg-dev-docs`
+- `npm run smoke:mdkg-dev-seo`
+- `npm run smoke:demo-graph`
+
+mdkg.dev launch-readiness surfaces in this repo:
+- `mdkg-dev/` is the Astro static-site subproject.
+- `docs/` is the Starlight docs subproject and repo-first documentation source plus generated command-reference output.
+- `examples/` contains local mdkg demo/template graphs for agentic-coding and website-generation demos.
+- `demo_agentic_coding:goal-1` and `template_mdkg_dev:goal-1` are private read-only subgraph qids after the root bundles are registered.
+- Site/docs/demo assets are not npm runtime payload and must not imply production deploy, DNS change, analytics activation, or durable demo promotion.
 
 ## Teaching model
 
@@ -23,6 +35,7 @@ Primary commands:
 - `list`
 - `search`
 - `pack`
+- `handoff`
 - `skill`
 - `capability`
 - `spec`
@@ -54,7 +67,8 @@ Advanced / maintenance commands:
 Skills are first-class and are accessed only through `mdkg skill ...`.
 Generic `list/show/search` do not expose skills.
 Capability cache discovery is read-only and accessed through `mdkg capability ...`.
-Optional reusable SPEC capability records are accessed through `mdkg spec ...`.
+Reusable manifest capability records are accessed through `mdkg manifest ...`;
+`mdkg spec ...` remains a one-compatibility-release legacy alias.
 Archive sidecars are accessed through `mdkg archive ...`.
 Full graph snapshot bundles are accessed through `mdkg bundle ...`.
 Whole-graph clone, fork, and same-repo template import workflows are accessed through `mdkg graph ...`.
@@ -155,22 +169,26 @@ Types:
 - `test`
 
 Agent workflow file types:
-- `spec`
+- `manifest`
 - `work`
 - `work_order`
 - `receipt`
 - `feedback`
 - `dispute`
 - `proposal`
+- `spec` is a legacy alias for `manifest` during the compatibility bridge and
+  emits `MANIFEST.md`.
 
 Agent workflow file type creation:
-- `mdkg new spec "<title>" [options] [--json]`
+- `mdkg new manifest "<title>" [options] [--json]`
 - `mdkg new work "<title>" [options] [--json]`
 - `mdkg new work_order "<title>" [options] [--json]`
 - `mdkg new receipt "<title>" [options] [--json]`
 - `mdkg new feedback "<title>" [options] [--json]`
 - `mdkg new dispute "<title>" [options] [--json]`
 - `mdkg new proposal "<title>" [options] [--json]`
+- `mdkg new spec "<title>" [options] [--json]` is a deprecated alias for
+  `mdkg new manifest` and creates `MANIFEST.md` with `type: manifest`.
 
 Goal node creation:
 - `mdkg new goal "<title>" [options] [--json]`
@@ -349,6 +367,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`
@@ -363,6 +385,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`
 
@@ -489,7 +531,7 @@ Notes:
 
 When to use:
 - discover deterministic capability surfaces across enabled workspaces
-- query skills, `SPEC.md`, `WORK.md`, core docs, and design docs without loading the whole graph body set
+- query skills, canonical `MANIFEST.md`, legacy `SPEC.md`, `WORK.md`, core docs, and design docs without loading the whole graph body set
 
 Usage:
 - `mdkg capability list [--kind <kind>] [--visibility <level>] [--json]`
@@ -514,17 +556,48 @@ Notes:
 - `capability resolve` ranks local and subgraph capabilities deterministically for orchestration planning
 - stale subgraphs remain visible with degraded ranking unless `--fresh-only` is supplied
 - records include deterministic source metadata such as workspace, visibility, kind, id/qid/slug, path, headings, refs, source hash, and `indexed_at`
-- SPEC and WORK capability records include read-only `linkage` arrays for related SPECs, work contracts, work orders, and receipts when those graph mirrors exist
+- MANIFEST/SPEC and WORK capability records include read-only `linkage` arrays for related manifests, work contracts, work orders, and receipts when those graph mirrors exist
 - `.mdkg/index/capabilities.json` is rebuilt by `mdkg index` and by capability commands when stale
 - normal task, epic, feat, bug, test, spike, and checkpoint nodes are intentionally excluded
 - visibility is mdkg export metadata used by capability filters, `pack --visibility`, public bundle checks, validation, and doctor diagnostics; it is not secret scanning or body redaction
 
+### `mdkg manifest`
+
+When to use:
+- list reusable capability surfaces from canonical `MANIFEST.md` or legacy
+  `SPEC.md`
+- show one manifest capability record by id, qid, path, or alias
+- validate the graph while ensuring a named manifest capability exists
+
+Usage:
+- `mdkg manifest list [--json]`
+- `mdkg manifest show <id-or-qid-or-alias> [--json]`
+- `mdkg manifest validate [<id-or-qid-or-alias>] [--json]`
+
+Flags:
+- `--json`
+
+Notes:
+- `MANIFEST.md` is canonical and `SPEC.md` remains a legacy alias; repos with no
+  manifest/spec files remain valid
+- manifest records are reusable-capability oriented, not documentation-only
+  planning notes
+- `mdkg manifest validate` with no ref validates the graph and all
+  manifest/spec records
+- `mdkg manifest validate <ref>` also checks that the target manifest reference
+  exists
+- JSON records keep capability `kind: spec` for compatibility and include
+  manifest metadata describing canonical, legacy, or transitional source mode
+- use `mdkg capability ...` for broader skill, MANIFEST/SPEC, WORK, core-doc,
+  and design-doc capability discovery
+
 ### `mdkg spec`
 
 When to use:
-- list optional `SPEC.md` reusable capability surfaces
-- show one SPEC capability record by id, qid, path, or alias
-- validate the graph while ensuring a named SPEC capability exists
+- temporarily support existing scripts during the one-compatibility-release
+  bridge to `mdkg manifest ...`
+- list, show, or validate the same MANIFEST/SPEC capability records with legacy
+  command labeling
 
 Usage:
 - `mdkg spec list [--json]`
@@ -535,11 +608,14 @@ Flags:
 - `--json`
 
 Notes:
-- `SPEC.md` is optional; repos with no SPEC files remain valid
-- SPEC records are reusable-capability oriented, not documentation-only planning notes
-- `mdkg spec validate` with no ref validates the graph and all optional SPEC records
-- `mdkg spec validate <ref>` also checks that the target SPEC reference exists
-- use `mdkg capability ...` for broader skill, SPEC, WORK, core-doc, and design-doc capability discovery
+- `mdkg spec` is a legacy alias for `mdkg manifest` during the compatibility
+  bridge
+- `mdkg spec validate` with no ref validates the graph and all manifest/spec
+  records
+- `mdkg spec validate <ref>` also checks that the target manifest reference
+  exists
+- JSON receipts keep `kind: spec` and add `canonical_kind: manifest`,
+  `legacy_alias: true`, and deprecation metadata
 
 ### `mdkg archive`
 
@@ -624,12 +700,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>`
@@ -638,6 +716,7 @@ Flags:
 - `--id-prefix <prefix>`
 - `--dry-run`
 - `--apply`
+- `--ws <alias>`
 - `--json`
 
 Notes:
@@ -651,12 +730,14 @@ Notes:
 - 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; 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?, activated_goal?, paused_goals, index?, validation?, warnings }`
+- `refs`: `{ action: "graph.refs", ok, target, outgoing, incoming, warnings }`
 
 ### `mdkg subgraph`
 
@@ -745,19 +826,22 @@ 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 manifest|spec|work|work_order|receipt|feedback|dispute|proposal] [--json]`
 
 Notes:
 - work commands mutate 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
-- `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
+- `work trigger` accepts a `WORK.md` ref directly or a `MANIFEST.md` / legacy `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 new` accepts URI-style requester/request/trigger refs, archive input refs, optional queue refs, and stable payload hashes
 - `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 MANIFEST.md, legacy 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
 
@@ -767,6 +851,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`
 
@@ -799,7 +884,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.
@@ -807,7 +892,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.
 
@@ -832,7 +917,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`
 
@@ -868,12 +953,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:
@@ -902,16 +988,25 @@ When to use:
 - run the repo trust gate before calling work done
 
 Usage:
-- `mdkg validate [--out <path>] [--quiet] [--json]`
+- `mdkg validate [--out <path>] [--json-out <path>] [--quiet] [--changed-only] [--summary] [--limit <n>] [--json]`
+- `--changed-only` filters warning presentation to changed `.mdkg` files while full graph errors still run
+- `--summary` emits bounded warning samples for agent/CI logs; `--limit <n>` controls the sample size
+- `--out <path>` writes the compatibility text report; `--json-out <path>` writes a clean full JSON receipt
+- JSON receipts include `warning_summary` and `warning_diagnostics` with warning ids, categories, severity, paths, refs, and remediation text
 
 Flags:
 - `--out <path>`
+- `--json-out <path>`
 - `--quiet`
+- `--changed-only`
+- `--summary`
+- `--limit <n>`
 - `--json`
 
 JSON receipt:
-- `{ action: "validated", ok, warning_count, error_count, warnings, errors, report_path }`
+- `{ action: "validated", ok, warning_count, error_count, warnings, warning_diagnostics, warning_summary, errors, report_path?, json_receipt_path? }`
 - `report_path` is included only when `--out` is used.
+- `json_receipt_path` is included only when `--json-out` is used.
 
 Notes:
 - validates nodes, graph integrity, skills, and event log contracts
@@ -959,11 +1054,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`
 
@@ -1003,6 +1099,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]`
@@ -1023,6 +1120,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;
@@ -1064,6 +1165,13 @@ Usage:
 
 Usage:
 - `mdkg format`
+- `mdkg format --headings [--dry-run|--apply] [--summary] [--limit <n>] [--json]`
+
+Notes:
+- default `mdkg format` normalizes frontmatter in place
+- `mdkg format --headings` defaults to dry-run and returns planned missing-heading additions
+- `--summary` emits bounded heading-change samples for agent/CI logs; `--limit <n>` controls the sample size
+- `mdkg format --headings --apply` appends missing recommended body headings and returns a migration receipt
 
 ### `mdkg status`