mdkg 0.3.0 → 0.3.1

package/README.md

@@ -133,6 +133,8 @@ mdkg show child_repo:work.example
 mdkg pack child_repo:work.example --dry-run --stats
 mdkg capability resolve "child capability" --json
 mdkg subgraph verify child_repo --json
+mdkg subgraph audit child_repo --target .mdkg/subgraphs --json
+mdkg subgraph upgrade-plan child_repo --json
 ```
 
 When the child repo is available under a configured root-relative `source_path`, refresh the root-owned bundle snapshot explicitly:
@@ -142,6 +144,8 @@ mdkg subgraph sync child_repo --dry-run --json
 mdkg subgraph sync child_repo --json
 ```
 
+`audit` is read-only and reports source-path Git state, dirty tracked child files, bundle validity/freshness, root-owned bundle-path safety, optional materialized-target marker safety, and count-only capability summaries. `upgrade-plan` is also read-only, returns `apply_supported: false`, and proposes safe sync/verify/materialize next steps without writing bundles or child files.
+
 `sync` inspects the child Git repo, refuses dirty tracked changes by default, builds the configured private/public bundle into the root-owned source path, verifies it, and records `<branch>@<sha>` in `source_repo`. It never commits, pulls, pushes, checks out, resets, or mutates child mdkg Markdown. Use `--allow-dirty` only when the dirty state is intentional and must be recorded in the receipt.
 
 Generate a local read-only inspection tree when humans need to browse extracted child graph files:
@@ -277,6 +281,8 @@ These are the commands new users and agents should learn first:
 - `mdkg goal`
 - `mdkg task`
 - `mdkg validate`
+- `mdkg status`
+- `mdkg fix`
 
 Advanced / maintenance commands still exist, but they are not the first-run story:
 - `mdkg event`
@@ -284,9 +290,34 @@ Advanced / maintenance commands still exist, but they are not the first-run stor
 - `mdkg index`
 - `mdkg guide`
 - `mdkg format`
-- `mdkg doctor`
+- `mdkg doctor --strict --json`
+- `mdkg fix plan --json`
 - `mdkg workspace`
 
+## Operator health
+
+Use `mdkg status --json` for a read-only operator summary before mutating a
+repo. It reports package/release state, Git cleanliness, graph validity,
+selected-goal state, project DB verification state, and generated cache
+freshness without rebuilding indexes, running migrations, repairing files, or
+changing selected-goal state.
+
+Use `mdkg doctor --strict --json` when a CI job or agent needs actionable
+typed checks. Strict doctor keeps the existing diagnostic command read-only and
+adds stable check fields: `id`, `status`, `severity`, `message`,
+`remediation`, and optional `refs`. Strict mode fails on invalid graph state,
+stale generated graph/capability cache state, stale or achieved selected-goal
+state, and enabled project DB verification failures. Warnings such as dirty
+runtime DB files, archive size guidance, and bundle handoff guidance remain
+warnings unless their underlying check fails.
+
+Use `mdkg fix plan --json` when you want repair guidance without mutation. It
+emits a receipt-shaped plan for generated index/cache repair, missing graph
+references, and duplicate local ids. Planned changes include affected paths,
+risk, reason codes, command hints, and `apply_supported: false`. `fix apply` is
+not exposed; apply behavior is deferred until the dry-run plan contract has
+enough evidence.
+
 ## Skills
 
 mdkg supports Agent Skills as procedural memory.

package/dist/cli.js

@@ -18,6 +18,8 @@ const next_1 = require("./commands/next");
 const validate_1 = require("./commands/validate");
 const format_1 = require("./commands/format");
 const doctor_1 = require("./commands/doctor");
+const status_1 = require("./commands/status");
+const fix_1 = require("./commands/fix");
 const db_1 = require("./commands/db");
 const capability_1 = require("./commands/capability");
 const spec_1 = require("./commands/spec");
