create-religion 1.4.0 → 1.6.0

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

@@ -1,7 +1,7 @@
 ---
 name: auto
 summary: run the loop unattended, within explicit bounds
-description: "Run the reviewed loop without stopping between steps, within bounds you set. With no argument it takes one work item and stops before completing it; `all` runs the remaining build plan; a number runs that many items; `fix` works through the findings ledger instead, every class most severe first or one class such as `fix P1`, one fix per file and class, re-reviewing every repair and folding any finding a repair surfaces into the same fix. Specs, implements, verifies, applies the configured gates, repairs confirmed high-severity findings, and completes each item. Its invocation grants committing, dependency installs, and remote reads for the run, and grants nothing else: it still stops to ask before any merge. Under git.mode pull-request it lands every item on one shared integration branch and ends by opening a single aggregate review packet it never merges, after stating that whole remote budget up front and being told yes. Use only when the user runs $auto or explicitly asks for an unattended run."
+description: "Run the reviewed loop without stopping between steps, within bounds you set. With no argument it takes one work item and stops before completing it; `all` runs the remaining build plan; a number runs that many items; a range or list such as `1-5` or `6, 7, 8` runs exactly those items; `refresh` brings the default branch into a run's integration branch after another run landed first; `fix` works through the findings ledger instead, every class most severe first or one class such as `fix P1`, one fix per file and class, re-reviewing every repair and folding any finding a repair surfaces into the same fix. Specs, implements, verifies, applies the configured gates, repairs confirmed high-severity findings, and completes each item. Its invocation grants committing, dependency installs, and remote reads for the run, and grants nothing else: it still stops to ask before any merge. Under git.mode pull-request it lands every item on one shared integration branch and ends by opening a single aggregate review packet it never merges, after stating that whole remote budget up front and being told yes. Use only when the user runs $auto or explicitly asks for an unattended run."
 ---
 
 # auto - the same loop, without the pauses
@@ -18,7 +18,11 @@ between steps.
 - `$auto all` - the remaining build plan, completing each item, until it runs out or hits
   a bound.
 - `$auto 3` - the next three items, completing each.
+- `$auto 1-5` or `$auto 6, 7, 8` - exactly those plan items, completing each. A range or
+  a comma list names items; a bare number is always a count. See Named items.
 - `$auto resume` - continue an interrupted run from the file-backed state.
+- `$auto refresh` - bring the default branch into a run's integration branch after another
+  run's aggregate landed first. See Refresh.
 - `$auto fix` - the findings ledger instead of the plan; see Fix mode.
 
 `auto.maxItems` caps successful completions. `auto.maxRepairAttempts` caps repeated
@@ -67,7 +71,7 @@ Before the first item:
   than one that never began.
 - The working tree is clean, or the only dirt belongs to work being resumed.
 - The plan has unchecked items, or in fix mode the ledger has `open` or `fixed` findings in
-  range.
+  range. A named run needs at least one of its own items unchecked.
 - Under `pull-request`, the repository can host one: a remote exists and the host command
   works. A repository that cannot is a stop, not a reason to fall back to local merges. The
   mode exists to produce review gates, and silently producing a different history instead
@@ -84,6 +88,24 @@ if one exists that does not descend from the recorded commit, stop, because the
 moved and that needs a person. Never rebase, reset, or force-push it: it is append-only for
 the run.
 
