wowbagger 0.1.0-alpha.4 → 0.1.0-alpha.5

package/CHANGELOG.md

@@ -5,7 +5,257 @@ A change to what a command accepts, refuses, emits, or writes is a behaviour
 change even when the commit that carried it was labelled refactor, docs, or
 consolidation. The first tagged release inherits this file.
 
-## Unreleased
+## 0.1.0-alpha.5 - 2026-08-16
+
+### Added
+
+- **The report draws the whole ledger as a 3D dependency graph.** It sits below
+  the evidence layer, under the decision surface. Every item is a node labelled
+  `#N`, coloured by readiness or terminal status and sized by the same
+  transitive unblocking leverage the recommended order uses; `depends_on` edges
+  are straight and arrowed, `parent` edges are curved and unarrowed, and both
+  run from the prerequisite to the item it releases. Hovering or clicking a node
+  shows its number, title, status, age, leverage, and the same reasons line the
+  ranked list prints for it. The renderer is `3d-force-graph` 1.80.0 over
+  Three.js r183, vendored at `vendor/3d-force-graph/` with its upstream SHA-256
+  recorded beside it and pinned by a test, and inlined at generation time: the
+  report stays one self-contained file and fetches nothing at generation or view
+  time. It costs roughly 1.3 MB of report size. A browser without WebGL gets the
+  section's plain explanation and a per-node roster instead; no
+  decision-relevant content exists only in the 3D view.
+
+### Changed
+
+- **An invalid ledger can now be diagnosed with the documented commands.** One
+  invalid item still refuses every read and every guarded mutation on that
+  ledger, but the refusals no longer hide what the operator has to read.
+  `inspect` keeps refusing exit 3 `ledger-invalid` — handing back a revision
+  from a ledger the core has not judged would read as a mutation precondition,
+  and there is no flag that skips validation — and its refusal now carries
+  `error.details.item`, the same lossless snapshot the success envelope
+  defines, for the item the request selected, whenever no validation error
+  names that item's path. A faulted item is withheld; `validate` already names
+  its repair. `claim-verify` now reports `result.ledger_validation`, carrying
+  `valid` and `errors` exactly as the bare `validate` result does, plus a
+  `remediation` when the ledger is invalid. Its claim answer is unchanged:
+  `findings`, `state`, and the exit status still describe claim state alone, so
+  a consistent journal over an invalid ledger is still exit 0 with
+  `findings: []` — it just no longer pretends that is a clear road. The report
+  costs no extra ledger read. Fixtures extend item #104's misplaced-item
+  scenario.
+- **The adapter forwards `inspect` refusals instead of calling them protocol
+  errors.** Both the engine and the independent oracle demanded a canonical
+  mutation request before they would accept any error details, which no read
+  command has, so every `inspect` `item-not-found` and `ledger-invalid` refusal
+  was mapped to `core-protocol-error`. The precondition now applies only to
+  mutation commands. The same surfaces accept the `expected_path` and
+  `remediation` that item #104 added to a validation error, and the optional
+  `details.item` on an `inspect` `ledger-invalid` refusal — on `inspect` only;
+  a mutation refusal that carries one is still rejected.
+
+- **The report's content security policy now also forbids `connect-src`.** The
+  report has never opened a connection; the policy now says so.
+
+- **The `item-outside-layout` validation error now names the expected path and
+  the relocation that repairs it.** It keeps its stable code and its actual
+  `path`, and gains `expected_path` plus a `remediation`; its message names
+  both paths. A committed item outside the configured items directory refuses
+  every read and every guarded mutation on that ledger, including ones that
+  never touch the misplaced item, so the refusal has to say where the item
+  belongs. The claim fence is not involved: `claim-verify` reports no finding
+  on such a ledger, refuting the PropertyCompass2 PR #2184 claim that a
+  root-misplaced item makes the fence report `stale-write-detected` with
+  `actual_revision: null`. Fixtures pin both configuration orders — layout
+  bound first, and layout bound after the item was already committed at the
+  root.
+- **The core contract version is now `3`.** Every core command envelope
+  (`capabilities`, `inspect`, `create`, `transition`, `patch`, `mint-id`,
+  `report`) carries `contract_version: 3`, the shipped adapters require core
+  contract version 3, and the installed skill's version check gates on 3. A
+  version 1 or version 2 consumer fails closed against this core, which is the
+  point of the bump. Version 3 is version 2 plus four deltas against published
+  `0.1.0-alpha.4`: the widened `date-before-created` / `date-before-updated`
+  issue shape carrying `item_created` and `item_updated` (the delta that forced
+  the bump — a version 2 consumer validating issue members exactly refuses the
+  six-member shape); the patch field set widening from `number`/`priority` to
+  `priority`/`depends_on`/`related`; number as the core-assigned immutable item
+  identity on schema version 2, with `create` refusing a supplied number and
+  `inspect` accepting `--number`; and `create` deriving its published path from
+  a committed `.wowbagger/layout.json`. The mutation contract's "Contract
+  versions" section carries the full enumeration. The legacy work-claim,
+  ledger-publication, and ledger-mutation envelopes and
+  `result.operations.work_claim.api_version` are separate version domains and
+  stay at 1; the adapter contract stays at 2.
+
+### Added
+
+- The README and the installed skill warn that `git mv` refuses a freshly
+  created item, because `create` writes an untracked file and the `git add -A`
+  behind it in an unchecked batch commits the item at the ledger root instead.
+  Both state the safe sequence: plain `mv`, then `git add`, checking every exit
+  code before the commit. The warning sits in the `0.1.0-alpha.4` boundary text
+  that already tells consumers that core ignores the layout file.
+- **`patch` can replace an item body.** `set.body` takes a JSON string that
+  replaces the whole body under `create`'s body rules, so a consumer whose
+  items mirror an external card updates them through the managed path instead
+  of hand-editing the Markdown. A body patch rewrites no frontmatter byte —
+  anchors, aliases, comments, quoting, styles, member order, and extension
+  members all survive, and only `updated` changes, as it does for every patch.
+  A body may be set in the same `set` as `priority`, `depends_on`, or
+  `related`, in one compare-and-swap write. `null` is refused at `/set/body`:
+  the body is a region of the file, so removing it means `""`, not null. A
+  claimed item, a stale revision, and a non-string body refuse as before. This
+  widens the patch request schema inside core contract version 3 and does not
+  move the version.
+- One envelope rule now covers every `--json` response. The mutation contract
+  states the response domains (core, work-claim, ledger-publication,
+  ledger-mutation, and bare result), the dispatch steps a generic consumer
+  follows, which domain each command's success and each refusal class answers
+  in, and the exact root members of each shape. Both sanctioned exceptions are
+  stated with their reasons: `validate` and `ready` stay bare results because
+  scripts and fixtures depend on those bytes, and a claim-fenced refusal to
+  `create`, `transition`, or `patch` answers in the `ledger-mutation` domain
+  with `command: "<command>-v1"` and `contract_version: 1` because it is the
+  work-claim contract refusing, not the core contract. The work-claim contract
+  now names all three of its `namespace` values.
+  `spec/fixtures/envelope-domains/manifest.json` pins all 37 response classes,
+  and `test/envelope-dispatch.test.js` walks every one of them through the
+  documented dispatch rule and rejects drift in either direction. No emitted
+  byte changed and no contract version moved.
+- `report` now renders a sequencing dashboard instead of a state snapshot. The
+  HTML opens with **Work next**, the ready set in a recommended order with the
+  factors that placed each entry printed beside it; then **Attention**, naming
+  blockers by number, the oldest open work with its age, and started work past
+  this ledger's own 85th-percentile cycle time; then an evidence layer with
+  aging buckets, weekly arrivals against completions, accept-to-complete cycle
+  time, and a Monte Carlo forecast as 50 and 85 percent bands. State counts,
+  item cards, and swarm batches remain, below that decision surface. Relations
+  and readiness reasons inside the drill-down now name items by number.
+  Ordering is a report-layer derivation, recomputed from ledger bytes at render
+  time and never persisted: `ready --json`, its four-step order, and the
+  mutation contract are unchanged. The report file stays self-contained with no
+  external runtime dependency.
+- Report configuration accepts two more `fields` mappings, `class` and `due`.
+  `class` is a class of service from `expedite | fixed-date | standard |
+  intangible`; `expedite` lifts an item above every other ready item, an absent
+  value means `standard`, and an unrecognised value is ranked as standard and
+  reported in the report rather than dropped. `due` is an ISO calendar date
+  ordered by proximity. Both ride the existing extension-member channel, so no
+  core field carries them.
+- The commit-per-mutation invariant is documented. On a provisioned ledger,
+  every mutation must be committed to Git before the next mutating command,
+  and `claim-verify` is the reconciliation procedure for the exit 6
+  `publication-reconciliation-required` refusal. The mutation contract, the
+  work-claim contract, the README, and the installed skill's claimed and
+  unclaimed loops all state the rule and the loop it implies. The mutation
+  contract also records why validating against working-tree bytes was
+  rejected.
+- `claim capabilities --ledger <dir> --json` now advertises
+  `result.backend.write_serialization`. A provisioned Git-journal backend
+  reports `scope: "all-worktrees-of-one-repository"` and
+  `blocks_until: "peer-commit-visible-in-this-checkout"`; an unprovisioned
+  backend reports `scope: "none"`. This makes the serialization the shared
+  Git-common-directory journal already performed discoverable instead of
+  implied. The core `capabilities` envelope is unchanged; this change is not
+  one of the version 3 deltas.
+
+- A `date-before-created` or `date-before-updated` issue now carries
+  `item_created` and `item_updated` after `related_ids` — the target item's own
+  dates at refusal time, both dates on both codes, on `transition` and `patch`
+  alike. One refusal now states the whole acceptable date window, so correcting
+  the request no longer costs an `inspect` round-trip. No other issue code
+  changes shape; a consumer that validates issue members exactly must accept
+  six members for these two codes. This widening is the reason the core
+  contract version moves to 3 (see Changed, above).
+  The mutation contract and the installed skill now also state that `create`
+  derives `created` from the ULID timestamp, which is UTC, with the
+  across-midnight example that produces this refusal.
+
+### Documentation
+
+- **`create` stays journal-silent, and the work-claim contract now says why.**
+  Section 3.1 already stated that `create` records no claim-journal entry and
+  therefore never blocks a sibling worktree. It now records the decision to
+  keep that asymmetry and the three reasons behind it: create's publication is
+  already atomic, no-clobber, and byte-verified; journaling create would
+  serialize every worktree on the highest-volume mutation; and the remaining
+  exposure window closes at the item's first `transition` or `patch`. The
+  window is stated honestly — until that first journal-visible mutation an
+  out-of-protocol overwrite of a created item is not detected, and a commit
+  alone does not close the window, because reconciliation compares only the
+  revisions the journal expects. `test/create-journal-asymmetry.test.js` pins
+  both halves end to end. No behaviour changed.
+
+### Fixed
+
+- A claim-fence refusal no longer reaches the agent as
+  `mutation-outcome-unknown`. Both adapter engines classified every response
+  with the core envelope validator, so a fenced refusal — `namespace:
+  "ledger-mutation"`, `command: "<command>-v1"`, `contract_version: 1`, `state:
+  "unchanged"` — failed core validation and became "the mutation may have been
+  applied; inspect current state before retrying", on every fenced refusal on a
+  provisioned ledger, about a write that provably never ran. The adapter now
+  dispatches on the response domain first, exactly as the mutation contract's
+  section 2 rule requires, and validates a fenced refusal on the work-claim
+  contract's terms: `claimed-item-write-refused` on `create`,
+  `active-claim-write-refused` on `transition` and `patch`, and
+  `claim-store-unavailable` on any mutation, each with its pinned message, exit,
+  and permitted states, its read-back bound to the item the caller asked to
+  write, and its reason plus findings and remediation forwarded verbatim. A
+  `claim-store-unavailable` refusal that declares `state: "unknown"` stays an
+  unknown outcome, and so does any namespaced envelope the adapter cannot
+  classify. Adapter contract section 6.1 states the rule and the honest-outcome
+  guarantee; five conformance vectors pin it, the differential test replays each
+  through both engines, and no version moved in either domain.
+- A mutation on a claim-protected ledger now reads the complete ledger twice
+  instead of three times. Journal reconciliation and the mutation engine's
+  pre-lock phase were separate unlocked reads of the same directory inside one
+  claim-lock hold, and reconciliation writes nothing a complete load reads, so
+  the pre-lock phase reuses reconciliation's snapshot. On a 1,500-item
+  provisioned fixture a create fell from about 1.15 s to about 0.89 s and a
+  transition from about 1.17 s to about 0.91 s, matching one full load at about
+  0.29 s. The read under lock stays: it is what decides the revision
+  compare-and-swap and the lock-closure stability check, and every decision
+  drawn from the shared snapshot is re-made against it. A lock-closure retry
+  still reads fresh. No validation rule changed, and a mutation on a plain
+  directory is unaffected.
+- A mutation on a large provisioned ledger no longer spends its wall time in
+  process spawns. Git HEAD reconciliation read every committed item with its
+  own `git show`, one subprocess per item, serially; it now reads them with
+  one `git cat-file --batch` subprocess per 16 MiB of tree content. On a
+  1,500-item fixture a create fell from about 15.4 s to about 1.2 s and a
+  transition from about 15.4 s to about 1.3 s. The reconciliation reads the
+  same bytes for the same items, and no validation is skipped: candidate
+  validation still validates the complete ledger.
+
+- Every reconciliation finding that blocks a mutation now carries a
+  `remediation` string naming the path to act on and `claim-verify`.
+  `revision-regression`, `legacy-mutation-outcome-unknown`, and
+  `publication-outcome-unknown` previously blocked with no recovery action;
+  they now also carry `expected_path` when it is identifiable.
+
+- A committed `.wowbagger/layout.json` now binds the ledger's item directory.
+  `create` derives its path from that configuration. Validation rejects parsed
+  items outside it, special or symbolic layout files, and metadata-directory
+  aliases. Malformed configuration fails closed. Ledgers without the file
+  retain the root-level `<id>.md` layout.
+- A refused legacy mutation and a clean `claim-verify` now leave the ledger
+  working tree byte-identical. The tracked reconciliation log projects only
+  journal entries that record a decision, so per-invocation clock entries no
+  longer dirty it, and a successful legacy mutation now projects its own
+  entries before returning instead of one command later. Batch tooling no
+  longer needs to stage the log after a failure.
+- `claim-verify` now classifies stale writes as unauthorized revisions, missing
+  Git finalization, worktree synchronization, or pending claimed publication.
+  Working-tree deletions of an authorized Git revision are unauthorized.
+  Findings name the expected item path and give a direct recovery action.
+- The contracts and the skill now state that a provisioned ledger's claim
+  journal serializes every worktree of one repository, and that a recorded
+  write blocks mutations in the other worktrees until its commit is visible
+  there. `limits.cross_worktree_coordination: false` is documented as "the
+  core never synchronizes checkouts", not as independent worktree writes.
+  Both stale-write remedies, the moving-`expected_revision` trap, and the
+  failed copy-the-item-in workaround are documented and pinned by tests.
 
 ## 0.1.0-alpha.4 - 2026-08-14
 

