@fullstackhouse/cerber 0.12.1 → 0.13.0

package/README.md

@@ -78,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/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/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.1",
+  "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)",