mdkg 0.3.5 → 0.3.7

package/dist/command-contract.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "tool": "mdkg",
-  "package_version": "0.3.5",
+  "package_version": "0.3.7",
   "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,10 +2571,23 @@
       "visibility": "public",
       "summary": "mdkg format command",
       "usage": [
-        "  mdkg format"
+        "  mdkg format",
+        "  mdkg format --headings [--dry-run|--apply] [--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] [--json]"
+        },
         {
           "name": "--help",
           "value": null,
@@ -2467,9 +2608,10 @@
         }
       ],
       "output_formats": [
-        "text"
+        "text",
+        "json"
       ],
-      "json_schema_ref": null,
+      "json_schema_ref": "mdkg.command_output.v1",
       "side_effects": [
         "normalize-graph-markdown"
       ],
@@ -2503,7 +2645,8 @@
         }
       ],
       "examples": [
-        "  mdkg format"
+        "  mdkg format",
+        "  mdkg format --headings [--dry-run|--apply] [--json]"
       ],
       "docs": {
         "help_target": "mdkg help format",
@@ -3726,9 +3869,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,
@@ -4012,13 +4161,13 @@
           "name": "--select-goal",
           "value": "requires",
           "required": false,
-          "description": "- --select-goal requires --start-goal and writes selected-goal state only after apply validation"
+          "description": "- --select-goal requires --start-goal; on apply it activates the imported start goal, pauses competing active root goals, validates, then writes selected-goal state"
         },
         {
           "name": "--start-goal",
-          "value": "and",
+          "value": null,
           "required": false,
-          "description": "- --select-goal requires --start-goal and writes selected-goal state only after apply validation"
+          "description": "- --select-goal requires --start-goal; on apply it activates the imported start goal, pauses competing active root goals, validates, then writes selected-goal state"
         },
         {
           "name": "--version",
@@ -4065,6 +4214,86 @@
         "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": [
@@ -4135,6 +4364,93 @@
         "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": [
@@ -4404,6 +4720,159 @@
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
+    {
+      "key": "mcp",
+      "path": [
+        "mcp"
+      ],
+      "category": "mcp",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg mcp command",
+      "usage": [
+        "  mdkg mcp serve --stdio"
+      ],
+      "args": [],
+      "flags": [
+        {
+          "name": "--help",
+          "value": null,
+          "required": false,
+          "description": "--help, -h          Show help"
+        },
+        {
+          "name": "--root",
+          "value": "<path>",
+          "required": false,
+          "description": "- use --root <path> to select the mdkg graph explicitly"
+        },
+        {
+          "name": "--stdio",
+          "value": null,
+          "required": false,
+          "description": "mdkg mcp serve --stdio"
+        },
+        {
+          "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 mcp serve --stdio"
+      ],
+      "docs": {
+        "help_target": "mdkg help mcp",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      }
+    },
+    {
+      "key": "mcp serve",
+      "path": [
+        "mcp",
+        "serve"
+      ],
+      "category": "mcp",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg mcp serve command",
+      "usage": [
+        "  mdkg mcp serve --stdio"
+      ],
+      "args": [],
+      "flags": [
+        {
+          "name": "--help",
+          "value": null,
+          "required": false,
+          "description": "--help, -h          Show help"
+        },
+        {
+          "name": "--root",
+          "value": null,
+          "required": false,
+          "description": "- starts one local Model Context Protocol server bound to the selected --root"
+        },
+        {
+          "name": "--stdio",
+          "value": null,
+          "required": false,
+          "description": "mdkg mcp serve --stdio"
+        },
+        {
+          "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 mcp serve --stdio"
+      ],
+      "docs": {
+        "help_target": "mdkg help mcp serve",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      }
+    },
     {
       "key": "new",
       "path": [
@@ -4706,6 +5175,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>",
@@ -6992,7 +7467,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": [
         {
@@ -7072,7 +7547,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]"
       ],
@@ -7446,10 +7921,16 @@
       "visibility": "public",
       "summary": "mdkg validate command",
       "usage": [
-        "  mdkg validate [--out <path>] [--quiet] [--json]"
+        "  mdkg validate [--out <path>] [--quiet] [--changed-only] [--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,
@@ -7500,7 +7981,7 @@
         }
       ],
       "examples": [
-        "  mdkg validate [--out <path>] [--quiet] [--json]"
+        "  mdkg validate [--out <path>] [--quiet] [--changed-only] [--json]"
       ],
       "docs": {
         "help_target": "mdkg help validate",
@@ -7521,9 +8002,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,
@@ -7551,9 +8038,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"
       ],
@@ -8120,6 +8608,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 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 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": [
@@ -8215,5 +8783,5 @@
       }
     }
   ],
-  "contract_hash": "2fd862666a24adc363a0912822b639f7e437bf5fd31dea13e6f4d87bf0a57d60"
+  "contract_hash": "e6b42d5850cb4e76b9cb29a21bb643b50c042667bb09c598ec3c7dd87f7cccdd"
 }