wowbagger 0.1.0-alpha.13 → 0.1.0-alpha.14

package/skills/wowbagger/SKILL.md

@@ -14,7 +14,7 @@ publish something.
 Install the core separately before using this skill:
 
 ```sh
-npm install -g wowbagger@0.1.0-alpha.13
+npm install -g wowbagger@0.1.0-alpha.14
 ```
 
 The core requires Node.js 20 or later. This plugin ships only agent
@@ -34,9 +34,9 @@ wowbagger capabilities --json
 
 Read the plain distribution version from the first command and the top-level
 `contract_version` from the second. **This skill requires distribution version
-`0.1.0-alpha.13` and core `contract_version: 5`.**
+`0.1.0-alpha.14` and core `contract_version: 5`.**
 
-The distribution pin names the published `0.1.0-alpha.13` release; the cut that
+The distribution pin names the published `0.1.0-alpha.14` release; the cut that
 publishes core `contract_version: 5` moves it. Earlier cores report
 `contract_version: 3` or lower and lack behavior this skill requires, including
 the bounded item source, so the version check refuses them. Do not soften
@@ -184,6 +184,32 @@ work read as ready.
   redaction and no access control. Say that plainly if a user asks for a report
   that hides work from a reader.
 
+## Every writer must be on the same core before the first create
+
+On a provisioned ledger, `create` now records its allocation in the shared
+claim journal before it publishes anything. That grammar is new, so the upgrade
+is a hard cutover with no automatic migration and no mixed-version grace
+period: **upgrade every writer in one Git coordination domain to the current
+core before the first alpha.14 create.** A worktree left on the old core does
+not write a duplicate — it stops making claim-protected mutations, which is the
+safe outcome, not a usable one.
+
+An old core cannot read the new create entry and says so badly. It answers
+exit 6, `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. Read that
+exact combination as **this repository was written by a newer Wowbagger;
+upgrade this worktree to continue**, and say so to the user: the old binary is
+immutable and can never print better guidance. (Item #185 is open for general
+version-drift detection.)
+
+Say what the fix does and does not cover. It 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. 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`.
+
 ## Writing
 
 Every write is an explicit, reviewable Git change. Show the user the command
@@ -434,6 +460,11 @@ authorized predecessor/successor window produces no finding, so another
 mutation can run before the first is committed. Do not mistake acceptance for
 durability. Commit each mutation anyway, then run `claim-verify`.
 
+`create` never gets that window. A new item has no earlier authorized revision,
+so Git `HEAD` is the only place its authorized bytes can live, and an
+uncommitted create blocks every later mutation — including the next create —
+with `git-finalization-required`.
+
 **`claim-verify` is the reconciliation procedure for that refusal.** Do not go
 looking for another verb; there is none. Read `details.findings`, do exactly
 what each finding's `remediation` string says (it names the path), run
@@ -491,7 +522,10 @@ commit. With `--auto-commit`, `changed_paths` matches `commit_paths`, and
 `git_commit` proves the commit.
 
 Batch work is where this bites: filing ten items means ten commits, not one
-commit at the end. Tell the user that before starting a batch.
+commit at the end. Tell the user that before starting a batch. There is no
+batch mutation to reach for — the create-then-commit loop is the supported bulk
+pattern, and item #186 is open to design a safe batch create. `--auto-commit`
+on each `create` is the shortest form of that loop.
 
 ### Or use --auto-commit and let one invocation do it
 
@@ -508,9 +542,11 @@ One flagged invocation refuses if anything is staged anywhere or any foreign
 path under the ledger is dirty, reconciles, runs the mutation unchanged,
 commits exactly the changed item plus at most one
 `.wowbagger/reconcile-<namespace>.md` with a fixed subject, verifies that commit,
-and runs `claim-verify` before it answers. A command that owns the claim journal
-may rebuild only its derived reconciliation log during preflight. `create`
-remains strict, and every other dirty ledger path still refuses.
+and runs `claim-verify` before it answers. A successful `create --auto-commit`
+commits exactly two paths: the created item and that reconciliation log. Every
+command rebuilds its own derived reconciliation log during preflight, but
+`create` refuses a log that was already dirty when you invoked it, and every
+other dirty ledger path still refuses.
 
 Preflight and post-commit reconciliation block findings for the requested item.
 An unrelated `worktree-synchronization-required` finding remains visible to
@@ -610,29 +646,85 @@ envelope's `limits.cross_worktree_coordination: false` as permission to write
 with hostile or noncooperating tools — it only says the core never synchronizes
 checkouts.
 
