@pmelab/gtd 52.1.0 → 53.0.0

package/src/workflows/feature/slicing.feature

@@ -1,297 +0,0 @@
-@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_PROTOTYPEROUNDS" set to "0"
-    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
-
-      ## Impact
-
-      - the greeting module
-
-      ## 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`"
-    When the process is driven
-    Then the process rests at "build.review.reviewing"
-    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.closing
-      gtd(check): implement.closing → build.review.reviewing
-      """
-    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
-
-      ## Impact
-
-      - the greeting module
-
-      ## 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", () => {})
-      """
-    When the process is driven
-    Then the process rests at "build.review.reviewing"
-    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.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.closing
-      gtd(check): implement.closing → build.review.reviewing
-      """
-    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
-
-      ## Impact
-
-      - the greeting module
-
-      ## 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
-
-      ## Impact
-
-      - the greeting module
-
-      ## 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
-
-      ## Impact
-
-      - the greeting module
-
-      ## 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
-
-      ## Impact
-
-      - the greeting module
-
-      ## 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"
-
-  Scenario: a steer that empties the last slice still ends at the review of the whole change
-    Given step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
-      """
-      # Requirements
-
-      ## Impact
-
-      - the greeting module
-
-      ## 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 and divide
-
-      - AC-1
-      - AC-3
-
-      ## Multiply
-
-      - AC-2
-      """
-    And step "seam.naive" writes "src/sub.test.ts" with:
-      """
-      it("[AC-1] subtracts", () => {})
-      """
-    When the process is driven
-    Then the process rests at "seam.steer"
-    Given a file ".gtd/REQUIREMENTS.md" with:
-      """
-      # Requirements
-
-      ## Impact
-
-      - the greeting module
-
-      ## Acceptance Criteria
-
-      - AC-1: subtract(a, b) returns a - b.
-      """
-    When gtd lands
-    And the process is driven
-    Then the process rests at "build.review.reviewing"
-    And the commit subjects end with:
-      """
-      gtd(human): seam.steer → 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.closing
-      gtd(check): implement.closing → build.review.reviewing
-      """
-    And ".gtd/REQUIREMENTS.md" does not exist
-    And ".gtd/SLICES.md" does not exist
-    And the output of gtd "slices" does not contain "feature-2"

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

@@ -1,49 +0,0 @@
-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

@@ -1,105 +0,0 @@
-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/shared/continuation.ts

@@ -1,92 +0,0 @@
-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
-}