create-religion 0.1.0

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

@@ -0,0 +1,172 @@
+---
+name: feature
+summary: turn a build-plan item into a reviewed, buildable spec
+description: "Turn a feature from the build plan into a buildable spec in religion/context/current-work.md. With no argument it specs the first unchecked item; given a number or name it specs that one; add `preview` to get a read-only briefing that writes nothing. A genuinely new feature goes through an intake that proposes the plan line, waits for approval, and refreshes the overview before spec'ing. Sizes the work and splits anything too large into sub-items, writes small build steps with observable outcomes, then red-teams its own draft and reports what the critique changed before stopping for review. Use when the user runs /feature, names or numbers a feature, asks to start or break down the next feature, or asks what an upcoming feature involves."
+---
+
+# feature - turn a build-plan item into a buildable spec
+
+Where this sits:
+
+    build-plan.md  ->  [feature]  ->  current-work.md  ->  implement
+    (one line)         (spec it)      (the spec)          (build it)
+
+The build plan is deliberately thin: one line per item, no detail. Turning one of those
+lines into something buildable is this skill's whole job. It plans; it never builds.
+
+## Input
+
+- **No argument** - the first unchecked item in the build plan, including the first
+  unchecked sub-item under an item that was split.
+- **A number or name** - `/feature 3`, `/feature "login"`.
+- **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.
+
+## Step 0 - make sure the ground is solid
+
+Two checks before anything else.
+
+**Overview freshness.** Recompute the source hash over the two plans. If it does not match
+the stamp in `religion/context/project-overview.md`, or the stamp is missing, follow the
+`/overview` skill first, report what changed, then continue here. A spec written
+against a stale overview encodes a data model the plans no longer describe.
+
+**Open questions.** Read the overview's Open questions section. If any of them lists an
+area this item touches in its `affects` line, the contradiction would be resolved by
+guessing while writing the spec. Instead:
+
+1. Name the question and quote what the two plans each say.
+2. Ask the user to decide.
+3. Show the exact edit their answer implies, in the plan section that is wrong.
+4. On approval, write it, follow `/overview` to regenerate, then continue.
+
+Only the user's own answer may resolve an open question, and only the edit they approved
+is written. If they would rather not decide now, stop and say which item remains blocked.
+
+An open question whose `affects` list does not cover this item does not block it.
+
+## Step 1 - pick the target
+
+Given a number or name that matches a build-plan item, use it. With no argument, read the
+plan top to bottom and take the first unchecked leaf. State which item you are spec'ing
+before going further.
+
+If the build plan is not a checklist yet, treat every item as unchecked, take the first,
+and offer to convert the list so progress can be tracked from here on. Proceed either way.
+
+### New work intake
+
+For a genuinely new capability, not a bug or small change. Those go to /fix.
+
+1. Search checked and unchecked items for an existing or near-duplicate item. If the
+   wording might just be a different name for something already planned, show the closest
+   matches instead of creating new scope.
+2. If it is genuinely new, propose one feature-sized checkbox line and where it belongs.
+   Preserve completed items and their numbers; take the next unused number.
+3. Check whether it materially changes product direction, users, data, stack, or
+   deployment. Include the exact proposed project-plan edits only when it does. Most
+   incremental work changes only the build plan.
+4. Stop for approval, showing the complete proposed plan change.
+5. After approval, write it, follow `/overview` to regenerate, then resume here with
+   the new item as the target.
+
+Never add scope to a plan the user owns without showing the exact change and waiting.
+
+## Step 2 - size it, and split if it is too big
+
+Read the target line, then take full context from the project overview: the data model,
+the stack, the conventions. Then decide how big this is.
+
+**Small enough to build and review as one unit** goes to Step 3.
+
+**Too big for one reviewable spec** gets split. Propose a short list of sub-items, title
+and one line each, let the user adjust it, then write them under the parent as an indented
+checklist (`4a`, `4b`, `4c`). Spec only the first now; the rest are picked up later.
+
+Two levels of breakdown, easily confused:
+
+- **Sub-items** are each big enough to stand alone: their own spec, review, and archive.
+- **Build steps** are small diffs inside one item.
+
+"Authentication" is too big for one spec, so it becomes `4a` registration, `4b` login,
+`4c` route protection. Inside `4a`, the page and its server action are steps, not items.
+
+This sizing call is exactly why the build plan stays high level.
+
+### Preview mode
+
+When the request ended in `preview`, stop here and report, writing nothing:
+
+- what the item is, in a sentence
+- what it depends on, and whether those are done
+- what it will touch: routes, models, modules
+- rough size, and how many steps it is likely to need
+- whether it will split, and into what
+- anything worth deciding before spec'ing it
+
+That is the whole of preview mode. Do not write the spec, touch the plans, or create files.
+
+## Step 3 - write the spec
+
+Write `religion/context/current-work.md` following `reference/spec-template.md`, filling
+every section.
+
+**Design reference.** If `prototypes/` exists, it is the reference and no image is needed.
+Check what is in it:
+
+- **Static mockups sharing a theme file** are throwaway. Link the relevant ones, treat the
+  theme as the source of truth for colour, type, and spacing, and make the **first build
+  step** port those tokens into the application's real stylesheet before any component is
+  built against them.
+- **Real components** are not throwaway. Link them and build on them directly. There is no
+  token-porting step, because the tokens are already the project's.
+
+If there are no prototypes and the work is visual or a replication of an existing design,
+ask for a screenshot, save it under `religion/reference/`, and link it. Do not write a
+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.
+Read the Commands section of the entry file while writing the Testing section, so predicted
+coverage matches the gate that is actually on.
+
+This is a draft. Do not present it yet.
+
+## Step 4 - red-team the draft, then tighten
+
+Turn on your own spec and try to break it. The cheapest place to catch a scope problem or
+an oversized step is here, before any code exists.
+
+- **Coverage.** What does this need that no step delivers? Push on what the happy path
+  skipped: empty, missing, or malformed input; the error, loading, and empty states; the
+  first-run case; failure of anything external it calls.
+- **Step size.** Would any step's diff be too large to read in one sitting? Split it.
+  Oversized steps defeat the review gate, which is the point of the whole loop.
+- **Order.** Does each step leave the project working, and depend only on earlier ones?
+- **Contracts.** Is any type, route, or stored shape that later work will touch left
+  undefined? Lock it now and mark it load-bearing.
+- **Scope honesty.** Is anything creeping in that belongs to a later item? Is anything
+  pushed out of scope that this item genuinely cannot ship without?
+- **Outcomes.** Is each one observable and checkable, or is it a vague "it works"?
+- **Visual fidelity.** If this is visual work, is a reference linked, or is it about to be
+  built blind from prose?
+- **Testing.** Does the predicted coverage match the gate that is on?
+
+Apply the fixes. Then stop and present the spec, leading with a short **what the critique
+changed** note: the splits, gaps, or scope cuts made, or "nothing, the draft held up".
+
+That note is the point. It shows the gate working before a line of code exists.
+
+## Rules
+
+- Small, reviewable steps. A diff too large to read means the step was too large.
+- Build in order. Each step leaves the project working.
+- Lock data contracts early and mark load-bearing shapes.
+- Scope honestly. State what is deferred so the item stays contained.
+- The plans belong to the user. Propose, show the exact change, and wait.
+- This skill plans. It never writes product code, and never starts building.
+
+## 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/.claude/skills/feature/reference/spec-template.md

