create-religion 0.2.0 → 0.4.0

package/dist/bin/religion.js

@@ -86,16 +86,33 @@ async function runInstall(options) {
         create: plan.filter((p) => p.action === "create").length,
         update: plan.filter((p) => p.action === "update").length,
         conflict: plan.filter((p) => p.action === "conflict").length,
-        kept: plan.filter((p) => p.action === "seed-skip").length
+        kept: plan.filter((p) => p.action === "seed-skip").length,
+        merge: plan.filter((p) => p.action === "merge").length,
+        remerge: plan.filter((p) => p.action === "remerge").length
     };
     console.log(`\nAdapters: ${adapters.map((a) => ADAPTERS[a].label).join(", ")}`);
     console.log(`  create   ${counts.create}`);
     console.log(`  update   ${counts.update}`);
     console.log(`  keep     ${counts.kept}  (your files, never overwritten)`);
     console.log(`  conflict ${counts.conflict}`);
+    if (counts.merge > 0)
+        console.log(`  merge    ${counts.merge}  (your file, awaiting a decision)`);
+    if (counts.remerge > 0)
+        console.log(`  merged   ${counts.remerge}  (your sections kept)`);
     for (const entry of plan.filter((p) => p.action === "conflict")) {
         console.log(`    ${entry.relative}`);
     }
