nerdsystem 0.0.24 → 0.0.26

package/dist/commands/session-review.js

@@ -0,0 +1,268 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { ApiClient } from "../api.js";
+import { RULES } from "../gates/rules.js";
+import { isReviewFile } from "../gates/text.js";
+import { findProjectRoot, projectPath, readNerdJson } from "../project.js";
+import { listSnapshotFiles } from "../snapshot.js";
+import { CliError, dashboardUrl, log, printJson } from "../util.js";
+import { saveSnapshot } from "./save.js";
+/**
+ * The session review: the app's coding agent reads its own changes against the platform's `review/`
+ * catalog before a deploy, and reports what it found.
+ *
+ * `nerd review checklist` prints what to look for, which files changed since the last report from this
+ * folder, the findings still open from earlier reviews, and the report's format. `nerd review report`
+ * stores a snapshot of the code as reviewed and sends the report with it. The platform checks every
+ * finding against that stored code and keeps the report as the agent's own word; it does its own
+ * independent read only now and then, and compares the two.
+ *
+ * What changed is worked out on this computer, from a list of file hashes kept in `.nerd/reviewed.json`
+ * at the last report. A fresh folder has no list, so its first review covers everything.
+ */
+/** Where the agent writes its report for `nerd review report` to send. */
+export const REPORT_FILE = ".nerd/review.json";
+const REVIEWED_FILE = ".nerd/reviewed.json";
+const SAFE_FILE = /^[\w./@-]{1,200}$/;
+export const REVIEW_RULES = Object.keys(RULES)
+    .filter((k) => k.startsWith("review/"))
+    .sort();
+/** Every file a review reads in this folder, with a hash of its contents. */
+export function reviewFiles(root) {
+    const out = {};
+    for (const f of listSnapshotFiles(root).files) {
+        if (!isReviewFile(f.path))
+            continue;
+        try {
+            out[f.path] = createHash("sha256").update(readFileSync(f.abs)).digest("hex");
+        }
+        catch {
+            // gone between the listing and the read: not part of the code any more
+        }
+    }
+    return out;
+}
+function readReviewed(root) {
+    try {
+        const v = JSON.parse(readFileSync(path.join(root, REVIEWED_FILE), "utf8"));
+        return v.files && typeof v.files === "object" ? v.files : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Records the code as it stands as reviewed. */
+export function writeReviewed(root, files) {
+    mkdirSync(path.join(root, ".nerd"), { recursive: true });
+    writeFileSync(path.join(root, REVIEWED_FILE), `${JSON.stringify({ at: new Date().toISOString(), files }, null, 2)}\n`);
+}
+export function reviewDue(root) {
+    const now = reviewFiles(root);
+    const before = readReviewed(root);
+    if (!before)
+        return { due: Object.keys(now).length > 0, first: true, changed: Object.keys(now).sort() };
+    const changed = Object.keys(now).filter((p) => before[p] !== now[p]).sort();
+    const removed = Object.keys(before).filter((p) => !(p in now));
+    return { due: [...changed, ...removed].some((p) => !p.endsWith(".css")), first: false, changed };
+}
+/** What is open from earlier reviews, as rule ids and places only. Empty when the platform cannot be asked. */
+async function openFindings(api, base) {
+    let got = null;
+    try {
+        got = await Promise.race([api.get(`${base}/review`), new Promise((r) => setTimeout(() => r(null), 5000))]);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const f of got?.review?.findings ?? []) {
+        if (typeof f.rule_id !== "string" || !REVIEW_RULES.includes(f.rule_id) || typeof f.file !== "string" || !SAFE_FILE.test(f.file) || !Number.isInteger(f.line))
+            continue;
+        out.push({ rule_id: f.rule_id, file: f.file, line: f.line, origin: f.origin === "session" ? "session" : "platform", leftAsIs: f.leftAsIs === true });
+    }
+    return out;
+}
+const FORMAT = {
+    summary: "Two or three plain sentences for the app's owner: what the app is and the shape it is in. No code, no file names, no jargon.",
+    does: ["Up to six short phrases, each something a person can do in the app today"],
+    missing: ["Up to five short phrases, each something the owner asked for or the description promises that is not built yet"],
+    findings: [{ rule: "review/<id>", file: "src/server/index.ts", line: 42 }],
+    leftAsIs: [{ rule: "review/<id>", file: "src/server/index.ts", line: 42 }],
+    fixed: [{ rule: "review/<id>", file: "src/server/index.ts" }],
+    dismissed: [{ rule: "review/<id>", file: "src/server/index.ts" }],
+};
+export function checklistText(c) {
+    const lines = [
+        `Review of ${c.app} before it is deployed`,
+        "",
+        "This is the review of this app's own code for what tests cannot see. You do it, as part of the work. nerdsystem reads the code itself only now and then, and compares what it finds with what you report here.",
+        "",
+        "How to do it:",
+        "1. Use a reviewer with fresh eyes when you have one. In Claude Code, give this output to the `nerd-reviewer` subagent that ships with the app, either pasted or saved to a file it can read (`nerd review checklist > .nerd/checklist.txt`). If the session says that subagent is not found, it was added after the session started: give a read-only subagent the file `.claude/agents/nerd-reviewer.md` as its instructions. In another agent, use a subagent or a new task that has not seen this conversation. With neither, do it yourself and read the files again from disk, not from memory.",
+        c.first
+            ? "2. No review has been reported from this folder yet, so read all of the app's own code: `src/server` and the database schema first, then `src/client`, plus README.md."
+            : c.changed.length
+                ? "2. Read the files that changed since the last review, and the code they call or are called by when a finding depends on it:"
+                : "2. No file a review reads has changed since the last review. Check the open findings below, if any, and report.",
+    ];
+    if (!c.first)
+        for (const f of c.changed.slice(0, 60))
+            lines.push(`   - ${f}`);
+    if (!c.first && c.changed.length > 60)
+        lines.push(`   … and ${c.changed.length - 60} more`);
+    lines.push("3. For each kind of problem under \"What to look for\", ask whether this code has it. Raise one only when you can point at the line that shows it. Finding nothing is a normal answer for a small change.", "4. Fix what is real and yours to fix. Anything marked [for the person to decide] is a plain question for them: ask it without file names or jargon, and wait for the answer.", `5. Write ${c.reportFile} in the format at the end and run \`nerd review report\`. Then \`nerd check\` and \`nerd deploy\` as usual.`, "");
+    if (c.open.length) {
+        lines.push("Open from earlier reviews. Check each against the code as it is now and answer it in the report:");
+        for (const f of c.open)
+            lines.push(`- ${f.rule_id} at ${f.file}:${f.line}${f.origin === "platform" ? "  (from nerdsystem's own read)" : ""}${f.leftAsIs ? "  (recorded as left as it is; it stays that way unless you report it differently)" : ""}`);
+        lines.push("");
+    }
+    lines.push("What to look for:");
+    for (const r of c.rules) {
+        lines.push(`- ${r.rule_id}: ${r.title}${r.audience === "human" ? " [for the person to decide]" : ""}`, `  Look for: ${r.lookFor}`, `  Fix: ${r.fix}`);
+    }
+    lines.push("", `The report, written to ${c.reportFile}:`, JSON.stringify(c.format, null, 2), "", "- findings: what is still in the code after your fixes and still needs someone to act or decide, each with the rule, the file, and the line that shows it. Leave it empty when there is nothing. A finding marked [for the person to decide] stays here until they have answered.", "- leftAsIs: what is real and deliberately left as it is, because the person decided so or because the rule's own advice is not to change working code for it. It is shown to the owner, kept on later reports, and not announced again to each new session.", "- fixed: what this review found and you then fixed, including findings from the open list above. If you fixed only part of one, list what remains under findings (or leftAsIs) at the line that still shows it, and do not list it as fixed.", "- dismissed: only for a finding from nerdsystem's own read that you checked against the code and that does not apply. The owner sees this as your judgement, so use it when you are sure.", "- A finding from nerdsystem's own read that the report does not mention stays open.", "- summary, does, missing are for the owner and are shown on their dashboard as written. Plain words only.", "", "Report what you found, not what would look good. The report is stored as this agent's own review, it never decides whether a deploy goes out, and a clean report that nerdsystem's own read later contradicts is recorded as a miss.");
+    return lines.join("\n");
+}
+/** `nerd review checklist`: what the agent reads before it reviews. */
+export async function reviewChecklist(opts) {
+    const root = findProjectRoot();
+    const nerd = readNerdJson(root);
+    const due = reviewDue(root);
+    let open = [];
+    try {
+        open = await openFindings(ApiClient.fromConfig(), projectPath(nerd));
+    }
+    catch {
+        // not signed in: the checklist is still worth printing
+    }
+    const c = {
+        app: `${nerd.org}/${nerd.project}`,
+        first: due.first,
+        changed: due.changed,
+        open,
+        rules: REVIEW_RULES.map((id) => ({ rule_id: id, title: RULES[id].title, audience: RULES[id].audience, lookFor: RULES[id].when ?? RULES[id].risk, fix: RULES[id].fix })),
+        reportFile: REPORT_FILE,
+        format: FORMAT,
+    };
+    if (opts.json)
+        return printJson(c);
+    process.stdout.write(`${checklistText(c)}\n`);
+}
+/**
+ * Reads the agent's report strictly, so a slip is corrected here with a sentence that says what to change,
+ * instead of being dropped without a word by the platform. `files` is what a review reads in this folder.
+ */
+export function parseReport(text, files, lineCount) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        throw new CliError(`${REPORT_FILE} is not valid JSON. Run \`nerd review checklist\` for the format.`);
+    }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        throw new CliError(`${REPORT_FILE} must be a JSON object. Run \`nerd review checklist\` for the format.`);
+    const r = raw;
+    const problems = [];
+    const rule = (v, where) => {
+        const id = typeof v === "string" ? (v.startsWith("review/") ? v : `review/${v}`) : "";
+        if (REVIEW_RULES.includes(id))
+            return id;
+        problems.push(`${where}: "${typeof v === "string" ? v.slice(0, 60) : typeof v}" is not a rule in the checklist`);
+        return null;
+    };
+    const list = (key) => {
+        const v = r[key];
+        if (v === undefined || v === null)
+            return [];
+        if (!Array.isArray(v)) {
+            problems.push(`${key} must be a list`);
+            return [];
+        }
+        return v.map((x) => (x && typeof x === "object" ? x : {}));
+    };
+    const placed = (key) => {
+        const out = [];
+        list(key).forEach((f, i) => {
+            const where = `${key}[${i}]`;
+            const id = rule(f.rule, where);
+            if (typeof f.file !== "string" || !(f.file in files))
+                return void problems.push(`${where}: "${String(f.file).slice(0, 80)}" is not a file a review reads (the app's own code under src/, README.md, package.json), or it does not exist`);
+            if (typeof f.line !== "number" || !Number.isInteger(f.line) || f.line < 1 || f.line > lineCount(f.file))
+                return void problems.push(`${where}: line ${String(f.line)} is not a line of ${f.file}`);
+            if (id)
+                out.push({ rule: id, file: f.file, line: f.line });
+        });
+        return out;
+    };
+    const findings = placed("findings");
+    const leftAsIs = placed("leftAsIs");
+    const notes = (key) => {
+        const out = [];
+        list(key).forEach((f, i) => {
+            const id = rule(f.rule, `${key}[${i}]`);
+            if (typeof f.file !== "string" || !SAFE_FILE.test(f.file))
+                return void problems.push(`${key}[${i}]: give the file the finding was in`);
+            if (id)
+                out.push({ rule: id, file: f.file });
+        });
+        return out;
+    };
+    const fixed = notes("fixed");
+    const dismissed = notes("dismissed");
+    const words = (key) => {
+        const v = r[key];
+        if (v === undefined || v === null)
+            return undefined;
+        if (!Array.isArray(v) || v.some((x) => typeof x !== "string")) {
+            problems.push(`${key} must be a list of short phrases`);
+            return undefined;
+        }
+        return v.map((x) => x.slice(0, 400)).slice(0, 12);
+    };
+    const does = words("does");
+    const missing = words("missing");
+    if (r.summary !== undefined && r.summary !== null && typeof r.summary !== "string")
+        problems.push("summary must be a sentence or two of plain text");
+    if (problems.length)
+        throw new CliError(`${REPORT_FILE} needs ${problems.length === 1 ? "a correction" : "corrections"} before it can be sent:\n${problems.map((p) => `  - ${p}`).join("\n")}\nFix the file and run \`nerd review report\` again.`);
+    return { findings, leftAsIs, fixed, dismissed, ...(typeof r.summary === "string" && r.summary.trim() ? { summary: r.summary.slice(0, 2000) } : {}), ...(does ? { does } : {}), ...(missing ? { missing } : {}) };
+}
+/** The name sent with a report. Only an agent this CLI can recognise for certain is named without being told. */
+function agentName(given) {
+    if (given)
+        return /^[a-z0-9][a-z0-9-]{0,29}$/.test(given) ? given : undefined;
+    return process.env.CLAUDECODE ? "claude-code" : undefined;
+}
+/** `nerd review report`: store the code as reviewed, and send the agent's report with it. */
+export async function reviewReport(opts) {
+    const root = findProjectRoot();
+    const nerd = readNerdJson(root);
+    const rel = opts.file ?? REPORT_FILE;
+    const file = path.resolve(root, rel);
+    if (!existsSync(file))
+        throw new CliError(`There is no review to report: ${rel} was not found. Run \`nerd review checklist\` for what to look for and the format to write.`);
+    const files = reviewFiles(root);
+    const report = parseReport(readFileSync(file, "utf8"), files, (f) => readFileSync(path.join(root, f), "utf8").split("\n").length);
+    const api = ApiClient.fromConfig();
+    const saved = await saveSnapshot(root, nerd, api, { quiet: true });
+    const agent = agentName(opts.agent);
+    const answer = await api.post(projectPath(nerd, `/sources/${saved.source.id}/review/report`), { ...report, ...(agent ? { agent } : {}) });
+    // From here the code as it stands counts as reviewed, and the report cannot be sent again by mistake against later code.
+    writeReviewed(root, files);
+    if (!opts.file)
+        rmSync(file, { force: true });
+    const page = `${dashboardUrl(api.apiUrl)}/app/${nerd.org}/projects/${nerd.project}/review`;
+    // Only the counts: the stored review carries a summary that may be a model's words, and those never go to a terminal.
+    if (opts.json)
+        return printJson({ accepted: answer.accepted, dropped: answer.dropped, carried: answer.carried, source: saved.source.id, dashboard: page });
+    const a = answer.accepted;
+    log.ok(`Review reported for ${nerd.org}/${nerd.project}: ${a.findings} open, ${a.fixed} fixed${a.leftAsIs ? `, ${a.leftAsIs} left as they are` : ""}${a.dismissed ? `, ${a.dismissed} judged not to apply` : ""}.`);
+    if (answer.dropped)
+        log.warn(`${answer.dropped} finding(s) were left out because the rule, the file, or the line did not match the stored code.`);
+    if (answer.carried)
+        log.warn(`${answer.carried} finding(s) from nerdsystem's own read are still open because the report did not answer them. \`nerd review\` lists them.`);
+    log.info(`The owner's page for this review: ${page}`);
+}

