mdkg 0.2.0 → 0.3.1

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

@@ -32,6 +32,7 @@ exports.AGENT_FILE_BASENAMES = {
 exports.AGENT_ATTRIBUTE_KEY_ORDER = {
     spec: [
         "version",
+        "spec_kind",
         "role",
         "runtime_mode",
         "work_contracts",
@@ -68,7 +69,10 @@ exports.AGENT_ATTRIBUTE_KEY_ORDER = {
         "requester",
         "order_status",
         "request_ref",
+        "trigger_ref",
+        "payload_hash",
         "input_refs",
+        "queue_refs",
         "requested_outputs",
         "constraint_refs",
         "artifact_policy",
@@ -79,8 +83,10 @@ exports.AGENT_ATTRIBUTE_KEY_ORDER = {
         "receipt_status",
         "outcome",
         "cost_ref",
+        "redaction_policy",
         "proof_refs",
         "attestation_refs",
+        "evidence_hashes",
         "input_hashes",
         "output_hashes",
     ],
@@ -128,6 +134,27 @@ const UPDATE_POLICY_VALUES = new Set([
     "automatic",
     "disabled",
 ]);
+const SPEC_KIND_VALUES = new Set([
+    "cli_tool",
+    "api",
+    "agent",
+    "runtime_agent",
+    "capability",
+    "tool",
+    "model",
+    "runtime_image",
+    "integration",
+    "project_service",
+]);
+const DOCUMENTATION_ONLY_SPEC_KIND_ROUTES = {
+    gap_register: "use an EDD, task, checkpoint, or goal for gap registers",
+    checkpoint: "use a checkpoint node for checkpoint evidence",
+    roadmap: "use an epic, goal, EDD, or PRD for roadmaps",
+    audit: "use a task, checkpoint, or EDD for audits",
+    go_no_go: "use a DEC, task, or checkpoint for go/no-go notes",
+    planning_note: "use an EDD, task, or checkpoint for planning notes",
+    launch_checklist: "use a task, test, checkpoint, or DEC for launch checklists",
+};
 const PRICING_MODEL_VALUES = new Set([
     "free",
     "included",
@@ -146,6 +173,11 @@ const ORDER_STATUS_VALUES = new Set([
 ]);
 const RECEIPT_STATUS_VALUES = new Set(["recorded", "verified", "rejected", "superseded"]);
 const OUTCOME_VALUES = new Set(["success", "partial", "failure"]);
+const REDACTION_POLICY_VALUES = new Set([
+    "refs_and_hashes_only",
+    "redacted_summary",
+    "external_private",
+]);
 const ARTIFACT_POLICY_VALUES = new Set([
     "commit_sidecar_and_zip",
     "external_only",
@@ -265,6 +297,16 @@ function requireEnum(value, key, allowed, filePath) {
         throw formatError(filePath, `${key} must be one of ${Array.from(allowed).join(", ")}`);
     }
 }
+function validateSpecKind(value, filePath) {
+    if (SPEC_KIND_VALUES.has(value)) {
+        return;
+    }
+    const route = DOCUMENTATION_ONLY_SPEC_KIND_ROUTES[value];
+    if (route) {
+        throw formatError(filePath, `spec_kind ${value} is documentation-only; ${route}. SPEC.md must define a reusable invocable capability surface.`);
+    }
+    throw formatError(filePath, `spec_kind must be one of ${Array.from(SPEC_KIND_VALUES).join(", ")}; documentation-only records belong in normal mdkg nodes such as task, test, epic, goal, checkpoint, EDD, PRD, DEC, bug, feedback, dispute, or proposal.`);
+}
 function requireLowerToken(value, key, filePath) {
     if (!LOWER_TOKEN_RE.test(value)) {
         throw formatError(filePath, `${key} must be lowercase snake/kebab style`);
@@ -290,6 +332,14 @@ function validatePortableRefs(values, key, filePath) {
         }
     }
 }
+function validateWorkInvocationAnchor(requiredCapabilities, refsByKey, filePath) {
+    const hasRequiredCapability = requiredCapabilities.length > 0;
+    const hasDependencyRef = Object.values(refsByKey).some((values) => values.length > 0);
+    if (hasRequiredCapability || hasDependencyRef) {
+        return;
+    }
+    throw formatError(filePath, "WORK.md must include at least one required_capabilities entry or dependency ref in skill_refs, tool_refs, model_refs, wasm_component_refs, runtime_image_refs, or subagent_refs");
+}
 function validatePortableOrUriRefs(values, key, filePath) {
     for (const [index, value] of values.entries()) {
         if (!(0, refs_1.validatePortableOrUriRef)(value)) {
@@ -315,6 +365,11 @@ function validateHashRefs(values, key, filePath) {
         }
     }
 }
+function validateHashRef(value, key, filePath) {
+    if (!(0, refs_1.isSha256Ref)(value)) {
+        throw formatError(filePath, `${key} must be sha256:<64 lowercase hex chars>`);
+    }
+}
 function validateRelativeMarkdownPaths(values, key, basename, filePath) {
     for (const [index, value] of values.entries()) {
         if (path_1.default.isAbsolute(value) || value.split(/[\\/]/).includes("..")) {
@@ -344,6 +399,10 @@ function validateAgentFrontmatter(type, frontmatter, filePath) {
     requireSemver(version, "version", filePath);
     switch (type) {
         case "spec": {
+            const specKind = optionalString(frontmatter, "spec_kind", filePath);
+            if (specKind) {
+                validateSpecKind(specKind, filePath);
+            }
             const role = expectString(frontmatter, "role", filePath);
             requireEnum(role, "role", ROLE_VALUES, filePath);
             const runtimeMode = expectString(frontmatter, "runtime_mode", filePath);
@@ -371,13 +430,28 @@ function validateAgentFrontmatter(type, frontmatter, filePath) {
             requireLowerToken(kind, "kind", filePath);
             const pricingModel = expectString(frontmatter, "pricing_model", filePath);
             requireEnum(pricingModel, "pricing_model", PRICING_MODEL_VALUES, filePath);
-            validateCapabilities(expectList(frontmatter, "required_capabilities", filePath), "required_capabilities", filePath);
-            validatePortableRefs(optionalList(frontmatter, "skill_refs", filePath), "skill_refs", filePath);
-            validatePortableRefs(optionalList(frontmatter, "tool_refs", filePath), "tool_refs", filePath);
-            validatePortableRefs(optionalList(frontmatter, "model_refs", filePath), "model_refs", filePath);
-            validatePortableRefs(optionalList(frontmatter, "wasm_component_refs", filePath), "wasm_component_refs", filePath);
-            validatePortableRefs(optionalList(frontmatter, "runtime_image_refs", filePath), "runtime_image_refs", filePath);
-            validatePortableRefs(optionalList(frontmatter, "subagent_refs", filePath), "subagent_refs", filePath);
+            const requiredCapabilities = expectList(frontmatter, "required_capabilities", filePath);
+            validateCapabilities(requiredCapabilities, "required_capabilities", filePath);
+            const skillRefs = optionalList(frontmatter, "skill_refs", filePath);
+            validatePortableRefs(skillRefs, "skill_refs", filePath);
+            const toolRefs = optionalList(frontmatter, "tool_refs", filePath);
+            validatePortableRefs(toolRefs, "tool_refs", filePath);
+            const modelRefs = optionalList(frontmatter, "model_refs", filePath);
+            validatePortableRefs(modelRefs, "model_refs", filePath);
+            const wasmComponentRefs = optionalList(frontmatter, "wasm_component_refs", filePath);
+            validatePortableRefs(wasmComponentRefs, "wasm_component_refs", filePath);
+            const runtimeImageRefs = optionalList(frontmatter, "runtime_image_refs", filePath);
+            validatePortableRefs(runtimeImageRefs, "runtime_image_refs", filePath);
+            const subagentRefs = optionalList(frontmatter, "subagent_refs", filePath);
+            validatePortableRefs(subagentRefs, "subagent_refs", filePath);
+            validateWorkInvocationAnchor(requiredCapabilities, {
+                skill_refs: skillRefs,
+                tool_refs: toolRefs,
+                model_refs: modelRefs,
+                wasm_component_refs: wasmComponentRefs,
+                runtime_image_refs: runtimeImageRefs,
+                subagent_refs: subagentRefs,
+            }, filePath);
             validateFieldDescriptors(expectList(frontmatter, "inputs", filePath), "inputs", filePath);
             validateFieldDescriptors(expectList(frontmatter, "outputs", filePath), "outputs", filePath);
             expectBoolean(frontmatter, "receipt_required", filePath);
@@ -396,7 +470,16 @@ function validateAgentFrontmatter(type, frontmatter, filePath) {
             if (requestRef) {
                 validatePortableOrUriScalar(requestRef, "request_ref", filePath);
             }
+            const triggerRef = optionalRefString(frontmatter, "trigger_ref", filePath);
+            if (triggerRef) {
+                validatePortableOrUriScalar(triggerRef, "trigger_ref", filePath);
+            }
+            const payloadHash = optionalString(frontmatter, "payload_hash", filePath);
+            if (payloadHash) {
+                validateHashRef(payloadHash, "payload_hash", filePath);
+            }
             validatePortableOrUriRefs(optionalList(frontmatter, "input_refs", filePath), "input_refs", filePath);
+            validatePortableOrUriRefs(optionalList(frontmatter, "queue_refs", filePath), "queue_refs", filePath);
             validateOptionalFieldDescriptors(optionalList(frontmatter, "requested_outputs", filePath), "requested_outputs", filePath);
             validatePortableOrUriRefs(optionalList(frontmatter, "constraint_refs", filePath), "constraint_refs", filePath);
             const artifactPolicy = optionalString(frontmatter, "artifact_policy", filePath);
@@ -416,8 +499,13 @@ function validateAgentFrontmatter(type, frontmatter, filePath) {
             if (costRef) {
                 validatePortableOrUriScalar(costRef, "cost_ref", filePath);
             }
+            const redactionPolicy = optionalString(frontmatter, "redaction_policy", filePath);
+            if (redactionPolicy) {
+                requireEnum(redactionPolicy, "redaction_policy", REDACTION_POLICY_VALUES, filePath);
+            }
             validatePortableOrUriRefs(optionalList(frontmatter, "proof_refs", filePath), "proof_refs", filePath);
             validatePortableOrUriRefs(optionalList(frontmatter, "attestation_refs", filePath), "attestation_refs", filePath);
+            validateHashRefs(optionalList(frontmatter, "evidence_hashes", filePath), "evidence_hashes", filePath);
             validateHashRefs(optionalList(frontmatter, "input_hashes", filePath), "input_hashes", filePath);
             validateHashRefs(optionalList(frontmatter, "output_hashes", filePath), "output_hashes", filePath);
             break;

package/dist/graph/capabilities_indexer.js

@@ -74,7 +74,92 @@ function pickAttributes(attributes, keys) {
     }
     return picked;
 }
-function nodeCapabilityRecord(root, config, node, kind, indexedAt) {
+function toStringList(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((item) => typeof item === "string");
+}
+function nodeRefSet(node) {
+    return new Set([node.id, node.qid, `${node.ws}:${node.id}`]);
+}
+function sortedNodes(nodes) {
+    return [...nodes].sort((a, b) => a.qid.localeCompare(b.qid));
+}
+function resolveSpecWorkContracts(index, specNode) {
+    const candidates = new Map();
+    const specDir = path_1.default.posix.dirname(specNode.path);
+    for (const contractPath of toStringList(specNode.attributes.work_contracts)) {
+        const normalizedPath = path_1.default.posix.normalize(path_1.default.posix.join(specDir, contractPath));
+        for (const node of Object.values(index.nodes)) {
+            if (node.type === "work" && node.ws === specNode.ws && node.path === normalizedPath) {
+                candidates.set(node.qid, node);
+            }
+        }
+    }
+    for (const qid of specNode.edges.relates) {
+        const node = index.nodes[qid];
+        if (node?.type === "work") {
+            candidates.set(node.qid, node);
+        }
+    }
+    for (const qid of index.reverse_edges.relates?.[specNode.qid] ?? []) {
+        const node = index.nodes[qid];
+        if (node?.type === "work") {
+            candidates.set(node.qid, node);
+        }
+    }
+    return sortedNodes(candidates.values());
+}
+function resolveWorkSpecs(index, workNode) {
+    const candidates = new Map();
+    const workRefs = nodeRefSet(workNode);
+    for (const node of Object.values(index.nodes)) {
+        if (node.type !== "spec" || node.ws !== workNode.ws) {
+            continue;
+        }
+        const agentId = typeof workNode.attributes.agent_id === "string" ? workNode.attributes.agent_id : undefined;
+        if (agentId && nodeRefSet(node).has(agentId)) {
+            candidates.set(node.qid, node);
+        }
+        if (resolveSpecWorkContracts(index, node).some((contract) => contract.qid === workNode.qid)) {
+            candidates.set(node.qid, node);
+        }
+        if (node.edges.relates.some((qid) => workRefs.has(qid))) {
+            candidates.set(node.qid, node);
+        }
+    }
+    return sortedNodes(candidates.values());
+}
+function resolveWorkOrders(index, workNode) {
+    const workRefs = nodeRefSet(workNode);
+    return sortedNodes(Object.values(index.nodes).filter((node) => node.type === "work_order" && workRefs.has(String(node.attributes.work_id ?? ""))));
+}
+function resolveReceiptsForOrders(index, orderNodes) {
+    const orderRefs = new Set();
+    for (const order of orderNodes) {
+        for (const ref of nodeRefSet(order)) {
+            orderRefs.add(ref);
+        }
+    }
+    return sortedNodes(Object.values(index.nodes).filter((node) => node.type === "receipt" && orderRefs.has(String(node.attributes.work_order_id ?? ""))));
+}
+function buildCapabilityLinkage(index, node, kind) {
+    if (kind !== "spec" && kind !== "work") {
+        return undefined;
+    }
+    const workContracts = kind === "spec" ? resolveSpecWorkContracts(index, node) : [node];
+    const specNodes = kind === "work" ? resolveWorkSpecs(index, node) : [];
+    const workOrders = workContracts.flatMap((workNode) => resolveWorkOrders(index, workNode));
+    const receipts = resolveReceiptsForOrders(index, workOrders);
+    return {
+        spec_qids: specNodes.map((specNode) => specNode.qid),
+        work_contract_qids: workContracts.map((workNode) => workNode.qid),
+        work_order_qids: workOrders.map((orderNode) => orderNode.qid),
+        receipt_qids: receipts.map((receiptNode) => receiptNode.qid),
+    };
+}
+function nodeCapabilityRecord(root, config, index, node, kind, indexedAt) {
     const absolutePath = path_1.default.resolve(root, node.path);
     const content = fs_1.default.readFileSync(absolutePath, "utf8");
     const record = {
@@ -99,6 +184,7 @@ function nodeCapabilityRecord(root, config, node, kind, indexedAt) {
     if (kind === "spec") {
         record.spec = pickAttributes(node.attributes, [
             "version",
+            "spec_kind",
             "role",
             "runtime_mode",
             "work_contracts",
@@ -131,6 +217,7 @@ function nodeCapabilityRecord(root, config, node, kind, indexedAt) {
             "receipt_required",
         ]);
     }
+    record.linkage = buildCapabilityLinkage(index, node, kind);
     return record;
 }
 function skillCapabilityRecord(root, config, skill, indexedAt) {
@@ -210,7 +297,7 @@ function buildCapabilitiesIndex(root, config, nodeIndex) {
         if (!kind) {
             continue;
         }
-        records.push(nodeCapabilityRecord(root, config, node, kind, generatedAt));
+        records.push(nodeCapabilityRecord(root, config, index, node, kind, generatedAt));
     }
     records.push(...buildWorkspaceSkillCapabilities(root, config, generatedAt));
     const sortedRecords = sortRecords(records);

package/dist/graph/frontmatter.js

@@ -24,6 +24,7 @@ exports.DEFAULT_FRONTMATTER_KEY_ORDER = [
     "next",
     "supersedes",
     "version",
+    "spec_kind",
     "role",
     "runtime_mode",
     "work_contracts",
@@ -42,10 +43,14 @@ exports.DEFAULT_FRONTMATTER_KEY_ORDER = [
     "requester",
     "order_status",
     "request_ref",
+    "trigger_ref",
+    "payload_hash",
+    "queue_refs",
     "work_order_id",
     "receipt_status",
     "outcome",
     "cost_ref",
+    "redaction_policy",
     "target_id",
     "sentiment",
     "feedback_status",
@@ -73,6 +78,7 @@ exports.DEFAULT_FRONTMATTER_KEY_ORDER = [
     "artifact_policy",
     "proof_refs",
     "attestation_refs",
+    "evidence_hashes",
     "input_hashes",
     "output_hashes",
     "tags",

package/dist/graph/node.js

@@ -226,14 +226,20 @@ function requireTemplateSchema(type, templateSchemas, filePath) {
     }
     return schema;
 }
+const OPTIONAL_COMPAT_TEMPLATE_KEYS = {
+    spec: {
+        spec_kind: "scalar",
+    },
+};
 function validateTemplateKeys(frontmatter, schema, filePath) {
     for (const key of Object.keys(frontmatter)) {
-        if (!schema.allowedKeys.has(key)) {
+        if (!schema.allowedKeys.has(key) &&
+            OPTIONAL_COMPAT_TEMPLATE_KEYS[schema.type]?.[key] === undefined) {
             throw formatError(filePath, `unknown key: ${key}`);
         }
     }
     for (const [key, value] of Object.entries(frontmatter)) {
-        const expected = schema.keyKinds[key];
+        const expected = schema.keyKinds[key] ?? OPTIONAL_COMPAT_TEMPLATE_KEYS[schema.type]?.[key];
         if (!expected) {
             continue;
         }

package/dist/init/AGENT_START.md

@@ -30,6 +30,7 @@ Agent operating prompt:
 - Record skill improvement candidates during normal goal execution; edit `SKILL.md` only when the active node is explicit skill-maintenance work.
 - Use `mdkg skill list`, `mdkg skill search`, and `mdkg skill show <slug>` for skill discovery.
 - Use `mdkg capability list/search/show` for deterministic skills, `SPEC.md`, `WORK.md`, core-doc, and design-doc capability discovery.
+- Use `mdkg spec list/show/validate` for focused optional `SPEC.md` capability records.
 - Use `mdkg index` to refresh JSON compatibility caches and `.mdkg/index/mdkg.sqlite` when SQLite mode is enabled.
 - Treat `.mdkg/db` as project application state; use `mdkg db init` to create
   the generic scaffold and enable `db.enabled` without creating an active
@@ -50,7 +51,7 @@ Agent operating prompt:
   `.mdkg/db/runtime/` and WAL/SHM/journal/lock/temp files ignored unless a
   sealed artifact policy explicitly says otherwise.
 - Use `mdkg archive add/list/show/verify/compress` for committed source and artifact sidecars under `.mdkg/archive`.
-- Use `mdkg work ...` helpers for semantic mirror contracts, work orders, receipts, and artifact registration.
+- Use `mdkg work ...` helpers for semantic mirror contracts, deterministic triggers, work order status, receipt verification, and artifact registration.
 - Treat work contracts, orders, and receipts as committed semantic mirrors only; never store raw secrets, credentials, live payment state, ledger mutations, or canonical marketplace state in mdkg.
 - Use `artifact://...` for external/runtime-managed artifacts and `archive://...` for committed mdkg archive sidecars.
 - Use `mdkg bundle create/list/show/verify` for explicit full `.mdkg` graph snapshot bundles.
@@ -107,6 +108,9 @@ Capability discovery:
 - `mdkg capability list --kind skill --json`
 - `mdkg capability search "<query>" --kind spec --json`
 - `mdkg capability search "<query>" --kind work --json`
+- `mdkg spec list --json`
+- `mdkg spec show <id-or-qid-or-alias> --json`
+- `mdkg spec validate <id-or-qid-or-alias> --json`
 
 Conventions:
 - `AGENTS.md` is the Codex/OpenAI-oriented wrapper doc.

package/dist/init/CLI_COMMAND_MATRIX.md

@@ -6,6 +6,9 @@ Verify live help with:
 - `mdkg --help`
 - `mdkg help <command>`
 
+Optional reusable SPEC capability records are accessed through `mdkg spec ...`.
+Repos without SPEC files remain valid.
+
 Primary commands:
 - `mdkg init`
 - `mdkg upgrade [--dry-run] [--apply] [--json]`
@@ -16,12 +19,22 @@ Primary commands:
 - `mdkg pack`
 - `mdkg skill`
 - `mdkg capability`
+- `mdkg spec`
 - `mdkg archive`
 - `mdkg bundle`
 - `mdkg work`
 - `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`
@@ -143,8 +156,19 @@ Capability discovery:
 - `mdkg capability resolve [query] [--requires <capability>] [--fresh-only] [--json]`
 - 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
 
+Spec capability records:
+- `mdkg spec list [--json]`
+- `mdkg spec show <id-or-qid-or-alias> [--json]`
+- `mdkg spec validate [<id-or-qid-or-alias>] [--json]`
+- `SPEC.md` is optional; repos with no SPEC files still validate
+- SPEC records describe reusable capability surfaces, not general planning notes
+- `mdkg spec validate` with no ref validates the graph and all optional SPEC records
+- `mdkg spec validate <ref>` also checks that the target SPEC reference exists
+- `mdkg spec ...` is the focused SPEC command family; `mdkg capability ...` remains broader skill/spec/work/core/design discovery
+
 Archive sidecars:
 - `mdkg archive add <file> [--id <archive.id>] [--kind source|artifact] [--visibility private|internal|public] [--title <title>] [--refs <...>] [--relates <...>] [--json]`
 - `mdkg archive list [--kind source|artifact] [--visibility private|internal|public] [--ws <alias>] [--json]`
@@ -178,21 +202,33 @@ 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
 
 Work semantic mirrors:
 - `mdkg work contract new "<title>" --id <work.id> --agent-id <agent.id> --kind <kind> --inputs <...> --outputs <...> [--required-capabilities <...>] [--pricing-model <...>] [--json]`
+- `mdkg work trigger <work-or-capability-ref> [--id <order.id>] [--title "<title>"] [--requester <ref>] [--enqueue <queue>] [--json]`
 - `mdkg work order new "<title>" --id <order.id> --work-id <work.id> --requester <ref> [--request-ref <ref>] [--input-refs <...>] [--requested-outputs <...>] [--json]`
+- `mdkg work order status <id-or-qid> [--json]`
 - `mdkg work order update <id-or-qid> [--status <status>] [--add-input-refs <...>] [--add-artifacts <...>] [--json]`
 - `mdkg work receipt new "<title>" --id <receipt.id> --work-order-id <order.id> --outcome success|partial|failure [--receipt-status recorded|verified|rejected|superseded] [--json]`
+- `mdkg work receipt verify <id-or-qid> [--json]`
 - `mdkg work receipt update <id-or-qid> [--receipt-status <status>] [--add-artifacts <...>] [--add-proof-refs <...>] [--add-attestation-refs <...>] [--json]`
 - `mdkg work artifact add <order-or-receipt-id-or-qid> <file> [--id <archive.id>] [--kind source|artifact] [--json]`
+- `work trigger` accepts a `WORK.md` ref directly or a `SPEC.md` capability ref with exactly one resolvable work contract; it creates a submitted order mirror and never executes work
+- example: `mdkg work trigger work.example --id order.example-1 --requester user://example --json`
+- `work trigger --enqueue <queue>` requires a valid project DB plus an explicitly created active queue, creates a submitted order mirror, and enqueues a local delivery message without executing work
+- `work order status` is read-only and reports deterministic order state plus linked receipts
+- `work receipt verify` is read-only and reports linkage, evidence, archive ref, hash, outcome, and redaction-policy checks
 - work commands mutate mdkg semantic mirror files only; production order, receipt, feedback, dispute, payment, ledger, marketplace inventory, fulfillment, and execution state remains canonical outside mdkg
 - do not store raw secrets, credentials, live payment state, ledger mutations, or canonical marketplace state in work mirrors
 - `artifact://...` refs identify external/runtime-managed artifacts; `archive://...` refs identify committed mdkg archive sidecars

package/dist/init/README.md

@@ -25,13 +25,26 @@ mdkg search "..."
 mdkg show <id>
 mdkg pack <id>
 mdkg capability search "..."
+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 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, `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 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:
 
@@ -40,6 +53,12 @@ mdkg new spec "image worker" --id agent.image-worker
 mdkg new work "generate image" --id work.generate-image
 ```
 
+`SPEC.md` is optional. Repos without SPEC files still validate. When present,
+SPEC records describe reusable capability surfaces rather than general planning
+notes. `mdkg spec list/show/validate` is the focused SPEC command family, while
+`mdkg capability ...` remains the broader read-only discovery surface for
+skills, SPECs, WORK contracts, core docs, and design docs.
+
 Read `AGENT_START.md` first when this repo includes it.
 
 ## Pack Profiles
@@ -123,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.
@@ -146,13 +169,29 @@ Use work lifecycle helpers for semantic mirrors only:
 
 ```bash
 mdkg work contract new "example capability" --id work.example --agent-id agent.example --kind example --inputs prompt:text:required --outputs result:text:required
-mdkg work order new "example request" --id order.example-1 --work-id work.example --requester user://example
+mdkg work trigger work.example --id order.example-1 --requester user://example
+mdkg work order status order.example-1 --json
 mdkg work receipt new "example receipt" --id receipt.example-1 --work-order-id order.example-1 --outcome success
+mdkg work receipt verify receipt.example-1 --json
+```
+
+Create a manual order instead of a trigger-created order when you need to supply
+input refs at order creation time:
+
+```bash
+mdkg work order new "example request" --id order.example-manual --work-id work.example --requester user://example --input-refs archive://archive.example
 ```
 
 Receipt statuses are `recorded`, `verified`, `rejected`, and `superseded`.
 Update and artifact commands accept local ids or local qids; subgraph qids are read-only and must be changed in their source workspace.
 
+`mdkg work trigger` creates a deterministic submitted `WORK_ORDER.md` from a
+WORK contract or a SPEC with exactly one resolvable work contract. `mdkg work
+order status` and `mdkg work receipt verify` are read-only review helpers.
+`mdkg work trigger --enqueue <queue>` optionally writes a local project DB queue
+delivery message after the queue has been explicitly created and is active; it
+still does not execute work.
+
 Production orders, receipts, feedback, disputes, payments, ledgers, marketplace inventory, fulfillment records, and execution state remain canonical outside mdkg. mdkg stores committed semantic mirrors and reviewable evidence. Do not store raw secrets, credentials, live payment state, ledger mutations, canonical marketplace state, or bulky raw payloads in these mirrors.
 
 Use `artifact://...` for external or runtime-managed artifact identities. Use `archive://...` only for committed mdkg archive sidecars.