@pmelab/gtd 36.0.0 → 38.0.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/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.test.ts

@@ -8,8 +8,9 @@ const { defaults, envDefaults, feature, fix, review, ShippedOptions } = workflow
 const { flagShipped } = options
 
 describe("the shipped workflow factories", () => {
-  it("take exactly the settings the shipped workflows declare as options", () => {
-    expect(Object.keys(ShippedOptions.fields).sort()).toEqual(
+  it("take exactly the settings the shipped workflows declare as options, and contextLimit", () => {
+    const settings = Object.keys(ShippedOptions.fields).filter((name) => name !== "contextLimit")
+    expect(settings.sort()).toEqual(
       [...Object.keys(defaults), ...Object.keys(envDefaults)]
         .filter((name) => !name.startsWith("flag_"))
         .sort(),
@@ -23,6 +24,14 @@ describe("the shipped workflow factories", () => {
       expect(defaults).toHaveProperty(`flag_${name}`, defaultOn ? "1" : "0")
   })
 
+  it("keep contextLimit out of the settings", () => {
+    const built = configure(feature({ contextLimit: { hard: 0.8 } }))
+    expect(built).toMatchObject({ ok: true })
+    const build = built?.ok === true ? built.build : undefined
+    expect(build?.defaults).not.toHaveProperty("contextLimit")
+    expect(build?.envDefaults).not.toHaveProperty("contextLimit")
+  })
+
   it("declare a seamAllow default a factory option overrides", () => {
     expect(configure(feature({ seamAllow: "docs/**" }))).toMatchObject({
       ok: true,

package/src/workflows/shared/options.ts

@@ -6,6 +6,7 @@ import {
   type WorkflowDoors,
   type WorkflowFactory,
   refuse,
+  scope,
   vars,
 } from "../../flows/index.js"
 import { defaultFlagRegistry, defaults, envDefaults } from "./vars.js"
@@ -20,12 +21,20 @@ export const ShippedOptions = Schema.Struct({
   reviewSeverityMinP: setting,
   refactorFlagPattern: setting,
   seamAllow: setting,
+  sliceMaxCriteria: setting,
   qualityReviews: setting,
   refactorQualityReviews: setting,
   testCommand: setting,
   plannerModel: setting,
   coderModel: setting,
   flagMode: Schema.optionalWith(Schema.Boolean, { exact: true }),
+  contextLimit: Schema.optionalWith(
+    Schema.Struct({
+      soft: Schema.optionalWith(Schema.Number, { exact: true }),
+      hard: Schema.optionalWith(Schema.Number, { exact: true }),
+    }),
+    { exact: true },
+  ),
 })
 
 export type ShippedOptions = Schema.Schema.Encoded<typeof ShippedOptions>
@@ -50,6 +59,12 @@ export const flagModeOn = (): boolean => {
   return value === "true"
 }
 
+// Not a setting: a factory option is known at load, so the scope wraps the
+// whole flow without reading a setting before its first step. The engine
+// refuses limits it cannot use when it reaches an agent step.
+const limited = (flow: Flow, context: ShippedOptions["contextLimit"]): Flow =>
+  context === undefined ? flow : () => scope({ context }, flow)
+
 /** A shipped flow as a factory: its options override the settings it declares, each in its own kind. */
 export const shipped = (
   flow: Flow,
@@ -58,8 +73,8 @@ export const shipped = (
 ): WorkflowFactory<ShippedOptions> =>
   defineWorkflow(
     Schema.standardSchemaV1(ShippedOptions, { onExcessProperty: "error", errors: "all" }),
-    (options) => ({
-      flow,
+    ({ contextLimit, ...options }) => ({
+      flow: limited(flow, contextLimit),
       defaults: over(defaults, options),
       envDefaults: over(envDefaults, options),
       doors,
@@ -77,10 +92,10 @@ export const flagShipped = (
 ): WorkflowFactory<FlagOptions> =>
   defineWorkflow(
     Schema.standardSchemaV1(FlagOptions, { onExcessProperty: "error", errors: "all" }),
-    (options) => {
+    ({ contextLimit, ...options }) => {
       const flagDefaults = { ...defaults, flag: "", flagRegistry: defaultFlagRegistry }
       return {
-        flow,
+        flow: limited(flow, contextLimit),
         defaults: over(flagDefaults, options),
         envDefaults: over(envDefaults, options),
         doors: { [name]: { args: [{ name: "flag" }], vars: ({ flag }) => ({ flag: flag ?? "" }) } },

package/src/workflows/shared/steps.ts

@@ -12,7 +12,9 @@ export const ESCALATION = ".gtd/ESCALATION.md"
 export const REQUIREMENTS = ".gtd/REQUIREMENTS.md"
 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 planner = (): string => env.plannerModel ?? ""
 export const coder = (): string => env.coderModel ?? ""