create-religion 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # create-religion
 
+## 1.6.0
+
+### Minor Changes
+
+- 6834ede: `auto refresh` catches a run up when another run's aggregate pull request merged into the
+  default branch first: it brings the default branch into the run's integration branch with a
+  merge commit, takes the landed plan, ledger and journal and redoes the run's own share on top,
+  runs `Verify`, then pushes the branch and notes the refresh in the aggregate pull request. It asks
+  for that push and edit before starting, and never rebases or force-pushes.
+- 6834ede: With `workflow.parallelItems` on under `git.mode: pull-request`, an `auto` run works in its own
+  git worktree beside the project, on an integration branch named from the date and its items,
+  such as `auto/2026-10-26-6-10`, so two sessions can each run a named set of items at once.
+  Before any work a named run stops on an item another run holds, and names the items it will
+  pass over because they wait on another run's. A named run now releases its items only as its
+  last write, after the aggregate pull request is open.
+- 9e73d9a: `auto` takes an explicit list or range of plan items, such as `1-5` or `6, 7, 8`, and records
+  them in its activity record as `items`. `religion status --json` reports them under `activity`
+  and under each `inFlight` entry, and lists a worktree whose run sits between items by the items
+  it holds. `religion status` and `feature` pass over items a run in another worktree holds,
+  including the ones it has not reached yet, and the handoff names them. A held plan item
+  holds every sub-item under it.
+
 ## 1.5.0
 
 ### Minor Changes

package/dist/lib/state.js

@@ -336,7 +336,7 @@ const CONTROL = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu;
  * write the record controls every field in it.
  */
 export function parseActivity(source, skills) {
-    const none = { recorded: false, command: null, status: null, summary: null, updatedAt: null, resumeCommand: null };
+    const none = { recorded: false, command: null, status: null, summary: null, updatedAt: null, resumeCommand: null, items: [] };
     if (!source)
         return none;
     let record;
@@ -348,7 +348,7 @@ export function parseActivity(source, skills) {
     }
     if (!record || typeof record !== "object")
         return none;
-    const { command, status, summary, updatedAt, resumeCommand } = record;
+    const { command, status, summary, updatedAt, resumeCommand, items } = record;
     if (typeof command !== "string" || !SKILL_NAME.test(command) || !skills.has(command))
         return none;
     if (typeof summary !== "string")
@@ -361,9 +361,18 @@ export function parseActivity(source, skills) {
         status: status,
         summary: summary.replace(CONTROL, " "),
         updatedAt: typeof updatedAt === "string" ? updatedAt.replace(CONTROL, " ") : null,
-        resumeCommand: resumes(command, resumeCommand) ? resumeCommand : null
+        resumeCommand: resumes(command, resumeCommand) ? resumeCommand : null,
+        items: command === "auto" ? heldItems(items) : []
     };
 }
+const HELD_MAX = 100;
+/** A malformed list degrades to fewer items, never to an unreadable record. */
+function heldItems(items) {
+    if (!Array.isArray(items))
+        return [];
+    const held = items.filter((i) => typeof i === "string" && /^\d+[a-z]?$/i.test(i)).map((i) => i.toLowerCase());
+    return [...new Set(held)].slice(0, HELD_MAX);
+}
 function resumes(command, resumeCommand) {
     if (typeof resumeCommand !== "string" || resumeCommand.length > RESUME_MAX)
         return false;
@@ -552,6 +561,7 @@ async function readPlain(file, within) {
     }
 }
 /** Active specs across the repository's worktrees; empty outside a repository. */
