@pmelab/gtd 52.0.0 → 52.1.0

package/src/workflows/feature/acceptance-criteria.feature

@@ -30,11 +30,15 @@ Feature: acceptance criteria carry stable IDs, and a sketch that states clear on
         greeting says "Helo"; make it "Hello".
         """
 
-    Scenario: triage writes ID'd criteria that reach the naive pass through the design gate
+    Scenario: [AC-6] triage writes ID'd criteria that reach the naive pass through the design gate
       Given step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
         """
         # Requirements
 
+        ## Impact
+
+        - the greeting module
+
         ## Acceptance Criteria
 
         - AC-1: `greeting` reads "Hello, world".
@@ -45,6 +49,7 @@ Feature: acceptance criteria carry stable IDs, and a sketch that states clear on
       Then the process rests at "seam.naive"
       And ".gtd/REQUIREMENTS.md" contains "- AC-1: `greeting` reads \"Hello, world\"."
       And ".gtd/REQUIREMENTS.md" contains "- AC-2: no other export changes."
+      And the resting step's content contains "maps where the change lands"
       And the resting step's content contains "Acceptance Criteria"
       And the commit subjects end with:
         """
@@ -58,6 +63,10 @@ Feature: acceptance criteria carry stable IDs, and a sketch that states clear on
         """
         # Requirements
 
+        ## Impact
+
+        - the greeting module
+
         ## Acceptance Criteria
 
         - `greeting` reads "Hello, world".
@@ -69,6 +78,10 @@ Feature: acceptance criteria carry stable IDs, and a sketch that states clear on
         """
         # Requirements
 
+        ## Impact
+
+        - the greeting module
+
         ## Acceptance Criteria
 
         - AC-1: `greeting` reads "Hello, world".
@@ -81,6 +94,10 @@ Feature: acceptance criteria carry stable IDs, and a sketch that states clear on
         """
         # Requirements
 
+        ## Impact
+
+        - the greeting module
+
         ## Acceptance Criteria
 
         - AC-1: `greeting` reads "Hello, world".
@@ -110,15 +127,114 @@ Feature: acceptance criteria carry stable IDs, and a sketch that states clear on
         """
         # Requirements
 
+        ## Impact
+
+        - the greeting module
+
+        ## Acceptance Criteria
+
+        - AC-1: `greeting` reads "Hi".
+        """
+      Then driving the process is refused with "criteria-frozen"
+
+  Rule: impact
+
+    Scenario: [AC-1] a triage turn with no Impact section is refused, naming it
+      Given a file "TODO.md" with:
+        """
+        # Fix the typo
+
+        greeting says "Helo"; make it "Hello".
+        """
+      And step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        ## Acceptance Criteria
+
+        - AC-1: `greeting` reads "Hello, world".
+        """
+      Then driving the process is refused with "impact: .gtd/REQUIREMENTS.md has no \"## Impact\" section"
+
+    Scenario: [AC-9] a design.impact turn that changes the criteria is refused
+      Given a file "TODO.md" with:
+        """
+        # Fix the typo
+
+        ## Acceptance criteria
+
+        - `greeting` reads "Hello, world".
+        """
+      And judge step "design.clear" answers:
+        """
+        [{"id":"clear","answer":"yes","p":0.9}]
+        """
+      And step "design.normalise" runs its script
+      And step "design.impact" writes ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        ## Impact
+
+        - the greeting module
+
         ## Acceptance Criteria
 
         - AC-1: `greeting` reads "Hi".
         """
       Then driving the process is refused with "criteria-frozen"
 
