wowbagger 0.1.0-alpha.9 → 0.5.0-beta.0

package/CHANGELOG.md

@@ -7,6 +7,456 @@ consolidation. The first tagged release inherits this file.
 
 ## Unreleased
 
+## 0.5.0-beta.0 - 2026-08-30
+
+- Promote Wowbagger from alpha to beta while keeping `next` as the documented
+  prerelease channel and `latest` mirrored to the same newest prerelease.
+
+- Existing ledgers can safely authorize standard `tags` corrections through
+  `extensions-provision`: dry-run and publication now require a valid complete
+  ledger, validate every historical occurrence against explicit
+  `string-list` authority, preserve all item bytes, and publish one canonical
+  no-clobber declaration.
+
+- `claim-verify` now accepts optional `--id <item>` for target-scoped
+  verification while retaining strict repository-wide behavior when omitted.
+  All findings remain visible with `blocks_verification_scope`; work-claim API
+  version is now 3 while the legacy envelope marker remains 1.
+
+- Journal-capacity exhaustion now preserves the public
+  `journal-capacity-exceeded` discriminator across claim, verification,
+  adoption, publication, and legacy mutation paths. Pre-publication refusals
+  remain exit 6 `claim-store-unavailable`, `unchanged`, with prior journal and
+  item bytes intact; genuine persistence failures and post-intent unknown
+  outcomes retain their existing classifications.
+
+- Lock diagnostics now preserve valid `parent-migrate` and `snooze` owners,
+  matching the five-operation mutation contract. Unknown or malformed owner
+  metadata remains `owner: null` with `owner_diagnostic: "invalid-shape"`;
+  mutual exclusion and refusal behavior are unchanged.
+
+- Batch create is permanently rejected for the direct-Markdown architecture.
+  `limits.multi_item_atomicity` remains `false`; serial
+  `create --auto-commit` calls in request order remain the supported bulk path,
+  with one invocation and one commit per item.
+
+The alpha.14 hard cutover remains the baseline: `claim-store-unavailable`
+answers **The durable claim store is unavailable.** with
+`claim-store-unreadable`; upgrade every writer before the first alpha.14 create.
+There is no automatic migration or mixed-version grace period. There is no
+batch mutation. The create-then-commit loop, implemented most briefly as serial
+`create --auto-commit`, remains the supported bulk path. Ledger item #186 records the
+permanent no-batch decision, and item #182 owns existing duplicate numbers.
+The fence adds no new Git roster or history
+traversal and costs two extra fsync'd journal appends within the 65,536-entry
+limit.
+
+## 0.1.0-alpha.17 - 2026-08-30
+
+- **Breaking:** raise the supported Node.js floor from 20 to 24. Node 20 and
+  Node 22 no longer satisfy `engines.node`; Node 26 remains outside the
+  supported matrix because of the separate Vitest incompatibility reported by
+  Lee.
+
+The alpha.14 hard cutover remains the baseline: `claim-store-unavailable`
+answers **The durable claim store is unavailable.** with
+`claim-store-unreadable`; upgrade every writer before the first alpha.14 create.
+There is no automatic migration or mixed-version grace period. There is no
+batch mutation, the create-then-commit loop remains supported, item #186 owns
+batch design, and item #182 owns existing duplicate numbers. The fence adds no
+new Git roster or history traversal and costs two extra fsync'd journal appends
+within the 65,536-entry limit.
+
+
+## 0.1.0-alpha.16 - 2026-08-30
+
+- Added `version-drift --json` to detect stale installed skill pins, core
+  contract versions, and package provenance before ledger mutation.
+
+The alpha.14 hard cutover remains the baseline: `claim-store-unavailable`
+answers **The durable claim store is unavailable.** with
+`claim-store-unreadable`; upgrade every writer before the first alpha.14
+create. There is no automatic migration or mixed-version grace period. There is
+no batch mutation, the create-then-commit loop remains supported, item #186 owns
+batch design, and item #182 owns existing duplicate numbers. The fence adds no
+new Git roster or history traversal and costs two extra fsync'd journal appends
+within the 65,536-entry limit.
+
+## 0.1.0-alpha.15 - 2026-08-30
+
+- **Duplicate-number recovery now has a separate `ledger-repair` contract
+  version 1.** Use the read-only `number-repair-proposal` command to review a
+  complete mapping, then apply it with `number-repair`. The repair path requires
+  duplicate-number errors to be the complete validation failure, preserves ULID
+  identities and relation values, uses the shared namespace fence, records
+  durable intent/final entries, and supports bounded auto-commit recovery.
+
+The alpha.14 hard cutover remains the baseline: `claim-store-unavailable`
+answers **The durable claim store is unavailable.** with
+`claim-store-unreadable`; upgrade every writer before the first alpha.14
+create. There is no automatic migration or mixed-version grace period. There is
+no batch mutation, the create-then-commit loop remains supported, item #186 owns
+batch design, and item #182 owns existing duplicate numbers.
+The fence adds no new Git roster or history traversal and costs two extra
+fsync'd journal appends within the 65,536-entry limit.
+
+## 0.1.0-alpha.14 - 2026-08-29
+
+### Changed
+
+- **Upgrading is a hard cutover: upgrade every writer in one Git coordination
+  domain before the first alpha.14 create.** The journal grammar widened —
+  `legacy-mutation-intent` and `legacy-mutation` accept `command: "create-v1"`,
+  a create intent accepts `expected_revision: null`, and a create abort requires
+  `command: "create-v1"` with `observed_revision: null` — and an alpha.13 binary
+  cannot read the new create entry. Run against a ledger whose shared journal
+  already carries one, alpha.13's `create` exits 6 with `error.code`
+  `claim-store-unavailable`, message `The durable claim store is unavailable.`,
+  and `error.details.reason` `claim-store-unreadable`, leaves state unchanged,
+  and writes no item. Failing closed is the compatibility guarantee: an old
+  writer cannot commit another duplicate. It is also the operational limit,
+  because alpha.13 is immutable and can only emit that generic unreadable-store
+  message. Read it 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; a partial upgrade leaves the remaining alpha.13
+  worktrees unable to make claim-protected mutations until they move. Item #185
+  owns general version-drift detection; nothing here can retrofit a message into
+  an already-published executable. The new reader executes every journal
+  alpha.13 emitted, which is the backward-compatibility direction that had to
+  hold.
+
+- **A create must be committed before the next mutation, and there is still no
+  batch operation.** A created item has no earlier authorized revision, so Git
+  `HEAD` is the only surface that can carry its authorized bytes; an uncommitted
+  create raises the global `git-finalization-required` barrier for every later
+  mutation, including the next create. It cannot occupy the authorized
+  predecessor/successor window a `patch` or `transition` may occupy, and that
+  window was never permission to skip a commit. The supported bulk pattern is
+  the create-then-commit loop — filing ten items is ten cycles, and
+  `--auto-commit` on each create is its shortest form. Safe batch design is
+  item #186.
+
+- **The measured cost of the fence is two extra fsync'd journal appends.** A
+  provisioned create already took the namespace lock, replayed the journal,
+  loaded the ledger, read Git `HEAD`, and reconciled, so the fence adds no new
+  Git roster or history traversal to a clean create; on a 1,500-item fixture the
+  captured `git` invocation sequence is identical before and after. 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
+  reserved before the intent append, so an exhausted journal refuses unchanged
+  rather than stranding an attempt. Journal compaction is not part of this
+  change.
+
+### Fixed
+
+- **Two worktrees can no longer commit two items carrying the same number.**
+  Through alpha.13, `create` was journal-silent by design: it derived
+  `1 + max(existing numbers)` from the items its own checkout held and recorded
+  nothing in the shared claim journal. Two worktrees that had not integrated
+  each other's commits therefore derived the same number and both published,
+  and they did not have to race to do it — a create today and a create tomorrow
+  collided just as reliably, because the loser was a stale checkout rather than
+  a lost race. `number` is immutable and `patch` correctly refuses it, so the
+  collision surfaced only at integration, as a global `duplicate-number`
+  validation failure that stopped the whole ledger. On a provisioned ledger,
+  `create` is now a journaled legacy mutation: under the shared namespace lock
+  it reconciles, validates the complete candidate ledger, reserves journal
+  capacity, appends a `legacy-mutation-intent` with `command: "create-v1"` and
+  `expected_revision: null` before any byte reaches the item path, publishes
+  atomically and no-clobber, verifies the exact bytes, and appends its terminal
+  — `legacy-mutation` when the bytes landed, or an abort carrying
+  `command: "create-v1"` and `observed_revision: null` when the path stayed
+  absent. Allocation is fenced in front of all of that: every global finding
+  blocks `create` as it blocks any write, and in addition any coordinated item
+  this checkout does not hold blocks `create`, because its number cannot be
+  read here. A stale revision of an item this checkout does hold stays
+  nonblocking, because a number is immutable. A fenced create refuses with
+  exit 6, `state: "unchanged"`, `error.code: "claim-store-unavailable"`,
+  `error.details.reason: "publication-reconciliation-required"`, and no item
+  file; integrate the named item, run `claim-verify` to exit 0, and resend the
+  same request ID to take the next number. **What this fixes and what it does
+  not:** it closes the reported PropertyCompass2 collision, so cooperating
+  alpha.14 worktrees of one clone that share one Git common directory can no
+  longer commit 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`. A ledger that already carries duplicate numbers
+  is not repaired here; item #182 owns that fenced recovery. Core
+  `contract_version` stays `5` and the create success and refusal envelopes add,
+  remove, and rename no member.
+
+- **`create --auto-commit` commits its reconciliation log with the item.**
+  Because create now owns journal entries, its commit set is exactly the created
+  item and `<ledger>/.wowbagger/reconcile-<namespace>.md`, and
+  `mutation-finalize` accepts that same two-path recovery token. Between the
+  fence landing and this fix, `create --auto-commit` failed outright with
+  `git-commit-failed`, `failure_stage: "prepare-commit-set"`, and
+  `reason: "tree-changed"`, because the commit set excluded a log the mutation
+  had just written. Owning that log is not absorbing what was already in it:
+  `create` still refuses a reconciliation log that was dirty before the
+  invocation, and every other dirty ledger path still refuses.
+
+- **A revision Git can already reach is no longer an instruction to wait for
+  it.** When the expected revision was reachable only from a tag, a
+  remote-tracking ref, a branch no worktree had checked out, or a live worktree
+  on a detached `HEAD`, the `worktree-synchronization-required` finding rendered
+  the not-yet-reachable sentence: "wait for the owning worktree to commit, then
+  synchronize this worktree and run claim-verify." The commit already existed
+  and no named worktree was ever going to publish it, so that wait could not
+  end. Those cases now render: "Revision <revision> of <path> is reachable in
+  Git, but no active named worktree owner is established; inspect the reachable
+  history, restore or explicitly adopt reviewed bytes, then run claim-verify."
+  A revision no reachable commit carries keeps the not-yet-reachable sentence
+  and its wait, and an item that has never existed in this checkout keeps the
+  cannot-be-established sentence. **A consumer that matches on `remediation`
+  text must update its patterns:** a finding that used to match "not yet
+  reachable" now matches "reachable in Git" for the four reachable-unowned
+  cases. Nothing else moves. The `reason` stays
+  `worktree-synchronization-required`, the code stays `stale-write-detected`,
+  `owner_unavailable: true` with no `owner_ref` or `owner_commit` is unchanged,
+  the finding stays advisory — it blocks a mutation targeting its own item and
+  lets an unrelated mutation proceed — and core `contract_version` stays `5`,
+  because no field, code, reason, or scope changes and the text correction
+  replaces a false instruction.
+
+### Documentation
+
+- **Worktree identity and its refusals are now documented.** Alpha.13 shipped an
+  explicit worktree identity — an opaque random UUID a worktree creates once in
+  its private Git directory — and started recording it as the optional
+  `writer_worktree_id` member on `legacy-mutation-intent`, `legacy-mutation`,
+  `publish-intent`, and `publish-final` journal entries. Reconciliation reads it
+  to tell this worktree's own unreachable successor from a sibling's, which is
+  what turns that topology into a global `unauthorized-revision` barrier instead
+  of advisory `worktree-synchronization-required`. Alpha.13 also began refusing
+  before it classifies anything when two live worktrees answer to one UUID, or
+  when the worktree roster cannot be read to completion: exit 6
+  `claim-store-unavailable`, reason `claim-store-unreadable`, plus one new
+  `error.details.identity_diagnostic` carrying `duplicate-worktree-identity`
+  with `worktree_id` and `live_worktree_count`, or `worktree-enumeration-failed`
+  with no further member, and the same diagnostic inside
+  `auto-commit-preflight-failed` with `retryable: false`. All of that shipped
+  without a release note; the alpha.13 entry mentioned writer identity only in
+  passing while describing which callers read it. The work-claim contract
+  section 3.1, the mutation contract auto-commit preflight details, and the
+  installed skill now state the journal field, its alpha.12-and-earlier
+  compatibility (such entries stay valid, attribute nothing, and leave the
+  writer unknown), what the identity discloses in committed history, and both
+  diagnostics. Core `contract_version` stays `5` and no public request or
+  success envelope changes.
+
+- **Owner evidence names only an active named worktree, and the contract now
+  says so.** Through alpha.12 the owner search was a reachability search, so a
+  finding could report `owner_ref` naming a tag, a remote-tracking ref, or a
+  branch no worktree had checked out — an owner that could never publish
+  anything, and an instruction to wait forever. Alpha.13 replaced that with the
+  live worktree roster: this checkout first, then live worktrees on a branch
+  ordered by branch ref and then path, with bare and prunable records excluded.
+  `owner_ref` is therefore always the branch of a live worktree. A revision
+  reachable only from a tag, a remote-tracking ref, an unchecked-out branch, or
+  a live worktree on a detached `HEAD` now reports `owner_unavailable: true` and
+  no `owner_ref`. That narrowing shipped in alpha.13 with no release note, and
+  the alpha.11 note promising that a finding "retains that `owner_ref` and
+  `owner_commit`" no longer describes those cases. The contract and the
+  installed skill now state the roster rule, the three distinct meanings of
+  `owner_unavailable`, and which remediation sentence each one gets.
+
+- **Repository-wide `claim-verify` and target-scoped mutation are stated as
+  different questions.** The mutation contract still said a recorded write in
+  one worktree "refuses every mutation in the others", which target scoping
+  stopped being true before alpha.11. It now states the item scope, and both
+  contracts and the installed skill now say plainly that a successful mutation
+  is not proof of a globally clean claim store: `claim-verify` names no target,
+  so it stays exit 6 while any item in the repository carries a blocking
+  finding, including an unrelated one. Item #184 is open in triage to decide the
+  supported verification surface; nothing about that behavior changed here, and
+  a gate that demands a globally clean `claim-verify` on a repository with live
+  sibling work is still unsatisfiable.
+
+- **A refused reconciliation still persists the clock floor.** Reconciliation
+  has written its clock entry before it classifies anything since work claims
+  were implemented, so a command that then refuses with
+  `publication-reconciliation-required` has already advanced the durable
+  monotonic floor to `max(physical_utc, previous_floor)`. Section 4 documented
+  the floor only for authoritative lease decisions, so the pre-decision advance
+  and its one observable consequence were undocumented: because the floor never
+  rolls back, a lease or fence observed expired at that floor can never read
+  live again, and a holder on a ledger whose floor runs ahead of its own wall
+  clock may find its lease expired the moment it asks after clearing a barrier.
+  Behavior is unchanged; the contract now says it.
+
+- **The reconciliation topology classifier moved without changing an answer.**
+  The topology decision that was spread across owner lookup, diagnosis, and
+  scope inference now lives in one pure module,
+  `src/reconciliation-classifier.js`, which takes normalized evidence and
+  returns a typed decision. That type is internal: scope travels beside a
+  finding and no response has ever carried it, so a consumer must keep reading
+  the refusal rather than the `reason` string. Every public seam — reason,
+  blocking behavior, owner fields, remediation sentence, exit, state, and
+  envelope domain — is byte-identical to alpha.13 on every matrix row, which is
+  the whole point of the change and the only claim made for it. No behavior
+  shipped with it.
+
+## 0.1.0-alpha.13 - 2026-08-28
+
+### Fixed
+
+- **Every reconciling command reads the same writer evidence.** `claim-verify`
+  and ordinary mutations named the worktree they spoke for when they
+  classified reconciliation; `publish-claimed`, `claim-adopt`, and the
+  `claim acquire`, `claim renew`, and `claim release` lifecycle commands did
+  not. An unreachable successor written by the current worktree therefore read
+  as advisory sibling synchronization on those surfaces, whose target scoping
+  let `publish-claimed` commit a publication and `claim acquire` grant a claim
+  in exactly the state a `patch` refused. `publish-claimed`, `claim acquire`,
+  and `claim renew` now report `unauthorized-revision` and refuse, matching
+  `claim-verify`. `claim release` stays available: it relinquishes authority
+  rather than extending it, and refusing it would strand the lease in the
+  worktree least able to clear the barrier, because no other worktree can take
+  the item over while the claim is held. The release compare-and-swap is
+  unchanged, so a wrong owner, epoch, or expiry still refuses with
+  `claim-conflict`. A genuine sibling successor and an authorization written
+  before writer identity existed remain advisory synchronization on every
+  surface. `claim-adopt` semantics are unchanged: it reports no reconciliation
+  diagnosis and stays available as the remedy. It now judges its own identity
+  bytes before the worktree roster, so its own malformed identity reports as
+  such instead of as a failed sibling enumeration.
+
+### Known limitations
+
+- **Creates in more than one worktree can commit duplicate item numbers, even
+  when the creates are sequential, and no sanctioned repair exists** (items
+  #181 and #182). Create is journal-silent, so nothing coordinates the number
+  it derives. Any two worktrees whose checkouts have not been integrated derive
+  the next schema-v2 `number` from the base each can see, and both derive the
+  same one. The two creates need not overlap in time: a create in one worktree
+  today and a create in another worktree tomorrow collide just as surely, so
+  long as neither worktree has seen the other's commit. Each create succeeds,
+  each refuses nothing, and reconciliation reports nothing. The collision only
+  exists once the branches are integrated. `validate` then fails globally with
+  `duplicate-number` on every colliding item, and because an invalid ledger
+  blocks every mutation, the whole ledger stops accepting work. `number` is
+  immutable and `patch` correctly rejects it, so Wowbagger currently offers no
+  operation that repairs the collision.
+
+  Until both items ship, serialize `create` through a single worktree, and run
+  `validate` immediately after you integrate branches so a collision surfaces
+  at the merge rather than at the next mutation.
+
+  The PropertyCompass repair — editing `number` in the item source by hand,
+  committing it, then running `claim-adopt` — was an emergency intervention
+  taken under an outage. It is **not a supported workaround**. It bypasses the
+  number-collision and reference checks every mutation performs, and it can
+  leave dangling `depends_on`, `related`, and parent references that nothing
+  reports. Do not adopt it as routine practice.
+
+## 0.1.0-alpha.12 - 2026-08-28
+
+### Fixed
+
+- **Out-of-protocol local states remain global reconciliation barriers.**
+  Alpha.11 could misclassify an unknown committed revision, an authorized
+  working-tree predecessor over an unknown `HEAD`, or a working-tree deletion
+  over an authorized `HEAD` as advisory sibling synchronization when another
+  worktree owned the expected revision. `claim-verify` still failed, but an
+  unrelated mutation could proceed through the documented global barrier.
+  Alpha.12 classifies local state before owner and target scope, while genuine
+  authorized sibling predecessors remain target-scoped synchronization.
+- **Windows report path resolution preserves the read-failure error class.**
+  Windows can report `ENOENT` where POSIX reports `ENOTDIR` when an output path
+  descends through a regular file. Report generation now recognizes that
+  non-directory ancestor and returns `report-read-failed` with
+  `resolve-output-path` and `ENOTDIR` before publication, instead of surfacing
+  `report-write-failed` with `EEXIST`.
+
+## 0.1.0-alpha.11 - 2026-08-27
+
+### Fixed
+
+- **Uncommitted sibling revisions keep target-scoped reconciliation safe.**
+  Previously authorized predecessor bytes now identify an in-protocol sibling
+  window without turning genuine hand edits or same-branch regressions into
+  nonblocking findings.
+  Restoring earlier authorized bytes in the same working tree remains
+  `unauthorized-revision` when the current branch owns the expected revision.
+  Detached `HEAD` uses its reachable history for the same current-owner guard,
+  so it cannot turn that regression into advisory sibling synchronization.
+  When Git proves that a sibling ref owns the expected revision, the finding
+  retains that `owner_ref` and `owner_commit` instead of reporting the owner as
+  unavailable.
+- **Journal-owning auto-commit rebuilds its derived reconciliation log.** Claim
+  decisions may dirty that tracked projection; patch, transition,
+  parent-migrate, snooze, and publish-claimed now validate and commit the rebuilt
+  log while every foreign dirty ledger path and create still refuse.
+- **Claim-verification failures preserve their cause.** Preflight and
+  post-commit errors carry the underlying claim verification code and reason;
+  claim-store lock contention is retryable while persistent reconciliation is
+  not.
+  `mutation-finalize` recovery now carries the identical diagnostics without
+  inventing a `findings` member.
+- **Auto-commit uses target scope before and after committing.** Unrelated
+  synchronization findings no longer turn a successfully committed mutation
+  into a reported post-commit failure; target-blocking findings remain fatal and
+  visible through claim-verify.
+
+### Changed
+
+- **Parent migration and snooze now have complete contract guidance.** The
+  contract and installed skill document their requests, CAS and date rules,
+  response domains, auto-commit behavior, and legacy journal fence-family
+  semantics. Parent-migrate help no longer invents a live-item restriction.
+- **Parent and snooze fields are documented as dedicated mutations, not
+  create-once values.** Existing items can be repointed to or from an epic with
+  `parent-migrate`, and `snooze` can set or clear `snoozed_until`; `kind` and
+  `provenance` remain genuinely create-once.
+- **Release numbering preserves the unpublished alpha.10 cut.** Alpha.10 was
+  cut and tagged but never published to npm. This release advances to alpha.11
+  instead of moving that tag, so tag identity remains immutable and the
+  registry history honestly skips alpha.10.
+
+### Known limitations
+
+- **Parent-migrate and snooze lock owners lose diagnostic detail.** Their real
+  lock still refuses every concurrent mutation, but the refusal currently
+  reports `owner: null` with `owner_diagnostic: "invalid-shape"`. Item #174
+  tracks restoring those owner details; mutual exclusion is unaffected.
+- **Ownership classification still needs one consolidated topology audit.**
+  Items #173, #176, and #177 close every case identified so far. Item #178
+  remains open to audit the topology as one matrix because each point fix
+  revealed an adjacent gap.
+
+## 0.1.0-alpha.10 - 2026-08-26
+
+### Fixed
+
+- **Cross-worktree reconciliation is target-scoped.** An unrelated item
+  mutation no longer refuses because another worktree has a committed revision.
+  When synchronization is required, the finding names the owning reference.
+- **Fresh clones recover committed claim history.** Reconciliation hydrates an
+  empty local claim journal from the committed reconciliation log, while
+  lock-free claim reads project that history without writing. Invalid or
+  over-capacity committed sequences fail closed.
+- **Auto-commit recovery handles refusal and no-op paths.** Refused preflight
+  checks no longer rewrite the tracked reconciliation log. The first
+  post-provision create works, byte-identical mutations commit only their log,
+  and `mutation-finalize` accepts the corresponding log-only recovery after
+  `HEAD` advances.
+- **Parent migration and snooze expose their guarded write contracts.**
+  Both commands support auto-commit, report their own response domains, return
+  a single unchanged invalid-request envelope, and report stale parent
+  witnesses as conflicts.
+- **Create reserves the `extensions` request container.** Item data must name
+  extension members directly so patch and extension declarations can address
+  them.
+- **Auto-commit preflight reports retryability explicitly.** Only a held
+  auto-commit mutex is retryable.
+- **CLI and release metadata stay discoverable and complete.** Help describes
+  claim verification and list requests, and the release-site manifest covers
+  historical version records.
+
 ## 0.1.0-alpha.9 - 2026-08-23
 
 ### Added