wowbagger 0.1.0-alpha.9 → 0.5.0

package/docs/work-claim-contract.md

@@ -1,11 +1,11 @@
 # Work-claim contract
 
 Status: accepted protocol design. The standalone Wowbagger CLI implements the
-version 2 claim operations and the merge-coordinated Git-journal profile for
+version 3 claim operations and the merge-coordinated Git-journal profile for
 provisioned Git-backed ledgers. The no-I/O reference model and conformance
 fixtures remain the oracle for the strict fenced protocol.
 
-This document defines version 2 of the transport-neutral work-claim and
+This document defines version 3 of the transport-neutral work-claim and
 claimed-publication API, plus the merge-coordinated capability profile. The
 words MUST, MUST NOT, SHOULD, and MAY are normative. JSON examples show objects
 before compact serialization; a CLI prints exactly one compact JSON object
@@ -23,6 +23,21 @@ Generic consumers migrate without a wire change: they first identify the
 work-claim envelope by `namespace: "work-claim"`, then require the advertised
 `api_version`.
 
+### Version 3
+
+Version 3 retains every version 2 request, response, state, exit, fencing, and
+recovery rule except for targeted verification. `claim-verify` accepts optional
+`--id <wb_...>` without requiring that item to exist in the local checkout.
+Bare verification remains strict repository-wide mode.
+
+Every success result adds `verification_scope`: `{"mode":"repository"}` for
+the bare command, or `{"mode":"target-item","item_id":"wb_..."}` for a target.
+Every returned finding adds `blocks_verification_scope`. Target mode keeps all
+repository findings visible but derives `ok`, exit status, and `state` only
+from findings that block that target. Global safety findings still block every
+target. This additive response and new CLI input move the negotiated API while
+the top-level claim-envelope `contract_version` remains `1`.
+
 ### Version 2
 
 Version 2 retains every version 1 request, response, state, exit, fencing, and
@@ -86,20 +101,25 @@ carries one operating rule that binds every caller:
 
 **Commit each mutation to Git before running the next mutating command.**
 
