create-religion 0.1.0

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

@@ -0,0 +1,114 @@
+---
+name: rollback
+summary: plan a guarded reversal of completed work, preserving its history
+description: "Plan the safe reversal of a completed item using its archive and the commits it recorded when it landed. Verifies the recorded commits still resolve and are ancestors of HEAD, reviews later commits for work that depends on them, then writes a Type: Rollback spec to religion/context/current-work.md and stops before any code changes. The reversal applies only the product diff in reverse, never a whole-commit revert, so the archive and plan bookkeeping that landed in the same commits survive. Use when the user runs $rollback, asks to remove or undo completed work, or wants the project returned to its behavior before an item without erasing the record that it existed."
+---
+
+# rollback - plan a guarded reversal
+
+Where this sits:
+
+    history/  ->  [rollback]  ->  implement  ->  complete
+    (archive)     (plan it)       (apply it)     (record it)
+
+Removing completed work is not `git revert`. The commits that landed an item also carry its
+archive, its build-plan tick, and its ledger pruning. Reverting them whole would delete the
+record that the work ever existed, and would fight with whatever the plan says now.
+
+This skill plans. It writes a spec and stops. No product file changes here.
+
+## Step 1 - identify the target
+
+Take a build-plan number or name. Match it to a **checked** item and its archive under
+`religion/history/features/`. If the item is not checked, it was never completed, and there
+is nothing to roll back: say so.
+
+Read the archive's `## Landed` section for the base commit, the item's commits, and the
+product paths it touched.
+
+**If there is no `## Landed` section**, the item was completed before that record existed.
+Do not guess the commit range from messages or dates: reversing the wrong commits damages
+unrelated work. Report what is missing, show the archive and the commits around it, and ask
+the user to confirm the exact range before continuing.
+
+## Step 2 - verify the record still holds
+
+Stop on any failure. Do not repair a mismatch by choosing a nearby commit.
+
+1. Every recorded identifier matches `^[0-9a-f]{40}$`. Reject abbreviated or uppercase
+   values.
+2. Every recorded commit resolves in this repository and is an ancestor of `HEAD`.
+3. The recorded base is the parent of the earliest recorded commit.
+4. The working tree is clean apart from the rollback spec being written.
+
+## Step 3 - preview the product diff
+
+Compute the reversal exactly as it will be applied, excluding everything the workflow owns:
+
+    git diff --binary <base> <last-recorded-commit> -- . \
+      ':(exclude).agents/**' ':(exclude).claude/**' \
+      ':(exclude)religion/**' \
+      ':(exclude)AGENTS.md' ':(exclude)CLAUDE.md' \
+      ':(exclude)prototypes/**'
+
+Confirm the result is non-empty and its paths match the product paths in the archive. A
+mismatch means the record and the repository disagree, which is a stop.
+
+Never drop those exclusions for convenience. They are what keeps the archive, the plan, and
+the ledger intact while the product change goes away.
+
+Under `git.mode: trunk` the item's commits sit among other commits on the same branch. The
+recorded range is what separates them; the diff is still computed only across that range,
+never from the branch tip.
+
+## Step 4 - review what came after
+
+Inspect commits after the target for work that depends on it: imports of things it added,
+callers of its functions, columns or fields it introduced, configuration it established.
+
+Report each dependency with its commit and file. A reversal that cascades into later work
+is not a rollback, it is a second reversal that has not been planned. Say so plainly and
+let the user decide before writing the spec.
+
+## Step 5 - write the spec
+
+Write `religion/context/current-work.md` marked `Type: Rollback`, recording:
+
+- **Target** - the item, its number, and its archive path
+- **Reason** - why it is being removed, in the user's words
+- **Base** and **Commits** - the verified full identifiers
+- **Product paths** - what the reverse patch will touch
+- **Later dependencies** - what Step 4 found, and how each is handled
+- **Build steps** - normally one: apply the reverse patch and confirm the tree
+- **Done when** - the removed behavior is gone, and one named unaffected path still works
+
+Include the exact command from Step 3 in the spec, so implementation applies the reviewed
+diff rather than reconstructing it.
+
+Then stop for review.
+
+## What implementation will do
+
+Recorded here so the spec and the build agree:
+
+1. Recompute the diff from Step 3 and confirm it still matches.
+2. Apply it in reverse with three-way conflict detection, and stage it:
+   `... | git apply --reverse --3way --index`
+3. Show the staged diff and the status, and confirm no workflow-owned path is touched.
+
+On a conflict: stop, report the exact paths and the later commit involved, and ask. Never
+auto-resolve, discard, stash, reset, or check out broadly. A cascade into other completed
+work needs its own plan.
+
+## Rules
+
+- The archive is never deleted or rewritten. Completion adds a rollback record beside it.
+- Reverse only the recorded product diff. Never a whole-commit revert.
+- The build-plan item is unticked and annotated, and keeps its number.
+- Stop on any mismatch between the record and the repository. Guessing is what makes a
+  rollback dangerous.
+
+## 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/setup/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: setup
+summary: tune the installation to this project, greenfield or existing
+description: "Set up Religion after installing it into a project. Detects whether the project is newly scaffolded or already has shipped work, and branches: a new project gets its entry file, standards, and configuration tuned before you write the plans, while an existing one is surveyed so the plans and standards are generated from what is actually there. Documents the real commands, reports existing checks, decides whether workflow files are committed, and says what to do next. Use when the user runs $setup, has just installed Religion, or asks what to do first."
+---
+
+# setup - make the installation match this project
+
+Run once, after installing. It replaces the shipped assumptions with what is true here.
+
+## Step 0 - which project is this
+
+Look before asking. Count source files, read the git history, check whether the project has
+shipped anything.
+
+- **New** - a scaffold, little or no history, no meaningful features yet. The plans are
+  written from intent, by the user, after this runs.
+- **Existing** - real features, real history, real users possibly. The plans are generated
+  from what already exists, in this run.
+
+State which you concluded and why, and let the user correct you. Guessing wrong is
+recoverable but wasteful: the existing path does substantially more work.
+
+## Step 1 - survey the project
+
+Both paths need this.
+
+- **Stack** - languages, framework, package manager, module system, versions.
+- **Commands** - the real ones, from the package manifest or task runner: dev, build, test,
+  lint, typecheck. Never invent one. A command that does not exist is worse than a missing
+  one, because it will be run.
+- **Checks that already exist** - test runner, typecheck, lint, continuous integration.
+  Report them; do not add any.
+- **Conventions** - file organization, naming, how components and modules are actually
+  structured, how data is accessed, how errors are handled. What the code does, not what a
+  style guide would say.
+- **Layout** - the directories that matter and what each owns.
+
+## Step 2 - write what you learned
+
+**The entry file's Commands section.** Replace the placeholder with the real commands. If
+the project has a single command that runs its checks in order, record it as `Verify`. If
+it does not, leave that out; $ci defines one deliberately later.
+
+**The coding standards' Stack conventions section.** Fill it from the survey: language
+conventions, file organization, naming, framework patterns, data access, as this project
+actually does them. Do not import opinions the project does not hold. If the project is
+inconsistent, say so and pick the dominant pattern, noting that it was a choice.
+
+**The project title** in the entry files, and the one-line description.
+
+## Step 3 - the plans
+
+**New project.** Leave both plans as templates and tell the user to fill them in, or to run
+$discovery for a guided session. Do not write plans from a scaffold; there is
+nothing there to derive intent from.
+
+**Existing project.** Generate both, then have them reviewed:
+
+- **Project plan** - problem, users, and features derived from the code, the README, and
+  the history. Tech and data from what is actually there. Mark anything you inferred rather
+  than found, because inferring intent from an implementation is exactly where this goes
+  wrong: the code says what was built, never why.
+- **Build plan** - shipped features listed as **checked** items, so the history is honest
+  and numbering starts from reality. Unshipped work goes in unchecked, if the user names
+  any.
+
+Ask for the intent the code cannot reveal: who this is for, what problem it solves, what
+was deliberately excluded. That conversation is the whole value of this path. Then stop for
+review before anything downstream runs.
+
+## Step 4 - visibility
+
+Ask whether the workflow files should be committed or kept local. Do not pick a default.
+
+- **Committed** - plans, specs, and history are part of the repository: portable across
+  machines, visible to collaborators, reviewable.
+- **Local** - added to `.gitignore`, so nothing about the workflow enters a shared
+  repository. Not portable: another machine needs it installed again.
+
+If those paths are already tracked and the user chooses local, say that `.gitignore` alone
+will not untrack them, and ask before running anything that would.
+
+## Step 5 - report
+
+- what was detected: stack, commands, existing checks
+- what was changed, file by file
+- what the user must do next, exactly: fill in the plans, or review generated ones
+- optional things worth knowing about, without pushing: $tests if there is logic and
+  no runner, $ci if there are checks and no automation
+
+Then stop. The next step is $overview, once the plans are real.
+
+## Rules
+
+- Detect before asking, then let the user correct the detection.
+- Never invent a command, a convention, or a feature.
+- Mark inferred intent as inferred.
+- Do not install anything, add a test runner, or create continuous integration here.
+- Generated plans are a draft for review, never a finished artifact.
+
+## 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/status/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: status
+summary: say where the work stands and what to do next
+description: "Report where the project stands: build-plan progress, the active spec and which of its steps are done, open findings, git state, and the one action that makes sense next. Uses the religion command-line tool when it is installed, since the parsing is deterministic, and reads the state files directly when it is not. Read-only. Use when the user runs $status, asks where things stand, what is next, what is in progress, or is picking work back up after a break or a cleared context."
+---
+
+# status - where things stand
+
+Read-only. It reports; it never advances anything.
+
+## Step 1 - get the state
+
+If the `religion` command is available, run `religion status --json` and use it. The
+parsing is deterministic and a program does it more reliably than a reading of the files.
+
+Otherwise read them directly: `religion/build-plan.md` for progress,
+`religion/context/current-work.md` for the active spec and its ticked steps,
+`religion/context/findings.md` for the ledger, `religion/context/project-overview.md` for
+its source hash, and the git branch and working-tree state.
+
+## Step 2 - report
+
+Lead with the next action, because that is the question actually being asked.
+
+- **Next** - the single command that makes sense now, and why in one clause.
+- **Active work** - the item, and which step it is on out of how many. "Nothing in
+  progress" when the spec is the stub.
+- **Plan** - items complete out of total, and the next unchecked one.
+- **Findings** - counts by status, naming any P0 or P1 that is `open` or `fixed`, since
+  those block completion.
+- **Git** - branch, whether the tree is dirty, and unpushed commits.
+- **Warnings** - only real ones: a stale overview, an open question blocking queued work,
+  a spec whose steps are all ticked but which was never completed, a dirty tree with no
+  active spec.
+
+Say "up to date" rather than inventing a warning when there is nothing wrong.
+
+## Choosing the next action
+
+| State | Next |
+| --- | --- |
+| Plans not filled in | Write them, or run $discovery |
+| Overview missing or stale | $overview |
+| No active spec, plan has unchecked items | $feature |
+| Active spec, steps unticked | $implement |
+| All steps ticked, not verified | $check |
+| Verified, findings blocking | $audit, or repair via $implement |
+| Verified, nothing blocking | $complete |
+| Plan complete | Add to the plan, or $release |
+
+When two apply, take the one further along: finishing beats starting.
+
+## Rules
+
+- Read-only. Never write a state file, tick a step, or advance anything.
+- One next action. A list of options is not an answer to "what now".
+- Do not guess at what is happening. If the state is contradictory, say what is
+  contradictory.
+
+## 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/tests/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: tests
+summary: set up unit testing, or backfill coverage for logic that already exists
+description: "Set up unit testing for this project: detect the stack, reuse an existing runner or install the stack-native one, add a small example test, record the command in the entry file, and run it. Declaring that command is what turns testing into a gate for logic-bearing work. Given `backfill`, instead writes tests for logic that already exists, worst-covered first. Use when the user runs $tests, asks to add or set up unit tests, or asks to cover existing code with tests."
+---
+
+# tests - turn the testing gate on, or backfill coverage
+
+Two modes. `$tests` sets the runner up. `$tests backfill` covers logic that already
+exists. Setup comes first; backfilling into no runner is not a thing.
+
+## Setup mode
+
+### Step 1 - look before installing
+
+If a runner is already configured, use it. Adding a second is how a project ends up with
+two test commands and no idea which one is authoritative.
+
+If there is none, choose the stack-native one: vitest for a TypeScript or JavaScript
+project, pytest for Python, the built-in tooling for Go or Rust. Do not import a preference
+the ecosystem does not share.
+
+Say what you found and what you propose before installing anything. Installing a dependency
+needs a yes.
+
+### Step 2 - wire it up
+
+Install the runner, add the script or task, and add **one** small test that genuinely
+exercises something real in this project. Not a test that asserts true is true: a test that
+would fail if the thing it covers broke.
+
+### Step 3 - record the command
+
+Add the exact command to the Commands section of the entry file as `Test`.
+
+**This is the switch.** Once that command is declared, a build step that adds logic ships a
+passing test in the same diff, and completion will not finish while the suite is red. Say
+that plainly, because it changes how every later work item behaves.
+
+If a `Verify` command exists, add the test command to it in the right order: typecheck,
+then tests, then build.
+
+### Step 4 - prove it
+
+Run the test command and show the output. Then run it again with the example test
+deliberately broken, to show it actually fails. A suite that cannot fail is not a gate, and
+an empty suite reporting success is the specific failure worth ruling out here.
+
+Restore it, and report what changed.
+
+## Backfill mode
+
+For logic that shipped without tests. Deliberate, bounded, and never automatic.
+
+### Step 1 - find what is worth covering
+
+Only in-scope logic: parsers, formatters, validators, identifier builders, server actions,
+anything with assertable inputs and outputs and real edge cases. Not components, not
+integration surfaces, not anything whose test would just mirror the implementation.
+
+Rank by risk, not by convenience: how badly a wrong answer would hurt, how likely a wrong
+answer is, how often the code changes. Present the ranked list and how many to do now. Do
+not attempt the whole project in one pass.
+
+### Step 2 - write them, in reviewed batches
+
+One module at a time, each as its own reviewable diff. For each, cover the normal case, the
+edges the code actually handles, and the edges it does not.
+
+**When a test fails, stop.** A backfilled test that fails has found a bug, and that is the
+valuable outcome. Do not adjust the test to match the behavior: report it, and let it
+become a fix. Writing the test around the bug destroys the only reason to have written it.
+
+### Step 3 - report
+
+What was covered, what was skipped and why, and every discrepancy found. Discrepancies are
+the point; coverage is the side effect.
+
+## Rules
+
+- Never install a runner during unrelated work. This is a deliberate setup step.
+- One runner per project.
+- Never write a test that cannot fail.
+- Never change behavior to make a backfilled test pass.
+- Setup adds one example test, not a suite.
+
+## 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/try/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: try
+summary: write the human walkthrough for reviewing the work yourself
+description: "Generate the manual walkthrough for the current or most recently completed work: what to start, where to go, what to click or run, what to expect, and what would count as wrong. Read-only, and written for a person rather than an agent. $complete emits one for every completed item automatically, so this is for asking again later or for work still in progress. Use when the user runs $try, asks how to see or test a change themselves, asks where to click, or wants a manual review path."
+---
+
+# try - the human review path
+
+$check is the agent proving the work. This is you checking it yourself, which is a
+different thing and catches different problems: the ones that are technically correct and
+still wrong.
+
+Read-only. It does not run the project unless asked to.
+
+## Step 1 - find the work
+
+Use `religion/context/current-work.md` when something is in progress. When it is the stub,
+use the most recent archive under `religion/history/`, and say which one you are describing.
+
+## Step 2 - write the walkthrough
+
+Read the spec's outcomes and the project's declared commands, then write instructions a
+person can follow without knowing how any of it was built.
+
+1. **Start it.** The exact command, and where it will be listening.
+2. **Get there.** The route, the screen, the command, the endpoint. Say how to reach it
+   from a cold start, including any state that has to exist first, such as being signed in
+   or having a record to act on.
+3. **Do the thing.** What to click, type, or run.
+4. **Expect this.** What should happen, concretely enough to disagree with.
+5. **This would be wrong.** The specific failure worth watching for. Skipping this makes
+   the whole walkthrough a confirmation exercise, because someone following instructions
+   tends to see what they were told to expect.
+
+Cover the unhappy paths too when they are quick: the empty state, the error case, what a
+second attempt does.
+
+For a rollback, say how to confirm the removed behavior is gone, and name one unaffected
+path that should still work.
+
+## Step 3 - keep it honest
+
+State any setup that will not be obvious: seed data, environment variables, a service that
+must be running, a browser signed into something.
+
+If a step cannot be described because the work has no observable effect, say so plainly.
+That is worth knowing before completion, not after.
+
+## Rules
+
+- Instructions for a person, never a claim that a person followed them. Generating a
+  walkthrough is not evidence of review.
+- Read-only. Do not start the project, change files, or run anything unless asked.
+- Concrete over complete. Five steps someone will actually follow beat twenty they will not.
+
+## 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/hooks/guard-rendered-output.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/**
+ * Blocks edits to rendered adapter trees inside a source checkout.
+ *
+ * Rendered output is overwritten by the next build, so an edit made there is lost without
+ * warning and the real source stays wrong. Applies only where `src/skills/` exists, which
+ * is what distinguishes a source checkout from an installed project.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+if (!existsSync(path.join(process.cwd(), "src", "skills"))) process.exit(0);
+
+let input = "";
+try {
+  input = readFileSync(0, "utf8");
+} catch {
+  process.exit(0);
+}
+
+let file = "";
+try {
+  const payload = JSON.parse(input);
+  file = payload?.tool_input?.file_path ?? "";
+} catch {
+  process.exit(0);
+}
+
+if (!file) process.exit(0);
+
+const relative = path.relative(process.cwd(), file);
+const rendered = [".claude/skills", ".agents/skills", "template/"];
+
+if (rendered.some((prefix) => relative.startsWith(prefix))) {
+  const source = relative.replace(/^template\//, "").replace(/^\.(claude|agents)\/skills/, "src/skills");
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason:
+        `Blocked: ${relative} is generated output and the next build overwrites it.\n\n` +
+        `Edit the source instead (likely ${source}), then run \`npm run build:skills\`.`
+    }
+  }));
+  process.exit(0);
+}
+
+process.exit(0);

