mdkg 0.3.7 → 0.3.9

package/dist/cli.js

@@ -71,7 +71,8 @@ function printUsage(log) {
     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, fork, import, and inspect mdkg graph references");
@@ -145,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:");
@@ -163,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 ...`.");
@@ -411,7 +414,8 @@ function printSkillHelp(log, subcommand) {
             log("Usage:");
             log("  mdkg skill sync [--force] [--json]");
             log("\nWhen to use:");
-            log("  Rebuild .agents/skills and .claude/skills from canonical .mdkg/skills.");
+            log("  Rebuild configured skill mirror targets from canonical .mdkg/skills.");
+            log("  Defaults are .agents/skills and .claude/skills; add custom targets in .mdkg/config.json.");
             printGlobalOptions(log);
             return;
         default:
@@ -469,38 +473,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);
     }
 }
@@ -721,7 +741,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;
@@ -747,10 +767,10 @@ function printWorkHelp(log, subcommand) {
             break;
         case "validate":
             log("Usage:");
-            log("  mdkg work validate [<id-or-qid>] [--type spec|work|work_order|receipt|feedback|dispute|proposal] [--json]");
+            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 SPEC.md, WORK.md, WORK_ORDER.md, RECEIPT.md, FEEDBACK.md, DISPUTE.md, and PROPOSAL.md files.");
+            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:
@@ -952,11 +972,13 @@ function printCheckpointHelp(log) {
 }
 function printValidateHelp(log) {
     log("Usage:");
-    log("  mdkg validate [--out <path>] [--quiet] [--changed-only] [--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_diagnostics with warning ids, categories, severity, paths, refs, and remediation text.");
+    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) {
@@ -1060,10 +1082,11 @@ function printFixHelp(log, subcommand) {
 function printFormatHelp(log) {
     log("Usage:");
     log("  mdkg format");
-    log("  mdkg format --headings [--dry-run|--apply] [--json]");
+    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) {
@@ -1134,6 +1157,9 @@ function printCommandHelp(log, command, subcommand) {
         case "capability":
             printCapabilityHelp(log, subcommand);
             return;
+        case "manifest":
+            printSpecHelp(log, subcommand, "manifest");
+            return;
         case "spec":
             printSpecHelp(log, subcommand);
             return;
@@ -1671,43 +1697,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) {
@@ -2671,6 +2701,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":
@@ -2914,10 +2946,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, changedOnly });
+            (0, validate_1.runValidateCommand)({ root, out, jsonOut, quiet, json, changedOnly, summary, limit });
             return 0;
         }
         case "status": {
@@ -2964,14 +2999,16 @@ function runCommand(parsed, root, runtime) {
             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)) {
-                throw new errors_1.UsageError("format --dry-run, --apply, and --json require --headings");
+            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 });
+            (0, format_1.runFormatCommand)({ root, headings, dryRun, apply, json, summary, limit });
             return 0;
         case "doctor": {
             if (parsed.positionals.length > 1) {