@bastani/atomic 0.9.14-alpha.3 → 0.9.14-alpha.5

package/dist/builtin/workflows/builtin/goal-runner.ts

@@ -1,5 +1,11 @@
 import { join } from "node:path";
 import type { WorkflowParallelOptions, WorkflowTaskOptions, WorkflowTaskResult, WorkflowTaskStep } from "../src/shared/types.js";
+import { fold_usage } from "./verification-usage.js";
+import {
+  convergence_escalation_evidence,
+  record_convergence,
+  type ConvergenceEntry,
+} from "./goal-convergence.js";
 import { orchestratorModelConfig, reviewerModelConfig } from "./goal-models.js";
 import {
   DEFAULT_BLOCKER_THRESHOLD,
@@ -22,6 +28,8 @@ import {
   reviewDecisionToRecord,
 } from "./goal-review.js";
 import { reviewerFailureText } from "./review-convergence.js";
+import { consolidateFindingsBatch } from "./review-convergence.js";
+import { reverify_consolidated_batch } from "./goal-reverify.js";
 import {
   renderForkedGoalOrchestratorPrompt,
   renderGoalOrchestratorPrompt,
@@ -79,11 +87,13 @@ function reviewerExecutionFailedDecision(input: {
   readonly reviewQuorum: number;
   readonly reviews: readonly ReviewRecord[];
   readonly reason: string;
+  readonly convergence?: readonly ConvergenceEntry[];
 }): ReducerDecision {
+  const evidence = convergence_escalation_evidence(input.convergence ?? []);
   return {
     turn: input.turn,
     decision: "needs_human",
-    reason: input.reason,
+    reason: [input.reason, ...evidence].join("\n"),
     complete_votes: input.reviews.filter((review) => review.decision === "complete").length,
     review_quorum: input.reviewQuorum,
     parsed: input.reviews.every((review) => review.parsed),
@@ -150,7 +160,9 @@ export async function runGoalWorkflow(ctx: GoalRunnerContext, options: GoalWorkf
         });
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        terminalRemainingWork = `Orchestrator failed before producing a receipt: ${message}`;
+        const baseReason = `Orchestrator failed before producing a receipt: ${message}`;
+        terminalRemainingWork = baseReason;
+        const reason = [baseReason, ...convergence_escalation_evidence(ledger.convergence ?? [])].join("\n");
         latestReviews = [];
         latestReviewArtifactPaths = [];
         latestReviewReportPath = undefined;
@@ -159,7 +171,7 @@ export async function runGoalWorkflow(ctx: GoalRunnerContext, options: GoalWorkf
         ledger.decisions.push({
           turn,
           decision: "needs_human",
-          reason: terminalRemainingWork,
+          reason,
           complete_votes: 0,
           review_quorum: reviewQuorum,
           parsed: false,
@@ -167,9 +179,9 @@ export async function runGoalWorkflow(ctx: GoalRunnerContext, options: GoalWorkf
           stopReviewLoop: false,
           nextAction: "needs_human",
           finalActionRemaining: false,
-          diagnostics: [terminalRemainingWork],
+          diagnostics: [baseReason],
         });
-        appendLifecycleEvent(ledger, "status_decided", terminalRemainingWork, turn);
+        appendLifecycleEvent(ledger, "status_decided", reason, turn);
         await writeGoalLedger(ledgerPath, ledger);
         break;
       }
@@ -269,10 +281,60 @@ export async function runGoalWorkflow(ctx: GoalRunnerContext, options: GoalWorkf
         );
         return record;
       }));
-      latestReviewReportPath = await writeReviewRoundArtifact(artifactDir, latestReviews);
+      const consolidatedFindings = consolidateFindingsBatch(
+        latestReviews.map((review) => ({
+          reviewer: review.reviewer,
+          findings: review.findings,
+        })),
+      );
+      const roundProducedDecisions = latestReviews.some((review) => review.parsed);
+      const reverifyResults: WorkflowTaskResult[] = [];
+      const reverifyContext = {
+        task: async (name: string, taskOptions: WorkflowTaskOptions): Promise<WorkflowTaskResult> => {
+          const result = await ctx.task(name, taskOptions);
+          reverifyResults.push(result);
+          return result;
+        },
+      };
+      const reverified = await reverify_consolidated_batch(reverifyContext, {
+        batch: consolidatedFindings,
+        context: {
+          objective,
+          candidateRefs: [ledgerPath, orchestratorReceiptPath],
+        },
+      });
+      latestReviewReportPath = await writeReviewRoundArtifact(
+        artifactDir,
+        latestReviews,
+        reverified.batch,
+        reverified.audits,
+      );
+      if (reverified.audits.length > 0) {
+        ledger.reverification ??= [];
+        ledger.reverification.push(...reverified.audits);
+      }
+      const findings = latestReviews.flatMap((review) => review.findings);
+      const traceability = latestReviews.flatMap((review) => review.requirements_traceability);
+      ledger.convergence ??= [];
+      // A thrown reviewer batch or an all-unparsed reviewer batch produced no
+      // decisions, so recording a zero-blocker round would fabricate progress
+      // and can suppress the escalation evidence on the very escalation it triggers.
+      if (!reviewerBatchFailed && roundProducedDecisions) {
+        ledger.convergence.push(record_convergence({
+          unresolvedBlockingCount: reverified.batch.filter((entry) => entry.blocking).length,
+          meanFindingConfidence: findings.length === 0
+            ? null
+            : findings.reduce((total, finding) => total + finding.confidence_score, 0) / findings.length,
+          fractionProven: traceability.length === 0
+            ? 0
+            : traceability.filter((entry) => entry.status === "proven").length / traceability.length,
+          demotions: reverified.audits.filter((audit) => audit.verdict === "demoted").length,
+          usage: fold_usage([orchestrator, ...reviewResults, ...reverifyResults]),
+        }));
+      }
+      ledger.reviews.push(...latestReviews);
       // Consolidated round artifact leads so the next orchestrator turn plans the full findings batch first.
       latestReviewArtifactPaths = [latestReviewReportPath, ...latestReviews.map((review) => review.artifact_path)];
-      ledger.reviews.push(...latestReviews);
       appendLifecycleEvent(
         ledger,
         "reviews_recorded",
@@ -282,14 +344,16 @@ export async function runGoalWorkflow(ctx: GoalRunnerContext, options: GoalWorkf
       if (reviewerBatchFailed) {
         terminalRemainingWork = collectRemainingWork(latestReviews);
         const reason = `Reviewer execution failed before quorum could be established. Remaining work: ${terminalRemainingWork}`;
-        ledger.decisions.push(reviewerExecutionFailedDecision({
+        const decision = reviewerExecutionFailedDecision({
           turn,
           reviewQuorum,
           reviews: latestReviews,
           reason,
-        }));
+          convergence: ledger.convergence,
+        });
+        ledger.decisions.push(decision);
         ledger.status = "needs_human";
-        appendLifecycleEvent(ledger, "status_decided", reason, turn);
+        appendLifecycleEvent(ledger, "status_decided", decision.reason, turn);
         await writeGoalLedger(ledgerPath, ledger);
         break;
       }
@@ -300,6 +364,7 @@ export async function runGoalWorkflow(ctx: GoalRunnerContext, options: GoalWorkf
         reviewQuorum,
         blockerThreshold,
         nextActionOnComplete: createPr ? "pull-request" : "finish",
+        convergence: ledger.convergence,
       });
       if (reducerOutcome.blockerObservation !== undefined) {
         ledger.blockers.push(reducerOutcome.blockerObservation);

package/dist/builtin/workflows/builtin/goal-schemas.ts

@@ -1,4 +1,5 @@
 import { Type } from "typebox";
+import { VERIFICATION_SCALE } from "./verification-criteria.js";
 
 const reviewFindingSchema = Type.Object(
   {
@@ -74,6 +75,12 @@ export const reviewDecisionSchema = Type.Object(
     receipt_assessment: Type.String(),
     verification_remaining: Type.String(),
     stop_review_loop: Type.Boolean(),
+    criterion_scores: Type.Optional(
+      Type.Array(Type.Object({
+        criterion_id: Type.String(),
+        score: VERIFICATION_SCALE.schema,
+      }, { additionalProperties: false })),
+    ),
     reviewer_error: Type.Optional(
       Type.Union([Type.Null(), reviewerErrorSchema]),
     ),

package/dist/builtin/workflows/builtin/goal-types.ts

@@ -1,4 +1,6 @@
 import type { ReviewConvergenceSummary } from "./review-convergence.js";
+import type { ReverifyAuditEntry } from "./goal-reverify.js";
+import type { ConvergenceEntry } from "./goal-convergence.js";
 
 export const DEFAULT_MAX_TURNS = 10;
 // Goal Runner runs three independent reviewer personas; two approvals form a majority.
@@ -55,6 +57,7 @@ export type ReviewerError = {
 
 export type ReviewDecision = {
   readonly findings: readonly ReviewFinding[];
+  readonly criterion_scores?: readonly { readonly criterion_id: string; readonly score: number }[];
   readonly overall_correctness: "patch is correct" | "patch is incorrect";
   readonly overall_explanation: string;
   readonly overall_confidence_score: number;
@@ -123,6 +126,9 @@ export type GoalLedger = {
   blockers: BlockerObservation[];
   decisions: ReducerDecision[];
   lifecycle: GoalLifecycleEvent[];
+  /** V9 audit records; the original findings remain in `reviews`. */
+  reverification?: ReverifyAuditEntry<ReviewFinding>[];
+  convergence?: ConvergenceEntry[];
 };
 
 export type ReducerOutcome = {

package/dist/builtin/workflows/builtin/loop-until-done-runner.ts

@@ -7,6 +7,7 @@ import type {
   WorkflowSerializableValue,
   WorkflowTaskResult,
 } from "../src/shared/types.js";
+import { classify_trend, score_progress, type Trend } from "./progress-scoring.js";
 import {
   renderCompletionPrompt,
   renderEvaluationPrompt,
@@ -14,6 +15,8 @@ import {
 } from "./loop-until-done-prompts.js";
 import { stableArtifactRoot } from "./pattern-artifact-root.js";
 
+const PROGRESS_DISCLAIMER = "Progress scores are a monitoring signal; VOC separation +0.079; never authoritative.";
+
 const evaluationSchema = Type.Object({
   done: Type.Boolean(),
   summary: Type.String(),
@@ -26,6 +29,8 @@ const evaluationSchema = Type.Object({
 type LoopInputs = {
   readonly prompt: string;
   readonly max_iterations: number;
+  readonly progress_scoring?: boolean;
+  readonly progress_repeats?: number;
 } & Record<string, WorkflowSerializableValue>;
 
 type Evaluation = {
@@ -36,6 +41,12 @@ type Evaluation = {
   readonly validationEvidence: readonly string[];
   readonly remainingWork: string;
 };
+type LedgerProgress = {
+  readonly score: number;
+  readonly perRepeat: (number | null)[][];
+  readonly trend: Trend;
+  readonly window: number;
+};
 type LedgerEntry = {
   readonly iteration: number;
   readonly artifact_path: string;
@@ -46,7 +57,57 @@ type LedgerEntry = {
   readonly validation_evidence: readonly string[];
   readonly done: boolean;
   readonly remaining_work: string;
+  readonly progress?: LedgerProgress;
 };
+
+function progressCurve(entries: readonly LedgerEntry[]): number[] {
+  return entries.flatMap((entry) => (entry.progress === undefined ? [] : [entry.progress.score]));
+}
+
+function progressReport(entries: readonly LedgerEntry[]): { curve: number[]; trend: Trend } {
+  const curve = progressCurve(entries);
+  return { curve, trend: classify_trend(curve).trend };
+}
+
+function formatProgressReport(report: { curve: readonly number[]; trend: Trend }): string {
+  return [
+    `Progress curve: ${JSON.stringify(report.curve)}`,
+    `Final trend: ${report.trend}`,
+    PROGRESS_DISCLAIMER,
+  ].join("\n");
+}
+
+function repeatCount(input: LoopInputs): number {
+  const repeats = input.progress_repeats;
+  return typeof repeats === "number" && Number.isInteger(repeats) && repeats > 0 ? repeats : 1;
+}
+
+async function scoreIteration(
+  ctx: WorkflowRunContext<LoopInputs>,
+  task: string,
+  entries: readonly LedgerEntry[],
+  repeats: number,
+): Promise<LedgerProgress | undefined> {
+  try {
+    const curve = await score_progress(ctx, {
+      problem: task,
+      steps: entries.map((entry) => entry.summary),
+      checkpoints: [entries.length],
+      repeats,
+    });
+    const score = curve.scores[0];
+    if (score === null || score === undefined) return undefined;
+    const trend = classify_trend([...progressCurve(entries), score]);
+    return {
+      score,
+      perRepeat: curve.perRepeat,
+      trend: trend.trend,
+      window: trend.evidence.window,
+    };
+  } catch {
+    return undefined;
+  }
+}
 function serializableObject(
   value: WorkflowSerializableValue | undefined,
 ): WorkflowSerializableObject | undefined {
@@ -79,14 +140,23 @@ function evaluationFrom(result: WorkflowTaskResult): Evaluation {
   return { done, summary, newFindings, failures, validationEvidence, remainingWork };
 }
 
-async function writeLedger(path: string, task: string, maxIterations: number, status: string,
-  entries: readonly LedgerEntry[]): Promise<void> {
+async function writeLedger(
+  path: string,
+  task: string,
+  maxIterations: number,
+  status: string,
+  entries: readonly LedgerEntry[],
+): Promise<void> {
+  const report = progressReport(entries);
   await writeFile(path, `${JSON.stringify({
     task,
     max_iterations: maxIterations,
     status,
     iterations_completed: entries.length,
     entries,
+    progress_curve: report.curve,
+    final_trend: report.trend,
+    progress_disclaimer: PROGRESS_DISCLAIMER,
   }, null, 2)}\n`);
 }
 
@@ -135,7 +205,7 @@ export async function runLoopUntilDone(ctx: WorkflowRunContext<LoopInputs>) {
     // runner persists the structured decision itself so evaluation-N.json
     // stays schema-shaped JSON rather than stage prose.
     await writeFile(evaluationPath, `${JSON.stringify(evaluator.structured, null, 2)}\n`);
-    entries.push({
+    const entry: LedgerEntry = {
       iteration,
       artifact_path: iterationPath,
       evaluation_artifact_path: evaluationPath,
@@ -145,7 +215,12 @@ export async function runLoopUntilDone(ctx: WorkflowRunContext<LoopInputs>) {
       validation_evidence: decision.validationEvidence,
       done: decision.done,
       remaining_work: decision.remainingWork,
-    });
+    };
+    entries.push(entry);
+    if (ctx.inputs.progress_scoring !== false) {
+      const progress = await scoreIteration(ctx, ctx.inputs.prompt, entries, repeatCount(ctx.inputs));
+      if (progress !== undefined) entries[entries.length - 1] = { ...entry, progress };
+    }
     await writeLedger(
       ledgerPath,
       ctx.inputs.prompt,
@@ -154,6 +229,7 @@ export async function runLoopUntilDone(ctx: WorkflowRunContext<LoopInputs>) {
       entries,
     );
     if (decision.done) {
+      const report = progressReport(entries);
       const resultPath = join(artifactDir, "result.md");
       const final = await ctx.task("completion-summary", {
         prompt: renderCompletionPrompt({ task: ctx.inputs.prompt, ledgerPath, iterationPath }),
@@ -164,8 +240,9 @@ export async function runLoopUntilDone(ctx: WorkflowRunContext<LoopInputs>) {
         // `result_path` below carries it for callers that want the contents.
         outputMode: "file-only",
       });
+      const result = `${final.text ? `${final.text.trimEnd()}\n\n` : ""}${formatProgressReport(report)}\n`;
       return {
-        result: final.text,
+        result,
         status: "complete" as const,
         iterations_completed: iteration,
         ledger_path: ledgerPath,
@@ -174,14 +251,22 @@ export async function runLoopUntilDone(ctx: WorkflowRunContext<LoopInputs>) {
         result_path: resultPath,
         remaining_work: "",
         artifact_dir: artifactDir,
+        progress_curve: report.curve,
+        final_trend: report.trend,
+        progress_disclaimer: PROGRESS_DISCLAIMER,
       };
     }
   }
 
   const last = entries.at(-1)!;
+  const report = progressReport(entries);
   await writeLedger(ledgerPath, ctx.inputs.prompt, ctx.inputs.max_iterations, "failed", entries);
+  const result = [
+    `Iteration limit exhausted after ${ctx.inputs.max_iterations} iterations. Inspect ${ledgerPath}.`,
+    formatProgressReport(report),
+  ].join("\n\n");
   return {
-    result: `Iteration limit exhausted after ${ctx.inputs.max_iterations} iterations. Inspect ${ledgerPath}.`,
+    result,
     status: "failed" as const,
     iterations_completed: ctx.inputs.max_iterations,
     ledger_path: ledgerPath,
@@ -190,5 +275,8 @@ export async function runLoopUntilDone(ctx: WorkflowRunContext<LoopInputs>) {
     result_path: ledgerPath,
     remaining_work: last.remaining_work,
     artifact_dir: artifactDir,
+    progress_curve: report.curve,
+    final_trend: report.trend,
+    progress_disclaimer: PROGRESS_DISCLAIMER,
   };
 }

package/dist/builtin/workflows/builtin/loop-until-done.d.ts

@@ -1,15 +1,20 @@
 import type { WorkflowDefinition, WorkflowInputValues, WorkflowOutputValues } from "../src/authoring.js";
 
 export type LoopUntilDoneWorkflowStatus = "complete" | "failed";
+export type LoopUntilDoneProgressTrend = "rising" | "flat" | "regressing";
 
 export type LoopUntilDoneWorkflowInputs = WorkflowInputValues & {
   readonly prompt: string;
   readonly max_iterations: number;
+  readonly progress_scoring: boolean;
+  readonly progress_repeats: number;
 };
 
 export type LoopUntilDoneWorkflowRunInputs = WorkflowInputValues & {
   readonly prompt: string;
   readonly max_iterations?: number;
+  readonly progress_scoring?: boolean;
+  readonly progress_repeats?: number;
 };
 
 export type LoopUntilDoneWorkflowOutputs = WorkflowOutputValues & {
@@ -22,6 +27,9 @@ export type LoopUntilDoneWorkflowOutputs = WorkflowOutputValues & {
   readonly result_path: string;
   readonly remaining_work: string;
   readonly artifact_dir: string;
+  readonly progress_curve: number[];
+  readonly final_trend: LoopUntilDoneProgressTrend;
+  readonly progress_disclaimer: string;
 };
 
 export type LoopUntilDoneWorkflowDefinition = WorkflowDefinition<

package/dist/builtin/workflows/builtin/loop-until-done.ts

@@ -18,6 +18,15 @@ export default workflow({
       default: 5,
       description: "Maximum work/evaluation iterations before returning an inspectable failed status (1-20).",
     }),
+    progress_scoring: Type.Boolean({
+      default: true,
+      description: "Enable advisory progress scoring after each completed iteration.",
+    }),
+    progress_repeats: Type.Integer({
+      minimum: 1,
+      default: 1,
+      description: "Number of advisory progress-scoring repeats per iteration.",
+    }),
   },
   outputs: {
     result: Type.String({ description: "Compact reference to the evidence-backed completion report, or the deterministic exhaustion report; read `result_path` for the full report." }),
@@ -31,6 +40,12 @@ export default workflow({
     result_path: Type.String({ description: "Path to the final report, or the ledger on exhausted failure." }),
     remaining_work: Type.String({ description: "Actionable remaining work; empty only after proven completion." }),
     artifact_dir: Type.String({ description: "Run-specific directory containing loop artifacts." }),
+    progress_curve: Type.Array(Type.Number(), { description: "Advisory progress scores in iteration order." }),
+    final_trend: Type.Union(
+      [Type.Literal("rising"), Type.Literal("flat"), Type.Literal("regressing")],
+      { description: "Final advisory trend classification; never a stop decision." },
+    ),
+    progress_disclaimer: Type.String({ description: "Calibration disclaimer for the advisory progress signal." }),
   },
   run: async (ctx) => await runLoopUntilDone(withSteeringPropagationContext(ctx)),
 });

package/dist/builtin/workflows/builtin/progress-scoring.ts

@@ -0,0 +1,230 @@
+/**
+ * Observation-grounded trajectory scoring and pure trend evidence.
+ *
+ * Progress is a monitoring magnitude only. The prompt asks about the supplied
+ * current state, and the trend result carries evidence without an action.
+ */
+import { Type } from "typebox";
+import type { WorkflowRunContext, WorkflowSerializableObject, WorkflowSerializableValue } from "../src/shared/types.js";
+import { VERIFICATION_SCALE } from "./verification-criteria.js";
+
+export const DEFAULT_TREND_WINDOW = 3;
+export const DEFAULT_RISE_DELTA = 1.5;
+export const DEFAULT_FALL_DELTA = -1.5;
+
+const DEFAULT_REPEATS = 1;
+const CALIBRATION_RULES = [
+	"Trust observed output, not the agent's narration.",
+	"Effort and step count are NOT progress.",
+	'Agent declarations of success ("done!", "all tests pass") are ZERO evidence.',
+	"Scores may plateau or fall; wrong approaches plateau, and regressions decrease.",
+] as const;
+const PROGRESS_SCALE_ORIENTATION = `${VERIFICATION_SCALE.min} = certainly would not satisfy the acceptance criteria … ${VERIFICATION_SCALE.max} = verified satisfaction with observed output`;
+
+export interface ProgressPromptInput {
+	readonly problem: string;
+	readonly steps: readonly string[];
+	readonly checkpoints: readonly number[];
+}
+
+export interface ProgressScoreInput {
+	readonly problem: string;
+	readonly steps: readonly string[];
+	readonly checkpoints?: readonly number[];
+	readonly repeats?: number;
+}
+
+export type ProgressScoringContext = Pick<WorkflowRunContext, "task">;
+
+export type ProgressCurve = {
+	checkpoints: number[];
+	scores: (number | null)[];
+	perRepeat: (number | null)[][];
+};
+
+export type TrendConfig = {
+	window?: number;
+	riseDelta?: number;
+	fallDelta?: number;
+};
+
+export type Trend = "rising" | "flat" | "regressing";
+
+export type TrendResult = {
+	trend: Trend;
+	evidence: {
+		series: readonly number[];
+		window: number;
+		delta: number;
+	};
+};
+
+const progressSchema = Type.Object({
+	scores: Type.Array(Type.Object({
+		checkpoint: Type.Integer({ minimum: 1 }),
+		score: VERIFICATION_SCALE.schema,
+	}, { additionalProperties: false })),
+}, { additionalProperties: false });
+
+type ProgressStructuredOutput = {
+	readonly scores: readonly WorkflowSerializableValue[];
+};
+
+function isRecord(value: WorkflowSerializableValue | undefined): value is WorkflowSerializableObject {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function isProgressStructuredOutput(value: WorkflowSerializableValue | undefined): value is ProgressStructuredOutput {
+	if (!isRecord(value) || Object.keys(value).length !== 1 || !Object.hasOwn(value, "scores")) return false;
+	return Array.isArray(value.scores);
+}
+
+function nullScores(checkpointCount: number): (number | null)[] {
+	return Array.from({ length: checkpointCount }, () => null);
+}
+
+function defaultCheckpoints(stepCount: number): number[] {
+	const result: number[] = [];
+	for (let checkpoint = 2; checkpoint <= stepCount - 1; checkpoint += 1) result.push(checkpoint);
+	return result;
+}
+
+function validateCheckpoints(checkpoints: readonly number[], stepCount: number): void {
+	for (const checkpoint of checkpoints) {
+		if (!Number.isInteger(checkpoint) || checkpoint < 1 || checkpoint > stepCount) {
+			throw new RangeError(`Progress checkpoint ${checkpoint} is outside the step range 1..${stepCount}.`);
+		}
+	}
+}
+
+function scoresFromStructured(
+	value: WorkflowSerializableValue | undefined,
+	checkpoints: readonly number[],
+): (number | null)[] {
+	if (!isProgressStructuredOutput(value)) return nullScores(checkpoints.length);
+	const requested = new Set(checkpoints);
+	const seen = new Set<number>();
+	const scoresByCheckpoint = new Map<number, number>();
+	for (const candidate of value.scores) {
+		if (!isRecord(candidate) || Object.keys(candidate).length !== 2 ||
+			!Object.hasOwn(candidate, "checkpoint") || !Object.hasOwn(candidate, "score")) continue;
+		const checkpoint = candidate.checkpoint;
+		const score = candidate.score;
+		if (typeof checkpoint !== "number" || !Number.isInteger(checkpoint) || seen.has(checkpoint)) continue;
+		if (!requested.has(checkpoint) || typeof score !== "number" || !Number.isInteger(score) ||
+			score < VERIFICATION_SCALE.min || score > VERIFICATION_SCALE.max) continue;
+		seen.add(checkpoint);
+		scoresByCheckpoint.set(checkpoint, score);
+	}
+	return checkpoints.map((checkpoint) => scoresByCheckpoint.get(checkpoint) ?? null);
+}
+
+/**
+ * Score all requested checkpoints in one structured stage call for one repeat.
+ * A failed or malformed call is an invalid repeat and leaves every checkpoint
+ * in that repeat null.
+ */
+async function scoreRepeat(
+	ctx: ProgressScoringContext,
+	input: ProgressScoreInput,
+	checkpoints: readonly number[],
+	repeat: number,
+): Promise<(number | null)[]> {
+	try {
+		const result = await ctx.task(`progress-score-${repeat + 1}`, {
+			prompt: build_progress_prompt({ ...input, checkpoints }),
+			context: "fresh",
+			schema: progressSchema,
+		});
+		return scoresFromStructured(result.structured, checkpoints);
+	} catch {
+		return nullScores(checkpoints.length);
+	}
+}
+
+/** Score every requested checkpoint once per repeat, returning null-safe means. */
+export async function score_progress(
+	ctx: ProgressScoringContext,
+	input: ProgressScoreInput,
+): Promise<ProgressCurve> {
+	if (input.steps.length === 0) throw new RangeError("Progress scoring requires a non-empty step prefix.");
+	const checkpoints = Array.from(input.checkpoints ?? defaultCheckpoints(input.steps.length));
+	validateCheckpoints(checkpoints, input.steps.length);
+	const repeats = input.repeats ?? DEFAULT_REPEATS;
+	const perRepeat: (number | null)[][] = [];
+	for (let repeat = 0; repeat < repeats; repeat += 1) {
+		perRepeat.push(await scoreRepeat(ctx, input, checkpoints, repeat));
+	}
+	const scores = checkpoints.map((_, checkpointIndex) => {
+		const valid = perRepeat
+			.map((repeat) => repeat[checkpointIndex])
+			.filter((score): score is number => score !== null);
+		if (valid.length === 0) return null;
+		return valid.reduce((total, score) => total + score, 0) / valid.length;
+	});
+	return { checkpoints, scores, perRepeat };
+}
+
+/**
+ * Build a progress prompt with V3's shared-head/varying-tail layout. Steps are
+ * part of the cacheable head; only the requested checkpoint list varies at the
+ * tail.
+ */
+export function build_progress_prompt(input: ProgressPromptInput): string {
+	const numberedSteps = input.steps.map((step, index) => `${index + 1}. ${step}`);
+	const sharedHead = [
+		"<progress_head>",
+		"<problem>",
+		input.problem,
+		"</problem>",
+		"<steps>",
+		...numberedSteps,
+		"</steps>",
+		"<calibration>",
+		...CALIBRATION_RULES,
+		"</calibration>",
+		"<scale>",
+		`Use VERIFICATION_SCALE ${VERIFICATION_SCALE.min}..${VERIFICATION_SCALE.max} to answer: would the CURRENT state satisfy the acceptance criteria?`,
+		PROGRESS_SCALE_ORIENTATION,
+		"Score only the supplied current state from observed output.",
+		"</scale>",
+		"</progress_head>",
+	].join("\n");
+	const checkpointTail = [
+		"<checkpoints>",
+		"Score each listed 1-indexed checkpoint.",
+		...input.checkpoints.map((checkpoint) => `- ${checkpoint}`),
+		"</checkpoints>",
+		"<output_format>",
+		`Return structured_output with scores: [{ checkpoint, score }], using integer scores from ${VERIFICATION_SCALE.min} through ${VERIFICATION_SCALE.max}.`,
+		"</output_format>",
+	].join("\n");
+	return `${sharedHead}\n\n${checkpointTail}`;
+}
+
+function mean(values: readonly number[]): number {
+	if (values.length === 0) return 0;
+	return values.reduce((total, value) => total + value, 0) / values.length;
+}
+
+/**
+ * Classify a score series using a deterministic hysteresis delta. The trailing
+ * 2*window values are split into equal leading/trailing halves; an odd sample
+ * drops its middle value. Thresholds are inclusive at +riseDelta and -fallDelta.
+ */
+export function classify_trend(series: readonly number[], config: TrendConfig = {}): TrendResult {
+	const window = config.window ?? DEFAULT_TREND_WINDOW;
+	const riseDelta = config.riseDelta ?? DEFAULT_RISE_DELTA;
+	const fallDelta = config.fallDelta ?? DEFAULT_FALL_DELTA;
+	if (series.length < window + 1) {
+		return { trend: "flat", evidence: { series, window, delta: 0 } };
+	}
+	const sample = series.slice(-2 * window);
+	const usableLength = sample.length % 2 === 1 ? sample.length - 1 : sample.length;
+	const halfLength = usableLength / 2;
+	const leading = sample.slice(0, halfLength);
+	const trailing = sample.slice(sample.length - halfLength);
+	const delta = halfLength === 0 ? 0 : mean(trailing) - mean(leading);
+	const trend: Trend = delta >= riseDelta ? "rising" : delta <= fallDelta ? "regressing" : "flat";
+	return { trend, evidence: { series, window, delta } };
+}