create-religion 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # create-religion
 
+## 1.5.0
+
+### Minor Changes
+
+- 419f78b: A finding raised while a planned item is active is now headed with the item's number, such as
+  `39a/F-1`, so items built side by side cannot hand out the same identifier. `religion status`,
+  the handoff and the dashboard read prefixed and bare identifiers alike, so existing ledgers keep
+  working, and the dashboard orders findings by their place in the ledger.
+- 9d0c8ba: `religion status --json` gains `inFlight`, the work items active in any worktree of the
+  repository, each with its worktree, branch, plan item, title, step counts and whether it is the
+  one the command ran in. `religion status` lists items in flight elsewhere and passes over a plan
+  item another worktree is building, and the handoff lists them too. Worktrees are read from git's
+  own files, so nothing runs git, and a spec in another worktree is read only when it is a plain
+  file inside that worktree.
+- 76e2f5b: With items built in their own worktrees, `complete` now lands each one on top of whatever
+  landed first: it merges the target without committing, takes the landed copy of the build plan,
+  findings ledger, journal, overview and handoff, redoes the item's own tick, findings and journal
+  entry, stops on any other conflict, and runs `Verify` again before committing the merge. A merge
+  given up half way resets to the item's work commit and names everything it discarded.
+- 4727989: A new setting, `workflow.parallelItems`, off by default, has `implement` start each planned
+  feature in its own git worktree beside the project, on the item's branch, moving the spec there
+  so the main checkout can spec the next item. `religion doctor` refuses the setting under
+  `git.mode: trunk`, and inside a linked worktree names the main checkout and says where to copy a
+  missing `.claude/settings.json` from.
+
 ## 1.4.0
 
 ### Minor Changes

package/dist/lib/dashboard.js

@@ -757,7 +757,8 @@ button.chip { font-family: inherit; cursor: pointer; }
   }
 
   const STATUS_ORDER = ["open", "fixed", "unverified", "accepted", "closed", "invalid"];
-  const idNumber = (f) => Number(String(f.id).slice(2)) || 0;
+  // The ledger only appends, so a finding's place in it is its age; identifiers restart per item prefix.
+  const age = (f) => data.findings.indexOf(f);
   const pill = (status) => "<span class='status " + (["open", "fixed", "closed"].indexOf(status) >= 0 ? status : "unverified") + "'>" + esc(status) + "</span>";
   const stacked = (parts, max) => "<span class='track'>" + parts.map((p) => "<i style='width:" + share(p[0], max) + "%;background:var(--sev-" + p[1].toLowerCase() + ")'></i>").join("") + "</span>";
 
@@ -822,7 +823,7 @@ button.chip { font-family: inherit; cursor: pointer; }
     const shown = all
       .filter((f) => (ui.status === "all" ? true : ui.status === "unresolved" ? UNRESOLVED.indexOf(f.status) >= 0 : f.status === ui.status))
       .filter((f) => !ui.severity || f.severity === ui.severity)
-      .sort((a, b) => a.severity.localeCompare(b.severity) || STATUS_ORDER.indexOf(a.status) - STATUS_ORDER.indexOf(b.status) || idNumber(a) - idNumber(b));
+      .sort((a, b) => a.severity.localeCompare(b.severity) || STATUS_ORDER.indexOf(a.status) - STATUS_ORDER.indexOf(b.status) || age(a) - age(b));
     const picked = shown.find((f) => f.id === ui.finding) || shown[0] || null;
     $("fd-table").innerHTML = shown.length
       ? "<table class='rows'><tr><th>ID</th><th>Sev</th><th>Finding</th><th>Status</th><th>File</th><th>Lens</th></tr>" +
@@ -999,7 +1000,7 @@ button.chip { font-family: inherit; cursor: pointer; }
     const count = (severity, status) => data.findings.filter((f) => f.severity === severity && (!status || f.status === status)).length;
     const max = Math.max(1, ...SEVERITIES.flatMap((s) => columns.map((c) => count(s, c))));
     const blocking = data.status.findings.blocking.length;
