create-religion 1.2.0 → 1.4.0

package/dist/lib/paths.js

@@ -1,6 +1,8 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 export const STATE_DIR = "religion";
+/** Where the adapters install their skills, one directory per skill. */
+export const SKILL_TREES = [".claude/skills", ".agents/skills"];
 /**
  * Walks up from `start` to the nearest directory holding the state directory.
  *
@@ -38,3 +40,19 @@ export async function readIfPresent(file) {
         return null;
     }
 }
+/** The skill names installed in any tree, read from the directories rather than trusted from a file. */
+export async function installedSkills(root) {
+    const names = new Set();
+    for (const tree of SKILL_TREES) {
+        try {
+            for (const entry of await fs.readdir(path.join(root, tree), { withFileTypes: true })) {
+                if (entry.isDirectory())
+                    names.add(entry.name);
+            }
+        }
+        catch {
+            // A tree that is not installed contributes nothing.
+        }
+    }
+    return names;
+}

package/dist/lib/settings.js

@@ -0,0 +1,156 @@
+/**
+ * Every setting in the configuration reference, with what it accepts.
+ *
+ * `doctor`, the surface record and the verification suite read this one table, and the
+ * verification suite holds it to `docs/architecture/config.md`, so the reference, the shipped
+ * defaults and the check cannot disagree without a failing check saying so.
+ */
+const prefix = (value, summary) => ({ kind: "prefix", default: value, summary });
+export const SETTINGS = {
+    schemaVersion: { kind: "integer", min: 1, max: 1, default: 1, summary: "The format of this file." },
+    "workflow.stepReview": {
+        kind: "enum", values: ["every", "item"], default: "every",
+        summary: "When implementation stops for review: after every step, or once with the whole item."
+    },
+    "workflow.parallelSteps": {
+        kind: "boolean", default: false,
+        summary: "Whether steps a spec marks as independent build together as one reviewed wave."
+    },
+    "git.mode": {
+        kind: "enum", values: ["trunk", "branch-per-item", "pull-request"], default: "trunk",
+        summary: "Where work lands: the branch you are on, a branch merged per item, or a pull request per item."
+    },
+    "git.checkpoints": {
+        kind: "enum", values: ["none", "every-step", "squash"], default: "every-step",
+        summary: "What happens to each step's work: one commit at completion, a commit per step, or per-step commits squashed at completion."
+    },
+    "git.featureBranchPrefix": prefix("feature/", "The prefix of a feature's branch, outside trunk mode."),
+    "git.fixBranchPrefix": prefix("fix/", "The prefix of a fix's branch, outside trunk mode."),
+    "git.rollbackBranchPrefix": prefix("rollback/", "The prefix of a rollback's branch, outside trunk mode."),
+    "git.refactorBranchPrefix": prefix("refactor/", "The prefix of a refactor campaign's branch, outside trunk mode."),
+    "git.integrationBranchPrefix": prefix("auto/", "The prefix of the branch an automated run lands every item on, under pull-request mode."),
+    "verification.logicTests": {
+        kind: "enum", values: ["when-configured", "required"], default: "when-configured",
+        summary: "Whether a logic change needs passing tests only when a test command is declared, or always."
+    },
+    "verification.uiEvidence": {
+        kind: "enum", values: ["when-available", "required"], default: "when-available",
+        summary: "Whether an interface outcome needs browser evidence when it can be had, or always."
+    },
+    "qualityGates.audit": {
+        kind: "enum", values: ["manual", "when-sensitive", "always"], default: "when-sensitive",
+        summary: "When the read-only review runs on its own: never, for sensitive work, or for every item."
+    },
+    "qualityGates.check": {
+        kind: "enum", values: ["manual", "when-behavioral", "always"], default: "when-behavioral",
+        summary: "When the outside proof runs on its own: never, when an outcome needs observed behaviour, or for every item."
+    },
+    "auto.maxItems": {
+        kind: "integer", min: 1, nullable: true, default: null,
+        summary: "How many items one automated run may complete; null for no limit."
+    },
+    "auto.maxRepairAttempts": {
+        kind: "integer", min: 0, max: 10, default: 2,
+        summary: "How many times an automated run tries to repair one finding before it stops and reports."
+    },
+    "auto.finalAudit": { kind: "boolean", default: false, summary: "Whether an automated run ends with one review across everything it produced." },
+    "security.blockInjection": {
+        kind: "boolean", default: false,
+        summary: "Whether content carrying three or more injection signatures is blocked, rather than read with a warning."
+    },
+    "refactor.maxFileLines": { kind: "integer", min: 1, default: 400, summary: "The file length the structure lens of a refactor survey measures against." },
+    "refactor.maxFunctionLines": { kind: "integer", min: 1, default: 50, summary: "The function length the structure lens of a refactor survey measures against." }
+};
+const PREFIX = /^[a-z0-9][a-z0-9._/-]*\/$/;
+// What git refuses in a branch name, checked per path component of the prefix.
+const BAD_COMPONENT = (part) => part === "" || part.startsWith(".") || part.endsWith(".lock") || part.includes("..");
+/** The reference's Values and Default cells for a setting, as `docs/architecture/config.md` writes them. */
+export function referenceCells(setting) {
+    const code = (value) => "`" + String(value) + "`";
+    const values = setting.kind === "enum"
+        ? setting.values.map(code).join(", ")
+        : setting.kind === "boolean"
+            ? "`true`, `false`"
+            : setting.kind === "prefix"
+                ? "lowercase prefix ending in `/`"
+                : setting.min === setting.max
+                    ? code(setting.min)
+                    : (setting.min === 1 && setting.max === undefined ? "positive integer" : `integer from ${setting.min} through ${setting.max}`) +
+                        (setting.nullable ? ", or `null` for no limit" : "");
+    return { values, default: code(setting.default) };
+}
+/** What each setting present in `config` gets wrong, one sentence each. Absent settings take their default. */
+export function settingProblems(config) {
+    if (config === null || typeof config !== "object" || Array.isArray(config))
+        return ["not an object"];
+    const problems = [];
+    const sections = new Set(Object.keys(SETTINGS).filter((k) => k.includes(".")).map((k) => k.split(".")[0]));
+    for (const section of sections) {
+        const value = config[section];
+        if (value !== undefined && (value === null || typeof value !== "object" || Array.isArray(value))) {
+            problems.push(`${section} is ${JSON.stringify(value)}, expected an object of settings`);
+        }
+    }
+    for (const [key, setting] of Object.entries(SETTINGS)) {
+        const value = key.split(".").reduce((node, part) => (node && typeof node === "object" && !Array.isArray(node) ? node[part] : undefined), config);
+        if (value === undefined)
+            continue;
+        const wanted = expected(setting, value);
+        if (wanted)
+            problems.push(`${key} is ${JSON.stringify(value)}, expected ${wanted}`);
+    }
+    return problems;
+}
+/** What would have been accepted, or null when the value is fine. */
+function expected(setting, value) {
+    switch (setting.kind) {
+        case "enum":
+            return typeof value === "string" && setting.values.includes(value) ? null : `one of ${setting.values.join(", ")}`;
+        case "boolean":
+            return typeof value === "boolean" ? null : "true or false";
+        case "prefix":
+            return typeof value === "string" && PREFIX.test(value) && !value.slice(0, -1).split("/").some(BAD_COMPONENT)
+                ? null
+                : "a lowercase prefix ending in /";
+        case "integer": {
+            if (value === null && setting.nullable)
+                return null;
+            const ok = Number.isInteger(value) && value >= setting.min && (setting.max === undefined || value <= setting.max);
+            if (ok)
+                return null;
+            const range = setting.max === undefined ? `${setting.min} or more` : setting.min === setting.max ? `${setting.min}` : `from ${setting.min} through ${setting.max}`;
+            return `an integer ${range}` + (setting.nullable ? ", or null" : "");
+        }
+    }
+}
+/** Every setting, set or not, with what it means and accepts, then any key the schema does not name. */
+export function describeSettings(config) {
+    const problems = settingProblems(config);
+    const read = (key) => key.split(".").reduce((node, part) => (node && typeof node === "object" && !Array.isArray(node) ? node[part] : undefined), config);
+    const rows = Object.entries(SETTINGS).map(([key, setting]) => {
+        const value = read(key);
+        const cells = referenceCells(setting);
+        return {
+            key,
+            summary: setting.summary,
+            accepts: cells.values,
+            default: cells.default,
+            value: value === undefined ? null : JSON.stringify(value),
+            problem: problems.find((p) => p.startsWith(`${key} is `)) ?? null
+        };
+    });
+    if (config && typeof config === "object" && !Array.isArray(config)) {
+        for (const [section, value] of Object.entries(config)) {
+            const keys = value && typeof value === "object" && !Array.isArray(value) ? Object.keys(value).map((k) => `${section}.${k}`) : [section];
+            for (const key of keys) {
+                if (!SETTINGS[key] && !(key === section && sectionNamed(section))) {
+                    rows.push({ key, summary: null, accepts: null, default: null, value: JSON.stringify(read(key)), problem: "not a setting Religion reads" });
+                }
+            }
+        }
+    }
+    return rows;
+}
+function sectionNamed(section) {
+    return Object.keys(SETTINGS).some((key) => key.startsWith(`${section}.`));
+}

