create-religion 1.3.0 → 1.5.0

package/template/.agents/skills/complete/reference/land-on-top.md

@@ -0,0 +1,174 @@
+# Landing on top of what already landed
+
+Used before an item's branch is squash-merged or pushed, when the branch it lands in has moved
+since the item began: another item, built in its own worktree, landed first. Both items wrote
+the same state files, and a text merge of those conflicts every time, because each holds
+bookkeeping derived from its own branch. So the landed copy of each is taken, and this item's
+share of it is done again on top.
+
+The **target** is the branch the item lands in: the default branch, or an automated run's
+integration branch. Under `pull-request`, fetch it first, which is a network read and asks
+outside an automated run, and use the remote-tracking name, such as `origin/main`.
+
+The merge this makes is a commit on the item's own branch, like the work commit, and is covered
+by the same yes; it never writes the target.
+
+Run each block as **one** command, from the item's checkout, after the work commit. Each runs in
+a subshell and sets what it needs. A block that stops ends the landing: report what it printed
+and stop. A stop after block 1 leaves the merge open: either put right what the block named and
+run it again, or abandon the merge with the block in "Abandoning the merge" below.
+
+## 1. Bring in what landed
+
+    (
+      root=$(git rev-parse --show-toplevel) || exit 1
+      target='<the target>'
+      [ -z "$(git -C "$root" status --porcelain -- . ':!religion/context/handoff.md')" ] ||
+        { echo "uncommitted changes; make the work commit first"; exit 1; }
+      git -C "$root" checkout -q -- religion/context/handoff.md 2>/dev/null
+      git -C "$root" rev-parse -q --verify "$target^{commit}" >/dev/null || { echo "no such target: $target"; exit 1; }
+      if git -C "$root" merge-base --is-ancestor "$target" HEAD; then echo "nothing landed since"; exit 0; fi
+      git -C "$root" merge --no-commit --no-ff "$target"
+      git -C "$root" rev-parse -q --verify MERGE_HEAD >/dev/null || { echo "the merge did not start"; exit 1; }
+      base=$(git -C "$root" merge-base HEAD MERGE_HEAD)
+      for f in build-plan.md context/findings.md learning/journal.md context/project-overview.md context/handoff.md; do
+        p="religion/$f"
+        git -C "$root" diff --quiet "$base" MERGE_HEAD -- "$p" && continue
+        if git -C "$root" cat-file -e "MERGE_HEAD:$p" 2>/dev/null; then
+          git -C "$root" checkout MERGE_HEAD -- "$p" || exit 1
+          echo "taken as landed: $p"
+        else
+          git -C "$root" rm -q -f --ignore-unmatch -- "$p" || exit 1
+          echo "no longer tracked by the target: $p"
+        fi
+      done
+      left=$(git -C "$root" diff --name-only --diff-filter=U)
+      if [ -n "$left" ]; then
+        echo "conflicts outside the shared state files:"; echo "$left"
+        git -C "$root" merge --abort; exit 1
+      fi
+      echo "merged; redo this item's share of each file taken as landed"
+    )
+
+`nothing landed since` means the target is already part of the branch: skip the rest. Only a
+shared file the target changed since the item began is taken from it; one it left alone merges
+as usual, carrying this item's changes with nothing to redo. A shared file the target stopped
+tracking is removed, as the target has it; this item's copy is still in `HEAD`. The handoff is generated and rewritten at the end of every turn, so discarding it loses nothing.
+
+Taking the target's copy of a shared file resolves that file, conflicted or not. A conflict in
+any other file, product code included, is not this routine's to settle: the merge is abandoned,
+the branch is exactly as it was, and the paths are reported for review. Never resolve them by
+taking either side.
+
+While the merge is open, `HEAD` is this item's own work and `MERGE_HEAD` is what landed.
+
+## 2. Redo this item's share
+
+For each file block 1 took as landed, edit it as it now stands, taking this item's part from
+`HEAD`'s copy, as `git show HEAD:religion/<file>` prints it:
+
+| File | This item's share |
+| --- | --- |
+| `build-plan.md` | a feature ticks its line, and its parent once every sub-item is ticked; a rollback unticks its target and adds its note; a fix or refactor campaign has none |
+| `context/findings.md` | append each entry `HEAD`'s copy holds that the merge base's did not, still `open`, `fixed` or `unverified`, unchanged; one whose identifier the landed copy already holds, two fixes' bare `F-1` say, takes its permanent prefixed form, the archive's name before it as completion would archive it, and the rename is reported; when the landed copy is the stub, replace its placeholder line |
+| `learning/journal.md` | append its entry, the one whose `**Archive:**` line names this item's archive |
+| `context/project-overview.md` | none: left as landed, and stale until $overview runs, as after any completion |
+| `context/handoff.md` | none |
+
+Then compare `HEAD`'s ledger with the merge base's,
+`git diff $(git merge-base HEAD MERGE_HEAD) HEAD -- religion/context/findings.md`. A change this
+item made to an entry it did not add is not carried, since the landed copy is the one kept; name
+each such entry in the report so it can be made again by hand.
+
+Everything else, this item's archive included, merged as git merges it.
+
+## 3. Check, then commit the merge
+
+Stage the redone files for the merge commit, then check them:
+
+    (
+      root=$(git rev-parse --show-toplevel) || exit 1
+      for f in build-plan.md context/findings.md learning/journal.md context/project-overview.md context/handoff.md; do
+        [ -e "$root/religion/$f" ] && git -C "$root" ls-files --error-unmatch -- "religion/$f" >/dev/null 2>&1 &&
+          { git -C "$root" add -- "religion/$f" || exit 1; }
+      done
+      for f in build-plan.md context/findings.md learning/journal.md; do
+        ! grep -n -e '^<<<<<<< ' -e '^>>>>>>> ' -- "$root/religion/$f" 2>/dev/null || { echo "conflict markers in religion/$f"; exit 1; }
+      done
+      [ -z "$(git -C "$root" diff --name-only --diff-filter=U)" ] || { echo "unresolved paths remain"; exit 1; }
+      echo "ready for Verify"
+    )
+
+Only the files edited by hand are searched: git leaves no markers in a file it merged cleanly,
+and a document elsewhere may show one on purpose.
+
+Run the project's full `Verify` on the result: it is new code, made of both items, and neither
+was checked against the other. A turn that ends before the merge is committed has its handoff
+rewritten by the hook; run block 3 again before committing, which stages it only while the index
+still tracks it.
+
+When `Verify` passes, commit the merge with a message that says what was brought in, such as
+`merge: bring in what landed on main`.
+
+When it fails, abandon the merge with the block below, which returns the branch to its work
+commit, and stop with the failure. The item is complete on its branch but cannot land as it
+stands: the way forward is $fix here, describing the failure, built on this branch.
+Completing that fix lands both through this routine: block 2 then redoes the share of both, the
+item's and the fix's, every row, each taken from `HEAD`, and the `## Landed` record goes into
+both archives with the one range they share, each saying it is shared.
+
+## Abandoning the merge
+
+    (
+      set -o pipefail
+      root=$(git rev-parse --show-toplevel) || exit 1
+      git -C "$root" rev-parse -q --verify MERGE_HEAD >/dev/null || { echo "no merge open"; exit 0; }
+      g="$(git -C "$root" rev-parse --absolute-git-dir)/abandon"
+      list() { git -C "$root" -c core.quotePath=false "$@"; }
+      list ls-files -o | LC_ALL=C sort >| "$g.before" || exit 1
+      { list diff --name-only --no-renames HEAD && list diff --cached --name-only --no-renames HEAD; } >| "$g.tracked" || exit 1
+      git -C "$root" reset -q --hard HEAD; rc=$?
+      list ls-files -o | LC_ALL=C sort >| "$g.after" || exit 1
+      { cat "$g.tracked"; LC_ALL=C comm -23 "$g.before" "$g.after"; } | LC_ALL=C sort -u | sed 's/^/discarded: /'
+      rm -f "$g.before" "$g.after" "$g.tracked"
+      [ "$rc" -eq 0 ] || { echo "the reset failed: the merge is still open, and a path named above may not be set back"; exit 1; }
+      list ls-files -o --exclude-standard --directory | sed 's/^/left untracked: /'
+      echo "back at the work commit"
+    )
+
+Block 1 started from a clean tree, so the work commit is the whole of this item's work, and
+resetting to it ends the merge and returns the branch exactly as it was, whatever the merge left:
+redone shares, a handoff the hook rewrote, output `Verify` regenerated, paths still in conflict.
+Each path the reset set back or removed is named once: every tracked path whose working or staged copy
+differed from the work commit, an edit made by hand while the merge was open among them, and every untracked or
+ignored file in the way of a path the work commit has, such as one inside a directory the target
+put where a file was, found by listing them with git before the reset and after it. Other
+untracked files are left where they are and named, a whole directory as one line. Names are
+printed as git prints them, quoted where they hold unusual characters. So nothing is lost without
+a word. A reset that fails, such as on a directory it cannot write, still names what it removed,
+then says the merge is still open: put right what git named and run the block again. Never
+abandon with `git merge --abort` alone, which refuses while a file the merge touched has unstaged
+changes. With no merge open, the block does nothing.
+
+## 4. Record what landed
+
+When a merge was made, the item's `## Landed` record names the last such merge's second parent,
+the target it brought in, as **Base**, and that merge commit and anything after it as **Commits**:
+`git diff` from that base to the last commit is then this item's work alone, which is what a
+rollback reverses. Without a merge, the record is as `$complete` describes. Commit the
+record: in a worktree, an uncommitted file goes when the worktree is removed.
+
+## When the state directory is ignored
+
+Then none of these files are in git, and the merge carries none of them: this item's archive,
+plan tick, journal entry and ledger exist only in its worktree's copy of `religion/`. Before
+the worktree can be removed, redo this item's share, as the table in block 2 lists it, in the
+main checkout's own `religion/` files, and copy this item's archive there. When this landing
+follows a failed `Verify`, that is the share and the archive of both, the item's and the fix's. With no `HEAD` copy
+or merge base in git, the worktree's own files are this item's part, and the ledger saved when
+the worktree was made, `religion/.state/findings-at-start.md` in it, is the base: an entry the
+worktree's ledger holds that the saved one did not is this item's. Comparing the two also shows
+each entry this item changed or removed, a repair it closed and pruned among them: make the
+same change in the main checkout's ledger, or name the entry in the report, so a finding this
+item closed does not stay open there. Removing the worktree deletes ignored files with it, so
+until then they are the only record.

