@kevinrabun/judges-cli 3.124.0

package/dist/commands/review-access-log.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Review-access-log — View and manage review access logs.
+ */
+export declare function runReviewAccessLog(argv: string[]): void;

package/dist/commands/review-access-log.js

@@ -0,0 +1,65 @@
+/**
+ * Review-access-log — View and manage review access logs.
+ */
+import { readFileSync, existsSync } from "fs";
+// ─── CLI ────────────────────────────────────────────────────────────────────
+export function runReviewAccessLog(argv) {
+    const storeIdx = argv.indexOf("--store");
+    const storePath = storeIdx >= 0 ? argv[storeIdx + 1] : ".judges-access-log.json";
+    const formatIdx = argv.indexOf("--format");
+    const format = formatIdx >= 0 ? argv[formatIdx + 1] : "table";
+    const userFilter = argv.indexOf("--user");
+    const filterUser = userFilter >= 0 ? argv[userFilter + 1] : "";
+    const lastN = argv.indexOf("--last");
+    const lastCount = lastN >= 0 ? parseInt(argv[lastN + 1], 10) : 0;
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`
+judges review-access-log — View review access logs
+
+Usage:
+  judges review-access-log [--store <path>] [--user <name>] [--last <n>] [--format table|json]
+
+Options:
+  --store <path>     Access log file (default: .judges-access-log.json)
+  --user <name>      Filter by user
+  --last <n>         Show only the last N entries
+  --format <fmt>     Output format: table (default), json
+  --help, -h         Show this help
+`);
+        return;
+    }
+    if (!existsSync(storePath)) {
+        console.log(`No access log found at: ${storePath}`);
+        console.log("Access logs are generated when permission features are enabled.");
+        return;
+    }
+    const store = JSON.parse(readFileSync(storePath, "utf-8"));
+    let entries = store.entries;
+    if (filterUser) {
+        entries = entries.filter((e) => e.user === filterUser);
+    }
+    if (lastCount > 0) {
+        entries = entries.slice(-lastCount);
+    }
+    if (format === "json") {
+        console.log(JSON.stringify(entries, null, 2));
+        return;
+    }
+    console.log(`\nAccess Log (${entries.length} entries)`);
+    console.log("═".repeat(80));
+    if (entries.length === 0) {
+        console.log("  No access log entries to display.");
+    }
+    else {
+        console.log(`  ${"User".padEnd(18)} ${"Action".padEnd(15)} ${"Resource".padEnd(20)} ${"Result".padEnd(10)} Date`);
+        console.log("  " + "─".repeat(75));
+        for (const e of entries) {
+            const res = e.resource.length > 18 ? e.resource.slice(0, 15) + "..." : e.resource;
+            console.log(`  ${e.user.padEnd(18)} ${e.action.padEnd(15)} ${res.padEnd(20)} ${e.result.padEnd(10)} ${e.timestamp.slice(0, 10)}`);
+        }
+    }
+    const allowed = entries.filter((e) => e.result === "allowed").length;
+    const denied = entries.filter((e) => e.result === "denied").length;
+    console.log(`\n  Allowed: ${allowed} | Denied: ${denied}`);
+    console.log("═".repeat(80));
+}

package/dist/commands/review-action-item-gen.d.ts

@@ -0,0 +1 @@
+export declare function runReviewActionItemGen(argv: string[]): void;

package/dist/commands/review-action-item-gen.js

