mdkg 0.2.0 → 0.3.0

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,6 +19,7 @@ Primary commands:
 - `mdkg pack`
 - `mdkg skill`
 - `mdkg capability`
+- `mdkg spec`
 - `mdkg archive`
 - `mdkg bundle`
 - `mdkg work`
@@ -143,8 +147,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]`
@@ -188,11 +203,19 @@ Subgraph orchestration:
 
 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,14 @@ 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 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.
 
 Agent workflow docs can use semantic ids:
 
@@ -40,6 +41,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
@@ -146,13 +153,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.

package/dist/init/init-manifest.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "tool": "mdkg",
-  "mdkg_version": "0.2.0",
+  "mdkg_version": "0.3.0",
   "files": [
     {
       "path": ".mdkg/config.json",
@@ -61,7 +61,7 @@
     {
       "path": ".mdkg/README.md",
       "category": "mdkg_doc",
-      "sha256": "14ba3fa0657a43345ae81631024519955868fa34081b7517cb253b0be96cf163"
+      "sha256": "353aa7318974d4b3dbdf772ae5a3deb2d41b5d71ea5308d260aab8081121548b"
     },
     {
       "path": ".mdkg/skills/build-pack-and-execute-task/SKILL.md",
@@ -151,7 +151,7 @@
     {
       "path": ".mdkg/templates/default/receipt.md",
       "category": "template",
-      "sha256": "f08753cc38e02d73a5df92df58c2d34b0d33749b298eeb31d81aa019c38d43dd"
+      "sha256": "516faf98abe421f154d162b18006c7875f1a0025ac4d35cc16df744c13548d9d"
     },
     {
       "path": ".mdkg/templates/default/rule.md",
@@ -161,7 +161,7 @@
     {
       "path": ".mdkg/templates/default/spec.md",
       "category": "template",
-      "sha256": "e3e05d8d627c478d2757451f61b5a8fda8a75da9885a9261b2f8f5cb8a3a36dc"
+      "sha256": "8c96e0b6dafa65acb83a2d84519e05a7354896aec8991c148650e9ec58196c77"
     },
     {
       "path": ".mdkg/templates/default/task.md",
@@ -176,12 +176,12 @@
     {
       "path": ".mdkg/templates/default/work_order.md",
       "category": "template",
-      "sha256": "6ee6007674f30f88153ce79ed67d8c736b4f0998ceb0c8314a3f2cf9c48ac88c"
+      "sha256": "5fe376413035f2afe406d13491a597f103a2fce29d137951fe55ae042a1082f5"
     },
     {
       "path": ".mdkg/templates/default/work.md",
       "category": "template",
-      "sha256": "9d8b971ded7a587105fb8b14bb79f68b612fa6e1962cf06859bab82e2aee57c7"
+      "sha256": "cfc53d3be1d2c31576448d071a579bc3d5d2f6851755e29c20825f6b6764c0aa"
     },
     {
       "path": ".mdkg/templates/skills/base.SKILL.md",
@@ -191,57 +191,57 @@
     {
       "path": ".mdkg/templates/specs/agent.SPEC.md",
       "category": "template",
-      "sha256": "6facd5a424fa91d23f7df3e357c98ca4d31691410fad024d5bc8ff3781b0f571"
+      "sha256": "dab10c0ed12aa10a752ee3bd61f263065644826eb950c71a9e3458673edb0ca5"
     },
     {
       "path": ".mdkg/templates/specs/api.SPEC.md",
       "category": "template",
-      "sha256": "42f6119478241a3c7dd12a2a25bd03b30d9c2bc60528287136ea044f20b215c4"
+      "sha256": "aee86cadcca31a5a015d7e15ad7503c4aa30f2af0079ec03f857b82b3ecbae59"
     },
     {
       "path": ".mdkg/templates/specs/base.SPEC.md",
       "category": "template",
-      "sha256": "cff1ee53e9369184e2d92194f165f131254d4439bc79bcbbaaae4a13d616c97b"
+      "sha256": "6d4171fac00c2f3d8f2a2ac746b8a47c59aaecebe224c3a0046dd6e6974a1d08"
     },
     {
       "path": ".mdkg/templates/specs/capability.SPEC.md",
       "category": "template",
-      "sha256": "755c24dea04f687da4714d0a12489e1ae36c5f17b838c2e24bb993378a7d9510"
+      "sha256": "68a91e8bbd80d1ff1972e4c31e29f26451d5a1be1d25d414170fdd670010066f"
     },
     {
       "path": ".mdkg/templates/specs/integration.SPEC.md",
       "category": "template",
-      "sha256": "990005a805bc6e6397f03e0de1ca69d536ae9d55719782a3075781289b44b941"
+      "sha256": "e907ce6ebc1fa5a455e31e39036e3f8699dccb3d9e45288c8ea025eaec4ca4a2"
     },
     {
       "path": ".mdkg/templates/specs/model.SPEC.md",
       "category": "template",
-      "sha256": "eb73ed195139cf5655ba70c948aaaa28fc2c85d2db1b6258d703f10e73bf3713"
+      "sha256": "56061a241819dfda4d3022c075f744cf6650f5f52c58cd15b0af9d1f613af4f2"
     },
     {
-      "path": ".mdkg/templates/specs/omniruntime-agent.SPEC.md",
+      "path": ".mdkg/templates/specs/project.SPEC.md",
       "category": "template",
-      "sha256": "343c7c148faae0c2b24364c276ce345757b5725a750cfebeee4cdeb3dde55009"
+      "sha256": "386c41852cbb46e7a6ba583a7b0c4126262a56618d8e214aaa601b68d55818b9"
     },
     {
-      "path": ".mdkg/templates/specs/project.SPEC.md",
+      "path": ".mdkg/templates/specs/runtime-agent.SPEC.md",
       "category": "template",
-      "sha256": "5ade0aa05907b9ec418c41ee051493d8ecc8ad3d45608ab74fc3cbe2974e79a4"
+      "sha256": "53af7c3e172f5ed1297f340aca0be5e53302613d2e6bb9145915067d7b0004c8"
     },
     {
       "path": ".mdkg/templates/specs/runtime-image.SPEC.md",
       "category": "template",
-      "sha256": "24c1b2fb0bd0d63bbce41ee36b43f9edf531b26438bca2706ad1ab556eaabbf0"
+      "sha256": "37416b045cd7733d1f5e1cc629ac9b6616024d5fa52f2bdcd90110267151e593"
     },
     {
       "path": ".mdkg/templates/specs/tool.SPEC.md",
       "category": "template",
-      "sha256": "18340481891bba180dd077d82b86248ede885131fb75675b775ea0c3749ee5c0"
+      "sha256": "05b827bbce4f721ea25beda62850688aff3db644aec65e71b9cf76cad8e5f46f"
     },
     {
       "path": "AGENT_START.md",
       "category": "startup_doc",
-      "sha256": "5948ed5222b2cbce0468191d00287ce5dbc1aaa434640f4daa676afb92d48d4b"
+      "sha256": "cf58e37c72be2593f1d920520dbdc6e316182bfda5c49837443a8b18024504c7"
     },
     {
       "path": "AGENTS.md",
@@ -256,7 +256,7 @@
     {
       "path": "CLI_COMMAND_MATRIX.md",
       "category": "startup_doc",
-      "sha256": "baf9792f0bd50ce44de2dc16babc73f631a1191acff853fdc4caa7d452f50561"
+      "sha256": "48c1b7fbef3a01faf5ddf8bb232b19362b49ef2a371a7c38ae11302c8b3bccac"
     },
     {
       "path": "llms.txt",