mdkg 0.3.0 → 0.3.1

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/validate.js

@@ -274,7 +274,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/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`
@@ -193,10 +202,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

package/dist/init/README.md

@@ -29,11 +29,23 @@ 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.
 
+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.
+
+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.
+
 Agent workflow docs can use semantic ids:
 
 ```bash
@@ -130,8 +142,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/init-manifest.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "tool": "mdkg",
-  "mdkg_version": "0.3.0",
+  "mdkg_version": "0.3.1",
   "files": [
     {
       "path": ".mdkg/config.json",
@@ -61,7 +61,7 @@
     {
       "path": ".mdkg/README.md",
       "category": "mdkg_doc",
-      "sha256": "353aa7318974d4b3dbdf772ae5a3deb2d41b5d71ea5308d260aab8081121548b"
+      "sha256": "0661196763bf05681523a576fcd0a29138ccc36df4f48dad7ba16a1f4b7b0418"
     },
     {
       "path": ".mdkg/skills/build-pack-and-execute-task/SKILL.md",
@@ -256,7 +256,7 @@
     {
       "path": "CLI_COMMAND_MATRIX.md",
       "category": "startup_doc",
-      "sha256": "48c1b7fbef3a01faf5ddf8bb232b19362b49ef2a371a7c38ae11302c8b3bccac"
+      "sha256": "a9a7133e5a7c9a07a6814c679d04637370ea144eac19a6500980a37a2c4199f5"
     },
     {
       "path": "llms.txt",

package/dist/util/argparse.js

@@ -94,6 +94,7 @@ const VALUE_FLAGS = new Set([
     "--requires",
     "--target",
     "--snapshot",
+    "--family",
 ]);
 const BOOLEAN_FLAGS = new Set([
     "--tolerant",

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "mdkg",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Markdown Knowledge Graph",
   "license": "MIT",
   "bin": {
     "mdkg": "dist/cli.js"
   },
   "scripts": {
-    "build": "node scripts/clean-build-output.js && tsc -p tsconfig.build.json && node scripts/add-shebang.js && node scripts/copy-init-assets.js",
+    "build": "node scripts/clean-build-output.js && tsc -p tsconfig.build.json && node scripts/add-shebang.js && node scripts/copy-init-assets.js && node scripts/generate-command-contract.js --write",
     "build:test": "node scripts/clean-build-output.js tests && tsc -p tsconfig.test.json",
     "test": "npm run build && npm run build:test && node --test dist/tests/**/*.test.js",
     "test:coverage": "npm run build && npm run build:test && node --test --experimental-test-coverage dist/tests/**/*.test.js",
@@ -25,6 +25,10 @@
     "smoke:archive-work": "npm run build && node scripts/smoke-archive-work.js",
     "smoke:work-invocation": "npm run build && node scripts/smoke-work-invocation.js",
     "smoke:cli-ux-polish": "npm run build && node scripts/smoke-cli-ux-polish.js",
+    "smoke:operator-health": "npm run build && node scripts/smoke-operator-health.js",
+    "smoke:fix-plan": "npm run build && node scripts/smoke-fix-plan.js",
+    "smoke:branch-conflicts": "npm run build && node scripts/smoke-branch-conflicts.js",
+    "smoke:command-docs": "npm run build && node scripts/smoke-command-docs.js",
     "smoke:bundle": "npm run build && node scripts/smoke-bundle.js",
     "smoke:bundle-import": "npm run smoke:subgraph",
     "smoke:visibility": "npm run build && node scripts/smoke-visibility.js",
@@ -33,8 +37,9 @@
     "smoke:goal": "npm run build && node scripts/smoke-goal.js",
     "cli:snapshot": "npm run build && node scripts/cli_help_snapshot.js",
     "cli:check": "npm run build && node scripts/cli_help_snapshot.js --check",
+    "cli:contract": "npm run build && node scripts/generate-command-contract.js --check",
     "prepack": "npm run build && node scripts/assert-publish-ready.js",
-    "prepublishOnly": "npm run test && npm run cli:check && node dist/cli.js validate && npm run smoke:consumer && npm run smoke:matrix && npm run smoke:upgrade && npm run smoke:init && npm run smoke:capabilities && npm run smoke:db && npm run smoke:db-queue && npm run smoke:db-queue-cli && npm run smoke:db-events && npm run smoke:db-materializer && npm run smoke:db-snapshot && npm run smoke:archive-work && npm run smoke:work-invocation && npm run smoke:cli-ux-polish && npm run smoke:bundle && npm run smoke:subgraph && npm run smoke:visibility && npm run smoke:sqlite && npm run smoke:parallel && npm run smoke:goal && node scripts/assert-publish-ready.js",
+    "prepublishOnly": "npm run test && npm run cli:check && npm run cli:contract && node dist/cli.js validate && npm run smoke:consumer && npm run smoke:matrix && npm run smoke:upgrade && npm run smoke:init && npm run smoke:capabilities && npm run smoke:db && npm run smoke:db-queue && npm run smoke:db-queue-cli && npm run smoke:db-events && npm run smoke:db-materializer && npm run smoke:db-snapshot && npm run smoke:archive-work && npm run smoke:work-invocation && npm run smoke:cli-ux-polish && npm run smoke:operator-health && npm run smoke:fix-plan && npm run smoke:branch-conflicts && npm run smoke:command-docs && npm run smoke:bundle && npm run smoke:subgraph && npm run smoke:visibility && npm run smoke:sqlite && npm run smoke:parallel && npm run smoke:goal && node scripts/assert-publish-ready.js",
     "postinstall": "node scripts/postinstall.js",
     "smoke:subgraph": "npm run build && node scripts/smoke-subgraph.js"
   },
@@ -44,6 +49,7 @@
   },
   "files": [
     "dist/cli.js",
+    "dist/command-contract.json",
     "dist/commands/",
     "dist/core/",
     "dist/graph/",
@@ -53,6 +59,7 @@
     "dist/util/",
     "scripts/postinstall.js",
     "README.md",
+    "CLI_COMMAND_MATRIX.md",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
     "LICENSE"