wowbagger 0.1.0-alpha.9 → 0.5.0

package/README.md

@@ -30,16 +30,17 @@ 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: published and self-hosted.** `0.5.0` is published on npm and has
+> a matching repository tag. It is the version this repository runs its own
+> backlog on. The API is stable at core contract version 5.
 >
-> **Install with `@next`.** Every published release is a prerelease. The
-> registry requires a `latest` dist-tag, so `latest` mirrors `next` — a bare
-> `npm install wowbagger` resolves to the current prerelease rather than an
-> older build — but `@next` is the documented install and the explicit
-> statement that you accept a prerelease.
+> **Channels.** A stable release sets both `latest` and `next` to the stable
+> version and publishes with `npm publish --tag latest`. A later prerelease
+> moves only `next` and publishes with `npm publish --tag next`, so `latest`
+> stays on the stable release. While every published release is a prerelease,
+> `latest` mirrors `next`: install the prerelease explicitly with
+> `wowbagger@next`. After the first stable release, a bare install resolves
+> to the stable release.
 >
 > **What is proved.** Contract version **5** validates the complete Markdown
 > ledger, selects a deterministic ready queue, exposes bounded `list` and
@@ -50,11 +51,12 @@ agent to use those guarantees instead of hand-editing your Markdown.
 > verification, and publication finalization coordinate cooperating writers
 > without pretending to be an exclusive dispatch lock.
 >
-> `report` is a self-contained sequencing dashboard: **Work next**, **Attention**,
-> facet filters, inline evidence, terminal history, area-diverse batches, and a
-> 3D dependency graph. Version 2 report configurations add named custom views
-> whose statistics, readiness, attention, evidence, graph, and drill-down all
-> describe one filtered subset. Reports remain derived output, not mirrored
+> `report` is a self-contained decision workspace: one scoped item browser with
+> **Work next** and other quick views, an area/status matrix, scoped attention
+> actions, dependency impact, interactive Flow charts, and a 3D dependency
+> graph that all share one scope. Version 2 report configurations add named
+> custom views whose statistics, readiness, attention, flow, graph, and impact
+> all describe one filtered subset. Reports remain derived output, not mirrored
 > ledger state.
 >
 > The core ships Claude Code, Codex, and OpenCode adapter packages on one shared
@@ -77,7 +79,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
 wowbagger capabilities --json       # require contract_version: 5
 wowbagger validate --ledger ledger --json
 wowbagger ready --ledger ledger --as-of YYYY-MM-DD --json
@@ -86,10 +88,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 +102,15 @@ 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@latest   # stable release
+npm install -g wowbagger@0.5.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
+wowbagger --version         # 0.5.0
 wowbagger capabilities --json              # must report contract_version: 5
 ```
 
@@ -166,21 +172,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 +299,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.
@@ -306,7 +337,7 @@ Four separate things, deliberately:
 
 The core and the plugin install independently and must carry matching
 distribution versions. The core contract version and the adapter contract
-version are separate domains: the core is at **3**, the adapter is at **2**, and
+version are separate domains: the core is at **5**, the adapter is at **2**, and
 the legacy work-claim, ledger-publication, and ledger-mutation envelopes stay at
 **1**.
 
@@ -317,12 +348,14 @@ the legacy work-claim, ledger-publication, and ledger-mutation envelopes stay at
 Wowbagger ships as an npm package with a single `wowbagger` binary. There are
 two supported install routes:
 
-- **npm registry** — `npm install -g wowbagger@next` installs the current
-  prerelease. `@next` is the documented spelling; `latest` mirrors it (the
-  registry requires a `latest` tag), so a bare install resolves to the same
-  bytes.
+- **npm registry** — `npm install -g wowbagger` installs the stable release
+  once it exists; `npm install -g wowbagger@next` installs the newest
+  prerelease. While every published release is a prerelease, `latest` mirrors
+  `next`, so a bare install resolves to the same bytes. After the first
+  stable release, `latest` stays on stable and only `next` follows later
+  prereleases.
 - **git tag** —
-  `npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.9` installs this
+  `npm install -g github:lstutzman/wowbagger#v0.5.0` installs this
   release. Installing at a ref installs the core and every adapter that ref
   carries.
 
