@mcoda/core 0.1.8 → 0.1.11

package/dist/services/review/CodeReviewService.js

@@ -1,9 +1,10 @@
 import path from "node:path";
 import fs from "node:fs/promises";
+import { fileURLToPath } from "node:url";
 import { AgentService } from "@mcoda/agents";
 import { DocdexClient, VcsClient } from "@mcoda/integrations";
-import { GlobalRepository, WorkspaceRepository } from "@mcoda/db";
-import { PathHelper } from "@mcoda/shared";
+import { GlobalRepository, WorkspaceRepository, } from "@mcoda/db";
+import { PathHelper, READY_TO_CODE_REVIEW, REVIEW_ALLOWED_STATUSES, filterTaskStatuses, normalizeReviewStatuses, } from "@mcoda/shared";
 import { JobService } from "../jobs/JobService.js";
 import { TaskSelectionService } from "../execution/TaskSelectionService.js";
 import { TaskStateService } from "../execution/TaskStateService.js";
@@ -11,36 +12,88 @@ 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 { isDocContextExcluded, loadProjectGuidance, normalizeDocType } from "../shared/ProjectGuidance.js";
+import { buildDocdexUsageGuidance } from "../shared/DocdexGuidance.js";
+import { createTaskCommentSlug, formatTaskCommentBody } from "../tasks/TaskCommentFormatter.js";
+import { AUTH_ERROR_REASON, isAuthErrorMessage } from "../shared/AuthErrors.js";
+import { normalizeReviewOutput } from "./ReviewNormalizer.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_DIR = (mcodaDir, jobId) => path.join(mcodaDir, "jobs", jobId, "review");
+const STATE_PATH = (mcodaDir, jobId) => path.join(REVIEW_DIR(mcodaDir, 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.",
+    "You are the code-review agent.",
+    buildDocdexUsageGuidance({ contextLabel: "the review", includeHeading: false, includeFallback: true }),
     "Use docdex snippets to verify contracts (data shapes, offline scope, accessibility/perf guardrails, acceptance criteria). Call out mismatches, missing tests, and undocumented changes.",
+    "When recommending tests, prefer the repo's existing runner (tests/all.js or package manager scripts). Avoid suggesting new Jest configs unless the repo explicitly documents them.",
+    "Do not require docs/qa/<task>.md reports unless the task explicitly asks for one. QA artifacts typically live in mcoda workspace outputs.",
+    "Do not hardcode ports; if a port matters, call out that it must be discovered or configured dynamically.",
 ].join("\n");
+const REPO_PROMPTS_DIR = fileURLToPath(new URL("../../../../../prompts/", import.meta.url));
+const resolveRepoPromptPath = (filename) => path.join(REPO_PROMPTS_DIR, filename);
 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 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 GATEWAY_PROMPT_MARKERS = [
+    "you are the gateway agent",
+    "return json only",
+    "output json only",
+    "docdexnotes",
+    "fileslikelytouched",
+    "filestocreate",
+    "do not include fields outside the schema",
+];
+const sanitizeNonGatewayPrompt = (value) => {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return undefined;
+    const lower = trimmed.toLowerCase();
+    if (GATEWAY_PROMPT_MARKERS.some((marker) => lower.includes(marker)))
+        return undefined;
+    return trimmed;
+};
+const readPromptFile = async (promptPath, fallback) => {
+    try {
+        const content = await fs.readFile(promptPath, "utf8");
+        const trimmed = content.trim();
+        if (trimmed)
+            return trimmed;
+    }
+    catch {
+        // fall through to fallback
+    }
+    return fallback;
+};
+const filterOpenApiContext = (entries, hasOpenApiSnippet) => {
+    let openApiIncluded = false;
+    const filtered = [];
+    for (const entry of entries) {
+        const isOpenApi = /\[linked:openapi\]|\[openapi\]/i.test(entry);
+        if (!isOpenApi) {
+            filtered.push(entry);
             continue;
-        const slice = candidate.slice(start, end + 1);
-        try {
-            const parsed = JSON.parse(slice);
-            return { ...parsed, raw: raw };
         }
-        catch {
-            /* ignore */
+        if (hasOpenApiSnippet) {
+            continue;
+        }
+        if (openApiIncluded) {
+            continue;
         }
+        openApiIncluded = true;
+        filtered.push(entry);
     }
-    return undefined;
+    return filtered;
 };
+const estimateTokens = (text) => Math.max(1, Math.ceil((text ?? "").length / 4));
 const summarizeComments = (comments) => {
     if (!comments.length)
         return "No prior comments.";
@@ -51,6 +104,41 @@ 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 isNonBlockingFinding = (finding) => {
+    const severity = (finding.severity ?? "").toLowerCase();
+    if (["info", "low"].includes(severity))
+        return true;
+    return false;
+};
+const isNonBlockingOnly = (findings = []) => {
+    if (!findings.length)
+        return false;
+    return findings.every((finding) => isNonBlockingFinding(finding));
+};
+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 +152,179 @@ 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 JSON_RETRY_RULES = [
+    "Return ONLY valid JSON. No markdown, no prose, no code fences.",
+    "The response must start with '{' and end with '}'.",
+    "Match the schema exactly; use empty arrays when no items apply.",
+].join("\n");
+const isRetryableAgentError = (message) => /unexpected eof|econnreset|etimedout|socket hang up|fetch failed|connection closed/i.test(message.toLowerCase());
 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 normalizeLineNumber = (value) => {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return Math.max(1, Math.round(value));
+    }
+    if (typeof value === "string") {
+        const parsed = Number.parseInt(value, 10);
+        if (Number.isFinite(parsed))
+            return Math.max(1, parsed);
+    }
+    return undefined;
+};
+const summaryIndicatesNoChanges = (summary) => {
+    const normalized = (summary ?? "").toLowerCase();
+    if (!normalized)
+        return false;
+    const patterns = [
+        "no changes required",
+        "no changes needed",
+        "no change required",
+        "no change needed",
+        "no code changes",
+        "already complete",
+        "already completed",
+        "already satisfied",
+    ];
+    return patterns.some((pattern) => normalized.includes(pattern));
+};
+const validateReviewOutput = (result, options = {}) => {
+    if (!result.decision || !["approve", "changes_requested", "block", "info_only"].includes(result.decision)) {
+        return "Review decision is required.";
+    }
+    if (!result.summary || !result.summary.trim()) {
+        return "Review summary is required.";
+    }
+    if (options.requireCommentSlugs && result.resolvedSlugs === undefined && result.unresolvedSlugs === undefined) {
+        return "resolvedSlugs/unresolvedSlugs required when comment backlog exists.";
+    }
+    for (const finding of result.findings ?? []) {
+        const message = (finding.message ?? "").trim();
+        const file = typeof finding.file === "string" ? finding.file.trim() : "";
+        const line = normalizeLineNumber(finding.line);
+        if (!message || !file || !line) {
+            return "Each review finding must include file, line, and message.";
+        }
+        finding.file = normalizePath(file);
+        finding.line = line;
+        finding.message = message;
+    }
+    return undefined;
+};
+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 details = parseCommentBody(comment.body);
+        const slug = comment.slug?.trim() ||
+            createTaskCommentSlug({
+                source: comment.sourceCommand ?? "comment",
+                message: details.message || comment.body,
+                file: comment.file,
+                line: comment.line,
+                category: comment.category ?? null,
+            });
+        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,14 +335,17 @@ 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();
         const agentService = new AgentService(repo);
         const routingService = await RoutingService.create();
+        const docdexRepoId = workspace.config?.docdexRepoId ?? process.env.MCODA_DOCDEX_REPO_ID ?? process.env.DOCDEX_REPO_ID;
         const docdex = new DocdexClient({
             workspaceRoot: workspace.workspaceRoot,
             baseUrl: workspace.config?.docdexUrl ?? process.env.MCODA_DOCDEX_URL,
+            repoId: docdexRepoId,
         });
         const workspaceRepo = await WorkspaceRepository.create(workspace.workspaceRoot);
         const jobService = new JobService(workspace, workspaceRepo);
@@ -141,6 +383,14 @@ export class CodeReviewService {
         await maybeClose(this.deps.routingService);
         await maybeClose(this.deps.docdex);
     }
+    setDocdexAvailability(available, reason) {
+        if (available)
+            return;
+        const docdex = this.deps.docdex;
+        if (docdex && typeof docdex.disable === "function") {
+            docdex.disable(reason);
+        }
+    }
     async readPromptFiles(paths) {
         const contents = [];
         const seen = new Set();
@@ -161,21 +411,11 @@ export class CodeReviewService {
     }
     async ensureMcoda() {
         await PathHelper.ensureDir(this.workspace.mcodaDir);
-        const gitignorePath = path.join(this.workspace.workspaceRoot, ".gitignore");
-        const entry = ".mcoda/\n";
-        try {
-            const content = await fs.readFile(gitignorePath, "utf8");
-            if (!content.includes(".mcoda/")) {
-                await fs.writeFile(gitignorePath, `${content.trimEnd()}\n${entry}`, "utf8");
-            }
-        }
-        catch {
-            await fs.writeFile(gitignorePath, entry, "utf8");
-        }
     }
     async loadPrompts(agentId) {
-        const mcodaPromptPath = path.join(this.workspace.workspaceRoot, ".mcoda", "prompts", "code-reviewer.md");
+        const mcodaPromptPath = path.join(this.workspace.mcodaDir, "prompts", "code-reviewer.md");
         const workspacePromptPath = path.join(this.workspace.workspaceRoot, "prompts", "code-reviewer.md");
+        const repoPromptPath = resolveRepoPromptPath("code-reviewer.md");
         try {
             await fs.mkdir(path.dirname(mcodaPromptPath), { recursive: true });
             await fs.access(mcodaPromptPath);
@@ -188,30 +428,29 @@ export class CodeReviewService {
                 console.info(`[code-review] copied code-reviewer prompt to ${mcodaPromptPath}`);
             }
             catch {
-                console.info(`[code-review] no code-reviewer prompt found at ${workspacePromptPath}; writing default prompt to ${mcodaPromptPath}`);
-                await fs.writeFile(mcodaPromptPath, DEFAULT_CODE_REVIEW_PROMPT, 'utf8');
+                try {
+                    await fs.access(repoPromptPath);
+                    await fs.copyFile(repoPromptPath, mcodaPromptPath);
+                    console.info(`[code-review] copied repo code-reviewer prompt to ${mcodaPromptPath}`);
+                }
+                catch {
+                    console.info(`[code-review] no code-reviewer prompt found at ${workspacePromptPath} or repo prompts; writing default prompt to ${mcodaPromptPath}`);
+                    await fs.writeFile(mcodaPromptPath, DEFAULT_CODE_REVIEW_PROMPT, "utf8");
+                }
             }
         }
-        const filePrompts = await this.readPromptFiles([mcodaPromptPath, workspacePromptPath]);
         const agentPrompts = "getPrompts" in this.deps.agentService ? await this.deps.agentService.getPrompts(agentId) : undefined;
-        const mergedCommandPrompt = (() => {
-            const parts = [...filePrompts];
-            if (agentPrompts?.commandPrompts?.["code-review"]) {
-                parts.push(agentPrompts.commandPrompts["code-review"]);
-            }
-            if (!parts.length)
-                parts.push(DEFAULT_CODE_REVIEW_PROMPT);
-            return parts.filter(Boolean).join("\n\n");
-        })();
+        const filePrompt = await readPromptFile(mcodaPromptPath, DEFAULT_CODE_REVIEW_PROMPT);
+        const commandPrompt = agentPrompts?.commandPrompts?.["code-review"]?.trim() || filePrompt;
         return {
-            jobPrompt: agentPrompts?.jobPrompt ?? DEFAULT_JOB_PROMPT,
-            characterPrompt: agentPrompts?.characterPrompt ?? DEFAULT_CHARACTER_PROMPT,
-            commandPrompt: mergedCommandPrompt || undefined,
+            jobPrompt: sanitizeNonGatewayPrompt(agentPrompts?.jobPrompt) ?? DEFAULT_JOB_PROMPT,
+            characterPrompt: sanitizeNonGatewayPrompt(agentPrompts?.characterPrompt) ?? DEFAULT_CHARACTER_PROMPT,
+            commandPrompt: commandPrompt || undefined,
         };
     }
     async loadRunbookAndChecklists() {
         const extras = [];
-        const runbookPath = path.join(this.workspace.workspaceRoot, ".mcoda", "prompts", "commands", "code-review.md");
+        const runbookPath = path.join(this.workspace.mcodaDir, "prompts", "commands", "code-review.md");
         try {
             const content = await fs.readFile(runbookPath, "utf8");
             extras.push(content);
@@ -219,7 +458,7 @@ export class CodeReviewService {
         catch {
             /* optional */
         }
-        const checklistDir = path.join(this.workspace.workspaceRoot, ".mcoda", "checklists");
+        const checklistDir = path.join(this.workspace.mcodaDir, "checklists");
         try {
             const entries = await fs.readdir(checklistDir);
             for (const entry of entries) {
@@ -240,7 +479,33 @@ export class CodeReviewService {
             commandName: "code-review",
             overrideAgentSlug: agentName,
         });
-        return resolved.agent;
+        if (agentName) {
+            const matches = agentName === resolved.agent.id || agentName === resolved.agent.slug;
+            if (!matches) {
+                throw new Error(`Review agent override "${agentName}" resolved to "${resolved.agent.slug}" (source: ${resolved.source}).`);
+            }
+        }
+        return resolved;
+    }
+    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.
@@ -250,7 +515,7 @@ export class CodeReviewService {
                 projectKey: filters.projectKey,
                 epicKey: filters.epicKey,
                 storyKey: filters.storyKey,
-                statuses: filters.statusFilter,
+                statuses: filters.statusFilter && filters.statusFilter.length ? filters.statusFilter : undefined,
                 verbose: true,
             });
             let tasks = result.summary.tasks;
@@ -272,13 +537,13 @@ export class CodeReviewService {
         }
     }
     async persistState(jobId, state) {
-        const dir = REVIEW_DIR(this.workspace.workspaceRoot, jobId);
+        const dir = REVIEW_DIR(this.workspace.mcodaDir, jobId);
         await fs.mkdir(dir, { recursive: true });
-        await fs.writeFile(STATE_PATH(this.workspace.workspaceRoot, jobId), JSON.stringify({ schema_version: 1, job_id: jobId, updated_at: new Date().toISOString(), ...state }, null, 2), "utf8");
+        await fs.writeFile(STATE_PATH(this.workspace.mcodaDir, jobId), JSON.stringify({ schema_version: 1, job_id: jobId, updated_at: new Date().toISOString(), ...state }, null, 2), "utf8");
     }
     async loadState(jobId) {
         try {
-            const raw = await fs.readFile(STATE_PATH(this.workspace.workspaceRoot, jobId), "utf8");
+            const raw = await fs.readFile(STATE_PATH(this.workspace.mcodaDir, jobId), "utf8");
             return JSON.parse(raw);
         }
         catch {
@@ -305,26 +570,109 @@ export class CodeReviewService {
         }
         return Array.from(hints).slice(0, 8);
     }
-    async gatherDocContext(taskTitle, paths, acceptance) {
+    async gatherDocContext(taskTitle, paths, acceptance, docLinks = []) {
         const snippets = [];
         const warnings = [];
+        if (typeof this.deps.docdex?.ensureRepoScope === "function") {
+            try {
+                await this.deps.docdex.ensureRepoScope();
+            }
+            catch (error) {
+                warnings.push(`docdex scope missing: ${error.message}`);
+                return { snippets, warnings };
+            }
+        }
         const queries = [...new Set([...(paths.length ? this.componentHintsFromPaths(paths) : []), taskTitle, ...(acceptance ?? [])])].slice(0, 8);
+        let reindexed = false;
+        const resolveDocType = (doc, pathOverride) => {
+            const content = doc.segments?.[0]?.content ?? doc.content ?? "";
+            const normalized = normalizeDocType({
+                docType: doc.docType,
+                path: doc.path ?? pathOverride,
+                title: doc.title,
+                content,
+            });
+            if (normalized.downgraded) {
+                warnings.push(`Docdex docType downgraded from SDS to DOC for ${doc.path ?? doc.title ?? doc.docType ?? "unknown"}: ${normalized.reason ?? "not_sds"}`);
+            }
+            return normalized.docType;
+        };
         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",
-                });
-                snippets.push(...docs.slice(0, 2).map((doc) => {
+                }), DOCDEX_TIMEOUT_MS, `docdex search for "${query}"`);
+                const filteredDocs = docs.filter((doc) => !isDocContextExcluded(doc.path ?? doc.title ?? doc.id, false));
+                snippets.push(...filteredDocs.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}`;
+                    return `- [${resolveDocType(doc)}] ${ref}: ${content}`;
                 }));
             }
             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`);
+                        const filteredDocs = docs.filter((doc) => !isDocContextExcluded(doc.path ?? doc.title ?? doc.id, false));
+                        snippets.push(...filteredDocs.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 `- [${resolveDocType(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}`);
             }
         }
+        const normalizeDocLink = (value) => {
+            const trimmed = value.trim();
+            const stripped = trimmed.replace(/^docdex:/i, "").replace(/^doc:/i, "");
+            const candidate = stripped || trimmed;
+            const looksLikePath = candidate.includes("/") ||
+                candidate.includes("\\") ||
+                /\.(md|markdown|txt|rst|yaml|yml|json)$/i.test(candidate);
+            return { type: looksLikePath ? "path" : "id", ref: candidate };
+        };
+        for (const link of docLinks) {
+            try {
+                const { type, ref } = normalizeDocLink(link);
+                if (type === "path" && isDocContextExcluded(ref, false)) {
+                    snippets.push(`- [linked:filtered] ${link} — excluded from non-QA context`);
+                    continue;
+                }
+                let doc = undefined;
+                if (type === "path" && "findDocumentByPath" in this.deps.docdex) {
+                    doc = await this.deps.docdex.findDocumentByPath(ref);
+                }
+                if (!doc) {
+                    doc = await this.deps.docdex.fetchDocumentById(ref);
+                }
+                if (!doc) {
+                    warnings.push(`docdex fetch returned no document for ${link}`);
+                    snippets.push(`- [linked:missing] ${link} — no docdex entry found`);
+                    continue;
+                }
+                const content = (doc.segments?.[0]?.content ?? doc.content ?? "").slice(0, 400);
+                const refLabel = doc.path ?? doc.id ?? doc.title ?? link;
+                snippets.push(`- [linked:${resolveDocType(doc, type === "path" ? ref : undefined)}] ${refLabel}: ${content}`);
+            }
+            catch (error) {
+                const message = error.message;
+                warnings.push(`docdex fetch failed for ${link}: ${message}`);
+                snippets.push(`- [linked:missing] ${link} — ${message}`);
+            }
+        }
         return { snippets: Array.from(new Set(snippets)), warnings };
     }
     buildReviewPrompt(params) {
@@ -333,7 +681,28 @@ 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 filteredDocContext = filterOpenApiContext(params.docContext, Boolean(params.openapiSnippet));
+        const docContextText = filteredDocContext.length
+            ? truncateSection("doc context", filteredDocContext.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);
+        const reviewFocus = [
+            "Review focus:",
+            "- First validate the task requirements and the work-on-tasks actions (history/comments) rather than the diff.",
+            "- If the diff is empty, decide whether no code changes are required to satisfy the task.",
+            "- If no changes are required, use decision=approve or info_only and explicitly say no code changes are needed.",
+            "- If changes are required, use decision=changes_requested and explain exactly what is missing and why.",
+        ].join("\n");
         parts.push([
+            reviewFocus,
             `Task ${params.task.key}: ${params.task.title}`,
             `Epic: ${params.task.epicKey ?? ""} ${params.task.epicTitle ?? ""}`.trim(),
             `Epic description: ${params.task.epicDescription ? params.task.epicDescription : "none"}`,
@@ -341,22 +710,25 @@ 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}`,
-            `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}`
+            `History:\n${historySummary}`,
+            commentBacklog
+                ? `Code-review comment backlog (unresolved slugs):\n${commentBacklog}`
+                : "Code-review comment backlog: none",
+            `Task DoD / acceptance criteria: ${acceptance}`,
+            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",
+            params.diffEmpty ? "Diff: (empty — no changes between base and branch)" : "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 code-review comment backlog items only; do not require docs/qa/* reports; avoid hardcoded ports; do not add prose or markdown fences outside JSON.",
         ].join("\n"));
         return parts.join("\n\n");
     }
     async buildHistorySummary(taskId) {
         const comments = await this.deps.workspaceRepo.listTaskComments(taskId, {
-            sourceCommands: ["work-on-tasks", "code-review", "qa-tasks"],
+            sourceCommands: ["work-on-tasks", "code-review"],
             limit: 10,
         });
         const lastReview = await this.deps.workspaceRepo.getLatestTaskReview(taskId);
@@ -378,9 +750,194 @@ export class CodeReviewService {
             }
         }
         if (!parts.length)
-            return "No prior review or QA history.";
+            return "No prior review history.";
         return parts.join("\n");
     }
+    async loadCommentContext(taskId) {
+        const comments = await this.deps.workspaceRepo.listTaskComments(taskId, {
+            sourceCommands: ["code-review"],
+            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 allowedSlugs = new Set(existingBySlug.keys());
+        const resolvedSlugs = normalizeSlugList(params.resolvedSlugs ?? undefined).filter((slug) => allowedSlugs.has(slug));
+        const resolvedSet = new Set(resolvedSlugs);
+        const unresolvedSet = new Set(normalizeSlugList(params.unresolvedSlugs ?? undefined).filter((slug) => allowedSlugs.has(slug)));
+        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 +1030,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,
@@ -487,12 +1047,12 @@ export class CodeReviewService {
         });
     }
     async persistContext(jobId, taskId, context) {
-        const dir = path.join(REVIEW_DIR(this.workspace.workspaceRoot, jobId), "context");
+        const dir = path.join(REVIEW_DIR(this.workspace.mcodaDir, jobId), "context");
         await fs.mkdir(dir, { recursive: true });
         await fs.writeFile(path.join(dir, `${taskId}.json`), JSON.stringify({ schema_version: 1, task_id: taskId, created_at: new Date().toISOString(), ...context }, null, 2), "utf8");
     }
     async persistDiff(jobId, taskId, diff) {
-        const dir = path.join(REVIEW_DIR(this.workspace.workspaceRoot, jobId), "diffs");
+        const dir = path.join(REVIEW_DIR(this.workspace.mcodaDir, jobId), "diffs");
         await fs.mkdir(dir, { recursive: true });
         await fs.writeFile(path.join(dir, `${taskId}.diff`), diff, "utf8");
         // structured review diff snapshot
@@ -525,6 +1085,13 @@ export class CodeReviewService {
             files.push(current);
         await fs.writeFile(path.join(dir, `${taskId}.json`), JSON.stringify({ schema_version: 1, task_id: taskId, files }, null, 2), "utf8");
     }
+    async persistReviewOutput(jobId, taskId, payload) {
+        const dir = path.join(REVIEW_DIR(this.workspace.mcodaDir, jobId), "outputs");
+        await fs.mkdir(dir, { recursive: true });
+        const target = path.join(dir, `${taskId}.json`);
+        await fs.writeFile(target, JSON.stringify(payload, null, 2), "utf8");
+        return path.relative(this.workspace.mcodaDir, target);
+    }
     severityToPriority(severity) {
         if (!severity)
             return null;
@@ -532,6 +1099,13 @@ export class CodeReviewService {
         const order = { critical: 1, high: 2, medium: 3, low: 4, info: 5 };
         return order[normalized] ?? null;
     }
+    severityToStoryPoints(severity) {
+        if (!severity)
+            return null;
+        const normalized = severity.toLowerCase();
+        const points = { critical: 8, high: 5, medium: 3, low: 2, info: 1 };
+        return points[normalized] ?? null;
+    }
     shouldCreateFollowupTask(decision, finding) {
         // SDS rule: create follow-ups for blocking/changes_requested decisions or critical/high issues,
         // and for contract/security/bug types at medium+ severity. Do not create for approve+low/info.
@@ -632,6 +1206,9 @@ export class CodeReviewService {
             const storyId = genericTarget ? genericContainers.story.id : params.task.userStoryId;
             const storyKey = genericTarget ? genericContainers.story.key : params.task.storyKey ?? genericContainers?.story.key ?? "US-AUTO";
             const epicId = genericTarget ? genericContainers.epic.id : params.task.epicId;
+            const fallbackPoints = this.resolveTaskComplexity(params.task) ?? params.task.storyPoints ?? 1;
+            const storyPoints = this.severityToStoryPoints(finding.severity) ?? fallbackPoints;
+            const boundedPoints = Number.isFinite(storyPoints) ? Math.min(10, Math.max(1, Math.round(storyPoints))) : 1;
             const taskKey = await ensureKey(storyId, storyKey);
             inserts.push({
                 projectId: params.task.projectId,
@@ -642,7 +1219,7 @@ export class CodeReviewService {
                 description: this.buildFollowupDescription(params.task, finding, params.decision),
                 type: finding.type ?? (params.decision === "changes_requested" || params.decision === "block" ? "bug" : "issue"),
                 status: "not_started",
-                storyPoints: null,
+                storyPoints: boundedPoints,
                 priority: this.severityToPriority(finding.severity),
                 metadata: {
                     source: "code-review",
@@ -658,6 +1235,7 @@ export class CodeReviewService {
                     suggestedFix: finding.suggestedFix,
                     generic: genericTarget ? true : false,
                     decision: params.decision,
+                    complexity: boundedPoints,
                 },
             });
         }
@@ -680,7 +1258,14 @@ export class CodeReviewService {
         await this.ensureMcoda();
         const agentStream = request.agentStream !== false;
         const baseRef = request.baseRef ?? this.workspace.config?.branch ?? DEFAULT_BASE_BRANCH;
-        const statusFilter = request.statusFilter && request.statusFilter.length ? request.statusFilter : ["ready_to_review"];
+        const ignoreStatusFilter = Boolean(request.taskKeys?.length) || request.ignoreStatusFilter === true;
+        const rawStatusFilter = ignoreStatusFilter
+            ? []
+            : request.statusFilter && request.statusFilter.length
+                ? request.statusFilter
+                : [READY_TO_CODE_REVIEW];
+        const { filtered: allowedStatusFilter, rejected } = filterTaskStatuses(rawStatusFilter, REVIEW_ALLOWED_STATUSES, REVIEW_ALLOWED_STATUSES);
+        const statusFilter = normalizeReviewStatuses(allowedStatusFilter);
         let state;
         const commandRun = await this.deps.jobService.startCommandRun("code-review", request.projectKey, {
             taskIds: request.taskKeys,
@@ -690,6 +1275,10 @@ export class CodeReviewService {
         let jobId = request.resumeJobId;
         let selectedTaskIds = [];
         let warnings = [];
+        if (rejected.length > 0 && !ignoreStatusFilter) {
+            warnings.push(`code-review ignores unsupported statuses: ${rejected.join(", ")}. Allowed: ${REVIEW_ALLOWED_STATUSES.join(", ")}.`);
+        }
+        let allowFollowups = request.createFollowupTasks === true;
         let selectedTasks = [];
         if (request.resumeJobId) {
             const job = await this.deps.jobService.getJob(request.resumeJobId);
@@ -698,16 +1287,37 @@ export class CodeReviewService {
             if ((job.commandName ?? job.type) !== "code-review" && job.type !== "review") {
                 throw new Error(`Job ${request.resumeJobId} is not a code-review job`);
             }
+            if (request.createFollowupTasks === undefined) {
+                allowFollowups = Boolean(job.payload?.createFollowupTasks);
+            }
             state = await this.loadState(request.resumeJobId);
             selectedTaskIds = state?.selectedTaskIds ?? (Array.isArray(job.payload?.selection) ? job.payload.selection : []);
             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 {
@@ -716,7 +1326,7 @@ export class CodeReviewService {
                     epicKey: request.epicKey,
                     storyKey: request.storyKey,
                     taskKeys: request.taskKeys,
-                    statusFilter,
+                    statusFilter: ignoreStatusFilter ? undefined : statusFilter,
                     limit: request.limit,
                 });
             }
@@ -726,10 +1336,11 @@ export class CodeReviewService {
                     epicKey: request.epicKey,
                     storyKey: request.storyKey,
                     taskKeys: request.taskKeys,
-                    statusFilter,
+                    statusFilter: ignoreStatusFilter ? undefined : statusFilter,
                     limit: request.limit,
+                    ignoreStatusFilter,
                 });
-                warnings = [...selection.warnings];
+                warnings = [...warnings, ...selection.warnings];
                 selectedTasks = selection.ordered.map((t) => t.task);
             }
             selectedTaskIds = selectedTasks.map((t) => t.id);
@@ -740,12 +1351,13 @@ export class CodeReviewService {
                     epicKey: request.epicKey,
                     storyKey: request.storyKey,
                     tasks: request.taskKeys,
-                    statusFilter,
+                    statusFilter: ignoreStatusFilter ? [] : statusFilter,
                     baseRef,
                     selection: selectedTaskIds,
                     dryRun: request.dryRun ?? false,
                     agent: request.agentName,
                     agentStream,
+                    createFollowupTasks: allowFollowups,
                 },
                 totalItems: selectedTaskIds.length,
                 processedItems: 0,
@@ -782,12 +1394,208 @@ export class CodeReviewService {
         const tasks = selectedTasks.length && selectedTaskIds.length === selectedTasks.length
             ? selectedTasks
             : await this.deps.workspaceRepo.getTasksWithRelations(selectedTaskIds);
-        const agent = await this.resolveAgent(request.agentName);
+        let resolvedAgent;
+        try {
+            resolvedAgent = await this.resolveAgent(request.agentName);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (request.agentName) {
+                const warning = `Review agent override (${request.agentName}) failed: ${message}`;
+                warnings.push(warning);
+                console.warn(`[code-review] ${warning}`);
+            }
+            throw error;
+        }
+        const agent = resolvedAgent.agent;
+        const reviewJsonAgentOverride = this.workspace.config?.reviewJsonAgent ??
+            process.env.MCODA_REVIEW_JSON_AGENT ??
+            process.env.MCODA_REVIEW_JSON_AGENT_NAME;
+        let reviewJsonAgent;
+        if (reviewJsonAgentOverride &&
+            reviewJsonAgentOverride !== agent.id &&
+            reviewJsonAgentOverride !== agent.slug) {
+            try {
+                reviewJsonAgent = (await this.resolveAgent(reviewJsonAgentOverride)).agent;
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                warnings.push(`Review JSON agent override (${reviewJsonAgentOverride}) failed: ${message}`);
+            }
+        }
         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, this.workspace.mcodaDir);
+        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 formatSessionId = (iso) => {
+            const date = new Date(iso);
+            const pad = (value) => String(value).padStart(2, "0");
+            return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}_${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`;
+        };
+        const formatDuration = (ms) => {
+            const totalSeconds = Math.max(0, Math.floor(ms / 1000));
+            const seconds = totalSeconds % 60;
+            const minutesTotal = Math.floor(totalSeconds / 60);
+            const minutes = minutesTotal % 60;
+            const hours = Math.floor(minutesTotal / 60);
+            if (hours > 0)
+                return `${hours}H ${minutes}M ${seconds}S`;
+            return `${minutes}M ${seconds}S`;
+        };
+        const resolveProvider = (adapter) => {
+            if (!adapter)
+                return "n/a";
+            const trimmed = adapter.trim();
+            if (!trimmed)
+                return "n/a";
+            if (trimmed.includes("-"))
+                return trimmed.split("-")[0];
+            return trimmed;
+        };
+        const resolveReasoning = (config) => {
+            if (!config)
+                return "n/a";
+            const raw = config.reasoning ?? config.thinking;
+            if (typeof raw === "string")
+                return raw;
+            if (typeof raw === "boolean")
+                return raw ? "enabled" : "disabled";
+            return "n/a";
+        };
+        const emitLine = (line) => {
+            console.info(line);
+        };
+        const emitBlank = () => emitLine("");
+        const emitReviewStart = (details) => {
+            emitLine("╭──────────────────────────────────────────────────────────╮");
+            emitLine("│              START OF CODE REVIEW TASK                   │");
+            emitLine("╰──────────────────────────────────────────────────────────╯");
+            emitLine(`  [🪪] Code Review Task ID: ${details.taskKey}`);
+            emitLine(`  [👹] Alias:          ${details.alias}`);
+            emitLine(`  [ℹ️] Summary:        ${details.summary}`);
+            emitLine(`  [🤖] Model:          ${details.model}`);
+            emitLine(`  [🕹️] Provider:       ${details.provider}`);
+            emitLine(`  [🧩] Step:           ${details.step}`);
+            emitLine(`  [🧠] Reasoning:      ${details.reasoning}`);
+            emitLine(`  [📁] Workdir:        ${details.workdir}`);
+            emitLine(`  [🔑] Session:        ${details.sessionId}`);
+            emitLine(`  [🕒] Started:        ${details.startedAt}`);
+            emitBlank();
+            emitLine("    ░░░░░ START OF CODE REVIEW TASK ░░░░░");
+            emitBlank();
+            emitLine(`    [STEP ${details.step}]  [MODEL ${details.model}]`);
+            emitBlank();
+            emitBlank();
+        };
+        const emitReviewEnd = (details) => {
+            emitLine("╭──────────────────────────────────────────────────────────╮");
+            emitLine("│                END OF CODE REVIEW TASK                   │");
+            emitLine("╰──────────────────────────────────────────────────────────╯");
+            emitLine(`  👀 CODE REVIEW TASK ${details.taskKey} | 📜 STATUS ${details.statusLabel} | ✅ DECISION ${details.decision ?? "n/a"} | 🔎 FINDINGS ${details.findingsCount} | ⌛ TIME ${formatDuration(details.elapsedMs)}`);
+            emitLine(`  [🕒] Started:        ${details.startedAt}`);
+            emitLine(`  [🕒] Ended:          ${details.endedAt}`);
+            emitLine(`  Tokens used:  ${details.tokensTotal.toLocaleString("en-US")}`);
+            emitBlank();
+            emitLine("    ░░░░░ END OF CODE REVIEW TASK ░░░░░");
+            emitBlank();
+        };
+        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 ?? "review",
+                    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 */
+                }
+            }
+        };
+        let abortRemainingReason = null;
         for (const task of tasks) {
+            if (abortRemainingReason)
+                break;
+            abortIfSignaled();
+            const startedAt = new Date().toISOString();
+            const taskStartMs = Date.now();
+            const sessionId = formatSessionId(startedAt);
+            const taskAlias = `Reviewing task ${task.key}`;
+            const taskSummary = task.title ?? task.description ?? "(none)";
+            const modelLabel = agent.defaultModel ?? "(default)";
+            const providerLabel = resolveProvider(agent.adapter);
+            const reasoningLabel = resolveReasoning(agent.config);
+            const stepLabel = "review";
+            let endEmitted = false;
+            const emitReviewEndOnce = (details) => {
+                if (endEmitted)
+                    return;
+                endEmitted = true;
+                emitReviewEnd({
+                    taskKey: task.key,
+                    statusLabel: details.statusLabel,
+                    decision: details.decision,
+                    findingsCount: details.findingsCount,
+                    elapsedMs: Date.now() - taskStartMs,
+                    tokensTotal: details.tokensTotal,
+                    startedAt,
+                    endedAt: new Date().toISOString(),
+                });
+            };
             const statusBefore = task.status;
             const taskRun = await this.deps.workspaceRepo.createTaskRun({
                 taskId: task.id,
@@ -796,19 +1604,42 @@ export class CodeReviewService {
                 commandRunId: commandRun.id,
                 agentId: agent.id,
                 status: "running",
-                startedAt: new Date().toISOString(),
+                startedAt,
                 storyPointsAtRun: task.storyPoints ?? null,
                 gitBranch: task.vcsBranch ?? null,
                 gitBaseBranch: task.vcsBaseBranch ?? null,
                 gitCommitSha: task.vcsLastCommitSha ?? null,
             });
+            const statusContext = {
+                commandName: "code-review",
+                jobId,
+                taskRunId: taskRun.id,
+                agentId: agent.id,
+                metadata: { lane: "review" },
+            };
             const findings = [];
             let decision;
             let statusAfter;
+            let reviewErrorCode;
             const followupCreated = [];
+            let commentResolution;
             // Debug visibility: show prompts/task details for this run
             const systemPrompt = systemPrompts.join("\n\n");
+            let tokensTotal = 0;
+            let agentOutput = "";
             try {
+                emitReviewStart({
+                    taskKey: task.key,
+                    alias: taskAlias,
+                    summary: taskSummary,
+                    model: modelLabel,
+                    provider: providerLabel,
+                    step: stepLabel,
+                    reasoning: reasoningLabel,
+                    workdir: this.workspace.workspaceRoot,
+                    sessionId,
+                    startedAt,
+                });
                 const metadata = task.metadata ?? {};
                 const allowedFiles = Array.isArray(metadata.files) ? metadata.files : [];
                 const diffResult = await this.buildDiff(task, state?.baseRef ?? baseRef, allowedFiles);
@@ -830,7 +1661,21 @@ export class CodeReviewService {
                         allowedFiles,
                     },
                 });
+                const diffEmpty = !diff.trim();
+                if (diffEmpty) {
+                    const message = `Empty diff for ${task.key}; reviewing task requirements to confirm whether no changes are acceptable.`;
+                    warnings.push(message);
+                    await this.deps.workspaceRepo.insertTaskLog({
+                        taskRunId: taskRun.id,
+                        sequence: this.sequenceForTask(taskRun.id),
+                        timestamp: new Date().toISOString(),
+                        source: "review_warning",
+                        message,
+                    });
+                }
                 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),
@@ -839,7 +1684,8 @@ export class CodeReviewService {
                     message: "Loaded task history",
                 });
                 const changedPaths = this.extractPathsFromDiff(diff);
-                const docLinks = await this.gatherDocContext(task.title, changedPaths.length ? changedPaths : allowedFiles, task.acceptanceCriteria);
+                const diffMeta = { diffEmpty, changedPaths };
+                const docLinks = await this.gatherDocContext(task.title, changedPaths.length ? changedPaths : allowedFiles, task.acceptanceCriteria, Array.isArray(task.metadata?.doc_links) ? task.metadata.doc_links : []);
                 if (docLinks.warnings.length)
                     warnings.push(...docLinks.warnings);
                 await this.deps.workspaceRepo.insertTaskLog({
@@ -865,12 +1711,15 @@ export class CodeReviewService {
                     systemPrompts,
                     task,
                     diff,
+                    diffEmpty,
                     docContext: docLinks.snippets,
                     openapiSnippet,
                     historySummary,
+                    commentBacklog,
                     baseRef: state?.baseRef ?? baseRef,
                     branch: task.vcsBranch ?? undefined,
                 });
+                const requireCommentSlugs = Boolean(commentBacklog.trim());
                 const separator = "============================================================";
                 const deps = Array.isArray(task.dependencyKeys) && task.dependencyKeys.length
                     ? task.dependencyKeys
@@ -878,7 +1727,6 @@ export class CodeReviewService {
                         ? task.metadata.depends_on
                         : [];
                 console.info(separator);
-                console.info("[code-review] START OF TASK");
                 console.info(`[code-review] Task key: ${task.key}`);
                 console.info(`[code-review] Title: ${task.title ?? "(none)"}`);
                 console.info(`[code-review] Description: ${task.description ?? "(none)"}`);
@@ -892,21 +1740,24 @@ export class CodeReviewService {
                 console.info(separator);
                 await this.persistContext(jobId, task.id, {
                     historySummary,
+                    commentBacklog,
                     docdex: docLinks.snippets,
                     openapiSnippet,
                     changedPaths,
+                    diffEmpty,
                 });
                 state?.contextBuilt.push(task.id);
                 await this.persistState(jobId, state);
                 await this.writeCheckpoint(jobId, "context_built", { contextBuilt: state?.contextBuilt ?? [], schema_version: 1 });
-                const recordUsage = async (phase, promptText, outputText, durationSeconds, tokenMeta) => {
+                const recordUsage = async (phase, promptText, outputText, durationSeconds, tokenMeta, agentUsed = agent, attempt = 1) => {
                     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,
-                        modelName: tokenMeta?.model ?? agent.defaultModel ?? undefined,
+                        agentId: agentUsed.id,
+                        modelName: tokenMeta?.model ?? agentUsed.defaultModel ?? undefined,
                         jobId,
                         commandRunId: commandRun.id,
                         taskRunId: taskRun.id,
@@ -914,43 +1765,85 @@ export class CodeReviewService {
                         projectId: task.projectId,
                         tokensPrompt,
                         tokensCompletion,
-                        tokensTotal,
+                        tokensTotal: entryTotal,
                         durationSeconds,
                         timestamp: new Date().toISOString(),
-                        metadata: { commandName: "code-review", phase, action: phase },
+                        metadata: { commandName: "code-review", phase, action: phase, attempt },
                     });
                 };
-                let agentOutput = "";
+                agentOutput = "";
                 let durationSeconds = 0;
-                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) {
-                        agentOutput += chunk.output ?? "";
-                        lastStreamMeta = chunk.metadata ?? lastStreamMeta;
+                let agentUsedForOutput = agent;
+                let outputAttempt = 1;
+                const invokeReviewAgent = async (agentToUse, useStream, logSource) => {
+                    let output = "";
+                    let metadata;
+                    const started = Date.now();
+                    if (useStream && this.deps.agentService.invokeStream) {
+                        const stream = await withAbort(this.deps.agentService.invokeStream(agentToUse.id, {
+                            input: prompt,
+                            metadata: { taskKey: task.key, retry: logSource === "agent_retry" },
+                        }));
+                        while (true) {
+                            abortIfSignaled();
+                            const { value, done } = await withAbort(stream.next());
+                            if (done)
+                                break;
+                            const chunk = value;
+                            output += chunk.output ?? "";
+                            metadata = chunk.metadata ?? metadata;
+                            await this.deps.workspaceRepo.insertTaskLog({
+                                taskRunId: taskRun.id,
+                                sequence: this.sequenceForTask(taskRun.id),
+                                timestamp: new Date().toISOString(),
+                                source: logSource,
+                                message: chunk.output ?? "",
+                            });
+                        }
+                    }
+                    else {
+                        const response = await withAbort(this.deps.agentService.invoke(agentToUse.id, {
+                            input: prompt,
+                            metadata: { taskKey: task.key, retry: logSource === "agent_retry" },
+                        }));
+                        output = response.output ?? "";
+                        metadata = response.metadata;
                         await this.deps.workspaceRepo.insertTaskLog({
                             taskRunId: taskRun.id,
                             sequence: this.sequenceForTask(taskRun.id),
                             timestamp: new Date().toISOString(),
-                            source: "agent",
-                            message: chunk.output ?? "",
+                            source: logSource,
+                            message: output,
                         });
                     }
-                    durationSeconds = Math.round(((Date.now() - started) / 1000) * 1000) / 1000;
+                    const durationSeconds = Math.round(((Date.now() - started) / 1000) * 1000) / 1000;
+                    return { output, durationSeconds, metadata };
+                };
+                try {
+                    const invocation = await invokeReviewAgent(agent, Boolean(agentStream && this.deps.agentService.invokeStream), "agent");
+                    agentOutput = invocation.output;
+                    durationSeconds = invocation.durationSeconds;
+                    lastStreamMeta = invocation.metadata;
                 }
-                else {
-                    const response = await this.deps.agentService.invoke(agent.id, { input: prompt, metadata: { taskKey: task.key } });
-                    agentOutput = response.output ?? "";
-                    durationSeconds = Math.round(((Date.now() - started) / 1000) * 1000) / 1000;
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    if (!isRetryableAgentError(message)) {
+                        throw error;
+                    }
+                    outputAttempt = 2;
+                    agentUsedForOutput = reviewJsonAgent ?? agent;
                     await this.deps.workspaceRepo.insertTaskLog({
                         taskRunId: taskRun.id,
                         sequence: this.sequenceForTask(taskRun.id),
                         timestamp: new Date().toISOString(),
-                        source: "agent",
-                        message: agentOutput,
+                        source: "agent_retry",
+                        message: `Transient agent error (${message}); retrying once with ${agentUsedForOutput.slug ?? agentUsedForOutput.id}.`,
                     });
-                    lastStreamMeta = response.metadata;
+                    const invocation = await invokeReviewAgent(agentUsedForOutput, false, "agent_retry");
+                    agentOutput = invocation.output;
+                    durationSeconds = invocation.durationSeconds;
+                    lastStreamMeta = invocation.metadata;
                 }
                 const tokenMetaMain = lastStreamMeta
                     ? {
@@ -962,20 +1855,60 @@ export class CodeReviewService {
                         model: (lastStreamMeta.model ?? lastStreamMeta.model_name ?? null),
                     }
                     : undefined;
-                await recordUsage("review_main", prompt, agentOutput, durationSeconds, tokenMetaMain);
-                let parsed = parseJsonOutput(agentOutput);
-                if (!parsed) {
+                await recordUsage("review_main", prompt, agentOutput, durationSeconds, tokenMetaMain, agentUsedForOutput, outputAttempt);
+                const primaryOutput = agentOutput;
+                let retryOutput;
+                let retryAgentUsed;
+                let normalization = normalizeReviewOutput(agentOutput);
+                let parsed = normalization.result;
+                let validationError = validateReviewOutput(parsed, { requireCommentSlugs });
+                if (validationError === "resolvedSlugs/unresolvedSlugs required when comment backlog exists.") {
+                    const warning = `Review output missing comment slugs for ${task.key}; assuming no backlog items resolved.`;
+                    warnings.push(warning);
+                    await this.deps.workspaceRepo.insertTaskLog({
+                        taskRunId: taskRun.id,
+                        sequence: this.sequenceForTask(taskRun.id),
+                        timestamp: new Date().toISOString(),
+                        source: "review_warning",
+                        message: warning,
+                    });
+                    validationError = undefined;
+                }
+                const needsRetry = Boolean(validationError) || normalization.usedFallback;
+                if (needsRetry) {
+                    const retryReason = validationError
+                        ? `Invalid review schema (${validationError}); retrying once with stricter instructions.`
+                        : "Unstructured review output; retrying once with stricter instructions.";
                     await this.deps.workspaceRepo.insertTaskLog({
                         taskRunId: taskRun.id,
                         sequence: this.sequenceForTask(taskRun.id),
                         timestamp: new Date().toISOString(),
                         source: "agent",
-                        message: "Invalid JSON from agent; retrying once with stricter instructions.",
+                        message: retryReason,
                     });
-                    const retryPrompt = `${prompt}\n\nRespond ONLY with valid JSON matching the schema above. Do not include prose or fences.`;
+                    const buildRetryPrompt = (raw) => [
+                        "Your previous response was invalid JSON. Reformat it to match the schema below.",
+                        JSON_RETRY_RULES,
+                        JSON_CONTRACT,
+                        "RESPONSE_TO_CONVERT:",
+                        raw,
+                    ].join("\n");
+                    const retryPrompt = agentOutput.trim()
+                        ? buildRetryPrompt(agentOutput)
+                        : `${prompt}\n\n${JSON_RETRY_RULES}\n${JSON_CONTRACT}`;
                     const retryStarted = Date.now();
-                    const retryResp = await this.deps.agentService.invoke(agent.id, { input: retryPrompt, metadata: { taskKey: task.key, retry: true } });
-                    const retryOutput = retryResp.output ?? "";
+                    retryAgentUsed = reviewJsonAgent ?? agent;
+                    if (retryAgentUsed.id !== agent.id) {
+                        await this.deps.workspaceRepo.insertTaskLog({
+                            taskRunId: taskRun.id,
+                            sequence: this.sequenceForTask(taskRun.id),
+                            timestamp: new Date().toISOString(),
+                            source: "agent_retry",
+                            message: `Retrying with JSON-only agent override: ${retryAgentUsed.slug ?? retryAgentUsed.id}`,
+                        });
+                    }
+                    const retryResp = await withAbort(this.deps.agentService.invoke(retryAgentUsed.id, { input: retryPrompt, metadata: { taskKey: task.key, retry: true } }));
+                    retryOutput = retryResp.output ?? "";
                     const retryDuration = Math.round(((Date.now() - retryStarted) / 1000) * 1000) / 1000;
                     await this.deps.workspaceRepo.insertTaskLog({
                         taskRunId: taskRun.id,
@@ -998,47 +1931,231 @@ export class CodeReviewService {
                             model: (retryResp.metadata.model ?? retryResp.metadata.model_name ?? null),
                         }
                         : undefined;
-                    await recordUsage("review_retry", retryPrompt, retryOutput, retryDuration, retryTokenMeta);
-                    parsed = parseJsonOutput(retryOutput);
+                    await recordUsage("review_retry", retryPrompt, retryOutput, retryDuration, retryTokenMeta, retryAgentUsed, 2);
+                    normalization = normalizeReviewOutput(retryOutput);
+                    parsed = normalization.result;
+                    validationError = validateReviewOutput(parsed, { requireCommentSlugs });
+                    if (validationError === "resolvedSlugs/unresolvedSlugs required when comment backlog exists.") {
+                        const warning = `Review output missing comment slugs for ${task.key} after retry; assuming no backlog items resolved.`;
+                        warnings.push(warning);
+                        await this.deps.workspaceRepo.insertTaskLog({
+                            taskRunId: taskRun.id,
+                            sequence: this.sequenceForTask(taskRun.id),
+                            timestamp: new Date().toISOString(),
+                            source: "review_warning",
+                            message: warning,
+                        });
+                        validationError = undefined;
+                    }
                     agentOutput = retryOutput;
                 }
-                if (!parsed) {
-                    throw new Error("Agent output did not contain valid JSON review result after retry");
+                if (validationError) {
+                    const fallbackSummary = `Review output missing required fields (${validationError}); treated as informational.`;
+                    warnings.push(`Review output missing required fields for ${task.key}; proceeding with info_only.`);
+                    await this.deps.workspaceRepo.insertTaskLog({
+                        taskRunId: taskRun.id,
+                        sequence: this.sequenceForTask(taskRun.id),
+                        timestamp: new Date().toISOString(),
+                        source: "review_warning",
+                        message: fallbackSummary,
+                    });
+                    parsed = {
+                        decision: "info_only",
+                        summary: fallbackSummary,
+                        findings: [],
+                        testRecommendations: [],
+                        raw: retryOutput ?? agentOutput,
+                    };
+                    normalization = { parsedFromJson: false, usedFallback: true, issues: ["validation_error"], result: parsed };
+                }
+                if (normalization.usedFallback) {
+                    const fallbackMessage = `Review output was not valid JSON for ${task.key}; treated as informational.`;
+                    warnings.push(fallbackMessage);
+                    await this.deps.workspaceRepo.insertTaskLog({
+                        taskRunId: taskRun.id,
+                        sequence: this.sequenceForTask(taskRun.id),
+                        timestamp: new Date().toISOString(),
+                        source: "review_warning",
+                        message: fallbackMessage,
+                    });
+                    try {
+                        const artifactPath = await this.persistReviewOutput(jobId, task.id, {
+                            schema_version: 1,
+                            task_key: task.key,
+                            created_at: new Date().toISOString(),
+                            agent_id: agent.id,
+                            retry_agent_id: retryAgentUsed?.id ?? agent.id,
+                            primary_output: primaryOutput,
+                            retry_output: retryOutput ?? agentOutput,
+                            validation_error: validationError ?? null,
+                        });
+                        warnings.push(`Review output saved to ${artifactPath} for ${task.key}.`);
+                    }
+                    catch (persistError) {
+                        warnings.push(`Failed to persist review output for ${task.key}: ${persistError instanceof Error ? persistError.message : String(persistError)}`);
+                    }
                 }
-                parsed.raw = agentOutput;
+                parsed.raw = parsed.raw ?? agentOutput;
+                const originalDecision = parsed.decision;
                 decision = parsed.decision;
                 findings.push(...(parsed.findings ?? []));
-                const followups = await this.createFollowupTasksForFindings({
+                const historySupportsNoChanges = task.metadata?.completed_reason === "no_changes" ||
+                    historySummary.toLowerCase().includes("no_changes") ||
+                    historySummary.toLowerCase().includes("no changes");
+                const summarySupportsNoChanges = summaryIndicatesNoChanges(parsed.summary);
+                const approveDecision = parsed.decision === "approve" || parsed.decision === "info_only";
+                let finalDecision = parsed.decision;
+                let emptyDiffOverride = false;
+                if (diffEmpty && approveDecision && !(summarySupportsNoChanges && historySupportsNoChanges)) {
+                    finalDecision = "changes_requested";
+                    emptyDiffOverride = true;
+                }
+                if (finalDecision === "changes_requested" && isNonBlockingOnly(parsed.findings ?? []) && !emptyDiffOverride) {
+                    finalDecision = "info_only";
+                    warnings.push(`Review for ${task.key} requested changes but only low/info findings were reported; downgrading to info_only.`);
+                }
+                commentResolution = await this.applyCommentResolutions({
                     task,
-                    findings: parsed.findings ?? [],
-                    decision: parsed.decision,
-                    jobId,
-                    commandRunId: commandRun.id,
                     taskRunId: taskRun.id,
+                    jobId,
+                    agentId: agent.id,
+                    findings: parsed.findings ?? [],
+                    resolvedSlugs: parsed.resolvedSlugs ?? undefined,
+                    unresolvedSlugs: parsed.unresolvedSlugs ?? undefined,
+                    decision: finalDecision,
+                    existingComments: commentContext.comments,
                 });
-                if (followups.length) {
-                    followupCreated.push(...followups.map((t) => ({
-                        taskId: t.id,
-                        taskKey: t.key,
-                        epicId: t.epicId,
-                        userStoryId: t.userStoryId,
-                        generic: t?.metadata?.generic ? true : undefined,
-                    })));
-                    warnings.push(`Created follow-up tasks for ${task.key}: ${followups.map((t) => t.key).join(", ")}`);
+                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(),
+                    });
+                }
+                if (emptyDiffOverride) {
+                    const message = [
+                        "Empty diff detected; approval requires an explicit no-changes justification",
+                        "and task history indicating no changes were needed.",
+                    ].join(" ");
+                    const slug = createTaskCommentSlug({
+                        source: "code-review",
+                        message,
+                        category: "review_empty_diff",
+                    });
+                    const body = formatTaskCommentBody({
+                        slug,
+                        source: "code-review",
+                        message,
+                        status: "open",
+                        category: "review_empty_diff",
+                    });
+                    await this.deps.workspaceRepo.createTaskComment({
+                        taskId: task.id,
+                        taskRunId: taskRun.id,
+                        jobId,
+                        sourceCommand: "code-review",
+                        authorType: "agent",
+                        authorAgentId: agent.id,
+                        category: "review_empty_diff",
+                        slug,
+                        status: "open",
+                        body,
+                        createdAt: new Date().toISOString(),
+                    });
+                    warnings.push(`Empty diff approval rejected for ${task.key}; requesting explicit no-changes justification.`);
+                }
+                const appendSyntheticFinding = (message, suggestedFix) => {
+                    const finding = {
+                        type: "process",
+                        severity: "info",
+                        message,
+                        suggestedFix,
+                    };
+                    if (!parsed.findings) {
+                        parsed.findings = [];
+                    }
+                    parsed.findings.push(finding);
+                    findings.push(finding);
+                };
+                if (finalDecision === "changes_requested" && (parsed.findings?.length ?? 0) === 0) {
+                    if (emptyDiffOverride) {
+                        appendSyntheticFinding("Empty diff lacks explicit no-changes justification; changes requested to confirm no code updates were required.", "Update the review summary to state no changes were required and confirm task history reflects no_changes.");
+                    }
+                    else if (commentResolution?.open?.length) {
+                        appendSyntheticFinding(`Unresolved comment backlog remains (${formatSlugList(commentResolution.open)}); approval requires resolving these items.`, "Resolve or explicitly reopen the listed comment slugs before approving.");
+                    }
+                    else {
+                        finalDecision = "info_only";
+                        warnings.push(`Review requested changes for ${task.key} but provided no findings; downgrading to info_only.`);
+                    }
+                }
+                parsed.decision = finalDecision;
+                decision = finalDecision;
+                if (allowFollowups) {
+                    const followups = await this.createFollowupTasksForFindings({
+                        task,
+                        findings: parsed.findings ?? [],
+                        decision: originalDecision,
+                        jobId,
+                        commandRunId: commandRun.id,
+                        taskRunId: taskRun.id,
+                    });
+                    if (followups.length) {
+                        followupCreated.push(...followups.map((t) => ({
+                            taskId: t.id,
+                            taskKey: t.key,
+                            epicId: t.epicId,
+                            userStoryId: t.userStoryId,
+                            generic: t?.metadata?.generic ? true : undefined,
+                        })));
+                        warnings.push(`Created follow-up tasks for ${task.key}: ${followups.map((t) => t.key).join(", ")}`);
+                    }
                 }
                 let taskStatusUpdate = statusBefore;
                 if (!request.dryRun) {
-                    if (parsed.decision === "approve") {
-                        await this.stateService.markReadyToQa(task);
-                        taskStatusUpdate = "ready_to_qa";
+                    const approveDecision = parsed.decision === "approve" || parsed.decision === "info_only";
+                    if (approveDecision) {
+                        if (diffEmpty) {
+                            await this.stateService.markCompleted(task, { review_no_changes: true }, statusContext);
+                            taskStatusUpdate = "completed";
+                        }
+                        else {
+                            await this.stateService.markReadyToQa(task, undefined, statusContext);
+                            taskStatusUpdate = "ready_to_qa";
+                        }
                     }
                     else if (parsed.decision === "changes_requested") {
-                        await this.stateService.returnToInProgress(task);
-                        taskStatusUpdate = "in_progress";
+                        await this.stateService.markChangesRequested(task, undefined, statusContext);
+                        taskStatusUpdate = "changes_requested";
                     }
                     else if (parsed.decision === "block") {
-                        await this.stateService.markBlocked(task, "review_blocked");
-                        taskStatusUpdate = "blocked";
+                        await this.stateService.markFailed(task, "review_blocked", statusContext);
+                        taskStatusUpdate = "failed";
                     }
                 }
                 else {
@@ -1052,26 +2169,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,8 +2180,11 @@ 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({
+                const review = await this.deps.workspaceRepo.createTaskReview({
                     taskId: task.id,
                     jobId,
                     agentId: agent.id,
@@ -1093,6 +2193,7 @@ export class CodeReviewService {
                     summary: parsed.summary ?? undefined,
                     findingsJson: parsed.findings ?? [],
                     testRecommendationsJson: parsed.testRecommendations ?? [],
+                    metadata: diffMeta,
                     createdAt: new Date().toISOString(),
                 });
                 await this.stateService.recordReviewMetadata(task, {
@@ -1100,6 +2201,9 @@ export class CodeReviewService {
                     agentId: agent.id,
                     modelName: agent.defaultModel ?? null,
                     jobId,
+                    reviewId: review.id,
+                    diffEmpty,
+                    changedPaths,
                 });
                 await this.deps.workspaceRepo.updateTaskRun(taskRun.id, {
                     status: "succeeded",
@@ -1151,6 +2255,18 @@ export class CodeReviewService {
                 await this.deps.jobService.updateJobStatus(jobId, "running", {
                     processedItems: state?.reviewed.length ?? 0,
                 });
+                emitReviewEndOnce({
+                    statusLabel: "FAILED",
+                    decision: "error",
+                    findingsCount: findings.length,
+                    tokensTotal,
+                });
+                await maybeRateTask(task, taskRun.id, tokensTotal);
+                if (isAuthErrorMessage(message)) {
+                    abortRemainingReason = message;
+                    warnings.push(`Auth/rate limit error detected; stopping after ${task.key}. ${message}`);
+                    break;
+                }
                 continue;
             }
             results.push({
@@ -1160,11 +2276,37 @@ export class CodeReviewService {
                 statusAfter,
                 decision,
                 findings,
+                error: reviewErrorCode,
                 followupTasks: followupCreated,
             });
+            const statusLabel = reviewErrorCode
+                ? "FAILED"
+                : decision === "approve" || decision === "info_only"
+                    ? "APPROVED"
+                    : decision === "block"
+                        ? "FAILED"
+                        : decision === "changes_requested"
+                            ? "CHANGES_REQUESTED"
+                            : "FAILED";
+            emitReviewEndOnce({
+                statusLabel,
+                decision,
+                findingsCount: findings.length,
+                tokensTotal,
+            });
             await this.deps.jobService.updateJobStatus(jobId, "running", {
                 processedItems: state?.reviewed.length ?? 0,
             });
+            await maybeRateTask(task, taskRun.id, tokensTotal);
+        }
+        if (abortRemainingReason) {
+            await this.deps.jobService.updateJobStatus(jobId, "failed", {
+                processedItems: state?.reviewed.length ?? 0,
+                totalItems: selectedTaskIds.length,
+                errorSummary: AUTH_ERROR_REASON,
+            });
+            await this.deps.jobService.finishCommandRun(commandRun.id, "failed", abortRemainingReason);
+            return { jobId, commandRunId: commandRun.id, tasks: results, warnings };
         }
         await this.deps.jobService.updateJobStatus(jobId, "completed", {
             processedItems: state?.reviewed.length ?? selectedTaskIds.length,