@shiyuphan/follow-me 0.1.1 → 0.2.0

package/dist/src/prompt.js

@@ -73,14 +73,28 @@ function describeAnchor(anchor) {
 }
 function renderComment(comment) {
     const lines = [`- ${comment.id}  on ${describeAnchor(comment.anchor)}`];
+    if (comment.follows)
+        lines.push(`  asks again after ${comment.follows}`);
     if (comment.context.commitMessage) {
         lines.push(`  commit message then: ${JSON.stringify(comment.context.commitMessage)}`);
     }
     if (comment.context.path)
         lines.push(`  path: ${comment.context.path}`);
+    if (comment.context.lines && comment.context.lines.length > 0) {
+        lines.push("  lines asked about:", ...comment.context.lines.map((l) => `    ${l}`));
+    }
+    if (comment.severity)
+        lines.push(`  severity: ${comment.severity}`);
     lines.push(`  comment: ${JSON.stringify(comment.body)}`);
+    for (const reply of comment.replies ?? []) {
+        lines.push(`  ${reply.author} replied: ${JSON.stringify(reply.body)}`);
+    }
     return lines.join("\n");
 }
+const QUESTIONS = `A question is not a request to change the plan. Answer it by explaining, not by moving lines. Where the asked-about lines now live, add or rewrite the \`narration\` of that commit or unit so it answers the question, in plain spoken sentences. When the answer is about flow, structure or order across files, add a \`diagram\` there too. Then write one response with \`"status": "answered"\`, a \`note\` of one to three sentences that answers the question directly, and \`"at"\` naming the commit (1-based) and unit that carry the explanation. Move lines only if answering shows the order itself was wrong. Say so in the note, and answer the question as well. If the diff cannot answer it, use \`"deferred"\` and say what is missing.`;
+const CONCERNS = `You are also a careful reviewer. Add a concern only for something you would raise in a pull request: a bug or unhandled case, a change with no test where one is expected, a name that misleads, or a risky change such as a migration, concurrency or security. Pin it to the change lines with \`lines\`. Say what goes wrong and when, in one or two sentences. Severity: \`blocker\` breaks behaviour or loses data, \`major\` should be fixed before merge, \`minor\` is worth a note. Do not flag style, formatting or taste. Do not repeat the narration. Most commits deserve no concern, and a plan with none is fine. Never write more than one concern per unit. Concerns are in your voice as a reviewer, while narration stays the author's.
+
+A concern is \`{ "severity": "blocker" | "major" | "minor", "kind": "bug" | "missing-test" | "naming" | "risk", "text": "...", "lines": [0, 1] }\`. \`lines\` holds change indices of that unit and is allowed only on a unit ref. Write \`"concerns": [ ... ]\` on a commit, or on a unit written as an object: \`{ "unit": "h_x:0-3", "concerns": [ ... ] }\`. Never write an id; follow-me derives one.`;
 const ORDERING = `Order the commits so the story reads naturally:
 - Scaffolding and types come before the code that uses them.
 - A failing test comes before the fix that makes it pass.
@@ -90,7 +104,7 @@ const ORDERING = `Order the commits so the story reads naturally:
 - The last commit must bring the tree to exactly the tip, which follows from covering every unit.
 
 Write each commit message as a short imperative title, then a blank line and a body that
