@pmelab/gtd 38.0.0 → 38.1.0

package/src/workflows/feature/continuation-rebuild.feature

@@ -0,0 +1,88 @@
+@inmem
+Feature: a rebuild stopped at its context limit is continued on the branch
+
+  The rebuild's snapshot is its own commit: the continuation finds the work
+  in the tree, and the health loop greens the whole build afterwards.
+  `seamAllow` is empty here, so the naive pass's change to an existing test
+  file is the judge's only stray and refactor-first rebuilds with no refactor.
+
+  Background:
+    Given the shipped workflows, as gtd install scaffolds them
+    And an environment variable "GTD_SEAMALLOW" set to ""
+    And an environment variable "GTD_QUALITYREVIEWS" set to ""
+    And an environment variable "GTD_REFACTORQUALITYREVIEWS" set to ""
+    And an environment variable "GTD_FLAG_RISK_TIER" set to "0"
+    And a file "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => a + b
+      """
+    And a file "tests/calc.test.ts" with:
+      """
+      it("adds", () => {})
+      """
+    And the working tree is committed as "feat: add calculator"
+    And a file "TODO.md" with:
+      """
+      # Add subtract and multiply
+      """
+    And step "unwind" changes nothing
+    And step "start-gate.check" changes nothing
+    And step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+      """
+      # Requirements
+
+      ## Acceptance Criteria
+
+      - AC-1: `subtract(5, 3)` returns 2.
+      - AC-2: `multiply(2, 3)` returns 6.
+      """
+    And step "design.gate.answer" changes nothing
+    And step "seam.check" changes nothing
+
+  Scenario: a rebuild stopped at its context limit lands its snapshot and is continued on the branch
+    Given step "seam.naive" writes "src/ops.ts" with:
+      """
+      export const subtract = (a: number, b: number) => a - b
+      export const multiply = (a: number, b: number) => a * b
+      """
+    And step "seam.naive" writes "tests/calc.test.ts" with:
+      """
+      it("adds", () => {})
+      it("[AC-1] subtracts", () => {})
+      it("[AC-2] multiplies", () => {})
+      """
+    And judge step "seam.judge" answers:
+      """
+      [{"id":"shape","answer":"refactor-first","p":0.9}]
+      """
+    And step "implement.building" writes "tests/calc.test.ts" with:
+      """
+      it("adds", () => {})
+      it("[AC-1] subtracts", () => {})
+      """
+    And step "implement.building" writes ".gtd/HANDOFF.md" with:
+      """
+      Rebuilt subtract behind the flag; multiply was next.
+      """
+    When the process is driven
+    Then the process rests at "implement.continue.building"
+    And the resting step's content contains "Still open: AC-2."
+    And the resting step's content contains "Its work is already in the tree."
+    And the resting step's content contains "Delete `.gtd/HANDOFF.md` once you are done"
+    And "tests/calc.test.ts" contains "[AC-1] subtracts"
+
+    Given step "implement.continue.building" writes "tests/calc.test.ts" with:
+      """
+      it("adds", () => {})
+      it("[AC-1] subtracts", () => {})
+      it("[AC-2] multiplies", () => {})
+      """
+    And step "implement.continue.building" deletes ".gtd/HANDOFF.md"
+    When the process is driven
+    Then the process rests at "implement.health.check"
+    And the commit subjects end with:
+      """
+      gtd(agent): implement.building → implement.continue.building
+      gtd(agent): implement.continue.building → implement.health.check
+      """
+

package/src/workflows/feature/continuation-slices.feature

@@ -0,0 +1,64 @@
+@inmem
+Feature: a continuation stays inside its coarse slice
+
+  A naive pass of one coarse slice that stops at its context limit is
+  continued with that slice's criteria still open, never another slice's.
+
+  Background:
+    Given the shipped workflows, as gtd install scaffolds them
+    And an environment variable "GTD_QUALITYREVIEWS" set to ""
+    And an environment variable "GTD_FLAGMODE" set to "false"
+    And an environment variable "GTD_SLICEMAXCRITERIA" set to "2"
+    And a file "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => a + b
+      """
+    And the working tree is committed as "feat: add calculator"
+    And a file "TODO.md" with:
+      """
+      # More arithmetic
+
+      subtract, multiply and divide.
+      """
+    And step "unwind" changes nothing
+    And step "start-gate.check" changes nothing
+    And step "design.gate.answer" changes nothing
+    And step "seam.check" changes nothing
+
+  Scenario: the first slice's continuation is told only that slice's open criterion
+    Given step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+      """
+      # Requirements
+
+      ## Acceptance Criteria
+
+      - AC-1: subtract(a, b) returns a - b.
+      - AC-2: multiply(a, b) returns a * b.
+      - AC-3: divide(a, b) returns a / b.
+      """
+    And step "design.slicing" writes ".gtd/SLICES.md" with:
+      """
+      # Slices
+
+      ## Subtract and divide
+
+      - AC-1
+      - AC-3
+
+      ## Multiply
+
+      - AC-2
+      """
+    And step "seam.naive" writes "src/sub.test.ts" with:
+      """
+      it("[AC-1] subtracts", () => {})
+      """
+    And step "seam.naive" writes ".gtd/HANDOFF.md" with:
+      """
+      Subtract is tested; divide was next.
+      """
+    When the process is driven
+    Then the process rests at "seam.continue.naive"
+    And the resting step's content contains "This slice builds AC-1, AC-3 only"
+    And the resting step's content contains "Still open: AC-3."
+    And the resting step's content does not contain "AC-2"

