mdkg 0.3.7 → 0.3.8

package/dist/command-contract.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "tool": "mdkg",
-  "package_version": "0.3.7",
+  "package_version": "0.3.8",
   "source": {
     "help_targets": "scripts/cli_help_targets.js",
     "command_matrix": "CLI_COMMAND_MATRIX.md"
@@ -2572,7 +2572,7 @@
       "summary": "mdkg format command",
       "usage": [
         "  mdkg format",
-        "  mdkg format --headings [--dry-run|--apply] [--json]"
+        "  mdkg format --headings [--dry-run|--apply] [--summary] [--limit <n>] [--json]"
       ],
       "args": [],
       "flags": [
@@ -2586,7 +2586,7 @@
           "name": "--headings",
           "value": "[--dry-run|--apply]",
           "required": false,
-          "description": "mdkg format --headings [--dry-run|--apply] [--json]"
+          "description": "mdkg format --headings [--dry-run|--apply] [--summary] [--limit <n>] [--json]"
         },
         {
           "name": "--help",
@@ -2594,12 +2594,24 @@
           "required": false,
           "description": "--help, -h          Show help"
         },
+        {
+          "name": "--limit",
+          "value": "controls",
+          "required": false,
+          "description": "--summary emits bounded heading-change samples for agent/CI logs; --limit controls the sample size."
+        },
         {
           "name": "--root",
           "value": null,
           "required": false,
           "description": "--root, -r <path>   Run against a specific repo root"
         },
+        {
+          "name": "--summary",
+          "value": "emits",
+          "required": false,
+          "description": "--summary emits bounded heading-change samples for agent/CI logs; --limit controls the sample size."
+        },
         {
           "name": "--version",
           "value": null,
@@ -2646,7 +2658,7 @@
       ],
       "examples": [
         "  mdkg format",
-        "  mdkg format --headings [--dry-run|--apply] [--json]"
+        "  mdkg format --headings [--dry-run|--apply] [--summary] [--limit <n>] [--json]"
       ],
       "docs": {
         "help_target": "mdkg help format",
@@ -4720,6 +4732,315 @@
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
+    {
+      "key": "manifest",
+      "path": [
+        "manifest"
+      ],
+      "category": "manifest",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg manifest command",
+      "usage": [
+        "  mdkg manifest list [--json]",
+        "  mdkg manifest show <id-or-qid-or-alias> [--json]",
+        "  mdkg manifest validate [<id-or-qid-or-alias>] [--json]"
+      ],
+      "args": [
+        {
+          "name": "id-or-qid-or-alias",
+          "required": true,
+          "source": "<id-or-qid-or-alias>"
+        }
+      ],
+      "flags": [
+        {
+          "name": "--help",
+          "value": null,
+          "required": false,
+          "description": "--help, -h          Show help"
+        },
+        {
+          "name": "--root",
+          "value": null,
+          "required": false,
+          "description": "--root, -r <path>   Run against a specific repo root"
+        },
+        {
+          "name": "--version",
+          "value": null,
+          "required": false,
+          "description": "--version, -V       Show version"
+        }
+      ],
+      "output_formats": [
+        "text",
+        "json"
+      ],
+      "json_schema_ref": "mdkg.command_output.v1",
+      "side_effects": [
+        "none"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [],
+      "dry_run": {
+        "supported": false
+      },
+      "lock_policy": "none-read-only",
+      "atomic_write_policy": "none-read-only",
+      "receipts": [],
+      "danger_level": "read-only",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "  mdkg manifest list [--json]",
+        "  mdkg manifest show <id-or-qid-or-alias> [--json]",
+        "  mdkg manifest validate [<id-or-qid-or-alias>] [--json]"
+      ],
+      "docs": {
+        "help_target": "mdkg help manifest",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      }
+    },
+    {
+      "key": "manifest list",
+      "path": [
+        "manifest",
+        "list"
+      ],
+      "category": "manifest",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg manifest list command",
+      "usage": [
+        "  mdkg manifest list [--json]"
+      ],
+      "args": [],
+      "flags": [
+        {
+          "name": "--help",
+          "value": null,
+          "required": false,
+          "description": "--help, -h          Show help"
+        },
+        {
+          "name": "--root",
+          "value": null,
+          "required": false,
+          "description": "--root, -r <path>   Run against a specific repo root"
+        },
+        {
+          "name": "--version",
+          "value": null,
+          "required": false,
+          "description": "--version, -V       Show version"
+        }
+      ],
+      "output_formats": [
+        "text",
+        "json"
+      ],
+      "json_schema_ref": "mdkg.command_output.v1",
+      "side_effects": [
+        "none"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [],
+      "dry_run": {
+        "supported": false
+      },
+      "lock_policy": "none-read-only",
+      "atomic_write_policy": "none-read-only",
+      "receipts": [],
+      "danger_level": "read-only",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "  mdkg manifest list [--json]"
+      ],
+      "docs": {
+        "help_target": "mdkg help manifest list",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      }
+    },
+    {
+      "key": "manifest show",
+      "path": [
+        "manifest",
+        "show"
+      ],
+      "category": "manifest",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg manifest show command",
+      "usage": [
+        "  mdkg manifest show <id-or-qid-or-alias> [--json]"
+      ],
+      "args": [
+        {
+          "name": "id-or-qid-or-alias",
+          "required": true,
+          "source": "<id-or-qid-or-alias>"
+        }
+      ],
+      "flags": [
+        {
+          "name": "--help",
+          "value": null,
+          "required": false,
+          "description": "--help, -h          Show help"
+        },
+        {
+          "name": "--root",
+          "value": null,
+          "required": false,
+          "description": "--root, -r <path>   Run against a specific repo root"
+        },
+        {
+          "name": "--version",
+          "value": null,
+          "required": false,
+          "description": "--version, -V       Show version"
+        }
+      ],
+      "output_formats": [
+        "text",
+        "json"
+      ],
+      "json_schema_ref": "mdkg.command_output.v1",
+      "side_effects": [
+        "none"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [],
+      "dry_run": {
+        "supported": false
+      },
+      "lock_policy": "none-read-only",
+      "atomic_write_policy": "none-read-only",
+      "receipts": [],
+      "danger_level": "read-only",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "  mdkg manifest show <id-or-qid-or-alias> [--json]"
+      ],
+      "docs": {
+        "help_target": "mdkg help manifest show",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      }
+    },
+    {
+      "key": "manifest validate",
+      "path": [
+        "manifest",
+        "validate"
+      ],
+      "category": "manifest",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg manifest validate command",
+      "usage": [
+        "  mdkg manifest validate [<id-or-qid-or-alias>] [--json]"
+      ],
+      "args": [
+        {
+          "name": "id-or-qid-or-alias",
+          "required": true,
+          "source": "<id-or-qid-or-alias>"
+        }
+      ],
+      "flags": [
+        {
+          "name": "--help",
+          "value": null,
+          "required": false,
+          "description": "--help, -h          Show help"
+        },
+        {
+          "name": "--root",
+          "value": null,
+          "required": false,
+          "description": "--root, -r <path>   Run against a specific repo root"
+        },
+        {
+          "name": "--version",
+          "value": null,
+          "required": false,
+          "description": "--version, -V       Show version"
+        }
+      ],
+      "output_formats": [
+        "text",
+        "json"
+      ],
+      "json_schema_ref": "mdkg.command_output.v1",
+      "side_effects": [
+        "none"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [],
+      "dry_run": {
+        "supported": false
+      },
+      "lock_policy": "none-read-only",
+      "atomic_write_policy": "none-read-only",
+      "receipts": [],
+      "danger_level": "read-only",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "  mdkg manifest validate [<id-or-qid-or-alias>] [--json]"
+      ],
+      "docs": {
+        "help_target": "mdkg help manifest validate",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      }
+    },
     {
       "key": "mcp",
       "path": [
@@ -7921,7 +8242,7 @@
       "visibility": "public",
       "summary": "mdkg validate command",
       "usage": [
-        "  mdkg validate [--out <path>] [--quiet] [--changed-only] [--json]"
+        "  mdkg validate [--out <path>] [--json-out <path>] [--quiet] [--changed-only] [--summary] [--limit <n>] [--json]"
       ],
       "args": [],
       "flags": [
@@ -7937,12 +8258,36 @@
           "required": false,
           "description": "--help, -h          Show help"
         },
+        {
+          "name": "--json-out",
+          "value": "writes",
+          "required": false,
+          "description": "--out writes the compatibility text report; --json-out writes a clean full JSON receipt."
+        },
+        {
+          "name": "--limit",
+          "value": "controls",
+          "required": false,
+          "description": "--summary emits bounded warning samples for agent/CI logs; --limit controls the sample size."
+        },
+        {
+          "name": "--out",
+          "value": "writes",
+          "required": false,
+          "description": "--out writes the compatibility text report; --json-out writes a clean full JSON receipt."
+        },
         {
           "name": "--root",
           "value": null,
           "required": false,
           "description": "--root, -r <path>   Run against a specific repo root"
         },
+        {
+          "name": "--summary",
+          "value": "emits",
+          "required": false,
+          "description": "--summary emits bounded warning samples for agent/CI logs; --limit controls the sample size."
+        },
         {
           "name": "--version",
           "value": null,
@@ -7981,7 +8326,7 @@
         }
       ],
       "examples": [
-        "  mdkg validate [--out <path>] [--quiet] [--changed-only] [--json]"
+        "  mdkg validate [--out <path>] [--json-out <path>] [--quiet] [--changed-only] [--summary] [--limit <n>] [--json]"
       ],
       "docs": {
         "help_target": "mdkg help validate",
@@ -8619,7 +8964,7 @@
       "visibility": "public",
       "summary": "mdkg work validate command",
       "usage": [
-        "  mdkg work validate [<id-or-qid>] [--type spec|work|work_order|receipt|feedback|dispute|proposal] [--json]"
+        "  mdkg work validate [<id-or-qid>] [--type manifest|spec|work|work_order|receipt|feedback|dispute|proposal] [--json]"
       ],
       "args": [
         {
@@ -8681,7 +9026,7 @@
         }
       ],
       "examples": [
-        "  mdkg work validate [<id-or-qid>] [--type spec|work|work_order|receipt|feedback|dispute|proposal] [--json]"
+        "  mdkg work validate [<id-or-qid>] [--type manifest|spec|work|work_order|receipt|feedback|dispute|proposal] [--json]"
       ],
       "docs": {
         "help_target": "mdkg help work validate",
@@ -8783,5 +9128,5 @@
       }
     }
   ],
-  "contract_hash": "e6b42d5850cb4e76b9cb29a21bb643b50c042667bb09c598ec3c7dd87f7cccdd"
+  "contract_hash": "145781176fcd00d6b7c7edd8e013e902acea2ace8764dbf0bb063a8d3913a3e1"
 }

package/dist/commands/capability.js

@@ -79,6 +79,7 @@ function capabilitySearchText(record) {
         ...record.aliases,
         ...record.links,
         ...record.headings.map((heading) => heading.text),
+        JSON.stringify(record.manifest ?? {}),
         JSON.stringify(record.spec ?? {}),
         JSON.stringify(record.work ?? {}),
         JSON.stringify(record.linkage ?? {}),

package/dist/commands/doctor.js

@@ -164,8 +164,8 @@ function runArchiveStorageCheck(root) {
         name: "archive-storage",
         ok: true,
         level: "warn",
-        detail: `stray uncompressed archive file(s) found without managed sidecars: ${strayRaw.join(", ")}; run \`mdkg archive add <file>\` or move raw files under a managed archive source directory`,
-        remediation: "Run `mdkg archive add <file>` or move raw files under a managed archive source directory.",
+        detail: `stray uncompressed archive file(s) found without managed sidecars: ${strayRaw.join(", ")}; these are storage hygiene warnings, not source defects`,
+        remediation: "Either run `mdkg archive add <file>` to create a managed sidecar, move raw files under an existing managed archive source directory, or remove unintended local files before committing.",
         refs: strayRaw,
     });
 }