+A named run's integration branch adds its items to the date, `<prefix><date>-<first>-<last>`,
+or `-<item>` for one, with labels as the plan writes them: `auto/2026-10-26-6-10`. Two runs on
+one day then never share a name, and a resume finds its own.
+
+**With `workflow.parallelItems` on**, under `pull-request`, the run works in its own worktree so
+another session can run beside it. The main checkout must be on the default branch at the
+recorded commit, since the worktree is made from `HEAD`; anything else stops. Make the
+integration branch with blocks 1 and 2 of the routine $implement keeps in
+`reference/item-worktree.md`, with `move='no'`, push it from the worktree, and work from there
+from then on: move the session into it where the tool can, and otherwise address every file and
+command to its path. Item branches stay plain branches, made and removed inside that worktree,
+so the main checkout stays on the default branch for the next session. Under
+`branch-per-item`, which merges each item into the default branch only one checkout can hold, a
+run stays in the main checkout and runs alone.
+
+**Resuming from the main checkout** while a run's worktree exists names that worktree and its
+branch and stops: the run resumes from there, never as a second copy here.
+
 State the bounds, the gates in force, and how many items are in range. Then start.
 
 ## Step 2 - each item
@@ -115,6 +137,102 @@ nothing left to build and stops there.
 
 An item counts against `auto.maxItems` once it has landed, not once it is built.
 
+## Named items
+
+Given a range or a list, the run builds those items and no others.
+
+- **Plan order**, whatever order they were given in, since the waiting rule assumes it.
+- **A ticked item** is named and passed over. **A number the plan does not have** stops the
+  run before any work starts, naming it: a typo should not quietly shrink the run.
+- **The waiting rule still applies.** An item waiting on one outside the list, or on a
+  spike, is passed over and named in the final report, as in Step 2.
+- **Refuse what another run holds.** Before any work, read `religion status --json`, or the
+  handoff without that command. A named item that an `inFlight` entry with `here` false holds
+  under `items` or is building, counting a parent and its sub-items as one, stops the run,
+  naming each such item and the branch that has it: two runs over one item is what holding
+  exists to prevent.
+- **Name what waits on another run.** A named item that waits on an item held elsewhere will
+  be passed over, since that item lands on the other run's integration branch, not this one.
+  Name each when stating the bounds, with what it waits on and the branch that holds it, so a
+  run that will build fewer items than it was given says so before it starts.
+- **Hold them.** The first write, made before the configuration is read, holds no `items`.
+  Once preflight knows where the run will run, write the listed items, lowercased, as `items`
+  in the record there, and keep them in every rewrite. A run that moves into its own worktree
+  writes them only in the worktree, then rewrites the main checkout's record as `completed`,
+  holding none and with no resume command, its summary naming the worktree: nothing resumes
+  from the main checkout, and a record holding the items there would read, from the run's own
+  worktree, as another run holding them. That is what lets `status`, the handoff and
+  $feature in another worktree pass over the items this run has not reached yet, which no
+  spec shows.
+- **Release them only when none is left to build**, each named item completed, already
+  ticked, or passed over as waiting. That release is the run's last write, made after Step 3
+  has opened the aggregate pull request where the mode has one, and it is `completed` although
+  the run ends waiting for review: `completed` is what says nothing remains to resume. It keeps
+  just the items the run completed, so the ones it passed over are free for another worktree to
+  take; a parent number stays only when every sub-item under it was completed, since a parent
+  still held holds all of them. A run that completed nothing has no aggregate to open, so it
+  releases at once, `completed` and holding none. Any other stop, a merge question, a bound, a
+  failure, an aggregate pull request opened early, or one Step 3 should have opened and did not,
+  keeps every item and writes `blocked` with `$auto resume`.
+- **Resume.** A record holding `items` resumes those still unticked, and when every one is
+  ticked it resumes at Step 3; a `completed` one has nothing left to resume. A record without
+  `items` is a count, `all` or fix run, and resumes as one. A named run whose record is gone
+  stops and asks for the list again rather than guessing which items it had.
+
+Plain numbers and sub-item labels are both items (`39a, 39b`); a range covers whole numbers
+only. A number that has sub-items stands for its unticked sub-items: build those, and record
+their labels in `items` beside the number, so readers that do not walk the plan still see
+them.
+
+## Refresh
+
+`$auto refresh` catches a run up when another run's aggregate pull request merged into the
+default branch first. Both wrote the plan, the ledger and the journal, so this run's aggregate
+now conflicts on them every time. It runs where the run's integration branch is checked out, in
+the run's own worktree when it has one, and only when all of these hold; otherwise it stops and
+says which:
+
+- the checked-out branch starts with `git.integrationBranchPrefix` and is not the default
+  branch, and the run's aggregate pull request is open with it as head and the default branch
+  as base
+- the run's own record, here, is `blocked` or `completed`, never `running`, and the spec is the
+  stub and the tree clean
+- after fetching it, the branch is at its remote-tracking copy or can fast-forward to it, which
+  is how an item merged on the host since reaches it; or it is ahead only by an earlier
+  refresh's own merge, one commit whose second parent is on the default branch, left by a
+  rejected push. Ahead by that merge and behind as well means the merge was made on a stale
+  branch: stop, naming the merge commit and saying why. Dropping it is a reset, first-tier and
+  the person's to take, after which a refresh starts again from the remote copy. Any other
+  difference stops
+
+A refresh writes **no activity record**, the one exception to writing one first: the record is
+the run's, and the `items` it holds are what keep other worktrees off the run's work.
+
+Its remote budget is asked for **before any work starts**, in full, as a run's is:
+
+    This refresh will, without asking again:
+      push <integration branch>, adding one merge commit that brings in <default branch>
+      update the body of its aggregate pull request <number>
+
+    It will not merge or push <default branch>, will not force-push,
+    and will not merge the aggregate pull request.
+
+Then, when the branch is behind, fast-forward it. When an earlier refresh's merge is waiting,
+push it as it is, add the body line, and end. Otherwise fetch the default branch and follow "A
+run catching up" in $complete's `reference/land-on-top.md`: blocks 1 to 3 with the
+default branch's remote-tracking name as the target, redoing the share of every item the run
+completed; `nothing landed since` ends the refresh with nothing to do. Run the full `Verify`.
+Only when it passes, commit the merge, push the integration branch by name, never forced, and
+add a line to the aggregate's body naming the default-branch commit brought in and the files
+redone. A rejected push is a stop that keeps the merge commit locally and says so. Once the
+cause is put right, `$auto refresh` again pushes it; when the push was refused because the
+branch moved on the host, it stops on the stale merge as above.
+
+Stop, keeping the state as it is, on a conflict outside the shared files, which the routine
+reports and abandons; on a failing `Verify`, abandoning the merge with the routine's block; or
+when nothing landed since. A refresh never rebases, resets or force-pushes the integration
+branch, and the run's activity record and the items it holds are left as they were.
+
 ## Fix mode
 
 `$auto fix` works through the findings ledger instead of the build plan, under the same

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

