mdkg 0.3.6 → 0.3.8

package/dist/command-contract.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "tool": "mdkg",
-  "package_version": "0.3.6",
+  "package_version": "0.3.8",
   "source": {
     "help_targets": "scripts/cli_help_targets.js",
     "command_matrix": "CLI_COMMAND_MATRIX.md"
@@ -1305,7 +1305,7 @@
       "visibility": "public",
       "summary": "mdkg checkpoint command",
       "usage": [
-        "  mdkg checkpoint new <title> [--ws <alias>] [--json]"
+        "  mdkg checkpoint new <title> [--kind implementation|test-proof|goal-closeout|audit|handoff] [--ws <alias>] [--json]"
       ],
       "args": [
         {
@@ -1370,7 +1370,7 @@
         }
       ],
       "examples": [
-        "  mdkg checkpoint new <title> [--ws <alias>] [--json]"
+        "  mdkg checkpoint new <title> [--kind implementation|test-proof|goal-closeout|audit|handoff] [--ws <alias>] [--json]"
       ],
       "docs": {
         "help_target": "mdkg help checkpoint",
@@ -1400,6 +1400,7 @@
         "  mdkg db queue ack|fail|dead-letter <queue> <message-id> --lease-owner <owner> [--json]",
         "  mdkg db queue pause|resume <queue> [--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]",
@@ -1593,6 +1594,133 @@
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
+    {
+      "key": "db queue",
+      "path": [
+        "db",
+        "queue"
+      ],
+      "category": "db",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg db queue command",
+      "usage": [
+        "  mdkg db queue create <queue> [--paused] [--reason <text>] [--json]",
+        "  mdkg db queue pause <queue> [--reason <text>] [--json]",
+        "  mdkg db queue resume <queue> [--json]",
+        "  mdkg db queue enqueue <queue> <message-id> --payload-json <json>|--payload-file <path> [--dedupe-key <key>] [--available-at-ms <ms>] [--max-attempts <n>] [--json]",
+        "  mdkg db queue claim <queue> --lease-owner <owner> --lease-ms <ms> [--json]",
+        "  mdkg db queue ack <queue> <message-id> --lease-owner <owner> [--json]",
+        "  mdkg db queue fail <queue> <message-id> --lease-owner <owner> --error <text> [--retry-after-ms <ms>] [--json]",
+        "  mdkg db queue dead-letter <queue> <message-id> --lease-owner <owner> --error <text> [--json]",
+        "  mdkg db queue release-expired [queue] [--json]",
+        "  mdkg db queue stats [queue] [--json]",
+        "  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 contract [--json]"
+      ],
+      "args": [
+        {
+          "name": "message-id",
+          "required": true,
+          "source": "<message-id>"
+        },
+        {
+          "name": "queue",
+          "required": true,
+          "source": "<queue>"
+        }
+      ],
+      "flags": [
+        {
+          "name": "--error",
+          "value": "<text>",
+          "required": false,
+          "description": "mdkg db queue fail <queue> <message-id> --lease-owner <owner> --error <text> [--retry-after-ms <ms>] [--json]"
+        },
+        {
+          "name": "--help",
+          "value": null,
+          "required": false,
+          "description": "--help, -h          Show help"
+        },
+        {
+          "name": "--lease-ms",
+          "value": "<ms>",
+          "required": false,
+          "description": "mdkg db queue claim <queue> --lease-owner <owner> --lease-ms <ms> [--json]"
+        },
+        {
+          "name": "--lease-owner",
+          "value": "<owner>",
+          "required": false,
+          "description": "mdkg db queue claim <queue> --lease-owner <owner> --lease-ms <ms> [--json]"
+        },
+        {
+          "name": "--payload-json",
+          "value": "<json>",
+          "required": false,
+          "description": "mdkg db queue enqueue <queue> <message-id> --payload-json <json>|--payload-file <path> [--dedupe-key <key>] [--available-at-ms <ms>] [--max-attempts <n>] [--json]"
+        },
+        {
+          "name": "--root",
+          "value": null,
+          "required": false,
+          "description": "--root, -r <path>   Run against a specific repo root"
+        },
+        {
+          "name": "--version",
+          "value": null,
+          "required": false,
+          "description": "--version, -V       Show version"
+        }
+      ],
+      "output_formats": [
+        "text",
+        "json"
+      ],
+      "json_schema_ref": "mdkg.project_db.queue.adapter.v1",
+      "side_effects": [
+        "emit-read-only-adapter-contract",
+        "read-or-write-local-project-db-queue-delivery-state"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [
+        ".mdkg/db/runtime/**"
+      ],
+      "dry_run": {
+        "supported": false
+      },
+      "lock_policy": "mutation-lock-required-for-create-pause-resume-enqueue-claim-ack-fail-dead-letter-release-expired",
+      "atomic_write_policy": "sqlite-transactions",
+      "receipts": [
+        "queue-adapter-contract-receipt",
+        "queue-receipt"
+      ],
+      "danger_level": "mixed",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "  mdkg db queue create <queue> [--paused] [--reason <text>] [--json]",
+        "  mdkg db queue pause <queue> [--reason <text>] [--json]",
+        "  mdkg db queue resume <queue> [--json]"
+      ],
+      "docs": {
+        "help_target": "mdkg help db queue",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      }
+    },
     {
       "key": "db snapshot",
       "path": [
@@ -2443,22 +2571,47 @@
       "visibility": "public",
       "summary": "mdkg format command",
       "usage": [
-        "  mdkg format"
+        "  mdkg format",
+        "  mdkg format --headings [--dry-run|--apply] [--summary] [--limit <n>] [--json]"
       ],
       "args": [],
       "flags": [
+        {
+          "name": "--apply",
+          "value": "to",
+          "required": false,
+          "description": "--headings adds missing recommended body headings; it defaults to dry-run and requires --apply to write files."
+        },
+        {
+          "name": "--headings",
+          "value": "[--dry-run|--apply]",
+          "required": false,
+          "description": "mdkg format --headings [--dry-run|--apply] [--summary] [--limit <n>] [--json]"
+        },
         {
           "name": "--help",
           "value": null,
           "required": false,
           "description": "--help, -h          Show help"
         },
+        {
+          "name": "--limit",
+          "value": "controls",
+          "required": false,
+          "description": "--summary emits bounded heading-change samples for agent/CI logs; --limit controls the sample size."
+        },
         {
           "name": "--root",
           "value": null,
           "required": false,
           "description": "--root, -r <path>   Run against a specific repo root"
         },
+        {
+          "name": "--summary",
+          "value": "emits",
+          "required": false,
+          "description": "--summary emits bounded heading-change samples for agent/CI logs; --limit controls the sample size."
+        },
         {
           "name": "--version",
           "value": null,
@@ -2467,9 +2620,10 @@
         }
       ],
       "output_formats": [
-        "text"
+        "text",
+        "json"
       ],
-      "json_schema_ref": null,
+      "json_schema_ref": "mdkg.command_output.v1",
       "side_effects": [
         "normalize-graph-markdown"
       ],
@@ -2503,7 +2657,8 @@
         }
       ],
       "examples": [
-        "  mdkg format"
+        "  mdkg format",
+        "  mdkg format --headings [--dry-run|--apply] [--summary] [--limit <n>] [--json]"
       ],
       "docs": {
         "help_target": "mdkg help format",
@@ -3726,9 +3881,15 @@
       "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 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]"
       ],
       "args": [
+        {
+          "name": "id-or-qid",
+          "required": true,
+          "source": "<id-or-qid>"
+        },
         {
           "name": "source-bundle-or-mdkg-dir",
           "required": true,
@@ -4058,26 +4219,540 @@
         }
       ],
       "examples": [
-        "  mdkg graph import-template <source-bundle-or-mdkg-dir> [--start-goal <goal-id>] [--select-goal] [--id-prefix <prefix>] [--dry-run] [--apply] [--json]"
+        "  mdkg graph import-template <source-bundle-or-mdkg-dir> [--start-goal <goal-id>] [--select-goal] [--id-prefix <prefix>] [--dry-run] [--apply] [--json]"
+      ],
+      "docs": {
+        "help_target": "mdkg help graph import-template",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      }
+    },
+    {
+      "key": "graph refs",
+      "path": [
+        "graph",
+        "refs"
+      ],
+      "category": "graph",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg graph refs command",
+      "usage": [
+        "  mdkg graph refs <id-or-qid> [--ws <alias>] [--json]"
+      ],
+      "args": [
+        {
+          "name": "id-or-qid",
+          "required": true,
+          "source": "<id-or-qid>"
+        }
+      ],
+      "flags": [
+        {
+          "name": "--help",
+          "value": null,
+          "required": false,
+          "description": "--help, -h          Show help"
+        },
+        {
+          "name": "--root",
+          "value": null,
+          "required": false,
+          "description": "--root, -r <path>   Run against a specific repo root"
+        },
+        {
+          "name": "--version",
+          "value": null,
+          "required": false,
+          "description": "--version, -V       Show version"
+        }
+      ],
+      "output_formats": [
+        "text",
+        "json"
+      ],
+      "json_schema_ref": "mdkg.command_output.v1",
+      "side_effects": [
+        "none"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [],
+      "dry_run": {
+        "supported": false
+      },
+      "lock_policy": "none-read-only",
+      "atomic_write_policy": "none-read-only",
+      "receipts": [
+        "graph-refs-receipt"
+      ],
+      "danger_level": "read-only",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "  mdkg graph refs <id-or-qid> [--ws <alias>] [--json]"
+      ],
+      "docs": {
+        "help_target": "mdkg help graph refs",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      }
+    },
+    {
+      "key": "guide",
+      "path": [
+        "guide"
+      ],
+      "category": "guide",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg guide command",
+      "usage": [
+        "  mdkg guide"
+      ],
+      "args": [],
+      "flags": [
+        {
+          "name": "--help",
+          "value": null,
+          "required": false,
+          "description": "--help, -h          Show help"
+        },
+        {
+          "name": "--root",
+          "value": null,
+          "required": false,
+          "description": "--root, -r <path>   Run against a specific repo root"
+        },
+        {
+          "name": "--version",
+          "value": null,
+          "required": false,
+          "description": "--version, -V       Show version"
+        }
+      ],
+      "output_formats": [
+        "text"
+      ],
+      "json_schema_ref": null,
+      "side_effects": [
+        "none"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [],
+      "dry_run": {
+        "supported": false
+      },
+      "lock_policy": "none-read-only",
+      "atomic_write_policy": "none-read-only",
+      "receipts": [],
+      "danger_level": "read-only",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "  mdkg guide"
+      ],
+      "docs": {
+        "help_target": "mdkg help guide",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      }
+    },
+    {
+      "key": "handoff",
+      "path": [
+        "handoff"
+      ],
+      "category": "handoff",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg handoff command",
+      "usage": [
+        "  mdkg handoff create <id-or-qid> [--ws <alias>] [--depth <n>] [--out <path>] [--json]"
+      ],
+      "args": [
+        {
+          "name": "id-or-qid",
+          "required": true,
+          "source": "<id-or-qid>"
+        }
+      ],
+      "flags": [
+        {
+          "name": "--help",
+          "value": null,
+          "required": false,
+          "description": "--help, -h          Show help"
+        },
+        {
+          "name": "--out",
+          "value": "must",
+          "required": false,
+          "description": "- --out must stay inside the repo root"
+        },
+        {
+          "name": "--root",
+          "value": null,
+          "required": false,
+          "description": "--root, -r <path>   Run against a specific repo root"
+        },
+        {
+          "name": "--version",
+          "value": null,
+          "required": false,
+          "description": "--version, -V       Show version"
+        }
+      ],
+      "output_formats": [
+        "text",
+        "json"
+      ],
+      "json_schema_ref": "mdkg.handoff.v1",
+      "side_effects": [
+        "create-sanitized-agent-handoff-when-out-is-provided"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [
+        ".mdkg/handoffs/**"
+      ],
+      "dry_run": {
+        "supported": false
+      },
+      "lock_policy": "not-required-for-stdout-output",
+      "atomic_write_policy": "atomic-file-write-when-out-is-provided",
+      "receipts": [
+        "handoff-receipt"
+      ],
+      "danger_level": "moderate",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "  mdkg handoff create <id-or-qid> [--ws <alias>] [--depth <n>] [--out <path>] [--json]"
+      ],
+      "docs": {
+        "help_target": "mdkg help handoff",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      }
+    },
+    {
+      "key": "index",
+      "path": [
+        "index"
+      ],
+      "category": "index",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg index command",
+      "usage": [
+        "  mdkg index [--tolerant]"
+      ],
+      "args": [],
+      "flags": [
+        {
+          "name": "--help",
+          "value": null,
+          "required": false,
+          "description": "--help, -h          Show help"
+        },
+        {
+          "name": "--root",
+          "value": null,
+          "required": false,
+          "description": "--root, -r <path>   Run against a specific repo root"
+        },
+        {
+          "name": "--version",
+          "value": null,
+          "required": false,
+          "description": "--version, -V       Show version"
+        }
+      ],
+      "output_formats": [
+        "text"
+      ],
+      "json_schema_ref": null,
+      "side_effects": [
+        "rebuild-generated-index-cache"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [
+        ".mdkg/index/**"
+      ],
+      "dry_run": {
+        "supported": false
+      },
+      "lock_policy": "mutation-lock-required",
+      "atomic_write_policy": "sqlite-transaction-and-atomic-cache-write",
+      "receipts": [
+        "index-rebuild-receipt"
+      ],
+      "danger_level": "moderate",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "  mdkg index [--tolerant]"
+      ],
+      "docs": {
+        "help_target": "mdkg help index",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      }
+    },
+    {
+      "key": "init",
+      "path": [
+        "init"
+      ],
+      "category": "init",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg init command",
+      "usage": [
+        "  mdkg init [options]"
+      ],
+      "args": [
+        {
+          "name": "options",
+          "required": false,
+          "source": "[options]"
+        }
+      ],
+      "flags": [
+        {
+          "name": "--agent",
+          "value": null,
+          "required": false,
+          "description": "--agent               Create the complete agent bootstrap, skills, events, and mirrors"
+        },
+        {
+          "name": "--force",
+          "value": null,
+          "required": false,
+          "description": "--force               Overwrite existing mdkg files"
+        },
+        {
+          "name": "--help",
+          "value": null,
+          "required": false,
+          "description": "--help, -h          Show help"
+        },
+        {
+          "name": "--no-update-ignores",
+          "value": null,
+          "required": false,
+          "description": "--no-update-ignores   Skip default .gitignore/.npmignore updates"
+        },
+        {
+          "name": "--root",
+          "value": null,
+          "required": false,
+          "description": "--root, -r <path>   Run against a specific repo root"
+        },
+        {
+          "name": "--update-dockerignore",
+          "value": "Append",
+          "required": false,
+          "description": "--update-dockerignore Append mdkg ignore entries"
+        },
+        {
+          "name": "--update-gitignore",
+          "value": null,
+          "required": false,
+          "description": "--update-gitignore    Append mdkg ignore entries"
+        },
+        {
+          "name": "--update-npmignore",
+          "value": null,
+          "required": false,
+          "description": "--update-npmignore    Append mdkg ignore entries"
+        },
+        {
+          "name": "--version",
+          "value": null,
+          "required": false,
+          "description": "--version, -V       Show version"
+        }
+      ],
+      "output_formats": [
+        "text"
+      ],
+      "json_schema_ref": null,
+      "side_effects": [
+        "initialize-mdkg-scaffold"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [
+        ".mdkg/**",
+        "AGENTS.md",
+        "AGENT_START.md",
+        "CLAUDE.md",
+        "CLI_COMMAND_MATRIX.md",
+        "llms.txt"
+      ],
+      "dry_run": {
+        "supported": false
+      },
+      "lock_policy": "not-required-before-mdkg-config-exists",
+      "atomic_write_policy": "exclusive-create-and-atomic-file-writes",
+      "receipts": [
+        "init-summary"
+      ],
+      "danger_level": "moderate",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "  mdkg init [options]"
+      ],
+      "docs": {
+        "help_target": "mdkg help init",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      }
+    },
+    {
+      "key": "list",
+      "path": [
+        "list"
+      ],
+      "category": "list",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg list command",
+      "usage": [
+        "  mdkg list [--type <type>] [--status <status>] [--ws <alias>] [--epic <id>]"
+      ],
+      "args": [],
+      "flags": [
+        {
+          "name": "--help",
+          "value": null,
+          "required": false,
+          "description": "--help, -h          Show help"
+        },
+        {
+          "name": "--root",
+          "value": null,
+          "required": false,
+          "description": "--root, -r <path>   Run against a specific repo root"
+        },
+        {
+          "name": "--version",
+          "value": null,
+          "required": false,
+          "description": "--version, -V       Show version"
+        }
+      ],
+      "output_formats": [
+        "text",
+        "json",
+        "xml",
+        "toon",
+        "md"
+      ],
+      "json_schema_ref": "mdkg.command_output.v1",
+      "side_effects": [
+        "none"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [],
+      "dry_run": {
+        "supported": false
+      },
+      "lock_policy": "none-read-only",
+      "atomic_write_policy": "none-read-only",
+      "receipts": [],
+      "danger_level": "read-only",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "  mdkg list [--type <type>] [--status <status>] [--ws <alias>] [--epic <id>]"
       ],
       "docs": {
-        "help_target": "mdkg help graph import-template",
+        "help_target": "mdkg help list",
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
     {
-      "key": "guide",
+      "key": "manifest",
       "path": [
-        "guide"
+        "manifest"
       ],
-      "category": "guide",
+      "category": "manifest",
       "status": "stable",
       "visibility": "public",
-      "summary": "mdkg guide command",
+      "summary": "mdkg manifest command",
       "usage": [
-        "  mdkg guide"
+        "  mdkg manifest list [--json]",
+        "  mdkg manifest show <id-or-qid-or-alias> [--json]",
+        "  mdkg manifest validate [<id-or-qid-or-alias>] [--json]"
+      ],
+      "args": [
+        {
+          "name": "id-or-qid-or-alias",
+          "required": true,
+          "source": "<id-or-qid-or-alias>"
+        }
       ],
-      "args": [],
       "flags": [
         {
           "name": "--help",
@@ -4099,9 +4774,10 @@
         }
       ],
       "output_formats": [
-        "text"
+        "text",
+        "json"
       ],
-      "json_schema_ref": null,
+      "json_schema_ref": "mdkg.command_output.v1",
       "side_effects": [
         "none"
       ],
@@ -4128,24 +4804,27 @@
         }
       ],
       "examples": [
-        "  mdkg guide"
+        "  mdkg manifest list [--json]",
+        "  mdkg manifest show <id-or-qid-or-alias> [--json]",
+        "  mdkg manifest validate [<id-or-qid-or-alias>] [--json]"
       ],
       "docs": {
-        "help_target": "mdkg help guide",
+        "help_target": "mdkg help manifest",
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
     {
-      "key": "index",
+      "key": "manifest list",
       "path": [
-        "index"
+        "manifest",
+        "list"
       ],
-      "category": "index",
+      "category": "manifest",
       "status": "stable",
       "visibility": "public",
-      "summary": "mdkg index command",
+      "summary": "mdkg manifest list command",
       "usage": [
-        "  mdkg index [--tolerant]"
+        "  mdkg manifest list [--json]"
       ],
       "args": [],
       "flags": [
@@ -4169,27 +4848,24 @@
         }
       ],
       "output_formats": [
-        "text"
+        "text",
+        "json"
       ],
-      "json_schema_ref": null,
+      "json_schema_ref": "mdkg.command_output.v1",
       "side_effects": [
-        "rebuild-generated-index-cache"
+        "none"
       ],
       "read_paths": [
         ".mdkg/**"
       ],
-      "write_paths": [
-        ".mdkg/index/**"
-      ],
+      "write_paths": [],
       "dry_run": {
         "supported": false
       },
-      "lock_policy": "mutation-lock-required",
-      "atomic_write_policy": "sqlite-transaction-and-atomic-cache-write",
-      "receipts": [
-        "index-rebuild-receipt"
-      ],
-      "danger_level": "moderate",
+      "lock_policy": "none-read-only",
+      "atomic_write_policy": "none-read-only",
+      "receipts": [],
+      "danger_level": "read-only",
       "aliases": [],
       "exit_codes": [
         {
@@ -4202,81 +4878,46 @@
         }
       ],
       "examples": [
-        "  mdkg index [--tolerant]"
+        "  mdkg manifest list [--json]"
       ],
       "docs": {
-        "help_target": "mdkg help index",
+        "help_target": "mdkg help manifest list",
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
     {
-      "key": "init",
+      "key": "manifest show",
       "path": [
-        "init"
+        "manifest",
+        "show"
       ],
-      "category": "init",
+      "category": "manifest",
       "status": "stable",
       "visibility": "public",
-      "summary": "mdkg init command",
+      "summary": "mdkg manifest show command",
       "usage": [
-        "  mdkg init [options]"
+        "  mdkg manifest show <id-or-qid-or-alias> [--json]"
       ],
       "args": [
         {
-          "name": "options",
-          "required": false,
-          "source": "[options]"
+          "name": "id-or-qid-or-alias",
+          "required": true,
+          "source": "<id-or-qid-or-alias>"
         }
       ],
       "flags": [
-        {
-          "name": "--agent",
-          "value": null,
-          "required": false,
-          "description": "--agent               Create the complete agent bootstrap, skills, events, and mirrors"
-        },
-        {
-          "name": "--force",
-          "value": null,
-          "required": false,
-          "description": "--force               Overwrite existing mdkg files"
-        },
         {
           "name": "--help",
           "value": null,
           "required": false,
           "description": "--help, -h          Show help"
         },
-        {
-          "name": "--no-update-ignores",
-          "value": null,
-          "required": false,
-          "description": "--no-update-ignores   Skip default .gitignore/.npmignore updates"
-        },
         {
           "name": "--root",
           "value": null,
           "required": false,
           "description": "--root, -r <path>   Run against a specific repo root"
         },
-        {
-          "name": "--update-dockerignore",
-          "value": "Append",
-          "required": false,
-          "description": "--update-dockerignore Append mdkg ignore entries"
-        },
-        {
-          "name": "--update-gitignore",
-          "value": null,
-          "required": false,
-          "description": "--update-gitignore    Append mdkg ignore entries"
-        },
-        {
-          "name": "--update-npmignore",
-          "value": null,
-          "required": false,
-          "description": "--update-npmignore    Append mdkg ignore entries"
-        },
         {
           "name": "--version",
           "value": null,
@@ -4285,32 +4926,24 @@
         }
       ],
       "output_formats": [
-        "text"
+        "text",
+        "json"
       ],
-      "json_schema_ref": null,
+      "json_schema_ref": "mdkg.command_output.v1",
       "side_effects": [
-        "initialize-mdkg-scaffold"
+        "none"
       ],
       "read_paths": [
         ".mdkg/**"
       ],
-      "write_paths": [
-        ".mdkg/**",
-        "AGENTS.md",
-        "AGENT_START.md",
-        "CLAUDE.md",
-        "CLI_COMMAND_MATRIX.md",
-        "llms.txt"
-      ],
+      "write_paths": [],
       "dry_run": {
         "supported": false
       },
-      "lock_policy": "not-required-before-mdkg-config-exists",
-      "atomic_write_policy": "exclusive-create-and-atomic-file-writes",
-      "receipts": [
-        "init-summary"
-      ],
-      "danger_level": "moderate",
+      "lock_policy": "none-read-only",
+      "atomic_write_policy": "none-read-only",
+      "receipts": [],
+      "danger_level": "read-only",
       "aliases": [],
       "exit_codes": [
         {
@@ -4323,26 +4956,33 @@
         }
       ],
       "examples": [
-        "  mdkg init [options]"
+        "  mdkg manifest show <id-or-qid-or-alias> [--json]"
       ],
       "docs": {
-        "help_target": "mdkg help init",
+        "help_target": "mdkg help manifest show",
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
     {
-      "key": "list",
+      "key": "manifest validate",
       "path": [
-        "list"
+        "manifest",
+        "validate"
       ],
-      "category": "list",
+      "category": "manifest",
       "status": "stable",
       "visibility": "public",
-      "summary": "mdkg list command",
+      "summary": "mdkg manifest validate command",
       "usage": [
-        "  mdkg list [--type <type>] [--status <status>] [--ws <alias>] [--epic <id>]"
+        "  mdkg manifest validate [<id-or-qid-or-alias>] [--json]"
+      ],
+      "args": [
+        {
+          "name": "id-or-qid-or-alias",
+          "required": true,
+          "source": "<id-or-qid-or-alias>"
+        }
       ],
-      "args": [],
       "flags": [
         {
           "name": "--help",
@@ -4365,10 +5005,7 @@
       ],
       "output_formats": [
         "text",
-        "json",
-        "xml",
-        "toon",
-        "md"
+        "json"
       ],
       "json_schema_ref": "mdkg.command_output.v1",
       "side_effects": [
@@ -4397,10 +5034,10 @@
         }
       ],
       "examples": [
-        "  mdkg list [--type <type>] [--status <status>] [--ws <alias>] [--epic <id>]"
+        "  mdkg manifest validate [<id-or-qid-or-alias>] [--json]"
       ],
       "docs": {
-        "help_target": "mdkg help list",
+        "help_target": "mdkg help manifest validate",
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
@@ -4859,6 +5496,12 @@
           "required": false,
           "description": "--dry-run                Preview selection/order/stats without writing files"
         },
+        {
+          "name": "--edges",
+          "value": "accepts",
+          "required": false,
+          "description": "--edges accepts parent, epic, relates, blocked_by, blocks, prev, next, context_refs, evidence_refs"
+        },
         {
           "name": "--format",
           "value": "<fmt>",
@@ -7145,7 +7788,7 @@
       "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]"
       ],
       "args": [
         {
@@ -7225,7 +7868,7 @@
         }
       ],
       "examples": [
-        "  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 <id-or-qid> [--ws <alias>] [--run-id <id>] [--note \"<text>\"] [--json]",
         "  mdkg task update <id-or-qid> [options] [--json]"
       ],
@@ -7599,22 +8242,52 @@
       "visibility": "public",
       "summary": "mdkg validate command",
       "usage": [
-        "  mdkg validate [--out <path>] [--quiet] [--json]"
+        "  mdkg validate [--out <path>] [--json-out <path>] [--quiet] [--changed-only] [--summary] [--limit <n>] [--json]"
       ],
       "args": [],
       "flags": [
+        {
+          "name": "--changed-only",
+          "value": "filters",
+          "required": false,
+          "description": "--changed-only filters warning presentation to changed .mdkg files while full graph errors still run."
+        },
         {
           "name": "--help",
           "value": null,
           "required": false,
           "description": "--help, -h          Show help"
         },
+        {
+          "name": "--json-out",
+          "value": "writes",
+          "required": false,
+          "description": "--out writes the compatibility text report; --json-out writes a clean full JSON receipt."
+        },
+        {
+          "name": "--limit",
+          "value": "controls",
+          "required": false,
+          "description": "--summary emits bounded warning samples for agent/CI logs; --limit controls the sample size."
+        },
+        {
+          "name": "--out",
+          "value": "writes",
+          "required": false,
+          "description": "--out writes the compatibility text report; --json-out writes a clean full JSON receipt."
+        },
         {
           "name": "--root",
           "value": null,
           "required": false,
           "description": "--root, -r <path>   Run against a specific repo root"
         },
+        {
+          "name": "--summary",
+          "value": "emits",
+          "required": false,
+          "description": "--summary emits bounded warning samples for agent/CI logs; --limit controls the sample size."
+        },
         {
           "name": "--version",
           "value": null,
@@ -7653,7 +8326,7 @@
         }
       ],
       "examples": [
-        "  mdkg validate [--out <path>] [--quiet] [--json]"
+        "  mdkg validate [--out <path>] [--json-out <path>] [--quiet] [--changed-only] [--summary] [--limit <n>] [--json]"
       ],
       "docs": {
         "help_target": "mdkg help validate",
@@ -7674,9 +8347,15 @@
         "  mdkg work trigger <work-or-capability-ref> ...",
         "  mdkg work order new|status|update ...",
         "  mdkg work receipt new|verify|update ...",
-        "  mdkg work artifact add ..."
+        "  mdkg work artifact add ...",
+        "  mdkg work validate [<id-or-qid>] [--type <workflow-type>] [--json]"
       ],
       "args": [
+        {
+          "name": "id-or-qid",
+          "required": true,
+          "source": "<id-or-qid>"
+        },
         {
           "name": "work-or-capability-ref",
           "required": true,
@@ -7704,9 +8383,10 @@
         }
       ],
       "output_formats": [
-        "text"
+        "text",
+        "json"
       ],
-      "json_schema_ref": null,
+      "json_schema_ref": "mdkg.command_output.v1",
       "side_effects": [
         "read-or-write-work-contract-mirrors"
       ],
@@ -8273,6 +8953,86 @@
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
+    {
+      "key": "work validate",
+      "path": [
+        "work",
+        "validate"
+      ],
+      "category": "work",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg work validate command",
+      "usage": [
+        "  mdkg work validate [<id-or-qid>] [--type manifest|spec|work|work_order|receipt|feedback|dispute|proposal] [--json]"
+      ],
+      "args": [
+        {
+          "name": "id-or-qid",
+          "required": true,
+          "source": "<id-or-qid>"
+        }
+      ],
+      "flags": [
+        {
+          "name": "--help",
+          "value": null,
+          "required": false,
+          "description": "--help, -h          Show help"
+        },
+        {
+          "name": "--root",
+          "value": null,
+          "required": false,
+          "description": "--root, -r <path>   Run against a specific repo root"
+        },
+        {
+          "name": "--version",
+          "value": null,
+          "required": false,
+          "description": "--version, -V       Show version"
+        }
+      ],
+      "output_formats": [
+        "text",
+        "json"
+      ],
+      "json_schema_ref": "mdkg.work_validate.v1",
+      "side_effects": [
+        "none"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [],
+      "dry_run": {
+        "supported": false
+      },
+      "lock_policy": "none-read-only",
+      "atomic_write_policy": "none-read-only",
+      "receipts": [
+        "work-validate-receipt"
+      ],
+      "danger_level": "read-only",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "  mdkg work validate [<id-or-qid>] [--type manifest|spec|work|work_order|receipt|feedback|dispute|proposal] [--json]"
+      ],
+      "docs": {
+        "help_target": "mdkg help work validate",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      }
+    },
     {
       "key": "workspace",
       "path": [
@@ -8368,5 +9128,5 @@
       }
     }
   ],
-  "contract_hash": "130236f8a2c5c757528f82acf95f43fb67809a0ddb333ebffa5d69b452a20146"
+  "contract_hash": "145781176fcd00d6b7c7edd8e013e902acea2ace8764dbf0bb063a8d3913a3e1"
 }