mdkg 0.1.10 → 0.3.0

package/CHANGELOG.md

@@ -6,6 +6,75 @@ 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.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`
+when the release represents a capability-track boundary.
+
+### Added
+
+- Added public `mdkg db queue ...` commands for local project DB queue
+  create/pause/resume/enqueue/claim/ack/fail/dead-letter/release-expired/stats/list/show.
+- Added `mdkg.project_db.queue_control.v1` / `005_mdkg_project_db_queue_control.sql`
+  for first-class queue active/paused state and migration backfill from existing
+  queue messages.
+- Added queue-aware snapshot sealing policies: default `--queue-policy drain`
+  blocks ready/leased messages, while `--queue-policy paused` allows ready
+  messages only in paused queues and always blocks leased messages.
+- Added packed CLI-only `smoke:db-queue-cli` coverage that exercises public
+  queue commands and pause/drain snapshot behavior from an installed tarball.
+
+### Changed
+
+- Source release line now targets `0.2.0` for the next project DB
+  materializer/profile capability track.
+- Project DB queue support is now public under `mdkg db queue`; event, reducer,
+  writer lease, and materializer command surfaces remain internal-only.
+
 ## 0.1.10 - 2026-06-05
 
 ### Added

package/README.md

@@ -14,7 +14,7 @@ mdkg stays deliberately boring:
 - first-class rebuildable SQLite cache through built-in `node:sqlite`
 - no daemon, hosted index, or vector DB
 
-Current package version in source: `0.1.10`
+Current package version in source: `0.2.0`
 
 mdkg is still pre-v1 public alpha software. The public package is usable, but graph, cache, bundle, and DAL contracts may continue to change quickly while the project converges on a stable v1 surface.
 
@@ -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
 
@@ -349,23 +367,29 @@ Runtime DB files, WAL, SHM, journal, lock, and temp files are ignored by
 default. `mdkg db init` does not create an active runtime SQLite database.
 Run `mdkg db migrate` after init to create or update the active runtime
 SQLite database at the configured `db.runtime_path`; built-in migrations write
-mdkg-owned generic foundation tables, then the internal local node:sqlite queue
-foundation, then internal local event/receipt/reducer and writer lease/CAS
-foundations, and record migration order, checksums, and applied timestamps.
-Queue state is durable local delivery infrastructure, not canonical event
-history. Event rows are the durable local history for project DB state
-transitions, receipts provide audit/review artifacts, reducers gate writes,
-writer leases coordinate snapshot-hash compare-and-swap commits, and
-materializers run local queue-backed reducer passes. These capabilities are
-available only through internal helper modules in this release; there is no
-public `mdkg db queue`, `mdkg db event`, `mdkg db reducer`, `mdkg db lease`, or
+mdkg-owned generic foundation tables, public local node:sqlite queue delivery
+tables, internal local event/receipt/reducer tables, writer lease/CAS tables,
+and queue control state, then record migration order, checksums, and applied
+timestamps. Queue state is durable local delivery infrastructure, not canonical
+event history. Use `mdkg db queue create|pause|resume|enqueue|claim|ack|fail|dead-letter|release-expired|stats|list|show`
+to operate local project queues. Paused queues reject enqueue/claim while still
+allowing ack/fail/dead-letter/release-expired so leased work can settle. Event
+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,
 receipt-file count, and state snapshot presence.
 Use `mdkg db snapshot seal` to create an explicit sealed checkpoint at
 `.mdkg/db/state/project.sqlite` with `.mdkg/db/state/project.manifest.json`.
+The default queue policy is `--queue-policy drain`, which requires no ready or
+leased queue messages. Use `--queue-policy paused` only when ready messages are
+intentionally preserved in paused queues; leased messages always block sealing.
 Use `mdkg db snapshot verify` and `mdkg db snapshot status` for checkpoint
 health, and use `mdkg db snapshot dump` / `mdkg db snapshot diff` as
 deterministic review aids for SQLite snapshots instead of comparing raw binary
@@ -398,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
 
@@ -420,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`
@@ -433,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