@webpieces/pr-gate 0.4.593 → 0.4.594

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/pr-gate",
-  "version": "0.4.593",
+  "version": "0.4.594",
   "description": "Gated PR system: 3-point squash-merge, merge validation gate, and red/yellow/green PR dashboard. Standalone scripts, no Nx dependency required.",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -15,7 +15,7 @@
     "directory": "packages/tooling/pr-gate"
   },
   "dependencies": {
-    "@webpieces/rules-config": "0.4.593",
+    "@webpieces/rules-config": "0.4.594",
     "@inversifyjs/binding-decorators": "1.1.5",
     "inversify": "7.10.4",
     "reflect-metadata": "0.2.2"

package/src/dashboard/checklist-comment-renderer.d.ts

@@ -0,0 +1,78 @@
+import { ChecklistCommentRow } from './checklist-comment-row';
+/**
+ * Hidden marker on the checklist review COMMENT — the "2nd comment" the PR description points at — so
+ * wp-finish can find and PATCH its own comment on every push instead of appending a new one. Versioned so
+ * the format can evolve without matching an old shape. v2 = the full roster (every DEFINED checklist,
+ * matched or not) + tri-state verdicts.
+ */
+export declare const CHECKLIST_COMMENT_MARKER = "<!-- webpieces-checklists v2 -->";
+/**
+ * Renders the 2nd PR comment: the reviewer checklist — full roster plus each reviewer's verbatim output.
+ *
+ * Split out of `Dashboard` when the PR-description/commit-body swap pushed that file over the 700-line
+ * cap, and the seam was already there to be found: this is ONE of the three surfaces the gated flow
+ * writes, it shares no rendering helper with the other two (it speaks `ChecklistCommentRow`, where the
+ * dashboard speaks `ChecklistRow`), and it owns the only size-fitting logic in the package. One class per
+ * surface is the shape the rest of this change assumes — see `Dashboard.renderPrBody` and
+ * `Dashboard.renderDetailComment`.
+ *
+ * `@injectable(bindingScopeValues.Singleton)` so it is drawn in the DI design and injected by type.
+ */
+export declare class ChecklistCommentRenderer {
+    /**
+     * The ONE combined PR comment. Two halves, in this order:
+     *
+     *   1. A roll-up plus the FULL ROSTER — every DEFINED checklist as a checkbox, each with a sub-bullet
+     *      stating exactly which globs fired against which files, or which did not and out of how many.
+     *      Skipped checklists are listed on purpose: skipping is the normal, healthy outcome, and a comment
+     *      that names only the reviewers that fired cannot distinguish "evaluated and irrelevant" from
+     *      "never wired up" — nor answer "why did the DB reviewer run on my frontend PR?".
+     *   2. One section per reviewer that RAN, carrying its full `output` — the depth a verdict line throws
+     *      away. Overridden first, then warned, then passed: a reader should meet the exceptions first.
+     *
+     * Idempotent: keyed by the hidden marker so wp-finish PATCHes this same comment on every push.
+     */
+    render(rows: readonly ChecklistCommentRow[], provenanceVerified: boolean, baseResolved: boolean): string;
+    /**
+     * The closing note when no reviewer produced a verdict. The original wording — "every configured
+     * checklist was evaluated and none of them applied" — is an all-clear, and it becomes FALSE the moment a
+     * checklist did apply and was declined. That sentence under a PR nobody reviewed is precisely the
+     * misreport this feature could otherwise introduce, so the declined case gets its own words.
+     */
+    private nothingRanNote;
+    private rollupHeader;
+    private rollupCounts;
+    private rosterBullet;
+    /**
+     * Did a reviewer actually produce a verdict for this row?
+     *
+     * `row.ran` is really "this checklist APPLIED to the diff" — for a required checklist the two are the
+     * same thing, because the PR cannot open otherwise, and the field was named before optional checklists
+     * existed. For a DECLINED optional one they diverge, and using `ran` alone would put a checked box and a
+     * reviewer section on a review that nobody performed.
+     */
+    private reviewerRan;
+    private declined;
+    private optionalTag;
+    /**
+     * Whether the reviewer demonstrably opened the diff, read from its own transcript. A QUALITY signal and
+     * never a blocker (see SubagentProvenanceService.evidenceFor) — but published, because "wrote a verdict
+     * without reading the change" is exactly what a reader of this comment would want to weigh.
+     */
+    private evidenceSuffix;
+    private verdictEmoji;
+    private verdictWords;
+    /**
+     * WHY this checklist ran or did not — the line that answers "why was this reviewer involved?". Branches
+     * on `configuredPatterns`, NEVER on `firedPatterns.length`: a patternless checklist and a skipped one
+     * both fired zero globs and they mean opposite things, so keying off the fired list would tell every
+     * skipped checklist's reader that the whole diff had been in its scope.
+     */
+    private whyLine;
+    private asCode;
+    private ranOrdered;
+    private rankOf;
+    private commentSection;
+    private fitComment;
+    private longestBodyIndex;
+}

package/src/dashboard/checklist-comment-renderer.js

@@ -0,0 +1,272 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChecklistCommentRenderer = exports.CHECKLIST_COMMENT_MARKER = void 0;
+const tslib_1 = require("tslib");
+const rules_config_1 = require("@webpieces/rules-config");
+const inversify_1 = require("inversify");
+/**
+ * Hidden marker on the checklist review COMMENT — the "2nd comment" the PR description points at — so
+ * wp-finish can find and PATCH its own comment on every push instead of appending a new one. Versioned so
+ * the format can evolve without matching an old shape. v2 = the full roster (every DEFINED checklist,
+ * matched or not) + tri-state verdicts.
+ */
+exports.CHECKLIST_COMMENT_MARKER = '<!-- webpieces-checklists v2 -->';
+const COMMENT_LIMIT = 65000; // under GitHub's 65536-char cap, with headroom for the marker + roll-up.
+// One checklist section for the combined comment (heading + verbatim reviewer output), so oversize
+// truncation can shrink the longest BODY without ever dropping a verdict heading.
+class CommentSection {
+    heading;
+    body;
+    constructor(heading, body) {
+        this.heading = heading;
+        this.body = body;
+    }
+}
+/**
+ * Renders the 2nd PR comment: the reviewer checklist — full roster plus each reviewer's verbatim output.
+ *
+ * Split out of `Dashboard` when the PR-description/commit-body swap pushed that file over the 700-line
+ * cap, and the seam was already there to be found: this is ONE of the three surfaces the gated flow
+ * writes, it shares no rendering helper with the other two (it speaks `ChecklistCommentRow`, where the
+ * dashboard speaks `ChecklistRow`), and it owns the only size-fitting logic in the package. One class per
+ * surface is the shape the rest of this change assumes — see `Dashboard.renderPrBody` and
+ * `Dashboard.renderDetailComment`.
+ *
+ * `@injectable(bindingScopeValues.Singleton)` so it is drawn in the DI design and injected by type.
+ */
+let ChecklistCommentRenderer = class ChecklistCommentRenderer {
+    /**
+     * The ONE combined PR comment. Two halves, in this order:
+     *
+     *   1. A roll-up plus the FULL ROSTER — every DEFINED checklist as a checkbox, each with a sub-bullet
+     *      stating exactly which globs fired against which files, or which did not and out of how many.
+     *      Skipped checklists are listed on purpose: skipping is the normal, healthy outcome, and a comment
+     *      that names only the reviewers that fired cannot distinguish "evaluated and irrelevant" from
+     *      "never wired up" — nor answer "why did the DB reviewer run on my frontend PR?".
+     *   2. One section per reviewer that RAN, carrying its full `output` — the depth a verdict line throws
+     *      away. Overridden first, then warned, then passed: a reader should meet the exceptions first.
+     *
+     * Idempotent: keyed by the hidden marker so wp-finish PATCHes this same comment on every push.
+     */
+    render(rows, provenanceVerified, baseResolved) {
+        const ran = this.ranOrdered(rows);
+        const prov = provenanceVerified
+            ? '_Each reviewer ran as its own independent subagent, verified from the Claude Code harness._'
+            : '_⚠️ Reviewer provenance was NOT verified (no Claude Code session) — treat these as unverified._';
+        // The roster lives in the HEADER, never in a section: fitComment only ever shrinks section bodies,
+        // so a roster line can never be the thing an oversize comment silently drops.
+        const lines = [exports.CHECKLIST_COMMENT_MARKER, this.rollupHeader(rows, baseResolved)];
+        // No reviewer ran ⇒ no provenance claim to make. Printing one either way would attest to nothing.
+        if (ran.length > 0)
+            lines.push(prov);
+        lines.push('', `### Checklists (all ${rows.length})`);
+        for (const row of rows)
+            lines.push(this.rosterBullet(row));
+        const header = lines.join('\n');
+        if (ran.length === 0) {
+            return `${header}\n\n${this.nothingRanNote(rows)}`;
+        }
+        return this.fitComment(`${header}\n\n### Reviews that ran`, ran.map((r) => this.commentSection(r)));
+    }
+    /**
+     * The closing note when no reviewer produced a verdict. The original wording — "every configured
+     * checklist was evaluated and none of them applied" — is an all-clear, and it becomes FALSE the moment a
+     * checklist did apply and was declined. That sentence under a PR nobody reviewed is precisely the
+     * misreport this feature could otherwise introduce, so the declined case gets its own words.
+     */
+    nothingRanNote(rows) {
+        const declined = rows.filter((r) => this.declined(r));
+        if (declined.length === 0) {
+            return '_No reviewer had to run on this diff — every configured checklist was evaluated and none of them applied._';
+        }
+        return (`_No reviewer ran. ${declined.length} OPTIONAL checklist(s) DID apply to this diff and were not ` +
+            `run; the rest were evaluated and did not apply._`);
+    }
+    // The roll-up line. `baseResolved:false` replaces it entirely: with no fork point the changed-file set is
+    // EMPTY, so nothing matched — including patternless ALWAYS-RUNS checklists — and reporting that as
+    // "all skipped ✅" would post a green all-clear for a PR where nothing was actually evaluated.
+    rollupHeader(rows, baseResolved) {
+        if (!baseResolved) {
+            return (`## 🔍 Company review checklists — ⚠️ NOT EVALUATED (${rows.length} defined)\n` +
+                `_No diff base (fork point of main) could be resolved, so no checklist was matched against ` +
+                `anything. This is **not** an all-clear._`);
+        }
+        const ran = rows.filter((r) => this.reviewerRan(r));
+        const declined = rows.filter((r) => this.declined(r));
+        const skipped = rows.length - ran.length - declined.length;
+        const parts = [];
+        for (const pair of this.rollupCounts(ran))
+            parts.push(pair);
+        const breakdown = parts.length > 0 ? ` (${parts.join(' · ')})` : '';
+        const skip = skipped > 0 ? ` · ${skipped} skipped ✅` : '';
+        // Counted SEPARATELY from "skipped", and without a ✅. A declined optional review is a legitimate
+        // outcome, but it is not the same good news as a checklist that had nothing to look at — folding the
+        // two together would let a PR that declined every optional review read as fully covered.
+        const notRun = declined.length > 0 ? ` · ${declined.length} optional not run` : '';
+        return `## 🔍 Company review checklists — ${rows.length} defined · ${ran.length} ran${breakdown}${skip}${notRun}`;
+    }
+    // `🟢 2 · 🟡 1` — only the non-zero buckets, so a clean run reads as one number rather than four.
+    rollupCounts(ran) {
+        const counts = [];
+        const emojiFor = ['🟢', '🟡', '🟠'];
+        const statusFor = [rules_config_1.CK_PASS, rules_config_1.CK_WARN, rules_config_1.CK_OVERRIDDEN];
+        statusFor.forEach((status, i) => {
+            const n = ran.filter((r) => r.status === status).length;
+            if (n > 0)
+                counts.push(`${emojiFor[i]} ${n}`);
+        });
+        return counts;
+    }
+    // One roster line + its why sub-bullet. A checked box means a reviewer ran; an unchecked one means the
+    // checklist was evaluated and did not apply, which the words state as the good news it is.
+    rosterBullet(row) {
+        const box = this.reviewerRan(row) ? '- [x]' : '- [ ]';
+        return (`${box} ${this.verdictEmoji(row)} **${row.subagent}**${this.optionalTag(row)} — ` +
+            `${this.verdictWords(row)}${this.evidenceSuffix(row)}\n` +
+            `  - ${this.whyLine(row)}`);
+    }
+    /**
+     * Did a reviewer actually produce a verdict for this row?
+     *
+     * `row.ran` is really "this checklist APPLIED to the diff" — for a required checklist the two are the
+     * same thing, because the PR cannot open otherwise, and the field was named before optional checklists
+     * existed. For a DECLINED optional one they diverge, and using `ran` alone would put a checked box and a
+     * reviewer section on a review that nobody performed.
+     */
+    reviewerRan(row) {
+        return row.ran && !this.declined(row);
+    }
+    // Applied, optional, and carrying no verdict — i.e. the human was offered this review and said no (or
+    // `--no-optional` skipped the offer). Never true of a required checklist: one of those with no verdict
+    // does not reach a PR at all.
+    declined(row) {
+        return row.ran && !row.required && (row.status === rules_config_1.CK_MISSING || row.status === '');
+    }
+    // Marks which rows the human could have declined. Without it a reader cannot tell a review that was
+    // skippable from one that simply passed, and so cannot judge how much this PR was actually reviewed.
+    optionalTag(row) {
+        return row.required ? '' : ' _(optional)_';
+    }
+    /**
+     * Whether the reviewer demonstrably opened the diff, read from its own transcript. A QUALITY signal and
+     * never a blocker (see SubagentProvenanceService.evidenceFor) — but published, because "wrote a verdict
+     * without reading the change" is exactly what a reader of this comment would want to weigh.
+     */
+    evidenceSuffix(row) {
+        if (!this.reviewerRan(row) || row.diffRead === '')
+            return '';
+        return row.diffRead === 'yes' ? ' _(diff read ✓)_' : ' _(⚠️ no diff read recorded)_';
+    }
+    verdictEmoji(row) {
+        if (!this.reviewerRan(row))
+            return '⚪';
+        if (row.status === rules_config_1.CK_PASS)
+            return '🟢';
+        if (row.status === rules_config_1.CK_WARN)
+            return '🟡';
+        if (row.status === rules_config_1.CK_OVERRIDDEN)
+            return '🟠';
+        if (row.status === rules_config_1.CK_FAIL)
+            return '🔴';
+        return '⚪';
+    }
+    // SHORT words for a roster line / section heading. Short on purpose: the reviewer's own output and any
+    // override justification get their own section below, and a roster exists to be scanned.
+    verdictWords(row) {
+        // Two different unchecked boxes, two different sentences. "Not applicable" is the diff's doing;
+        // "not run" is a person's, and reporting the second as the first would quietly credit a review that
+        // a human deliberately declined.
+        if (this.declined(row))
+            return 'OPTIONAL — applied to this diff but was NOT run (not selected)';
+        if (!row.ran)
+            return 'skipped, not applicable to this diff (expected ✅)';
+        if (row.status === rules_config_1.CK_PASS)
+            return 'passed';
+        if (row.status === rules_config_1.CK_WARN)
+            return 'passed with concerns';
+        if (row.status === rules_config_1.CK_OVERRIDDEN)
+            return 'OVERRIDDEN — shipped with a stated justification';
+        if (row.status === rules_config_1.CK_FAIL)
+            return 'FAILED review';
+        if (row.status === rules_config_1.CK_MISSING)
+            return 'no verdict written';
+        return `unknown verdict (${row.status})`;
+    }
+    /**
+     * WHY this checklist ran or did not — the line that answers "why was this reviewer involved?". Branches
+     * on `configuredPatterns`, NEVER on `firedPatterns.length`: a patternless checklist and a skipped one
+     * both fired zero globs and they mean opposite things, so keying off the fired list would tell every
+     * skipped checklist's reader that the whole diff had been in its scope.
+     */
+    whyLine(row) {
+        const total = row.changedFileCount;
+        if (row.configuredPatterns.length === 0) {
+            // State the fact, not a suspicion. Patternless is a deliberate configuration — an always-runs
+            // gate (every PR names a ticket, every PR has an owner) is exactly what it is FOR — so telling
+            // every such row to "add `patterns` if that is not intended" nags the repos that meant it, on
+            // every PR, forever. A reader who wants to know whether it was intended can read the config.
+            return (`ALWAYS RUNS (no patterns) — whole diff in scope, ${total} changed file(s): ` +
+                `${(0, rules_config_1.formatFileList)(row.matchedFiles)}`);
+        }
+        const configured = this.asCode(row.configuredPatterns);
+        if (row.firedPatterns.length === 0) {
+            return `${configured} matched 0 of ${total} changed file(s)`;
+        }
+        return (`matched ${this.asCode(row.firedPatterns)} → ${row.matchedFiles.length} of ${total} ` +
+            `changed file(s): ${(0, rules_config_1.formatFileList)(row.matchedFiles)}`);
+    }
+    asCode(patterns) {
+        return patterns.map((p) => `\`${p}\``).join(', ');
+    }
+    // Reviewers that ran, exceptions first (overridden → warned → passed) so a reader meets what needs
+    // attention before a wall of green.
+    ranOrdered(rows) {
+        const rank = [rules_config_1.CK_OVERRIDDEN, rules_config_1.CK_WARN, rules_config_1.CK_PASS];
+        return rows
+            .filter((r) => this.reviewerRan(r))
+            .slice()
+            .sort((a, b) => this.rankOf(rank, a.status) - this.rankOf(rank, b.status));
+    }
+    rankOf(rank, status) {
+        const idx = rank.indexOf(status);
+        return idx < 0 ? rank.length : idx;
+    }
+    commentSection(row) {
+        const heading = `#### ${this.verdictEmoji(row)} ${row.subagent} — ${this.verdictWords(row)}`;
+        const body = row.detail.trim() !== '' ? row.detail.trim() : '_(reviewer recorded no output)_';
+        return new CommentSection(heading, body);
+    }
+    // Keep the comment under GitHub's size cap by shrinking the LONGEST section body first (so a short
+    // overridden note is never cut to make room for a long passing one), never dropping a verdict heading.
+    fitComment(header, sections) {
+        const assemble = () => `${header}\n\n${sections.map((s) => `${s.heading}\n\n${s.body}`).join('\n\n')}`;
+        const trunc = '\n\n…_[truncated to fit the GitHub comment size limit]_';
+        let out = assemble();
+        while (out.length > COMMENT_LIMIT) {
+            const idx = this.longestBodyIndex(sections);
+            if (idx < 0 || sections[idx].body.length <= trunc.length + 1)
+                break;
+            const over = out.length - COMMENT_LIMIT;
+            const keep = Math.max(0, sections[idx].body.length - over - trunc.length - 8);
+            sections[idx].body = sections[idx].body.slice(0, keep).trimEnd() + trunc;
+            out = assemble();
+        }
+        return out;
+    }
+    longestBodyIndex(sections) {
+        let idx = -1;
+        let max = -1;
+        sections.forEach((s, i) => {
+            if (s.body.length > max) {
+                max = s.body.length;
+                idx = i;
+            }
+        });
+        return idx;
+    }
+};
+exports.ChecklistCommentRenderer = ChecklistCommentRenderer;
+exports.ChecklistCommentRenderer = ChecklistCommentRenderer = tslib_1.__decorate([
+    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton)
+], ChecklistCommentRenderer);
+//# sourceMappingURL=checklist-comment-renderer.js.map