+    Scenario: [AC-9] a design.impact turn that adds no Impact section is refused
+      Given a file "TODO.md" with:
+        """
+        # Fix the typo
+
+        ## Acceptance criteria
+
+        - `greeting` reads "Hello, world".
+        """
+      And judge step "design.clear" answers:
+        """
+        [{"id":"clear","answer":"yes","p":0.9}]
+        """
+      And step "design.normalise" runs its script
+      And step "design.impact" appends to ".gtd/REQUIREMENTS.md":
+        """
+        Touches the greeting module.
+        """
+      Then driving the process is refused with "impact: .gtd/REQUIREMENTS.md has no \"## Impact\" section"
+
+    Scenario: [AC-9] a design.impact turn that drops the sketch pointer is refused
+      Given a file "TODO.md" with:
+        """
+        # Fix the typo
+
+        ## Acceptance criteria
+
+        - `greeting` reads "Hello, world".
+        """
+      And judge step "design.clear" answers:
+        """
+        [{"id":"clear","answer":"yes","p":0.9}]
+        """
+      And step "design.normalise" runs its script
+      And step "design.impact" writes ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        ## Impact
+
+        - the greeting module
+
+        ## Acceptance Criteria
+
+        - AC-1: `greeting` reads "Hello, world".
+        """
+      Then driving the process is refused with "impact-only"
+
   Rule: the skip path
 
-    Scenario: clear stated criteria are normalised into ID'd requirements with no triage and no design gate
+    Scenario: [AC-9] [AC-10] clear stated criteria are normalised into ID'd requirements with no triage and no design gate
       Given a file "TODO.md" with:
         """
         # Fix the typo
@@ -133,18 +249,52 @@ Feature: acceptance criteria carry stable IDs, and a sketch that states clear on
         [{"id":"clear","answer":"yes","p":0.9}]
         """
       And step "design.normalise" runs its script
+      And step "design.impact" appends to ".gtd/REQUIREMENTS.md":
+        """
+        ## Impact
+
+        - the greeting module
+        """
       When the process is driven
       Then the process rests at "seam.naive"
       And ".gtd/REQUIREMENTS.md" contains "- AC-1: `greeting` reads \"Hello, world\"."
       And ".gtd/REQUIREMENTS.md" contains "- AC-2: no other export changes."
+      And ".gtd/REQUIREMENTS.md" contains "Stated in `TODO.md` by the sketch"
+      And the resting step's content contains "maps where the change lands"
       And the commit subjects end with:
         """
         gtd(human): idle → unwind
         gtd(check): unwind → start-gate.check
         gtd(check): start-gate.check → design.clear
         gtd(judge): design.clear → design.normalise
-        gtd(check): design.normalise → seam.naive
+        gtd(check): design.normalise → design.impact
+        gtd(agent): design.impact → seam.naive
+        """
+
+    Scenario: a fast-path process recorded before design.impact existed fails replay
+      Given a file "TODO.md" with:
+        """
+        # Fix the typo
+
+        ## Acceptance criteria
+
+        - `greeting` reads "Hello, world".
+        """
+      And judge step "design.clear" answers:
+        """
+        [{"id":"clear","answer":"yes","p":0.9}]
+        """
+      And step "design.normalise" runs its script
+      When the process is driven
+      Then the process rests at "design.impact"
+      Given the working tree is committed with the message:
+        """
+        gtd(agent): seam.naive → seam.check
+
+        Gtd-Step: seam.naive#1
+        Gtd-Format: 1
         """
+      Then driving the process is refused with "the workflow changed under this process"
 
     Scenario: IDs the sketch already gave its criteria are kept
       Given a file "TODO.md" with:
@@ -159,6 +309,12 @@ Feature: acceptance criteria carry stable IDs, and a sketch that states clear on
         [{"id":"clear","answer":"yes","p":0.9}]
         """
       And step "design.normalise" runs its script
+      And step "design.impact" appends to ".gtd/REQUIREMENTS.md":
+        """
+        ## Impact
+
+        - the greeting module
+        """
       When the process is driven
       Then the process rests at "seam.naive"
       And ".gtd/REQUIREMENTS.md" contains "- AC-3: `greeting` reads \"Hello, world\"."

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

