create-religion 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # create-religion
 
+## 1.4.0
+
+### Minor Changes
+
+- a15784b: With `workflow.parallelSteps` on, `implement` builds each wave step in its own detached git
+  worktree outside the project and joins the steps' patches with one all-or-nothing `git apply`,
+  stopping for review with the project unchanged when they do not apply. The commands live in the
+  implement skill's `reference/worktrees.md`. The authority rules let a run remove the worktrees it
+  created for a wave once that wave has joined; removing anything else still asks.
+
 ## 1.3.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-religion",
-  "version": "1.3.0",
+  "version": "1.4.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/implement/SKILL.md

@@ -154,16 +154,30 @@ Two waves of one, then a wave of two, then a wave of one.
 **Refuse a wave rather than guess at one.** Run the wave sequentially, and say why, when:
 
 - a marker names a later step, itself, or a step that does not exist
-- two steps in the wave would change the same file, which is a conflict the spec did not
-  intend and the author is better placed to resolve than a merge
+- two steps in the wave would change the same authored file, which is a conflict the spec
+  did not intend and the author is better placed to resolve than a merge. Output the
+  project's build generates from those files does not count; it is rendered once after
+  the join
 - the wave is larger than three steps, which usually means the spec is describing one step
   badly rather than three independent ones
 
-**Building a wave.** Each step runs in its own subagent with the step, the spec, the
-standards, and nothing else. They build and **return**; they do not tick, do not write the
-spec, and do not touch the ledger. The parent applies what comes back, runs the gate for each
-step, and performs every write. This is the same rule audit's lenses follow, for the same
-reason: concurrent writers to one file is the one thing waves must never introduce.
+**Building a wave.** Each step builds in its own detached git worktree outside the project,
+set up and torn down by `reference/worktrees.md`, so a step cannot see or change another
+step's files. Each runs in its own subagent with the step, the spec, the standards, the path
+of its worktree, and nothing else. They build there and **return** their evidence; they do
+not tick, do not write the spec, and do not touch the ledger. The parent extracts each
+step's patch and performs every write. This is the same rule audit's lenses follow, for the
+same reason: concurrent writers to one file is the one thing waves must never introduce.
+
+**Joining a wave.** The parent concatenates the patches in step order and applies them with
+one `git apply`, which lands all of them or none. Then it renders generated output once,
+when any was left out of the patches, and runs each step's gate on the joined tree. A step
+that fails its gate there leaves its patch applied for review, as a failed step always does.
+
+**A join that does not apply stops the wave** with the project exactly as it was. Report the
+paths `git apply` named and where each worktree is, keep the worktrees, tick nothing, and
+leave the conflict for review. Never retry with a three-way apply, merge, or edit to make it
+fit.
 
 **A failure stops the wave.** Report which steps passed and which did not, tick only what
 passed, and stop. Do not retry the wave; the next run resumes at the first unticked step,

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

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

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

@@ -154,16 +154,30 @@ Two waves of one, then a wave of two, then a wave of one.
 **Refuse a wave rather than guess at one.** Run the wave sequentially, and say why, when:
 
 - a marker names a later step, itself, or a step that does not exist
-- two steps in the wave would change the same file, which is a conflict the spec did not
-  intend and the author is better placed to resolve than a merge
+- two steps in the wave would change the same authored file, which is a conflict the spec
+  did not intend and the author is better placed to resolve than a merge. Output the
+  project's build generates from those files does not count; it is rendered once after
+  the join
 - the wave is larger than three steps, which usually means the spec is describing one step
   badly rather than three independent ones
 
-**Building a wave.** Each step runs in its own subagent with the step, the spec, the
-standards, and nothing else. They build and **return**; they do not tick, do not write the
-spec, and do not touch the ledger. The parent applies what comes back, runs the gate for each
-step, and performs every write. This is the same rule audit's lenses follow, for the same
-reason: concurrent writers to one file is the one thing waves must never introduce.
+**Building a wave.** Each step builds in its own detached git worktree outside the project,
+set up and torn down by `reference/worktrees.md`, so a step cannot see or change another
+step's files. Each runs in its own subagent with the step, the spec, the standards, the path
+of its worktree, and nothing else. They build there and **return** their evidence; they do
+not tick, do not write the spec, and do not touch the ledger. The parent extracts each
+step's patch and performs every write. This is the same rule audit's lenses follow, for the
+same reason: concurrent writers to one file is the one thing waves must never introduce.
+
+**Joining a wave.** The parent concatenates the patches in step order and applies them with
+one `git apply`, which lands all of them or none. Then it renders generated output once,
+when any was left out of the patches, and runs each step's gate on the joined tree. A step
+that fails its gate there leaves its patch applied for review, as a failed step always does.
+
+**A join that does not apply stops the wave** with the project exactly as it was. Report the
+paths `git apply` named and where each worktree is, keep the worktrees, tick nothing, and
+leave the conflict for review. Never retry with a three-way apply, merge, or edit to make it
+fit.
 
 **A failure stops the wave.** Report which steps passed and which did not, tick only what
 passed, and stop. Do not retry the wave; the next run resumes at the first unticked step,

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

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

package/template/AGENTS.md

@@ -104,6 +104,10 @@ carry to a later instance.
 - deleting files or data, and any rewrite of existing history
 - changing a remote service, its configuration, or its secrets
 
+Removing a detached worktree that the current run created for a wave, outside the project,
+once that wave's join has succeeded, is not deleting files or data. Removing any other
+worktree still asks.
+
 Pushing a branch that a run created itself is the single action that may be granted ahead
 of time, and only in the narrow way set out below. Every other push is first tier.
 
@@ -184,8 +188,9 @@ needed, a conflict appears, the work drifts outside its spec, or something in th
 tier of the authority rules comes up.
 
 `workflow.parallelSteps` ships `false`. Turned on, steps a spec marks as independent are
-built together in one wave and reviewed as one packet, so nothing lands unreviewed either
-way. While it is off, those markers are ignored and every spec builds in order.
+built together in one wave, each in its own git worktree, then joined and reviewed as one
+packet, so nothing lands unreviewed either way. A join that does not apply cleanly stops for
+review. While it is off, those markers are ignored and every spec builds in order.
 ## Activity
 
 Any skill that changes something writes an activity record to

package/template/CLAUDE.md

@@ -68,6 +68,10 @@ carry to a later instance.
 - deleting files or data, and any rewrite of existing history
 - changing a remote service, its configuration, or its secrets
 
+Removing a detached worktree that the current run created for a wave, outside the project,
+once that wave's join has succeeded, is not deleting files or data. Removing any other
+worktree still asks.
+
 Pushing a branch that a run created itself is the single action that may be granted ahead
 of time, and only in the narrow way set out below. Every other push is first tier.
 
@@ -148,8 +152,9 @@ needed, a conflict appears, the work drifts outside its spec, or something in th
 tier of the authority rules comes up.
 
 `workflow.parallelSteps` ships `false`. Turned on, steps a spec marks as independent are
-built together in one wave and reviewed as one packet, so nothing lands unreviewed either
-way. While it is off, those markers are ignored and every spec builds in order.
+built together in one wave, each in its own git worktree, then joined and reviewed as one
+packet, so nothing lands unreviewed either way. A join that does not apply cleanly stops for
+review. While it is off, those markers are ignored and every spec builds in order.
 ## Activity
 
 Any skill that changes something writes an activity record to