package/src/dashboard/checklist-comment-renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checklist-comment-renderer.js","sourceRoot":"","sources":["../../../../../../packages/tooling/pr-gate/src/dashboard/checklist-comment-renderer.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n    formatFileList, CK_PASS, CK_WARN, CK_OVERRIDDEN, CK_FAIL, CK_MISSING,\n} from '@webpieces/rules-config';\nimport { injectable, bindingScopeValues } from 'inversify';\nimport { ChecklistCommentRow } from './checklist-comment-row';\n\n/**\n * Hidden marker on the checklist review COMMENT — the \"2nd comment\" the PR description points at — so\n * wp-finish can find and PATCH its own comment on every push instead of appending a new one. Versioned so\n * the format can evolve without matching an old shape. v2 = the full roster (every DEFINED checklist,\n * matched or not) + tri-state verdicts.\n */\nexport const CHECKLIST_COMMENT_MARKER = '<!-- webpieces-checklists v2 -->';\n\nconst COMMENT_LIMIT = 65000; // under GitHub's 65536-char cap, with headroom for the marker + roll-up.\n\n// One checklist section for the combined comment (heading + verbatim reviewer output), so oversize\n// truncation can shrink the longest BODY without ever dropping a verdict heading.\nclass CommentSection {\n    heading: string;\n    body: string;\n\n    constructor(heading: string, body: string) {\n        this.heading = heading;\n        this.body = body;\n    }\n}\n\n/**\n * Renders the 2nd PR comment: the reviewer checklist — full roster plus each reviewer's verbatim output.\n *\n * Split out of `Dashboard` when the PR-description/commit-body swap pushed that file over the 700-line\n * cap, and the seam was already there to be found: this is ONE of the three surfaces the gated flow\n * writes, it shares no rendering helper with the other two (it speaks `ChecklistCommentRow`, where the\n * dashboard speaks `ChecklistRow`), and it owns the only size-fitting logic in the package. One class per\n * surface is the shape the rest of this change assumes — see `Dashboard.renderPrBody` and\n * `Dashboard.renderDetailComment`.\n *\n * `@injectable(bindingScopeValues.Singleton)` so it is drawn in the DI design and injected by type.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class ChecklistCommentRenderer {\n    /**\n     * The ONE combined PR comment. Two halves, in this order:\n     *\n     *   1. A roll-up plus the FULL ROSTER — every DEFINED checklist as a checkbox, each with a sub-bullet\n     *      stating exactly which globs fired against which files, or which did not and out of how many.\n     *      Skipped checklists are listed on purpose: skipping is the normal, healthy outcome, and a comment\n     *      that names only the reviewers that fired cannot distinguish \"evaluated and irrelevant\" from\n     *      \"never wired up\" — nor answer \"why did the DB reviewer run on my frontend PR?\".\n     *   2. One section per reviewer that RAN, carrying its full `output` — the depth a verdict line throws\n     *      away. Overridden first, then warned, then passed: a reader should meet the exceptions first.\n     *\n     * Idempotent: keyed by the hidden marker so wp-finish PATCHes this same comment on every push.\n     */\n    render(\n        rows: readonly ChecklistCommentRow[],\n        provenanceVerified: boolean,\n        baseResolved: boolean,\n    ): string {\n        const ran = this.ranOrdered(rows);\n        const prov = provenanceVerified\n            ? '_Each reviewer ran as its own independent subagent, verified from the Claude Code harness._'\n            : '_⚠️ Reviewer provenance was NOT verified (no Claude Code session) — treat these as unverified._';\n        // The roster lives in the HEADER, never in a section: fitComment only ever shrinks section bodies,\n        // so a roster line can never be the thing an oversize comment silently drops.\n        const lines: string[] = [CHECKLIST_COMMENT_MARKER, this.rollupHeader(rows, baseResolved)];\n        // No reviewer ran ⇒ no provenance claim to make. Printing one either way would attest to nothing.\n        if (ran.length > 0) lines.push(prov);\n        lines.push('', `### Checklists (all ${rows.length})`);\n        for (const row of rows) lines.push(this.rosterBullet(row));\n        const header = lines.join('\\n');\n        if (ran.length === 0) {\n            return `${header}\\n\\n${this.nothingRanNote(rows)}`;\n        }\n        return this.fitComment(\n            `${header}\\n\\n### Reviews that ran`,\n            ran.map((r: ChecklistCommentRow): CommentSection => this.commentSection(r)),\n        );\n    }\n\n    /**\n     * The closing note when no reviewer produced a verdict. The original wording — \"every configured\n     * checklist was evaluated and none of them applied\" — is an all-clear, and it becomes FALSE the moment a\n     * checklist did apply and was declined. That sentence under a PR nobody reviewed is precisely the\n     * misreport this feature could otherwise introduce, so the declined case gets its own words.\n     */\n    private nothingRanNote(rows: readonly ChecklistCommentRow[]): string {\n        const declined = rows.filter((r: ChecklistCommentRow): boolean => this.declined(r));\n        if (declined.length === 0) {\n            return '_No reviewer had to run on this diff — every configured checklist was evaluated and none of them applied._';\n        }\n        return (\n            `_No reviewer ran. ${declined.length} OPTIONAL checklist(s) DID apply to this diff and were not ` +\n            `run; the rest were evaluated and did not apply._`\n        );\n    }\n\n    // The roll-up line. `baseResolved:false` replaces it entirely: with no fork point the changed-file set is\n    // EMPTY, so nothing matched — including patternless ALWAYS-RUNS checklists — and reporting that as\n    // \"all skipped ✅\" would post a green all-clear for a PR where nothing was actually evaluated.\n    private rollupHeader(rows: readonly ChecklistCommentRow[], baseResolved: boolean): string {\n        if (!baseResolved) {\n            return (\n                `## 🔍 Company review checklists — ⚠️ NOT EVALUATED (${rows.length} defined)\\n` +\n                `_No diff base (fork point of main) could be resolved, so no checklist was matched against ` +\n                `anything. This is **not** an all-clear._`\n            );\n        }\n        const ran = rows.filter((r: ChecklistCommentRow): boolean => this.reviewerRan(r));\n        const declined = rows.filter((r: ChecklistCommentRow): boolean => this.declined(r));\n        const skipped = rows.length - ran.length - declined.length;\n        const parts: string[] = [];\n        for (const pair of this.rollupCounts(ran)) parts.push(pair);\n        const breakdown = parts.length > 0 ? ` (${parts.join(' · ')})` : '';\n        const skip = skipped > 0 ? ` · ${skipped} skipped ✅` : '';\n        // Counted SEPARATELY from \"skipped\", and without a ✅. A declined optional review is a legitimate\n        // outcome, but it is not the same good news as a checklist that had nothing to look at — folding the\n        // two together would let a PR that declined every optional review read as fully covered.\n        const notRun = declined.length > 0 ? ` · ${declined.length} optional not run` : '';\n        return `## 🔍 Company review checklists — ${rows.length} defined · ${ran.length} ran${breakdown}${skip}${notRun}`;\n    }\n\n    // `🟢 2 · 🟡 1` — only the non-zero buckets, so a clean run reads as one number rather than four.\n    private rollupCounts(ran: readonly ChecklistCommentRow[]): string[] {\n        const counts: string[] = [];\n        const emojiFor: string[] = ['🟢', '🟡', '🟠'];\n        const statusFor: string[] = [CK_PASS, CK_WARN, CK_OVERRIDDEN];\n        statusFor.forEach((status: string, i: number): void => {\n            const n = ran.filter((r: ChecklistCommentRow): boolean => r.status === status).length;\n            if (n > 0) counts.push(`${emojiFor[i]} ${n}`);\n        });\n        return counts;\n    }\n\n    // One roster line + its why sub-bullet. A checked box means a reviewer ran; an unchecked one means the\n    // checklist was evaluated and did not apply, which the words state as the good news it is.\n    private rosterBullet(row: ChecklistCommentRow): string {\n        const box = this.reviewerRan(row) ? '- [x]' : '- [ ]';\n        return (\n            `${box} ${this.verdictEmoji(row)} **${row.subagent}**${this.optionalTag(row)} — ` +\n            `${this.verdictWords(row)}${this.evidenceSuffix(row)}\\n` +\n            `  - ${this.whyLine(row)}`\n        );\n    }\n\n    /**\n     * Did a reviewer actually produce a verdict for this row?\n     *\n     * `row.ran` is really \"this checklist APPLIED to the diff\" — for a required checklist the two are the\n     * same thing, because the PR cannot open otherwise, and the field was named before optional checklists\n     * existed. For a DECLINED optional one they diverge, and using `ran` alone would put a checked box and a\n     * reviewer section on a review that nobody performed.\n     */\n    private reviewerRan(row: ChecklistCommentRow): boolean {\n        return row.ran && !this.declined(row);\n    }\n\n    // Applied, optional, and carrying no verdict — i.e. the human was offered this review and said no (or\n    // `--no-optional` skipped the offer). Never true of a required checklist: one of those with no verdict\n    // does not reach a PR at all.\n    private declined(row: ChecklistCommentRow): boolean {\n        return row.ran && !row.required && (row.status === CK_MISSING || row.status === '');\n    }\n\n    // Marks which rows the human could have declined. Without it a reader cannot tell a review that was\n    // skippable from one that simply passed, and so cannot judge how much this PR was actually reviewed.\n    private optionalTag(row: ChecklistCommentRow): string {\n        return row.required ? '' : ' _(optional)_';\n    }\n\n    /**\n     * Whether the reviewer demonstrably opened the diff, read from its own transcript. A QUALITY signal and\n     * never a blocker (see SubagentProvenanceService.evidenceFor) — but published, because \"wrote a verdict\n     * without reading the change\" is exactly what a reader of this comment would want to weigh.\n     */\n    private evidenceSuffix(row: ChecklistCommentRow): string {\n        if (!this.reviewerRan(row) || row.diffRead === '') return '';\n        return row.diffRead === 'yes' ? ' _(diff read ✓)_' : ' _(⚠️ no diff read recorded)_';\n    }\n\n    private verdictEmoji(row: ChecklistCommentRow): string {\n        if (!this.reviewerRan(row)) return '⚪';\n        if (row.status === CK_PASS) return '🟢';\n        if (row.status === CK_WARN) return '🟡';\n        if (row.status === CK_OVERRIDDEN) return '🟠';\n        if (row.status === CK_FAIL) return '🔴';\n        return '⚪';\n    }\n\n    // SHORT words for a roster line / section heading. Short on purpose: the reviewer's own output and any\n    // override justification get their own section below, and a roster exists to be scanned.\n    private verdictWords(row: ChecklistCommentRow): string {\n        // Two different unchecked boxes, two different sentences. \"Not applicable\" is the diff's doing;\n        // \"not run\" is a person's, and reporting the second as the first would quietly credit a review that\n        // a human deliberately declined.\n        if (this.declined(row)) return 'OPTIONAL — applied to this diff but was NOT run (not selected)';\n        if (!row.ran) return 'skipped, not applicable to this diff (expected ✅)';\n        if (row.status === CK_PASS) return 'passed';\n        if (row.status === CK_WARN) return 'passed with concerns';\n        if (row.status === CK_OVERRIDDEN) return 'OVERRIDDEN — shipped with a stated justification';\n        if (row.status === CK_FAIL) return 'FAILED review';\n        if (row.status === CK_MISSING) return 'no verdict written';\n        return `unknown verdict (${row.status})`;\n    }\n\n    /**\n     * WHY this checklist ran or did not — the line that answers \"why was this reviewer involved?\". Branches\n     * on `configuredPatterns`, NEVER on `firedPatterns.length`: a patternless checklist and a skipped one\n     * both fired zero globs and they mean opposite things, so keying off the fired list would tell every\n     * skipped checklist's reader that the whole diff had been in its scope.\n     */\n    private whyLine(row: ChecklistCommentRow): string {\n        const total = row.changedFileCount;\n        if (row.configuredPatterns.length === 0) {\n            // State the fact, not a suspicion. Patternless is a deliberate configuration — an always-runs\n            // gate (every PR names a ticket, every PR has an owner) is exactly what it is FOR — so telling\n            // every such row to \"add `patterns` if that is not intended\" nags the repos that meant it, on\n            // every PR, forever. A reader who wants to know whether it was intended can read the config.\n            return (\n                `ALWAYS RUNS (no patterns) — whole diff in scope, ${total} changed file(s): ` +\n                `${formatFileList(row.matchedFiles)}`\n            );\n        }\n        const configured = this.asCode(row.configuredPatterns);\n        if (row.firedPatterns.length === 0) {\n            return `${configured} matched 0 of ${total} changed file(s)`;\n        }\n        return (\n            `matched ${this.asCode(row.firedPatterns)} → ${row.matchedFiles.length} of ${total} ` +\n            `changed file(s): ${formatFileList(row.matchedFiles)}`\n        );\n    }\n\n    private asCode(patterns: readonly string[]): string {\n        return patterns.map((p: string): string => `\\`${p}\\``).join(', ');\n    }\n\n    // Reviewers that ran, exceptions first (overridden → warned → passed) so a reader meets what needs\n    // attention before a wall of green.\n    private ranOrdered(rows: readonly ChecklistCommentRow[]): ChecklistCommentRow[] {\n        const rank: string[] = [CK_OVERRIDDEN, CK_WARN, CK_PASS];\n        return rows\n            .filter((r: ChecklistCommentRow): boolean => this.reviewerRan(r))\n            .slice()\n            .sort(\n                (a: ChecklistCommentRow, b: ChecklistCommentRow): number =>\n                    this.rankOf(rank, a.status) - this.rankOf(rank, b.status),\n            );\n    }\n\n    private rankOf(rank: readonly string[], status: string): number {\n        const idx = rank.indexOf(status);\n        return idx < 0 ? rank.length : idx;\n    }\n\n    private commentSection(row: ChecklistCommentRow): CommentSection {\n        const heading = `#### ${this.verdictEmoji(row)} ${row.subagent} — ${this.verdictWords(row)}`;\n        const body =\n            row.detail.trim() !== '' ? row.detail.trim() : '_(reviewer recorded no output)_';\n        return new CommentSection(heading, body);\n    }\n\n    // Keep the comment under GitHub's size cap by shrinking the LONGEST section body first (so a short\n    // overridden note is never cut to make room for a long passing one), never dropping a verdict heading.\n    private fitComment(header: string, sections: CommentSection[]): string {\n        const assemble = (): string =>\n            `${header}\\n\\n${sections.map((s: CommentSection): string => `${s.heading}\\n\\n${s.body}`).join('\\n\\n')}`;\n        const trunc = '\\n\\n…_[truncated to fit the GitHub comment size limit]_';\n        let out = assemble();\n        while (out.length > COMMENT_LIMIT) {\n            const idx = this.longestBodyIndex(sections);\n            if (idx < 0 || sections[idx].body.length <= trunc.length + 1) break;\n            const over = out.length - COMMENT_LIMIT;\n            const keep = Math.max(0, sections[idx].body.length - over - trunc.length - 8);\n            sections[idx].body = sections[idx].body.slice(0, keep).trimEnd() + trunc;\n            out = assemble();\n        }\n        return out;\n    }\n\n    private longestBodyIndex(sections: readonly CommentSection[]): number {\n        let idx = -1;\n        let max = -1;\n        sections.forEach((s: CommentSection, i: number): void => {\n            if (s.body.length > max) {\n                max = s.body.length;\n                idx = i;\n            }\n        });\n        return idx;\n    }\n}\n"]}

