@pmelab/gtd 37.0.0 → 38.1.0

package/src/workflows/shared/text.ts

@@ -290,6 +290,30 @@ printf '%s\\n' ${lines.map(quote).join(" ")} > ${quote(".gtd/REQUIREMENTS.md")}
 `
 }
 
+export const slicingPrompt = (cap: number): string =>
+  `${stateFileRules}
+- Read \`.gtd/REQUIREMENTS.md\`: its \`## Acceptance Criteria\` are settled
+  and more than ${cap}, too many to build in one slice
+- Group them into slices in \`.gtd/SLICES.md\`, one \`## <title>\` heading per
+  slice over a \`- AC-<n>\` list item per criterion it builds. Put criteria of
+  the same flow or subsystem together; every criterion in exactly one slice,
+  at most ${cap} per slice
+- Keep it coarse: as few slices as the cap allows, never one per criterion
+- Order the slices so each builds on the ones before: they run in that order,
+  each from where the previous one landed
+- Change nothing but \`.gtd/SLICES.md\` — leave the criteria as they are
+- Leave everything uncommitted and finish your turn — do not commit
+`
+
+/** The line telling a slice's turn which criteria are its own; empty for a single slice. */
+const sliceLine = (ids: readonly string[] | undefined): string =>
+  ids === undefined
+    ? ""
+    : `- This slice builds ${ids.join(", ")} only: every rule here about the criteria
+  means these. The others are for other slices, before or after it — leave
+  them unbuilt and untested
+`
+
 export const designSystem = (): string =>
   `${designPersona}
 
@@ -351,6 +375,7 @@ export const refactorBuildingPrompt = ({
   reference,
   feedback = false,
   note = false,
+  from,
 }: {
   pkg: string
   strays: readonly string[]
@@ -358,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
@@ -386,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}
@@ -1174,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
@@ -1203,10 +1231,75 @@ ${listed(retry.strays)}
 Start over and choose a different approach; do not rebuild the same diff.
 `
 
-export const naivePassPrompt = (retry?: NaiveRetry): 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
-${criteriaBinding(false)}
+${sliceLine(slice)}${criteriaBinding(false)}
 - Implement them the quickest way that works — the naive version. Do not
   restructure, abstract or refactor around the change; it may land exactly as
   you leave it, and a reviewer makes it fit
@@ -1221,9 +1314,34 @@ ${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 {
@@ -1289,6 +1407,25 @@ const afterRefactorLine = (rebuild: Rebuild): string =>
   rule below; if nothing is, ${carries(rebuild) ? "carry over the acceptance tests below and change nothing else" : "change nothing and finish your turn"}
 `
 
+const flagLine = (
+  flagMode: boolean,
+  tier: "low" | "high" | undefined,
+  amend: boolean | undefined,
+  sliced: boolean,
+): string =>
+  !flagMode
+    ? "- Add no release flag — this project ships without release flags"
+    : tier === "low"
+      ? "- Add no release flag — this change is low risk tier"
+      : amend === true
+        ? "- Keep the release flag the earlier lap added, if it added one; otherwise put\n  the behaviour behind a new release flag"
+        : sliced
+          ? `- Put the new behaviour behind the release flag an earlier slice of this
+  change added; only when none did, behind a new one, following the
+  repository's flag conventions`
+          : `- Put the new behaviour behind a new release flag, following the
+  repository's flag conventions`
+
 export const implementBuildingPrompt = (
   reference: string | undefined,
   tier?: "low" | "high",
@@ -1296,10 +1433,12 @@ export const implementBuildingPrompt = (
   afterRefactor?: boolean,
   flagMode = true,
   rebuild: Rebuild = {},
+  slice?: readonly string[],
+  from?: Handoff,
 ): string =>
   `${stateFileRules}
 - Read \`.gtd/REQUIREMENTS.md\`: the settled requirements for this change
-${criteriaBinding(true)}
+${sliceLine(slice)}${criteriaBinding(true)}
 ${afterRefactor === true ? afterRefactorLine(rebuild) : ""}${
     amend === true
       ? `- The change already exists in the tree from an earlier lap; amend it to meet
@@ -1318,22 +1457,14 @@ ${afterRefactor === true ? afterRefactorLine(rebuild) : ""}${
   Read it for ideas; never apply, cherry-pick or check it out — write
   the change fresh${carries(rebuild) ? ", its acceptance tests excepted (below)" : ""}
 `
-  }${rebuildLines(rebuild)}${
-    !flagMode
-      ? "- Add no release flag — this project ships without release flags"
-      : tier === "low"
-        ? "- Add no release flag — this change is low risk tier"
-        : amend === true
-          ? "- Keep the release flag the earlier lap added, if it added one; otherwise put\n  the behaviour behind a new release flag"
-          : `- Put the new behaviour behind a new release flag, following the
-  repository's flag conventions`
-  }
+  }${rebuildLines(rebuild)}${flagLine(flagMode, tier, amend, slice !== undefined)}
 - 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}
@@ -1437,10 +1568,10 @@ export const coverageMessage = (): string =>
 counts every criterion as uncovered.
 `
 
-export const coveringPrompt = (uncovered: readonly string[]): string =>
+export const coveringPrompt = (uncovered: readonly string[], slice?: readonly string[]): string =>
   `${stateFileRules}
 - Read \`.gtd/REQUIREMENTS.md\`: the settled requirements for this change
-${criteriaBinding(true)}
+${sliceLine(slice)}${criteriaBinding(true)}
 - A judge found no passing test in this change that covers ${uncovered.join(", ")}.
   Write a behaviour-level test for each, naming its ID in the test or scenario
   name (\`[${uncovered[0]}] …\`), and fix the code if the test shows it falls short

package/src/workflows/shared/vars.ts

@@ -26,6 +26,7 @@ export const defaults: Readonly<Record<string, string>> = {
   refactorFlagPattern: "\\bGTD_FLAG_\\w+",
   seamAllow: [...testFileGlobs, ".gtd/**"].join(", "),
   flagMode: "true",
+  sliceMaxCriteria: "8",
   // GTD_FLAG_RISK_TIER, recorded at process start; only "1" is on.
   flag_risk_tier: "0",
   // Decides the turn count: one `build.quality.<lens>` scope per entry, each
@@ -33,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. */

package/src/workflows/shared/workflows.steps.ts

@@ -52,3 +52,16 @@ Then("no commit body contains {string}", (world: TestkitWorld, text: string) =>
     .find((m) => m.includes(text))
   assert.ok(hit === undefined, `a commit body contains "${text}":\n${hit}`)
 })
+
+Then(
+  "slice {string} begins where slice {string} ends",
+  async (world: TestkitWorld, later: string, earlier: string) => {
+    const { stdout } = await world.repo().gtd("slices")
+    const range = (name: string): string[] => {
+      const line = stdout.split("\n").find((l) => l.startsWith(`${name} `))
+      assert.ok(line !== undefined, stdout)
+      return line.slice(name.length + 1).split("..")
+    }
+    assert.strictEqual(range(later)[0], range(earlier)[1], stdout)
+  },
+)