package/dist/commands/status.d.ts

@@ -16,9 +16,10 @@ export interface Attention {
     /** When the review the findings come from was made, so a finding already fixed since is not a surprise. */
     reviewedAt?: string;
 }
-/** The latest model review's findings for this app, mapped through this CLI's own catalog. */
+/** What is open from the latest review of this app (its agent's own, or the platform's read), mapped through this CLI's own catalog. */
 export declare function reviewItems(api: ApiClient, base: string): Promise<{
     items: AttentionItem[];
+    left: AttentionItem[];
     reviewedAt?: string;
 }>;
 /**
@@ -41,7 +42,7 @@ export declare function status(opts: {
     json: boolean;
     hook: boolean;
 }): Promise<void>;
-/** `nerd review`: only the model review's findings, with every fix written out. */
+/** `nerd review`: only what is open from the latest review, with every fix written out. */
 export declare function review(opts: {
     json: boolean;
 }): Promise<void>;

package/dist/commands/status.js

@@ -4,28 +4,30 @@ import { ApiClient } from "../api.js";
 import { RULES } from "../gates/rules.js";
 import { currentVersions, pinned, versionFindings } from "../gates/versions.js";
 import { findProjectRoot, projectPath, readNerdJson } from "../project.js";
-import { log } from "../util.js";
+import { localDay, log } from "../util.js";
 import { cliVersion } from "./source.js";
 const within = (p, ms) => Promise.race([p.catch(() => null), new Promise((r) => setTimeout(() => r(null), ms))]);
 const item = (rule_id, extra = {}) => {
     const r = RULES[rule_id];
     return r ? { rule_id, title: r.title, severity: r.severity, audience: r.audience, risk: r.risk, fix: extra.fix ?? r.fix, ...(extra.where ? { where: extra.where } : {}) } : null;
 };
