@fullstackhouse/cerber 0.12.0 → 0.13.0

package/README.md

@@ -41,6 +41,24 @@ for reviews you sent, one for the ones you marked reviewed or skipped, one for
 merged and closed PRs — and PRs in archived repos are never picked up at all,
 since the repo is read-only and a review could never be sent.
 
+Settling a review is your decision, not GitHub's: skip a PR, or mark one
+reviewed without sending, and GitHub still holds its review request open,
+because nothing cerber does here reaches it. Those rows stay marked where they
+sit, counted on the drawer they went into, and named in place of the empty
+inbox — cerber never tells you nothing awaits you while its own poll says
+otherwise. It is a report, not a nag: what you decided here stands, and the
+mark clears itself the moment GitHub hears from you.
+
+An open request doesn't mean the ball is yours, though. You may have argued the
+whole thing out in the PR conversation and never pressed GitHub's review
+button, which leaves the request open with nothing blocked on you. So cerber
+reads the conversation and says whose move it is: `you haven't replied` (they
+are waiting), `waiting on them` (you had the last word), or `they replied last`
+(it is back with you). Bots don't count as an answer, or a chatty CI would put
+every PR back on you. If the conversation can't be read it says `unanswered on
+GitHub` and claims nothing further — guessing "you never replied" at someone
+who did is the one mistake worth designing against.
+
 The cockpit is a background tab most of the day, so it tells you when the queue
 grows: a desktop notification naming the PR that arrived — click it to open the
 review — folded into one popup when several land at once. It stays quiet while
@@ -60,9 +78,11 @@ Each review is a plain JSON artifact in `~/.cerber/reviews/` (override with
 - **Chapters** — the changed files grouped into a logical walkthrough, each
   with a title, an explanation, and its slice of the diff
 - **Draft comments** — inline, anchored to file/line, only things worth a
-  human's time
+  human's time. Findings are graded **blocker / minor / nit** — the words mean
+  what they mean everywhere, and only a blocker stands between the PR and
+  approval; a question or note carries no grade at all
 - **Verdict** — approve / comment / request changes, with a 0–100 confidence
-  score and reasoning
+  score and reasoning that names the worst finding still standing
 - **Run metadata** — model, whether it read the source or only the diff, and
   the token spend as an API-rate equivalent
 

package/dist/core/artifact.js

@@ -1,5 +1,12 @@
 import { z } from "zod";
 export const SCHEMA_VERSION = 1;
+/**
+ * How hard a finding presses on the merge. The words carry their own
+ * semantics: a blocker is the only tier that stops approval; minor is
+ * "should fix, author's call"; nit is taste. Absent (null) means the comment
+ * is not a finding at all — a question, a note, praise — not "unknown".
+ */
+export const SeveritySchema = z.enum(["blocker", "minor", "nit"]);
 /** A draft inline comment. Never sent to GitHub unless the user explicitly sends the review. */
 export const CommentSchema = z.object({
     id: z.string(),
@@ -8,6 +15,8 @@ export const CommentSchema = z.object({
     line: z.number().int().positive().nullable(),
     body: z.string(),
     chapterId: z.string().nullable().default(null),
+    /** Merge impact of this finding; null for remarks that are not findings. */
+    severity: SeveritySchema.nullable().default(null),
     origin: z.enum(["ai", "user"]),
     status: z.enum(["draft", "approved", "dropped"]).default("draft"),
     /** Set when the user edits an AI comment's body — calibration signal. */
@@ -111,7 +120,13 @@ export const RevisionSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("summary"), body: z.string() }),
     z.object({ kind: z.literal("verdict"), verdict: VerdictSchema }),
     z.object({ kind: z.literal("chapter"), chapterId: z.string(), title: z.string().optional(), explanation: z.string().optional() }),
-    z.object({ kind: z.literal("comment-edit"), commentId: z.string(), body: z.string() }),
+    z.object({
+        kind: z.literal("comment-edit"),
+        commentId: z.string(),
+        body: z.string(),
+        /** Re-grade while editing; omitted = grade unchanged, null = not a finding. */
+        severity: SeveritySchema.nullable().optional(),
+    }),
     z.object({ kind: z.literal("comment-drop"), commentId: z.string() }),
     z.object({
         kind: z.literal("comment-add"),
@@ -119,6 +134,7 @@ export const RevisionSchema = z.discriminatedUnion("kind", [
         line: z.number().int().positive().nullable(),
         body: z.string(),
         chapterId: z.string().nullable().default(null),
+        severity: SeveritySchema.nullable().default(null),
     }),
 ]);
 /** A revision the run declined to make, and why — shown in the transcript. */
@@ -217,6 +233,7 @@ export const AiReviewSchema = z.object({
         line: z.number().int().positive().nullable(),
         body: z.string(),
         chapterId: z.string().nullable().optional(),
+        severity: SeveritySchema.nullable().optional(),
     })),
     verdict: VerdictSchema,
 });

package/dist/core/autosend.js

@@ -16,6 +16,15 @@ export function evaluateAutoSend(artifact, threshold) {
             reason: `recommendation is ${artifact.verdict.recommendation} — only approve auto-sends`,
         };
     }
+    // An approve verdict standing next to a live blocker finding contradicts
+    // itself; a contradiction is a human's to resolve, never auto-sent.
+    const blockers = artifact.comments.filter((c) => c.status !== "dropped" && c.severity === "blocker");
+    if (blockers.length > 0) {
+        return {
+            eligible: false,
+            reason: `verdict says approve but ${blockers.length} blocker finding(s) still stand — a human resolves that`,
+        };
+    }
     if (artifact.verdict.confidence < threshold) {
         return {
             eligible: false,

package/dist/core/export.js

@@ -1,3 +1,7 @@
+/** Same convention as Send: the grade travels in the text, ungraded stays bare. */
+function grade(c) {
+    return c.severity ? `**${c.severity}:** ` : "";
+}
 /** Render an artifact as a standalone markdown review document. */
 export function toMarkdown(artifact) {
     const lines = [];
@@ -29,7 +33,7 @@ export function toMarkdown(artifact) {
             lines.push("");
             const comments = artifact.comments.filter((c) => c.chapterId === ch.id && c.status !== "dropped");
             for (const c of comments) {
-                lines.push(`> **${c.path}${c.line != null ? `:${c.line}` : ""}** — ${c.body.replace(/\n/g, "\n> ")}`);
+                lines.push(`> **${c.path}${c.line != null ? `:${c.line}` : ""}** — ${grade(c)}${c.body.replace(/\n/g, "\n> ")}`);
                 lines.push("");
             }
         }

package/dist/core/gh.js

@@ -114,6 +114,58 @@ export function mapSearchResults(raw) {
         ];
     });
 }
+/** GitHub types bot accounts, and names them `something[bot]` besides. */
+export const isBot = (c) => c.bot || c.author.endsWith("[bot]");
+/** The PR's conversation comments, oldest first. Not the inline review ones —
+ *  those come attached to a review, which would have cleared the request. */
+export async function fetchConversation(ref) {
+    const out = await gh([
+        "api",
+        "--paginate",
+        `repos/${ref.owner}/${ref.repo}/issues/${ref.number}/comments`,
+        "--jq",
+        '.[] | {author: .user.login, at: .created_at, bot: (.user.type == "Bot")}',
+    ]);
+    // --jq streams one object per line rather than a JSON array.
+    return out
+        .split("\n")
+        .filter((line) => line.trim() !== "")
+        .map((line) => JSON.parse(line));
+}
+/**
+ * Whose move it is, from the conversation: you have not spoken at all, you
+ * spoke last (so it is on them), or a person answered after you (back to you).
+ *
+ * Bots are ignored outright. A repo whose CI posts on every push would
+ * otherwise report "they replied last" on everything, which is the fastest way
+ * to make a signal worthless.
+ */
+export function classifyReply(comments, login) {
+    const human = comments.filter((c) => !isBot(c));
+    const mine = human.filter((c) => c.author === login);
+    if (mine.length === 0)
+        return "none";
+    const lastMine = mine[mine.length - 1].at;
+    // A comment of your own posted at the same instant can't be someone else's
+    // answer to it, so only strictly-later comments hand the move back.
+    return human.some((c) => c.author !== login && c.at > lastMine) ? "them" : "you";
+}
+/** The login `@me` resolves to. Asked once — it cannot change mid-process. */
+let cachedLogin = null;
+export function currentLogin() {
+    cachedLogin ??= gh(["api", "user", "--jq", ".login"]).then((out) => out.trim(), (err) => {
+        // A login we could not fetch is not an answer worth keeping. gh may be
+        // offline or mid-re-auth; caching the rejection would leave every later
+        // poll reporting "unknown" until the process restarts.
+        cachedLogin = null;
+        throw err;
+    });
+    return cachedLogin;
+}
+/** Test seam: forget the cached login so the next call asks again. */
+export function resetLoginCache() {
+    cachedLogin = null;
+}
 export function searchAwaitingArgs(repoFilter, limit = 50) {
     const args = [
         "search",

package/dist/core/revise.js

@@ -39,7 +39,7 @@ export function mergeConcurrentEdits(before, after, current) {
         // Absent from `before` means the user added it while the turn ran.
         if (!then)
             return true;
-        return then.body !== now.body || then.status !== now.status;
+        return then.body !== now.body || then.status !== now.status || then.severity !== now.severity;
     };
     const merged = current.comments.map((now) => userTouched(now.id, now) ? now : fromTurn.get(now.id) ?? now);
     // Comments the turn itself added are not in `current` yet. Only those: a
@@ -115,7 +115,14 @@ export function applyRevisions(artifact, revisions, opts = {}) {
                 }
                 next = {
                     ...next,
-                    comments: next.comments.map((c) => c.id === revision.commentId ? { ...c, body: revision.body } : c),
+                    comments: next.comments.map((c) => c.id === revision.commentId
+                        ? {
+                            ...c,
+                            body: revision.body,
+                            // Omitted = the turn is not re-grading; null = "not a finding".
+                            severity: revision.severity === undefined ? c.severity : revision.severity,
+                        }
+                        : c),
                 };
                 applied.push(revision);
                 break;
@@ -149,6 +156,7 @@ export function applyRevisions(artifact, revisions, opts = {}) {
                             line: revision.line,
                             body: revision.body,
                             chapterId: revision.chapterId,
+                            severity: revision.severity,
                             origin: "ai",
                             status: "draft",
                             editedByUser: false,

package/dist/core/send.js

@@ -2,6 +2,14 @@ import { newSideLines } from "./diff.js";
 export function eventForRecommendation(rec) {
     return { approve: "APPROVE", comment: "COMMENT", request_changes: "REQUEST_CHANGES" }[rec];
 }
+/**
+ * The grade travels in the text: to a reader used to review convention, an
+ * unprefixed comment says "please change this", so leaving a nit bare would
+ * invert its meaning. Ungraded remarks (questions, notes) stay bare.
+ */
+function withGrade(c) {
+    return c.severity ? `**${c.severity}:** ${c.body}` : c.body;
+}
 /**
  * Build the GitHub review payload from an artifact.
  * Includes every comment that is not dropped. Comments whose line is not part
@@ -17,7 +25,7 @@ export function buildReviewPayload(artifact, event) {
         // holds different code — posting there would point the author at something
         // the comment was never about.
         if (!c.drifted && c.line != null && anchorable.get(c.path)?.has(c.line)) {
-            inline.push({ path: c.path, line: c.line, side: "RIGHT", body: c.body });
+            inline.push({ path: c.path, line: c.line, side: "RIGHT", body: withGrade(c) });
         }
         else {
             folded.push(c);
@@ -39,7 +47,7 @@ export function buildReviewPayload(artifact, event) {
             // A drifted comment's line no longer exists, so name it as "was at" —
             // pointing a reader at a line number that moved is worse than no number.
             const at = c.line != null ? `:${c.drifted ? `~${c.line}` : c.line}` : "";
-            parts.push(`- \`${c.path}${at}\` — ${c.body}`);
+            parts.push(`- \`${c.path}${at}\` — ${withGrade(c)}`);
         }
     }
     parts.push("", "---", "_Reviewed with [cerber](https://github.com/fullstackhouse/cerber) 🐕 — drafted by AI, sent by a human._");