-    const oldest = pending.slice().sort((a, b) => idNumber(a) - idNumber(b)).slice(0, 3);
+    const oldest = pending.slice().sort((a, b) => age(a) - age(b)).slice(0, 3);
     return "<table><tr><th>Severity</th><th>Open</th><th>Fixed</th><th>Unverified</th><th>Total</th></tr>" +
       SEVERITIES.map((s) =>
         "<tr><td><span class='sev " + s.toLowerCase() + "'>" + s + "</span></td>" + columns.map((c) => "<td class='" + heat(count(s, c), max) + "'>" + count(s, c) + "</td>").join("") +

package/dist/lib/doctor.js

@@ -9,7 +9,7 @@ import path from "node:path";
 import { exists, readIfPresent, SKILL_TREES, STATE_DIR, statePath } from "./paths.js";
 import { editedSinceInstall, isPlainFile } from "./install.js";
 import { SETTINGS, settingProblems } from "./settings.js";
-import { readProjectState } from "./state.js";
+import { listWorktrees, readProjectState } from "./state.js";
 const REQUIRED = [
     "config.json",
     "project-plan.md",
@@ -50,6 +50,10 @@ export async function runDoctor(root, changes) {
     }
     else {
         const bad = settingProblems(state.config);
+        const config = (state.config ?? {});
+        if (bad.length === 0 && config.workflow?.parallelItems === true && (config.git?.mode ?? "trunk") === "trunk") {
+            bad.push("workflow.parallelItems needs a branch per item, which git.mode trunk never makes");
+        }
         results.push({
             name: "configuration",
             ok: bad.length === 0,
@@ -121,14 +125,20 @@ export async function runDoctor(root, changes) {
         detail: ignored ? "state is local only" : "state is committed",
         blocks: "nothing"
     });
+    const worktrees = await listWorktrees(root);
+    const linkedTo = worktrees?.main && worktrees.main !== worktrees.home ? worktrees.main : null;
     results.push({
         name: "git",
         ok: await exists(path.join(root, ".git")),
-        detail: (await exists(path.join(root, ".git"))) ? "repository present" : "not a git repository",
+        detail: !(await exists(path.join(root, ".git")))
+            ? "not a git repository"
+            : linkedTo
+                ? `linked worktree of ${linkedTo}`
+                : "repository present",
         blocks: "completion"
     });
     results.push(managedFilesCheck(changes === undefined ? await editedSinceInstall(root) : changes));
-    results.push(await readHooks(root));
+    results.push(await readHooks(root, linkedTo));
     return results;
 }
 const SETTINGS_FILE = ".claude/settings.json";
@@ -143,7 +153,7 @@ export const HOOKS = [
     { event: "PostToolUse", command: "node .claude/hooks/scan-untrusted-input.mjs" },
     { event: "PreToolUse", command: "node .claude/hooks/warn-on-drift.mjs" }
 ];
-async function readHooks(root) {
+async function readHooks(root, mainCheckout) {
     const files = new Set();
     for (const { command } of HOOKS) {
         const file = hookFile(command);
@@ -156,7 +166,8 @@ async function readHooks(root) {
         wanted: HOOKS,
         settings: await readSettings(root, SETTINGS_FILE),
         local: await readSettings(root, LOCAL_SETTINGS_FILE),
-        files
+        files,
+        mainCheckout
     });
 }
 /** A settings file's text, read only when it is a plain file reached without a link. */
@@ -221,8 +232,11 @@ export function hooksCheck(input) {
     if (input.settings === "not-file")
         return result(false, `${SETTINGS_FILE} is not a regular file`);
     const local = typeof input.local === "string" && input.local !== "link" && input.local !== "not-file" ? input.local : null;
-    if (input.settings === null && local === null)
-        return result(false, `${SETTINGS_FILE} is missing; a fresh install writes it`);
+    if (input.settings === null && local === null) {
+        return result(false, input.mainCheckout
+            ? `${SETTINGS_FILE} is missing in this linked worktree; copy the main checkout's from ${input.mainCheckout}`
+            : `${SETTINGS_FILE} is missing; a fresh install writes it`);
+    }
     const shared = input.settings === null ? [] : parseHooks(input.settings);
     if (shared === null)
         return result(false, `${SETTINGS_FILE} does not parse`);

package/dist/lib/settings.js

@@ -16,6 +16,10 @@ export const SETTINGS = {
         kind: "boolean", default: false,
         summary: "Whether steps a spec marks as independent build together as one reviewed wave."
     },
+    "workflow.parallelItems": {
+        kind: "boolean", default: false,
+        summary: "Whether implement starts each planned item in its own git worktree beside the project."
+    },
     "git.mode": {
         kind: "enum", values: ["trunk", "branch-per-item", "pull-request"], default: "trunk",
         summary: "Where work lands: the branch you are on, a branch merged per item, or a pull request per item."

package/dist/lib/state.js

@@ -7,6 +7,7 @@
  */
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
+import path from "node:path";
 import { installedSkills, readIfPresent, statePath } from "./paths.js";
 /** Item numbers a spike archive says it answered and settled, from `**For:** item N` and `**Settled:** yes`. */
 export function parseSettledSpike(source) {
@@ -425,7 +426,8 @@ export function parseFindings(source) {
         return [];
     const entries = source.split(/^(?=###\s)/m);
     return entries.flatMap((entry) => {
-        const m = /^###\s+(F-\d+)\s+\[(P[0-3])\]\s+(\w+)\s+-\s+(.+)$/im.exec(entry);
+        // A finding raised during a planned item carries the item's prefix, `39a/F-1`; older ones are bare.
+        const m = /^###\s+((?:[\w-]+\/)?F-\d+)\s+\[(P[0-3])\]\s+(\w+)\s+-\s+(.+)$/im.exec(entry);
         if (!m)
             return [];
         // A finding raised while building has no lens: "2026-09-26 while writing the guide".
@@ -462,6 +464,126 @@ export function parseOpenQuestions(overview) {
         return [];
     return [...section[1].matchAll(/^-\s+\*\*(.+?)\*\*/gim)].map((m) => (m[1] ?? "").trim());
 }
+function headBranch(head) {
+    return /^ref:\s*refs\/heads\/(.+)$/m.exec(head ?? "")?.[1]?.trim() ?? null;
+}
+/** The git directory a `.git` entry stands for: itself, or where its `gitdir:` line points. */
+async function gitDir(dotgit) {
+    const stat = await fs.stat(dotgit).catch(() => null);
+    if (!stat)
+        return null;
+    if (stat.isDirectory())
+        return dotgit;
+    const target = /^gitdir:\s*(.+)$/m.exec((await readIfPresent(dotgit)) ?? "")?.[1]?.trim();
+    return target ? path.resolve(path.dirname(dotgit), target) : null;
+}
+/**
+ * The repository's worktrees, the one holding `root` and the main checkout, read from git's own records under
+ * `worktrees/` rather than by running git, which shipped code may not do. A worktree whose
+ * directory is gone is left out, and so is the main entry of a bare repository. Null outside
+ * a repository.
+ */
+export async function listWorktrees(root) {
+    let home = await fs.realpath(root).catch(() => null);
+    let own = null;
+    while (home && !(own = await gitDir(path.join(home, ".git")))) {
+        const up = path.dirname(home);
+        home = up === home ? null : up;
+    }
+    if (!home || !own)
+        return null;
+    const commondir = await readIfPresent(path.join(own, "commondir"));
+    const common = commondir ? path.resolve(own, commondir.trim()) : own;
+    const records = [{ dir: path.basename(common) === ".git" ? path.dirname(common) : null, git: common }];
+    for (const id of await fs.readdir(path.join(common, "worktrees")).catch(() => [])) {
+        const git = path.join(common, "worktrees", id);
+        const target = (await readIfPresent(path.join(git, "gitdir")))?.trim();
+        // Git calls a record prunable once the `.git` file it points at is gone.
+        const dotgit = target ? path.resolve(git, target) : null;
+        if (dotgit && (await fs.stat(dotgit).catch(() => null)))
+            records.push({ dir: path.dirname(dotgit), git });
+    }
+    const trees = [];
+    for (const { dir, git } of records) {
+        const resolved = dir ? await fs.realpath(dir).catch(() => null) : null;
+        if (resolved)
+            trees.push({ path: resolved, branch: headBranch(await readIfPresent(path.join(git, "HEAD"))) });
+    }
+    if (!trees.some((t) => t.path === home))
+        trees.unshift({ path: home, branch: headBranch(await readIfPresent(path.join(own, "HEAD"))) });
+    const main = records[0].dir ? await fs.realpath(records[0].dir).catch(() => null) : null;
+    return { home, main, trees };
+}
+/** Far above any real spec; a larger file in another worktree is not read. */
+const SPEC_MAX = 256 * 1024;
+/**
+ * A file another worktree's branch controls: a link could point at a device that never ends,
+ * or at a file whose first heading would be reported as a title. So it is opened without
+ * following a link or blocking, checked through the open handle, and read up to the cap.
+ */
+async function readPlain(file, within) {
+    // 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 = await fs.realpath(path.dirname(file)).catch(() => null);
+    if (!folder || !(folder + path.sep).startsWith(within + path.sep))
+        return null;
+    const resolved = path.join(folder, path.basename(file));
+    const flags = fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0);
+    const handle = await fs.open(resolved, flags).catch(() => null);
+    if (!handle)
+        return null;
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.size > SPEC_MAX)
+            return null;
+        // Windows has no O_NOFOLLOW: the name must still be a plain file, the one that was opened.
+        const named = await fs.lstat(resolved);
+        if (!named.isFile() || named.ino !== stat.ino || named.dev !== stat.dev)
+            return null;
+        const buffer = Buffer.alloc(stat.size);
+        const { bytesRead } = await handle.read(buffer, 0, stat.size, 0);
+        return buffer.subarray(0, bytesRead).toString("utf8");
+    }
+    catch {
+        return null;
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
+/** Active specs across the repository's worktrees; empty outside a repository. */
+export async function readInFlight(root) {
+    const listed = await listWorktrees(root);
+    const self = await fs.realpath(root).catch(() => null);
+    if (!listed || !self)
+        return [];
+    // Religion may live below the repository's top, so each spec sits at the same offset in its worktree.
+    const offset = path.relative(listed.home, self);
+    const found = [];
+    for (const { path: worktree, branch } of listed.trees) {
+        // A wave's step worktree holds a copy of its parent item's spec, not an item of its own.
+        if (/^step-\d+$/.test(path.basename(worktree)) && (await readIfPresent(path.join(path.dirname(worktree), "base"))) !== null)
+            continue;
+        const spec = statePath(path.join(worktree, offset), "context", "current-work.md");
+        // This worktree's spec is read as `work` reads it; another's comes from someone else's branch.
+        const source = worktree === listed.home ? await readIfPresent(spec) : await readPlain(spec, worktree);
+        const work = parseWork(source);
+        if (!source || !work.active)
+            continue;
+        const plan = field(source, "From build plan");
+        found.push({
+            worktree,
+            branch,
+            // Plan numbers are compared lowercased, as the build plan's parser stores them.
+            item: plan ? /^item\s+([0-9a-z]+)/i.exec(plan)?.[1]?.toLowerCase() ?? null : null,
+            title: work.title,
+            stepsDone: work.stepsDone,
+            stepsTotal: work.stepsTotal,
+            here: worktree === listed.home
+        });
+    }
+    return found;
+}
 /** The stamp the overview carries, and the hash the current plans produce. */
 export function overviewHash(projectPlan, buildPlan) {
     return crypto.createHash("sha256").update(projectPlan).update(buildPlan).digest("hex").slice(0, 16);
@@ -522,6 +644,7 @@ export async function readProjectState(root) {
         inbox: parseInbox(inbox),
         learning: { lessons: parseLessons(lessons), journal: entries, undecided: entries.filter((e) => !e.decided).length },
         settledSpikes,
-        spec: specState(work)
+        spec: specState(work),
+        inFlight: await readInFlight(root)
     };
 }

package/dist/lib/status.js

@@ -12,8 +12,13 @@ export function computeStatus(state) {
     const done = leaves.filter((i) => i.done).length;
     const { waits, problems } = waiting(state.plan, new Set(state.settledSpikes));
     const waitsOn = (item) => (item.number ? waits.get(item.number) : undefined);
-    const nextItem = leaves.find((i) => !i.done && !waitsOn(i)) ?? null;
-    const passedOver = leaves.slice(0, nextItem ? leaves.indexOf(nextItem) : leaves.length).filter((i) => !i.done && waitsOn(i));
+    // An item another worktree is building is not this checkout's to start.
+    const elsewhere = new Map(state.inFlight.filter((i) => !i.here && i.item).map((i) => [i.item, i.branch ?? i.worktree]));
+    const busy = (item) => !!item.number && elsewhere.has(item.number);
+    const nextItem = leaves.find((i) => !i.done && !waitsOn(i) && !busy(i)) ?? null;
+    const before = leaves.slice(0, nextItem ? leaves.indexOf(nextItem) : leaves.length).filter((i) => !i.done);
+    const passedOver = before.filter((i) => waitsOn(i));
+    const building = before.filter((i) => !waitsOn(i) && busy(i));
     const byStatus = {};
     for (const finding of state.findings) {
         byStatus[finding.status] = (byStatus[finding.status] ?? 0) + 1;
@@ -26,6 +31,10 @@ export function computeStatus(state) {
         const named = passedOver.map((i) => `${i.number} (${waitsOn(i).join(", ")})`);
         warnings.push(`passed over plan items that are waiting: ${named.join("; ")}`);
     }
+    if (building.length > 0) {
+        const named = building.map((i) => `${i.number} (${elsewhere.get(i.number)})`);
+        warnings.push(`passed over plan items in flight in another worktree: ${named.join("; ")}`);
+    }
     warnings.push(...problems.map((p) => `the build plan: ${p}`));
     if (!state.configValid)
         warnings.push("config.json does not parse; workflow commands will stop rather than guess");
@@ -46,7 +55,7 @@ export function computeStatus(state) {
     }
     return {
         schemaVersion: 1,
-        next: nextAction(state, nextItem?.title ?? null, blocking.length > 0, leaves.filter((i) => !i.done && waitsOn(i)), waitsOn),
+        next: nextAction(state, nextItem?.title ?? null, blocking.length > 0, leaves.filter((i) => !i.done && waitsOn(i)), waitsOn, building.length > 0),
         plan: { done, total: leaves.length, nextItem: nextItem?.title ?? null },
         work: state.work,
         findings: { total: state.findings.length, blocking, byStatus },
@@ -54,10 +63,11 @@ export function computeStatus(state) {
         activity: state.activity,
         inbox: { notes: state.inbox.length },
         spec: state.spec,
+        inFlight: state.inFlight,
         warnings
     };
 }
-function nextAction(state, nextItem, blocked, waitingLeaves, waitsOn) {
+function nextAction(state, nextItem, blocked, waitingLeaves, waitsOn, building) {
     if (!state.configValid)
         return { command: "doctor", because: "configuration cannot be parsed" };
     if (!state.overviewPresent)
@@ -82,6 +92,9 @@ function nextAction(state, nextItem, blocked, waitingLeaves, waitsOn) {
         return { command: "feature", because: `next in the plan: ${nextItem}` };
     if (state.plan.length === 0)
         return { command: "overview", because: "the build plan has no items yet" };
+    if (building && waitingLeaves.length === 0) {
+        return { command: "implement", because: "every remaining item is in flight in another worktree; continue one there" };
+    }
     if (waitingLeaves.length > 0) {
         const onSpike = waitingLeaves.find((i) => waitsOn(i).includes("a spike"));
         return onSpike
@@ -98,6 +111,10 @@ export function renderStatus(status, cmd = "/") {
         ? `Active:   ${status.work.title ?? "untitled"} - step ${status.work.stepsDone}/${status.work.stepsTotal}` +
             (status.work.status ? ` (${status.work.status})` : "")
         : "Active:   nothing in progress");
+    for (const item of status.inFlight.filter((i) => !i.here)) {
+        out.push(`In flight: ${item.item ? `item ${item.item} ` : ""}${item.title ?? "untitled"} - step ${item.stepsDone}/${item.stepsTotal}` +
+            ` on ${item.branch ?? item.worktree}`);
+    }
     out.push(`Plan:     ${status.plan.done}/${status.plan.total} complete (${pct}%)`);
     const run = status.activity;
     out.push(run.recorded

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-religion",
-  "version": "1.4.0",
+  "version": "1.5.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/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/.agents/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/.agents/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.