create-religion 1.3.0 → 1.5.0

package/CHANGELOG.md

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

package/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.3.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,