mdkg 0.1.10 → 0.3.0

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,25 +30,28 @@ 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
   runtime SQLite database. Use `mdkg db migrate` after init to create or update
-  the runtime SQLite database with mdkg-owned foundation plus internal local
-  node:sqlite queue, event/receipt/reducer, and writer lease/CAS foundation
-  migrations. Queue state is delivery infrastructure, not canonical event
-  history. Event rows are durable local project DB history; receipts, reducers,
-  writer leases, and materializers are internal local helper surfaces, and there
-  is no public `mdkg db queue`, `mdkg db event`, `mdkg db reducer`,
-  `mdkg db lease`, or `mdkg db materializer` CLI yet. Use `mdkg db verify` and `mdkg db stats` for
+  the runtime SQLite database with mdkg-owned foundation plus public local
+  node:sqlite queue delivery, internal event/receipt/reducer, writer lease/CAS,
+  and queue control migrations. Queue state is delivery infrastructure, not
+  canonical event history; use `mdkg db queue ...` to create, pause, enqueue,
+  claim, settle, inspect, and drain local queues. Event rows are durable local
+  project DB history; receipts, reducers, writer leases, and materializers are
+  internal local helper surfaces, with no public `mdkg db event`,
+  `mdkg db reducer`, `mdkg db lease`, or `mdkg db materializer` CLI yet. Use `mdkg db verify` and `mdkg db stats` for
   non-mutating health and summary receipts. Use `mdkg db snapshot seal` for
-  explicit sealed checkpoints,
+  explicit sealed checkpoints; default queue policy is drain, and
+  `--queue-policy paused` is only for intentionally paused queues,
   `mdkg db snapshot verify/status` for checkpoint health, and
   `mdkg db snapshot dump/diff` for deterministic review aids. Keep
   `.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.
@@ -105,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`
@@ -39,7 +43,8 @@ Project database commands:
 - `mdkg db migrate [--json]`
 - `mdkg db verify [--json]`
 - `mdkg db stats [--json]`
-- `mdkg db snapshot seal [--json]`
+- `mdkg db queue create|pause|resume|enqueue|claim|ack|fail|dead-letter|release-expired|stats|list|show ... [--json]`
+- `mdkg db snapshot seal [--queue-policy drain|paused] [--json]`
 - `mdkg db snapshot verify [--json]`
 - `mdkg db snapshot status [--json]`
 - `mdkg db snapshot dump [--snapshot <path>] [--output <path>] [--json]`
@@ -53,8 +58,10 @@ Project database commands:
   queue, event/receipt/reducer, and writer lease/CAS foundation migrations
 - `mdkg db migrate` records migration order, checksums, and applied timestamps
   in the configured migration table
-- queue tables are durable local delivery state, not canonical event history;
-  there is no public `mdkg db queue` CLI yet
+- `mdkg db queue ...` exposes durable local delivery operations backed by
+  node:sqlite; queue rows are delivery state, not canonical event history
+- paused queues reject enqueue and claim, but ack/fail/dead-letter and
+  release-expired remain available so leased work can settle
 - event tables are durable local history for project DB state transitions;
   receipts, typed reducers, writer leases, and materializers remain internal
   helper surfaces in this release, with no public `mdkg db event`,
@@ -64,8 +71,10 @@ Project database commands:
 - `mdkg db stats` reports table counts, database size, migration state,
   transient runtime files, receipt-file count, and state snapshot presence
 - `mdkg db snapshot seal` writes an opt-in sealed checkpoint and manifest under
-  `.mdkg/db/state`; `snapshot verify/status/dump/diff` inspect and review that
-  checkpoint without treating raw binary diffs as human-readable truth
+  `.mdkg/db/state`; default `--queue-policy drain` requires no ready or leased
+  messages, while `--queue-policy paused` allows ready messages only in paused
+  queues. `snapshot verify/status/dump/diff` inspect and review that checkpoint
+  without treating raw binary diffs as human-readable truth
 - active `.mdkg/db/runtime/` files and `.mdkg/db` WAL/SHM/journal/lock/temp files are ignored by default
 
 Validation commands:
