@pmelab/gtd 36.0.0 → 37.0.0

package/src/workflows/feature/refactor-absorbs.feature

@@ -4,9 +4,9 @@ Feature: a refactor that carried the whole feature still gets a quality lap over
 
   With GTD_FLAG_RISK_TIER off, a refactor-first
   refactor can land everything the requirements ask for. The feature slice's
-  implement turn then has nothing to author: its empty turn completes the
-  step, and with no code changed since the refactor the feature slice's
-  quality lap covers the whole change, refactor included.
+  implement turn then has only the naive pass's acceptance tests to carry
+  over, and with no code but tests changed since the refactor the feature
+  slice's quality lap covers the whole change, refactor included.
 
   Background:
     Given the shipped workflows, as gtd install scaffolds them
@@ -42,7 +42,7 @@ Feature: a refactor that carried the whole feature still gets a quality lap over
       """
     And step "design.gate.answer" changes nothing
 
-  Scenario: an empty implement turn after a refactor that did it all reaches the quality lap and idle
+  Scenario: a tests-only implement turn after a refactor that did it all reaches the quality lap and idle
     Given step "seam.check" changes nothing
     And step "seam.naive" writes "src/acceptance.test.ts" with:
       """
@@ -57,6 +57,10 @@ Feature: a refactor that carried the whole feature still gets a quality lap over
       """
       [{"id":"shape","answer":"refactor-first","p":0.9}]
       """
+    And step "seam.note" writes ".gtd/REFACTOR-NOTE.md" with:
+      """
+      Seam: the existing code the strays touch.
+      """
     And step "refactor.deriving" runs its script
     And step "refactor.building" writes "src/calc.ts" with:
       """
@@ -91,7 +95,10 @@ Feature: a refactor that carried the whole feature still gets a quality lap over
       - [x] ./src/calc.ts#1-2
         subtract next to add
       """
-    And step "implement.building" changes nothing
+    And step "implement.building" writes "src/acceptance.test.ts" with:
+      """
+      it("[AC-1] holds", () => {})
+      """
     And step "implement.health.check" changes nothing
     And step "implement.closing" runs its script
     And judge step "implement.coverage" answers:

package/src/workflows/feature/refactor-first.feature

@@ -56,6 +56,10 @@ Feature: a refactor-first judgment walks one fixed path to idle
       """
       [{"id":"shape","answer":"refactor-first","p":0.9}]
       """
+    And step "seam.note" writes ".gtd/REFACTOR-NOTE.md" with:
+      """
+      Seam: the existing code the strays touch.
+      """
     And step "refactor.deriving" runs its script
     When the process is driven
     Then the process rests at "refactor.building"
@@ -106,6 +110,10 @@ Feature: a refactor-first judgment walks one fixed path to idle
       export const add = (a: number, b: number) => op(a, b, 1)
       export const subtract = (a: number, b: number) => op(a, b, -1)
       """
+    And step "implement.building" writes "src/acceptance.test.ts" with:
+      """
+      it("[AC-1] holds", () => {})
+      """
     And step "implement.health.check" changes nothing
     And step "implement.closing" runs its script
     And judge step "implement.coverage" answers:
@@ -125,7 +133,8 @@ Feature: a refactor-first judgment walks one fixed path to idle
       gtd(human): design.gate.answer → seam.naive
       gtd(agent): seam.naive → seam.check
       gtd(check): seam.check → seam.judge
-      gtd(judge): seam.judge → refactor.deriving
+      gtd(judge): seam.judge → seam.note
+      gtd(agent): seam.note → refactor.deriving
       gtd(check): refactor.deriving → refactor.building
       gtd(agent): refactor.building → refactor.health.check
       gtd(check): refactor.health.check → refactor.closing
@@ -140,7 +149,7 @@ Feature: a refactor-first judgment walks one fixed path to idle
       """
     And the commit "gtd(human): idle → unwind" has a body containing "Gtd-Var: flag_risk_tier=0"
     And the commit "gtd(agent): seam.naive → seam.check" has a body containing "Gtd-Kept:"