package/template/.agents/skills/distill/SKILL.md

@@ -56,7 +56,8 @@ finding, already repaired, is an incident.
 
 For each group that earns it, propose the coding-standard rule that would have prevented every
 finding in it, in the standards' own voice, as an instruction for work not yet started, with the
-findings cited by identifier. A rule that only restates one finding is not a standard. Skip a
+findings cited by their archived identifier, prefix included, such as `39a/F-2` or `27/F-161`.
+A rule that only restates one finding is not a standard. Skip a
 group already recorded in `religion/learning/journal-archive.md` unless it has grown since.
 
 ## Step 3 - route by kind

package/template/.agents/skills/feature/SKILL.md

@@ -65,7 +65,10 @@ plan top to bottom and take the first unchecked leaf that waits on nothing: an i
 those is unticked, or says `spike first` and no archive under `religion/history/spikes/` records
 `**For:** item N` with `**Settled:** yes`. Wording inside a code span does not count.
 Name each item passed over and what it waits on, and point a spike-first one at
-$spike. State which item you are spec'ing before going further.
+$spike. An item another worktree is already building is passed over too: one that
+`religion status --json` lists under `inFlight` with `here` false, or, without the `religion`
+command, one the handoff lists as in flight in another worktree. Name it with its branch.
+State which item you are spec'ing before going further.
 
 Asked by number for an item that waits, say what it waits on and stop: speccing it now
 builds on an answer nobody has yet. A reference to an item the plan does not have, or items