@@ -255,8 +255,8 @@ function runProjectDbRuntimePolicyCheck(root) {
         name: "project-db-runtime",
         ok: true,
         level: "warn",
-        detail: `active project DB runtime/transient file(s) are local-only and should not be committed: ${files.join(", ")}`,
-        remediation: "Keep runtime DB and transient files ignored; commit sealed state only by explicit repo policy.",
+        detail: `active project DB runtime/transient file(s) are local-only and should not be committed: ${files.join(", ")}; this is expected local state when \`mdkg db verify\` passes`,
+        remediation: "Keep runtime DB and transient files ignored, run `mdkg db verify --json` if DB health is in question, and commit sealed state only by explicit repo policy.",
         refs: files,
     });
 }
@@ -386,7 +386,7 @@ function runSelectedGoalChecks(root, config, options) {
                 ok: true,
                 level: "warn",
                 detail: selected.warning,
-                remediation: "Run `mdkg goal select <goal-id>` or `mdkg goal clear`.",
+                remediation: "Run `mdkg goal clear --json` when no repo-local goal should be selected, or create/select a repo-local active goal only when work is continuing.",
                 strictFail: true,
             }),
         ];
@@ -418,7 +418,7 @@ function runSelectedGoalChecks(root, config, options) {
                     ok: true,
                     level: "warn",
                     detail: `selected goal ${selected.state.qid} is missing from the graph`,
-                    remediation: "Run `mdkg goal select <active-goal>` or `mdkg goal clear`.",
+                    remediation: "Run `mdkg goal clear --json` when no repo-local goal should be selected, or `mdkg goal activate <goal-id> --json` for the next active repo-local goal.",
                     refs: [selected.state.qid],
                     strictFail: true,
                 }),
@@ -433,7 +433,7 @@ function runSelectedGoalChecks(root, config, options) {
                     ok: true,
                     level: "warn",
                     detail: `selected goal ${selected.state.qid} is achieved but still current`,
-                    remediation: "Run `mdkg goal select <active-goal>` or `mdkg goal clear`.",
+                    remediation: "Run `mdkg goal clear --json` for an achieved current goal, or `mdkg goal activate <goal-id> --json` only when a new repo-local goal should become active. Root orchestrators should not mutate dirty child repos without approval.",
                     refs: [selected.state.qid],
                     strictFail: true,
                 }),

package/dist/commands/format.js

@@ -68,6 +68,41 @@ function appendMissingHeadings(body, headings) {
     const prefix = trimmed.length > 0 ? `${trimmed}\n\n` : "";
     return `${prefix}${headings.map((heading) => `# ${heading}\n`).join("\n")}`;
 }
+function countBuckets(values) {
+    const counts = new Map();
+    for (const value of values) {
+        if (!value) {
+            continue;
+        }
+        counts.set(value, (counts.get(value) ?? 0) + 1);
+    }
+    return Array.from(counts.entries())
+        .map(([key, count]) => ({ key, count }))
+        .sort((a, b) => b.count - a.count || a.key.localeCompare(b.key));
+}
+function normalizeLimit(limit) {
+    if (limit === undefined) {
+        return 50;
+    }
+    if (!Number.isInteger(limit) || limit < 0) {
+        throw new errors_1.ValidationError("--limit must be a non-negative integer");
+    }
+    return limit;
+}
+function buildHeadingsSummary(changes, limit) {
+    const effectiveLimit = limit === null || limit === undefined ? changes.length : limit;
+    const emitted = Math.min(changes.length, effectiveLimit);
+    return {
+        total: changes.length,
+        emitted,
+        truncated: emitted < changes.length,
+        omitted_count: changes.length - emitted,
+        limit: limit === undefined ? null : limit,
+        affected_file_count: new Set(changes.map((change) => change.path)).size,
+        by_node_type: countBuckets(changes.map((change) => change.type)),
+        top_paths: countBuckets(changes.map((change) => change.path)).slice(0, 25),
+    };
+}
 function normalizeScalar(value) {
     return value.trim();
 }
@@ -348,13 +383,17 @@ function runHeadingFormatCommandLocked(options) {
             (0, atomic_1.atomicWriteFile)(change.filePath, change.content);
         }
     }
+    const publicChanges = changes.map(({ filePath: _filePath, content: _content, ...change }) => change);
+    const summaryLimit = options.summary ? normalizeLimit(options.limit) : undefined;
+    const emittedChanges = options.summary ? publicChanges.slice(0, summaryLimit) : publicChanges;
     const receipt = {
         action: "format.headings",
         ok: true,
         dry_run: !apply,
         applied: apply,
         changed_count: changes.length,
-        changes: changes.map(({ filePath: _filePath, content: _content, ...change }) => change),
+        summary: buildHeadingsSummary(publicChanges, summaryLimit),
+        changes: emittedChanges,
     };
     if (options.json) {
         console.log(JSON.stringify(receipt, null, 2));

package/dist/commands/handoff.js

@@ -268,6 +268,12 @@ function runHandoffCreateCommand(options) {
         },
         output_path: outPath ? path_1.default.relative(options.root, outPath).split(path_1.default.sep).join("/") : null,
         content_sha256: contentHash,
+        warning_count: warnings.length + buildResult.warnings.length,
+        warnings: [...warnings, ...buildResult.warnings],
+        index_warning_count: warnings.length,
+        index_warnings: warnings,
+        pack_warning_count: buildResult.warnings.length,
+        pack_warnings: buildResult.warnings,
         raw_marker_warning_count: rawWarnings.length,
         raw_marker_warnings: rawWarnings,
         latest_checkpoint_qid: buildResult.pack.meta.latest_checkpoint_qid ?? null,

package/dist/commands/new.js

@@ -27,6 +27,7 @@ const DEC_STATUS = new Set(["proposed", "accepted", "rejected", "superseded"]);
 const SKILL_SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const CORE_TYPES = new Set(["rule"]);
 const DESIGN_TYPES = new Set(["prd", "edd", "dec", "prop"]);
+const LEGACY_NEW_SPEC_WARNING = "warning: mdkg new spec is legacy; use mdkg new manifest. This alias creates MANIFEST.md with type: manifest during the compatibility release.";
 function parseCsvList(raw) {
     if (!raw) {
         return [];
@@ -162,6 +163,9 @@ function fileNameForType(type, id, slug) {
     }
     return `${id}-${slug}.md`;
 }
+function canonicalCreationType(requestedType) {
+    return requestedType === "spec" ? "manifest" : requestedType;
+}
 function ensureExists(index, value, ws, label) {
     const resolved = (0, qid_1.resolveQid)(index, value, ws);
     if (resolved.status !== "ok") {
@@ -177,13 +181,15 @@ function runNewCommandLocked(options) {
     if (!title) {
         throw new errors_1.UsageError("title cannot be empty");
     }
-    const type = options.type.toLowerCase();
-    if (type === "archive") {
+    const requestedType = options.type.toLowerCase();
+    if (requestedType === "archive") {
         throw new errors_1.UsageError("use `mdkg archive add <file>` to create archive sidecars");
     }
-    if (!node_1.ALLOWED_TYPES.has(type)) {
+    if (!node_1.ALLOWED_TYPES.has(requestedType)) {
         throw new errors_1.UsageError(`type must be one of ${Array.from(node_1.ALLOWED_TYPES).join(", ")}`);
     }
+    const type = canonicalCreationType(requestedType);
+    const legacySpecAlias = requestedType === "spec";
     const config = (0, config_1.loadConfig)(options.root);
     const ws = normalizeWorkspace(options.ws);
     if (!config.workspaces[ws]) {
@@ -389,6 +395,9 @@ function runNewCommandLocked(options) {
         ...(status ? { status } : {}),
         ...(priority !== undefined ? { priority } : {}),
     };
+    if (legacySpecAlias) {
+        console.error(LEGACY_NEW_SPEC_WARNING);
+    }
     if (options.json) {
         console.log(JSON.stringify({
             action: "created",