package/src/dashboard/dashboard.d.ts

@@ -1,6 +1,13 @@
 import { GateDefinition, ReviewJson } from '@webpieces/rules-config';
-import { ChecklistCommentRow } from './checklist-comment-row';
-export declare const CHECKLIST_COMMENT_MARKER = "<!-- webpieces-checklists v2 -->";
+/**
+ * Hidden marker on the FULL-DASHBOARD comment — the "1st comment" the PR description points at — so
+ * finish PATCHes its own comment on every push instead of appending a new one, exactly like the checklist
+ * comment (see ChecklistCommentRenderer, which owns the 2nd).
+ *
+ * This comment did not exist before the PR description became the git-log body: the dashboard WAS the
+ * description. Moving it here is what keeps a risk table out of every squash commit on main.
+ */
+export declare const DETAIL_COMMENT_MARKER = "<!-- webpieces-pr-detail v1 -->";
 export declare class GateResult {
     name: string;
     warningColor: string;
@@ -29,70 +36,77 @@ export declare class DashboardInput {
     mainHead: string;
     review: ReviewJson;
     checklists: ChecklistRow[];
-    constructor(title: string, gateResults: GateResult[], disables: DisableCounts, buildPassed: boolean, forkPoint: string, featureHead: string, mainHead: string, review: ReviewJson, checklists?: ChecklistRow[]);
+    /**
+     * `commands.pr-gate.buildCommand` VERBATIM, named in the PR-body footer so `git log` records WHICH
+     * command vouched for the commit. Read from config rather than hard-coded because the footer used to
+     * assert "build ran via nx affected" on every repo, including those whose buildCommand is not nx.
+     *
+     * REQUIRED, with no default, and `checklists` lost its `= []` for the same reason. A defaulted
+     * `buildCommand: string = ''` let every pre-existing 9-argument construction keep compiling while
+     * silently rendering a footer that claims nothing — an absence that quietly means "no build was
+     * named", which is the widening-by-omission the compatibility policy calls out. Making it required
+     * means every caller states what vouched for the commit, and the empty string stays available for a
+     * repo that genuinely has no build command, but only when someone writes it down.
+     */
+    buildCommand: string;
+    constructor(title: string, gateResults: GateResult[], disables: DisableCounts, buildPassed: boolean, forkPoint: string, featureHead: string, mainHead: string, review: ReviewJson, checklists: ChecklistRow[], buildCommand: string);
 }
 /** Renders the PR-gate dashboard markdown (gates × changed files, disables, risk, 3-point hashes). */
 export declare class Dashboard {
     computeGateResults(gates: GateDefinition[], changedFiles: string[]): GateResult[];
     countAddedDisables(patch: string): DisableCounts;
-    renderDashboard(input: DashboardInput): string;
     /**
-     * The ONE combined PR comment. Two halves, in this order:
+     * The FULL dashboard — every row (green included), the whole summary, the 3-point hash points.
      *
-     *   1. A roll-up plus the FULL ROSTER — every DEFINED checklist as a checkbox, each with a sub-bullet
-     *      stating exactly which globs fired against which files, or which did not and out of how many.
-     *      Skipped checklists are listed on purpose: skipping is the normal, healthy outcome, and a comment
-     *      that names only the reviewers that fired cannot distinguish "evaluated and irrelevant" from
-     *      "never wired up" — nor answer "why did the DB reviewer run on my frontend PR?".
-     *   2. One section per reviewer that RAN, carrying its full `output` — the depth a verdict line throws
-     *      away. Overridden first, then warned, then passed: a reader should meet the exceptions first.
+     * This is the **1st PR comment**, not the PR description. It used to be the description, and that is
+     * exactly what put it into main's history: GitHub's `squash_merge_commit_message: PR_BODY` copies the
+     * description verbatim into the squash commit, so every `git log` entry carried the risk table, the
+     * hash points and the gate token. The description now holds {@link renderPrBody}'s compact form, and
+     * everything long-form lives here where a reader can open it and `git log` never sees it.
      *
-     * Idempotent: keyed by the hidden marker so wp-finish PATCHes this same comment on every push.
+     * Machine-facing content belongs HERE too — this comment carries the HMAC gate token. That is the
+     * whole rule that keeps the description clean: an HTML comment is invisible in rendered markdown but
+     * perfectly visible in `git log`, so nothing hidden may live in the description.
      */
-    renderChecklistComment(rows: readonly ChecklistCommentRow[], provenanceVerified: boolean, baseResolved: boolean): string;
+    renderDetailComment(input: DashboardInput): string;
     /**
-     * The closing note when no reviewer produced a verdict. The original wording — "every configured
-     * checklist was evaluated and none of them applied" — is an all-clear, and it becomes FALSE the moment a
-     * checklist did apply and was declined. That sentence under a PR nobody reviewed is precisely the
-     * misreport this feature could otherwise introduce, so the declined case gets its own words.
-     */
-    private nothingRanNote;
-    private rollupHeader;
-    private rollupCounts;
-    private rosterBullet;
-    /**
-     * Did a reviewer actually produce a verdict for this row?
+     * The PR DESCRIPTION — which is also, byte for byte, the squash-commit body that lands in main.
      *
-     * `row.ran` is really "this checklist APPLIED to the diff" — for a required checklist the two are the
-     * same thing, because the PR cannot open otherwise, and the field was named before optional checklists
-     * existed. For a DECLINED optional one they diverge, and using `ran` alone would put a checked box and a
-     * reviewer section on a review that nobody performed.
-     */
-    private reviewerRan;
-    private declined;
-    private optionalTag;
-    /**
-     * Whether the reviewer demonstrably opened the diff, read from its own transcript. A QUALITY signal and
-     * never a blocker (see SubagentProvenanceService.evidenceFor) — but published, because "wrote a verdict
-     * without reading the change" is exactly what a reader of this comment would want to weigh.
+     * ─── Why one string serves both ─────────────────────────────────────────────────────────────────
+     * There used to be two: a long dashboard in the description and this compact form passed to
+     * `gh pr merge --body-file`. That made the good `git log` reachable ONLY through an explicit
+     * `--body-file` merge, because every other route (the GitHub Merge button, a bare `gh pr merge`)
+     * takes its body from the repo's `squash_merge_commit_message`, and on `PR_BODY` that copied the
+     * whole dashboard into history. Two repos ran that way for months.
+     *
+     * Making the DESCRIPTION the compact form inverts it: `PR_BODY` now yields exactly the right commit,
+     * so the UI button, a bare `gh pr merge`, `wp-land-pr` and finish's own auto-merge all converge on
+     * identical bytes. The consumer requirement is two repo settings — `squash_merge_commit_title:
+     * PR_TITLE` and `squash_merge_commit_message: PR_BODY` — not a config key and not a command anyone
+     * has to remember. That convergence is the point, and `pr-body-is-merge-body.spec.ts` pins it.
+     *
+     * ─── The shape, and why each part earns its line ────────────────────────────────────────────────
+     * The URL leads, labelled `(for git log)` so nobody deletes it as redundant while reading the PR on
+     * GitHub — on the page it is obviously the page you are on; in `git log` it is the only way back.
+     * Then the risk score (always). Then ONLY the non-green flags: a commit log should surface what
+     * stands out, and the green rows are in the 1st comment. The last bullet is always the pointer to
+     * that comment, so a reader of main's history is never left thinking this is all there was. Then the
+     * summary capped at 4 sentences, then the footer naming the build command that vouched for it.
+     *
+     * The hidden gate-token marker is appended AFTER this by the caller, so it is the very last line of
+     * the description and therefore of the commit. It stays an HTML comment — invisible on the PR page,
+     * visible in `git log` — which is a deliberate accepted trade: the alternative was reshaping a live
+     * CI-critical surface that two consumer repos verify on every PR, to save one line of history.
      */
-    private evidenceSuffix;
-    private verdictEmoji;
-    private verdictWords;
+    renderPrBody(input: DashboardInput, prUrl: string): string;
     /**
-     * WHY this checklist ran or did not — the line that answers "why was this reviewer involved?". Branches
-     * on `configuredPatterns`, NEVER on `firedPatterns.length`: a patternless checklist and a skipped one
-     * both fired zero globs and they mean opposite things, so keying off the fired list would tell every
-     * skipped checklist's reader that the whole diff had been in its scope.
+     * The footer, naming the build command from `commands.pr-gate.buildCommand` VERBATIM.
+     *
+     * No backticks: this string's primary home is `git log` in a terminal, where markdown ticks are
+     * literal punctuation. "run locally" is the honest claim — this is the LOCAL gate's receipt, and the
+     * server-side proof is the gate token in the 1st comment, not this sentence.
      */
-    private whyLine;
-    private asCode;
-    private ranOrdered;
-    private rankOf;
-    private commentSection;
-    private fitComment;
-    private longestBodyIndex;
-    renderCommitBody(input: DashboardInput, prUrl: string): string;
+    private prBodyFooter;
     private nonGreenFlags;
     private checklistStatusText;
     private firstSentences;