-    And the commit "gtd(judge): seam.judge → refactor.deriving" has a body containing "\"answer\":\"refactor-first\""
+    And the commit "gtd(judge): seam.judge → seam.note" has a body containing "\"answer\":\"refactor-first\""
     And no commit body contains "Gtd-Approved:"
     And the output lines of gtd "slices" start with:
       """

package/src/workflows/feature/refactor-lens-models.feature

@@ -50,6 +50,10 @@ Feature: the refactor review's lenses take their model hints from refactorQualit
       """
       [{"id":"shape","answer":"refactor-first","p":0.9}]
       """
+    And step "seam.note" writes ".gtd/REFACTOR-NOTE.md" with:
+      """
+      Seam: the existing code the strays touch.
+      """
     And step "refactor.deriving" runs its script
     And step "refactor.building" writes "src/calc.ts" with:
       """

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

@@ -0,0 +1,269 @@
+# One SDLC path per file, so a changed path reds exactly one fixture — do not merge.
+@inmem
+Feature: refactor-first writes a refactor note, refactors on its own, then rebuilds
+
+  On a refactor-first judgment the naive pass is never applied. `seam.note`
+  reads the whole naive diff and writes `.gtd/REFACTOR-NOTE.md`; the refactor
+  lands on its own with the existing suite green; the rebuild re-implements the
+  change on the refactored base and lands only once it carries the naive pass's
+  acceptance tests and the suite is green. The note reaches both turns.
+
+  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
+
+      subtract(a, b) returns the difference.
+      """
+    And step "unwind" changes nothing
+    And step "start-gate.check" changes nothing
+    And step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+      """
+      # Requirements
+
+      ## Concerns
+
+      ### Subtract
+
+      - `subtract(a, b)` returns `a - b`.
+
+      ## Acceptance Criteria
+
+      - AC-1: subtract returns the difference.
+      """
+    And step "design.gate.answer" changes nothing
+    And step "seam.check" changes nothing
+    And step "seam.naive" writes "src/acceptance.test.ts" with:
+      """
+      it("[AC-1] subtracts", () => {})
+      """
+    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}]
+      """
+
+  Scenario: the refactor note reaches the refactor turn and the rebuild turn
+    When the process is driven
+    Then the process rests at "seam.note"
+    And the resting step's content contains "git show"
+    And the resting step's content contains ".gtd/REFACTOR-NOTE.md"
+    And "src/calc.ts" does not contain "subtract"
+
+    Given step "seam.note" writes ".gtd/REFACTOR-NOTE.md" with:
+      """
+      # Refactor note
+
+      Seam: route add through a shared `op(a, b, sign)` in src/calc.ts.
+      """
+    And step "refactor.deriving" runs its script
+    When the process is driven
+    Then the process rests at "refactor.building"
+    And ".gtd/REFACTOR.md" contains "## Refactor note"
+    And ".gtd/REFACTOR.md" contains "shared `op(a, b, sign)`"
+    And the resting step's content contains "Refactor note"
+
+    Given 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) => op(a, b, 1)
+      """
+    And step "refactor.health.check" changes nothing
+    And step "refactor.closing" runs its script
+    And step "refactor.build.review.reviewing" writes ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## calc
+
+      - [ ] ./src/calc.ts#1-2
+        add built on the shared op
+      """
+    And step "refactor.build.review.closing" runs its script
+    When the process is driven
+    Then the process rests at "refactor.build.review.await-review"
+
+    Given a file ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## calc
+
+      - [x] ./src/calc.ts#1-2
+        add built on the shared op
+      """
+    When gtd lands
+    And the process is driven
+    Then the process rests at "implement.building"
+    And the resting step's content contains "shared `op(a, b, sign)`"
+    And the resting step's content contains "acceptance tests for AC-1"
+
+  Scenario: a note turn that changes anything but the note is refused
+    Given step "seam.note" writes "src/calc.ts" with:
+      """
+      export const sub = 1
+      """
+    Then driving the process is refused with "refactor-note"
+
+  Scenario: the refactor lands on its own only with the existing suite green
+    Given 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) => op(a, b, -1)
+      """
+    And step "refactor.health.check" writes ".gtd/FEEDBACK.md" with:
+      """
+      FAIL add(1, 2) returned -1
+      """
+    When the process is driven
+    Then the process rests at "refactor.fix.suite.fixing"
+
+    Given step "refactor.fix.suite.fixing" 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)
+      """
+    And step "refactor.health.check" changes nothing
+    And step "refactor.closing" runs its script
+    And step "refactor.build.review.reviewing" writes ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## calc
+
+      - [ ] ./src/calc.ts#1-2
+        add built on the shared op
+      """
+    And step "refactor.build.review.closing" runs its script
+    When the process is driven
+    Then the process rests at "refactor.build.review.await-review"
+
+    Given a file ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## calc
+
+      - [x] ./src/calc.ts#1-2
+        add built on the shared op
+      """
+    When gtd lands
+    And the process is driven
+    Then the process rests at "implement.building"
+    And "src/calc.ts" contains "op(a, b, 1)"
+    And "src/calc.ts" does not contain "subtract"
+    And the output of gtd "slices" contains "refactor "
+
+  Scenario: the rebuild lands only once it carries the naive pass's acceptance tests, green
+    Given 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) => op(a, b, 1)
+      """
+    And step "refactor.health.check" changes nothing
+    And step "refactor.closing" runs its script
+    And step "refactor.build.review.reviewing" writes ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## calc
+
+      - [ ] ./src/calc.ts#1-2
+        add built on the shared op
+      """
+    And step "refactor.build.review.closing" runs its script
+    When the process is driven
+    Then the process rests at "refactor.build.review.await-review"
+
+    Given a file ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## calc
+
+      - [x] ./src/calc.ts#1-2
+        add built on the shared op
+      """
+    When gtd lands
+    And the process is driven
+    Then the process rests at "implement.building"
+
+    Given step "implement.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)
+      export const subtract = (a: number, b: number) => op(a, b, -1)
+      """
+    Then driving the process is refused with "rebuild-acceptance"
+
+    Given step "implement.building" writes "src/acceptance.test.ts" with:
+      """
+      it("[AC-1] subtracts", () => {})
+      """
+    And step "implement.health.check" changes nothing
+    And step "implement.closing" runs its script
+    And judge step "implement.coverage" answers:
+      """
+      [{"id":"AC-1","answer":"yes","p":0.9}]
+      """
+    When the process is driven
+    Then the process rests at "idle"
+    And "src/calc.ts" contains "op(a, b, -1)"
+    And "src/acceptance.test.ts" contains "[AC-1]"
+    And ".gtd/REFACTOR-NOTE.md" does not exist
+    And the commit subjects end with:
+      """
+      gtd(judge): seam.judge → seam.note
+      gtd(agent): seam.note → refactor.deriving
+      gtd(check): refactor.deriving → refactor.building
+      gtd(agent): refactor.building → refactor.health.check
+      gtd(check): refactor.health.check → refactor.closing
+      gtd(check): refactor.closing → refactor.build.review.reviewing
+      gtd(agent): refactor.build.review.reviewing → refactor.build.review.await-review
+      gtd(human): refactor.build.review.await-review → refactor.build.review.closing
+      gtd(check): refactor.build.review.closing → implement.building
+      gtd(agent): implement.building → implement.health.check
+      gtd(check): implement.health.check → implement.coverage
+      gtd(judge): implement.coverage → implement.closing
+      gtd(check): implement.closing → idle
+      """
+    And the output lines of gtd "slices" start with:
+      """
+      refactor
+      feature
+      """

package/src/workflows/feature/refactor-review.feature

@@ -66,6 +66,10 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
       """
       [{"id":"shape","answer":"refactor-first","p":0.9}]
       """
+    And step "seam.note" writes ".gtd/REFACTOR-NOTE.md" with:
+      """
+      Seam: the existing code the strays touch.
+      """
     And step "refactor.deriving" runs its script
     And step "refactor.building" writes "src/calc.ts" with:
       """