-A recorded `transition`, `patch`, or claimed publication blocks mutations
-targeting that same item with exit 6 `claim-store-unavailable`, reason
-`publication-reconciliation-required`. An unrelated item mutation may proceed
-when the only finding is `worktree-synchronization-required`. `create` records
-nothing, so it never creates a publication block.
+A recorded `create`, `transition`, `patch`, or claimed publication blocks
+mutations targeting that same item with exit 6 `claim-store-unavailable`,
+reason `publication-reconciliation-required`. An unrelated item mutation may
+proceed when the only finding is `worktree-synchronization-required`.
+
+`create` is the one exception to that scoping, because it allocates the next
+number from the items this checkout can see. It also refuses when the journal
+records a committed item this worktree does not hold at all: that item carries
+a number nobody here can read, so the next number allocated here might already
+be taken. A stale revision of an item this worktree does hold is not a blocker
+for `create` — a number is immutable, so the local maximum is still right. The
+refusal is the same exit 6 `claim-store-unavailable` with reason
+`publication-reconciliation-required`, state `unchanged`, and no item file
+written; integrate the missing item, run `claim-verify` until it exits 0, and
+resend the same request, which then takes the next number.
+
+That fence stops new collisions; it does not repair old ones. A ledger that
+already carries duplicate numbers is item #182's recovery work: it fails
+`validate` and refuses every mutation until #182 ships. Never hand-edit a
+`number` to clear it — the edit skips the collision and reference checks every
+mutation runs and can leave dangling `depends_on`, `related`, and parent
+references that nothing reports.
 
 Read `error.details.findings[0].reason` and act on the named item:
 
 - `git-finalization-required` — you wrote the item here and have not committed.
   Commit, then `claim-verify`.
-- `worktree-synchronization-required` — another worktree wrote the item. If the
+- `worktree-synchronization-required` — another worktree wrote the item.
+  `owner_ref` names an **active named worktree** and nothing else: it is always
+  the branch of a live worktree that carries the expected revision. If the
   finding names `owner_ref` and `owner_commit`, WAIT for that owner to publish,
-  then synchronize this checkout and run `claim-verify`. If it carries
-  `owner_unavailable: true`, follow its `remediation`: a revision that is not
-  yet reachable means WAIT for the owning worktree to commit, then synchronize;
-  only ownership that cannot be established from reachable refs calls for
-  inspecting reachable or dangling commits with explicit restore or
-  `claim-adopt`. Never merge unrelated live work.
+  then synchronize this checkout and run `claim-verify`. `owner_unavailable:
+  true` means no such worktree exists, and it covers three cases: the expected
+  revision is not reachable at all, a live sibling holds it on a detached
+  `HEAD`, or it is reachable only from a tag, a remote-tracking ref, or a
+  branch no worktree has checked out. Reachability is not ownership; a ref you
+  can see is not a worktree that can publish. Follow the `remediation`, which
+  separates those cases. A revision that is **not yet reachable** means WAIT for
+  the owning worktree to commit, then synchronize. A revision that is
+  **reachable in Git while no active named worktree owner is established** —
+  a tag, a remote-tracking ref, an unchecked-out branch, or a detached sibling
+  carries it — is not a wait at all: inspect that reachable history, then
+  restore the authorized bytes or use explicit `claim-adopt` after review.
+  Ownership that **cannot be established from reachable refs** — the item has
+  never existed in this checkout — calls for inspecting reachable or dangling
+  commits with the same explicit restore or `claim-adopt`. Never merge unrelated
+  live work.
 - `unauthorized-revision` — the item changed outside the protocol. Two remedies
   are explicit: **restore** the authorized revision and run `claim-verify` to
   discard the edit, or **adopt** the committed revision and run `claim-verify`
   to keep it. Ask before discarding reviewed work.
 
+Two live worktrees answering to one identity, or a worktree roster the
+coordinator could not finish reading, refuse before anything is classified.
+You get exit 6 `claim-store-unavailable`, reason `claim-store-unreadable`, with
+`error.details.identity_diagnostic`: `duplicate-worktree-identity` naming the
+`worktree_id` and `live_worktree_count`, or `worktree-enumeration-failed` with
+no further member. Auto-commit reports the same diagnostic inside
+`auto-commit-preflight-failed` with `retryable: false`. Neither is retryable
+and neither is yours to repair by editing files. Report the diagnostic verbatim,
+including the `worktree_id` and `live_worktree_count`: a duplicate means two
+live worktrees hold the same identity file, usually because a private Git
+directory was copied, and which worktree keeps the UUID is a person's decision.
+An enumeration failure means a registered worktree path could not be read. The
+identity itself is an opaque UUID a worktree writes once into its private Git
+directory. Never create, copy, or edit it.
+
+**`claim-verify` is repository-wide, and a clean mutation does not make it
+exit 0.** It names no target, so any blocking finding anywhere in the
+repository keeps it at exit 6 — including a finding on an item belonging to
+work you have nothing to do with. On a repository with live sibling worktrees
+you may commit every one of your own mutations and still never see
+`claim-verify` exit 0. That is current behavior; item #184 is open in triage to
+decide the supported verification surface. When the remaining findings all name
+items you are not working on, say so and stop; do not hand-edit an item, and do
+not run `claim-adopt` on a sibling's item to force exit 0. Adoption moves the
+coordinator's authorized revision and is not a way to silence someone else's
+finding.
+
 Adoption is per item and per revision explicit. Name the item and both
 revisions, take them from the finding, and commit the edited bytes first:
 