package/dist/runner/prompt.js

@@ -49,6 +49,7 @@ Respond with ONLY a JSON object (no markdown fences, no prose before or after) m
       "path": "path/to/file.ts",
       "line": 42,
       "body": "markdown — the review comment. First sentence states the problem plainly; then the evidence or fix. Concrete, actionable, kind.",
+      "severity": "blocker" | "minor" | "nit" | null,
       "chapterId": "short-kebab-id"
     }
   ],
@@ -70,6 +71,13 @@ Rules:
 - Group ALL changed files into chapters that tell the story of the PR (schema first, then logic, then tests, etc). Every changed file must appear in exactly one chapter.
 - "line" is the line number in the NEW version of the file (the "+" side of the diff). Use null for file-level comments. Only reference lines that appear in the diff.
 - Only write comments that are worth a human reading: real bugs, risky patterns, missing tests, unclear naming. No nitpicks a linter would catch. An empty comments array is a perfectly good review of a clean PR.
+- "severity" is the finding's merge impact. The words mean what they mean everywhere:
+  - "blocker" — you would not approve with this in: data loss, a security hole, wrong behavior on a path people actually hit, a broken build. The only tier that blocks.
+  - "minor" — should be fixed, but the author's call; you would approve and not chase it.
+  - "nit" — taste: naming, wording, formatting.
+  - null — not a finding at all: a question, a note, praise.
+- Grade severity as if the finding is true. If you do not believe it enough to grade it, do not write it — or ask it as a question with severity null. Never lower a grade to hedge doubt; doubt belongs in the verdict's "confidence", nowhere else.
+- The verdict must follow from the worst finding still standing: any blocker → "request_changes"; none → "approve" (or "comment" when you genuinely take no position). Name the deciding finding in "reasoning". Never request changes without a blocker in the list, and never approve past one.
 ${confidenceRule}
 - Never invent files or lines not present in the diff.
 