@@ -0,0 +1,72 @@
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+function generateActionItems(findings) {
+    const items = [];
+    for (let i = 0; i < findings.length; i++) {
+        const f = findings[i];
+        items.push({
+            id: i + 1,
+            ruleId: f.ruleId,
+            title: f.title,
+            severity: f.severity,
+            action: f.recommendation,
+            status: "open",
+        });
+    }
+    // Sort by severity priority
+    const sevOrder = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
+    items.sort((a, b) => (sevOrder[a.severity] ?? 5) - (sevOrder[b.severity] ?? 5));
+    // Re-number after sort
+    for (let i = 0; i < items.length; i++) {
+        items[i].id = i + 1;
+    }
+    return items;
+}
+export function runReviewActionItemGen(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`Usage: judges review-action-item-gen [options]
+
+Generate action items from findings.
+
+Options:
+  --report <path>      Path to verdict JSON file
+  --format <fmt>       Output format: table (default), json, or markdown
+  -h, --help           Show this help message`);
+        return;
+    }
+    const formatIdx = argv.indexOf("--format");
+    const format = formatIdx !== -1 && argv[formatIdx + 1] ? argv[formatIdx + 1] : "table";
+    const reportIdx = argv.indexOf("--report");
+    const reportPath = reportIdx !== -1 && argv[reportIdx + 1]
+        ? join(process.cwd(), argv[reportIdx + 1])
+        : join(process.cwd(), ".judges", "last-verdict.json");
+    if (!existsSync(reportPath)) {
+        console.log(`No report found at: ${reportPath}`);
+        return;
+    }
+    const data = JSON.parse(readFileSync(reportPath, "utf-8"));
+    const findings = data.findings ?? [];
+    if (findings.length === 0) {
+        console.log("No findings — no action items needed.");
+        return;
+    }
+    const items = generateActionItems(findings);
+    if (format === "json") {
+        console.log(JSON.stringify(items, null, 2));
+        return;
+    }
+    if (format === "markdown") {
+        console.log("# Action Items\n");
+        for (const item of items) {
+            console.log(`- [ ] **${item.ruleId}** (${item.severity}): ${item.title}`);
+            console.log(`  - ${item.action}`);
+        }
+        return;
+    }
+    console.log(`\n=== Action Items (${items.length}) ===\n`);
+    for (const item of items) {
+        console.log(`#${item.id} [${item.severity.toUpperCase()}] ${item.ruleId}: ${item.title}`);
+        console.log(`   Action: ${item.action}`);
+        console.log();
+    }
+}

package/dist/commands/review-adoption-metrics.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Review-adoption-metrics — Track Judges adoption metrics across a team/org.
+ */
+export declare function runReviewAdoptionMetrics(argv: string[]): void;

package/dist/commands/review-adoption-metrics.js