package/dist/lib/state.js

@@ -7,7 +7,71 @@
  */
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
-import { readIfPresent, statePath } from "./paths.js";
+import { installedSkills, readIfPresent, statePath } from "./paths.js";
+/** Item numbers a spike archive says it answered and settled, from `**For:** item N` and `**Settled:** yes`. */
+export function parseSettledSpike(source) {
+    const item = /^\*\*For:\*\*\s*item\s+(\d+[a-z]?)\b/im.exec(source)?.[1]?.toLowerCase();
+    return item && /^\*\*Settled:\*\*\s*yes\b/im.test(source) ? item : null;
+}
+/**
+ * What each unticked item still waits on, and the references that cannot be met at all.
+ * An item waits on an earlier one until that is ticked, and on its spike until one settles it.
+ */
+export function waiting(plan, settled) {
+    const byNumber = new Map();
+    const problems = [];
+    for (const item of plan.filter((i) => i.number)) {
+        if (byNumber.has(item.number))
+            problems.push(`item ${item.number} appears more than once`);
+        else
+            byNumber.set(item.number, item);
+    }
+    const waits = new Map();
+    // A sub-item inherits what its parent waits on: splitting an item does not answer its spike.
+    const parents = [];
+    for (const item of plan) {
+        while (parents.length && parents[parents.length - 1].depth >= item.depth)
+            parents.pop();
+        const inherited = parents.flatMap((p) => (p.number && !p.done ? waits.get(p.number) ?? [] : []));
+        parents.push(item);
+        if (item.done || !item.number)
+            continue;
+        const reasons = [...inherited];
+        for (const n of item.after) {
+            const other = byNumber.get(n);
+            if (!other)
+                problems.push(`item ${item.number} comes after item ${n}, which the plan does not have`);
+            else if (!other.done)
+                reasons.push(`item ${n}`);
+        }
+        if (item.spikeFirst && !settled.has(item.number))
+            reasons.push("a spike");
+        if (reasons.length)
+            waits.set(item.number, [...new Set(reasons)]);
+    }
+    // A cycle never resolves by ticking anything, so it is named once rather than waited on.
+    const seen = new Set();
+    for (const start of byNumber.keys()) {
+        const path = [];
+        const visit = (n) => {
+            if (seen.has(n))
+                return;
+            const at = path.indexOf(n);
+            if (at >= 0) {
+                problems.push(`items ${[...path.slice(at), n].join(" -> ")} wait on each other`);
+                return;
+            }
+            path.push(n);
+            for (const next of byNumber.get(n)?.after ?? [])
+                if (byNumber.has(next) && !byNumber.get(next).done)
+                    visit(next);
+            path.pop();
+            seen.add(n);
+        };
+        visit(start);
+    }
+    return { waits, problems };
+}
 const CHECKBOX = /^(\s*)- \[( |x|X)\]\s*(.*)$/;
 export function parsePlan(source) {
     if (!source)
@@ -26,11 +90,16 @@ export function parsePlan(source) {
         // 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;
+        // A line that only mentions the syntax, in a code span, does not wait on anything.
+        const prose = body.replace(/`[^`]*`/g, "");
+        const after = [...prose.matchAll(/\bafter items? (\d+[a-z]?(?:(?:,\s*(?:and\s+)?|\s+and\s+)\d+[a-z]?)*)/gi)].map((m) => m[1]);
         items.push({
-            number: /^([\dA-Za-z]+)\./.exec(body)?.[1] ?? null,
+            number: /^([\dA-Za-z]+)\./.exec(body)?.[1]?.toLowerCase() ?? null,
             title: body.replace(/^[\dA-Za-z]+\.\s*/, "").replace(/\*\*/g, ""),
             done: (match[2] ?? " ").toLowerCase() === "x",
-            depth: Math.floor((match[1] ?? "").length / 2)
+            depth: Math.floor((match[1] ?? "").length / 2),
+            after: after.flatMap((list) => list.split(/,\s*(?:and\s+)?|\s+and\s+/)).map((n) => n.trim().toLowerCase()).filter(Boolean),
+            spikeFirst: /\bspike first\b/i.test(prose)
         });
     }
     return items;
@@ -71,7 +140,8 @@ function field(source, name) {
 export function parseSpec(source) {
     if (!source || /_Nothing in progress\./.test(source))
         return null;
-    const section = sections(source);
+    // A heading inside a code fence is an example, not a section of the spec.
+    const section = sections(outsideFences(source));
     return {
         title: field(source, "#"),
         type: field(source, "Type"),
@@ -81,7 +151,77 @@ export function parseSpec(source) {
         inScope: bullets(section.get("in scope")),
         outOfScope: bullets(section.get("out of scope")),
         files: bullets(section.get("files and areas")),
-        steps: bullets(section.get("build steps"), true).map(parseStep)
+        steps: bullets(section.get("build steps"), true).map(parseStep),
+        evidence: parseEvidence(section.get("evidence")),
+        ...approval(source)
+    };
+}
+function approval(source) {
+    // An example of the stamp or the section inside a code fence is documentation, not the record.
+    const prose = outsideFences(source);
+    const line = /^\*\*Approved:\*\*.*$/m.exec(prose)?.[0];
+    const stamp = line ? /^\*\*Approved:\*\*\s*(\d{4}-\d{2}-\d{2})\s*,\s*([0-9a-f]{16})\s*$/i.exec(line) : null;
+    const approved = stamp ? { date: stamp[1], hash: stamp[2].toLowerCase() } : null;
+    return {
+        approved,
+        amendments: bullets(sections(prose).get("amendments")),
+        // A stamp line that cannot be read proves nothing, so it counts as drift rather than hiding it.
+        drifted: line !== undefined && (approved === null || approved.hash !== specHash(source))
+    };
+}
+function specState(work) {
+    const spec = parseSpec(work);
+    if (!spec || !work)
+        return { hash: null, approved: null, drifted: false };
+    return { hash: specHash(work), approved: spec.approved?.hash ?? null, drifted: spec.drifted };
+}
+const FENCE = /^\s*(```|~~~)/;
+/** The source with every line inside a ``` or ~~~ fence blanked, so line structure stays but nothing inside is read. */
+function outsideFences(source) {
+    let fenced = false;
+    return source
+        .split("\n")
+        .map((line) => {
+        if (FENCE.test(line)) {
+            fenced = !fenced;
+            return "";
+        }
+        return fenced ? "" : line;
+    })
+        .join("\n");
+}
+/**
+ * The hash of what a spec asks for. Ticks, the status, the stamp, and the Evidence and
+ * Amendments sections change as work proceeds without changing what was approved, so they are
+ * left out; anything else that changes is a change to the spec.
+ */
+export function specHash(source) {
+    const kept = [];
+    let fenced = false;
+    let skipping = false;
+    for (const line of source.replace(/\r\n/g, "\n").split("\n")) {
+        if (FENCE.test(line))
+            fenced = !fenced;
+        else if (!fenced && /^##\s/.test(line))
+            skipping = /^##\s+(evidence|amendments)\s*$/i.test(line);
+        if (skipping)
+            continue;
+        if (!fenced && /^\*\*(Status|Approved):\*\*/.test(line))
+            continue;
+        kept.push((fenced ? line : line.replace(/^(\s*- \[)[xX](\])/, "$1 $2")).replace(/\s+$/, ""));
+    }
+    const text = kept.join("\n").replace(/\s+$/, "");
+    return crypto.createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+function parseEvidence(body) {
+    if (body === undefined)
+        return null;
+    return {
+        stamp: /^Checked .+$/m.exec(body)?.[0].trim() ?? null,
+        entries: bullets(body).map((item) => {
+            const m = /^\*\*(.+?)\*\*\s*-\s*(pass|fail|could not check):?\s*([\s\S]*)$/i.exec(item);
+            return m ? { outcome: m[1].trim(), verdict: m[2].toLowerCase(), detail: m[3].trim() } : { outcome: item, verdict: "unknown", detail: "" };
+        })
     };
 }
 /** Each heading's body, keyed by the lowercased heading; `levels` widens it to `###` too. */
@@ -179,6 +319,95 @@ export function parseInbox(source) {
         text: (m[2] ?? "").trim()
     }));
 }
