pi-long-task 0.3.8 → 0.3.10

package/src/coordinator.ts

@@ -11,18 +11,21 @@ import type {
 import { commitAfterSession, gitDirtyPaths, shouldCommitOutcome, type CommitAfterSessionResult } from "./git.ts";
 import { formatCoordinatorResultMessage } from "./render.ts";
 import { extractResultSummary } from "./result_writer.ts";
+import { runGuardedSessionPrompt } from "./session_guard.ts";
 import { parseWorkerRuntimeConfig } from "./worker_config.ts";
 import { buildTaskProgressModel, type TaskProgressModel, type TaskProgressStatus } from "./task_progress.ts";
 import {
+  applyGoalInstructionsToTodoMarkdown,
   buildTodoCreationPrompt,
-  extractTodoMarkdown,
+  buildTodoRepairPrompt,
+  extractAndValidateTodoMarkdown,
+  TodoGenerationError,
   todoMarkdownFromString,
   validateTodoMarkdown,
 } from "./todo_generator.ts";
 import { markTaskDone, parseTasks, todoGlobalInstructions, type Task } from "./todo_parser.ts";
 import {
   createIsolatedWorkerSession,
-  lastAssistantTextFromMessages,
   runWorkerTask,
   type RunWorkerTaskOptions,
   type SessionOutcome,
@@ -35,6 +38,8 @@ export type { CoordinatorStatus } from "./types.ts";
 export const DEFAULT_COORDINATOR_OPTIONS = {
   maxAttemptsPerTask: 3,
   taskTimeoutMs: 900_000,
+  todoTimeoutMs: 300_000,
+  todoGracefulShutdownMs: 15_000,
   maxBashTimeoutMs: 300_000,
   taskThinking: "high",
   todoThinking: "xhigh",
@@ -51,6 +56,18 @@ export type CoordinatorProgressPhase =
   | "task_failed"
   | "complete";
 
+export type PlannerDiagnosticKind = "timeout" | "abort" | "invalid_output" | "repair_attempt" | "failure";
+
+export interface PlannerDiagnostic {
+  kind: PlannerDiagnosticKind;
+  message: string;
+  diagnostics?: string[];
+  sessionFile?: string;
+  sessionId?: string;
+}
+
+export type PlannerDiagnosticHandler = (diagnostic: PlannerDiagnostic) => void;
+
 export type CoordinatorProgressItemStatus = "empty" | "in_progress" | "done" | "failed" | "blocked";
 
 export interface CoordinatorProgressTask {
@@ -82,9 +99,14 @@ export interface CoordinatorProgressUpdate {
   isError?: boolean;
   totalTasks?: number;
   workerCostTotal: number;
+  goal?: string;
   currentTask?: CoordinatorProgressTask;
   subtasks?: CoordinatorProgressSubtask[];
   taskProgress?: TaskProgressModel;
+  plannerDiagnostic?: PlannerDiagnosticKind;
+  plannerDiagnostics?: string[];
+  plannerSessionFile?: string;
+  plannerSessionId?: string;
 }
 
 export type CoordinatorProgressHandler = (update: CoordinatorProgressUpdate) => void;
@@ -102,6 +124,8 @@ export interface RunCoordinatorOptions extends PiLongTaskInput {
   workerModelName?: string;
   maxAttemptsPerTask?: number;
   taskTimeoutMs?: number;
+  todoTimeoutMs?: number;
+  todoGracefulShutdownMs?: number;
   maxBashTimeoutMs?: number;
   taskThinking?: string;
   todoThinking?: string;
@@ -116,7 +140,11 @@ export interface TodoPlannerOptions {
   thinkingLevel: string;
   model?: unknown;
   abortSignal?: AbortSignal;
+  timeoutMs?: number;
+  gracefulShutdownMs?: number;
   sessionFactory?: WorkerSessionFactory;
+  onDiagnostic?: PlannerDiagnosticHandler;
+  goal?: string;
 }
 
 export interface TaskAttemptSummary {
@@ -152,6 +180,7 @@ export interface CoordinatorResult {
   taskProgress: TaskProgressModel;
   workerCostTotal: number;
   commit: boolean;
+  goal?: string;
   error?: string;
 }
 
@@ -173,8 +202,11 @@ interface RuntimeOptions {
   maxBashTimeoutSeconds: number;
   workerModel?: unknown;
   workerModelName?: string;
+  goal?: string;
   taskThinking: string;
   todoThinking: string;
+  todoTimeoutMs: number;
+  todoGracefulShutdownMs: number;
   workerRunner: WorkerRunner;
   todoPlanner: TodoPlanner;
   abortSignal?: AbortSignal;
@@ -183,21 +215,25 @@ interface RuntimeOptions {
   now: () => Date;
   onProgress?: CoordinatorProgressHandler;
   workerCostState: WorkerCostState;
+  plannerDiagnostics: PlannerDiagnostic[];
 }
 
 export async function runCoordinator(options: RunCoordinatorOptions): Promise<CoordinatorResult> {
   const runtime = buildRuntimeOptions(options);
+  const inputText = coordinatorInputText(options);
   const attempts: TaskAttemptSummary[] = [];
   const outcomes: SessionOutcome[] = [];
   const commits: CoordinatorCommitSummary[] = [];
 
   await mkdir(runtime.runDir, { recursive: true });
   await writeFile(runtime.taskResultPath, initialTaskResultMarkdown(runtime.runId), "utf8");
+  let planningComplete = false;
 
   try {
     emitProgress(runtime, "Creating TODO plan...", { phase: "planning" });
-    let todoMarkdown = await generateOrNormalizeTodoMarkdown(options.inputText, runtime);
+    let todoMarkdown = await generateOrNormalizeTodoMarkdown(inputText, runtime);
     validateTodoMarkdown(todoMarkdown);
+    planningComplete = true;
     await writeFile(runtime.todoPath, todoMarkdown, "utf8");
     const initialTasks = parseTasks(todoMarkdown);
     emitProgress(runtime, `Created TODO plan with ${initialTasks.length} task(s).`, {
@@ -244,6 +280,7 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
         commitRequested: options.commit,
         previousAttempts: previousAttempts.get(nextTask.taskId)?.join("\n\n---\n\n"),
         globalInstructions: todoGlobalInstructions(todoMarkdown),
+        goal: runtime.goal,
         maxBashTimeoutSeconds: runtime.maxBashTimeoutSeconds,
         taskTimeoutSeconds: runtime.taskTimeoutSeconds,
         model: runtime.workerModel,
@@ -367,6 +404,7 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
       taskProgress,
       workerCostTotal: runtime.workerCostState.total,
       commit: options.commit,
+      goal: runtime.goal,
       error: failure,
     };
     result.message = formatCoordinatorResultMessage(result);
@@ -379,9 +417,18 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
     return result;
   } catch (error) {
     const message = errorMessage(error);
-    const summary = `Pi Long Task failed: ${message}`;
+    if (!planningComplete) {
+      recordPlannerDiagnostic(runtime, {
+        kind: "failure",
+        message: `TODO planning failed: ${message}`,
+      });
+    }
+    const resultError = !planningComplete
+      ? `${message} See ${runtime.taskResultPath} for planner diagnostics.`
+      : message;
+    const summary = `Pi Long Task failed: ${resultError}`;
     try {
-      await appendFile(runtime.taskResultPath, `\n## Pi Long Task failure\n\n${message}\n`, "utf8");
+      await appendFailureNote(runtime.taskResultPath, message, !planningComplete ? runtime.plannerDiagnostics : []);
     } catch {
       // Best effort only; the original error is returned below.
     }
@@ -407,7 +454,8 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
       taskProgress: buildTaskProgressModel({ tasks: [], attempts }),
       workerCostTotal: runtime.workerCostState.total,
       commit: options.commit,
-      error: message,
+      goal: runtime.goal,
+      error: resultError,
     };
     result.message = formatCoordinatorResultMessage(result);
     emitProgress(runtime, "Pi Long Task failed.", {
@@ -420,62 +468,253 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
 }
 
 async function generateOrNormalizeTodoMarkdown(inputText: string, runtime: RuntimeOptions): Promise<string> {
-  const local = todoMarkdownFromString(inputText);
+  const local = todoMarkdownFromString(inputText, runtime.goal);
   if (local) {
     return local;
   }
 
-  const plannerText = await runtime.todoPlanner({
+  const plannerText = await requestTodoPlan(inputText, runtime);
+  const planned = await extractTodoMarkdownWithOneRepair(
+    inputText,
+    plannerText,
+    (repairPrompt) => requestTodoPlan(repairPrompt, runtime),
+    runtime.goal,
+    {
+      onInvalidOutput: (validationError) =>
+        recordPlannerDiagnostic(runtime, {
+          kind: "invalid_output",
+          message: `TODO planner returned invalid output: ${validationError}`,
+        }),
+      onRepairAttempt: (validationError) =>
+        recordPlannerDiagnostic(runtime, {
+          kind: "repair_attempt",
+          message: `Asking TODO planner to repair invalid output: ${validationError}`,
+        }),
+      onFailure: (validationError) =>
+        recordPlannerDiagnostic(runtime, {
+          kind: "failure",
+          message: `TODO planner repair failed: ${validationError}`,
+        }),
+    },
+  );
+  return applyGoalInstructionsToTodoMarkdown(planned, runtime.goal);
+}
+
+interface TodoExtractionRepairHooks {
+  onInvalidOutput?: (validationError: string) => void;
+  onRepairAttempt?: (validationError: string) => void;
+  onFailure?: (validationError: string) => void;
+}
+
+async function extractTodoMarkdownWithOneRepair(
+  inputText: string,
+  plannerText: string,
+  requestRepair: (repairPrompt: string) => Promise<string>,
+  goal?: string,
+  hooks: TodoExtractionRepairHooks = {},
+): Promise<string> {
+  try {
+    return extractAndValidateTodoMarkdown(plannerText);
+  } catch (error) {
+    const validationError = errorMessage(error);
+    hooks.onInvalidOutput?.(validationError);
+    hooks.onRepairAttempt?.(validationError);
+    const repairText = await requestRepair(buildTodoRepairPrompt(inputText, plannerText, validationError, goal));
+    try {
+      return extractAndValidateTodoMarkdown(repairText);
+    } catch (repairError) {
+      const repairMessage = errorMessage(repairError);
+      hooks.onFailure?.(repairMessage);
+      throw new TodoGenerationError(
+        `TODO planner returned invalid TODO markdown after one repair attempt: ${repairMessage}`,
+      );
+    }
+  }
+}
+
+async function requestTodoPlan(inputText: string, runtime: RuntimeOptions): Promise<string> {
+  return runtime.todoPlanner({
     inputText,
     cwd: runtime.cwd,
     runDir: runtime.runDir,
     thinkingLevel: runtime.todoThinking,
     model: runtime.workerModel,
     abortSignal: runtime.abortSignal,
+    timeoutMs: runtime.todoTimeoutMs,
+    gracefulShutdownMs: runtime.todoGracefulShutdownMs,
     sessionFactory: runtime.todoSessionFactory,
+    onDiagnostic: (diagnostic) => recordPlannerDiagnostic(runtime, diagnostic),
+    goal: runtime.goal,
   });
-  return extractTodoMarkdown(plannerText);
 }
 
+// Planner/worker lifecycle differences are audited in docs/planner-worker-lifecycle-audit.md;
+// keep this function's public contract stable while moving shared prompt guarding into a helper.
 export async function runTodoPlanner(options: TodoPlannerOptions): Promise<string> {
-  let session: WorkerSessionLike | undefined;
+  const sessionFactory = options.sessionFactory ?? createIsolatedWorkerSession;
+  const result = await sessionFactory({
+    cwd: options.cwd,
+    tools: [],
+    model: options.model,
+    thinkingLevel: options.thinkingLevel,
+  });
+  const session = result.session;
+  const timeoutMs = positiveMilliseconds(options.timeoutMs, DEFAULT_COORDINATOR_OPTIONS.todoTimeoutMs);
+  const gracefulShutdownMs = options.gracefulShutdownMs ?? DEFAULT_COORDINATOR_OPTIONS.todoGracefulShutdownMs;
+
+  let plannerMarkdown: string | undefined;
+  let plannerError: unknown;
+
   try {
-    const sessionFactory = options.sessionFactory ?? createIsolatedWorkerSession;
-    const result = await sessionFactory({
-      cwd: options.cwd,
-      tools: [],
-      model: options.model,
-      thinkingLevel: options.thinkingLevel,
+    const plannerText = await runTodoPlannerPrompt({
+      session,
+      prompt: buildTodoCreationPrompt(options.inputText, options.goal),
+      abortSignal: options.abortSignal,
+      timeoutMs,
+      gracefulShutdownMs,
+      diagnostics: result.diagnostics,
+      onDiagnostic: options.onDiagnostic,
     });
-    session = result.session;
 
-    if (options.abortSignal?.aborted) {
-      throw new Error("TODO planner aborted before start");
-    }
+    plannerMarkdown = await extractTodoMarkdownWithOneRepair(
+      options.inputText,
+      plannerText,
+      (repairPrompt) =>
+        runTodoPlannerPrompt({
+          session,
+          prompt: repairPrompt,
+          abortSignal: options.abortSignal,
+          timeoutMs,
+          gracefulShutdownMs,
+          diagnostics: result.diagnostics,
+          onDiagnostic: options.onDiagnostic,
+        }),
+      options.goal,
+      {
+        onInvalidOutput: (validationError) =>
+          options.onDiagnostic?.({
+            kind: "invalid_output",
+            message: `TODO planner returned invalid output: ${validationError}`,
+            diagnostics: result.diagnostics,
+            sessionFile: session.sessionFile,
+            sessionId: session.sessionId,
+          }),
+        onRepairAttempt: (validationError) =>
+          options.onDiagnostic?.({
+            kind: "repair_attempt",
+            message: `Asking TODO planner to repair invalid output: ${validationError}`,
+            diagnostics: result.diagnostics,
+            sessionFile: session.sessionFile,
+            sessionId: session.sessionId,
+          }),
+        onFailure: (validationError) =>
+          options.onDiagnostic?.({
+            kind: "failure",
+            message: `TODO planner repair failed: ${validationError}`,
+            diagnostics: result.diagnostics,
+            sessionFile: session.sessionFile,
+            sessionId: session.sessionId,
+          }),
+      },
+    );
+  } catch (error) {
+    plannerError = error;
+  }
 
-    await session.prompt(buildTodoCreationPrompt(options.inputText));
-    const direct = session.getLastAssistantText?.();
-    const fromMessages = lastAssistantTextFromMessages(session.messages);
-    const text = direct || fromMessages;
-    if (!text) {
-      throw new Error("TODO planner did not return assistant text.");
-    }
-    return text;
-  } finally {
-    session?.dispose?.();
+  try {
+    await Promise.resolve(session.dispose?.());
+  } catch (error) {
+    plannerError = plannerError ?? new TodoGenerationError(`TODO planner dispose failed: ${errorMessage(error)}`);
   }
+
+  if (plannerError) {
+    throw plannerError;
+  }
+  if (!plannerMarkdown) {
+    throw new TodoGenerationError("TODO planner did not return valid TODO markdown.");
+  }
+  return applyGoalInstructionsToTodoMarkdown(plannerMarkdown, options.goal);
+}
+
+async function runTodoPlannerPrompt(options: {
+  session: WorkerSessionLike;
+  prompt: string;
+  abortSignal?: AbortSignal;
+  timeoutMs: number;
+  gracefulShutdownMs: number;
+  diagnostics?: string[];
+  onDiagnostic?: PlannerDiagnosticHandler;
+}): Promise<string> {
+  const promptResult = await runGuardedSessionPrompt({
+    session: options.session,
+    prompt: options.prompt,
+    abortSignal: options.abortSignal,
+    timeoutMs: options.timeoutMs,
+    gracefulShutdownMs: options.gracefulShutdownMs,
+    gracefulShutdownPrompt: buildTodoPlanningShutdownMessage(),
+    diagnostics: options.diagnostics,
+    dispose: false,
+  });
+
+  if (promptResult.timedOut) {
+    const message = `TODO planner timed out: ${promptResult.error ?? "time budget exceeded"}`;
+    options.onDiagnostic?.(plannerPromptDiagnostic("timeout", message, promptResult));
+    throw new TodoGenerationError(message);
+  }
+  if (promptResult.aborted) {
+    const message = `TODO planner aborted: ${promptResult.error ?? "outer abort signal"}`;
+    options.onDiagnostic?.(plannerPromptDiagnostic("abort", message, promptResult));
+    throw new TodoGenerationError(message);
+  }
+  if (promptResult.error) {
+    const message = `TODO planner failed: ${promptResult.error}`;
+    options.onDiagnostic?.(plannerPromptDiagnostic("failure", message, promptResult));
+    throw new TodoGenerationError(message);
+  }
+  if (!promptResult.assistantText) {
+    const message = "TODO planner did not return assistant text.";
+    options.onDiagnostic?.(plannerPromptDiagnostic("failure", message, promptResult));
+    throw new TodoGenerationError(message);
+  }
+  return promptResult.assistantText;
+}
+
+function plannerPromptDiagnostic(
+  kind: Extract<PlannerDiagnosticKind, "timeout" | "abort" | "failure">,
+  message: string,
+  promptResult: {
+    diagnostics: string[];
+    sessionFile?: string;
+    sessionId?: string;
+  },
+): PlannerDiagnostic {
+  return {
+    kind,
+    message,
+    diagnostics: promptResult.diagnostics,
+    sessionFile: promptResult.sessionFile,
+    sessionId: promptResult.sessionId,
+  };
+}
+
+function buildTodoPlanningShutdownMessage(): string {
+  return `Pi Long Task notice: TODO planning has reached its time budget.
+Return the best valid Pi Long Task TODO markdown you can produce now, or stop if that is not possible.`;
 }
 
 function buildRuntimeOptions(options: RunCoordinatorOptions): RuntimeOptions {
   const cwd = path.resolve(options.cwd ?? process.cwd());
   const runId = sanitizeRunId(options.runId ?? defaultRunId(options.now?.() ?? new Date()));
   const runDir = path.join(cwd, "tmp", "pi-long-task", runId);
-  const parsedWorkerConfig = parseWorkerRuntimeConfig(options.inputText);
+  const parsedWorkerConfig = parseWorkerRuntimeConfig(options.inputText ?? "");
   const configuredAttempts = options.maxAttemptsPerTask ?? parsedWorkerConfig.maxAttemptsPerTask;
   const configuredTaskTimeoutMs = options.taskTimeoutMs ?? parsedWorkerConfig.taskTimeoutMs;
+  const configuredTodoTimeoutMs = options.todoTimeoutMs;
+  const configuredTodoGracefulShutdownMs = options.todoGracefulShutdownMs;
   const configuredMaxBashTimeoutMs = options.maxBashTimeoutMs ?? parsedWorkerConfig.maxBashTimeoutMs;
   const workerModelName = options.workerModelName ?? parsedWorkerConfig.modelName;
   const workerModel = workerModelName ? undefined : options.workerModel;
+  const goal = normalizeOptionalText(options.goal);
 
   return {
     cwd,
@@ -485,10 +724,16 @@ function buildRuntimeOptions(options: RunCoordinatorOptions): RuntimeOptions {
     taskResultPath: path.join(runDir, "TASK_RESULT.md"),
     maxAttemptsPerTask: positiveInteger(configuredAttempts, DEFAULT_COORDINATOR_OPTIONS.maxAttemptsPerTask),
     taskTimeoutSeconds: positiveMilliseconds(configuredTaskTimeoutMs, DEFAULT_COORDINATOR_OPTIONS.taskTimeoutMs) / 1000,
+    todoTimeoutMs: positiveMilliseconds(configuredTodoTimeoutMs, DEFAULT_COORDINATOR_OPTIONS.todoTimeoutMs),
+    todoGracefulShutdownMs: positiveMilliseconds(
+      configuredTodoGracefulShutdownMs,
+      DEFAULT_COORDINATOR_OPTIONS.todoGracefulShutdownMs,
+    ),
     maxBashTimeoutSeconds:
       positiveMilliseconds(configuredMaxBashTimeoutMs, DEFAULT_COORDINATOR_OPTIONS.maxBashTimeoutMs) / 1000,
     workerModel,
     workerModelName,
+    goal,
     taskThinking: options.taskThinking ?? DEFAULT_COORDINATOR_OPTIONS.taskThinking,
     todoThinking: options.todoThinking ?? DEFAULT_COORDINATOR_OPTIONS.todoThinking,
     workerRunner: options.workerRunner ?? runWorkerTask,
@@ -499,6 +744,7 @@ function buildRuntimeOptions(options: RunCoordinatorOptions): RuntimeOptions {
     now: options.now ?? (() => new Date()),
     onProgress: options.onProgress,
     workerCostState: createWorkerCostState(),
+    plannerDiagnostics: [],
   };
 }
 
@@ -514,6 +760,32 @@ function emitProgress(
     resultPath: runtime.taskResultPath,
     workerCostTotal: runtime.workerCostState.total,
     ...update,
+    goal: runtime.goal,
+  });
+}
+
+function recordPlannerDiagnostic(runtime: RuntimeOptions, diagnostic: PlannerDiagnostic): void {
+  const normalized: PlannerDiagnostic = {
+    kind: diagnostic.kind,
+    message: diagnostic.message,
+    diagnostics: diagnostic.diagnostics?.filter(Boolean),
+    sessionFile: diagnostic.sessionFile,
+    sessionId: diagnostic.sessionId,
+  };
+  const last = runtime.plannerDiagnostics.at(-1);
+  if (last?.kind === normalized.kind && last.message === normalized.message) {
+    return;
+  }
+  runtime.plannerDiagnostics.push(normalized);
+  emitProgress(runtime, normalized.message, {
+    phase: "planning",
+    status: normalized.kind,
+    isError: normalized.kind !== "repair_attempt",
+    plannerDiagnostic: normalized.kind,
+    plannerDiagnostics: normalized.diagnostics,
+    plannerSessionFile: normalized.sessionFile,
+    plannerSessionId: normalized.sessionId,
+    taskProgress: buildTaskProgressModel({ tasks: [] }),
   });
 }
 
@@ -771,6 +1043,30 @@ function initialTaskResultMarkdown(runId: string): string {
   return `# Pi Long Task TASK_RESULT\n\nRun: ${runId}\n`;
 }
 
+async function appendFailureNote(
+  pathname: string,
+  message: string,
+  plannerDiagnostics: readonly PlannerDiagnostic[],
+): Promise<void> {
+  const lines = ["", "## Pi Long Task failure", "", message];
+  if (plannerDiagnostics.length > 0) {
+    lines.push("", "### Planner diagnostics");
+    for (const diagnostic of plannerDiagnostics) {
+      lines.push("", `- ${diagnostic.kind}: ${diagnostic.message}`);
+      if (diagnostic.sessionId) {
+        lines.push(`  - Session ID: ${diagnostic.sessionId}`);
+      }
+      if (diagnostic.sessionFile) {
+        lines.push(`  - Session file: ${diagnostic.sessionFile}`);
+      }
+      for (const item of diagnostic.diagnostics ?? []) {
+        lines.push(`  - Diagnostic: ${item}`);
+      }
+    }
+  }
+  await appendFile(pathname, `${lines.join("\n")}\n`, "utf8");
+}
+
 async function appendCommitNote(pathname: string, result: CommitAfterSessionResult): Promise<void> {
   const lines = ["", "### Commit note", ""];
   if (result.hash) {
@@ -874,6 +1170,15 @@ function sanitizeRunId(runId: string): string {
   return sanitized || defaultRunId(new Date());
 }
 
+function normalizeOptionalText(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+function coordinatorInputText(options: RunCoordinatorOptions): string {
+  return normalizeOptionalText(options.inputText) ?? normalizeOptionalText(options.goal) ?? "";
+}
+
 function positiveInteger(value: number | undefined, fallback: number): number {
   if (typeof value === "number" && Number.isFinite(value) && value > 0) {
     return Math.floor(value);

package/src/coverage_goal.ts

@@ -0,0 +1,90 @@
+export interface CoverageGoal {
+  thresholdPercent: number;
+  thresholdText: string;
+  relation: "above" | "at least";
+}
+
+const PERCENT_RE = /(\d+(?:\.\d+)?)\s*%/;
+const COVERAGE_RE = /\b(?:test(?:ing)?\s+)?(?:line\s+)?coverage\b/i;
+const ABOVE_RE = /(?:\babove\b|\bover\b|\bgreater\s+than\b|\bmore\s+than\b|>)/i;
+const AT_LEAST_RE = /(?:\bat\s+least\b|\bminimum\b|\bmin\b|\bno\s+less\s+than\b|>=)/i;
+
+export function parseCoverageGoal(text: string | undefined): CoverageGoal | undefined {
+  const trimmed = text?.trim();
+  if (!trimmed || !COVERAGE_RE.test(trimmed)) {
+    return undefined;
+  }
+
+  const percent = PERCENT_RE.exec(trimmed);
+  if (!percent?.[1]) {
+    return undefined;
+  }
+
+  const thresholdPercent = Number.parseFloat(percent[1]);
+  if (!Number.isFinite(thresholdPercent) || thresholdPercent < 0 || thresholdPercent > 100) {
+    return undefined;
+  }
+
+  return {
+    thresholdPercent,
+    thresholdText: formatPercent(thresholdPercent),
+    relation: coverageRelation(trimmed),
+  };
+}
+
+export function coverageGoalPhrase(goal: CoverageGoal): string {
+  return `testing line coverage ${goal.relation} ${goal.thresholdText}%`;
+}
+
+export function coverageGoalAction(goal: CoverageGoal): string {
+  return `Raise or maintain ${coverageGoalPhrase(goal)}.`;
+}
+
+export function coverageGoalVerification(goal: CoverageGoal): string {
+  return `Run the repository's coverage command and confirm line coverage is ${goal.relation} ${goal.thresholdText}%; report the command and resulting line coverage.`;
+}
+
+export function coverageGoalVerifyBullet(goal: CoverageGoal): string {
+  return `- ${coverageGoalVerification(goal)}`;
+}
+
+export function inferCoverageGoalText(text: string): string | undefined {
+  const normalized = text.replace(/\s+/g, " ").trim();
+  if (!parseCoverageGoal(normalized)) {
+    return undefined;
+  }
+
+  const coverageIndex = normalized.search(/(?:test(?:ing)?\s+)?(?:line\s+)?coverage/i);
+  if (coverageIndex < 0) {
+    return normalized;
+  }
+
+  const prefix = normalized.slice(0, coverageIndex).trimEnd();
+  const action = /(have|reach|raise|maintain|keep|increase|get|achieve|hit|ensure)\s*$/i.exec(prefix);
+  const start = action?.index ?? coverageIndex;
+  return normalizeCoverageGoalText(normalized.slice(start));
+}
+
+function normalizeCoverageGoalText(text: string): string | undefined {
+  const trimmed = text
+    .replace(/^\b(?:to|for|that)\b\s+/i, "")
+    .replace(/[.,;:!?]+$/g, "")
+    .trim();
+  return trimmed || undefined;
+}
+
+function coverageRelation(text: string): CoverageGoal["relation"] {
+  const percentIndex = text.search(PERCENT_RE);
+  const relationWindow = percentIndex >= 0 ? text.slice(Math.max(0, percentIndex - 40), percentIndex + 8) : text;
+  if (AT_LEAST_RE.test(relationWindow)) {
+    return "at least";
+  }
+  if (ABOVE_RE.test(relationWindow)) {
+    return "above";
+  }
+  return "at least";
+}
+
+function formatPercent(value: number): string {
+  return Number.isInteger(value) ? String(value) : String(value).replace(/0+$/g, "").replace(/\.$/, "");
+}