@@ -155,6 +159,10 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
       """
       [{"id":"shape","answer":"refactor-first","p":0.9}]
       """
+    And step "seam.note" writes ".gtd/REFACTOR-NOTE.md" with:
+      """
+      Seam: the existing code the strays touch.
+      """
     And step "refactor.deriving" runs its script
     And step "refactor.building" writes "src/calc.ts" with:
       """
@@ -243,6 +251,10 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
         """
         [{"id":"shape","answer":"refactor-first","p":0.9}]
         """
+      And step "seam.note" writes ".gtd/REFACTOR-NOTE.md" with:
+        """
+        Seam: the existing code the strays touch.
+        """
       And step "refactor.deriving" runs its script
       And step "refactor.building" writes "src/calc.ts" with:
         """
@@ -345,6 +357,10 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
         export const add = (a: number, b: number) => op(a, b, 1)
         export const subtract = (a: number, b: number) => op(a, b, -1)
         """
+      And step "implement.building" writes "src/acceptance.test.ts" with:
+        """
+        it("[AC-1] holds", () => {})
+        """
       And step "implement.health.check" changes nothing
       And step "implement.closing" runs its script
       And judge step "implement.coverage" answers:
@@ -638,6 +654,10 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
         export const add = (a: number, b: number) => op(a, b, 1)
         export const subtract = (a: number, b: number) => op(a, b, -1)
         """