@@ -122,7 +130,8 @@ function renderReview(artifact) {
         .map((c) => {
         const mine = c.origin === "user" || c.editedByUser ? " [THE USER'S OWN WRITING]" : "";
         const dropped = c.status === "dropped" ? " [dropped]" : "";
-        return `- ${c.id} — ${c.path}:${c.line ?? "file-level"}${mine}${dropped}\n  ${c.body}`;
+        const graded = c.severity ? ` [${c.severity}]` : "";
+        return `- ${c.id} — ${c.path}:${c.line ?? "file-level"}${graded}${mine}${dropped}\n  ${c.body}`;
     })
         .join("\n");
     const verdict = artifact.verdict
@@ -192,9 +201,9 @@ Respond with ONLY a JSON object (no markdown fences, no prose before or after) m
     { "kind": "summary", "body": "the rewritten summary" },
     { "kind": "verdict", "verdict": { "recommendation": "approve" | "comment" | "request_changes", "confidence": 0-100, "reasoning": "..." } },
     { "kind": "chapter", "chapterId": "...", "title": "optional new title", "explanation": "optional new explanation" },
-    { "kind": "comment-edit", "commentId": "...", "body": "the rewritten comment" },
+    { "kind": "comment-edit", "commentId": "...", "body": "the rewritten comment", "severity": "blocker" | "minor" | "nit" | null (optional — omit to leave the grade as it is) },
     { "kind": "comment-drop", "commentId": "..." },
-    { "kind": "comment-add", "path": "path/to/file.ts", "line": 42, "body": "...", "chapterId": "..." }
+    { "kind": "comment-add", "path": "path/to/file.ts", "line": 42, "body": "...", "severity": "blocker" | "minor" | "nit" | null, "chapterId": "..." }
   ]
 }
 
