pi-long-task 0.3.10 → 0.3.11

package/README.md

@@ -280,7 +280,7 @@ Use `pi_goal_task` when you have a high-level outcome instead of a ready TODO pl
 Use pi_goal_task with goal "modernize the settings page, add tests, and update docs" and commit true.
 ```
 
-Goal loops default to `commit true`, `maxIterations 50`, a 48-hour total timeout, 3 hours per implementation iteration, and 30 minutes per reviewer pass. Override limits when you want a larger or smaller loop.
+Goal loops default to `commit true`, `minIterations 1`, `maxIterations 50`, a 48-hour total timeout, 3 hours per implementation iteration, and 30 minutes per reviewer pass. Override limits when you want a larger or smaller loop. When you explicitly set `maxIterations` without `minIterations`, that number also becomes the minimum target, so the loop will not stop early just because a reviewer found one pass complete.
 
 Examples:
 
@@ -289,14 +289,14 @@ Run a goal task with commits for goal: build a full Slack alternative chat app f
 ```
 
 ```text
-Use pi_goal_task with goal "build a full Slack alternative chat app focused on speed" and commit true and maxIterations 100.
+Use pi_goal_task with goal "build a full Slack alternative chat app focused on speed" and commit true and minIterations 100 and maxIterations 100.
 ```
 
 ```text
 Use pi_goal_task with goal "ship a polished analytics dashboard with onboarding, tests, docs, and launch notes" and commit false and maxIterations 20.
 ```
 
-For broad software-product goals like the Slack example, `pi_goal_task` first creates a software/product specification, then generates implementation TODOs from that spec, runs them, reviews completion, and repeats until the spec is complete or safety limits stop the loop.
+For broad software-product goals like the Slack example, `pi_goal_task` first creates a software/product specification, then generates implementation TODOs from that spec, runs them, reviews completion, and repeats until the spec is complete and the minimum iteration target is reached, or until safety limits stop the loop.
 
 ### Discovery for vague software goals
 
@@ -335,7 +335,8 @@ Goal-loop artifacts are stored under `tmp/pi-goal-task/<goal-run-id>/`, includin
 
 Safety controls:
 
-- `maxIterations` stops retry loops when the reviewer keeps finding remaining work; default is `50`.
+- `minIterations` prevents early success before the requested number of loops; default is `1`.
+- `maxIterations` stops retry loops when the reviewer keeps finding remaining work; default is `50`. If explicitly provided without `minIterations`, it is also used as the minimum target.
 - `timeoutMs` caps the overall goal loop; default is `172800000` ms (48 hours).
 - `iterationTimeoutMs` caps each generated TODO worker iteration; default is `10800000` ms (3 hours).
 - `reviewerTimeoutMs` caps each reviewer session; default is `1800000` ms (30 minutes).
