wowbagger 0.1.0-alpha.9 → 0.5.0-beta.0

package/README.md

@@ -30,10 +30,10 @@ agent to use those guarantees instead of hand-editing your Markdown.
 
 **Start here:** [install the core and set up a ledger](#start-here).
 
-> **Status: alpha, published, and self-hosted.** `0.1.0-alpha.9` is on npm under
-> the `next` tag and on this repository's `v0.1.0-alpha.9` tag. It is the
-> version this repository runs its own backlog on. The API is not frozen and the
-> version will move before a stable release.
+> **Status: beta, published, and self-hosted.** `0.5.0-beta.0` is on npm under
+> the `next` tag and on this repository's `v0.5.0-beta.0` tag. It is the
+> version this repository runs its own backlog on. The API remains pre-stable
+> and can change before the first stable release.
 >
 > **Install with `@next`.** Every published release is a prerelease. The
 > registry requires a `latest` dist-tag, so `latest` mirrors `next` — a bare
@@ -77,7 +77,7 @@ Wowbagger is the core authority for a Git-native work ledger. Use it instead
 of editing ledger Markdown by hand.
 
 ```sh
-wowbagger --version                 # require 0.1.0-alpha.9
+wowbagger --version                 # require 0.5.0-beta.0
 wowbagger capabilities --json       # require contract_version: 5
 wowbagger validate --ledger ledger --json
 wowbagger ready --ledger ledger --as-of YYYY-MM-DD --json
@@ -86,10 +86,12 @@ wowbagger inspect --ledger ledger --number N --json
 
 For a write, inspect immediately before dispatch, send the returned exact-byte
 revision as the compare-and-swap witness, use the explicit core mutation, and
-validate again. Commit each provisioned-ledger mutation before the next one.
-Never replay a lost write: reconnect, re-read current state, and treat the
-outcome as unknown until the core or a human resolves it. Numbers are the
-human-facing item identity; `wb_...` ULIDs are internal identities.
+validate again. On a provisioned ledger, commit each `create`, `transition`,
+`parent-migrate`, `snooze`, `patch`, or `publish-claimed` mutation before the
+next mutating command. Never replay a lost write: reconnect, re-read current
+state, and treat the outcome as unknown until the core or a human resolves it.
+Numbers are the human-facing item identity; `wb_...` ULIDs are internal
+identities.
 
 The core owns validation, ready selection, projections, lifecycle, CAS,
 publication, claims, fencing, and reconciliation. The harness or host owns
@@ -98,13 +100,14 @@ cooperating writers; they are not exclusive locks.
 
 ## Start here
 
-Install the core CLI, then verify it. The core requires Node.js 20 or later:
+Install the core CLI, then verify it. The supported runtime is Node.js 24; Node
+26 remains excluded because of the separate Vitest incompatibility:
 
 ```sh
-npm install -g wowbagger@0.1.0-alpha.9   # exact plugin-matched release
+npm install -g wowbagger@0.5.0-beta.0   # exact plugin-matched release
 # or, from this release's Git tag:
-# npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.9
-wowbagger --version         # 0.1.0-alpha.9
+# npm install -g github:lstutzman/wowbagger#v0.5.0-beta.0
+wowbagger --version         # 0.5.0-beta.0
 wowbagger capabilities --json              # must report contract_version: 5
 ```
 
@@ -166,21 +169,45 @@ names — `create` publishes into an existing directory and does not make one.
 Nothing is renamed after a create. This repository dogfoods that binding: its
 own items live in [`ledger/items/`](ledger/items/).
 
-If your items mirror an external tracker and carry your own identifier fields,
-declare them now too. `<ledger>/.wowbagger/extensions.json` is what makes a
-consumer-owned extension member patchable:
+If your items will mirror an external tracker and carry consumer-owned fields,
+declare those fields **before the first item**. The declaration makes each
+named extension member patchable:
 
 ```sh
 echo '{"extensions_version":1,"members":{"external_id":"string"}}' \
   > path/to/ledger/.wowbagger/extensions.json
 ```
 
-Each member declares one value type — `string`, `integer`, `boolean`, or
-`string-list`. **A ledger without that file has no patchable extension member at
-all**, and a `set.extensions` patch against it is refused by name. The
-declaration authorizes a write; it never describes the ledger, so `validate`
-does not read it. Both files are ledger setup, not runner configuration: commit
-them.
+Each member declares one value type: `string`, `integer`, `boolean`, or
+`string-list`. A ledger without the file has no patchable extension member,
+and `set.extensions` refuses the missing declaration by name. The declaration
+authorizes writes; it does not define item validity, so `validate` does not
+read it. Commit the declaration with the other ledger setup.
+
+If an existing ledger already carries extension values, do not create the
+declaration by hand. Select every member and type explicitly in a request,
+review a dry run, then publish the same proposal:
+
+```json
+{"members":{"tags":"string-list"}}
+```
+
+```sh
+wowbagger extensions-provision --ledger path/to/ledger \
+  --input declaration.json --json --dry-run
+wowbagger extensions-provision --ledger path/to/ledger \
+  --input declaration.json --json
+git add path/to/ledger/.wowbagger/extensions.json
+git commit -m "Declare patchable ledger extensions"
+```
+
+The command first requires a valid complete ledger. It validates every
+occurrence of each selected member, reports occurrence counts, changes no item
+bytes, and publishes one canonical declaration without overwriting a different
+one. Commit that file before the first corresponding `patch`, inspect the
+target for its current revision, then use `set.extensions.tags`. An item that
+writes the selected member with a YAML anchor or alias remains
+`extension-anchored` and requires a reviewed hand-edit.
 
 Cores at `0.1.0-alpha.4` and earlier ignore the layout file and publish every
 item at the ledger root.
@@ -269,8 +296,9 @@ skill exists because four things break when it does.
 - **Validation is whole-ledger and fail-closed.** One malformed item refuses
   every read and every guarded mutation on that ledger, including commands that
   never touch it. A hand-edit finds that out later, and usually in someone
-  else's session. `create`, `transition`, and `patch` validate the complete
-  candidate ledger *before* publishing anything, and refuse `unchanged`.
+  else's session. `create`, `transition`, `parent-migrate`, `snooze`, and
+  `patch` validate the complete candidate ledger *before* publishing anything,
+  and refuse `unchanged`.
 - **A hand-edit has no lost-update guard.** Every guarded write takes the exact
   SHA-256 revision `inspect` returned and refuses if the bytes moved. An editor
   writes over whatever is there.
@@ -322,7 +350,7 @@ two supported install routes:
   registry requires a `latest` tag), so a bare install resolves to the same
   bytes.
 - **git tag** —
-  `npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.9` installs this
+  `npm install -g github:lstutzman/wowbagger#v0.5.0-beta.0` installs this
   release. Installing at a ref installs the core and every adapter that ref
   carries.
 
@@ -358,10 +386,10 @@ version.
 
 ### Security
 
-- **Read-only by default.** `validate`, `ready`, `report`, `inspect`,
-  `capabilities`, and `mint-id` never modify anything. Every mutation
-  (`create`, `transition`, `patch`, and `publish-claimed`) is an explicit,
-  reviewable write.
+- **Read-only by default.** `validate`, `ready`, `report`, `inspect`, `list`,
+  `capabilities`, and `mint-id` never modify anything. Every item mutation
+  (`create`, `transition`, `parent-migrate`, `snooze`, `patch`, and
+  `publish-claimed`) is an explicit, reviewable write.
 - **Lock is not a claim.** A short mutation lock serializes writers during one
   operation. It does not grant a work claim.
 - **Claims are merge-coordinated, not exclusive.** `claim acquire` uses
@@ -394,7 +422,7 @@ Upgrade the pieces you installed:
 
 ```sh
 npm install -g wowbagger@next                  # public npm registry
-npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.9  # immutable Git release
+npm install -g github:lstutzman/wowbagger#v0.5.0-beta.0  # immutable Git release
 git pull && npm ci                            # or: a direct checkout
 ```
 
@@ -442,6 +470,16 @@ core, these are the changes most likely to touch you:
   `create` and refuses a caller-supplied one; `patch` refuses it because it is
   immutable identity. Keep a legacy identifier in a declared extension member or
   in the item body.
+
+- **Repair duplicate numbers through `ledger-repair` version 1.** Generate a
+  read-only proposal with `number-repair-proposal`, review every
+  `expected_revision` and `replacement_number`, then apply the complete mapping
+  with `number-repair`. The command preserves ULID identities and relations and
+  does not change core contract version 5.
+
+- **Run `version-drift --json` before mutation.** It compares the installed
+  skill pin, required core contract, and running core, and names the stale
+  package, plugin cache, or linked checkout with remediation.
 - **Delete your local ULID generator.** `wowbagger mint-id --json` prints a
   canonical ID; `--date YYYY-MM-DD` selects the creation date the ID must
   encode.
@@ -552,7 +590,8 @@ approval never rides the bootstrap request, which the model controls;
 
 ## Core commands
 
-The current core requires Node.js 20 or later. From a Wowbagger checkout,
+The current core requires Node.js 24. Node 26 is not in the supported matrix.
+From a Wowbagger checkout,
 `./bin/wowbagger.js --help` prints the full command inventory,
 `./bin/wowbagger.js <command> --help` prints that command's usage, and
 `./bin/wowbagger.js --version` prints the installed package version. The
@@ -565,21 +604,28 @@ npm ci
 ./bin/wowbagger.js ready --ledger path/to/ledger --as-of 2030-01-15
 ./bin/wowbagger.js report --ledger path/to/ledger --as-of 2030-01-15 --json
 ./bin/wowbagger.js capabilities --json
-./bin/wowbagger.js mint-id --json
 ./bin/wowbagger.js inspect --ledger path/to/ledger --id wb_... --json
 ./bin/wowbagger.js inspect --ledger path/to/ledger --number 30 --json
+./bin/wowbagger.js list --ledger path/to/ledger --input query.json --json
 ./bin/wowbagger.js create --ledger path/to/ledger --input request.json --json
 ./bin/wowbagger.js transition --ledger path/to/ledger --input request.json --json
+./bin/wowbagger.js parent-migrate --ledger path/to/ledger --input request.json --json
+./bin/wowbagger.js snooze --ledger path/to/ledger --input request.json --json
 ./bin/wowbagger.js patch --ledger path/to/ledger --input request.json --json
+./bin/wowbagger.js extensions-provision --ledger path/to/ledger --input declaration.json --json
+./bin/wowbagger.js mint-id --json
+./bin/wowbagger.js publish-claimed --ledger path/to/ledger --input request.json --json
+./bin/wowbagger.js claim-merge-verify --ledger path/to/ledger --base main --head feature --json
+./bin/wowbagger.js claim-sync --ledger path/to/ledger --json
+./bin/wowbagger.js claim-adopt --ledger path/to/ledger --input request.json --json
+./bin/wowbagger.js mutation-finalize --ledger path/to/ledger --recovery-token token --json
 ./bin/wowbagger.js provision --ledger path/to/ledger --json
 ./bin/wowbagger.js claim capabilities --ledger path/to/ledger --json
 ./bin/wowbagger.js claim acquire --ledger path/to/ledger --input request.json --json
 ./bin/wowbagger.js claim read --ledger path/to/ledger --input request.json --json
 ./bin/wowbagger.js claim renew --ledger path/to/ledger --input request.json --json
 ./bin/wowbagger.js claim release --ledger path/to/ledger --input request.json --json
-./bin/wowbagger.js publish-claimed --ledger path/to/ledger --input request.json --json
-./bin/wowbagger.js claim-verify --ledger path/to/ledger --json
-./bin/wowbagger.js claim-adopt --ledger path/to/ledger --input request.json --json
+./bin/wowbagger.js claim-verify --ledger path/to/ledger [--id wb_...] --json
 ```
 
 `validate` writes exactly one JSON result to standard output. A valid ledger
@@ -642,10 +688,12 @@ change is an addition. And **extension members are patchable only where the
 ledger declares them** — see [Set the ledger up before the first
 item](#set-the-ledger-up-before-the-first-item).
 
-Which members you own at all is a three-way split — core-owned,
-consumer-editable through `patch`, and create-once — stated member by member in
-the mutation contract's **frontmatter ownership** table. Read the table; do not
-send a patch and interpret the refusal.
+Which members you own at all is a four-way split — core-owned,
+consumer-editable through `patch`, mutable through a dedicated command, and
+create-once — stated member by member in the mutation contract's
+**frontmatter ownership** table. Use `parent-migrate` to repoint an existing
+item to or from an epic, and `snooze` to set or clear `snoozed_until`. Read the
+table; do not send a patch and interpret the refusal.
 
 ### An epic's progress is derived, never stored
 
@@ -670,9 +718,11 @@ command asks you to parse the Markdown by hand:
   refusal carries `error.details.item`, the complete snapshot of the item you
   asked for, whenever no validation error names that item's path. A faulted
   item is withheld; `validate` already names its repair.
-- `claim-verify --json` reports `result.ledger_validation`. Exit 0 with
-  `findings: []` and `ledger_validation.valid: false` says the claim journal is
-  consistent and validation alone is blocking every mutation.
+- `claim-verify --json` reports `result.ledger_validation`. Bare verification
+  is strict repository-wide mode; `--id <item>` keeps all findings visible but
+  fails only for that item and global barriers. Exit 0 with an invalid
+  `ledger_validation` still means claim state is clean but validation blocks
+  mutation.
 
 ### Work claims
 
@@ -702,22 +752,29 @@ operating rule:
 
 **Commit each mutation to Git before running the next mutating command.**
 
-The durable claim store validates every recorded mutation against Git `HEAD`,
-not against working-tree bytes. That is what makes a recorded mutation durable
-rather than a local edit one `git checkout` away from vanishing. An uncommitted
-mutation is an unreconciled mutation, so the next `create`, `transition`, or
-`patch` refuses instead of writing on top of it.
+The durable claim store reconciles every recorded mutation with Git `HEAD` and
+the working tree. The next mutation refuses when that reconciliation finds an
+`unauthorized-revision`, requires Git finalization, or requires synchronization
+for the item the command targets. A synchronization finding on an unrelated
+item remains visible to `claim-verify` but does not block the command.
+
+An existing item's latest authorized working-tree bytes and an earlier
+authorized revision at `HEAD` form an authorized predecessor/successor window.
+That window produces no finding, so another mutation can run before the first
+one is committed. Acceptance of the later mutation does not make either change
+durable. Commit each mutation anyway, then run `claim-verify`.
 
 The loop that works:
 
 ```sh
 ./bin/wowbagger.js create --ledger path/to/ledger --input request.json --json
 git add path/to/ledger && git commit -m "Record the mutation"
-./bin/wowbagger.js claim-verify --ledger path/to/ledger --json
+./bin/wowbagger.js claim-verify --ledger path/to/ledger --id wb_... --json
 ./bin/wowbagger.js transition --ledger path/to/ledger --input next.json --json
 ```
 
-Skip the commit and the next command returns exit 6:
+For example, an authorized new item that is still absent from `HEAD` makes the
+next command return exit 6:
 
 ```json
 {"ok":false,"namespace":"ledger-mutation","command":"create-v1","contract_version":1,
@@ -732,10 +789,16 @@ Skip the commit and the next command returns exit 6:
 `state: "unchanged"` is exact — nothing was written. **`claim-verify` is the
 reconciliation procedure.** Read `details.findings`, do what each
 `remediation` string says, run `claim-verify` until it returns exit 0, then
-repeat the refused command.
+repeat the refused command. A `worktree-synchronization-required` finding on an
+unrelated item does not block the requested mutation. The same finding on the
+target item, and every `unauthorized-revision` finding, remains blocking.
 
-Batch work is where this bites. Filing ten items means ten commits, not one
-commit at the end.
+Batch work is where this bites. Filing ten items means ten serial
+`create --auto-commit` calls and ten commits, not one batch commit. Wowbagger
+permanently rejects batch create for the direct-Markdown architecture:
+`limits.multi_item_atomicity` remains `false`, request order is the supported
+bulk order, and each create must finish or recover before the next begins. See
+the [batch-create decision](docs/design/2026-08-30-batch-create.md).
 
 ### Or fold the commit into the mutation
 
@@ -748,16 +811,23 @@ ledger only:
 
 It is opt-in per invocation. There is no configuration setting or environment
 default, because a hidden default would make existing automation create Git
-commits unexpectedly. The flag is accepted on `create`, `transition`, `patch`,
-and `publish-claimed`.
+commits unexpectedly. The flag is accepted on `create`, `transition`,
+`parent-migrate`, `snooze`, `patch`, and `publish-claimed`.
 
 What one flagged invocation does: refuse if anything is staged anywhere or any
-path under the ledger is dirty; reconcile; run the mutation unchanged; commit
-exactly the changed item and at most one
+foreign path under the ledger is dirty; reconcile; run the mutation unchanged;
+commit exactly the changed item and at most one
 `.wowbagger/reconcile-<namespace>.md` with a fixed subject such as
 `wowbagger: transition item #7`; verify the commit; then run `claim-verify`
-before it answers. On success the result gains `git_commit`, `commit_paths`, and
-`claim_verified`.
+before it answers. A command that owns the claim journal may rebuild only its
+derived reconciliation log during preflight. `create` remains strict, and
+every other dirty ledger path still refuses. On success the result gains
+`git_commit`, `commit_paths`, and `claim_verified`.
+
+If claim verification refuses, auto-commit preserves its code and reason in
+`claim_verify_code` and `claim_verify_reason`. Only
+`claim_verify_reason: "claim-store-locked"` is retryable; unresolved
+reconciliation is not.
 
 Unstaged and untracked files **outside** the ledger are left alone. Hooks and
 signing are honoured; `--no-verify` is never passed. Nothing is pushed.
@@ -1143,18 +1213,20 @@ the finding as a ledger item rather than leaving it in a transcript.
 
 ### The verification gate
 
-Four commands. All four must pass, and the test commands run on **both** the
-current Node runtime and Node 20:
+Four commands. All four must pass, and the test commands run on **Node 24.20.0**:
 
 ```sh
-TMPDIR=/tmp node --test test/*.test.js
-TMPDIR=/tmp /opt/homebrew/opt/node@20/bin/node --test test/*.test.js
-TMPDIR=/tmp node spec/run-adapter-implementation.js
-node bin/wowbagger.js validate --ledger ledger --json
+TMPDIR=/tmp /opt/homebrew/opt/node@24/bin/node --test test/*.test.js
+TMPDIR=/tmp /opt/homebrew/opt/node@24/bin/node --pending-deprecation --throw-deprecation --test test/*.test.js
+TMPDIR=/tmp /opt/homebrew/opt/node@24/bin/node spec/run-adapter-implementation.js
+TMPDIR=/tmp /opt/homebrew/opt/node@24/bin/node bin/wowbagger.js validate --ledger ledger --json
 ```
 
 `TMPDIR=/tmp` is not optional: the default macOS temporary path makes the claim
-lock socket path too long. Substitute your own Node 20 binary path.
+lock socket path too long. Use an explicit Node 24.20.0 binary path.
+
+The supported runtime matrix is Node 24.20.0. Node 26 remains excluded until
+the separate Vitest incompatibility reported by Lee is resolved.
 
 `npm test`, `npm audit --omit=dev`, and `git diff --check` are useful alongside
 it; they are not a substitute for the four commands above.

package/docs/adapter-contract.md

@@ -1477,7 +1477,7 @@ error registry. It changes only this versioned surface:
 The core capability probe adapter contract version 2 requires is core
 contract version 5. It adds exactly
 `operations.patch: {"supported":true,"write_scope":"single-item","cas_scope":"exact-byte-sha256"}`,
-`operations.work_claim.api_version: 2`, and
+`operations.work_claim.api_version: 3`, and
 `limits.max_item_source_bytes: 8388608` as the first member of
 `limits`.
 Its mutation backend scope is always

package/docs/host-contract.md

@@ -26,10 +26,13 @@ shell: an absolute Node executable, the absolute `wowbagger.js` the package
 installed, an argument array, and `shell: false`. Neither path is discovered by
 searching a global npm directory, and neither is a platform command shim.
 
-Wowbagger requires Node.js 20 or later. The package declares that floor in
+Wowbagger requires Node.js 24 or later. The package declares that floor in
 `engines.node`, and the launch seam exports it as `MINIMUM_NODE_MAJOR` for a
 host that resolves its own runtime instead of reusing the one it is running on.
 
+The supported release matrix is Node 24.20.0. Node 26 is excluded until the
+separate Vitest incompatibility reported by Lee is resolved.
+
 ~~~js
 import { resolveCoreLaunch } from 'wowbagger';
 
@@ -258,6 +261,9 @@ not a fetch URL.
 | `bare-ready-result.json` | bare result | a `ready` success |
 | `ledger-mutation-refusal.json` | ledger-mutation 1 | the legacy-write fence refusals |
 | `report-config-v1.json` | report config 1 | `<ledger>/.wowbagger/report.json` at version 1 |
+| `ledger-repair-request.json` | ledger-repair 1 | the strict `number-repair` request |
+| `ledger-repair-proposal.json` | ledger-repair 1 | the read-only `number-repair-proposal` result |
+| `ledger-repair-response.json` | ledger-repair 1 | every `number-repair-proposal` and `number-repair` response |
 | `report-config-v2.json` | report config 2 | the same file at version 2, which names views |
 
 Every schema fixes its root members exactly and pins the version of its own