+      And step "implement.building" writes "src/acceptance.test.ts" with:
+        """
+        it("[AC-1] holds", () => {})
+        """
       And step "implement.health.check" changes nothing
       And step "implement.closing" runs its script
       And judge step "implement.coverage" answers:
@@ -717,6 +737,10 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
         export const add = (a: number, b: number) => op(a, b, 1)
         export const subtract = (a: number, b: number) => op(a, b, -1)
         """
+      And step "implement.building" writes "src/acceptance.test.ts" with:
+        """
+        it("[AC-1] holds", () => {})
+        """
       And step "implement.health.check" changes nothing
       And step "implement.closing" runs its script
       And judge step "implement.coverage" answers:
@@ -983,6 +1007,10 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
         export const add = (a: number, b: number) => op(a, b, 1)
         export const subtract = (a: number, b: number) => op(a, b, -1)
         """
+      And step "implement.building" writes "src/acceptance.test.ts" with:
+        """
+        it("[AC-1] holds", () => {})
+        """
       And step "implement.health.check" changes nothing
       And step "implement.closing" runs its script
       And judge step "implement.coverage" answers:
@@ -1066,6 +1094,10 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
         export const add = (a: number, b: number) => op(a, b, 1)
         export const subtract = (a: number, b: number) => op(a, b, -1)
         """
+      And step "implement.building" writes "src/acceptance.test.ts" with:
+        """
+        it("[AC-1] holds", () => {})
+        """
       And step "implement.health.check" changes nothing
       And step "implement.closing" runs its script
       And judge step "implement.coverage" answers:
@@ -1212,6 +1244,10 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
         """
         [{"id":"shape","answer":"refactor-first","p":0.9}]
         """
+      And step "seam.note" writes ".gtd/REFACTOR-NOTE.md" with:
+        """
+        Seam: the existing code the strays touch.
+        """
       And step "refactor.deriving" runs its script
       And step "refactor.building" writes "src/calc.ts" with:
         """