@@ -0,0 +1,95 @@
+/**
+ * Review-adoption-metrics — Track Judges adoption metrics across a team/org.
+ */
+import { readFileSync, writeFileSync, existsSync } from "fs";
+// ─── CLI ────────────────────────────────────────────────────────────────────
+export function runReviewAdoptionMetrics(argv) {
+    const storeIdx = argv.indexOf("--store");
+    const addIdx = argv.indexOf("--add");
+    const reviewsIdx = argv.indexOf("--reviews");
+    const usersIdx = argv.indexOf("--users");
+    const fixedIdx = argv.indexOf("--fixed");
+    const scoreIdx = argv.indexOf("--score");
+    const passIdx = argv.indexOf("--pass-rate");
+    const formatIdx = argv.indexOf("--format");
+    const storePath = storeIdx >= 0 ? argv[storeIdx + 1] : ".judges-adoption.json";
+    const format = formatIdx >= 0 ? argv[formatIdx + 1] : "table";
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`
+judges review-adoption-metrics — Track adoption metrics
+
+Usage:
+  judges review-adoption-metrics [--store <path>] [--add <period>]
+                                 [--reviews <n>] [--users <n>] [--fixed <n>]
+                                 [--score <n>] [--pass-rate <n>]
+                                 [--format table|json]
+
+Options:
+  --store <path>     Metrics store file (default: .judges-adoption.json)
+  --add <period>     Add entry for period (e.g., 2026-W12, 2026-03)
+  --reviews <n>      Number of reviews run
+  --users <n>        Number of unique users
+  --fixed <n>        Number of findings fixed
+  --score <n>        Average review score
+  --pass-rate <n>    Pass rate percentage
+  --format <fmt>     Output format: table (default), json
+  --help, -h         Show this help
+`);
+        return;
+    }
+    let store;
+    if (existsSync(storePath)) {
+        store = JSON.parse(readFileSync(storePath, "utf-8"));
+    }
+    else {
+        store = { entries: [], lastUpdated: new Date().toISOString().split("T")[0] };
+    }
+    // Add new entry
+    if (addIdx >= 0) {
+        const period = argv[addIdx + 1];
+        const entry = {
+            period,
+            reviewsRun: reviewsIdx >= 0 ? parseInt(argv[reviewsIdx + 1], 10) : 0,
+            uniqueUsers: usersIdx >= 0 ? parseInt(argv[usersIdx + 1], 10) : 0,
+            findingsFixed: fixedIdx >= 0 ? parseInt(argv[fixedIdx + 1], 10) : 0,
+            avgScore: scoreIdx >= 0 ? parseFloat(argv[scoreIdx + 1]) : 0,
+            passRate: passIdx >= 0 ? parseFloat(argv[passIdx + 1]) : 0,
+        };
+        const existingIdx = store.entries.findIndex((e) => e.period === period);
+        if (existingIdx >= 0) {
+            store.entries[existingIdx] = entry;
+        }
+        else {
+            store.entries.push(entry);
+        }
+        store.lastUpdated = new Date().toISOString().split("T")[0];
+        writeFileSync(storePath, JSON.stringify(store, null, 2));
+        console.log(`Added metrics for period: ${period}`);
+        return;
+    }
+    // Display
+    if (format === "json") {
+        console.log(JSON.stringify(store, null, 2));
+        return;
+    }
+    console.log(`\nAdoption Metrics`);
+    console.log("═".repeat(75));
+    if (store.entries.length === 0) {
+        console.log("  No adoption data recorded. Use --add <period> to add entries.");
+        console.log("═".repeat(75));
+        return;
+    }
+    console.log(`  ${"Period".padEnd(15)} ${"Reviews".padEnd(10)} ${"Users".padEnd(8)} ${"Fixed".padEnd(8)} ${"Score".padEnd(8)} Pass%`);
+    console.log("  " + "─".repeat(60));
+    for (const e of store.entries) {
+        console.log(`  ${e.period.padEnd(15)} ${String(e.reviewsRun).padEnd(10)} ${String(e.uniqueUsers).padEnd(8)} ${String(e.findingsFixed).padEnd(8)} ${String(e.avgScore).padEnd(8)} ${e.passRate}%`);
+    }
+    // Trend
+    if (store.entries.length >= 2) {
+        const first = store.entries[0];
+        const last = store.entries[store.entries.length - 1];
+        const reviewGrowth = first.reviewsRun > 0 ? Math.round(((last.reviewsRun - first.reviewsRun) / first.reviewsRun) * 100) : 0;
+        console.log(`\n  Trend: ${reviewGrowth >= 0 ? "+" : ""}${reviewGrowth}% review volume growth`);
+    }
+    console.log("═".repeat(75));
+}

package/dist/commands/review-adoption-score.d.ts

@@ -0,0 +1 @@
+export declare function runReviewAdoptionScore(argv: string[]): void;

package/dist/commands/review-adoption-score.js