package/template/.claude/hooks/guard-tier-one.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * Blocks first-tier commands that were not approved in the conversation.
+ *
+ * This enforces nothing new. The Authority section of the project entry file already says
+ * merging, pushing, deploying, publishing, deleting data, and rewriting history each need
+ * a fresh yes. The hook exists because that rule is prose, and prose can be forgotten
+ * mid-task. It is a safety net for one tool, never a rule of its own.
+ */
+
+import { readFileSync } from "node:fs";
+
+const PATTERNS = [
+  { re: /\bgit\s+push\b/, what: "pushing to a remote" },
+  { re: /\bgit\s+merge\b/, what: "merging" },
+  { re: /\bgit\s+(?:rebase|reset\s+--hard|filter-branch)\b/, what: "rewriting history" },
+  { re: /\bgit\s+commit\b.*--amend\b/, what: "rewriting a commit" },
+  { re: /\bnpm\s+publish\b|\bpnpm\s+publish\b|\byarn\s+publish\b/, what: "publishing" },
+  { re: /\b(?:vercel|railway|render)\s+(?:deploy|up)\b/, what: "deploying" },
+  { re: /\brm\s+-[a-z]*r[a-z]*f?\b/, what: "recursive deletion" }
+];
+
+let input = "";
+try {
+  input = readFileSync(0, "utf8");
+} catch {
+  process.exit(0);
+}
+
+let command = "";
+try {
+  const payload = JSON.parse(input);
+  command = payload?.tool_input?.command ?? "";
+} catch {
+  process.exit(0);
+}
+
+if (!command) process.exit(0);
+
+// A force flag makes an otherwise ordinary command destructive, so it is always first tier.
+const forced = /--force\b|(?:^|\s)-f(?:\s|$)/.test(command) && /\bgit\s+push\b/.test(command);
+
+for (const { re, what } of PATTERNS) {
+  if (!re.test(command)) continue;
+
+  const reason =
+    `Blocked: ${what}${forced ? " (forced)" : ""} is a first-tier action.\n\n` +
+    `The Authority section of this project's entry file requires an explicit yes for it, ` +
+    `in this conversation, every time. No mode or setting grants it.\n\n` +
+    `If the user has already approved this exact action, say so and ask them to confirm ` +
+    `once more, then proceed. Do not edit or disable this hook to get past it.`;
+
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "ask",
+      permissionDecisionReason: reason
+    }
+  }));
+  process.exit(0);
+}
+
+process.exit(0);

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

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * Regenerates the handoff file at the end of a turn.
+ *
+ * The handoff answers "where does this sit, what should I read, what should I watch" for
+ * whoever picks the project up next. It is derived from the other state files, so a hook
+ * can produce it and the model cannot forget to. Losing it costs nothing.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+const STATE = "religion";
+const root = process.cwd();
+const contextDir = path.join(root, STATE, "context");
+if (!existsSync(contextDir)) process.exit(0);
+
+const read = (file) => {
+  try {
+    return readFileSync(path.join(root, STATE, file), "utf8");
+  } catch {
+    return "";
+  }
+};
+
+const buildPlan = read("build-plan.md");
+const work = read("context/current-work.md");
+const findings = read("context/findings.md");
+
+const done = (buildPlan.match(/^\s*- \[x\]/gim) ?? []).length;
+const open = (buildPlan.match(/^\s*- \[ \]/gim) ?? []).length;
+const nextItem = buildPlan.match(/^\s*- \[ \]\s*(.+)$/im)?.[1]?.trim();
+
+const active = !/_Nothing in progress\./.test(work) && work.trim().length > 0;
+const title = work.match(/^#\s+(.+)$/m)?.[1]?.trim();
+const stepsDone = (work.match(/^\s*- \[x\]/gim) ?? []).length;
+const stepsLeft = (work.match(/^\s*- \[ \]/gim) ?? []).length;
+const nextStep = work.match(/^\s*- \[ \]\s*(?:\*\*)?(.+?)(?:\*\*)?\s*-/im)?.[1]?.trim();
+
+const blocking = [...findings.matchAll(/^### (F-\d+) \[(P[01])\] (open|fixed) - (.+)$/gim)]
+  .map((m) => `${m[1]} [${m[2]}] ${m[3]} - ${m[4]}`);
+
+const lines = [
+  "# Handoff",
+  "",
+  "> **Generated file.** Rewritten at the end of each turn from the other state files.",
+  "> Nothing reads it to make a decision; it is how a person or a fresh session catches up.",
+  "",
+  "## Where the work sits",
+  ""
+];
+
+if (active) {
+  lines.push(
+    `**${title ?? "Active work"}** is in progress: ${stepsDone} step(s) done, ${stepsLeft} to go.`,
+    ...(nextStep ? [`Next step: ${nextStep}.`] : []),
+    ""
+  );
+} else {
+  lines.push("Nothing in progress.", "");
+}
+
+lines.push(
+  `Plan: ${done} of ${done + open} item(s) complete.` + (nextItem ? ` Next up: ${nextItem}` : ""),
+  ""
+);
+
+if (blocking.length > 0) {
+  lines.push("## Blocking findings", "", ...blocking.map((f) => `- ${f}`), "",
+    "These prevent completion until repaired and re-reviewed.", "");
+}
+
+lines.push(
+  "## Read first",
+  "",
+  `1. \`${STATE}/context/current-work.md\` - the active spec and which steps are done`,
+  `2. \`${STATE}/context/project-overview.md\` - the source of truth`,
+  `3. \`${STATE}/build-plan.md\` - what is done and what is next`,
+  ""
+);
+
+writeFileSync(path.join(contextDir, "handoff.md"), lines.join("\n") + "\n");
+process.exit(0);