@@ -1236,7 +1272,7 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
     Scenario: each slice's quality lap reviews from that slice's base
       When the process is driven
       Then the process rests at "refactor.build.quality.correctness.reviewing"
-      And the resting step's content contains the hash of the commit "gtd(judge): seam.judge → refactor.deriving"
+      And the resting step's content contains the hash of the commit "gtd(agent): seam.note → refactor.deriving"
       Given step "refactor.build.quality.correctness.reviewing" changes nothing
       And step "implement.building" writes "src/calc.ts" with:
         """
@@ -1244,6 +1280,10 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
         export const add = (a: number, b: number) => op(a, b, 1)
         export const subtract = (a: number, b: number) => op(a, b, -1)
         """
+      And step "implement.building" writes "src/acceptance.test.ts" with:
+        """
+        it("[AC-1] holds", () => {})
+        """
       And step "implement.health.check" changes nothing
       And step "implement.closing" runs its script
       And judge step "implement.coverage" answers:
@@ -1318,6 +1358,10 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
         """
         [{"id":"shape","answer":"refactor-first","p":0.9}]
         """
+      And step "seam.note" writes ".gtd/REFACTOR-NOTE.md" with:
+        """
+        Seam: the existing code the strays touch.
+        """
 
     Scenario: a test-file stray is dropped from the derived refactor package
       Given step "seam.check" changes nothing

package/src/workflows/feature/refactor.ts

@@ -27,6 +27,8 @@ export const REFACTOR_PACKAGE = REFACTOR
 export interface RefactorOptions {
   /** Blank counts as absent: `kept()` reports `""` while the keeping turn is pending. */
   readonly reference?: string | undefined
+  /** The refactor note `seam.note` wrote; rides the package as `## Refactor note`. */
+  readonly note?: string | undefined
 }
 
 const isCode = (path: string): boolean => path !== ".gtd" && !path.startsWith(".gtd/")
@@ -203,7 +205,7 @@ const packageLines = (
   "",
 ]
 
-// Nested under `## Review feedback`, so every heading of the collected text drops a level.
+// Nested under a `##` section (review feedback, the refactor note), so every heading drops a level.
 const demoteHeadings = (text: string): string[] => {
   const marked = markFenced(text.trimEnd())
   const lines = marked.map((m) => m.line)
@@ -230,6 +232,7 @@ interface Plan {
   readonly pattern: string
   readonly strays: readonly string[]
   readonly reference: string | undefined
+  readonly note: string | undefined
 }
 
 /** Undefined for every shape that is not a readable `refactor-first`; throws on a bad flag pattern. */
@@ -245,7 +248,8 @@ const plan = (shape: DiffShapeResult, options: RefactorOptions): Plan | undefine
       `gtd: refactorFlagPattern (${pattern}) produces a zero-length match in:\n${listPaths(zeroLength)}`,
     )
   const reference = options.reference?.trim() ? options.reference : undefined
-  return { pattern, strays, reference }
+  const note = options.note?.trim() ? options.note : undefined
+  return { pattern, strays, reference, note }
 }
 
 // The in-memory `strays`, never the package file: a hand edit of its list changes nothing.
@@ -260,11 +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 { pattern, strays, reference } = p
+  const { pattern, strays, reference, note } = p
   await run(
     "deriving",
     deriveScript([
       ...packageLines(strays, pattern, reference),
+      ...(note === undefined ? [] : ["## Refactor note", "", ...demoteHeadings(note), ""]),
       ...(feedback === undefined
         ? []
         : ["## Review feedback", "", ...demoteHeadings(feedback), ""]),
@@ -279,6 +284,7 @@ const refactorLap = async (p: Plan, guard: Guard, feedback?: string): Promise<vo
       pattern,
       reference,
       feedback: feedback !== undefined,
+      note: note !== undefined,
     }),
     { label: "Refactoring", model: coder(), system: t.builderSystem() },
   )