@@ -0,0 +1,67 @@
+# <Feature name>
+
+**Type:** Feature
+**From build plan:** item <n>
+**Status:** not started
+
+## Goal
+
+What this delivers, in a sentence or two, and why it matters. Someone reading only this
+section should know what will be true when the work is done.
+
+## Design reference
+
+For visual or replication work, link the reference here: the mockups under `prototypes/`
+when they exist, or an image saved under `religion/reference/`. Prose underspecifies a
+visual target, and the approximation costs more to correct than the reference costs to
+obtain. Delete this section when the work has no visual target.
+
+## In scope
+
+- The specific things this work includes.
+
+## Out of scope
+
+- What it deliberately does not touch, and which later item picks it up.
+
+## Build loop
+
+Build one step at a time, never the whole item at once.
+
+1. The step is planned before any code is written.
+2. Just that step is implemented, as the smallest change that satisfies its outcome.
+3. The diff is shown, not whole files, and explained in plain language.
+4. Its stated outcome is proved with evidence, then the step is approved.
+
+Never accept a step you have not read. If a diff is too large to review, the step was too
+large, so split it.
+
+## Build steps
+
+Small, reviewable units. Each ends with something that works, and each carries an
+observable outcome that can be checked. These boxes are ticked as the steps land, which is
+what lets a cleared context resume from the first unchecked one.
+
+- [ ] **Step 1 - <what it builds>** - what changes. *Done when:* <observable outcome>.
+- [ ] **Step 2 - <what it builds>** - what changes. *Done when:* <observable outcome>.
+
+## Files and areas
+
+- The files or modules this creates or changes.
+
+## Data and contracts
+
+- Types, stored shapes, or interface shapes involved, or "none".
+- Mark anything later work will depend on as load-bearing.
+
+## Testing
+
+- How the outcomes are verified, per step.
+- When a test command is declared, name the in-scope logic that needs a test: parsers,
+  formatters, validators, server actions. Not components or integration surfaces.
+- When no runner is configured, say so and rely on running it, a screenshot, and the build.
+
+## Notes for the agent
+
+- Conventions and constraints this work must respect, drawn from the coding standards and
+  the project overview. Anything that would be wrong in a way review would not catch.

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

