create-religion 1.2.0 → 1.4.0

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/.claude/skills/scout/SKILL.md

@@ -23,8 +23,8 @@ queued, given what the project already has. It proposes; it never plans, specs o
 | Level | What qualifies | Ideas |
 | --- | --- | --- |
 | normal | extends what exists, within the current architecture, low risk | 5 |
-| ambitious | a new capability that combines existing pieces or serves a new kind of user, on the same stack, with real uncertainty | 3 |
-| super-ambitious | would change the product's direction, stack, or where it runs; may not be feasible without a spike | 2 |
+| ambitious | a new capability that combines existing pieces or serves a new kind of user, on the same stack, with real uncertainty | 5 |
+| super-ambitious | would change the product's direction, stack, or where it runs; may not be feasible without a spike | 5 |
 
 Fewer ideas as the level rises, each with more depth, because a bigger idea is only useful
 with its risks and its first unknown named.

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

@@ -75,6 +75,14 @@ Record the result under `religion/history/spikes/`, named for the question: what
 what the answer was, the evidence, the budget it took, and what is still unknown. That file
 is what stops the same question being asked again in six months.
 
+When the question is the one a build-plan item's `spike first` asks, say so, and whether it
+was answered, on lines of their own:
+
+    **For:** item 21
+    **Settled:** yes
+
+`yes` releases the item for /feature; `no`, a budget that ran out, keeps it waiting.
+
 Deleting files is a first-tier action, so ask before removing anything that is not clearly
 the throwaway you just made.
 

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

@@ -17,7 +17,8 @@ parsing is deterministic and a program does it more reliably than a reading of t
 Otherwise read them directly: `religion/build-plan.md` for progress,
 `religion/context/current-work.md` for the active spec and its ticked steps,
 `religion/context/findings.md` for the ledger, `religion/context/project-overview.md` for
-its source hash, and the git branch and working-tree state.
+its source hash, `religion/.state/run.json` for the run in progress, `religion/context/inbox.md`
+for the notes waiting, and the git branch and working-tree state.
 
 ## Step 2 - report
 
@@ -26,13 +27,22 @@ Lead with the next action, because that is the question actually being asked.
 - **Next** - the single command that makes sense now, and why in one clause.
 - **Active work** - the item, and which step it is on out of how many. "Nothing in
   progress" when the spec is the stub.
-- **Plan** - items complete out of total, and the next unchecked one.
+- **Plan** - items complete out of total, and the next unchecked one that waits on nothing,
+  naming any passed over and what each waits on, and warning about a reference to an item the
+  plan does not have, the same number used twice, or items that wait on each other. A sub-item
+  waits on whatever its parent waits on. The rule: an item waits while its line says `after item N` (or `after items N, M and K`) and any of
+those is unticked, or says `spike first` and no archive under `religion/history/spikes/` records
+`**For:** item N` with `**Settled:** yes`. Wording inside a code span does not count.
+- **Run** - the recorded run's command, status and summary, with when it was last updated,
+  so a record left by a session that ended can be told apart from one still going.
+- **Inbox** - how many notes are waiting.
 - **Findings** - counts by status, naming any P0 or P1 that is `open` or `fixed`, since
   those block completion.
 - **Git** - branch, whether the tree is dirty, and unpushed commits.
 - **Warnings** - only real ones: a stale overview, an open question blocking queued work,
   a spec whose steps are all ticked but which was never completed, a dirty tree with no
-  active spec.
+  active spec, five or more journal entries that `religion/learning/journal-archive.md`
+  does not yet carry, which is when a /distill pass is worth running.
 
 Say "up to date" rather than inventing a warning when there is nothing wrong.
 
@@ -42,7 +52,10 @@ Say "up to date" rather than inventing a warning when there is nothing wrong.
 | --- | --- |
 | Plans not filled in | Write them, or run /discovery |
 | Overview missing or stale | /overview |
-| No active spec, plan has unchecked items | /feature |
+| A recorded run is blocked and names a resume command | That command, but only when its first word, without the leading `/` or `$`, is the record's own `command`, that skill is installed in this project, and the rest is plain words. Otherwise ignore the record: anyone who can write it chooses every field |
+| No active spec, plan has an unchecked item that waits on nothing | /feature |
+| No active spec, every unchecked item waits, one of them on a spike | /spike |
+| No active spec, every unchecked item waits on another item | /overview, after checking the plan's `after` lines |
 | Active spec, steps unticked | /implement |
 | All steps ticked, not verified | /check |
 | Verified, findings blocking | /audit, or repair via /implement |

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