@@ -365,6 +366,7 @@ Safety controls:
 {
   goal: string;
   commit?: boolean;
+  minIterations?: number;
   maxIterations?: number;
   timeoutMs?: number;
   iterationTimeoutMs?: number;
@@ -383,7 +385,7 @@ Use pi_goal_task with goal "build a full Slack alternative chat app focused on s
 ```
 
 ```text
-Use pi_goal_task with goal "build a full Slack alternative chat app focused on speed" and commit true and maxIterations 100 and timeoutMs 172800000.
+Use pi_goal_task with goal "build a full Slack alternative chat app focused on speed" and commit true and minIterations 100 and maxIterations 100 and timeoutMs 1296000000.
 ```
 
 For natural-language requests, Pi Long Task routes phrases like "run a long task with commits" to the tool with commits enabled. Phrases like "with goal to have testing line coverage above 80%" are parsed into the `goal` option. If you ask for a long task without mentioning commits, commits stay disabled.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-long-task",
-  "version": "0.3.10",
+  "version": "0.3.11",
   "type": "module",
   "description": "Pi extension for breaking down and running long coding tasks safely.",
   "keywords": [

package/src/goal_discovery.ts

@@ -167,7 +167,7 @@ function buildScopedRequirements(goal: string): GoalScopedRequirements {
       {
         id: "REQ-1",
         title: "Primary product outcome",
-        description: `Define and deliver the smallest coherent software/product slice that satisfies the user goal: ${goal}`,
+        description: `Define and deliver the complete scoped software/product outcome described by the user goal: ${goal}`,
         priority: "must",
         acceptanceCriterionIds: ["AC-1", "AC-2"],
         milestoneIds: ["MS-1", "MS-2"],
@@ -252,10 +252,10 @@ function buildScopedRequirements(goal: string): GoalScopedRequirements {
       "Implementation workers should use this persisted specification as the definition-of-done instead of relying only on the original vague goal.",
     ],
     openQuestions: [
-      "Who are the primary and secondary users, and what job-to-be-done should the first implementation slice satisfy?",
+      "Who are the primary and secondary users, and what job-to-be-done should the complete scoped product satisfy?",
       "Which repository areas, platforms, integrations, or external services constrain the implementation?",
       "What measurable product or operational signal proves the delivered slice is successful?",
-      "Which non-goals or edge cases must remain out of scope for the first implementation pass?",
+      "Which non-goals or edge cases must remain out of scope for this goal-oriented delivery?",
     ],
   };
 }
@@ -338,7 +338,7 @@ function buildAcceptanceCriteria(goal: string): GoalAcceptanceCriterion[] {
     {
       id: "AC-6",
       description:
-        "Relevant launch, positioning, target segment, and growth metric context is available or explicitly deemed unnecessary for the first slice.",
+        "Relevant launch, positioning, target segment, and growth metric context is available or explicitly deemed unnecessary for the scoped goal.",
       requirementIds: ["REQ-6"],
       verificationGateIds: ["VG-5"],
     },
@@ -409,7 +409,7 @@ function buildDesignConstraints(goal: string): GoalDesignConstraints {
     uxPrinciples: [
       "Optimize for the primary user workflow before secondary or administrative flows.",
       "Prefer clear, reversible, and observable interactions over hidden automation.",
-      "Keep first-slice UX simple enough for implementation workers to verify without stakeholder interviews.",
+      "Keep UX states explicit enough for implementation workers to verify without stakeholder interviews.",
     ],
     uiRequirements: [
       `Any user-facing UI for '${goal}' should use existing project components, layout conventions, and content tone where available.`,
@@ -433,7 +433,7 @@ function buildDesignConstraints(goal: string): GoalDesignConstraints {
       },
       {
         id: "DC-2",
-        title: "Accessible first slice",
+        title: "Accessible scoped product",
         description:
           "Do not mark user-facing work complete without considering keyboard, screen-reader, and contrast needs.",
       },
@@ -457,8 +457,8 @@ function buildProductConstraints(goal: string): GoalProductConstraints {
       "Pi goal-task orchestration artifacts under the run directory.",
     ],
     businessRules: [
-      "Only first-slice behavior required to satisfy the scoped goal should be implemented.",
-      "Out-of-scope enhancements require a later goal or explicit stakeholder decision.",
+      "All behavior required to satisfy the scoped goal should be implemented, while unrelated expansion stays out of scope.",
+      "Out-of-scope enhancements require a later goal or explicit stakeholder decision",
     ],
     compliance: [
       "Respect existing authorization, privacy, data-retention, and safety constraints present in the repository.",
@@ -476,8 +476,9 @@ function buildProductConstraints(goal: string): GoalProductConstraints {
     constraints: [
       {
         id: "PC-1",
-        title: "Scoped first release",
-        description: "Deliver a coherent first slice rather than a broad product rewrite or speculative roadmap.",
+        title: "Scoped full-goal delivery",
+        description:
+          "Deliver the complete scoped goal rather than downgrading broad user intent to an MVP or speculative roadmap.",
       },
       {
         id: "PC-2",
@@ -497,11 +498,11 @@ function buildMarketingGrowthContext(goal: string): GoalMarketingGrowthContext {
   return {
     targetSegments: [
       `Users, teams, or operators whose workflow improves when '${goal}' is delivered.`,
-      "Early internal adopters or reviewers who can validate the first implementation slice.",
+      "Early internal adopters or reviewers who can validate the delivered scoped product.",
     ],
     positioning: [
-      "A scoped software improvement with a clear first-use outcome and reviewable definition-of-done.",
-      "Avoid promising broad product transformation beyond the accepted first slice.",
+      "A scoped software product outcome with clear user value and reviewable definition-of-done.",
+      "Avoid downgrading explicit user intent to a partial MVP unless the user asked for an MVP.",
     ],
     acquisitionChannels: [
       "Release notes, README/update documentation, in-app messaging, or internal handoff notes as appropriate.",
@@ -525,10 +526,11 @@ function buildDiscoveryConsolidation(goal: string): GoalDiscoveryConsolidation {
       {
         role: "product_owner",
         title: "Product Owner",
-        objective: "Define user value, first-slice scope, non-goals, and product acceptance for the vague goal.",
+        objective:
+          "Define user value, full scoped product requirements, non-goals, and product acceptance for the vague goal.",
         findings: [
           `The goal '${goal}' needs a primary user outcome before implementation begins.`,
-          "Scope should emphasize one coherent product slice and preserve unresolved stakeholder questions.",
+          "Scope should preserve explicit user requirements as mandatory and clarify any unresolved stakeholder questions.",
         ],
         decisions: [
           "Use REQ-1 as the core product outcome and AC-1 as the primary acceptance criterion.",
@@ -573,7 +575,7 @@ function buildDiscoveryConsolidation(goal: string): GoalDiscoveryConsolidation {
           "Use REQ-3 and AC-4 to constrain technical design.",
           "Make architecture/regression review a required gate.",
         ],
-        risks: ["New dependencies or rewrites could exceed the first-slice product scope."],
+        risks: ["New dependencies or rewrites could exceed the scoped product requirements."],
         requirementIds: ["REQ-3"],
         milestoneIds: ["MS-2"],
         acceptanceCriterionIds: ["AC-4", "AC-5"],
@@ -587,7 +589,7 @@ function buildDiscoveryConsolidation(goal: string): GoalDiscoveryConsolidation {
           "Translate vague product intent into workflow, UI state, accessibility, and design-system constraints.",
         findings: [
           "User-facing work needs explicit workflow states and accessibility expectations.",
-          "Existing design conventions should guide any first-slice UI rather than a new visual direction.",
+          "Existing design conventions should guide product UI unless the discovered requirements call for a new visual direction.",
         ],
         decisions: [
           "Use REQ-4 and AC-3 to keep UX/design review in scope.",
@@ -655,7 +657,7 @@ function buildDefinitionOfDone(
 ): GoalDefinitionOfDone {
   return {
     summary:
-      "Done when all must/should scoped requirements are implemented or explicitly deferred, acceptance criteria are satisfied, required verification gates pass or record justified blockers, and review evaluates the result against this persisted product definition.",
+      "Done when all must/should scoped requirements are implemented, acceptance criteria are satisfied, required verification gates pass or record justified blockers, and review evaluates the result against this persisted product definition. Do not treat a partial MVP as complete when the original goal requests a broader product.",
     requirementIds,
     acceptanceCriterionIds,
     verificationGateIds: requiredGateIds,

package/src/goal_loop.ts

@@ -5,6 +5,7 @@ import type { CoordinatorStatus } from "./types.ts";
 export const GOAL_LOOP_STATE_SCHEMA_VERSION = 1;
 
 export const DEFAULT_GOAL_LOOP_LIMITS = {
+  minIterations: 1,
   maxIterations: 50,
   timeoutMs: 172_800_000,
   iterationTimeoutMs: 10_800_000,
@@ -35,6 +36,7 @@ export type GoalIterationStatus =
 export type GoalLoopStopKind = "cancelled" | "timeout" | "max_iterations" | "complete";
 
 export interface GoalLoopLimits {
+  minIterations: number;
   maxIterations: number;
   timeoutMs: number;
   iterationTimeoutMs: number;
@@ -42,6 +44,7 @@ export interface GoalLoopLimits {
 }
 
 export interface GoalLoopLimitInput {
+  minIterations?: number;
   maxIterations?: number;
   timeoutMs?: number;
   iterationTimeoutMs?: number;
@@ -169,8 +172,16 @@ export class GoalLoopStateError extends Error {
 }
 
 export function normalizeGoalLoopLimits(input: GoalLoopLimitInput = {}): GoalLoopLimits {
+  const explicitMaxIterations = optionalPositiveInteger(input.maxIterations);
+  const minIterations = positiveInteger(
+    input.minIterations,
+    explicitMaxIterations ?? DEFAULT_GOAL_LOOP_LIMITS.minIterations,
+  );
+  const maxIterations = Math.max(minIterations, explicitMaxIterations ?? DEFAULT_GOAL_LOOP_LIMITS.maxIterations);
+
   return {
-    maxIterations: positiveInteger(input.maxIterations, DEFAULT_GOAL_LOOP_LIMITS.maxIterations),
+    minIterations,
+    maxIterations,
     timeoutMs: positiveMilliseconds(input.timeoutMs, DEFAULT_GOAL_LOOP_LIMITS.timeoutMs),
     iterationTimeoutMs: positiveMilliseconds(input.iterationTimeoutMs, DEFAULT_GOAL_LOOP_LIMITS.iterationTimeoutMs),
     reviewerTimeoutMs: positiveMilliseconds(input.reviewerTimeoutMs, DEFAULT_GOAL_LOOP_LIMITS.reviewerTimeoutMs),
@@ -442,6 +453,10 @@ export function validateGoalLoopState(value: unknown): GoalLoopState {
   if (!state.limits || typeof state.limits !== "object") {
     throw new GoalLoopStateError("Goal loop state is missing limits.");
   }
+  state.limits = normalizeGoalLoopLimits({
+    ...state.limits,
+    minIterations: state.limits.minIterations ?? DEFAULT_GOAL_LOOP_LIMITS.minIterations,
+  });
   if (!Array.isArray(state.iterations) || !Array.isArray(state.trace)) {
     throw new GoalLoopStateError("Goal loop state is missing iterations or trace arrays.");
   }
@@ -553,10 +568,14 @@ function withTrace(state: GoalLoopState, event: GoalLoopTraceEvent): GoalLoopSta
 }
 
 function positiveInteger(value: number | undefined, fallback: number): number {
+  return optionalPositiveInteger(value) ?? fallback;
+}
+
+function optionalPositiveInteger(value: number | undefined): number | undefined {
   if (typeof value === "number" && Number.isFinite(value) && value > 0) {
     return Math.floor(value);
   }
-  return fallback;
+  return undefined;
 }
 
 function positiveMilliseconds(value: number | undefined, fallback: number): number {

package/src/goal_orchestrator.ts

@@ -52,6 +52,7 @@ export interface GoalLoopProgressUpdate {
   status: GoalLoopStatus;
   currentIteration: number;
   totalIterations: number;
+  minIterations: number;
   maxIterations: number;
   limits: GoalLoopLimits;
   resultPath: string;
@@ -125,6 +126,7 @@ export async function runGoalLoop(options: RunGoalLoopOptions): Promise<GoalLoop
       goalRunId:
         options.goalRunId ?? `goal-${new Date().toISOString().replace(/[:.]/g, "-")}-${randomUUID().slice(0, 8)}`,
       goalRunDir: options.goalRunDir,
+      minIterations: options.minIterations,
       maxIterations: options.maxIterations,
       timeoutMs: options.timeoutMs,
       iterationTimeoutMs: options.iterationTimeoutMs,
@@ -155,6 +157,7 @@ export async function runGoalLoop(options: RunGoalLoopOptions): Promise<GoalLoop
       status: state.status,
       currentIteration: state.currentIteration,
       totalIterations: state.iterations.length,
+      minIterations: state.limits.minIterations,
       maxIterations: state.limits.maxIterations,
       limits: state.limits,
       resultPath: store.paths.resultPath,

package/src/goal_review.ts

@@ -180,6 +180,8 @@ export async function runGoalReviewSession(options: GoalReviewOptions): Promise<
     });
   }
 
+  reviewerResult = enforceMinimumIterationsBeforeCompletion(reviewerResult, state, iteration.iteration);
+
   state = recordReviewerResult(state, iteration.iteration, reviewerResult, { now: now() });
   await persistStateChange(store, previousTraceLength, state);
   const updatedIteration = currentIteration(state, iteration.iteration);
@@ -220,6 +222,11 @@ export function buildGoalReviewTaskPayload(options: {
   const reviewTargetInstruction = options.goalSpecification
     ? "Review whether the latest worker run satisfies the persisted goal specification and definition-of-done. Treat the persisted specification as the primary review target; keep the original high-level goal available only as traceability/context."
     : "Review whether the original high-level goal is complete after the latest worker run.";
+  const iterationPolicy = `Goal loop iteration policy:
+- Current iteration: ${iteration.iteration}
+- Minimum iterations before completion may stop the loop: ${state.limits.minIterations}
+- Maximum iterations: ${state.limits.maxIterations}
+- If current iteration is below the minimum, do not return "complete" even if the current implementation looks good. Return "incomplete" with concrete remainingWork for the next improvement pass, such as missing verification, hardening, UX polish, security, performance, docs, edge cases, or maintainability follow-up.`;
   const decisionRules = options.goalSpecification
     ? `- Use "complete" only when the persisted definition-of-done is satisfied, including in-scope requirements, milestones, acceptance criteria, required verification gates, and applicable design/product constraints.
 - Use "incomplete" when any required spec requirement, milestone, acceptance criterion, verification gate, artifact, or constraint still needs work and another TODO-generation iteration should be started.
@@ -242,6 +249,8 @@ ${specificationBlock}
 Goal run: ${state.goalRunId}
 Iteration: ${iteration.iteration}
 Generated TODO path: ${generatedTodo?.todoPath ?? "unknown"}
+
+${iterationPolicy}
 Worker result:
 
 ${markdownFence(JSON.stringify(workerResult ?? null, null, 2), "json")}
@@ -279,6 +288,38 @@ export function parseGoalReviewerOutput(
   };
 }
 
