@pmelab/gtd 37.0.0 → 38.1.0

package/src/workflows/feature/slicing.feature

@@ -0,0 +1,225 @@
+@inmem
+Feature: a change with more criteria than the cap is built in coarse slices
+
+  After design, criteria within sliceMaxCriteria are one slice, built as
+  before. Above it design.slicing groups them in .gtd/SLICES.md, at most the
+  cap per slice, and each slice runs in order — naive pass, implement, quality
+  lap — from where the previous one landed, as slices feature-1, feature-2, …
+
+  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
+    And step "implement.applying" runs its script
+    And step "implement.health.check" changes nothing
+    And step "implement.closing" runs its script
+
+  Scenario: criteria within the cap are one unnumbered slice with no slicing turn
+    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.
+      """
+    And step "seam.naive" writes "src/calc.test.ts" with:
+      """
+      it("[AC-1] subtracts", () => {})
+      it("[AC-2] multiplies", () => {})
+      """
+    And step "seam.naive" is prompted with "Read `.gtd/REQUIREMENTS.md`"
+    And judge step "implement.coverage" answers:
+      """
+      [{"id":"AC-1","answer":"yes","p":0.9},{"id":"AC-2","answer":"yes","p":0.9}]
+      """
+    When the process is driven
+    Then the process rests at "idle"
+    And the commit subjects end with:
+      """
+      gtd(human): design.gate.answer → seam.naive
+      gtd(agent): seam.naive → seam.check
+      gtd(check): seam.check → implement.applying
+      gtd(check): implement.applying → 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:
+      """
+      feature
+      """
+    And the output of gtd "slices" does not contain "feature-"
+    And no commit body contains "This slice builds"
+
+  Scenario: criteria above the cap are sliced and built slice by slice
+    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" is prompted with "at most 2 per slice"
+    And step "design.slicing" writes ".gtd/SLICES.md" with:
+      """
+      # Slices
+
+      ## Subtract and divide
+
+      - AC-1
+      - AC-3
+
+      ## Multiply
+
+      - AC-2
+      """
+    And step "seam.naive", when prompted with "This slice builds AC-1, AC-3 only", writes "src/sub.test.ts" with:
+      """
+      it("[AC-1] subtracts", () => {})
+      it("[AC-3] divides", () => {})
+      """
+    And step "seam.naive", when prompted with "This slice builds AC-2 only", writes "src/mul.test.ts" with:
+      """
+      it("[AC-2] multiplies", () => {})
+      """
+    And judge step "implement.coverage", when its questions contain "AC-3", answers:
+      """
+      [{"id":"AC-1","answer":"yes","p":0.9},{"id":"AC-3","answer":"yes","p":0.9}]
+      """
+    And judge step "implement.coverage", when its questions contain "AC-2", answers:
+      """
+      [{"id":"AC-2","answer":"yes","p":0.9}]
+      """
+    When the process is driven
+    Then the process rests at "idle"
+    And the commit subjects end with:
+      """
+      gtd(agent): design.triage → design.gate.answer
+      gtd(human): design.gate.answer → design.slicing
+      gtd(agent): design.slicing → seam.naive
+      gtd(agent): seam.naive → seam.check
+      gtd(check): seam.check → implement.applying
+      gtd(check): implement.applying → implement.health.check
+      gtd(check): implement.health.check → implement.coverage
+      gtd(judge): implement.coverage → implement.closing
+      gtd(check): implement.closing → seam.naive
+      gtd(agent): seam.naive → seam.check
+      gtd(check): seam.check → implement.applying
+      gtd(check): implement.applying → 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:
+      """
+      feature-1
+      feature-2
+      """
+    And slice "feature-2" begins where slice "feature-1" ends
+    And "src/sub.test.ts" contains "[AC-3] divides"
+    And "src/mul.test.ts" contains "[AC-2] multiplies"
+    And ".gtd/REQUIREMENTS.md" does not exist
+    And ".gtd/SLICES.md" does not exist
+
+  Scenario: a slice over the cap is refused
+    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
+
+      ## Everything
+
+      - AC-1
+      - AC-2
+      - AC-3
+      """
+    Then driving the process is refused with "more than 2 criteria in: Everything"
+
+  Scenario: a criterion in no slice is refused
+    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
+
+      - AC-1
+
+      ## Multiply
+
+      - AC-2
+      """
+    Then driving the process is refused with "no slice for: AC-3"
+
+  Scenario: a slicing turn may not change the acceptance criteria
+    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/REQUIREMENTS.md" with:
+      """
+      # Requirements
+
+      ## Acceptance Criteria
+
+      - AC-1: subtract(a, b) returns a - b.
+      - AC-2: multiply(a, b) returns a * b.
+      """
+    And step "design.slicing" writes ".gtd/SLICES.md" with:
+      """
+      # Slices
+
+      ## Subtract
+
+      - AC-1
+
+      ## Multiply
+
+      - AC-2
+      """
+    Then driving the process is refused with "wrote outside its write access"

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

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest"
+import { sliceCriteria, slicesOf } from "./slicing.js"
+
+describe("slicesOf", () => {
+  it("reads each level-2 heading's ID'd items, in order", () => {
+    expect(
+      slicesOf("# Slices\n\n## Parse\n\n- AC-1: parses\n- AC-3\n\n## Print\n\n- AC-2 prints\n"),
+    ).toEqual([
+      { title: "Parse", ids: ["AC-1", "AC-3"] },
+      { title: "Print", ids: ["AC-2"] },
+    ])
+  })
+
+  it("keeps an item not led by an ID as an empty one, and skips fenced lines", () => {
+    expect(slicesOf("## One\n\n```md\n## Two\n- AC-9\n```\n- AC-10\n- see AC-1\n")).toEqual([
+      { title: "One", ids: ["AC-10", ""] },
+    ])
+  })
+
+  it("ends a slice at any other heading", () => {
+    expect(
+      slicesOf("## One\n\n- AC-1\n\n### Why\n\n- shares the lexer\n\n# Later\n\n- AC-5\n"),
+    ).toEqual([{ title: "One", ids: ["AC-1"] }])
+  })
+
+  it("reads no slice from a file without level-2 headings", () => {
+    expect(slicesOf("# Slices\n\n- AC-1\n")).toEqual([])
+  })
+})
+
+describe("sliceCriteria", () => {
+  const slices = [
+    { title: "A", ids: ["AC-1", "AC-3"] },
+    { title: "B", ids: ["AC-2"] },
+    { title: "C", ids: ["AC-4"] },
+  ]
+
+  it("keeps an earlier slice to its own IDs", () => {
+    expect(sliceCriteria(slices, 1)).toEqual({ only: ["AC-2"] })
+  })
+
+  it("gives the last slice every ID no earlier slice builds", () => {
+    expect(sliceCriteria(slices, 2)).toEqual({ except: ["AC-1", "AC-3", "AC-2"] })
+  })
+
+  it("leaves a single slice unsliced", () => {
+    expect(sliceCriteria([slices[0]!], 0)).toBeUndefined()
+  })
+})

package/src/workflows/feature/slicing.ts

@@ -0,0 +1,105 @@
+import { read, refuse, scope, vars } from "../../flows/index.js"
+import { HEADING, ITEM, markFenced } from "../shared/fences.js"
+import { planner, REQUIREMENTS, SLICES } from "../shared/steps.js"
+import * as t from "../shared/text.js"
+import { defaults } from "../shared/vars.js"
+import { criterionIds, type CriteriaSlice } from "./criteria.js"
+
+/** One slice of the change: the criterion IDs it builds, in the order `.gtd/SLICES.md` lists them. */
+export interface Slice {
+  readonly title: string
+  readonly ids: readonly string[]
+}
+
+const ID = /^(AC-\d+)(?![\w-])/
+
+/** The `sliceMaxCriteria` setting. Anything but a positive integer fails rather than guess a cap. */
+export const sliceCap = (): number => {
+  const value = vars.sliceMaxCriteria ?? defaults.sliceMaxCriteria!
+  if (!/^[1-9]\d*$/.test(value))
+    refuse(`gtd: sliceMaxCriteria must be a positive integer, got ${JSON.stringify(value)}`)
+  return Number(value)
+}
+
+/** Each `## ` heading of `text` with the list items under it; an item not led by an ID keeps an empty one. */
+export const slicesOf = (text: string): readonly Slice[] => {
+  const slices: { title: string; ids: string[] }[] = []
+  // Only items right under a `##` heading: another heading ends the slice.
+  let open = false
+  for (const { line, fenced } of markFenced(text)) {
+    if (fenced) continue
+    const heading = HEADING.exec(line)
+    if (heading !== null) {
+      open = heading[1] === "##"
+      if (open) slices.push({ title: heading[2]!, ids: [] })
+      continue
+    }
+    const item = ITEM.exec(line)
+    if (item !== null && open) slices.at(-1)!.ids.push(ID.exec(item[1]!)?.[1] ?? "")
+  }
+  return slices
+}
+
+const twice = (list: readonly string[]): string[] => [
+  ...new Set(list.filter((id, i) => list.indexOf(id) !== i)),
+]
+
+/** Why `slices` fail to put each of `ids` in exactly one slice of at most `cap`, or `undefined`. */
+const sliceFault = (
+  slices: readonly Slice[],
+  ids: readonly string[],
+  cap: number,
+): string | undefined => {
+  const listed = slices.flatMap((s) => s.ids)
+  if (slices.length === 0) return `no "## " slice`
+  const empty = slices.filter((s) => s.ids.length === 0).map((s) => s.title)
+  if (empty.length > 0) return `a slice with no criterion: ${empty.join(", ")}`
+  if (listed.includes("")) return "a list item not led by a criterion ID"
+  const over = slices.filter((s) => s.ids.length > cap).map((s) => s.title)
+  if (over.length > 0) return `more than ${cap} criteria in: ${over.join(", ")}`
+  const repeated = twice(listed)
+  if (repeated.length > 0) return `an ID in more than one slice: ${repeated.join(", ")}`
+  const unknown = listed.filter((id) => !ids.includes(id))
+  if (unknown.length > 0) return `an ID ${REQUIREMENTS} does not list: ${unknown.join(", ")}`
+  const missing = ids.filter((id) => !listed.includes(id))
+  if (missing.length > 0) return `no slice for: ${missing.join(", ")}`
+  return undefined
+}
+
+/** Refuse a turn whose `.gtd/SLICES.md` does not put each of `ids` in exactly one slice of at most `cap`. */
+export const requireSlices = (ids: readonly string[], cap: number): readonly Slice[] => {
+  const slices = slicesOf(read(SLICES) ?? "")
+  const why = sliceFault(slices, ids, cap)
+  if (why !== undefined)
+    refuse(
+      `gtd land: slices: ${SLICES} has ${why} — list each slice as a "## <title>" heading over "- AC-<n>" items, every criterion of ${REQUIREMENTS} in exactly one slice, at most ${cap} per slice`,
+    )
+  return slices
+}
+
+/**
+ * The slices to build, in order. Criteria within `sliceMaxCriteria` are one
+ * slice and no turn; above it `design.slicing` groups them.
+ */
+export const slicing = async (): Promise<readonly Slice[]> => {
+  const all = criterionIds(read(REQUIREMENTS) ?? "")
+  const cap = sliceCap()
+  if (all.length <= cap) return [{ title: "", ids: all }]
+  return scope("design", async () => {
+    await t.agentWithSkills("slicing", t.slicingPrompt(cap), {
+      label: "Slicing the change",
+      file: SLICES,
+      model: planner(),
+      system: t.designSystem(),
+    })
+    return requireSlices(all, cap)
+  })
+}
+
+/** Slice `i`'s criteria; `undefined` when `slices` is the one slice of an unsliced change. */
+export const sliceCriteria = (slices: readonly Slice[], i: number): CriteriaSlice | undefined =>
+  slices.length === 1
+    ? undefined
+    : i < slices.length - 1
+      ? { only: slices[i]!.ids }
+      : { except: slices.slice(0, -1).flatMap((s) => s.ids) }

package/src/workflows/index.ts

@@ -25,6 +25,7 @@ export * from "./feature/criteria.js"
 export * from "./feature/planning.js"
 export * from "./feature/refactor.js"
 export * from "./feature/seam.js"
+export * from "./feature/slicing.js"
 export {
   buildTail,
   type BuildTailOptions,

package/src/workflows/shared/continuation.ts

@@ -0,0 +1,92 @@
+import { human, refuse, scope, vars } from "../../flows/index.js"
+import * as t from "./text.js"
+import type { Handoff } from "./text.js"
+import { defaults } from "./vars.js"
+
+export type { Handoff }
+
+export interface Turned<T> {
+  readonly result: T
+  /** Set when the turn wrote a handoff note, i.e. stopped at its context limit. */
+  readonly handoff?: Handoff | undefined
+}
+
+/** Runs a turn's agent step in a conversation of its own, or in the caller's. */
+export type Fresh = <T>(fn: () => Promise<T>) => Promise<T>
+
+/**
+ * One phase's continuations, shared by every `continuing()` call in it (a naive
+ * retry, a refactor lap) so the caps hold per phase. `spent`: once a turn hit
+ * its context limit, resuming that conversation would only hit it again.
+ */
+export interface Phase {
+  readonly name: string
+  spent: boolean
+  count: number
+  stalled: number
+  /** Run after a landing at `oversized`, where a person may narrow the requirements; absent, the gate does not suggest it. */
+  readonly steered?: (() => void) | undefined
+}
+
+export const phase = (name: string, steered?: () => void): Phase => ({
+  name,
+  spent: false,
+  count: 0,
+  stalled: 0,
+  steered,
+})
+
+const own: Fresh = (fn) => fn()
+// Every `scope()` call is a new conversation; the names keep continuations
+// apart in history from later turns of a phase that merely start afresh.
+const continued: Fresh = (fn) => scope("continue", fn)
+const afresh: Fresh = (fn) => scope("fresh", fn)
+
+const setting = (name: "continuations" | "continuationStall", least: number): number => {
+  const raw = vars[name] ?? defaults[name]!
+  const n = Number(raw)
+  if (raw.trim() === "" || !Number.isInteger(n) || n < least)
+    refuse(`gtd: ${name} must be a whole number of at least ${least}, got ${JSON.stringify(raw)}`)
+  return n
+}
+
+/**
+ * Run `turn` until one ends without a handoff note: each stopped turn is picked
+ * up by a continuation in a fresh conversation. Past `continuations` of them in
+ * the phase, or after `continuationStall` in a row that close nothing still
+ * open, the phase rests at `oversized` for a person; landing there grants a new round.
+ */
+export const continuing = async <T>(
+  phase: Phase,
+  turn: (from: Handoff | undefined, fresh: Fresh) => Promise<Turned<T>>,
+): Promise<T> => {
+  const cap = setting("continuations", 0)
+  const stall = setting("continuationStall", 1)
+  let last = await turn(undefined, phase.spent ? afresh : own)
+  while (last.handoff !== undefined) {
+    phase.spent = true
+    const from = last.handoff
+    if (phase.count >= cap || phase.stalled >= stall) {
+      await human("oversized", {
+        message: t.oversizedMessage(
+          phase.name,
+          from,
+          phase.count >= cap ? { cap } : { stall },
+          phase.steered !== undefined,
+        ),
+        label: "Too big for its context",
+        acceptClean: true,
+      })
+      phase.steered?.()
+      phase.count = 0
+      phase.stalled = 0
+    }
+    last = await turn(from, continued)
+    phase.count++
+    // Nothing countable left open is no stall: only the cap stops such a phase.
+    const closed =
+      from.open.length === 0 || from.open.some((item) => !(last.handoff?.open ?? []).includes(item))
+    phase.stalled = closed ? 0 : phase.stalled + 1
+  }
+  return last.result
+}

package/src/workflows/shared/fences.ts

@@ -17,3 +17,8 @@ export const markFenced = (text: string): readonly { line: string; fenced: boole
     return { line, fenced }
   })
 }
+
+/** A markdown heading: its `#` run, then its text. */
+export const HEADING = /^ {0,3}(#{1,6})\s+(.*?)\s*#*\s*$/
+/** A list item, its checkbox dropped: its text. */
+export const ITEM = /^ ?(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]\s+)?(.*)$/

package/src/workflows/shared/options.ts

@@ -21,8 +21,11 @@ export const ShippedOptions = Schema.Struct({
   reviewSeverityMinP: setting,
   refactorFlagPattern: setting,
   seamAllow: setting,
+  sliceMaxCriteria: setting,
   qualityReviews: setting,
   refactorQualityReviews: setting,
+  continuations: setting,
+  continuationStall: setting,
   testCommand: setting,
   plannerModel: setting,
   coderModel: setting,

package/src/workflows/shared/steps.ts

@@ -14,6 +14,8 @@ export const REVIEW = ".gtd/REVIEW.md"
 export const REFACTOR = ".gtd/REFACTOR.md"
 export const REFACTOR_NOTE = ".gtd/REFACTOR-NOTE.md"
 export const QUALITY = ".gtd/QUALITY.md"
+export const SLICES = ".gtd/SLICES.md"
+export const HANDOFF = ".gtd/HANDOFF.md"
 
 export const planner = (): string => env.plannerModel ?? ""
 export const coder = (): string => env.coderModel ?? ""

package/src/workflows/shared/text.test.ts

@@ -976,7 +976,9 @@ describe("the seam phase's texts", () => {
   it("has a red retry pick up the kept attempt instead of starting over", () => {
     const prompt = renderText(() => naivePassPrompt({ red: "abc123" }))
     expect(prompt).toContain("left the suite red")
-    expect(prompt).toContain("git diff --binary abc123^ abc123 | git apply")
+    expect(prompt).toContain(
+      "git diff --binary --no-color --no-ext-diff --no-textconv abc123^ abc123 | git apply",
+    )
     expect(prompt).toContain(".gtd/FEEDBACK.md")
     expect(prompt).not.toContain("rejected")
   })
@@ -1042,7 +1044,9 @@ describe("the seam phase's texts", () => {
     }
     const prompt = renderText(() => naivePassPrompt(fault))
     expect(prompt).toContain("names AC-2")
-    expect(prompt).toContain("git diff --binary abc123^ abc123 | git apply")
+    expect(prompt).toContain(
+      "git diff --binary --no-color --no-ext-diff --no-textconv abc123^ abc123 | git apply",
+    )
     const message = renderText(() => seamSteerMessage(fault))
     expect(message).toContain("names AC-2")
     expect(message).toContain("`seam.check` runs its suite")