-/** The latest model review's findings for this app, mapped through this CLI's own catalog. */
+/** What is open from the latest review of this app (its agent's own, or the platform's read), mapped through this CLI's own catalog. */
 export async function reviewItems(api, base) {
     const got = await within(api.get(`${base}/review`), 5000);
     const review = got?.review;
     if (!review || review.status !== "done")
-        return { items: [] };
+        return { items: [], left: [] };
     const items = [];
+    // Recorded as real and deliberately left as they are: kept for whoever asks, not announced to every new session.
+    const left = [];
     for (const f of review.findings ?? []) {
         if (typeof f.rule_id !== "string" || !f.rule_id.startsWith("review/") || typeof f.file !== "string" || !/^[\w./@-]{1,200}$/.test(f.file) || !Number.isInteger(f.line))
             continue;
         const it = item(f.rule_id, { where: `${f.file}:${f.line}` });
         if (it)
-            items.push(it);
+            (f.leftAsIs === true ? left : items).push(it);
     }
-    return { items, reviewedAt: review.createdAt };
+    return { items, left, reviewedAt: review.createdAt };
 }
 /**
  * Everything the platform has noticed about this app that someone should act on, gathered in a few
@@ -92,7 +94,7 @@ export function attentionText(a) {
         }
     }
     if (a.reviewedAt)
-        lines.push("", `Findings with a file and a line come from a model's review of the version deployed on ${a.reviewedAt.slice(0, 10)}. It is a second opinion and can be wrong, and code changed since may already have fixed one: read the code at each place before changing anything.`);
+        lines.push("", `Findings with a file and a line come from the latest review of this app (${localDay(a.reviewedAt)}): the one its coding agent reported, or nerdsystem's own read of the code. A review is a second opinion and can be wrong, and code changed since may already have fixed one: read the code at each place before changing anything, and say what you did about each in the next \`nerd review report\`.`);
     lines.push("", "Before starting on what the person asked for, tell them about these in one or two plain sentences, with no file names or jargon, and offer to take care of them. If they say yes, fix what is real, run `nerd check`, and deploy. Anything marked for the person to decide, put to them as a plain question and wait for the answer. If they would rather get on with their own request, do that first and remind them once at the end.");
     return lines.join("\n");
 }
@@ -119,7 +121,7 @@ export async function status(opts) {
     else if (!opts.hook)
         log.ok(`Nothing needs attention${a.app ? ` for ${a.app}` : ""}.`);
 }
-/** `nerd review`: only the model review's findings, with every fix written out. */
+/** `nerd review`: only what is open from the latest review, with every fix written out. */
 export async function review(opts) {
     const root = findProjectRoot();
     const nerd = readNerdJson(root);
@@ -129,12 +131,15 @@ export async function review(opts) {
         return;
     }
     if (!r.reviewedAt) {
-        log.info("No model review of this app yet. One runs at the end of `nerd deploy`.");
+        log.info("No review of this app yet. Run `nerd review checklist` to do one before the next deploy.");
         return;
     }
+    const leftLines = r.left.length ? ["", "Known and deliberately left as they are (recorded in an earlier review; nothing to do unless the code around them changes):", ...r.left.map((it) => `- ${it.title} (${it.where})`)] : [];
     if (!r.items.length) {
-        log.ok(`The review of the version deployed on ${r.reviewedAt.slice(0, 10)} found nothing to raise.`);
+        log.ok(`Nothing is open from the latest review (${localDay(r.reviewedAt)}).`);
+        if (leftLines.length)
+            process.stdout.write(`${leftLines.slice(1).join("\n")}\n`);
         return;
     }
-    process.stdout.write(`${attentionText({ app: `${nerd.org}/${nerd.project}`, items: r.items, reviewedAt: r.reviewedAt })}\n`);
+    process.stdout.write(`${attentionText({ app: `${nerd.org}/${nerd.project}`, items: r.items, reviewedAt: r.reviewedAt })}${leftLines.length ? `\n${leftLines.join("\n")}` : ""}\n`);
 }

