create-religion 0.1.0

package/dist/lib/install.js

@@ -0,0 +1,170 @@
+/**
+ * Installing and updating the workflow files.
+ *
+ * The rule that shapes all of this: files the project owns are seeded once and never
+ * touched again, while files the workflow owns are managed and can be updated. Getting
+ * that backwards destroys someone's plans on an update, so the two sets are kept explicit
+ * rather than inferred from paths at the point of use.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { exists, STATE_DIR } from "./paths.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"] },
+    copilot: { label: "GitHub Copilot", trees: [".agents/skills"], entry: ["AGENTS.md"] },
+    opencode: { label: "OpenCode", trees: [".agents/skills"], entry: ["AGENTS.md"] }
+};
+const MANIFEST = path.join(STATE_DIR, ".state", "manifest.json");
+export function hash(contents) {
+    return crypto.createHash("sha256").update(contents).digest("hex").slice(0, 16);
+}
+/** Managed files are the workflow's own; everything under the state directory is the project's. */
+export function isManaged(relative) {
+    return !relative.startsWith(`${STATE_DIR}/`);
+}
+export async function planInstall(templateRoot, target, adapters, previous) {
+    const wanted = wantedPaths(adapters);
+    const plan = [];
+    for (const relative of await walk(templateRoot)) {
+        if (!wanted(relative))
+            continue;
+        const destination = path.join(target, relative);
+        const source = await fs.readFile(path.join(templateRoot, relative));
+        if (!(await exists(destination))) {
+            plan.push({ relative, action: "create" });
+            continue;
+        }
+        // State files hold the project's real work. Once present they are never rewritten.
+        if (!isManaged(relative)) {
+            plan.push({ relative, action: "seed-skip" });
+            continue;
+        }
+        const current = await fs.readFile(destination);
+        if (hash(current) === hash(source)) {
+            plan.push({ relative, action: "unchanged" });
+            continue;
+        }
+        // A managed file that differs is only safe to replace when it still matches what was
+        // 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" });
+    }
+    return plan;
+}
+export async function applyInstall(templateRoot, target, plan, options) {
+    const written = [];
+    const conflicts = [];
+    const backups = [];
+    for (const entry of plan) {
+        if (entry.action === "unchanged" || entry.action === "seed-skip")
+            continue;
+        if (entry.action === "conflict" && !options.force) {
+            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);
+            await fs.mkdir(path.dirname(backup), { recursive: true });
+            await fs.copyFile(destination, backup);
+            backups.push(entry.relative);
+        }
+        await fs.mkdir(path.dirname(destination), { recursive: true });
+        await fs.copyFile(path.join(templateRoot, entry.relative), destination);
+        written.push(entry.relative);
+    }
+    return { written, conflicts, backups };
+}
+/**
+ * Records what was *installed*, not what is currently on disk.
+ *
+ * This distinction is the whole mechanism. The manifest answers "is this file still the one
+ * we shipped, or did someone edit it", so it must hold the template's hash. Hashing the
+ * working copy instead records a local edit as though it were the installed version, and
+ * the next update then treats that edit as stale and overwrites it. The protection would
+ * work exactly once.
+ *
+ * A file left alone as a conflict keeps its previous entry, since that is still the last
+ * version actually installed there.
+ */
+export async function writeManifest(target, version, adapters, templateRoot, previous, skipped) {
+    const managed = {};
+    const untouched = new Set(skipped);
+    for (const relative of await walk(templateRoot, wantedPaths(adapters))) {
+        if (!isManaged(relative))
+            continue;
+        if (untouched.has(relative)) {
+            const recorded = previous?.managed[relative];
+            if (recorded)
+                managed[relative] = recorded;
+            continue;
+        }
+        managed[relative] = hash(await fs.readFile(path.join(templateRoot, relative)));
+    }
+    const manifest = { schemaVersion: 1, version, adapters: [...adapters], managed };
+    const file = path.join(target, MANIFEST);
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, JSON.stringify(manifest, null, 2) + "\n");
+}
+/**
+ * Wires the hooks into Claude Code's settings.
+ *
+ * Only when there are no settings yet. A project's existing settings are its own, and
+ * merging into them blind is how a tool destroys configuration it did not write. When they
+ * exist, the caller is told to wire it manually and shown where the template is.
+ */
+export async function wireHooks(target) {
+    const template = path.join(target, STATE_DIR, ".state", "settings-template.json");
+    const settings = path.join(target, ".claude", "settings.json");
+    if (!(await exists(template)))
+        return "no-template";
+    if (await exists(settings))
+        return "exists";
+    await fs.mkdir(path.dirname(settings), { recursive: true });
+    await fs.copyFile(template, settings);
+    return "written";
+}
+export async function readManifest(target) {
+    try {
+        return JSON.parse(await fs.readFile(path.join(target, MANIFEST), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function wantedPaths(adapters) {
+    const prefixes = new Set();
+    for (const adapter of adapters) {
+        for (const tree of ADAPTERS[adapter].trees)
+            prefixes.add(tree);
+        for (const entry of ADAPTERS[adapter].entry)
+            prefixes.add(entry);
+    }
+    prefixes.add(STATE_DIR);
+    return (relative) => [...prefixes].some((p) => relative === p || relative.startsWith(`${p}/`));
+}
+async function walk(dir, filter, prefix = "") {
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const files = [];
+    for (const entry of entries) {
+        if (entry.name === "node_modules" || entry.name === ".git")
+            continue;
+        const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            files.push(...(await walk(path.join(dir, entry.name), filter, relative)));
+        }
+        else if (!filter || filter(relative)) {
+            files.push(relative);
+        }
+    }
+    return files.sort();
+}

package/dist/lib/paths.js

@@ -0,0 +1,40 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+export const STATE_DIR = "religion";
+/**
+ * Walks up from `start` to the nearest directory holding the state directory.
+ *
+ * Commands are routinely run from a subdirectory, and a tool that only works from the
+ * repository root is a tool people stop using.
+ */
+export async function findProjectRoot(start) {
+    let current = path.resolve(start);
+    for (;;) {
+        if (await exists(path.join(current, STATE_DIR, "config.json")))
+            return current;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+export function statePath(root, ...parts) {
+    return path.join(root, STATE_DIR, ...parts);
+}
+export async function exists(target) {
+    try {
+        await fs.stat(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function readIfPresent(file) {
+    try {
+        return await fs.readFile(file, "utf8");
+    }
+    catch {
+        return null;
+    }
+}

package/dist/lib/state.js

@@ -0,0 +1,117 @@
+/**
+ * Parsers for the state files.
+ *
+ * Each file has one parser and one shape. These are deliberately tolerant: a half-written
+ * plan or a hand-edited ledger should degrade into partial information, never an exception,
+ * because the commands that use this are how someone finds out what is wrong.
+ */
+import crypto from "node:crypto";
+import { readIfPresent, statePath } from "./paths.js";
+const CHECKBOX = /^(\s*)- \[( |x|X)\]\s*(.*)$/;
+export function parsePlan(source) {
+    if (!source)
+        return [];
+    // The shipped template explains the format with worked examples, which are checkboxes
+    // too. Reading the whole file counts those as real work. When a `## Plan` heading exists,
+    // only what follows it is the plan; the guidance above it is documentation.
+    const planSection = /^##\s+Plan\s*$/im.exec(source);
+    const body = planSection ? source.slice(planSection.index + planSection[0].length) : source;
+    const items = [];
+    for (const line of body.split(/\r?\n/)) {
+        const match = CHECKBOX.exec(line);
+        if (!match)
+            continue;
+        const body = (match[3] ?? "").trim();
+        // The template ships two placeholder items so the shape is visible. They are not work.
+        if (/^\d+\.\s+\*\*(Feature one|Feature two)\*\*/.test(body))
+            continue;
+        items.push({
+            number: /^([\dA-Za-z]+)\./.exec(body)?.[1] ?? null,
+            title: body.replace(/^[\dA-Za-z]+\.\s*/, "").replace(/\*\*/g, ""),
+            done: (match[2] ?? " ").toLowerCase() === "x",
+            depth: Math.floor((match[1] ?? "").length / 2)
+        });
+    }
+    return items;
+}
+export function parseWork(source) {
+    const empty = {
+        active: false,
+        title: null,
+        type: null,
+        status: null,
+        stepsDone: 0,
+        stepsTotal: 0,
+        nextStep: null
+    };
+    if (!source || /_Nothing in progress\./.test(source))
+        return empty;
+    const steps = [...source.matchAll(/^\s*- \[( |x|X)\]\s*(?:\*\*)?(.+?)(?:\*\*)?(?:\s+-\s|$)/gim)];
+    const done = steps.filter((s) => (s[1] ?? " ").toLowerCase() === "x").length;
+    return {
+        active: true,
+        title: /^#\s+(.+)$/m.exec(source)?.[1]?.trim() ?? null,
+        type: /^\*\*Type:\*\*\s*(.+)$/m.exec(source)?.[1]?.trim() ?? null,
+        status: /^\*\*Status:\*\*\s*(.+)$/m.exec(source)?.[1]?.trim() ?? null,
+        stepsDone: done,
+        stepsTotal: steps.length,
+        nextStep: steps.find((s) => (s[1] ?? " ").toLowerCase() !== "x")?.[2]?.trim() ?? null
+    };
+}
+export function parseFindings(source) {
+    if (!source)
+        return [];
+    return [...source.matchAll(/^###\s+(F-\d+)\s+\[(P[0-3])\]\s+(\w+)\s+-\s+(.+)$/gim)].map((m) => ({
+        id: m[1],
+        severity: m[2],
+        status: m[3],
+        title: (m[4] ?? "").trim()
+    }));
+}
+export function parseOpenQuestions(overview) {
+    if (!overview)
+        return [];
+    const section = /##\s+Open questions\s*\n([\s\S]*?)(?:\n##\s|$)/i.exec(overview);
+    if (!section?.[1])
+        return [];
+    return [...section[1].matchAll(/^-\s+\*\*(.+?)\*\*/gim)].map((m) => (m[1] ?? "").trim());
+}
+/** The stamp the overview carries, and the hash the current plans produce. */
+export function overviewHash(projectPlan, buildPlan) {
+    return crypto.createHash("sha256").update(projectPlan).update(buildPlan).digest("hex").slice(0, 16);
+}
+export async function readProjectState(root) {
+    const [configRaw, projectPlan, buildPlan, work, findings, overview] = await Promise.all([
+        readIfPresent(statePath(root, "config.json")),
+        readIfPresent(statePath(root, "project-plan.md")),
+        readIfPresent(statePath(root, "build-plan.md")),
+        readIfPresent(statePath(root, "context", "current-work.md")),
+        readIfPresent(statePath(root, "context", "findings.md")),
+        readIfPresent(statePath(root, "context", "project-overview.md"))
+    ]);
+    let config = null;
+    let configValid = true;
+    if (configRaw !== null) {
+        try {
+            config = JSON.parse(configRaw);
+        }
+        catch {
+            configValid = false;
+        }
+    }
+    const stamped = overview ? /source-hash\s+([0-9a-f]{16})/.exec(overview)?.[1] ?? null : null;
+    const generated = overview !== null && !/_Not generated yet\./.test(overview);
+    return {
+        root,
+        config,
+        configValid,
+        plan: parsePlan(buildPlan),
+        work: parseWork(work),
+        findings: parseFindings(findings),
+        overviewPresent: generated,
+        overviewFresh: !generated || stamped === null
+            ? null
+            : stamped === overviewHash(projectPlan ?? "", buildPlan ?? ""),
+        openQuestions: parseOpenQuestions(overview)
+    };
+}

package/dist/lib/status.js

@@ -0,0 +1,88 @@
+/**
+ * What the project's state means, and the one action that follows from it.
+ *
+ * The next action is the point. A report that lists five things someone could do has not
+ * answered the question they asked, which is almost always "what now".
+ */
+export function computeStatus(state) {
+    const leaves = state.plan.filter((item, index) => state.plan[index + 1] === undefined || state.plan[index + 1].depth <= item.depth);
+    const done = leaves.filter((i) => i.done).length;
+    const nextItem = leaves.find((i) => !i.done) ?? null;
+    const byStatus = {};
+    for (const finding of state.findings) {
+        byStatus[finding.status] = (byStatus[finding.status] ?? 0) + 1;
+    }
+    const blocking = state.findings
+        .filter((f) => (f.severity === "P0" || f.severity === "P1") && (f.status === "open" || f.status === "fixed"))
+        .map((f) => `${f.id} [${f.severity}] ${f.status} - ${f.title}`);
+    const warnings = [];
+    if (!state.configValid)
+        warnings.push("config.json does not parse; workflow commands will stop rather than guess");
+    if (state.overviewFresh === false)
+        warnings.push("the plans changed after the overview was generated");
+    if (state.openQuestions.length > 0) {
+        warnings.push(`open question(s) in the overview: ${state.openQuestions.join(", ")}`);
+    }
+    if (state.work.active && state.work.stepsTotal > 0 && state.work.stepsDone === state.work.stepsTotal &&
+        state.work.status !== "verified") {
+        warnings.push("every step is ticked but the work is not verified");
+    }
+    return {
+        schemaVersion: 1,
+        next: nextAction(state, nextItem?.title ?? null, blocking.length > 0),
+        plan: { done, total: leaves.length, nextItem: nextItem?.title ?? null },
+        work: state.work,
+        findings: { total: state.findings.length, blocking, byStatus },
+        overview: { present: state.overviewPresent, fresh: state.overviewFresh },
+        warnings
+    };
+}
+function nextAction(state, nextItem, blocked) {
+    if (!state.configValid)
+        return { command: "doctor", because: "configuration cannot be parsed" };
+    if (!state.overviewPresent)
+        return { command: "overview", because: "no source of truth has been generated" };
+    if (state.overviewFresh === false)
+        return { command: "overview", because: "the plans have changed since it was generated" };
+    if (state.work.active) {
+        if (blocked)
+            return { command: "audit", because: "a blocking finding must be re-reviewed before completion" };
+        if (state.work.stepsDone < state.work.stepsTotal) {
+            return { command: "implement", because: `step ${state.work.stepsDone + 1} of ${state.work.stepsTotal} is next` };
+        }
+        if (state.work.status !== "verified")
+            return { command: "check", because: "every step is built but nothing has proved it" };
+        return { command: "complete", because: "the work is built and verified" };
+    }
+    if (nextItem)
+        return { command: "feature", because: `next in the plan: ${nextItem}` };
+    if (state.plan.length === 0)
+        return { command: "overview", because: "the build plan has no items yet" };
+    return { command: "release", because: "the build plan is complete" };
+}
+export function renderStatus(status, cmd = "/") {
+    const out = [];
+    const pct = status.plan.total > 0 ? Math.round((status.plan.done / status.plan.total) * 100) : 0;
+    out.push(`Next:     ${cmd}${status.next.command}  (${status.next.because})`, "");
+    out.push(status.work.active
+        ? `Active:   ${status.work.title ?? "untitled"} - step ${status.work.stepsDone}/${status.work.stepsTotal}` +
+            (status.work.status ? ` (${status.work.status})` : "")
+        : "Active:   nothing in progress");
+    out.push(`Plan:     ${status.plan.done}/${status.plan.total} complete (${pct}%)`);
+    if (status.findings.total === 0) {
+        out.push("Findings: none");
+    }
+    else {
+        const summary = Object.entries(status.findings.byStatus).map(([k, v]) => `${v} ${k}`).join(", ");
+        out.push(`Findings: ${summary}`);
+        for (const item of status.findings.blocking)
+            out.push(`          BLOCKING  ${item}`);
+    }
+    out.push(`Overview: ${!status.overview.present ? "not generated" : status.overview.fresh === false ? "stale" : "current"}`);
+    if (status.warnings.length > 0) {
+        out.push("", "Warnings:");
+        for (const warning of status.warnings)
+            out.push(`  - ${warning}`);
+    }
+    return out.join("\n");
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "create-religion",
+  "version": "0.1.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",
+  "type": "module",
+  "homepage": "https://github.com/foo-stack/religion#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/foo-stack/religion.git",
+    "directory": "packages/create-religion"
+  },
+  "bugs": { "url": "https://github.com/foo-stack/religion/issues" },
+  "keywords": [
+    "ai",
+    "ai-coding",
+    "agent",
+    "claude",
+    "claude-code",
+    "codex",
+    "copilot",
+    "opencode",
+    "spec-driven-development",
+    "context-engineering",
+    "workflow",
+    "scaffold"
+  ],
+  "bin": {
+    "create-religion": "dist/bin/religion.js",
+    "religion": "dist/bin/religion.js"
+  },
+  "files": ["dist/", "template/", "README.md", "LICENSE"],
+  "engines": { "node": ">=20" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm --prefix ../.. run build && npm run build"
+  },
+  "publishConfig": { "access": "public" }
+}

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

@@ -0,0 +1,169 @@
+---
+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."
+---
+
+# audit - review the code, and record what you find
+
+$check proves the work behaves as promised. This skill reviews the code itself.
+
+It changes nothing except the findings ledger. It never edits source, installs anything,
+commits, merges, or starts repair work.
+
+## Input
+
+Scope and lens are separate, and may appear in either order: `$audit security current`,
+`$audit src/auth tests`.
+
+**Scope**, defaulting to `current` when work is active, else `changed` when the tree is
+dirty, else `full`:
+
+- `current` - the active spec, everything the work item has changed so far, and the code
+  around it that the change affects
+- `changed` - staged, unstaged, and untracked source, plus nearby code
+- `full` - all project-owned source, tests, and configuration, excluding dependencies,
+  generated files, build output, caches, vendored code, and minified assets
+- a path - that area, plus the tests and callers needed to understand it
+
+**Lens**, defaulting to all four:
+
+- `quality` - duplication, dead code, unreachable paths, oversized modules, abstractions
+  that do not pay for themselves, inconsistency, drift from the project's standards
+- `security` - missing authorization, client-controlled ownership, injection, unsafe
+  parsing, data exposure, secret handling, insecure defaults, trust-boundary mistakes
+- `performance` - repeated queries and network calls, unnecessary rendering, blocking work
+  on hot paths, unbounded loops and collections, memory growth, oversized payloads,
+  missing pagination, unsafe concurrency
+- `tests` - important logic with no coverage, weak assertions, tests that only mirror the
+  implementation, excessive mocking, shared state, order or time dependence, skipped or
+  focused tests, swallowed failures
+
+State the scope and lens you chose before reviewing.
+
+## Step 1 - gather context
+
+Read the project overview, the coding standards, the active spec, the existing findings
+ledger (for identifiers and statuses), the configuration, and the relevant source.
+
+For `current`, resolve the comparison base without touching the network: a base named by
+the spec or project instructions, else the recorded default branch, else a local `main`
+then `master`. Find the merge base and inspect the committed range through `HEAD`, then add
+staged, unstaged, and untracked work. If no reliable base exists, say so and review the
+spec plus local changes, without claiming committed work was covered.
+
+For `full`, state the excluded paths before reviewing, so generated or third-party code
+does not consume the review.
+
+## Step 2 - run the signals that exist
+
+Use only commands the project already has. Do not install tools, and do not fetch.
+
+Lint and typecheck when relevant; the test command for the tests lens or to validate a
+suspected risk; the build when the lens needs compilation evidence. A useful command that
+does not exist is a gap worth reporting, not a reason to add one.
+
+## Step 3 - review, one subagent per lens
+
+Run each selected lens as its own subagent over the resolved scope. They read code and
+**return** findings; they never write. This skill merges what comes back, assigns
+identifiers, and performs the single write in Step 4. Parallel reviewers cannot race a
+file that only one of them writes.
+
+Give each subagent the scope, the file list, the standards, and its own lens only. A lens
+that wanders into another lens produces duplicates that then have to be reconciled.
+
+**The ledger never scopes the review.** Review the code fresh, then record what was found.
+Working from the open findings as a checklist and verifying only those is the exact failure
+the ledger exists to prevent: a repair can introduce a defect no existing entry points at.
+
+Ground every finding in reachable code. Prefer a short list of real findings to a long list
+of guesses, and do not report style differences that are merely different.
+
+Do not broaden a focused pass because another lens looks interesting. If an obvious P0
+appears outside the selected lens, record it as an out-of-lens critical risk, but do not
+start searching that lens.
+
+If a possible secret appears, never quote its value, paste the matching line, or include
+raw output containing it. Report the redacted category, file, line, risk, and remediation.
+
+## Step 4 - write the ledger
+
+`religion/context/findings.md` is the durable record. Chat does not survive a cleared
+context; this does. Create it with a `# Findings` heading if it is missing.
+
+One block per finding. The header line is the machine-readable part and keeps this exact
+shape; the prose below it is for people.
+
+    ### F-03 [P0] open - Retained auth volumes carry the run label
+
+    **File:** ops/compose.yaml:86
+    **Found:** 2026-09-04 by audit (scope: current; lens: security)
+    **Why it matters:** ...
+    **Suggested fix:** ...
+    **Resolution:**
+
+Identifiers are sequential within the ledger, one past the highest present, never reused
+and never renumbered while their entries live there. Completion archives resolved entries
+under a work-item prefix, and that prefixed form is the permanent reference.
+
+| Status | Meaning | Blocks completion at P0/P1 |
+| --- | --- | --- |
+| `unverified` | Suspected, no confirming evidence yet | No |
+| `open` | Confirmed, not yet repaired | Yes |
+| `fixed` | Repaired, not yet re-reviewed | Yes |
+| `closed` | Repaired and re-reviewed against the new code | No |
+| `accepted` | Not fixing, by the user's explicit decision, reason recorded | No |
+| `invalid` | Re-examination proved it wrong, evidence recorded | No |
+
+After reviewing:
+
+- Append each new confirmed finding as `open`.
+- Record a lead worth tracking as `unverified`. It never gates anything.
+- Update entries this pass re-examined, noting the evidence in **Resolution**.
+- Move `fixed` to `closed` only when all three hold: this pass covered the finding's file,
+  re-examining the repaired code confirmed the defect is gone and nothing worse replaced
+  it, and the report names it as closed. An unrelated new problem in the same file gets its
+  own entry. Never close implicitly.
+- Set `accepted` only on the user's explicit decision, with their reason. Never on their
+  behalf.
+- Set `invalid` only when re-examination shows the finding was wrong, with that evidence.
+  It is a review verdict, never a shortcut past a gate.
+
+`fixed` blocking completion is deliberate: a repair is done when a review has looked at the
+result, not when the code changed.
+
+## Step 5 - report
+
+Findings first, ordered by severity, using the identifiers just assigned.
+
+Severity: **P0** data loss, a security break, or code that cannot ship. **P1** a likely bug,
+a broken contract, a missing guard. **P2** a maintainability problem worth fixing before
+the work closes. **P3** a small cleanup or follow-up.
+
+P0 and P1 require a concrete code path, a violated contract or boundary, a failing command,
+or reproducible behavior. Incomplete evidence goes under **Unverified risks** with what is
+missing, never presented as a confirmed high-severity finding.
+
+Then report: ledger changes by identifier; commands run and their results; the scope and
+lens chosen; the commit range for `current`; the paths reviewed and excluded; checks that
+could not run; and a suggested repair order.
+
+A focused lens is not a broad review. Say what was not reviewed, and never imply the
+omitted lenses passed. For `full`, say whether coverage was complete or partial.
+
+## Rules
+
+- The ledger is the only file this skill writes.
+- The ledger reports status; it never defines what the review looks at.
+- Never reproduce a secret or sensitive value.
+- Ground every finding in a file and line where possible.
+- Recommend the smallest fix that removes the risk, not a rewrite.
+- Respect the project's existing patterns over generic advice.
+- The goal is code that is understandable, consistent, tested where it matters, and safe to
+  keep building on. Not perfection.
+
+## Formatting
+
+Match the conventions in `religion/context/ai-interaction.md`: concise, scannable
+markdown, lists for enumerations and tables for matrices rather than dense paragraphs.