mdkg 0.3.0 → 0.3.2

package/README.md

@@ -14,7 +14,7 @@ mdkg stays deliberately boring:
 - first-class rebuildable SQLite cache through built-in `node:sqlite`
 - no daemon, hosted index, or vector DB
 
-Current package version in source: `0.2.0`
+Current package version in source: `0.3.1`
 
 mdkg is still pre-v1 public alpha software. The public package is usable, but graph, cache, bundle, and DAL contracts may continue to change quickly while the project converges on a stable v1 surface.
 
@@ -48,10 +48,16 @@ Initialize mdkg in a repo:
 
 ```bash
 mdkg init --agent
+mdkg index
 ```
 
 This is the canonical AI-agent bootstrap path. It creates `.mdkg/`, `AGENT_START.md`, `AGENTS.md`, `CLAUDE.md`, `llms.txt`, `CLI_COMMAND_MATRIX.md`, strict-node `SOUL.md` / `HUMAN.md`, the three default mdkg usage skills, `events.jsonl`, the skill registry, core pin updates, and mirrored skill folders under `.agents/skills/` and `.claude/skills/`. It also updates `.gitignore` / `.npmignore` by default. Use `--no-update-ignores` to opt out of those ignore-file updates.
 
+Run `mdkg index` after a fresh init before using `mdkg status --json` or
+`mdkg doctor --strict --json` as health gates. Init writes source scaffold
+files; indexing creates the generated graph, skill, capability, subgraph, and
+SQLite caches that strict doctor expects.
+
 For a non-agent markdown graph only, run `mdkg init`.
 
 Preview safe scaffold upgrades in an existing mdkg workspace:
@@ -86,7 +92,28 @@ mdkg goal next goal-1
 mdkg goal evaluate goal-1 --json
 ```
 
-Goal nodes capture a measurable end condition, recursive loop state, required skills, required checks, and completion evidence. They guide agent harnesses through repeated graph-backed progress, while tasks, bugs, tests, and features remain the concrete executable work units. In this release `mdkg goal evaluate` is report-only: it lists required checks and evidence state, but does not execute scripts.
+Goal nodes capture a measurable end condition, recursive loop state, required skills, required checks, and completion evidence. They guide agent harnesses through repeated graph-backed progress, while tasks, bugs, tests, spikes, and features remain the concrete executable work units. In this release `mdkg goal evaluate` is report-only: it lists required checks and evidence state, but does not execute scripts.
+
+Create a research spike when the next useful work is investigation, planning,
+or grounding a future implementation:
+
+```bash
+mdkg new spike "research mdkg.dev launch guide" --status todo --priority 1
+mdkg task start spike-1
+mdkg show spike-1
+```
+
+Spikes are task-like work nodes, not autonomous research agents. mdkg does not
+perform web search, execute research, create follow-up nodes, or generate
+`SKILL.md` files automatically. Record sources, findings, tradeoffs,
+recommendations, follow-up node ideas, and skill candidates in the spike body,
+then create follow-up work intentionally:
+
+```bash
+mdkg new task "write mdkg.dev quickstart guide" --parent spike-1 --status todo --priority 1
+mdkg new test "validate mdkg.dev docs examples" --parent spike-1 --status todo --priority 1
+mdkg new task "author mdkg.dev launch planning skill" --parent spike-1 --status todo --priority 2
+```
 
 Create an agent workflow document with a semantic portable id:
 
@@ -133,6 +160,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 +171,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:
@@ -246,7 +277,7 @@ The root docs below are the canonical fast-start set for humans and agents:
 mdkg lives under a hidden root directory:
 - `.mdkg/core/` rules and pinned docs
 - `.mdkg/design/` product, design, and decision docs
-- `.mdkg/work/` tasks, bugs, tests, epics, checkpoints
+- `.mdkg/work/` tasks, bugs, tests, spikes, epics, checkpoints
 - `.mdkg/templates/` templates used by `mdkg new`
 - `.mdkg/skills/` Agent Skills packages
 - `.mdkg/archive/` sidecar metadata plus deterministic compressed source/artifact caches
@@ -277,6 +308,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 +317,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.
@@ -403,12 +461,35 @@ as sealed state.
 
 Goal nodes are durable recursive objective contracts. Use `mdkg new goal "<objective>"` when a human or agent needs to keep working across multiple concrete nodes until a measurable end condition is achieved.
 
-`goal` is work-like but distinct from `task`: it can have status, priority, graph links, skills, explicit `scope_refs`, and structured goal fields, but normal `mdkg next` does not select goals. Use `mdkg goal select <goal-id>` once, then `mdkg goal next` to choose the next local feature, task, bug, or test inside that goal. `mdkg goal next <goal-id>` remains available for explicit selection. Epics organize goal scope recursively but are not returned as executable work.
+`goal` is work-like but distinct from `task`: it can have status, priority, graph links, skills, explicit `scope_refs`, and structured goal fields, but normal `mdkg next` does not select goals. Use `mdkg goal select <goal-id>` once, then `mdkg goal next` to choose the next local feature, task, bug, test, or spike inside that goal. `mdkg goal next <goal-id>` remains available for explicit selection. Epics organize goal scope recursively but are not returned as executable work.
 
 Use `mdkg goal claim [goal-id] <work-id>` to durably set `active_node` after choosing the next scoped item. `goal next` is read-only. Use `mdkg goal pause|resume|done` to update goal state after review.
 
 Required checks are stored as report-only guidance. Agents should run the checks themselves, record evidence in the goal or active work item, then use `mdkg goal evaluate` to summarize the current evidence state. During normal goal execution, skill improvements should be recorded as improvement candidates or proposal nodes; edit `SKILL.md` files only when the active node is explicit skill-maintenance work.
 
+## Research spikes
+
+Spikes are first-class actionable work nodes for research and planning. Use
+`mdkg new spike "<question>"` when the right output is a documented
+recommendation, not code. They share the existing task lifecycle:
+
+```bash
+mdkg new spike "research queue-backed materializer UX" --status todo --priority 1
+mdkg task start spike-1
+mdkg task update spike-1 --status review --add-refs task-250
+mdkg task done spike-1
+```
+
+The default spike template includes sections for research question, context,
+search plan, findings, options and tradeoffs, recommendation, follow-up nodes,
+skill candidates, data-structure and algorithm notes, UX notes, security notes,
+mdkg.dev launch implications, and evidence/sources.
+
+Spikes deliberately do not expose a `mdkg spike ...` namespace in this release,
+do not run browser or web-search tools, do not create tasks/tests/goals, and do
+not write `SKILL.md` files. They make the research output reviewable so humans
+or agents can intentionally create the next nodes with normal mdkg commands.
+
 ## Agent workflow files
 
 mdkg recognizes a small set of canonical agent workflow documents:

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");
@@ -132,7 +136,7 @@ function printNewHelp(log) {
     log("Usage:");
     log('  mdkg new <type> "<title>" [options] [--json]');
     log("\nTypes:");
-    log("  rule prd edd dec prop goal epic feat task bug checkpoint test");
+    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("  Use --id <portable-id> with these types for semantic ids like agent.image-worker.");
@@ -153,6 +157,9 @@ function printNewHelp(log) {
     log("  --owners <owner,owner,...> Owners");
     log("\nNotes:");
     log("  spec/work scaffold as validation-clean docs; relational workflow docs need real refs.");
+    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 ...`.");
     printGlobalOptions(log);
 }
 function printGuideHelp(log) {
@@ -514,7 +521,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 +589,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 +621,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");
     }