@@ -692,7 +784,9 @@ Use the claimed write path as one complete loop:
 9. Run `claim-verify` after the commit or merge. It finalizes the Git outcome,
    repairs response-loss cases, and reports later revision drift. Require exit
    0 before the next mutating command; exit 6 means findings remain, so act on
-   each `remediation` string and run it again.
+   each `remediation` string and run it again. If every remaining finding names
+   an item you are not working on, that is the repository-wide scope described
+   above, not a failure of your work: report it instead of forcing exit 0.
 10. Release the claim with its current observed state.
 11. Run `validate` and show the resulting diff.
 
@@ -717,7 +811,8 @@ response envelopes, refusal precedence, and recovery rules.
    `git add <dir> && git commit`.
 8. On a provisioned ledger, run `claim-verify --ledger <dir> --json` and
    require exit 0 before the next `create`, `transition`, `parent-migrate`,
-   `snooze`, `patch`, or `publish-claimed`.
+   `snooze`, `patch`, or `publish-claimed`. Findings that name only unrelated
+   items are repository-wide scope; report them rather than forcing exit 0.
 
 Write, commit, `claim-verify`, next write. The unclaimed loop obeys the same
 rule as the claimed one, because both run through the same coordinator. Steps 7

package/src/claim-coordinator.js

@@ -37,6 +37,12 @@ export async function withLegacyMutationFence(
   const capability = resolveWorkClaimCapability({ gitCommonDir, namespace });
   if (!capability.claim_protected_publication) return write();
 
+  // A create is the one mutation that reads an identity it was not given: it
+  // allocates the ledger's next number from the items this checkout holds. Its
+  // reconciliation therefore stays target-scoped like every other mutation, and
+  // gains one extra barrier below, for the coordinated items this working
+  // ledger cannot see at all.
+  const create = command === 'create-v1';
   const storePath = claimStorePath(gitCommonDir, namespace);
   const journalPath = claimJournalPath(gitCommonDir, namespace);
   let intent = null;
@@ -61,9 +67,15 @@ export async function withLegacyMutationFence(
         physicalNow: new Date().toISOString(),
         targetItemId: itemId,
         writeLogOnUnsafe: false,
-        writeLogWhenEmpty: command !== 'create-v1',
+        writeLogWhenEmpty: !create,
       });
