create-religion 1.3.0 → 1.5.0

package/template/.claude/hooks/write-handoff.mjs

@@ -8,7 +8,7 @@
  */
 
 import { createHash } from "node:crypto";
-import { existsSync, lstatSync, readFileSync, writeFileSync } from "node:fs";
+import { closeSync, constants, existsSync, fstatSync, lstatSync, openSync, readdirSync, readFileSync, readSync, realpathSync, statSync, writeFileSync } from "node:fs";
 import path from "node:path";
 
 const STATE = "religion";
@@ -49,10 +49,10 @@ const capped = (items) =>
   items.length > LISTED ? [...items.slice(0, LISTED), `and ${items.length - LISTED} more in \`${STATE}/context/findings.md\``] : items;
 
 const blocking = capped(
-  [...findings.matchAll(/^### (F-\d+) \[(P[01])\] (open|fixed) - (.+)$/gim)].map((m) => `${m[1]} [${m[2]}] ${m[3]} - ${plain(m[4])}`)
+  [...findings.matchAll(/^### ((?:[\w-]+\/)?F-\d+) \[(P[01])\] (open|fixed) - (.+)$/gim)].map((m) => `${m[1]} [${m[2]}] ${m[3]} - ${plain(m[4])}`)
 );
 // Unconfirmed findings are the least trusted titles in the ledger, so only their identifiers.
-const unverifiedIds = [...findings.matchAll(/^### (F-\d+) \[(P[0-3])\] unverified - /gim)].map((m) => `${m[1]} [${m[2]}]`);
+const unverifiedIds = [...findings.matchAll(/^### ((?:[\w-]+\/)?F-\d+) \[(P[0-3])\] unverified - /gim)].map((m) => `${m[1]} [${m[2]}]`);
 const unverified = unverifiedIds.length > 10 ? [...unverifiedIds.slice(0, 10), `and ${unverifiedIds.length - 10} more`] : unverifiedIds;
 
 // The same stamp overview writes and status compares: the plans' SHA-256, first 16 characters.
@@ -62,6 +62,78 @@ const stale = stamp !== undefined && stamp !== plansHash;
 
 const notes = (inbox.match(/^- .+$/gm) ?? []).length;
 
+// Items active in the repository's other worktrees, found as status finds them: from git's own
+// worktree records, since this hook runs no subprocess. A spec there is written by whoever
+// works in that worktree, so what is copied from it is cleaned like a ledger title.
+const quiet = (fn) => {
+  try {
+    return fn();
+  } catch {
+    return null;
+  }
+};
+const gitDir = (dotgit) => {
+  const stat = quiet(() => statSync(dotgit));
+  if (!stat) return null;
+  if (stat.isDirectory()) return dotgit;
+  const target = quiet(() => readFileSync(dotgit, "utf8"))?.match(/^gitdir:\s*(.+)$/m)?.[1]?.trim();
+  return target ? path.resolve(path.dirname(dotgit), target) : null;
+};
+const headBranch = (git) => quiet(() => readFileSync(path.join(git, "HEAD"), "utf8"))?.match(/^ref:\s*refs\/heads\/(.+)$/m)?.[1]?.trim() ?? null;
+// Another worktree's branch decides what its spec is: a link could point at a device that never
+// ends, or at a file whose first heading would be copied in as a title. So it is opened without
+// following a link or blocking, checked through the open handle, and read up to a cap.
+const readPlain = (file, within) =>
+  quiet(() => {
+    // The folder is resolved so a linked directory cannot lead outside that worktree; the spec
+    // itself is not, so a spec that is a link is refused below.
+    const folder = realpathSync(path.dirname(file));
+    if (!(folder + path.sep).startsWith(within + path.sep)) return null;
+    const resolved = path.join(folder, path.basename(file));
+    const fd = openSync(resolved, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+    try {
+      const stat = fstatSync(fd);
+      if (!stat.isFile() || stat.size > 256 * 1024) return null;
+      // Windows has no O_NOFOLLOW: the name must still be a plain file, the one that was opened.
+      const named = lstatSync(resolved);
+      if (!named.isFile() || named.ino !== stat.ino || named.dev !== stat.dev) return null;
+      const buffer = Buffer.alloc(stat.size);
+      return buffer.subarray(0, readSync(fd, buffer, 0, stat.size, 0)).toString("utf8");
+    } finally {
+      closeSync(fd);
+    }
+  });
+const elsewhere = (() => {
+  const self = quiet(() => realpathSync(root));
+  let home = self;
+  let own = null;
+  while (home && !(own = gitDir(path.join(home, ".git")))) home = path.dirname(home) === home ? null : path.dirname(home);
+  if (!home || !own) return [];
+  const commondir = quiet(() => readFileSync(path.join(own, "commondir"), "utf8"));
+  const common = commondir ? path.resolve(own, commondir.trim()) : own;
+  const records = path.basename(common) === ".git" ? [{ dir: path.dirname(common), git: common }] : [];
+  for (const id of quiet(() => readdirSync(path.join(common, "worktrees"))) ?? []) {
+    const git = path.join(common, "worktrees", id);
+    const target = quiet(() => readFileSync(path.join(git, "gitdir"), "utf8"))?.trim();
+    // Git calls a record prunable once the `.git` file it points at is gone.
+    if (target && existsSync(path.resolve(git, target))) records.push({ dir: path.dirname(path.resolve(git, target)), git });
+  }
+  const offset = path.relative(home, self);
+  return records.flatMap(({ dir, git }) => {
+    const tree = quiet(() => realpathSync(dir));
+    if (!tree || tree === home) return [];
+    // 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 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.`];
+  });
+})();
+
 // Only names the status rule accepts reach this file, which every session loads: no free text
 // from a record any skill can write.
 let run = null;
@@ -97,6 +169,11 @@ if (active) {
   lines.push("Nothing in progress.", "");
 }
 
+if (elsewhere.length > 0) {
+  const more = elsewhere.length - LISTED;
+  lines.push("In flight in other worktrees:", "", ...elsewhere.slice(0, LISTED), ...(more > 0 ? [`- and ${more} more`] : []), "");
+}
+
 lines.push(
   `Plan: ${done} of ${done + open} item(s) complete.` + (nextItem ? ` Next up: ${nextItem}` : ""),
   ""

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

@@ -96,7 +96,7 @@ context; this does. Create it with a `# Findings` heading if it is missing.
 One block per finding. The header line is the machine-readable part and keeps this exact
 shape; the prose below it is for people.
 
-    ### F-03 [P0] open - Retained auth volumes carry the run label
+    ### 12/F-3 [P0] open - Retained auth volumes carry the run label
 
     **File:** ops/compose.yaml:86
     **Found:** 2026-09-04 by audit (scope: current; lens: security)
@@ -105,12 +105,18 @@ shape; the prose below it is for people.
     **Resolution:**
 
 When the pass is re-reviewing a repair and finds a new problem in the code that repair
-changed, add `**Surfaced by:** F-NN` after **Found**, naming the finding whose repair exposed
-it. That link is what keeps a defect a repair introduced attached to the repair.
-
-Identifiers are sequential within the ledger, one past the highest present, never reused
-and never renumbered while their entries live there. Completion archives resolved entries
-under a work-item prefix, and that prefixed form is the permanent reference.
+changed, add `**Surfaced by:** <identifier>` after **Found**, naming the finding whose repair
+exposed it, in full: `**Surfaced by:** 12/F-3`. That link is what keeps a defect a repair
+introduced attached to the repair.
+
+**Identifiers carry the item they were raised in.** While the active spec has a
+`**From build plan:** item <n>` line, a new finding is `<n>/F-<k>`: item 12's first is
+`12/F-1`, and `k` is one past the highest present with that prefix. Two items built in
+separate worktrees then never hand out the same identifier. With no active planned item, a
+finding is bare, `F-<k>`, one past the highest bare identifier present, as entries raised
+before prefixes are. Either way an identifier is never reused and never renumbered while its
+entry lives in the ledger. Completion archives resolved entries under the item's prefix, and
+that prefixed form is the permanent reference.
 
 | Status | Meaning | Blocks completion at P0/P1 |
 | --- | --- | --- |

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

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

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

@@ -0,0 +1,174 @@
+# Landing on top of what already landed
+
+Used before an item's branch is squash-merged or pushed, when the branch it lands in has moved
+since the item began: another item, built in its own worktree, landed first. Both items wrote
+the same state files, and a text merge of those conflicts every time, because each holds
+bookkeeping derived from its own branch. So the landed copy of each is taken, and this item's
+share of it is done again on top.
+
+The **target** is the branch the item lands in: the default branch, or an automated run's
+integration branch. Under `pull-request`, fetch it first, which is a network read and asks
+outside an automated run, and use the remote-tracking name, such as `origin/main`.
+
+The merge this makes is a commit on the item's own branch, like the work commit, and is covered
+by the same yes; it never writes the target.
+
+Run each block as **one** command, from the item's checkout, after the work commit. Each runs in
+a subshell and sets what it needs. A block that stops ends the landing: report what it printed
+and stop. A stop after block 1 leaves the merge open: either put right what the block named and
+run it again, or abandon the merge with the block in "Abandoning the merge" below.
+
+## 1. Bring in what landed
+
+    (
+      root=$(git rev-parse --show-toplevel) || exit 1
+      target='<the target>'
+      [ -z "$(git -C "$root" status --porcelain -- . ':!religion/context/handoff.md')" ] ||
+        { echo "uncommitted changes; make the work commit first"; exit 1; }
+      git -C "$root" checkout -q -- religion/context/handoff.md 2>/dev/null
+      git -C "$root" rev-parse -q --verify "$target^{commit}" >/dev/null || { echo "no such target: $target"; exit 1; }
+      if git -C "$root" merge-base --is-ancestor "$target" HEAD; then echo "nothing landed since"; exit 0; fi
+      git -C "$root" merge --no-commit --no-ff "$target"
+      git -C "$root" rev-parse -q --verify MERGE_HEAD >/dev/null || { echo "the merge did not start"; exit 1; }
+      base=$(git -C "$root" merge-base HEAD MERGE_HEAD)
+      for f in build-plan.md context/findings.md learning/journal.md context/project-overview.md context/handoff.md; do
+        p="religion/$f"
+        git -C "$root" diff --quiet "$base" MERGE_HEAD -- "$p" && continue
+        if git -C "$root" cat-file -e "MERGE_HEAD:$p" 2>/dev/null; then
+          git -C "$root" checkout MERGE_HEAD -- "$p" || exit 1
+          echo "taken as landed: $p"
+        else
+          git -C "$root" rm -q -f --ignore-unmatch -- "$p" || exit 1
+          echo "no longer tracked by the target: $p"
+        fi
+      done
+      left=$(git -C "$root" diff --name-only --diff-filter=U)
+      if [ -n "$left" ]; then
+        echo "conflicts outside the shared state files:"; echo "$left"
+        git -C "$root" merge --abort; exit 1
+      fi
+      echo "merged; redo this item's share of each file taken as landed"
+    )
+
+`nothing landed since` means the target is already part of the branch: skip the rest. Only a
+shared file the target changed since the item began is taken from it; one it left alone merges
+as usual, carrying this item's changes with nothing to redo. A shared file the target stopped
+tracking is removed, as the target has it; this item's copy is still in `HEAD`. The handoff is generated and rewritten at the end of every turn, so discarding it loses nothing.
+
+Taking the target's copy of a shared file resolves that file, conflicted or not. A conflict in
+any other file, product code included, is not this routine's to settle: the merge is abandoned,
+the branch is exactly as it was, and the paths are reported for review. Never resolve them by
+taking either side.
+
+While the merge is open, `HEAD` is this item's own work and `MERGE_HEAD` is what landed.
+
+## 2. Redo this item's share
+
+For each file block 1 took as landed, edit it as it now stands, taking this item's part from
+`HEAD`'s copy, as `git show HEAD:religion/<file>` prints it:
+
+| File | This item's share |
+| --- | --- |
+| `build-plan.md` | a feature ticks its line, and its parent once every sub-item is ticked; a rollback unticks its target and adds its note; a fix or refactor campaign has none |
+| `context/findings.md` | append each entry `HEAD`'s copy holds that the merge base's did not, still `open`, `fixed` or `unverified`, unchanged; one whose identifier the landed copy already holds, two fixes' bare `F-1` say, takes its permanent prefixed form, the archive's name before it as completion would archive it, and the rename is reported; when the landed copy is the stub, replace its placeholder line |
+| `learning/journal.md` | append its entry, the one whose `**Archive:**` line names this item's archive |
+| `context/project-overview.md` | none: left as landed, and stale until /overview runs, as after any completion |
+| `context/handoff.md` | none |
+
+Then compare `HEAD`'s ledger with the merge base's,
+`git diff $(git merge-base HEAD MERGE_HEAD) HEAD -- religion/context/findings.md`. A change this
+item made to an entry it did not add is not carried, since the landed copy is the one kept; name
+each such entry in the report so it can be made again by hand.
+
+Everything else, this item's archive included, merged as git merges it.
+
+## 3. Check, then commit the merge
+
+Stage the redone files for the merge commit, then check them:
+
+    (
+      root=$(git rev-parse --show-toplevel) || exit 1
+      for f in build-plan.md context/findings.md learning/journal.md context/project-overview.md context/handoff.md; do
+        [ -e "$root/religion/$f" ] && git -C "$root" ls-files --error-unmatch -- "religion/$f" >/dev/null 2>&1 &&
+          { git -C "$root" add -- "religion/$f" || exit 1; }
+      done
+      for f in build-plan.md context/findings.md learning/journal.md; do
+        ! grep -n -e '^<<<<<<< ' -e '^>>>>>>> ' -- "$root/religion/$f" 2>/dev/null || { echo "conflict markers in religion/$f"; exit 1; }
+      done
+      [ -z "$(git -C "$root" diff --name-only --diff-filter=U)" ] || { echo "unresolved paths remain"; exit 1; }
+      echo "ready for Verify"
+    )
+
+Only the files edited by hand are searched: git leaves no markers in a file it merged cleanly,
+and a document elsewhere may show one on purpose.
+
+Run the project's full `Verify` on the result: it is new code, made of both items, and neither
+was checked against the other. A turn that ends before the merge is committed has its handoff
+rewritten by the hook; run block 3 again before committing, which stages it only while the index
+still tracks it.
+
+When `Verify` passes, commit the merge with a message that says what was brought in, such as
+`merge: bring in what landed on main`.
+
+When it fails, abandon the merge with the block below, which returns the branch to its work
+commit, and stop with the failure. The item is complete on its branch but cannot land as it
+stands: the way forward is /fix here, describing the failure, built on this branch.
+Completing that fix lands both through this routine: block 2 then redoes the share of both, the
+item's and the fix's, every row, each taken from `HEAD`, and the `## Landed` record goes into
+both archives with the one range they share, each saying it is shared.
+
+## Abandoning the merge
+
+    (
+      set -o pipefail
+      root=$(git rev-parse --show-toplevel) || exit 1
+      git -C "$root" rev-parse -q --verify MERGE_HEAD >/dev/null || { echo "no merge open"; exit 0; }
+      g="$(git -C "$root" rev-parse --absolute-git-dir)/abandon"
+      list() { git -C "$root" -c core.quotePath=false "$@"; }
+      list ls-files -o | LC_ALL=C sort >| "$g.before" || exit 1
+      { list diff --name-only --no-renames HEAD && list diff --cached --name-only --no-renames HEAD; } >| "$g.tracked" || exit 1
+      git -C "$root" reset -q --hard HEAD; rc=$?
+      list ls-files -o | LC_ALL=C sort >| "$g.after" || exit 1
+      { cat "$g.tracked"; LC_ALL=C comm -23 "$g.before" "$g.after"; } | LC_ALL=C sort -u | sed 's/^/discarded: /'
+      rm -f "$g.before" "$g.after" "$g.tracked"
+      [ "$rc" -eq 0 ] || { echo "the reset failed: the merge is still open, and a path named above may not be set back"; exit 1; }
+      list ls-files -o --exclude-standard --directory | sed 's/^/left untracked: /'
+      echo "back at the work commit"
+    )
+
+Block 1 started from a clean tree, so the work commit is the whole of this item's work, and
+resetting to it ends the merge and returns the branch exactly as it was, whatever the merge left:
+redone shares, a handoff the hook rewrote, output `Verify` regenerated, paths still in conflict.
+Each path the reset set back or removed is named once: every tracked path whose working or staged copy
+differed from the work commit, an edit made by hand while the merge was open among them, and every untracked or
+ignored file in the way of a path the work commit has, such as one inside a directory the target
+put where a file was, found by listing them with git before the reset and after it. Other
+untracked files are left where they are and named, a whole directory as one line. Names are
+printed as git prints them, quoted where they hold unusual characters. So nothing is lost without
+a word. A reset that fails, such as on a directory it cannot write, still names what it removed,
+then says the merge is still open: put right what git named and run the block again. Never
+abandon with `git merge --abort` alone, which refuses while a file the merge touched has unstaged
+changes. With no merge open, the block does nothing.
+
+## 4. Record what landed
+
+When a merge was made, the item's `## Landed` record names the last such merge's second parent,
+the target it brought in, as **Base**, and that merge commit and anything after it as **Commits**:
+`git diff` from that base to the last commit is then this item's work alone, which is what a
+rollback reverses. Without a merge, the record is as `/complete` describes. Commit the
+record: in a worktree, an uncommitted file goes when the worktree is removed.
+
+## When the state directory is ignored
+
+Then none of these files are in git, and the merge carries none of them: this item's archive,
+plan tick, journal entry and ledger exist only in its worktree's copy of `religion/`. Before
+the worktree can be removed, redo this item's share, as the table in block 2 lists it, in the
+main checkout's own `religion/` files, and copy this item's archive there. When this landing
+follows a failed `Verify`, that is the share and the archive of both, the item's and the fix's. With no `HEAD` copy
+or merge base in git, the worktree's own files are this item's part, and the ledger saved when
+the worktree was made, `religion/.state/findings-at-start.md` in it, is the base: an entry the
+worktree's ledger holds that the saved one did not is this item's. Comparing the two also shows
+each entry this item changed or removed, a repair it closed and pruned among them: make the
+same change in the main checkout's ledger, or name the entry in the report, so a finding this
+item closed does not stay open there. Removing the worktree deletes ignored files with it, so
+until then they are the only record.

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

@@ -56,7 +56,8 @@ finding, already repaired, is an incident.
 
 For each group that earns it, propose the coding-standard rule that would have prevented every
 finding in it, in the standards' own voice, as an instruction for work not yet started, with the
-findings cited by identifier. A rule that only restates one finding is not a standard. Skip a
+findings cited by their archived identifier, prefix included, such as `39a/F-2` or `27/F-161`.
+A rule that only restates one finding is not a standard. Skip a
 group already recorded in `religion/learning/journal-archive.md` unless it has grown since.
 
 ## Step 3 - route by kind

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

@@ -65,7 +65,10 @@ plan top to bottom and take the first unchecked leaf that waits on nothing: an i
 those is unticked, or says `spike first` and no archive under `religion/history/spikes/` records
 `**For:** item N` with `**Settled:** yes`. Wording inside a code span does not count.
 Name each item passed over and what it waits on, and point a spike-first one at
-/spike. State which item you are spec'ing before going further.
+/spike. An item another worktree is already building is passed over too: one that
+`religion status --json` lists under `inFlight` with `here` false, or, without the `religion`
+command, one the handoff lists as in flight in another worktree. Name it with its branch.
+State which item you are spec'ing before going further.
 
 Asked by number for an item that waits, say what it waits on and stop: speccing it now
 builds on an answer nobody has yet. A reference to an item the plan does not have, or items

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

@@ -14,8 +14,9 @@ numbered, it ticks nothing, and it archives on its own.
 - **A description** - `/fix "password reset email never sends"`. A problem stated in the
   conversation already counts; this skill does not scan the project hoping to find
   something wrong.
-- **Finding identifiers** - `/fix F-03` specs the repair of that ledger entry, and
-  `/fix F-03 F-07` repairs several together. Group findings only when they share a file
+- **Finding identifiers** - `/fix 39a/F-2` specs the repair of that ledger entry, and
+  `/fix 39a/F-2 F-07` repairs several together. An identifier is used exactly as the
+  ledger heads it, with an item prefix when it has one, bare when it does not. Group findings only when they share a file
   and a severity, as /auto's fix mode does: one fix then stays one reviewable diff.
 
 - **An issue** - `/fix #42` or its link. Read it through the host's own command-line tool, for example `gh issue view 42 --json title,body,url` on

package/template/.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,17 @@ 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 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.
+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.
 
@@ -154,16 +169,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,
@@ -180,7 +209,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,116 @@
+# 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.
+
+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, 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>'
+      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
+      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
+      mkdir -p "$tree/religion/context" && cp -p "$root/$spec" "$tree/$spec" && cmp -s "$root/$spec" "$tree/$spec" || exit 1
+      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.