@@ -0,0 +1,181 @@
+import { readFileSync, existsSync, readdirSync } from "fs";
+import { join } from "path";
+function runChecks(projectDir) {
+    const checks = [];
+    // 1) Configuration exists
+    const configPaths = [".judgesrc", ".judgesrc.json", "judges.config.json"];
+    const hasConfig = configPaths.some((p) => existsSync(join(projectDir, p)));
+    checks.push({
+        category: "Configuration",
+        check: "Config file present",
+        passed: hasConfig,
+        points: hasConfig ? 15 : 0,
+        maxPoints: 15,
+        detail: hasConfig ? "Configuration file found" : "No .judgesrc or judges.config.json found",
+    });
+    // 2) CI integration
+    const ciPaths = [".github/workflows", ".gitlab-ci.yml", "Jenkinsfile", ".circleci"];
+    const hasCI = ciPaths.some((p) => existsSync(join(projectDir, p)));
+    checks.push({
+        category: "CI Integration",
+        check: "CI pipeline detected",
+        passed: hasCI,
+        points: hasCI ? 15 : 0,
+        maxPoints: 15,
+        detail: hasCI ? "CI pipeline configuration found" : "No CI pipeline detected",
+    });
+    // 3) Review history
+    const historyDir = join(projectDir, ".judges", "history");
+    let historyCount = 0;
+    if (existsSync(historyDir)) {
+        const files = readdirSync(historyDir);
+        historyCount = files.filter((f) => typeof f === "string" && f.endsWith(".json")).length;
+    }
+    const historyScore = Math.min(historyCount * 2, 15);
+    checks.push({
+        category: "Usage",
+        check: "Review history depth",
+        passed: historyCount >= 3,
+        points: historyScore,
+        maxPoints: 15,
+        detail: `${historyCount} historical reviews found`,
+    });
+    // 4) Last verdict exists
+    const lastVerdict = join(projectDir, ".judges", "last-verdict.json");
+    const hasLastVerdict = existsSync(lastVerdict);
+    checks.push({
+        category: "Usage",
+        check: "Recent review available",
+        passed: hasLastVerdict,
+        points: hasLastVerdict ? 10 : 0,
+        maxPoints: 10,
+        detail: hasLastVerdict ? "Last verdict file present" : "No recent review verdict found",
+    });
+    // 5) Baseline configured
+    const baselinePath = join(projectDir, ".judges", "baseline.json");
+    const hasBaseline = existsSync(baselinePath);
+    checks.push({
+        category: "Configuration",
+        check: "Baseline configured",
+        passed: hasBaseline,
+        points: hasBaseline ? 10 : 0,
+        maxPoints: 10,
+        detail: hasBaseline ? "Baseline file found" : "No baseline — run `judges baseline` to create one",
+    });
+    // 6) Custom rules or overrides
+    let hasOverrides = false;
+    if (hasConfig) {
+        try {
+            const configPath = configPaths.find((p) => existsSync(join(projectDir, p)));
+            if (configPath) {
+                const raw = readFileSync(join(projectDir, configPath), "utf-8");
+                const cfg = JSON.parse(raw);
+                hasOverrides = Boolean(cfg["ruleOverrides"]) || Boolean(cfg["disabledRules"]);
+            }
+        }
+        catch {
+            // Ignore parse errors
+        }
+    }
+    checks.push({
+        category: "Customization",
+        check: "Custom rules/overrides",
+        passed: hasOverrides,
+        points: hasOverrides ? 10 : 0,
+        maxPoints: 10,
+        detail: hasOverrides ? "Rule customization detected" : "No rule overrides configured yet",
+    });
+    // 7) Quality trend (improving scores)
+    let trendPositive = false;
+    if (historyCount >= 2 && existsSync(historyDir)) {
+        try {
+            const files = readdirSync(historyDir)
+                .filter((f) => typeof f === "string" && f.endsWith(".json"))
+                .sort();
+            const recent = files.slice(-3);
+            const scores = [];
+            for (const file of recent) {
+                const data = JSON.parse(readFileSync(join(historyDir, file), "utf-8"));
+                scores.push(data.overallScore ?? 0);
+            }
+            trendPositive = scores.length >= 2 && scores[scores.length - 1] >= scores[0];
+        }
+        catch {
+            // Skip
+        }
+    }
+    checks.push({
+        category: "Quality",
+        check: "Score trend improving",
+        passed: trendPositive,
+        points: trendPositive ? 10 : 0,
+        maxPoints: 10,
+        detail: trendPositive ? "Quality scores are improving" : "Not enough data or scores declining",
+    });
+    // 8) Git hooks
+    const hookPaths = [".husky", ".git/hooks/pre-commit"];
+    const hasHooks = hookPaths.some((p) => existsSync(join(projectDir, p)));
+    checks.push({
+        category: "Integration",
+        check: "Git hooks installed",
+        passed: hasHooks,
+        points: hasHooks ? 10 : 0,
+        maxPoints: 10,
+        detail: hasHooks ? "Git hooks detected" : "No git hooks — run `judges hook-install` to set up",
+    });
+    // 9) Documentation
+    const docPaths = ["docs/judges.md", "docs/code-review.md", ".judges/README.md"];
+    const hasDocs = docPaths.some((p) => existsSync(join(projectDir, p)));
+    checks.push({
+        category: "Documentation",
+        check: "Review documentation",
+        passed: hasDocs,
+        points: hasDocs ? 5 : 0,
+        maxPoints: 5,
+        detail: hasDocs ? "Review documentation found" : "Consider adding review docs for your team",
+    });
+    return checks;
+}
+export function runReviewAdoptionScore(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`Usage: judges review-adoption-score [options]
+
+Calculate adoption readiness score for the project.
+
+Options:
+  --dir <path>         Project directory (default: current)
+  --format <fmt>       Output format: table (default) or json
+  -h, --help           Show this help message`);
+        return;
+    }
+    const formatIdx = argv.indexOf("--format");
+    const format = formatIdx !== -1 && argv[formatIdx + 1] ? argv[formatIdx + 1] : "table";
+    const dirIdx = argv.indexOf("--dir");
+    const projectDir = dirIdx !== -1 && argv[dirIdx + 1] ? join(process.cwd(), argv[dirIdx + 1]) : process.cwd();
+    const checks = runChecks(projectDir);
+    const totalPoints = checks.reduce((s, c) => s + c.points, 0);
+    const maxPoints = checks.reduce((s, c) => s + c.maxPoints, 0);
+    const scorePercent = maxPoints > 0 ? Math.round((totalPoints / maxPoints) * 100) : 0;
+    if (format === "json") {
+        console.log(JSON.stringify({ score: scorePercent, totalPoints, maxPoints, checks }, null, 2));
+        return;
+    }
+    let grade;
+    if (scorePercent >= 90)
+        grade = "A — Fully Adopted";
+    else if (scorePercent >= 70)
+        grade = "B — Well Integrated";
+    else if (scorePercent >= 50)
+        grade = "C — Getting Started";
+    else if (scorePercent >= 30)
+        grade = "D — Early Stage";
+    else
+        grade = "F — Not Yet Adopted";
+    console.log(`\n=== Adoption Score: ${scorePercent}% (${grade}) ===\n`);
+    for (const c of checks) {
+        const icon = c.passed ? "✓" : "✗";
+        console.log(`  ${icon} [${c.points}/${c.maxPoints}] ${c.check}`);
+        console.log(`           ${c.detail}`);
+    }
+    console.log(`\n  Total: ${totalPoints}/${maxPoints} points`);
+}