package/template/.agents/skills/fix/SKILL.md

@@ -14,8 +14,9 @@ numbered, it ticks nothing, and it archives on its own.
 - **A description** - `$fix "password reset email never sends"`. A problem stated in the
   conversation already counts; this skill does not scan the project hoping to find
   something wrong.
-- **Finding identifiers** - `$fix F-03` specs the repair of that ledger entry, and
-  `$fix F-03 F-07` repairs several together. Group findings only when they share a file
+- **Finding identifiers** - `$fix 39a/F-2` specs the repair of that ledger entry, and
+  `$fix 39a/F-2 F-07` repairs several together. An identifier is used exactly as the
+  ledger heads it, with an item prefix when it has one, bare when it does not. Group findings only when they share a file
   and a severity, as $auto's fix mode does: one fix then stays one reviewable diff.
 
 - **An issue** - `$fix #42` or its link. Read it through the host's own command-line tool, for example `gh issue view 42 --json title,body,url` on

package/template/.agents/skills/implement/SKILL.md

@@ -24,6 +24,10 @@ guess past broken configuration.
 **Read the spec.** If `religion/context/current-work.md` is still the stub, or its status
 is already complete, stop and say to run $feature, $fix, or
 $rollback first.
+When it is the stub and `religion status --json` lists items under `inFlight` with `here`
+false, or the handoff lists items in flight in other worktrees, name each with its worktree
+and branch, and say that resuming one means working from that worktree. Never start one of
+them again here.
 
 **Take the context.** Conventions from `religion/context/coding-standards.md`, the data
 model from the project overview. Code that ignores them is rework, not progress.