@@ -26,6 +26,10 @@ Feature: past its continuation cap a phase rests for a person
       """
       # Requirements
 
+      ## Impact
+
+      - the greeting module
+
       ## Acceptance Criteria
 
       - AC-1: `subtract(5, 3)` returns 2.

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

@@ -31,6 +31,10 @@ Feature: a rebuild stopped at its context limit is continued on the branch
       """
       # Requirements
 
+      ## Impact
+
+      - the greeting module
+
       ## Acceptance Criteria
 
       - AC-1: `subtract(5, 3)` returns 2.

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

@@ -30,6 +30,10 @@ Feature: a continuation stays inside its coarse slice
       """
       # Requirements
 
+      ## Impact
+
+      - the greeting module
+
       ## Acceptance Criteria
 
       - AC-1: subtract(a, b) returns a - b.

package/src/workflows/feature/continuation.feature

@@ -29,6 +29,10 @@ Feature: a turn stopped at its context limit is snapshotted and continued
       """
       # Requirements
 
+      ## Impact
+
+      - the greeting module
+
       ## Acceptance Criteria
 
       - AC-1: `subtract(5, 3)` returns 2.

package/src/workflows/feature/criteria.test.ts

@@ -1,6 +1,13 @@
 import { describe, expect, it } from "vitest"
 import type { Change } from "../../flows/index.js"
-import { criteriaOf, criterionIds, handsOnIds, statedCriteria, unstableIds } from "./criteria.js"
+import {
+  criteriaOf,
+  criterionIds,
+  handsOnIds,
+  hasImpact,
+  statedCriteria,
+  unstableIds,
+} from "./criteria.js"
 
 const added = (path: string, after: string): Change => ({
   path,
@@ -177,3 +184,17 @@ describe("unstableIds", () => {
     expect(unstableIds(["AC-0", "AC-2"], ids)).toMatch(/^numbers AC-0, AC-2 at or below AC-3/)
   })
 })
+
+describe("hasImpact", () => {
+  it.each([
+    ["a level-2 heading", "# R\n\n## Impact\n\nx\n", true],
+    ["a mixed-case heading", "## impact\n", true],
+    ["a level-3 heading", "### Impact\n", false],
+    ["a level-1 heading", "# Impact\n", false],
+    ["a longer heading", "## Impactful\n", false],
+    ["a fenced heading", "```md\n## Impact\n```\n", false],
+    ["no heading", "# R\n\nImpact\n", false],
+  ])("%s", (_name, text, expected) => {
+    expect(hasImpact(text)).toBe(expected)
+  })
+})

package/src/workflows/feature/criteria.ts

@@ -1,15 +1,17 @@
 import {
   answered,
   changes,
+  head,
   judge,
   read,
   refuse,
+  requireProgress,
   run,
   scope,
   type Change,
 } from "../../flows/index.js"
 import { HEADING, ITEM, markFenced } from "../shared/fences.js"
-import { REQUIREMENTS } from "../shared/steps.js"
+import { planner, REQUIREMENTS } from "../shared/steps.js"
 import * as t from "../shared/text.js"
 
 export interface Criterion {
@@ -165,6 +167,54 @@ export const requireCriteria = (file: string): void => {
   )
 }
 