package/dist/commands/review-ai-feedback-loop.d.ts

@@ -0,0 +1 @@
+export declare function runReviewAiFeedbackLoop(argv: string[]): void;

package/dist/commands/review-ai-feedback-loop.js

@@ -0,0 +1,116 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { join } from "path";
+function computeStats(entries) {
+    const agree = entries.filter((e) => e.feedback === "agree").length;
+    const disagree = entries.filter((e) => e.feedback === "disagree").length;
+    const partial = entries.filter((e) => e.feedback === "partial").length;
+    const disagreedRules = new Map();
+    for (const e of entries) {
+        if (e.feedback === "disagree") {
+            disagreedRules.set(e.ruleId, (disagreedRules.get(e.ruleId) ?? 0) + 1);
+        }
+    }
+    const topDisagreed = [...disagreedRules.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 10)
+        .map(([ruleId, count]) => ({ ruleId, count }));
+    return {
+        total: entries.length,
+        agree,
+        disagree,
+        partial,
+        agreementRate: entries.length > 0 ? agree / entries.length : 0,
+        topDisagreed,
+    };
+}
+export function runReviewAiFeedbackLoop(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`Usage: judges review-ai-feedback-loop [options]
+
+Capture and analyze reviewer feedback on AI findings.
+
+Options:
+  --add <ruleId>       Add feedback for a specific rule
+  --feedback <type>    Feedback type: agree, disagree, partial
+  --reason <text>      Reason for feedback
+  --report <path>      Path to verdict JSON to review
+  --stats              Show feedback statistics
+  --format <fmt>       Output format: table (default) or json
+  -h, --help           Show this help message`);
+        return;
+    }
+    const formatIdx = argv.indexOf("--format");
+    const format = formatIdx !== -1 && argv[formatIdx + 1] ? argv[formatIdx + 1] : "table";
+    const feedbackDir = join(process.cwd(), ".judges", "feedback");
+    if (!existsSync(feedbackDir)) {
+        mkdirSync(feedbackDir, { recursive: true });
+    }
+    const feedbackFile = join(feedbackDir, "feedback-log.json");
+    let entries = [];
+    if (existsSync(feedbackFile)) {
+        entries = JSON.parse(readFileSync(feedbackFile, "utf-8"));
+    }
+    if (argv.includes("--stats")) {
+        const stats = computeStats(entries);
+        if (format === "json") {
+            console.log(JSON.stringify(stats, null, 2));
+            return;
+        }
+        console.log("\n=== AI Feedback Statistics ===\n");
+        console.log(`Total feedback entries: ${stats.total}`);
+        console.log(`  Agree: ${stats.agree} (${(stats.agreementRate * 100).toFixed(1)}%)`);
+        console.log(`  Disagree: ${stats.disagree}`);
+        console.log(`  Partial: ${stats.partial}`);
+        if (stats.topDisagreed.length > 0) {
+            console.log("\nTop Disagreed Rules:");
+            for (const rule of stats.topDisagreed) {
+                console.log(`  ${rule.ruleId}: ${rule.count} disagreements`);
+            }
+        }
+        return;
+    }
+    const addIdx = argv.indexOf("--add");
+    if (addIdx !== -1 && argv[addIdx + 1]) {
+        const ruleId = argv[addIdx + 1];
+        const fbIdx = argv.indexOf("--feedback");
+        const feedbackType = fbIdx !== -1 && argv[fbIdx + 1] ? argv[fbIdx + 1] : "agree";
+        const reasonIdx = argv.indexOf("--reason");
+        const reason = reasonIdx !== -1 && argv[reasonIdx + 1] ? argv[reasonIdx + 1] : "";
+        if (feedbackType !== "agree" && feedbackType !== "disagree" && feedbackType !== "partial") {
+            console.error("Invalid feedback type. Use: agree, disagree, or partial");
+            process.exitCode = 1;
+            return;
+        }
+        const entry = {
+            ruleId,
+            verdict: "reviewed",
+            feedback: feedbackType,
+            reason,
+            timestamp: new Date().toISOString(),
+        };
+        entries.push(entry);
+        writeFileSync(feedbackFile, JSON.stringify(entries, null, 2));
+        console.log(`Feedback recorded for ${ruleId}: ${feedbackType}`);
+        return;
+    }
+    const reportIdx = argv.indexOf("--report");
+    if (reportIdx !== -1 && argv[reportIdx + 1]) {
+        const reportPath = join(process.cwd(), argv[reportIdx + 1]);
+        if (!existsSync(reportPath)) {
+            console.error(`Report not found: ${reportPath}`);
+            process.exitCode = 1;
+            return;
+        }
+        const data = JSON.parse(readFileSync(reportPath, "utf-8"));
+        const findings = data.findings ?? [];
+        console.log(`\nFound ${findings.length} findings to review.`);
+        console.log("Use --add <ruleId> --feedback <type> to record feedback.\n");
+        for (const f of findings) {
+            const existingFb = entries.find((e) => e.ruleId === f.ruleId);
+            const fbStatus = existingFb !== undefined ? ` [${existingFb.feedback}]` : " [no feedback]";
+            console.log(`  ${f.ruleId} (${f.severity})${fbStatus}: ${f.title}`);
+        }
+        return;
+    }
+    console.log("Use --stats, --add, or --report to interact with the feedback system.");
+}

package/dist/commands/review-annotate.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Review-annotate — Generate GitHub-compatible PR annotations from findings.
+ */
+export declare function runReviewAnnotate(argv: string[]): void;

package/dist/commands/review-annotate.js

@@ -0,0 +1,122 @@
+/**
+ * Review-annotate — Generate GitHub-compatible PR annotations from findings.
+ */
+import { readFileSync } from "fs";
+// ─── Severity mapping ──────────────────────────────────────────────────────
+function severityToLevel(severity) {
+    switch (severity) {
+        case "critical":
+        case "high":
+            return "failure";
+        case "medium":
+            return "warning";
+        default:
+            return "notice";
+    }
+}
+// ─── Annotation generation ─────────────────────────────────────────────────
+function findingToAnnotation(finding, defaultPath) {
+    const line = finding.lineNumbers?.[0] || 1;
+    return {
+        path: defaultPath,
+        start_line: line,
+        end_line: line,
+        annotation_level: severityToLevel(finding.severity || "low"),
+        title: `[${finding.severity || "low"}] ${finding.ruleId || "unknown"}`,
+        message: `${finding.title}\n\n${finding.description || ""}\n\nRecommendation: ${finding.recommendation || "Review this finding."}`.trim(),
+    };
+}
+// ─── Output formatters ─────────────────────────────────────────────────────
+function formatGitHubActions(annotations) {
+    return annotations
+        .map((a) => {
+        const level = a.annotation_level === "failure" ? "error" : a.annotation_level;
+        const msg = a.message.replace(/\n/g, "%0A");
+        return `::${level} file=${a.path},line=${a.start_line},title=${a.title}::${msg}`;
+    })
+        .join("\n");
+}
+function formatCheckRun(annotations) {
+    return JSON.stringify({
+        name: "Judges Panel Review",
+        conclusion: annotations.some((a) => a.annotation_level === "failure") ? "failure" : "success",
+        output: {
+            title: "Judges Panel Review",
+            summary: `${annotations.length} annotation(s) from Judges Panel review`,
+            annotations: annotations.slice(0, 50),
+        },
+    }, null, 2);
+}
+// ─── CLI ────────────────────────────────────────────────────────────────────
+export function runReviewAnnotate(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`
+judges review-annotate — Generate PR annotations from findings
+
+Usage:
+  judges review-annotate --input verdict.json --file src/app.ts
+  judges review-annotate --input verdict.json --style github-actions
+  judges review-annotate --input verdict.json --style check-run
+  judges review-annotate --format json
+
+Options:
+  --input <file>       TribunalVerdict JSON file (required)
+  --file <path>        Source file path for annotations (default: "unknown")
+  --style <type>       Output style: github-actions, check-run, json (default: github-actions)
+  --min-severity <s>   Minimum severity to annotate (default: low)
+  --limit <n>          Maximum annotations (default: 50, GitHub limit)
+  --format json        Raw JSON annotations
+  --help, -h           Show this help
+
+Styles:
+  github-actions       ::error/::warning/::notice workflow commands
+  check-run            Check Run API payload format
+  json                 Raw annotation JSON array
+
+Generates annotations compatible with GitHub Actions workflow commands
+or Check Run API payloads.
+`);
+        return;
+    }
+    const inputPath = argv.find((_a, i) => argv[i - 1] === "--input");
+    const filePath = argv.find((_a, i) => argv[i - 1] === "--file") || "unknown";
+    const style = argv.find((_a, i) => argv[i - 1] === "--style") || "github-actions";
+    const minSev = argv.find((_a, i) => argv[i - 1] === "--min-severity") || "low";
+    const limitStr = argv.find((_a, i) => argv[i - 1] === "--limit");
+    const limit = limitStr ? parseInt(limitStr, 10) : 50;
+    const format = argv.find((_a, i) => argv[i - 1] === "--format") || "text";
+    if (!inputPath) {
+        console.error("Error: --input is required. Provide a verdict JSON file.");
+        process.exitCode = 1;
+        return;
+    }
+    let verdict;
+    try {
+        verdict = JSON.parse(readFileSync(inputPath, "utf-8"));
+    }
+    catch {
+        console.error(`Error: Cannot read or parse ${inputPath}`);
+        process.exitCode = 1;
+        return;
+    }
+    const sevOrder = { critical: 0, high: 1, medium: 2, low: 3 };
+    const minLevel = sevOrder[minSev] ?? 3;
+    let findings = (verdict.findings || []).filter((f) => (sevOrder[f.severity || "low"] ?? 3) <= minLevel);
+    findings = findings.slice(0, limit);
+    const annotations = findings.map((f) => findingToAnnotation(f, filePath));
+    if (format === "json") {
+        console.log(JSON.stringify(annotations, null, 2));
+        return;
+    }
+    switch (style) {
+        case "check-run":
+            console.log(formatCheckRun(annotations));
+            break;
+        case "json":
+            console.log(JSON.stringify(annotations, null, 2));
+            break;
+        default:
+            console.log(formatGitHubActions(annotations));
+            break;
+    }
+}