@@ -93,9 +93,9 @@ Read the spec's type.
 
 The number lives in the path. It never appears in the commit message.
 
-**Record what landed.** After the work commit exists in Step 3, append a `## Landed`
-section to the archive with the exact commits this item produced, oldest first, and the
-commit that preceded them:
+**Record what landed.** After the work commit exists in Step 3, and after Step 4 has landed
+it on top of anything that landed first, append a `## Landed` section to the archive with the
+exact commits this item produced, oldest first, and the commit that preceded them:
 
     ## Landed
 
@@ -110,9 +110,10 @@ commits sit among others on the same branch, so this record is the only reliable
 
 **Prune the ledger.** Append every `closed`, `accepted`, and `invalid` entry to a
 `## Findings` section in the archive just written, at its final status, with the reason
-preserved for accepted entries. Prefix each identifier with the archive name so it is
-globally unique: item 12's `F-03` becomes `12/F-03`, and that prefixed form is the
-permanent reference.
+preserved for accepted entries. Every archived identifier carries a prefix, so it is
+globally unique, and that prefixed form is the permanent reference. One raised under the
+item's prefix already has it and moves across unchanged: item 12's `12/F-3` stays `12/F-3`.
+Prefix only a bare one, with the archive name: item 12's `F-03` becomes `12/F-03`.
 
 Then remove only those entries from the ledger. `open`, `fixed`, and `unverified` entries
 stay, with their identifiers, so nothing is silently dropped. A `fixed` P2 does not block