package/README.md

@@ -14,7 +14,7 @@ putting a database or hosted service inside your repository.
 > scope is deliberately narrow: cooperative writers in one working copy, one
 > item at a time. A Claude Code adapter and plugin ship from this
 > repository; the adapter answers the negotiation surface of the harness-neutral
-> contract and passes all 183 assertions across all 15 cases on native Darwin.
+> contract and passes all 196 assertions across all 15 cases on native Darwin.
 > The Claude Code adapter declares Darwin `supported`; all other shipped adapter
 > platform declarations remain `unverified`. The shipped core mutation contract
 > and adapter contract are version 2; their frozen version 1 definitions are not
@@ -36,7 +36,7 @@ Install the core CLI, then verify it:
 ```sh
 npm install -g wowbagger@next   # public npm prerelease
 # or, from this release's Git tag:
-# npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.4
+# npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.5
 wowbagger capabilities --json
 ```
 
@@ -54,6 +54,38 @@ core contract version 2. It refuses an absent or incompatible core. It will not
 fall back to editing ledger files by hand, because that would bypass validation
 and atomic publication.
 
+Decide where items live **before your first `create`**. A ledger publishes items
+to `<ledger>/<id>.md` unless a committed `<ledger>/.wowbagger/layout.json` binds
+a subdirectory:
+
+```sh
+mkdir -p path/to/ledger/.wowbagger path/to/ledger/items
+echo '{"layout_version":1,"items_directory":"items"}' > path/to/ledger/.wowbagger/layout.json
+```
+
+`layout_version` must be `1` and `items_directory` names the committed item
+directory. `create` then publishes atomically to `<items_directory>/<id>.md`,
+and validation rejects parsed items outside it. Commit the directory the file
+names — `create` publishes into an existing directory and does not make one.
+Nothing is renamed after a create. Cores at `0.1.0-alpha.4` and earlier ignore
+the file and publish every item at the ledger root.
+
+On such a core, relocating an item by hand has a trap. `create` writes an
+untracked file, so `git mv` refuses the path it just published; an unchecked
+batch then runs `git add -A` and commits the item at the ledger root, where it
+silently stays. Use plain `mv`, then `git add` both paths, and check the exit
+code of every command before the commit:
+
+```sh
+mv path/to/ledger/<id>.md path/to/ledger/items/<id>.md || exit 1
+git add path/to/ledger || exit 1
+```
+
+A committed item outside the configured items directory then fails validation
+and refuses every read and every guarded mutation on that ledger, including
+ones that never touch it. The refusal names the expected path and the
+relocation that repairs it.
+
 For an isolated consumer pilot, create or select the disposable worktree before
 the agent starts. Then launch a new session with that worktree as its project
 root. Follow the [isolated dogfood pilot runbook](docs/isolated-dogfood-pilot.md);