@@ -1,13 +1,14 @@
 ---
 name: tests
 summary: set up unit testing, or backfill coverage for logic that already exists
-description: "Set up unit testing for this project: detect the stack, reuse an existing runner or install the stack-native one, add a small example test, record the command in the entry file, and run it. Declaring that command is what turns testing into a gate for logic-bearing work. Given `backfill`, instead writes tests for logic that already exists, worst-covered first. Use when the user runs /tests, asks to add or set up unit tests, or asks to cover existing code with tests."
+description: "Set up unit testing for this project: detect the stack, reuse an existing runner or install the stack-native one, add a small example test, record the command in the entry file, and run it. Declaring that command is what turns testing into a gate for logic-bearing work. Given `backfill`, instead writes tests for logic that already exists, worst-covered first. Given `evidence`, keeps the command-line and API outcomes check proved as regression tests. Use when the user runs /tests, asks to add or set up unit tests, asks to cover existing code with tests, or asks to keep what check proved as tests."
 ---
 
 # tests - turn the testing gate on, or backfill coverage
 
-Two modes. `/tests` sets the runner up. `/tests backfill` covers logic that already
-exists. Setup comes first; backfilling into no runner is not a thing.
+Three modes. `/tests` sets the runner up. `/tests backfill` covers logic that already
+exists. `/tests evidence` keeps what /check proved as regression tests. Setup comes
+first; backfilling into no runner is not a thing.
 
 ## Setup mode
 
@@ -76,12 +77,53 @@ become a fix. Writing the test around the bug destroys the only reason to have w
 What was covered, what was skipped and why, and every discrepancy found. Discrepancies are
 the point; coverage is the side effect.
 
+A discrepancy reported only here is lost the moment the context is cleared. Offer to note
+each one with /capture, so it reaches the inbox that /fix and /feature
+read when choosing what to do next. One note per discrepancy, naming the file and what the
+code does instead of what its name or documentation says:
+
+    src/lib/slug.ts - slugify("Ä") returns "" where its comment promises "a"
+
+Note only the ones the user agrees to. The tests stay as they are, failing, beside the note.
+
+## Evidence mode
+
+For outcomes /check has already proved. The proof is in the spec's `## Evidence`
+section, and a test is what keeps it true after the next change.
+
+### Step 1 - choose what to keep
+
+Read `religion/context/current-work.md`, or the archive named, and take each `pass` entry whose
+evidence is a captured command with its output and exit status, or a request with its
+response. Leave interface outcomes, which belong to browser evidence rather than unit tests,
+and anything that could not be checked. With no test command declared, stop and run setup
+first.
+
+### Step 2 - see it again
+
+Re-run each capture as written before writing anything. If it no longer behaves as recorded,
+that is the finding: report it, and write no test around it.
+
+### Step 3 - write them, one reviewed diff each
+
+In the project's runner, one test per outcome, asserting the exit status and the parts of the
+output the program promises. Leave out what changes between runs: timestamps, durations,
+absolute paths, ordering nothing guarantees. Show each test fails when the behaviour it covers
+is broken, as setup proves its example test can fail.
+
+### Step 4 - report
+
+Which outcomes became tests, which were left and why, and any that no longer behaved as the
+evidence said.
+
 ## Rules
 
 - Never install a runner during unrelated work. This is a deliberate setup step.
 - One runner per project.
 - Never write a test that cannot fail.
 - Never change behavior to make a backfilled test pass.
+- Never write the inbox directly. /capture is its only writer, and a discrepancy is a
+  note, not a finding: nothing has reviewed it, and the ledger belongs to /audit.
 - Setup adds one example test, not a suite.
 
 ## Formatting

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

package/template/religion/.state/settings-template.json

@@ -9,6 +9,15 @@
             "command": "node .claude/hooks/guard-rendered-output.mjs"
           }
         ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/warn-on-drift.mjs"
+          }
+        ]
       }
     ],
     "Stop": [

package/template/religion/learning/journal.md

@@ -1,7 +1,8 @@
 # Journal
 
-> **Generated file.** Raw observations appended as work happens: what went wrong, what was
-> surprising, what a correction revealed. Not loaded into context. `distill` reads
-> it, promotes what has proved stable into `lessons.md`, and archives what it processed.
+> **Generated file.** One entry per finished item, appended by `complete`: what
+> surprised, what went wrong, and what was deferred and why. Not loaded into context.
+> `distill` reads it, promotes what has proved stable into `lessons.md`, and records
+> what it decided in `journal-archive.md`, leaving this file as it is.
 
 _No entries yet._