@nyxa/nyx-agent 0.7.0 → 0.8.0

package/README.md

@@ -11,7 +11,8 @@ For every run NyxAgent:
    confirm the proposed checklist.
 2. For each selected issue, in an isolated git **worktree**:
    - **implements** it (the agent — the only customizable prompt),
-   - optionally **reviews** and **revises** it (bounded loop),
+   - optionally **reviews** it in bounded discovery rounds, then revises only
+     verified blockers with locked validation,
    - **commits** the change (the engine, deterministically).
 3. Optionally runs a **global review** across the whole run.
 4. **Pushes** the run branch and **opens one pull request** (the engine).
@@ -45,7 +46,7 @@ nyxagent update               # self-update to the latest published version
   "model": "gpt-5.5",
   "reasoning_effort": "medium",
   "review": "each",
-  "review_max_attempts": 4,
+  "review_rounds": { "each": 1, "global": 1 },
   "tracker": { "type": "github", "repo": "owner/repo" },
   "base_branch": "main",
   "max_iterations": 5
@@ -54,12 +55,19 @@ nyxagent update               # self-update to the latest published version
 
 - `harness`: `codex` or `claude` (override per run with `--harness`).
 - `review`: `each` (per task), `all` (global only), `both`, or `none`.
-- `review_max_attempts`: review+revise rounds per stage before the run fails (default 4).
+- `review_rounds.each`: fresh per-task discovery rounds (default 1).
+- `review_rounds.global`: fresh global discovery rounds (default 1).
+- `review_max_attempts`: deprecated; accepted for old configs with a warning, but
+  ignored by the review loop.
+- `agents.execution`, `agents.review`, `agents.global_review`, and
+  `agents.global_review.roles.<role>` can override `harness`, `model`, and
+  `reasoning_effort` for specialized phases. Global review roles are
+  `diff-contract`, `integration`, `domain-invariants`, and `tests-validation`.
 - `base_branch`: optional; defaults to the current branch at run time.
 
-If a run fails review after exhausting its attempts but has already produced
+If a run fails review validation but has already produced
 commits, NyxAgent pushes the branch and opens a **draft** pull request with the
-unresolved feedback, so the work is never stranded on an orphaned branch.
+unresolved blockers, so the work is never stranded on an orphaned branch.
 
 ## Requirements
 

package/dist/cli.js

@@ -20,7 +20,9 @@ program
     .option("--model <name>", "model name")
     .option("--reasoning-effort <level>", "reasoning effort (default: medium)")
     .option("--review <mode>", "review strategy: each, all, both, or none")
-    .option("--review-attempts <count>", "max review attempts per stage (default: 4)")
+    .option("--review-rounds-each <count>", "per-work-item review discovery rounds (default: 1)")
+    .option("--review-rounds-global <count>", "global review discovery rounds (default: 1)")
+    .option("--review-attempts <count>", "deprecated alias for both review round counts")
     .option("--repo <owner/repo>", "GitHub repository")
     .option("--base-branch <branch>", "base branch (default: current branch)")
     .option("--max-iterations <count>", "maximum work items per run")

package/dist/commands/init.js

@@ -2,8 +2,8 @@
 import path from "node:path";
 import { input, number as numberPrompt, select } from "@inquirer/prompts";
 import pc from "picocolors";
-import { harnessNames, reviewModes } from "../config/schema.js";
-import { ensureDir, pathExists, readText, writeText } from "../runtime/files.js";
+import { harnessNames, reviewModes, } from "../config/schema.js";
+import { ensureDir, pathExists, readText, writeText, } from "../runtime/files.js";
 import { getNyxDir, relativeToProject } from "../runtime/paths.js";
 import { EXECUTION_PROMPT_FILE } from "../runtime/prompts.js";
 const DEFAULT_CODEX_MODEL = "gpt-5.5";