+const isImpactHeading = (h: RegExpExecArray | null): boolean =>
+  h !== null && h[1]!.length === 2 && /^impact$/i.test(h[2]!.trim())
+
+/** Whether `text` has an unfenced, level-2 `## Impact` heading. */
+export const hasImpact = (text: string): boolean =>
+  markFenced(text).some((l) => !l.fenced && isImpactHeading(HEADING.exec(l.line)))
+
+/** `text` without its `## Impact` section, whitespace collapsed. */
+const withoutImpact = (text: string): string => {
+  let inImpact = false
+  const kept = markFenced(text).filter((l) => {
+    const h = l.fenced ? null : HEADING.exec(l.line)
+    if (h !== null && h[1]!.length <= 2) inImpact = isImpactHeading(h)
+    return !inImpact
+  })
+  return kept
+    .map((l) => l.line)
+    .join(" ")
+    .replace(/\s+/g, " ")
+    .trim()
+}
+
+/**
+ * Refuse a turn that leaves `file` without a `## Impact` section. Only the
+ * pending turn (`head()` is `""`): a triage lap recorded before Impact existed
+ * replays without one, and refusing there would fail every in-flight process.
+ * A human's edit at a later gate is not checked — the human owns that file then.
+ */
+export const requireImpact = (file: string): void => {
+  if (head() !== "") return
+  const text = read(file)
+  if (text === undefined) return
+  if (hasImpact(text)) return
+  refuse(
+    `gtd land: impact: ${file} has no "## Impact" section — explore the codebase and add "## Impact" naming the units, public surfaces and surprises this change touches`,
+  )
+}
+
+/** Refuse a turn that changed `file` beyond its `## Impact` section. */
+export const requireImpactOnly = (file: string): void => {
+  const change = changes().get(file)
+  if (change === undefined) return
+  if (withoutImpact(change.before ?? "") === withoutImpact(change.after ?? "")) return
+  refuse(
+    `gtd land: impact-only: this turn may only add "## Impact" to ${file} — restore everything else`,
+  )
+}
+
 /** The IDs a review's feedback lap must respect. */
 export interface StableIds {
   /** Listed when the build closed: each may stay, reworded or not, or go. */
@@ -211,6 +261,20 @@ const clear = async (stated: StatedCriteria): Promise<boolean> => {
   return truncated.length === 0 && answered(answers.clear, "yes", CLEAR_MIN_P)
 }
 
+/** The fast path's impact-only turn: add `## Impact`, leave the criteria alone. */
+const impact = async (): Promise<void> => {
+  await t.agentWithSkills("impact", t.designImpactPrompt(), {
+    label: "Mapping the change's impact",
+    file: REQUIREMENTS,
+    model: planner(),
+    system: t.designSystem(),
+  })
+  requireProgress(REQUIREMENTS)
+  requireCriteriaFrozen(REQUIREMENTS)
+  requireImpact(REQUIREMENTS)
+  requireImpactOnly(REQUIREMENTS)
+}
+
 /**
  * The skip path: when the sketch stated clear, checkable criteria, write them
  * to `.gtd/REQUIREMENTS.md` as they are and resolve `true` — no triage, no
@@ -225,6 +289,7 @@ export const skipDesign = (stated: StatedCriteria | undefined): Promise<boolean>
           label: "Recording the stated acceptance criteria",
           file: REQUIREMENTS,
         })
+        await impact()
         return true
       })
 

package/src/workflows/feature/fast-path.feature

@@ -38,6 +38,10 @@ Feature: a trivial change takes the same few beats at either risk tier
 
       <tier> — one-line copy fix
 
+      ## Impact
+
+      - the greeting module
+
       ## Acceptance Criteria
 
       - AC-1: the change behaves as described.

package/src/workflows/feature/feature.test.ts

@@ -99,7 +99,7 @@ describe("afterTail feedback lap", () => {
       "build.review.collecting": (_, r) => {
         r.write(
           ".gtd/REQUIREMENTS.md",
-          "# Requirements\n\n- multiply\n\n## Acceptance Criteria\n\n- AC-1: done\n",
+          "# Requirements\n\n- multiply\n\n## Impact\n\n- the module\n\n## Acceptance Criteria\n\n- AC-1: done\n",
         )
         r.write(".gtd/REVIEW.md", `${review("also export multiply")}    - A: noted.\n`)
       },
@@ -115,7 +115,7 @@ describe("afterTail feedback lap", () => {
     "design.triage": (_: unknown, r: ReturnType<typeof testRepo>) =>
       r.write(
         ".gtd/REQUIREMENTS.md",
-        "# Requirements\n\n- multiply, designed\n\n## Acceptance Criteria\n\n- AC-1: done\n",
+        "# Requirements\n\n- multiply, designed\n\n## Impact\n\n- the module\n\n## Acceptance Criteria\n\n- AC-1: done\n",
       ),
     "design.gate.answer": () => undefined,
   }
@@ -214,7 +214,7 @@ describe("an in-flight 28.0.0 naive-pass process", () => {
       "design.triage": (_, r) =>
         r.write(
           ".gtd/REQUIREMENTS.md",
-          "# Requirements\n\n## Concerns\n\n### S\n\n- `s`\n\n## Acceptance Criteria\n\n- AC-1: done\n",
+          "# Requirements\n\n## Concerns\n\n### S\n\n- `s`\n\n## Impact\n\n- the module\n\n## Acceptance Criteria\n\n- AC-1: done\n",
         ),
       "design.gate.answer": () => undefined,
       "seam.naive": (_, r) => {
@@ -258,6 +258,7 @@ describe("an in-flight 28.0.0 naive-pass process", () => {
 })
 
 describe("an in-flight process from before the architecture path was removed", () => {
+  // No `## Impact`: no version before it wrote one, and replaying its triage must not refuse.
   const REQUIREMENTS =
     "# Requirements\n\n## Concerns\n\n### Subtract\n\n- `subtract`\n\n## Acceptance Criteria\n\n- AC-1: done\n"
 
@@ -321,7 +322,7 @@ describe("flagMode", () => {
       "design.triage": (_, r) =>
         r.write(
           ".gtd/REQUIREMENTS.md",
-          "# Requirements\n\n## Concerns\n\n### S\n\n- `s`\n\n## Acceptance Criteria\n\n- AC-1: done\n",
+          "# Requirements\n\n## Concerns\n\n### S\n\n- `s`\n\n## Impact\n\n- the module\n\n## Acceptance Criteria\n\n- AC-1: done\n",
         ),
       "design.gate.answer": () => undefined,
     })
@@ -342,7 +343,7 @@ describe("flagMode", () => {
       "design.triage": (_, r) =>
         r.write(
           ".gtd/REQUIREMENTS.md",
-          "# Requirements\n\n## Concerns\n\n### S\n\n- `s`\n\n## Acceptance Criteria\n\n- AC-1: done\n",
+          "# Requirements\n\n## Concerns\n\n### S\n\n- `s`\n\n## Impact\n\n- the module\n\n## Acceptance Criteria\n\n- AC-1: done\n",
         ),
       "design.gate.answer": () => undefined,
       "seam.naive": (_, r) => {

package/src/workflows/feature/flag-mode.feature

@@ -37,6 +37,10 @@ Feature: flag mode off lands the naive pass with no release flag, seam judge or
 
       - `subtract(a, b)` returns `a - b`.
 
+      ## Impact
+
+      - the greeting module
+
       ## Acceptance Criteria
 
       - AC-1: the change behaves as described.

package/src/workflows/feature/hands-on-skip.feature

@@ -39,6 +39,10 @@ Feature: the hands-on test tries only the criteria a person can observe
       """
       # Requirements
 
+      ## Impact
+
+      - the greeting module
+
       ## Acceptance Criteria
 
       - AC-1: subtract(a, b) returns a - b.
@@ -79,6 +83,10 @@ Feature: the hands-on test tries only the criteria a person can observe
       """
       # Requirements
 
+      ## Impact
+
+      - the greeting module
+
       ## Acceptance Criteria
 
       - AC-1: subtract(a, b) returns a - b.
@@ -114,6 +122,10 @@ Feature: the hands-on test tries only the criteria a person can observe
       """
       # Requirements
 
+      ## Impact
+
+      - the greeting module
+
       ## Acceptance Criteria
 
       - AC-1: subtract(a, b) returns a - b.
@@ -149,6 +161,10 @@ Feature: the hands-on test tries only the criteria a person can observe
       """
       # Requirements
 
+      ## Impact
+
+      - the greeting module
+
       ## Acceptance Criteria
 
       - AC-1: subtract(a, b) returns a - b.
@@ -176,6 +192,10 @@ Feature: the hands-on test tries only the criteria a person can observe
       """
       # Requirements
 
+      ## Impact
+
+      - the greeting module
+
       ## Acceptance Criteria
 
       - AC-1: subtract(a, b) returns a - b.
@@ -203,6 +223,10 @@ Feature: the hands-on test tries only the criteria a person can observe
       """
       # Requirements
 
+      ## Impact
+
+      - the greeting module
+
       ## Acceptance Criteria
 
       - AC-1: add is unchanged.
@@ -229,6 +253,10 @@ Feature: the hands-on test tries only the criteria a person can observe
       """
       # Requirements
 
+      ## Impact
+
+      - the greeting module
+
       ## Acceptance Criteria
 
       - AC-1 (no hands-on): the build prompt names subtract.
@@ -252,6 +280,10 @@ Feature: the hands-on test tries only the criteria a person can observe
       """
       # Requirements
 
+      ## Impact
+
+      - the greeting module
+
       ## Acceptance Criteria
 
       - AC-1: subtract(a, b) returns a - b.
@@ -315,6 +347,10 @@ Feature: the hands-on test tries only the criteria a person can observe
       """
       # Requirements
 
+      ## Impact
+
+      - the greeting module
+
       ## Acceptance Criteria
 
       - AC-1: subtract(a, b) returns a - b.
@@ -337,6 +373,10 @@ Feature: the hands-on test tries only the criteria a person can observe
       """
       # Requirements
 
+      ## Impact
+
+      - the greeting module
+
       ## Acceptance Criteria
 
       - AC-1 (no hands-on): subtract(a, b) returns a - b.

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

@@ -33,6 +33,10 @@ Feature: each quality lens runs on its own model hint
       """
       # Requirements
 
+      ## Impact
+
+      - the greeting module
+
       ## Acceptance Criteria
 
       - AC-1: `subtract(a, b)` returns `a - b`.

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

@@ -35,6 +35,10 @@ Feature: the quality lap's findings are triaged before the review
 
       - `subtract(a, b)` returns `a - b`.
 
+      ## Impact
+
+      - the greeting module
+
       ## Acceptance Criteria
 
       - AC-1: subtract(a, b) returns a - b.

package/src/workflows/feature/naive-acceptance.feature

@@ -28,6 +28,10 @@ Feature: a naive pass ends only when a test names every criterion and the suite
       """
       # Requirements
 
+      ## Impact
+
+      - the greeting module
+
       ## Acceptance Criteria
 
       - AC-1: `subtract(5, 3)` returns 2.

package/src/workflows/feature/one-step-land.feature

@@ -36,6 +36,10 @@ Feature: a naive pass the judge rules land is itself the implementation
 
       - greeting reads "Hello, world".
 
+      ## Impact
+
+      - the greeting module
+
       ## Acceptance Criteria
 
       - AC-1: the change behaves as described.

package/src/workflows/feature/planning.ts

@@ -8,7 +8,7 @@ import {
   scope,
 } from "../../flows/index.js"
 import { REQUIREMENTS } from "../shared/steps.js"
-import { requireCriteria } from "./criteria.js"
+import { requireCriteria, requireImpact } from "./criteria.js"
 import { answerProductQuestions, triage } from "./steps.js"
 
 /**
@@ -33,6 +33,7 @@ export const design = (base: string, guard?: () => void): Promise<void> =>
       requireProgress(REQUIREMENTS)
       requireReplies(REQUIREMENTS)
       requireCriteria(REQUIREMENTS)
+      requireImpact(REQUIREMENTS)
       guard?.()
     } while (await noteGate(REQUIREMENTS, answerProductQuestions))
   })

package/src/workflows/feature/prototype-rounds.feature

@@ -28,6 +28,10 @@ Feature: past its round cap the hands-on test rests at a person's gate
       """
       # Requirements
 
+      ## Impact
+
+      - the greeting module
+
       ## Acceptance Criteria
 
       - AC-1: subtract(a, b) returns a - b.