@@ -138,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]`
@@ -183,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
@@ -75,17 +82,19 @@ Fresh mdkg workspaces default to `index.backend: sqlite`; `.mdkg/index/mdkg.sqli
 `.mdkg/index`. Run `mdkg db init` to create the generic scaffold, write
 `.mdkg/db/project-db.json`, and enable `db.enabled`; it does not create an
 active runtime SQLite database. Run `mdkg db migrate` after init to create or
-update the active runtime SQLite database with mdkg-owned foundation plus
-internal local node:sqlite queue, event/receipt/reducer, and writer lease/CAS
-foundation migrations. Queue state is delivery infrastructure, not canonical
-event history. Event rows are durable local project DB history; receipts,
-reducers, writer leases, and materializers are internal local helper surfaces,
-and there is no public `mdkg db queue`, `mdkg db event`, `mdkg db reducer`,
-`mdkg db lease`, or `mdkg db materializer` CLI yet. Use `mdkg db verify` for non-mutating health checks and
+update the active runtime SQLite database with mdkg-owned foundation plus public
+local node:sqlite queue delivery, internal event/receipt/reducer, writer
+lease/CAS, and queue control migrations. Queue state is delivery
+infrastructure, not canonical event history; use `mdkg db queue ...` to create,
+pause, enqueue, claim, settle, inspect, and drain local queues. Event rows are
+durable local project DB history; receipts, reducers, writer leases, and
+materializers are internal local helper surfaces, with no public `mdkg db event`,
+`mdkg db reducer`, `mdkg db lease`, or `mdkg db materializer` CLI yet. Use `mdkg db verify` for non-mutating health checks and
 `mdkg db stats` for table counts, DB size, migration state, and receipt-file
 counts. Use `mdkg db snapshot seal` to create an opt-in sealed checkpoint under
-`.mdkg/db/state`, then use `mdkg db snapshot verify/status` for integrity and
-freshness checks. Use `mdkg db snapshot dump/diff` as deterministic review aids
+`.mdkg/db/state`; the default queue policy is drain, and
+`--queue-policy paused` is only for intentionally paused queues. Then use
+`mdkg db snapshot verify/status` for integrity and freshness checks. Use `mdkg db snapshot dump/diff` as deterministic review aids
 for SQLite snapshots. Keep active runtime DB files and transient
 WAL/SHM/journal, lock, and temp files ignored. Commit schema files, manifests,
 receipts, and sealed state snapshots only by explicit repo policy.
