mdkg 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -6,7 +6,50 @@ This project follows a pragmatic changelog style inspired by Keep a Changelog. V
 
 mdkg is pre-v1 public alpha software. Command, graph, cache, bundle, and DAL contracts may change quickly while the project converges on a stable v1 surface.
 
-## 0.2.0 - Unreleased
+## 0.3.0 - Unreleased
+
+### Added
+
+- Added optional `SPEC.md` reusable capability records with strict validation
+  for supported `spec_kind` values and diagnostics that reject documentation-only
+  misuse while keeping repos without SPEC files valid.
+- Added focused `mdkg spec list/show/validate` commands for optional SPEC
+  capability discovery alongside the broader `mdkg capability ...` surface.
+- Added a dogfood mdkg CLI `SPEC.md` and linked `WORK.md` contract so the CLI's
+  graph, project DB, skill, and tool capabilities are discoverable through the
+  same capability index used by downstream repos.
+- Added deterministic `mdkg work trigger`, `mdkg work order status`, and
+  `mdkg work receipt verify` helpers for creating submitted work-order mirrors,
+  reviewing order/receipt linkage, and validating receipt evidence without
+  executing work.
+- Added optional `mdkg work trigger --enqueue <queue>` delivery bridging to the
+  public local project DB queue surface. The bridge requires an initialized,
+  migrated, verified DB and an explicitly created active queue, records
+  delivery refs, and still does not execute work.
+- Added read-only SPEC/WORK capability linkage arrays for related specs, work
+  contracts, work orders, and receipts.
+- Added packed `smoke:work-invocation` coverage for trigger-to-order-to-receipt
+  verification plus queue bridge delivery from an installed tarball.
+
+### Changed
+
+- Hardened default SPEC, WORK, WORK_ORDER, and RECEIPT templates with capability
+  metadata, payload hashes, queue refs, evidence hashes, redaction policies, and
+  explicit semantic-mirror boundaries.
+- Updated README, command matrix, help snapshots, init assets, and upgrade
+  smokes for optional SPEC adoption, work invocation helpers, queue bridge
+  behavior, capability linkage, and no-SPEC backward compatibility.
+- Strengthened init and upgrade smokes so fresh workspaces can remain SPEC-free
+  while optional SPEC/WORK templates can be created and validated on demand.
+
+### Security
+
+- Audited templates, docs, dogfood mirrors, and work invocation command paths for
+  no-secret and semantic-mirror boundaries before the 0.3.0 release metadata
+  bump. No raw secret, credential, payment, ledger, or canonical production
+  state values were identified.
+
+## 0.2.0 - 2026-06-06
 
 Release numbering note: future project DB materializer/profile release planning
 should follow `0.1.9 -> 0.2.0` rather than continuing the line as `0.1.10`

package/README.md

@@ -167,8 +167,16 @@ mdkg index
 mdkg capability list --kind skill --json
 mdkg capability search "image worker" --kind work --json
 mdkg capability show <id-or-qid-or-slug> --json
+mdkg spec list --json
+mdkg spec show <id-or-qid-or-alias> --json
 ```
 
+`SPEC.md` is optional. Repos with no 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.
+
 Register source and artifact files as committed archive sidecars:
 
 ```bash
@@ -181,11 +189,20 @@ Create semantic mirror work contracts, orders, receipts, and artifacts:
 
 ```bash
 mdkg work contract new "generate image" --id work.generate-image --agent-id agent.image-worker --kind image_generation --inputs prompt:text:required --outputs image_url:url:required
-mdkg work order new "generate image request" --id order.generate-image-1 --work-id work.generate-image --requester user://example --input-refs archive://archive.key-input-doc
+mdkg work trigger work.generate-image --id order.generate-image-1 --requester user://example
+mdkg work order status order.generate-image-1 --json
 mdkg work receipt new "generate image receipt" --id receipt.generate-image-1 --work-order-id order.generate-image-1 --outcome success --receipt-status recorded
+mdkg work receipt verify receipt.generate-image-1 --json
 mdkg work artifact add receipt.generate-image-1 ./outputs/image.png --id archive.generated-image --kind artifact
 ```
 
