@llm4ts/flow 2.31.1 → 2.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/flow",
-  "version": "2.31.1",
+  "version": "2.33.0",
   "description": "Effect-native LLM workflow, persistence, review, and repository automation",
   "license": "MIT",
   "type": "module",
@@ -34,6 +34,7 @@
     "./CostTracker": "./dist/CostTracker.js",
     "./CoverageLedger": "./dist/CoverageLedger.js",
     "./Decisions": "./dist/Decisions.js",
+    "./Diagnostics": "./dist/Diagnostics.js",
     "./Domains": "./dist/Domains.js",
     "./EpicBrief": "./dist/EpicBrief.js",
     "./EpicRuns": "./dist/EpicRuns.js",
@@ -67,6 +68,7 @@
     "./Persistence": "./dist/Persistence.js",
     "./Plan": "./dist/Plan.js",
     "./PlanExecution": "./dist/PlanExecution.js",
+    "./Port": "./dist/Port.js",
     "./Planner": "./dist/Planner.js",
     "./PrSummary": "./dist/PrSummary.js",
     "./PriceList": "./dist/PriceList.js",
@@ -82,6 +84,7 @@
     "./Spans": "./dist/Spans.js",
     "./Roster": "./dist/Roster.js",
     "./RosterSeats": "./dist/RosterSeats.js",
+    "./Stall": "./dist/Stall.js",
     "./Stories": "./dist/Stories.js",
     "./StoryPlan": "./dist/StoryPlan.js",
     "./Survey": "./dist/Survey.js",
@@ -90,6 +93,7 @@
     "./TransientRetry": "./dist/TransientRetry.js",
     "./Usage": "./dist/Usage.js",
     "./Wall": "./dist/Wall.js",
+    "./WorkQueue": "./dist/WorkQueue.js",
     "./Workspace": "./dist/Workspace.js",
     "./WorkspaceLayout": "./dist/WorkspaceLayout.js",
     "./WorkspaceTools": "./dist/WorkspaceTools.js",
@@ -118,7 +122,7 @@
     "typescript"
   ],
   "dependencies": {
-    "@llm4ts/core": "2.31.1"
+    "@llm4ts/core": "2.33.0"
   },
   "peerDependencies": {
     "effect": "4.0.0"

package/src/Chat.ts

@@ -3,9 +3,10 @@ import * as Ref from "effect/Ref"
 import * as Semaphore from "effect/Semaphore"
 import type { LlmServiceShape } from "@llm4ts/core/LlmService"
 import { Message, type LlmResponse } from "@llm4ts/core/Models"
-import { collect } from "@llm4ts/core/Streaming"
+import { collectAny } from "@llm4ts/core/Streaming"
 import { withToolActivity } from "./Activity.ts"
-import { FlowLlmError } from "./FlowError.ts"
+import { FlowLlmError, type Stalled } from "./FlowError.ts"
+import { noRepeats, stallGuard, type StallOptions } from "./Stall.ts"
 import { Info, TokensUsed, type FlowEventsShape } from "./FlowEvents.ts"
 import { isContextOverflow } from "./TransientRetry.ts"
 
@@ -24,6 +25,8 @@ export interface ChatOptions {
   readonly events?: FlowEventsShape
   /** Request label for published `TokensUsed` events. Default: "chat". */
   readonly agent?: string
+  /** End a turn that repeats one tool call or goes silent (ADR 0027 decision 11). */
+  readonly stall?: StallOptions
 }
 
 const publishUsage = (options: ChatOptions, response: LlmResponse): Effect.Effect<void> =>
@@ -38,7 +41,7 @@ const publishUsage = (options: ChatOptions, response: LlmResponse): Effect.Effec
       )
 
 export interface Chat {
-  readonly ask: (prompt: string) => Effect.Effect<string, FlowLlmError>
+  readonly ask: (prompt: string) => Effect.Effect<string, FlowLlmError | Stalled>
   readonly messages: Effect.Effect<ReadonlyArray<Message>>
 }
 