@@ -195,6 +196,15 @@ is refused outright when any of those commits has already been pushed.
 Under **`git.mode: trunk`** the work is already on the branch you were on. There is nothing
 to merge. Go to Step 5.
 
+**Under either branching mode, land on top of what already landed.** Before the squash merge
+or the push, follow `reference/land-on-top.md`. When the branch the item lands in has moved
+since the item began, because another item built in its own worktree landed first, it brings
+that in, takes the landed copy of each of the plan, ledger, journal, overview and handoff that
+the other item changed, and redoes this item's share of them, so those files are never merged
+as text. Any other conflict stops
+for review. When nothing landed in between, it does nothing. Write the `## Landed` record after
+it, as its last section says, so a later rollback reverses this item's work alone.
+
 Under **`branch-per-item`**:
 
 1. Squash-merge into the default branch, only with an explicit yes, so the item lands as
@@ -245,6 +255,12 @@ confirm the work commit is actually in it, and only then delete the branch local
 the remote. A squash-merge leaves no merge parent, so `git branch -d` will refuse; verify
 the content landed before reaching for `-D`.
 
+An item built in its own worktree holds its branch there, so the cleanup runs from the main
+checkout: remove the worktree first, then the branch. Removing the worktree is deleting files,
+so it asks, every time, and only once the work commit is confirmed in the default branch. When
+the state directory is ignored, the item's record is in the worktree alone until the routine's
+last section has copied it to the main checkout; say so when asking.
+
 ## Step 5 - say how to try it
 
 Always end with the manual walkthrough for what just landed: what to start, where to go,

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

@@ -0,0 +1,188 @@
+# 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.
+
+## A run catching up
+
+`$auto refresh` uses blocks 1 to 3 for a whole run rather than one item, when another run's
+aggregate pull request merged into the default branch first. The checkout is the run's
+integration branch, between items, and the target is the default branch's remote-tracking name,
+such as `origin/main`, fetched first. The merge is a commit on the integration branch, which
+stays append-only: nothing is rebased, reset or force-pushed.
+
+Block 2's share is every item the run completed, each row as the table gives it: every one of
+the run's plan ticks, and a parent's once all its sub-items are ticked; the ledger entries
+`HEAD` holds beyond the merge base, as for one item; and each journal entry whose `**Archive:**`
+names one of the run's archives. Block 4 does not apply: each item's `## Landed` record already
+names its own commits on the integration branch, and the refresh's merge belongs to none of them.
+
+## 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,12 @@ 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. So is an item an automated
+run in another worktree holds: one listed under `items` on an `inFlight` entry with `here`
+false, or named as held in the handoff. 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,18 @@ 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 a plain branch per item, inside the run's own worktree when it has
+one, 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.
 
@@ -194,7 +210,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,133 @@
+# 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. An automated run makes its own worktree with the same blocks; see
+the last section.
+
+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, or for a run when it is a worktree on the run's branch, 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>'
+      move='yes'
+      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"
+      if [ "$move" = yes ]; then
+        ! 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
+      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
+      if [ "$move" = yes ]; then
+        mkdir -p "$tree/religion/context" && cp -p "$root/$spec" "$tree/$spec" && cmp -s "$root/$spec" "$tree/$spec" || exit 1
+      fi
+      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.
+
+## A run's worktree
+
+`$auto` under `pull-request` with `workflow.parallelItems` on makes its worktree with blocks
+1 and 2: `branch` is the run's integration branch, and block 2 sets `move='no'`, since a run
+starts with no spec to move. Block 2 then copies only what git does not carry; the worktree's
+spec is whatever its branch holds, the stub. Block 3 is an item's and never runs for a run.
+
+Once the run writes its activity record there, `religion status` in the main checkout lists the
+run under `inFlight` with the items it holds, as block 4 describes for an item.

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