package/src/workflows/feature/continuation.feature

@@ -0,0 +1,205 @@
+@inmem
+Feature: a turn stopped at its context limit is snapshotted and continued
+
+  A naive pass, refactor or build turn told to stop at its context limit
+  writes its handoff note to `.gtd/HANDOFF.md`. That turn is the snapshot —
+  the naive pass's kept tip, or the refactor's or build's own commit — and a
+  continuation in a fresh conversation (`<phase>.continue.<step>`) picks up
+  from it with the note and what is still open. After `continuations` (3) of
+  them, or `continuationStall` (2) in a row that close nothing still open, the
+  phase rests at `<phase>.oversized`.
+
+  Background:
+    Given the shipped workflows, as gtd install scaffolds them
+    And an environment variable "GTD_QUALITYREVIEWS" set to ""
+    And an environment variable "GTD_REFACTORQUALITYREVIEWS" set to ""
+    And an environment variable "GTD_FLAG_RISK_TIER" set to "0"
+    And a file "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => a + b
+      """
+    And the working tree is committed as "feat: add calculator"
+    And a file "TODO.md" with:
+      """
+      # Add subtract and multiply
+      """
+    And step "unwind" changes nothing
+    And step "start-gate.check" changes nothing
+    And step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+      """
+      # Requirements
+
+      ## Acceptance Criteria
+
+      - AC-1: `subtract(5, 3)` returns 2.
+      - AC-2: `multiply(2, 3)` returns 6.
+      """
+    And step "design.gate.answer" changes nothing
+    And step "seam.check" changes nothing
+
+  Scenario: a naive pass stopped at its context limit is continued from its kept tip with the open IDs
+    Given step "seam.naive" writes "tests/calc.test.ts" with:
+      """
+      it("[AC-1] subtracts", () => {})
+      """
+    And step "seam.naive" writes ".gtd/HANDOFF.md" with:
+      """
+      Wrote subtract and its test; multiply was next.
+      """
+    When the process is driven
+    Then the process rests at "seam.continue.naive"
+    And the resting step's content contains "Your previous turn stopped at its context limit"
+    And the resting step's content contains "Still open: AC-2."
+    And the resting step's content contains "Wrote subtract and its test; multiply was next."
+    And the resting step's content contains "':(top)' ':(top,exclude).gtd/HANDOFF.md' | git apply"
+    And ".gtd/HANDOFF.md" does not exist
+    And the output of gtd "next --json" contains "\"resume\":false"
+    And the output of gtd "next --json" contains "\"memory\":\"seam.continue#"
+
+    Given step "seam.continue.naive" writes "tests/calc.test.ts" with:
+      """
+      it("[AC-1] subtracts", () => {})
+      it("[AC-2] multiplies", () => {})
+      """
+    When the process is driven
+    Then the process rests at "implement.applying"
+    And the commit subjects end with:
+      """
+      gtd(human): design.gate.answer → seam.naive
+      gtd(agent): seam.naive → seam.continue.naive
+      gtd(agent): seam.continue.naive → seam.check
+      gtd(check): seam.check → implement.applying
+      """
+
+  Scenario: two continuations in a row that close nothing rest for a person
+    Given step "seam.naive" writes "tests/calc.test.ts" with:
+      """
+      it("[AC-1] subtracts", () => {})
+      """
+    And step "seam.naive" writes ".gtd/HANDOFF.md" with:
+      """
+      Subtract is tested; multiply was next.
+      """
+    And step "seam.continue.naive" writes ".gtd/HANDOFF.md" with:
+      """
+      Still on multiply.
+      """
+    When the process is driven
+    Then the process rests at "seam.oversized"
+    And the resting step's content contains "the last 2 continuations closed nothing still open"
+    And the commit subjects end with:
+      """
+      gtd(human): design.gate.answer → seam.naive
+      gtd(agent): seam.naive → seam.continue.naive
+      gtd(agent): seam.continue.naive
+      gtd(agent): seam.continue.naive → seam.oversized
+      """
+
+  Scenario: a refactor stopped at its context limit is run green before its continuation
+    Given step "seam.naive" writes "tests/calc.test.ts" with:
+      """
+      it("[AC-1] subtracts", () => {})
+      it("[AC-2] multiplies", () => {})
+      """
+    And step "seam.naive" writes "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => a + b
+      export const subtract = (a: number, b: number) => a - b
+      export const multiply = (a: number, b: number) => a * b
+      """
+    And judge step "seam.judge" answers:
+      """
+      [{"id":"shape","answer":"refactor-first","p":0.9}]
+      """
+    And step "seam.note" writes ".gtd/REFACTOR-NOTE.md" with:
+      """
+      Seam: a shared `op` in src/calc.ts.
+      """
+    And step "refactor.deriving" runs its script
+    And step "refactor.building" writes ".gtd/HANDOFF.md" with:
+      """
+      Started on op; nothing changed yet.
+      """
+    And step "refactor.health.check" changes nothing
+    When the process is driven
+    Then the process rests at "refactor.continue.building"
+    And the resting step's content contains "Still open: src/calc.ts."
+    And the resting step's content contains "Started on op; nothing changed yet."
+    And the commit subjects end with:
+      """
+      gtd(agent): refactor.building → refactor.health.check
+      gtd(check): refactor.health.check → refactor.continue.building
+      """
+
+  Scenario: a refactor continuation that leaves the note in place stopped again
+    Given step "seam.naive" writes "tests/calc.test.ts" with:
+      """
+      it("[AC-1] subtracts", () => {})
+      it("[AC-2] multiplies", () => {})
+      """
+    And step "seam.naive" writes "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => a + b
+      export const subtract = (a: number, b: number) => a - b
+      """
+    And judge step "seam.judge" answers:
+      """
+      [{"id":"shape","answer":"refactor-first","p":0.9}]
+      """
+    And step "seam.note" writes ".gtd/REFACTOR-NOTE.md" with:
+      """
+      Seam: a shared `op` in src/calc.ts.
+      """
+    And step "refactor.deriving" runs its script
+    And step "refactor.building" writes "src/calc.ts" with:
+      """
+      export const op = (a: number, b: number, sign: number) => a + sign * b
+      export const add = (a: number, b: number) => a + b
+      """
+    And step "refactor.building" writes ".gtd/HANDOFF.md" with:
+      """
+      op is in; routing add through it was next.
+      """
+    And step "refactor.health.check" changes nothing
+    And step "refactor.continue.building" writes "src/calc.ts" with:
+      """
+      export const op = (a: number, b: number, sign: number) => a + sign * b
+      export const add = (a: number, b: number) => op(a, b, 1)
+      """
+    When the process is driven
+    Then the process rests at "refactor.continue.building"
+    And the commit subjects end with:
+      """
+      gtd(agent): refactor.building → refactor.health.check
+      gtd(check): refactor.health.check → refactor.continue.building
+      gtd(agent): refactor.continue.building → refactor.health.check
+      gtd(check): refactor.health.check → refactor.continue.building
+      gtd(agent): refactor.continue.building
+      """
+
+  Scenario: once a naive pass has continued, its retry runs in a fresh conversation, not as a continuation
+    Given step "seam.naive" writes "tests/calc.test.ts" with:
+      """
+      it("[AC-1] subtracts", () => {})
+      """
+    And step "seam.naive" writes ".gtd/HANDOFF.md" with:
+      """
+      Multiply was next.
+      """
+    And step "seam.continue.naive" writes "tests/calc.test.ts" with:
+      """
+      it("[AC-1] subtracts", () => {})
+      it("[AC-2] multiplies", () => {})
+      """
+    And step "seam.continue.naive" writes "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => a - b
+      """
+    And judge step "seam.judge" answers:
+      """
+      [{"id":"shape","answer":"reject","p":0.9}]
+      """
+    When the process is driven
+    Then the process rests at "seam.fresh.naive"
+    And the resting step's content contains "rejected"
+    And the output of gtd "next --json" contains "\"resume\":false"

