lee-spec-kit 0.9.4 → 0.9.5

package/dist/index.js

@@ -213,6 +213,7 @@ var koCli = {
   "init.choice.taskAgent.on": "\uC0AC\uC6A9 - \uAC01 Task \uAD6C\uD604\uC744 \uC704\uC784",
   "init.choice.taskAgent.off": "\uC0AC\uC6A9 \uC548 \uD568 - \uBA54\uC778 \uC5D0\uC774\uC804\uD2B8\uAC00 \uC9C1\uC811 \uAD6C\uD604",
   "init.prompt.reviews": "\uB3C5\uB9BD \uAC80\uC218 \uB2E8\uACC4\uB97C \uC120\uD0DD\uD558\uC138\uC694:",
+  "init.prompt.maxReviewRounds": "\uC0AC\uC6A9\uC790\uC5D0\uAC8C \uD310\uB2E8\uC744 \uC694\uCCAD\uD558\uAE30 \uC804 \uB9AC\uBDF0 \uC9C0\uC801 \uC790\uB3D9 \uBC18\uC601 \uCD5C\uB300 \uD69F\uC218:",
   "init.choice.review.plan": "Plan",
   "init.choice.review.task": "Task",
   "init.choice.review.feature": "Feature",
@@ -238,6 +239,7 @@ var koCli = {
   "init.log.workflowLabel": "\uC6CC\uD06C\uD50C\uB85C\uC6B0",
   "init.log.taskAgentLabel": "Task \uAD6C\uD604",
   "init.log.reviewsLabel": "\uAC80\uC218",
+  "init.log.maxReviewRoundsLabel": "\uB9AC\uBDF0 \uC9C0\uC801 \uC790\uB3D9 \uBC18\uC601 \uD69F\uC218",
   "init.log.completionStrategyLabel": "\uB85C\uCEEC \uD1B5\uD569",
   "init.summary.taskAgent.on": "\uC11C\uBE0C\uC5D0\uC774\uC804\uD2B8",
   "init.summary.taskAgent.off": "\uBA54\uC778 \uC5D0\uC774\uC804\uD2B8",
@@ -525,6 +527,7 @@ var enCli = {
   "init.choice.taskAgent.on": "On - delegate each task implementation",
   "init.choice.taskAgent.off": "Off - implement tasks in the main agent",
   "init.prompt.reviews": "Select independent review gates:",
+  "init.prompt.maxReviewRounds": "Maximum automatic review finding remediation rounds before asking the user:",
   "init.choice.review.plan": "Plan",
   "init.choice.review.task": "Task",
   "init.choice.review.feature": "Feature",
@@ -550,6 +553,7 @@ var enCli = {
   "init.log.workflowLabel": "Workflow",
   "init.log.taskAgentLabel": "Task implementation",
   "init.log.reviewsLabel": "Reviews",
+  "init.log.maxReviewRoundsLabel": "Review remediation rounds",
   "init.log.completionStrategyLabel": "Local integration",
   "init.summary.taskAgent.on": "subagent",
   "init.summary.taskAgent.off": "main agent",
@@ -1364,14 +1368,15 @@ Before taking the next workflow step:
 10. In standalone mode, do not hand-write \`git worktree add\`; run the exact \`nextAction.command\` from \`workflow-stage\` so the managed workspace path, stale directory cleanup, and \`.env\` / \`.env.*\` copy step stay consistent
 11. Keep docs and code synchronized; if code changes materially, update the active feature docs in the same turn before stopping
 12. When docs are synced to code, keep exactly one explicit marker like \`<!-- lee-spec-kit:workflow-sync 2026-04-16T12:34:56.789Z -->\` in a single active feature doc (prefer \`tasks.md\` or \`decisions.md\`): replace an existing marker timestamp or remove duplicates instead of appending another marker, so \`workflow-audit\` can prove the sync happened after the latest code change
-13. When \`workflow-stage --json\` returns \`nextAction.category === "plan_review"\` with \`executor === "subagent"\`, delegate a fresh read-only review of \`spec.md\` and \`plan.md\` using the returned model settings and exact \`specHash\` / \`planHash\`; the main agent records evidence, decision, reviewer metadata, and both hashes, and any later spec/plan content change requires a fresh review
+13. When \`workflow-stage --json\` returns \`nextAction.category === "plan_review"\` with \`executor === "subagent"\`, delegate a fresh read-only review of \`spec.md\` and \`plan.md\` using the returned model settings and exact \`specHash\` / \`planHash\`; the main agent records the returned reviewRound, evidence, decision, reviewer metadata, and both hashes, and any later spec/plan content change requires a fresh review
 14. When \`workflow-stage --json\` returns \`nextAction.category === "task_execute"\` with \`executor === "subagent"\`, mark exactly the returned \`taskId\` as active and delegate its implementation plus task-scoped verification to a fresh subagent in the returned \`workingDirectory\`, using the returned \`model\`, \`reasoningEffort\`, \`onUnavailable\`, and exact \`workerContract\`; no named execution skill is required
 15. The task implementation worker executes directly: it must follow the approved Verification Contract, must not add unplanned durable tests, and must not run \`workflow-stage\`, spawn another subagent, edit lee-spec-kit docs, change task state, commit, request approvals, or perform remote/destructive actions. It may modify project code and run task-scoped checks only. The main agent inspects the result, synchronizes docs and task state, and owns every commit and workflow transition; official hooks block commits while \`task_execute\` is still active
-16. When \`workflow-stage --json\` returns \`nextAction.category === "task_review"\` with \`executor === "subagent"\`, delegate a fresh read-only review for the returned \`taskId\`, \`baseSha\`, \`targetSha\`, and \`targetTree\`; the main agent records the evidence and moves the task from \`REVIEW\` to \`DONE\` only after an approve decision
-17. When \`workflow-stage --json\` returns \`nextAction.category === "pre_pr_review"\` and \`nextAction.executor === "subagent"\`, delegate a fresh read-only Feature review using the returned \`model\`, \`reasoningEffort\`, \`onUnavailable\`, and review target metadata; do not select or require a named review skill
+16. When \`workflow-stage --json\` returns \`nextAction.category === "task_review"\` with \`executor === "subagent"\`, delegate a fresh read-only review for the returned \`taskId\`, \`baseSha\`, \`targetSha\`, and \`targetTree\`; the main agent records the returned reviewRound and evidence and moves the task from \`REVIEW\` to \`DONE\` only after an approve decision
+17. When \`workflow-stage --json\` returns \`nextAction.category === "pre_pr_review"\` and \`nextAction.executor === "subagent"\`, delegate a fresh read-only Feature review using the returned \`model\`, \`reasoningEffort\`, \`onUnavailable\`, reviewRound, and review target metadata; do not select or require a named review skill
 18. Review subagents return findings without modifying code; the main agent remediates findings and records the actual reviewer metadata, reviewed scope, evidence, decision, and exact hash/SHA/tree target metadata
-19. For a local workflow, do not report completion directly after implementation approval; follow the exact returned \`local verify\` / \`local merge\` / \`local cleanup\` commands until \`workflow-stage\` proves verification, integration, and cleanup and returns \`done\`; review-fix and \`feature_remediation\` stages explicitly permit scoped fixes
-20. In a \`local-ff\` or \`local-squash\` workflow, keep implementation approval and local merge approval distinct when \`local_merge\` is required: the first accepts the implementation, and the second authorizes the configured integration strategy, post-merge checks, and local cleanup
+19. workflow.agentReview.maxRounds counts automatic finding-remediation passes, not the initial review. When workflow-stage returns nextAction.category review_escalation, those passes have been exhausted; do not remediate or delegate another review, keep implementation blocked, and present the exact returned action options to the user. Another remediation pass requires increasing maxRounds first
+20. For a local workflow, do not report completion directly after implementation approval; follow the exact returned \`local verify\` / \`local merge\` / \`local cleanup\` commands until \`workflow-stage\` proves verification, integration, and cleanup and returns \`done\`; review-fix and \`feature_remediation\` stages explicitly permit scoped fixes
+21. In a \`local-ff\` or \`local-squash\` workflow, keep implementation approval and local merge approval distinct when \`local_merge\` is required: the first accepts the implementation, and the second authorizes the configured integration strategy, post-merge checks, and local cleanup
 
 Approval and remote actions:
 
@@ -2104,6 +2109,15 @@ function assertValidInitWorkflowOptions(options) {
       "`--completion-strategy` must be `local-ff`, `local-squash`, or `none`."
     );
   }
+  if (options.maxReviewRounds !== void 0) {
+    const parsed = Number(options.maxReviewRounds);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+      throw createCliError(
+        "INVALID_ARGUMENT",
+        "`--max-review-rounds` must be a positive integer."
+      );
+    }
+  }
 }
 function initCommand(program2) {
   program2.command("init").description("Initialize project documentation structure").option("-n, --name <name>", "Project name (default: current folder name)").option(
@@ -2115,6 +2129,9 @@ function initCommand(program2) {
   ).option("-l, --lang <lang>", "Language: ko | en (default: en)").option("--workflow <mode>", "Workflow mode: github | local").option("--task-agent <mode>", "Task implementation agent: on | off").option(
     "--reviews <list>",
     "Review gates: comma-separated plan,task,feature | none"
+  ).option(
+    "--max-review-rounds <count>",
+    "Automatic review finding remediation rounds before user escalation (default: 1)"
   ).option(
     "--completion-strategy <strategy>",
     "Local completion: local-ff | local-squash | none"
@@ -2158,6 +2175,7 @@ async function runInit(options) {
   let workflowMode = options.workflow || "github";
   let taskAgentEnabled = options.taskAgent !== "off";
   let enabledReviews = parseInitReviews(options.reviews) ?? ["plan", "feature"];
+  let maxReviewRounds = Number(options.maxReviewRounds || 1);
   let completionStrategy = options.completionStrategy || "local-ff";
   let docsRepo = options.docsRepo || "embedded";
   let pushDocs = typeof options.pushDocs === "boolean" ? options.pushDocs : void 0;
@@ -2419,7 +2437,7 @@ async function runInit(options) {
         docsRemote = remoteResponse.docsRemote || docsRemote;
       }
     }
-    const hasExplicitWorkflowSetup = typeof options.taskAgent !== "undefined" || typeof options.reviews !== "undefined" || typeof options.completionStrategy !== "undefined";
+    const hasExplicitWorkflowSetup = typeof options.taskAgent !== "undefined" || typeof options.reviews !== "undefined" || typeof options.maxReviewRounds !== "undefined" || typeof options.completionStrategy !== "undefined";
     let customizeWorkflow = hasExplicitWorkflowSetup;
     if (!hasExplicitWorkflowSetup) {
       const setupResponse = await prompts(
@@ -2496,6 +2514,13 @@ async function runInit(options) {
               selected: phase !== "task"
             }))
           },
+          {
+            type: typeof options.maxReviewRounds === "undefined" ? "number" : null,
+            name: "maxReviewRounds",
+            message: tr(lang, "cli", "init.prompt.maxReviewRounds"),
+            initial: 1,
+            min: 1
+          },
           {
             type: workflowMode === "local" && typeof options.completionStrategy === "undefined" ? "select" : null,
             name: "completionStrategy",
@@ -2539,6 +2564,9 @@ async function runInit(options) {
           (phase) => workflowResponse.reviews.includes(phase)
         );
       }
+      if (Number.isInteger(workflowResponse.maxReviewRounds) && workflowResponse.maxReviewRounds > 0) {
+        maxReviewRounds = workflowResponse.maxReviewRounds;
+      }
       completionStrategy = workflowResponse.completionStrategy || completionStrategy;
     }
   }
@@ -2770,6 +2798,11 @@ async function runInit(options) {
           `  ${tr(lang, "cli", "init.log.reviewsLabel")}: ${reviewSummary}`
         )
       );
+      console.log(
+        chalk.gray(
+          `  ${tr(lang, "cli", "init.log.maxReviewRoundsLabel")}: ${maxReviewRounds}`
+        )
+      );
       if (workflowMode === "local") {
         console.log(
           chalk.gray(
@@ -2839,6 +2872,7 @@ async function runInit(options) {
             }
           },
           agentReview: {
+            maxRounds: maxReviewRounds,
             plan: {
               enabled: enabledReviews.includes("plan"),
               evidenceMode: "path_required",
@@ -3099,7 +3133,7 @@ function sanitizeTasksForLocal(content, lang) {
     filtered.push(line);
   }
   next = filtered.join("\n");
-  next = lang === "ko" ? next.replaceAll("**PR \uC804 \uB9AC\uBDF0**", "**Feature \uB9AC\uBDF0**").replaceAll("**PR \uC804 \uB9AC\uBDF0 Evidence**", "**Feature \uB9AC\uBDF0 Evidence**").replaceAll("**PR \uC804 \uB9AC\uBDF0 Decision**", "**Feature \uB9AC\uBDF0 Decision**").replaceAll("**PR \uC804 \uB9AC\uBDF0 Head**", "**Feature \uB9AC\uBDF0 Head**").replaceAll("**PR \uC804 \uB9AC\uBDF0 Tree**", "**Feature \uB9AC\uBDF0 Tree**").replaceAll("pre-PR \uB9AC\uBDF0 handoff", "Feature \uB9AC\uBDF0 handoff") : next.replaceAll("**Pre-PR Review**", "**Feature Review**").replaceAll("**Pre-PR Evidence**", "**Feature Review Evidence**").replaceAll("**Pre-PR Decision**", "**Feature Review Decision**").replaceAll("**Pre-PR Reviewed Head**", "**Feature Reviewed Head**").replaceAll("**Pre-PR Reviewed Tree**", "**Feature Reviewed Tree**").replaceAll("pre-PR review handoff", "Feature review handoff");
+  next = lang === "ko" ? next.replaceAll("**PR \uC804 \uB9AC\uBDF0**", "**Feature \uB9AC\uBDF0**").replaceAll("**PR \uC804 \uB9AC\uBDF0 Evidence**", "**Feature \uB9AC\uBDF0 Evidence**").replaceAll("**PR \uC804 \uB9AC\uBDF0 Decision**", "**Feature \uB9AC\uBDF0 Decision**").replaceAll("**PR \uC804 \uB9AC\uBDF0 Round**", "**Feature \uB9AC\uBDF0 Round**").replaceAll("**PR \uC804 \uB9AC\uBDF0 Head**", "**Feature \uB9AC\uBDF0 Head**").replaceAll("**PR \uC804 \uB9AC\uBDF0 Tree**", "**Feature \uB9AC\uBDF0 Tree**").replaceAll("pre-PR \uB9AC\uBDF0 handoff", "Feature \uB9AC\uBDF0 handoff") : next.replaceAll("**Pre-PR Review**", "**Feature Review**").replaceAll("**Pre-PR Evidence**", "**Feature Review Evidence**").replaceAll("**Pre-PR Decision**", "**Feature Review Decision**").replaceAll("**Pre-PR Review Round**", "**Feature Review Round**").replaceAll("**Pre-PR Reviewed Head**", "**Feature Reviewed Head**").replaceAll("**Pre-PR Reviewed Tree**", "**Feature Reviewed Tree**").replaceAll("pre-PR review handoff", "Feature review handoff");
   next = next.replace(/feat\/\{issue-number\}-/g, "feat/").replace(/feat\/\{이슈번호\}-/g, "feat/").replace(/feat\/-/g, "feat/");
   return normalizeTrailingBlankLines(next);
 }
@@ -4154,6 +4188,11 @@ async function backfillMissingConfigDefaults(cwd, docsDir) {
     changedPaths.push("workflow.agentReview");
   }
   const agentReview = workflow.agentReview;
+  setIfMissing(agentReview, "maxRounds", 1, "workflow.agentReview.maxRounds");
+  if (typeof agentReview.maxRounds !== "number" || !Number.isInteger(agentReview.maxRounds) || agentReview.maxRounds < 1) {
+    agentReview.maxRounds = 1;
+    changedPaths.push("workflow.agentReview.maxRounds");
+  }
   const normalizeAgentReviewPhase = (key, enabledDefault, legacySeed = null) => {
     const phasePath = `workflow.agentReview.${key}`;
     if (!isPlainObject(agentReview[key])) {
@@ -8351,6 +8390,12 @@ var PRE_PR_DECISION_LABELS = [
   "Feature Review Decision",
   "Feature \uB9AC\uBDF0 Decision"
 ];
+var PRE_PR_REVIEW_ROUND_LABELS = [
+  "Pre-PR Review Round",
+  "PR \uC804 \uB9AC\uBDF0 Round",
+  "Feature Review Round",
+  "Feature \uB9AC\uBDF0 Round"
+];
 var PRE_PR_REVIEWED_HEAD_LABELS = [
   "Pre-PR Reviewed Head",
   "PR \uC804 \uB9AC\uBDF0 Head",
@@ -8374,6 +8419,11 @@ var PLAN_REVIEW_DECISION_LABELS = [
   "Plan \uAC80\uC218 Decision",
   "Plan \uB9AC\uBDF0 Decision"
 ];
+var PLAN_REVIEW_ROUND_LABELS = [
+  "Plan Review Round",
+  "Plan \uAC80\uC218 Round",
+  "Plan \uB9AC\uBDF0 Round"
+];
 var PLAN_REVIEWED_SPEC_HASH_LABELS = [
   "Plan Reviewed Spec Hash",
   "Plan \uAC80\uC218 Spec Hash",
@@ -8460,6 +8510,14 @@ function parseReviewDecisionOutcome(value) {
   const match = (value || "").trim().toLowerCase().match(/\b(approve|changes_requested|blocked)\b/);
   return match?.[1] || null;
 }
+function parseReviewRound(value) {
+  const parsed = Number((value || "").trim());
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : null;
+}
+function resolveMaxReviewRounds(config) {
+  const configured = config.workflow?.agentReview?.maxRounds;
+  return typeof configured === "number" && Number.isInteger(configured) && configured > 0 ? configured : 1;
+}
 function parseWorkflowTaskLine(line, index = -1) {
   const canonical = parseTaskLine(line, index);
   if (canonical) {
@@ -8530,6 +8588,13 @@ function parseTasksDoc(content, feature) {
       index,
       ["Review Decision", "Task Review Decision", "\uD0DC\uC2A4\uD06C \uB9AC\uBDF0 Decision"]
     );
+    const reviewRound = parseReviewRound(
+      extractTaskReviewValue(nonCodeLines, index, [
+        "Review Round",
+        "Task Review Round",
+        "\uD0DC\uC2A4\uD06C \uB9AC\uBDF0 Round"
+      ])
+    );
     const legacyTitleKey = normalizeCommitTopicText(parsed.title).toLowerCase();
     const sameTitleOccurrence = (legacyTitleOccurrences.get(legacyTitleKey) || 0) + 1;
     legacyTitleOccurrences.set(legacyTitleKey, sameTitleOccurrence);
@@ -8547,6 +8612,7 @@ function parseTasksDoc(content, feature) {
       ),
       reviewDecision,
       reviewDecisionOutcome: parseReviewDecisionOutcome(reviewDecision),
+      reviewRound,
       reviewedHead: extractTaskReviewValue(
         nonCodeLines,
         index,
@@ -8602,6 +8668,9 @@ function parseTasksDoc(content, feature) {
     ),
     prePrDecision: sanitizeMetadataValue2(prePrDecision),
     prePrDecisionOutcome,
+    prePrReviewRound: parseReviewRound(
+      extractFieldValue2(content, PRE_PR_REVIEW_ROUND_LABELS)
+    ),
     prePrReviewedHead: sanitizeMetadataValue2(
       extractFieldValue2(content, PRE_PR_REVIEWED_HEAD_LABELS)
     ),
@@ -8633,6 +8702,9 @@ function parsePlanReview(content) {
   const decision = sanitizeMetadataValue2(
     extractFieldValue2(content, PLAN_REVIEW_DECISION_LABELS)
   );
+  const reviewRound = parseReviewRound(
+    extractFieldValue2(content, PLAN_REVIEW_ROUND_LABELS)
+  );
   const reviewedSpecHash = sanitizeMetadataValue2(
     extractFieldValue2(content, PLAN_REVIEWED_SPEC_HASH_LABELS)
   );
@@ -8644,6 +8716,7 @@ function parsePlanReview(content) {
     evidence,
     decision,
     decisionOutcome: parseReviewDecisionOutcome(decision),
+    reviewRound,
     reviewedSpecHash,
     reviewedPlanHash,
     hasMetadata: PLAN_REVIEW_STATUS_LABELS.some((label) => {
@@ -8669,6 +8742,7 @@ function buildPlanReviewTarget(specContent, planContent) {
       ...PLAN_REVIEW_STATUS_LABELS,
       ...PLAN_REVIEW_EVIDENCE_LABELS,
       ...PLAN_REVIEW_DECISION_LABELS,
+      ...PLAN_REVIEW_ROUND_LABELS,
       ...PLAN_REVIEWED_SPEC_HASH_LABELS,
       ...PLAN_REVIEWED_PLAN_HASH_LABELS
     ])
@@ -9585,31 +9659,68 @@ function resolveFeatureSelectionError(selection) {
 }
 function resolvePlanReviewPayload(config, feature, review, target) {
   const targetMatches = review.reviewedSpecHash === target.specHash && review.reviewedPlanHash === target.planHash;
+  const maxReviewRounds = resolveMaxReviewRounds(config);
+  const reviewRound = review.reviewRound || 1;
+  const nextReviewRound = !targetMatches && review.decisionOutcome ? reviewRound + 1 : reviewRound;
   const actionContext = {
     reviewScope: "plan",
+    reviewRound: nextReviewRound,
+    maxReviewRounds,
     specHash: target.specHash,
     planHash: target.planHash,
     docsDirectory: config.docsDir
   };
-  if (targetMatches && review.decisionOutcome === "changes_requested") {
-    return {
-      status: "ok",
-      reasonCode: "WORKFLOW_STAGE_RESOLVED",
-      docsDir: config.docsDir,
-      featureRef: buildFeatureRef(feature),
-      stage: "plan_review_fix",
-      nextAction: buildAction(
-        "plan_review_fix",
-        "Address the independent Plan review findings in spec.md or plan.md, keep implementation blocked, and request a fresh review for the resulting document hashes.",
-        false,
-        null,
-        void 0,
-        actionContext
-      ),
-      approvalRequired: false,
-      implementationAllowed: false,
-      blockedReasonCode: "PLAN_REVIEW_NOT_APPROVED"
-    };
+  if (review.decisionOutcome === "changes_requested") {
+    if (reviewRound > maxReviewRounds) {
+      return {
+        status: "ok",
+        reasonCode: "WORKFLOW_STAGE_RESOLVED",
+        docsDir: config.docsDir,
+        featureRef: buildFeatureRef(feature),
+        stage: "review_escalation",
+        nextAction: buildAction(
+          "review_escalation",
+          `Plan review requested more changes after ${maxReviewRounds} automatic remediation round(s) were used. Ask the user whether to revise again, request a different reviewer, accept the documented risk, change scope, or hold the Feature.`,
+          true,
+          null,
+          void 0,
+          { ...actionContext, reviewRound }
+        ),
+        approvalRequired: true,
+        implementationAllowed: false,
+        primaryActionLabel: "A",
+        actionOptions: [
+          buildStageOption(
+            "A",
+            "A",
+            "review_retry",
+            "Increase workflow.agentReview.maxRounds, then revise the Plan and run one more fresh review round."
+          ),
+          buildStageOption("B", "B", "hold", "Hold the Feature for user resolution.")
+        ],
+        blockedReasonCode: "PLAN_REVIEW_NOT_APPROVED"
+      };
+    }
+    if (targetMatches) {
+      return {
+        status: "ok",
+        reasonCode: "WORKFLOW_STAGE_RESOLVED",
+        docsDir: config.docsDir,
+        featureRef: buildFeatureRef(feature),
+        stage: "plan_review_fix",
+        nextAction: buildAction(
+          "plan_review_fix",
+          `Address the independent Plan review findings in spec.md or plan.md, record review round ${reviewRound + 1}, keep implementation blocked, and request a fresh review for the resulting document hashes.`,
+          false,
+          null,
+          void 0,
+          { ...actionContext, reviewRound }
+        ),
+        approvalRequired: false,
+        implementationAllowed: false,
+        blockedReasonCode: "PLAN_REVIEW_NOT_APPROVED"
+      };
+    }
   }
   if (targetMatches && review.decisionOutcome === "blocked") {
     return {
@@ -9624,7 +9735,7 @@ function resolvePlanReviewPayload(config, feature, review, target) {
         false,
         null,
         void 0,
-        actionContext
+        { ...actionContext, reviewRound }
       ),
       approvalRequired: false,
       implementationAllowed: false,
@@ -9639,7 +9750,7 @@ function resolvePlanReviewPayload(config, feature, review, target) {
     stage: "plan_review",
     nextAction: buildAction(
       "plan_review",
-      "Delegate a fresh read-only review of spec.md and plan.md. Verify the Verification Contract, NONE/UPDATE/ADD decisions, requirement coverage, independent oracles, stable observation boundaries, realistic failure/rollback cases, exclusions, and focused/full verification scope. Record Plan Review status, evidence, decision, reviewer metadata, Reviewed Spec Hash, and Reviewed Plan Hash without modifying the documents.",
+      `Delegate fresh read-only Plan review round ${nextReviewRound} of spec.md and plan.md. Verify the Verification Contract, NONE/UPDATE/ADD decisions, requirement coverage, independent oracles, stable observation boundaries, realistic failure/rollback cases, exclusions, and focused/full verification scope. Record Plan Review Round, status, evidence, decision, reviewer metadata, Reviewed Spec Hash, and Reviewed Plan Hash without modifying the documents.`,
       false,
       null,
       resolveAgentReviewer(config, "plan"),
@@ -9927,29 +10038,58 @@ async function collectWorkflowStage(cwd, selector, component) {
     }
     const reviewContext = {
       reviewScope: "task",
+      reviewRound: reviewTask.reviewRound || 1,
+      maxReviewRounds: resolveMaxReviewRounds(config),
       ...reviewTask.taskId ? { taskId: reviewTask.taskId } : {},
       ...reviewTarget
     };
     const evidenceMatchesTarget = reviewTask.reviewedHead === reviewTarget.targetSha && reviewTask.reviewedTree === reviewTarget.targetTree;
-    if (evidenceMatchesTarget && reviewTask.reviewDecisionOutcome === "changes_requested") {
-      return {
-        status: "ok",
-        reasonCode: "WORKFLOW_STAGE_RESOLVED",
-        docsDir: config.docsDir,
-        featureRef: buildFeatureRef(feature),
-        stage: "task_review_fix",
-        nextAction: buildAction(
-          "task_review_fix",
-          `Address the independent review findings for ${reviewTask.taskId || reviewTask.title}, return the task to REVIEW, commit the new code tip, and request a fresh review.`,
-          false,
-          null,
-          void 0,
-          reviewContext
-        ),
-        approvalRequired: false,
-        implementationAllowed: true,
-        blockedReasonCode: "TASK_REVIEW_NOT_APPROVED"
-      };
+    if (reviewTask.reviewDecisionOutcome === "changes_requested") {
+      if (reviewContext.reviewRound > reviewContext.maxReviewRounds) {
+        return {
+          status: "ok",
+          reasonCode: "WORKFLOW_STAGE_RESOLVED",
+          docsDir: config.docsDir,
+          featureRef: buildFeatureRef(feature),
+          stage: "review_escalation",
+          nextAction: buildAction(
+            "review_escalation",
+            `Task review for ${reviewTask.taskId || reviewTask.title} requested more changes after ${reviewContext.maxReviewRounds} automatic remediation round(s) were used. Ask the user whether to authorize another remediation round or hold the Feature.`,
+            true,
+            null,
+            void 0,
+            reviewContext
+          ),
+          approvalRequired: true,
+          implementationAllowed: false,
+          primaryActionLabel: "A",
+          actionOptions: [
+            buildStageOption("A", "A", "review_retry", "Increase workflow.agentReview.maxRounds, then run one more task remediation and fresh review round."),
+            buildStageOption("B", "B", "hold", "Hold the Feature for user resolution.")
+          ],
+          blockedReasonCode: "TASK_REVIEW_NOT_APPROVED"
+        };
+      }
+      if (evidenceMatchesTarget) {
+        return {
+          status: "ok",
+          reasonCode: "WORKFLOW_STAGE_RESOLVED",
+          docsDir: config.docsDir,
+          featureRef: buildFeatureRef(feature),
+          stage: "task_review_fix",
+          nextAction: buildAction(
+            "task_review_fix",
+            `Address the independent review findings for ${reviewTask.taskId || reviewTask.title}, return the task to REVIEW, commit the new code tip, and request fresh review round ${reviewContext.reviewRound + 1}.`,
+            false,
+            null,
+            void 0,
+            reviewContext
+          ),
+          approvalRequired: false,
+          implementationAllowed: true,
+          blockedReasonCode: "TASK_REVIEW_NOT_APPROVED"
+        };
+      }
     }
     if (evidenceMatchesTarget && reviewTask.reviewDecisionOutcome === "blocked") {
       return {
@@ -10000,11 +10140,14 @@ async function collectWorkflowStage(cwd, selector, component) {
       stage: "task_review",
       nextAction: buildAction(
         "task_review",
-        `Delegate a fresh read-only review of ${reviewTask.taskId || reviewTask.title} for ${reviewTarget.baseSha}..${reviewTarget.targetSha}. Record evidence, decision, reviewer metadata, Reviewed Head, and Reviewed Tree without modifying code.`,
+        `Delegate fresh read-only review round ${evidenceMatchesTarget ? reviewContext.reviewRound : reviewTask.reviewDecisionOutcome ? reviewContext.reviewRound + 1 : reviewContext.reviewRound} of ${reviewTask.taskId || reviewTask.title} for ${reviewTarget.baseSha}..${reviewTarget.targetSha}. Record Review Round, evidence, decision, reviewer metadata, Reviewed Head, and Reviewed Tree without modifying code.`,
         false,
         null,
         resolveAgentReviewer(config, "task"),
-        reviewContext
+        {
+          ...reviewContext,
+          reviewRound: !evidenceMatchesTarget && reviewTask.reviewDecisionOutcome ? reviewContext.reviewRound + 1 : reviewContext.reviewRound
+        }
       ),
       approvalRequired: false,
       implementationAllowed: false,
@@ -10104,27 +10247,59 @@ async function collectWorkflowStage(cwd, selector, component) {
       effectiveProjectGitCwd,
       "feature"
     );
-    const reviewContext = reviewTarget ? { reviewScope: "feature", ...reviewTarget } : null;
+    const reviewContext = reviewTarget ? {
+      reviewScope: "feature",
+      reviewRound: tasks.prePrReviewRound || 1,
+      maxReviewRounds: resolveMaxReviewRounds(config),
+      ...reviewTarget
+    } : null;
     const evidenceMatchesTarget = !!reviewTarget && tasks.prePrReviewedHead === reviewTarget.targetSha && tasks.prePrReviewedTree === reviewTarget.targetTree;
-    if (reviewContext && evidenceMatchesTarget && tasks.prePrDecisionOutcome === "changes_requested") {
-      return {
-        status: "ok",
-        reasonCode: "WORKFLOW_STAGE_RESOLVED",
-        docsDir: config.docsDir,
-        featureRef: buildFeatureRef(feature),
-        stage: "feature_review_fix",
-        nextAction: buildAction(
-          "feature_review_fix",
-          "Address the Feature review findings, commit the remediation, and request a fresh review of the new code tree before implementation approval.",
-          false,
-          null,
-          void 0,
-          reviewContext
-        ),
-        approvalRequired: false,
-        implementationAllowed: true,
-        blockedReasonCode: "PRE_PR_REVIEW_NOT_APPROVED"
-      };
+    if (reviewContext && tasks.prePrDecisionOutcome === "changes_requested") {
+      if (reviewContext.reviewRound > reviewContext.maxReviewRounds) {
+        return {
+          status: "ok",
+          reasonCode: "WORKFLOW_STAGE_RESOLVED",
+          docsDir: config.docsDir,
+          featureRef: buildFeatureRef(feature),
+          stage: "review_escalation",
+          nextAction: buildAction(
+            "review_escalation",
+            `Feature review requested more changes after ${reviewContext.maxReviewRounds} automatic remediation round(s) were used. Ask the user whether to authorize another remediation round, accept the documented risk, change scope, or hold the Feature.`,
+            true,
+            null,
+            void 0,
+            reviewContext
+          ),
+          approvalRequired: true,
+          implementationAllowed: false,
+          primaryActionLabel: "A",
+          actionOptions: [
+            buildStageOption("A", "A", "review_retry", "Increase workflow.agentReview.maxRounds, then run one more Feature remediation and fresh review round."),
+            buildStageOption("B", "B", "hold", "Hold the Feature for user resolution.")
+          ],
+          blockedReasonCode: "PRE_PR_REVIEW_NOT_APPROVED"
+        };
+      }
+      if (evidenceMatchesTarget) {
+        return {
+          status: "ok",
+          reasonCode: "WORKFLOW_STAGE_RESOLVED",
+          docsDir: config.docsDir,
+          featureRef: buildFeatureRef(feature),
+          stage: "feature_review_fix",
+          nextAction: buildAction(
+            "feature_review_fix",
+            `Address the Feature review findings, commit the remediation, record review round ${reviewContext.reviewRound + 1}, and request a fresh review of the new code tree before implementation approval.`,
+            false,
+            null,
+            void 0,
+            reviewContext
+          ),
+          approvalRequired: false,
+          implementationAllowed: true,
+          blockedReasonCode: "PRE_PR_REVIEW_NOT_APPROVED"
+        };
+      }
     }
     if (reviewContext && evidenceMatchesTarget && tasks.prePrDecisionOutcome === "blocked") {
       return {
@@ -10147,6 +10322,7 @@ async function collectWorkflowStage(cwd, selector, component) {
       };
     }
     if (!featureReviewSatisfied(config, feature, tasks, reviewTarget)) {
+      const requestedRound = reviewContext && !evidenceMatchesTarget && tasks.prePrDecisionOutcome ? reviewContext.reviewRound + 1 : reviewContext?.reviewRound;
       return {
         status: "ok",
         reasonCode: "WORKFLOW_STAGE_RESOLVED",
@@ -10155,11 +10331,11 @@ async function collectWorkflowStage(cwd, selector, component) {
         stage: "pre_pr_review",
         nextAction: buildAction(
           "pre_pr_review",
-          reviewTarget ? `Delegate an independent read-only Feature review to a fresh subagent for ${reviewTarget.baseSha}..${reviewTarget.targetSha}. Record findings, decision, reviewer metadata, Pre-PR Reviewed Head, and Pre-PR Reviewed Tree as evidence.` : "Create a project commit before requesting the independent Feature review.",
+          reviewTarget ? `Delegate independent read-only Feature review round ${requestedRound} to a fresh subagent for ${reviewTarget.baseSha}..${reviewTarget.targetSha}. Record Review Round, findings, decision, reviewer metadata, Pre-PR Reviewed Head, and Pre-PR Reviewed Tree as evidence.` : "Create a project commit before requesting the independent Feature review.",
           false,
           null,
           reviewTarget ? resolveAgentReviewer(config, "feature") : void 0,
-          reviewContext || void 0
+          reviewContext ? { ...reviewContext, reviewRound: requestedRound } : void 0
         ),
         approvalRequired: false,
         implementationAllowed: false,