@pmelab/gtd 38.0.0 → 38.1.0

package/src/workflows/feature/seam.ts

@@ -18,13 +18,15 @@ import {
   run,
   scope,
   slice as sliced,
+  start,
   vars,
   wrote,
   type Change,
   type DiffShapeResult,
   type KeptTip,
 } from "../../flows/index.js"
-import { coder, FEEDBACK, REFACTOR_NOTE, REQUIREMENTS, SLICES } from "../shared/steps.js"
+import { continuing, phase, type Handoff, type Phase } from "../shared/continuation.js"
+import { coder, FEEDBACK, HANDOFF, REFACTOR_NOTE, REQUIREMENTS, SLICES } from "../shared/steps.js"
 import * as t from "../shared/text.js"
 import { defaults } from "../shared/vars.js"
 import { green, requireCoverage } from "./coverage.js"
@@ -32,6 +34,7 @@ import {
   criterionIds,
   requireCriteria,
   requireCriteriaFrozen,
+  requireCriteriaIfEdited,
   sliceIds,
   type CriteriaSlice,
 } from "./criteria.js"
@@ -60,14 +63,47 @@ export const judgeSeam = (tip: KeptTip): Promise<DiffShapeResult> =>
     exempt: tip.changes.filter((c) => c.status === "added").map((c) => c.path),
   })
 
