@mcoda/core 0.1.7 → 0.1.9

package/dist/services/review/CodeReviewService.js

@@ -2,7 +2,7 @@ import path from "node:path";
 import fs from "node:fs/promises";
 import { AgentService } from "@mcoda/agents";
 import { DocdexClient, VcsClient } from "@mcoda/integrations";
-import { GlobalRepository, WorkspaceRepository } from "@mcoda/db";
+import { GlobalRepository, WorkspaceRepository, } from "@mcoda/db";
 import { PathHelper } from "@mcoda/shared";
 import { JobService } from "../jobs/JobService.js";
 import { TaskSelectionService } from "../execution/TaskSelectionService.js";
@@ -11,9 +11,20 @@ import { BacklogService } from "../backlog/BacklogService.js";
 import yaml from "yaml";
 import { createTaskKeyGenerator } from "../planning/KeyHelpers.js";
 import { RoutingService } from "../agents/RoutingService.js";
+import { AgentRatingService } from "../agents/AgentRatingService.js";
+import { loadProjectGuidance } from "../shared/ProjectGuidance.js";
+import { createTaskCommentSlug, formatTaskCommentBody } from "../tasks/TaskCommentFormatter.js";
 const DEFAULT_BASE_BRANCH = "mcoda-dev";
 const REVIEW_DIR = (workspaceRoot, jobId) => path.join(workspaceRoot, ".mcoda", "jobs", jobId, "review");
 const STATE_PATH = (workspaceRoot, jobId) => path.join(REVIEW_DIR(workspaceRoot, jobId), "state.json");
+const REVIEW_PROMPT_LIMITS = {
+    diff: 12000,
+    history: 3000,
+    docContext: 4000,
+    openapi: 8000,
+    checklist: 3000,
+};
+const DOCDEX_TIMEOUT_MS = 8000;
 const DEFAULT_CODE_REVIEW_PROMPT = [
     "You are the code-review agent. Before reviewing, query docdex with the task key and feature keywords (MCP `docdex_search` limit 4–8 or CLI `docdexd query --repo <repo> --query \"<term>\" --limit 6 --snippets=false`). If results look stale, reindex (`docdex_index` or `docdexd index --repo <repo>`) then re-run. Fetch snippets via `docdex_open` or `/snippet/:doc_id?text_only=true` only for specific hits.",
     "Use docdex snippets to verify contracts (data shapes, offline scope, accessibility/perf guardrails, acceptance criteria). Call out mismatches, missing tests, and undocumented changes.",
@@ -21,22 +32,53 @@ const DEFAULT_CODE_REVIEW_PROMPT = [
 const DEFAULT_JOB_PROMPT = "You are an mcoda agent that follows workspace runbooks and responds with actionable, concise output.";
 const DEFAULT_CHARACTER_PROMPT = "Write clearly, avoid hallucinations, cite assumptions, and prioritize risk mitigation for the user.";
 const estimateTokens = (text) => Math.max(1, Math.ceil((text ?? "").length / 4));
+const extractJsonSlice = (candidate) => {
+    const start = candidate.indexOf("{");
+    const end = candidate.lastIndexOf("}");
+    if (start === -1 || end === -1 || end <= start)
+        return undefined;
+    return candidate.slice(start, end + 1);
+};
+const sanitizeJsonCandidate = (value) => {
+    const cleanedLines = value
+        .split(/\r?\n/)
+        .filter((line) => {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return true;
+        if (trimmed.startsWith("{") ||
+            trimmed.startsWith("}") ||
+            trimmed.startsWith("[") ||
+            trimmed.startsWith("]") ||
+            trimmed.startsWith("\"")) {
+            return true;
+        }
+        return false;
+    })
+        .join("\n");
+    return cleanedLines.replace(/,\s*([}\]])/g, "$1");
+};
 const parseJsonOutput = (raw) => {
     const trimmed = raw.trim();
     const fenced = trimmed.replace(/^```(?:json)?/i, "").replace(/```$/, "").trim();
     const candidates = [trimmed, fenced];
     for (const candidate of candidates) {
-        const start = candidate.indexOf("{");
-        const end = candidate.lastIndexOf("}");
-        if (start === -1 || end === -1 || end <= start)
+        const slice = extractJsonSlice(candidate);
+        if (!slice)
             continue;
-        const slice = candidate.slice(start, end + 1);
         try {
             const parsed = JSON.parse(slice);
             return { ...parsed, raw: raw };
         }
         catch {
-            /* ignore */
+            const sanitized = sanitizeJsonCandidate(slice);
+            try {
+                const parsed = JSON.parse(sanitized);
+                return { ...parsed, raw: raw };
+            }
+            catch {
+                /* ignore */
+            }
         }
     }
     return undefined;
@@ -51,6 +93,30 @@ const summarizeComments = (comments) => {
     })
         .join("\n");
 };
+const truncateSection = (label, text, limit) => {
+    if (!text)
+        return text;
+    if (text.length <= limit)
+        return text;
+    const trimmed = text.slice(0, limit);
+    const remaining = text.length - limit;
+    return `${trimmed}\n...[truncated ${remaining} chars from ${label}]`;
+};
+const withTimeout = async (promise, ms, label) => {
+    let timeoutId;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => {
+            reject(new Error(`${label} timed out after ${ms}ms`));
+        }, ms);
+    });
+    try {
+        return await Promise.race([promise, timeoutPromise]);
+    }
+    finally {
+        if (timeoutId)
+            clearTimeout(timeoutId);
+    }
+};
 const JSON_CONTRACT = `{
   "decision": "approve | changes_requested | block | info_only",
   "summary": "short textual summary",
@@ -64,28 +130,116 @@ const JSON_CONTRACT = `{
       "suggestedFix": "Optional suggested change"
     }
   ],
-  "testRecommendations": ["Optional test or QA recommendations per task"]
+  "testRecommendations": ["Optional test or QA recommendations per task"],
+  "resolvedSlugs": ["Optional list of comment slugs that are confirmed fixed"],
+  "unresolvedSlugs": ["Optional list of comment slugs still open or reintroduced"]
 }`;
 const normalizeSingleLine = (value, fallback) => {
     const trimmed = (value ?? "").replace(/\s+/g, " ").trim();
     return trimmed || fallback;
 };
+const normalizeSlugList = (input) => {
+    if (!Array.isArray(input))
+        return [];
+    const cleaned = new Set();
+    for (const slug of input) {
+        if (typeof slug !== "string")
+            continue;
+        const trimmed = slug.trim();
+        if (trimmed)
+            cleaned.add(trimmed);
+    }
+    return Array.from(cleaned);
+};
+const normalizePath = (value) => value
+    .replace(/\\/g, "/")
+    .replace(/^\.\//, "")
+    .replace(/^\/+/, "");
+const parseCommentBody = (body) => {
+    const trimmed = (body ?? "").trim();
+    if (!trimmed)
+        return { message: "(no details provided)" };
+    const lines = trimmed.split(/\r?\n/);
+    const normalize = (value) => value.trim().toLowerCase();
+    const messageIndex = lines.findIndex((line) => normalize(line) === "message:");
+    const suggestedIndex = lines.findIndex((line) => {
+        const normalized = normalize(line);
+        return normalized === "suggested_fix:" || normalized === "suggested fix:";
+    });
+    if (messageIndex >= 0) {
+        const messageLines = lines.slice(messageIndex + 1, suggestedIndex >= 0 ? suggestedIndex : undefined);
+        const message = messageLines.join("\n").trim();
+        const suggestedLines = suggestedIndex >= 0 ? lines.slice(suggestedIndex + 1) : [];
+        const suggestedFix = suggestedLines.join("\n").trim();
+        return { message: message || trimmed, suggestedFix: suggestedFix || undefined };
+    }
+    if (suggestedIndex >= 0) {
+        const message = lines.slice(0, suggestedIndex).join("\n").trim() || trimmed;
+        const inlineFix = lines[suggestedIndex]?.split(/suggested fix:/i)[1]?.trim();
+        const suggestedTail = lines.slice(suggestedIndex + 1).join("\n").trim();
+        const suggestedFix = inlineFix || suggestedTail || undefined;
+        return { message, suggestedFix };
+    }
+    return { message: trimmed };
+};
+const buildCommentBacklog = (comments) => {
+    if (!comments.length)
+        return "";
+    const seen = new Set();
+    const lines = [];
+    const toSingleLine = (value) => value.replace(/\s+/g, " ").trim();
+    for (const comment of comments) {
+        const slug = comment.slug?.trim() || undefined;
+        const details = parseCommentBody(comment.body);
+        const key = slug ??
+            `${comment.sourceCommand}:${comment.file ?? ""}:${comment.line ?? ""}:${details.message || comment.body}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const location = comment.file
+            ? `${comment.file}${typeof comment.line === "number" ? `:${comment.line}` : ""}`
+            : "(location not specified)";
+        const message = toSingleLine(details.message || comment.body || "(no details provided)");
+        lines.push(`- [${slug ?? "untracked"}] ${location} ${message}`);
+        const suggestedFix = comment.metadata?.suggestedFix ?? details.suggestedFix ?? undefined;
+        if (suggestedFix) {
+            lines.push(`  Suggested fix: ${toSingleLine(suggestedFix)}`);
+        }
+    }
+    return lines.join("\n");
+};
+const formatSlugList = (slugs, limit = 12) => {
+    if (!slugs.length)
+        return "none";
+    if (slugs.length <= limit)
+        return slugs.join(", ");
+    return `${slugs.slice(0, limit).join(", ")} (+${slugs.length - limit} more)`;
+};
 const buildStandardReviewComment = (params) => {
     const decision = params.decision ?? (params.error ? "error" : "info_only");
     const statusAfter = params.statusAfter ?? params.statusBefore;
     const summary = normalizeSingleLine(params.summary, params.error ? "Review failed." : "No summary provided.");
     const error = normalizeSingleLine(params.error, "none");
     const followups = params.followupTaskKeys && params.followupTaskKeys.length ? params.followupTaskKeys.join(", ") : "none";
-    return [
+    const lines = [
         "[code-review]",
         `decision: ${decision}`,
         `status_before: ${params.statusBefore}`,
         `status_after: ${statusAfter}`,
         `findings: ${params.findingsCount}`,
         `summary: ${summary}`,
-        `followups: ${followups}`,
-        `error: ${error}`,
-    ].join("\n");
+    ];
+    if (typeof params.resolvedCount === "number") {
+        lines.push(`resolved_slugs: ${params.resolvedCount}`);
+    }
+    if (typeof params.reopenedCount === "number") {
+        lines.push(`reopened_slugs: ${params.reopenedCount}`);
+    }
+    if (typeof params.openCount === "number") {
+        lines.push(`open_slugs: ${params.openCount}`);
+    }
+    lines.push(`followups: ${followups}`, `error: ${error}`);
+    return lines.join("\n");
 };
 export class CodeReviewService {
     constructor(workspace, deps) {
@@ -96,6 +250,7 @@ export class CodeReviewService {
         this.stateService = deps.stateService ?? new TaskStateService(deps.workspaceRepo);
         this.vcs = deps.vcsClient ?? new VcsClient();
         this.routingService = deps.routingService;
+        this.ratingService = deps.ratingService;
     }
     static async create(workspace) {
         const repo = await GlobalRepository.create();
@@ -242,6 +397,26 @@ export class CodeReviewService {
         });
         return resolved.agent;
     }
+    ensureRatingService() {
+        if (!this.ratingService) {
+            this.ratingService = new AgentRatingService(this.workspace, {
+                workspaceRepo: this.deps.workspaceRepo,
+                globalRepo: this.deps.repo,
+                agentService: this.deps.agentService,
+                routingService: this.routingService,
+            });
+        }
+        return this.ratingService;
+    }
+    resolveTaskComplexity(task) {
+        const metadata = task.metadata ?? {};
+        const metaComplexity = typeof metadata.complexity === "number" && Number.isFinite(metadata.complexity) ? metadata.complexity : undefined;
+        const storyPoints = typeof task.storyPoints === "number" && Number.isFinite(task.storyPoints) ? task.storyPoints : undefined;
+        const candidate = metaComplexity ?? storyPoints;
+        if (!Number.isFinite(candidate ?? NaN))
+            return undefined;
+        return Math.min(10, Math.max(1, Math.round(candidate)));
+    }
     async selectTasksViaApi(filters) {
         // Prefer the backlog/task OpenAPI surface (via BacklogService) to mirror API filtering semantics.
         const backlog = await BacklogService.create(this.workspace);
@@ -309,12 +484,13 @@ export class CodeReviewService {
         const snippets = [];
         const warnings = [];
         const queries = [...new Set([...(paths.length ? this.componentHintsFromPaths(paths) : []), taskTitle, ...(acceptance ?? [])])].slice(0, 8);
+        let reindexed = false;
         for (const query of queries) {
             try {
-                const docs = await this.deps.docdex.search({
+                const docs = await withTimeout(this.deps.docdex.search({
                     query,
                     profile: "workspace-code",
-                });
+                }), DOCDEX_TIMEOUT_MS, `docdex search for "${query}"`);
                 snippets.push(...docs.slice(0, 2).map((doc) => {
                     const content = (doc.segments?.[0]?.content ?? doc.content ?? "").slice(0, 400);
                     const ref = doc.path ?? doc.id ?? doc.title ?? query;
@@ -322,6 +498,26 @@ export class CodeReviewService {
                 }));
             }
             catch (error) {
+                if (!reindexed && typeof this.deps.docdex.reindex === "function") {
+                    reindexed = true;
+                    try {
+                        await this.deps.docdex.reindex();
+                        const docs = await withTimeout(this.deps.docdex.search({
+                            query,
+                            profile: "workspace-code",
+                        }), DOCDEX_TIMEOUT_MS, `docdex search for "${query}" after reindex`);
+                        snippets.push(...docs.slice(0, 2).map((doc) => {
+                            const content = (doc.segments?.[0]?.content ?? doc.content ?? "").slice(0, 400);
+                            const ref = doc.path ?? doc.id ?? doc.title ?? query;
+                            return `- [${doc.docType ?? "doc"}] ${ref}: ${content}`;
+                        }));
+                        continue;
+                    }
+                    catch (retryError) {
+                        warnings.push(`docdex search failed after reindex for ${query}: ${retryError.message}`);
+                        continue;
+                    }
+                }
                 warnings.push(`docdex search failed for ${query}: ${error.message}`);
             }
         }
@@ -333,6 +529,16 @@ export class CodeReviewService {
             parts.push(params.systemPrompts.join("\n\n"));
         }
         const acceptance = params.task.acceptanceCriteria && params.task.acceptanceCriteria.length ? params.task.acceptanceCriteria.join(" | ") : "none provided";
+        const historySummary = truncateSection("history", params.historySummary, REVIEW_PROMPT_LIMITS.history);
+        const commentBacklog = params.commentBacklog
+            ? truncateSection("comment backlog", params.commentBacklog, REVIEW_PROMPT_LIMITS.history)
+            : "";
+        const docContextText = params.docContext.length ? truncateSection("doc context", params.docContext.join("\n"), REVIEW_PROMPT_LIMITS.docContext) : "";
+        const openapiSnippet = params.openapiSnippet ? truncateSection("openapi", params.openapiSnippet, REVIEW_PROMPT_LIMITS.openapi) : undefined;
+        const checklistsText = params.checklists?.length
+            ? truncateSection("checklists", params.checklists.join("\n\n"), REVIEW_PROMPT_LIMITS.checklist)
+            : "";
+        const diffText = truncateSection("diff", params.diff || "(no diff)", REVIEW_PROMPT_LIMITS.diff);
         parts.push([
             `Task ${params.task.key}: ${params.task.title}`,
             `Epic: ${params.task.epicKey ?? ""} ${params.task.epicTitle ?? ""}`.trim(),
@@ -341,16 +547,17 @@ export class CodeReviewService {
             `Story description: ${params.task.storyDescription ? params.task.storyDescription : "none"}`,
             `Status: ${params.task.status}, Branch: ${params.branch ?? params.task.vcsBranch ?? "n/a"} (base ${params.baseRef})`,
             `Task description: ${params.task.description ? params.task.description : "none"}`,
-            `History:\n${params.historySummary}`,
+            `History:\n${historySummary}`,
+            commentBacklog ? `Comment backlog (unresolved slugs):\n${commentBacklog}` : "Comment backlog: none",
             `Acceptance criteria: ${acceptance}`,
-            params.docContext.length ? `Doc context (docdex excerpts):\n${params.docContext.join("\n")}` : "Doc context: none",
-            params.openapiSnippet
-                ? `OpenAPI (authoritative contract; do not invent endpoints outside this):\n${params.openapiSnippet}`
+            docContextText ? `Doc context (docdex excerpts):\n${docContextText}` : "Doc context: none",
+            openapiSnippet
+                ? `OpenAPI (authoritative contract; do not invent endpoints outside this):\n${openapiSnippet}`
                 : "OpenAPI: not provided; avoid inventing endpoints.",
-            params.checklists && params.checklists.length ? `Review checklists/runbook:\n${params.checklists.join("\n\n")}` : "Checklists: none",
-            "Diff:\n" + (params.diff || "(no diff)"),
+            checklistsText ? `Review checklists/runbook:\n${checklistsText}` : "Checklists: none",
+            "Diff:\n" + diffText,
             "Respond with STRICT JSON only, matching:\n" + JSON_CONTRACT,
-            "Rules: honor OpenAPI contracts; cite doc context where relevant; do not add prose outside JSON.",
+            "Rules: honor OpenAPI contracts; cite doc context where relevant; include resolvedSlugs/unresolvedSlugs for comment backlog items; do not add prose outside JSON.",
         ].join("\n"));
         return parts.join("\n\n");
     }
@@ -381,6 +588,190 @@ export class CodeReviewService {
             return "No prior review or QA history.";
         return parts.join("\n");
     }
+    async loadCommentContext(taskId) {
+        const comments = await this.deps.workspaceRepo.listTaskComments(taskId, {
+            sourceCommands: ["code-review", "qa-tasks"],
+            limit: 50,
+        });
+        const unresolved = comments.filter((comment) => !comment.resolvedAt);
+        return { comments, unresolved };
+    }
+    commentSlugKey(file, line, category) {
+        if (!file)
+            return undefined;
+        const normalizedFile = normalizePath(file);
+        const linePart = typeof line === "number" ? String(line) : "";
+        const categoryPart = category?.toLowerCase() ?? "";
+        return `${normalizedFile}|${linePart}|${categoryPart}`;
+    }
+    buildCommentSlugIndex(comments) {
+        const index = new Map();
+        for (const comment of comments) {
+            if (!comment.slug)
+                continue;
+            const key = this.commentSlugKey(comment.file, comment.line, comment.category);
+            if (!key)
+                continue;
+            if (!index.has(key))
+                index.set(key, comment.slug);
+        }
+        return index;
+    }
+    resolveFindingSlug(finding, slugIndex) {
+        const key = this.commentSlugKey(finding.file, finding.line, finding.type ?? null);
+        const existing = key ? slugIndex.get(key) : undefined;
+        if (existing)
+            return existing;
+        const message = (finding.message ?? "").trim() || "Review finding.";
+        return createTaskCommentSlug({
+            source: "code-review",
+            message,
+            file: finding.file,
+            line: finding.line,
+            category: finding.type ?? null,
+        });
+    }
+    async applyCommentResolutions(params) {
+        const existingBySlug = new Map();
+        const openBySlug = new Set();
+        const resolvedBySlug = new Set();
+        for (const comment of params.existingComments) {
+            if (!comment.slug)
+                continue;
+            if (!existingBySlug.has(comment.slug)) {
+                existingBySlug.set(comment.slug, comment);
+            }
+            if (comment.resolvedAt) {
+                resolvedBySlug.add(comment.slug);
+            }
+            else {
+                openBySlug.add(comment.slug);
+            }
+        }
+        const reviewSlugIndex = this.buildCommentSlugIndex(params.existingComments.filter((comment) => comment.sourceCommand === "code-review"));
+        const resolvedSlugs = normalizeSlugList(params.resolvedSlugs ?? undefined);
+        const resolvedSet = new Set(resolvedSlugs);
+        const unresolvedSet = new Set(normalizeSlugList(params.unresolvedSlugs ?? undefined));
+        const findingSlugs = [];
+        for (const finding of params.findings ?? []) {
+            const slug = this.resolveFindingSlug(finding, reviewSlugIndex);
+            findingSlugs.push(slug);
+            const severity = (finding.severity ?? "").toLowerCase();
+            const autoResolve = (params.decision === "approve" || params.decision === "info_only") &&
+                ["info", "low"].includes(severity);
+            if (!resolvedSet.has(slug) && !autoResolve) {
+                unresolvedSet.add(slug);
+            }
+        }
+        for (const slug of resolvedSet) {
+            unresolvedSet.delete(slug);
+        }
+        const toResolve = resolvedSlugs.filter((slug) => openBySlug.has(slug));
+        const toReopen = Array.from(unresolvedSet).filter((slug) => resolvedBySlug.has(slug));
+        for (const slug of toResolve) {
+            await this.deps.workspaceRepo.resolveTaskComment({
+                taskId: params.task.id,
+                slug,
+                resolvedAt: new Date().toISOString(),
+                resolvedBy: params.agentId,
+            });
+        }
+        for (const slug of toReopen) {
+            await this.deps.workspaceRepo.reopenTaskComment({ taskId: params.task.id, slug });
+        }
+        const createdSlugs = new Set();
+        for (const finding of params.findings ?? []) {
+            const slug = this.resolveFindingSlug(finding, reviewSlugIndex);
+            if (existingBySlug.has(slug) || createdSlugs.has(slug))
+                continue;
+            const severity = (finding.severity ?? "").toLowerCase();
+            const autoResolve = (params.decision === "approve" || params.decision === "info_only") &&
+                ["info", "low"].includes(severity);
+            const message = (finding.message ?? "").trim() || "(no details provided)";
+            const body = formatTaskCommentBody({
+                slug,
+                source: "code-review",
+                message,
+                status: autoResolve ? "resolved" : "open",
+                category: finding.type ?? "other",
+                file: finding.file ?? null,
+                line: finding.line ?? null,
+                suggestedFix: finding.suggestedFix ?? null,
+            });
+            const resolvedAt = autoResolve ? new Date().toISOString() : undefined;
+            await this.deps.workspaceRepo.createTaskComment({
+                taskId: params.task.id,
+                taskRunId: params.taskRunId,
+                jobId: params.jobId,
+                sourceCommand: "code-review",
+                authorType: "agent",
+                authorAgentId: params.agentId,
+                category: finding.type ?? "other",
+                slug,
+                status: autoResolve ? "resolved" : "open",
+                file: finding.file ?? null,
+                line: finding.line ?? null,
+                pathHint: finding.file ?? null,
+                body,
+                resolvedAt,
+                resolvedBy: autoResolve ? params.agentId : undefined,
+                metadata: {
+                    severity: finding.severity,
+                    suggestedFix: finding.suggestedFix,
+                },
+                createdAt: new Date().toISOString(),
+            });
+            createdSlugs.add(slug);
+        }
+        const openSet = new Set(openBySlug);
+        for (const slug of unresolvedSet) {
+            openSet.add(slug);
+        }
+        for (const slug of resolvedSet) {
+            openSet.delete(slug);
+        }
+        if (resolvedSlugs.length || toReopen.length || unresolvedSet.size) {
+            const resolutionMessage = [
+                `Resolved slugs: ${formatSlugList(toResolve)}`,
+                `Reopened slugs: ${formatSlugList(toReopen)}`,
+                `Open slugs: ${formatSlugList(Array.from(openSet))}`,
+            ].join("\n");
+            const resolutionSlug = createTaskCommentSlug({
+                source: "code-review",
+                message: resolutionMessage,
+                category: "comment_resolution",
+            });
+            const resolutionBody = formatTaskCommentBody({
+                slug: resolutionSlug,
+                source: "code-review",
+                message: resolutionMessage,
+                status: "resolved",
+                category: "comment_resolution",
+            });
+            const createdAt = new Date().toISOString();
+            await this.deps.workspaceRepo.createTaskComment({
+                taskId: params.task.id,
+                taskRunId: params.taskRunId,
+                jobId: params.jobId,
+                sourceCommand: "code-review",
+                authorType: "agent",
+                authorAgentId: params.agentId,
+                category: "comment_resolution",
+                slug: resolutionSlug,
+                status: "resolved",
+                body: resolutionBody,
+                createdAt,
+                resolvedAt: createdAt,
+                resolvedBy: params.agentId,
+                metadata: {
+                    resolvedSlugs: toResolve,
+                    reopenedSlugs: toReopen,
+                    openSlugs: Array.from(openSet),
+                },
+            });
+        }
+        return { resolved: toResolve, reopened: toReopen, open: Array.from(openSet) };
+    }
     extractPathsFromDiff(diff) {
         const regex = /^(?:\+\+\+ b\/|\-\-\- a\/)([^\s]+)$/gm;
         const paths = new Set();
@@ -473,6 +864,9 @@ export class CodeReviewService {
             summary: params.summary,
             followupTaskKeys: params.followupTaskKeys,
             error: params.error,
+            resolvedCount: params.resolvedCount,
+            reopenedCount: params.reopenedCount,
+            openCount: params.openCount,
         });
         await this.deps.workspaceRepo.createTaskComment({
             taskId: params.task.id,
@@ -703,11 +1097,29 @@ export class CodeReviewService {
             if (!selectedTaskIds.length) {
                 throw new Error("Resume requested but no task selection found in job payload");
             }
+            selectedTasks = await this.deps.workspaceRepo.getTasksWithRelations(selectedTaskIds);
+            const terminalStatuses = new Set(["completed", "cancelled"]);
+            const terminalTasks = selectedTasks.filter((task) => terminalStatuses.has((task.status ?? "").toLowerCase()));
+            if (terminalTasks.length) {
+                const terminalIds = new Set(terminalTasks.map((task) => task.id));
+                const terminalKeys = terminalTasks.map((task) => task.key);
+                warnings.push(`Skipping terminal tasks on resume: ${terminalKeys.join(", ")}`);
+                selectedTasks = selectedTasks.filter((task) => !terminalIds.has(task.id));
+                selectedTaskIds = selectedTaskIds.filter((id) => !terminalIds.has(id));
+                if (state) {
+                    state.selectedTaskIds = selectedTaskIds;
+                    await this.persistState(job.id, state);
+                }
+                await this.writeCheckpoint(job.id, "resume_filtered", {
+                    skippedTaskKeys: terminalKeys,
+                    selectedTaskIds,
+                    schema_version: 1,
+                });
+            }
             await this.deps.jobService.updateJobStatus(job.id, "running", {
-                totalItems: job.totalItems ?? selectedTaskIds.length,
+                totalItems: selectedTaskIds.length,
                 processedItems: state?.reviewed.length ?? 0,
             });
-            selectedTasks = await this.deps.workspaceRepo.getTasksWithRelations(selectedTaskIds);
         }
         else {
             try {
@@ -785,9 +1197,77 @@ export class CodeReviewService {
         const agent = await this.resolveAgent(request.agentName);
         const prompts = await this.loadPrompts(agent.id);
         const extras = await this.loadRunbookAndChecklists();
-        const systemPrompts = [prompts.jobPrompt, prompts.characterPrompt, prompts.commandPrompt, ...extras].filter(Boolean);
+        const projectGuidance = await loadProjectGuidance(this.workspace.workspaceRoot);
+        if (projectGuidance) {
+            console.info(`[code-review] loaded project guidance from ${projectGuidance.source}`);
+        }
+        const guidanceBlock = projectGuidance?.content ? `Project Guidance (read first):\n${projectGuidance.content}` : undefined;
+        const systemPrompts = [guidanceBlock, prompts.jobPrompt, prompts.characterPrompt, prompts.commandPrompt, ...extras].filter(Boolean);
+        const abortSignal = request.abortSignal;
+        const resolveAbortReason = () => {
+            const reason = abortSignal?.reason;
+            if (typeof reason === "string" && reason.trim().length > 0)
+                return reason;
+            if (reason instanceof Error && reason.message)
+                return reason.message;
+            return "code_review_aborted";
+        };
+        const abortIfSignaled = () => {
+            if (abortSignal?.aborted) {
+                throw new Error(resolveAbortReason());
+            }
+        };
+        const withAbort = async (promise) => {
+            if (!abortSignal)
+                return promise;
+            if (abortSignal.aborted) {
+                throw new Error(resolveAbortReason());
+            }
+            return await new Promise((resolve, reject) => {
+                const onAbort = () => reject(new Error(resolveAbortReason()));
+                abortSignal.addEventListener("abort", onAbort, { once: true });
+                promise.then(resolve, reject).finally(() => {
+                    abortSignal.removeEventListener("abort", onAbort);
+                });
+            });
+        };
         const results = [];
+        const maybeRateTask = async (task, taskRunId, tokensTotal) => {
+            if (!request.rateAgents || tokensTotal <= 0)
+                return;
+            try {
+                const ratingService = this.ensureRatingService();
+                await ratingService.rate({
+                    workspace: this.workspace,
+                    agentId: agent.id,
+                    commandName: "code-review",
+                    jobId,
+                    commandRunId: commandRun.id,
+                    taskId: task.id,
+                    taskKey: task.key,
+                    discipline: task.type ?? undefined,
+                    complexity: this.resolveTaskComplexity(task),
+                });
+            }
+            catch (error) {
+                const message = `Agent rating failed for ${task.key}: ${error instanceof Error ? error.message : String(error)}`;
+                warnings.push(message);
+                try {
+                    await this.deps.workspaceRepo.insertTaskLog({
+                        taskRunId,
+                        sequence: this.sequenceForTask(taskRunId),
+                        timestamp: new Date().toISOString(),
+                        source: "rating",
+                        message,
+                    });
+                }
+                catch {
+                    /* ignore rating log failures */
+                }
+            }
+        };
         for (const task of tasks) {
+            abortIfSignaled();
             const statusBefore = task.status;
             const taskRun = await this.deps.workspaceRepo.createTaskRun({
                 taskId: task.id,
@@ -806,8 +1286,10 @@ export class CodeReviewService {
             let decision;
             let statusAfter;
             const followupCreated = [];
+            let commentResolution;
             // Debug visibility: show prompts/task details for this run
             const systemPrompt = systemPrompts.join("\n\n");
+            let tokensTotal = 0;
             try {
                 const metadata = task.metadata ?? {};
                 const allowedFiles = Array.isArray(metadata.files) ? metadata.files : [];
@@ -830,7 +1312,57 @@ export class CodeReviewService {
                         allowedFiles,
                     },
                 });
+                if (!diff.trim()) {
+                    const message = "Review diff is empty; blocking review until changes are produced.";
+                    warnings.push(`Empty diff for ${task.key}; blocking review.`);
+                    await this.deps.workspaceRepo.insertTaskLog({
+                        taskRunId: taskRun.id,
+                        sequence: this.sequenceForTask(taskRun.id),
+                        timestamp: new Date().toISOString(),
+                        source: "review_warning",
+                        message,
+                    });
+                    if (!request.dryRun) {
+                        await this.stateService.markBlocked(task, "review_empty_diff");
+                        statusAfter = "blocked";
+                    }
+                    await this.writeReviewSummaryComment({
+                        task,
+                        taskRunId: taskRun.id,
+                        jobId,
+                        agentId: agent.id,
+                        statusBefore,
+                        statusAfter: statusAfter ?? statusBefore,
+                        decision: "block",
+                        summary: message,
+                        findingsCount: 0,
+                    });
+                    await this.deps.workspaceRepo.updateTaskRun(taskRun.id, {
+                        status: "failed",
+                        finishedAt: new Date().toISOString(),
+                        runContext: { decision: "block", reason: "empty_diff" },
+                    });
+                    state?.reviewed.push({ taskId: task.id, decision: "block" });
+                    await this.persistState(jobId, state);
+                    await this.writeCheckpoint(jobId, "review_applied", { reviewed: state?.reviewed ?? [], schema_version: 1 });
+                    results.push({
+                        taskId: task.id,
+                        taskKey: task.key,
+                        statusBefore,
+                        statusAfter: statusAfter ?? statusBefore,
+                        decision: "block",
+                        findings,
+                        followupTasks: followupCreated,
+                    });
+                    await this.deps.jobService.updateJobStatus(jobId, "running", {
+                        processedItems: state?.reviewed.length ?? 0,
+                    });
+                    await maybeRateTask(task, taskRun.id, tokensTotal);
+                    continue;
+                }
                 const historySummary = await this.buildHistorySummary(task.id);
+                const commentContext = await this.loadCommentContext(task.id);
+                const commentBacklog = buildCommentBacklog(commentContext.unresolved);
                 await this.deps.workspaceRepo.insertTaskLog({
                     taskRunId: taskRun.id,
                     sequence: this.sequenceForTask(taskRun.id),
@@ -868,6 +1400,7 @@ export class CodeReviewService {
                     docContext: docLinks.snippets,
                     openapiSnippet,
                     historySummary,
+                    commentBacklog,
                     baseRef: state?.baseRef ?? baseRef,
                     branch: task.vcsBranch ?? undefined,
                 });
@@ -892,6 +1425,7 @@ export class CodeReviewService {
                 console.info(separator);
                 await this.persistContext(jobId, task.id, {
                     historySummary,
+                    commentBacklog,
                     docdex: docLinks.snippets,
                     openapiSnippet,
                     changedPaths,
@@ -902,7 +1436,8 @@ export class CodeReviewService {
                 const recordUsage = async (phase, promptText, outputText, durationSeconds, tokenMeta) => {
                     const tokensPrompt = tokenMeta?.tokensPrompt ?? estimateTokens(promptText);
                     const tokensCompletion = tokenMeta?.tokensCompletion ?? estimateTokens(outputText);
-                    const tokensTotal = tokenMeta?.tokensTotal ?? tokensPrompt + tokensCompletion;
+                    const entryTotal = tokenMeta?.tokensTotal ?? tokensPrompt + tokensCompletion;
+                    tokensTotal += entryTotal;
                     await this.deps.jobService.recordTokenUsage({
                         workspaceId: this.workspace.workspaceId,
                         agentId: agent.id,
@@ -914,7 +1449,7 @@ export class CodeReviewService {
                         projectId: task.projectId,
                         tokensPrompt,
                         tokensCompletion,
-                        tokensTotal,
+                        tokensTotal: entryTotal,
                         durationSeconds,
                         timestamp: new Date().toISOString(),
                         metadata: { commandName: "code-review", phase, action: phase },
@@ -925,8 +1460,13 @@ export class CodeReviewService {
                 const started = Date.now();
                 let lastStreamMeta;
                 if (agentStream && this.deps.agentService.invokeStream) {
-                    const stream = await this.deps.agentService.invokeStream(agent.id, { input: prompt, metadata: { taskKey: task.key } });
-                    for await (const chunk of stream) {
+                    const stream = await withAbort(this.deps.agentService.invokeStream(agent.id, { input: prompt, metadata: { taskKey: task.key } }));
+                    while (true) {
+                        abortIfSignaled();
+                        const { value, done } = await withAbort(stream.next());
+                        if (done)
+                            break;
+                        const chunk = value;
                         agentOutput += chunk.output ?? "";
                         lastStreamMeta = chunk.metadata ?? lastStreamMeta;
                         await this.deps.workspaceRepo.insertTaskLog({
@@ -940,7 +1480,7 @@ export class CodeReviewService {
                     durationSeconds = Math.round(((Date.now() - started) / 1000) * 1000) / 1000;
                 }
                 else {
-                    const response = await this.deps.agentService.invoke(agent.id, { input: prompt, metadata: { taskKey: task.key } });
+                    const response = await withAbort(this.deps.agentService.invoke(agent.id, { input: prompt, metadata: { taskKey: task.key } }));
                     agentOutput = response.output ?? "";
                     durationSeconds = Math.round(((Date.now() - started) / 1000) * 1000) / 1000;
                     await this.deps.workspaceRepo.insertTaskLog({
@@ -964,6 +1504,7 @@ export class CodeReviewService {
                     : undefined;
                 await recordUsage("review_main", prompt, agentOutput, durationSeconds, tokenMetaMain);
                 let parsed = parseJsonOutput(agentOutput);
+                let invalidJson = false;
                 if (!parsed) {
                     await this.deps.workspaceRepo.insertTaskLog({
                         taskRunId: taskRun.id,
@@ -974,7 +1515,7 @@ export class CodeReviewService {
                     });
                     const retryPrompt = `${prompt}\n\nRespond ONLY with valid JSON matching the schema above. Do not include prose or fences.`;
                     const retryStarted = Date.now();
-                    const retryResp = await this.deps.agentService.invoke(agent.id, { input: retryPrompt, metadata: { taskKey: task.key, retry: true } });
+                    const retryResp = await withAbort(this.deps.agentService.invoke(agent.id, { input: retryPrompt, metadata: { taskKey: task.key, retry: true } }));
                     const retryOutput = retryResp.output ?? "";
                     const retryDuration = Math.round(((Date.now() - retryStarted) / 1000) * 1000) / 1000;
                     await this.deps.workspaceRepo.insertTaskLog({
@@ -1003,15 +1544,78 @@ export class CodeReviewService {
                     agentOutput = retryOutput;
                 }
                 if (!parsed) {
-                    throw new Error("Agent output did not contain valid JSON review result after retry");
+                    invalidJson = true;
+                    const fallbackSummary = "Review agent returned non-JSON output after retry; block review and re-run with a stricter JSON-only model.";
+                    warnings.push(`Review agent returned non-JSON output for ${task.key}; blocking review.`);
+                    await this.deps.workspaceRepo.insertTaskLog({
+                        taskRunId: taskRun.id,
+                        sequence: this.sequenceForTask(taskRun.id),
+                        timestamp: new Date().toISOString(),
+                        source: "review_warning",
+                        message: fallbackSummary,
+                    });
+                    parsed = {
+                        decision: "block",
+                        summary: fallbackSummary,
+                        findings: [],
+                        testRecommendations: [],
+                        raw: agentOutput,
+                    };
                 }
                 parsed.raw = agentOutput;
+                const originalDecision = parsed.decision;
                 decision = parsed.decision;
                 findings.push(...(parsed.findings ?? []));
-                const followups = await this.createFollowupTasksForFindings({
+                commentResolution = await this.applyCommentResolutions({
                     task,
+                    taskRunId: taskRun.id,
+                    jobId,
+                    agentId: agent.id,
                     findings: parsed.findings ?? [],
+                    resolvedSlugs: parsed.resolvedSlugs ?? undefined,
+                    unresolvedSlugs: parsed.unresolvedSlugs ?? undefined,
                     decision: parsed.decision,
+                    existingComments: commentContext.comments,
+                });
+                let finalDecision = parsed.decision;
+                if (commentResolution?.open?.length &&
+                    (finalDecision === "approve" || finalDecision === "info_only")) {
+                    const openSlugs = commentResolution.open;
+                    finalDecision = "changes_requested";
+                    const message = `Unresolved comment slugs remain: ${formatSlugList(openSlugs)}. Review approval requires resolving these items.`;
+                    const backlogSlug = createTaskCommentSlug({
+                        source: "code-review",
+                        message,
+                        category: "comment_backlog",
+                    });
+                    const backlogBody = formatTaskCommentBody({
+                        slug: backlogSlug,
+                        source: "code-review",
+                        message,
+                        status: "open",
+                        category: "comment_backlog",
+                    });
+                    await this.deps.workspaceRepo.createTaskComment({
+                        taskId: task.id,
+                        taskRunId: taskRun.id,
+                        jobId,
+                        sourceCommand: "code-review",
+                        authorType: "agent",
+                        authorAgentId: agent.id,
+                        category: "comment_backlog",
+                        slug: backlogSlug,
+                        status: "open",
+                        body: backlogBody,
+                        metadata: { openSlugs },
+                        createdAt: new Date().toISOString(),
+                    });
+                }
+                parsed.decision = finalDecision;
+                decision = finalDecision;
+                const followups = await this.createFollowupTasksForFindings({
+                    task,
+                    findings: parsed.findings ?? [],
+                    decision: originalDecision,
                     jobId,
                     commandRunId: commandRun.id,
                     taskRunId: taskRun.id,
@@ -1028,18 +1632,25 @@ export class CodeReviewService {
                 }
                 let taskStatusUpdate = statusBefore;
                 if (!request.dryRun) {
-                    if (parsed.decision === "approve") {
-                        await this.stateService.markReadyToQa(task);
-                        taskStatusUpdate = "ready_to_qa";
-                    }
-                    else if (parsed.decision === "changes_requested") {
-                        await this.stateService.returnToInProgress(task);
-                        taskStatusUpdate = "in_progress";
-                    }
-                    else if (parsed.decision === "block") {
-                        await this.stateService.markBlocked(task, "review_blocked");
+                    if (invalidJson) {
+                        await this.stateService.markBlocked(task, "review_invalid_output");
                         taskStatusUpdate = "blocked";
                     }
+                    else {
+                        const approveDecision = parsed.decision === "approve" || parsed.decision === "info_only";
+                        if (approveDecision) {
+                            await this.stateService.markReadyToQa(task);
+                            taskStatusUpdate = "ready_to_qa";
+                        }
+                        else if (parsed.decision === "changes_requested") {
+                            await this.stateService.returnToInProgress(task);
+                            taskStatusUpdate = "in_progress";
+                        }
+                        else if (parsed.decision === "block") {
+                            await this.stateService.markBlocked(task, "review_blocked");
+                            taskStatusUpdate = "blocked";
+                        }
+                    }
                 }
                 else {
                     await this.deps.workspaceRepo.insertTaskLog({
@@ -1052,26 +1663,6 @@ export class CodeReviewService {
                     });
                 }
                 statusAfter = taskStatusUpdate;
-                for (const finding of parsed.findings ?? []) {
-                    await this.deps.workspaceRepo.createTaskComment({
-                        taskId: task.id,
-                        taskRunId: taskRun.id,
-                        jobId,
-                        sourceCommand: "code-review",
-                        authorType: "agent",
-                        authorAgentId: agent.id,
-                        category: finding.type ?? "other",
-                        file: finding.file,
-                        line: finding.line,
-                        pathHint: finding.file,
-                        body: finding.message + (finding.suggestedFix ? `\n\nSuggested fix: ${finding.suggestedFix}` : ""),
-                        metadata: {
-                            severity: finding.severity,
-                            suggestedFix: finding.suggestedFix,
-                        },
-                        createdAt: new Date().toISOString(),
-                    });
-                }
                 await this.writeReviewSummaryComment({
                     task,
                     taskRunId: taskRun.id,
@@ -1083,6 +1674,9 @@ export class CodeReviewService {
                     summary: parsed.summary,
                     findingsCount: parsed.findings?.length ?? 0,
                     followupTaskKeys: followupCreated.map((t) => t.taskKey),
+                    resolvedCount: commentResolution?.resolved.length,
+                    reopenedCount: commentResolution?.reopened.length,
+                    openCount: commentResolution?.open.length,
                 });
                 await this.deps.workspaceRepo.createTaskReview({
                     taskId: task.id,
@@ -1151,6 +1745,7 @@ export class CodeReviewService {
                 await this.deps.jobService.updateJobStatus(jobId, "running", {
                     processedItems: state?.reviewed.length ?? 0,
                 });
+                await maybeRateTask(task, taskRun.id, tokensTotal);
                 continue;
             }
             results.push({
@@ -1165,6 +1760,7 @@ export class CodeReviewService {
             await this.deps.jobService.updateJobStatus(jobId, "running", {
                 processedItems: state?.reviewed.length ?? 0,
             });
+            await maybeRateTask(task, taskRun.id, tokensTotal);
         }
         await this.deps.jobService.updateJobStatus(jobId, "completed", {
             processedItems: state?.reviewed.length ?? selectedTaskIds.length,