@@ -60,15 +63,19 @@ export const makeChat = Effect.fn("@llm4ts/flow/Chat.make")(function* (
 ): Effect.fn.Return<Chat> {
   const history = yield* Ref.make(initialHistory(options))
   const gate = yield* Semaphore.make(1)
+  const repeats = yield* Ref.make(noRepeats)
 
   const send = (messages: ReadonlyArray<Message>) => {
     const stream = service.executeStreamWithHistory(messages)
-    return collect(options.events === undefined ? stream : withToolActivity(options.events, stream))
+    const watched = options.events === undefined ? stream : withToolActivity(options.events, stream)
+    return collectAny(
+      options.stall === undefined ? watched : stallGuard(watched, options.stall, repeats)
+    )
   }
 
   const askRound = Effect.fn("@llm4ts/flow/Chat.ask")(function* (
     prompt: string
-  ): Effect.fn.Return<string, FlowLlmError> {
+  ): Effect.fn.Return<string, FlowLlmError | Stalled> {
     const userTurn = Message.make({ role: "User", content: prompt })
     const earlier = yield* Ref.get(history)
     const full = [...earlier, userTurn]
@@ -81,7 +88,8 @@ export const makeChat = Effect.fn("@llm4ts/flow/Chat.make")(function* (
     // this turn alone, and continue the conversation from there.
     const response = yield* send(full).pipe(
       Effect.catchIf(
-        (error) => isContextOverflow(error) && full.length > system.length + 1,
+        (error) =>
+          error._tag !== "Stalled" && isContextOverflow(error) && full.length > system.length + 1,
         (error) =>
           Effect.gen(function* () {
             messages = [
@@ -106,7 +114,7 @@ export const makeChat = Effect.fn("@llm4ts/flow/Chat.make")(function* (
             return yield* send(messages)
           })
       ),
-      Effect.mapError(FlowLlmError.from)
+      Effect.mapError((error) => (error._tag === "Stalled" ? error : FlowLlmError.from(error)))
     )
     yield* publishUsage(options, response)
     yield* Ref.set(history, [

package/src/Diagnostics.ts

@@ -0,0 +1,105 @@
+// Compiler and test-runner output as a work queue (ADR 0028): a pack's
+// `## Diagnostics` command prints what is red, this module reads it and
+// groups it by unit so each fixer gets one unit and nothing else.
+import { dirname } from "node:path"
+import * as Schema from "effect/Schema"
+
+export class Diagnostic extends Schema.Class<Diagnostic>("Diagnostic")({
+  file: Schema.String,
+  line: Schema.optionalKey(Schema.Int),
+  message: Schema.String,
+  /** The unit the fixer owns (a crate, a package, a folder); default: the file's directory. */
+  unit: Schema.optionalKey(Schema.String)
+}) {}
+
+export const DiagnosticsFormat = Schema.Literals(["json", "cargo"])
+export type DiagnosticsFormat = typeof DiagnosticsFormat.Type
+
+const decodeJsonLine = Schema.decodeUnknownOption(Schema.fromJsonString(Diagnostic))
+
+const CargoMessage = Schema.fromJsonString(
+  Schema.Struct({
+    reason: Schema.optionalKey(Schema.String),
+    target: Schema.optionalKey(Schema.Struct({ name: Schema.optionalKey(Schema.String) })),
+    message: Schema.optionalKey(
+      Schema.Struct({
+        level: Schema.optionalKey(Schema.String),
+        message: Schema.optionalKey(Schema.String),
+        spans: Schema.optionalKey(
+          Schema.Array(
+            Schema.Struct({
+              file_name: Schema.optionalKey(Schema.String),
+              line_start: Schema.optionalKey(Schema.Int),
+              is_primary: Schema.optionalKey(Schema.Boolean)
+            })
+          )
+        )
+      })
+    )
+  })
+)
+const decodeCargo = Schema.decodeUnknownOption(CargoMessage)
+
+/**
+ * `json`: one `{file, line?, message, unit?}` object per line. `cargo`:
+ * `cargo check --message-format=json`, errors only, the crate as the unit.
+ * Lines that do not parse are skipped: a build prints more than diagnostics.
+ */
+export const parseDiagnostics = (
+  text: string,
+  format: DiagnosticsFormat = "json"
+): ReadonlyArray<Diagnostic> => {
+  const out: Array<Diagnostic> = []
+  for (const raw of text.split("\n")) {
+    const line = raw.trim()
+    if (line.length === 0 || !line.startsWith("{")) continue
+    if (format === "json") {
+      const decoded = decodeJsonLine(line)
+      if (decoded._tag === "Some") out.push(decoded.value)
+      continue
+    }
+    const decoded = decodeCargo(line)
+    if (decoded._tag !== "Some") continue
+    const value = decoded.value
+    if (value.reason !== "compiler-message" || value.message?.level !== "error") continue
+    const span =
+      value.message.spans?.find((candidate) => candidate.is_primary === true) ??
+      value.message.spans?.[0]
+    if (span?.file_name === undefined) continue
+    out.push(
+      Diagnostic.make({
+        file: span.file_name,
+        ...(span.line_start === undefined ? {} : { line: span.line_start }),
+        message: value.message.message ?? "error",
+        ...(value.target?.name === undefined ? {} : { unit: value.target.name })
+      })
+    )
+  }
+  return out
+}
+
+/** Diagnostics by the unit a fixer owns, in a stable order. */
+export const groupDiagnostics = (
+  diagnostics: ReadonlyArray<Diagnostic>
+): ReadonlyArray<{ readonly unit: string; readonly diagnostics: ReadonlyArray<Diagnostic> }> => {
+  const groups = new Map<string, Array<Diagnostic>>()
+  for (const diagnostic of diagnostics) {
+    const unit = diagnostic.unit ?? dirname(diagnostic.file)
+    groups.set(unit, [...(groups.get(unit) ?? []), diagnostic])
+  }
+  return [...groups.entries()]
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([unit, list]) => ({ unit, diagnostics: list }))
+}
+
+/** The diagnostics of one unit as the fixer reads them, capped by count. */
+export const renderDiagnostics = (diagnostics: ReadonlyArray<Diagnostic>, limit = 60): string =>
+  [
+    ...diagnostics
+      .slice(0, limit)
+      .map(
+        (diagnostic) =>
+          `- ${diagnostic.file}${diagnostic.line === undefined ? "" : `:${diagnostic.line}`}: ${diagnostic.message.split("\n")[0] ?? ""}`
+      ),
+    ...(diagnostics.length > limit ? [`- … ${diagnostics.length - limit} more`] : [])
+  ].join("\n")

package/src/Flow.ts

@@ -44,6 +44,8 @@ import {
 } from "./Review.ts"
 import type { OracleRules } from "./OracleGuard.ts"
 import type { Reviewer } from "./Reviewer.ts"
+import { withContract } from "./AutonomyContract.ts"
+import type { StallOptions } from "./Stall.ts"
 
 export { publishUsage, structuredAndPublish } from "./Usage.ts"
 
@@ -109,6 +111,18 @@ export interface ImplementPlanOptions {
    * `testsChange` is true.
    */
   readonly oracle?: { readonly rules?: OracleRules; readonly testsChange?: boolean }
+  /** Independent votes of the adversarial lens per round (ADR 0027 decision 7). Default 1. */
+  readonly votes?: number
+  /**
+   * Who applies review findings (ADR 0027 decision 8): the implementer's own
+   * chat (default), or a fresh chat on the coder seat briefed to apply the
+   * findings and nothing else, with the carried notes for orientation.
+   */
+  readonly fixer?: "coder" | "separate"
+  /** The repository's own review rules (`.llm4ts/review-rules.md`), loaded by the caller, as one extra lens. */
+  readonly repoRules?: Effect.Effect<Reviewer | undefined, FlowError>
+  /** End a coder turn that repeats one tool call or goes silent (ADR 0027 decision 11). */
+  readonly stall?: StallOptions
   /** How gate output reaches the coder in the fix prompt. */
   readonly fix?: FixPromptOptions
   /** Where each review lens's answer is kept, so a rerun over the same diff asks nothing. */
@@ -211,6 +225,14 @@ const defaultCommitMessage = (plan: Plan, task: Task): string => `${plan.epicId}
 const composeSystem = (base: string | undefined, note: string): string =>
   [base, note].filter((part): part is string => part !== undefined && part.length > 0).join("\n\n")
 
+/** The separate fixer's brief (ADR 0027 decision 8): the Bun port's fixer, word for word in spirit. */
+export const fixerBrief = [
+  "You apply review findings to a change another coder made. Apply the findings. Nothing else.",
+  "Surgical edits only: no refactors, no extras, no new tests beyond what a finding asks for.",
+  "If a finding is wrong (the reviewer misread the code), skip it and say so in one line.",
+  "Then stop."
+].join("\n")
+
 /**
  * The task's triage: the explicit one, or one built from `baseline` over the
  * commit the task starts from (HEAD now), or none.
@@ -258,7 +280,8 @@ export const implementPlanFlow = Effect.fn("@llm4ts/flow/Flow.implementPlan")(fu
     sharedCoder = yield* makeChat(context.coder, {
       events: context.events,
       agent: "coder",
-      ...(options.system === undefined ? {} : { system: options.system })
+      ...(options.system === undefined ? {} : { system: options.system }),
+      ...(options.stall === undefined ? {} : { stall: options.stall })
     })
   }
 
@@ -279,7 +302,8 @@ export const implementPlanFlow = Effect.fn("@llm4ts/flow/Flow.implementPlan")(fu
           coder = yield* makeChat(context.coder, {
             events: context.events,
             agent: "coder",
-            system: composeSystem(options.system, planSoFar.render)
+            system: composeSystem(options.system, planSoFar.render),
+            ...(options.stall === undefined ? {} : { stall: options.stall })
           })
         }
         // `plan.taskPrompt` deliberately reads the frozen `plan` captured at
@@ -354,6 +378,24 @@ export const implementPlanFlow = Effect.fn("@llm4ts/flow/Flow.implementPlan")(fu
           }
         }
         const triage = yield* triageFor(context, options)
+        const repoRules = options.repoRules === undefined ? undefined : yield* options.repoRules
+        const reviewers = [
+          ...(options.reviewers ?? minimalReviewers),
+          ...(repoRules === undefined ? [] : [repoRules])
+        ]
+        const fixWith =
+          options.fixer === "separate"
+            ? (prompt: string): Effect.Effect<string, FlowError> =>
+                Effect.flatMap(
+                  makeChat(context.coder, {
+                    events: context.events,
+                    agent: "coder",
+                    system: withContract(fixerBrief),
+                    ...(options.stall === undefined ? {} : { stall: options.stall })
+                  }),
+                  (fixer) => fixer.ask(withNotes(prompt, notes))
+                )
+            : undefined
         const oracle: OracleGateOptions | undefined =
           options.oracle === undefined
             ? undefined
@@ -368,7 +410,7 @@ export const implementPlanFlow = Effect.fn("@llm4ts/flow/Flow.implementPlan")(fu
                   : { baseCount: Effect.map(triage.baseline, (base) => base?.passedCount) })
               }
         yield* reviewAndFixLoop({
-          reviewers: options.reviewers ?? minimalReviewers,
+          reviewers,
           reviewerService: flowReviewer(context),
           coder,
           taskTitle: task.title,
@@ -379,6 +421,9 @@ export const implementPlanFlow = Effect.fn("@llm4ts/flow/Flow.implementPlan")(fu
           ...(options.format === undefined ? {} : { format: options.format }),
           ...(triage === undefined ? {} : { triage }),
           ...(oracle === undefined ? {} : { oracle }),
+          ...(options.votes === undefined ? {} : { votes: options.votes }),
+          ...(fixWith === undefined ? {} : { fixWith }),
+          ...(options.stall === undefined ? {} : { stallOnIdenticalDiff: true }),
           ...(options.fix === undefined ? {} : { fix: options.fix }),
           ...(options.reviewCache === undefined ? {} : { cache: options.reviewCache }),
           ...(options.onReview === undefined

package/src/FlowError.ts

@@ -267,6 +267,21 @@ export class RosterExhausted extends Schema.TaggedError<RosterExhausted>()("Rost
 }
 
 /** One story failed; carries the story id so a fail-fast run names its cause. */
+/**
+ * A loop that stopped making progress (ADR 0027 decision 11): the review
+ * round saw the same diff twice, the coder repeated one tool call too many
+ * times, or the seat went silent for too long. A stopping condition the
+ * model does not control; the story fails and the retro diagnoses.
+ */
+export class Stalled extends Schema.TaggedError<Stalled>()("Stalled", {
+  signal: Schema.Literals(["identical-diff", "repeated-tool-call", "silence", "no-progress"]),
+  detail: Schema.String
+}) {
+  get message(): string {
+    return `stalled (${this.signal}): ${this.detail}`
+  }
+}
+
 export class StoryFailed extends Schema.TaggedError<StoryFailed>()("StoryFailed", {
   story: Schema.String,
   reason: Schema.String
@@ -371,6 +386,7 @@ export const FlowError = Schema.Union([
   EpicIncomplete,
   LandingFailed,
   StoryFailed,
+  Stalled,
   DecisionsInvalid,
   OpenPointsPending,
   ContractConflict,

package/src/FlowEvents.ts

@@ -171,6 +171,19 @@ export class CapabilityUnenforceable extends Schema.TaggedClass<CapabilityUnenfo
   }
 ) {}
 
+/** A review finding moved down a severity because it could not be placed in the diff (ADR 0027). */
+export class ReviewFindingDemoted extends Schema.TaggedClass<ReviewFindingDemoted>()(
+  "ReviewFindingDemoted",
+  {
+    lens: Schema.String,
+    title: Schema.String,
+    from: Schema.Literals(["Critical", "Warning", "Info"]),
+    to: Schema.Literals(["Critical", "Warning", "Info"]),
+    reason: Schema.String,
+    lane: Schema.optionalKey(Schema.String)
+  }
+) {}
+
 /** A task's `verified:` claims against the tool calls its transcript shows (ADR 0027). */
 export class EvidenceChecked extends Schema.TaggedClass<EvidenceChecked>()("EvidenceChecked", {
   task: Schema.String,
@@ -356,6 +369,7 @@ export const FlowEvent = Schema.Union([
   CapabilityDeniedEvent,
   CapabilityUnenforceable,
   EvidenceChecked,
+  ReviewFindingDemoted,
   Declassified,
   ExecutorLeased,
   ExecutorReleased,

package/src/Pack.ts

@@ -4,7 +4,7 @@ import { Dimension } from "@llm4ts/core/eval/Eval"
 import type { ConsolidateRules } from "./Domains.ts"
 import { PlanParseError } from "./FlowError.ts"
 import { oracleRulesFrom, type OracleRules } from "./OracleGuard.ts"
-import { parseReviewer, type Reviewer } from "./Reviewer.ts"
+import { Reviewer, parseReviewer } from "./Reviewer.ts"
 import { CoverageRule } from "./SpecChecks.ts"
 import type { WorkspaceError, WorkspaceShape } from "./Workspace.ts"
 
@@ -74,6 +74,26 @@ export interface Pack {
    * over the defaults. Absent: the defaults.
    */
   readonly oracle: OracleRules | undefined
+  /**
+   * The `## Review rules` section (ADR 0027 decision 9): extra rules every
+   * pack lens carries after the shared preamble, or `- preamble: off`.
+   */
+  readonly reviewRules: { readonly text: string; readonly preamble: boolean } | undefined
+  /**
+   * `target:` (ADR 0028): the template of a source file's port
+   * (`{{dir}}/{{base}}.rs`); present only in a porting pack.
+   */
+  readonly target: string | undefined
+  /** `comment:` (ADR 0028): the target language's line-comment marker for the PORT STATUS trailer; default `//`. */
+  readonly comment: string | undefined
+  /**
+   * `## Diagnostics` (ADR 0028): `- command: …` prints what is red after a
+   * build, `- format: json | cargo` says how to read it. Present only in a
+   * porting pack.
+   */
+  readonly diagnostics:
+    | { readonly command: ReadonlyArray<string>; readonly format: "json" | "cargo" }
+    | undefined
   readonly dir: string
   readonly gate: (name: string) => ReadonlyArray<string> | undefined
   readonly prompt: (name: string) => string | undefined
@@ -237,9 +257,36 @@ export const loadPack = Effect.fn("@llm4ts/flow/Pack.load")(function* (
   const gates = Object.fromEntries(
     Object.entries(gateValues).map(([name, command]) => [name, command.split(/\s+/)])
   )
+  const reviewRulesBody = section(manifest.sections, "Review rules")
+  const reviewRulesValues = namedItems(reviewRulesBody)
+  const reviewRules =
+    reviewRulesBody === undefined
+      ? undefined
+      : {
+          text: reviewRulesBody
+            .split(/\r?\n/)
+            .filter((line) => !/^- preamble:/iu.test(line.trim()))
+            .join("\n")
+            .trim(),
+          preamble: reviewRulesValues.preamble?.toLowerCase() !== "off"
+        }
   const lenses = Object.entries(lensFiles)
     .sort(([left], [right]) => left.localeCompare(right))
     .map(([name, text]) => parseReviewer(name, text))
+    // The pack's own review rules ride on every lens; `preamble: off` leaves
+    // the shared preamble out (ADR 0027 decision 9).
+    .map((lens) =>
+      reviewRules === undefined
+        ? lens
+        : Reviewer.make({
+            ...lens,
+            systemPrompt:
+              reviewRules.text.length === 0
+                ? lens.systemPrompt
+                : `${lens.systemPrompt}\n\nPack review rules:\n${reviewRules.text}`,
+            ...(reviewRules.preamble ? {} : { preamble: false })
+          })
+    )
   const fields = manifest.fields
   if (fields["programFiles"] !== undefined) {
     return yield* PlanParseError.make({
@@ -273,6 +320,17 @@ export const loadPack = Effect.fn("@llm4ts/flow/Pack.load")(function* (
       message: `pack manifest 'spec-schema:' must be 'pagespec' when set, got: ${specSchema}`
     })
   }
+  const diagnosticsValues = namedItems(section(manifest.sections, "Diagnostics"))
+  const diagnostics =
+    diagnosticsValues.command === undefined
+      ? undefined
+      : {
+          command: diagnosticsValues.command.split(/\s+/),
+          format:
+            diagnosticsValues.format?.toLowerCase() === "cargo"
+              ? ("cargo" as const)
+              : ("json" as const)
+        }
   const oracleValues = namedItems(section(manifest.sections, "Oracle"))
   const oracle: OracleRules | undefined =
     section(manifest.sections, "Oracle") === undefined
@@ -346,6 +404,10 @@ export const loadPack = Effect.fn("@llm4ts/flow/Pack.load")(function* (
     specSchema,
     consolidate,
     oracle,
+    reviewRules,
+    target: fields["target"],
+    comment: fields["comment"],
+    diagnostics,
     dir: directory,
     gate: (name) => gates[name],
     prompt: (name) => prompts[name],

package/src/Port.ts

@@ -0,0 +1,178 @@
+// Porting a code base file by file (ADR 0028): the manifest, its batches, the
+// deterministic target path, the machine-readable PORT STATUS trailer every
+// draft ends with, and the pilot report. Pure; the flows own the seats.
+import { basename, dirname, extname } from "node:path"
+import * as Schema from "effect/Schema"
+import { DraftApprovalMarker } from "./Approval.ts"
+import type { QueueOutcome } from "./WorkQueue.ts"
+
+export class PortEntry extends Schema.Class<PortEntry>("PortEntry")({
+  /** Repo-relative source path; also the queue item id. */
+  id: Schema.String,
+  source: Schema.String,
+  target: Schema.String,
+  loc: Schema.Int
+}) {}
+
+/**
+ * The target path of a source, from the pack's `target:` template:
+ * `{{dir}}` (the source's directory, "" at the root), `{{base}}` (its name
+ * without extension), `{{ext}}` (the extension without the dot), `{{path}}`
+ * (the whole source path).
+ */
+export const targetPathOf = (template: string, source: string): string => {
+  const dir = dirname(source)
+  const ext = extname(source)
+  const rendered = template
+    .replaceAll("{{dir}}", dir === "." ? "" : dir)
+    .replaceAll("{{base}}", basename(source, ext))
+    .replaceAll("{{ext}}", ext.replace(/^\./u, ""))
+    .replaceAll("{{path}}", source)
+  return rendered.replace(/^\/+/u, "").replaceAll("//", "/")
+}
+
+export const linesOf = (text: string): number =>
+  text.length === 0 ? 0 : text.split(/\r?\n/u).filter((line) => line.trim().length > 0).length
+
+export interface BatchPolicy {
+  /** Files per batch. Default 100. */
+  readonly files?: number
+  /** A batch whose first file is longer than this (lines) shrinks to `small`. Default 2200. */
+  readonly bigLoc?: number
+  /** Default 6. */
+  readonly small?: number
+}
+
+/** Contiguous batches of the manifest; a batch led by a big file is small (the Bun rule). */
+export const batchesOf = (
+  entries: ReadonlyArray<PortEntry>,
+  policy: BatchPolicy = {}
+): ReadonlyArray<ReadonlyArray<PortEntry>> => {
+  const files = Math.max(1, policy.files ?? 100)
+  const bigLoc = policy.bigLoc ?? 2_200
+  const small = Math.max(1, policy.small ?? 6)
+  const batches: Array<ReadonlyArray<PortEntry>> = []
+  let index = 0
+  while (index < entries.length) {
+    const first = entries[index]
+    const size = first !== undefined && first.loc > bigLoc ? small : files
+    batches.push(entries.slice(index, index + size))
+    index += size
+  }
+  return batches
+}
+
+export const PortConfidence = Schema.Literals(["high", "medium", "low"])
+export type PortConfidence = typeof PortConfidence.Type
+
+export interface PortStatus {
+  readonly confidence: PortConfidence | undefined
+  readonly todos: number | undefined
+  readonly notes: string | undefined
+}
+
+const statusWindow = 40
+
+/**
+ * The PORT STATUS trailer of a draft: in any comment syntax, within the last
+ * lines of the file, `confidence: high|medium|low`, `todos: <n>`, `notes: …`.
+ * All undefined when the draft has no trailer.
+ */
+export const portStatusIn = (text: string): PortStatus => {
+  const lines = text.split(/\r?\n/u)
+  const tail = lines.slice(Math.max(0, lines.length - statusWindow))
+  const start = tail.findIndex((line) => /PORT STATUS/u.test(line))
+  if (start < 0) {
+    return { confidence: undefined, todos: undefined, notes: undefined }
+  }
+  const block = tail.slice(start).join("\n")
+  const confidence = /confidence:\s*(high|medium|low)\b/iu.exec(block)?.[1]?.toLowerCase()
+  const todos = /todos?:\s*(\d+)/iu.exec(block)?.[1]
+  const notes = /notes?:\s*(.+)$/imu.exec(block)?.[1]?.trim()
+  return {
+    confidence:
+      confidence === "high" || confidence === "medium" || confidence === "low"
+        ? confidence
+        : undefined,
+    todos: todos === undefined ? undefined : Number.parseInt(todos, 10),
+    notes: notes === undefined || notes.length === 0 ? undefined : notes.replace(/\s*\*\/\s*$/u, "")
+  }
+}
+
+/** The instruction every implementer gets: how to end the file. */
+export const portStatusInstruction = (comment: string): string =>
+  [
+    `End the file with a machine-readable trailer in ${comment} comments, exactly this shape:`,
+    `${comment} PORT STATUS`,
+    `${comment} source: <the source path>`,
+    `${comment} confidence: high | medium | low`,
+    `${comment} todos: <number of TODO(port) markers you left>`,
+    `${comment} notes: <one line: what you could not translate faithfully, or "none">`,
+    "`confidence: low` means the logic is probably wrong and must be re-read against the source."
+  ].join("\n")
+
+export interface PilotFacts {
+  readonly outcomes: ReadonlyArray<QueueOutcome>
+  readonly piloted: number
+  readonly remaining: number
+  readonly elapsedMs: number
+  readonly estimatedCostUsd: number | undefined
+}
+
+const minutes = (ms: number): string => `${(ms / 60_000).toFixed(1)} min`
+
+/** The pilot report (R7 of the plan): rates measured, totals extrapolated, an approval to continue. */
+export const renderPilotReport = (facts: PilotFacts): string => {
+  const done = facts.outcomes.filter((outcome) => outcome.status === "done")
+  const failed = facts.outcomes.filter((outcome) => outcome.status === "failed")
+  const count = (level: PortConfidence) =>
+    done.filter((outcome) => outcome.confidence === level).length
+  const todos = done.reduce((sum, outcome) => sum + (outcome.todos ?? 0), 0)
+  const perItemMs = facts.piloted === 0 ? 0 : facts.elapsedMs / facts.piloted
+  const perItemCost =
+    facts.estimatedCostUsd === undefined || facts.piloted === 0
+      ? undefined
+      : facts.estimatedCostUsd / facts.piloted
+  return [
+    "# Port pilot",
+    "",
+    `- piloted: ${facts.piloted} file(s), ${done.length} done, ${failed.length} failed, in ${minutes(facts.elapsedMs)}`,
+    `- confidence: ${count("high")} high, ${count("medium")} medium, ${count("low")} low; ${todos} TODO(port) marker(s)`,
+    ...(perItemCost === undefined
+      ? []
+      : [
+          `- cost: ~$${(facts.estimatedCostUsd ?? 0).toFixed(2)} (~$${perItemCost.toFixed(3)} per file)`
+        ]),
+    `- remaining: ${facts.remaining} file(s) → about ${minutes(perItemMs * facts.remaining)} at this rate${
+      perItemCost === undefined ? "" : ` and ~$${(perItemCost * facts.remaining).toFixed(2)}`
+    }`,
+    "",
+    ...(failed.length === 0
+      ? []
+      : [
+          "## Failed",
+          "",
+          ...failed.map((outcome) => `- ${outcome.id}: ${outcome.note ?? ""}`),
+          ""
+        ]),
+    "Read the drafted files beside their sources, then tick the box to let the next run",
+    "port the rest; edit `prompts/porting.md` in the pack first if the drafts show a",
+    "pattern the rulebook should settle.",
+    "",
+    DraftApprovalMarker,
+    ""
+  ].join("\n")
+}
+
+/** A whole new file rendered as a unified diff of additions, for reviewers that judge diffs. */
+export const asAddedFileDiff = (path: string, content: string): string => {
+  const lines = content.split(/\r?\n/u)
+  return [
+    `diff --git a/${path} b/${path}`,
+    "new file mode 100644",
+    "--- /dev/null",
+    `+++ b/${path}`,
+    `@@ -0,0 +1,${lines.length} @@`,
+    ...lines.map((line) => `+${line}`)
+  ].join("\n")
+}