@@ -72,7 +104,7 @@ two supported install routes:
 - **npm registry** — `npm install -g wowbagger@next` installs the current
   prerelease.
 - **git tag** —
-  `npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.4` installs this
+  `npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.5` installs this
   release. Installing at a ref installs the core and every adapter that ref
   carries.
 
@@ -136,7 +168,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.4  # immutable Git release
+npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.5  # immutable Git release
 git pull && npm ci                            # or: a direct checkout
 ```
 
@@ -153,12 +185,14 @@ wowbagger capabilities --json
 ```
 
 The plugin requires its exact core distribution version and top-level core
-`contract_version: 2`. Direct API consumers must check the contract version
+`contract_version: 3`. Direct API consumers must check the contract version
 they support; installed plugin users must also keep the plugin and core
 distribution versions equal.
 
 The shipped adapter selects only adapter contract version 2 and requires core
-contract version 2. A v1-only consumer receives
+contract version 3. The adapter contract and the core contract are separate
+version domains: the adapter stays at 2 while the core moves to 3. 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
@@ -192,6 +226,11 @@ core, these are the changes most likely to touch you:
   `core.status: "triage"`, and the refusal for a caller-supplied `status`
   names the accepting transition (triage to backlog) that makes an item
   ready.
+- **Bind a subdirectory layout in the ledger, not in each runner.** Commit
+  `<ledger>/.wowbagger/layout.json` with
+  `{"layout_version":1,"items_directory":"items"}`. `create` then derives
+  `<ledger>/items/<id>.md`; validation rejects parsed items outside `items/`.
+  Without the file, the compatible layout remains `<ledger>/<id>.md`.
 
 ## Why the name?
 