+const AUTO = new Set(["auto"]);
 export async function readInFlight(root) {
     const listed = await listWorktrees(root);
     const self = await fs.realpath(root).catch(() => null);
@@ -564,13 +574,17 @@ export async function readInFlight(root) {
         // A wave's step worktree holds a copy of its parent item's spec, not an item of its own.
         if (/^step-\d+$/.test(path.basename(worktree)) && (await readIfPresent(path.join(path.dirname(worktree), "base"))) !== null)
             continue;
-        const spec = statePath(path.join(worktree, offset), "context", "current-work.md");
-        // This worktree's spec is read as `work` reads it; another's comes from someone else's branch.
-        const source = worktree === listed.home ? await readIfPresent(spec) : await readPlain(spec, worktree);
+        const base = path.join(worktree, offset);
+        // This worktree's files are read as `work` reads them; another's come from someone else's branch.
+        const read = (file) => (worktree === listed.home ? readIfPresent(file) : readPlain(file, worktree));
+        const source = await read(statePath(base, "context", "current-work.md"));
+        // Only an `auto` run holds items, so no other skill needs to be installed for its record to count.
+        const { items } = parseActivity(await read(statePath(base, ".state", "run.json")), AUTO);
         const work = parseWork(source);
-        if (!source || !work.active)
+        // A run between items has no spec, yet still holds the items it has not reached.
+        if (!work.active && items.length === 0)
             continue;
-        const plan = field(source, "From build plan");
+        const plan = work.active ? field(source, "From build plan") : null;
         found.push({
             worktree,
             branch,
@@ -579,7 +593,8 @@ export async function readInFlight(root) {
             title: work.title,
             stepsDone: work.stepsDone,
             stepsTotal: work.stepsTotal,
-            here: worktree === listed.home
+            here: worktree === listed.home,
+            items
         });
     }
     return found;

package/dist/lib/status.js

@@ -12,9 +12,20 @@ export function computeStatus(state) {
     const done = leaves.filter((i) => i.done).length;
     const { waits, problems } = waiting(state.plan, new Set(state.settledSpikes));
     const waitsOn = (item) => (item.number ? waits.get(item.number) : undefined);
-    // An item another worktree is building is not this checkout's to start.
-    const elsewhere = new Map(state.inFlight.filter((i) => !i.here && i.item).map((i) => [i.item, i.branch ?? i.worktree]));
-    const busy = (item) => !!item.number && elsewhere.has(item.number);
+    // An item another worktree is building, or that a run there holds, is not this checkout's to start.
+    const elsewhere = new Map(state.inFlight.filter((i) => !i.here).flatMap((i) => [...i.items, ...(i.item ? [i.item] : [])].map((n) => [n, i.branch ?? i.worktree])));
+    // A run holding a parent holds its sub-items, which are what actually get built.
+    const holder = new Map();
+    const parents = [];
+    for (const item of state.plan) {
+        while (parents.length && parents[parents.length - 1].depth >= item.depth)
+            parents.pop();
+        const by = [...parents, item].map((p) => p.number && elsewhere.get(p.number)).find(Boolean);
+        if (by)
+            holder.set(item, by);
+        parents.push(item);
+    }
+    const busy = (item) => holder.has(item);
     const nextItem = leaves.find((i) => !i.done && !waitsOn(i) && !busy(i)) ?? null;
     const before = leaves.slice(0, nextItem ? leaves.indexOf(nextItem) : leaves.length).filter((i) => !i.done);
     const passedOver = before.filter((i) => waitsOn(i));
@@ -31,8 +42,9 @@ export function computeStatus(state) {
         const named = passedOver.map((i) => `${i.number} (${waitsOn(i).join(", ")})`);
         warnings.push(`passed over plan items that are waiting: ${named.join("; ")}`);
     }
-    if (building.length > 0) {
-        const named = building.map((i) => `${i.number} (${elsewhere.get(i.number)})`);
+    // An unnumbered line under a held parent is passed over too, but has no number to name.
+    if (building.some((i) => i.number)) {
+        const named = building.filter((i) => i.number).map((i) => `${i.number} (${holder.get(i)})`);
         warnings.push(`passed over plan items in flight in another worktree: ${named.join("; ")}`);
     }
     warnings.push(...problems.map((p) => `the build plan: ${p}`));
@@ -112,8 +124,11 @@ export function renderStatus(status, cmd = "/") {
             (status.work.status ? ` (${status.work.status})` : "")
         : "Active:   nothing in progress");
     for (const item of status.inFlight.filter((i) => !i.here)) {
-        out.push(`In flight: ${item.item ? `item ${item.item} ` : ""}${item.title ?? "untitled"} - step ${item.stepsDone}/${item.stepsTotal}` +
-            ` on ${item.branch ?? item.worktree}`);
+        const holding = item.items.length > 0 ? `holding items ${item.items.join(", ")}` : "";
+        // A run between items has no spec to describe, only the items it holds.
+        const between = holding && !item.item && !item.title && item.stepsTotal === 0;
+        const work = between ? null : `${item.item ? `item ${item.item} ` : ""}${item.title ?? "untitled"} - step ${item.stepsDone}/${item.stepsTotal}`;
+        out.push(`In flight: ${work ? work + (holding ? `, ${holding}` : "") : `auto run ${holding}`} on ${item.branch ?? item.worktree}`);
     }
     out.push(`Plan:     ${status.plan.done}/${status.plan.total} complete (${pct}%)`);
     const run = status.activity;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-religion",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "A file-backed, spec-driven AI development workflow. Spec before code, small reviewed diffs, and project state in markdown so a cleared context costs nothing.",
   "license": "MIT",
   "author": "Nate",

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/reference/land-on-top.md

@@ -158,6 +158,20 @@ the target it brought in, as **Base**, and that merge commit and anything after
 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,

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

@@ -67,7 +67,9 @@ those is unticked, or says `spike first` and no archive under `religion/history/
 Name each item passed over and what it waits on, and point a spike-first one at
 $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.
+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

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

@@ -64,8 +64,9 @@ second one.
 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.
+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

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

@@ -4,7 +4,8 @@ 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.
+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:
@@ -38,7 +39,8 @@ 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.
+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
 
@@ -48,12 +50,15 @@ 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"
-      ! 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
+      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
@@ -75,7 +80,9 @@ block 1:
       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
+      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"
     )
 
@@ -114,3 +121,13 @@ 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/.claude/hooks/write-handoff.mjs

@@ -103,6 +103,15 @@ const readPlain = (file, within) =>
       closeSync(fd);
     }
   });
+// The rule `religion status` applies: only an `auto` run holds items, each a plan number, capped.
+const heldItems = (source) =>
+  quiet(() => {
+    const record = JSON.parse(source ?? "");
+    if (record?.command !== "auto" || typeof record.summary !== "string" || !["running", "blocked", "ready", "completed"].includes(record.status)) return [];
+    if (!Array.isArray(record.items)) return [];
+    const held = record.items.filter((i) => typeof i === "string" && /^\d+[a-z]?$/i.test(i)).map((i) => i.toLowerCase());
+    return [...new Set(held)].slice(0, 100);
+  }) ?? [];
 const elsewhere = (() => {
   const self = quiet(() => realpathSync(root));
   let home = self;
@@ -125,12 +134,15 @@ const elsewhere = (() => {
     // A wave's step worktree holds a copy of its parent item's spec, not an item of its own.
     if (/^step-\d+$/.test(path.basename(tree)) && existsSync(path.join(path.dirname(tree), "base"))) return [];
     const spec = readPlain(path.join(tree, offset, STATE, "context", "current-work.md"), tree) ?? "";
-    if (!spec.trim() || /_Nothing in progress\./.test(spec)) return [];
+    const items = heldItems(readPlain(path.join(tree, offset, STATE, ".state", "run.json"), tree));
+    const holding = items.length > 0 ? `holding items ${items.join(", ")}` : "";
+    const on = `on \`${plain(headBranch(git) ?? tree)}\``;
+    if (!spec.trim() || /_Nothing in progress\./.test(spec)) return holding ? [`- **An automated run** ${on}, ${holding}.`] : [];
     const item = spec.match(/^\*\*From build plan:\*\*[ \t]*item[ \t]+([0-9a-z]+)/im)?.[1]?.toLowerCase();
     const name = plain(spec.match(/^#\s+(.+)$/m)?.[1] ?? "Active work");
     // Spaces and tabs only: `\s` crosses newlines, which makes blank lines quadratic.
     const steps = `${(spec.match(/^[ \t]*- \[x\]/gim) ?? []).length} of ${(spec.match(/^[ \t]*- \[[ x]\]/gim) ?? []).length}`;
-    return [`- **${name}**${item ? ` (item ${plain(item)})` : ""} on \`${plain(headBranch(git) ?? tree)}\`: ${steps} step(s) done.`];
+    return [`- **${name}**${item ? ` (item ${plain(item)})` : ""} ${on}: ${steps} step(s) done${holding ? `, ${holding}` : ""}.`];
   });
 })();
 

package/template/.claude/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/.claude/skills/complete/reference/land-on-top.md

@@ -158,6 +158,20 @@ the target it brought in, as **Base**, and that merge commit and anything after
 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,

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

@@ -67,7 +67,9 @@ those is unticked, or says `spike first` and no archive under `religion/history/
 Name each item passed over and what it waits on, and point a spike-first one at
 /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.
+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

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

@@ -64,8 +64,9 @@ second one.
 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.
+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

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

@@ -4,7 +4,8 @@ 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.
+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:
@@ -38,7 +39,8 @@ 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.
+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
 
@@ -48,12 +50,15 @@ 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"
-      ! 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
+      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
@@ -75,7 +80,9 @@ block 1:
       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
+      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"
     )
 
@@ -114,3 +121,13 @@ 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.md

@@ -222,6 +222,16 @@ its intended handoff, such as an unattended run waiting for review. Use `blocked
 exact recovery command when work can resume. `boundary` is `read-only`, `reviewed`, or
 `local-only`. Everything after `updatedAt` is optional.
 
+An `auto` run given explicit items also writes `items`, the plan numbers it holds as strings,
+such as `["6", "7", "8"]`, on every write in the checkout it runs from, starting once preflight
+knows which that is. Other worktrees pass those items over, including the ones the run has not
+reached yet. Only when none of them is left to build, after any aggregate pull request is open,
+does its last write, `completed`, keep just the items it completed, and a parent number only
+when all of its sub-items were; when none is left, a run that completed nothing releases at
+once. Every earlier stop keeps them all and is `blocked`.
+
+`$auto refresh` writes none: it acts on a run whose record holds that run's items.
+
 Writing this record grants nothing and bypasses nothing. A failure to write it is reported
 and ignored: reporting must never turn into a workflow failure.
 

package/template/CLAUDE.md

@@ -186,6 +186,16 @@ its intended handoff, such as an unattended run waiting for review. Use `blocked
 exact recovery command when work can resume. `boundary` is `read-only`, `reviewed`, or
 `local-only`. Everything after `updatedAt` is optional.
 
+An `auto` run given explicit items also writes `items`, the plan numbers it holds as strings,
+such as `["6", "7", "8"]`, on every write in the checkout it runs from, starting once preflight
+knows which that is. Other worktrees pass those items over, including the ones the run has not
+reached yet. Only when none of them is left to build, after any aggregate pull request is open,
+does its last write, `completed`, keep just the items it completed, and a parent number only
+when all of its sub-items were; when none is left, a run that completed nothing releases at
+once. Every earlier stop keeps them all and is `blocked`.
+
+`/auto refresh` writes none: it acts on a run whose record holds that run's items.
+
 Writing this record grants nothing and bypasses nothing. A failure to write it is reported
 and ignored: reporting must never turn into a workflow failure.