thurview 0.11.1 → 0.13.0

package/dist/cli.js

@@ -9,45 +9,28 @@ import { join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import open from "open";
 import * as g from "./git.js";
-import { SCHEMA, home, newId, now, readReview, writeReview, listReviews, reviewsFor, reviewDir, revisionDir, readThreads, readText, writeText, writeJson, readJson, serverStateFile, deleteReview, kindOf, } from "./store.js";
+import { SCHEMA, home, newId, now, readReview, writeReview, listReviews, reviewsFor, reviewDir, revisionDir, passFile, readThreads, readText, writeText, writeJson, readJson, serverStateFile, deleteReview, kindOf, } from "./store.js";
 import { compileDocument, compileMap, globToRegExp } from "./document/compile.js";
 import { computeCoverage, scopeGlob, scopeGraph, scopeTruncated, } from "./coverage.js";
 import { parseTheme, compileTheme } from "./theme.js";
 import { registerTheme } from "./highlight.js";
 import { replyThread, setThreadStatus, needsAgent } from "./threads.js";
+import { targetLabel, truncate } from "./thread-state.js";
 import { attach } from "./presence.js";
 import { startServer } from "./server/server.js";
 import { parseFlags, helpFor, str, bool } from "./flags.js";
 import { forgeFor, repoOf, summariseCi, } from "./forge/index.js";
-import { parseSubmission, longComments } from "./forge/submission.js";
+import { parseSubmission, longComments, buildPass } from "./forge/submission.js";
 import { VERSION } from "./version.js";
 const execFileP = promisify(execFile);
 const HERE = dirname(fileURLToPath(import.meta.url));
-const DESCRIPTION = "Guided, evidence-anchored reviews of a change and explainers of a codebase, read and answered in the browser";
+const DESCRIPTION = "Guided, evidence-anchored reviews of a change, explainers of a codebase and designs of what to build, read and answered in the browser";
 function note(msg) {
     process.stderr.write(msg + "\n");
 }
 function short(id) {
     return id.slice(0, 8);
 }
-function truncate(text, max) {
-    return text.length > max
-        ? `${text.slice(0, max)}... (truncated, ${text.length} chars total)`
-        : text;
-}
-function targetLabel(t) {
-    if (t.type === "document")
-        return `document${t.quote ? ` "${truncate(t.quote, 40)}"` : ""}`;
-    if (t.type === "file") {
-        if (!t.line)
-            return `${t.path} (file)`;
-        const range = t.endLine && t.endLine > t.line ? `${t.line}-${t.endLine}` : String(t.line);
-        return `${t.path}:${range}${t.side === "base" ? " (base)" : ""}`;
-    }
-    if (t.type === "map")
-        return `map ${t.node}`;
-    return "review";
-}
 /** `PR #12` or `MR !12`, because the forge's own word is what the reader knows. */
 function bindingLabel(b) {
     if (b.kind !== "pr")
@@ -77,7 +60,13 @@ async function worktreeOf(cwd) {
         return null;
     }
 }
-async function resolveReview(idOpt) {
+/**
+ * `terminal` keeps an approved or closed review in the search. `forge pass`
+ * needs it: approve and close are two of the three decisions it carries, and
+ * both of them end the review, so without it the command cannot find the very
+ * review it was asked about unless the id is spelled out.
+ */
+async function resolveReview(idOpt, opts = {}) {
     if (idOpt) {
         const r = await readReview(idOpt);
         if (r)
@@ -92,7 +81,7 @@ async function resolveReview(idOpt) {
         throw new AxiError("not inside a git repository", "VALIDATION_ERROR", [
             "Run inside the source worktree, or pass --review <id>",
         ]);
-    const mine = (await reviewsFor(worktree)).filter((r) => !r.dismissed && r.status !== "accepted" && r.status !== "closed");
+    const mine = (await reviewsFor(worktree)).filter((r) => !r.dismissed && (opts.terminal || (r.status !== "accepted" && r.status !== "closed")));
     if (mine.length === 1)
         return mine[0];
     if (mine.length)
@@ -145,9 +134,9 @@ async function reviewRow(r, fields) {
         row["binding"] = bindingLabel(r.binding);
     if (fields.has("all") || fields.has("pins"))
         row["pins"] =
-            kindOf(r) === "explainer"
-                ? r.pins.head.slice(0, 12)
-                : `${r.pins.base.slice(0, 12)}..${r.pins.head.slice(0, 12)}`;
+            kindOf(r) === "review"
+                ? `${r.pins.base.slice(0, 12)}..${r.pins.head.slice(0, 12)}`
+                : r.pins.head.slice(0, 12);
     if (fields.has("all") || fields.has("worktree"))
         row["worktree"] = r.worktree;
     if (fields.has("all") || fields.has("inSync"))
@@ -334,6 +323,150 @@ const TEMPLATE_EXPLAIN_MAP = `# The structure of the code at the pinned commit:
 nodes: []
 edges: []
 `;
+const TEMPLATE_DESIGN_MD = (title) => `# ${title}
+
+**Summary**
+
+- The agent is still writing this design. The page offers the new revision
+  when the proposal lands.
+`;
+const TEMPLATE_DESIGN_DATA = `# Typed inputs for the design: actors, anchors, stores, and the proposals it
+# makes. A design is pinned to ONE commit - the code as it stands, which the
+# design changes - so every anchor reads that commit and \`graph: base\` is an
+# error.
+#
+# An anchor is evidence, never a proposal. It points at code that exists today:
+# what the design changes, and what constrains it.
+#
+# anchors:
+#   login:
+#     title: where a request is authenticated today
+#     peek: { file: src/auth.ts, from: 41, to: 58 }
+#
+# interfaces holds what the design WOULD add, change or remove. Each entry names
+# the interface, what it would let a consumer do, and the anchor of the code it
+# lands in, replaces or plugs into today. A design with no entry here proposes
+# nothing, and publish refuses it: that document is a code explainer.
+#
+# interfaces:
+#   strict:
+#     name: auth.login --strict
+#     change: added
+#     capability: Rejects an empty user instead of answering false.
+#     anchor: login
+actors: {}
+anchors: {}
+stores: {}
+interfaces: {}
+`;
+const TEMPLATE_DESIGN_MAP = `# The structure the design proposes, with the structure as it stands under
+# \`base\`, so the Map tab shows what it adds, changes and removes. A node under
+# \`nodes\` may own files that do not exist yet - that is a proposed part. A node
+# under \`base\` may not: it is a claim about today, and publish warns.
+# Seed base from \`thurview graph architecture\`.
+nodes: []
+edges: []
+`;
+const EXPLAINER = {
+    kind: "explainer",
+    command: "explain",
+    title: (scope, worktree) => scope === "**" ? worktree.split("/").pop() || "Codebase" : scope.replace(/\/\*\*$/, ""),
+    templates: { md: TEMPLATE_EXPLAIN_MD, data: TEMPLATE_EXPLAIN_DATA, map: TEMPLATE_EXPLAIN_MAP },
+};
+const DESIGN = {
+    kind: "design",
+    command: "design",
+    title: (scope) => (scope === "**" ? "Design" : `${scope.replace(/\/\*\*$/, "")} design`),
+    templates: { md: TEMPLATE_DESIGN_MD, data: TEMPLATE_DESIGN_DATA, map: TEMPLATE_DESIGN_MAP },
+};
+/** The kind with its article, so a generated sentence reads as one: "an explainer". */
+function kindWord(kind) {
+    return kind === "explainer" ? "an explainer" : kind === "design" ? "a design" : "a review";
+}
+/** The command that re-pins a document of this kind, for a message that offers it. */
+function repinCommand(kind) {
+    return kind === "review"
+        ? "thurview scaffold"
+        : `thurview ${kind === "design" ? "design" : "explain"}`;
+}
+async function pinOneCommit(p, k) {
+    const worktree = await worktreeOf(process.cwd());
+    if (!worktree)
+        throw new AxiError("not inside a git repository", "VALIDATION_ERROR", [
+            `Run \`thurview ${k.command}\` inside the source worktree`,
+        ]);
+    const existing = bool(p, "update") || str(p, "review") ? await resolveReview(str(p, "review")) : null;
+    if (existing && kindOf(existing) !== k.kind) {
+        const other = kindOf(existing);
+        throw new AxiError(`${short(existing.id)} is ${kindWord(other)}, not ${kindWord(k.kind)}`, "VALIDATION_ERROR", [
+            `Run \`${repinCommand(other)} --update --review ${short(existing.id)}\` to re-pin that ${other}`,
+            `Run \`thurview ${k.command}\` with no --review to start ${kindWord(k.kind)}`,
+        ]);
+    }
+    const scope = scopeGlob(p.positional[0] ?? existing?.binding.name);
+    let commit;
+    try {
+        commit = await g.revParse(worktree, str(p, "commit") ?? "HEAD");
+    }
+    catch (e) {
+        throw new AxiError(e.message, "VALIDATION_ERROR", [
+            `Pass a resolvable ref: \`thurview ${k.command} --commit <ref>\``,
+        ]);
+    }
+    // A scope that matches nothing is a typo, and a document of nothing would
+    // still publish and still state honest-looking coverage of zero files.
+    const files = await g.listFiles(worktree, commit);
+    const inScope = scope === "**" ? files : files.filter((f) => globToRegExp(scope).test(f));
+    if (!inScope.length)
+        throw new AxiError(`no file matches "${scope}" at ${commit.slice(0, 12)}`, "VALIDATION_ERROR", [
+            `Pass a path that exists at that commit: \`thurview ${k.command} src/server\``,
+            `Run \`thurview ${k.command}\` with no scope for the whole repository`,
+        ]);
+    const binding = { kind: "codebase", name: scope };
+    if (existing) {
+        existing.pins = { base: commit, head: commit };
+        existing.binding = binding;
+        if (str(p, "title"))
+            existing.title = str(p, "title");
+        await writeReview(existing);
+        return { review: existing, reused: false, scope, commit, worktree, inScope };
+    }
+    const match = bool(p, "new")
+        ? []
+        : (await reviewsFor(worktree)).filter((r) => kindOf(r) === k.kind &&
+            r.binding.name === scope &&
+            r.status !== "accepted" &&
+            r.status !== "closed");
+    if (match.length) {
+        const review = match[0];
+        review.pins = { base: commit, head: commit };
+        await writeReview(review);
+        return { review, reused: true, scope, commit, worktree, inScope };
+    }
+    const id = newId();
+    const review = {
+        schema: SCHEMA,
+        id,
+        kind: k.kind,
+        title: str(p, "title") || k.title(scope, worktree),
+        worktree,
+        repoRoot: worktree,
+        binding,
+        pins: { base: commit, head: commit },
+        status: "draft",
+        revision: 0,
+        dismissed: false,
+        createdAt: now(),
+        updatedAt: now(),
+    };
+    await mkdir(reviewDir(id), { recursive: true });
+    await writeText(join(reviewDir(id), "review.md"), k.templates.md(review.title));
+    await writeText(join(reviewDir(id), "data.yaml"), k.templates.data);
+    await writeText(join(reviewDir(id), "map.yaml"), k.templates.map);
+    await writeText(join(reviewDir(id), "theme.yaml"), TEMPLATE_THEME);
+    await writeReview(review);
+    return { review, reused: false, scope, commit, worktree, inScope };
+}
 // ---- commands ----
 const SPECS = {
     scaffold: {
@@ -379,8 +512,25 @@ const SPECS = {
             "thurview explain --update --review <id>",
         ],
     },
+    design: {
+        description: "Create a design or architecture document: what to build, argued against the code as it stands",
+        args: "[<path scope>]",
+        flags: {
+            commit: { kind: "string", help: "commit to pin (default: HEAD)" },
+            title: { kind: "string", help: "initial title" },
+            new: { kind: "boolean", help: "create another design even if one matches the scope" },
+            update: { kind: "boolean", help: "re-pin an existing design to a new commit" },
+            review: { kind: "string", help: "design to update (id prefix)" },
+        },
+        examples: [
+            "thurview design",
+            "thurview design src/server",
+            "thurview design --title 'Queue the forge pass'",
+            "thurview design --update --review <id>",
+        ],
+    },
     info: {
-        description: "Reviews and explainers bound to this worktree (or all of them with --all)",
+        description: "Reviews, explainers and designs bound to this worktree (or all of them with --all)",
         flags: {
             all: { kind: "boolean", help: "every review, not only this worktree" },
             fields: {
@@ -478,7 +628,7 @@ const SPECS = {
     },
     forge: {
         description: "Read a pull or merge request through its forge, and post the review back to it",
-        args: 'status|prior|submit --file <path>|reply <threadId> --body "<text>"',
+        args: 'status|prior|pass|submit --file <path>|reply <threadId> --body "<text>"',
         flags: {
             review: { kind: "string", help: "review id prefix; its binding names the change request" },
             change: { kind: "string", help: "change request number or URL, instead of a review binding" },
@@ -488,6 +638,10 @@ const SPECS = {
             },
             repo: { kind: "string", help: "host/path, when `origin` is not the repository to post to" },
             file: { kind: "string", help: "submit: the JSON submission to post" },
+            out: {
+                kind: "string",
+                help: "pass: where to write the submission (default: ~/.thurview/passes/<id>.json)",
+            },
             body: { kind: "string", help: "reply: the answer text" },
             resolve: { kind: "boolean", help: "reply: resolve the thread as well as answering it" },
             at: { kind: "string", help: "reply --resolve: the commit the point was verified at" },
@@ -504,6 +658,7 @@ const SPECS = {
         examples: [
             "thurview forge status --change 123",
             "thurview forge prior --change 123 --mine",
+            "thurview forge pass --review <id>",
             "thurview forge submit --file pass.json --dry-run",
             'thurview forge reply <threadId> --body "<answer>" --resolve --at <sha>',
         ],
@@ -559,6 +714,7 @@ async function homeView() {
                 "Run `thurview scaffold` to create a review of the current branch",
                 "Run `thurview scaffold --pr <number>` for a pull request",
                 "Run `thurview explain [<path>]` to explain the codebase at HEAD instead",
+                "Run `thurview design [<path>]` to design a change before writing it",
             ],
         };
     const reviews = [];
@@ -725,87 +881,8 @@ const commands = {
     },
     async explain(args) {
         const p = parseFlags("explain", args, spec("explain").flags, 1);
-        const cwd = process.cwd();
-        const worktree = await worktreeOf(cwd);
-        if (!worktree)
-            throw new AxiError("not inside a git repository", "VALIDATION_ERROR", [
-                "Run `thurview explain` inside the source worktree",
-            ]);
-        const existing = bool(p, "update") || str(p, "review") ? await resolveReview(str(p, "review")) : null;
-        if (existing && kindOf(existing) !== "explainer")
-            throw new AxiError(`${short(existing.id)} is a review, not an explainer`, "VALIDATION_ERROR", [
-                "Run `thurview scaffold --update --review <id>` to re-pin a review",
-                "Run `thurview explain` with no --review to start an explainer",
-            ]);
-        const scope = scopeGlob(p.positional[0] ?? existing?.binding.name);
-        let commit;
-        try {
-            commit = await g.revParse(worktree, str(p, "commit") ?? "HEAD");
-        }
-        catch (e) {
-            throw new AxiError(e.message, "VALIDATION_ERROR", [
-                "Pass a resolvable ref: `thurview explain --commit <ref>`",
-            ]);
-        }
-        // A scope that matches nothing is a typo, and an explainer of nothing would
-        // still publish and still state honest-looking coverage of zero files.
-        const files = await g.listFiles(worktree, commit);
-        const inScope = scope === "**" ? files : files.filter((f) => globToRegExp(scope).test(f));
-        if (!inScope.length)
-            throw new AxiError(`no file matches "${scope}" at ${commit.slice(0, 12)}`, "VALIDATION_ERROR", [
-                "Pass a path that exists at that commit: `thurview explain src/server`",
-                "Run `thurview explain` with no scope for the whole repository",
-            ]);
-        const binding = { kind: "codebase", name: scope };
-        const defaultTitle = scope === "**" ? worktree.split("/").pop() || "Codebase" : scope.replace(/\/\*\*$/, "");
-        let review;
-        let reused = false;
-        if (existing) {
-            review = existing;
-            review.pins = { base: commit, head: commit };
-            review.binding = binding;
-            if (str(p, "title"))
-                review.title = str(p, "title");
-            await writeReview(review);
-        }
-        else {
-            const match = bool(p, "new")
-                ? []
-                : (await reviewsFor(worktree)).filter((r) => kindOf(r) === "explainer" &&
-                    r.binding.name === scope &&
-                    r.status !== "accepted" &&
-                    r.status !== "closed");
-            if (match.length) {
-                review = match[0];
-                reused = true;
-                review.pins = { base: commit, head: commit };
-                await writeReview(review);
-            }
-            else {
-                const id = newId();
-                review = {
-                    schema: SCHEMA,
-                    id,
-                    kind: "explainer",
-                    title: str(p, "title") || defaultTitle,
-                    worktree,
-                    repoRoot: worktree,
-                    binding,
-                    pins: { base: commit, head: commit },
-                    status: "draft",
-                    revision: 0,
-                    dismissed: false,
-                    createdAt: now(),
-                    updatedAt: now(),
-                };
-                await mkdir(reviewDir(id), { recursive: true });
-                await writeText(join(reviewDir(id), "review.md"), TEMPLATE_EXPLAIN_MD(review.title));
-                await writeText(join(reviewDir(id), "data.yaml"), TEMPLATE_EXPLAIN_DATA);
-                await writeText(join(reviewDir(id), "map.yaml"), TEMPLATE_EXPLAIN_MAP);
-                await writeText(join(reviewDir(id), "theme.yaml"), TEMPLATE_THEME);
-                await writeReview(review);
-            }
-        }
+        const pinned = await pinOneCommit(p, EXPLAINER);
+        const { review, scope, commit, worktree } = pinned;
         const dir = reviewDir(review.id);
         return {
             explainer: {
@@ -818,7 +895,7 @@ const commands = {
                 scope,
                 commit,
                 worktree,
-                reused,
+                reused: pinned.reused,
                 dir,
             },
             files: {
@@ -827,7 +904,7 @@ const commands = {
                 map: join(dir, "map.yaml"),
                 theme: join(dir, "theme.yaml"),
             },
-            scale: { filesInScope: inScope.length },
+            scale: { filesInScope: pinned.inScope.length },
             guidance: await guidanceFiles(worktree),
             help: [
                 `Run \`thurview graph architecture --review ${short(review.id)}\` for the clusters, their hubs and the links between them`,
@@ -836,6 +913,40 @@ const commands = {
             ],
         };
     },
+    async design(args) {
+        const p = parseFlags("design", args, spec("design").flags, 1);
+        const pinned = await pinOneCommit(p, DESIGN);
+        const { review, scope, commit, worktree } = pinned;
+        const dir = reviewDir(review.id);
+        return {
+            design: {
+                id: short(review.id),
+                uuid: review.id,
+                kind: "design",
+                title: review.title,
+                status: review.status,
+                rev: review.revision,
+                scope,
+                commit,
+                worktree,
+                reused: pinned.reused,
+                dir,
+            },
+            files: {
+                document: join(dir, "review.md"),
+                data: join(dir, "data.yaml"),
+                map: join(dir, "map.yaml"),
+                theme: join(dir, "theme.yaml"),
+            },
+            scale: { filesInScope: pinned.inScope.length },
+            guidance: await guidanceFiles(worktree),
+            help: [
+                `Run \`thurview graph architecture --review ${short(review.id)}\` for the structure the design has to fit`,
+                `Declare in ${join(dir, "data.yaml")} what the design would add, change or remove, each anchored to the code it lands in today`,
+                `Edit ${join(dir, "review.md")}, then run \`thurview publish --review ${short(review.id)}\``,
+            ],
+        };
+    },
     async info(args) {
         const p = parseFlags("info", args, spec("info").flags);
         const fields = new Set((str(p, "fields") ?? "").split(",").filter(Boolean));
@@ -1009,7 +1120,7 @@ const commands = {
         if (review.binding.kind === "codebase") {
             const tip = await g.revParse(review.worktree, "HEAD").catch(() => null);
             if (tip && tip !== review.pins.head)
-                warnings.push(`HEAD has moved past the pinned commit; run \`thurview explain --update --review ${short(review.id)}\` to re-pin`);
+                warnings.push(`HEAD has moved past the pinned commit; run \`${repinCommand(kind)} --update --review ${short(review.id)}\` to re-pin`);
         }
         if (review.binding.kind === "branch") {
             const tip = await g.revParse(review.worktree, review.binding.name).catch(() => null);
@@ -1064,7 +1175,9 @@ const commands = {
                 map: !!map,
                 ...(kind === "explainer"
                     ? { coverage: coverage ? coverage.verdict : "(unavailable)" }
-                    : { interfaces: doc.document.interfaces?.verdict ?? "(unavailable)" }),
+                    : kind === "design"
+                        ? { proposes: doc.document.interfaces?.verdict ?? "(unavailable)" }
+                        : { interfaces: doc.document.interfaces?.verdict ?? "(unavailable)" }),
                 theme: theme?.name ?? "default",
                 url: url ?? "(server not running)",
             },
@@ -1269,8 +1382,8 @@ const commands = {
         }
         // A next step has to name the same commits, or it answers about another change.
         const again = review ? "" : ` --base ${short(t.pins.base)} --head ${short(t.pins.head)}`;
-        if (review && kindOf(review) === "explainer" && (sub === "interfaces" || sub === "impact"))
-            throw new AxiError(`graph ${sub} compares two commits; an explainer is pinned to one`, "VALIDATION_ERROR", [
+        if (review && kindOf(review) !== "review" && (sub === "interfaces" || sub === "impact"))
+            throw new AxiError(`graph ${sub} compares two commits; ${kindOf(review) === "design" ? "a design" : "an explainer"} is pinned to one`, "VALIDATION_ERROR", [
                 `Run \`thurview graph architecture --review ${short(review.id)}\` for the structure at that commit`,
                 `Run \`thurview graph callers <name> --review ${short(review.id)}\` to follow one symbol`,
             ]);
@@ -1343,9 +1456,11 @@ const commands = {
                 ],
             };
         }
-        // An explainer is scoped to a path, so its structure is that path's, not the
-        // repository's: the same bound the Coverage tab accounts for.
-        if (review && kindOf(review) === "explainer") {
+        // An explainer and a design are both scoped to a path and pinned to one
+        // commit, so the structure they get back is that path's, not the
+        // repository's: for an explainer, the same bound the Coverage tab accounts
+        // for; for a design, the structure it has to fit.
+        if (review && kindOf(review) !== "review") {
             const scope = review.binding.name;
             const g0 = scopeGraph(head, scope);
             const allFiles = await g.listFiles(t.worktree, t.pins.head);
@@ -1500,10 +1615,11 @@ const commands = {
         const usage = [
             "thurview forge status [--change <ref>] [--review <id>]",
             "thurview forge prior [--change <ref>] [--mine] [--full]",
+            "thurview forge pass [--review <id>] [--out <path>]",
             "thurview forge submit --file <path> [--dry-run] [--confirm]",
             'thurview forge reply <threadId> --body "<text>" [--resolve --at <sha>]',
         ];
-        if (!sub || !["status", "prior", "submit", "reply"].includes(sub))
+        if (!sub || !["status", "prior", "pass", "submit", "reply"].includes(sub))
             throw new AxiError(`unknown forge command${sub ? ` ${sub}` : ""}`, "VALIDATION_ERROR", usage);
         const common = {
             review: s["review"],
@@ -1618,6 +1734,70 @@ const commands = {
                     : ["This is the first pass; there is no prior review to answer"],
             };
         }
+        if (sub === "pass") {
+            const p = parseFlags("forge pass", rest, { review: s["review"], out: s["out"] });
+            // Approve and close both end the review, so a pass has to be able to
+            // reach a finished one - but only when no active review answers first,
+            // or a review the reader finished last week shadows the one in hand.
+            const review = await resolveReview(str(p, "review")).catch((e) => {
+                if (e instanceof AxiError && e.code === "NOT_FOUND")
+                    return resolveReview(str(p, "review"), { terminal: true });
+                throw e;
+            });
+            const t = await readThreads(review.id);
+            const id = short(review.id);
+            const decision = t.decisions[t.decisions.length - 1];
+            if (!decision)
+                throw new AxiError(`review ${id} has no decision to carry to the forge`, "NOT_FOUND", [
+                    "The reader decides in the browser; nothing is posted before they submit",
+                    `Run \`thurview wait --review ${id}\` to block until they do`,
+                ]);
+            const plan = buildPass(t.threads, decision);
+            const out = resolve(process.cwd(), str(p, "out") ?? passFile(review.id));
+            const text = JSON.stringify(plan.submission, null, 2) + "\n";
+            // Checked by the parser `submit` reads it with, so a file this wrote is
+            // never one that command refuses.
+            parseSubmission(text, out);
+            await writeText(out, text);
+            return {
+                pass: {
+                    review: id,
+                    file: out,
+                    decision: plan.decision,
+                    verdict: plan.submission.verdict,
+                    ...(plan.verdictReason ? { why: plan.verdictReason } : {}),
+                    inline: plan.inline.length,
+                    summary: plan.summary.length,
+                    skipped: plan.skipped.length,
+                    anchoredAt: review.pins.head,
+                },
+                comments: plan.inline.length
+                    ? plan.inline.map((c) => ({ thread: c.thread, at: c.at, side: c.side }))
+                    : "0 (a summary-only pass)",
+                summary: plan.summary.length
+                    ? plan.summary.map((x) => ({ thread: x.thread, target: x.target, why: x.why }))
+                    : "0 (every comment is anchored to a line)",
+                skipped: plan.skipped.length
+                    ? plan.skipped.map((x) => ({ thread: x.thread, target: x.target, why: x.why }))
+                    : "0 (no question, resolved or held thread to leave out)",
+                help: [
+                    `Read ${out} before it is posted; the file is the thing a human checks`,
+                    `Every anchor is a line at ${review.pins.head.slice(0, 12)}; run \`thurview forge status --review ${id}\` first, because a forge refuses a comment on a line its current head does not have`,
+                    `Run \`thurview forge submit --review ${id} --file ${out} --dry-run\` to see what would reach the change request`,
+                    "Tell the reader which comments went to the summary, and why they are not on their line",
+                    ...(decision.revision === review.revision
+                        ? []
+                        : [
+                            `The decision is the reader's on revision ${decision.revision} and the review is at ${review.revision}; they have not judged what you published since`,
+                        ]),
+                    ...(review.binding.kind === "pr"
+                        ? []
+                        : [
+                            `This review is bound to ${review.binding.name}, not to a change request; \`forge submit\` will need --change <ref>`,
+                        ]),
+                ],
+            };
+        }
         if (sub === "submit") {
             const p = parseFlags("forge submit", rest, {
                 ...common,
@@ -1826,7 +2006,7 @@ const commands = {
             return {
                 skill: installed,
                 help: [
-                    "Invoke them as /thurview and /review-fix in Claude Code, or by name in other agents",
+                    `Invoke them as ${names.map((n) => `/${n}`).join(", ")} in Claude Code, or by name in other agents`,
                     "Run `thurview setup hooks` for ambient context at session start",
                 ],
             };