@@ -257,9 +296,9 @@ This checkout ships three adapter packages on one shared entrypoint runtime:
 [`adapters/claude-code/`](adapters/claude-code/), [`adapters/codex/`](adapters/codex/),
 and [`adapters/opencode/`](adapters/opencode/). Each answers the section 3.3 bootstrap
 wire with its own identity and honest host declaration. The native Darwin
-Claude Code report passes all 183 assertions across all 15 cases — run
+Claude Code report passes all 196 assertions across all 15 cases — run
 `node spec/run-adapter-implementation.js` to see the evidence. Codex and
-OpenCode share the version 2 engine and execute all 183 assertions with
+OpenCode share the version 2 engine and execute all 196 assertions with
 `--target codex` or `--target opencode`, but both target reports remain `fail`
 pending target-specific evidence. Invocation forwarding, path and limit guards,
 approval, and context all enter through the shared shipped engine. Platform
@@ -333,7 +372,9 @@ relative `--out` overrides resolve from the caller's working directory.
   "fields": {
     "area": "/priority_area",
     "complexity": "/complexity",
-    "rank": "/priority_rank"
+    "rank": "/priority_rank",
+    "class": "/class",
+    "due": "/due"
   },
   "swarm": { "eligible_complexities": ["small", "medium"] }
 }