@@ -17,7 +17,7 @@ const GITIGNORE_ENTRIES = [
     ".nyxagent/state.json",
     ".nyxagent/config.json",
     ".nyxagent/config.toml",
-    ".nyxagent/prompts/"
+    ".nyxagent/prompts/",
 ];
 export async function initCommand(options, projectRoot = process.cwd()) {
     const root = path.resolve(projectRoot);
@@ -46,14 +46,14 @@ async function resolveInitOptions(options) {
             message: "Default harness",
             choices: [
                 { name: "codex", value: "codex" },
-                { name: "claude", value: "claude" }
-            ]
+                { name: "claude", value: "claude" },
+            ],
         });
     const model = options.model ??
         (await input({
             message: "Model",
             default: harness === "codex" ? DEFAULT_CODEX_MODEL : "",
-            validate: (value) => value.trim().length > 0 || "Model is required"
+            validate: (value) => value.trim().length > 0 || "Model is required",
         }));
     const reasoning_effort = options.reasoningEffort ??
         (await input({ message: "Reasoning effort", default: "medium" }));
@@ -65,34 +65,27 @@ async function resolveInitOptions(options) {
                 { name: "After each task", value: "each" },
                 { name: "After all tasks (global review)", value: "all" },
                 { name: "Both per-task and global", value: "both" },
-                { name: "No review", value: "none" }
+                { name: "No review", value: "none" },
             ],
-            default: "each"
+            default: "each",
         });
-    const review_max_attempts = review === "none"
-        ? 4
-        : parseReviewAttempts(options.reviewAttempts) ??
-            (await numberPrompt({
-                message: "Max review attempts per stage",
-                default: 4,
-                required: true
-            }));
-    if (!Number.isInteger(review_max_attempts) || review_max_attempts <= 0) {
-        throw new Error("review attempts must be a positive integer");
-    }
-    const repo = options.repo ?? (await input({ message: "GitHub repository (owner/repo)" }));
+    const review_rounds = await resolveReviewRounds(options, review);
+    const repo = options.repo ??
+        (await input({ message: "GitHub repository (owner/repo)" }));
     validateRepository(repo);
     const baseBranchInput = options.baseBranch ??
         (await input({
             message: "Base branch (blank = current branch at run time)",
-            default: ""
+            default: "",
         }));