@@ -345,8 +378,9 @@ sending the request and reading the refusal — an `unknown-member` issue at
 `/set/body_append` means the core predates the append — or pin the distribution
 version.
 
-- **Node.js:** 20 and later. The adapter conformance vectors run against Node
-  20 and the current runtime before each release.
+- **Node.js:** 24 and later. The release gate runs the full suite on Node
+  24.20.0 with the strict deprecation gate; Node 26 stays excluded because of
+  the separate Vitest incompatibility.
 - **Platforms:** the core runs wherever Node.js runs. The Claude Code adapter
   declares Darwin, Linux, and Windows `supported` from native common-vector
   evidence. Every other shipped adapter target remains `unverified`.
@@ -358,10 +392,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
@@ -393,8 +427,8 @@ wowbagger core, this is how you move forward safely.
 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 wowbagger@latest                  # public npm registry
+npm install -g github:lstutzman/wowbagger#v0.5.0  # immutable Git release
 git pull && npm ci                            # or: a direct checkout
 ```
 
@@ -417,7 +451,7 @@ distribution versions equal.
 
 The shipped adapter selects only adapter contract version 2 and requires core
 contract version 5. The adapter contract and the core contract are separate
-version domains: the adapter stays at 2 while the core moves to 4. A v1-only
+version domains: the adapter stays at 2 while the core is at 5. A v1-only
 consumer receives `unsupported-adapter-contract-version`; it does not receive v2
 behavior. The schema-2 transport is available. Ledger migration remains a
 separate quiesced maintenance operation. The
@@ -442,6 +476,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 +596,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 +610,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 +694,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 +724,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 +758,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 +795,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 +817,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.
@@ -850,62 +926,108 @@ relative `--out` overrides resolve from the caller's working directory.
     "complexity": "/complexity",
     "rank": "/priority_rank",
     "class": "/class",
-    "due": "/due"
+    "due": "/due",
+    "tags": "/tags"
   },
   "swarm": { "eligible_complexities": ["small", "medium"] }
 }
 ```
-
 `repository.logo`, `fields`, and `swarm` are optional. Field values resolve
 from parsed frontmatter with RFC 6901 JSON Pointers. A swarm requires mapped
 `area` and `complexity` fields. The report fetches nothing at view time.
 