+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 "generate image request" --id order.generate-image-manual --work-id work.generate-image --requester user://example --input-refs archive://archive.key-input-doc
+```
+
 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.
 
@@ -254,6 +271,7 @@ These are the commands new users and agents should learn first:
 - `mdkg pack`
 - `mdkg skill`
 - `mdkg capability`
+- `mdkg spec`
 - `mdkg archive`
 - `mdkg work`
 - `mdkg goal`
@@ -326,7 +344,7 @@ mdkg maintains `.mdkg/index/capabilities.json` as a derived access cache for det
 
 The capability cache is not the full graph and is not source of truth. Normal tasks, epics, bugs, tests, feats, and checkpoints remain in the standard graph index. Markdown remains authoritative; deleting the cache is recoverable with `mdkg index` or by running a capability command when auto-reindex is enabled.
 
-Capability records aggregate enabled registered workspaces and include deterministic source metadata such as `workspace`, `visibility`, `kind`, `id`, `qid`, `path`, headings, refs, source hash, and `indexed_at`. Workspace `visibility` also feeds mdkg's export safety checks for public/internal packs and public bundles. This is a CLI safety layer, not secret scanning, body redaction, or a replacement for private git hosting.
+Capability records aggregate enabled registered workspaces and include deterministic source metadata such as `workspace`, `visibility`, `kind`, `id`, `qid`, `path`, headings, refs, source hash, and `indexed_at`. SPEC and WORK records also expose read-only `linkage` arrays when related work contracts, work orders, and receipts exist, so an orchestrator can discover a capability from reusable surface to invocation evidence without loading the full graph. Workspace `visibility` also feeds mdkg's export safety checks for public/internal packs and public bundles. This is a CLI safety layer, not secret scanning, body redaction, or a replacement for private git hosting.
 
 ## Index backends and parallel safety
 
@@ -360,6 +378,9 @@ rows are durable local project DB history; receipts, reducers, writer leases,
 and materializers remain internal helper surfaces in this release, with no
 public `mdkg db event`, `mdkg db reducer`, `mdkg db lease`, or
 `mdkg db materializer` CLI yet.
+`mdkg work trigger --enqueue <queue>` can bridge a submitted work order mirror
+into an explicitly created active project DB queue; it writes local delivery
+state only and never executes work.
 Use `mdkg db verify` for non-mutating health checks over config, layout,
 runtime SQLite integrity, migration metadata, and transient runtime files. Use
 `mdkg db stats` for deterministic table counts, DB size, migration state,
@@ -401,7 +422,7 @@ Use `mdkg new spec|work|work_order|receipt|feedback|dispute|proposal "<title>"`
 
 Relational templates contain editable placeholder refs. `spec` and `work` scaffold as validation-clean standalone docs; `work_order`, `receipt`, `feedback`, `dispute`, and `proposal` need real refs before strict `mdkg validate` passes.
 
-For executable or purchasable capability mirrors, prefer the lifecycle helpers under `mdkg work ...`. They create and update `WORK.md`, `WORK_ORDER.md`, and `RECEIPT.md` semantic mirror files only. Production order state, receipt state, feedback, disputes, payments, ledgers, marketplace inventory, fulfillment records, and execution state remain canonical outside mdkg, such as in Postgres or another application database. Do not store raw secrets, credentials, live payment state, ledger mutations, canonical marketplace state, or bulky raw payloads in these mirrors.
+For executable or purchasable capability mirrors, prefer the lifecycle helpers under `mdkg work ...`. They create and update `WORK.md`, `WORK_ORDER.md`, and `RECEIPT.md` semantic mirror files only. `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 for deterministic closeout. `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 order state, receipt state, feedback, disputes, payments, ledgers, marketplace inventory, fulfillment records, and execution state remain canonical outside mdkg, such as in Postgres or another application database. Do not store raw secrets, credentials, live payment state, ledger mutations, canonical marketplace state, or bulky raw payloads in these mirrors.
 
 ## Archive sidecars
 
@@ -423,6 +444,7 @@ This release includes:
 - root-only published init seed config
 - skills indexing and search/show/list support
 - JSON capability cache for skills, `SPEC.md`, `WORK.md`, core docs, and design docs
+- optional `mdkg spec list/show/validate` for reusable SPEC capability records
 - SQLite index backend for fresh workspaces using built-in `node:sqlite`
 - mutation locking and atomic writes for parallel mdkg calls
 - first-class `goal` nodes and `mdkg goal show/next/evaluate/pause/resume/done`
@@ -436,7 +458,7 @@ This release includes:
 - shared `AGENT_START.md` startup guidance
 - conservative `mdkg upgrade` with mode-aware init manifests
 - archive sidecars with deterministic ZIP caches
-- semantic mirror helpers under `mdkg work ...`
+- semantic mirror helpers under `mdkg work ...`, including trigger/order status/receipt verification
 - explicit public/internal/private visibility enforcement for packs, bundles, archives, imports, validation, and doctor diagnostics
 - strict archive ZIP payload integrity checks during validation
 

package/dist/cli.js

@@ -20,6 +20,7 @@ const format_1 = require("./commands/format");
 const doctor_1 = require("./commands/doctor");
 const db_1 = require("./commands/db");
 const capability_1 = require("./commands/capability");
+const spec_1 = require("./commands/spec");
 const archive_1 = require("./commands/archive");
 const bundle_1 = require("./commands/bundle");
 const subgraph_1 = require("./commands/subgraph");
@@ -63,6 +64,7 @@ function printUsage(log) {
     log("  pack        Generate a context pack");
     log("  skill       Create, list, show, search, and validate skills");
     log("  capability  List, search, show, and resolve cached capability surfaces");
+    log("  spec        List, show, and validate optional SPEC.md capability records");
     log("  archive     Add, list, show, verify, and compress archive sidecars");
     log("  bundle      Create, list, show, and verify full graph snapshot bundles");
     log("  subgraph    Register, sync, materialize, and verify read-only child graph snapshots");
@@ -435,6 +437,41 @@ function printCapabilityHelp(log, subcommand) {
             printGlobalOptions(log);
     }
 }
+function printSpecHelp(log, subcommand) {
+    switch ((subcommand ?? "").toLowerCase()) {
+        case "list":
+            log("Usage:");
+            log("  mdkg spec list [--json]");
+            log("\nNotes:");
+            log("  SPEC.md is optional and declares reusable capability surfaces.");
+            printGlobalOptions(log);
+            return;
+        case "show":
+            log("Usage:");
+            log("  mdkg spec show <id-or-qid-or-alias> [--json]");
+            log("\nNotes:");
+            log("  Shows one optional SPEC.md capability record from the capability index.");
+            printGlobalOptions(log);
+            return;
+        case "validate":
+            log("Usage:");
+            log("  mdkg spec validate [<id-or-qid-or-alias>] [--json]");
+            log("\nNotes:");
+            log("  With no reference, validates the graph and all optional SPEC.md capability records.");
+            log("  With a reference, also ensures that specific SPEC.md capability exists.");
+            printGlobalOptions(log);
+            return;
+        default:
+            log("Usage:");
+            log("  mdkg spec list [--json]");
+            log("  mdkg spec show <id-or-qid-or-alias> [--json]");
+            log("  mdkg spec validate [<id-or-qid-or-alias>] [--json]");
+            log("\nNotes:");
+            log("  SPEC.md is optional and reusable-capability oriented.");
+            log("  Use `mdkg capability ...` for broader skill, SPEC.md, WORK.md, core-doc, and design-doc discovery.");
+            printGlobalOptions(log);
+    }
+}
 function printArchiveHelp(log, subcommand) {
     switch ((subcommand ?? "").toLowerCase()) {
         case "add":
@@ -580,15 +617,31 @@ function printWorkHelp(log, subcommand) {
             log("Usage:");
             log('  mdkg work contract new "<title>" --id <work.id> --agent-id <agent.id> --kind <kind> --inputs <...> --outputs <...> [--required-capabilities <...>] [--pricing-model <...>] [--json]');
             break;
+        case "trigger":
+            log("Usage:");
+            log('  mdkg work trigger <work-or-capability-ref> [--id <order.id>] [--title "<title>"] [--requester <ref>] [--enqueue <queue>] [--json]');
+            log("\nExample:");
+            log("  mdkg work trigger work.example --id order.example-1 --requester user://example --json");
+            log("\nNotes:");
+            log("  Accepted targets: direct WORK.md ref, or SPEC.md ref with exactly one resolvable work contract.");
+            log("  Creates a deterministic WORK_ORDER.md semantic mirror and does not execute work.");
+            log("  Queue enqueue requires a valid project DB plus an explicitly created active queue and never executes work.");
+            break;
         case "order":
             log("Usage:");
-            log('  mdkg work order new "<title>" --id <order.id> --work-id <work.id> --requester <ref> [--request-ref <ref>] [--input-refs <...>] [--requested-outputs <...>] [--json]');
-            log("  mdkg work order update <id-or-qid> [--status <status>] [--add-input-refs <...>] [--add-artifacts <...>] [--json]");
+            log('  mdkg work order new "<title>" --id <order.id> --work-id <work.id> --requester <ref> [--request-ref <ref>] [--trigger-ref <ref>] [--payload-hash <sha256:...>] [--input-refs <...>] [--queue-refs <...>] [--requested-outputs <...>] [--json]');
+            log("  mdkg work order status <id-or-qid> [--json]");
+            log("  mdkg work order update <id-or-qid> [--status <status>] [--add-input-refs <...>] [--add-queue-refs <...>] [--add-artifacts <...>] [--json]");
+            log("\nNotes:");
+            log("  work order status is read-only and reports deterministic JSON order state plus linked receipts.");
             break;
         case "receipt":
             log("Usage:");
-            log('  mdkg work receipt new "<title>" --id <receipt.id> --work-order-id <order.id> --outcome success|partial|failure [--receipt-status recorded|verified|rejected|superseded] [--json]');
-            log("  mdkg work receipt update <id-or-qid> [--receipt-status <status>] [--add-artifacts <...>] [--add-proof-refs <...>] [--add-attestation-refs <...>] [--json]");
+            log('  mdkg work receipt new "<title>" --id <receipt.id> --work-order-id <order.id> --outcome success|partial|failure [--receipt-status recorded|verified|rejected|superseded] [--redaction-policy refs_and_hashes_only|redacted_summary|external_private] [--evidence-hashes <sha256:...>] [--json]');
+            log("  mdkg work receipt verify <id-or-qid> [--json]");
+            log("  mdkg work receipt update <id-or-qid> [--receipt-status <status>] [--add-artifacts <...>] [--add-proof-refs <...>] [--add-attestation-refs <...>] [--add-evidence-hashes <sha256:...>] [--json]");
+            log("\nNotes:");
+            log("  work receipt verify is read-only and reports deterministic JSON linkage, evidence, hash, outcome, and redaction checks.");
             break;
         case "artifact":
             log("Usage:");
@@ -597,8 +650,9 @@ function printWorkHelp(log, subcommand) {
         default:
             log("Usage:");
             log("  mdkg work contract new ...");
-            log("  mdkg work order new|update ...");
-            log("  mdkg work receipt new|update ...");
+            log("  mdkg work trigger <work-or-capability-ref> ...");
+            log("  mdkg work order new|status|update ...");
+            log("  mdkg work receipt new|verify|update ...");
             log("  mdkg work artifact add ...");
             log("\nNotes:");
             log("  - work commands mutate semantic mirror files only");
@@ -837,6 +891,9 @@ function printCommandHelp(log, command, subcommand) {
         case "capability":
             printCapabilityHelp(log, subcommand);
             return;
+        case "spec":
+            printSpecHelp(log, subcommand);
+            return;
         case "archive":
             printArchiveHelp(log, subcommand);
             return;
@@ -1353,6 +1410,45 @@ function runCapabilitySubcommand(parsed, root) {
             throw new errors_1.UsageError("capability requires list/search/show/resolve");
     }
 }
+function runSpecSubcommand(parsed, root) {
+    const subcommand = (parsed.positionals[1] ?? "").toLowerCase();
+    switch (subcommand) {
+        case "list": {
+            if (parsed.positionals.length > 2) {
+                throw new errors_1.UsageError("spec list does not accept positional arguments");
+            }
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
+            const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
+            (0, spec_1.runSpecListCommand)({ root, json, noCache, noReindex });
+            return 0;
+        }
+        case "show": {
+            const id = parsed.positionals[2];
+            if (!id || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("spec show requires <id-or-qid-or-alias>");
+            }
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
+            const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
+            (0, spec_1.runSpecShowCommand)({ root, id, json, noCache, noReindex });
+            return 0;
+        }
+        case "validate": {
+            const id = parsed.positionals[2];
+            if (parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("spec validate accepts at most one SPEC reference");
+            }
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
+            const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
+            (0, spec_1.runSpecValidateCommand)({ root, id, json, noCache, noReindex });
+            return 0;
+        }
+        default:
+            throw new errors_1.UsageError("spec requires list/show/validate");
+    }
+}
 function runArchiveSubcommand(parsed, root) {
     const subcommand = (parsed.positionals[1] ?? "").toLowerCase();
     switch (subcommand) {
@@ -1587,6 +1683,18 @@ function runWorkSubcommand(parsed, root) {
     const action = (parsed.positionals[2] ?? "").toLowerCase();
     const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
     const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+    if (domain === "trigger") {
+        const targetRef = parsed.positionals[2];
+        if (!targetRef || parsed.positionals.length > 3) {
+            throw new errors_1.UsageError("work trigger requires <work-or-capability-ref>");
+        }
+        const id = requireFlagValue("--id", parsed.flags["--id"]);
+        const title = requireFlagValue("--title", parsed.flags["--title"]);
+        const requester = requireFlagValue("--requester", parsed.flags["--requester"]);
+        const enqueue = requireFlagValue("--enqueue", parsed.flags["--enqueue"]);
+        (0, work_1.runWorkTriggerCommand)({ root, ws, targetRef, id, title, requester, enqueue, json });
+        return 0;
+    }
     if (domain === "contract" && action === "new") {
         const title = parsed.positionals.slice(3).join(" ");
         const id = requireFlagValue("--id", parsed.flags["--id"]);
@@ -1623,7 +1731,10 @@ function runWorkSubcommand(parsed, root) {
             throw new errors_1.UsageError("work order new requires title, --id, --work-id, and --requester");
         }
         const requestRef = requireFlagValue("--request-ref", parsed.flags["--request-ref"]);
+        const triggerRef = requireFlagValue("--trigger-ref", parsed.flags["--trigger-ref"]);
+        const payloadHash = requireFlagValue("--payload-hash", parsed.flags["--payload-hash"]);
         const inputRefs = requireFlagValue("--input-refs", parsed.flags["--input-refs"]);
+        const queueRefs = requireFlagValue("--queue-refs", parsed.flags["--queue-refs"]);
         const requestedOutputs = requireFlagValue("--requested-outputs", parsed.flags["--requested-outputs"]);
         const constraintRefs = requireFlagValue("--constraint-refs", parsed.flags["--constraint-refs"]);
         (0, work_1.runWorkOrderNewCommand)({
@@ -1634,7 +1745,10 @@ function runWorkSubcommand(parsed, root) {
             workId,
             requester,
             requestRef,
+            triggerRef,
+            payloadHash,
             inputRefs,
+            queueRefs,
             requestedOutputs,
             constraintRefs,
             json,
@@ -1648,8 +1762,17 @@ function runWorkSubcommand(parsed, root) {
         }
         const status = requireFlagValue("--status", parsed.flags["--status"]);
         const addInputRefs = requireFlagValue("--add-input-refs", parsed.flags["--add-input-refs"]);
+        const addQueueRefs = requireFlagValue("--add-queue-refs", parsed.flags["--add-queue-refs"]);
         const addArtifacts = requireFlagValue("--add-artifacts", parsed.flags["--add-artifacts"]);
-        (0, work_1.runWorkOrderUpdateCommand)({ root, ws, id, status, addInputRefs, addArtifacts, json });
+        (0, work_1.runWorkOrderUpdateCommand)({ root, ws, id, status, addInputRefs, addQueueRefs, addArtifacts, json });
+        return 0;
+    }
+    if (domain === "order" && action === "status") {
+        const id = parsed.positionals[3];
+        if (!id || parsed.positionals.length > 4) {
+            throw new errors_1.UsageError("work order status requires <id-or-qid>");
+        }
+        (0, work_1.runWorkOrderStatusCommand)({ root, ws, id, json });
         return 0;
     }
     if (domain === "receipt" && action === "new") {
@@ -1662,9 +1785,11 @@ function runWorkSubcommand(parsed, root) {
         }
         const receiptStatus = requireFlagValue("--receipt-status", parsed.flags["--receipt-status"]);
         const costRef = requireFlagValue("--cost-ref", parsed.flags["--cost-ref"]);
+        const redactionPolicy = requireFlagValue("--redaction-policy", parsed.flags["--redaction-policy"]);
         const artifacts = requireFlagValue("--artifacts", parsed.flags["--artifacts"]);
         const proofRefs = requireFlagValue("--proof-refs", parsed.flags["--proof-refs"]);
         const attestationRefs = requireFlagValue("--attestation-refs", parsed.flags["--attestation-refs"]);
+        const evidenceHashes = requireFlagValue("--evidence-hashes", parsed.flags["--evidence-hashes"]);
         const inputHashes = requireFlagValue("--input-hashes", parsed.flags["--input-hashes"]);
         const outputHashes = requireFlagValue("--output-hashes", parsed.flags["--output-hashes"]);
         (0, work_1.runWorkReceiptNewCommand)({
@@ -1676,9 +1801,11 @@ function runWorkSubcommand(parsed, root) {
             outcome,
             receiptStatus,
             costRef,
+            redactionPolicy,
             artifacts,
             proofRefs,
             attestationRefs,
+            evidenceHashes,
             inputHashes,
             outputHashes,
             json,
@@ -1694,6 +1821,7 @@ function runWorkSubcommand(parsed, root) {
         const addArtifacts = requireFlagValue("--add-artifacts", parsed.flags["--add-artifacts"]);
         const addProofRefs = requireFlagValue("--add-proof-refs", parsed.flags["--add-proof-refs"]);
         const addAttestationRefs = requireFlagValue("--add-attestation-refs", parsed.flags["--add-attestation-refs"]);
+        const addEvidenceHashes = requireFlagValue("--add-evidence-hashes", parsed.flags["--add-evidence-hashes"]);
         (0, work_1.runWorkReceiptUpdateCommand)({
             root,
             ws,
@@ -1702,10 +1830,19 @@ function runWorkSubcommand(parsed, root) {
             addArtifacts,
             addProofRefs,
             addAttestationRefs,
+            addEvidenceHashes,
             json,
         });
         return 0;
     }
+    if (domain === "receipt" && action === "verify") {
+        const id = parsed.positionals[3];
+        if (!id || parsed.positionals.length > 4) {
+            throw new errors_1.UsageError("work receipt verify requires <id-or-qid>");
+        }
+        (0, work_1.runWorkReceiptVerifyCommand)({ root, ws, id, json });
+        return 0;
+    }
     if (domain === "artifact" && action === "add") {
         const targetId = parsed.positionals[3];
         const file = parsed.positionals[4];
@@ -2175,6 +2312,8 @@ function runCommand(parsed, root, runtime) {
             return runSkillSubcommand(parsed, root);
         case "capability":
             return runCapabilitySubcommand(parsed, root);
+        case "spec":
+            return runSpecSubcommand(parsed, root);
         case "archive":
             return runArchiveSubcommand(parsed, root);
         case "bundle":

package/dist/commands/capability.js

@@ -1,5 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadCapabilityRecords = loadCapabilityRecords;
+exports.filterCapabilityRecords = filterCapabilityRecords;
+exports.resolveCapabilityRecord = resolveCapabilityRecord;
 exports.runCapabilityListCommand = runCapabilityListCommand;
 exports.runCapabilitySearchCommand = runCapabilitySearchCommand;
 exports.runCapabilityShowCommand = runCapabilityShowCommand;
@@ -29,7 +32,7 @@ function normalizeVisibility(value) {
     }
     throw new errors_1.UsageError(`--visibility must be one of ${capabilities_indexer_1.CAPABILITY_VISIBILITIES.join(", ")}`);
 }
-function loadRecords(options) {
+function loadCapabilityRecords(options) {
     const config = (0, config_1.loadConfig)(options.root);
     const { index, stale, rebuilt } = (0, capabilities_index_cache_1.loadCapabilitiesIndex)({
         root: options.root,
@@ -46,7 +49,7 @@ function loadRecords(options) {
     }
     return [...index.records, ...subgraph.records];
 }
-function applyFilters(records, options) {
+function filterCapabilityRecords(records, options) {
     const kind = normalizeKind(options.kind);
     const visibility = normalizeVisibility(options.visibility);
     return records.filter((record) => {
@@ -78,6 +81,7 @@ function capabilitySearchText(record) {
         ...record.headings.map((heading) => heading.text),
         JSON.stringify(record.spec ?? {}),
         JSON.stringify(record.work ?? {}),
+        JSON.stringify(record.linkage ?? {}),
         JSON.stringify(record.skill ?? {}),
     ]
         .filter((value) => typeof value === "string" && value.length > 0)
@@ -117,6 +121,7 @@ function requirementMatch(record, required) {
         ...record.tags,
         JSON.stringify(record.spec ?? {}),
         JSON.stringify(record.work ?? {}),
+        JSON.stringify(record.linkage ?? {}),
         JSON.stringify(record.skill ?? {}),
     ]
         .join(" ")
@@ -199,7 +204,7 @@ function printCapabilityList(records, json, query) {
         console.log(`${record.qid} | ${record.kind} | ${record.visibility} | ${label} | ${record.title}`);
     }
 }
-function resolveCapability(records, id) {
+function resolveCapabilityRecord(records, id) {
     const normalized = id.toLowerCase();
     const exact = records.find((record) => record.qid === id || record.id === id);
     if (exact) {
@@ -233,19 +238,19 @@ function printCapability(record, json) {
     console.log(`path: ${record.path}`);
 }
 function runCapabilityListCommand(options) {
-    const records = applyFilters(loadRecords(options), options);
+    const records = filterCapabilityRecords(loadCapabilityRecords(options), options);
     printCapabilityList(records, options.json);
 }
 function runCapabilitySearchCommand(options) {
-    const records = applyFilters(loadRecords(options), options).filter((record) => matchesQuery(record, options.query));
+    const records = filterCapabilityRecords(loadCapabilityRecords(options), options).filter((record) => matchesQuery(record, options.query));
     printCapabilityList(records, options.json, options.query);
 }
 function runCapabilityShowCommand(options) {
-    const records = loadRecords(options);
-    printCapability(resolveCapability(records, options.id), options.json);
+    const records = loadCapabilityRecords(options);
+    printCapability(resolveCapabilityRecord(records, options.id), options.json);
 }
 function runCapabilityResolveCommand(options) {
-    const records = applyFilters(loadRecords(options), options);
+    const records = filterCapabilityRecords(loadCapabilityRecords(options), options);
     const items = resolveCapabilities(records, options).map((record, rank) => ({
         rank: rank + 1,
         score: resolveScore(record, options),

package/dist/commands/format.js

@@ -37,7 +37,7 @@ const EXTERNAL_REF_LIST_KEYS = new Set([
     "proof_refs",
     "attestation_refs",
 ]);
-const HASH_REF_LIST_KEYS = new Set(["input_hashes", "output_hashes"]);
+const HASH_REF_LIST_KEYS = new Set(["evidence_hashes", "input_hashes", "output_hashes"]);
 function isValidId(value) {
     return (0, id_1.isCanonicalId)(value);
 }

package/dist/commands/spec.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSpecListCommand = runSpecListCommand;
+exports.runSpecShowCommand = runSpecShowCommand;
+exports.runSpecValidateCommand = runSpecValidateCommand;
+const capability_1 = require("./capability");
+const validate_1 = require("./validate");
+const errors_1 = require("../util/errors");
+function sortSpecRecords(records) {
+    return [...records].sort((a, b) => {
+        const qidDelta = a.qid.localeCompare(b.qid);
+        if (qidDelta !== 0) {
+            return qidDelta;
+        }
+        return a.path.localeCompare(b.path);
+    });
+}
+function loadSpecRecords(options) {
+    const listOptions = {
+        root: options.root,
+        kind: "spec",
+        noCache: options.noCache,
+        noReindex: options.noReindex,
+    };
+    return sortSpecRecords((0, capability_1.filterCapabilityRecords)((0, capability_1.loadCapabilityRecords)(listOptions), listOptions));
+}
+function matchesSpecRef(record, id) {
+    const normalized = id.toLowerCase();
+    return (record.id === id ||
+        record.qid === id ||
+        record.path === id ||
+        record.id.toLowerCase() === normalized ||
+        record.qid.toLowerCase() === normalized ||
+        record.path.toLowerCase() === normalized ||
+        record.aliases.some((alias) => alias.toLowerCase() === normalized));
+}
+function resolveSpecRecord(records, id) {
+    const matches = records.filter((record) => matchesSpecRef(record, id));
+    if (matches.length === 1) {
+        return matches[0];
+    }
+    if (matches.length > 1) {
+        throw new errors_1.UsageError(`SPEC reference is ambiguous: ${id}`);
+    }
+    throw new errors_1.NotFoundError(`SPEC not found: ${id}`);
+}
+function stringValue(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function stringArrayValue(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function printSpecList(records, json) {
+    if (json) {
+        console.log(JSON.stringify({
+            kind: "spec",
+            count: records.length,
+            items: records,
+        }, null, 2));
+        return;
+    }
+    if (records.length === 0) {
+        console.log("no SPEC.md capabilities found");
+        return;
+    }
+    console.log(`SPEC.md capabilities: ${records.length}`);
+    for (const record of records) {
+        const kind = stringValue(record.spec?.spec_kind);
+        const kindLabel = kind ? ` | ${kind}` : "";
+        console.log(`${record.qid} | ${record.visibility}${kindLabel} | ${record.title}`);
+    }
+}
+function printSpec(record, json) {
+    if (json) {
+        console.log(JSON.stringify({ kind: "spec", item: record }, null, 2));
+        return;
+    }
+    console.log(`${record.qid} | ${record.visibility}`);
+    console.log(`title: ${record.title}`);
+    const specKind = stringValue(record.spec?.spec_kind);
+    if (specKind) {
+        console.log(`spec_kind: ${specKind}`);
+    }
+    console.log(`path: ${record.path}`);
+    const requestedCapabilities = stringArrayValue(record.spec?.requested_capabilities);
+    if (requestedCapabilities.length > 0) {
+        console.log(`requested_capabilities: ${requestedCapabilities.join(", ")}`);
+    }
+}
+function runSpecListCommand(options) {
+    printSpecList(loadSpecRecords(options), options.json);
+}
+function runSpecShowCommand(options) {
+    printSpec(resolveSpecRecord(loadSpecRecords(options), options.id), options.json);
+}
+function runSpecValidateCommand(options) {
+    if (options.id) {
+        resolveSpecRecord(loadSpecRecords(options), options.id);
+    }
+    (0, validate_1.runValidateCommand)({ root: options.root, json: options.json });
+}