-export const naivePass = (retry?: t.NaiveRetry, slice?: CriteriaSlice): Promise<void> =>
-  t.agentWithSkills("naive", t.naivePassPrompt(retry, sliceIds(slice)), {
-    label: retry === undefined ? "Writing the naive pass" : "Rewriting the naive pass",
+export const naivePass = (
+  retry?: t.NaiveRetry,
+  slice?: CriteriaSlice,
+  from?: Handoff,
+): Promise<void> =>
+  t.agentWithSkills("naive", t.naivePassPrompt(retry, sliceIds(slice), from), {
+    label:
+      from !== undefined
+        ? "Continuing the naive pass"
+        : retry === undefined
+          ? "Writing the naive pass"
+          : "Rewriting the naive pass",
     keep: true,
     model: coder(),
     system: t.builderSystem(),
   })
 
+const handoffOf = (tip: KeptTip, slice: CriteriaSlice | undefined): Handoff | undefined => {
+  const note = tip.changes.find((c) => c.path === HANDOFF && c.after !== undefined)
+  if (note === undefined) return undefined
+  return {
+    snapshot: tip.hash,
+    note: note.after!.trim(),
+    open: unnamed(idsOf(REQUIREMENTS, slice), acceptanceTests(tip.changes)),
+  }
+}
+
+/** A naive pass, continued until a pass ends without a handoff note: the snapshot is its kept tip. */
+const naiveContinued = (
+  retry: t.NaiveRetry | undefined,
+  slice: CriteriaSlice | undefined,
+  naive: Phase,
+) =>
+  continuing(naive, async (from, fresh) => {
+    const tip = await fresh(async () => {
+      await naivePass(retry, slice, from)
+      return kept("naive")!
+    })
+    return { result: tip, handoff: handoffOf(tip, slice) }
+  })
+
 // Only a string an import, `require` or `mock` call takes: a URL route or path-like data is not one.
 const IMPORTED = /(?:\bfrom|\bimport|\brequire\s*\(|\bmock\s*\()\s*\(?\s*(["'`])([^"'`\n]+)\1/g
 const EXTENSION = /\.[\w-]+$/
@@ -258,6 +294,56 @@ const applied = async (tip: string): Promise<boolean> => {
   return !wrote(FEEDBACK) && codeChanges().length > 0
 }
 
+/** `carried` limited to the criteria `.gtd/REQUIREMENTS.md` lists now; a file listing none narrows nothing. */
+const settled = (
+  carried: readonly string[] | undefined,
+  slice: CriteriaSlice | undefined,
+): readonly string[] => {
+  const listed = idsOf(REQUIREMENTS, slice)
+  if (carried === undefined) return listed
+  return listed.length === 0 ? carried : carried.filter((id) => listed.includes(id))
+}
+
+// A snapshot lands on the branch as it is; the health loop greens the whole build after.
+// Open IDs count every test line since the process start, so an amend lap's earlier tests close theirs.
+const build = (options: ImplementOptions): Promise<void> =>
+  continuing(phase("build", requireCriteriaIfEdited), async (from, fresh) => {
+    await fresh(() =>
+      t.agentWithSkills(
+        "building",
+        t.implementBuildingPrompt(
+          options.reference,
+          options.tier,
+          options.amend,
+          options.afterRefactor,
+          flagModeOn(),
+          options.rebuild,
+          sliceIds(options.slice),
+          from,
+        ),
+        {
+          label: from === undefined ? "Implementing" : "Continuing the implementation",
+          model: coder(),
+          system: t.builderSystem(),
+          ...(options.afterRefactor === true ? { allowEmpty: true } : {}),
+        },
+      ),
+    )
+    requireCriteriaFrozen(REQUIREMENTS)
+    // Committed by the snapshot, so a turn stopped again may leave it as it was: present means stopped.
+    const note = read(HANDOFF)
+    if (note === undefined) return { result: undefined }
+    const ids = settled(options.rebuild?.acceptance?.ids, options.slice)
+    return {
+      result: undefined,
+      handoff: {
+        snapshot: head(),
+        note: note.trim(),
+        open: unnamed(ids, acceptanceTests(changesSince(start()))),
+      },
+    }
+  })
+
 export function implement(options?: ImplementOptions): Promise<void>
 /** @deprecated Pass `implement({ reference, tier, amend })`. */
 export function implement(
@@ -276,27 +362,11 @@ export function implement(
     const since = head()
     const acceptance = options.rebuild?.acceptance
     const built = options.naive === undefined || !(await applied(options.naive))
-    if (built)
-      await t.agentWithSkills(
-        "building",
-        t.implementBuildingPrompt(
-          options.reference,
-          options.tier,
-          options.amend,
-          options.afterRefactor,
-          flagModeOn(),
-          options.rebuild,
-          sliceIds(options.slice),
-        ),
-        {
-          label: "Implementing",
-          model: coder(),
-          system: t.builderSystem(),
-          ...(options.afterRefactor === true ? { allowEmpty: true } : {}),
-        },
-      )
-    requireCriteriaFrozen(REQUIREMENTS)
-    if (built && acceptance !== undefined) requireAcceptance(acceptance, since)
+    if (built) await build(options)
+    else requireCriteriaFrozen(REQUIREMENTS)
+    // Only the criteria still listed: a person may narrow them at `implement.oversized`.
+    if (built && acceptance !== undefined)
+      requireAcceptance({ ...acceptance, ids: settled(acceptance.ids, options.slice) }, since)
     // Fix turns are held to the carried tests too: deleting a red one must not buy a green suite.
     await green(
       built && acceptance !== undefined ? () => requireAcceptanceKept(acceptance) : undefined,
@@ -311,9 +381,11 @@ export const closeOut = (): Promise<void> => scope("implement", () => closing(fa
 
 /** A slice with `more` after it keeps the criteria and the slicing for the next one. */
 const closing = (more: boolean): Promise<void> =>
-  run("closing", removeScript(more ? [REFACTOR_NOTE] : [REQUIREMENTS, REFACTOR_NOTE, SLICES]), {
-    label: "Closing out the implementation",
-  })
+  run(
+    "closing",
+    removeScript(more ? [REFACTOR_NOTE, HANDOFF] : [REQUIREMENTS, REFACTOR_NOTE, SLICES, HANDOFF]),
+    { label: "Closing out the implementation" },
+  )
 
 interface Decision {
   readonly reference: string
@@ -392,10 +464,10 @@ const ruled = async (tip: KeptTip, again: Vetting["again"]): Promise<Decision |
 const decide = (slice: CriteriaSlice | undefined): Promise<Decision> =>
   scope("seam", async () => {
     const vetting: Vetting = { again: budget(), waived: false }
+    const naive = phase("naive pass", requireCriteriaIfEdited)
     let retry: t.NaiveRetry | undefined
     for (;;) {
-      await naivePass(retry, slice)
-      const tip = kept("naive")!
+      const tip = await naiveContinued(retry, slice, naive)
       const outcome =
         (await vetted(tip, vetting, slice)) ??
         (flagModeOn() ? await ruled(tip, vetting.again) : { reference: tip.hash, tip })

package/src/workflows/shared/continuation.ts

@@ -0,0 +1,92 @@
+import { human, refuse, scope, vars } from "../../flows/index.js"
+import * as t from "./text.js"
+import type { Handoff } from "./text.js"
+import { defaults } from "./vars.js"
+
+export type { Handoff }
+
+export interface Turned<T> {
+  readonly result: T
+  /** Set when the turn wrote a handoff note, i.e. stopped at its context limit. */
+  readonly handoff?: Handoff | undefined
+}
+
+/** Runs a turn's agent step in a conversation of its own, or in the caller's. */
+export type Fresh = <T>(fn: () => Promise<T>) => Promise<T>
+
+/**
+ * One phase's continuations, shared by every `continuing()` call in it (a naive
+ * retry, a refactor lap) so the caps hold per phase. `spent`: once a turn hit
+ * its context limit, resuming that conversation would only hit it again.
+ */
+export interface Phase {
+  readonly name: string
+  spent: boolean
+  count: number
+  stalled: number
+  /** Run after a landing at `oversized`, where a person may narrow the requirements; absent, the gate does not suggest it. */
+  readonly steered?: (() => void) | undefined
+}
+
+export const phase = (name: string, steered?: () => void): Phase => ({
+  name,
+  spent: false,
+  count: 0,
+  stalled: 0,
+  steered,
+})
+
+const own: Fresh = (fn) => fn()
+// Every `scope()` call is a new conversation; the names keep continuations
+// apart in history from later turns of a phase that merely start afresh.
+const continued: Fresh = (fn) => scope("continue", fn)
+const afresh: Fresh = (fn) => scope("fresh", fn)
+
+const setting = (name: "continuations" | "continuationStall", least: number): number => {
+  const raw = vars[name] ?? defaults[name]!
+  const n = Number(raw)
+  if (raw.trim() === "" || !Number.isInteger(n) || n < least)
+    refuse(`gtd: ${name} must be a whole number of at least ${least}, got ${JSON.stringify(raw)}`)
+  return n
+}
+
+/**
+ * Run `turn` until one ends without a handoff note: each stopped turn is picked
+ * up by a continuation in a fresh conversation. Past `continuations` of them in
+ * the phase, or after `continuationStall` in a row that close nothing still
+ * open, the phase rests at `oversized` for a person; landing there grants a new round.
+ */
+export const continuing = async <T>(
+  phase: Phase,
+  turn: (from: Handoff | undefined, fresh: Fresh) => Promise<Turned<T>>,
+): Promise<T> => {
+  const cap = setting("continuations", 0)
+  const stall = setting("continuationStall", 1)
+  let last = await turn(undefined, phase.spent ? afresh : own)
+  while (last.handoff !== undefined) {
+    phase.spent = true
+    const from = last.handoff
+    if (phase.count >= cap || phase.stalled >= stall) {
+      await human("oversized", {
+        message: t.oversizedMessage(
+          phase.name,
+          from,
+          phase.count >= cap ? { cap } : { stall },
+          phase.steered !== undefined,
+        ),
+        label: "Too big for its context",
+        acceptClean: true,
+      })
+      phase.steered?.()
+      phase.count = 0
+      phase.stalled = 0
+    }
+    last = await turn(from, continued)
+    phase.count++
+    // Nothing countable left open is no stall: only the cap stops such a phase.
+    const closed =
+      from.open.length === 0 || from.open.some((item) => !(last.handoff?.open ?? []).includes(item))
+    phase.stalled = closed ? 0 : phase.stalled + 1
+  }
+  return last.result
+}

package/src/workflows/shared/options.ts

@@ -24,6 +24,8 @@ export const ShippedOptions = Schema.Struct({
   sliceMaxCriteria: setting,
   qualityReviews: setting,
   refactorQualityReviews: setting,
+  continuations: setting,
+  continuationStall: setting,
   testCommand: setting,
   plannerModel: setting,
   coderModel: setting,

package/src/workflows/shared/steps.ts

@@ -15,6 +15,7 @@ export const REFACTOR = ".gtd/REFACTOR.md"
 export const REFACTOR_NOTE = ".gtd/REFACTOR-NOTE.md"
 export const QUALITY = ".gtd/QUALITY.md"
 export const SLICES = ".gtd/SLICES.md"
+export const HANDOFF = ".gtd/HANDOFF.md"
 
 export const planner = (): string => env.plannerModel ?? ""
 export const coder = (): string => env.coderModel ?? ""

package/src/workflows/shared/text.test.ts

@@ -976,7 +976,9 @@ describe("the seam phase's texts", () => {
   it("has a red retry pick up the kept attempt instead of starting over", () => {
     const prompt = renderText(() => naivePassPrompt({ red: "abc123" }))
     expect(prompt).toContain("left the suite red")
-    expect(prompt).toContain("git diff --binary abc123^ abc123 | git apply")
+    expect(prompt).toContain(
+      "git diff --binary --no-color --no-ext-diff --no-textconv abc123^ abc123 | git apply",
+    )
     expect(prompt).toContain(".gtd/FEEDBACK.md")
     expect(prompt).not.toContain("rejected")
   })
@@ -1042,7 +1044,9 @@ describe("the seam phase's texts", () => {
     }
     const prompt = renderText(() => naivePassPrompt(fault))
     expect(prompt).toContain("names AC-2")
-    expect(prompt).toContain("git diff --binary abc123^ abc123 | git apply")
+    expect(prompt).toContain(
+      "git diff --binary --no-color --no-ext-diff --no-textconv abc123^ abc123 | git apply",
+    )
     const message = renderText(() => seamSteerMessage(fault))
     expect(message).toContain("names AC-2")
     expect(message).toContain("`seam.check` runs its suite")

package/src/workflows/shared/text.ts

@@ -375,6 +375,7 @@ export const refactorBuildingPrompt = ({
   reference,
   feedback = false,
   note = false,
+  from,
 }: {
   pkg: string
   strays: readonly string[]
@@ -382,6 +383,8 @@ export const refactorBuildingPrompt = ({
   reference?: string | undefined
   feedback?: boolean | undefined
   note?: boolean | undefined
+  /** A continuation of a refactor turn that stopped at its context limit; `open` are its untouched paths. */
+  from?: Handoff | undefined
 }): string =>
   `${stateFileRules}
 - The package to implement is \`${pkg}\`; never delete it
@@ -410,8 +413,9 @@ ${
   refactor that touches none of it is wrong, however clean — never
   swap in an unrelated tidy-up
 `
-}- Leave everything uncommitted and finish your turn — do not commit
-`
+}${handoffRule()}
+- Leave everything uncommitted and finish your turn — do not commit
+${from === undefined ? "" : continuationLines(from)}`
 
 export const refactorFixPrompt = (strays: readonly string[], pattern: string): string =>
   `${stateFileRules}
@@ -1198,8 +1202,8 @@ export type NaiveRetry = SeamRejection | NaiveRed | NaiveFault
 const isRed = (retry: NaiveRetry): retry is NaiveRed => "red" in retry
 const isFault = (retry: NaiveRetry): retry is NaiveFault => "fault" in retry
 
-const pickUp = (hash: string): string =>
-  `Pick it up — \`git diff --binary ${hash}^ ${hash} | git apply\``
+const pickUp = (hash: string, exclude?: string): string =>
+  `Pick it up — \`git diff --binary --no-color --no-ext-diff --no-textconv ${hash}^ ${hash}${exclude === undefined ? "" : ` -- ${quote(":(top)")} ${quote(`:(top,exclude)${exclude}`)}`} | git apply\``
 
 const criteriaBinding = (refused: boolean): string =>
   `- Its \`## Acceptance Criteria\` (\`AC-<n>\`) bind this turn: re-read them from
@@ -1227,7 +1231,72 @@ ${listed(retry.strays)}
 Start over and choose a different approach; do not rebuild the same diff.
 `
 
-export const naivePassPrompt = (retry?: NaiveRetry, slice?: readonly string[]): string =>
+/** A turn that stopped at its context limit: the snapshot it left, its handoff note, what it left open. */
+export interface Handoff {
+  /** The commit holding the stopped turn's work: its kept tip, or the turn's own commit. */
+  readonly snapshot: string
+  readonly note: string
+  readonly open: readonly string[]
+}
+
+const quoted = (text: string): string =>
+  text
+    .trimEnd()
+    .split("\n")
+    .map((line) => (line === "" ? "" : `  > ${line}`))
+    .join("\n")
+
+/** Every turn a continuation may pick up tells its agent where the note goes. */
+const handoffRule = (): string =>
+  `- Should you be told to stop at a context limit, write the handoff note to
+  \`.gtd/HANDOFF.md\` — what you touched, what was next — and finish your turn:
+  a fresh turn picks up from what you leave, broken or not. That file is the one
+  exception to any path rule here; write it at no other time`
+
+/** `pickUp`: how the snapshot gets into the tree — absent when it already is. */
+const continuationLines = (from: Handoff, pickUp?: string): string =>
+  `
+Your previous turn stopped at its context limit; this fresh turn picks up from
+its snapshot (\`${from.snapshot}\`). ${pickUp === undefined ? "Its work is already in the tree." : `${pickUp}.`} Its handoff note:
+
+${quoted(from.note === "" ? "(empty)" : from.note)}
+
+Still open: ${from.open.length === 0 ? "nothing the workflow can count — finish what the note says is next" : from.open.join(", ")}.
+${pickUp === undefined ? "Delete `.gtd/HANDOFF.md` once you are done; rewrite it should you be stopped again.\n" : ""}`
+
+export const oversizedMessage = (
+  phase: string,
+  from: Handoff,
+  why: { readonly cap: number } | { readonly stall: number },
+  narrowable = true,
+): string =>
+  `The ${phase} keeps outgrowing its context: ${
+    "cap" in why
+      ? why.cap === 0
+        ? "continuations are off (`continuations` is 0) and the turn stopped at its context limit"
+        : `${why.cap} continuation${why.cap === 1 ? "" : "s"} ran and the last still stopped at its context limit`
+      : `the last ${why.stall} continuation${why.stall === 1 ? "" : "s"} closed nothing still open`
+  }. The last snapshot is \`${from.snapshot}\`; still open: ${from.open.length === 0 ? "nothing countable" : from.open.join(", ")}.
+
+Its handoff note:
+
+${quoted(from.note === "" ? "(empty)" : from.note)}
+
+Land to go on: a fresh round of continuations picks up from that snapshot${
+    narrowable
+      ? ` — narrow
+\`.gtd/REQUIREMENTS.md\` first if the change is too big, or raise the context limit`
+      : ` — raise
+the context limit first if the refactor is too big`
+  }. \`gtd abandon\` gives the change up.
+`
+
+/** `from`: a continuation of a pass that stopped at its context limit, in place of `retry`'s pick-up. */
+export const naivePassPrompt = (
+  retry?: NaiveRetry,
+  slice?: readonly string[],
+  from?: Handoff,
+): string =>
   `${stateFileRules}
 - Read \`.gtd/REQUIREMENTS.md\`: the settled requirements for this change
 ${sliceLine(slice)}${criteriaBinding(false)}
@@ -1245,9 +1314,34 @@ ${sliceLine(slice)}${criteriaBinding(false)}
 - Run \`${env.testCommand}\` and finish only once it is green with every
   criterion's test passing: the next step runs it on your diff and sends a red
   pass back
-- Leave \`.gtd/\` untouched
+- Leave \`.gtd/\` untouched, a handoff note excepted
+${handoffRule()}
 - Leave everything uncommitted and finish your turn — do not commit
-${retry === undefined ? "" : naiveRetry(retry)}`
+${
+  from !== undefined
+    ? `${continuationLines(from, pickUp(from.snapshot, ".gtd/HANDOFF.md"))}${
+        retry === undefined
+          ? ""
+          : isFault(retry)
+            ? `
+The pass this continues was a retry: its tests fell short, and still must not:
+${retry.fault}
+`
+            : isRed(retry)
+              ? `
+The pass this continues was a retry after a red suite (\`.gtd/FEEDBACK.md\`
+holds the output): finish only once the suite is green.
+`
+              : `
+The pass this continues was a retry after a \`reject\`: keep away from the
+approach that changed these files outside the expected set:
+${listed(retry.strays)}
+`
+      }`
+    : retry === undefined
+      ? ""
+      : naiveRetry(retry)
+}`
 
 /** The naive pass's kept tip, its acceptance test files and the criterion IDs they name. */
 export interface Acceptance {
@@ -1340,6 +1434,7 @@ export const implementBuildingPrompt = (
   flagMode = true,
   rebuild: Rebuild = {},
   slice?: readonly string[],
+  from?: Handoff,
 ): string =>
   `${stateFileRules}
 - Read \`.gtd/REQUIREMENTS.md\`: the settled requirements for this change
@@ -1366,9 +1461,10 @@ ${afterRefactor === true ? afterRefactorLine(rebuild) : ""}${
 - Write the tests first, then the code that makes them pass. Name each
   criterion's ID in the test that covers it (\`[AC-3] …\`): once the suite is
   green a judge checks every ID has a passing test, and sends uncovered ones back
+${handoffRule()}
 - Leave \`.gtd/REQUIREMENTS.md\` in place and everything uncommitted, then
   finish your turn
-`
+${from === undefined ? "" : continuationLines(from)}`
 
 export const implementFixPrompt = (): string =>
   `${stateFileRules}

package/src/workflows/shared/vars.ts

@@ -34,6 +34,11 @@ export const defaults: Readonly<Record<string, string>> = {
   qualityReviews:
     "correctness, owasp-security, ponytail-review, test-audit, conventions, spec-challenge",
   refactorQualityReviews: "correctness, ponytail-review, conventions",
+  // Per phase (naive pass, refactor, build): continuations of a turn that
+  // stopped at its context limit before a person is asked, and how many in a
+  // row may close nothing still open.
+  continuations: "3",
+  continuationStall: "2",
 }
 
 /** Environment settings. */