@@ -205,6 +214,7 @@ Rules:
 - Comments marked [THE USER'S OWN WRITING] are theirs. Do not edit or drop them. If one of them is what needs changing, say so in your reply and let them do it.
 - Every "commentId" and "chapterId" must be one listed below. Never invent one.
 - "line" is a line in the NEW version of the file and must appear in the diff. Use null for a file-level comment.
+- "severity" is the finding's merge impact — "blocker" (would not approve with this in; the only tier that blocks), "minor" (should fix, author's call), "nit" (taste), null (not a finding: a question, a note). Grade as if the finding is true; hedge in the reply, never in the grade. A verdict revision must still follow from the worst finding left standing.
 - Your reply is prose to a person, not a changelog. The cockpit already shows what you changed — do not list your own edits back to them.
 
 Writing style:

package/dist/runner/review.js

@@ -164,6 +164,7 @@ async function runReview(ref, opts) {
                 line: c.line,
                 body: c.body,
                 chapterId: c.chapterId ?? null,
+                severity: c.severity ?? null,
                 origin: "ai",
                 status: "draft",
                 editedByUser: false,

package/dist/server/daemon.js

@@ -1,7 +1,7 @@
 import { SCHEMA_VERSION, artifactId, artifactKey } from "../core/artifact.js";
 import { evaluateAutoSend } from "../core/autosend.js";
 import { loadConfig } from "../core/config.js";
-import { fetchPrInfo, searchAwaitingMe, submitReview } from "../core/gh.js";
+import { classifyReply, currentLogin, fetchConversation, fetchPrInfo, searchAwaitingMe, submitReview, } from "../core/gh.js";
 import { buildReviewPayload, computeCalibration } from "../core/send.js";
 import { appendAutoSendLog, deleteArtifact, listArtifacts, loadArtifact, saveArtifact, updateArtifactByKey, } from "../core/state.js";
 import { ReviewInProgressError } from "../runner/inflight.js";
@@ -78,6 +78,7 @@ export function startDaemon(opts) {
         lastPollAt: null,
         nextPollAt: new Date(Date.now()).toISOString(),
         lastSummary: null,
+        awaiting: [],
         lastPollError: null,
         autoSend: opts.autoSend,
         autoSendThreshold: opts.autoSendThreshold,
@@ -170,6 +171,34 @@ export function startDaemon(opts) {
         }
         return { discovered };
     }
+    /**
+     * Whose move it is on each awaiting PR, one conversation read apiece.
+     *
+     * GitHub's `commenter:` search qualifier would answer this in a single call,
+     * but it demonstrably disagrees with the REST API — it misses PRs whose only
+     * comment is the newest thing on them — and a tag that says "you never
+     * replied" to someone who did is the exact bug this whole change fixes. So
+     * the conversation is read per PR, bounded by the review concurrency. A read
+     * that fails yields `unknown`, which claims nothing.
+     */
+    async function classifyAll(refs) {
+        let login;
+        try {
+            login = await currentLogin();
+        }
+        catch {
+            // Without knowing who you are, no comment can be attributed to you.
+            return refs.map((ref) => ({ id: artifactId(ref), reply: "unknown" }));
+        }
+        return pool(refs, opts.parallel, async (ref) => {
+            try {
+                return { id: artifactId(ref), reply: classifyReply(await fetchConversation(ref), login) };
+            }
+            catch {
+                return { id: artifactId(ref), reply: "unknown" };
+            }
+        });
+    }
     async function reviewAll(refs) {
         let reviewed = 0;
         let skipped = 0;
@@ -222,13 +251,19 @@ export function startDaemon(opts) {
             // Recomputed too, so a trust rule added mid-run shows up in the strip.
             status.trustedRuns = autoReview && opts.trust !== false && config.trust.length > 0;
             if (!knobs.poll) {
-                // Deliberately off is not an outage — don't leave a stale error up.
+                // Deliberately off is not an outage — don't leave a stale error up, or
+                // a list of PRs we are no longer checking are still awaiting you.
                 status.lastPollError = null;
+                status.awaiting = [];
                 status.lastSummary = "polling off (settings) — the queue only shows what you review by hand";
                 return;
             }
             const refs = await discover();
             status.lastPollError = null;
+            // The same refs behind lastSummary's count, so the number the strip shows
+            // and the rows the cockpit can name always come from one answer.
+            // A failed poll leaves the last good list up; lastPollError says so.
+            status.awaiting = await classifyAll(refs);
             const { discovered } = await syncQueue(refs);
             if (autoReview) {
                 const { reviewed, skipped, failed } = await reviewAll(refs);

package/dist/server/index.js

@@ -6,7 +6,7 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { randomUUID } from "node:crypto";
-import { ArtifactStatusSchema, VerdictSchema, artifactKey } from "../core/artifact.js";
+import { ArtifactStatusSchema, SeveritySchema, VerdictSchema, artifactKey } from "../core/artifact.js";
 import { toMarkdown } from "../core/export.js";
 import { fetchPrDiff, fetchPrInfo, submitReview } from "../core/gh.js";
 import { z } from "zod";
@@ -194,6 +194,9 @@ export async function buildApp(opts) {
                 ? {
                     ...cm,
                     ...(body.body !== undefined ? { body: String(body.body) } : {}),
+                    ...(body.severity !== undefined
+                        ? { severity: SeveritySchema.nullable().parse(body.severity) }
+                        : {}),
                     ...(body.status !== undefined
                         ? { status: body.status }
                         : {}),
@@ -219,6 +222,7 @@ export async function buildApp(opts) {
                     line: body.line != null ? Number(body.line) : null,
                     body: String(body.body ?? ""),
                     chapterId: body.chapterId ?? null,
+                    severity: SeveritySchema.nullable().parse(body.severity ?? null),
                     origin: "user",
                     status: "draft",
                     editedByUser: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fullstackhouse/cerber",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "AI code-review cockpit: Claude reviews your PRs into local artifacts; nothing reaches GitHub until you say so.",
   "license": "MIT",
   "author": "Full Stack House (https://fullstack.house)",