+    const mergeable = plan.filter((p) => p.action === "merge").map((p) => p.relative);
+    let merge = false;
+    if (mergeable.length > 0) {
+        console.log(`\nThese already exist and were written by you:`);
+        for (const relative of mergeable)
+            console.log(`    ${relative}`);
+        console.log("\nReligion can append its own sections to them inside markers, keeping everything" +
+            "\nyou wrote exactly where it is. Later updates then replace only what is between" +
+            "\nthose markers. The originals are backed up either way.");
+        merge = await confirmMerge(options.yes);
+    }
     if (options.dryRun) {
         console.log("\nDry run. Nothing written.");
         return;
@@ -103,9 +120,12 @@ async function runInstall(options) {
     if (plan.length === 0) {
         throw new Error(`No template files found under ${templateRoot}. Nothing would be installed, which is never correct.`);
     }
-    const result = await applyInstall(templateRoot, target, plan, { force: options.force });
+    const result = await applyInstall(templateRoot, target, plan, { force: options.force, merge });
     await writeManifest(target, await version(), adapters, templateRoot, previous, result.conflicts);
     console.log(`\nWrote ${result.written.length} file(s).`);
+    if (result.merged.length > 0) {
+        console.log(`Merged ${result.merged.length} entry file(s), keeping what you wrote.`);
+    }
     if (result.backups.length > 0)
         console.log(`Backed up ${result.backups.length} conflicting file(s).`);
     if (result.conflicts.length > 0) {
@@ -126,6 +146,21 @@ async function runInstall(options) {
         console.log("\nNext: run the setup skill in your AI tool, then fill in the two plans.");
     }
 }
+/**
+ * Ask before rewriting a file the user wrote.
+ *
+ * Defaults to yes because the merge is additive and reversible: nothing of theirs moves and
+ * the original is backed up first. Declining leaves the file untouched and reported as a
+ * conflict, which is the old behaviour.
+ */
+async function confirmMerge(assumeYes) {
+    if (assumeYes || !process.stdin.isTTY)
+        return assumeYes;
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = (await rl.question("\nMerge them? [Y/n] ")).trim().toLowerCase();
+    rl.close();
+    return answer === "" || answer === "y" || answer === "yes";
+}
 async function chooseAdapters(assumeYes) {
     const all = Object.keys(ADAPTERS);
     if (assumeYes || !process.stdin.isTTY)

package/dist/lib/doctor.js

@@ -14,17 +14,21 @@ const REQUIRED = [
     "build-plan.md",
     "context/project-overview.md",
     "context/coding-standards.md",
+    "context/untrusted-input.md",
     "context/ai-interaction.md",
     "context/current-work.md",
     "context/findings.md",
+    "context/inbox.md",
     "history/features",
     "history/fixes",
     "history/rollbacks",
+    "history/refactors",
+    "history/spikes",
     "reference"
 ];
 const ALLOWED = {
     "workflow.stepReview": ["every", "item"],
-    "git.mode": ["trunk", "branch-per-item"],
+    "git.mode": ["trunk", "branch-per-item", "pull-request"],
     "git.checkpoints": ["none", "every-step", "squash"],
     "verification.logicTests": ["when-configured", "required"],
     "verification.uiEvidence": ["when-available", "required"],

package/dist/lib/install.js

@@ -10,6 +10,7 @@ import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { exists, STATE_DIR } from "./paths.js";
+import { hasDamagedMarkers, hasMarkers, replaceManagedBlock, spliceEntry } from "./merge.js";
 export const ADAPTERS = {
     claude: { label: "Claude Code", trees: [".claude/skills", ".claude/hooks"], entry: ["CLAUDE.md"] },
     codex: { label: "Codex", trees: [".agents/skills"], entry: ["AGENTS.md"] },
@@ -24,8 +25,13 @@ export function hash(contents) {
 export function isManaged(relative) {
     return !relative.startsWith(`${STATE_DIR}/`);
 }
+/** The entry files for the chosen adapters, which are the only files merging applies to. */
+function entryFiles(adapters) {
+    return new Set(adapters.flatMap((a) => ADAPTERS[a].entry));
+}
 export async function planInstall(templateRoot, target, adapters, previous) {
     const wanted = wantedPaths(adapters);
+    const entries = entryFiles(adapters);
     const plan = [];
     for (const relative of await walk(templateRoot)) {
         if (!wanted(relative))
@@ -50,7 +56,22 @@ export async function planInstall(templateRoot, target, adapters, previous) {
         // installed. Anything else is a local edit, and overwriting it silently is the failure
         // this manifest exists to prevent.
         const recorded = previous?.managed[relative];
-        plan.push({ relative, action: recorded && recorded === hash(current) ? "update" : "conflict" });
+        if (recorded && recorded === hash(current)) {
+            plan.push({ relative, action: "update" });
+            continue;
+        }
+        // An entry file is the one place where "differs from the template" is the normal case
+        // rather than a problem: a repository that already tells agents how to work has one, and
+        // it is usually the most carefully written file in the project.
+        if (entries.has(relative)) {
+            const text = current.toString("utf8");
+            // A damaged marker pair is a conflict, never a fresh merge: splicing a second block
+            // into a file that already has one is worse than the damage.
+            const action = hasMarkers(text) ? "remerge" : hasDamagedMarkers(text) ? "conflict" : "merge";
+            plan.push({ relative, action });
+            continue;
+        }
+        plan.push({ relative, action: "conflict" });
     }
     return plan;
 }
@@ -58,6 +79,7 @@ export async function applyInstall(templateRoot, target, plan, options) {
     const written = [];
     const conflicts = [];
     const backups = [];
+    const merged = [];
     for (const entry of plan) {
         if (entry.action === "unchanged" || entry.action === "seed-skip")
             continue;
@@ -65,6 +87,33 @@ export async function applyInstall(templateRoot, target, plan, options) {
             conflicts.push(entry.relative);
             continue;
         }
+        // Replacing only what is between the markers is the whole point of having merged: the
+        // user's own prose sits outside them and is never read, let alone rewritten.
+        if (entry.action === "remerge" || (entry.action === "merge" && options.merge)) {
+            const destination = path.join(target, entry.relative);
+            const template = await fs.readFile(path.join(templateRoot, entry.relative), "utf8");
+            const current = await fs.readFile(destination, "utf8");
+            if (entry.action === "merge") {
+                const backup = path.join(target, STATE_DIR, ".state", "backups", entry.relative);
+                await fs.mkdir(path.dirname(backup), { recursive: true });
+                await fs.copyFile(destination, backup);
+                backups.push(entry.relative);
+            }
+            const next = entry.action === "merge" ? spliceEntry(current, template) : replaceManagedBlock(current, template);
+            if (next === null) {
+                // Markers went missing between planning and writing, or were edited into an order
+                // this cannot reason about. Leaving it alone is the only safe answer.
+                conflicts.push(entry.relative);
+                continue;
+            }
+            await fs.writeFile(destination, next, "utf8");
+            merged.push(entry.relative);
+            continue;
+        }
+        if (entry.action === "merge") {
+            conflicts.push(entry.relative);
+            continue;
+        }
         const destination = path.join(target, entry.relative);
         if (entry.action === "conflict") {
             const backup = path.join(target, STATE_DIR, ".state", "backups", entry.relative);
@@ -76,7 +125,7 @@ export async function applyInstall(templateRoot, target, plan, options) {
         await fs.copyFile(path.join(templateRoot, entry.relative), destination);
         written.push(entry.relative);
     }
-    return { written, conflicts, backups };
+    return { written, conflicts, backups, merged };
 }
 /**
  * Records what was *installed*, not what is currently on disk.

package/dist/lib/merge.js

@@ -0,0 +1,119 @@
+/**
+ * Merging Religion's entry-file sections into a file the project already had.
+ *
+ * A repository that already carries agent instructions is the normal case, not the odd one,
+ * and the previous behaviour left those installs with the workflow on disk but nothing
+ * telling the agent it existed. Overwriting was never an option: those files are often the
+ * most carefully written thing in the repository.
+ *
+ * So the user's file stays exactly where it is and Religion's sections are appended inside
+ * markers. The markers are what make the result maintainable rather than a one-time paste:
+ * a later update replaces what is between them and never reads what is outside.
+ *
+ * Two sections are deliberately left outside the block. "What this is" is what the user's own
+ * file already says, and Commands is filled in by the setup skill with the project's real
+ * commands. Both would be destroyed by an update that replaced them.
+ */
+export const MANAGED_START = "<!-- religion:managed:start -->";
+export const MANAGED_END = "<!-- religion:managed:end -->";
+/** Sections the user owns. They never enter the managed block. */
+const USER_OWNED = new Set(["What this is", "Commands"]);
+const BLOCK_NOTE = "Everything between these markers is generated by Religion and replaced on update.\n" +
+    "Edit the files it points at, or the sections outside this block, rather than editing here.";
+/** Split a rendered entry file into its leading lines and its `## ` sections. */
+function parse(entry) {
+    const lines = entry.split(/\r?\n/);
+    const lead = [];
+    const sections = [];
+    let current = null;
+    for (const line of lines) {
+        const heading = /^## (.+)$/.exec(line);
+        if (heading?.[1]) {
+            current = { heading: heading[1].trim(), body: "" };
+            sections.push(current);
+            continue;
+        }
+        if (current)
+            current.body += line + "\n";
+        else
+            lead.push(line);
+    }
+    return { lead, sections };
+}
+function render(sections) {
+    return sections.map((s) => `## ${s.heading}\n${s.body.replace(/\n+$/, "")}\n`).join("\n");
+}
+/**
+ * The part of a rendered entry file that Religion owns.
+ *
+ * Includes the import lines, which is what makes a merged install keep receiving new context
+ * files: leaving them outside the block would freeze the set of loaded files at whatever
+ * shipped on the day of the merge.
+ */
+export function managedBlock(templateEntry) {
+    const { lead, sections } = parse(templateEntry);
+    const imports = lead.filter((line) => line.startsWith("@")).join("\n");
+    const owned = sections.filter((s) => !USER_OWNED.has(s.heading));
+    return [
+        MANAGED_START,
+        "",
+        BLOCK_NOTE,
+        "",
+        ...(imports ? [imports, ""] : []),
+        render(owned).replace(/\n+$/, ""),
+        "",
+        MANAGED_END
+    ].join("\n");
+}
+/** The sections the user owns, taken from the template as a starting point. */
+export function userOwnedSections(templateEntry) {
+    const { sections } = parse(templateEntry);
+    const owned = sections.filter((s) => USER_OWNED.has(s.heading) && s.heading !== "What this is");
+    return render(owned).replace(/\n+$/, "");
+}
+export function hasMarkers(contents) {
+    return contents.includes(MANAGED_START) && contents.includes(MANAGED_END);
+}
+/**
+ * A file carrying one marker but not both, or them in the wrong order.
+ *
+ * This must be told apart from a file that was never merged. Treating it as unmerged splices
+ * a second block into a file that already had one, which is a worse state than the damage it
+ * was trying to repair.
+ */
+export function hasDamagedMarkers(contents) {
+    const start = contents.indexOf(MANAGED_START);
+    const end = contents.indexOf(MANAGED_END);
+    if (start < 0 && end < 0)
+        return false;
+    return start < 0 || end < 0 || end < start;
+}
+/**
+ * Build the merged file: their content, then Religion's block, then the sections they own.
+ *
+ * Nothing of theirs moves. That is the property that makes this safe to accept without
+ * reading the diff, and the reason the block is appended rather than woven in.
+ */
+export function spliceEntry(existing, templateEntry) {
+    const body = existing.replace(/\n+$/, "");
+    const commands = userOwnedSections(templateEntry);
+    const parts = [body, "", managedBlock(templateEntry)];
+    // Only add Commands when their file has no section by that name; theirs is more accurate
+    // than the placeholder, and setup will find either one.
+    if (commands && !/^## Commands\s*$/m.test(existing))
+        parts.push("", commands);
+    return parts.join("\n") + "\n";
+}
+/**
+ * Replace the managed block in a merged file, leaving everything outside it untouched.
+ *
+ * Returns null when the markers are missing or out of order, which is treated as a conflict
+ * rather than repaired: a file whose markers were edited is one whose owner had a reason.
+ */
+export function replaceManagedBlock(existing, templateEntry) {
+    const start = existing.indexOf(MANAGED_START);
+    const end = existing.indexOf(MANAGED_END);
+    if (start < 0 || end < 0 || end < start)
+        return null;
+    return existing.slice(0, start) + managedBlock(templateEntry) + existing.slice(end + MANAGED_END.length);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-religion",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "A file-backed, spec-driven AI development workflow. Spec before code, small reviewed diffs, and project state in markdown so a cleared context costs nothing.",
   "license": "MIT",
   "author": "Nate",

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

@@ -2,6 +2,7 @@
 name: audit
 summary: review the code itself across four lenses, recording findings in the ledger
 description: "Read-only code review across four lenses (quality, security, performance, tests) and four scopes (current work, changed files, a path, or the whole project), fanning the lenses out to subagents that read and return findings while this skill performs the single write. Records each finding in religion/context/findings.md with a durable identifier, a severity from P0 to P3, and a status, where an open or fixed P0 or P1 blocks completion. Use when the user runs $audit, asks for a code, quality, security, performance, or test review, wants dead code or duplication found, or wants a repair re-reviewed before it closes."
+allowed-tools: Read, Grep, Glob, Bash, Agent, Write, Edit
 ---
 
 # audit - review the code, and record what you find

package/template/.agents/skills/auto/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: auto
 summary: run the loop unattended, within explicit bounds
-description: "Run the reviewed loop without stopping between steps, within bounds you set. With no argument it takes one work item and stops before completing it; `all` runs the remaining build plan; a number runs that many items. Specs, implements, verifies, applies the configured gates, repairs confirmed high-severity findings, and completes each item. Its invocation grants committing, dependency installs, and remote reads for the run, and grants nothing else: it still stops to ask before any merge. Use only when the user runs $auto or explicitly asks for an unattended run."
+description: "Run the reviewed loop without stopping between steps, within bounds you set. With no argument it takes one work item and stops before completing it; `all` runs the remaining build plan; a number runs that many items. Specs, implements, verifies, applies the configured gates, repairs confirmed high-severity findings, and completes each item. Its invocation grants committing, dependency installs, and remote reads for the run, and grants nothing else: it still stops to ask before any merge. Under git.mode pull-request it lands every item on one shared integration branch and ends by opening a single aggregate review packet it never merges, after stating that whole remote budget up front and being told yes. Use only when the user runs $auto or explicitly asks for an unattended run."
 ---
 
 # auto - the same loop, without the pauses
@@ -29,14 +29,32 @@ produced.
 Running this authorizes, for this run only: committing, installing dependencies, and
 network reads. That is the second authority tier, and the invocation is the approval.
 
-It grants **nothing** in the first tier. Merging, pushing, deploying, publishing, deleting
-data, and rewriting history each still stop and ask, every time, no matter how many items
-remain.
+It grants **nothing** in the first tier. Merging into the default branch, pushing to it,
+deploying, publishing, deleting data, and rewriting history each still stop and ask, every
+time, no matter how many items remain.
 
 Under `git.mode: trunk` there is no merge, so a run completes items and keeps going. Under
 `branch-per-item` it stops once per item to ask. That is not a flaw in the mode; landing
 work on a shared branch is a decision, and it stays one.
 
+Under `pull-request` nothing lands on the default branch, so there is no merge to stop for.
+What the run does need is the one grant the authority rules allow to be given ahead of time,
+and it is asked for **before any work starts**, in full:
+
+    This run will, without asking again:
+      create and push the integration branch <integrationBranchPrefix><date>
+      create and push one branch per item
+      open a pull request from each item into the integration branch
+      merge those pull requests into the integration branch
+      open one aggregate pull request into <default branch>
+
+    It will not merge or push <default branch>, and it will not merge
+    the aggregate pull request.
+
+Print that, naming the real branches, and wait. **The enumeration is the approval, and it is
+the whole remote budget.** A general yes to running is not it, and neither is silence. If the
+answer is no, the run does not start.
+
 ## Step 1 - preflight once
 
 Before the first item:
@@ -48,6 +66,21 @@ Before the first item:
   than one that never began.
 - The working tree is clean, or the only dirt belongs to work being resumed.
 - The plan has unchecked items.
+- Under `pull-request`, the repository can host one: a remote exists and the host command
+  works. A repository that cannot is a stop, not a reason to fall back to local merges. The
+  mode exists to produce review gates, and silently producing a different history instead
+  would be worse than not running.
+
+Record the default branch's current commit. It bounds what the aggregate pull request will
+carry, and the final report refers to it.
+
+Under `pull-request`, then establish the run's integration branch, named from
+`git.integrationBranchPrefix` and the date. Create it from that recorded commit and push it.
+Every item branches off it and lands back into it, which is what lets item three build on
+items one and two. On a resume, reuse the branch of that name rather than opening a second;
+if one exists that does not descend from the recorded commit, stop, because the run's base
+moved and that needs a person. Never rebase, reset, or force-push it: it is append-only for
+the run.
 
 State the bounds, the gates in force, and how many items are in range. Then start.
 
@@ -66,9 +99,39 @@ For every item, in plan order:
    the finding recorded rather than trying variations.
 5. **Complete it**, following $complete, which archives, ticks the plan, prunes the
    ledger, and commits. Ask before any merge.
-6. **Report one line** and move on.
+6. **Land it**, under `pull-request` only: push the item's branch, open its pull request
+   **into the integration branch** rather than the default branch, and merge it there once
+   its checks are green. Merge only a pull request this run opened, only into the integration
+   branch. A failing or conflicted one is a stop, never something to force. Then delete the
+   item branch, confirming the work commit is in the integration branch first, since a
+   squash leaves no merge parent for `git branch -d` to find. Return to the integration
+   branch clean before the next item.
+7. **Report one line** and move on.
+
+An item counts against `auto.maxItems` once it has landed, not once it is built.
+
+## Step 3 - close the run
+
+Under `trunk` and `branch-per-item` there is nothing to close: the items are done and the
+run reports.
+
+Under `pull-request`, open one aggregate pull request from the integration branch into the
+default branch. Title it for the run rather than for any one item. Its body is the run's
+review packet, and it is the artefact a person actually reads:
+
+- one section per completed item, in plan order, naming what it delivered, its merged pull
+  request, and the checks that proved it
+- findings still open or fixed, by identifier, and anything deliberately left out
+- what the run did not reach, and why it stopped
+
+Report the URL and stop. **Never merge it.** It is the review gate the mode exists to reach.
+
+Open it even when the run stopped early with completed items behind it, saying plainly in
+the body that it stopped short: work that passed every gate deserves to be reviewable, and a
+packet describing three of six items beats an integration branch nobody knows about. When
+the run completed no items at all, open nothing and say so.
 
-## Step 3 - stop
+## Step 4 - stop
 
 Stop immediately, keeping all state intact, when any of these happens:
 
@@ -84,9 +147,11 @@ Stop immediately, keeping all state intact, when any of these happens:
 A stopped run leaves the branch, the spec, and the ticked steps exactly as they are.
 `$auto resume` picks up from there, because the state is in files rather than in the run.
 
-## Step 4 - report
+## Step 5 - report
 
 - items completed, by name, and what each delivered
+- under `pull-request`, the recorded starting commit, the integration branch and its head,
+  each item's merged pull request, and the aggregate pull request URL or why none was opened
 - what stopped the run, exactly, and the state it stopped in
 - findings raised, repaired, and still open
 - checks run, and any that could not run
@@ -100,7 +165,9 @@ the part it got wrong.
 
 - Explicit invocation only.
 - The gates are the same gates. Unattended is not a reason to lower one.
-- Never merge, push, deploy, publish, or delete without asking, however long the queue is.
+- Never write to the default branch, in any mode. Never merge the aggregate pull request,
+  and never force-push anything, the integration branch included.
+- Never deploy, publish, or delete without asking, however long the queue is.
 - Never widen an item's scope to make its gate pass.
 - Stop on ambiguity. There is nobody to ask mid-run, so a guess compounds silently.
 

package/template/.agents/skills/capture/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: capture
+summary: note something for later without breaking the one thing in progress
+description: "Write a one-line note into religion/context/inbox.md and carry on, so noticing something worth doing does not cost the work item in progress. Takes the note as an argument, records it dated with where it came from, and stops. It never specs, never plans, and never starts work: $fix and $feature read the inbox when choosing what to build next. Use when the user runs $capture, says to note, park, remember or jot something down, mentions something worth doing later or some other time, or spots a problem mid-build that is not the thing being built."
+allowed-tools: Read, Grep, Glob, Bash, Write, Edit
+---
+
+# capture - note it, keep building
+
+This exists because of a rule elsewhere: one work item at a time. That rule is what makes a
+cleared context cheap, and it is also what makes noticing something mid-build awkward, since
+there is nowhere to put it. Without an answer, a good observation either derails the work or
+is lost.
+
+The answer is a line in a file and no ceremony at all.
+
+## Input
+
+The note, as an argument:
+
+    $capture "the rate limiter drops the first request after an idle period"
+
+With no argument, ask what to note. Do not guess from the conversation, and do not sweep up
+everything recently mentioned: a note nobody chose is a note nobody wants.
+
+## What it does
+
+Append one line to `religion/context/inbox.md` with the date and, when there is one, the file
+or area it concerns. Then stop, and return to whatever was happening.
+
+That is the whole skill. It is deliberately small: anything more, and using it costs more
+attention than the thought was worth, which is the failure mode that makes people stop
+noting things.
+
+## What it does not do
+
+- **It does not spec.** A note is not a work item. $fix turns one into a spec when you
+  decide to.
+- **It does not start work**, touch the active spec, or tick anything.
+- **It does not record code defects found by review.** Those are findings, they carry
+  severities and block completion, and $audit owns them. A note is something you
+  thought of; a finding is something a review proved.
+- **It does not judge.** Write down what was said. Triage happens when the note is read, not
+  when it is written.
+
+## How a note leaves the inbox
+
+$fix and $feature read the inbox when they start, and offer what is in it
+alongside the build plan. Choosing one specs it and removes the line; that is the only way a
+note leaves, other than you deleting it.
+
+An inbox nobody reads is a list of things nobody did, so the reading is the point rather
+than the writing.
+
+## Rules
+
+- One line per note. If it needs a paragraph, it needs a spec, and that is $fix.
+- Never interrupt the work in progress to discuss the note.
+- Never write to the findings ledger.
+- Never let the inbox become a plan. The build plan is the plan.
+
+## Formatting
+
+Match the conventions in `religion/context/ai-interaction.md`: concise, scannable markdown,
+lists for enumerations and tables for matrices rather than dense paragraphs.

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

@@ -1,7 +1,7 @@
 ---
 name: complete
 summary: run the final gate, archive the work, commit it, and close it out
-description: "Close out a finished feature, fix, rollback, or refactor campaign. Runs the full Verify command and the final safety pass, applies the configured quality gates, archives the spec under religion/history/, ticks the build plan, prunes resolved findings into the archive, resets the active spec, and makes the work commit. Under branch-per-item it squash-merges only with explicit approval, then asks separately before pushing. Ends with a manual walkthrough of what landed. Use when the user runs $complete, or asks to finish, wrap up, close out, or merge the current work item once it is built and reviewed."
+description: "Close out a finished feature, fix, rollback, or refactor campaign. Runs the full Verify command and the final safety pass, applies the configured quality gates, archives the spec under religion/history/, ticks the build plan, prunes resolved findings into the archive, resets the active spec, and makes the work commit. Under branch-per-item it squash-merges only with explicit approval, then asks separately before pushing. Under pull-request it pushes the branch and opens a pull request into the default branch, merging nothing. Ends with a manual walkthrough of what landed. Use when the user runs $complete, or asks to finish, wrap up, close out, or merge the current work item once it is built and reviewed."
 ---
 
 # complete - close out the finished work
@@ -152,10 +152,33 @@ Under **`branch-per-item`**:
 2. Delete the branch after a clean merge.
 3. Stop.
 
-Then, in either mode, ask separately whether to push. **Approval to merge is not approval
-to push.** Push only after an explicit yes to pushing, in this conversation. If there is no
+In those two modes, ask separately whether to push. **Approval to merge is not approval to
+push.** Push only after an explicit yes to pushing, in this conversation. If there is no
 remote, say so rather than guessing.
 
+Under **`pull-request`** nothing is merged here and the default branch is never written to.
+The branch goes up, the pull request describes it, and the merge is the user's, on the host:
+
+1. Confirm the repository can host one: a remote exists and the host command works. If it
+   cannot, stop and say so plainly. The work is committed on its branch and the user can
+   open the pull request themselves. Never invent a remote, and never quietly fall back to
+   a local merge, which would swap the history model without saying so.
+2. Push the branch and set its upstream, only with an explicit yes in this conversation.
+   **That yes covers pushing this branch and nothing else.** Neither running this skill nor
+   "looks good" is that yes.
+3. Open the pull request from the branch into the default branch. Title it from the work
+   commit. The body carries what changed and why, the checks that ran with the exact command
+   or output proving each, the manual walkthrough from Step 5, and anything left open:
+   unresolved findings, deliberate omissions, follow-ups.
+4. Report the pull request URL and stop. Do not merge it, do not wait or poll for it, and do
+   not touch the default branch.
+
+Deleting the branch is a separate, later action, because the merge happens outside this
+session. When the user says it merged: check out the default branch, fast-forward it,
+confirm the work commit is actually in it, and only then delete the branch locally and on
+the remote. A squash-merge leaves no merge parent, so `git branch -d` will refuse; verify
+the content landed before reaching for `-D`.
+
 ## 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/doctor/SKILL.md

@@ -2,6 +2,7 @@
 name: doctor
 summary: check the setup is healthy and explain anything that is not
 description: "Read-only health check of the installation: required files present, adapter trees in sync, the entry file's commands accurate, configuration valid, plans usable, overview fresh, ignore rules sane, and git state workable. Runs the religion command-line tool for the deterministic checks when it is installed, then explains what any failure means and offers the fix. Use when the user runs $doctor, asks whether the setup is correct, wants a health check, or says something feels wrong before starting or resuming work."
+allowed-tools: Read, Grep, Glob, Bash
 ---
 
 # doctor - is this set up correctly

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

@@ -22,6 +22,11 @@ lines into something buildable is this skill's whole job. It plans; it never bui
 - **A description with no match in the plan** - goes through **New work intake** below.
 - **`preview`** appended to any of the above - a read-only briefing, writing nothing.
 
+Read `religion/context/inbox.md` before choosing. When it holds anything and no argument
+named a specific item, list what is in it alongside the plan item you would otherwise take,
+and let the user pick. A note that is specced leaves the inbox with the line removed; the
+rest stay. An inbox nobody reads is a list of things nobody did.
+
 ## Step 0 - make sure the ground is solid
 
 Two checks before anything else.
@@ -127,9 +132,20 @@ visual spec from words alone when an image could exist.
 
 **Build steps** are the core of the file. Each is a small diff, ends with something that
 works, depends only on earlier steps, and carries an outcome that can actually be observed.
+
+Where two steps genuinely do not depend on each other, mark the later one `(with N)`. It is
+an assertion, not a hint: that these steps touch different files and neither needs the
+other's result. Mark nothing you are unsure of. An unmarked spec is sequential, which is
+always correct and never wrong, and a project with `workflow.parallelSteps` off ignores the
+markers entirely.
 Read the Commands section of the entry file while writing the Testing section, so predicted
 coverage matches the gate that is actually on.
 
+When writing the spec needed a broad read of the codebase first, run that read in a subagent
+and have it return what it found. A survey large enough to be worth doing is large enough to
+crowd out the context that has to write the spec from it. The subagent reads and returns; this
+skill writes, as it always does.
+
 This is a draft. Do not present it yet.
 
 ## Step 4 - red-team the draft, then tighten

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

@@ -16,7 +16,12 @@ numbered, it ticks nothing, and it archives on its own.
   something wrong.
 - **A finding identifier** - `$fix F-03` specs the repair of that ledger entry.
 
-Without either, ask what is wrong. Do not guess.
+- **Nothing** - read `religion/context/inbox.md` and offer what is there. Those notes were
+  taken mid-build precisely because they were not worth stopping for at the time, and this is
+  the moment they are worth something. Specced notes leave the inbox; the rest stay.
+
+Without any of those, ask what is wrong. Do not guess, and do not scan the project hoping to
+find something.
 
 ## Step 1 - understand the problem