@@ -56,6 +60,17 @@ They differ only in how the work leaves the branch at completion, which is not t
 concern. On a resume the branch exists already, so check it out rather than creating a
 second one.
 
+**With `workflow.parallelItems` on**, under either of those modes, a feature from the build
+plan starts in its own worktree instead: follow `reference/item-worktree.md`, which creates
+it on that branch beside the project and moves the spec there. Creating it is part of
+positioning the work, as creating the branch is; removing it is deleting files, and asks.
+An automated run keeps the plain branch, since it removes each item's branch once it lands,
+and a worktree holding the branch would stop that. From then on the item is the worktree's.
+Move the session into it where the tool can; otherwise address every file and
+command to the worktree's path, and tell the user to open later sessions there, since hooks
+keep running where a session started. A resume inside the worktree is the ordinary resume
+below. Fixes, rollbacks and refactor campaigns keep the branch above.
+
 Either way, if the project is not a git repository, say so and ask the user to initialize
 one. The loop needs history to be reviewable.
 
@@ -154,16 +169,30 @@ Two waves of one, then a wave of two, then a wave of one.
 **Refuse a wave rather than guess at one.** Run the wave sequentially, and say why, when:
 
 - a marker names a later step, itself, or a step that does not exist
-- two steps in the wave would change the same file, which is a conflict the spec did not
-  intend and the author is better placed to resolve than a merge
+- two steps in the wave would change the same authored file, which is a conflict the spec
+  did not intend and the author is better placed to resolve than a merge. Output the
+  project's build generates from those files does not count; it is rendered once after
+  the join
 - the wave is larger than three steps, which usually means the spec is describing one step
   badly rather than three independent ones
 
-**Building a wave.** Each step runs in its own subagent with the step, the spec, the
-standards, and nothing else. They build and **return**; they do not tick, do not write the
-spec, and do not touch the ledger. The parent applies what comes back, runs the gate for each
-step, and performs every write. This is the same rule audit's lenses follow, for the same
-reason: concurrent writers to one file is the one thing waves must never introduce.
+**Building a wave.** Each step builds in its own detached git worktree outside the project,
+set up and torn down by `reference/worktrees.md`, so a step cannot see or change another
+step's files. Each runs in its own subagent with the step, the spec, the standards, the path
+of its worktree, and nothing else. They build there and **return** their evidence; they do
+not tick, do not write the spec, and do not touch the ledger. The parent extracts each
+step's patch and performs every write. This is the same rule audit's lenses follow, for the
+same reason: concurrent writers to one file is the one thing waves must never introduce.
+
+**Joining a wave.** The parent concatenates the patches in step order and applies them with
+one `git apply`, which lands all of them or none. Then it renders generated output once,
+when any was left out of the patches, and runs each step's gate on the joined tree. A step
+that fails its gate there leaves its patch applied for review, as a failed step always does.
+
+**A join that does not apply stops the wave** with the project exactly as it was. Report the
+paths `git apply` named and where each worktree is, keep the worktrees, tick nothing, and
+leave the conflict for review. Never retry with a three-way apply, merge, or edit to make it
+fit.
 
 **A failure stops the wave.** Report which steps passed and which did not, tick only what
 passed, and stop. Do not retry the wave; the next run resumes at the first unticked step,