package/dist/commands/upgrade.js

@@ -1,12 +1,14 @@
+import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { findProjectRoot } from "../project.js";
 import { log } from "../util.js";
 import { renderAgentFiles } from "./agents.js";
+import { KNOWN_CLAUDE_MD } from "./claude-md-history.js";
 import { templateDir } from "./init.js";
 import { cliVersion } from "./source.js";
 /** Files that are the platform's, not the app's: replaced with the current version every time. */
-const OURS = [".claude/skills/nerdsystem/SKILL.md", "test/setup.ts", "test/global-setup.ts", "vitest.config.ts"];
+const OURS = [".claude/skills/nerdsystem/SKILL.md", ".claude/agents/nerd-reviewer.md", "test/setup.ts", "test/global-setup.ts", "vitest.config.ts"];
 /** Files an app is expected to change: written only when the app has none. */
 const STARTERS = [
     ["test/access.test.ts", "test/access.test.ts"],
@@ -75,9 +77,13 @@ export function upgradeProject(root, tpl, version) {
     // purpose, so it is carried over word for word.
     const seeded = oldClaude ? /^(# [^\n]*\n\n[\s\S]*?\n\n)## This app runs on nerdsystem\n/.exec(oldClaude) : null;
     const newClaude = tplClaude !== null && seeded ? seeded[1] + tplClaude.replace(/^# This app runs on nerdsystem\n/, "## This app runs on nerdsystem\n") : tplClaude;
+    // The platform's part of the old file, as the template had it: when that is word for word a version this
+    // project shipped, nobody has added anything, and there is nothing to keep.
+    const oldPlatformText = oldClaude === null ? null : seeded ? oldClaude.slice(seeded[1].length).replace(/^## This app runs on nerdsystem\n/, "# This app runs on nerdsystem\n") : oldClaude;
+    const untouched = oldPlatformText !== null && KNOWN_CLAUDE_MD.has(createHash("sha256").update(oldPlatformText).digest("hex"));
     let keptOld = false;
     if (newClaude !== null && oldClaude !== newClaude) {
-        if (oldClaude !== null && !existsSync(path.join(root, "CLAUDE.previous.md"))) {
+        if (oldClaude !== null && !untouched && !existsSync(path.join(root, "CLAUDE.previous.md"))) {
             renameSync(path.join(root, "CLAUDE.md"), path.join(root, "CLAUDE.previous.md"));
             changed.push("CLAUDE.previous.md");
             keptOld = true;
@@ -113,6 +119,8 @@ export function upgradeProject(root, tpl, version) {
     const next = ["Run `pnpm install`.", "Run `nerd check` and work through what it reports. It names what this app's own code should adopt (for example sign-in for every route, checked input, access tests)."];
     if (startersWritten.includes("test/access.test.ts"))
         next.push("`test/access.test.ts` is the starter's: keep the first test, and rewrite the owner test for this app's own routes. Then set `\"tests\": \"required\"` in nerd.json.");
+    if (changed.includes(".claude/agents/nerd-reviewer.md"))
+        next.push("A reviewer for Claude Code was added or updated at `.claude/agents/nerd-reviewer.md`. Claude Code loads it when a session starts, so a session that was already open will say it is not found: until the next session, give a read-only subagent that file as its instructions.");
     if (keptOld)
         next.push("Your earlier `CLAUDE.md` is now `CLAUDE.previous.md`. Move anything the person added into the new `CLAUDE.md`, then delete the old file.");
     next.push("Tell the person in plain words what changed, then run `nerd deploy` when the check passes.");

package/dist/commands/verify.js

@@ -4,7 +4,7 @@ import { ApiClient } from "../api.js";
 import { BUILD_GATES, gateSummary, knownSecretsFrom, runGates, skippedGates, SOURCE_GATES } from "../gates/index.js";
 import { findProjectRoot, projectPath, readDevVars, readNerdJson } from "../project.js";
 import { CliError, log } from "../util.js";
-import { readBuildOutput } from "./deploy.js";
+import { dropLocalSecretCopies, readBuildOutput } from "./deploy.js";
 /** Suppressions a human approved in the dashboard, so they stop being reported. Best effort. */
 export async function approvedSuppressions(root) {
     try {
@@ -28,6 +28,7 @@ export async function runVerify(root, opts) {
     let stop = source.capped;
     if (opts.withBuild && source.ok && existsSync(path.join(root, "dist"))) {
         const build = readBuildOutput(root);
+        dropLocalSecretCopies(build);
         const built = await runGates(BUILD_GATES.filter((g) => g.name !== "policy"), { ...ctxBase, build }, { stopOnFail: opts.stopOnFail, trackAttempts: false });
         results = [...results, ...built.results];
         failures = [...failures, ...built.failures];

package/dist/gates/design.js

@@ -108,6 +108,9 @@ export function designFindings(root, files, routes, authPath = "/api/auth") {
         for (const p of patterns) {
             if (SYSTEM.has(p.path))
                 continue;
+            // A webhook or a callback is called by another service, never by a screen.
+            if (/\/(webhooks?|callbacks?)(\/|$)/.test(p.path))
+                continue;
             if (endings.some((e) => p.path.endsWith(e)))
                 continue;
             // The route's name passed the same strict pattern as every other route name read from the report.

package/dist/gates/review.d.ts

@@ -1,8 +1,10 @@
 import { type Gate } from "./types.js";
 /**
- * Brings the platform's latest model review of this app into the same list as every other check, so an
- * agent meets its findings in the loop it already runs and nobody has to go and look for them. Advice
- * only. The words are this CLI's catalog; the review itself contributes a rule id, a file, and a line.
- * Skipped without comment when there is no sign-in, no linked project, no review, or no network.
+ * Brings the review of this app into the same list as every other check, so an agent meets it in the
+ * loop it already runs and nobody has to go and look for it. Two things: the findings still open from
+ * the latest review (the agent's own or the platform's read), and a reminder when code a review reads
+ * has changed since the last one reported from this folder. Advice only. The words are this CLI's
+ * catalog; a review contributes a rule id, a file, and a line.
+ * Skipped without comment when there is no sign-in, no linked project, or no network.
  */
 export declare const reviewGate: Gate;

package/dist/gates/review.js

@@ -1,18 +1,23 @@
 import { ApiClient } from "../api.js";
+import { reviewDue } from "../commands/session-review.js";
 import { reviewItems } from "../commands/status.js";
 import { projectPath, readNerdJson } from "../project.js";
+import { finding } from "./secrets.js";
+import { localDay } from "../util.js";
 import { counts, result, verdict } from "./types.js";
 /**
- * Brings the platform's latest model review of this app into the same list as every other check, so an
- * agent meets its findings in the loop it already runs and nobody has to go and look for them. Advice
- * only. The words are this CLI's catalog; the review itself contributes a rule id, a file, and a line.
- * Skipped without comment when there is no sign-in, no linked project, no review, or no network.
+ * Brings the review of this app into the same list as every other check, so an agent meets it in the
+ * loop it already runs and nobody has to go and look for it. Two things: the findings still open from
+ * the latest review (the agent's own or the platform's read), and a reminder when code a review reads
+ * has changed since the last one reported from this folder. Advice only. The words are this CLI's
+ * catalog; a review contributes a rule id, a file, and a line.
+ * Skipped without comment when there is no sign-in, no linked project, or no network.
  */
 export const reviewGate = {
     name: "review",
-    title: "Model review of the deployed version",
+    title: "Review of how the app is built",
     blocking: false,
-    rulePrefixes: ["review/"],
+    rulePrefixes: ["review/", "session/"],
     async run(ctx) {
         const t = Date.now();
         // A git build has no person's sign-in to ask with, and the review is of code already deployed.
@@ -25,13 +30,23 @@ export const reviewGate = {
         catch {
             return result(this, "skip", "No linked project or sign-in to ask with", [], t);
         }
-        if (!got.reviewedAt)
-            return result(this, "skip", "No review yet; one runs at the end of nerd deploy", [], t);
         const findings = got.items.map((i) => {
             const [file, line] = (i.where ?? "").split(":");
-            return { rule_id: i.rule_id, severity: i.severity, audience: i.audience, file, line: Number(line) || undefined, risk: i.risk, fix: i.fix, verify: "nerd deploy (the code is reviewed again after the next deploy)", attempt: 1, fingerprint: `${i.rule_id}:${i.where}` };
+            return { rule_id: i.rule_id, severity: i.severity, audience: i.audience, file, line: Number(line) || undefined, risk: i.risk, fix: i.fix, verify: "nerd review report (say what you fixed), then nerd deploy", attempt: 1, fingerprint: `${i.rule_id}:${i.where}` };
         });
-        const when = got.reviewedAt.slice(0, 10);
-        return result(this, verdict(findings), findings.length ? `${counts(findings)}, from the review of the version deployed on ${when}; a second opinion that can be wrong, so read the code first` : `Nothing raised in the review of the version deployed on ${when}`, findings, t);
+        const open = findings.length;
+        let due = false;
+        let first = false;
+        try {
+            ({ due, first } = reviewDue(ctx.root));
+        }
+        catch {
+            // a folder that cannot be listed has nothing to say here
+        }
+        if (due)
+            findings.push(finding("session/review-due", { verify: "nerd review report" }));
+        const when = got.reviewedAt ? localDay(got.reviewedAt) : undefined;
+        const said = [open ? `${open} open from the review of ${when}; a second opinion that can be wrong, so read the code first` : when ? `Nothing open from the review of ${when}` : "No review yet", ...(due ? [first ? "no review has been reported from this folder: run nerd review checklist" : "code has changed since the last review: run nerd review checklist"] : [])];
+        return result(this, verdict(findings), findings.length ? `${counts(findings)}: ${said.join("; ")}` : said.join("; "), findings, t);
     },
 };

package/dist/gates/rules.js

@@ -56,6 +56,7 @@ export const RULES = {
     "design/unused-table": { title: "A table nothing uses", severity: "warn", audience: "agent", risk: "A table left over from the starter or from a removed feature confuses the next change and may still hold people's data.", fix: "If the feature is gone, remove the table from the schema and write a migration that drops it; tell the person first if it may hold data they want. If it is meant to be used, connect it." },
     "design/long-file": { title: "A very long file", severity: "info", audience: "agent", risk: "Changes to a file this long are more likely to break something elsewhere in it, for a person or an agent.", fix: "Split it along its natural parts (one screen, one group of routes per file) the next time you change it. Do not reorganise working code just for this." },
     "design/unfinished": { title: "Something marked as unfinished", severity: "info", audience: "agent", risk: "A note to finish something later, or placeholder text, is about to go live.", fix: "Finish it, remove it, or tell the person it is not done yet so they can decide." },
+    "session/review-due": { title: "The code as it is now has not been reviewed", severity: "warn", audience: "agent", risk: "Tests show the app does what was checked; they cannot show that the server trusts a price the browser sent, or that two people can book the same slot. Nobody has looked for that in the code as it is now.", fix: "Run `nerd review checklist` and follow it: review the files it lists (in Claude Code, with the `nerd-reviewer` subagent), fix what is real, write the report it describes, and run `nerd review report`." },
     "platform/vulnerable-package": { title: "A package this app uses has a serious vulnerability reported since it was deployed", severity: "warn", audience: "agent", risk: "The app passed its checks when it went live. Since then a flaw has been made public in something it depends on, and the live app still carries it.", fix: "Run `nerd check`: it names the package and the version to move to. Update it, run the tests, and deploy." },
     "versions/cli-outdated": { title: "The nerd command is behind", severity: "warn", audience: "agent", risk: "An older nerd runs fewer checks and may not know about newer platform features.", fix: "Run `npm install -g nerdsystem@latest`." },
     "versions/sdk-outdated": { title: "The app's SDK is behind", severity: "warn", audience: "agent", risk: "The app is missing fixes and safeguards that newer versions of the platform's library and instructions carry.", fix: "Run `nerd upgrade`, then `pnpm install` and `nerd check`." },

package/dist/gates/text.d.ts

@@ -68,6 +68,13 @@ export interface OsvVulnerability {
 export declare function osvSeverity(v: OsvVulnerability): AdvisorySeverity;
 /** CVSS v3.0/3.1 base score from a vector string, or null when the vector is malformed. */
 export declare function cvss3BaseScore(vector: string): number | null;
+/**
+ * The files a review of an app reads: its own code and its description. Tests, generated files, and the
+ * instructions written for agents are left out. The control plane's model review and the session review an
+ * agent does itself (`nerd review checklist`) both go by this, so "what changed since the last review"
+ * means the same thing on both sides.
+ */
+export declare function isReviewFile(posixPath: string): boolean;
 /** Name of the first entry in every snapshot tar. */
 export declare const SNAPSHOT_MANIFEST = ".nerd-snapshot.json";
 /** Most files one snapshot may hold. */

package/dist/gates/text.js

@@ -150,6 +150,17 @@ export function cvss3BaseScore(vector) {
     const roundUp = (x) => Math.ceil(x * 10 - 1e-9) / 10;
     return scopeChanged ? roundUp(Math.min(1.08 * (impact + exploitability), 10)) : roundUp(Math.min(impact + exploitability, 10));
 }
+/**
+ * The files a review of an app reads: its own code and its description. Tests, generated files, and the
+ * instructions written for agents are left out. The control plane's model review and the session review an
+ * agent does itself (`nerd review checklist`) both go by this, so "what changed since the last review"
+ * means the same thing on both sides.
+ */
+export function isReviewFile(posixPath) {
+    if (/\.d\.ts$/.test(posixPath))
+        return false;
+    return /^src\/.+\.(ts|tsx|js|jsx|mjs|css)$/.test(posixPath) || posixPath === "README.md" || posixPath === "package.json";
+}
 /*
  * Source snapshots (docs/source-snapshots.md). The CLI packs them, the control plane validates
  * them while streaming, and both read the lists below, so a rule added here holds on both sides.

package/dist/gates/versions.js

@@ -114,7 +114,9 @@ export const versionsGate = {
             // no package.json: the rules gate says so
         }
         const findings = versionFindings({ cli: installedCli(), sdk, versions, inBuilder: Boolean(ctx.committed) });
-        const summary = findings.length ? findings.map((f) => f.rule_id.split("/")[1]).join(", ") : versions.latest ? `nerd and the SDK are current (${versions.latest})` : "Nothing older than the platform accepts";
+        // The platform's answer is kept for a day, so straight after an update this copy can be newer than the "latest" it remembers.
+        const shown = versions.latest && compareVersions(installedCli(), versions.latest) > 0 ? installedCli() : versions.latest;
+        const summary = findings.length ? findings.map((f) => f.rule_id.split("/")[1]).join(", ") : shown ? `nerd and the SDK are current (${shown})` : "Nothing older than the platform accepts";
         return result(this, verdict(findings), summary, findings, t);
     },
 };

package/dist/util.d.ts

@@ -29,6 +29,8 @@ export declare function runOrThrow(cmd: string, args: string[], opts?: RunOption
 export declare function printJson(value: unknown): void;
 export declare function table(rows: Record<string, unknown>[], columns: string[]): void;
 /** The dashboard that goes with an API origin (https://api.nerdsystem.com -> https://nerdsystem.com). */
+/** The calendar day of a timestamp where the person is, as YYYY-MM-DD. The platform's times are UTC, which is tomorrow for part of every evening in the Americas. */
+export declare function localDay(iso: string): string;
 export declare function dashboardUrl(apiUrl: string): string;
 /** Stops with one sentence instead of npx noise when `pnpm install` has not been run. */
 export declare function ensureDeps(root: string): void;

package/dist/util.js

@@ -49,6 +49,14 @@ export function table(rows, columns) {
         process.stdout.write(`${line(columns.map((c) => String(r[c] ?? "")))}\n`);
 }
 /** The dashboard that goes with an API origin (https://api.nerdsystem.com -> https://nerdsystem.com). */
+/** The calendar day of a timestamp where the person is, as YYYY-MM-DD. The platform's times are UTC, which is tomorrow for part of every evening in the Americas. */
+export function localDay(iso) {
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return iso.slice(0, 10);
+    const two = (n) => String(n).padStart(2, "0");
+    return `${d.getFullYear()}-${two(d.getMonth() + 1)}-${two(d.getDate())}`;
+}
 export function dashboardUrl(apiUrl) {
     return apiUrl.replace(/\/$/, "").replace(/^https?:\/\/api\./, "https://");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nerdsystem",
-  "version": "0.0.24",
+  "version": "0.0.26",
   "description": "nerd: start, check, and deploy a web app on nerdsystem from the terminal or a coding agent.",
   "type": "module",
   "bin": {