@shiyuphan/follow-me 0.2.0 → 0.4.0

package/dist/src/prompt.js

@@ -1,3 +1,4 @@
+import { tipStartOf } from "./diff.js";
 /** Consecutive runs collapse: [0,1,2,3,7] becomes "0-3,7". */
 function formatRanges(changes) {
     const sorted = [...new Set(changes)].sort((a, b) => a - b);
@@ -53,7 +54,7 @@ function renderPreviousPlan(plan) {
     })
         .join("\n");
 }
-function describeAnchor(anchor) {
+function describeAnchor(anchor, ctx) {
     switch (anchor.kind) {
         case "plan":
             return "the whole plan";
@@ -62,7 +63,16 @@ function describeAnchor(anchor) {
         case "position":
             return `the position of commit ${anchor.commit + 1} (the reviewer thinks it belongs elsewhere)`;
         case "hunk": {
-            const where = anchor.changes === null ? "the whole unit" : `change lines ${formatRanges(anchor.changes)}`;
+            const pick = ctx === null ? null : pickRows(ctx, anchor);
+            if (pick !== null) {
+                const rows = formatRanges(pick.offsets);
+                return `${pick.label} in commit ${anchor.commit + 1} (${anchor.unit} rows ${rows}; ${pick.counts})`;
+            }
+            const where = anchor.offsets !== undefined
+                ? `rows ${formatRanges(anchor.offsets)}`
+                : anchor.changes === null
+                    ? "the whole unit"
+                    : `change lines ${formatRanges(anchor.changes)}`;
             return `${anchor.unit} (${where}) in commit ${anchor.commit + 1}`;
         }
         default: {
@@ -71,8 +81,92 @@ function describeAnchor(anchor) {
         }
     }
 }
-function renderComment(comment) {
-    const lines = [`- ${comment.id}  on ${describeAnchor(comment.anchor)}`];
+/** The hunk around the picked rows with the picked ones marked `>`; empty without offsets. */
+function anchorRows(ctx, anchor) {
+    return (ctx === null ? null : pickRows(ctx, anchor))?.rows ?? [];
+}
+const PICK_MARGIN = 3;
+function plural(n, noun) {
+    return `${n} ${noun}${n === 1 ? "" : "s"}`;
+}
+/**
+ * Resolves offsets against the hunk. Line numbers are the branch tip's, or the base's when a
+ * picked row is a removal, since a removed line has no tip number. Rows are shown as the commit
+ * writes them: its own changes marked +/-, everything else as context.
+ */
+function pickRows(ctx, anchor) {
+    if (anchor.kind !== "hunk" || anchor.offsets === undefined)
+        return null;
+    const hunk = ctx.units.get(anchor.unit);
+    const { offsets } = anchor;
+    const first = offsets[0];
+    const last = offsets.at(-1);
+    if (hunk?.kind !== "hunk" || first === undefined || last === undefined)
+        return null;
+    if (last >= hunk.body.length)
+        return null;
+    // Without the projected commit, the hunk is quoted as git shows it.
+    const projected = anchor.commit < ctx.commits.length;
+    const owners = ownersOf(ctx.commits, hunk);
+    const picked = new Set(offsets);
+    let tip = tipStartOf(hunk, ctx.units);
+    let base = hunk.oldStart + 1;
+    const rows = [];
+    const lines = [];
+    hunk.body.forEach((line, i) => {
+        lines.push({ op: line.op, tip, base });
+        let op = line.op;
+        let shown = true;
+        if (projected && line.op !== " ") {
+            const owner = owners[line.change] ?? null;
+            const applied = owner !== null && owner < anchor.commit;
+            if (owner !== anchor.commit) {
+                shown = line.op === "+" ? applied : !applied;
+                op = " ";
+            }
+        }
+        if (picked.has(i) && !shown) {
+            shown = true;
+            op = line.op;
+        }
+        const inWindow = i >= first - PICK_MARGIN && i <= last + PICK_MARGIN;
+        if (shown && inWindow)
+            rows.push(`${picked.has(i) ? ">" : " "} ${op}${stripEol(line.text)}`);
+        if (line.op !== "-")
+            tip += 1;
+        if (line.op !== "+")
+            base += 1;
+    });
+    const chosen = offsets.flatMap((i) => lines[i] ?? []);
+    const removal = chosen.some((l) => l.op === "-");
+    const numbers = removal
+        ? chosen.filter((l) => l.op !== "+").map((l) => l.base)
+        : chosen.map((l) => l.tip);
+    const from = Math.min(...numbers);
+    const to = Math.max(...numbers);
+    const range = from === to ? `${from}` : `${from}-${to}`;
+    const count = (op) => chosen.filter((l) => l.op === op).length;
+    const counts = [
+        count(" ") === 0 ? null : plural(count(" "), "context line"),
+        count("+") === 0 ? null : `${count("+")} added`,
+        count("-") === 0 ? null : `${count("-")} removed`,
+    ].filter((part) => part !== null);
+    return {
+        offsets,
+        label: `${hunk.path}:${range}${removal ? " (base side)" : ""}`,
+        range,
+        baseSide: removal,
+        line: from,
+        counts: counts.join(", "),
+        rows,
+        touchesContext: count(" ") > 0,
+    };
+}
+/** Said once wherever comments reach the agent, with the same words. */
+const CONTEXT_RULE = "A comment on a context row (marked `>` with no + or -) is about code this branch leaves alone or depends on. The plan cannot move it, so do not move lines because of it. Answer a question with an explanation, or point at the commit that last touched those lines. Answer a change request as a code issue, not by reordering.";
+function renderComment(comment, ctx) {
+    const lines = [`- ${comment.id}  on ${describeAnchor(comment.anchor, ctx)}`];
+    const rows = anchorRows(ctx, comment.anchor);
     if (comment.follows)
         lines.push(`  asks again after ${comment.follows}`);
     if (comment.context.commitMessage) {
@@ -80,7 +174,10 @@ function renderComment(comment) {
     }
     if (comment.context.path)
         lines.push(`  path: ${comment.context.path}`);
-    if (comment.context.lines && comment.context.lines.length > 0) {
+    if (rows.length > 0) {
+        lines.push("  rows asked about, picked ones marked >:", ...rows.map((r) => `    ${r}`));
+    }
+    else if (comment.context.lines && comment.context.lines.length > 0) {
         lines.push("  lines asked about:", ...comment.context.lines.map((l) => `    ${l}`));
     }
     if (comment.severity)
@@ -91,8 +188,8 @@ function renderComment(comment) {
     }
     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.
+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\` (the page shows it as your note) of that commit or unit so it answers the question, in plain 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 note. 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 the note 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:
@@ -104,7 +201,8 @@ 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. Keep the title to 50 characters or fewer; put detail in the body.`;
+says why. Put the why in the body first, before anything else. Keep the title to 50
+characters or fewer; put detail in the body.`;
 const GOALS = {
     split: {
         title: "plan the commits",
@@ -116,17 +214,16 @@ ${ORDERING}`,
     },
     walk: {
         title: "tell the story of this branch",
-        goal: `The reader is a reviewer meeting this branch for the first time. They will watch it
-being written commit by commit, hear your narration read aloud as each line appears, and
-comment on the code itself. The final tree is fixed. You decide how its change lines are
-grouped and ordered, and what the author is thinking while writing them.
+        goal: `The reader is a reviewer meeting this branch for the first time. They will read it commit
+by commit and comment on the code itself. The final tree is fixed. You decide how its change
+lines are grouped and ordered, and why each step is there.
 
 ${ORDERING}
 
-Give every commit a \`narration\`. Add one to a unit too wherever the why of that hunk is not
-obvious from the commit's narration. Narration should sound like someone thinking aloud at the
-keyboard: first person, present tense, two or three sentences, no markdown. Say why, not what
-the lines already show.`,
+Add a \`narration\` to a commit, or to a unit, only when it says something the commit message
+body does not. The page shows it as your note. A note is one plain paragraph on why, in plain
+text with no markdown. Say why, not what the lines already show. Leave it out when the body
+already says it.`,
     },
 };
 const FORMAT = (draftPath, base, tip) => `Write the plan as JSON to ${draftPath}. Write only the file, in this format:
@@ -139,7 +236,7 @@ const FORMAT = (draftPath, base, tip) => `Write the plan as JSON to ${draftPath}
     { "message": "Add the Token type\\n\\nThe parser needs it.", "units": ["h_0123456789ab", "h_ba9876543210:0-3,7"] },
     {
       "message": "Parse tokens",
-      "narration": "Now that tokens exist I can finally read them. I start with the happy path.",
+      "narration": "Tokens are read in one pass, so the loop below never backtracks.",
       "units": [{ "unit": "h_ba9876543210", "narration": "The loop is boring on purpose." }, "f_0123456789ab"]
     }
   ],
@@ -148,19 +245,18 @@ 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.
+\`narration\` is optional on a commit and on a unit, and the page shows it as your note. A unit
+with a note 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
+the code: a commit's diagram under its commit, a unit's under its hunk. 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.
+The note stays plain text even when a diagram is present.
 \`responses\` is [] when there are no review comments. \`status\` is one of "addressed",
 "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,
@@ -174,6 +270,35 @@ const RULES = (checkCommand) => `- A unit is "h_…" (a text hunk), "f_…" (a w
 - Every commit needs a non-empty message and at least one unit.
 - 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.`;
+function renderUnit(unit) {
+    return unit.kind === "hunk" ? renderHunk(unit) : renderOtherUnit(unit);
+}
+/** The vanished and new units, and the reviewer's comments on hunks that vanished, quoted. */
+function renderChanges(changes, input, ctx) {
+    const { since, vanished, added } = changes;
+    const gone = new Set(vanished.map((v) => v.unit.id));
+    const review = input.mode === "split" ? input.review : null;
+    const orphans = (review?.comments ?? []).filter((c) => c.author !== "agent" && c.anchor.kind === "hunk" && gone.has(c.anchor.unit));
+    const parts = [
+        `## Changes since v${since}\n`,
+        `The branch moved after plan v${since}. ${input.draftPath} already holds that plan on the new tip: every unit whose hunk did not change keeps its commit, and any commit left with no unit was dropped. Put each new unit below into a commit, an existing one or a new one, and keep the rest as it is.`,
+    ];
+    if (vanished.length > 0) {
+        parts.push(`\nThese units of v${since} changed, so their ids are gone:`, ...vanished.map(({ unit, commits }) => {
+            const where = commits
+                .map((c) => `commit ${c.index + 1} ${JSON.stringify(c.message.split("\n")[0] ?? "")}`)
+                .join(", ");
+            return `- ${unit.id}  ${unit.path}, was in ${where}`;
+        }));
+    }
+    if (added.length > 0) {
+        parts.push("\nNew units, in no commit yet:\n", added.map(renderUnit).join("\n\n"));
+    }
+    if (orphans.length > 0) {
+        parts.push(`\nThe reviewer commented on hunks that changed. Write a response for each saying what you changed, and post the same with \`follow-me reply <id>\`:\n`, orphans.map((c) => renderComment(c, ctx)).join("\n"));
+    }
+    return parts.join("\n");
+}
 /** The planner prompt for a coding agent. Pure and deterministic for the same input. */
 export function renderPrompt(input) {
     const { diff, draftPath } = input;
@@ -187,22 +312,34 @@ export function renderPrompt(input) {
     if (input.mode === "walk") {
         const sections = [
             ...head,
+            ...(input.changes === undefined
+                ? []
+                : [renderChanges(input.changes, input, { commits: [], units: diff.units })]),
             `## Concerns\n\n${CONCERNS}`,
-            `## Questions from the reviewer\n\n${QUESTIONS}`,
+            `## Questions from the reviewer\n\n${QUESTIONS}\n\n${CONTEXT_RULE}`,
             units,
         ];
         return `${sections.join("\n\n")}\n`;
     }
-    const sections = [...head, units];
+    const ctx = {
+        commits: input.previousCommits ?? [],
+        units: diff.units,
+    };
+    const sections = [
+        ...head,
+        ...(input.changes === undefined ? [] : [renderChanges(input.changes, input, ctx)]),
+        units,
+    ];
     const { previousPlan, review } = input;
     if (previousPlan) {
         sections.push(`## Previous plan\n\nCommits are numbered from 1.\n\n${renderPreviousPlan(previousPlan)}`);
     }
-    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];
+    const theirs = review?.comments.filter((c) => c.author !== "agent") ?? [];
+    const asked = theirs.filter((c) => c.kind === "question");
+    const changes = theirs.filter((c) => c.kind !== "question");
+    const questions = [`## Questions from the reviewer\n`, QUESTIONS, `\n${CONTEXT_RULE}`];
     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"));
+        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((c) => renderComment(c, ctx)).join("\n"));
     }
     sections.push(questions.join("\n"));
     if (review && changes.length > 0) {
@@ -210,7 +347,7 @@ export function renderPrompt(input) {
             `## 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",
-            changes.map(renderComment).join("\n"),
+            changes.map((c) => renderComment(c, ctx)).join("\n"),
         ].join("\n"));
     }
     return `${sections.join("\n\n")}\n`;
@@ -253,17 +390,6 @@ function excerpt(hunk, tipStart, owners, k) {
     }
     return lines;
 }
-/** Where the hunk starts in the tip: its base position shifted by earlier hunks of the file. */
-function tipStartOf(hunk, units) {
-    let shift = 0;
-    for (const u of units.values()) {
-        if (u.kind !== "hunk" || u.path !== hunk.path || u.oldStart >= hunk.oldStart)
-            continue;
-        for (const line of u.body)
-            shift += line.op === "+" ? 1 : line.op === "-" ? -1 : 0;
-    }
-    return hunk.oldStart + shift + 1;
-}
 /** A fence longer than any backtick run in the content, so quoted code cannot close it. */
 function fence(lines) {
     const longest = Math.max(0, ...lines.flatMap((l) => (l.match(/`+/g) ?? []).map((r) => r.length)));
@@ -299,6 +425,15 @@ function whereComment(ctx, c) {
         case "position":
             return { path: null, line: null, label: `commit ${anchor.commit + 1} position`, quote: [] };
         case "hunk": {
+            const pick = pickRows(ctx, anchor);
+            if (pick !== null) {
+                return {
+                    path: ctx.units.get(anchor.unit)?.path ?? c.context.path,
+                    line: pick.line,
+                    label: `${pick.range.includes("-") ? "lines" : "line"} ${pick.range}${pick.baseSide ? " (base side)" : ""}`,
+                    quote: pick.rows,
+                };
+            }
             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) {
@@ -514,10 +649,24 @@ function renderQuestions(ctx, questions, responses) {
     }
     return out;
 }
+/** Threads the agent opened, with what the reviewer said back. */
+function renderThreads(ctx, threads) {
+    const out = ["## Threads you started", ""];
+    for (const c of threads) {
+        const where = whereComment(ctx, c);
+        const place = where.path === null ? where.label : `${where.path} · ${where.label}`;
+        out.push(`### ${c.id} · ${place}`, "", ...quoteBlock(where.quote));
+        if (where.quote.length > 0)
+            out.push("");
+        out.push(`Agent: ${c.body}`, ...renderReplies(c), "");
+    }
+    return out;
+}
 /** Plan feedback for a split review: what the planner answers through `responses`. */
-function renderPlanFeedback(commits, comments) {
+function renderPlanFeedback(ctx, comments) {
+    const { commits } = ctx;
     const out = [];
-    const line = (c) => [`- ${c.id} on ${describeAnchor(c.anchor)}`];
+    const line = (c) => [`- ${c.id} on ${describeAnchor(c.anchor, ctx)}`];
     const planLevel = comments.filter((c) => c.anchor.kind === "plan");
     if (planLevel.length > 0) {
         out.push("## Whole plan", "");
@@ -535,6 +684,9 @@ function renderPlanFeedback(commits, comments) {
             out.push(...line(c));
             if (c.context.path)
                 out.push(`  - file: ${c.context.path}`);
+            const rows = anchorRows(ctx, c.anchor);
+            if (rows.length > 0)
+                out.push("  - picked rows are marked >:", ...rows.map((r) => `    ${r}`));
             out.push(`  - ${c.body.split("\n").join("\n    ")}`);
             for (const reply of renderReplies(c))
                 out.push(`  - ${reply}`);
@@ -549,6 +701,155 @@ function renderPlanFeedback(commits, comments) {
     }
     return out;
 }
+/** The rows `want` picks, numbered as the quoting code numbers them. */
+function numberedRows(hunk, units, want) {
+    let tip = tipStartOf(hunk, units);
+    let base = hunk.oldStart + 1;
+    const rows = [];
+    hunk.body.forEach((line, i) => {
+        if (want(i, line.op === " " ? null : line.change))
+            rows.push({ op: line.op, tip, base });
+        if (line.op !== "-")
+            tip += 1;
+        if (line.op !== "+")
+            base += 1;
+    });
+    return rows;
+}
+const NO_SPAN = { newLine: null, oldLine: null, startNewLine: null, startOldLine: null };
+/** The last row names the line: both sides for context, the tip for an addition, the base for a removal. */
+function spanOf(rows) {
+    const first = rows[0];
+    const last = rows.at(-1);
+    if (first === undefined || last === undefined)
+        return NO_SPAN;
+    const range = rows.length > 1;
+    return {
+        newLine: last.op === "-" ? null : last.tip,
+        oldLine: last.op === "+" ? null : last.base,
+        startNewLine: range && first.op !== "-" ? first.tip : null,
+        startOldLine: range && first.op !== "+" ? first.base : null,
+    };
+}
+function commentSpan(ctx, c) {
+    const { anchor } = c;
+    if (anchor.kind !== "hunk")
+        return NO_SPAN;
+    const hunk = ctx.units.get(anchor.unit);
+    if (hunk?.kind !== "hunk")
+        return NO_SPAN;
+    const { offsets, changes } = anchor;
+    if (offsets !== undefined)
+        return spanOf(numberedRows(hunk, ctx.units, (i) => offsets.includes(i)));
+    return spanOf(numberedRows(hunk, ctx.units, (_, n) => n !== null && (changes === null || changes.includes(n))));
+}
+function concernSpan(ctx, concern) {
+    const hunk = concern.unit === undefined ? undefined : ctx.units.get(concern.unit);
+    if (hunk?.kind !== "hunk")
+        return NO_SPAN;
+    const lines = concern.lines;
+    return spanOf(numberedRows(hunk, ctx.units, (_, n) => n !== null && (lines === undefined || lines.includes(n))));
+}
+function threadOf(c) {
+    return (c.replies ?? []).map((r) => ({ author: r.author, body: r.body }));
+}
+function withSeverity(severity, text) {
+    return severity === null ? text : `**${severity}**\n\n${text}`;
+}
+function collectItems(review, commits, units, responses) {
+    const ctx = { commits, units };
+    const fromReviewer = review.comments.filter((c) => c.author !== "agent");
+    const walk = review.mode === "walk";
+    const rest = fromReviewer.filter((c) => c.kind !== "question");
+    const issues = walk ? rest : rest.filter((c) => c.severity !== undefined);
+    const noComments = new Set(review.excluded?.comments ?? []);
+    const noConcerns = new Set(review.excluded?.concerns ?? []);
+    const resolved = new Set(review.resolved ?? []);
+    const out = buildItems(ctx, keptConcerns(review, commits), issues).map((it) => {
+        const { kept } = it;
+        const first = it.comments[0];
+        if (kept !== null) {
+            const note = kept.note === null ? "" : `\n\nReviewer: ${kept.note}`;
+            const thread = it.comments.flatMap((c) => [
+                { author: "reviewer", body: c.body },
+                ...threadOf(c),
+            ]);
+            return {
+                where: it.where,
+                item: {
+                    ...concernSpan(ctx, kept.concern),
+                    path: it.where.path,
+                    oldPath: it.where.path,
+                    severity: it.severity,
+                    kind: "concern",
+                    body: withSeverity(it.severity, `${kept.concern.text}${note}`),
+                    thread,
+                    resolved: false,
+                    excluded: noConcerns.has(kept.concern.id),
+                },
+            };
+        }
+        if (first === undefined)
+            throw new Error("an item with neither a concern nor a comment");
+        return {
+            where: it.where,
+            item: {
+                ...commentSpan(ctx, first),
+                path: it.where.path,
+                oldPath: it.where.path,
+                severity: it.severity,
+                kind: "flag",
+                body: withSeverity(it.severity, first.body),
+                thread: threadOf(first),
+                resolved: resolved.has(first.id),
+                excluded: noComments.has(first.id),
+            },
+        };
+    });
+    for (const q of fromReviewer.filter((c) => c.kind === "question")) {
+        const where = whereComment(ctx, q);
+        const answer = responses.find((r) => r.comment === q.id)?.note;
+        const lastAgent = (q.replies ?? []).findLast((r) => r.author === "agent")?.body;
+        const said = answer ?? lastAgent;
+        const details = said === undefined ? "" : `\n\n<details><summary>Answer</summary>\n\n${said}\n\n</details>`;
+        out.push({
+            where,
+            item: {
+                ...commentSpan(ctx, q),
+                path: where.path,
+                oldPath: where.path,
+                severity: q.severity ?? null,
+                kind: "question",
+                body: `${q.body}${details}`,
+                thread: threadOf(q),
+                resolved: resolved.has(q.id),
+                excluded: noComments.has(q.id),
+            },
+        });
+    }
+    return sortItems(out, units);
+}
+/**
+ * The items of a review for the merge request, in file order then line order, general items last.
+ * Excluded ones are present and marked; whoever posts them skips those.
+ */
+export function reportItems(review, commits, units, opts) {
+    return collectItems(review, commits, units, opts.responses).map((c) => c.item);
+}
+/** A short list of what the reviewer left out, so nothing vanishes without a trace. */
+function renderExcluded(collected) {
+    const left = collected.filter((c) => c.item.excluded);
+    if (left.length === 0)
+        return [];
+    const out = ["## Excluded", "", "The reviewer left these out of the hand-off:", ""];
+    for (const { item, where } of left) {
+        const place = where.path === null ? where.label : `${where.path} · ${where.label}`;
+        const first = item.body.split("\n").find((l) => l !== "" && !l.startsWith("**")) ?? "";
+        out.push(`- ${place} · ${item.kind}${item.severity === null ? "" : ` · ${item.severity}`}: ${first}`);
+    }
+    out.push("");
+    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
@@ -556,11 +857,29 @@ function renderPlanFeedback(commits, comments) {
  * 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) {
+export function renderReport(full, commits, units, opts) {
+    const excluded = full.excluded;
+    if (excluded === undefined)
+        return renderIncluded(full, commits, units, opts);
+    const noComments = new Set(excluded.comments);
+    const noConcerns = new Set(excluded.concerns);
+    const review = {
+        ...full,
+        comments: full.comments.filter((c) => !noComments.has(c.id)),
+        concerns: (full.concerns ?? []).filter((d) => !noConcerns.has(d.concern)),
+    };
+    const tail = renderExcluded(collectItems(full, commits, units, opts.responses));
+    const main = renderIncluded(review, commits, units, opts);
+    return tail.length === 0 ? main : `${main}${main.endsWith("\n") ? "" : "\n"}${tail.join("\n")}`;
+}
+function renderIncluded(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 fromReviewer = review.comments.filter((c) => c.author !== "agent");
+    // A thread the agent started matters to it only once the reviewer has answered.
+    const started = review.comments.filter((c) => c.author === "agent" && (c.replies ?? []).some((r) => r.author === "reviewer"));
+    const questions = fromReviewer.filter((c) => c.kind === "question");
+    const rest = fromReviewer.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);
@@ -573,36 +892,47 @@ export function renderReport(review, commits, units, opts) {
     }
     else {
         out.push(`# Review of plan v${review.planVersion}`, "");
-        if (feedback.length === 0 && items.length === 0 && questions.length === 0) {
+        if (feedback.length === 0 &&
+            items.length === 0 &&
+            questions.length === 0 &&
+            started.length === 0) {
             out.push("No comments.", "");
             return out.join("\n");
         }
-        out.push(...renderPlanFeedback(commits, feedback));
+        out.push(...renderPlanFeedback(ctx, 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 (started.length > 0)
+        out.push(...renderThreads(ctx, started));
     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`.", "");
     }
+    const onContext = review.comments.some((c) => pickRows(ctx, c.anchor)?.touchesContext);
+    if (onContext)
+        out.push(CONTEXT_RULE, "");
     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) {
+function renderEvent(event, ctx) {
     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)}`];
+            const lines = [`- ${verb} ${what} ${c.id} on ${describeAnchor(c.anchor, ctx)}`];
+            const rows = anchorRows(ctx, c.anchor);
+            if (rows.length > 0)
+                lines.push(...rows.map((r) => `  ${r}`));
             if (c.context.path)
                 lines.push(`  - file: ${c.context.path}`);
             if (c.severity)
@@ -625,6 +955,8 @@ function renderEvent(event) {
             return [`- question ${event.commentId} marked ${event.resolved ? "resolved" : "open again"}`];
         case "version":
             return [`- plan v${event.version} is now open`];
+        case "submitted":
+            return ["- the reviewer submitted the review"];
         case "ended":
             return [`- the reviewer ended the review; the report is next to ${event.review}`];
         default: {
@@ -634,9 +966,10 @@ function renderEvent(event) {
     }
 }
 /** A markdown digest of what happened on the review page, for `follow-me watch`. */
-export function renderEvents(events) {
+export function renderEvents(events, ctx = null) {
     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");
+    const body = events.flatMap((event) => renderEvent(event, ctx));
+    return [`# Review activity (${range})`, "", ...body, ""].join("\n");
 }