mdkg 0.4.2 → 0.5.0

package/dist/command-contract.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "tool": "mdkg",
-  "package_version": "0.4.2",
+  "package_version": "0.5.0",
   "source": {
     "help_targets": "scripts/cli_help_targets.js",
     "command_matrix": "CLI_COMMAND_MATRIX.md"
@@ -5356,6 +5356,760 @@
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
+    {
+      "key": "loop",
+      "path": [
+        "loop"
+      ],
+      "category": "loop",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg loop command",
+      "usage": [
+        "mdkg loop list [--ws <alias>] [--json]",
+        "mdkg loop show <loop-or-template> [--meta] [--ws <alias>] [--json]",
+        "mdkg loop fork <template> --scope <scope> [--title <title>] [--materialization default_children|planning_only|manual] [--planning-only] [--no-children] [--dry-run] [--run-id <id>] [--ws <alias>] [--json]",
+        "mdkg loop plan <loop> [--ws <alias>] [--json]",
+        "mdkg loop next <loop> [--ws <alias>] [--json]",
+        "mdkg loop runs <loop> [--ws <alias>] [--json]"
+      ],
+      "args": [],
+      "flags": [
+        {
+          "name": "--root",
+          "value": "<path>",
+          "required": false,
+          "description": "Run against a specific repository root; -r is the short alias."
+        },
+        {
+          "name": "--ws",
+          "value": "<alias>",
+          "required": false,
+          "description": "Resolve the command against one workspace alias."
+        },
+        {
+          "name": "--json",
+          "value": null,
+          "required": false,
+          "description": "Emit deterministic JSON instead of text."
+        },
+        {
+          "name": "--no-cache",
+          "value": null,
+          "required": false,
+          "description": "Build a non-persisting in-memory index projection instead of reading the cache."
+        },
+        {
+          "name": "--no-reindex",
+          "value": null,
+          "required": false,
+          "description": "Do not rebuild a stale or missing index projection."
+        },
+        {
+          "name": "--run-id",
+          "value": "<id>",
+          "required": false,
+          "description": "Attach an optional run id to the fork event when event logging is enabled."
+        }
+      ],
+      "output_formats": [
+        "text",
+        "json"
+      ],
+      "json_schema_ref": "mdkg.command_output.v1",
+      "side_effects": [
+        "read-or-write-loop-graph-state"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [
+        ".mdkg/**/*.md",
+        ".mdkg/events/*.jsonl",
+        ".mdkg/index/**"
+      ],
+      "dry_run": {
+        "supported": true,
+        "commands": [
+          "fork"
+        ]
+      },
+      "lock_policy": "mutation-lock-required-for-fork",
+      "atomic_write_policy": "exclusive-create-and-atomic-file-writes",
+      "receipts": [
+        "loop-receipt"
+      ],
+      "danger_level": "mixed",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "mdkg loop fork <template> --scope <scope> [--title <title>] [--materialization default_children|planning_only|manual] [--planning-only] [--no-children] [--dry-run] [--run-id <id>] [--ws <alias>] [--json]",
+        "mdkg loop list [--ws <alias>] [--json]",
+        "mdkg loop show <loop-or-template> [--meta] [--ws <alias>] [--json]"
+      ],
+      "docs": {
+        "help_target": "mdkg help loop",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      },
+      "descriptor_source": "src/commands/loop_descriptors.ts",
+      "handler": "runLoopSubcommand",
+      "help_notes": [
+        "loop is one first-class node type. Templates, scoped forks, and run-bearing loops are represented through metadata and links.",
+        "mdkg defines reusable process state and graph context; runtimes execute agents, tools, sandboxes, traces, and model routing."
+      ]
+    },
+    {
+      "key": "loop fork",
+      "path": [
+        "loop",
+        "fork"
+      ],
+      "category": "loop",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg loop fork command",
+      "usage": [
+        "mdkg loop fork <template> --scope <scope> [--title <title>] [--materialization <mode>] [--planning-only] [--no-children] [--dry-run] [--run-id <id>] [--ws <alias>] [--no-cache] [--no-reindex] [--json]"
+      ],
+      "args": [
+        {
+          "name": "template",
+          "required": true,
+          "source": "<template>",
+          "description": "Loop template node id/qid or seed template name/ref."
+        }
+      ],
+      "flags": [
+        {
+          "name": "--scope",
+          "value": "<scope>",
+          "required": true,
+          "description": "Scope ref, qid, URI, path, or description for the scoped loop."
+        },
+        {
+          "name": "--title",
+          "value": "<title>",
+          "required": false,
+          "description": "Override the generated scoped loop title."
+        },
+        {
+          "name": "--materialization",
+          "value": "<mode>",
+          "required": false,
+          "description": "Child materialization mode: default_children, planning_only, or manual."
+        },
+        {
+          "name": "--planning-only",
+          "value": null,
+          "required": false,
+          "description": "Create only the scoped loop shell."
+        },
+        {
+          "name": "--no-children",
+          "value": null,
+          "required": false,
+          "description": "Alias for planning-only materialization."
+        },
+        {
+          "name": "--dry-run",
+          "value": null,
+          "required": false,
+          "description": "Plan the fork without writing loop or child nodes."
+        },
+        {
+          "name": "--run-id",
+          "value": "<id>",
+          "required": false,
+          "description": "Attach an optional run id to the fork event when event logging is enabled."
+        },
+        {
+          "name": "--root",
+          "value": "<path>",
+          "required": false,
+          "description": "Run against a specific repository root; -r is the short alias."
+        },
+        {
+          "name": "--ws",
+          "value": "<alias>",
+          "required": false,
+          "description": "Resolve the command against one workspace alias."
+        },
+        {
+          "name": "--json",
+          "value": null,
+          "required": false,
+          "description": "Emit deterministic JSON instead of text."
+        },
+        {
+          "name": "--no-cache",
+          "value": null,
+          "required": false,
+          "description": "Build a non-persisting in-memory index projection instead of reading the cache."
+        },
+        {
+          "name": "--no-reindex",
+          "value": null,
+          "required": false,
+          "description": "Do not rebuild a stale or missing index projection."
+        }
+      ],
+      "output_formats": [
+        "text",
+        "json"
+      ],
+      "json_schema_ref": "mdkg.command_output.v1",
+      "side_effects": [
+        "append-loop-fork-event-when-event-logging-is-enabled",
+        "create-scoped-loop-and-optional-child-nodes",
+        "rebuild-derived-indexes-when-auto-reindex-is-enabled",
+        "reserve-sqlite-node-ids-when-configured"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [
+        ".mdkg/**/*.md",
+        ".mdkg/events/*.jsonl",
+        ".mdkg/index/**"
+      ],
+      "dry_run": {
+        "supported": true,
+        "flag": "--dry-run",
+        "side_effects": [
+          "none"
+        ],
+        "write_paths": [],
+        "reserves_ids": false
+      },
+      "lock_policy": "mutation-lock-required",
+      "atomic_write_policy": "exclusive-create-and-atomic-file-writes",
+      "receipts": [
+        "loop-fork-receipt"
+      ],
+      "danger_level": "moderate",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "mdkg loop fork <template> --scope <scope> [--title <title>] [--materialization <mode>] [--planning-only] [--no-children] [--dry-run] [--run-id <id>] [--ws <alias>] [--no-cache] [--no-reindex] [--json]"
+      ],
+      "docs": {
+        "help_target": "mdkg help loop fork",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      },
+      "descriptor_source": "src/commands/loop_descriptors.ts",
+      "handler": "runLoopForkCommand",
+      "help_notes": [
+        "Seed templates resolve from .mdkg/templates/loops/<name>.loop.md.",
+        "Default forks create a scoped loop plus linked spike/task/test child nodes."
+      ]
+    },
+    {
+      "key": "loop list",
+      "path": [
+        "loop",
+        "list"
+      ],
+      "category": "loop",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg loop list command",
+      "usage": [
+        "mdkg loop list [--ws <alias>] [--no-cache] [--no-reindex] [--json]"
+      ],
+      "args": [],
+      "flags": [
+        {
+          "name": "--root",
+          "value": "<path>",
+          "required": false,
+          "description": "Run against a specific repository root; -r is the short alias."
+        },
+        {
+          "name": "--ws",
+          "value": "<alias>",
+          "required": false,
+          "description": "Resolve the command against one workspace alias."
+        },
+        {
+          "name": "--json",
+          "value": null,
+          "required": false,
+          "description": "Emit deterministic JSON instead of text."
+        },
+        {
+          "name": "--no-cache",
+          "value": null,
+          "required": false,
+          "description": "Build a non-persisting in-memory index projection instead of reading the cache."
+        },
+        {
+          "name": "--no-reindex",
+          "value": null,
+          "required": false,
+          "description": "Do not rebuild a stale or missing index projection."
+        }
+      ],
+      "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": [
+        "loop-list-receipt"
+      ],
+      "danger_level": "read-only",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "mdkg loop list [--ws <alias>] [--no-cache] [--no-reindex] [--json]"
+      ],
+      "docs": {
+        "help_target": "mdkg help loop list",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      },
+      "descriptor_source": "src/commands/loop_descriptors.ts",
+      "handler": "runLoopListCommand",
+      "help_notes": [
+        "Lists indexed loop nodes and reusable seed loop templates."
+      ]
+    },
+    {
+      "key": "loop next",
+      "path": [
+        "loop",
+        "next"
+      ],
+      "category": "loop",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg loop next command",
+      "usage": [
+        "mdkg loop next <loop> [--ws <alias>] [--no-cache] [--no-reindex] [--json]"
+      ],
+      "args": [
+        {
+          "name": "loop",
+          "required": true,
+          "source": "<loop>",
+          "description": "Loop node id or qid."
+        }
+      ],
+      "flags": [
+        {
+          "name": "--root",
+          "value": "<path>",
+          "required": false,
+          "description": "Run against a specific repository root; -r is the short alias."
+        },
+        {
+          "name": "--ws",
+          "value": "<alias>",
+          "required": false,
+          "description": "Resolve the command against one workspace alias."
+        },
+        {
+          "name": "--json",
+          "value": null,
+          "required": false,
+          "description": "Emit deterministic JSON instead of text."
+        },
+        {
+          "name": "--no-cache",
+          "value": null,
+          "required": false,
+          "description": "Build a non-persisting in-memory index projection instead of reading the cache."
+        },
+        {
+          "name": "--no-reindex",
+          "value": null,
+          "required": false,
+          "description": "Do not rebuild a stale or missing index projection."
+        }
+      ],
+      "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": [
+        "loop-next-receipt"
+      ],
+      "danger_level": "read-only",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "mdkg loop next <loop> [--ws <alias>] [--no-cache] [--no-reindex] [--json]"
+      ],
+      "docs": {
+        "help_target": "mdkg help loop next",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      },
+      "descriptor_source": "src/commands/loop_descriptors.ts",
+      "handler": "runLoopNextCommand",
+      "help_notes": [
+        "Read-only routing for the next actionable child, readiness lane, or blocker recovery step."
+      ]
+    },
+    {
+      "key": "loop plan",
+      "path": [
+        "loop",
+        "plan"
+      ],
+      "category": "loop",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg loop plan command",
+      "usage": [
+        "mdkg loop plan <loop> [--ws <alias>] [--no-cache] [--no-reindex] [--json]"
+      ],
+      "args": [
+        {
+          "name": "loop",
+          "required": true,
+          "source": "<loop>",
+          "description": "Loop node id or qid."
+        }
+      ],
+      "flags": [
+        {
+          "name": "--root",
+          "value": "<path>",
+          "required": false,
+          "description": "Run against a specific repository root; -r is the short alias."
+        },
+        {
+          "name": "--ws",
+          "value": "<alias>",
+          "required": false,
+          "description": "Resolve the command against one workspace alias."
+        },
+        {
+          "name": "--json",
+          "value": null,
+          "required": false,
+          "description": "Emit deterministic JSON instead of text."
+        },
+        {
+          "name": "--no-cache",
+          "value": null,
+          "required": false,
+          "description": "Build a non-persisting in-memory index projection instead of reading the cache."
+        },
+        {
+          "name": "--no-reindex",
+          "value": null,
+          "required": false,
+          "description": "Do not rebuild a stale or missing index projection."
+        }
+      ],
+      "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": [
+        "loop-plan-receipt"
+      ],
+      "danger_level": "read-only",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "mdkg loop plan <loop> [--ws <alias>] [--no-cache] [--no-reindex] [--json]"
+      ],
+      "docs": {
+        "help_target": "mdkg help loop plan",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      },
+      "descriptor_source": "src/commands/loop_descriptors.ts",
+      "handler": "runLoopPlanCommand",
+      "help_notes": [
+        "Read-only readiness cockpit for loop execution planning."
+      ]
+    },
+    {
+      "key": "loop runs",
+      "path": [
+        "loop",
+        "runs"
+      ],
+      "category": "loop",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg loop runs command",
+      "usage": [
+        "mdkg loop runs <loop> [--ws <alias>] [--no-cache] [--no-reindex] [--json]"
+      ],
+      "args": [
+        {
+          "name": "loop",
+          "required": true,
+          "source": "<loop>",
+          "description": "Loop node id or qid."
+        }
+      ],
+      "flags": [
+        {
+          "name": "--root",
+          "value": "<path>",
+          "required": false,
+          "description": "Run against a specific repository root; -r is the short alias."
+        },
+        {
+          "name": "--ws",
+          "value": "<alias>",
+          "required": false,
+          "description": "Resolve the command against one workspace alias."
+        },
+        {
+          "name": "--json",
+          "value": null,
+          "required": false,
+          "description": "Emit deterministic JSON instead of text."
+        },
+        {
+          "name": "--no-cache",
+          "value": null,
+          "required": false,
+          "description": "Build a non-persisting in-memory index projection instead of reading the cache."
+        },
+        {
+          "name": "--no-reindex",
+          "value": null,
+          "required": false,
+          "description": "Do not rebuild a stale or missing index projection."
+        }
+      ],
+      "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": [
+        "loop-runs-receipt"
+      ],
+      "danger_level": "read-only",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "mdkg loop runs <loop> [--ws <alias>] [--no-cache] [--no-reindex] [--json]"
+      ],
+      "docs": {
+        "help_target": "mdkg help loop runs",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      },
+      "descriptor_source": "src/commands/loop_descriptors.ts",
+      "handler": "runLoopRunsCommand",
+      "help_notes": [
+        "Lists run refs and evidence refs without executing runtime jobs."
+      ]
+    },
+    {
+      "key": "loop show",
+      "path": [
+        "loop",
+        "show"
+      ],
+      "category": "loop",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg loop show command",
+      "usage": [
+        "mdkg loop show <loop-or-template> [--meta] [--ws <alias>] [--no-cache] [--no-reindex] [--json]"
+      ],
+      "args": [
+        {
+          "name": "loop-or-template",
+          "required": true,
+          "source": "<loop-or-template>",
+          "description": "Loop node id/qid or seed template name/ref."
+        }
+      ],
+      "flags": [
+        {
+          "name": "--meta",
+          "value": null,
+          "required": false,
+          "description": "Show metadata without the full body."
+        },
+        {
+          "name": "--root",
+          "value": "<path>",
+          "required": false,
+          "description": "Run against a specific repository root; -r is the short alias."
+        },
+        {
+          "name": "--ws",
+          "value": "<alias>",
+          "required": false,
+          "description": "Resolve the command against one workspace alias."
+        },
+        {
+          "name": "--json",
+          "value": null,
+          "required": false,
+          "description": "Emit deterministic JSON instead of text."
+        },
+        {
+          "name": "--no-cache",
+          "value": null,
+          "required": false,
+          "description": "Build a non-persisting in-memory index projection instead of reading the cache."
+        },
+        {
+          "name": "--no-reindex",
+          "value": null,
+          "required": false,
+          "description": "Do not rebuild a stale or missing index projection."
+        }
+      ],
+      "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": [
+        "loop-show-receipt"
+      ],
+      "danger_level": "read-only",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "mdkg loop show <loop-or-template> [--meta] [--ws <alias>] [--no-cache] [--no-reindex] [--json]"
+      ],
+      "docs": {
+        "help_target": "mdkg help loop show",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      },
+      "descriptor_source": "src/commands/loop_descriptors.ts",
+      "handler": "runLoopShowCommand",
+      "help_notes": [
+        "Shows an indexed loop node or a seed loop template."
+      ]
+    },
     {
       "key": "manifest",
       "path": [
@@ -9794,5 +10548,5 @@
       }
     }
   ],
-  "contract_hash": "b6ce5590f19cd90b00820a9488c5773f2824c6525730d83d5f32d6e04612327c"
+  "contract_hash": "e9bd2d82d340887bc58d518c7e67541996f4b7744b2d1981763060575265aa29"
 }