-The report is a **sequencing dashboard**, not a state snapshot. It opens with
-**Work next**: the ready set in a recommended order, each entry carrying the
-factors that placed it. Below it sit **Attention** (blocked work naming its
-blockers, the oldest open work, and started work past this ledger's own
-85th-percentile cycle time), then the **evidence layer**, then the **ledger
-graph**. State counts, item cards, filters, grouping, detail levels, terminal
-history, and area-diverse ready batches all remain, demoted below that decision
-surface.
-
-The drill-down filters are **facet groups**: Readiness, Status, Kind, and one
-group for every configured mapped field, each a fieldset of checkbox chips.
-Values inside a group are alternatives and groups narrow each other, so
-`ready` or `blocked` in Readiness plus `bug` in Class means ready-or-blocked
-bugs; the search box is one more condition on the same answer. Every chip
-carries the count it would leave, measured against the search and the other
-groups but never against its own, so two selections in one group cannot make
-their siblings read zero. The result count states how much of the open set is
-showing, and **Clear filters** gives every selection back. A Work next or
-Attention row still reaches its card: opening one clears the facets and the
-search first, because a row that names an item promises the item can be seen.
-
-The evidence layer is inline SVG, drawn at generation time and embedded in the
-file: an aging heatmap, weekly arrivals against completions, throughput with a
-four-week mean, a cumulative flow area, accept-to-complete cycle time, and a
-Monte Carlo forecast as 50, 85, and 95 percent bands. Each chart carries
-`role="img"` and an aria-label that states its finding in words, so the evidence
-survives a screen reader and a printout.
+`tags` is the one multi-value mapped field. It accepts a nonempty string or an
+array holding only nonempty strings: a scalar reads as a one-tag set, exact
+duplicates collapse, and values sort deterministically. The mapping never
+splits commas, lowercases values, coerces objects, or partially accepts a
+mixed-type array. An empty array counts as missing; any other rejected value
+is omitted from the item and counted as invalid metadata. `area` stays scalar.
+The model carries `fieldCoverage`, one entry per configured field plus `area`
+and `tags` when unmapped, ordered by field name with `present`, `missing`, and
+`invalid` counts over the retained report population. An unmapped field counts
+every retained item as missing, and a visible missing-mapping notice tells an
+unconfigured mapping apart from missing item values. Missing metadata never
+matches a filter value: there is no `Unclassified` bucket, so a filter for a
+literal `Unclassified` tag matches only items really carrying that tag.
+
+The report is a **decision-focused workspace**, not a state snapshot. It has
+three sections behind accessible view navigation: **Items** (the default),
+**Flow**, and **Dependencies**. Only the selected section is visible when
+scripting runs; without scripting, every section stays readable through its
+anchor and native `details` elements, and the artifact states its fixed scope.
+
+Items opens with the state counts, then a sticky control strip: search, five
+quick views (**Work next**, **In progress**, **Blocked**, **Needs triage**, and
+**All open**), and the display controls (grouping, sorting, Basic/Standard/
+Detailed, Show history, Expand all, Collapse all). Below 1100px the display
+controls fold behind a **Display** toggle so search and quick views stay in
+reach. Search and the facet groups form the **scope**; the scope narrows the
+summaries, Flow, and Dependencies alike. Quick views and Show history change
+only the list. Work next keeps its recommended order and prints the reasons
+beside each row; any other sort presents itself as that sort.
+
+There is one list and one canonical detail per retained item. Desktop widths
+use a list/detail split; narrower widths show the selected detail inline.
+Opening a detail never clears the search, the facets, or the list position, and
+a detail opened from Flow or Dependencies returns to Items with the scope
+intact. Expand all acts on visible rows only.
+
+The **filters** are facet groups: Readiness, Status, Kind, Priority, and one
+group for every configured mapped field, each a fieldset of checkbox chips
+behind a collapsed **Filters** control. Values inside a group are alternatives
+and groups narrow each other; the search box is one more condition on the same
+answer. Every chip carries the count it would leave, measured against the
+search and the other groups but never against its own. Missing metadata is its
+own **Missing** chip, distinct from a literal `Unclassified` value. The result
+count states how much of the retained set is showing, and **Clear filters**
+gives every selection back.
+
+Above the list sit scoped summaries that open exact contributing items through
+a labelled drilldown pill: attention actions (in progress, blocked, needs
+triage, oldest, and started work past this ledger's own 85th-percentile cycle
+time), an **area/status matrix** with count and blocked count per cell, and
+**Scoped members of existing batches**, which intersects the area-diverse
+batches with the scoped ready set and omits empty batches. Each item detail
+states its **downstream reach** (transitive dependents in the report) and,
+separately, the items that become **ready if done**; neither alters core
+readiness or the recommended order.
+
+### Flow
+
+Flow recomputes from the scoped open and terminal population in the browser:
+cumulative flow, weekly arrivals against closures with done counted
+separately, throughput with a four-week mean, current aging by status,
+acceptance-to-completion samples, and the closure forecast. Inclusive **From**
+and **To** controls default to the twelve-week window; a start after the end,
+or an end after the report date, is refused with a visible error while the last
+valid charts stay. Weekly buckets, aging cells, completion samples, and
+cumulative date/band selections each drill into the exact contributing items,
+and the accessible tables offer the same actions. The forecast is computed only
+when Flow first opens and cached by cohort and range. Missing acceptance history
+is stated as reconstruction uncertainty; an item killed straight from triage is
+complete history, not a gap. The fixed server-rendered charts remain for
+readers without scripting, each with `role="img"` and an aria-label that states
+its finding in words.
 
 ### The ledger graph
 