-      if (reconciled.unsafe) {
+      // The extra create barrier promised above rides on the same refusal: a
+      // coordinated item this checkout does not hold carries a number nobody
+      // here can read, so the next number this create would allocate may be one
+      // a sibling worktree already published. A stale revision of an item that
+      // is present hides no number: an item's number is immutable, so target
+      // scoping above still lets that create through.
+      if (reconciled.unsafe || (create && reconciled.missingCoordinatedItems.length > 0)) {
         return claimStoreUnavailable(responseCommand, 'publication-reconciliation-required', {
           findings: reconciled.findings,
         });
@@ -75,7 +87,7 @@ export async function withLegacyMutationFence(
       const projected = [...reconciled.entries];
       const record = reconciled.state.claims.find((entry) => entry.item_id === itemId)
         ?? { item_id: itemId, last_epoch: '0', active: null };
-      const mustRefuse = command === 'create-v1'
+      const mustRefuse = create
         ? record.last_epoch !== '0'
         : record.active !== null && observedAt < record.active.expires_at;
       if (mustRefuse) return legacyRefusal(responseCommand, namespace, itemId, observedAt, record);
@@ -110,6 +122,7 @@ export async function withLegacyMutationFence(
           attempt_id: attemptId,
           ledger_namespace: namespace,
           item_id: itemId,
+          ...(create ? { command } : {}),
           observed_revision: expectedRevision,
           observed_at: observedAt,
         };
@@ -180,6 +193,7 @@ export async function withLegacyMutationFence(
             attempt_id: intent.attempt_id,
             ledger_namespace: namespace,
             item_id: itemId,
+            ...(create ? { command } : {}),
             observed_revision: intent.expected_revision,
             observed_at: observedAt,
           }));

package/src/claim-journal.js

@@ -20,6 +20,8 @@ const JOURNAL_ENTRY_TYPES = new Set([
   'publish-intent',
   'revision-adoption',
 ]);
+// Every command the legacy mutation fence journals.
+const LEGACY_MUTATION_COMMANDS = new Set(['patch-v1', 'transition-v1', 'create-v1']);
 // The reconciliation log is a tracked derived artifact. Entry types that every
 // invocation appends, including refusals and read-only verification, stay out
 // of it so a mutation that changes nothing leaves the working tree unchanged.
@@ -177,6 +179,7 @@ async function readJournalEntries(journalPath, namespace = null) {
   const lines = source.split('\n').filter(Boolean);
   if (lines.length > MAX_JOURNAL_ENTRIES) throw journalCapacityExceeded();
   const entries = lines.map((line) => JSON.parse(line));
+  const createAttempts = new Map();
   for (let index = 0; index < entries.length; index += 1) {
     if (!Number.isSafeInteger(entries[index]?.seq) || entries[index].seq !== index + 1) {
       throw journalInvalid('non-contiguous-sequence');
@@ -187,6 +190,9 @@ async function readJournalEntries(journalPath, namespace = null) {
     if (!validJournalEntry(entries[index], namespace)) {
       throw journalInvalid('invalid-entry');
     }
+    if (!validCreateResolution(entries[index], createAttempts)) {
+      throw journalInvalid('invalid-entry');
+    }
   }
   return entries;
 }
@@ -282,8 +288,10 @@ function validJournalEntry(entry, namespace) {
       && typeof entry.ledger_namespace === 'string'
       && (namespace === null || entry.ledger_namespace === namespace)
       && typeof entry.item_id === 'string'
-      && ['patch-v1', 'transition-v1'].includes(entry.command)
-      && typeof entry.expected_revision === 'string'
+      && LEGACY_MUTATION_COMMANDS.has(entry.command)
+      && (entry.command === 'create-v1'
+        ? entry.expected_revision === null
+        : typeof entry.expected_revision === 'string')
       && typeof entry.candidate_revision === 'string'
       && (!Object.hasOwn(entry, 'item_path') || typeof entry.item_path === 'string')
       && (!Object.hasOwn(entry, 'writer_worktree_id')
@@ -295,7 +303,7 @@ function validJournalEntry(entry, namespace) {
       && typeof entry.ledger_namespace === 'string'
       && (namespace === null || entry.ledger_namespace === namespace)
       && typeof entry.item_id === 'string'
-      && ['patch-v1', 'transition-v1'].includes(entry.command)
+      && LEGACY_MUTATION_COMMANDS.has(entry.command)
       && typeof entry.committed_revision === 'string'
       && (!Object.hasOwn(entry, 'item_path') || typeof entry.item_path === 'string')
       && (!Object.hasOwn(entry, 'writer_worktree_id')
@@ -303,11 +311,19 @@ function validJournalEntry(entry, namespace) {
       && typeof entry.observed_at === 'string';
   }
   if (entry.type === 'legacy-mutation-abort') {
+    // A create abort names no predecessor revision, so the absence of one is
+    // its evidence. Patch and transition aborts keep their exact legacy shape
+    // and never carry a command.
+    const validAbortRevision = (
+      !Object.hasOwn(entry, 'command') && typeof entry.observed_revision === 'string'
+    ) || (
+      entry.command === 'create-v1' && entry.observed_revision === null
+    );
     return typeof entry.attempt_id === 'string'
       && typeof entry.ledger_namespace === 'string'
       && (namespace === null || entry.ledger_namespace === namespace)
       && typeof entry.item_id === 'string'
-      && typeof entry.observed_revision === 'string'
+      && validAbortRevision
       && typeof entry.observed_at === 'string';
   }
   if (entry.type === 'revision-adoption') {
@@ -351,6 +367,30 @@ function validJournalEntry(entry, namespace) {
     && typeof entry.git_commit === 'string';
 }
 
+// A journal-fenced create is only meaningful as a pair: the terminal that ends
+// an attempt must name the intent that opened it, so a standalone create
+// terminal names no authorized attempt and fails closed. Patch and transition
+// entries remain valid standing alone, so only create-v1 attempts are tracked.
+function validCreateResolution(entry, attempts) {
+  if (entry.command !== 'create-v1') return true;
+  if (entry.type === 'legacy-mutation-intent') {
+    attempts.set(entry.attempt_id, entry);
+    return true;
+  }
+  if (entry.type !== 'legacy-mutation' && entry.type !== 'legacy-mutation-abort') return true;
+  const intent = attempts.get(entry.attempt_id);
+  if (intent === undefined || intent.item_id !== entry.item_id) return false;
+  // A committed create publishes exactly the revision its intent proposed; an
+  // aborted one publishes none.
+  if (entry.type === 'legacy-mutation' && intent.candidate_revision !== entry.committed_revision) {
+    return false;
+  }
+  // One attempt resolves once, so the intent is consumed here and a repeated
+  // resolution finds no open attempt to end.
+  attempts.delete(entry.attempt_id);
+  return true;
+}
+
 function isRecord(value) {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 }