wowbagger 0.1.0-alpha.9 → 0.5.0

package/docs/mutation-contract.md

@@ -81,8 +81,9 @@ complete difference against published version 2 (`0.1.0-alpha.4`):
 - **the patchable title.** `title` joins the patchable set as a non-empty
   schema string that replaces the current title whole (section 9), and section
   9 gains the frontmatter ownership table that states, member by member, which
-  members are core-owned, which are consumer-editable through `patch`, and
-  which are create-once. The version stays 3 by the same argument the relations
+  members are core-owned, which are consumer-editable through `patch`, which
+  move through a dedicated command, and which are create-once. The version
+  stays 3 by the same argument the relations
   and body deltas used: this widens the patch request schema, and adds, removes,
   and renames no response envelope member. **Version 3 is published, so state
   the consequence plainly: a consumer probing for title-patch support cannot
@@ -190,11 +191,11 @@ and stops.
 
 The bootstrap wire, adapter approval, instruction, handoff, and fixture-format
 versions are separate version domains and remain version 1. The adapter
-contract remains version 2. The work-claim API moves to 2 with this release,
-for its own reason stated in
-[the work-claim contract](work-claim-contract.md), section 6: the item-source
-refusal replaces the version 1 error that an oversized candidate used to
-receive.
+contract remains version 2. The work-claim API moved to 2 with this core
+release because the item-source refusal replaced the version 1 error that an
+oversized publication candidate used to receive. It later moved to 3 for
+target-scoped `claim-verify`; the current value is always negotiated from
+capabilities, never inferred from the core version.
 
 Version negotiation uses distinct existing fields. A core consumer MUST read
 the top-level `contract_version` from `capabilities --json`. A work-claim
@@ -258,7 +259,7 @@ and stops.
 
 The bootstrap wire, adapter approval, instruction, handoff, and fixture-format
 versions are separate version domains and remain version 1. The adapter
-contract remains version 2 and the work-claim API remains version 2. The list
+contract remains version 2 and the work-claim API remains version 3. The list
 query and the workbench projection each have their own version domain,
 `query_version` and `projection_version`, both `1`: a consumer negotiates them
 through `result.operations.list.query_version` and
@@ -321,16 +322,18 @@ wowbagger inspect --ledger <dir> --id <id> --workbench --as-of YYYY-MM-DD --json
 wowbagger list --ledger <dir> --input <json-file|-> --json
 wowbagger create --ledger <dir> --input <json-file|-> --json [--auto-commit]
 wowbagger transition --ledger <dir> --input <json-file|-> --json [--auto-commit]
+wowbagger parent-migrate --ledger <dir> --input <json-file|-> --json [--auto-commit]
+wowbagger snooze --ledger <dir> --input <json-file|-> --json [--auto-commit]
 wowbagger patch --ledger <dir> --input <json-file|-> --json [--auto-commit]
 wowbagger mint-id [--date YYYY-MM-DD] --json
 wowbagger mutation-finalize --ledger <dir> --recovery-token <token> --json
 ~~~
 
 `--auto-commit` is a bare opt-in flag. It is accepted once on `create`,
-`transition`, `patch`, and `publish-claimed`, and it is an unknown argument
-everywhere else. Repeating it is `invalid-request`. Section 13 defines what it
-does. Without it, every existing invocation keeps its exact stdout, exit,
-files, index, and Git `HEAD`.
+`transition`, `parent-migrate`, `snooze`, `patch`, and `publish-claimed`, and it
+is an unknown argument everywhere else. Repeating it is `invalid-request`.
+Section 13 defines what it does. Without it, every existing invocation keeps
+its exact stdout, exit, files, index, and Git `HEAD`.
 
 A dash for --input means standard input. File and standard-input requests have
 identical semantics. Request bytes must be valid UTF-8 JSON with one top-level
@@ -338,7 +341,8 @@ object and no duplicate member names at any depth. Duplicate members are
 invalid; a parser must not apply last-member-wins behaviour.
 
 Unknown, missing, and repeated command arguments are invalid-request. Create,
-transition, and patch use JSON input rather than parallel field flags.
+transition, parent migration, snooze, and patch use JSON input rather than
+parallel field flags.
 
 ### Standard output and standard error
 
@@ -372,6 +376,7 @@ answer in two domains.
 | work-claim | `work-claim` | 1, the legacy envelope marker | `result.operations.work_claim.api_version` of `claim capabilities --json` |
 | ledger-publication | `ledger-publication` | 1, the legacy envelope marker | the same work-claim `api_version` |
 | ledger-mutation | `ledger-mutation` | 1, the legacy envelope marker | the same work-claim `api_version` |
+| ledger-repair | `ledger-repair` | 1 | `contract_version` of `number-repair-proposal` or `number-repair` |
 | bare result | absent, and no `ok` member either | none | none |
 
 The rule has three steps:
@@ -397,6 +402,7 @@ legacy claim-envelope marker, and a consumer must never compare it with the core
 | `inspect` | core | core |
 | `list` | core | core |
 | `mint-id` | core | core |