@@ -341,9 +382,65 @@ relative `--out` overrides resolve from the caller's working directory.
 
 `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 shows canonical readiness, filters,
-sorting, grouping, three detail levels, terminal history, and area-diverse
-ready batches. It contains no external runtime dependency.
+`area` and `complexity` fields. The report fetches nothing at view time.
+
+The report 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), the **evidence layer**
+(aging buckets, weekly arrivals against completions, accept-to-complete cycle
+time, and a Monte Carlo forecast as 50 and 85 percent bands), and 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 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.
+
+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
+`1.80.0` with its upstream SHA-256 recorded in `VERSIONS.json` and pinned by a
+test. It is inlined into the report at generation time. Nothing is fetched from
+a CDN, at generation time or at view time, and the report's content security
+policy forbids every remote load. The bundle costs roughly 1.3 MB of the
+report's size; the report stays one self-contained file you can attach, open
+offline, and share.
+
+Without WebGL the graph section says so and expands its own roster instead: one
+row per node, carrying that node's number, title, status, age, leverage, and
+reasons. No decision-relevant content exists only in the 3D view.
+
+The recommended order is a report-layer derivation. It is recomputed from
+ledger bytes at render time, never persisted, never a mutation, and it does not
+change `ready`: the core still selects and sorts by priority, created date,
+then ID. Ordering runs as separate, visible steps rather than one opaque score
+— expedite class, then due proximity, then transitive unblocking leverage over
+`depends_on`, then epic enablement from `parent`, then priority, then age, then
+the mapped `complexity` as a WSJF-style size denominator — and every step that
+placed an entry is printed beside it.
+
+Two mapped fields carry the value dimensions the schema deliberately does not:
+
+- **`class`** — a class of service, one of `expedite`, `fixed-date`,
+  `standard`, or `intangible`. `expedite` lifts an item above every other ready
+  item. An absent value means `standard`. An unrecognised value is ranked as
+  standard and reported by number in the report, never silently dropped.
+- **`due`** — an ISO calendar date. The nearest due date sorts first and an
+  overdue one sorts first of all; an item with no due date sorts behind every
+  dated one at that step.
+
+Both ride the ordinary extension-member channel, so the core neither reads nor
+validates them. `complexity` weighs `xs`/`s`/`small` as 1, `m`/`medium` as 2,
+`l`/`large` as 3, and `xl`/`extra-large` as 5; any other value carries no
+weight and is shown as written.
 
 This repository keeps its report configuration in
 `ledger/.wowbagger/report.json`. Generate the ignored local report with:
@@ -363,6 +460,23 @@ nothing else — under the same lock and compare-and-swap. See
 [the mutation contract](docs/mutation-contract.md) for the JSON request,
 response, recovery, and scope details.
 
+### Diagnosing an invalid ledger
+
+One invalid item refuses every read and every guarded mutation on that ledger,
+including commands that never touch it. That refusal is the diagnosis, and no
+command asks you to parse the Markdown by hand:
+
+- `validate --json` lists every error. An error whose repair the validator can
+  derive also carries `expected_path` and a `remediation` naming the repair.
+- `inspect` still refuses with exit 3 `ledger-invalid` — a revision from an
+  unjudged ledger must never look like a mutation precondition — but the
+  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.
+
 `provision` binds one ledger namespace to the repository. `claim` manages
 durable acquire, read, renew, and release decisions. `publish-claimed` accepts
 the exact candidate item bytes and fences their publication against the active
@@ -383,6 +497,51 @@ refuses rather than guessing. The shipped plugin skill also requires its exact
 core distribution version. Direct checkout use—`./bin/wowbagger.js` from a
 clone—remains supported and is what this repository's own ledger uses.
 
+## Commit each mutation before the next one
+
+On a **provisioned** ledger — one where `provision` has bound a namespace and
+`claim capabilities` reports `mode: "merge-coordinated"` — there is one
+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 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 transition --ledger path/to/ledger --input next.json --json
+```
+
+Skip the commit and the next command returns exit 6:
+
+```json
+{"ok":false,"namespace":"ledger-mutation","command":"create-v1","contract_version":1,
+ "state":"unchanged","error":{"code":"claim-store-unavailable",
+ "message":"The durable claim store is unavailable.",
+ "details":{"reason":"publication-reconciliation-required","findings":[{
+   "code":"stale-write-detected","reason":"git-finalization-required",
+   "expected_path":"wb_....md",
+   "remediation":"Commit wb_....md in Git, then run claim-verify."}]}}}
+```
+
+`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.
+
+Full rules, the other blocking finding codes, and why validating against
+working-tree bytes was rejected are in
+[the mutation contract](docs/mutation-contract.md) section 12 and
+[the work-claim contract](docs/work-claim-contract.md).
+
 ## Verify a checkout
 
 The development workflow is intentionally self-hosted: edit code and ledger
@@ -486,7 +645,7 @@ It is the durable work ledger beneath those systems.
 - Stabilize the machine-readable command contract and compatibility evidence.
 - 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 183 native assertions. Other adapter targets and
+  `supported` after passing all 196 native assertions. Other adapter targets and
   platform declarations remain unverified.**
 - Document the generic tool contract for other agent harnesses.
 - Implement merge-coordinated work claims for cooperating Git worktrees.

package/adapters/claude-code/wowbagger-adapter.json

@@ -4,7 +4,7 @@
   "adapter_version": "0.1.0",
   "adapter_contract_versions": [2],
   "bootstrap_wire_version": 1,
-  "required_core_contract_version": 2,
+  "required_core_contract_version": 3,
   "entrypoints": {
     "describe": {
       "kind": "command",

package/adapters/codex/wowbagger-adapter.json

@@ -4,7 +4,7 @@
   "adapter_version": "0.1.0",
   "adapter_contract_versions": [2],
   "bootstrap_wire_version": 1,
-  "required_core_contract_version": 2,
+  "required_core_contract_version": 3,
   "entrypoints": {
     "describe": {
       "kind": "command",

package/adapters/opencode/wowbagger-adapter.json

@@ -4,7 +4,7 @@
   "adapter_version": "0.1.0",
   "adapter_contract_versions": [2],
   "bootstrap_wire_version": 1,
-  "required_core_contract_version": 2,
+  "required_core_contract_version": 3,
   "entrypoints": {
     "describe": {
       "kind": "command",