package/src/workflows/feature/criteria.ts

@@ -189,3 +189,14 @@ export const skipDesign = (stated: StatedCriteria | undefined): Promise<boolean>
         })
         return true
       })
+
+/** After a gate that invites narrowing the requirements: an edit must leave valid criteria. */
+export const requireCriteriaIfEdited = (): void => {
+  const change = changes().get(REQUIREMENTS)
+  if (change === undefined) return
+  if (change.status === "deleted")
+    refuse(
+      `gtd land: criteria-missing: ${REQUIREMENTS} must stay — narrow its criteria, never delete it`,
+    )
+  requireCriteria(REQUIREMENTS)
+}

package/src/workflows/feature/refactor.ts

@@ -15,8 +15,9 @@ import {
 } from "../../flows/index.js"
 import { lensEntriesOf } from "../../workflow-kit/index.js"
 import { markFenced } from "../shared/fences.js"
+import { continuing, phase, type Phase } from "../shared/continuation.js"
 import { healthy, type Guard } from "../shared/health.js"
-import { coder, FEEDBACK, REFACTOR } from "../shared/steps.js"
+import { coder, FEEDBACK, HANDOFF, REFACTOR } from "../shared/steps.js"
 import * as t from "../shared/text.js"
 import { defaults, testFileGlobs } from "../shared/vars.js"
 import { buildTail, reUnwind, type FeedbackTarget } from "./review.js"