-says why.`;
+says why. Keep the title to 50 characters or fewer; put detail in the body.`;
 const GOALS = {
     split: {
         title: "plan the commits",
@@ -136,8 +150,21 @@ const FORMAT = (draftPath, base, tip) => `Write the plan as JSON to ${draftPath}
 
 \`narration\` is optional on a commit and on a unit. A unit with narration is written as
 \`{ "unit": "<ref>", "narration": "..." }\` instead of the plain ref string.
+
+\`diagram\` is optional on a commit and on a unit, written the same way:
+\`{ "unit": "<ref>", "diagram": "..." }\`. It is Mermaid source that the review page draws beside
+the code: a commit's diagram while its commit is on screen, a unit's while playback is on that
+unit. Add one only where a picture says what the code and prose cannot: data flowing between
+modules, a state machine, a call graph, or the before and after shape of a structure. Most commits
+need none. The first line names the diagram type, for example:
+
+  "diagram": "flowchart LR\\n  parse --> validate --> apply"
+
+Narration stays plain text even when a diagram is present, because it is read aloud.
 \`responses\` is [] when there are no review comments. \`status\` is one of "addressed",
-"declined" or "deferred", and \`note\` says what you did or why not.`;
+"declined", "deferred" or, for a question, "answered", and \`note\` says what you did or why not.
+An "answered" response also carries \`"at": { "commit": 3, "unit": "h_x" }\`: the commit, counted from 1,
+and optionally the unit that holds the explanation.`;
 const RULES = (checkCommand) => `- A unit is "h_…" (a text hunk), "f_…" (a whole file) or "m_…" (a mode change).
 - "h_x:0-3,7" takes change lines 0, 1, 2, 3 and 7 of hunk h_x. Indices are the [n] shown below.
 - A bare "h_x" takes every change line of that hunk that no other commit claimed.
@@ -145,50 +172,61 @@ const RULES = (checkCommand) => `- A unit is "h_…" (a text hunk), "f_…" (a w
 - Use the unit ids exactly as printed. Do not invent ids.
 - "f_…" and "m_…" units are taken whole, never with a line list.
 - Every commit needs a non-empty message and at least one unit.
-- Check your work with \`${checkCommand}\` and fix every issue it prints.`;
+- Keep every file syntactically whole in every commit: a function with its closing brace, a block with both ends, an import before or with its first use. Commits need not build or pass tests, but each file a commit writes must parse.
+- Check your work with \`${checkCommand}\` and fix every issue it prints, syntax errors included.`;
 /** The planner prompt for a coding agent. Pure and deterministic for the same input. */
 export function renderPrompt(input) {
     const { diff, draftPath } = input;
     const { title, goal } = GOALS[input.mode];
-    const sections = [
+    const head = [
         `# follow-me: ${title}\n\n${goal}`,
         `## Output format\n\n${FORMAT(draftPath, diff.base, diff.tip)}`,
         `## Rules\n\n${RULES(input.checkCommand)}`,
-        `## Units\n\nChange lines are shown as \`[n]+ text\` or \`[n]- text\`. Indented lines without a bracket are context and cannot be selected.\n\n${renderUnits(diff)}`,
     ];
-    if (input.mode === "walk")
+    const units = `## Units\n\nChange lines are shown as \`[n]+ text\` or \`[n]- text\`. Indented lines without a bracket are context and cannot be selected.\n\n${renderUnits(diff)}`;
+    if (input.mode === "walk") {
+        const sections = [
+            ...head,
+            `## Concerns\n\n${CONCERNS}`,
+            `## Questions from the reviewer\n\n${QUESTIONS}`,
+            units,
+        ];
         return `${sections.join("\n\n")}\n`;
+    }
+    const sections = [...head, units];
     const { previousPlan, review } = input;
     if (previousPlan) {
         sections.push(`## Previous plan\n\nCommits are numbered from 1.\n\n${renderPreviousPlan(previousPlan)}`);
     }
-    if (review && review.comments.length > 0) {
+    const asked = review?.comments.filter((c) => c.kind === "question") ?? [];
+    const changes = review?.comments.filter((c) => c.kind !== "question") ?? [];
+    const questions = [`## Questions from the reviewer\n`, QUESTIONS];
+    if (review && asked.length > 0) {
+        questions.push(`\nThe reviewer asked ${asked.length === 1 ? "this question" : "these questions"} about plan v${review.planVersion}. Commits are numbered from 1. Write one response for each.\n`, asked.map(renderComment).join("\n"));
+    }
+    sections.push(questions.join("\n"));
+    if (review && changes.length > 0) {
         sections.push([
             `## Open review comments\n`,
             `A reviewer commented on plan v${review.planVersion}. Commits are numbered from 1.`,
             "Answer every comment below with one entry in `responses`, changing the plan where you agree.\n",
-            review.comments.map(renderComment).join("\n"),
+            changes.map(renderComment).join("\n"),
         ].join("\n"));
     }
     return `${sections.join("\n\n")}\n`;
 }
 /** The owning commit of each change line of a hunk, or null when the plan leaves it out. */
-function ownersOf(plan, hunk) {
+function ownersOf(commits, hunk) {
     const owners = new Array(hunk.changeCount).fill(null);
-    const rest = [];
-    plan.commits.forEach((commit, k) => {
-        for (const ref of commit.units) {
-            if (ref.unit !== hunk.id)
+    commits.forEach((commit, k) => {
+        for (const ref of commit.refs) {
+            if (ref.unit !== hunk.id || ref.select.kind !== "lines")
                 continue;
-            if (ref.select.kind === "rest")
-                rest.push(k);
-            else
-                for (const c of ref.select.changes)
-                    owners[c] = k;
+            for (const c of ref.select.changes)
+                owners[c] = k;
         }
     });
-    const restOwner = rest[0] ?? null;
-    return owners.map((o) => o ?? restOwner);
+    return owners;
 }
 /**
  * The hunk as it reads in commit `k`: context, lines earlier commits left in place, and this
@@ -232,93 +270,274 @@ function fence(lines) {
     return "`".repeat(Math.max(3, longest + 1));
 }
 const EXCERPT_CONTEXT = 3;
-function renderCodeComment(comment, plan, units) {
-    const { anchor } = comment;
-    const hunk = anchor.kind === "hunk" ? units.get(anchor.unit) : undefined;
-    if (anchor.kind !== "hunk" || hunk?.kind !== "hunk") {
-        return [`### ${comment.id}`, "", comment.body, ""];
-    }
-    let lines = excerpt(hunk, tipStartOf(hunk, units), ownersOf(plan, hunk), anchor.commit);
-    const picked = anchor.changes;
+/** The lines of a hunk as commit `k` writes them, cut to the picked change lines. Null if no hunk. */
+function quoteHunk(units, commits, unit, k, picked) {
+    const hunk = units.get(unit);
+    if (hunk?.kind !== "hunk")
+        return null;
+    let lines = excerpt(hunk, tipStartOf(hunk, units), ownersOf(commits, hunk), k);
     const marked = lines.flatMap((l, i) => l.change !== null && (picked === null || picked.includes(l.change)) ? [i] : []);
     const first = marked[0];
     const last = marked.at(-1);
-    const at = first === undefined ? undefined : lines[first];
-    const where = at === undefined ? "" : `, line ${at.tipLine}`;
+    const line = first === undefined ? null : (lines[first]?.tipLine ?? null);
     if (picked !== null && first !== undefined && last !== undefined) {
         lines = lines.slice(Math.max(0, first - EXCERPT_CONTEXT), last + EXCERPT_CONTEXT + 1);
     }
-    const text = lines.map((l) => l.text);
-    const f = fence(text);
-    return [`### ${comment.id}${where}`, "", `${f}diff`, ...text, f, "", comment.body, ""];
-}
-/** A reviewer's code review for the author, grouped by file in diff order. */
-function renderCodeReview(review, plan, units) {
-    const out = ["# Code review", ""];
-    if (review.comments.length === 0) {
-        out.push("The reviewer left no comments.", "");
-        return out.join("\n");
+    return { line, text: lines.map((l) => l.text) };
+}
+const SEVERITY_RANK = { blocker: 0, major: 1, minor: 2 };
+function lineLabel(line, fallback) {
+    return line === null ? fallback : `line ${line}`;
+}
+function whereComment(ctx, c) {
+    const { anchor } = c;
+    switch (anchor.kind) {
+        case "plan":
+            return { path: null, line: null, label: "whole plan", quote: [] };
+        case "message":
+            return { path: null, line: null, label: `commit ${anchor.commit + 1} message`, quote: [] };
+        case "position":
+            return { path: null, line: null, label: `commit ${anchor.commit + 1} position`, quote: [] };
+        case "hunk": {
+            const quoted = quoteHunk(ctx.units, ctx.commits, anchor.unit, anchor.commit, anchor.changes);
+            const path = ctx.units.get(anchor.unit)?.path ?? c.context.path;
+            if (quoted === null) {
+                return {
+                    path,
+                    line: null,
+                    label: "code that has since changed",
+                    quote: c.context.lines ?? [],
+                };
+            }
+            return {
+                path,
+                line: quoted.line,
+                label: lineLabel(quoted.line, anchor.unit),
+                quote: quoted.text,
+            };
+        }
+        default: {
+            const exhaustive = anchor;
+            return exhaustive;
+        }
     }
-    out.push(`A reviewer watched this branch being written commit by commit and left ${review.comments.length === 1 ? "1 comment" : `${review.comments.length} comments`}.`, "");
+}
+function whereConcern(ctx, kept) {
+    const { concern, commit } = kept;
+    if (concern.unit === undefined) {
+        return { path: null, line: null, label: `commit ${commit + 1}`, quote: [] };
+    }
+    const path = ctx.units.get(concern.unit)?.path ?? null;
+    const quoted = quoteHunk(ctx.units, ctx.commits, concern.unit, commit, concern.lines ?? null);
+    if (quoted === null)
+        return { path, line: null, label: concern.unit, quote: [] };
+    return {
+        path,
+        line: quoted.line,
+        label: lineLabel(quoted.line, concern.unit),
+        quote: quoted.text,
+    };
+}
+/** Whether a comment is about the same lines as a concern: same unit, and lines that intersect. */
+function overlaps(kept, c) {
+    const { anchor } = c;
+    const { concern } = kept;
+    if (concern.unit === undefined) {
+        return ((anchor.kind === "message" || anchor.kind === "position") && anchor.commit === kept.commit);
+    }
+    if (anchor.kind !== "hunk" || anchor.unit !== concern.unit)
+        return false;
+    if (anchor.changes === null || concern.lines === undefined)
+        return true;
+    const mine = concern.lines;
+    return anchor.changes.some((n) => mine.includes(n));
+}
+function keptConcerns(review, commits) {
+    const decisions = new Map((review.concerns ?? []).map((d) => [d.concern, d]));
+    return commits.flatMap((commit, k) => (commit.concerns ?? []).flatMap((concern) => {
+        const decision = decisions.get(concern.id);
+        if (decision?.decision !== "kept")
+            return [];
+        return [
+            {
+                concern,
+                commit: k,
+                severity: decision.severity ?? concern.severity,
+                note: decision.note ?? null,
+            },
+        ];
+    }));
+}
+function strongest(severities) {
+    return severities.reduce((best, s) => {
+        if (s === null)
+            return best;
+        return best === null || SEVERITY_RANK[s] < SEVERITY_RANK[best] ? s : best;
+    }, null);
+}
+/** Kept concerns and rated or code comments become items; a comment joins the concern it overlaps. */
+function buildItems(ctx, kept, comments) {
+    const items = kept.map((k) => ({
+        where: whereConcern(ctx, k),
+        severity: k.severity,
+        kept: k,
+        comments: [],
+    }));
+    const merged = new Map();
+    const alone = [];
+    for (const c of comments) {
+        const home = items.find((item) => item.kept !== null && overlaps(item.kept, c));
+        if (home !== undefined)
+            merged.set(home, [...(merged.get(home) ?? []), c]);
+        else {
+            alone.push({
+                where: whereComment(ctx, c),
+                severity: c.severity ?? null,
+                kept: null,
+                comments: [c],
+            });
+        }
+    }
+    const joined = items.map((item) => {
+        const mine = merged.get(item) ?? [];
+        return {
+            ...item,
+            severity: strongest([item.severity, ...mine.map((c) => c.severity ?? null)]),
+            comments: mine,
+        };
+    });
+    return [...joined, ...alone];
+}
+/** Files in diff order, then by line on the branch; items without a line close their file. */
+function sortItems(items, units) {
     const order = new Map();
     for (const u of units.values())
         if (!order.has(u.path))
             order.set(u.path, order.size);
-    const byPath = new Map();
-    const general = [];
-    for (const c of review.comments) {
-        const path = c.anchor.kind === "hunk" ? c.context.path : null;
-        if (path === null)
-            general.push(c);
-        else
-            byPath.set(path, [...(byPath.get(path) ?? []), c]);
-    }
-    const rank = (path) => order.get(path) ?? order.size;
-    const paths = [...byPath.keys()].sort((a, b) => rank(a) - rank(b) || a.localeCompare(b));
-    for (const path of paths) {
-        out.push(`## ${path}`, "");
-        for (const c of byPath.get(path) ?? [])
-            out.push(...renderCodeComment(c, plan, units));
-    }
-    if (general.length > 0) {
-        out.push("## General", "");
-        for (const c of general)
-            out.push(...renderCodeComment(c, plan, units));
+    const rank = (path) => path === null ? order.size + 1 : (order.get(path) ?? order.size);
+    return items
+        .map((item, i) => ({ item, i }))
+        .sort((a, b) => rank(a.item.where.path) - rank(b.item.where.path) ||
+        (a.item.where.line ?? Number.MAX_SAFE_INTEGER) -
+            (b.item.where.line ?? Number.MAX_SAFE_INTEGER) ||
+        a.i - b.i)
+        .map(({ item }) => item);
+}
+function quoteBlock(quote) {
+    if (quote.length === 0)
+        return [];
+    const f = fence(quote);
+    return [`${f}diff`, ...quote, f];
+}
+function voices(item) {
+    const { kept } = item;
+    const out = [];
+    if (kept !== null)
+        out.push(`Agent: ${kept.concern.text}`);
+    if (kept?.note)
+        out.push(`Reviewer: ${kept.note}`);
+    for (const c of item.comments) {
+        out.push(`Reviewer: ${c.body}`, ...renderReplies(c));
     }
-    out.push("Address each comment above in the code on this branch, then tell the reviewer what you changed and what you chose not to change and why.", "");
-    return out.join("\n");
+    return out;
 }
-/**
- * A markdown digest of a review for `follow-me feedback`. A split review is plan feedback for
- * the planner; a walk review is a code review for the author.
- */
-export function renderFeedback(review, plan, units) {
-    if (review.mode === "walk")
-        return renderCodeReview(review, plan, units);
-    const out = [`# Review of plan v${review.planVersion}`, ""];
-    if (review.comments.length === 0) {
-        out.push("No comments.", "");
-        return out.join("\n");
+function renderReplies(c) {
+    return (c.replies ?? []).flatMap((r) => {
+        const label = r.author === "agent" ? "Agent replied" : "Reviewer replied";
+        return [
+            `${label}: ${r.body}`,
+            ...(r.diagram === undefined ? [] : ["```mermaid", r.diagram.trimEnd(), "```"]),
+        ];
+    });
+}
+function itemHeading(item, level) {
+    const { where, kept } = item;
+    const parts = [where.label, item.severity ?? "unrated"];
+    if (kept !== null)
+        parts.push(kept.concern.kind);
+    parts.push(kept === null ? "raised by the reviewer" : "raised by the agent, kept by the reviewer");
+    return `${"#".repeat(level)} ${parts.join(" · ")}`;
+}
+function renderItems(items, units, level) {
+    const out = [];
+    const sorted = sortItems(items, units);
+    const paths = [...new Set(sorted.flatMap((i) => (i.where.path === null ? [] : [i.where.path])))];
+    const group = (title, members) => {
+        if (members.length === 0)
+            return;
+        out.push(`${"#".repeat(level)} ${title}`, "");
+        for (const item of members) {
+            out.push(itemHeading(item, level + 1), "", ...quoteBlock(item.where.quote));
+            if (item.where.quote.length > 0)
+                out.push("");
+            out.push(...voices(item), "");
+        }
+    };
+    for (const path of paths)
+        group(path, sorted.filter((i) => i.where.path === path));
+    group("General", sorted.filter((i) => i.where.path === null));
+    return out;
+}
+function summarizeIssues(items) {
+    if (items.length === 0)
+        return "no issues";
+    const count = (s) => items.filter((i) => i.severity === s).length;
+    const tally = [
+        [count("blocker"), "blocker"],
+        [count("major"), "major"],
+        [count("minor"), "minor"],
+        [count(null), "unrated"],
+    ];
+    const parts = tally.flatMap(([n, label]) => (n === 0 ? [] : [`${n} ${label}`]));
+    return `${items.length} ${items.length === 1 ? "issue" : "issues"}: ${parts.join(", ")}`;
+}
+function renderQuestions(ctx, questions, responses) {
+    const items = sortItems(questions.map((c) => ({ where: whereComment(ctx, c), comment: c })), ctx.units);
+    const out = ["## Questions", ""];
+    for (const { where, comment } of items) {
+        const place = where.path === null ? where.label : `${where.path} · ${where.label}`;
+        out.push(`### ${comment.id} · ${place}`, "", ...quoteBlock(where.quote));
+        if (where.quote.length > 0)
+            out.push("");
+        out.push(`Reviewer asked: ${comment.body}`, ...renderReplies(comment));
+        const answer = responses.find((r) => r.comment === comment.id);
+        if (answer !== undefined) {
+            const at = answer.at;
+            const explained = at === undefined
+                ? ""
+                : `, explained in commit ${at.commit}${at.unit === undefined ? "" : ` (${at.unit})`}`;
+            out.push(`Answer (${answer.status}${explained}): ${answer.note}`);
+        }
+        else if ((comment.replies ?? []).length === 0)
+            out.push("Not answered yet.");
+        out.push("");
     }
-    const planLevel = review.comments.filter((c) => c.anchor.kind === "plan");
+    return out;
+}
+/** Plan feedback for a split review: what the planner answers through `responses`. */
+function renderPlanFeedback(commits, comments) {
+    const out = [];
+    const line = (c) => [`- ${c.id} on ${describeAnchor(c.anchor)}`];
+    const planLevel = comments.filter((c) => c.anchor.kind === "plan");
     if (planLevel.length > 0) {
         out.push("## Whole plan", "");
         for (const c of planLevel)
-            out.push(`- ${c.id}: ${c.body}`);
+            out.push(`- ${c.id}: ${c.body}`, ...renderReplies(c));
         out.push("");
     }
-    const placed = plan.commits.length;
-    const orphans = review.comments.filter((c) => c.anchor.kind !== "plan" && c.anchor.commit >= placed);
-    plan.commits.forEach((commit, i) => {
-        const mine = review.comments.filter((c) => c.anchor.kind !== "plan" && c.anchor.commit === i);
+    const orphans = comments.filter((c) => c.anchor.kind !== "plan" && c.anchor.commit >= commits.length);
+    commits.forEach((commit, i) => {
+        const mine = comments.filter((c) => c.anchor.kind !== "plan" && c.anchor.commit === i);
         if (mine.length === 0)
             return;
         out.push(`## Commit ${i + 1}: ${commit.message.split("\n")[0] ?? ""}`, "");
         for (const c of mine) {
-            out.push(`- ${c.id} on ${describeAnchor(c.anchor)}`);
+            out.push(...line(c));
             if (c.context.path)
                 out.push(`  - file: ${c.context.path}`);
             out.push(`  - ${c.body.split("\n").join("\n    ")}`);
+            for (const reply of renderReplies(c))
+                out.push(`  - ${reply}`);
         }
         out.push("");
     });
@@ -328,6 +547,96 @@ export function renderFeedback(review, plan, units) {
             out.push(`- ${c.id}: ${c.body}`);
         out.push("");
     }
-    out.push("Answer every comment id above in `responses` of the next draft, then run `follow-me check` and `follow-me apply`.", "");
+    return out;
+}
+/**
+ * The consolidated report of a review, in the voices of both the reviewer and the agent: the
+ * reviewer's comments and the agent's concerns the reviewer kept, grouped by file and ordered by
+ * line, then the questions with their answers. A walk review is a code review for the author. A
+ * split review is plan feedback for the planner, followed by the same code issues and questions.
+ * Concerns the reviewer has not decided are left out, as are those dismissed.
+ */
+export function renderReport(review, commits, units, opts) {
+    const ctx = { commits, units };
+    const walk = review.mode === "walk";
+    const questions = review.comments.filter((c) => c.kind === "question");
+    const rest = review.comments.filter((c) => c.kind !== "question");
+    const issues = walk ? rest : rest.filter((c) => c.severity !== undefined);
+    const feedback = walk ? [] : rest.filter((c) => c.severity === undefined);
+    const items = buildItems(ctx, keptConcerns(review, commits), issues);
+    const out = [];
+    if (walk) {
+        out.push(`# Code review: ${opts.branch} (${commits.length === 1 ? "1 commit" : `${commits.length} commits`}, ${summarizeIssues(items)})`, "");
+        if (items.length === 0 && questions.length === 0)
+            out.push("The reviewer raised no issues.", "");
+        out.push(...renderItems(items, units, 2));
+    }
+    else {
+        out.push(`# Review of plan v${review.planVersion}`, "");
+        if (feedback.length === 0 && items.length === 0 && questions.length === 0) {
+            out.push("No comments.", "");
+            return out.join("\n");
+        }
+        out.push(...renderPlanFeedback(commits, feedback));
+        if (items.length > 0) {
+            out.push(`## Code issues (${summarizeIssues(items)})`, "", ...renderItems(items, units, 3));
+        }
+    }
+    if (questions.length > 0)
+        out.push(...renderQuestions(ctx, questions, opts.responses));
+    if (walk && items.length > 0) {
+        out.push("Address each issue above in the code on this branch, then tell the reviewer what you changed and what you chose not to change and why.", "");
+    }
+    if (!walk && (feedback.length > 0 || questions.length > 0)) {
+        out.push("Answer every comment id above in `responses` of the next draft, then run `follow-me check` and `follow-me apply`.", "");
+    }
+    if (!walk && items.length > 0) {
+        out.push("Fix the code issues on the original branch, then run `follow-me extract` again.", "");
+    }
     return out.join("\n");
 }
+function renderEvent(event) {
+    switch (event.type) {
+        case "comment":
+        case "comment-updated": {
+            const { comment: c } = event;
+            const what = c.kind === "question" ? "question" : "comment";
+            const verb = event.type === "comment" ? "new" : "edited";
+            const lines = [`- ${verb} ${what} ${c.id} on ${describeAnchor(c.anchor)}`];
+            if (c.context.path)
+                lines.push(`  - file: ${c.context.path}`);
+            if (c.severity)
+                lines.push(`  - severity: ${c.severity}`);
+            if (c.follows)
+                lines.push(`  - asks again after ${c.follows}`);
+            lines.push(`  - ${c.body.split("\n").join("\n    ")}`);
+            return lines;
+        }
+        case "comment-deleted":
+            return [`- comment ${event.id} was deleted`];
+        case "reply":
+            return [`- ${event.reply.author} replied under ${event.commentId}: ${event.reply.body}`];
+        case "concern": {
+            const severity = event.severity === undefined ? "" : ` as ${event.severity}`;
+            const note = event.note === undefined ? "" : `: ${event.note}`;
+            return [`- concern ${event.concernId} ${event.decision}${severity}${note}`];
+        }
+        case "resolved":
+            return [`- question ${event.commentId} marked ${event.resolved ? "resolved" : "open again"}`];
+        case "version":
+            return [`- plan v${event.version} is now open`];
+        case "ended":
+            return [`- the reviewer ended the review; the report is next to ${event.review}`];
+        default: {
+            const exhaustive = event;
+            return exhaustive;
+        }
+    }
+}
+/** A markdown digest of what happened on the review page, for `follow-me watch`. */
+export function renderEvents(events) {
+    const first = events[0]?.seq;
+    const last = events.at(-1)?.seq;
+    const range = first === last ? `event ${first}` : `events ${first}-${last}`;
+    return [`# Review activity (${range})`, "", ...events.flatMap(renderEvent), ""].join("\n");
+}