+const ACTIVITY_STATUSES = new Set(["running", "blocked", "ready", "completed"]);
+const SKILL_NAME = /^[a-z][a-z-]{0,39}$/;
+// The blocked skill's own invocation and plain word arguments, such as `/auto resume`.
+// Anything else in the record could be a shell command dressed up as the next thing to run.
+// The length bound comes first: the repeated group overflows the regex stack on megabytes.
+const RESUME_ARGUMENTS = /^(?: [\w-]+)*$/;
+const RESUME_MAX = 200;
+// A record is written by an agent, so it must not be able to move the cursor, print lines,
+// or reorder the text around it.
+const CONTROL = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu;
+/**
+ * The activity record a running skill writes. Skills write it, so only its named fields are
+ * read, and a record naming a skill that is not installed is not believed at all: whoever can
+ * write the record controls every field in it.
+ */
+export function parseActivity(source, skills) {
+    const none = { recorded: false, command: null, status: null, summary: null, updatedAt: null, resumeCommand: null };
+    if (!source)
+        return none;
+    let record;
+    try {
+        record = JSON.parse(source);
+    }
+    catch {
+        return none;
+    }
+    if (!record || typeof record !== "object")
+        return none;
+    const { command, status, summary, updatedAt, resumeCommand } = record;
+    if (typeof command !== "string" || !SKILL_NAME.test(command) || !skills.has(command))
+        return none;
+    if (typeof summary !== "string")
+        return none;
+    if (typeof status !== "string" || !ACTIVITY_STATUSES.has(status))
+        return none;
+    return {
+        recorded: true,
+        command,
+        status: status,
+        summary: summary.replace(CONTROL, " "),
+        updatedAt: typeof updatedAt === "string" ? updatedAt.replace(CONTROL, " ") : null,
+        resumeCommand: resumes(command, resumeCommand) ? resumeCommand : null
+    };
+}
+function resumes(command, resumeCommand) {
+    if (typeof resumeCommand !== "string" || resumeCommand.length > RESUME_MAX)
+        return false;
+    const invocation = resumeCommand.replace(/^[/$]/, "");
+    return (invocation === command || invocation.startsWith(command + " ")) &&
+        RESUME_ARGUMENTS.test(invocation.slice(command.length));
+}
+/** The lessons after the file's own heading and note, or none while it holds only the stub. */
+export function parseLessons(source) {
+    if (!source)
+        return [];
+    const body = source
+        .split(/\r?\n/)
+        .filter((line) => !/^#{1,6}[ \t]/.test(line) && !/^>/.test(line) && !/^_Nothing learned yet\._$/.test(line.trim()))
+        .join("\n");
+    return blocks(body);
+}
+/** One entry per `##` heading, each decided once `journal-archive.md` carries that heading. */
+export function parseJournal(source, archive) {
+    if (!source)
+        return [];
+    const decided = new Set((archive ?? "").split(/\r?\n/).flatMap((line) => /^##[ \t]+(\S.*)$/.exec(line)?.[1]?.trim() ?? []));
+    return source.split(/^(?=##[ \t])/m).flatMap((entry) => {
+        const heading = /^##[ \t]+(\S.*)$/.exec(entry.split(/\r?\n/, 1)[0] ?? "")?.[1]?.trim();
+        if (!heading)
+            return [];
+        const unlabelled = entry
+            .split(/\r?\n/)
+            .slice(1)
+            .filter((line) => !/^\*\*[^*]+:\*\*/.test(line))
+            .join("\n");
+        return [
+            {
+                heading,
+                date: /^(\d{4}-\d{2}-\d{2})\b/.exec(heading)?.[1] ?? null,
+                archive: labelled(entry, "Archive"),
+                surprised: labelled(entry, "Surprised"),
+                wentWrong: labelled(entry, "Went wrong"),
+                deferred: labelled(entry, "Deferred"),
+                summary: blocks(unlabelled)[0] ?? null,
+                decided: decided.has(heading)
+            }
+        ];
+    });
+}
 /** Paragraphs and list items, each as one line of text. */
 function blocks(body) {
     if (!body)
@@ -238,14 +467,33 @@ 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([
+    const [configRaw, projectPlan, buildPlan, work, findings, overview, activity, inbox] = 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"))
+        readIfPresent(statePath(root, "context", "project-overview.md")),
+        readIfPresent(statePath(root, ".state", "run.json")),
+        readIfPresent(statePath(root, "context", "inbox.md"))
+    ]);
+    const [lessons, journal, journalArchive] = await Promise.all([
+        readIfPresent(statePath(root, "learning", "lessons.md")),
+        readIfPresent(statePath(root, "learning", "journal.md")),
+        readIfPresent(statePath(root, "learning", "journal-archive.md"))
     ]);
+    const entries = parseJournal(journal, journalArchive);
+    const settledSpikes = [];
+    try {
+        for (const name of (await fs.readdir(statePath(root, "history", "spikes"))).filter((n) => n.endsWith(".md") && n !== "README.md")) {
+            const item = parseSettledSpike((await readIfPresent(statePath(root, "history", "spikes", name))) ?? "");
+            if (item)
+                settledSpikes.push(item);
+        }
+    }
+    catch {
+        // No spikes directory: nothing settled.
+    }
     let config = null;
     let configValid = true;
     if (configRaw !== null) {
@@ -269,6 +517,11 @@ export async function readProjectState(root) {
         overviewFresh: !generated || stamped === null
             ? null
             : stamped === overviewHash(projectPlan ?? "", buildPlan ?? ""),
-        openQuestions: parseOpenQuestions(overview)
+        openQuestions: parseOpenQuestions(overview),
+        activity: parseActivity(activity, await installedSkills(root)),
+        inbox: parseInbox(inbox),
+        learning: { lessons: parseLessons(lessons), journal: entries, undecided: entries.filter((e) => !e.decided).length },
+        settledSpikes,
+        spec: specState(work)
     };
 }

package/dist/lib/status.js

@@ -4,10 +4,16 @@
  * 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".
  */
+import { waiting } from "./state.js";
+/** Below this a distill pass has little to group, and recurrence is what it promotes on. */
+export const DISTILL_AFTER = 5;
 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 { waits, problems } = waiting(state.plan, new Set(state.settledSpikes));
+    const waitsOn = (item) => (item.number ? waits.get(item.number) : undefined);
+    const nextItem = leaves.find((i) => !i.done && !waitsOn(i)) ?? null;
+    const passedOver = leaves.slice(0, nextItem ? leaves.indexOf(nextItem) : leaves.length).filter((i) => !i.done && waitsOn(i));
     const byStatus = {};
     for (const finding of state.findings) {
         byStatus[finding.status] = (byStatus[finding.status] ?? 0) + 1;
@@ -16,6 +22,11 @@ export function computeStatus(state) {
         .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 (passedOver.length > 0) {
+        const named = passedOver.map((i) => `${i.number} (${waitsOn(i).join(", ")})`);
+        warnings.push(`passed over plan items that are waiting: ${named.join("; ")}`);
+    }
+    warnings.push(...problems.map((p) => `the build plan: ${p}`));
     if (!state.configValid)
         warnings.push("config.json does not parse; workflow commands will stop rather than guess");
     if (state.overviewFresh === false)
@@ -23,27 +34,40 @@ export function computeStatus(state) {
     if (state.openQuestions.length > 0) {
         warnings.push(`open question(s) in the overview: ${state.openQuestions.join(", ")}`);
     }
+    if (state.spec.drifted) {
+        warnings.push("the active spec changed since its approval stamp; record an amendment saying why and renew the stamp");
+    }
+    if (state.learning.undecided >= DISTILL_AFTER) {
+        warnings.push(`${state.learning.undecided} journal entries are waiting for distill`);
+    }
     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),
+        next: nextAction(state, nextItem?.title ?? null, blocking.length > 0, leaves.filter((i) => !i.done && waitsOn(i)), waitsOn),
         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 },
+        activity: state.activity,
+        inbox: { notes: state.inbox.length },
+        spec: state.spec,
         warnings
     };
 }
-function nextAction(state, nextItem, blocked) {
+function nextAction(state, nextItem, blocked, waitingLeaves, waitsOn) {
     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" };
+    const run = state.activity;
+    if (run.status === "blocked" && run.resumeCommand) {
+        return { command: run.resumeCommand.replace(/^[/$]/, ""), because: `the ${run.command} run is blocked: ${run.summary}` };
+    }
     if (state.work.active) {
         if (blocked)
             return { command: "audit", because: "a blocking finding must be re-reviewed before completion" };
@@ -58,6 +82,12 @@ function nextAction(state, nextItem, blocked) {
         return { command: "feature", because: `next in the plan: ${nextItem}` };
     if (state.plan.length === 0)
         return { command: "overview", because: "the build plan has no items yet" };
+    if (waitingLeaves.length > 0) {
+        const onSpike = waitingLeaves.find((i) => waitsOn(i).includes("a spike"));
+        return onSpike
+            ? { command: "spike", because: `every remaining item waits, and item ${onSpike.number} waits on a spike` }
+            : { command: "overview", because: "every remaining item waits on another; check the plan's after lines" };
+    }
     return { command: "release", because: "the build plan is complete" };
 }
 export function renderStatus(status, cmd = "/") {
@@ -69,6 +99,11 @@ export function renderStatus(status, cmd = "/") {
             (status.work.status ? ` (${status.work.status})` : "")
         : "Active:   nothing in progress");
     out.push(`Plan:     ${status.plan.done}/${status.plan.total} complete (${pct}%)`);
+    const run = status.activity;
+    out.push(run.recorded
+        ? `Run:      ${cmd}${run.command} ${run.status} - ${run.summary}` + (run.updatedAt ? ` (updated ${run.updatedAt})` : "")
+        : "Run:      none recorded");
+    out.push(`Inbox:    ${status.inbox.notes === 0 ? "empty" : `${status.inbox.notes} note(s)`}`);
     if (status.findings.total === 0) {
         out.push("Findings: none");
     }