mdkg 0.3.6 → 0.3.8

package/dist/cli.js

@@ -15,6 +15,7 @@ const list_1 = require("./commands/list");
 const search_1 = require("./commands/search");
 const show_1 = require("./commands/show");
 const pack_1 = require("./commands/pack");
+const handoff_1 = require("./commands/handoff");
 const next_1 = require("./commands/next");
 const validate_1 = require("./commands/validate");
 const format_1 = require("./commands/format");
@@ -67,12 +68,14 @@ function printUsage(log) {
     log("  list        List nodes with filters");
     log("  search      Search nodes by query");
     log("  pack        Generate a context pack");
+    log("  handoff     Create sanitized agent handoff prompts from graph context");
     log("  skill       Create, list, show, search, and validate skills");
     log("  capability  List, search, show, and resolve cached capability surfaces");
-    log("  spec        List, show, and validate optional SPEC.md capability records");
+    log("  manifest    List, show, and validate MANIFEST.md/SPEC.md capability records");
+    log("  spec        Legacy alias for `mdkg manifest` during the compatibility bridge");
     log("  archive     Add, list, show, verify, and compress archive sidecars");
     log("  bundle      Create, list, show, and verify full graph snapshot bundles");
-    log("  graph       Clone and fork whole mdkg graphs");
+    log("  graph       Clone, fork, import, and inspect mdkg graph references");
     log("  subgraph    Register, audit, plan, sync, materialize, and verify read-only child graph snapshots");
     log("  work        Create and update work contracts, orders, receipts, and artifacts");
     log("  goal        Inspect and advance recursive goal nodes");
@@ -143,7 +146,8 @@ function printNewHelp(log) {
     log("\nTypes:");
     log("  rule prd edd dec prop goal epic feat task bug spike checkpoint test");
     log("\nAgent workflow file types:");
-    log("  spec work work_order receipt feedback dispute proposal");
+    log("  manifest work work_order receipt feedback dispute proposal");
+    log("  spec is a legacy alias for manifest and emits MANIFEST.md during the compatibility bridge.");
     log("  Use --id <portable-id> with these types for semantic ids like agent.image-worker.");
     log("  Use `mdkg archive add` for archive sidecars instead of `mdkg new archive`.");
     log("\nOptions:");
@@ -161,7 +165,8 @@ function printNewHelp(log) {
     log("  --links --artifacts --refs --aliases --owners --cases --supersedes");
     log("  --owners <owner,owner,...> Owners");
     log("\nNotes:");
-    log("  spec/work scaffold as validation-clean docs; relational workflow docs need real refs.");
+    log("  manifest/work scaffold as validation-clean docs; relational workflow docs need real refs.");
+    log("  mdkg new spec is deprecated; use mdkg new manifest for new reusable capability manifests.");
     log("  spike creates actionable research/planning work; use `mdkg task ...` for lifecycle.");
     log("  record spike research evidence by editing the Markdown body sections.");
     log("  spikes do not run web search, create follow-up nodes, generate SKILL.md, or expose `mdkg spike ...`.");
@@ -236,8 +241,10 @@ function printDbHelp(log, subcommand) {
             log("  mdkg db queue stats [queue] [--json]");
             log("  mdkg db queue list <queue> [--status ready|leased|acked|dead_letter|all] [--limit <n>] [--json]");
             log("  mdkg db queue show <queue> <message-id> [--json]");
+            log("  mdkg db queue contract [--json]");
             log("\nSemantics:");
             log("  - queues are durable local delivery state, not canonical event history");
+            log("  - contract is read-only adapter metadata and does not require an initialized project DB");
             log("  - paused queues reject enqueue and claim");
             log("  - ack, fail, dead-letter, and release-expired are allowed while paused so leased work can settle");
             log("  - no raw SQL or hosted queue dependency is exposed");
@@ -258,6 +265,7 @@ function printDbHelp(log, subcommand) {
             log("  mdkg db queue ack|fail|dead-letter <queue> <message-id> --lease-owner <owner> [--json]");
             log("  mdkg db queue pause|resume <queue> [--json]");
             log("  mdkg db queue stats|list|show ... [--json]");
+            log("  mdkg db queue contract [--json]");
             log("  mdkg db snapshot seal [--queue-policy drain|paused] [--json]");
             log("  mdkg db snapshot verify [--json]");
             log("  mdkg db snapshot status [--json]");
@@ -326,12 +334,14 @@ function printPackHelp(log) {
     log("      --list-profiles          List built-in pack profiles and exit");
     log("\nAdvanced shaping / debug flags:");
     log("  --depth --edges --strip-code --max-code-lines --max-chars --max-lines --max-tokens");
+    log("  --edges accepts parent, epic, relates, blocked_by, blocks, prev, next, context_refs, evidence_refs");
     log("  --truncation-report --stats-out");
     log("\nExamples:");
     log("  mdkg pack --list-profiles");
     log("  mdkg pack task-1");
     log("  mdkg pack task-1 --profile concise --dry-run --stats");
     log("  mdkg pack task-1 --visibility public --dry-run");
+    log("  mdkg pack task-1 --edges context_refs,evidence_refs --format json");
     log("  mdkg pack task-1 --skills auto --skills-depth full");
     log("  mdkg pack epic-2 --format json --profile headers");
     printGlobalOptions(log);
@@ -347,6 +357,19 @@ function printPackProfiles(log) {
         }
     }
 }
+function printHandoffHelp(log) {
+    log("Usage:");
+    log("  mdkg handoff create <id-or-qid> [--ws <alias>] [--depth <n>] [--out <path>] [--json]");
+    log("\nPurpose:");
+    log("  - create a sanitized, copy-ready agent handoff from mdkg graph context");
+    log("  - summarize goal/work state, included pack nodes, latest checkpoint, boundaries, required checks, and next actions");
+    log("  - include raw secret, prompt, token, or payload marker warnings without copying raw node bodies into the handoff");
+    log("  - use pack traversal with context_refs and evidence_refs for background and proof nodes");
+    log("\nBoundaries:");
+    log("  - handoff create does not execute work, mutate graph nodes, or generate detailed node content");
+    log("  - --out must stay inside the repo root");
+    printGlobalOptions(log);
+}
 function printSkillHelp(log, subcommand) {
     switch ((subcommand ?? "").toLowerCase()) {
         case "new":
@@ -449,38 +472,54 @@ function printCapabilityHelp(log, subcommand) {
             printGlobalOptions(log);
     }
 }
-function printSpecHelp(log, subcommand) {
+function printSpecHelp(log, subcommand, surface = "spec") {
+    const command = surface === "manifest" ? "manifest" : "spec";
+    const legacyNote = surface === "spec"
+        ? "  `mdkg spec` is the legacy alias for `mdkg manifest` during the compatibility bridge."
+        : undefined;
     switch ((subcommand ?? "").toLowerCase()) {
         case "list":
             log("Usage:");
-            log("  mdkg spec list [--json]");
+            log(`  mdkg ${command} list [--json]`);
             log("\nNotes:");
-            log("  SPEC.md is optional and declares reusable capability surfaces.");
+            log("  MANIFEST.md is canonical; SPEC.md remains a legacy alias for reusable capability surfaces.");
+            if (legacyNote) {
+                log(legacyNote);
+            }
             printGlobalOptions(log);
             return;
         case "show":
             log("Usage:");
-            log("  mdkg spec show <id-or-qid-or-alias> [--json]");
+            log(`  mdkg ${command} show <id-or-qid-or-alias> [--json]`);
             log("\nNotes:");
-            log("  Shows one optional SPEC.md capability record from the capability index.");
+            log("  Shows one MANIFEST.md/SPEC.md capability record from the capability index.");
+            if (legacyNote) {
+                log(legacyNote);
+            }
             printGlobalOptions(log);
             return;
         case "validate":
             log("Usage:");
-            log("  mdkg spec validate [<id-or-qid-or-alias>] [--json]");
+            log(`  mdkg ${command} validate [<id-or-qid-or-alias>] [--json]`);
             log("\nNotes:");
-            log("  With no reference, validates the graph and all optional SPEC.md capability records.");
-            log("  With a reference, also ensures that specific SPEC.md capability exists.");
+            log("  With no reference, validates the graph and all MANIFEST.md/SPEC.md capability records.");
+            log("  With a reference, also ensures that the specific manifest capability exists.");
+            if (legacyNote) {
+                log(legacyNote);
+            }
             printGlobalOptions(log);
             return;
         default:
             log("Usage:");
-            log("  mdkg spec list [--json]");
-            log("  mdkg spec show <id-or-qid-or-alias> [--json]");
-            log("  mdkg spec validate [<id-or-qid-or-alias>] [--json]");
+            log(`  mdkg ${command} list [--json]`);
+            log(`  mdkg ${command} show <id-or-qid-or-alias> [--json]`);
+            log(`  mdkg ${command} validate [<id-or-qid-or-alias>] [--json]`);
             log("\nNotes:");
-            log("  SPEC.md is optional and reusable-capability oriented.");
-            log("  Use `mdkg capability ...` for broader skill, SPEC.md, WORK.md, core-doc, and design-doc discovery.");
+            log("  MANIFEST.md is canonical and reusable-capability oriented; SPEC.md remains a legacy alias.");
+            if (legacyNote) {
+                log(legacyNote);
+            }
+            log("  Use `mdkg capability ...` for broader skill, MANIFEST.md/SPEC.md, WORK.md, core-doc, and design-doc discovery.");
             printGlobalOptions(log);
     }
 }
@@ -586,14 +625,24 @@ function printGraphHelp(log, subcommand) {
             log("  - rewrites canonical numeric IDs and structured graph links deterministically");
             log("  - --select-goal requires --start-goal; on apply it activates the imported start goal, pauses competing active root goals, validates, then writes selected-goal state");
             break;
+        case "refs":
+            log("Usage:");
+            log("  mdkg graph refs <id-or-qid> [--ws <alias>] [--json]");
+            log("\nNotes:");
+            log("  - read-only summary of inbound and outbound graph references");
+            log("  - reports scope_refs, context_refs, evidence_refs, blockers, related refs, and structural links");
+            log("  - subgraph qids are inspectable but remain read-only");
+            break;
         default:
             log("Usage:");
             log("  mdkg graph clone <source-bundle-or-mdkg-dir> --target <path> [--json]");
             log("  mdkg graph fork <source-bundle-or-mdkg-dir> --target <path> [--start-goal <goal-id>] [--json]");
             log("  mdkg graph import-template <source-bundle-or-mdkg-dir> [--start-goal <goal-id>] [--select-goal] [--id-prefix <prefix>] [--dry-run] [--apply] [--json]");
+            log("  mdkg graph refs <id-or-qid> [--ws <alias>] [--json]");
             log("\nNotes:");
             log("  - graph clone/fork create authored graph state in separate target directories and preserve IDs");
             log("  - graph import-template imports template work nodes into the current graph with rewritten IDs");
+            log("  - graph refs is read-only and explains local plus subgraph graph relationships");
             log("  - subgraphs remain read-only bundle projections for orchestration context");
     }
     printGlobalOptions(log);
@@ -691,7 +740,7 @@ function printWorkHelp(log, subcommand) {
             log("\nExample:");
             log("  mdkg work trigger work.example --id order.example-1 --requester user://example --json");
             log("\nNotes:");
-            log("  Accepted targets: direct WORK.md ref, or SPEC.md ref with exactly one resolvable work contract.");
+            log("  Accepted targets: direct WORK.md ref, or MANIFEST.md/SPEC.md ref with exactly one resolvable work contract.");
             log("  Creates a deterministic WORK_ORDER.md semantic mirror and does not execute work.");
             log("  Queue enqueue requires a valid project DB plus an explicitly created active queue and never executes work.");
             break;
@@ -715,6 +764,14 @@ function printWorkHelp(log, subcommand) {
             log("Usage:");
             log("  mdkg work artifact add <order-or-receipt-id-or-qid> <file> [--id <archive.id>] [--kind source|artifact] [--json]");
             break;
+        case "validate":
+            log("Usage:");
+            log("  mdkg work validate [<id-or-qid>] [--type manifest|spec|work|work_order|receipt|feedback|dispute|proposal] [--json]");
+            log("\nNotes:");
+            log("  Read-only focused validation for agent workflow mirrors.");
+            log("  Reports typed diagnostics for MANIFEST.md, legacy SPEC.md, WORK.md, WORK_ORDER.md, RECEIPT.md, FEEDBACK.md, DISPUTE.md, and PROPOSAL.md files.");
+            log("  Obvious raw secret, prompt, token, or payload markers are warnings so humans and agents can review boundaries.");
+            break;
         default:
             log("Usage:");
             log("  mdkg work contract new ...");
@@ -722,8 +779,10 @@ function printWorkHelp(log, subcommand) {
             log("  mdkg work order new|status|update ...");
             log("  mdkg work receipt new|verify|update ...");
             log("  mdkg work artifact add ...");
+            log("  mdkg work validate [<id-or-qid>] [--type <workflow-type>] [--json]");
             log("\nNotes:");
             log("  - work commands mutate semantic mirror files only");
+            log("  - work validate is read-only and reports typed workflow diagnostics");
             log("  - production order, receipt, feedback, dispute, payment, ledger, marketplace inventory, fulfillment, and execution state remains canonical outside mdkg");
             log("  - do not store raw secrets, credentials, live payment state, ledger mutations, or canonical marketplace state in work mirrors");
             log("  - artifact:// refs identify external/runtime-managed artifacts; archive:// refs identify committed mdkg archive sidecars");
@@ -754,7 +813,7 @@ function printTaskHelp(log, subcommand) {
         case "done":
             log("Usage:");
             log('  mdkg task done <id-or-qid> [--ws <alias>] [--add-artifacts <a,...>] [--add-links <l,...>]');
-            log('                 [--add-refs <id,...>] [--checkpoint "<title>"] [--run-id <id>] [--note "<text>"] [--json]');
+            log('                 [--add-refs <id,...>] [--checkpoint "<title>"] [--checkpoint-kind implementation|test-proof|goal-closeout|audit|handoff] [--run-id <id>] [--note "<text>"] [--json]');
             log("\nWhen to use:");
             log("  Mark a task-like node done, optionally create a checkpoint, and emit a completion event when enabled.");
             log("  Use `--checkpoint` for milestone compression, not every routine task completion.");
@@ -764,7 +823,7 @@ function printTaskHelp(log, subcommand) {
             log("Usage:");
             log('  mdkg task start <id-or-qid> [--ws <alias>] [--run-id <id>] [--note "<text>"] [--json]');
             log("  mdkg task update <id-or-qid> [options] [--json]");
-            log('  mdkg task done <id-or-qid> [--checkpoint "<title>"] [options] [--json]');
+            log('  mdkg task done <id-or-qid> [--checkpoint "<title>"] [--checkpoint-kind implementation|test-proof|goal-closeout|audit|handoff] [options] [--json]');
             log("\nNotes:");
             log("  `mdkg task ...` only supports feat, task, bug, test, and spike nodes.");
             log("  Spikes use this lifecycle; there is no separate `mdkg spike ...` command family.");
@@ -778,7 +837,7 @@ function printGoalHelp(log, subcommand) {
             log("Usage:");
             log("  mdkg goal show <goal-id-or-qid> [--ws <alias>] [--json]");
             log("\nWhen to use:");
-            log("  Inspect a goal condition, current goal state, active node, required skills, and required checks.");
+            log("  Inspect a goal condition, current goal state, active node, last active node, required skills, and required checks.");
             printGlobalOptions(log);
             return;
         case "next":
@@ -847,6 +906,9 @@ function printGoalHelp(log, subcommand) {
             log(`  mdkg goal ${subcommand} <goal-id-or-qid> [--ws <alias>] [--json]`);
             log("\nWhen to use:");
             log("  Update durable goal state after agent or human review.");
+            if (subcommand === "done") {
+                log("  Done goals preserve the final active_node as last_active_node and stop routing actionable work.");
+            }
             printGlobalOptions(log);
             return;
         default:
@@ -863,6 +925,7 @@ function printGoalHelp(log, subcommand) {
             log("\nNotes:");
             log("  - goals orchestrate recursive progress; features, tasks, bugs, tests, and spikes are iterable work units");
             log("  - `mdkg goal next` is read-only; use `mdkg goal claim` to update active_node");
+            log("  - `mdkg goal done` moves active_node to last_active_node so completed goals keep history without staying actionable");
             log("  - `mdkg goal activate` enforces one active local root goal and pauses competing active goals");
             log("  - goal evaluation is report-only and never executes required_checks");
             log("  - subgraph goal qids are read-only; update the source workspace instead");
@@ -901,13 +964,20 @@ function printNextHelp(log) {
 }
 function printCheckpointHelp(log) {
     log("Usage:");
-    log("  mdkg checkpoint new <title> [--ws <alias>] [--json]");
+    log("  mdkg checkpoint new <title> [--kind implementation|test-proof|goal-closeout|audit|handoff] [--ws <alias>] [--json]");
+    log("  Checkpoint bodies include command evidence, pass/fail status, warnings, changed surfaces, boundaries, and follow-up refs.");
     log('        [--relates <id,id,...>] [--scope <id,id,...>] [--run-id <id>] [--note "<text>"]');
     printGlobalOptions(log);
 }
 function printValidateHelp(log) {
     log("Usage:");
-    log("  mdkg validate [--out <path>] [--quiet] [--json]");
+    log("  mdkg validate [--out <path>] [--json-out <path>] [--quiet] [--changed-only] [--summary] [--limit <n>] [--json]");
+    log("\nNotes:");
+    log("  Validates frontmatter schemas, graph references, visibility, skills, and events.");
+    log("  --changed-only filters warning presentation to changed .mdkg files while full graph errors still run.");
+    log("  JSON output includes warning_summary plus warning_diagnostics with warning ids, categories, severity, paths, refs, and remediation text.");
+    log("  --summary emits bounded warning samples for agent/CI logs; --limit controls the sample size.");
+    log("  --out writes the compatibility text report; --json-out writes a clean full JSON receipt.");
     printGlobalOptions(log);
 }
 function printStatusHelp(log) {
@@ -1011,6 +1081,11 @@ function printFixHelp(log, subcommand) {
 function printFormatHelp(log) {
     log("Usage:");
     log("  mdkg format");
+    log("  mdkg format --headings [--dry-run|--apply] [--summary] [--limit <n>] [--json]");
+    log("\nNotes:");
+    log("  Default format normalizes frontmatter in place.");
+    log("  --headings adds missing recommended body headings; it defaults to dry-run and requires --apply to write files.");
+    log("  --summary emits bounded heading-change samples for agent/CI logs; --limit controls the sample size.");
     printGlobalOptions(log);
 }
 function printDoctorHelp(log) {
@@ -1072,12 +1147,18 @@ function printCommandHelp(log, command, subcommand) {
         case "pack":
             printPackHelp(log);
             return;
+        case "handoff":
+            printHandoffHelp(log);
+            return;
         case "skill":
             printSkillHelp(log, subcommand);
             return;
         case "capability":
             printCapabilityHelp(log, subcommand);
             return;
+        case "manifest":
+            printSpecHelp(log, subcommand, "manifest");
+            return;
         case "spec":
             printSpecHelp(log, subcommand);
             return;
@@ -1436,6 +1517,12 @@ function runDbSubcommand(parsed, root) {
                     }
                     (0, db_1.runDbQueueCreateCommand)(common);
                     return 0;
+                case "contract":
+                    if (parsed.positionals.length > 3) {
+                        throw new errors_1.UsageError("mdkg db queue contract accepts no positional arguments");
+                    }
+                    (0, db_1.runDbQueueContractCommand)(common);
+                    return 0;
                 case "pause":
                     if (!queueName || parsed.positionals.length > 4) {
                         throw new errors_1.UsageError("mdkg db queue pause requires <queue>");
@@ -1503,7 +1590,7 @@ function runDbSubcommand(parsed, root) {
                     (0, db_1.runDbQueueShowCommand)(common);
                     return 0;
                 default:
-                    throw new errors_1.UsageError("mdkg db queue requires create/pause/resume/enqueue/claim/ack/fail/dead-letter/release-expired/stats/list/show");
+                    throw new errors_1.UsageError("mdkg db queue requires create/contract/pause/resume/enqueue/claim/ack/fail/dead-letter/release-expired/stats/list/show");
             }
         }
         case "snapshot": {
@@ -1609,43 +1696,47 @@ function runCapabilitySubcommand(parsed, root) {
             throw new errors_1.UsageError("capability requires list/search/show/resolve");
     }
 }
-function runSpecSubcommand(parsed, root) {
+function runSpecSubcommand(parsed, root, surface = "spec") {
     const subcommand = (parsed.positionals[1] ?? "").toLowerCase();
+    const command = surface === "manifest" ? "manifest" : "spec";
     switch (subcommand) {
         case "list": {
             if (parsed.positionals.length > 2) {
-                throw new errors_1.UsageError("spec list does not accept positional arguments");
+                throw new errors_1.UsageError(`${command} list does not accept positional arguments`);
             }
             const json = parseBooleanFlag("--json", parsed.flags["--json"]);
             const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
             const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
-            (0, spec_1.runSpecListCommand)({ root, json, noCache, noReindex });
+            const runList = surface === "manifest" ? spec_1.runManifestListCommand : spec_1.runSpecListCommand;
+            runList({ root, json, noCache, noReindex });
             return 0;
         }
         case "show": {
             const id = parsed.positionals[2];
             if (!id || parsed.positionals.length > 3) {
-                throw new errors_1.UsageError("spec show requires <id-or-qid-or-alias>");
+                throw new errors_1.UsageError(`${command} show requires <id-or-qid-or-alias>`);
             }
             const json = parseBooleanFlag("--json", parsed.flags["--json"]);
             const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
             const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
-            (0, spec_1.runSpecShowCommand)({ root, id, json, noCache, noReindex });
+            const runShow = surface === "manifest" ? spec_1.runManifestShowCommand : spec_1.runSpecShowCommand;
+            runShow({ root, id, json, noCache, noReindex });
             return 0;
         }
         case "validate": {
             const id = parsed.positionals[2];
             if (parsed.positionals.length > 3) {
-                throw new errors_1.UsageError("spec validate accepts at most one SPEC reference");
+                throw new errors_1.UsageError(`${command} validate accepts at most one manifest reference`);
             }
             const json = parseBooleanFlag("--json", parsed.flags["--json"]);
             const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
             const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
-            (0, spec_1.runSpecValidateCommand)({ root, id, json, noCache, noReindex });
+            const runValidate = surface === "manifest" ? spec_1.runManifestValidateCommand : spec_1.runSpecValidateCommand;
+            runValidate({ root, id, json, noCache, noReindex });
             return 0;
         }
         default:
-            throw new errors_1.UsageError("spec requires list/show/validate");
+            throw new errors_1.UsageError(`${command} requires list/show/validate`);
     }
 }
 function runArchiveSubcommand(parsed, root) {
@@ -1799,8 +1890,17 @@ function runGraphSubcommand(parsed, root) {
             (0, graph_1.runGraphImportTemplateCommand)({ root, source, startGoal, idPrefix, dryRun, apply, selectGoal, json });
             return 0;
         }
+        case "refs": {
+            const id = parsed.positionals[2];
+            if (!id || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("graph refs requires <id-or-qid>");
+            }
+            const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
+            (0, graph_1.runGraphRefsCommand)({ root, id, ws, json });
+            return 0;
+        }
         default:
-            throw new errors_1.UsageError("graph requires clone/fork/import-template");
+            throw new errors_1.UsageError("graph requires clone/fork/import-template/refs");
     }
 }
 function runSubgraphSubcommand(parsed, root) {
@@ -1956,6 +2056,15 @@ function runWorkSubcommand(parsed, root) {
         (0, work_1.runWorkTriggerCommand)({ root, ws, targetRef, id, title, requester, enqueue, json });
         return 0;
     }
+    if (domain === "validate") {
+        const id = parsed.positionals[2];
+        if (parsed.positionals.length > 3) {
+            throw new errors_1.UsageError("work validate accepts at most one workflow reference");
+        }
+        const type = requireFlagValue("--type", parsed.flags["--type"]);
+        (0, work_1.runWorkValidateCommand)({ root, ws, id, type, json });
+        return 0;
+    }
     if (domain === "contract" && action === "new") {
         const title = parsed.positionals.slice(3).join(" ");
         const id = requireFlagValue("--id", parsed.flags["--id"]);
@@ -2115,7 +2224,7 @@ function runWorkSubcommand(parsed, root) {
         (0, work_1.runWorkArtifactAddCommand)({ root, ws, targetId, file, id, kind, json });
         return 0;
     }
-    throw new errors_1.UsageError("work requires contract new, order new/update, receipt new/update, or artifact add");
+    throw new errors_1.UsageError("work requires contract new, trigger, order new/update/status, receipt new/update/verify, artifact add, or validate");
 }
 function runSkillSubcommand(parsed, root) {
     const subcommand = (parsed.positionals[1] ?? "").toLowerCase();
@@ -2400,6 +2509,7 @@ function runTaskSubcommand(parsed, root) {
             const addLinks = requireFlagValue("--add-links", parsed.flags["--add-links"]);
             const addRefs = requireFlagValue("--add-refs", parsed.flags["--add-refs"]);
             const checkpoint = requireFlagValue("--checkpoint", parsed.flags["--checkpoint"]);
+            const checkpointKind = requireFlagValue("--checkpoint-kind", parsed.flags["--checkpoint-kind"]);
             const runId = requireFlagValue("--run-id", parsed.flags["--run-id"]);
             const note = requireFlagValue("--note", parsed.flags["--note"]);
             const json = parseBooleanFlag("--json", parsed.flags["--json"]);
@@ -2411,6 +2521,7 @@ function runTaskSubcommand(parsed, root) {
                 addLinks,
                 addRefs,
                 checkpoint,
+                checkpointKind,
                 runId,
                 note,
                 json,
@@ -2589,6 +2700,8 @@ function runCommand(parsed, root, runtime) {
             return runSkillSubcommand(parsed, root);
         case "capability":
             return runCapabilitySubcommand(parsed, root);
+        case "manifest":
+            return runSpecSubcommand(parsed, root, "manifest");
         case "spec":
             return runSpecSubcommand(parsed, root);
         case "archive":
@@ -2749,6 +2862,32 @@ function runCommand(parsed, root, runtime) {
             });
             return 0;
         }
+        case "handoff": {
+            const sub = (parsed.positionals[1] ?? "").toLowerCase();
+            if (!sub) {
+                throw new errors_1.UsageError("handoff requires a subcommand");
+            }
+            if (sub !== "create") {
+                throw new errors_1.UsageError(`unknown handoff subcommand: ${sub}`);
+            }
+            const id = parsed.positionals[2];
+            if (!id || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("mdkg handoff create requires <id-or-qid>");
+            }
+            const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
+            const out = requireFlagValue("--out", parsed.flags["--out"]);
+            const depth = parseNumberFlag("--depth", parsed.flags["--depth"]);
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            (0, handoff_1.runHandoffCreateCommand)({
+                root,
+                id,
+                ws,
+                out,
+                depth,
+                json,
+            });
+            return 0;
+        }
         case "next": {
             if (parsed.positionals.length > 2) {
                 throw new errors_1.UsageError("next accepts at most one id");
@@ -2778,6 +2917,7 @@ function runCommand(parsed, root, runtime) {
             const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
             const relates = requireFlagValue("--relates", parsed.flags["--relates"]);
             const scope = requireFlagValue("--scope", parsed.flags["--scope"]);
+            const kind = requireFlagValue("--kind", parsed.flags["--kind"]);
             const status = requireFlagValue("--status", parsed.flags["--status"]);
             const priority = parseNumberFlag("--priority", parsed.flags["--priority"]);
             const template = requireFlagValue("--template", parsed.flags["--template"]);
@@ -2790,6 +2930,7 @@ function runCommand(parsed, root, runtime) {
                 ws,
                 relates,
                 scope,
+                kind,
                 status,
                 priority,
                 template,
@@ -2804,9 +2945,13 @@ function runCommand(parsed, root, runtime) {
                 throw new errors_1.UsageError("validate does not accept positional arguments");
             }
             const out = requireFlagValue("--out", parsed.flags["--out"]);
+            const jsonOut = requireFlagValue("--json-out", parsed.flags["--json-out"]);
             const quiet = parseBooleanFlag("--quiet", parsed.flags["--quiet"]);
+            const changedOnly = parseBooleanFlag("--changed-only", parsed.flags["--changed-only"]);
+            const summary = parseBooleanFlag("--summary", parsed.flags["--summary"]);
+            const limit = parseNumberFlag("--limit", parsed.flags["--limit"]);
             const json = parseBooleanFlag("--json", parsed.flags["--json"]);
-            (0, validate_1.runValidateCommand)({ root, out, quiet, json });
+            (0, validate_1.runValidateCommand)({ root, out, jsonOut, quiet, json, changedOnly, summary, limit });
             return 0;
         }
         case "status": {
@@ -2850,7 +2995,19 @@ function runCommand(parsed, root, runtime) {
             if (parsed.positionals.length > 1) {
                 throw new errors_1.UsageError("format does not accept positional arguments");
             }
-            (0, format_1.runFormatCommand)({ root });
+            const headings = parseBooleanFlag("--headings", parsed.flags["--headings"]);
+            const dryRun = parseBooleanFlag("--dry-run", parsed.flags["--dry-run"]);
+            const apply = parseBooleanFlag("--apply", parsed.flags["--apply"]);
+            const summary = parseBooleanFlag("--summary", parsed.flags["--summary"]);
+            const limit = parseNumberFlag("--limit", parsed.flags["--limit"]);
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            if (!headings && (dryRun || apply || json || summary || limit !== undefined)) {
+                throw new errors_1.UsageError("format --dry-run, --apply, --summary, --limit, and --json require --headings");
+            }
+            if (dryRun && apply) {
+                throw new errors_1.UsageError("format --headings cannot use --dry-run and --apply together");
+            }
+            (0, format_1.runFormatCommand)({ root, headings, dryRun, apply, json, summary, limit });
             return 0;
         case "doctor": {
             if (parsed.positionals.length > 1) {