+| `version-drift` | core | core |
 | `report` | core | core |
 | `create` | core | core, or ledger-mutation when the claim fence refuses |
 | `transition` | core | core, or ledger-mutation when the claim fence refuses |
@@ -411,13 +417,15 @@ legacy claim-envelope marker, and a consumer must never compare it with the core
 | `claim-sync` | work-claim | work-claim |
 | `claim-adopt` | work-claim | work-claim |
 | `mutation-finalize` | work-claim | work-claim |
-| `claim verify` | ledger-publication, `command: "read"` | ledger-publication |
+| `number-repair-proposal` | ledger-repair | ledger-repair |
+| `number-repair` | ledger-repair | ledger-repair |
 | `publish-claimed` | ledger-publication | ledger-publication |
 
 **Exact root members**
 
 A core response has exactly `ok`, `command`, `contract_version`, and one of
-`result` or `error`; `create`, `transition`, and `patch` add `state`. A
+`result` or `error`; `create`, `transition`, `parent-migrate`, `snooze`, and
+`patch` add `state`. A
 claim-domain response has exactly `ok`, `namespace`, `command`,
 `contract_version`, `state`, and one of `result` or `error`; a `claim
 capabilities` response omits `state`, and a claimed-publication response adds
@@ -425,8 +433,9 @@ capabilities` response omits `state`, and a claimed-publication response adds
 Successful mutation responses may carry `result.changed_paths`. It is the
 complete deterministic ledger-relative set whose bytes this invocation changed
 in the working tree. It does not mean Git committed those paths. `create`
-returns only its item path; `transition`, `patch`, and `publish-claimed` return
-their item path plus the tracked reconciliation log when that log changed.
+returns only its item path; `transition`, `parent-migrate`, `snooze`, `patch`,
+and `publish-claimed` return their item path plus the tracked reconciliation
+log when that log changed.
 `--auto-commit` additionally returns `commit_paths` and `git_commit`; its
 `changed_paths` equals the committed set.
 `operation_id` once schema validation has accepted it. No expected envelope has
@@ -442,7 +451,8 @@ them would break every existing reader for no gain a consumer can use, because
 neither command mutates and neither participates in version negotiation. They
 stay bare, and step 3 of the rule is how a consumer recognizes them.
 
-A claim-fenced refusal to `create`, `transition`, or `patch` answers in the
+A claim-fenced refusal to `create`, `transition`, `parent-migrate`, `snooze`,
+or `patch` answers in the
 ledger-mutation domain with `command: "<command>-v1"` and
 `contract_version: 1`. This is not envelope drift: it is the work-claim
 contract answering, because a merge-coordinated backend refused the write
@@ -477,7 +487,7 @@ A successful read-only command has exactly:
 }
 ~~~
 
-A successful create, transition, or patch adds state:
+A successful create, transition, parent migration, snooze, or patch adds state:
 
 ~~~json
 {
@@ -504,7 +514,8 @@ A read-only error has exactly:
 }
 ~~~
 
-Every create, transition, or patch error has a state member:
+Every create, transition, parent-migrate, snooze, or patch error has a state
+member:
 
 ~~~json
 {
@@ -546,7 +557,7 @@ presence is reported separately as bounded recovery_artifacts.
 | 6 | An unexpected operating or post-publication recovery condition. | operation-failed, post-commit-recovery-required, write-outcome-unknown, git-commit-failed, git-commit-outcome-unknown, post-commit-reconciliation-failed |
 
 Only exit 0 is normal completion. A client must inspect mutation state on every
-nonzero create, transition, or patch result.
+nonzero create, transition, parent-migrate, snooze, or patch result.
 
 ## 3. Deterministic invalid-request issues
 
@@ -681,7 +692,7 @@ capability paths; all omitted paths retain their version 1 values:
 | `result.operations.list` | `{"supported":true,"write_scope":"none","cas_scope":"none","query_version":1}` |
 | `result.operations.patch` | `{"supported":true,"write_scope":"single-item","cas_scope":"exact-byte-sha256"}` |
 | `result.operations.report` | `{"supported":true,"write_scope":"derived-output","config_versions":[1,2],"named_views":true}` |
-| `result.operations.work_claim.api_version` | `2` |
+| `result.operations.work_claim.api_version` | `3` |
 | `result.limits.max_item_source_bytes` | `8388608` |
 | `result.limits.default_list_page_size` | `50` |
 | `result.limits.max_list_page_size` | `200` |
@@ -759,7 +770,8 @@ defines the advertisement.
 `result.limits.max_item_source_bytes` is the first member of `result.limits`,
 before `multi_item_atomicity`. It is the exact number of bytes the complete
 serialized item source may occupy, and it applies to successor bytes accepted
-by `create`, `transition`, `patch`, and `publish-claimed`. It does not claim a
+by `create`, `transition`, `parent-migrate`, `snooze`, `patch`, and
+`publish-claimed`. It does not claim a
 raw request limit and it does not claim an `inspect` output limit; the
 serialized `publish-claimed` request keeps its own separate transport bound.
 
@@ -783,10 +795,18 @@ another. It is **not** a statement that worktrees write independently.
 
 On a provisioned Git-backed ledger they do not. One claim journal lives in the
 shared Git common directory, so it serializes every worktree of that
-repository: a recorded `transition` or `patch` in one worktree refuses every
-mutation in the others with exit 6 `claim-store-unavailable`, reason
+repository. The serialization is scoped to the item: a recorded `transition` or
+`patch` in one worktree refuses a mutation in the others that targets *that
+item* with exit 6 `claim-store-unavailable`, reason
 `publication-reconciliation-required`, until the writing commit is visible in
-the blocked checkout. Clones do not share the common directory, so
+the blocked checkout. A mutation targeting an unrelated item still runs, and
+the sibling's finding remains visible. Own uncommitted work and out-of-protocol
+revisions are global barriers and refuse every mutation. Bare `claim-verify`
+reports exit 6 while any item carries a blocking finding.
+`claim-verify --id <item>` keeps every finding visible but returns success when
+only unrelated target-scoped findings remain; global findings still block.
+See [the work-claim contract](work-claim-contract.md), section 3.2, for the
+scope rules. Clones do not share the common directory, so
 `limits.cross_clone_coordination: false` carries no such consequence.
 
 That serialization is discoverable, per ledger, at
@@ -889,8 +909,8 @@ snapshot the successful item shape above defines, for the item the request
 selected. It is present when the request resolves an item and no validation
 error names that item's path. It is absent when nothing resolves, and absent
 when the resolved item is itself faulted, because that item's own frontmatter
-or placement is what validation rejects. A create, transition, or patch
-ledger-invalid refusal never carries it.
+or placement is what validation rejects. A create, transition, parent-migrate,
+snooze, or patch ledger-invalid refusal never carries it.
 
 This keeps the section 5 rule intact — inspect loads and validates the complete
 ledger, and every member of the attached snapshot comes from the one raw byte
@@ -1291,11 +1311,11 @@ A writer creates the lock file exclusively as valid UTF-8 JSON no larger than
 ~~~
 
 writer_id is an opaque ASCII string of 1 through 128 characters. operation is
-create, transition, or patch — the three operations that take per-ID locks.
-`publish-claimed` writes no lock file, so no lock file names it and a reader
-never has to classify one. The remaining values must match their schema and
-lock path. Metadata contains no credentials, user name, host name, or command
-arguments.
+create, transition, parent-migrate, snooze, or patch — the operations that
+take per-ID locks. `publish-claimed` writes no lock file, so no lock file
+names it and a reader never has to classify one. The remaining values must
+match their schema and lock path. Metadata contains no credentials, user name,
+host name, or command arguments.
 
 A reader reads at most 4097 bytes. A lock larger than 4096 bytes, invalid UTF-8,
 duplicate-key JSON, invalid JSON, unknown members, or invalid field values is
@@ -1304,6 +1324,7 @@ one of too-large, invalid-utf8, duplicate-key, invalid-json, or invalid-shape.
 Valid metadata returns owner and owner_diagnostic null. Raw invalid bytes are
 never returned.
 
+
 Locks are never removed automatically merely because started_at is old. Manual
 recovery follows ADR 0003.
 
@@ -1346,6 +1367,12 @@ Create accepts exactly:
 | item extension members | No | Permitted schema extensions. |
 | body | Yes | JSON string; empty and LF-leading strings are distinct and valid. |
 
+The member name `extensions` is reserved for the `patch` request container.
+Create refuses `item.extensions`; extension members must be named directly on
+the item, such as `item.tags` or `item.tier`. This prevents a nested mapping
+from becoming an extension value that `patch` and the declaration workflow
+cannot address.
+
 If a file named by `--input` cannot be read before a request ID is known,
 create or transition returns `invalid-request` with one `invalid-value` issue at
 `/input`, the stable message `Request input could not be read.`, and mutation
@@ -1536,6 +1563,68 @@ no-clobber publication still protects an intervening creator.
 Successful create returns state committed and the inspect item shape from
 section 5.
 
+### Journal-fenced allocation on a provisioned ledger
+
+On a provisioned merge-coordinated ledger, a schema-version-2 create is a
+journaled legacy mutation. Under the shared namespace lock it reconciles,
+applies the allocation fence below, loads and validates the ledger, derives
+`1 + max(existing numbers)`, serializes the candidate, validates the complete
+candidate ledger, reserves journal capacity, and only then appends its
+`legacy-mutation-intent` with `command: "create-v1"` before any byte reaches
+the item path. Publication, exact-byte verification, and the terminal append
+all happen under that same lock. The intent carries
+`expected_revision: null`, which is valid only for `create-v1`. The committed
+terminal is `legacy-mutation` with `command: "create-v1"`; the create abort
+carries `command: "create-v1"` and `observed_revision: null`. No entry records
+the assigned number, because the candidate revision binds the complete item
+bytes and the ledger remains the one number authority.
+
+The allocation fence reads reconciliation with one extra barrier. Every global
+finding blocks create as it blocks every write. 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. A stale revision of an item this checkout holds does not
+block `create`, because a number is immutable and the local maximum is already
+correct. A fenced create refuses with exit 6, `state: "unchanged"`,
+`error.code: "claim-store-unavailable"`, and
+`error.details.reason: "publication-reconciliation-required"` in the
+`ledger-mutation` domain as `create-v1`, having written no item byte. Resolve
+each finding by its own `remediation`, run `claim-verify` until it exits 0, and
+retry the same request ID; the retry takes the next number.
+
+A create has no authorized predecessor, so Git `HEAD` is the only surface that
+can carry its authorized bytes, and an uncommitted create raises the global
+`git-finalization-required` barrier for every later mutation. Commit each
+created item before the next mutating command. This release adds no batch
+mutation; the supported bulk pattern remains the create-then-commit loop.
+A ledger that already carries duplicate numbers is item #182 recovery work and
+is repaired through the separate `ledger-repair` contract, not through core
+version 5 mutation. Run
+`number-repair-proposal --ledger <dir> --json`, review the complete mapping, then
+run `number-repair --ledger <dir> --input <repair.json> --json`. The repair
+command operates 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 this guarantees, and what it does not.** The fence 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 the fence and still rely on branch integration plus `validate`.
+
+The widened journal grammar forces a hard cutover, so upgrade every writer in
+one Git coordination domain before the first alpha.14 create. An alpha.13
+binary cannot read a `create-v1` intent: it refuses with exit 6,
+`error.code` `claim-store-unavailable`, message
+`The durable claim store is unavailable.`, and `error.details.reason`
+`claim-store-unreadable`, leaving state unchanged and writing no item. That
+refusal means **this repository was written by a newer Wowbagger; upgrade this
+worktree to continue.** There is no automatic migration and no mixed-version
+grace period.
+
 ## 8. Transition
 
 ### Request
@@ -1856,6 +1945,84 @@ temporary file followed by the platform's existing-file atomic replacement
 primitive. It then re-reads exact final bytes. This remains a local filesystem
 operation without universal crash durability or hostile-writer protection.
 
+## 8.1 Parent migration
+
+`parent-migrate` moves one item to an epic or detaches it without changing item
+identity or lifecycle. Parent-migrate accepts exactly:
+
+~~~json
+{
+  "id": "wb_...",
+  "expected_revision": "sha256:<64 lowercase hexadecimal characters>",
+  "expected_parent": "wb_...",
+  "parent": null,
+  "date": "2030-01-11"
+}
+~~~
+
+`id`, `expected_revision`, `expected_parent`, `parent`, and `date` are required.
+`expected_parent` and `parent` are each a canonical item ID or `null`.
+`expected_parent` is a second compare-and-swap witness: it must equal the
+current parent after the locked re-read. A mismatch returns exit 4
+`parent-migration-precondition-failed` with a `parent-revision-conflict` issue
+and both `expected_parent` and `actual_parent`. An unknown parent, a non-epic
+parent, self-parenting, or a date before `created` or `updated` returns exit 2
+with the same error code and deterministic issues. Revision and lock conflicts
+retain their ordinary exit 4 precedence.
+
+The command sets `updated` to request `date` and changes only `parent`. For an
+item whose status is `done`, `killed`, `archived`, or `deferred`, the request
+date must equal the existing `updated` date. No status or liveness precondition
+exists; the complete candidate ledger still validates every parent and rollup
+invariant before publication.
+
+A core success answers as command `parent-migrate`, contract version 5, state
+`committed`, and returns the lossless item. On a provisioned ledger, a claim
+fence refusal answers in the `ledger-mutation` domain as command
+`parent-migrate-v1`. `--auto-commit` commits the changed item, when its bytes
+move, plus the reconciliation log under the fixed parent-migrate subject.
+
+Parent migration reuses the legacy `patch-v1` fence family in the durable claim
+journal. That journal `command` is a fence-family and recovery classifier, not
+the public operation name. Internally, `responseCommand` identifies the
+response operation and keeps `parent-migrate-v1` distinct in envelopes. The
+journal's attempt ID and expected, candidate, and committed revisions remain
+the recovery evidence; Git history remains the reviewable operation audit.
+
+## 8.2 Snooze
+
+`snooze` sets or clears one item's snooze date without changing lifecycle.
+Snooze accepts exactly:
+
+~~~json
+{
+  "id": "wb_...",
+  "expected_revision": "sha256:<64 lowercase hexadecimal characters>",
+  "snoozed_until": "2030-02-01",
+  "date": "2030-01-11"
+}
+~~~
+
+`id`, `expected_revision`, `snoozed_until`, and `date` are required.
+`snoozed_until` is an ISO calendar date or `null`; `null` removes the member.
+`date` is an ISO calendar date not before `created` or `updated`. The command
+sets `updated` to request `date` and changes only `snoozed_until`. For an item
+whose status is `done`, `killed`, `archived`, or `deferred`, the request date
+must equal the existing `updated` date.
+
+Invalid input returns exit 2 `invalid-request`; stale item revision and lock
+conflicts retain exit 4; date and candidate validation use the same bounded
+issue and error shapes as patch. A core success answers as command `snooze`,
+contract version 5, state `committed`, and returns the lossless item. On a
+provisioned ledger, a claim fence refusal answers in the `ledger-mutation`
+domain as command `snooze-v1`. `--auto-commit` commits the changed item, when
+its bytes move, plus the reconciliation log under the fixed snooze subject.
+
+Snooze also reuses the legacy `patch-v1` fence family in the durable claim
+journal. The journal `command` identifies the fence and recovery family, while
+`responseCommand` identifies the response operation as `snooze-v1`. This split
+is intentional and does not change the journal format.
+
 ## 9. Patch
 
 Patch changes the mutable non-lifecycle content of one existing item — its
@@ -1905,6 +2072,14 @@ Patch accepts exactly:
 | date | Yes | ISO calendar date not earlier than existing created or updated. |
 | set | Yes | Mapping naming at least one patchable field. |
 
+For an item whose status is `done`, `killed`, `archived`, or `deferred`, the
+request date must equal the existing `updated` date for `patch`, `snooze`, and
+`parent-migrate`. The active lifecycle date must equal `updated`; these three
+verbs update `updated` without changing that lifecycle date. An earlier request
+fails the date floor, while a later request produces `candidate-invalid` with
+`terminal-date-must-match-updated`. Inspect immediately before the mutation and
+reuse the item's current `updated` date.
+
 The patchable field set is exactly `title`, `priority`, `depends_on`,
 `related`, `body`, `body_append`, and `extensions`. A set member outside it is an invalid-request issue at
 its /set pointer — the boundary is stated here, not discovered from the
@@ -2077,6 +2252,27 @@ before it can correct anything. `validate` is therefore unchanged by this file,
 and an item whose extension member disagrees with the declaration is still a
 valid item — it is simply an item a patch can correct.
 
+**Provisioning a declaration on an existing ledger.**
+
+`extensions-provision --ledger <dir> --input <request> --json [--dry-run]`
+accepts an explicit non-empty `members` mapping in the same version-1 member
+and type vocabulary. It never infers a type from stored values. Before it
+proposes anything, it requires the complete ledger to validate. For each
+selected member, it validates every stored occurrence against the selected
+type, requires at least one occurrence, and reports that occurrence count.
+The member need not appear on every item. Empty `string-list` values are valid;
+scalars, null, maps, nested lists, and lists containing non-strings conflict
+with `string-list`.
+
+Dry-run returns the canonical declaration bytes and writes nothing. Publication
+creates exactly `.wowbagger/extensions.json` with no-clobber semantics.
+Repeating the identical declaration is idempotent; a different existing
+declaration is `extension-declaration-conflict`, exit 4, `unchanged`.
+Neither form changes an item byte or revision, records a claim-journal entry,
+or creates an item revision. The generated declaration is committed before
+the first patch that uses it. Anchors and aliases remain item-specific patch
+preconditions and do not prevent declaration provisioning.
+
 Absence is fail-closed and total. A ledger with no `extensions.json` has **no**
 patchable extension member, and a `set.extensions` request against it is
 refused `patch-precondition-failed`, exit 2, `unchanged`, with one
@@ -2130,8 +2326,8 @@ that parses as something else is caught before publication, not after.
 
 ### Frontmatter ownership
 
-Every frontmatter member belongs to exactly one of three classes, and this
-table is the whole boundary. A consumer reads it instead of sending a patch and
+Every frontmatter member belongs to exactly one of four classes, and this table
+is the whole boundary. A consumer reads it instead of sending a patch and
 interpreting the refusal.
 
 | Member | Class | How it changes |
@@ -2141,7 +2337,7 @@ interpreting the refusal.
 | `number` | Core-owned | Create assigns it on schema version 2. It is the item handle and never moves. |
 | `status` | Core-owned | `transition` only, along an allowed lifecycle edge. |
 | `created` | Core-owned | Create derives it from the UTC date the ID encodes. |
-| `updated` | Core-owned | Every `transition` and `patch` sets it to `request.date`. |
+| `updated` | Core-owned | Every `transition`, `parent-migrate`, `snooze`, and `patch` sets it to `request.date`. |
 | `completed` | Core-owned | `transition` writes it on completion and clears it on any other edge. |
 | `killed` | Core-owned | `transition` writes it on a kill and clears it on any other edge. |
 | `archived` | Core-owned | `transition` writes it on an archive and clears it on any other edge. |
@@ -2154,8 +2350,8 @@ interpreting the refusal.
 | `body` (the region after the frontmatter, not a member) | Consumer-editable through `patch` | `set.body` replaces the whole body; `""` empties it. `set.body_append` appends without a merge; the two are mutually exclusive in one request. |
 | `kind` | Create-once | Create fixes it. `patch` refuses it. |
 | `provenance` | Create-once | Create writes it. Every later verb preserves it byte for byte. |
-| `parent` | Create-once | Create writes it. No verb moves an item between epics. |
-| `snoozed_until` | Create-once | Create writes it. No verb changes it. |
+| `parent` | Dedicated mutation through `parent-migrate` | Create may set it; `parent-migrate` repoints the existing item to an epic or detaches it with compare-and-swap witnesses. |
+| `snoozed_until` | Dedicated mutation through `snooze` | Create may set it; `snooze` sets or clears it with a compare-and-swap witness. |
 | declared extension members (`tags`, `tier`, a consumer's own identifier fields) | Consumer-owned, patchable through `set.extensions` | `set.extensions.<member>` replaces the member whole; `null` removes it. Patchable only where `<ledger>/.wowbagger/extensions.json` declares the member and its value type, and only where the item does not write it with a YAML anchor or alias. |
 | undeclared extension members | Consumer-owned, not patchable | Supplied at create, preserved byte for byte by every verb, and otherwise a reviewable hand-edit. A ledger with no extension declaration has no patchable extension member at all. |
 
@@ -2304,9 +2500,9 @@ on code, mutation state, and documented details.
 
 ### The bounded item source
 
-`create`, `transition`, and `patch` each measure the complete serialized
-successor before validating it as a ledger candidate. A successor larger than
-`result.limits.max_item_source_bytes` returns:
+`create`, `transition`, `parent-migrate`, `snooze`, and `patch` each measure
+the complete serialized successor before validating it as a ledger candidate.
+A successor larger than `result.limits.max_item_source_bytes` returns:
 
 - code `item-source-too-large`;
 - message `The proposed item source exceeds the supported byte limit.`;
@@ -2497,8 +2693,8 @@ claim-fenced mutation refusals and the bare `validate` and `ready` results.
 
 A ledger becomes provisioned when `provision` binds a namespace to the
 repository and `claim capabilities` reports `mode: "merge-coordinated"`. On
-such a ledger, `create`, `transition`, and `patch` run inside the claim
-coordinator described by the [work-claim
+such a ledger, `create`, `transition`, `parent-migrate`, `snooze`, and `patch`
+run inside the claim coordinator described by the [work-claim
 contract](work-claim-contract.md).
 
 ### The rule
@@ -2506,17 +2702,42 @@ contract](work-claim-contract.md).
 **Commit each mutation to Git before running the next mutating command.**
 
 The coordinator records every authorized mutation in the durable journal and
-validates the recorded revisions against Git `HEAD`, not against working-tree
-bytes. An uncommitted mutation is therefore an unreconciled mutation, and the
-next `create`, `transition`, or `patch` refuses rather than writing on top of
-work that is not yet durable.
+reconciles those records with Git `HEAD` and working-tree bytes. It refuses the
+next mutation when reconciliation 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 that mutation.
+
+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. The later command's acceptance does not prove durability;
+the operating rule remains write, commit, `claim-verify`, next write.
+
+`create` never occupies that window. A created item has no earlier authorized
+revision, so Git `HEAD` is the only surface that can carry its authorized
+bytes, and an uncommitted create raises the global `git-finalization-required`
+barrier for every later mutation, including the next create. Filing ten items
+is therefore ten serial `create --auto-commit` cycles, not one commit at the
+end. The accepted batch-create decision permanently rejects a batch mutation
+for the direct-Markdown architecture and keeps
+`limits.multi_item_atomicity: false`; see
+[`docs/design/2026-08-30-batch-create.md`](design/2026-08-30-batch-create.md).
+
+The journal is bounded at 65,536 entries and 8,388,608 bytes. If capacity is
+known before a legacy create, transition, parent migration, snooze, or patch
+intent is published, the command returns exit 6 `claim-store-unavailable`,
+reason `journal-capacity-exceeded`, and `unchanged`. Existing journal bytes
+remain an exact prefix and no item byte is written. A genuinely unreadable
+journal retains `claim-store-unreadable`; an indeterminate outcome after an
+intent retains its outcome-unknown classification.
 
 The loop that works:
 
 ~~~sh
 wowbagger create --ledger <dir> --input request.json --json
 git add <dir> && git commit -m "Record the mutation"
-wowbagger claim-verify --ledger <dir> --json
+wowbagger claim-verify --ledger <dir> --id <item> --json
 wowbagger transition --ledger <dir> --input next.json --json
 ~~~
 
@@ -2526,10 +2747,11 @@ refusals below name it by design.
 
 ### The refusal
 
-An uncommitted prior mutation makes the next mutating command return exit 6.
-The refusal answers in the ledger-mutation domain, not the core domain, because
-the claim coordinator refused before the core mutation ran. Section 2 states
-that rule; `namespace` is what a consumer reads to recognize it.
+A blocking reconciliation finding makes the next mutating command return exit
+6. The refusal answers in the ledger-mutation domain, not the core domain,
+because the claim coordinator refused before the core mutation ran. Section 2
+states that rule; `namespace` is what a consumer reads to recognize it. The
+example below is an authorized new item that is still absent from `HEAD`.
 
 ~~~json
 {
@@ -2564,8 +2786,11 @@ that rule; `namespace` is what a consumer reads to recognize it.
 `details.findings`. Every finding that blocks a mutation carries a
 `remediation` string, and every such string names both the path to act on and
 `claim-verify`. `actual_revision: null` with `observed_surface: "git-head"`
-means the authorized revision is not in `HEAD` at all, which is what an
-uncommitted mutation looks like.
+means the authorized item is absent from `HEAD`, so Git finalization is
+required. Not every uncommitted mutation produces this refusal: an existing
+item whose working tree has the latest authorized bytes while `HEAD` has an
+earlier authorized revision is the nonblocking predecessor/successor window
+defined above.
 
 `spec/fixtures/mutation-refusals/uncommitted-prior-mutation/manifest.json` is
 the normative envelope for this refusal.
@@ -2578,10 +2803,19 @@ envelope, subject and commit set included.
 For every blocking finding:
 
 1. Do what `remediation` says, for each finding, using its `expected_path`.
-   `git-finalization-required` means commit that path.
-2. Run `wowbagger claim-verify --ledger <dir> --json`.
-3. Exit 0 with `state: "committed"` means the ledger is reconciled and the next
-   mutating command may run. Exit 6 means findings remain; repeat from step 1.
+   `git-finalization-required` means commit that path. A
+   `worktree-synchronization-required` finding means wait only when its
+   `remediation` names an owner to wait for or says the expected revision is not
+   yet reachable. When it says the revision is reachable in Git while no active
+   named worktree owner is established, there is no commit left to wait for:
+   inspect that reachable history, then restore or explicitly adopt reviewed
+   bytes.
+2. Run `wowbagger claim-verify --ledger <dir> --id <finding.item_id> --json`
+   for each affected item. Use the bare command only for strict repository
+   diagnosis.
+3. Exit 0 with `state: "committed"` means that item is reconciled and its next
+   mutating command may run. Exit 6 means blocking findings remain; repeat from
+   step 1.
 
 The reasons a `stale-write-detected` finding can carry, and the other blocking
 finding codes, are enumerated in the [work-claim
@@ -2628,22 +2862,30 @@ by sending the flag, not by reading a version.
 
 Only the paths this invocation owns:
 
-| Command | Commit set |
-|---|---|
-| `create` | the created item |
+| `create` | the created item and one `<ledger>/.wowbagger/reconcile-<namespace>.md` |
 | `transition` | the changed item and one `<ledger>/.wowbagger/reconcile-<namespace>.md` |
-| `patch` | the changed item and the same one reconciliation log |
-| `publish-claimed` | the published item and the same one reconciliation log |
-
-`create` is journal-silent by design, so its commit set has no log. For the
-other three the log must already carry this invocation's terminal entry before
-it may be staged; if it does not, the invocation reports `git-commit-failed`
-with `reason: "log-unavailable"` rather than making an item-only commit.
+| `parent-migrate` | the changed item and one reconciliation log |
+| `snooze` | the changed item and one reconciliation log |
+| `patch` | the changed item and one reconciliation log |
+| `publish-claimed` | the published item and one reconciliation log |
+
+The item path appears in the set only when the successor bytes differ from the
+item bytes at `HEAD`. A byte-identical `parent-migrate`, `snooze`, or `patch`
+still records its decision in the reconciliation log, so its auto-commit set
+contains the log alone.
+
+`create` is journal-visible from the item's birth, so a successful `create`
+commits exactly the created item and its reconciliation log. For every command,
+the log must already carry this invocation's terminal entry before it may be
+staged; if it does not, the invocation reports `git-commit-failed` with
+`reason: "log-unavailable"`.
 
 Commit subjects are fixed:
 
     wowbagger: create item #N
     wowbagger: transition item #N
+    wowbagger: parent-migrate item #N
+    wowbagger: snooze item #N
     wowbagger: patch item #N
     wowbagger: publish claimed item #N
 
@@ -2664,12 +2906,16 @@ Before the mutation runs, the invocation takes a per-working-tree mutex and
 requires all of:
 
 - No path staged anywhere in the repository.
-- No dirty path under the ledger: tracked, untracked, or partially staged.
+- No dirty path under the ledger, with one exception: `transition`,
+  `parent-migrate`, `snooze`, `patch`, and `publish-claimed` tolerate a dirty
+  current-namespace reconciliation log, because each rebuilds that one derived
+  file from the authoritative journal. `create` does not tolerate it.
 - A Git identity Git can resolve without committing.
 - A `HEAD` that exists. A detached `HEAD` is supported, because a commit works
   from one; an unborn `HEAD` refuses.
-- A clean internal `claim-verify`, which is also what makes an unreconciled
-  prior mutation refuse before `publish-claimed`.
+- An internal `claim-verify` with no findings blocking the target item, which
+  is also what makes an unreconciled prior mutation refuse before
+  `publish-claimed`.
 
 Unstaged and untracked paths **outside** the ledger are allowed and stay
 byte-identical; they are never staged. Any other failure returns exit 4
@@ -2678,11 +2924,27 @@ staging, or commit occurs. `details.reason` is one of `staged-paths-present`,
 `ledger-not-clean`, `identity-unavailable`, `unborn-head`, `mutex-held`,
 `claim-state-unreconciled`, or `git-unavailable`.
 
-The rule is deliberately strict rather than preserving foreign staged work in a
-temporary index. Reconciliation excludes `.wowbagger/` from the Git item
-surface, and a dirty reconciliation log does not itself refuse a mutation, so a
-broad add would silently commit foreign ledger work. Refusing is the cheaper
-correct answer.
+Every `auto-commit-preflight-failed` refusal also carries
+`details.retryable`. `mutex-held` is retryable inside one working tree.
+`claim-state-unreconciled` also carries optional `claim_verify_code`,
+`claim_verify_reason`, `identity_diagnostic`, and bounded `findings`;
+`claim-store-locked` is retryable, while persistent reconciliation is not
+retryable. An `identity_diagnostic` reports an ambiguous or unreadable
+worktree identity — `duplicate-worktree-identity` with `worktree_id` and
+`live_worktree_count`, or `worktree-enumeration-failed` with no further member
+— and is never retryable. Every other
+preflight reason is not retryable. Clients branch on this boolean and the
+underlying verification reason, never on the generic message.
+
+The rule is deliberately strict rather than preserving foreign staged work in
+a temporary index. A journal-owning auto-commit validates and rebuilds the
+dirty derived reconciliation log from the authoritative journal, then commits
+it with the mutation. Owning the log is not absorbing what was already in it:
+`create` still refuses a dirty reconciliation log, because residue that
+predates the invocation is foreign to the entries create is about to write.
+Every other dirty ledger path refuses. Claim refusal evidence is never
+suppressed: both the authoritative journal and its projected log retain the
+decision before a later command rebuilds or commits the log.
 
 A flagged invocation on an advisory or non-provisioned ledger returns exit 5
 `capability-unavailable` with `state: "unchanged"` before the mutation. It does
@@ -2704,12 +2966,18 @@ not fall back to manual mode.
    dirt: refusing on it would make an already-published item impossible to
    commit.
 
+When a successful mutation produces item bytes identical to `HEAD`, the item
+path is omitted from `commit_paths`; the journal log remains the only changed
+path. This avoids reporting a staged-path mismatch for a valid audit-only
+mutation and keeps `mutation-finalize` idempotent after an advanced `HEAD`.
+
 On success the response keeps its original domain and adds three members to
 `result`: `git_commit`, `commit_paths`, and `claim_verified: true`. A successful
 invocation does not return until an internal `claim-verify` exits 0 with no
-findings and a valid ledger. For `publish-claimed` the same `claim-verify` must
-also report `git_finalized: true` and the new commit in the publication's
-finalization row.
+findings blocking the target item and a valid ledger. Nonblocking findings
+remain available to `claim-verify`; the success envelope does not duplicate
+them. For `publish-claimed`, the same verification must also report
+`git_finalized: true` and the new commit in the publication's finalization row.
 
 ### The commit-failed contract
 
@@ -2718,8 +2986,9 @@ Exit 6, `state: "committed"`, code `git-commit-failed`, message
 still describes item publication as section 2 defines it. It does not claim Git
 finalization.
 
-`create`, `transition`, and `patch` keep the core domain: no `namespace`, the
-original command name, and the core `contract_version`. `ledger-mutation` is
+`create`, `transition`, `parent-migrate`, `snooze`, and `patch` keep the core
+domain: no `namespace`, the original command name, and the core
+`contract_version`. `ledger-mutation` is
 not used, because that domain means the fence refused before the core mutation
 ran. `publish-claimed` keeps `namespace: "ledger-publication"`,
 `command: "publish-claimed"`, its legacy envelope marker, and its top-level
@@ -2743,7 +3012,10 @@ it match.
 
 A commit that is established while reconciliation then refuses is exit 6
 `post-commit-reconciliation-failed` with `state: "committed"`. It carries
-`git_commit`, `commit_paths`, and the `findings`. The commit stands.
+`git_commit`, `commit_paths`, and optional `claim_verify_code`,
+`claim_verify_reason`, and bounded `findings` from the failed verification. The
+commit stands; callers inspect the preserved cause and never replay the
+mutation.
 
 No failure envelope contains raw hook output, signing output, an absolute path,
 an environment value, or platform exception text. A bounded human diagnostic may