wowbagger 0.5.0-beta.0 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,65 @@ consolidation. The first tagged release inherits this file.
 
 ## Unreleased
 
+## 0.5.0 - 2026-09-05
+
+- **The report is one decision-focused workspace.** Items, Flow, and
+  Dependencies sit behind accessible view navigation; only the selected section
+  shows, and a reader without scripting keeps every section through anchors and
+  native `details`. The duplicated Work next and Attention lists are gone: one
+  canonical list carries five quick views (Work next, In progress, Blocked,
+  Needs triage, All open), one canonical detail per retained item, a desktop
+  list/detail split, and inline details below 1100px. Search plus facet groups
+  are the shared scope for the summaries, Flow, and the graph; quick views and
+  Show history change only the list. Opening a detail no longer clears the
+  search or facets, and a detail opened from Flow or Dependencies returns to
+  Items with the scope intact. Missing metadata is its own `Missing` chip,
+  distinct from a literal `Unclassified` value, and `tags` is projected as a
+  multi-value mapped field with per-field coverage counts.
+- **Concentrations and blockers lead to exact items.** Scoped attention
+  actions, an area/status matrix with count and blocked count per cell, and
+  scoped members of the existing area-diverse batches each open a labelled
+  drilldown of their contributing items. Item details state downstream reach
+  and, separately, the items that become ready if done, derived once at
+  generation from the complete ledger and exposed to the browser as an
+  immutable `impactById`; excluded named-view items never enter it. Core
+  readiness and the recommended order are unchanged.
+- **Flow is scoped and interactive.** Flow recomputes in the browser from the
+  scoped open and terminal population with inclusive From/To range controls
+  that refuse an invalid range visibly while keeping the last valid charts.
+  Weekly buckets, aging cells, completion samples, and cumulative date/band
+  selections drill into exact contributing items, including now-closed items
+  accepted on the selected date. Closures and done are named separately, the
+  forecast is computed only when Flow first opens, and an item killed straight
+  from triage no longer counts as missing acceptance history.
+- **The graph follows the shared scope.** The graph-only status filter is
+  removed; nodes, induced links, labels, and the roster follow the report
+  scope, node and roster selections open the canonical detail, and downstream
+  and ready-if-done actions drill into the same sets the detail names. The
+  graph starts only when Dependencies first opens, pauses while hidden, and
+  probes WebGL once. The legend, the WebGL-less roster, reduced motion, the
+  vendored bundle pin, and the no-fetch content security policy are unchanged.
+- `scripts/report-design-demo.js` publishes a deterministic, explicitly
+  synthetic report through the real pipeline for browser verification.
+- **Stable and prerelease channels are defined.** A stable release sets both
+  `latest` and `next` to the stable version; a later prerelease moves only
+  `next` while `latest` stays on stable. Publish stable releases with
+  `npm publish --tag latest` and prereleases with `npm publish --tag next`.
+- **Release tooling is version-aware.** The cut still proves exact version-site
+  equality and never edits the manifest; publication and channel verification
+  follow the stable-or-prerelease target state above.
+
+The alpha.14 hard cutover remains the baseline: `claim-store-unavailable`
+answers **The durable claim store is unavailable.** with
+`claim-store-unreadable`; upgrade every writer before the first alpha.14 create.
+There is no automatic migration or mixed-version grace period. There is no
+batch mutation. The create-then-commit loop, implemented most briefly as serial
+`create --auto-commit`, remains the supported bulk path. Ledger item #186 records the
+permanent no-batch decision, and item #182 owns existing duplicate numbers.
+The fence adds no new Git roster or history
+traversal and costs two extra fsync'd journal appends within the 65,536-entry
+limit.
+
 ## 0.5.0-beta.0 - 2026-08-30
 
 - Promote Wowbagger from alpha to beta while keeping `next` as the documented

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: 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.
+> **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.5.0-beta.0
+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
@@ -104,10 +106,11 @@ 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.5.0-beta.0   # 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.5.0-beta.0
-wowbagger --version         # 0.5.0-beta.0
+# npm install -g github:lstutzman/wowbagger#v0.5.0
+wowbagger --version         # 0.5.0
 wowbagger capabilities --json              # must report contract_version: 5
 ```
 
@@ -334,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**.
 
@@ -345,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.5.0-beta.0` 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.
 
@@ -373,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`.
@@ -421,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.5.0-beta.0  # 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
 ```
 
@@ -445,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
@@ -920,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
@@ -1018,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.
 
@@ -1085,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
@@ -1151,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
@@ -1330,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wowbagger",
-  "version": "0.5.0-beta.0",
+  "version": "0.5.0",
   "description": "Git-native work ledger for coding agents: deterministic ready queues, guarded CAS mutations, claims and fencing, and self-contained HTML reports.",
   "type": "module",
   "license": "MIT",

package/schemas/report-config-v1.json

@@ -45,6 +45,10 @@
           "type": "string",
           "pattern": "^(/([^/~]|~[01])*)*$"
         },
+        "tags": {
+          "type": "string",
+          "pattern": "^(/([^/~]|~[01])*)*$"
+        },
         "class": {
           "type": "string",
           "pattern": "^(/([^/~]|~[01])*)*$"

package/schemas/report-config-v2.json

@@ -45,6 +45,10 @@
           "type": "string",
           "pattern": "^(/([^/~]|~[01])*)*$"
         },
+        "tags": {
+          "type": "string",
+          "pattern": "^(/([^/~]|~[01])*)*$"
+        },
         "class": {
           "type": "string",
           "pattern": "^(/([^/~]|~[01])*)*$"
@@ -189,6 +193,7 @@
                   "propertyNames": {
                     "enum": [
                       "area",
+                      "tags",
                       "class",
                       "due",
                       "rank",

package/skills/wowbagger/SKILL.md

@@ -14,7 +14,7 @@ publish something.
 Install the core separately before using this skill:
 
 ```sh
-npm install -g wowbagger@0.5.0-beta.0
+npm install -g wowbagger@0.5.0
 ```
 
 The core requires Node.js 24 or later. This plugin ships only agent
@@ -38,9 +38,9 @@ wowbagger capabilities --json
 
 Read the plain distribution version from the first command and the top-level
 `contract_version` from the second. **This skill requires distribution version
-`0.5.0-beta.0` and core `contract_version: 5`.**
+`0.5.0` and core `contract_version: 5`.**
 
-The distribution pin names the published `0.5.0-beta.0` release; the cut that
+The distribution pin names the published `0.5.0` release; the cut that
 publishes core `contract_version: 5` moves it. Earlier cores report
 `contract_version: 3` or lower and lack behavior this skill requires, including
 the bounded item source, so the version check refuses them. Do not soften
@@ -146,8 +146,10 @@ the absolute `result.output`. On failure, require `ok: false` and inspect
 publication preserves the prior report. Do not parse the generated HTML and do
 not parse human output: the JSON result is the only machine surface.
 
-The report ends its decision surface with a 3D dependency graph of the items the
-artifact covers. Its renderer is a pinned, checksummed `3d-force-graph` build
+The report is one shared Items, Flow, and Dependencies workspace. The
+Dependencies section holds the 3D dependency graph of the items the artifact
+covers, under the same scope as Items and Flow. Its renderer is a pinned,
+checksummed `3d-force-graph` build
 vendored at `vendor/3d-force-graph/` and inlined at generation time, so the
 report is still one self-contained file that fetches nothing — it is roughly
 1.3 MB larger for it. A browser without WebGL shows the graph section's plain