mdkg 0.3.0 → 0.3.2

package/dist/commands/subgraph.js

@@ -10,6 +10,8 @@ exports.runSubgraphRemoveCommand = runSubgraphRemoveCommand;
 exports.runSubgraphEnableCommand = runSubgraphEnableCommand;
 exports.runSubgraphDisableCommand = runSubgraphDisableCommand;
 exports.runSubgraphVerifyCommand = runSubgraphVerifyCommand;
+exports.runSubgraphAuditCommand = runSubgraphAuditCommand;
+exports.runSubgraphUpgradePlanCommand = runSubgraphUpgradePlanCommand;
 exports.runSubgraphRefreshCommand = runSubgraphRefreshCommand;
 exports.runSubgraphSyncCommand = runSubgraphSyncCommand;
 exports.runSubgraphMaterializeCommand = runSubgraphMaterializeCommand;
@@ -321,6 +323,304 @@ function runSubgraphVerifyCommand(options) {
         throw new errors_1.ValidationError("subgraph verify failed");
     }
 }
+function pushAuditCheck(receipt, check) {
+    receipt.checks.push(check);
+    if (!check.ok && check.severity === "error") {
+        receipt.errors.push(`${check.id}: ${check.message}`);
+    }
+    else if (!check.ok && check.severity === "warning") {
+        receipt.warnings.push(`${check.id}: ${check.message}`);
+    }
+}
+function inspectSourcePathForAudit(root, alias, subgraph) {
+    try {
+        return inspectSourcePath(root, alias, subgraph, true);
+    }
+    catch {
+        return undefined;
+    }
+}
+function auditOneAlias(options) {
+    const receipt = {
+        alias: options.alias,
+        enabled: options.health.enabled,
+        visibility: options.health.visibility,
+        source_path: options.health.source_path,
+        source_repo: options.health.source_repo,
+        capability_summary: {
+            node_count: options.nodeTypes.length,
+            spec_count: options.nodeTypes.filter((type) => type === "spec").length,
+            work_count: options.nodeTypes.filter((type) => type === "work").length,
+            skill_count: options.nodeTypes.filter((type) => type === "skill").length,
+        },
+        checks: [],
+        warnings: [],
+        errors: [],
+        ok: true,
+    };
+    pushAuditCheck(receipt, {
+        id: "subgraph.enabled",
+        ok: options.subgraph.enabled,
+        severity: options.subgraph.enabled ? "info" : "warning",
+        message: options.subgraph.enabled ? "subgraph is enabled" : "subgraph is disabled",
+    });
+    if (!options.subgraph.source_path) {
+        pushAuditCheck(receipt, {
+            id: "subgraph.source_path.configured",
+            ok: false,
+            severity: "warning",
+            message: "source_path is not configured; sync and upgrade planning cannot inspect child Git state",
+        });
+    }
+    else {
+        let gitState;
+        try {
+            gitState = inspectSourcePath(options.root, options.alias, options.subgraph, true);
+            receipt.source_git_head = gitState.head;
+            receipt.source_repo_current = gitState.sourceRepo;
+            receipt.dirty_tracked = gitState.dirtyTracked;
+            receipt.dirty_tracked_paths = gitState.dirtyTrackedPaths;
+            pushAuditCheck(receipt, {
+                id: "subgraph.source_path.git_root",
+                ok: true,
+                severity: "info",
+                message: "source_path is a contained child Git repo root with .mdkg",
+                path: options.subgraph.source_path,
+            });
+            pushAuditCheck(receipt, {
+                id: "subgraph.source_path.clean",
+                ok: !gitState.dirtyTracked,
+                severity: "warning",
+                message: gitState.dirtyTracked
+                    ? `source_path has dirty tracked changes: ${gitState.dirtyTrackedPaths.join(", ")}`
+                    : "source_path has no dirty tracked changes",
+                path: options.subgraph.source_path,
+                details: { dirty_tracked_paths: gitState.dirtyTrackedPaths },
+            });
+            if (options.subgraph.source_repo && options.subgraph.source_repo !== gitState.sourceRepo) {
+                pushAuditCheck(receipt, {
+                    id: "subgraph.source_repo.current",
+                    ok: false,
+                    severity: "warning",
+                    message: `configured source_repo differs from child repo head: ${options.subgraph.source_repo} -> ${gitState.sourceRepo}`,
+                    details: { configured: options.subgraph.source_repo, current: gitState.sourceRepo },
+                });
+            }
+        }
+        catch (err) {
+            pushAuditCheck(receipt, {
+                id: "subgraph.source_path.git_root",
+                ok: false,
+                severity: "error",
+                message: err instanceof Error ? err.message : String(err),
+                path: options.subgraph.source_path,
+            });
+        }
+        if (gitState) {
+            for (const source of options.subgraph.sources) {
+                const bundlePath = path_1.default.resolve(options.root, source.path);
+                pushAuditCheck(receipt, {
+                    id: "subgraph.bundle.root_owned",
+                    ok: !isPathWithin(gitState.sourceRoot, bundlePath),
+                    severity: "error",
+                    message: isPathWithin(gitState.sourceRoot, bundlePath)
+                        ? `bundle path must be root-owned and outside source_path: ${source.path}`
+                        : `bundle path is root-owned and outside source_path: ${source.path}`,
+                    path: source.path,
+                });
+            }
+        }
+    }
+    for (const source of options.health.sources) {
+        pushAuditCheck(receipt, {
+            id: "subgraph.bundle.enabled",
+            ok: source.enabled,
+            severity: source.enabled ? "info" : "warning",
+            message: source.enabled ? `source is enabled: ${source.path}` : `source is disabled: ${source.path}`,
+            path: source.path,
+        });
+        pushAuditCheck(receipt, {
+            id: "subgraph.bundle.valid",
+            ok: source.error_count === 0,
+            severity: "error",
+            message: source.error_count === 0
+                ? `bundle source is valid: ${source.path}`
+                : `bundle source has errors: ${source.errors.join("; ")}`,
+            path: source.path,
+            details: { errors: source.errors },
+        });
+        pushAuditCheck(receipt, {
+            id: "subgraph.bundle.fresh",
+            ok: !source.stale,
+            severity: "warning",
+            message: source.stale
+                ? `bundle source is stale: ${source.warnings.join("; ")}`
+                : `bundle source is fresh: ${source.path}`,
+            path: source.path,
+            details: { warnings: source.warnings },
+        });
+    }
+    if (options.targetRoot) {
+        const outputDir = path_1.default.join(options.targetRoot, options.alias);
+        const markerPath = path_1.default.join(outputDir, ".mdkg-materialized.json");
+        const exists = fs_1.default.existsSync(outputDir);
+        const hasMarker = fs_1.default.existsSync(markerPath);
+        pushAuditCheck(receipt, {
+            id: "subgraph.materialize.target_safe",
+            ok: !exists || hasMarker,
+            severity: "error",
+            message: !exists
+                ? `materialize target is available: ${relativeToRoot(options.root, outputDir)}`
+                : hasMarker
+                    ? `materialize target has mdkg marker: ${relativeToRoot(options.root, outputDir)}`
+                    : `materialize target exists without mdkg marker: ${relativeToRoot(options.root, outputDir)}`,
+            path: relativeToRoot(options.root, outputDir),
+        });
+    }
+    receipt.ok = receipt.errors.length === 0;
+    return receipt;
+}
+function runSubgraphAuditCommand(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    const aliases = selectAliases(config, options.alias, options.all);
+    const projection = (0, subgraphs_1.buildSubgraphsIndex)(options.root, config).index;
+    const targetRoot = options.target ? path_1.default.resolve(options.root, normalizeContained(options.target, "--target")) : undefined;
+    const results = aliases.map((alias) => {
+        const health = projection.subgraphs.find((item) => item.alias === alias);
+        if (!health) {
+            throw new errors_1.NotFoundError(`subgraph not found: ${alias}`);
+        }
+        const nodeTypes = Object.values(projection.nodes)
+            .filter((node) => node.ws === alias)
+            .map((node) => node.type);
+        return auditOneAlias({ root: options.root, alias, subgraph: config.subgraphs[alias], health, nodeTypes, targetRoot });
+    });
+    const errors = results.flatMap((item) => item.errors.map((error) => `${item.alias}: ${error}`));
+    const warnings = results.flatMap((item) => item.warnings.map((warning) => `${item.alias}: ${warning}`));
+    const receipt = {
+        action: "audited",
+        ok: errors.length === 0,
+        count: results.length,
+        target: targetRoot ? relativeToRoot(options.root, targetRoot) : undefined,
+        errors,
+        warnings,
+        subgraphs: results,
+    };
+    if (options.json) {
+        writeJson(receipt);
+    }
+    else {
+        console.log(`subgraphs audited: ${results.length}`);
+        for (const item of results) {
+            const status = item.errors.length > 0 ? "error" : item.warnings.length > 0 ? "warning" : "ok";
+            console.log(`${item.alias} | ${status} | checks:${item.checks.length}`);
+        }
+    }
+    if (!receipt.ok) {
+        throw new errors_1.ValidationError("subgraph audit failed");
+    }
+}
+function upgradePlanForAlias(options) {
+    const actions = [];
+    const blockers = [];
+    if (!options.subgraph.enabled) {
+        actions.push({
+            action: "none",
+            status: "skipped",
+            reason: "subgraph is disabled",
+        });
+        return { alias: options.alias, ok: true, capability_summary: options.audit.capability_summary, actions, blockers };
+    }
+    if (!options.subgraph.source_path) {
+        blockers.push("source_path is required for upgrade planning");
+    }
+    const sourceGitError = options.audit.checks.find((check) => check.id === "subgraph.source_path.git_root" && !check.ok && check.severity === "error");
+    if (sourceGitError) {
+        blockers.push(sourceGitError.message);
+    }
+    if (options.audit.dirty_tracked) {
+        blockers.push(`source_path has dirty tracked changes: ${options.audit.dirty_tracked_paths?.join(", ")}`);
+    }
+    const rootOwnedErrors = options.audit.checks.filter((check) => check.id === "subgraph.bundle.root_owned" && !check.ok);
+    blockers.push(...rootOwnedErrors.map((check) => check.message));
+    const bundleErrors = options.health.sources.flatMap((source) => source.errors.map((error) => `${source.path}: ${error}`));
+    blockers.push(...bundleErrors);
+    const needsSync = options.health.stale ||
+        !options.subgraph.source_repo ||
+        (options.audit.source_repo_current !== undefined && options.subgraph.source_repo !== options.audit.source_repo_current);
+    if (blockers.length > 0) {
+        actions.push({
+            action: "subgraph.sync",
+            status: "blocked",
+            command: `mdkg subgraph sync ${options.alias} --dry-run --json`,
+            blockers,
+        });
+    }
+    else if (needsSync) {
+        actions.push({
+            action: "subgraph.sync",
+            status: "planned",
+            command: `mdkg subgraph sync ${options.alias} --dry-run --json`,
+            apply_command: `mdkg subgraph sync ${options.alias} --json`,
+            reason: options.health.stale ? "bundle is stale or source HEAD changed" : "configured source_repo is missing or behind current child head",
+            current_source_repo: options.audit.source_repo_current,
+            configured_source_repo: options.subgraph.source_repo,
+        });
+    }
+    else {
+        actions.push({
+            action: "subgraph.verify",
+            status: "planned",
+            command: `mdkg subgraph verify ${options.alias} --json`,
+            reason: "bundle snapshot is current; verify before downstream use",
+        });
+    }
+    actions.push({
+        action: "subgraph.materialize",
+        status: "optional",
+        command: `mdkg subgraph materialize ${options.alias} --target .mdkg/subgraphs --gitignore --json`,
+        reason: "generate an ignored read-only inspection tree when human review needs file-level child graph context",
+    });
+    return { alias: options.alias, ok: blockers.length === 0, capability_summary: options.audit.capability_summary, actions, blockers };
+}
+function runSubgraphUpgradePlanCommand(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    const aliases = selectAliases(config, options.alias, options.all);
+    const projection = (0, subgraphs_1.buildSubgraphsIndex)(options.root, config).index;
+    const plans = aliases.map((alias) => {
+        const health = projection.subgraphs.find((item) => item.alias === alias);
+        if (!health) {
+            throw new errors_1.NotFoundError(`subgraph not found: ${alias}`);
+        }
+        const nodeTypes = Object.values(projection.nodes)
+            .filter((node) => node.ws === alias)
+            .map((node) => node.type);
+        const audit = auditOneAlias({ root: options.root, alias, subgraph: config.subgraphs[alias], health, nodeTypes });
+        return upgradePlanForAlias({ root: options.root, alias, subgraph: config.subgraphs[alias], audit, health });
+    });
+    const blockers = plans.flatMap((plan) => plan.blockers.map((blocker) => `${plan.alias}: ${blocker}`));
+    const receipt = {
+        action: "upgrade_plan",
+        ok: blockers.length === 0,
+        count: plans.length,
+        apply_supported: false,
+        mutation_policy: "read_only_plan",
+        blockers,
+        subgraphs: plans,
+    };
+    if (options.json) {
+        writeJson(receipt);
+    }
+    else {
+        console.log(`subgraph upgrade plan: ${plans.length}`);
+        for (const plan of plans) {
+            console.log(`${plan.alias} | ${plan.ok ? "ok" : "blocked"} | actions:${plan.actions.length}`);
+        }
+    }
+    if (!receipt.ok) {
+        throw new errors_1.ValidationError("subgraph upgrade plan blocked");
+    }
+}
 function runSubgraphRefreshCommand(options) {
     withSubgraphLock(options.root, () => {
         const config = (0, config_1.loadConfig)(options.root);

package/dist/commands/task.js

@@ -22,7 +22,7 @@ const atomic_1 = require("../util/atomic");
 const lock_1 = require("../util/lock");
 const event_support_1 = require("./event_support");
 const checkpoint_1 = require("./checkpoint");
-const MUTABLE_TASK_TYPES = new Set(["feat", "task", "bug", "test"]);
+const MUTABLE_TASK_TYPES = new Set(["feat", "task", "bug", "test", "spike"]);
 const SKILL_SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 function parseCsvList(raw) {
     if (!raw) {
@@ -113,7 +113,7 @@ function loadMutableTaskNode(root, idOrQid, wsHint) {
         throw new errors_1.UsageError(`cannot mutate read-only subgraph node ${node.qid}; update the source workspace for subgraph ${node.source.subgraph_alias}`);
     }
     if (!MUTABLE_TASK_TYPES.has(node.type)) {
-        throw new errors_1.UsageError(`mdkg task only supports feat, task, bug, and test nodes; use markdown editing for ${node.type}:${node.id}`);
+        throw new errors_1.UsageError(`mdkg task only supports feat, task, bug, test, and spike nodes; use markdown editing for ${node.type}:${node.id}`);
     }
     const filePath = path_1.default.resolve(root, node.path);
     const content = fs_1.default.readFileSync(filePath, "utf8");

package/dist/commands/validate.js

@@ -36,6 +36,17 @@ const RECOMMENDED_HEADINGS = {
         "Links / Artifacts",
     ],
     feat: ["Overview", "Acceptance Criteria", "Notes"],
+    spike: [
+        "Research Question",
+        "Context And Constraints",
+        "Search Plan",
+        "Findings",
+        "Options And Tradeoffs",
+        "Recommendation",
+        "Follow-Up Nodes To Create",
+        "Skill Candidates",
+        "Evidence And Sources",
+    ],
     epic: ["Goal", "Scope", "Milestones", "Out of Scope", "Risks", "Links / Artifacts"],
     checkpoint: [
         "Summary",
@@ -274,7 +285,7 @@ function runValidateCommand(options) {
                 });
                 if (idsByWorkspace[alias].has(node.id)) {
                     const firstPath = idsByWorkspace[alias].get(node.id);
-                    errors.push(`${filePath}: duplicate id ${node.id} in workspace ${alias} (also in ${firstPath})`);
+                    errors.push(`${path_1.default.relative(options.root, filePath).split(path_1.default.sep).join("/")}: duplicate id ${node.id} in workspace ${alias} (also in ${firstPath ? path_1.default.relative(options.root, firstPath).split(path_1.default.sep).join("/") : "unknown"})`);
                     continue;
                 }
                 idsByWorkspace[alias].set(node.id, filePath);

package/dist/commands/workspace.js

@@ -4,16 +4,18 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runWorkspaceListCommand = runWorkspaceListCommand;
-exports.runWorkspaceAddCommand = runWorkspaceAddCommand;
-exports.runWorkspaceRemoveCommand = runWorkspaceRemoveCommand;
 exports.runWorkspaceEnableCommand = runWorkspaceEnableCommand;
 exports.runWorkspaceDisableCommand = runWorkspaceDisableCommand;
+exports.runWorkspaceAddCommand = runWorkspaceAddCommand;
+exports.runWorkspaceRemoveCommand = runWorkspaceRemoveCommand;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const config_1 = require("../core/config");
 const migrate_1 = require("../core/migrate");
 const workspace_path_1 = require("../core/workspace_path");
+const atomic_1 = require("../util/atomic");
 const errors_1 = require("../util/errors");
+const lock_1 = require("../util/lock");
 const ALIAS_RE = /^[a-z][a-z0-9_]*$/;
 function workspaceReceipt(alias, workspace) {
     return {
@@ -59,7 +61,7 @@ function readRawConfig(root) {
     return { path: configPath, raw: migrated };
 }
 function writeRawConfig(configPath, raw) {
-    fs_1.default.writeFileSync(configPath, JSON.stringify(raw, null, 2), "utf8");
+    (0, atomic_1.atomicWriteFile)(configPath, `${JSON.stringify(raw, null, 2)}\n`);
 }
 function normalizeAlias(alias) {
     if (alias.toLowerCase() === "all") {
@@ -114,7 +116,7 @@ function normalizeVisibility(value) {
     }
     throw new errors_1.UsageError("--visibility must be private, internal, or public");
 }
-function runWorkspaceAddCommand(options) {
+function runWorkspaceAddCommandLocked(options) {
     const alias = normalizeAlias(options.alias);
     const workspacePath = normalizeCommandWorkspacePath(options.workspacePath, "workspace path");
     const mdkgDir = normalizeCommandWorkspacePath(options.mdkgDir ?? ".mdkg", "workspace mdkg dir");
@@ -153,7 +155,7 @@ function runWorkspaceAddCommand(options) {
     fs_1.default.mkdirSync(path_1.default.join(wsRoot, "work"), { recursive: true });
     printWorkspaceMutationReceipt("added", workspaceReceipt(alias, workspace), options.json);
 }
-function runWorkspaceRemoveCommand(options) {
+function runWorkspaceRemoveCommandLocked(options) {
     const alias = normalizeAlias(options.alias);
     if (alias === "root") {
         throw new errors_1.UsageError("cannot remove root workspace");
@@ -196,8 +198,18 @@ function setWorkspaceEnabled(options, enabled) {
     printWorkspaceMutationReceipt(enabled ? "enabled" : "disabled", workspaceReceipt(alias, updated), options.json);
 }
 function runWorkspaceEnableCommand(options) {
-    setWorkspaceEnabled(options, true);
+    const config = (0, config_1.loadConfig)(options.root);
+    return (0, lock_1.withMutationLock)(options.root, config.index.lock_timeout_ms, () => setWorkspaceEnabled(options, true));
 }
 function runWorkspaceDisableCommand(options) {
-    setWorkspaceEnabled(options, false);
+    const config = (0, config_1.loadConfig)(options.root);
+    return (0, lock_1.withMutationLock)(options.root, config.index.lock_timeout_ms, () => setWorkspaceEnabled(options, false));
+}
+function runWorkspaceAddCommand(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    return (0, lock_1.withMutationLock)(options.root, config.index.lock_timeout_ms, () => runWorkspaceAddCommandLocked(options));
+}
+function runWorkspaceRemoveCommand(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    return (0, lock_1.withMutationLock)(options.root, config.index.lock_timeout_ms, () => runWorkspaceRemoveCommandLocked(options));
 }

package/dist/graph/goal_scope.js

@@ -5,7 +5,7 @@ exports.goalScopeRefs = goalScopeRefs;
 exports.collectGoalScope = collectGoalScope;
 const qid_1 = require("../util/qid");
 exports.GOAL_SCOPE_CONTAINER_TYPES = new Set(["epic", "feat"]);
-exports.GOAL_SCOPE_ACTIONABLE_TYPES = new Set(["feat", "task", "bug", "test"]);
+exports.GOAL_SCOPE_ACTIONABLE_TYPES = new Set(["feat", "task", "bug", "test", "spike"]);
 exports.GOAL_SCOPE_ALLOWED_TYPES = new Set([
     ...exports.GOAL_SCOPE_CONTAINER_TYPES,
     ...exports.GOAL_SCOPE_ACTIONABLE_TYPES,

package/dist/graph/node.js

@@ -10,7 +10,7 @@ const id_1 = require("../util/id");
 const refs_1 = require("../util/refs");
 const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 const DEC_ID_RE = /^dec-[0-9]+$/;
-exports.WORK_TYPES = new Set(["goal", "epic", "feat", "task", "bug", "checkpoint", "test"]);
+exports.WORK_TYPES = new Set(["goal", "epic", "feat", "task", "bug", "spike", "checkpoint", "test"]);
 exports.DEC_TYPES = new Set(["dec"]);
 exports.ALLOWED_TYPES = new Set([
     "rule",
@@ -23,6 +23,7 @@ exports.ALLOWED_TYPES = new Set([
     "feat",
     "task",
     "bug",
+    "spike",
     "checkpoint",
     "test",
     "archive",

package/dist/init/CLI_COMMAND_MATRIX.md

@@ -26,6 +26,15 @@ Primary commands:
 - `mdkg goal`
 - `mdkg task`
 - `mdkg validate`
+- `mdkg status [--json]`
+- `mdkg fix plan [--family index|refs|ids|all] [--target <id-or-qid>] [--json]`
+
+Operator health:
+- `mdkg status [--json]` is a read-only summary for scripts and agents
+- reports mdkg version/config, git state, graph/index freshness, selected-goal state, project DB verification summary, and generated cache status
+- does not rebuild indexes, run migrations, repair files, mutate graph nodes, or change selected-goal state
+- `mdkg fix plan ...` is dry-run repair planning only; it writes nothing and `fix apply` is not exposed
+- `fix plan --json` returns a receipt-shaped plan with selected families, risk counts, paths, reason codes, and `apply_supported: false`
 
 Index backend:
 - fresh mdkg workspaces default to `index.backend: sqlite`
@@ -83,6 +92,7 @@ Validation commands:
 Node creation commands:
 - `mdkg new <type> "<title>" [options] [--json]`
 - `mdkg new goal "<title>" [options] [--json]`
+- `mdkg new spike "<research question>" [options] [--json]`
 
 Agent workflow file type creation:
 - `mdkg new spec "<title>" [options] [--json]`
@@ -100,6 +110,9 @@ Agent workflow notes:
 - `spec` and `work` scaffold as validation-clean standalone docs.
 - `work_order`, `receipt`, `feedback`, `dispute`, and `proposal` need real refs before strict `mdkg validate` passes.
 - `goal` nodes capture recursive objective state and required checks, but normal `mdkg next` does not select them.
+- `spike` nodes are actionable research/planning work under `.mdkg/work/`; use `mdkg task start|update|done` for lifecycle state.
+- Spikes record sources, findings, recommendations, follow-up node ideas, and skill candidates in Markdown body sections; they do not perform web search, execute research, create follow-up nodes, generate `SKILL.md`, or expose a `mdkg spike ...` namespace automatically.
+- after fresh init, run `mdkg index` before treating `mdkg doctor --strict --json` as a clean health gate; init writes source scaffold files and index writes generated caches.
 
 Workspace registry commands:
 - `mdkg workspace ls [--json]`
@@ -116,6 +129,7 @@ Task mutation commands:
 - `mdkg task start <id-or-qid> [--ws <alias>] [--run-id <id>] [--note "<text>"] [--json]`
 - `mdkg task update <id-or-qid> [options] [--json]`
 - `mdkg task done <id-or-qid> [--checkpoint "<title>"] [options] [--json]`
+- task commands support task-like `feat`, `task`, `bug`, `test`, and `spike` nodes
 
 Checkpoint commands:
 - `mdkg checkpoint new <title> [--ws <alias>] [--json]`
@@ -148,7 +162,7 @@ Capability discovery:
 - capability records are deterministic cache projections from Markdown
 - records include source hash, headings, refs, and `indexed_at`
 - SPEC and WORK capability records include read-only `linkage` arrays for related SPECs, work contracts, work orders, and receipts when those graph mirrors exist
-- normal task, epic, feat, bug, test, and checkpoint nodes are intentionally excluded
+- normal task, epic, feat, bug, test, spike, and checkpoint nodes are intentionally excluded
 
 Spec capability records:
 - `mdkg spec list [--json]`
@@ -193,10 +207,14 @@ Subgraph orchestration:
 - `mdkg subgraph disable <alias> [--json]`
 - `mdkg subgraph verify [alias|--all] [--json]`
 - `mdkg subgraph refresh [alias|--all] [--json]`
+- `mdkg subgraph audit [alias|--all] [--target <path>] [--json]`
+- `mdkg subgraph upgrade-plan [alias|--all] [--json]`
 - `mdkg subgraph sync [alias|--all] [--dry-run] [--allow-dirty] [--json]`
 - `mdkg subgraph materialize [alias|--all] --target <path> [--clean] [--gitignore] [--json]`
 - subgraphs are read-only planning views and use subgraph-alias qids such as `child_repo:task-1`
 - subgraph refresh reloads configured bundle sources only and never mutates child repos
+- subgraph audit reports read-only source/bundle/materialized-target safety checks
+- subgraph upgrade-plan returns a read-only downstream plan with `apply_supported: false`
 - subgraph sync builds root-owned bundle snapshots from configured clean child Git repo `source_path` entries
 - subgraph materialize extracts generated inspection trees under a target directory; `.mdkg/subgraphs/` is local generated state
 - public/internal subgraphs require public bundle profiles
@@ -240,7 +258,7 @@ Goal nodes:
 - `mdkg goal pause <goal-id-or-qid> [--ws <alias>] [--json]`
 - `mdkg goal resume <goal-id-or-qid> [--ws <alias>] [--json]`
 - `mdkg goal done <goal-id-or-qid> [--ws <alias>] [--json]`
-- goals orchestrate recursive progress through explicit `scope_refs`; tasks, bugs, tests, and features remain concrete executable units
+- goals orchestrate recursive progress through explicit `scope_refs`; tasks, bugs, tests, spikes, and features remain concrete executable units
 - `goal next` is read-only; use `goal claim` to set `active_node`
 - `mdkg goal evaluate` is report-only and never runs commands from `required_checks`
 - skill improvements discovered during normal goal execution should be recorded as candidates or proposals unless the active node is skill-maintenance

package/dist/init/README.md

@@ -8,7 +8,7 @@ mdkg is pre-v1 public alpha software. Graph, cache, bundle, and DAL contracts ma
 
 - `core/`: rules, operating guide, and pinned docs
 - `design/`: product/engineering decision records
-- `work/`: epics, tasks, bugs, tests, checkpoints
+- `work/`: epics, tasks, bugs, tests, spikes, checkpoints
 - `templates/`: default node templates
 - `archive/`: sidecar metadata and deterministic compressed source/artifact caches
 - `bundles/`: optional committed full graph snapshot bundles
@@ -20,6 +20,7 @@ mdkg is pre-v1 public alpha software. Graph, cache, bundle, and DAL contracts ma
 
 ```bash
 mdkg upgrade
+mdkg index
 mdkg new task "..." --status todo --priority 1
 mdkg search "..."
 mdkg show <id>
@@ -29,10 +30,38 @@ mdkg spec list --json
 mdkg archive list
 mdkg bundle create --profile private
 mdkg subgraph list --json
+mdkg status --json
+mdkg fix plan --json
 mdkg validate
 ```
 
-This repo is already initialized. Use `mdkg upgrade` to preview safe scaffold updates, `mdkg new` to create work, `mdkg new goal "..."` plus `mdkg goal select/current/next/claim/evaluate` for recursive long-running objectives, `mdkg search`/`mdkg show` to inspect graph state, `mdkg capability ...` to inspect cached skill/spec/work/core/design capabilities, `mdkg spec ...` for focused optional SPEC records, `mdkg capability resolve ...` to rank local and subgraph capabilities, `mdkg archive ...` to register source/artifact sidecars, `mdkg work ...` to create work contract/order/receipt semantic mirrors and deterministic trigger/verification records, `mdkg bundle ...` to create full graph snapshot bundles, `mdkg subgraph ...` to register read-only child graph planning views, `mdkg pack <id>` to build deterministic context, and `mdkg validate` before closeout.
+This repo is already initialized. Use `mdkg upgrade` to preview safe scaffold updates, `mdkg index` to create or refresh generated graph/skill/capability/subgraph and SQLite caches after init, `mdkg new` to create work, `mdkg new goal "..."` plus `mdkg goal select/current/next/claim/evaluate` for recursive long-running objectives, `mdkg search`/`mdkg show` to inspect graph state, `mdkg capability ...` to inspect cached skill/spec/work/core/design capabilities, `mdkg spec ...` for focused optional SPEC records, `mdkg capability resolve ...` to rank local and subgraph capabilities, `mdkg archive ...` to register source/artifact sidecars, `mdkg work ...` to create work contract/order/receipt semantic mirrors and deterministic trigger/verification records, `mdkg bundle ...` to create full graph snapshot bundles, `mdkg subgraph ...` to register read-only child graph planning views, `mdkg pack <id>` to build deterministic context, and `mdkg validate` before closeout.
+
+Use `mdkg status --json` for a read-only operator summary of Git, graph,
+selected-goal, project DB, and generated-cache health before mutating work. Use
+`mdkg doctor --strict --json` for typed diagnostic checks in CI or agent
+orchestration. These commands inspect state; they do not apply repairs. After a
+fresh init, run `mdkg index` first so strict doctor can load generated caches.
+
+Use `mdkg fix plan --json` for dry-run repair guidance. It reports generated
+index/cache repair hints, missing graph references, and duplicate local ids as
+receipt-shaped planned changes with risk levels and `apply_supported: false`.
+`fix apply` is not exposed; repair application is intentionally deferred.
+
+Use research spikes for investigation and planning work that should produce a
+reviewable recommendation before implementation:
+
+```bash
+mdkg new spike "research docs launch workflow" --status todo --priority 1
+mdkg task start spike-1
+mdkg show spike-1
+```
+
+Spikes use the existing task lifecycle and goal routing. They do not perform web
+search, execute research, create follow-up nodes, or generate `SKILL.md` files
+automatically. Record sources, findings, recommendations, follow-up node ideas,
+and skill candidates in the spike body, then create follow-up tasks or tests
+intentionally with `mdkg new task ...` or `mdkg new test ...`.
 
 Agent workflow docs can use semantic ids:
 
@@ -130,8 +159,12 @@ Register child bundle snapshots as read-only subgraphs with:
 mdkg subgraph add child_repo child-repo/.mdkg/bundles/private/all.mdkg.zip --source-path child-repo
 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
 ```
 
+Use `mdkg subgraph audit child_repo --target .mdkg/subgraphs --json` to inspect 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. Use `mdkg subgraph upgrade-plan child_repo --json` for a read-only downstream plan; it returns `apply_supported: false`.
+
 Use `mdkg subgraph sync child_repo --dry-run --json` before writing a refreshed root-owned child bundle snapshot, then `mdkg subgraph sync child_repo --json` when the receipt is acceptable. `sync` inspects the configured child Git repo `source_path`, refuses dirty tracked changes by default, verifies the new bundle, and records `source_repo` as `<branch>@<sha>` without committing, pulling, pushing, checking out, resetting, or mutating child mdkg Markdown.
 
 Use `mdkg subgraph materialize child_repo --target .mdkg/subgraphs --gitignore --json` only when you need a generated read-only inspection tree. Materialized views are local generated state and are not root graph nodes.

package/dist/init/core/rule-5-release-and-versioning.md

@@ -67,10 +67,19 @@ It MUST NOT include:
 - verify `package.json` `"files"` includes only expected files
 - optionally run `npm pack` and inspect tarball contents
 
-7) Publish
-- `npm publish`
-
-8) Tag and push
+7) Confirm npm auth
+- if using an exported `NPM_TOKEN`, create a temporary npm userconfig that
+  references `${NPM_TOKEN}` literally:
+  `//registry.npmjs.org/:_authToken=${NPM_TOKEN}`
+- run `npm whoami --registry=https://registry.npmjs.org/ --userconfig=/private/tmp/mdkg-npm-publish.npmrc`
+- do not print the token, do not commit the temp userconfig, and do not add
+  unsupported `always-auth` config
+
+8) Publish
+- `npm publish --registry=https://registry.npmjs.org/ --userconfig=/private/tmp/mdkg-npm-publish.npmrc`
+- omit `--userconfig` only when an existing npm login has already been verified
+
+9) Tag and push
 - create git tag matching version (example `v0.1.0`)
 - push commits and tags