@@ -67,12 +69,14 @@ function printUsage(log) {
     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("  subgraph    Register, sync, materialize, and verify read-only child graph snapshots");
+    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");
     log("  task        Start, update, and complete task-like nodes");
     log("  next        Suggest the next work item");
     log("  validate    Validate frontmatter + graph");
+    log("  status      Show read-only operator health summary");
+    log("  fix         Plan read-only repairs with receipt-shaped JSON");
     log("\nAdvanced / maintenance commands:");
     log("  db          Project database and index-cache commands");
     log("  event       Enable or append episodic event logs");
@@ -514,7 +518,7 @@ function printBundleHelp(log, subcommand) {
     switch ((subcommand ?? "").toLowerCase()) {
         case "import":
             log("Usage:");
-            log("  mdkg subgraph add/list/show/rm/enable/disable/verify/refresh/sync/materialize ...");
+            log("  mdkg subgraph add/list/show/rm/enable/disable/verify/refresh/audit/upgrade-plan/sync/materialize ...");
             log("\n`mdkg bundle import` has been replaced by `mdkg subgraph`.");
             break;
         case "create":
@@ -582,6 +586,20 @@ function printSubgraphHelp(log, subcommand) {
             log("Usage:");
             log("  mdkg subgraph refresh [alias|--all] [--json]");
             break;
+        case "audit":
+            log("Usage:");
+            log("  mdkg subgraph audit [alias|--all] [--target <path>] [--json]");
+            log("\nNotes:");
+            log("  - read-only audit for configured bundle health, source_path Git state, root-owned bundle paths, and optional materialize target safety");
+            log("  - exits nonzero only for error-level safety failures; warning-level drift stays in the receipt");
+            break;
+        case "upgrade-plan":
+            log("Usage:");
+            log("  mdkg subgraph upgrade-plan [alias|--all] [--json]");
+            log("\nNotes:");
+            log("  - read-only downstream upgrade planning receipt; apply_supported is false");
+            log("  - plans safe sync/verify/materialize next steps without mutating child repos or root bundles");
+            break;
         case "sync":
             log("Usage:");
             log("  mdkg subgraph sync [alias|--all] [--dry-run] [--allow-dirty] [--json]");
@@ -600,12 +618,15 @@ function printSubgraphHelp(log, subcommand) {
             log("  mdkg subgraph disable <alias> [--json]");
             log("  mdkg subgraph verify [alias|--all] [--json]");
             log("  mdkg subgraph refresh [alias|--all] [--json]");
+            log("  mdkg subgraph audit [alias|--all] [--target <path>] [--json]");
+            log("  mdkg subgraph upgrade-plan [alias|--all] [--json]");
             log("  mdkg subgraph sync [alias|--all] [--dry-run] [--allow-dirty] [--json]");
             log("  mdkg subgraph materialize [alias|--all] --target <path> [--clean] [--gitignore] [--json]");
             log("\nNotes:");
             log("  - subgraphs are read-only graph views backed by explicit bundle snapshots");
             log("  - default permissions are read-only and default freshness is 3600 seconds");
             log("  - refresh reloads configured bundle sources only; it does not build child bundles");
+            log("  - audit and upgrade-plan are read-only safety receipts for downstream orchestration");
             log("  - sync builds root-owned bundles from clean configured child source_path repos");
             log("  - materialize extracts bundle contents into generated inspection trees");
     }
@@ -824,6 +845,47 @@ function printValidateHelp(log) {
     log("  mdkg validate [--out <path>] [--quiet] [--json]");
     printGlobalOptions(log);
 }
+function printStatusHelp(log) {
+    log("Usage:");
+    log("  mdkg status [--json]");
+    log("\nChecks:");
+    log("  - release/package and CHANGELOG summary");
+    log("  - git branch, dirty state, and upstream ahead/behind counts");
+    log("  - graph index load, validation errors, and generated cache freshness");
+    log("  - selected goal existence, achieved state, and active node");
+    log("  - project DB enabled/verify summary");
+    log("\nBoundaries:");
+    log("  - read-only operator summary; does not rebuild indexes or repair files");
+    log("  - use `mdkg doctor` for diagnostic detail and future strict check IDs");
+    log("\nOptions:");
+    log("  --json                Emit machine-readable JSON output");
+    printGlobalOptions(log);
+}
+function printFixHelp(log, subcommand) {
+    switch ((subcommand ?? "").toLowerCase()) {
+        case "plan":
+            log("Usage:");
+            log("  mdkg fix plan [--family index|refs|ids|all] [--target <id-or-qid>] [--json]");
+            log("\nBoundaries:");
+            log("  - read-only repair planning; writes no files and does not rebuild indexes");
+            log("  - emits a deterministic receipt-shaped JSON plan with paths, risks, and reason codes");
+            log("  - initial families are index/cache, graph refs, and duplicate ids");
+            log("  - `fix apply` is intentionally not available in this release slice");
+            log("\nOptions:");
+            log("  --family <family>     Select index, refs, ids, or all (default all)");
+            log("  --target <id-or-qid>  Optional node target for family planners");
+            log("  --json                Emit machine-readable JSON output");
+            printGlobalOptions(log);
+            return;
+        default:
+            log("Usage:");
+            log("  mdkg fix plan [--family index|refs|ids|all] [--target <id-or-qid>] [--json]");
+            log("\nNotes:");
+            log("  - fix planning is dry-run only and writes nothing");
+            log("  - apply behavior is deferred until the receipt contract is proven");
+            printGlobalOptions(log);
+    }
+}
 function printFormatHelp(log) {
     log("Usage:");
     log("  mdkg format");
@@ -831,10 +893,12 @@ function printFormatHelp(log) {
 }
 function printDoctorHelp(log) {
     log("Usage:");
-    log("  mdkg doctor [--json]");
+    log("  mdkg doctor [--strict] [--json]");
     log("\nChecks:");
     log("  - Node.js version compatibility");
     log("  - mdkg repo root + .mdkg/config.json");
+    log("  - Selected-goal stale or achieved state");
+    log("  - Project DB verification when enabled");
     log("  - Template schema availability");
     log("  - Archive sidecar storage hygiene");
     log("  - Bundle snapshot storage guidance");
@@ -843,6 +907,7 @@ function printDoctorHelp(log) {
     log("  - Capability cache load/rebuild health");
     log("  - SQLite cache health when enabled");
     log("\nOptions:");
+    log("  --strict              Fail on stale selected-goal, DB, and generated cache health issues");
     log("  --json                Emit machine-readable JSON output");
     printGlobalOptions(log);
 }
@@ -924,6 +989,12 @@ function printCommandHelp(log, command, subcommand) {
         case "validate":
             printValidateHelp(log);
             return;
+        case "status":
+            printStatusHelp(log);
+            return;
+        case "fix":
+            printFixHelp(log, subcommand);
+            return;
         case "format":
             printFormatHelp(log);
             return;
@@ -1648,6 +1719,25 @@ function runSubgraphSubcommand(parsed, root) {
             (0, subgraph_1.runSubgraphRefreshCommand)({ root, alias, all, json });
             return 0;
         }
+        case "audit": {
+            if (parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("subgraph audit accepts at most one alias");
+            }
+            const alias = parsed.positionals[2];
+            const all = parseBooleanFlag("--all", parsed.flags["--all"]);
+            const target = requireFlagValue("--target", parsed.flags["--target"]);
+            (0, subgraph_1.runSubgraphAuditCommand)({ root, alias, all, target, json });
+            return 0;
+        }
+        case "upgrade-plan": {
+            if (parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("subgraph upgrade-plan accepts at most one alias");
+            }
+            const alias = parsed.positionals[2];
+            const all = parseBooleanFlag("--all", parsed.flags["--all"]);
+            (0, subgraph_1.runSubgraphUpgradePlanCommand)({ root, alias, all, json });
+            return 0;
+        }
         case "sync": {
             if (parsed.positionals.length > 3) {
                 throw new errors_1.UsageError("subgraph sync accepts at most one alias");
@@ -1675,7 +1765,7 @@ function runSubgraphSubcommand(parsed, root) {
             return 0;
         }
         default:
-            throw new errors_1.UsageError("subgraph requires add/list/show/rm/enable/disable/verify/refresh/sync/materialize");
+            throw new errors_1.UsageError("subgraph requires add/list/show/rm/enable/disable/verify/refresh/audit/upgrade-plan/sync/materialize");
     }
 }
 function runWorkSubcommand(parsed, root) {
@@ -2530,6 +2620,31 @@ function runCommand(parsed, root, runtime) {
             (0, validate_1.runValidateCommand)({ root, out, quiet, json });
             return 0;
         }
+        case "status": {
+            if (parsed.positionals.length > 1) {
+                throw new errors_1.UsageError("status does not accept positional arguments");
+            }
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            (0, status_1.runStatusCommand)({ root, json });
+            return 0;
+        }
+        case "fix": {
+            const sub = (parsed.positionals[1] ?? "").toLowerCase();
+            if (!sub) {
+                throw new errors_1.UsageError("fix requires a subcommand");
+            }
+            if (sub !== "plan") {
+                throw new errors_1.UsageError(`unknown fix subcommand: ${sub}`);
+            }
+            if (parsed.positionals.length > 2) {
+                throw new errors_1.UsageError("fix plan does not accept positional arguments");
+            }
+            const family = requireFlagValue("--family", parsed.flags["--family"]);
+            const target = requireFlagValue("--target", parsed.flags["--target"]);
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            (0, fix_1.runFixPlanCommand)({ root, family, target, json });
+            return 0;
+        }
         case "format":
             if (parsed.positionals.length > 1) {
                 throw new errors_1.UsageError("format does not accept positional arguments");
@@ -2543,7 +2658,8 @@ function runCommand(parsed, root, runtime) {
             const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
             const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
             const json = parseBooleanFlag("--json", parsed.flags["--json"]);
-            (0, doctor_1.runDoctorCommand)({ root, noCache, noReindex, json });
+            const strict = parseBooleanFlag("--strict", parsed.flags["--strict"]);
+            (0, doctor_1.runDoctorCommand)({ root, noCache, noReindex, json, strict });
             return 0;
         }
         default: