@expo/code-review-cli 0.7.0 → 0.9.0

package/build/core/render.js

@@ -1,5 +1,6 @@
+// @ref LLP 0005#comment-rendering — pure Markdown builder; the comment body is the durable state store
 import { createHash } from "node:crypto";
-import { fingerprintFinding, scopedFingerprint, SEVERITIES, SEVERITY_RANK } from "./schema.js";
+import { collectPins, FeedbackPinSchema, FeedbackRecordSchema, fingerprintFinding, scopedFingerprint, SEVERITIES, SEVERITY_RANK, } from "./schema.js";
 /**
  * Build the file → right-side-line-numbers index from changed files' patch text,
  * by walking each unified-diff hunk (`@@ -a,b +c,d @@`) and collecting the new-tree
@@ -62,9 +63,44 @@ export function groupBySeverity(findings) {
 export function commentMarker(tag) {
     return `<!-- ${tag} -->`;
 }
+// @ref LLP 0011#forged-state-markers [implements] — the first-match parsers make an earlier forged marker win, so untrusted prose never keeps a raw `<!--`
+/**
+ * Neutralize anything that could impersonate this reviewer's embedded state
+ * comment. `parseReviewState` and `parseEmbeddedFingerprints` match with a
+ * non-global RegExp, so they take the FIRST marker in the body while the genuine
+ * one is appended LAST: a forged `<!-- tag:state=… -->` rendered earlier — inside
+ * a model-written rationale, a path, a dismissal reason — would win over the real
+ * state and let PR content dictate the dismissal list. None of that prose ever
+ * legitimately needs an HTML comment, so every `<!--` in it is escaped.
+ */
+export function stripStateMarkers(text) {
+    return text.replace(/<!--/g, "&lt;!--");
+}
+/** GitHub logins are `[A-Za-z0-9-]`, 39 chars max — anything else is forged. */
+const LOGIN_RE = /^[A-Za-z0-9-]{1,39}$/;
+/** A reply link must be a github.com URL, so a record can't inject an arbitrary
+ * target into the body. */
+const REPLY_URL_RE = /^https:\/\/github\.com\/[\w.\-/#]+$/;
+// @ref LLP 0011#never-echo-reply-text [constrained-by] — only the login and the link are rendered, both validated; a login that isn't GitHub-shaped names no one
+/**
+ * `@login`, or `an author` when the login isn't GitHub-shaped. The reply's own
+ * text is never rendered, so this credit line is the whole of what a reply
+ * contributes to the body.
+ */
+function replyAuthor(record) {
+    return LOGIN_RE.test(record.by) ? `@${record.by}` : "an author";
+}
+/** Link `text` to the reply comment, or leave it plain when the URL doesn't
+ * validate. */
+function replyLink(text, record) {
+    return record.url && REPLY_URL_RE.test(record.url) ? `[${text}](${record.url})` : text;
+}
 function locationText(finding) {
-    return finding.line != null ? `${finding.file}:${finding.line}` : finding.file;
+    // A git path may legally hold anything, including a forged state marker.
+    const file = stripStateMarkers(finding.file);
+    return finding.line != null ? `${file}:${finding.line}` : file;
 }
+// @ref LLP 0005#comment-rendering [implements] — diff anchor only if the line is in the diff; else base-SHA blob (f9fecd5)
 /**
  * Render a finding's location as inline code, linked to the code it points at:
  *  - in the diff (file+line shown in a hunk) → the PR's "Files changed" tab at that
@@ -92,7 +128,7 @@ function location(finding, link) {
     }
     if (link.baseSha) {
         const lineAnchor = finding.line != null ? `#L${finding.line}` : "";
-        const url = `https://github.com/${link.repo}/blob/${link.baseSha}/${finding.file}${lineAnchor}`;
+        const url = `https://github.com/${link.repo}/blob/${link.baseSha}/${stripStateMarkers(finding.file)}${lineAnchor}`;
         return `[\`${text}\`](${url})`;
     }
     return `\`${text}\``;
@@ -102,29 +138,41 @@ function location(finding, link) {
  * per-PR dismissals. Findings whose fingerprint appears in `dismissed` render in a
  * collapsed "Dismissed" section instead of the main list.
  */
-export function renderMarkdown(review, tag, dismissed = [], link) {
+export function renderMarkdown(review, tag, dismissed = [], link, feedback = [], pins = []) {
     const dismissedByFp = new Map(dismissed.map((record) => [record.fp, record]));
     const withFp = review.findings.map((finding) => ({ finding, fp: fingerprintFinding(finding) }));
-    const kept = withFp.filter(({ fp }) => !dismissedByFp.has(fp));
-    const dropped = withFp.filter(({ fp }) => dismissedByFp.has(fp));
+    const feedbackByFp = matchedFeedback(feedback, new Set(withFp.map((entry) => entry.fp)));
+    // An applied reply cleared the finding, so it leaves the active list exactly
+    // like a dismissal — with its own audit line saying a reply is what did it.
+    const isDropped = ({ fp }) => dismissedByFp.has(fp) || feedbackByFp.get(fp)?.applied === true;
+    const notDismissed = withFp.filter((entry) => !isDropped(entry));
+    const dropped = withFp.filter((entry) => isDropped(entry));
+    // A requalified finding is addressed by a stacked PR: shown in its own collapsed
+    // section and counted, but never in the main (blocking) severity list.
+    const kept = notDismissed.filter(({ finding }) => !finding.requalifiedBy);
+    const requalified = notDismissed.filter(({ finding }) => finding.requalifiedBy);
     const lines = [commentMarker(tag), "## 🤖 AI code review", ""];
-    lines.push(`**Decision:** ${review.couldNotComplete ? "No review — every pass failed" : decisionLabel(review.decision)}`, "", review.summary, "");
+    lines.push(`**Decision:** ${review.couldNotComplete ? "No review — every pass failed" : decisionLabel(review.decision)}`, "", stripStateMarkers(review.summary), "");
     if (review.incomplete.length > 0) {
-        lines.push("> ⏱️ **Coverage note:** coverage is partial — some review passes did not", "> finish (timed out or failed), so issues may exist in areas not fully reviewed:", ...review.incomplete.map((note) => `> - ${note}`), "");
+        lines.push("> ⏱️ **Coverage note:** coverage is partial — some review passes did not", "> finish (timed out or failed), so issues may exist in areas not fully reviewed:", ...review.incomplete.map((note) => `> - ${stripStateMarkers(note)}`), "");
     }
+    lines.push(...setupNote(review.setupNotes));
+    lines.push(...requalificationAuditNote(requalified.map((entry) => entry.finding)));
+    lines.push(...feedbackAuditNote([...feedbackByFp.values()]));
     if (kept.length === 0) {
         lines.push("No findings.", "");
     }
     else {
-        lines.push(...renderSeveritySections(kept.map((entry) => entry.finding), link));
+        lines.push(...renderSeveritySections(kept.map((entry) => entry.finding), link, fingerprintFinding, feedbackByFp));
+    }
+    if (requalified.length > 0) {
+        lines.push("<details>", `<summary>🔁 Addressed in stacked PRs (${requalified.length})</summary>`, "", ...requalified.flatMap(({ finding, fp }) => addressedLines(finding, fp, link)), "</details>", "");
     }
     if (dropped.length > 0) {
         lines.push("<details>", `<summary>🚫 Dismissed on this PR (${dropped.length})</summary>`, "");
         for (const { finding, fp } of dropped) {
-            const record = dismissedByFp.get(fp);
-            const who = record.by ? ` by @${record.by}` : "";
-            const why = record.reason ? ` — ${record.reason}` : "";
-            lines.push(`- **${finding.title}** — ${location(finding, link)} \`id:${fp}\`${who}${why}`);
+            const suffix = droppedSuffix(dismissedByFp.get(fp), feedbackByFp.get(fp));
+            lines.push(`- **${stripStateMarkers(finding.title)}** — ${location(finding, link)} \`id:${fp}\`${suffix}`);
         }
         lines.push("", "_Re-add one with `/undismiss <id>`._", "</details>", "");
     }
@@ -133,7 +181,7 @@ export function renderMarkdown(review, tag, dismissed = [], link) {
     // and dismissals, so `/dismiss` can re-render this comment without re-running.
     const fingerprints = review.findings.map(fingerprintFinding);
     lines.push("", `<!-- ${tag}:fingerprints=${JSON.stringify(fingerprints)} -->`);
-    lines.push(`<!-- ${tag}:state=${encodeState({ review, dismissed })} -->`);
+    lines.push(`<!-- ${tag}:state=${encodeState(reviewState({ review, dismissed }, feedbackByFp, pins))} -->`);
     return lines.join("\n");
 }
 /**
@@ -141,7 +189,7 @@ export function renderMarkdown(review, tag, dismissed = [], link) {
  * aggregate renderers. `idFor` supplies each finding's id (default:
  * fingerprintFinding); the aggregate renderer passes a scope-namespaced id.
  */
-function renderSeveritySections(findings, link, idFor = fingerprintFinding) {
+function renderSeveritySections(findings, link, idFor = fingerprintFinding, feedbackById) {
     const out = [];
     const groups = groupBySeverity(sortFindings(findings));
     for (const severity of SEVERITIES) {
@@ -151,12 +199,14 @@ function renderSeveritySections(findings, link, idFor = fingerprintFinding) {
         }
         out.push(`### ${severityHeading(severity)} (${group.length})`, "");
         for (const finding of group) {
-            out.push(...renderFindingLines(finding, link, idFor(finding)));
+            const id = idFor(finding);
+            out.push(...renderFindingLines(finding, link, id, feedbackById?.get(id)));
         }
         out.push("");
     }
     return out;
 }
+// @ref LLP 0005#comment-rendering [constrained-by] — blank lines must stay truly empty or <details> escapes the list (euxy#45)
 /**
  * Indent every line of a multi-line value to a list item's content column.
  *
@@ -173,19 +223,116 @@ function renderSeveritySections(findings, link, idFor = fingerprintFinding) {
 function indentContinuation(value, indent = "  ") {
     return value.split("\n").map((line) => (line.trim() === "" ? "" : `${indent}${line}`));
 }
-function renderFindingLines(finding, link, id = fingerprintFinding(finding)) {
+function renderFindingLines(finding, link, id = fingerprintFinding(finding), reply) {
     const out = [
-        `- **${finding.title}** — ${location(finding, link)} _(${finding.category})_ · \`id:${id}\``,
-        ...indentContinuation(finding.rationale),
+        `- **${stripStateMarkers(finding.title)}** — ${location(finding, link)} _(${finding.category})_ · \`id:${id}\`${replyAnnotation(reply)}`,
+        ...indentContinuation(stripStateMarkers(finding.rationale)),
     ];
     if (finding.suggestion) {
-        out.push(...indentContinuation(`_Suggestion:_ ${finding.suggestion}`));
+        out.push(...indentContinuation(`_Suggestion:_ ${stripStateMarkers(finding.suggestion)}`));
     }
     // Separator so a rationale ending in `</details>` cannot swallow the next
     // bullet. Findings are already loose list items, so this changes no spacing.
     out.push("");
     return out;
 }
+// @ref LLP 0012#run-points-command-and-review [implements] — setup advice renders outside the findings list, so it never blocks
+/** Advice about the reviewer's own setup (stale refs, cited code this PR moves). */
+function setupNote(notes = []) {
+    if (notes.length === 0) {
+        return [];
+    }
+    return ["> 🔗 **Review setup:**", ...notes.map((note) => `> - ${stripStateMarkers(note)}`), ""];
+}
+// @ref LLP 0010#rendering-in-all-three-paths [implements] — the visible audit count is mandatory: requalification's only effect on a real finding is moving it out of the blocking set, so it must never be silent
+/**
+ * The visible one-line audit note in the OPEN body, naming the addressing PRs. This
+ * is what keeps requalification from being a "collapsed fold nobody reads": the
+ * count and PR numbers show above the fold. Empty when nothing was requalified.
+ */
+function requalificationAuditNote(requalified) {
+    if (requalified.length === 0) {
+        return [];
+    }
+    const prNumbers = [
+        ...new Set(requalified
+            .map((finding) => finding.requalifiedBy?.prNumber)
+            .filter((n) => n != null)),
+    ].sort((a, b) => a - b);
+    const prList = prNumbers.map((n) => `#${n}`).join(", ");
+    return [
+        `> 🔁 **${requalified.length} finding(s)** marked addressed by stacked PR(s) (${prList}); ` +
+            "excluded from the decision but shown below.",
+        "",
+    ];
+}
+/** One bullet per finding in the "Addressed in stacked PRs" section — names the
+ * addressing PR and the exact upstack path relied on. */
+function addressedLines(finding, fp, link) {
+    const requalified = finding.requalifiedBy;
+    const reason = requalified.reason ? `: ${stripStateMarkers(requalified.reason)}` : "";
+    return [
+        `- **${stripStateMarkers(finding.title)}** — ${location(finding, link)} \`id:${fp}\` — addressed in ` +
+            `#${requalified.prNumber} (\`${stripStateMarkers(requalified.file)}\`)${reason}`,
+    ];
+}
+/**
+ * Index the feedback records that answer a finding actually present in this
+ * comment, keyed by the id the comment renders. A record whose finding is gone
+ * (the flagged code changed, so the fingerprint moved) is dropped: it can no
+ * longer be shown, counted, or audited, so carrying it forward only grows state.
+ */
+function matchedFeedback(feedback, ids) {
+    const matched = new Map();
+    for (const record of feedback) {
+        if (ids.has(record.fp) && !matched.has(record.fp)) {
+            matched.set(record.fp, record);
+        }
+    }
+    return matched;
+}
+// @ref LLP 0011#suppression-is-never-silent [implements] — the count sits above the fold, exactly like the requalification note, so a reply clearing a finding is never a quiet fold nobody opens
+/** The visible one-line audit note for author responses. Empty when no reply
+ * matched a finding in this comment. */
+function feedbackAuditNote(records) {
+    if (records.length === 0) {
+        return [];
+    }
+    const applied = records.filter((record) => record.applied).length;
+    return [
+        `> 💬 **${records.length} finding(s)** have an author response (${applied} applied).`,
+        "",
+    ];
+}
+/** ` · 💬 [@login replied](url)` on an active finding — the entire visible trace
+ * of a reply. The reply's own text is never part of it. */
+function replyAnnotation(record) {
+    return record ? ` · 💬 ${replyLink(`${replyAuthor(record)} replied`, record)}` : "";
+}
+/** The audit tail of a "Dismissed" bullet: an explicit `/dismiss`, or the reply
+ * that cleared the finding. */
+function droppedSuffix(dismissal, reply) {
+    if (dismissal) {
+        const who = dismissal.by ? ` by @${stripStateMarkers(dismissal.by)}` : "";
+        const why = dismissal.reason ? ` — ${stripStateMarkers(dismissal.reason)}` : "";
+        return `${who}${why}`;
+    }
+    return reply ? ` — dismissed via reply by ${replyLink(replyAuthor(reply), reply)}` : "";
+}
+// @ref LLP 0011#the-pin-belongs-to-the-finding [implements] — the pin set rides the state on EVERY render, independent of which replies matched this run, so a reply that disappears can never drop a maintainer's restore
+/** Attach the matched feedback to the state blob. It rides the embedded state
+ * like dismissals do, so the next run re-reads what was recorded (including a
+ * verdict already decided) instead of re-deriving it.
+ *
+ * `pins` is written whole and unfiltered — NOT indexed by the findings or the records
+ * this render happens to show. A pin is a maintainer's decision about a finding, so it
+ * must outlive a run where the reply was edited away, the record was dropped, or the
+ * finding itself was not re-emitted. */
+function reviewState(state, feedbackByFp, pins = []) {
+    const feedback = [...feedbackByFp.values()];
+    const withFeedback = feedback.length > 0 ? { ...state, feedback } : state;
+    return pins.length > 0 ? { ...withFeedback, pins } : withFeedback;
+}
 /** Parse the fingerprints embedded in a previously-posted comment body. */
 export function parseEmbeddedFingerprints(body, tag) {
     // Escape the (config-controlled) tag so regex metacharacters can't break the match.
@@ -213,6 +360,7 @@ export function worstDecision(decisions) {
 }
 /** GitHub's comment body limit is ~65k chars; keep a margin. */
 const MAX_COMMENT_CHARS = 60_000;
+// @ref LLP 0005#truncation-and-aggregate-state [constrained-by] — truncation trims shown findings only; dismissed findings always kept in state
 /**
  * One aggregated comment under the single existing marker: a scope summary table,
  * an optional coverage block, one <details> per scope (findings rendered with
@@ -221,19 +369,33 @@ const MAX_COMMENT_CHARS = 60_000;
  * carries the real per-scope data. Oversized bodies trim each scope's findings to
  * the most severe N (halving until it fits, floor 3) with a per-scope note.
  */
-export function renderAggregateMarkdown(results, tag, dismissed, link, opts) {
+export function renderAggregateMarkdown(results, tag, dismissed, link, opts, feedback = [], pins = []) {
     const dismissedByFp = new Map(dismissed.map((record) => [record.fp, record]));
     const idOf = (result, finding) => scopedFingerprint(result.isDefault ? null : result.scope, finding);
-    // Split each scope's findings into kept/dropped once (dismissal is limit-independent).
+    // Feedback is keyed by the SAME scope-namespaced id the comment renders, so a
+    // record can never cross scopes.
+    const feedbackById = matchedFeedback(feedback, new Set(results.flatMap((result) => result.review.findings.map((f) => idOf(result, f)))));
+    // Split each scope's findings into kept/requalified/dropped once (dismissal and
+    // requalification are both limit-independent). `kept` is the active/blocking set;
+    // requalified findings are addressed by a stacked PR — counted and shown, never
+    // in the blocking list.
     const perScope = results.map((result) => {
         const withId = result.review.findings.map((finding) => ({
             finding,
             id: idOf(result, finding),
         }));
+        // An applied reply drops a finding out of the active list, like a dismissal.
+        const isDropped = (entry) => dismissedByFp.has(entry.id) || feedbackById.get(entry.id)?.applied === true;
+        const notDismissed = withId.filter((entry) => !isDropped(entry));
         return {
             result,
-            kept: withId.filter((entry) => !dismissedByFp.has(entry.id)),
-            dropped: withId.filter((entry) => dismissedByFp.has(entry.id)),
+            kept: notDismissed.filter((entry) => !entry.finding.requalifiedBy),
+            requalified: notDismissed.filter((entry) => entry.finding.requalifiedBy),
+            dropped: withId.filter((entry) => isDropped(entry)),
+            // The scope's own author responses, for its audit note.
+            feedback: withId
+                .map((entry) => feedbackById.get(entry.id))
+                .filter((record) => record != null),
         };
     });
     const worst = worstDecision(results.map((result) => result.review.decision));
@@ -249,7 +411,7 @@ export function renderAggregateMarkdown(results, tag, dismissed, link, opts) {
             "| --- | --- | --- |",
         ];
         for (const { result, kept } of perScope) {
-            lines.push(`| ${result.scope} | ${result.review.couldNotComplete ? "No review — every pass failed" : decisionLabel(result.review.decision)} | ${kept.length} |`);
+            lines.push(`| ${stripStateMarkers(result.scope)} | ${result.review.couldNotComplete ? "No review — every pass failed" : decisionLabel(result.review.decision)} | ${kept.length} |`);
         }
         lines.push("");
         const anyIncomplete = results.some((result) => result.review.incomplete.length > 0);
@@ -258,54 +420,77 @@ export function renderAggregateMarkdown(results, tag, dismissed, link, opts) {
             if (unmatched.length > 0) {
                 const shown = unmatched
                     .slice(0, 10)
-                    .map((file) => `\`${file}\``)
+                    .map((file) => `\`${stripStateMarkers(file)}\``)
                     .join(", ");
                 const more = unmatched.length > 10 ? `, …(+${unmatched.length - 10} more)` : "";
                 lines.push(`> - ${unmatched.length} changed file(s) matched no scope: ${shown}${more}`);
             }
             for (const result of results) {
                 for (const note of result.review.incomplete) {
-                    lines.push(`> - [${result.scope}] ${note}`);
+                    lines.push(`> - [${stripStateMarkers(result.scope)}] ${stripStateMarkers(note)}`);
                 }
             }
             lines.push("");
         }
+        const setupLines = results.flatMap((result) => (result.review.setupNotes ?? []).map((note) => `> - [${stripStateMarkers(result.scope)}] ${stripStateMarkers(note)}`));
+        if (setupLines.length > 0) {
+            lines.push("> 🔗 **Review setup:**", ...setupLines, "");
+        }
         // Shown = the most-severe N kept findings per scope (N = limitPerScope). The
         // embedded state trims KEPT findings to the same set so a truncated comment
         // still fits GitHub's body limit (the hidden findings are noted, not silently
         // carried) — but dismissed findings are always kept in state (see below).
-        const rendered = perScope.map(({ result, kept, dropped }) => ({
+        const rendered = perScope.map(({ result, kept, requalified, dropped, feedback: replies }) => ({
             result,
+            replies,
             shown: sortFindings(kept.map((entry) => entry.finding)).slice(0, limitPerScope),
             hidden: Math.max(0, kept.length - limitPerScope),
+            // The requalified section is trimmed by the same per-scope limit as shown: it
+            // is coordinator-populated (a wide stack can requalify many findings at once),
+            // and an untrimmed section would keep the truncation loop below from ever
+            // converging under MAX_COMMENT_CHARS. The audit note carries the TOTAL count,
+            // so trimming never hides that requalification happened.
+            requalified: requalified.slice(0, limitPerScope),
+            requalifiedHidden: Math.max(0, requalified.length - limitPerScope),
+            requalifiedAll: requalified,
             dropped,
         }));
-        for (const { result, shown, hidden } of rendered) {
-            const open = shown.length > 0 ? " open" : "";
+        for (const { result, replies, shown, hidden, requalified, requalifiedAll, requalifiedHidden, } of rendered) {
+            // @ref LLP 0011#suppression-is-never-silent — a reply-suppressed scope opens
+            // its fold so the audit note is visible, matching renderMarkdown and LLP 0010's
+            // visible-suppression rule (else a scope replies cleared reads as clean).
+            const open = shown.length > 0 || requalifiedAll.length > 0 || replies.length > 0 ? " open" : "";
             const keptCount = shown.length + hidden;
-            lines.push(`<details${open}>`, `<summary>${result.scope} — ${decisionLabel(result.review.decision)} (${keptCount})</summary>`, "");
+            lines.push(`<details${open}>`, `<summary>${stripStateMarkers(result.scope)} — ${decisionLabel(result.review.decision)} (${keptCount})</summary>`, "");
             if (result.review.summary) {
-                lines.push(result.review.summary, "");
+                lines.push(stripStateMarkers(result.review.summary), "");
             }
+            lines.push(...requalificationAuditNote(requalifiedAll.map((entry) => entry.finding)));
+            lines.push(...feedbackAuditNote(replies));
             if (shown.length === 0) {
                 lines.push("No findings.", "");
             }
             else {
-                lines.push(...renderSeveritySections(shown, link, (finding) => idOf(result, finding)));
+                lines.push(...renderSeveritySections(shown, link, (finding) => idOf(result, finding), feedbackById));
             }
             if (hidden > 0) {
                 lines.push(`_…and ${hidden} more finding(s) — see the workflow log._`, "");
             }
+            if (requalifiedAll.length > 0) {
+                lines.push(`**🔁 Addressed in stacked PRs (${requalifiedAll.length})**`, "", ...requalified.flatMap((entry) => addressedLines(entry.finding, entry.id, link)));
+                if (requalifiedHidden > 0) {
+                    lines.push(`_…and ${requalifiedHidden} more addressed finding(s) — see the workflow log._`);
+                }
+                lines.push("");
+            }
             lines.push("</details>", "");
         }
         const allDropped = perScope.flatMap(({ result, dropped }) => dropped.map((entry) => ({ ...entry, scope: result.scope })));
         if (allDropped.length > 0) {
             lines.push("<details>", `<summary>🚫 Dismissed on this PR (${allDropped.length})</summary>`, "");
             for (const { finding, id, scope } of allDropped) {
-                const record = dismissedByFp.get(id);
-                const who = record.by ? ` by @${record.by}` : "";
-                const why = record.reason ? ` — ${record.reason}` : "";
-                lines.push(`- **${finding.title}** — ${location(finding, link)} \`id:${id}\` _(${scope})_${who}${why}`);
+                const suffix = droppedSuffix(dismissedByFp.get(id), feedbackById.get(id));
+                lines.push(`- **${stripStateMarkers(finding.title)}** — ${location(finding, link)} \`id:${id}\` _(${stripStateMarkers(scope)})_${suffix}`);
             }
             lines.push("", "_Re-add one with `/undismiss <id>`._", "</details>", "");
         }
@@ -316,11 +501,30 @@ export function renderAggregateMarkdown(results, tag, dismissed, link, opts) {
         // review) so /undismiss can restore them and the Dismissed section persists
         // across re-renders. The per-scope data (`scopes`) plus a merged v1 `review`
         // keep both v2 and v1 consumers working.
-        const stateScopes = rendered.map(({ result, shown, dropped }) => ({
-            scope: result.scope,
-            isDefault: result.isDefault,
-            review: { ...result.review, findings: [...shown, ...dropped.map((entry) => entry.finding)] },
-        }));
+        const stateScopes = rendered.map(({ result, shown, requalified, dropped }) => {
+            // @ref LLP 0011#suppression-is-never-silent — strip any per-scope `feedback`
+            // a freshly-reviewed scope's ReviewRunResult carries: the top-level feedback
+            // array (reviewState below) is the single source of truth. A stale per-scope
+            // copy that survived here would be read back on a later carried-over run and
+            // could re-apply a record a human /undismiss already overrode at the top level.
+            const { feedback: _feedback, ...review } = result.review;
+            return {
+                scope: result.scope,
+                isDefault: result.isDefault,
+                // Requalified findings ride the embedded state (like dismissed ones) so a
+                // re-render (/dismiss) round-trips them and the addressed section persists.
+                // Under truncation they are trimmed exactly like `shown` — state bytes count
+                // toward the comment size, so an untrimmed list would defeat the cap loop.
+                review: {
+                    ...review,
+                    findings: [
+                        ...shown,
+                        ...requalified.map((entry) => entry.finding),
+                        ...dropped.map((entry) => entry.finding),
+                    ],
+                },
+            };
+        });
         const merged = {
             decision: worst,
             findings: stateScopes.flatMap((scope) => scope.review.findings),
@@ -331,12 +535,17 @@ export function renderAggregateMarkdown(results, tag, dismissed, link, opts) {
         };
         const fingerprints = stateScopes.flatMap((scope) => scope.review.findings.map((finding) => scopedFingerprint(scope.isDefault ? null : scope.scope, finding)));
         lines.push("", `<!-- ${tag}:fingerprints=${JSON.stringify(fingerprints)} -->`);
-        lines.push(`<!-- ${tag}:state=${encodeState({ review: merged, dismissed, scopes: stateScopes })} -->`);
+        // Feedback records and `/undismiss` pins ride the state whole, never trimmed by the
+        // cap loop: each is a handful of bytes, and losing one would lose a verdict already
+        // decided — or a maintainer's restore, which no later run could recover.
+        lines.push(`<!-- ${tag}:state=${encodeState(reviewState({ review: merged, dismissed, scopes: stateScopes }, feedbackById, pins))} -->`);
         return lines.join("\n");
     };
     let limit = Number.POSITIVE_INFINITY;
     let body = buildBody(limit);
-    const largestScope = Math.max(0, ...perScope.map((entry) => entry.kept.length));
+    // Seed from the largest per-scope section the limit applies to — kept OR
+    // requalified — so the halving loop shrinks whichever one is oversized.
+    const largestScope = Math.max(0, ...perScope.map((entry) => Math.max(entry.kept.length, entry.requalified.length)));
     while (body.length > MAX_COMMENT_CHARS && limit > 3) {
         limit =
             limit === Number.POSITIVE_INFINITY
@@ -359,7 +568,21 @@ export function parseReviewState(body, tag) {
     try {
         const parsed = JSON.parse(Buffer.from(match[1], "base64").toString("utf8"));
         if (parsed && Array.isArray(parsed.review?.findings) && Array.isArray(parsed.dismissed)) {
-            return parsed;
+            // The v3 `feedback` field is shape-validated rather than trusted: it feeds
+            // the blocking decision, so a malformed blob must yield no records, not
+            // junk ones. Same for the v4 `pins`.
+            const feedback = FeedbackRecordSchema.array().safeParse(parsed.feedback ?? []);
+            const records = feedback.success ? feedback.data : [];
+            const parsedPins = FeedbackPinSchema.array().safeParse(parsed.pins ?? []);
+            // Migration on read: a v3 comment stored its pins on the records themselves, so
+            // collectPins lifts those into the set. Without this, the first render by this
+            // version would write a state with no pins at all and silently release every
+            // `/undismiss` a maintainer had already made.
+            return {
+                ...parsed,
+                feedback: records,
+                pins: collectPins(parsedPins.success ? parsedPins.data : [], records),
+            };
         }
     }
     catch {

package/build/core/responses.js

@@ -0,0 +1,158 @@
+/** Blockquote lines read per comment. A reply that quotes half the review is
+ * either noise or an attempt to match everything at once. */
+const MAX_QUOTED_LINES = 50;
+/**
+ * Minimum normalized length of a quoted line before it may match a title. A bare
+ * `> ok` or `> +1` must never collide with a short finding title.
+ */
+const MIN_QUOTE_LEN = 8;
+/** `id:<hex>` as it renders in the comment, in the fingerprint alphabet
+ * (`dismiss.ts` sanitizes user input to the same one). */
+const FINDING_ID_RE = /\bid:([a-f0-9]{6,64})\b/gi;
+/**
+ * Our own comment always ends with the embedded `:state=` / `:fingerprints=`
+ * markers. The caller passes only non-bot comments, but matching our own body
+ * would let the review answer itself, so this is the tag-independent backstop.
+ */
+const OWN_COMMENT_RE = /<!--[^\n]*:(?:state|fingerprints)=/;
+/**
+ * Markdown → comparable text: link text without the target, no backticks or
+ * emphasis marks, collapsed whitespace, lowercase, no trailing punctuation. A
+ * reply quoting a rendered finding title is byte-identical to it, so this only
+ * has to absorb the copy-paste noise around that.
+ */
+export function normalizeTitle(text) {
+    return text
+        .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
+        .replace(/[`*_~]/g, "")
+        .replace(/\s+/g, " ")
+        .trim()
+        .toLowerCase()
+        .replace(/[.,;:!?]+$/, "")
+        .trim();
+}
+/**
+ * The blockquote lines (`> …`) of a comment body, in order and bounded. Fenced
+ * code blocks are skipped: a `>` inside a fence is quoted CODE, not the author
+ * quoting the review, and treating it as a quote would let a pasted snippet
+ * match a finding nobody replied to.
+ */
+export function extractQuotedLines(body) {
+    const out = [];
+    let inFence = false;
+    for (const raw of body.split("\n")) {
+        if (/^\s*(?:```|~~~)/.test(raw)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence || !/^\s*>/.test(raw)) {
+            continue;
+        }
+        // Strip the marker plus any nesting (`>> quoted reply`).
+        const text = raw.replace(/^\s*>[\s>]*/, "").trim();
+        if (text === "") {
+            continue;
+        }
+        out.push(text);
+        if (out.length >= MAX_QUOTED_LINES) {
+            break;
+        }
+    }
+    return out;
+}
+/** The `id:<hex>` tokens a comment cites, lowercased and deduped. */
+export function extractFindingIds(body) {
+    const ids = [...body.matchAll(FINDING_ID_RE)].map((match) => match[1].toLowerCase());
+    return [...new Set(ids)];
+}
+// @ref LLP 0011#a-quote-annotates-an-id-clears [implements] — only an id the replier wrote OUTSIDE any blockquote counts as citing the finding
+/**
+ * The `id:<hex>` tokens the commenter wrote THEMSELVES — an id inside a blockquote
+ * line does not count. GitHub's "Quote reply" copies the target comment verbatim with
+ * every line prefixed `> `, and the untrusted PR author controls that text, so a quoted
+ * title OR a quoted id may be text they planted. Only an unquoted id is a citation by
+ * the replier, which is what `feedbackApplied` requires before a reply may CLEAR a
+ * finding.
+ */
+export function extractCitedFindingIds(body) {
+    const own = body
+        .split("\n")
+        .filter((line) => !/^\s*>/.test(line))
+        .join("\n");
+    return extractFindingIds(own);
+}
+// @ref LLP 0011#deterministic-matching [implements] — an ambiguous quote records nothing; only an id disambiguates
+/**
+ * Match author replies to the findings they answer. Deterministic by design: a
+ * quoted line is compared to the rendered title, an `id:` token is compared to
+ * the known fingerprints, and nothing else counts — no model decides which
+ * finding a reply is about.
+ *
+ * An id in the known set wins outright and is the only way a quote shared by
+ * several findings resolves; a quoted line matching 2+ findings otherwise
+ * records NOTHING, because attributing pushback to the wrong finding is worse
+ * than recording no pushback at all. One record per finding: when several
+ * comments answer the same one, the newest (highest comment id) wins.
+ *
+ * `citedId` records HOW the reply names the finding: true only when the replier cited
+ * the finding's id in their own words. It is independent of `opts.match` — that knob
+ * selects how a reply MATCHES, while `citedId` is what `feedbackApplied` requires
+ * before a reply may CLEAR (see LLP 0011).
+ */
+export function matchReplies(comments, findings, opts) {
+    const known = new Set(findings.map((entry) => entry.fp));
+    const byTitle = new Map();
+    for (const { finding, fp } of findings) {
+        const key = normalizeTitle(finding.title);
+        byTitle.set(key, [...(byTitle.get(key) ?? []), fp]);
+    }
+    const newest = new Map();
+    for (const comment of comments) {
+        if (OWN_COMMENT_RE.test(comment.body)) {
+            continue;
+        }
+        const matched = new Set();
+        // The ids this replier cited in their own words, computed whatever `match` says: a
+        // quote-matched reply still records WHETHER it cites the finding, because that is
+        // what decides clearing.
+        const cited = new Set(extractCitedFindingIds(comment.body));
+        if (opts.match !== "quote") {
+            for (const id of extractFindingIds(comment.body)) {
+                if (known.has(id)) {
+                    matched.add(id);
+                }
+            }
+        }
+        if (opts.match !== "id") {
+            for (const quoted of extractQuotedLines(comment.body)) {
+                const key = normalizeTitle(quoted);
+                if (key.length < MIN_QUOTE_LEN) {
+                    continue;
+                }
+                const candidates = byTitle.get(key);
+                // Ambiguous (2+ findings share this title): the only resolution is an id
+                // in the same comment, which the pass above already recorded.
+                if (candidates?.length === 1) {
+                    matched.add(candidates[0]);
+                }
+            }
+        }
+        for (const fp of matched) {
+            const previous = newest.get(fp);
+            if (previous && previous.commentId >= comment.id) {
+                continue;
+            }
+            newest.set(fp, {
+                fp,
+                by: comment.login,
+                commentId: comment.id,
+                ...(comment.url ? { url: comment.url } : {}),
+                maintainer: comment.maintainer,
+                author: comment.author,
+                citedId: cited.has(fp),
+                applied: false,
+            });
+        }
+    }
+    return [...newest.values()].sort((a, b) => a.fp.localeCompare(b.fp));
+}