-    const base_branch = baseBranchInput.trim() ? baseBranchInput.trim() : undefined;
+    const base_branch = baseBranchInput.trim()
+        ? baseBranchInput.trim()
+        : undefined;
     const max_iterations = parseMaxIterations(options.maxIterations) ??
         (await numberPrompt({
             message: "Max work items per run",
             default: 5,
-            required: true
+            required: true,
         }));
     if (!Number.isInteger(max_iterations) || max_iterations <= 0) {
         throw new Error("max iterations must be a positive integer");
@@ -102,10 +95,10 @@ async function resolveInitOptions(options) {
         model: model.trim(),
         reasoning_effort: reasoning_effort.trim() || "medium",
         review,
-        review_max_attempts,
+        review_rounds,
         repo,
         base_branch,
-        max_iterations
+        max_iterations,
     };
 }
 function buildConfig(options) {
@@ -115,11 +108,11 @@ function buildConfig(options) {
         reasoning_effort: options.reasoning_effort,
         review: options.review,
         tracker: { type: "github", repo: options.repo },
-        max_iterations: options.max_iterations
+        max_iterations: options.max_iterations,
     };
-    // No point persisting an attempts cap when reviews are disabled.
+    // No point persisting review rounds when reviews are disabled.
     if (options.review !== "none") {
-        config.review_max_attempts = options.review_max_attempts;
+        config.review_rounds = options.review_rounds;
     }
     if (options.base_branch) {
         config.base_branch = options.base_branch;
@@ -149,7 +142,38 @@ function parseMaxIterations(value) {
     }
     return Number.parseInt(value, 10);
 }
-function parseReviewAttempts(value) {
+async function resolveReviewRounds(options, review) {
+    if (review === "none") {
+        return { each: 1, global: 1 };
+    }
+    const deprecatedAttempts = parsePositiveInteger(options.reviewAttempts);
+    const each = parsePositiveInteger(options.reviewRoundsEach) ??
+        deprecatedAttempts ??
+        (review === "each" || review === "both"
+            ? await numberPrompt({
+                message: "Review rounds per work item",
+                default: 1,
+                required: true,
+            })
+            : 1);
+    const global = parsePositiveInteger(options.reviewRoundsGlobal) ??
+        deprecatedAttempts ??
+        (review === "all" || review === "both"
+            ? await numberPrompt({
+                message: "Global review rounds",
+                default: 1,
+                required: true,
+            })
+            : 1);
+    if (!Number.isInteger(each) || each <= 0) {
+        throw new Error("review_rounds.each must be a positive integer");
+    }
+    if (!Number.isInteger(global) || global <= 0) {
+        throw new Error("review_rounds.global must be a positive integer");
+    }
+    return { each, global };
+}
+function parsePositiveInteger(value) {
     if (value === undefined) {
         return undefined;
     }

package/dist/config/schema.js

@@ -7,7 +7,37 @@ import { z } from "zod";
  */
 export const harnessNames = ["codex", "claude"];
 export const reviewModes = ["each", "all", "both", "none"];
+export const globalReviewRoles = [
+    "diff-contract",
+    "integration",
+    "domain-invariants",
+    "tests-validation",
+];
 const githubRepositoryPattern = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const reviewRoundsSchema = z
+    .object({
+    each: z.number().int().positive().default(1),
+    global: z.number().int().positive().default(1),
+})
+    .default({ each: 1, global: 1 });
+const agentOverrideSchema = z
+    .object({
+    harness: z.enum(harnessNames).optional(),
+    model: z.string().min(1).optional(),
+    reasoning_effort: z.string().min(1).optional(),
+})
+    .strict();
+const globalReviewAgentOverrideSchema = agentOverrideSchema.extend({
+    roles: z
+        .object({
+        "diff-contract": agentOverrideSchema.optional(),
+        integration: agentOverrideSchema.optional(),
+        "domain-invariants": agentOverrideSchema.optional(),
+        "tests-validation": agentOverrideSchema.optional(),
+    })
+        .strict()
+        .optional(),
+});
 export const nyxConfigSchema = z
     .object({
     /** Which agent CLI runs each phase. Overridable per run via `run --harness`. */
@@ -18,18 +48,29 @@ export const nyxConfigSchema = z
     reasoning_effort: z.string().min(1).default("medium"),
     /** When the agent reviews its own work. */
     review: z.enum(reviewModes).default("each"),
-    /** How many review+revise rounds a review stage gets before the run fails. */
-    review_max_attempts: z.number().int().positive().default(4),
+    /** How many fresh discovery rounds each review stage may run. */
+    review_rounds: reviewRoundsSchema,
+    /** Deprecated: accepted for existing configs, but no longer drives reviews. */
+    review_max_attempts: z.number().int().positive().optional(),
+    /** Optional agent overrides by phase and global-review role. */
+    agents: z
+        .object({
+        execution: agentOverrideSchema.optional(),
+        review: agentOverrideSchema.optional(),
+        global_review: globalReviewAgentOverrideSchema.optional(),
+    })
+        .strict()
+        .optional(),
     /** Work item tracker. GitHub issues only in this version. */
     tracker: z.object({
         type: z.literal("github"),
         repo: z
             .string()
-            .regex(githubRepositoryPattern, 'tracker.repo must be "owner/repo"')
+            .regex(githubRepositoryPattern, 'tracker.repo must be "owner/repo"'),
     }),
     /** Base branch the run branch is cut from. Defaults to the current branch. */
     base_branch: z.string().min(1).optional(),
     /** Maximum work items processed in a single run. */
-    max_iterations: z.number().int().positive().default(5)
+    max_iterations: z.number().int().positive().default(5),
 })
     .strict();

package/dist/runtime/prompts.js

@@ -23,39 +23,72 @@ test, implement the smallest change that satisfies it, then tidy the result.
 
 Do not commit and do not touch git — NyxAgent commits your changes for you. Leave
 clear validation evidence (commands run and their results) in your final response.`;
-export const REVIEW_PROMPT = `Review the implementation of the selected work item.
+export const REVIEW_PROMPT = `Discover findings in the implementation of the selected work item.
 
-The uncommitted changes for this item are shown as a diff in the context above; you
-may also read files in the working directory. Stay read-only and do not modify
-anything.
+Use the review-context artifact paths in the context above. Inspect the patch file,
+diffstat, changed-files list, and the working directory as needed. Stay read-only
+and do not modify anything.
 
-Assess: alignment with the work item, correctness and regression risk, test or
-validation evidence, design fit, and security or data-safety concerns.
+This is discovery for the current review round only. Assess alignment with the work
+item, correctness and regression risk, test or validation evidence, design fit, and
+security or data-safety concerns.
 
-Set outcome to "approved" when the work is ready, or "changes_requested" with a
-concrete, actionable list in required_changes. Always include a short summary.`;
+Put only must-fix issues in blockers. Put missing or weak validation in test_gaps,
+non-blocking concerns in advisory_findings, uncertain suspicions in
+uncertain_findings, and explicitly refuted candidates in rejected_findings.`;
+export const REVIEW_CHALLENGE_PROMPT = `Challenge the proposed blockers for the selected work item.
+
+Stay read-only. Try to refute each proposed blocker using the current code,
+review-context artifacts, and concrete evidence. Return only blockers that remain
+valid and actionable. Move false positives or already-satisfied findings to
+rejected_findings with evidence. Do not introduce new findings in this phase.`;
 export const REVISION_PROMPT = `Apply the changes requested by the review for the selected work item.
 
-The required changes are listed in the context above. Address exactly those, keeping
-the work focused. Do not commit — NyxAgent commits your changes for you.`;
+The verified blockers are listed in the context above. Address exactly those,
+keeping the work focused. Do not commit — NyxAgent commits your changes for you.`;
+export const REVIEW_VALIDATION_PROMPT = `Validate the correction for the previously verified blockers.
+
+Stay read-only. Validate only the blockers listed in the context above. Do not run a
+new review and do not introduce unrelated new findings. For each blocker, return one
+status: resolved, unresolved, false_positive, or regression_from_correction.
+
+Use regression_from_correction only when the correction itself directly created a
+new blocker and the evidence proves that causal link.`;
 export const GLOBAL_REVIEW_PROMPT = `Review the entire run as a whole, now that every selected work item is implemented
 and committed.
 
-The combined diff for the run is shown in the context above; you may also read files
-in the working directory. Stay read-only and do not modify anything.
+Use the review-context artifact paths in the context above. Inspect the patch file,
+diffstat, changed-files list, commit list, and the working directory as needed. Stay
+read-only and do not modify anything.
 
 Focus on cross-cutting concerns a per-item review cannot see: integration between
 items, regressions one item introduced in another, overall design coherence,
 duplication, and gaps versus the issues' intent.
 
-Set outcome to "approved" when the run is coherent and ready, or
-"changes_requested" with a concrete, actionable list in required_changes. Always
-include a short summary.`;
+Return typed findings. Put only must-fix issues in blockers. Put missing or weak
+validation in test_gaps, non-blocking concerns in advisory_findings, uncertain
+suspicions in uncertain_findings, and explicitly refuted candidates in
+rejected_findings.`;
+export const GLOBAL_REVIEW_CHALLENGE_PROMPT = `Challenge the aggregated global-review blockers.
+
+Stay read-only. Try to refute each proposed blocker using the current code,
+review-context artifacts, and concrete evidence. Return only blockers that remain
+valid and actionable. Move false positives or already-satisfied findings to
+rejected_findings with evidence. Do not introduce new findings in this phase.`;
 export const GLOBAL_REVISION_PROMPT = `Apply the changes requested by the global review of the whole run.
 
-The required changes are listed in the context above. Address exactly those, across
+The verified blockers are listed in the context above. Address exactly those, across
 whichever work items are affected. Do not commit — NyxAgent commits your corrections
 for you.`;
+export const GLOBAL_REVIEW_VALIDATION_PROMPT = `Validate the global review correction for the previously verified blockers.
+
+Stay read-only. Validate only the blockers listed in the context above. Do not run a
+new global review and do not introduce unrelated new findings. For each blocker,
+return one status: resolved, unresolved, false_positive, or
+regression_from_correction.
+
+Use regression_from_correction only when the correction itself directly created a
+new blocker and the evidence proves that causal link.`;
 /** Rendered into .nyxagent/prompts/execution.md at init; the only editable prompt. */
 export const EXECUTION_PROMPT_FILE = `${EXECUTION_PROMPT}
 `;
@@ -88,7 +121,7 @@ export function buildPhasePrompt(input) {
         "",
         "## Instructions",
         "",
-        input.guidance.trim()
+        input.guidance.trim(),
     ];
     if (input.schema) {
         parts.push("", "## Required result", "", "End your response with a single <nyxagent_result> block containing JSON that", "matches this schema. NyxAgent parses the last such block, validates it, and", "ignores everything else for control flow.", "", "```json", JSON.stringify(input.schema, null, 2), "```", "", "<nyxagent_result>", "{ ... }", "</nyxagent_result>");

package/dist/runtime/runPipeline.js

@@ -1,19 +1,22 @@
 import path from "node:path";
+import { execa } from "execa";
 import { loadConfig } from "../config/loadConfig.js";
-import { ensureDir, pathExists, readText } from "./files.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 { 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 { GLOBAL_REVIEW_SCHEMA, REVIEW_SCHEMA, SELECTION_SCHEMA, } from "./schemas.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";
 const MAX_CANDIDATES = 50;
 const EXCERPT_CHARS = 800;
+const CORRECTION_VALIDATION_MAX_ATTEMPTS = 3;
 export function defaultPipelineDependencies() {
     return {
         listIssues: listGitHubIssues,
@@ -37,16 +40,22 @@ 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);
     const reporter = input.reporter ?? createRunReporter({ verbose: input.verbose ?? false });
     reporter.heading(`NyxAgent run ${runId}`);
-    reporter.info(`Harness: ${harness} · model: ${config.model} · review: ${config.review}`);
+    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.
@@ -66,7 +75,7 @@ export async function runPipeline(input = {}, deps = defaultPipelineDependencies
     const proposed = await runSelection({
         projectRoot,
         runDir,
-        harness,
+        cliHarness: input.harness,
         config,
         candidates,
         runPhase: deps.runPhase,
@@ -114,7 +123,7 @@ export async function runPipeline(input = {}, deps = defaultPipelineDependencies
                 item,
                 guidance: executionGuidance,
                 git,
-                harness,
+                cliHarness: input.harness,
                 config,
                 runPhase: deps.runPhase,
                 reporter,
@@ -124,9 +133,9 @@ export async function runPipeline(input = {}, deps = defaultPipelineDependencies
                     iterationDir,
                     item,
                     git,
-                    harness,
+                    cliHarness: input.harness,
                     config,
-                    maxAttempts: config.review_max_attempts,
+                    rounds: config.review_rounds.each,
                     runPhase: deps.runPhase,
                     reporter,
                 });
@@ -153,9 +162,10 @@ export async function runPipeline(input = {}, deps = defaultPipelineDependencies
             const corrections = await runGlobalReviewLoop({
                 runDir,
                 git,
-                harness,
+                completed,
+                cliHarness: input.harness,
                 config,
-                maxAttempts: config.review_max_attempts,
+                rounds: config.review_rounds.global,
                 runPhase: deps.runPhase,
                 reporter,
             });
@@ -257,6 +267,10 @@ async function salvageFailedRun(input) {
     }
 }
 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],
@@ -275,9 +289,9 @@ async function runSelection(input) {
         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,
@@ -304,6 +318,11 @@ 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)"],
@@ -314,9 +333,9 @@ async function runExecution(input) {
         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 }),
         reporter: input.reporter,
@@ -326,54 +345,275 @@ async function runExecution(input) {
     }
 }
 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;
-        input.reporter.info(`  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,
@@ -381,74 +621,233 @@ async function runReviewLoop(input) {
         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;
-        input.reporter.info(`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 ?? []],
-                ]),
-            }),
-            reporter: input.reporter,
-        });
-        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;
-            input.reporter.detail("Committed global review corrections.");
+    }
+    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");
@@ -508,12 +907,12 @@ function buildDraftPrBody(items, reason) {
         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")}`;
 }

package/dist/runtime/schemas.js

@@ -12,41 +12,127 @@ export const SELECTION_SCHEMA = {
         work_item_keys: {
             type: "array",
             items: { type: "string" },
-            description: "Ordered keys of the chosen candidates (prerequisites first)."
-        }
+            description: "Ordered keys of the chosen candidates (prerequisites first).",
+        },
     },
     allOf: [
         {
             if: { properties: { outcome: { const: "selected" } } },
-            then: { required: ["work_item_keys"] }
-        }
+            then: { required: ["work_item_keys"] },
+        },
     ],
-    additionalProperties: true
+    additionalProperties: true,
+};
+const evidenceSchema = {
+    type: "object",
+    properties: {
+        file: { type: "string" },
+        line: { type: "integer", minimum: 1 },
+        command: { type: "string" },
+        observation: { type: "string" },
+        detail: { type: "string" },
+    },
+    additionalProperties: true,
+};
+const findingSchema = {
+    type: "object",
+    required: ["title", "required_change", "confidence", "evidence"],
+    properties: {
+        title: { type: "string", minLength: 1 },
+        required_change: { type: "string", minLength: 1 },
+        confidence: {
+            type: "string",
+            enum: ["low", "medium", "high"],
+        },
+        evidence: {
+            type: "array",
+            minItems: 1,
+            items: evidenceSchema,
+            description: "Concrete evidence: file+line, command+observation, or an equivalent current-code observation.",
+        },
+    },
+    additionalProperties: true,
 };
-const reviewSchema = {
+const findingArraySchema = {
+    type: "array",
+    items: findingSchema,
+    default: [],
+};
+const reviewDiscoverySchema = {
     $schema: "https://json-schema.org/draft/2020-12/schema",
     type: "object",
-    required: ["outcome", "summary"],
+    required: [
+        "summary",
+        "blockers",
+        "test_gaps",
+        "advisory_findings",
+        "uncertain_findings",
+        "rejected_findings",
+    ],
     properties: {
-        outcome: { type: "string", enum: ["approved", "changes_requested"] },
         summary: {
             type: "string",
             minLength: 1,
-            description: "A brief assessment of the work."
+            description: "A brief assessment of the work.",
         },
-        required_changes: {
+        blockers: findingArraySchema,
+        test_gaps: findingArraySchema,
+        advisory_findings: findingArraySchema,
+        uncertain_findings: findingArraySchema,
+        rejected_findings: findingArraySchema,
+    },
+    additionalProperties: true,
+};
+const reviewChallengeSchema = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    type: "object",
+    required: ["summary", "blockers", "rejected_findings"],
+    properties: {
+        summary: { type: "string", minLength: 1 },
+        blockers: findingArraySchema,
+        rejected_findings: findingArraySchema,
+    },
+    additionalProperties: true,
+};
+const validationSchema = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    type: "object",
+    required: ["summary", "validations"],
+    properties: {
+        summary: { type: "string", minLength: 1 },
+        validations: {
             type: "array",
-            items: { type: "string" },
-            description: 'Specific, actionable changes (required when outcome is "changes_requested").'
-        }
+            items: {
+                type: "object",
+                required: ["blocker_title", "status", "evidence"],
+                properties: {
+                    blocker_title: { type: "string", minLength: 1 },
+                    status: {
+                        type: "string",
+                        enum: [
+                            "resolved",
+                            "unresolved",
+                            "false_positive",
+                            "regression_from_correction",
+                        ],
+                    },
+                    required_change: {
+                        type: "string",
+                        description: "Required when the status remains unresolved or is a correction-caused regression.",
+                    },
+                    evidence: {
+                        type: "array",
+                        minItems: 1,
+                        items: evidenceSchema,
+                    },
+                },
+                additionalProperties: true,
+            },
+        },
     },
-    allOf: [
-        {
-            if: { properties: { outcome: { const: "changes_requested" } } },
-            then: { required: ["required_changes"] }
-        }
-    ],
-    additionalProperties: true
+    additionalProperties: true,
 };
-export const REVIEW_SCHEMA = reviewSchema;
-export const GLOBAL_REVIEW_SCHEMA = reviewSchema;
+export const REVIEW_DISCOVERY_SCHEMA = reviewDiscoverySchema;
+export const GLOBAL_REVIEW_SCHEMA = reviewDiscoverySchema;
+export const REVIEW_CHALLENGE_SCHEMA = reviewChallengeSchema;
+export const REVIEW_VALIDATION_SCHEMA = validationSchema;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nyxa/nyx-agent",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "A lightweight phase orchestrator for repeatedly launching coding agents with fresh context.",
   "type": "module",
   "repository": {