-A merge-coordinated backend validates recorded revisions against Git `HEAD`,
-never against working-tree bytes. An uncommitted mutation is an unreconciled
-mutation. The next `create`, `transition`, `patch`, or `publish-claimed`
-therefore refuses with exit 6 `claim-store-unavailable` and
-`details.reason: "publication-reconciliation-required"` rather than writing on
-top of work that is not yet durable.
-
-`claim-verify` is the reconciliation procedure for that refusal. The loop is
-write, commit, `claim-verify`, next write. Section 6 defines `claim-verify`,
-section 7 defines the refusal the legacy write paths emit, and section 8
-defines the error envelope. The [mutation
+A merge-coordinated backend reconciles recorded revisions with Git `HEAD` and
+the working tree. It refuses the next mutation when it finds an
+`unauthorized-revision`, requires Git finalization, or requires synchronization
+for the target item. A `worktree-synchronization-required` finding on an
+unrelated item remains visible without blocking 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 is not finalization: callers still follow write,
+commit, `claim-verify`, next write.
+
+`claim-verify` is the reconciliation procedure for every refusal. Section 6
+defines `claim-verify`, section 7 defines the refusal the legacy write paths
+emit, and section 8 defines the error envelope. The [mutation
 contract](mutation-contract.md) section 12 states the same rule for
-`create`, `transition`, and `patch` callers, together with the
-considered-and-rejected alternative of validating against working-tree bytes.
+`create`, `transition`, `parent-migrate`, `snooze`, and `patch` callers,
+together with the considered-and-rejected alternative of validating only
+against working-tree bytes.
 
 The optional `--auto-commit` flag performs that whole loop inside one
 invocation on a provisioned ledger: it runs the pre-mutation `claim-verify`,
@@ -123,6 +143,15 @@ runs `claim-verify`. Repeating it creates no second commit. [Mutation
 contract](mutation-contract.md) section 13 defines the flag, its strict
 preflight, its commit sets, its failure envelopes, and this command.
 
+When a provisioned ledger is opened in a fresh Git clone, the local claim
+journal may not exist even though `HEAD` carries a committed reconciliation
+log. The first reconciliation hydrates the local journal from that committed
+projection, preserving its sequence gaps with non-projected clock entries. A
+lock-free claim read projects the same committed evidence in memory without
+writing the journal. This makes committed claim and publication history visible
+without inventing new authority; later writes still require the clone's own
+Git history to finalize them.
+
 ## 2. Ledger namespace and identity
 
 Every claim key is the immutable tuple `(ledger_namespace, item_id)`. No state,
@@ -178,7 +207,7 @@ most `18446744073709551615`. Epochs never wrap, decrement, or get reused.
     "operations": {
       "work_claim": {
         "supported": true,
-        "api_version": 2,
+        "api_version": 3,
         "mode": "fenced",
         "claim_protected_publication": true,
         "fencing_enforced_at": "ledger-publication-commit-boundary",
@@ -268,7 +297,7 @@ A provisioned Git-journal backend MAY instead report:
   "operations": {
     "work_claim": {
       "supported": true,
-      "api_version": 2,
+      "api_version": 3,
       "mode": "merge-coordinated",
       "claim_protected_publication": true,
       "fencing_enforced_at": "git-history-reconciliation",
@@ -313,38 +342,199 @@ the local working tree and the local Git HEAD. A revision written in another
 worktree is absent in both, so reconciliation reports
 `stale-write-detected` and the mutation refuses with exit 6
 `claim-store-unavailable`, reason `publication-reconciliation-required` only
-when the mutation targets that item. `claim-verify` remains repository-wide and
-reports every unresolved finding.
+when the mutation targets that item. Bare `claim-verify` remains
+repository-wide. `claim-verify --id <item>` reports every unresolved finding
+but blocks only on that target and global safety barriers.
 
 The plain statement: **a recorded private write in one worktree blocks
 mutations targeting that item, not unrelated item mutations in sibling
 worktrees.** Own uncommitted work and out-of-protocol revisions remain global
 safety barriers. This is item-scoped availability, not exclusive dispatch.
+`create` reads that same reconciliation with one extra barrier, because it is
+the one mutation whose output depends on an identity no caller supplied.
+
+**Superseded: create no longer stays journal-silent.** Through alpha.13 this
+contract decided that create records nothing, and three reasons held that
+decision: create already protects its own instant, because publication is
+atomic, refuses to clobber an existing path, and verifies the published bytes
+exactly; a journaled create would serialize every worktree on the
+highest-volume mutation; and the remaining exposure window was judged narrow
+because it closed at the item's first journal-visible mutation.
+
+Item #181 overturns that decision. The first reason answers the wrong
+question. Create's atomic instant protects the path it publishes to, and
+nothing protected the `number` it derives. A schema-version-2 create takes
+`1 + max(existing numbers)` from the items its own checkout holds, so two
+worktrees that have not integrated each other's commits derive the same number
+and both publish. They need not overlap in time: a create today and a create
+tomorrow collide as reliably as two simultaneous ones, because the loser is a
+stale checkout rather than a lost race, and a wider mutex cannot fix a
+sequential failure. Only durable evidence can. `number` is immutable and
+`patch` correctly rejects it, so an undetected collision surfaces at
+integration as a global `duplicate-number` validation failure that stops the
+whole ledger.
+
+**The fixed ordering.** On a provisioned ledger a create is a legacy mutation
+like any other, and the shared namespace lock is held across every step:
+
+1. Acquire the shared namespace lock.
+2. Reconcile the repository state and apply the allocation fence below.
+3. Load this worktree's ledger.
+4. Acquire the item, relation, and number-index lock closure.
+5. Reload and validate the ledger under those locks.
+6. Derive `1 + max(existing numbers)`.
+7. Serialize the candidate item.
+8. Validate the complete candidate ledger.
+9. Reserve journal capacity, then append the create intent.
+10. Publish with atomic no-clobber semantics.
+11. Verify the final path holds the exact candidate bytes.
+12. Append the committed or aborted terminal.
+
+A create appends its `legacy-mutation-intent` with `command: "create-v1"`
+before any byte reaches the item path, and it appends that intent only after
+step 8, so a refusal the command would have returned anyway records no
+attempt. The intent carries `expected_revision: null`, which is valid only for
+`create-v1`; every other command still requires a string revision. The
+committed terminal is `legacy-mutation` with `command: "create-v1"`. The
+create abort carries `command: "create-v1"` and `observed_revision: null`,
+while an abort for any other command remains valid without `command` and still
+requires a string revision. No entry records the assigned number: the
+candidate revision binds the complete item bytes, and the ledger stays the one
+number authority.
+
+**The allocation fence.** Create reconciles with its own item as the target,
+exactly like every other mutation, and one extra barrier reads the result.
+Every global finding blocks create because it blocks every write:
+`git-finalization-required` for this worktree's own uncommitted authorized
+bytes, `unauthorized-revision` for out-of-protocol bytes, and an unresolved
+`legacy-mutation-outcome-unknown`. On top of those, any coordinated item this
+checkout does not hold blocks `create`, because the journal records a
+committed terminal for an item whose number this working ledger cannot read,
+so the next number derived here may be one a sibling already published. A
+stale revision of an item this checkout holds does not block `create`: a
+number is immutable, so the local maximum is already correct, and that finding
+keeps its ordinary target scope.
+
+**The old exposure window is closed on a provisioned ledger.** The journal used
+to learn of an item only at its first `transition` or `patch`, so an
+out-of-protocol overwrite before that mutation went unreported. A journaled
+create records an authorized revision at the item's birth, so the ordinary
+surfaces cover the item from then on: an out-of-protocol overwrite reports
+`unauthorized-revision` and the next mutation refuses. An unprovisioned or
+non-Git ledger keeps only its local number-index lock and its atomic
+no-clobber publication; nothing there coordinates across checkouts, and nothing
+here defends against an actor that bypasses this tool.
+
+**The refusal.** A fenced create refuses before it allocates a number and
+before it writes a byte:
+
+```text
+exit: 6
+ok: false
+namespace: "ledger-mutation"
+command: "create-v1"
+contract_version: 1
+state: "unchanged"
+error.code: "claim-store-unavailable"
+error.details.reason: "publication-reconciliation-required"
+```
 
-**Decided: create stays journal-silent.** The asymmetry is intended. Three
-reasons hold it:
-
-1. Create already protects its own instant. Publication is atomic, it refuses
-   to clobber an existing path, and it verifies the published bytes exactly
-   after the write. A journal entry adds no protection to that instant.
-2. A journaled create would serialize every worktree on the highest-volume
-   mutation. The field reports name create as the most frequent mutation and as
-   the most frequent victim of a block. Making create a blocker as well as a
-   victim multiplies a cost that consumers already report.
-3. The remaining exposure window is real but narrow, and it closes at the
-   item's first journal-visible mutation.
-
-**The exposure window, stated honestly.** The journal does not know a created
-item until that item's first journal-visible mutation, which is a `transition`
-or a `patch`. Until then an out-of-protocol overwrite of the item's bytes is
-not detected. A commit alone does not close the window, because reconciliation
-compares only the revisions the journal expects, and the journal expects none
-for that item. From the first `transition` or `patch`, the ordinary surfaces
-cover the item: with the authorized revision committed, an out-of-protocol
-overwrite of the working-tree bytes reports `unauthorized-revision` and the
-next mutation refuses. Inside the window, only an actor that bypasses this tool
-can overwrite the item, and this protocol does not defend against that actor.
-It is merge-coordinated, not exclusive.
+`error.details.findings` names the item whose authorized create this checkout
+cannot see, and each finding's own `remediation` string stays authoritative:
+commit this worktree's bytes for `git-finalization-required`; synchronize the
+named sibling revision when `owner_ref` names a live worktree; inspect the
+reachable or dangling history and restore or explicitly adopt reviewed bytes
+for a locally absent or reachable-unowned revision; and restore or adopt for
+unauthorized bytes. The reproduced stale-sibling case is locally absent on both
+surfaces, so it renders the cannot-be-established sentence, which is an
+instruction to inspect and integrate, never an instruction to wait. Once the
+ledger validates and `claim-verify` exits 0, retry the same request ID: the
+refusal published no byte, so the retry is an ordinary no-clobber create and
+takes the next number. The fence does not trap recovery — `claim-verify` stays
+read-only, `claim-adopt` keeps its explicit override, claim release stays
+available under barriers, and Git synchronization was never this tool's to
+block.
+
+**Recovery from an interrupted create.** An intent with no terminal resolves on
+the next invocation from the item path alone: the candidate revision present
+appends the committed terminal, the path absent appends the create abort, and
+any third revision reports `legacy-mutation-outcome-unknown` as a global
+barrier. Recovery never guesses a number and never publishes an item. Because
+capacity for the intent, one clock entry, and one terminal is reserved before
+the intent is appended, an exhausted journal refuses unchanged before
+publication rather than stranding an unresolvable attempt.
+
+**Create owns its item and its reconciliation log.** A successful create is
+journal-visible from the item's birth, so its `changed_paths` and its
+`--auto-commit` commit set are exactly the created item and
+`<ledger>/.wowbagger/reconcile-<namespace>.md`. Owning the log it writes is not
+permission to absorb residue: a reconciliation log already dirty before the
+invocation is foreign, and create still refuses it.
+
+**Commit every create before the next mutation.** A create has no authorized
+predecessor — there is no earlier revision of an item that did not exist — so
+Git `HEAD` is the only surface that can hold its authorized bytes, and an
+uncommitted create reports the global `git-finalization-required` until it is
+committed. A `patch` or `transition` may instead occupy the documented
+authorized predecessor/successor window and run before its predecessor is
+committed, but that window is an accepted overlap, not a license: commit every
+mutation before the next one. Batch create is permanently rejected for the
+direct-Markdown architecture. The supported bulk pattern is serial
+`create --auto-commit`, one invocation and one commit per successful item; see
+the [accepted batch-create decision](design/2026-08-30-batch-create.md).
+
+**Cost.** A provisioned create already took the namespace lock, replayed the
+journal, loaded the ledger, read Git `HEAD`, and reconciled. The fence changes
+which findings refuse; it adds no new Git roster or history traversal to a
+clean create, and the measured cost of the change is two extra fsync'd journal
+appends. The durable cost is journal growth: each successful create adds one
+intent and one committed terminal, so with no other activity the
+65,536-entry limit permits at most 21,845 three-entry create cycles and the
+8 MiB byte limit may bind first. Other claim and mutation activity lowers that
+ceiling. Capacity is checked before publication and fails closed with exit 6
+`claim-store-unavailable`, reason `journal-capacity-exceeded`, and `unchanged`;
+no current-operation intent, terminal, or item byte is published. The same
+reason applies to claim lifecycle, verification, adoption, publication reads,
+and every legacy mutation while capacity is known before publication. A
+genuine persistence failure remains `clock-floor-persistence-failed`, and an
+ambiguous outcome after an intent remains an outcome-unknown refusal. Journal
+history is never truncated, and automatic compaction is not part of this
+contract.
+
+A ledger that already carries duplicate numbers is item #182 recovery work and
+is repaired through the separate `ledger-repair` contract, not through claim
+operations. Run `number-repair-proposal --ledger <dir> --json`, review the
+complete mapping, then run `number-repair --ledger <dir> --input <repair.json>
+--json`. The repair command runs only when duplicate-number errors are the
+complete validation failure, preserves ULID identities and relation values, and
+publishes all affected items under the shared namespace fence. Arbitrary hand
+edits remain unsupported because they can damage IDs, paths, or references.
+
+**What alpha.14 guarantees, and what it does not.** Alpha.14 closes the
+reported PropertyCompass2 collision: cooperating alpha.14 worktrees of one
+clone that share one Git common directory can no longer commit two items
+carrying the same number, because every such create is visible through the
+shared journal before publication even without branch integration. Separate
+clones, separate machines, alpha.13 writers before the hard cutover, and
+noncooperating writes stay outside that fence and still rely on branch
+integration plus `validate`.
+
+**The upgrade is a hard cutover.** Alpha.13 cannot read a `create-v1` legacy
+intent. Executed against a ledger whose shared journal already carries one, its
+create exits 6 with `error.code` `claim-store-unavailable`, message
+`The durable claim store is unavailable.`, and `error.details.reason`
+`claim-store-unreadable`, leaving the state unchanged and writing no item. That
+fail-closed behavior is the compatibility guarantee: an old writer cannot
+commit another duplicate. It is also the operational limit, because alpha.13 is
+immutable and emits a generic unreadable-store message rather than upgrade
+guidance. Read that exact refusal as **this repository was written by a newer
+Wowbagger; upgrade this worktree to continue.** There is no automatic migration
+and no mixed-version grace period: upgrade every writer in one Git coordination
+domain before the first alpha.14 create. If a partial upgrade writes the new
+grammar first, every remaining alpha.13 worktree stops making claim-protected
+mutations until it is upgraded. Item #185 owns the general ability of a running
+old binary to diagnose its own version drift; no change here can retrofit a
+message into an already-published executable.
 
 **`unauthorized-revision` has two remedies, and only one of them is
 destructive.** Restoring the authorized revision discards the out-of-protocol
@@ -359,26 +549,158 @@ Each refusal carries a `reason` that separates the cases:
 | `reason` | Cause | Remedy |
 |---|---|---|
 | `git-finalization-required` | this worktree wrote the item and has not committed it | commit here, then `claim-verify` |
-| `worktree-synchronization-required` | another worktree wrote the item | wait for the owner named by `owner_ref`/`owner_commit`, then synchronize this checkout and run `claim-verify`; if `owner_unavailable` is true, inspect reachable or dangling commits and use explicit restore/adopt authority |
+| `worktree-synchronization-required` | another worktree wrote the item | wait for the owner named by `owner_ref`/`owner_commit`, then synchronize this checkout and run `claim-verify`; if `owner_unavailable` is true, follow the finding's `remediation` (section 3.2 step 4) |
 | `unauthorized-revision` | the item was changed outside the protocol | restore the authorized revision and discard the edit, then `claim-verify`; or adopt the committed revision and keep the edit, then `claim-verify` (section 3.3) |
 
+**Scope is the coordinator's judgement, not a published member.** What a
+finding refuses — every write, only a write against the item it names, or
+nothing — is decided from the topology and travels beside the finding, never
+inside it. No response carries it. A consumer MUST NOT infer scope from the
+`reason` string, from the `remediation` sentence, or from whether `owner_ref`
+is present: those are diagnostics for a person, and reading them as a scope
+signal is exactly how alpha.11 treated an out-of-protocol revision as advisory
+synchronization. The only supported scope signal is the refusal itself: a
+mutation that returns exit 6 was blocked, and one that returns exit 0 was not.
+
+Ownership on the current symbolic ref is never reported as a foreign worktree
+owner, and a detached `HEAD` applies the same guard through its reachable
+commit history. If the expected revision is already reachable from the current
+checkout, a same-branch regression cannot be repaired by waiting for another
+worktree; it remains `unauthorized-revision` and blocks unrelated mutations.
+This distinguishes a real sibling's uncommitted successor from history the
+current checkout already owns.
+
+**`owner_ref` names an active named worktree, and nothing else.** Owner
+evidence is the worktree roster Git reports live, searched this checkout first,
+then every live worktree that has a branch checked out, ordered by branch ref
+and then by path so one revision carried by several live worktrees always names
+the same owner. A bare record, a record Git marks prunable, and a worktree
+whose `HEAD` names no commit are excluded. `owner_ref` is always the branch of
+one of those live worktrees, and `owner_commit` is the commit in that
+worktree's history whose item bytes are the expected revision.
+
+Reachability alone is never ownership. A tag, a remote-tracking ref, a branch
+no worktree has checked out, and a live worktree on a detached `HEAD` can each
+reach the expected revision while naming nobody who could publish it. All of
+them, and a revision no reachable commit carries at all, produce
+`owner_unavailable: true` and no `owner_ref`. So `owner_unavailable` means one
+of three things: the expected revision is not reachable at all, a live sibling
+holds it on a detached `HEAD`, or it is reachable only from refs no active
+worktree has checked out.
+
+Three `owner_unavailable` remediation sentences separate those cases. The
+sentence naming ownership that cannot be established from reachable refs is
+emitted only when this checkout has no item path and `HEAD` has none either, so
+the item has never existed here. A revision Git does reach — from a tag, a
+remote-tracking ref, a branch no worktree has checked out, or a live worktree on
+a detached `HEAD` — gets the sentence saying the revision is reachable in Git
+while no active named worktree owner is established. Its remedy is to inspect
+the reachable history and restore or explicitly adopt reviewed bytes, then run
+`claim-verify`; there is no commit left to wait for. Only a revision no
+reachable commit carries at all gets the not-yet-reachable sentence, whose
+remedy is to wait for the owning worktree to commit, then synchronize this
+checkout and run `claim-verify`.
+
+Through alpha.13 the reachable cases were given the not-yet-reachable sentence
+too, which told a reader to wait for a commit Git already had. The wait never
+ended, because no named worktree was ever going to publish those bytes. The
+`reason`, the codes, the scope, and the finding members are unchanged; only the
+`remediation` text for the reachable-unowned cases is corrected.
+
+**Writer identity.** A legacy mutation and a claimed publication record the
+worktree that authorized them in their journal entries as
+`writer_worktree_id`: `legacy-mutation-intent`, `legacy-mutation`,
+`publish-intent`, and `publish-final`. The field is optional on all of them: an
+entry written before the field existed, which is every entry alpha.12 and
+earlier wrote, stays valid, attributes nothing, and leaves the expected writer
+`unknown`. Writer attribution alone therefore cannot turn such a finding into a
+global barrier: it stays advisory `worktree-synchronization-required`. Local
+state and current-checkout ownership are still judged first, and both remain
+global barriers whatever the entry records. A publication resolves its identity
+once under the claim lock, so its intent and its terminal name one writer, and
+a terminal that recovery reconstructs after a lost response carries the
+identity its intent recorded. When the journal names the current worktree as
+the writer of the expected revision and no reachable ref carries that revision,
+no sibling can ever produce it, so the finding is
+`unauthorized-revision` and blocks every mutation instead of
+`worktree-synchronization-required`, which blocks only its own item.
+
+Recording the field on publication entries is an additive optional journal
+change, so core `contract_version` stays `5` and every public request, success
+envelope, and refusal envelope is unchanged. The item #122 lock-coarsening
+parity golden, `test/publication-parity-baseline.json`, was regenerated to
+record it: that recording is a work-claim contract change, never routine
+fixture maintenance.
+
+**What that identity discloses.** The identity is an opaque random UUID,
+created once per worktree in that worktree's private Git directory. It contains
+no path, branch, ref, hostname, user, or machine data. Journal entries are
+projected into the tracked reconciliation log, so the identity persists in
+committed Git history: any reader of that history can correlate every entry
+written from one worktree, and an identity stays in that history indefinitely
+after the worktree it named is removed. It never becomes a claim owner, and no
+protocol decision reads it other than the writer comparison above.
+
+**Ambiguous identity.** A UUID names one worktree. Before it reasons from a
+recorded writer, the coordinator enumerates the worktrees Git currently reports
+live and reads the identity each one already holds; it creates none. Two live
+worktrees answering to one UUID, or a roster the coordinator could not finish
+reading, refuses `claim-verify`, every claim-protected mutation,
+`publish-claimed`, and `claim-adopt` before anything is classified or written.
+The refusal keeps the existing exit `6`, `claim-store-unavailable`,
+`claim-store-unreadable`, `state: "unchanged"` form and adds one
+`error.details.identity_diagnostic`: `code: "duplicate-worktree-identity"` with
+`worktree_id` and `live_worktree_count`, or `code:
+"worktree-enumeration-failed"` with no further member. Auto-commit surfaces the
+same diagnostic inside its `auto-commit-preflight-failed` details with
+`retryable: false`. Nothing else about the envelope changes, and core
+`contract_version` stays `5`.
+
+Detection covers only what Git reports live. A worktree Git marks prunable —
+including one whose path is temporarily unavailable or unmounted — is excluded,
+so a duplicate identity held there is not detected until Git sees that worktree
+live again. Removing a worktree removes the private Git directory that held its
+identity, and nothing restores it: a worktree recreated at the same path earns
+a new UUID, and the removed UUID stays in journal history attributing nothing.
+
 ### 3.2 Recovering from a foreign-writer block
 
 1. Stop writing the affected item in the blocked worktree. Unrelated item
    mutations may proceed when the finding is only
    `worktree-synchronization-required`.
+
 2. Read the finding. It names the item path and expected revision. When Git can
    prove ownership, it also names `owner_ref` and `owner_commit`; otherwise it
    carries `owner_unavailable: true`.
 3. If an owner is named, WAIT for that owner to publish the commit, then
    synchronize this checkout to it. Do not merge unrelated live work.
-4. If ownership is unavailable, inspect reachable or dangling commits. Restore
-   the exact authorized bytes or use explicit `claim-adopt` authority after
-   review. Do not copy peer working-tree bytes.
-5. Run `claim-verify --ledger <dir> --json` in the blocked worktree and require
-   exit 0.
+4. If ownership is unavailable, the `remediation` string separates three cases.
+   When it says the expected revision is not yet reachable, the owning
+   worktree has not committed it yet: wait as in step 3, then synchronize.
+   When it says the revision is reachable in Git while no active named worktree
+   owner is established, do not wait: inspect the reachable history that carries
+   it, then restore the exact authorized bytes or use explicit `claim-adopt`
+   authority after review. When it says ownership cannot be established from
+   reachable refs, inspect reachable or dangling commits and remedy it the same
+   way. In neither inspection case do you copy peer working-tree bytes.
+5. Run `claim-verify --ledger <dir> --id <finding.item_id> --json` in the
+   blocked worktree and require exit 0.
 6. Resume the affected item.
 
+Auto-commit applies this target scope both before and after its Git commit. A
+successful mutation requires a valid ledger and no findings blocking the target
+item, not a globally empty findings list. Nonblocking findings remain visible
+in targeted verification.
+
+**A target-scoped success is not a globally clean claim store.** The two scopes
+answer different questions and a caller MUST NOT substitute one for the other.
+`claim-verify --id <item>` keeps every finding visible, marks each with
+`blocks_verification_scope`, and derives its exit from that item plus global
+barriers. Bare `claim-verify` remains strict repository diagnosis and exits 6
+while any item carries a blocking finding. A cooperating worker can therefore
+finish its own item while bare verification still reports sibling work. Do not
+hand-edit or adopt a sibling's item to force either scope clean.
+
 `claim-verify` in the writing worktree finalizes that worktree's own state; it
 does not make a sibling checkout able to see the item. Synchronization or
 explicit recovery is still required for the affected item.
@@ -420,10 +742,12 @@ answering with `namespace: "work-claim"`, `command: "claim-adopt"`, and
 mutation runs and no item file changes. It is not a `claim-verify` flag, because
 `claim-verify` is the read-mostly reconciliation report every remediation string
 names, and one command name must not mean both "tell me the state" and "change
-the authorization baseline". It is not a `claim` subcommand, because every claim
-lifecycle subcommand refuses with `publication-reconciliation-required` while
-reconciliation reports blocking findings, and adoption exists to clear exactly
-that state, so it runs while those findings stand.
+the authorization baseline". It is not a `claim` subcommand, because
+`work-claim.acquire` and `work-claim.renew` refuse with
+`publication-reconciliation-required` while reconciliation reports blocking
+findings, and adoption exists to clear exactly that state, so it runs while
+those findings stand. `work-claim.release` also runs while they stand, for the
+narrower reason that surrendering a lease takes no authority (section 5).
 
 The request is UTF-8 JSON with exactly these members:
 
@@ -556,6 +880,23 @@ fails or its durability is uncertain, the backend returns exit 6 with
 to guess. It cannot report a lease success or semantic rejection whose time
 was not persisted.
 
+**A refused reconciliation has already advanced the floor.** Reconciliation
+persists its clock entry before it classifies anything, so a command that then
+refuses with exit 6 `claim-store-unavailable`, reason
+`publication-reconciliation-required`, has still moved the durable floor to
+`max(physical_utc, previous_floor)`. No claim, epoch, or ledger byte changes,
+and the refusal reports none. The floor is monotonic, so the effect is on time
+alone and it is permanent: once a refused reconciliation has published a floor
+at or past a lease's `expires_at`, that lease can never read live again, and a
+later acquire, renew, or fence check on the same tuple observes it expired.
+On a ledger whose floor already runs ahead of this caller's wall clock, every
+refused reconciliation republishes the higher floor, so a holder whose lease
+looks live by its own clock may find it expired the moment it asks. A caller
+that meets a barrier during a long recovery SHOULD expect to reacquire rather
+than assume its lease survived. This is section 5's rule for a rejected
+decision applied one step earlier: an advanced floor is never evidence that
+anything succeeded.
+
 When `last_epoch` is `18446744073709551615` (the unsigned 64-bit maximum), a
 new acquire or takeover is impossible. After the authoritative decision time
 has been persisted, the backend returns exit 6 `epoch-exhausted` with message
@@ -570,6 +911,22 @@ member at any depth, and exactly the listed members. Unknown members, wrong
 types, noncanonical values, and unprovisioned namespaces are exit 2
 `invalid-request`; no authoritative lease decision has then occurred.
 
+**A reconciliation barrier stops a caller from taking or extending authority,
+never from surrendering it.** `work-claim.acquire` and `work-claim.renew` MUST
+refuse with exit 6 `claim-store-unavailable`, reason
+`publication-reconciliation-required`, and the reconciliation `findings`,
+whenever reconciliation reports a finding that blocks the request's item.
+`work-claim.release` MUST NOT refuse for that reason. The holder has to be able
+to hand the lease back: no other worktree can take the item over while the
+claim is held, and the worktree holding it is often the one least able to clear
+the barrier. Refusing the surrender strands the lease and the item with it.
+
+Release keeps every other refusal. An identity the domain cannot resolve, a
+journal it cannot read, and a clock floor it cannot persist all refuse before
+any lease decision, and the owner, epoch, and expected-expiry CAS tuple below
+still rules on the request: a mismatch is exit 4 `claim-conflict` and the claim
+stays held. A barrier never turns a release into an unconditional discard.
+
 ### Read
 
 `work-claim.read` accepts exactly:
@@ -641,6 +998,10 @@ It uses the same precedence. Success sets `active` to `null`, retains
 `last_epoch`, and returns `released_claim` plus `read_back`. A later acquire
 must allocate a greater epoch, preventing ABA even across restart.
 
+A reconciliation barrier does not refuse a release; it refuses only acquire and
+renew (section 5 preamble). The CAS tuple still applies, so a release under a
+barrier is exactly as conditional as a release without one.
+
 Success envelopes for these three commands have exactly `ok`, `namespace`,
 `command`, `contract_version`, `state: "committed"`, and `result`. Semantic
 failures replace `result` with `error`, use `state: "unchanged"`, and include
@@ -805,18 +1166,21 @@ recovers an owner only when the OS reports the PID absent.
 
 That reconciliation is unconditional. It is not conditioned on an unresolved
 `publish-intent`, because the commit-per-mutation invariant (section 1) binds
-`publish-claimed` exactly as it binds `create`, `transition`, and `patch`, and
-an uncommitted legacy mutation leaves no publish-intent behind. When
-reconciliation produces any blocking finding, `publish-claimed` MUST refuse
-with exit 6 `claim-store-unavailable`,
+`publish-claimed` exactly as it binds `create`, `transition`, `parent-migrate`,
+`snooze`, and `patch`, and an uncommitted legacy mutation leaves no
+publish-intent behind. When reconciliation produces any blocking finding,
+`publish-claimed` MUST refuse with exit 6 `claim-store-unavailable`,
 `details.reason: "publication-reconciliation-required"`, and
 `details.findings` set to those findings. `state` MUST be `unchanged`: the
 refused publication wrote no item byte. Reconciliation itself still writes —
 a clock entry, the terminals it resolved, and the finalizations it observed —
-because those record what was already true, never a new item revision. This is
-the identical refusal section 7 defines for a legacy write, so one uncommitted
-mutation blocks every mutating command alike, and one `claim-verify` clears
-them all.
+because those record what was already true, never a new item revision.
+
+This is the identical refusal section 7 defines for a legacy write. The
+authorized predecessor/successor window from section 1 produces no blocking
+finding, so not every uncommitted mutation refuses the next command. When
+blocking findings do exist, `claim-verify` is the one reconciliation procedure
+for all of them.
 
 That refusal also outranks step 5. The numbered precedence orders a backend
 that judges a candidate against an authoritative ledger; a merge-coordinated
@@ -839,13 +1203,14 @@ process MAY recover the lock only when the operating system reports that owner
 process as absent. A live or malformed lock remains `claim-store-unavailable`;
 elapsed time alone never authorizes lock recovery.
 
-`claim-verify` takes the ledger path and no request body. Under the namespace
-lock, it replays the journal, advances and persists the clock floor, and
-reconciles pending intents against the exact item revision. It also compares
-successful publications with Git `HEAD`. When `HEAD` contains the committed
-revision, it appends one idempotent `publish-finalization` entry that records
-the Git commit. It writes a per-namespace reconciliation log outside the shared
-journal; that log is a derived audit artifact, not authority.
+`claim-verify` takes the ledger path, optional target item ID, and no request
+body. The target ID is syntax-validated without requiring local item presence.
+Under the namespace lock, it replays the journal, advances and persists the
+clock floor, and reconciles pending intents against exact item revisions. It
+also compares successful publications with Git `HEAD`. When `HEAD` contains a
+committed revision, it appends one idempotent `publish-finalization` entry that
+records the Git commit. It writes a per-namespace reconciliation log outside
+the shared journal; that log is a derived audit artifact, not authority.
 
 The log projects only journal entries that record a decision. `clock` and
 `publish-finalization` entries are never projected. A command therefore writes
@@ -880,13 +1245,19 @@ not a claim finding, and a caller MUST NOT treat it as one. It is the honest
 statement that a clean claim answer is not a clear road, and the caller must
 repair validation before the next mutation will run.
 
-A clean verification returns exit 0 and `state: "committed"`. Findings named
-`pending-intent-resolved` are clean recovery. Any
-`legacy-mutation-outcome-unknown`, `publication-outcome-unknown`,
-`revision-regression`, or `stale-write-detected` finding returns exit 6 and
-`state: "unknown"`. A caller MUST stop publication work and inspect those
-findings. Repeating verification MUST NOT duplicate a publication
-finalization.
+A verification result always names `verification_scope`, and every finding
+states `blocks_verification_scope`. Bare mode treats every blocking repository
+finding as blocking. Target mode keeps unrelated target-scoped findings
+visible but nonblocking; findings classified as global still block. A clean
+scope returns exit 0 and `state: "committed"`. This state describes durable
+coordinator reconciliation, not Git finalization of every successful
+publication; callers must inspect each `result.publications` row's
+`git_finalized` and `git_commit`. Findings named `pending-intent-resolved` are
+visible and nonblocking. Any blocking `legacy-mutation-outcome-unknown`,
+`publication-outcome-unknown`, `revision-regression`, or
+`stale-write-detected` finding returns exit 6 and `state: "unknown"`. A caller
+MUST stop publication work and inspect those findings. Repeating verification
+MUST NOT duplicate a publication finalization.
 
 Every finding that blocks a mutation MUST carry a `remediation` string, and
 that string MUST name both the action to take and `claim-verify`. It MUST also
@@ -948,9 +1319,9 @@ without a second ledger write.
 
 Every refusal in this section answers in the `ledger-mutation` namespace with
 `contract_version: 1` and `command: "<core command>-v1"`, even though the caller
-invoked the core `create`, `transition`, or `patch` command. This is a pinned
-version 1 consumer surface; it is not the core mutation envelope and MUST NOT be
-re-wrapped in one.
+invoked the core `create`, `transition`, `parent-migrate`, `snooze`, or `patch`
+command. This is a pinned version 1 consumer surface; it is not the core
+mutation envelope and MUST NOT be re-wrapped in one.
 
 For a fenced or merge-coordinated capability, legacy transition MUST check the
 active claim under the same namespace lock and return exit 4
@@ -960,18 +1331,24 @@ create MUST reject any item identity whose tuple has claim history with exit 4
 high-water mark. Both checks persist authoritative decision time before their
 response.
 
-Before a merge-coordinated backend permits a legacy transition or patch to
-write bytes, it MUST fsync a `legacy-mutation-intent` with the expected and
-candidate revisions. Under the same namespace lock, it MUST reserve journal
-capacity for that intent, one recovery clock entry, and one terminal entry. A
-committed write appends `legacy-mutation`; an unchanged write appends
-`legacy-mutation-abort`. Reconciliation resolves a pending intent to the
-committed terminal when the candidate revision is present, or to the abort
+Before a merge-coordinated backend permits a legacy create, transition, or
+patch to write bytes, it MUST fsync a `legacy-mutation-intent` carrying the
+expected and candidate revisions. Under the same namespace lock, it MUST
+reserve journal capacity for that intent, one recovery clock entry, and one
+terminal entry. A committed write appends `legacy-mutation`; an unchanged write
+appends `legacy-mutation-abort`. Reconciliation resolves a pending intent to
+the committed terminal when the candidate revision is present, or to the abort
 terminal when the expected revision remains. Any third revision produces
 `legacy-mutation-outcome-unknown`. The latest committed terminal is the
 authorized expected revision. A later unrecorded revision remains a stale
 write.
 
+A create has no predecessor, so its intent carries `expected_revision: null`,
+which is valid only for `create-v1`, and the item path's absence is what
+resolves it to the abort terminal. Section 3.1 states the complete create
+ordering, its allocation fence, and the alpha.13 cutover the widened grammar
+forces.
+
 A merge-coordinated backend MUST reconcile before it authorizes a legacy write,
 and section 6 states the same requirement for `publish-claimed`.
 When reconciliation produces any blocking finding, the legacy command MUST
@@ -1086,9 +1463,10 @@ merge-coordinated backend returns when reconciliation found blocking findings,
 and it is the reason an uncommitted prior mutation produces. **`claim-verify`
 is its reconciliation procedure.** The envelope also carries
 `details.findings`; act on each finding's `remediation` string, then run
-`wowbagger claim-verify --ledger <dir> --json` and require exit 0 before
-repeating the refused command. Nothing else reconciles the journal, and no
-other verb is needed.
+`wowbagger claim-verify --ledger <dir> --id <finding.item_id> --json` for the
+affected item and require exit 0 before repeating that item's refused command.
+Use bare verification only for strict repository diagnosis. Nothing else
+reconciles the journal, and no other verb is needed.
 
 This code was added after the version 1 vectors were written. It is additive:
 it names a condition the original text did not model, changes no existing code,