@@ -263,7 +264,12 @@ const guardOf =
   }
 
 /** Derive, build, check and close one refactor lap; `feedback` is the collected review text of the lap before. */
-const refactorLap = async (p: Plan, guard: Guard, feedback?: string): Promise<void> => {
+const refactorLap = async (
+  p: Plan,
+  guard: Guard,
+  refactor: Phase,
+  feedback?: string,
+): Promise<void> => {
   const { pattern, strays, reference, note } = p
   await run(
     "deriving",
@@ -276,32 +282,59 @@ const refactorLap = async (p: Plan, guard: Guard, feedback?: string): Promise<vo
     ]),
     { label: "Deriving the refactor package", file: REFACTOR_PACKAGE },
   )
-  await t.agentWithSkills(
-    "building",
-    t.refactorBuildingPrompt({
-      pkg: REFACTOR_PACKAGE,
-      strays,
-      pattern,
-      reference,
-      feedback: feedback !== undefined,
-      note: note !== undefined,
-    }),
-    { label: "Refactoring", model: coder(), system: t.builderSystem() },
-  )
-  guard()
-  await healthy(
-    async () => {
-      await t.agentWithSkills("fix.suite.fixing", t.refactorFixPrompt(strays, pattern), {
-        label: "Fixing the check",
-        file: FEEDBACK,
-        model: coder(),
-        system: t.builderSystem(),
-      })
-      guard()
-    },
-    { describeGuard: guard, rules: t.refactorRules(strays, pattern) },
-  )
-  await run("closing", removeScript([REFACTOR_PACKAGE]), { label: "Closing out the refactor" })
+  const reached = new Set<string>()
+  // Each snapshot is greened before its continuation: every sub-step keeps the old suite green.
+  await continuing(refactor, async (from, fresh) => {
+    await fresh(() =>
+      t.agentWithSkills(
+        "building",
+        t.refactorBuildingPrompt({
+          pkg: REFACTOR_PACKAGE,
+          strays,
+          pattern,
+          reference,
+          feedback: feedback !== undefined,
+          note: note !== undefined,
+          from,
+        }),
+        {
+          label: from === undefined ? "Refactoring" : "Continuing the refactor",
+          model: coder(),
+          system: t.builderSystem(),
+        },
+      ),
+    )
+    // Committed by the snapshot, so a turn stopped again may leave it as it was: present means stopped.
+    const left = read(HANDOFF)
+    guard()
+    const snapshot = head()
+    // The building turns' own changes only: a fix turn reaching a path is not the refactor reaching it.
+    for (const c of changes()) reached.add(c.path)
+    await healthy(
+      async () => {
+        await t.agentWithSkills("fix.suite.fixing", t.refactorFixPrompt(strays, pattern), {
+          label: "Fixing the check",
+          file: FEEDBACK,
+          model: coder(),
+          system: t.builderSystem(),
+        })
+        guard()
+      },
+      { describeGuard: guard, rules: t.refactorRules(strays, pattern) },
+    )
+    if (left === undefined) return { result: undefined }
+    return {
+      result: undefined,
+      handoff: {
+        snapshot,
+        note: left.trim(),
+        open: strays.filter((path) => !reached.has(path)),
+      },
+    }
+  })
+  await run("closing", removeScript([REFACTOR_PACKAGE, HANDOFF]), {
+    label: "Closing out the refactor",
+  })
 }
 
 const strayAccess = (strays: readonly string[]) => ({
@@ -315,7 +348,7 @@ export const refactorFirst = async (
   const p = plan(shape, options)
   if (p === undefined) return false
   return scope({ name: "refactor", access: strayAccess(p.strays) }, async () => {
-    await refactorLap(p, guardOf(p, head()))
+    await refactorLap(p, guardOf(p, head()), phase("refactor"))
     return true
   })
 }
@@ -342,9 +375,10 @@ export const reviewedRefactor = async (
         "gtd land: refactor-feedback: the review feedback changed files but wrote no .gtd/REFACTOR.md — a refactor cannot act on it; revert the change, or `gtd abandon` and restart",
       dropped: t.refactorDroppedRefusal,
     }
+    const refactor = phase("refactor")
     let collected: string | undefined
     for (;;) {
-      await refactorLap(p, guard, collected)
+      await refactorLap(p, guard, refactor, collected)
       // A person's edit at an escalation rest is never refused, as in the lap.
       const outcome = await buildTail(entry, {
         green: true,