@@ -180,7 +209,8 @@ block completion, so close the loop now rather than discovering it later.
 
 For each `open` P0 or P1:
 
-1. **Append it to the spec's build steps** first (`- [ ] Repair F-03 - <title>`), so the
+1. **Append it to the spec's build steps** first (`- [ ] Repair 39a/F-2 - <title>`, using
+   the identifier exactly as the ledger heads it), so the
    repair is on the record and survives a cleared context. That changes what the spec asks
    for, so record it as an amendment naming the finding, and renew the stamp.
 2. Build it through the same loop as Step 2: smallest change, diff, explanation, evidence.

package/template/.agents/skills/implement/reference/item-worktree.md

@@ -0,0 +1,116 @@
+# Starting an item in its own worktree
+
+Used when `workflow.parallelItems` is `true`, `git.mode` is `branch-per-item` or
+`pull-request`, the spec is a feature from the build plan, and no automated run is underway.
+The item gets its own git worktree beside the project, on the branch Step 1 would otherwise
+create, and its spec moves there. The main checkout is then idle, and `$feature` can spec
+the next item from it.
+
+Run each block as **one** command. Each runs in a subshell, so a stop ends that block and never
+the shell a tool keeps between commands, and nothing set in one block survives into the next:
+each sets what it needs. A block that stops ends the start: report what it printed and stop.
+
+A branch whose name holds a `'` is refused before anything runs, since the blocks quote it.
+
+## 1. Check, then create
+
+    (
+      root=$(git rev-parse --show-toplevel) || exit 1
+      [ "$(git -C "$root" rev-parse --absolute-git-dir)" = "$(git -C "$root" rev-parse --path-format=absolute --git-common-dir)" ] ||
+        { echo "not the main checkout: $root"; exit 1; }
+      [ -z "$(git -C "$root" status --porcelain -- . ':!religion/context/current-work.md' ':!religion/context/handoff.md')" ] ||
+        { echo "uncommitted changes beyond the spec"; exit 1; }
+      branch='<the branch Step 1 names>'
+      tree="${root%/*}/${root##*/}.$(printf '%s' "$branch" | tr / -)"
+      [ ! -e "$tree" ] && [ ! -L "$tree" ] || { echo "already exists: $tree"; exit 1; }
+      ! git -C "$root" show-ref --verify --quiet "refs/heads/$branch" || { echo "branch exists: $branch"; exit 1; }
+      git -C "$root" worktree add -q -b "$branch" "$tree" HEAD || exit 1
+      echo "$tree"
+    )
+
+Started from inside a linked worktree, the first check stops: that worktree is an item already,
+and a second one made from it would land on top of it. Anything uncommitted but the spec and
+the generated handoff stops it too, settings and plan edits included, since the worktree is
+made from `HEAD` and would run without them. Commit them first.
+
+The path is the project's directory name, a dot, and the branch with each `/` as `-`, in the
+project's parent directory: `religion` building `feature/export-reports` gets
+`religion.feature-export-reports`. Landing the item later looks for it there, so never choose
+another. A path or branch that already exists is another item's, or a start that stopped after
+this block: when the path is a worktree on this item's branch and the main checkout still holds
+the spec, go on to block 2; otherwise stop and say which, never reusing or replacing it.
+
+## 2. Copy what git does not carry, then move the spec
+
+Safe to run again until block 3 has run, and it refuses after that. Use the same branch as
+block 1:
+
+    (
+      root=$(git rev-parse --show-toplevel) || exit 1
+      branch='<the branch Step 1 names>'
+      tree="${root%/*}/${root##*/}.$(printf '%s' "$branch" | tr / -)"
+      [ "$(git -C "$tree" branch --show-current 2>/dev/null)" = "$branch" ] || { echo "not this item's worktree: $tree"; exit 1; }
+      spec="religion/context/current-work.md"
+      ! grep -q '_Nothing in progress' "$root/$spec" || { echo "the main checkout holds no spec to move"; exit 1; }
+      if [ -f "$tree/$spec" ] && ! grep -q '_Nothing in progress' "$tree/$spec" && ! cmp -s "$root/$spec" "$tree/$spec"; then
+        echo "the worktree already holds another spec"; exit 1
+      fi
+      for f in .claude/settings.json .claude/settings.local.json .claude/hooks; do
+        if [ -e "$root/$f" ] && git -C "$root" check-ignore -q "$f"; then
+          mkdir -p "$tree/$(dirname "$f")" && cp -RPp "$root/$f" "$tree/$(dirname "$f")/" || exit 1
+        fi
+      done
+      if git -C "$root" check-ignore -q religion; then
+        (cd "$root/religion" && find . -path ./.state -prune -o -type f -print) > "$tree.files" || exit 1
+        while IFS= read -r f; do
+          mkdir -p "$tree/religion/$(dirname "$f")" && cp -Pp "$root/religion/$f" "$tree/religion/$f" || exit 1
+        done < "$tree.files"
+        rm -f "$tree.files"
+      fi
+      for d in node_modules; do
+        [ -d "$root/$d" ] || continue
+        [ -e "$tree/$d" ] || [ -L "$tree/$d" ] || ln -s "$root/$d" "$tree/$d" || exit 1
+        git -C "$tree" check-ignore -q "$d" || printf '/%s\n' "$d" >> "$(git -C "$root" rev-parse --path-format=absolute --git-path info/exclude)" || exit 1
+      done
+      if git -C "$root" check-ignore -q religion && [ -f "$root/religion/context/findings.md" ]; then
+        mkdir -p "$tree/religion/.state" && cp -p "$root/religion/context/findings.md" "$tree/religion/.state/findings-at-start.md" || exit 1
+      fi
+      mkdir -p "$tree/religion/context" && cp -p "$root/$spec" "$tree/$spec" && cmp -s "$root/$spec" "$tree/$spec" || exit 1
+      echo "copied"
+    )
+
+The installer's output that git ignores is copied only where git ignores it; a tracked copy is
+already in the worktree. When `religion/` itself is ignored, which `doctor` reports as "state is
+local only", every state file but `religion/.state/` is copied, since each worktree keeps its own
+activity record; the ledger as it stood is saved in the worktree's `religion/.state/` as
+`findings-at-start.md`, the base landing later tells this item's findings apart by. The list of files is written beside the worktree, not piped, so a failed copy
+stops the block in every shell; a block that stopped there leaves that list, `<worktree>.files`,
+and the rerun removes it.
+
+The checks at the top are what make a rerun safe. Once block 3 has reset the main checkout's
+spec, there is nothing to move, and copying would put the stub over the only copy of the spec.
+A worktree that already holds a different spec belongs to work that has started, and copying the
+main checkout's over it would replace that work.
+
+Each installed dependency directory at the project root that the gate needs is linked, never
+installed: an install needs its own yes. Name each one in the `for d` list; `node_modules` is the
+usual one. A pattern such as `node_modules/` matches a directory but not a link to one, so a link
+git would not ignore is added to the repository's own exclude file, which is never committed;
+without that, the link would be committed with the item's work.
+
+## 3. Reset the main checkout's spec
+
+Only after block 2 printed `copied`: reset the main checkout's
+`religion/context/current-work.md` to its stub, exactly as shipped, as `$complete` does.
+The spec now lives only in the worktree. That is a move, not a deletion: if the copy did not
+match, nothing is reset, and the spec is still where it was.
+
+## 4. Confirm
+
+From the main checkout, `religion status` lists the item under `inFlight` with its branch and
+`here` false, and reports nothing active. From the worktree, it reports the item as active, and
+`religion doctor` there names the main checkout in its git check. Without the `religion`
+command, the handoff and the two specs say the same.
+
+From here on, every file and command of this item is the worktree's. Removing the worktree is
+deleting files, so it asks, every time.