+function enforceMinimumIterationsBeforeCompletion(
+  result: GoalReviewerResultState,
+  state: GoalLoopState,
+  iteration: number,
+): GoalReviewerResultState {
+  if (result.decision !== "complete" && !result.complete) {
+    return result;
+  }
+  if (iteration >= state.limits.minIterations) {
+    return result;
+  }
+
+  const remainingIterations = Math.max(1, state.limits.minIterations - iteration);
+  const remainingWork = result.remainingWork.length > 0 ? result.remainingWork : minimumIterationRemainingWork(state);
+  return {
+    ...result,
+    decision: "incomplete",
+    complete: false,
+    summary: `Minimum iteration target not reached (${iteration}/${state.limits.minIterations}); continuing goal loop.`,
+    rationale: `${result.rationale}\n\nReviewer completion was deferred because this goal loop requires at least ${state.limits.minIterations} iteration(s) before it may stop. ${remainingIterations} more iteration(s) are required, so the next pass should look for concrete improvements, hardening, verification, and polish rather than stopping early.`,
+    remainingWork,
+  };
+}
+
+function minimumIterationRemainingWork(state: GoalLoopState): string[] {
+  return [
+    `Continue toward the required minimum of ${state.limits.minIterations} goal-loop iterations before accepting completion.`,
+    "Run another pass focused on gaps the previous TODO did not cover: verification depth, edge cases, security, performance, UX polish, documentation, maintainability, and product completeness.",
+    "Generate concrete implementation or review tasks from the persisted goal specification and latest evidence instead of stopping after the first apparently complete pass.",
+  ];
+}
+
 export async function runGoalReviewerSession(options: GoalReviewerRunnerOptions): Promise<GoalReviewerSessionResult> {
   const sessionFactory = options.sessionFactory ?? createIsolatedWorkerSession;
   const events: unknown[] = [];

package/src/goal_state.ts

@@ -112,6 +112,7 @@ export class GoalStateStore {
       "",
       "## Safety limits",
       "",
+      `- Minimum iterations before completion: ${state.limits.minIterations}`,
       `- Max iterations: ${state.limits.maxIterations}`,
       `- Run timeout: ${state.limits.timeoutMs}ms`,
       `- Iteration timeout: ${state.limits.iterationTimeoutMs}ms`,

package/src/goal_todo_generation.ts

@@ -147,7 +147,7 @@ export async function runGoalTodoGenerationLongTask(
 }
 
 export function buildGoalTodoGenerationTaskPayload(options: {
-  state: Pick<GoalLoopState, "goal" | "goalRunId">;
+  state: Pick<GoalLoopState, "goal" | "goalRunId" | "limits">;
   iteration: number;
   outputPath: string;
   additionalContext?: string;
@@ -162,6 +162,8 @@ export function buildGoalTodoGenerationTaskPayload(options: {
         "markdown",
       )}\n`
     : "";
+  const iterationPolicy = `- Goal-loop iteration target: generate implementation work for iteration ${options.iteration} of at least ${options.state.limits.minIterations} required iteration(s), with a hard maximum of ${options.state.limits.maxIterations}.
+- Do not generate a no-op TODO merely because a previous reviewer believed the goal was complete before the minimum iteration target. Always look for the next concrete improvement, hardening, verification, UX, security, performance, docs, maintainability, or product-completeness pass until the minimum is reached.`;
 
   return `# Pi Long Task TODO
 
@@ -173,6 +175,7 @@ export function buildGoalTodoGenerationTaskPayload(options: {
 - Write the generated Pi Long Task-compatible TODO markdown to \`${options.outputPath}\`.
 - Do not wrap the generated file in a code fence and do not include commentary outside the TODO markdown in that file.
 - Keep generated tasks focused, independently assignable, and safe for separate worker sessions.
+${iterationPolicy}
 ${
   options.goalSpecification
     ? "- A persisted goal specification is available; derive implementation TODOs from that specification rather than only the original vague goal.\n- Ensure generated tasks explicitly cover relevant requirement IDs, milestones, acceptance criteria, verification gates, constraints, and definition-of-done items from the specification.\n- Include spec IDs (for example REQ-*, MS-*, AC-*, VG-*) in generated task goals/status/verification/done-when guidance wherever applicable.\n"

package/src/input_router.ts

@@ -21,6 +21,8 @@ const COMMIT_TRUE_RE =
 const GOAL_RE = /\b(?:with\s+(?:the\s+)?goal|goal)\s*(?::|=|\b(?:to|of|for|that)\b)\s*([\s\S]+)$/i;
 const TRAILING_COMMIT_MODIFIER_RE =
   /(?:\s+(?:with|without|no|enable|enabled|disable|disabled)\s+commits?|\s+commits?\s*(?:true|false|on|off|enabled|disabled)|\s+commit\s*:\s*(?:true|false|on|off|yes|no))\s*$/i;
+const TRAILING_ITERATION_MODIFIER_RE =
+  /(?:[.;,\s]+(?:(?:use|set)?\s*(?:min(?:imum)?|max(?:imum)?)\s+(?:iterations?|loops?|passes?|cycles?)\s*(?::|=|of|to)?\s*\d+|at\s+least\s+\d+\s*(?:iterations?|loops?|passes?|cycles?)|(?:i\s+want\s+it\s+to\s+)?run\s+(?:for|in)\s*\d+\s*(?:iterations?|loops?|passes?|cycles?)))[.!?]*\s*$/i;
 
 export interface ParsedLongTaskRequestOptions {
   commit: boolean;
@@ -28,6 +30,7 @@ export interface ParsedLongTaskRequestOptions {
 }
 
 export interface ParsedGoalTaskRequestOptions extends ParsedLongTaskRequestOptions {
+  minIterations?: number;
   maxIterations?: number;
 }
 
@@ -60,10 +63,13 @@ export function parseLongTaskRequestOptions(text: string): ParsedLongTaskRequest
 }
 
 export function parseGoalTaskRequestOptions(text: string): ParsedGoalTaskRequestOptions {
+  const maxIterations = inferMaxIterations(text);
+  const minIterations = inferMinIterations(text) ?? inferExactIterationCount(text) ?? maxIterations;
   return {
     commit: inferCommitSetting(text) ?? true,
     goal: inferGoalSetting(text) ?? inferGoalLoopText(text),
-    maxIterations: inferMaxIterations(text),
+    minIterations,
+    maxIterations,
   };
 }
 
@@ -114,17 +120,38 @@ export function inferGoalSetting(text: string): string | undefined {
 
 function normalizeGoalText(text: string): string | undefined {
   let goal = text.trim();
-  while (TRAILING_COMMIT_MODIFIER_RE.test(goal)) {
-    goal = goal.replace(TRAILING_COMMIT_MODIFIER_RE, "").trim();
+  while (TRAILING_COMMIT_MODIFIER_RE.test(goal) || TRAILING_ITERATION_MODIFIER_RE.test(goal)) {
+    goal = goal.replace(TRAILING_COMMIT_MODIFIER_RE, "").replace(TRAILING_ITERATION_MODIFIER_RE, "").trim();
   }
   goal = goal.replace(/^["'“”‘’]+|["'“”‘’.,;:!?]+$/g, "").trim();
   return goal || undefined;
 }
 
 function inferMaxIterations(text: string): number | undefined {
-  const match = /\bmax(?:imum)?\s+(?:iterations?|loops?|passes?)\s*(?::|=|of|to)?\s*(\d+)\b/i.exec(text);
-  const value = match?.[1] ? Number.parseInt(match[1], 10) : undefined;
-  return value && Number.isFinite(value) && value > 0 ? value : undefined;
+  const match = /\bmax(?:imum)?\s+(?:iterations?|loops?|passes?|cycles?)\s*(?::|=|of|to)?\s*(\d+)\b/i.exec(text);
+  return positiveIntegerMatch(match?.[1]);
+}
+
+function inferMinIterations(text: string): number | undefined {
+  const explicitMin = /\bmin(?:imum)?\s+(?:iterations?|loops?|passes?|cycles?)\s*(?::|=|of|to)?\s*(\d+)\b/i.exec(text);
+  if (explicitMin?.[1]) {
+    return positiveIntegerMatch(explicitMin[1]);
+  }
+  const atLeast = /\bat\s+least\s+(\d+)\s*(?:iterations?|loops?|passes?|cycles?)\b/i.exec(text);
+  return positiveIntegerMatch(atLeast?.[1]);
+}
+
+function inferExactIterationCount(text: string): number | undefined {
+  const match =
+    /\b(?:run|iterate|loop|cycle|spin)(?:\s+\w+){0,6}?\s+(?:for|in)?\s*(\d+)\s*(?:iterations?|loops?|passes?|cycles?)\b/i.exec(
+      text,
+    );
+  return positiveIntegerMatch(match?.[1]);
+}
+
+function positiveIntegerMatch(value: string | undefined): number | undefined {
+  const parsed = value ? Number.parseInt(value, 10) : undefined;
+  return parsed && Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
 }
 
 function inferGoalLoopText(text: string): string | undefined {
@@ -158,11 +185,13 @@ function buildGoalTaskToolPrompt(originalText: string, options: ParsedGoalTaskRe
   const goalLine = options.goal
     ? `Set goal to ${JSON.stringify(options.goal)}.`
     : "Set goal from the original request.";
+  const minIterationsLine = options.minIterations ? [`Set minIterations to ${options.minIterations}.`] : [];
   const maxIterationsLine = options.maxIterations ? [`Set maxIterations to ${options.maxIterations}.`] : [];
   return [
     "Use the pi_goal_task tool for this request.",
     goalLine,
     `Set commit to ${options.commit ? "true" : "false"}.`,
+    ...minIterationsLine,
     ...maxIterationsLine,
     "The goal loop will generate TODO markdown, execute it as a long task, review completion, and repeat until complete or stopped by limits.",
     "Do not perform the work directly outside pi_goal_task.",

package/src/render.ts

@@ -126,6 +126,7 @@ export interface GoalTaskToolRenderDetails {
   status: GoalLoopStatus;
   currentIteration: number;
   totalIterations: number;
+  minIterations: number;
   maxIterations: number;
   resultPath: string;
   statePath?: string;
@@ -145,6 +146,7 @@ export function formatGoalLoopResultMessage(result: GoalLoopResultForRendering):
     `Pi Goal Task: ${state.status}`,
     `Goal: ${state.goal}`,
     `Iterations: ${state.iterations.length}/${state.limits.maxIterations}`,
+    `Minimum iterations: ${state.limits.minIterations}`,
     `Result file: ${result.resultPath}`,
     `State file: ${state.goalRunDir}/GOAL_STATE.json`,
   ];
@@ -174,6 +176,7 @@ export function goalTaskDetailsFromResult(result: GoalLoopResultForRendering): G
     status: result.state.status,
     currentIteration: result.state.currentIteration,
     totalIterations: result.state.iterations.length,
+    minIterations: result.state.limits.minIterations,
     maxIterations: result.state.limits.maxIterations,
     resultPath: result.resultPath,
     statePath: `${result.state.goalRunDir}/GOAL_STATE.json`,
@@ -188,12 +191,20 @@ export function goalTaskDetailsFromResult(result: GoalLoopResultForRendering): G
 }
 
 export function renderGoalTaskToolCall(
-  args: { goal?: string; commit?: boolean; maxIterations?: number; timeoutMs?: number; reviewerTimeoutMs?: number },
+  args: {
+    goal?: string;
+    commit?: boolean;
+    minIterations?: number;
+    maxIterations?: number;
+    timeoutMs?: number;
+    reviewerTimeoutMs?: number;
+  },
   theme: Theme,
 ): Text {
   const commit = (args.commit ?? true) ? theme.fg("warning", "commit:on") : theme.fg("dim", "commit:off");
   const goal = oneLine(args.goal ?? "");
   const limits = [
+    args.minIterations ? `min:${args.minIterations}` : undefined,
     args.maxIterations ? `max:${args.maxIterations}` : undefined,
     args.timeoutMs ? `timeout:${args.timeoutMs}ms` : undefined,
     args.reviewerTimeoutMs ? `review:${args.reviewerTimeoutMs}ms` : undefined,
@@ -227,11 +238,13 @@ function renderGoalTaskProgress(details: Record<string, unknown> | undefined, fa
   const message = stringValue(details?.message) || firstLine(fallback) || "Pi Goal Task is running...";
   const phase = stringValue(details?.phase);
   const iteration = numberValue(details?.iteration) ?? numberValue(details?.currentIteration);
+  const minIterations = numberValue(details?.minIterations);
   const maxIterations = numberValue(details?.maxIterations);
   const status = stringValue(details?.status) || "running";
   const cost = numberValue(details?.totalCost);
   const meta = [
     iteration ? `iteration ${iteration}${maxIterations ? `/${maxIterations}` : ""}` : undefined,
+    minIterations && iteration && iteration < minIterations ? `min:${minIterations}` : undefined,
     status,
     cost && cost > 0 ? formatCost(cost) : undefined,
   ]
@@ -249,6 +262,7 @@ function renderGoalTaskSummary(details: GoalTaskToolRenderDetails, expanded: boo
   const summary = [
     `${theme.fg(statusStyle, icon)} ${theme.fg("toolTitle", theme.bold("Pi Goal Task"))} ${theme.fg(statusStyle, details.status)}`,
     theme.fg("muted", `${details.totalIterations}/${details.maxIterations} iterations`),
+    details.totalIterations < details.minIterations ? theme.fg("muted", `min:${details.minIterations}`) : undefined,
     details.latestReviewerDecision ? theme.fg("muted", `review:${details.latestReviewerDecision}`) : undefined,
     details.totalCost ? theme.fg("muted", `spend ${formatCost(details.totalCost)}`) : undefined,
   ].filter(Boolean);
@@ -295,6 +309,7 @@ function goalTaskDetails(details: Record<string, unknown> | undefined): GoalTask
     status,
     currentIteration: numberValue(details.currentIteration) ?? 0,
     totalIterations: numberValue(details.totalIterations) ?? 0,
+    minIterations: numberValue(details.minIterations) ?? 0,
     maxIterations: numberValue(details.maxIterations) ?? 0,
     resultPath,
     statePath: stringValue(details.statePath),

package/src/types.ts

@@ -37,10 +37,18 @@ export const PiGoalTaskParams = Type.Object(
           "Whether worker long tasks may commit completed TODO work during the goal loop. Defaults to true for goal loops.",
       }),
     ),
+    minIterations: Type.Optional(
+      Type.Integer({
+        minimum: 1,
+        description:
+          "Minimum number of generate → execute → review iterations before a complete review may stop the loop. If omitted while maxIterations is provided, maxIterations is also used as the minimum target.",
+      }),
+    ),
     maxIterations: Type.Optional(
       Type.Integer({
         minimum: 1,
-        description: "Maximum number of generate → execute → review iterations before stopping. Defaults to 50.",
+        description:
+          "Maximum number of generate → execute → review iterations before stopping. Defaults to 50; when explicitly provided without minIterations, it also acts as the minimum target.",
       }),
     ),
     timeoutMs: Type.Optional(