-Below the evidence layer the report draws the whole ledger as a force-directed
-3D graph. Every item is a node, labelled `#N`, coloured by readiness for open
-items and by terminal status for closed ones, and sized by the same transitive
-unblocking leverage the recommended order uses. Edges run from a prerequisite
-or a parent to the item it releases: a `depends_on` edge is straight and
-arrowed, a `parent` edge is curved and unarrowed. Hovering or clicking a node
-opens a card with its number, title, status, age, leverage, and the same
-reasons line the ranked list prints for it.
-
-Above the stage sits one chip group of the lifecycle statuses the ledger holds,
-all selected, with **Select all** and **Clear**. Deselecting a status drops its
-nodes, every link that touched one of them, and their labels together, then
-reheats the layout in place: nothing is reloaded and the ledger is never
-touched. The roster and the node count follow the same selection, and clearing
-every status draws an empty graph that says it is empty rather than quietly
-showing the last one.
+Dependencies draws the scoped items as a force-directed 3D graph. Every item is
+a node, labelled `#N`, coloured by readiness for open items and by terminal
+status for closed ones, and sized by the same transitive unblocking leverage the
+recommended order uses. Edges run from a prerequisite or a parent to the item
+it releases: a `depends_on` edge is straight and arrowed, a `parent` edge is
+curved and unarrowed. Hovering a node opens a card with its number, title,
+status, age, leverage, and reasons; clicking it, or a roster row, opens the
+canonical detail in Items. Downstream and ready-if-done actions on the roster
+drill into the same sets the detail names.
+
+The graph has no filter of its own: it follows the shared scope, so a scope
+change drops nodes, every link that touched one of them, and their labels
+together, then reheats the layout in place. A hidden blocker never turns a
+retained item ready, because readiness is projected over the complete ledger
+before any view narrows it. The graph starts only when Dependencies first
+opens, pauses while another section is shown, and an empty scope draws an
+empty graph that says so.
 
 The renderer is [`3d-force-graph`](https://github.com/vasturiano/3d-force-graph)
 over Three.js, vendored into `vendor/3d-force-graph/` at a pinned version
@@ -948,9 +1070,10 @@ weight and is shown as written.
 ### Named custom report views
 
 A named custom view is a second self-contained report generated from the same
-complete ledger. Every section of it — statistics, **Work next**, **Attention**,
-the evidence layer, the graph, the open-item drill-down, terminal history, and
-the swarm batches — describes one configured subset, so the file is honest to
+complete ledger. Every section of it — statistics, **Work next** and the other
+quick views, the **Attention** summaries and area/status matrix, dependency
+impact, Flow, the graph, the drill-down pill, terminal history, and the
+swarm batches — describes one configured subset, so the file is honest to
 share as a scoped report. Excluded items are absent from the bytes rather than
 hidden by a stylesheet. The base report stays available and unchanged.
 
@@ -1015,9 +1138,10 @@ A `fields` key must also be a configured report field. Each field filter is a
 non-empty array of unique JSON strings, finite numbers, or booleans, and matching
 preserves JSON scalar type and value: stringification is not equality, so a
 mapped `2` does not answer a filter for `"2"`. An item carrying no mapped value
-for a field matches no value selected for that field. No title-text inference,
-regular expression, arbitrary JSON pointer, or body search belongs in a view
-filter.
+for a field matches no value selected for that field. A `tags` filter uses
+any-member matching, so one item carrying two tags answers either tag. No
+title-text inference, regular expression, arbitrary JSON pointer, or body
+search belongs in a view filter.
 
 Wowbagger validates the complete ledger and computes readiness against the
 complete ledger before it filters, so excluding a blocker never makes blocked
@@ -1081,6 +1205,16 @@ current UTC date:
 npm run report -- --as-of YYYY-MM-DD
 ```
 
+If you verify the report in a browser from a checkout, generate a deterministic
+synthetic report through the real pipeline:
+
+```sh
+node scripts/report-design-demo.js --out /private/tmp/wowbagger-report-demo.html --items 40
+```
+
+That output is synthetic and checkout-only: it describes fixed demo data,
+never this repository's ledger.
+
 ## Where the contracts live
 
 The README is the map. These are the territory, and they are normative where
@@ -1143,18 +1277,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.
@@ -1258,7 +1394,7 @@ It is the durable work ledger beneath those systems.
   **Shipped: the policy-input contract and the report's mapped fields keep
   consumer vocabulary out of the schema.**
 - Stabilize the machine-readable command contract and compatibility evidence.
-  **In progress at core contract version 5; the version is not frozen.**
+  **Shipped: core contract version 5 is the stable contract.**
 - Ship Claude Code and Codex adapters. **Claude Code, Codex, and OpenCode
   packages share the version 2 engine; the Claude Code manifest declares Darwin
   `supported` after passing all 212 native assertions. Other adapter targets and