package/template/.agents/skills/implement/reference/worktrees.md

@@ -0,0 +1,175 @@
+# Building a wave in worktrees
+
+One detached git worktree per wave step, outside the project, so a step can neither see nor
+change another step's files. The parent runs every command here; a step's subagent only
+works inside the worktree it is given.
+
+Run the phases in order. A command that fails stops the wave: report it and stop, as for any
+failed step.
+
+## 1. Base
+
+Once per wave, after every earlier step has landed, take the base, make the wave's directory,
+and save the values every later phase needs. Run these lines as **one** command: the save
+needs the values the first lines produce, and a fresh shell would have none of them.
+
+    (
+      root=$(git rev-parse --show-toplevel) || exit 1
+      case "$root" in */step-*) [ ! -f "${root%/*}/base" ] || exit 1;; esac
+      [ ! -e "$root/religion/.state/wave" ] || { cat "$root/religion/.state/wave"; exit 1; }
+      base=$(git -C "$root" stash create) || exit 1
+      [ -n "$base" ] || base=$(git -C "$root" rev-parse HEAD) || exit 1
+      wave=$(mktemp -d) && wave=$(cd -- "$wave" >/dev/null && pwd -P) || exit 1
+      printf '%s\n' "$base" > "$wave/base" || exit 1
+      mkdir -p "$root/religion/.state" && printf '%s\n' "$wave" > "$root/religion/.state/wave" || exit 1
+    )
+
+Each line that can fail stops the block, rather than `set -e`, which would stay on in a tool
+that keeps one shell between commands. The block runs in a subshell, so its exits end only
+the subshell and never that shell; it hands nothing back, since every later phase reads the
+saved values. The `cd` sends its output away so a shell hook that prints on a directory change
+cannot end up in the saved path. Without the stops, a failed `mktemp` leaves `wave`
+empty, `cd ""` stays in the project, and the block saves the project itself as the wave; a
+failed `git stash create` falls back to `HEAD` and drops uncommitted earlier steps.
+
+A saved wave that already exists means an earlier one was not torn down, which is what a
+failed join leaves. The block prints the directory it names and stops, so the record of where
+those worktrees are is never overwritten; deal with them first.
+
+Every command that touches the project runs against `$root`, never the current directory.
+From a subdirectory, `git apply` skips every path outside it and still exits 0, and
+`git ls-files` lists only what is below it, so a wave started there would join nothing and
+then tear down the work as if it had landed.
+
+`git stash create` makes a commit of the working tree without touching the stash list, any
+ref, or the working tree, so uncommitted earlier steps are part of the base. An empty result
+means the tree is clean, and `HEAD` is the base.
+
+Never `git stash push`, and never `git add -N` in the project: the user's index and stash
+are not the wave's to change.
+
+## 2. Create
+
+`pwd -P` saves the resolved path, the form `git rev-parse` reports, so the check below can
+compare the two. A shell that does not keep variables between commands starts each later
+phase by reading the values back, and stops if the current directory has drifted into one of
+the wave's own worktrees:
+
+    root=$(git rev-parse --show-toplevel)
+    case "$root" in */step-*) [ ! -f "${root%/*}/base" ] || exit 1;; esac
+    wave=$(cat "$root/religion/.state/wave")
+    base=$(cat "$wave/base")
+    case "$root/" in "$wave"/*) exit 1;; esac
+
+From inside a worktree, `root` would be that worktree, and the join would land there and
+report success while the project stayed unchanged. The first `case` stops in a step worktree
+of any wave, including one kept by an earlier failed join, recognised by the `base` file in
+the wave directory beside it; the second stops in one of this wave's own. A linked worktree
+the user works from is neither, so it is not refused.
+
+Then, once per step, named for the step's number:
+
+    git -C "$root" worktree add --detach "$wave/step-<n>" "$base"
+
+`--detach` creates no branch, whatever `git.mode` says. Keeping the worktrees outside the
+project keeps a second copy of the source out of the project's own tests, linters and file
+watchers.
+
+The stash commit leaves untracked files out, so copy them in, all but the workflow's own
+state, which would carry the saved wave path into the worktree:
+
+    git -C "$root" ls-files --others --exclude-standard -z |
+      while IFS= read -r -d '' f; do
+        case "$f" in religion/.state/*) continue;; esac
+        mkdir -p "$wave/step-<n>/$(dirname "$f")" && cp -RPp "$root/$f" "$wave/step-<n>/$f"
+      done
+
+`-RP` copies an untracked link as a link. Plain `cp` refuses a link to a directory, and
+following it would copy whatever it points at.
+
+Then make the copies part of the step's base, so they are not handed back as new files:
+
+    git -C "$wave/step-<n>" add -A
+    git -C "$wave/step-<n>" write-tree > "$wave/step-<n>.base"
+
+`write-tree` saves a tree object and nothing else: no commit, no ref. The saved file is the
+base phase 5 diffs against, and it survives a shell that does not keep variables between
+commands.
+
+## 3. Link
+
+A fresh worktree has none of the project's installed dependencies. Symlink each installed
+dependency directory at the project root that the gate needs, such as `node_modules`:
+
+    [ -e "$wave/step-<n>/node_modules" ] || [ -L "$wave/step-<n>/node_modules" ] ||
+      ln -s "$root/node_modules" "$wave/step-<n>/node_modules"
+
+Skip the link when anything already sits at that path, such as an untracked link copied in
+phase 2. `ln -s` onto an existing link to a directory does not replace it: it creates a new
+link inside the directory it points at, which here is the project's real dependencies.
+
+Never install into a worktree. That is a dependency install, which the Authority section
+does not grant a wave. On Windows the link would be a junction, which this routine has not
+been run against.
+
+## 4. Build
+
+When the project's gate reads build output that is not committed, run the project's build in
+the worktree before handing it to the subagent, so the step's checks can run there at all.
+Run it in a subshell, `(cd "$wave/step-<n>" && <build>)`, so the current directory never
+moves into the worktree.
+
+## 5. Extract
+
+When the subagent returns, take its patch:
+
+    git -C "$wave/step-<n>" add -A
+    git -C "$wave/step-<n>" diff --cached --binary "$(cat "$wave/step-<n>.base")" -- . <exclusions> > "$wave/step-<n>.patch"
+
+`add -A` writes to the worktree's own index, never the project's, and brings new files into
+the patch. `<exclusions>` is one `':!<path>'` for each link made in phase 3, which an ignore
+rule with a trailing slash such as `node_modules/` does not cover, because a link is not a
+directory. Then one more for each path the project's instructions declare as generated, such
+as rendered trees, so two steps that both regenerate a shared file do not
+collide over output the build reproduces. A project that declares none keeps every path, and
+a generated file that both steps touched then fails the join and stops it.
+
+## 6. Join
+
+All patches, in step order, through **one** `git apply` of one file:
+
+    for p in "$wave"/step-<n>.patch "$wave"/step-<m>.patch; do [ -f "$p" ] || exit 1; done
+    cat "$wave"/step-<n>.patch "$wave"/step-<m>.patch > "$wave/join.patch"
+    git -C "$root" apply "$wave/join.patch"
+
+Check that every step's patch exists first, and never pipe into `git apply`: without
+`pipefail` a pipe reports `git apply`'s status alone, so a missing patch would land the
+others as a success and teardown would delete the step that never applied.
+
+One concatenated input applies all or nothing, including two patches to the same file.
+Separate patch files given to one `git apply` do not: the first lands even when a later one
+fails. Never `--3way`, never a merge, and never resolve a conflict by editing.
+
+On failure the project is exactly as it was. Stop the wave, keep the worktrees, and report
+the paths `git apply` named and where each worktree is.
+
+On success, run the project's build once when any path was excluded, so generated output is
+rendered from the joined sources, then run each step's gate on the joined tree.
+
+## 7. Teardown
+
+Only after a successful join, and only for worktrees this run created for this wave. Once per
+step:
+
+    rm "$wave/step-<n>/node_modules"
+    git worktree remove --force "$wave/step-<n>"
+    rm "$wave/step-<n>.patch" "$wave/step-<n>.base"
+
+Then once for the wave:
+
+    rm "$wave/join.patch" "$wave/base"
+    rmdir "$wave"
+    rm "$root/religion/.state/wave"
+
+Remove each link first, so nothing follows it into the project's real dependencies. Removing
+any other worktree, or these after a failed join, still asks.

package/template/.agents/skills/rollback/SKILL.md

@@ -67,7 +67,9 @@ Stop on any failure. Do not repair a mismatch by choosing a nearby commit.
 1. Every recorded identifier matches `^[0-9a-f]{40}$`. Reject abbreviated or uppercase
    values.
 2. Every recorded commit resolves in this repository and is an ancestor of `HEAD`.
-3. The recorded base is the parent of the earliest recorded commit.
+3. The recorded base is the parent of the earliest recorded commit. For an item landed on top
+   of another, that commit is the merge that brought the other in, and the base must be its
+   second parent, what it brought in: the first parent would reverse the other item's work.
 4. The working tree is clean apart from the rollback spec being written.
 
 ## Step 3 - preview the product diff