@nyxa/nyx-agent 0.7.0 → 0.8.1

package/README.md

@@ -7,11 +7,13 @@ GitHub issue at a time, each phase with fresh context.
 
 For every run NyxAgent:
 
-1. **Selects** open GitHub issues to work on (read-only), then asks the user to
-   confirm the proposed checklist.
+1. **Selects** executable open GitHub issues to work on (read-only), grouping
+   GitHub sub-issues under non-executable parent PRD/plan issues, then asks the
+   user to 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).
@@ -19,7 +21,9 @@ For every run NyxAgent:
 The agent only implements, reviews, and revises. Every git/gh side effect —
 commit, push, pull request — is performed by the engine, so closing the loop
 never depends on the model. Issues are closed by GitHub when the PR merges
-(`Closes #n` in the PR body); the human merges the PR.
+(`Closes #n` in the PR body); parent PRD/plan issues are closed only when
+NyxAgent can prove the PR completes their remaining open executable children.
+The human merges the PR.
 
 The workflow shape is fixed (not configurable). Only `.nyxagent/prompts/execution.md`
 is editable.
@@ -45,7 +49,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 +58,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>");