@@ -0,0 +1,76 @@
+---
+name: fix
+summary: spec an unplanned bug or small change, or repair a recorded finding
+description: "Write a short spec for an unplanned bug or small change into religion/context/current-work.md so it runs through the same reviewed loop as planned work, then stop. Given a finding identifier instead, specs the repair of that recorded finding. Fixes are archived under religion/history/fixes/ and never touch the build plan. Use when the user runs /fix, reports a bug, asks to fix or change something that is not a planned item, or asks to pick up a finding from the ledger."
+---
+
+# fix - spec an unplanned change
+
+Same loop as planned work, smaller spec. A fix is not a build-plan item: it is not
+numbered, it ticks nothing, and it archives on its own.
+
+## Input
+
+- **A description** - `/fix "password reset email never sends"`. A problem stated in the
+  conversation already counts; this skill does not scan the project hoping to find
+  something wrong.
+- **A finding identifier** - `/fix F-03` specs the repair of that ledger entry.
+
+Without either, ask what is wrong. Do not guess.
+
+## Step 1 - understand the problem
+
+**For a described problem**, establish what actually happens before writing what should.
+Reproduce it if you can do so cheaply. If the cause is genuinely unclear and finding it
+would mean exploring, stop and point at /debug, which isolates a failure without
+changing anything. Writing a fix spec against a guessed cause produces a fix for the wrong
+problem.
+
+**For a finding**, read its entry in `religion/context/findings.md`: the file and line, why
+it matters, the suggested fix. The finding is the problem statement.
+
+If something is already in progress in `religion/context/current-work.md`, say so and ask
+whether to set it aside. One thing at a time is the point.
+
+## Step 2 - write the spec
+
+Write `religion/context/current-work.md` following the shape in
+`/feature`'s spec template, marked `Type: Fix`, with no build-plan number. Keep it
+short. A fix that needs a long spec is a feature that has not admitted it yet, and should
+go through /feature instead.
+
+Fill in:
+
+- **Goal** - what is wrong, and what will be true afterwards.
+- **Cause** - what actually produces the behavior, and how that was established. If the
+  cause is a guess, say so; a fix built on a guess needs review to know that.
+- **In and out of scope** - especially what nearby brokenness is deliberately not being
+  fixed now. Fixes sprawl more easily than features because the surrounding code is already
+  under suspicion.
+- **Build steps** - usually one or two, each with an observable outcome.
+- **Testing** - when a test runner is configured and the fix touches logic, the fix ships a
+  test that fails without it. A bug that could recur silently is exactly what the test gate
+  is for.
+
+For a finding repair, name the finding identifier in the Goal so the archive and the ledger
+agree about what happened.
+
+## Step 3 - stop
+
+Present the spec for review. This skill plans; /implement builds it.
+
+For a finding repair, note that implementation marks the finding `fixed` and only a later
+/audit moves it to `closed`.
+
+## Rules
+
+- A fix needs a real problem statement. Do not invent one.
+- Do not fix things nobody reported while you are in there. Note them instead.
+- If the fix turns out to be feature-sized, stop and say so rather than growing the spec.
+- Never mark a finding `accepted` or `invalid`. Those are the user's call and a review's
+  verdict.
+
+## 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/.claude/skills/implement/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: implement
+summary: build the current spec one reviewed step at a time
+description: "Build the feature, fix, or rollback spec'd in religion/context/current-work.md, one small reviewable step at a time. Implements each step as the smallest change that satisfies its stated outcome, shows the diff and explains it in plain language, proves the outcome with evidence, ticks the step off so progress survives a cleared context, and resumes from the first unchecked step when interrupted. Repairs open high-severity findings as extra reviewed steps and has them re-reviewed independently. Ends with a review packet; the work commit and any merge belong to /complete. Use when the user runs /implement, or asks to build, start, continue, or resume the current work item once its spec is ready."
+---
+
+# implement - build the current spec, one reviewed step at a time
+
+Where this sits:
+
+    feature, fix, or rollback  ->  [implement]  ->  complete
+    (the spec)                     (build it)       (commit, close it out)
+
+The spec was written and reviewed. This skill turns it into code without vibe coding:
+small steps, a visible diff and a plain-language explanation for each, evidence that its
+outcome is met, and iteration until it works.
+
+## Before you start
+
+**Read `religion/config.json`.** A missing file means defaults. If it exists but cannot
+be parsed, stop and point at /doctor; a skill that is about to change code must not
+guess past broken configuration.
+
+**Read the spec.** If `religion/context/current-work.md` is still the stub, or its status
+is already complete, stop and say to run /feature, /fix, or
+/rollback first.
+
+**Take the context.** Conventions from `religion/context/coding-standards.md`, the data
+model from the project overview. Code that ignores them is rework, not progress.
+
+**Resuming?** Steps already ticked (`- [x]`) mean this was started earlier and
+interrupted, usually by a cleared context. That is expected and costs nothing. Read which
+steps are done, check the working tree and recent commits to see what actually landed, and
+continue from the **first unchecked step**. Do not start over, and do not re-verify
+completed steps unless something suggests they broke.
+
+**A rollback spec** carries `Type: Rollback`. Apply it by recomputing the diff command the
+spec records, confirming it still matches, then applying it in reverse with three-way
+conflict detection and staging it. Show the staged diff and confirm no workflow-owned path
+was touched before presenting the step. Never write the reversal freehand, and never run a
+whole-commit revert: the commits being reversed also carry the archive and plan bookkeeping
+that must survive. On a conflict, stop and report the paths and the later commit involved
+rather than resolving it.
+
+## Step 1 - position the work
+
+Read `git.mode`.
+
+**`trunk`** (the default) works on the branch already checked out. Do not create a branch.
+If the current branch looks wrong for this work, say so and ask; do not switch or create
+one unprompted.
+
+**`branch-per-item`** creates and checks out a branch named from the spec using the
+configured prefix. On a resume the branch exists already, so check it out rather than
+creating a second one.
+
+Either way, if the project is not a git repository, say so and ask the user to initialize
+one. The loop needs history to be reviewable.
+
+## Step 2 - build one step
+
+Set the spec's status to `in progress` before the first code change of this run, and again
+whenever work resumes after a passing check and touches product code. That invalidates
+stale verification state.
+
+Work through the build steps **in order, one at a time**. For each:
+
+1. **Implement just that step.** The smallest change that satisfies its stated outcome.
+   Nothing from a later step, nothing nobody asked for.
+2. **Show the diff**, not whole files.
+3. **Explain it, and prove it.** What the step delivered, one line per changed file on
+   what it does and why, then the outcome shown true with evidence: command output, a
+   screenshot, a passing assertion. Keep it concrete; this is the comprehension gate, not
+   a ritual. Add a short **how to try it** line when there is a manual path.
+4. **Verify what the step touched.** Run the focused checks for this change: the relevant
+   test, the typecheck, whatever proves this diff. The full `Verify` command runs once
+   before the work is completed, so a step does not pay for the whole suite every time.
+   Run the full command earlier anyway if a step could plausibly break something far away.
+
+   With `verification.logicTests: "required"`, a logic change with no configured runner
+   stops and points at /tests. With `when-configured`, the gate applies only when a
+   test command is declared. When it is on, a step that adds in-scope logic ships a passing
+   test in the same diff. Interface and integration steps ride on running it, a screenshot,
+   and the build. With `verification.uiEvidence: "required"`, an interface outcome cannot
+   pass on build output alone.
+
+   Never install a runner mid-step unless this spec is what sets that runner up.
+5. **Iterate until it works.** If it fails, revise and re-test. After two or three
+   attempts that do not work, **stop**. Report what each attempt did and why you think it
+   is failing, and offer to hand it to /debug, which reproduces the failure and
+   tests competing hypotheses in parallel. Do not keep trying variations.
+6. **Tick the step** (`- [x]`) once its gate is satisfied, so progress survives a cleared
+   context. If the step repaired a finding, mark that finding `fixed` and note the repair
+   in its resolution line. Never mark it `closed`; see Step 3.
+7. **Then prompt, according to config.**
+
+   With `workflow.stepReview: "item"`, do not prompt. Continue to the next step and
+   collect everything into one packet at the end. Still stop early for a failed check, a
+   decision, a conflict, scope drift, or anything in the first tier of the authority rules.
+
+   With `stepReview: "every"`, offer only the options that config actually allows:
+
+   - **Continue** - move to the next step.
+   - **Commit checkpoint** - only when `git.checkpoints` is `every-step` or `squash`.
+     Choosing it is the approval that authorizes the commit. Commit just this step with a
+     conventional message describing what the change does.
+   - **Walk me through it** - a deeper, line-level explanation: why this approach, what
+     each part does, the gotchas. Then re-ask. A loop back, not a terminal choice.
+   - **Stop here** - pause. Say where things stand and how to resume.
+
+   Use the tool's short input prompt when there is one. When you have just produced a long
+   block to read, ask in plain text instead, so the prompt does not cover what is still
+   being read.
+
+Never batch the whole item into one diff. A diff too large to read means the step was too
+large; split it.
+
+## Step 3 - clear the ledger before handing off
+
+Read `religion/context/findings.md`. A P0 or P1 finding that is `open` or `fixed` will
+block completion, so close the loop now rather than discovering it later.
+
+For each `open` P0 or P1:
+
+1. **Append it to the spec's build steps** first (`- [ ] Repair F-03 - <title>`), so the
+   repair is on the record and survives a cleared context.
+2. Build it through the same loop as Step 2: smallest change, diff, explanation, evidence.
+3. Tick the step and mark the finding `fixed`.
+
+Then have the repairs re-reviewed. Run /audit over the repaired code **in a
+subagent with fresh context**, and record what it returns. The independence is the point:
+a repair is not done when the code changes, it is done when a review that did not write it
+has looked at the result, because a fix can introduce a worse defect than the one it
+removed. Reviewing your own repair in the context that produced it is not that review.
+
+A finding that a user decides not to fix is `accepted`, and only they may set it, with
+their reason recorded. A finding that looks wrong goes back to review to be marked
+`invalid` with evidence. This skill sets neither.
+
+## Step 4 - hand off
+
+When every step is built and its gate has passed, stop with a compact review packet:
+
+- where the work sits: branch, or the current branch under trunk mode
+- what changed, grouped by file or area
+- checks run, with the exact command and result for each
+- how to try it manually
+- ledger state: any findings still `open` or `fixed`, by identifier
+- known risks, skipped checks, or follow-ups
+- next action, normally /complete
+
+Set the spec's status to `verified` immediately before that packet, but only when every
+required command, outcome, and configured gate actually passed. A gate that could not run
+is a blocker, not a pass.
+
+Then say that /complete runs the full `Verify`, archives the spec, updates the
+build plan, makes the work commit, and asks separately before any merge or push.
+
+## Rules
+
+- One small step per diff, and never a commit before its review gate is satisfied.
+- Explain every change in plain language. Understanding the code is the point.
+- Build only what the spec says. If the spec is wrong or thin, stop and fix the spec
+  first. Do not improvise around it.
+- Follow the project's coding standards, including scoping user-owned queries by the
+  authenticated identity taken from the server.
+- Checkpoints are optional rollback points. The work commit, any merge, and any push
+  belong to /complete.
+- This skill does not merge, push, or complete.
+
+## 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/.claude/skills/overview/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: overview
+summary: distill the two planning documents into the project's source of truth
+description: "Validate the two user-owned planning documents and generate religion/context/project-overview.md from them, the single source of truth every session loads. Proposes a normalized checkbox build plan when the plan is still loose bullets, separates what the product already does from what is queued, derives a concrete domain model and a code map, and records contradictions as open questions that can block work in the areas they affect. Also runs automatically when the plans have changed since the overview was generated. Use when the user runs /overview, has just written or edited the plans, asks to regenerate the project overview, or when another skill finds the overview stale."
+---
+
+# overview - turn the two plans into the source of truth
+
+Where this sits:
+
+    project-plan.md  +  build-plan.md  ->  [this skill]  ->  project-overview.md
+    (what and why)      (what order)                          (what everything reads)
+
+The plans are yours: long, rough, written in whatever order made sense at the time. The
+overview is the distilled version every skill reads every session. Regenerating it is
+cheap; working from a stale one is not.
+
+## When this runs
+
+**Explicitly**, when the user asks.
+
+**Automatically**, when a skill that reads the overview finds it stale. Any skill in that
+position follows the steps below first, reports what changed, and then continues with what
+it was asked to do. Nothing acts on a stale overview.
+
+## Staleness
+
+The generated file carries a hash of the two plans it was built from:
+
+    <!-- religion:source-hash <16 hex characters> -->
+
+Compute it exactly this way, so that two runs never disagree and report a false change:
+concatenate the raw bytes of `religion/project-plan.md` then `religion/build-plan.md`
+with nothing between them, take the SHA-256, and use the first 16 characters of the
+lowercase hexadecimal digest.
+
+    cat religion/project-plan.md religion/build-plan.md | shasum -a 256 | cut -c1-16
+
+Recompute it over the current plans. A mismatch means the plans moved and the overview did
+not. A missing stamp means an overview generated before this mechanism existed, or one
+hand-edited; treat both as stale.
+
+## Step 1 - read the plans
+
+Read `religion/project-plan.md` and `religion/build-plan.md` in full, plus the existing
+overview when there is one, so that a regeneration can report what changed rather than
+just replacing the file.
+
+Sections 6 through 8 of the project plan are optional. A plan that deleted them has not
+made a mistake, and the corresponding overview headings are omitted rather than filled
+with "not applicable".
+
+## Step 2 - validate, and propose fixes for approval
+
+Check both plans are usable before generating from them:
+
+- **Required sections.** Sections 1 through 5 of the project plan are answered, not left
+  as the placeholder prompts they ship with.
+- **Build plan shape.** The build plan is a checkbox list. The loop reads those boxes to
+  know what is next and what is done, so a plain bullet list breaks progress tracking.
+- **Item sizing.** Each build-plan item is a feature-sized outcome, not a whole product
+  area ("Auth, billing, and dashboard") or a loose task ("Database").
+- **Item kind.** The build plan is for features. An item that describes something broken
+  ("search ranking is bad", "the switcher does not remember") is a fix, and an item that
+  describes reviewing rather than building ("audit the hook types") is a review pass.
+  Both have their own path and their own place in the history, and neither belongs in the
+  plan. Point them at /fix and /audit, and propose removing them.
+- **Numbering.** Completed items keep their numbers, since archives refer back to them.
+
+When something is wrong, show the exact proposed replacement and ask before writing. These
+two files are the user's. Never edit them silently, and never rewrite prose that is merely
+rough: a plan can be informal and still be usable, and only shape problems that actually
+break the loop are worth proposing a change for.
+
+If the user declines a proposed fix, say what will not work as a result and generate
+anyway.
+
+## Step 3 - generate the overview
+
+Write `religion/context/project-overview.md` following
+`reference/project-overview-template.md`. Stamp the freshly computed source hash.
+
+Three sections are real work rather than distillation.
+
+**What it does** and **Roadmap** are deliberately separate. The first is the product's
+identity, taken from section 3; the second is the queue, taken from the build plan. On a
+new project they are nearly the same list. On an established one they barely overlap, and
+collapsing them produces an overview claiming the product's features are whatever three
+small things happen to be queued. Never merge them, and never fill one from the other.
+
+**Domain model** turns the plan's list of nouns into concrete shapes with fields and
+relationships. What that means depends on the project: persisted entities for something
+with a database, the shapes read and emitted for a compiler or CLI, the public types and
+their contracts for a library. A project with no database still has a domain model. Write
+what it actually works with and say what kind it is.
+
+**Code map** records where things live, derived by looking at the repository rather than
+the plans, since neither plan describes layout. For several packages, name the boundary
+each one owns. Without this, every spec re-derives the layout from scratch.
+
+Mark any shape later work will depend on as load-bearing.
+
+Derive, do not invent. If the plans do not determine something a section needs, that is an
+open question, not a gap to fill with a plausible guess. The code map is the one exception:
+it is read from the repository, because that is where the answer actually is.
+
+## Step 4 - record open questions
+
+Contradictions and gaps go in the **Open questions** section, and each one names what it
+affects:
+
+    - **Storage engine** (affects: data model, features 3 and 7) - section 5 names
+      Postgres while section 4 describes local SQLite files. Resolve in the plans and
+      regenerate.
+
+The "affects" list is load-bearing, not decoration. Work touching a named area is blocked
+while the question is open, and work elsewhere proceeds normally. Scope each one as
+narrowly as the evidence allows: a question marked as affecting everything stops the
+project, so only write that when it is true.
+
+Raise a question only for a real conflict or a real gap that later work will hit. Stylistic
+thinness is not an open question.
+
+## Step 5 - report
+
+Lead with what changed, then the questions:
+
+- **generated** or **regenerated**, and on a regeneration, what moved: sections added or
+  removed, shapes or fields that changed, items that entered or left the roadmap
+- open questions, by title, and what each blocks
+- any plan fix that was proposed, and whether it was applied
+- the next action
+
+On a first generation, say so plainly rather than reporting a diff against nothing.
+
+## Rules
+
+- The two plans belong to the user. Propose, show the exact change, and wait. Never edit
+  them without approval.
+- The overview is derived. Never hand-edit it, and never patch it to work around a plan
+  that says something different; fix the plan and regenerate.
+- Derive from the plans only. An overview that states something neither plan supports is
+  worse than one with an open question, because nothing later will question it.
+- Do not turn a rough plan into a polished one. Distil what is there.
+- Scope every open question to what it genuinely affects.
+
+## Formatting
+
+Match the conventions in `religion/context/ai-interaction.md`: concise, scannable
+markdown, lists for enumerations and tables for matrices rather than dense paragraphs.