wowbagger 0.1.0-alpha.5 → 0.1.0-alpha.7

package/CHANGELOG.md

@@ -5,8 +5,515 @@ A change to what a command accepts, refuses, emits, or writes is a behaviour
 change even when the commit that carried it was labelled refactor, docs, or
 consolidation. The first tagged release inherits this file.
 
+## Unreleased
+
+## 0.1.0-alpha.7 - 2026-08-18
+
+### Changed
+
+- **The item source is bounded at every candidate door, and the core contract
+  moves to 4.** The published version 3 core accepted a 50-MiB `create` with
+  exit `0` and state `committed` in 0.70 s: `create`, `transition`, and `patch`
+  had no bound
+  anywhere, and `publish-claimed` alone bounded candidates but reported an
+  oversized, perfectly canonical candidate as `The candidate source is not
+  canonical base64.` One shared `MAX_ITEM_SOURCE_BYTES` of 8,388,608 now bounds
+  the complete serialized successor at all four doors, and every one of them
+  answers the same named refusal: `item-source-too-large`, exit 2, state
+  `unchanged`, details exactly `{id, size_bytes, limit_bytes}` in the core
+  domain and `{item_id, size_bytes, limit_bytes}` in the ledger-publication
+  domain. The measurement is serialized UTF-8 bytes, so frontmatter, decisions,
+  extensions, and body all draw on the same budget; `transition` is bounded
+  because its decision block can push a legal stored item past it. Core
+  capabilities advertises the value at `result.limits.max_item_source_bytes`.
+  This narrows accepted input against a published version, so the core contract
+  moves to 4 and version 3 consumers fail closed at negotiation. A ledger
+  committed before the bound does not brick: an oversized item still validates,
+  still inspects, and a patch that shrinks it under the bound is accepted.
+
+- **The work-claim API moves to 2.** The oversized-candidate response replaces
+  the error `publish-claimed` version 1 pinned for that input, so
+  `result.operations.work_claim.api_version` is now `2` and version 1 consumers
+  fail closed. Malformed base64 keeps its version 1 `invalid-request`: without
+  canonical base64 there is no item source to measure. The base64-character
+  precheck is gone — the 11,534,336-byte serialized-request bound already caps
+  what a candidate can decode to, and the precheck was the remaining path that
+  answered a genuine size refusal with a false base64 message. That transport
+  bound is unchanged and still measures a different object.
+- **A claimed publication no longer takes one cooperative lock per ledger
+  item.** `publish-claimed` computed its lock closure from every item in the
+  loaded ledger, so publishing one item on a 1,500-item ledger created, wrote,
+  fsynced, and unlinked 1,503 lock files. It runs from journal replay through
+  its terminal record inside the namespace write lock, and every other
+  cooperative writer of a provisioned ledger enters that same lock before it
+  writes, so the per-item closure excluded nobody the namespace lock did not
+  already exclude. Publication now takes no per-item locks. Newly instrumented
+  phase counters measured the cost this removes: on 1,500 items the lock phase
+  was 11.2 s of the 12.6 s the publication took, against 0.2 s for reading Git
+  HEAD. Everything else is unchanged and proved byte-for-byte identical against
+  the previous implementation across all six publication outcome classes —
+  success, fence refusal, revision conflict, validation refusal, idempotent
+  replay, and indeterminate publication — in envelope, claim journal, and item
+  bytes. Every cooperative writer of one ledger must be upgraded together: a
+  writer that honors only per-ID locks can race one that honors only the
+  namespace lock.
+- **The README installs with `@next` and says why.** The registry mandates a
+  `latest` dist-tag, so `latest` mirrors `next`; `@next` stays the documented
+  spelling and the explicit prerelease consent.
+- **Cuts happen on the release branch, not in a session worktree.** Merge
+  session work first, then cut; the cut command refuses to run anywhere but the
+  branch tip. The previous two-phase topology is why the last two release tags
+  name merge commits rather than their cut commits.
+  `docs/adapter-release-path.md` records the ritual.
+
+### Fixed
+
+- **A live publication is no longer reported as a broken lock.** Publication
+  lock files recorded `"operation": "publish-claimed"`, but the lock reader
+  accepts only `create`, `transition`, and `patch`, so a concurrent writer that
+  hit a live publication lock classified it `invalid-shape` — a diagnostic that
+  says the lock is corrupt. Publication writes no lock files at all now, so
+  there is nothing to misclassify.
+
+- **A committed `patch` is forwarded instead of reported as an unknown
+  outcome.** The shipped adapter engine still named the pre-widening patchable
+  pair `number` and `priority`, so every patch a consumer actually sends — a
+  body rewrite, a title correction, a relation-list replacement, a declared
+  extension member — read as a non-canonical request, failed result
+  correlation, and came back `mutation-outcome-unknown` with recovery guidance
+  about a write that had provably committed. `number` is the immutable item
+  identity and was never patchable at all. The patchable field set is now what
+  mutation contract section 9 names — `title`, `priority`, `depends_on`,
+  `related`, `body`, `body_append`, and `extensions` — with the two body write
+  modes mutually exclusive and the extensions container judged only on its own
+  shape, and correlation follows each member to the surface it is observable
+  on. The independent reference model already had all of this, so the drift was
+  one-sided and no differential test could see it; the new end-to-end
+  core-outcome vectors found it on their first run.
+
+- **`publish-claimed` now reconciles the journal unconditionally, like every
+  other mutating command.** The work-claim contract has always said an
+  uncommitted prior mutation refuses the next `create`, `transition`, `patch`,
+  **or `publish-claimed`**. The code only reconciled when it happened to
+  observe an unresolved `publish-intent`, and an uncommitted legacy mutation
+  leaves none behind. A fixture pinned the gap: with a legacy create and
+  transition sitting uncommitted, `claim-verify` returned exit 6 and a legacy
+  `create` refused with `publication-reconciliation-required`, while
+  `publish-claimed` on a claimed item published straight over the unreconciled
+  ledger. It now reconciles before the fence decision on every publication and
+  refuses with exit 6 `claim-store-unavailable`,
+  `details.reason: "publication-reconciliation-required"`, and
+  `details.findings` — the same envelope the legacy fence emits, so one
+  `claim-verify` clears every blocked path. **A publication behind an
+  unresolvable prior intent now returns that refusal instead of exit 6
+  `publication-outcome-unknown`.** The old code named the refused publication's
+  own outcome uncertain when it had not run at all; `state: "unchanged"` is the
+  honest answer, and the blocking finding still travels in `details.findings`.
+  The cost is honest about which read is new. Reconciliation adds no
+  complete-ledger read: it produces the snapshot the candidate validation and
+  the mutation engine's pre-lock read already share, so a claimed publication
+  still reads the working-tree ledger exactly twice. It does add the Git `HEAD`
+  read — `rev-parse`, one `ls-tree`, and a batched `cat-file` over every item
+  blob at `HEAD` — to every publication that previously had no unresolved
+  intent. That is the same read `create`, `transition`, `patch`, and every
+  claim lifecycle command already perform, so `publish-claimed` now pays the
+  toll its peers pay rather than a new one. Each publication persists one clock
+  floor, as it did before; a publication behind a pending intent, which used to
+  persist two, now persists one as well.
+
+- **A shipped adapter no longer advertises trusted approval it cannot
+  exercise.** The three shipped entrypoints declared
+  `trusted_approval: {"supported": true, "sources": ["consumer"]}` while
+  `runAdapterEntrypoint` passed no approval, clock, nonce store, or core
+  executable identity to the invoke engine, so `create`, `transition`, and
+  `patch` through every shipped adapter refused `consumer-approval-required`
+  and could not succeed on any input. The declaration now reflects the runtime
+  of the invocation, the way `optional_features.claims` already reflects the
+  core probe: a bare entrypoint run declares no trusted approval and refuses a
+  mutation `capability-unavailable` with `missing: ["trusted-approval"]`, the
+  refusal section 5.1 already required for an absent declaration, and a host
+  that wires an approval source declares it truthfully. The two refusals stay
+  distinguishable, because they are different facts — no approval source at all
+  versus a source that produced no approval for this invocation — and conformance
+  case `07-mutation-approval` now pins both against the runtimes that produce
+  them, adding one assertion to the conformance suite.
+- **A committed `create` is forwarded instead of reported as an unknown
+  outcome.** Both adapter engines required `schema_version: 1` in a create
+  result and re-serialized the expected candidate with the schema 1 default, so
+  every create against a real ledger — an empty ledger is schema 2 — failed the
+  result correlation, was judged an invalid core envelope, and came back as
+  `mutation-outcome-unknown` with recovery guidance about a write that had
+  provably committed. The ledger's schema version and the number the core
+  assigns under its own lock are the only two members of the answer a caller
+  could not have known; both engines now read those from the result and
+  re-derive the whole candidate from the request bytes, leaving every other
+  member pinned by an exact byte comparison against the source the core
+  returned. The defect was unreachable while every shipped mutation refused
+  before launch, and surfaced the moment a host runtime carried a real approval
+  through to the core.
+- Adapter contract section 5's core-request table and section 5.1's approval
+  rule named only `create` and `transition`. Both have accepted `patch` since
+  adapter contract version 2; the prose now says so.
+
+### Added
+
+- **The conformance suite now measures real core outcomes end to end.** A new
+  equivalence case, `16-core-outcome-e2e`, carries nine hand-authored scenarios
+  that each run the direct real core in one isolated temporary workspace and,
+  separately, spawn the real shipped entrypoint over the bootstrap wire against
+  the real core in a second workspace materialized from the same before state:
+  `inspect` item-not-found, a committed `create`, a committed `transition`, a
+  committed `patch` by body replacement and by declared extension member, the
+  six-member date refusal, and all three `ledger-mutation` claim-fence refusal
+  classes. Success vectors match the exact core exit, stdout bytes, decoded
+  adapter streams with their digests and lengths, and the exact ledger
+  post-state; refusal vectors match the exact nonzero exit and unchanged ledger
+  bytes, and the fence refusals arrive as `ok: true` adapter transport results
+  rather than adapter errors. Before this case, no conformance assertion and no
+  bootstrap-wire test carried a mutation through a spawned entrypoint into a
+  launched core, which is how two real adapter defects shipped. The suite is
+  210 assertions across 16 cases.
+
+  Determinism comes from fixed inputs and never from normalizing output: a
+  caller-supplied ULID, seeded revisions on isolated temporary ledgers, literal
+  dates, and — for the two real claim-fence read-backs — a fixed namespace, a
+  hand-authored claim journal, and a seeded future clock floor, so the emitted
+  `observed_at` is `max(physical_now, floor)` and therefore the floor. That
+  makes the refusal bytes fixed without mocking the core clock, and it expires:
+  both runners fail loudly and name `2031-01-15T12:01:00.000Z` once wall time
+  reaches it. Goldens are authored from the adapter contract, the work-claim
+  contract, and the normative `spec/fixtures/mutations/**` bytes; every byte
+  reused from those fixtures carries a `derived_from` pin, so drift on either
+  side stops the vector and asks for a reviewed golden change instead of
+  regenerating one. Only base64, SHA-256, and byte length are derived, and only
+  from an already hand-authored byte string.
+
+  The conformance host gains a granting approval mode, without which no
+  mutation can cross the spawned entrypoint at all. **Adapter contract section
+  10 previously said no conformance fixture could manufacture authority; that
+  is no longer true, and the claim is withdrawn rather than quietly narrowed.**
+  What replaces it is narrower and checkable: the granting mode is reachable
+  only from a fixture's own runtime configuration, which no shipped adapter
+  package reads and no wire this contract defines carries; every granting
+  scenario runs against a throwaway temporary ledger; the approval is minted
+  from the binding the engine resolved and canonicalized by the independent
+  reference model. The evidence label is the production adapter engine under a
+  conformance host approval provider, not a live consumer approval mechanism.
+
+- **A host process can wire consumer approval into a shipped adapter
+  entrypoint.** `runAdapterEntrypoint` now accepts an optional `hostRuntime`
+  carrying the approval source, the current time, the redeemed-nonce store, and
+  the core executable identity the host attests. It is a code-level parameter of
+  the embedding process and is deliberately absent from every wire: the
+  bootstrap request root schema is exact and has no approval member, so an
+  approval a model places on the request is an `invalid-invocation` that never
+  reaches the gate, exactly as adapter contract section 5.1 requires. The
+  approval may be a finished event or a resolver the adapter calls with the
+  exact binding it has just resolved — the argument vector, absolute workspace
+  paths, and instruction and handoff digests an approval covers do not exist
+  until the adapter has built them, so an interactive consumer prompt cannot
+  mint the approval any earlier. A resolver that fails produced no approval and
+  the mutation refuses; it never proceeds unapproved. The default is unchanged
+  and remains no approval. `test/adapter-host-approval-wire.test.js` carries the
+  first approved mutation in this repository to cross a spawned entrypoint into
+  a launched core and change a ledger, with its binding digest canonicalized by
+  the independent reference model rather than by the engine under test. No
+  version moved in any domain: `host.trusted_approval` has been optional since
+  version 1, the approval object and binding are untouched, and the mechanism is
+  invisible on every wire the contract defines. Adapter contract sections 3.2,
+  3.3, 5.1, 10, and 12 state the seam, the honesty rule, the two-runtime
+  evidence, and the version argument.
+
+- **The cut is one command, and version drift now fails the cut instead of
+  shipping.** `npm run release:cut -- <version> --date YYYY-MM-DD` runs on the
+  tip of the release branch, proves every version site is accounted for, plans
+  the new bytes in memory, runs the full release gate over them, and leaves one
+  `Cut <version>` commit and one annotated `v<version>` tag. It stops there:
+  push, `npm publish --tag next`, and the registry check stay separate named
+  steps, because no local command can undo any of them. Coverage is proved by
+  exact-set equality against a hand-maintained
+  `scripts/release-version-sites.json`, not by a global grep — the changelog and
+  the dated design records must keep naming old versions, so "grep finds
+  nothing" would be the wrong test. A release site added next month is
+  unmanifested and refuses the cut. `--dry-run` runs the same planner and the
+  same gate against a copy of HEAD and then proves the repository unchanged.
+  Reruns converge rather than repair: a cut tag at a clean HEAD reports
+  `already cut`, a complete cut commit without its tag resumes at tagging, and a
+  tag pointing elsewhere refuses.
+- **The changelog can no longer lose its Unreleased section.** A cut opens a
+  fresh empty `## Unreleased` and files the released notes beneath it. The two
+  previous cuts renamed the heading instead, which left later changes landing
+  under an already published release.
+- **The prerelease channel policy is stated and checkable.**
+  `npm run release:channels -- check|repair <version>` encodes it: `latest`
+  mirroring `next` at the published version and the first published alpha
+  deprecated. The first-choice policy — no `latest` at all, so a bare install
+  fails loudly — was refused by the registry itself: npm rejects deleting the
+  `latest` tag with E400 (verified live), so the current prerelease replaces
+  the dead first alpha as the forced default. `check` is read-only and is the
+  post-publish verification step; `repair` is idempotent and never unpublishes.
+
+- **`--auto-commit` folds the commit-per-mutation ceremony into the mutation.**
+  The invariant is correct and the ceremony around it was the consumer's most
+  frequent daily cost: mutate, `git add`, `git commit`, `claim-verify`, repeat,
+  ten times for ten items. On a provisioned merge-coordinated ledger the new
+  opt-in bare flag on `create`, `transition`, `patch`, and `publish-claimed`
+  does that loop inside one invocation. It takes a per-working-tree mutex,
+  refuses any staged path anywhere and any dirty path under the ledger, checks
+  Git identity, runs an internal pre-mutation `claim-verify`, runs the mutation
+  unchanged, then commits **exactly** the changed item plus at most one
+  `.wowbagger/reconcile-<namespace>.md` under a fixed subject
+  (`wowbagger: transition item #7`; the canonical item ID for a schema-1 item
+  with no number). It verifies the resulting commit's parent, subject,
+  changed-path set, and every blob, then runs `claim-verify` again before it
+  answers. Success adds `git_commit`, `commit_paths`, and `claim_verified` to
+  `result`.
+
+  There is no configuration file setting, environment default, or repository
+  default, because a hidden default would make existing mutation automation
+  create Git commits unexpectedly. An invocation without the flag is
+  byte-identical to before, so the core contract stays 3 and the work-claim API
+  stays 1. The flag is direct-CLI only in this release; no adapter advertises or
+  constructs it.
+
+  What it will not do: commit anything on `state: "unchanged"` or
+  `state: "unknown"`, including the documented reconcile-log residue a refused
+  `publish-claimed` leaves behind; stage a path outside the ledger; broad-add,
+  amend, squash, reset, clean, stash, or unstage; pass `--no-verify` or disable
+  signing; fabricate an author; customize a commit message; or push, fetch,
+  pull, merge, or rebase. Hooks through `core.hooksPath`, `commit.gpgSign`, and
+  signing programs are honoured, and a hook that rewrites the subject or the
+  tree is reported rather than accepted.
+
+- **An honest commit-failed contract, and one idempotent recovery verb.** A
+  post-publication Git failure that proves the commit is absent is exit 6
+  `git-commit-failed` with `state: "committed"` — the state still describes item
+  publication, not Git finalization — carrying the published revision, the exact
+  ledger-relative commit set with digests, `failure_stage`, `reason`, and a
+  bounded `recovery_token`. `create`, `transition`, and `patch` keep the core
+  domain; `publish-claimed` keeps `ledger-publication` and its top-level
+  `operation_id`. An **ambiguous** Git outcome is `git-commit-outcome-unknown`,
+  never `git-commit-failed`, and a commit that stands while reconciliation then
+  refuses is `post-commit-reconciliation-failed`. No failure envelope carries
+  hook output, signing output, absolute paths, or environment values.
+
+  New command: `wowbagger mutation-finalize --ledger <dir> --recovery-token
+  <token> --json`, answering in the work-claim domain because it changes Git
+  reconciliation state and no item byte. It re-derives every path from the
+  ledger and the provisioned namespace — the token is a witness, never authority
+  to select a path — re-checks the current bytes and the foreign-change rules,
+  creates the exact commit if it is absent, then runs `claim-verify`. When
+  `HEAD` already holds that exact commit it verifies and returns it without
+  creating a second one, so a lost response and a failed commit recover through
+  the same command, and repeating it is safe.
+
+  A failed attempt leaves its own commit set staged, because the design forbids
+  unstaging. Recovery tolerates exactly that residue and refuses anything else
+  staged; until it runs, the next `--auto-commit` invocation refuses on
+  `staged-paths-present`, which is the intended signal.
+
+## 0.1.0-alpha.6 - 2026-08-17
+
+### Added
+
+- **`set.extensions` gives consumer-owned extension members a sanctioned patch
+  path.** Two field reports in two days: a consumer's own identifier field
+  rides a permitted extension member, and a wrong or missing one had no
+  ledger-side repair verb at all. On a provisioned ledger the hand-edit that
+  filled the gap is a stale write, so the protocol was forcing the edit it then
+  punished. `patch` now accepts an `extensions` container whose members name
+  extension members and whose values replace each one whole; `null` removes a
+  member. The fixed `set` allowlist is unchanged — `extensions` is one more
+  name on it, not an opening for arbitrary keys — so a top-level typo is still
+  an `unknown-member` refusal. Which members the container may name comes from
+  the committed `<ledger>/.wowbagger/extensions.json`, which declares a member
+  name and one value type each (`string`, `integer`, `boolean`, `string-list`).
+  **A ledger without that file has no patchable extension member at all**, and
+  the refusal names the missing declaration. Five new
+  `patch-precondition-failed` issue codes carry the refusals —
+  `extension-declaration-missing`, `extension-declaration-invalid`,
+  `extension-not-declared`, `extension-value-invalid`, `extension-anchored` —
+  in the existing four-member issue shape, with the member at fault named in
+  `field`. A member the item writes with a YAML anchor or alias is refused
+  rather than replaced, because replacing it would change every node bound to
+  the anchor; every member the request does not name keeps its exact
+  `extensionNodeIdentity` guarantee. The declaration authorizes a write and
+  never describes the ledger: `validate` does not read it, so an item whose
+  extension member disagrees with it stays valid and stays repairable. Nested
+  extension values still have no patch path and stay a reviewable hand-edit.
+  Core contract version stays 3 — the patch request schema widens and no
+  response envelope member is added, removed, or renamed — but version 3 is
+  published, so `contract_version` cannot answer whether a core carries this:
+  probe by sending an extension patch and reading the refusal, or pin the
+  distribution version. Documented in mutation contract section 9 and pinned by
+  `spec/fixtures/mutations/patch-extensions/`.
+
+- **`claim-adopt` gives `unauthorized-revision` a non-destructive remedy.** A
+  consumer's staging checkout was blocked exit 6 on three items whose bodies
+  were hand-edited in a design session and merged. The refusal was correct, but
+  the only documented remedy — restore the authorized revision, then
+  `claim-verify` — discards reviewed, merged work. `claim-adopt` records that an
+  operator ruled the committed bytes legitimate and moves the coordinator's
+  authorized revision to them. It writes no item byte, so `updated` and the body
+  survive exactly. It is a standalone verb in the work-claim domain, a sibling
+  of `claim-verify`, and it is per item and per revision explicit: the request
+  names the item, the revision it believes is authorized, the revision being
+  adopted, and who is ruling. There is no adopt-all. It refuses
+  `adoption-witness-mismatch` on a stale witness (including a replay of a
+  successful adoption), `claim-held` while an unexpired claim holds the item,
+  `adoption-revision-uncommitted` unless the adopted revision is at Git `HEAD`
+  and in the caller's own working tree, and `adoption-ledger-invalid` when the
+  complete ledger would not validate. Success appends one `revision-adoption`
+  journal entry naming who, when, and both revisions, so the audit trail records
+  the ruling instead of losing it. Adoption is not a fence hole: the next
+  out-of-protocol edit is `unauthorized-revision` again, measured against the
+  adopted revision. Additive at contract version 1 — one new command, one new
+  journal entry type, three new error codes, no existing shape changed.
+  Documented in work-claim contract section 3.3 and pinned by
+  `spec/fixtures/work-claims/revision-adoption/`.
+
+### Changed
+
+- **The report's epic-enablement factor now counts done or killed children
+  only.** It counted every child carrying a terminal date, which folded
+  archived and deferred children into the numerator: an epic with one done,
+  one archived, one deferred, and one backlog child reported enablement 0.75
+  while the mutation contract's terminal ratio for the same epic was 0.25. Two
+  numbers wore one name. A terminal date is not a terminal disposition —
+  archived restores and deferred undefers, both documented edges — so a parked
+  child is work postponed, not work retired, and counting it reported progress
+  that one transition takes back. The factor now reads the same done-or-killed
+  set as the contract and the epic complete rollup: one definition, three
+  surfaces. This is display-only and recomputed at render time; no ledger byte,
+  no wire shape, and no `ready` ordering changes. What does change is the
+  report: an epic with parked children reports a lower percentage, and its open
+  children rank lower on the epic-enablement step of `work next`.
+- **Every `unauthorized-revision` remediation string now names both remedies.**
+  It was one sentence naming only the restore path, which reads as an
+  instruction to throw the edit away; the field report above did exactly that.
+  It is now two sentences, and each says what happens to the edit: `Restore the
+  authorized revision at <path>, then run claim-verify; that discards the edit.
+  Or adopt the committed revision of <path> with claim-adopt, then run
+  claim-verify; that keeps the edit.` The finding's `code`, `reason`,
+  `observed_surface`, `expected_path`, and revisions are unchanged; only the
+  human-readable `remediation` prose changed. `revision-regression` keeps its
+  restore-only string on purpose: it only fires while an active claim holds the
+  item, which is a state adoption refuses.
+- **`patch` corrects an item title.** `set.title` takes a non-empty schema
+  string and replaces the title whole, under the same per-ID lock, exact-byte
+  compare-and-swap, candidate complete-ledger validation, and atomic
+  publication as every other patch; an item with an active claim is refused,
+  and `updated` moves to `request.date`. The scalar node is rewritten in place,
+  so the quoting style, the comments, the anchors, and every extension node
+  survive byte for byte. This closes a protocol contradiction reported twice
+  from the field: correcting a title used to require an out-of-protocol edit,
+  and on a provisioned ledger that edit is a stale write, so the next mutation
+  refused exit 6 `unauthorized-revision` and every later mutation stayed
+  blocked. `null` follows the frontmatter removal convention onto
+  `candidate-invalid`, because title is required; `""` is refused one step
+  earlier, at the request.
+- **The mutation contract states the frontmatter ownership boundary.** Section
+  9 gains a `Frontmatter ownership` table: one row per member, sorted into
+  core-owned (`schema_version`, `id`, `number`, `status`, `created`, `updated`,
+  the terminal dates, `decisions`), consumer-editable through `patch` (`title`,
+  `priority`, `depends_on`, `related`, `body`), and create-once (`kind`,
+  `provenance`, `parent`, `snoozed_until`). The boundary was previously
+  discoverable only by sending a patch and reading the refusal. A docs test
+  pins every row and the skill teaches the same three classes.
+
+### Decided
+
+- **`kind` stays unpatchable, and the contract now says why.** A task-to-epic
+  flip changes which parent and children rules the item is validated under and
+  which lifecycle edges it may take. It needs its own verb with its own
+  preconditions, not a wider patch set.
+- **Extension members stay out of `patch`, and the contract records the
+  reasons.** Two field reports asked for a sanctioned path for consumer-owned
+  identifier fields riding permitted extension members. The widening was
+  assessed against title's machinery and is not the same machinery: the
+  fail-closed `set` rule has no room for an arbitrary key, candidate validation
+  constrains no extension value, nested and anchored values do not survive a
+  whole-value replace the way a scalar does, and the oracle has no observable
+  surface to correlate an extension patch against. Section 9 names what a real
+  path would need — a `set.extensions` container, a declared per-ledger
+  extension schema, a stated rule for anchored and nested values, and an
+  oracle-visible surface — so the deferral is a design boundary rather than a
+  silence. Their status is stated in the ownership table either way.
+- **`patch` gains `set.body_append`.** It takes a JSON string written after the
+  item's current body, under the same string rules `set.body` takes: the empty
+  string is valid, the bytes are the UTF-8 encoding of the string exactly, and
+  `null` is refused at `/set/body_append` because appending nothing is the empty
+  string. It is the same byte splice after the closing delimiter, so no
+  frontmatter byte moves, `updated` becomes request.date, and every existing
+  body byte survives — the request never names them. `body` and `body_append`
+  are mutually exclusive in one request: naming both is an `invalid-request`
+  issue at `/set`, exit 2, unchanged. This covers the annotation shape a mirror
+  consumer needs without making it carry a merge. The core contract stays
+  version 3 — it widens the patch request schema and moves no response envelope
+  member — but version 3 is already published without it, so a consumer
+  **cannot** probe for append support by reading `contract_version`. Send an
+  append and read the refusal instead: a core without it answers `unknown-member`
+  at `/set/body_append`, exit 2, unchanged.
+
+### Documentation
+
+- **The allowed-edges table carries the defer and undefer edges.** `task` and
+  `epic` `backlog` to `deferred` and `deferred` to `backlog` have shipped in
+  `src/mutation.js` since deferral existed, both requiring a decision, and the
+  ownership table already documented `deferred` as a core-owned field that
+  `transition` writes on a defer. Section 8's edge table listed neither row, so
+  the one place a consumer looks up what it may drive under-reported the
+  lifecycle by two edges. Both rows are added with the evidence the code
+  generates — `set deferred; append defer decision` and `clear deferred; append
+  undefer decision` — and a docs guard pins the kind, the date, and the
+  decision on each. No emitted byte changes and the core contract stays version
+  3: this documents shipped edges, it does not add them.
+
+- **The epic derivation section cites one shared definition instead of a
+  divergence.** It recorded the report's epic-enablement factor as a different,
+  wider number than the terminal ratio. The report factor was narrowed to match
+  (see Changed above), so the paragraph is replaced: the contract, the epic
+  complete rollup, and the report all count done or killed direct children over
+  all direct children, and the section now says outright that a terminal date is
+  not the test. The docs guard is re-pointed at the new truth rather than
+  relaxed.
+
+- **The contract states that `set.body` replaces and never merges.** A consumer
+  mirroring an external source regenerated an item body from its upstream card
+  and destroyed a ledger-only annotation; every check passed, because
+  `expected_revision` is a byte-level lost-update guard with no semantic safety.
+  Mutation contract section 9 and the skill's body bullet now say it plainly:
+  the replacement is total, and a mirroring consumer MUST read-modify-write from
+  the current item body and MUST never regenerate from the source alone. Docs
+  guards pin both sentences.
+
+- **The contract documents the selector an `inspect` `item-not-found` refusal
+  echoes.** `inspect --number <n>` on a number no item carries emits
+  `details: {"number": <n>}`, and it has done so since `--number` shipped in
+  0.1.0-alpha.5. Mutation contract section 5 claimed these details contain only
+  `id`, so the published prose and the published wire disagreed. Section 5 now
+  states the rule the runtime follows — the details carry exactly the selector
+  the request used, `id` for `--id` and `number` for `--number` — and
+  `spec/fixtures/mutations/inspect-number-not-found/` pins it. No emitted byte
+  changes and the core contract stays version 3: this documents a shipped
+  shape, it does not introduce one. The adapter surfaces still require id-only
+  details, deliberately: the adapter's `inspect` request accepts no `number`
+  member and always invokes `--id`, so it can never see the number variant.
+
 ## 0.1.0-alpha.5 - 2026-08-16
 
+### Breaking
+
+- **`number` is no longer caller-settable on schema version 2 ledgers.**
+  `create` refuses a request supplying `item.number` and assigns the next
+  number itself (`max + 1` under the number-index lock); `patch` refuses
+  `set.number` because the number is the immutable item identity. A consumer
+  mirroring a legacy backlog cannot carry its legacy numbers into wowbagger
+  handles — keep legacy identifiers in a permitted extension member or in the
+  item body instead. (Shipped as part of the number-as-identity work; this
+  notice was added after the 0.1.0-alpha.5 tarball was cut, so the packaged
+  changelog carries it only inside the contract version 3 delta note.)
+
 ### Added
 
 - **The report draws the whole ledger as a 3D dependency graph.** It sits below