@pmelab/gtd 52.0.0 → 53.0.0

package/src/wire/BeatStatus.ts

@@ -5,7 +5,6 @@ import type {
   RenderedDemandSource,
   StateMode,
   StateName,
-  StepContextLimit,
 } from "./types.js"
 
 /** One pending change — `gtd next --json`'s `changes` entries. */
@@ -33,7 +32,6 @@ export interface BeatStatus {
   readonly initial: boolean
   readonly model: string | undefined
   readonly system: string | undefined
-  readonly context: StepContextLimit | undefined
   readonly log: string
   readonly state: StateName
   readonly actor: Actor
@@ -76,7 +74,6 @@ export const statusOf = (input: {
     initial,
     model: rendered.model,
     system: rendered.system !== undefined && rendered.system !== "" ? rendered.system : undefined,
-    context: rendered.context,
     log,
     state: rendered.state,
     actor: rendered.actor,

package/src/wire/WireSchema.test.ts

@@ -9,8 +9,6 @@ import {
   landFields,
   renderBeatJson,
   renderLandJson,
-  renderSlicesJson,
-  slicesDocument,
   statusOf,
   WIRE_SCHEMA,
   type BeatKind,
@@ -118,9 +116,6 @@ const documents: Readonly<Record<string, string>> = {
     }),
   ),
   "judge.json": JUDGE,
-  "slices.json": renderSlicesJson(
-    slicesDocument([{ name: "build", base: "a".repeat(40), tip: "b".repeat(40), closed: true }]),
-  ),
 }
 
 describe(`wire schema ${WIRE_SCHEMA}`, () => {
@@ -144,19 +139,6 @@ describe(`wire schema ${WIRE_SCHEMA}`, () => {
     }
   })
 
-  describe("slicesDocument", () => {
-    it("stamps WIRE_SCHEMA and drops any field beyond the four", () => {
-      const doc = slicesDocument([
-        { name: "n", base: "b", tip: "t", closed: false, extra: 1 } as never,
-      ])
-      expect(doc).toEqual({
-        schema: WIRE_SCHEMA,
-        slices: [{ name: "n", base: "b", tip: "t", closed: false }],
-      })
-      expect(Object.keys(doc.slices[0]!)).toEqual(["name", "base", "tip", "closed"])
-    })
-  })
-
   describe("the shape check", () => {
     const land = JSON.parse(documents["land.json"]!) as Record<string, unknown>
     const { subject, ...rest } = land

package/src/wire/index.ts

@@ -10,5 +10,3 @@ export * from "./Judge.js"
 export { selectPath } from "./Select.js"
 export { resolveSession } from "./Sessions.js"
 export { globMatches } from "./Glob.js"
-export * from "./Slices.js"
-export * from "./ContextLimit.js"

package/src/wire/types.ts

@@ -38,12 +38,6 @@ export interface ApprovalEntry {
   readonly commit: string
 }
 
-/** The context-limit shares a step sets; a driver fills an absent one from its defaults. */
-export interface StepContextLimit {
-  readonly soft?: number
-  readonly hard?: number
-}
-
 export interface RenderedDemandSource {
   readonly state: StateName
   readonly actor: Actor
@@ -57,5 +51,4 @@ export interface RenderedDemandSource {
   readonly judge?: string
   readonly skills?: readonly string[]
   readonly access?: StepAccess
-  readonly context?: StepContextLimit
 }

package/src/workflow/Workflow.ts

@@ -1,12 +1,5 @@
 import type { WorkflowBase, Flow, ScopeAccess, Summary } from "../flows/index.js"
-import type {
-  Actor,
-  ContentKind,
-  StateMode,
-  StateName,
-  StepAccess,
-  StepContextLimit,
-} from "../wire/index.js"
+import type { Actor, ContentKind, StateMode, StateName, StepAccess } from "../wire/index.js"
 
 export type { Actor, ContentKind, StateMode, StateName }
 
@@ -51,7 +44,6 @@ export interface StepDef {
   readonly approve?: boolean
   readonly skills?: readonly string[]
   readonly access?: StepAccess
-  readonly context?: StepContextLimit
 }
 
 /**

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/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,
@@ -132,17 +139,9 @@ describe("statedCriteria", () => {
 describe("criterionIds", () => {
   const requirements = "## Acceptance Criteria\n\n- AC-1: a\n- AC-2: b\n- AC-4: added\n- unnamed\n"
 
-  it("lists every ID'd criterion of an unsliced change", () => {
+  it("lists every ID'd criterion", () => {
     expect(criterionIds(requirements)).toEqual(["AC-1", "AC-2", "AC-4"])
   })
-
-  it("keeps `only` to the IDs the file still lists", () => {
-    expect(criterionIds(requirements, { only: ["AC-1", "AC-3"] })).toEqual(["AC-1"])
-  })
-
-  it("gives `except` every other ID, one added since included", () => {
-    expect(criterionIds(requirements, { except: ["AC-1", "AC-3"] })).toEqual(["AC-2", "AC-4"])
-  })
 })
 
 describe("handsOnIds", () => {
@@ -152,11 +151,6 @@ describe("handsOnIds", () => {
   it("leaves out every criterion tagged (no hands-on)", () => {
     expect(handsOnIds(requirements)).toEqual(["AC-1", "AC-3"])
   })
-
-  it("keeps to the slice", () => {
-    expect(handsOnIds(requirements, { only: ["AC-2", "AC-3"] })).toEqual(["AC-3"])
-    expect(handsOnIds(requirements, { only: ["AC-2", "AC-4"] })).toEqual([])
-  })
 })
 
 describe("unstableIds", () => {
@@ -177,3 +171,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 {
@@ -77,37 +79,16 @@ export const criteriaOf = (text: string): readonly Criterion[] | undefined =>
     return id === null ? { id: "", text: item } : criterion(id)
   })
 
-/**
- * Which criteria one slice builds, resolved against the file whenever read:
- * `only` drops an ID a steer deleted, `except` (the last slice) takes one a
- * steer added.
- */
-export interface CriteriaSlice {
-  readonly only?: readonly string[]
-  readonly except?: readonly string[]
-}
-
-/** The ID'd criteria of `text`, only `slice`'s when given. */
-export const criterionIds = (text: string, slice?: CriteriaSlice): string[] =>
-  (criteriaOf(text) ?? [])
-    .map((c) => c.id)
-    .filter(
-      (id) =>
-        id !== "" &&
-        (slice?.only === undefined || slice.only.includes(id)) &&
-        !(slice?.except ?? []).includes(id),
-    )
+/** The ID'd criteria of `text`. */
+export const criterionIds = (text: string): string[] =>
+  (criteriaOf(text) ?? []).map((c) => c.id).filter((id) => id !== "")
 
-/** The ID'd criteria of `text` (`slice`'s when given) a person can try by hand: none tagged `(no hands-on)`. */
-export const handsOnIds = (text: string, slice?: CriteriaSlice): string[] => {
+/** The ID'd criteria of `text` a person can try by hand: none tagged `(no hands-on)`. */
+export const handsOnIds = (text: string): string[] => {
   const tagged = (criteriaOf(text) ?? []).filter((c) => c.noHandsOn).map((c) => c.id)
-  return criterionIds(text, slice).filter((id) => !tagged.includes(id))
+  return criterionIds(text).filter((id) => !tagged.includes(id))
 }
 
-/** `slice`'s IDs in `.gtd/REQUIREMENTS.md` as it is now; `undefined` for an unsliced change. */
-export const sliceIds = (slice: CriteriaSlice | undefined): string[] | undefined =>
-  slice === undefined ? undefined : criterionIds(read(REQUIREMENTS) ?? "", slice)
-
 /** Items numbered `AC-1`…, unless every one already carries its own distinct ID. */
 const numbered = (items: readonly string[]): Criterion[] => {
   const ids = items.map((item) => ID.exec(item))
@@ -165,6 +146,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 +240,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,16 +268,6 @@ export const skipDesign = (stated: StatedCriteria | undefined): Promise<boolean>
           label: "Recording the stated acceptance criteria",
           file: REQUIREMENTS,
         })
+        await impact()
         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/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) => {