@@ -144,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.1.10",
+  "mdkg_version": "0.3.0",
   "files": [
     {
       "path": ".mdkg/config.json",
@@ -61,7 +61,7 @@
     {
       "path": ".mdkg/README.md",
       "category": "mdkg_doc",
-      "sha256": "0b5e7fa852aa71616ac108b2af3fb21b9ab66ee1ea69cb75539ba1df80be1072"
+      "sha256": "353aa7318974d4b3dbdf772ae5a3deb2d41b5d71ea5308d260aab8081121548b"
     },
     {
       "path": ".mdkg/skills/build-pack-and-execute-task/SKILL.md",
@@ -81,7 +81,7 @@
     {
       "path": ".mdkg/skills/verify-close-and-checkpoint/SKILL.md",
       "category": "default_skill",
-      "sha256": "f85ffa4a139db10c3bc3203cde0e4f41603fbc7f3925e6fdaba821346ffa28b8"
+      "sha256": "3e4137b7b6a71f088dee79b5ee2f4743aefa3b43adae07337307db89a24416b6"
     },
     {
       "path": ".mdkg/templates/default/archive.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,17 +176,72 @@
     {
       "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",
+      "category": "template",
+      "sha256": "08a1bd65297173a1dc9df95776775d406337a419d4bc51863593b6f28777ebdb"
+    },
+    {
+      "path": ".mdkg/templates/specs/agent.SPEC.md",
+      "category": "template",
+      "sha256": "dab10c0ed12aa10a752ee3bd61f263065644826eb950c71a9e3458673edb0ca5"
+    },
+    {
+      "path": ".mdkg/templates/specs/api.SPEC.md",
+      "category": "template",
+      "sha256": "aee86cadcca31a5a015d7e15ad7503c4aa30f2af0079ec03f857b82b3ecbae59"
+    },
+    {
+      "path": ".mdkg/templates/specs/base.SPEC.md",
+      "category": "template",
+      "sha256": "6d4171fac00c2f3d8f2a2ac746b8a47c59aaecebe224c3a0046dd6e6974a1d08"
+    },
+    {
+      "path": ".mdkg/templates/specs/capability.SPEC.md",
+      "category": "template",
+      "sha256": "68a91e8bbd80d1ff1972e4c31e29f26451d5a1be1d25d414170fdd670010066f"
+    },
+    {
+      "path": ".mdkg/templates/specs/integration.SPEC.md",
+      "category": "template",
+      "sha256": "e907ce6ebc1fa5a455e31e39036e3f8699dccb3d9e45288c8ea025eaec4ca4a2"
+    },
+    {
+      "path": ".mdkg/templates/specs/model.SPEC.md",
+      "category": "template",
+      "sha256": "56061a241819dfda4d3022c075f744cf6650f5f52c58cd15b0af9d1f613af4f2"
+    },
+    {
+      "path": ".mdkg/templates/specs/project.SPEC.md",
+      "category": "template",
+      "sha256": "386c41852cbb46e7a6ba583a7b0c4126262a56618d8e214aaa601b68d55818b9"
+    },
+    {
+      "path": ".mdkg/templates/specs/runtime-agent.SPEC.md",
+      "category": "template",
+      "sha256": "53af7c3e172f5ed1297f340aca0be5e53302613d2e6bb9145915067d7b0004c8"
+    },
+    {
+      "path": ".mdkg/templates/specs/runtime-image.SPEC.md",
+      "category": "template",
+      "sha256": "37416b045cd7733d1f5e1cc629ac9b6616024d5fa52f2bdcd90110267151e593"
+    },
+    {
+      "path": ".mdkg/templates/specs/tool.SPEC.md",
+      "category": "template",
+      "sha256": "05b827bbce4f721ea25beda62850688aff3db644aec65e71b9cf76cad8e5f46f"
     },
     {
       "path": "AGENT_START.md",
       "category": "startup_doc",
-      "sha256": "1e9def4cf02de6eecd164cff7855829dc3632009a2aa801eccb67b89bad4a570"
+      "sha256": "cf58e37c72be2593f1d920520dbdc6e316182bfda5c49837443a8b18024504c7"
     },
     {
       "path": "AGENTS.md",
@@ -201,7 +256,7 @@
     {
       "path": "CLI_COMMAND_MATRIX.md",
       "category": "startup_doc",
-      "sha256": "95bc386d88817ca597ae4f0fe4fa2d904843227a81147d606f54a32b93694c83"
+      "sha256": "48c1b7fbef3a01faf5ddf8bb232b19362b49ef2a371a7c38ae11302c8b3bccac"
     },
     {
       "path": "llms.txt",

package/dist/init/skills/default/verify-close-and-checkpoint/SKILL.md

@@ -46,13 +46,14 @@ Finish work with evidence, validation, and minimal memory drift.
 Use this local repo-only checklist before publishing mdkg:
 
 1. Confirm package intent and version in `package.json`, `package-lock.json`, `README.md`, `CLI_COMMAND_MATRIX.md`, and `CHANGELOG.md`.
-2. Use a clean npm cache: `export NPM_CONFIG_CACHE=/private/tmp/mdkg-npm-cache`.
-3. Run `npm ci`, `npm run build`, `node scripts/assert-publish-ready.js`, `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:archive-work`, `npm run smoke:bundle`, `npm run smoke:subgraph`, and `npm run smoke:visibility`.
-4. Run `npm pack --dry-run --json` and confirm the tarball includes `dist/cli.js`, compiled folders, `dist/init/`, release docs, and `scripts/postinstall.js`.
-5. Confirm registry state with `npm view mdkg version --registry=https://registry.npmjs.org/`.
-6. Publish only after the registry still shows the previous version and npm auth is known to have write access.
-7. If publishing fails with 2FA or token policy errors, do not commit; fix npm auth or package policy, then rerun publish.
-8. After successful publish, verify `npm view mdkg version` and `npm view mdkg dist-tags`, then commit the release changes.
+2. Confirm release-line intent before bumping: when a change crosses a capability-track boundary, prefer the next minor release line over patch-style continuation. For the current project DB track, follow `0.1.9 -> 0.2.0` rather than naming the next planned source line `0.1.10`.
+3. Use a clean npm cache: `export NPM_CONFIG_CACHE=/private/tmp/mdkg-npm-cache`.
+4. Run `npm ci`, `npm run build`, `node scripts/assert-publish-ready.js`, `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:archive-work`, `npm run smoke:bundle`, `npm run smoke:subgraph`, and `npm run smoke:visibility`.
+5. Run `npm pack --dry-run --json` and confirm the tarball includes `dist/cli.js`, compiled folders, `dist/init/`, release docs, and `scripts/postinstall.js`.
+6. Confirm registry state with `npm view mdkg version --registry=https://registry.npmjs.org/`.
+7. Publish only after the registry still shows the previous version and npm auth is known to have write access.
+8. If publishing fails with 2FA or token policy errors, do not commit; fix npm auth or package policy, then rerun publish.
+9. After successful publish, verify `npm view mdkg version` and `npm view mdkg dist-tags`, then commit the release changes.
 
 ## Bundle-Aware Commit Gate
 

package/dist/init/templates/default/receipt.md

@@ -7,8 +7,10 @@ work_order_id: order.example
 receipt_status: recorded
 outcome: success
 cost_ref: cost.redacted
+redaction_policy: refs_and_hashes_only
 proof_refs: []
 attestation_refs: []
+evidence_hashes: []
 input_hashes: []
 output_hashes: []
 tags: []
@@ -38,7 +40,16 @@ archive sidecars.
 
 # Proof
 
-Record non-secret proof, attestation, and hash references.
+Record non-secret proof, attestation, and hash references. `evidence_hashes`
+can hash receipt evidence bundles or redacted proof summaries that are not
+stored directly in this file.
+
+# Redaction
+
+`redaction_policy` records how this mirror avoids raw secrets and canonical
+runtime state. Use refs, hashes, archive refs, artifact refs, and redacted
+summaries instead of credentials, auth headers, live payment state, ledger
+mutations, marketplace inventory, or production runtime state.
 
 # Notes
 

package/dist/init/templates/default/spec.md

@@ -3,8 +3,9 @@ id: {{id}}
 type: spec
 title: {{title}}
 version: 0.1.0
-role: subagent
-runtime_mode: room_orchestrated
+spec_kind: capability
+role: tool_service
+runtime_mode: tool_service
 work_contracts: []
 requested_capabilities: []
 skill_refs: []
@@ -13,7 +14,7 @@ model_refs: []
 wasm_component_refs: []
 runtime_image_refs: []
 subagent_refs: []
-resource_profile: builder
+resource_profile: local_cli
 update_policy: manual
 tags: []
 owners: []
@@ -28,11 +29,11 @@ updated: {{updated}}
 
 # Purpose
 
-Define the agent, package, or runtime specification.
+Define the reusable capability surface.
 
 # Runtime
 
-Describe role, runtime mode, resource profile, and update policy.
+Describe the role, runtime mode, resource profile, and update policy.
 
 # Work Contracts
 
@@ -40,4 +41,5 @@ List related WORK.md contracts.
 
 # Capabilities
 
-List requested capabilities and relevant constraints.
+List requested capabilities and the authority/resource constraints that govern
+use.

package/dist/init/templates/default/work.md

@@ -6,7 +6,7 @@ version: 0.1.0
 agent_id: agent.example
 kind: generic
 pricing_model: quoted
-required_capabilities: []
+required_capabilities: [capability.example]
 skill_refs: []
 tool_refs: []
 model_refs: []
@@ -31,6 +31,10 @@ updated: {{updated}}
 
 Describe the reusable capability contract.
 
+Replace `capability.example` with at least one concrete required capability or
+add an explicit dependency ref such as `skill_refs`, `tool_refs`, `model_refs`,
+`wasm_component_refs`, `runtime_image_refs`, or `subagent_refs`.
+
 This file is a semantic mirror for discovery and review. Do not store raw
 secrets, credentials, live payment state, ledger mutations, marketplace
 inventory, or canonical execution state here.

package/dist/init/templates/default/work_order.md

@@ -8,7 +8,10 @@ work_version: 0.1.0
 requester: user.example
 order_status: submitted
 request_ref: request.example
+trigger_ref: trigger.manual
+payload_hash: sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
 input_refs: []
+queue_refs: []
 requested_outputs: [result:text:required]
 constraint_refs: []
 artifact_policy: commit_sidecar_and_zip
@@ -27,6 +30,9 @@ updated: {{updated}}
 
 Capture the concrete request against a WORK.md version.
 
+`payload_hash` should be the stable sha256 of the redacted trigger payload or
+request mirror used to create this order.
+
 This file is a committed semantic mirror, not the canonical execution database.
 Do not store raw secrets, credentials, live payment state, ledger mutations,
 marketplace inventory, or bulky payloads here.
@@ -37,6 +43,11 @@ Record committed input references without secrets. Use `archive://...` for mdkg
 archive sidecars and `artifact://...` for external or runtime-managed artifact
 identities.
 
+# Queue refs
+
+Queue refs are optional delivery-state pointers. They are not canonical runtime
+state.
+
 # Requested Outputs
 
 Document the output descriptors requested from the work contract.

package/dist/init/templates/skills/base.SKILL.md

@@ -0,0 +1,66 @@
+---
+name: {{skill_slug}}
+description: {{description}}
+tags: [stage:plan, writer:orchestrator]
+version: 0.1.0
+authors: [{{owner}}]
+links: []
+---
+
+# Purpose
+
+Describe the repeatable workflow and the durable outcome this skill produces.
+
+## When To Use
+
+- Trigger condition.
+
+## Inputs
+
+- Required context or artifacts.
+
+## Outputs
+
+- Result, patch, artifact, report, or handoff.
+
+## Required Capabilities
+
+- Capability needed by the worker or orchestrator.
+
+## Resources Touched
+
+- Files, repos, services, or mdkg nodes the skill may inspect or mutate.
+
+## Steps
+
+1. Ground in source and mdkg truth.
+2. Execute the smallest deterministic workflow.
+3. Record evidence.
+
+## Validation Checks
+
+- Command or review gate.
+
+## Closeout Evidence
+
+- Evidence required before work can be considered done.
+
+## Failure Modes
+
+- Known blocker or ambiguity.
+
+## Safety Rules
+
+- No secrets or unrelated broad mutation.
+
+## Related SPECs
+
+- SPEC refs.
+
+## Projection Targets
+
+- Runtime or agent config projections, if any.
+
+## Open Questions
+
+- Question to resolve before implementation.