@@ -669,7 +693,7 @@ function printTaskHelp(log, subcommand) {
             log("Usage:");
             log('  mdkg task start <id-or-qid> [--ws <alias>] [--run-id <id>] [--note "<text>"] [--json]');
             log("\nWhen to use:");
-            log("  Move a task, bug, or test into progress as a structured state change.");
+            log("  Move a task-like node (feat, task, bug, test, or spike) into progress as a structured state change.");
             log("  If `events.jsonl` is missing, mdkg prints a short reminder about `mdkg event enable`.");
             printGlobalOptions(log);
             return;
@@ -698,7 +722,8 @@ function printTaskHelp(log, subcommand) {
             log("  mdkg task update <id-or-qid> [options] [--json]");
             log('  mdkg task done <id-or-qid> [--checkpoint "<title>"] [options] [--json]');
             log("\nNotes:");
-            log("  `mdkg task ...` only supports feat, task, bug, and test nodes.");
+            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.");
             log("  Feat and epic closeout remain checkpoint-first guidance plus manual parent updates.");
             printGlobalOptions(log);
     }
@@ -716,7 +741,7 @@ function printGoalHelp(log, subcommand) {
             log("Usage:");
             log("  mdkg goal next [goal-id-or-qid] [--ws <alias>] [--json]");
             log("\nWhen to use:");
-            log("  Select the next local feature, task, bug, or test inside a recursive goal without mutating active_node.");
+            log("  Select the next local feature, task, bug, test, or spike inside a recursive goal without mutating active_node.");
             log("  If no goal id is supplied, mdkg uses the selected goal or the unique active goal.");
             printGlobalOptions(log);
             return;
@@ -776,7 +801,7 @@ function printGoalHelp(log, subcommand) {
             log("  mdkg goal clear [--json]");
             log("  mdkg goal pause|resume|done <goal-id-or-qid> [--json]");
             log("\nNotes:");
-            log("  - goals orchestrate recursive progress; features, tasks, bugs, and tests are iterable work units");
+            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("  - goal evaluation is report-only and never executes required_checks");
             log("  - subgraph goal qids are read-only; update the source workspace instead");
@@ -824,6 +849,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 +897,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 +911,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 +993,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 +1723,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 +1769,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 +2624,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 +2662,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: