@nyxa/nyx-agent 0.6.1 → 0.8.0

package/dist/runtime/runPipeline.js

@@ -1,26 +1,29 @@
 import path from "node:path";
-import pc from "picocolors";
+import { execa } from "execa";
 import { loadConfig } from "../config/loadConfig.js";
-import { ensureDir, pathExists, readText } from "./files.js";
-import { deleteBranch, removeRunWorktree, setUpRunWorktree } from "./gitLifecycle.js";
-import { markWorkItemCompleted, readWorkItemLedger, writeWorkItemLedger } from "./ledger.js";
+import { globalReviewRoles, } from "../config/schema.js";
+import { ensureDir, pathExists, readText, writeText } from "./files.js";
+import { deleteBranch, removeRunWorktree, setUpRunWorktree, } from "./gitLifecycle.js";
+import { markWorkItemCompleted, readWorkItemLedger, writeWorkItemLedger, } from "./ledger.js";
 import { getNyxDir, relativeToProject } from "./paths.js";
-import { buildContextBlock, buildPhasePrompt, EXECUTION_PROMPT, GLOBAL_REVIEW_PROMPT, GLOBAL_REVISION_PROMPT, REVIEW_PROMPT, REVISION_PROMPT, SELECTION_PROMPT, truncateForPrompt } from "./prompts.js";
-import { runAgentPhase } from "./runPhase.js";
-import { GLOBAL_REVIEW_SCHEMA, REVIEW_SCHEMA, SELECTION_SCHEMA } from "./schemas.js";
-import { commitAll, commitsAhead, createPullRequest, pushBranch, rangeDiff, stageAllAndDiff } from "./scm.js";
-import { confirmWorkItemSelection } from "./selectionConfirmation.js";
+import { buildContextBlock, buildPhasePrompt, EXECUTION_PROMPT, GLOBAL_REVIEW_CHALLENGE_PROMPT, GLOBAL_REVIEW_PROMPT, GLOBAL_REVIEW_VALIDATION_PROMPT, GLOBAL_REVISION_PROMPT, REVIEW_CHALLENGE_PROMPT, REVIEW_PROMPT, REVIEW_VALIDATION_PROMPT, REVISION_PROMPT, SELECTION_PROMPT, } from "./prompts.js";
+import { createRunReporter } from "./reporter.js";
+import { runAgentPhase, } from "./runPhase.js";
+import { REVIEW_CHALLENGE_SCHEMA, REVIEW_DISCOVERY_SCHEMA, GLOBAL_REVIEW_SCHEMA, REVIEW_VALIDATION_SCHEMA, SELECTION_SCHEMA, } from "./schemas.js";
+import { commitAll, commitsAhead, createPullRequest, pushBranch, rangeDiff, stageAllAndDiff, } from "./scm.js";
+import { confirmWorkItemSelection, } from "./selectionConfirmation.js";
 import { createRunId } from "./time.js";
-import { filterAvailable, listGitHubIssues, resolveSelectedQueue } from "./workItems.js";
+import { filterAvailable, listGitHubIssues, resolveSelectedQueue, } from "./workItems.js";
 const MAX_CANDIDATES = 50;
 const EXCERPT_CHARS = 800;
+const CORRECTION_VALIDATION_MAX_ATTEMPTS = 3;
 export function defaultPipelineDependencies() {
     return {
         listIssues: listGitHubIssues,
         runPhase: runAgentPhase,
         pushBranch,
         createPullRequest,
-        confirmSelection: confirmWorkItemSelection
+        confirmSelection: confirmWorkItemSelection,
     };
 }
 /**
@@ -37,60 +40,74 @@ export async function runPipeline(input = {}, deps = defaultPipelineDependencies
     const nyxDir = getNyxDir(projectRoot);
     const configPath = input.configPath ?? path.join(nyxDir, "config.json");
     const config = await loadConfig(configPath);
-    const harness = input.harness ?? config.harness;
+    const baseAgent = resolveAgentProfile({
+        config,
+        cliHarness: input.harness,
+    });
     const runId = createRunId();
     const runDir = path.join(nyxDir, "runs", runId);
     await ensureDir(runDir);
-    console.log(pc.bold(`NyxAgent run ${runId}`));
-    console.log(`Harness: ${harness} · model: ${config.model} · review: ${config.review}`);
+    const reporter = input.reporter ?? createRunReporter({ verbose: input.verbose ?? false });
+    reporter.heading(`NyxAgent run ${runId}`);
+    reporter.info(`Harness: ${baseAgent.harness} · model: ${baseAgent.model} · review: ${config.review}`);
+    reporter.detail(`Config: ${relativeToProject(projectRoot, configPath)}`);
+    reporter.detail(`Artifacts: ${relativeToProject(projectRoot, runDir)}`);
+    reporter.detail(`Tracker: ${config.tracker.repo}`);
+    if (config.review_max_attempts !== undefined) {
+        reporter.warn("review_max_attempts is deprecated and ignored; use review_rounds.each/global instead.");
+    }
     const ledger = await readWorkItemLedger(nyxDir);
+    reporter.detail(`Completed work items already in ledger: ${ledger.completed_work_item_keys.length}`);
     // 1. Selection runs read-only in the main checkout, before any branch exists.
     const candidates = filterAvailable({
         candidates: await deps.listIssues({
             repo: config.tracker.repo,
             maxCandidates: MAX_CANDIDATES,
-            excerptChars: EXCERPT_CHARS
+            excerptChars: EXCERPT_CHARS,
         }),
-        completedKeys: ledger.completed_work_item_keys
+        completedKeys: ledger.completed_work_item_keys,
     });
+    reporter.detail(`Available work item candidates: ${candidates.length}`);
     if (candidates.length === 0) {
-        console.log("No open work items available. Nothing to do.");
+        reporter.info("No open work items available. Nothing to do.");
         return;
     }
     const proposed = await runSelection({
         projectRoot,
         runDir,
-        harness,
+        cliHarness: input.harness,
         config,
         candidates,
-        runPhase: deps.runPhase
+        runPhase: deps.runPhase,
+        reporter,
     });
     if (proposed.length === 0) {
-        console.log("Selection chose no work items. Nothing to do.");
+        reporter.info("Selection chose no work items. Nothing to do.");
         return;
     }
     const selected = await deps.confirmSelection({
         candidates,
         proposed,
         maxItems: config.max_iterations,
-        autoAccept: input.autoAcceptSelection ?? false
+        autoAccept: input.autoAcceptSelection ?? false,
     });
     if (selected.length === 0) {
-        console.log("No work items selected. Nothing to do.");
+        reporter.info("No work items selected. Nothing to do.");
         return;
     }
     const planned = selected.slice(0, config.max_iterations);
-    console.log(`Selected ${planned.length} work item(s):`);
+    reporter.info(`Selected ${planned.length} work item(s):`);
     for (const item of planned) {
-        console.log(`  - ${item.title} (#${item.number})`);
+        reporter.info(`  - ${item.title} (#${item.number})`);
     }
     // 2. One branch + worktree per run (created only now that there is work).
     const git = await setUpRunWorktree({
         projectRoot,
         runId,
-        base: config.base_branch
+        base: config.base_branch,
     });
-    console.log(`Branch ${git.branch} (base ${git.base})`);
+    reporter.info(`Branch ${git.branch} (base ${git.base})`);
+    reporter.detail(`Worktree: ${relativeToProject(projectRoot, git.worktree)}`);
     let success = false;
     let producedCommits = false;
     let currentLedger = ledger;
@@ -100,40 +117,43 @@ export async function runPipeline(input = {}, deps = defaultPipelineDependencies
         for (const [index, item] of planned.entries()) {
             const iterationNumber = index + 1;
             const iterationDir = path.join(runDir, "iterations", String(iterationNumber).padStart(3, "0"));
-            console.log(pc.cyan(`\n[${iterationNumber}/${planned.length}] ${item.title} (#${item.number})`));
+            reporter.section(`\n[${iterationNumber}/${planned.length}] ${item.title} (#${item.number})`);
             await runExecution({
                 iterationDir,
                 item,
                 guidance: executionGuidance,
                 git,
-                harness,
+                cliHarness: input.harness,
                 config,
-                runPhase: deps.runPhase
+                runPhase: deps.runPhase,
+                reporter,
             });
             if (config.review === "each" || config.review === "both") {
                 await runReviewLoop({
                     iterationDir,
                     item,
                     git,
-                    harness,
+                    cliHarness: input.harness,
                     config,
-                    maxAttempts: config.review_max_attempts,
-                    runPhase: deps.runPhase
+                    rounds: config.review_rounds.each,
+                    runPhase: deps.runPhase,
+                    reporter,
                 });
             }
             const { committed } = await commitAll({
                 cwd: git.worktree,
-                message: buildCommitMessage(item)
+                message: buildCommitMessage(item),
             });
             if (committed) {
                 producedCommits = true;
+                reporter.detail(`Committed work item #${item.number}.`);
             }
             else {
-                console.log(pc.yellow("  No changes to commit for this item."));
+                reporter.warn("  No changes to commit for this item.");
             }
             currentLedger = markWorkItemCompleted({
                 ledger: currentLedger,
-                workItem: item
+                workItem: item,
             });
             await writeWorkItemLedger(nyxDir, currentLedger);
             completed.push(item);
@@ -142,20 +162,24 @@ export async function runPipeline(input = {}, deps = defaultPipelineDependencies
             const corrections = await runGlobalReviewLoop({
                 runDir,
                 git,
-                harness,
+                completed,
+                cliHarness: input.harness,
                 config,
-                maxAttempts: config.review_max_attempts,
-                runPhase: deps.runPhase
+                rounds: config.review_rounds.global,
+                runPhase: deps.runPhase,
+                reporter,
             });
             if (corrections) {
                 producedCommits = true;
             }
         }
-        if (!producedCommits || (await commitsAhead(git.worktree, git.base)) === 0) {
-            console.log("\nRun produced no commits; skipping pull request.");
+        if (!producedCommits ||
+            (await commitsAhead(git.worktree, git.base)) === 0) {
+            reporter.info("\nRun produced no commits; skipping pull request.");
             success = true;
             return;
         }
+        reporter.detail(`Pushing branch ${git.branch}.`);
         await deps.pushBranch({ cwd: git.worktree, branch: git.branch });
         const prUrl = await deps.createPullRequest({
             cwd: git.worktree,
@@ -163,9 +187,9 @@ export async function runPipeline(input = {}, deps = defaultPipelineDependencies
             base: git.base,
             head: git.branch,
             title: buildPrTitle(completed),
-            body: buildPrBody(completed)
+            body: buildPrBody(completed),
         });
-        console.log(pc.green(`\nPull request opened: ${prUrl}`));
+        reporter.success(`\nPull request opened: ${prUrl}`);
         success = true;
     }
     catch (error) {
@@ -179,7 +203,8 @@ export async function runPipeline(input = {}, deps = defaultPipelineDependencies
             producedCommits,
             completed,
             config,
-            deps
+            deps,
+            reporter,
         });
         throw error;
     }
@@ -211,14 +236,15 @@ async function salvageFailedRun(input) {
         }
     }
     if (ahead === 0) {
-        console.log(pc.red(`\nRun failed. Branch ${input.git.branch} and worktree kept for debugging: ${location}`));
+        input.reporter.error(`\nRun failed. Branch ${input.git.branch} and worktree kept for debugging: ${location}`);
         return;
     }
     const reason = input.error instanceof Error ? input.error.message : String(input.error);
     try {
+        input.reporter.detail(`Pushing failed run branch ${input.git.branch}.`);
         await input.deps.pushBranch({
             cwd: input.git.worktree,
-            branch: input.git.branch
+            branch: input.git.branch,
         });
         const url = await input.deps.createPullRequest({
             cwd: input.git.worktree,
@@ -227,20 +253,24 @@ async function salvageFailedRun(input) {
             head: input.git.branch,
             title: buildDraftPrTitle(input.completed),
             body: buildDraftPrBody(input.completed, reason),
-            draft: true
+            draft: true,
         });
-        console.log(pc.yellow(`\nRun failed, but the work was salvaged into a DRAFT pull request: ${url}`));
-        console.log(pc.yellow(`Branch ${input.git.branch} and worktree kept: ${location}`));
+        input.reporter.warn(`\nRun failed, but the work was salvaged into a DRAFT pull request: ${url}`);
+        input.reporter.warn(`Branch ${input.git.branch} and worktree kept: ${location}`);
     }
     catch (salvageError) {
         const detail = salvageError instanceof Error
             ? salvageError.message
             : String(salvageError);
-        console.log(pc.red(`\nRun failed, and salvaging the work into a draft pull request also failed: ${detail}`));
-        console.log(pc.red(`Branch ${input.git.branch} and worktree kept for debugging: ${location}`));
+        input.reporter.error(`\nRun failed, and salvaging the work into a draft pull request also failed: ${detail}`);
+        input.reporter.error(`Branch ${input.git.branch} and worktree kept for debugging: ${location}`);
     }
 }
 async function runSelection(input) {
+    const agent = resolveAgentProfile({
+        config: input.config,
+        cliHarness: input.cliHarness,
+    });
     const context = buildContextBlock([
         ["Repository", input.config.tracker.repo],
         ["Max work items this run", input.config.max_iterations],
@@ -251,24 +281,25 @@ async function runSelection(input) {
                 number: candidate.number,
                 title: candidate.title,
                 labels: candidate.labels,
-                excerpt: candidate.excerpt
-            }))
-        ]
+                excerpt: candidate.excerpt,
+            })),
+        ],
     ]);
     const result = await input.runPhase({
         phaseId: "selection",
         phaseDir: path.join(input.runDir, "selection"),
         workdir: input.projectRoot,
-        harness: input.harness,
-        model: input.config.model,
-        reasoning: input.config.reasoning_effort,
+        harness: agent.harness,
+        model: agent.model,
+        reasoning: agent.reasoning_effort,
         capability: "readonly",
         prompt: buildPhasePrompt({
             guidance: SELECTION_PROMPT,
             context,
-            schema: SELECTION_SCHEMA
+            schema: SELECTION_SCHEMA,
         }),
-        schema: SELECTION_SCHEMA
+        schema: SELECTION_SCHEMA,
+        reporter: input.reporter,
     });
     if (!result.ok) {
         throw new Error(result.error);
@@ -279,7 +310,7 @@ async function runSelection(input) {
     }
     const resolved = resolveSelectedQueue({
         keys: value.work_item_keys,
-        candidates: input.candidates
+        candidates: input.candidates,
     });
     if (!resolved.ok) {
         throw new Error(`Selection produced an invalid queue: ${resolved.error}`);
@@ -287,142 +318,536 @@ async function runSelection(input) {
     return resolved.queue;
 }
 async function runExecution(input) {
+    const agent = resolveAgentProfile({
+        config: input.config,
+        cliHarness: input.cliHarness,
+        phase: "execution",
+    });
     const context = buildContextBlock([
         ["Work item", workItemSummary(input.item)],
         ["Issue description", input.item.excerpt ?? "(no description provided)"],
         ["Working directory", input.git.worktree],
-        ["Branch", `${input.git.branch} (base ${input.git.base})`]
+        ["Branch", `${input.git.branch} (base ${input.git.base})`],
     ]);
     const result = await input.runPhase({
         phaseId: "execution",
         phaseDir: path.join(input.iterationDir, "execution"),
         workdir: input.git.worktree,
-        harness: input.harness,
-        model: input.config.model,
-        reasoning: input.config.reasoning_effort,
+        harness: agent.harness,
+        model: agent.model,
+        reasoning: agent.reasoning_effort,
         capability: "write",
-        prompt: buildPhasePrompt({ guidance: input.guidance, context })
+        prompt: buildPhasePrompt({ guidance: input.guidance, context }),
+        reporter: input.reporter,
     });
     if (!result.ok) {
         throw new Error(result.error);
     }
 }
 async function runReviewLoop(input) {
-    for (let attempt = 1; attempt <= input.maxAttempts; attempt += 1) {
-        const diff = await stageAllAndDiff(input.git.worktree);
-        const reviewResult = await input.runPhase({
+    const agent = resolveAgentProfile({
+        config: input.config,
+        cliHarness: input.cliHarness,
+        phase: "review",
+    });
+    const validationHistory = [];
+    for (let round = 1; round <= input.rounds; round += 1) {
+        const roundDir = path.join(input.iterationDir, `review-round-${round}`);
+        const discoveryPack = await createReviewContextPack({
+            dir: path.join(roundDir, "discovery", "review-context"),
+            git: input.git,
+            scope: "item",
+            workItems: [input.item],
+            validations: validationHistory,
+        });
+        const discoveryResult = await input.runPhase({
             phaseId: "review",
-            phaseDir: path.join(input.iterationDir, `review-${attempt}`),
+            phaseDir: path.join(roundDir, "discovery"),
             workdir: input.git.worktree,
-            harness: input.harness,
-            model: input.config.model,
-            reasoning: input.config.reasoning_effort,
+            harness: agent.harness,
+            model: agent.model,
+            reasoning: agent.reasoning_effort,
             capability: "readonly",
             prompt: buildPhasePrompt({
                 guidance: REVIEW_PROMPT,
                 context: buildContextBlock([
                     ["Work item", workItemSummary(input.item)],
-                    ["Uncommitted changes (diff)", truncateForPrompt(diff || "(no changes)")]
+                    ["Review round", round],
+                    ["Review context", reviewContextSummary(discoveryPack)],
                 ]),
-                schema: REVIEW_SCHEMA
+                schema: REVIEW_DISCOVERY_SCHEMA,
             }),
-            schema: REVIEW_SCHEMA
+            schema: REVIEW_DISCOVERY_SCHEMA,
+            reporter: input.reporter,
         });
-        if (!reviewResult.ok) {
-            throw new Error(reviewResult.error);
+        if (!discoveryResult.ok) {
+            throw new Error(discoveryResult.error);
         }
-        const review = reviewResult.result;
-        console.log(`  review: ${review.outcome}`);
-        if (review.outcome === "approved") {
-            return;
+        const discovery = discoveryResult.result;
+        const proposedBlockers = normalizeFindings(discovery.blockers);
+        input.reporter.info(`  review round ${round}: ${proposedBlockers.length} proposed blocker(s)`);
+        const challenge = await runReviewChallenge({
+            phaseId: "review_challenge",
+            phaseDir: path.join(roundDir, "challenge"),
+            workdir: input.git.worktree,
+            agent,
+            runPhase: input.runPhase,
+            reporter: input.reporter,
+            guidance: REVIEW_CHALLENGE_PROMPT,
+            contextEntries: [
+                ["Work item", workItemSummary(input.item)],
+                ["Review round", round],
+                ["Review context", reviewContextSummary(discoveryPack)],
+                ["Proposed blockers", proposedBlockers],
+                ["Rejected findings from discovery", discovery.rejected_findings ?? []],
+            ],
+        });
+        input.reporter.info(`  review round ${round}: ${challenge.blockers.length} verified blocker(s)`);
+        await runCorrectionValidationLoop({
+            scope: "item",
+            roundDir,
+            git: input.git,
+            workItems: [input.item],
+            validationHistory,
+            blockers: challenge.blockers,
+            agent,
+            runPhase: input.runPhase,
+            reporter: input.reporter,
+            revisionPhaseId: "revision",
+            validationPhaseId: "review_validation",
+            revisionGuidance: REVISION_PROMPT,
+            validationGuidance: REVIEW_VALIDATION_PROMPT,
+            failureMessage: (blockers) => `Review for #${input.item.number} has unresolved blocker(s) after ${CORRECTION_VALIDATION_MAX_ATTEMPTS} correction validation attempts:${formatBlockers(blockers)}`,
+        });
+    }
+}
+async function runGlobalReviewLoop(input) {
+    let committedCorrections = false;
+    const validationHistory = [];
+    for (let round = 1; round <= input.rounds; round += 1) {
+        const roundDir = path.join(input.runDir, "final", `global-round-${round}`);
+        const discoveryPack = await createReviewContextPack({
+            dir: path.join(roundDir, "discovery", "review-context"),
+            git: input.git,
+            scope: "global",
+            workItems: input.completed,
+            validations: validationHistory,
+        });
+        const discoveries = [];
+        for (const role of globalReviewRoles) {
+            const roleAgent = resolveAgentProfile({
+                config: input.config,
+                cliHarness: input.cliHarness,
+                phase: "global_review",
+                role,
+            });
+            const reviewResult = await input.runPhase({
+                phaseId: "global_review",
+                phaseDir: path.join(roundDir, "discovery", role),
+                workdir: input.git.worktree,
+                harness: roleAgent.harness,
+                model: roleAgent.model,
+                reasoning: roleAgent.reasoning_effort,
+                capability: "readonly",
+                prompt: buildPhasePrompt({
+                    guidance: buildGlobalReviewGuidance(role),
+                    context: buildContextBlock([
+                        ["Run branch", `${input.git.branch} (base ${input.git.base})`],
+                        ["Review round", round],
+                        ["Reviewer role", role],
+                        ["Review context", reviewContextSummary(discoveryPack)],
+                    ]),
+                    schema: GLOBAL_REVIEW_SCHEMA,
+                }),
+                schema: GLOBAL_REVIEW_SCHEMA,
+                reporter: input.reporter,
+            });
+            if (!reviewResult.ok) {
+                throw new Error(reviewResult.error);
+            }
+            discoveries.push(reviewResult.result);
         }
-        if (attempt === input.maxAttempts) {
-            throw new Error(`Review for #${input.item.number} not approved after ${input.maxAttempts} attempts: ${review.summary}${formatRequiredChanges(review.required_changes)}`);
+        const aggregated = aggregateDiscoveries(discoveries);
+        input.reporter.info(`global review round ${round}: ${aggregated.blockers.length} proposed blocker(s)`);
+        const challengeAgent = resolveAgentProfile({
+            config: input.config,
+            cliHarness: input.cliHarness,
+            phase: "global_review",
+        });
+        const challenge = await runReviewChallenge({
+            phaseId: "global_review_challenge",
+            phaseDir: path.join(roundDir, "challenge"),
+            workdir: input.git.worktree,
+            agent: challengeAgent,
+            runPhase: input.runPhase,
+            reporter: input.reporter,
+            guidance: GLOBAL_REVIEW_CHALLENGE_PROMPT,
+            contextEntries: [
+                ["Run branch", `${input.git.branch} (base ${input.git.base})`],
+                ["Review round", round],
+                ["Review context", reviewContextSummary(discoveryPack)],
+                ["Aggregated proposed blockers", aggregated.blockers],
+                ["Aggregated rejected findings", aggregated.rejected_findings],
+            ],
+        });
+        input.reporter.info(`global review round ${round}: ${challenge.blockers.length} verified blocker(s)`);
+        const roundCommittedCorrections = await runCorrectionValidationLoop({
+            scope: "global",
+            roundDir,
+            git: input.git,
+            workItems: input.completed,
+            validationHistory,
+            blockers: challenge.blockers,
+            agent: challengeAgent,
+            runPhase: input.runPhase,
+            reporter: input.reporter,
+            revisionPhaseId: "global_revision",
+            validationPhaseId: "global_review_validation",
+            revisionGuidance: GLOBAL_REVISION_PROMPT,
+            validationGuidance: GLOBAL_REVIEW_VALIDATION_PROMPT,
+            commitMessage: "Apply global review corrections",
+            failureMessage: (blockers) => `Global review has unresolved blocker(s) after ${CORRECTION_VALIDATION_MAX_ATTEMPTS} correction validation attempts:${formatBlockers(blockers)}`,
+        });
+        if (roundCommittedCorrections) {
+            committedCorrections = true;
         }
+    }
+    return committedCorrections;
+}
+function resolveAgentProfile(input) {
+    const profile = {
+        harness: input.cliHarness ?? input.config.harness,
+        model: input.config.model,
+        reasoning_effort: input.config.reasoning_effort,
+    };
+    const phaseOverride = input.phase
+        ? phaseAgentOverride(input.config, input.phase)
+        : undefined;
+    const roleOverride = input.role
+        ? input.config.agents?.global_review?.roles?.[input.role]
+        : undefined;
+    return applyAgentOverride(applyAgentOverride(profile, phaseOverride), roleOverride);
+}
+function phaseAgentOverride(config, phase) {
+    if (phase === "execution") {
+        return config.agents?.execution;
+    }
+    if (phase === "review") {
+        return config.agents?.review;
+    }
+    return config.agents?.global_review;
+}
+function applyAgentOverride(profile, override) {
+    if (!override) {
+        return profile;
+    }
+    return {
+        harness: override.harness ?? profile.harness,
+        model: override.model ?? profile.model,
+        reasoning_effort: override.reasoning_effort ?? profile.reasoning_effort,
+    };
+}
+function buildGlobalReviewGuidance(role) {
+    const focus = {
+        "diff-contract": "Focus on the public contract of the diff: APIs, CLI behavior, schemas, config compatibility, and generated artifacts.",
+        integration: "Focus on integration across touched modules, phase sequencing, artifact paths, and cross-item behavior.",
+        "domain-invariants": "Focus on NyxAgent workflow invariants: engine-owned git side effects, read-only review phases, closed pipeline control flow, and review semantics.",
+        "tests-validation": "Focus on test coverage, validation evidence, failure modes, and whether the committed changes are demonstrably safe.",
+    };
+    return `${GLOBAL_REVIEW_PROMPT}\n\nRole focus (${role}): ${focus[role]}`;
+}
+async function runReviewChallenge(input) {
+    const result = await input.runPhase({
+        phaseId: input.phaseId,
+        phaseDir: input.phaseDir,
+        workdir: input.workdir,
+        harness: input.agent.harness,
+        model: input.agent.model,
+        reasoning: input.agent.reasoning_effort,
+        capability: "readonly",
+        prompt: buildPhasePrompt({
+            guidance: input.guidance,
+            context: buildContextBlock(input.contextEntries),
+            schema: REVIEW_CHALLENGE_SCHEMA,
+        }),
+        schema: REVIEW_CHALLENGE_SCHEMA,
+        reporter: input.reporter,
+    });
+    if (!result.ok) {
+        throw new Error(result.error);
+    }
+    const challenge = result.result;
+    return {
+        ...challenge,
+        blockers: normalizeFindings(challenge.blockers),
+        rejected_findings: normalizeFindings(challenge.rejected_findings),
+    };
+}
+async function runCorrectionValidationLoop(input) {
+    let pending = normalizeFindings(input.blockers);
+    let committedCorrections = false;
+    if (pending.length === 0) {
+        return committedCorrections;
+    }
+    for (let attempt = 1; attempt <= CORRECTION_VALIDATION_MAX_ATTEMPTS; attempt += 1) {
+        const revisionPack = await createReviewContextPack({
+            dir: path.join(input.roundDir, `${input.revisionPhaseId}-${attempt}`, "review-context"),
+            git: input.git,
+            scope: input.scope,
+            workItems: input.workItems,
+            validations: input.validationHistory,
+        });
         const revision = await input.runPhase({
-            phaseId: "revision",
-            phaseDir: path.join(input.iterationDir, `revision-${attempt}`),
+            phaseId: input.revisionPhaseId,
+            phaseDir: path.join(input.roundDir, `${input.revisionPhaseId}-${attempt}`),
             workdir: input.git.worktree,
-            harness: input.harness,
-            model: input.config.model,
-            reasoning: input.config.reasoning_effort,
+            harness: input.agent.harness,
+            model: input.agent.model,
+            reasoning: input.agent.reasoning_effort,
             capability: "write",
             prompt: buildPhasePrompt({
-                guidance: REVISION_PROMPT,
+                guidance: input.revisionGuidance,
                 context: buildContextBlock([
-                    ["Work item", workItemSummary(input.item)],
-                    ["Required changes", review.required_changes ?? []]
-                ])
-            })
+                    ["Review context", reviewContextSummary(revisionPack)],
+                    [
+                        "Correction attempt",
+                        `${attempt}/${CORRECTION_VALIDATION_MAX_ATTEMPTS}`,
+                    ],
+                    ["Verified blockers", pending],
+                ]),
+            }),
+            reporter: input.reporter,
         });
         if (!revision.ok) {
             throw new Error(revision.error);
         }
-    }
-}
-async function runGlobalReviewLoop(input) {
-    let committedCorrections = false;
-    for (let attempt = 1; attempt <= input.maxAttempts; attempt += 1) {
-        const diff = await rangeDiff(input.git.worktree, input.git.base);
-        const reviewResult = await input.runPhase({
-            phaseId: "global_review",
-            phaseDir: path.join(input.runDir, "final", `global-review-${attempt}`),
+        if (input.commitMessage) {
+            const { committed } = await commitAll({
+                cwd: input.git.worktree,
+                message: input.commitMessage,
+            });
+            if (committed) {
+                committedCorrections = true;
+                input.reporter.detail("Committed global review corrections.");
+            }
+        }
+        const validationPack = await createReviewContextPack({
+            dir: path.join(input.roundDir, `${input.validationPhaseId}-${attempt}`, "review-context"),
+            git: input.git,
+            scope: input.scope,
+            workItems: input.workItems,
+            validations: input.validationHistory,
+        });
+        const validationResult = await input.runPhase({
+            phaseId: input.validationPhaseId,
+            phaseDir: path.join(input.roundDir, `${input.validationPhaseId}-${attempt}`),
             workdir: input.git.worktree,
-            harness: input.harness,
-            model: input.config.model,
-            reasoning: input.config.reasoning_effort,
+            harness: input.agent.harness,
+            model: input.agent.model,
+            reasoning: input.agent.reasoning_effort,
             capability: "readonly",
             prompt: buildPhasePrompt({
-                guidance: GLOBAL_REVIEW_PROMPT,
+                guidance: input.validationGuidance,
                 context: buildContextBlock([
-                    ["Run branch", `${input.git.branch} (base ${input.git.base})`],
+                    ["Review context", reviewContextSummary(validationPack)],
                     [
-                        "Combined run diff (base...HEAD)",
-                        truncateForPrompt(diff || "(no changes)")
-                    ]
+                        "Correction attempt",
+                        `${attempt}/${CORRECTION_VALIDATION_MAX_ATTEMPTS}`,
+                    ],
+                    ["Validated blockers", pending],
                 ]),
-                schema: GLOBAL_REVIEW_SCHEMA
+                schema: REVIEW_VALIDATION_SCHEMA,
             }),
-            schema: GLOBAL_REVIEW_SCHEMA
+            schema: REVIEW_VALIDATION_SCHEMA,
+            reporter: input.reporter,
         });
-        if (!reviewResult.ok) {
-            throw new Error(reviewResult.error);
+        if (!validationResult.ok) {
+            throw new Error(validationResult.error);
         }
-        const review = reviewResult.result;
-        console.log(`global review: ${review.outcome}`);
-        if (review.outcome === "approved") {
+        const validation = validationResult.result;
+        const validations = normalizeValidations(validation.validations);
+        input.validationHistory.push(...validations);
+        pending = blockersNeedingCorrection(pending, validations);
+        input.reporter.info(`${input.scope} validation attempt ${attempt}: ${pending.length} unresolved blocker(s)`);
+        if (pending.length === 0) {
             return committedCorrections;
         }
-        if (attempt === input.maxAttempts) {
-            throw new Error(`Global review not approved after ${input.maxAttempts} attempts: ${review.summary}${formatRequiredChanges(review.required_changes)}`);
+    }
+    throw new Error(input.failureMessage(pending));
+}
+async function createReviewContextPack(input) {
+    await ensureDir(input.dir);
+    const patch = input.scope === "item"
+        ? await stageAllAndDiff(input.git.worktree)
+        : await rangeDiff(input.git.worktree, input.git.base);
+    const diffstat = input.scope === "item"
+        ? await gitOutput(input.git.worktree, ["diff", "--cached", "--stat"], "diff --cached --stat")
+        : await gitOutput(input.git.worktree, ["diff", "--stat", `${input.git.base}..HEAD`], "diff --stat range");
+    const files = input.scope === "item"
+        ? await gitOutput(input.git.worktree, ["diff", "--cached", "--name-only"], "diff --cached --name-only")
+        : await gitOutput(input.git.worktree, ["diff", "--name-only", `${input.git.base}..HEAD`], "diff --name-only range");
+    const commits = await gitOutput(input.git.worktree, ["log", "--oneline", `${input.git.base}..HEAD`], "log range");
+    const pack = {
+        dir: input.dir,
+        summaryPath: path.join(input.dir, "summary.md"),
+        patchPath: path.join(input.dir, "combined.patch"),
+        diffstatPath: path.join(input.dir, "diffstat.txt"),
+        commitsPath: path.join(input.dir, "commits.txt"),
+        filesPath: path.join(input.dir, "modified-files.txt"),
+        issuesPath: path.join(input.dir, "issues.json"),
+        validationsPath: path.join(input.dir, "validations.json"),
+    };
+    await writeText(pack.patchPath, textOrPlaceholder(patch, "(no changes)"));
+    await writeText(pack.diffstatPath, textOrPlaceholder(diffstat, "(no diffstat)"));
+    await writeText(pack.commitsPath, textOrPlaceholder(commits, "(no commits yet)"));
+    await writeText(pack.filesPath, textOrPlaceholder(files, "(no modified files)"));
+    await writeText(pack.issuesPath, `${JSON.stringify((input.workItems ?? []).map(workItemSummary), null, 2)}\n`);
+    await writeText(pack.validationsPath, `${JSON.stringify(input.validations, null, 2)}\n`);
+    await writeText(pack.summaryPath, [
+        "# NyxAgent review context",
+        "",
+        `Scope: ${input.scope}`,
+        `Branch: ${input.git.branch}`,
+        `Base: ${input.git.base}`,
+        "",
+        "Artifacts:",
+        `- combined patch: ${pack.patchPath}`,
+        `- diffstat: ${pack.diffstatPath}`,
+        `- modified files: ${pack.filesPath}`,
+        `- commits: ${pack.commitsPath}`,
+        `- issues: ${pack.issuesPath}`,
+        `- validations: ${pack.validationsPath}`,
+        "",
+        "Inspect these files, or run the corresponding git commands in the working directory.",
+    ].join("\n"));
+    return pack;
+}
+async function gitOutput(cwd, args, label) {
+    const result = await execa("git", args, { cwd, reject: false });
+    if (result.exitCode !== 0) {
+        const detail = (result.stderr || result.stdout || "unknown error").trim();
+        throw new Error(`git ${label} failed: ${detail}`);
+    }
+    return result.stdout;
+}
+function reviewContextSummary(pack) {
+    return {
+        directory: pack.dir,
+        summary: pack.summaryPath,
+        combined_patch: pack.patchPath,
+        diffstat: pack.diffstatPath,
+        modified_files: pack.filesPath,
+        commits: pack.commitsPath,
+        issues: pack.issuesPath,
+        validations: pack.validationsPath,
+    };
+}
+function aggregateDiscoveries(discoveries) {
+    return {
+        summary: discoveries
+            .map((discovery) => discovery.summary)
+            .filter((summary) => Boolean(summary))
+            .join("\n"),
+        blockers: dedupeFindings(discoveries.flatMap((discovery) => normalizeFindings(discovery.blockers))),
+        test_gaps: dedupeFindings(discoveries.flatMap((discovery) => normalizeFindings(discovery.test_gaps))),
+        advisory_findings: dedupeFindings(discoveries.flatMap((discovery) => normalizeFindings(discovery.advisory_findings))),
+        uncertain_findings: dedupeFindings(discoveries.flatMap((discovery) => normalizeFindings(discovery.uncertain_findings))),
+        rejected_findings: dedupeFindings(discoveries.flatMap((discovery) => normalizeFindings(discovery.rejected_findings))),
+    };
+}
+function blockersNeedingCorrection(pending, validations) {
+    const byTitle = new Map(pending.map((blocker) => [normalizeTitle(blocker.title), blocker]));
+    const seen = new Set();
+    const unresolved = [];
+    for (const validation of validations) {
+        const key = normalizeTitle(validation.blocker_title);
+        seen.add(key);
+        if (validation.status === "unresolved") {
+            const original = byTitle.get(key);
+            if (original) {
+                unresolved.push({
+                    ...original,
+                    required_change: validation.required_change ?? original.required_change,
+                    evidence: normalizeEvidence(validation.evidence, original.evidence),
+                });
+            }
+            continue;
+        }
+        if (validation.status === "regression_from_correction") {
+            unresolved.push({
+                title: validation.blocker_title,
+                required_change: validation.required_change ??
+                    `Fix regression from correction: ${validation.blocker_title}`,
+                confidence: "high",
+                evidence: normalizeEvidence(validation.evidence),
+            });
         }
-        const revision = await input.runPhase({
-            phaseId: "global_revision",
-            phaseDir: path.join(input.runDir, "final", `global-revision-${attempt}`),
-            workdir: input.git.worktree,
-            harness: input.harness,
-            model: input.config.model,
-            reasoning: input.config.reasoning_effort,
-            capability: "write",
-            prompt: buildPhasePrompt({
-                guidance: GLOBAL_REVISION_PROMPT,
-                context: buildContextBlock([
-                    ["Required changes", review.required_changes ?? []]
-                ])
-            })
-        });
-        if (!revision.ok) {
-            throw new Error(revision.error);
+    }
+    for (const blocker of pending) {
+        if (!seen.has(normalizeTitle(blocker.title))) {
+            unresolved.push(blocker);
         }
-        const { committed } = await commitAll({
-            cwd: input.git.worktree,
-            message: "Apply global review corrections"
-        });
-        if (committed) {
-            committedCorrections = true;
+    }
+    return dedupeFindings(unresolved);
+}
+function normalizeFindings(findings) {
+    return dedupeFindings((findings ?? [])
+        .filter((finding) => finding.title && finding.required_change)
+        .map((finding) => ({
+        title: finding.title,
+        required_change: finding.required_change,
+        confidence: normalizeConfidence(finding.confidence),
+        evidence: normalizeEvidence(finding.evidence),
+    })));
+}
+function normalizeValidations(validations) {
+    const allowed = new Set([
+        "resolved",
+        "unresolved",
+        "false_positive",
+        "regression_from_correction",
+    ]);
+    return (validations ?? [])
+        .filter((validation) => validation.blocker_title && allowed.has(validation.status))
+        .map((validation) => ({
+        ...validation,
+        evidence: normalizeEvidence(validation.evidence),
+    }));
+}
+function dedupeFindings(findings) {
+    const seen = new Set();
+    const deduped = [];
+    for (const finding of findings) {
+        const key = `${normalizeTitle(finding.title)}\n${finding.required_change.trim().toLowerCase()}`;
+        if (seen.has(key)) {
+            continue;
         }
+        seen.add(key);
+        deduped.push(finding);
     }
-    return committedCorrections;
+    return deduped;
+}
+function normalizeEvidence(evidence, fallback) {
+    if (Array.isArray(evidence) && evidence.length > 0) {
+        return evidence;
+    }
+    if (fallback && fallback.length > 0) {
+        return fallback;
+    }
+    return [{ detail: "No evidence provided." }];
+}
+function normalizeConfidence(value) {
+    if (value === "low" || value === "medium" || value === "high") {
+        return value;
+    }
+    return "medium";
+}
+function normalizeTitle(value) {
+    return value.trim().toLowerCase();
+}
+function textOrPlaceholder(text, placeholder) {
+    const trimmed = text.trim();
+    return `${trimmed.length > 0 ? trimmed : placeholder}\n`;
 }
 async function loadExecutionGuidance(nyxDir) {
     const override = path.join(nyxDir, "prompts", "execution.md");
@@ -441,7 +866,7 @@ function workItemSummary(item) {
         title: item.title,
         locator: item.source.locator,
         url: item.url,
-        labels: item.labels
+        labels: item.labels,
     };
 }
 function buildCommitMessage(item) {
@@ -454,7 +879,9 @@ function buildPrTitle(items) {
     return `NyxAgent: ${items.length} work items`;
 }
 function buildPrBody(items) {
-    const list = items.map((item) => `- ${item.title} (#${item.number})`).join("\n");
+    const list = items
+        .map((item) => `- ${item.title} (#${item.number})`)
+        .join("\n");
     const closes = items.map((item) => `Closes #${item.number}`).join("\n");
     return [
         "Automated changes by NyxAgent.",
@@ -463,7 +890,7 @@ function buildPrBody(items) {
         "",
         list,
         "",
-        closes
+        closes,
     ].join("\n");
 }
 function buildDraftPrTitle(items) {
@@ -477,15 +904,15 @@ function buildDraftPrBody(items, reason) {
         "",
         `**Why the run failed:** ${reason}`,
         "",
-        buildPrBody(items)
+        buildPrBody(items),
     ].join("\n");
 }
-/** Render review `required_changes` as a bullet list to append to a failure message. */
-function formatRequiredChanges(changes) {
-    if (!changes || changes.length === 0) {
+/** Render unresolved blockers as a bullet list to append to a failure message. */
+function formatBlockers(blockers) {
+    if (blockers.length === 0) {
         return "";
     }
-    return `\n\nUnresolved review feedback:\n${changes
-        .map((change) => `- ${change}`)
+    return `\n\nUnresolved review blockers:\n${blockers
+        .map((blocker) => `- ${blocker.title}: ${blocker.required_change}`)
         .join("\n")}`;
 }