create-religion 1.4.0 → 1.6.0

package/template/.claude/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/.claude/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/.claude/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

package/template/AGENTS.md

@@ -43,7 +43,8 @@ Implementation lands one small step at a time, each with a diff to read and evid
 its stated outcome was met.
 
 `religion/context/current-work.md` holds exactly one work item. Finish it, archive it,
-then start the next. Progress lives in checkboxes inside that file, so a cleared context
+then start the next. With `workflow.parallelItems` on, other items may be in flight in other
+git worktrees, one each; they land one at a time. Progress lives in checkboxes inside that file, so a cleared context
 costs nothing: a fresh session reads which steps are ticked and resumes from the first
 one that is not.
 
@@ -221,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

@@ -35,7 +35,8 @@ Implementation lands one small step at a time, each with a diff to read and evid
 its stated outcome was met.
 
 `religion/context/current-work.md` holds exactly one work item. Finish it, archive it,
-then start the next. Progress lives in checkboxes inside that file, so a cleared context
+then start the next. With `workflow.parallelItems` on, other items may be in flight in other
+git worktrees, one each; they land one at a time. Progress lives in checkboxes inside that file, so a cleared context
 costs nothing: a fresh session reads which steps are ticked and resumes from the first
 one that is not.
 
@@ -185,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.
 

package/template/religion/config.json

@@ -2,7 +2,8 @@
   "schemaVersion": 1,
   "workflow": {
     "stepReview": "every",
-    "parallelSteps": false
+    "parallelSteps": false,
+    "parallelItems": false
   },
   "git": {
     "mode": "trunk",