mdkg 0.3.6 → 0.3.7

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,13 @@ 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("  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");
@@ -236,8 +238,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 +262,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 +331,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 +354,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":
@@ -586,14 +606,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);
@@ -715,6 +745,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 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 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 +760,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 +794,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 +804,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 +818,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 +887,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 +906,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 +945,18 @@ 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>] [--quiet] [--changed-only] [--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_diagnostics with warning ids, categories, severity, paths, refs, and remediation text.");
     printGlobalOptions(log);
 }
 function printStatusHelp(log) {
@@ -1011,6 +1060,10 @@ function printFixHelp(log, subcommand) {
 function printFormatHelp(log) {
     log("Usage:");
     log("  mdkg format");
+    log("  mdkg format --headings [--dry-run|--apply] [--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.");
     printGlobalOptions(log);
 }
 function printDoctorHelp(log) {
@@ -1072,6 +1125,9 @@ function printCommandHelp(log, command, subcommand) {
         case "pack":
             printPackHelp(log);
             return;
+        case "handoff":
+            printHandoffHelp(log);
+            return;
         case "skill":
             printSkillHelp(log, subcommand);
             return;
@@ -1436,6 +1492,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 +1565,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": {
@@ -1799,8 +1861,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 +2027,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 +2195,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 +2480,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 +2492,7 @@ function runTaskSubcommand(parsed, root) {
                 addLinks,
                 addRefs,
                 checkpoint,
+                checkpointKind,
                 runId,
                 note,
                 json,
@@ -2749,6 +2831,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 +2886,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 +2899,7 @@ function runCommand(parsed, root, runtime) {
                 ws,
                 relates,
                 scope,
+                kind,
                 status,
                 priority,
                 template,
@@ -2805,8 +2915,9 @@ function runCommand(parsed, root, runtime) {
             }
             const out = requireFlagValue("--out", parsed.flags["--out"]);
             const quiet = parseBooleanFlag("--quiet", parsed.flags["--quiet"]);
+            const changedOnly = parseBooleanFlag("--changed-only", parsed.flags["--changed-only"]);
             const json = parseBooleanFlag("--json", parsed.flags["--json"]);
-            (0, validate_1.runValidateCommand)({ root, out, quiet, json });
+            (0, validate_1.runValidateCommand)({ root, out, quiet, json, changedOnly });
             return 0;
         }
         case "status": {
@@ -2850,7 +2961,17 @@ 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 json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            if (!headings && (dryRun || apply || json)) {
+                throw new errors_1.UsageError("format --dry-run, --apply, 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 });
             return 0;
         case "doctor": {
             if (parsed.positionals.length > 1) {