@pmelab/gtd 55.0.0 → 57.0.0

package/src/workflows/feature/prototype.feature

@@ -1,428 +0,0 @@
-@inmem
-Feature: every observable criterion is tested by hand before the quality lap
-
-  Once the suite is green, implement.prototype.observable judges which
-  criteria a person can observe, and implement.prototype.testing uses the
-  change the way a person would and writes .gtd/PROTOTYPE.md, one chunk per
-  such criterion headed `## AC-<n>: pass|fail|blocked`, plus one per problem
-  found beside them. A failure goes to implement.prototype.fix.fixing and is tested again; only a clean
-  report closes the test. Past `prototypeRounds` fix rounds, or with nothing a
-  fixer can take, a person decides at implement.prototype.open.
-
-  Background:
-    Given the shipped workflows, as gtd install scaffolds them
-    And an environment variable "GTD_QUALITYREVIEWS" set to "correctness"
-    And an environment variable "GTD_FLAGMODE" set to "false"
-    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:
-      """
-      # Add subtract
-
-      subtract(a, b) returns the difference.
-      """
-    And step "unwind" changes nothing
-    And step "start-gate.check" changes nothing
-    And 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: add is unchanged.
-      """
-    And step "design.gate.answer" changes nothing
-    And step "seam.naive" writes "src/calc.ts" with:
-      """
-      export const add = (a: number, b: number) => a + b
-      export const subtract = (a: number, b: number) => a + b
-      """
-    And step "seam.naive" writes "src/calc.test.ts" with:
-      """
-      it("[AC-1] subtracts", () => expect(subtract(3, 1)).toBe(2))
-      it("[AC-2] adds", () => expect(add(1, 1)).toBe(2))
-      """
-    And step "seam.check" changes nothing
-    And step "implement.applying" runs its script
-    And step "implement.health.check" changes nothing
-    And judge step "implement.prototype.observable" answers:
-      """
-      [{"id":"AC-1","answer":"yes","p":0.9},{"id":"AC-2","answer":"yes","p":0.9}]
-      """
-    And step "implement.closing" runs its script
-
-  Scenario: the testing turn is told to use every criterion for real, in a disposable place
-    When the process is driven
-    Then the process rests at "implement.prototype.testing"
-    And the last commit subject is "gtd(judge): implement.prototype.observable → implement.prototype.testing"
-    And the resting step's content contains "Running the test suite is not this"
-    And the resting step's content contains "against the user's real data or this working tree"
-    And the resting step's content contains "`## AC-<n>: pass`"
-
-  Scenario: a clean report closes the test and moves on to the quality lap
-    Given step "implement.prototype.testing" writes ".gtd/PROTOTYPE.md" with:
-      """
-      # Prototype test
-
-      ## AC-1: pass
-
-      Ran `node -e 'console.log(subtract(3, 1))'` in a scratch directory; printed 2.
-
-      ## AC-2: pass
-
-      Ran `node -e 'console.log(add(1, 1))'`; printed 2.
-      """
-    When the process is driven
-    Then the process rests at "build.quality.correctness.reviewing"
-    And the commit subjects end with:
-      """
-      gtd(judge): implement.prototype.observable → implement.prototype.testing
-      gtd(agent): implement.prototype.testing → implement.closing
-      gtd(check): implement.closing → build.quality.correctness.reviewing
-      """
-    And ".gtd/PROTOTYPE.md" does not exist
-
-  Scenario: a failed criterion is fixed and re-tested before the quality lap
-    Given step "implement.prototype.testing", when prompted with "Find how this project", writes ".gtd/PROTOTYPE.md" with:
-      """
-      # Prototype test
-
-      ## AC-1: fail
-
-      Ran `subtract(3, 1)` in a scratch directory; printed 4. Expected 2.
-
-      ## AC-2: pass
-
-      Ran `add(1, 1)`; printed 2.
-      """
-    And step "implement.prototype.fix.fixing" writes "src/calc.ts" with:
-      """
-      export const add = (a: number, b: number) => a + b
-      export const subtract = (a: number, b: number) => a - b
-      """
-    And step "implement.prototype.fix.fixing" is prompted with "Read `.gtd/PROTOTYPE.md`: a hands-on test"
-    And step "implement.prototype.health.check" changes nothing
-    And step "implement.prototype.testing", when prompted with "This is a re-test", writes ".gtd/PROTOTYPE.md" with:
-      """
-      # Prototype test
-
-      ## AC-1: pass
-
-      Re-tested: `subtract(3, 1)` printed 2.
-
-      ## AC-2: pass
-
-      Re-ran `add(1, 1)`; printed 2.
-      """
-    When the process is driven
-    Then the process rests at "build.quality.correctness.reviewing"
-    And the commit subjects end with:
-      """
-      gtd(judge): implement.prototype.observable → implement.prototype.testing
-      gtd(agent): implement.prototype.testing → implement.prototype.fix.fixing
-      gtd(agent): implement.prototype.fix.fixing → implement.prototype.health.check
-      gtd(check): implement.prototype.health.check → implement.prototype.testing
-      gtd(agent): implement.prototype.testing → implement.closing
-      gtd(check): implement.closing → build.quality.correctness.reviewing
-      """
-
-  Scenario: a problem outside any criterion is fixed too
-    Given step "implement.prototype.testing" writes ".gtd/PROTOTYPE.md" with:
-      """
-      ## AC-1: pass
-
-      Printed 2.
-
-      ## AC-2: pass
-
-      Printed 2.
-
-      ## Problem a warning on every call: fail
-
-      Every call printed a deprecation warning.
-      """
-    When the process is driven
-    Then the process rests at "implement.prototype.fix.fixing"
-
-  Scenario: a blocked criterion goes to a person, not a fixer
-    Given step "implement.prototype.testing" writes ".gtd/PROTOTYPE.md" with:
-      """
-      ## AC-1: blocked
-
-      The criterion expects a - b, but the sketch asked for the absolute difference.
-
-      ## AC-2: pass
-
-      Printed 2.
-      """
-    When the process is driven
-    Then the process rests at "implement.prototype.open"
-    And the resting step's content contains "- AC-1: blocked"
-
-  Scenario: overruling the open items goes on to the quality lap
-    Given step "implement.prototype.testing" writes ".gtd/PROTOTYPE.md" with:
-      """
-      ## AC-1: blocked
-
-      Could not tell.
-
-      ## AC-2: pass
-
-      Printed 2.
-      """
-    And step "implement.prototype.open" changes nothing
-    When the process is driven
-    Then the process rests at "build.quality.correctness.reviewing"
-    And the commit subjects end with:
-      """
-      gtd(agent): implement.prototype.testing → implement.prototype.open
-      gtd(human): implement.prototype.open → implement.closing
-      gtd(check): implement.closing → build.quality.correctness.reviewing
-      """
-
-  Scenario: with no testing instructions the step rests at a gate saying so
-    Given step "implement.prototype.testing" writes ".gtd/PROTOTYPE.md" with:
-      """
-      ## No testing instructions
-
-      No project skill, no manual testing section, no recognised project shape.
-      """
-    When the process is driven
-    Then the process rests at "implement.prototype.unguided"
-    And the resting step's content contains "no way to exercise this project for real"
-
-  Scenario: a report missing a criterion is refused
-    Given step "implement.prototype.testing" writes ".gtd/PROTOTYPE.md" with:
-      """
-      ## AC-1: pass
-
-      Printed 2.
-      """
-    Then driving the process is refused with "exactly one chunk headed `## <ID>: pass|fail|blocked` for AC-2"
-
-  Scenario: a testing turn that changes the working tree is refused
-    Given step "implement.prototype.testing" writes ".gtd/PROTOTYPE.md" with:
-      """
-      ## AC-1: pass
-
-      Printed 2.
-
-      ## AC-2: pass
-
-      Printed 2.
-      """
-    And step "implement.prototype.testing" writes "scratch.txt" with:
-      """
-      left behind
-      """
-    Then driving the process is refused with "change nothing but .gtd/PROTOTYPE.md"
-
-  Scenario: a fix turn may not change the acceptance criteria
-    Given step "implement.prototype.testing" writes ".gtd/PROTOTYPE.md" with:
-      """
-      ## AC-1: fail
-
-      Printed 4.
-
-      ## AC-2: pass
-
-      Printed 2.
-      """
-    And step "implement.prototype.fix.fixing" writes ".gtd/REQUIREMENTS.md" with:
-      """
-      # Requirements
-
-      ## Impact
-
-      - the greeting module
-
-      ## Acceptance Criteria
-
-      - AC-2: add is unchanged.
-      """
-    Then driving the process is refused with "criteria-frozen"
-
-  Scenario: a fix turn may not edit the report it fixes from
-    Given step "implement.prototype.testing" writes ".gtd/PROTOTYPE.md" with:
-      """
-      ## AC-1: fail
-
-      Printed 4.
-
-      ## AC-2: pass
-
-      Printed 2.
-      """
-    And step "implement.prototype.fix.fixing" writes "src/calc.ts" with:
-      """
-      export const add = (a: number, b: number) => a + b
-      export const subtract = (a: number, b: number) => a - b
-      """
-    And step "implement.prototype.fix.fixing" writes ".gtd/PROTOTYPE.md" with:
-      """
-      ## AC-1: pass
-
-      Fixed.
-
-      ## AC-2: pass
-
-      Printed 2.
-      """
-    Then driving the process is refused with "prototype-fix: leave .gtd/PROTOTYPE.md as it is"
-
-  Scenario: a chunk naming no criterion of the change is still an open item
-    Given step "implement.prototype.testing" writes ".gtd/PROTOTYPE.md" with:
-      """
-      ## AC-1: pass
-
-      Printed 2.
-
-      ## AC-2: pass
-
-      Printed 2.
-
-      ## AC-9: fail
-
-      No such command yet.
-      """
-    When the process is driven
-    Then the process rests at "implement.prototype.fix.fixing"
-
-  Scenario: instructions added at the unguided gate run the suite, then a fresh test
-    Given step "implement.prototype.testing", when prompted with "Find how this project", writes ".gtd/PROTOTYPE.md" with:
-      """
-      ## No testing instructions
-
-      Nothing found.
-      """
-    And step "implement.prototype.unguided" writes "AGENTS.md" with:
-      """
-      ## Manual testing
-
-      Run `node -e` against the calculator in a scratch directory.
-      """
-    And step "implement.prototype.health.check" changes nothing
-    And step "implement.prototype.testing" is prompted with "Find how this project"
-    When the process is driven
-    # The fresh test still finds no way in; the gate's second visit adds nothing new and goes on.
-    Then the process rests at "build.quality.correctness.reviewing"
-    And the commit subjects end with:
-      """
-      gtd(agent): implement.prototype.testing → implement.prototype.unguided
-      gtd(human): implement.prototype.unguided → implement.prototype.health.check
-      gtd(check): implement.prototype.health.check → implement.prototype.testing
-      gtd(agent): implement.prototype.testing → implement.prototype.unguided
-      gtd(human): implement.prototype.unguided → implement.closing
-      gtd(check): implement.closing → build.quality.correctness.reviewing
-      """
-
-  Scenario: a clean land at the unguided gate goes on untested
-    Given step "implement.prototype.testing" writes ".gtd/PROTOTYPE.md" with:
-      """
-      ## No testing instructions
-
-      Nothing found.
-      """
-    And step "implement.prototype.unguided" changes nothing
-    When the process is driven
-    Then the process rests at "build.quality.correctness.reviewing"
-    And the commit subjects end with:
-      """
-      gtd(agent): implement.prototype.testing → implement.prototype.unguided
-      gtd(human): implement.prototype.unguided → implement.closing
-      gtd(check): implement.closing → build.quality.correctness.reviewing
-      """
-
-  Scenario: a no-instructions chunk beside tested criteria is read as an ordinary report
-    Given step "implement.prototype.testing" writes ".gtd/PROTOTYPE.md" with:
-      """
-      ## AC-1: fail
-
-      Printed 4.
-
-      ## AC-2: pass
-
-      Printed 2.
-
-      ## No testing instructions
-
-      Found none for the edge cases; used the CLI.
-      """
-    When the process is driven
-    Then the process rests at "implement.prototype.fix.fixing"
-
-  Scenario: a fix turn that finds nothing to fix goes on to the re-test
-    Given step "implement.prototype.testing", when prompted with "Find how this project", writes ".gtd/PROTOTYPE.md" with:
-      """
-      ## AC-1: fail
-
-      Printed 4, I think.
-
-      ## AC-2: pass
-
-      Printed 2.
-      """
-    And step "implement.prototype.fix.fixing" changes nothing
-    And step "implement.prototype.health.check" changes nothing
-    And step "implement.prototype.testing", when prompted with "This is a re-test", writes ".gtd/PROTOTYPE.md" with:
-      """
-      ## AC-1: pass
-
-      Looked again: printed 2.
-
-      ## AC-2: pass
-
-      Printed 2.
-      """
-    When the process is driven
-    Then the process rests at "build.quality.correctness.reviewing"
-
-  Scenario: a problem heading that misses the shape is refused, not dropped
-    Given step "implement.prototype.testing" writes ".gtd/PROTOTYPE.md" with:
-      """
-      ## AC-1: pass
-
-      Printed 2.
-
-      ## AC-2: pass
-
-      Printed 2.
-
-      ## Problem every call warns — fail
-
-      Each call printed a deprecation warning.
-      """
-    Then driving the process is refused with "these miss it:"
-
-  Scenario: a re-test that finds no way to test is refused, keeping the open items in view
-    Given step "implement.prototype.testing", when prompted with "Find how this project", writes ".gtd/PROTOTYPE.md" with:
-      """
-      ## AC-1: fail
-
-      Printed 4.
-
-      ## AC-2: pass
-
-      Printed 2.
-      """
-    And step "implement.prototype.fix.fixing" writes "src/calc.ts" with:
-      """
-      export const add = (a: number, b: number) => a + b
-      export const subtract = (a: number, b: number) => a - b
-      """
-    And step "implement.prototype.health.check" changes nothing
-    And step "implement.prototype.testing", when prompted with "This is a re-test", writes ".gtd/PROTOTYPE.md" with:
-      """
-      ## No testing instructions
-
-      The CLI is gone.
-      """
-    Then driving the process is refused with "needs exactly one chunk"

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

@@ -1,43 +0,0 @@
-import { describe, expect, it } from "vitest"
-import { reportOf } from "./prototype.js"
-
-describe("reportOf", () => {
-  it("reads each criterion and problem chunk with its verdict, any case", () => {
-    expect(
-      reportOf(
-        "# Prototype test\n\n## AC-1: pass\n\nok\n\n## AC-2 : FAIL\n\n## Problem double replies: blocked\n",
-      ),
-    ).toEqual({
-      unguided: false,
-      items: [
-        { subject: "AC-1", verdict: "pass" },
-        { subject: "AC-2", verdict: "fail" },
-        { subject: "Problem double replies", verdict: "blocked" },
-      ],
-      malformed: [],
-    })
-  })
-
-  it("skips fenced lines, deeper headings and prose headings", () => {
-    expect(reportOf("```md\n## AC-1: fail\n```\n### AC-2: fail\n## Notes\n")).toEqual({
-      unguided: false,
-      items: [],
-      malformed: [],
-    })
-  })
-
-  it("lists an item-like heading that misses the shape", () => {
-    expect(
-      reportOf("## Problem crash — fail\n## AC-2: failed\n## Problems: fail\n## AC-3: maybe\n")
-        .malformed,
-    ).toEqual(["Problem crash — fail", "AC-2: failed", "Problems: fail", "AC-3: maybe"])
-  })
-
-  it("upper-cases a criterion ID written in lower case", () => {
-    expect(reportOf("## ac-1: pass\n").items).toEqual([{ subject: "AC-1", verdict: "pass" }])
-  })
-
-  it("reads the no-instructions chunk", () => {
-    expect(reportOf("## No testing instructions\n\nNo skill found.\n").unguided).toBe(true)
-  })
-})

package/src/workflows/feature/prototype.ts

@@ -1,198 +0,0 @@
-import { answered, changes, human, judge, read, refuse, scope, vars } from "../../flows/index.js"
-import { HEADING, markFenced } from "../shared/fences.js"
-import { coder, PROTOTYPE, REQUIREMENTS } from "../shared/steps.js"
-import * as t from "../shared/text.js"
-import { defaults } from "../shared/vars.js"
-import { green } from "./green.js"
-import { criteriaOf, criterionIds, handsOnIds, requireCriteriaFrozen } from "./criteria.js"
-
-/** Only a `no` at this or above skips a criterion: no verdict, or an unsure one, sends it to the hands-on test. */
-const UNOBSERVABLE_MIN_P = 0.5
-
-/** The `prototypeRounds` setting. Anything but a non-negative integer fails rather than guess a cap. */
-export const prototypeRounds = (): number => {
-  const value = vars.prototypeRounds ?? defaults.prototypeRounds!
-  if (!/^(0|[1-9]\d*)$/.test(value))
-    refuse(`gtd: prototypeRounds must be a non-negative integer, got ${JSON.stringify(value)}`)
-  return Number(value)
-}
-
-export type Verdict = "pass" | "fail" | "blocked"
-
-export interface Item {
-  /** A criterion ID, or `Problem <title>`. */
-  readonly subject: string
-  readonly verdict: Verdict
-}
-
-export interface Report {
-  readonly unguided: boolean
-  readonly items: readonly Item[]
-  /** Headings that read as an item but miss the shape: a failure there would go unseen. */
-  readonly malformed: readonly string[]
-}
-
-const CHUNK = /^(AC-\d+|Problem\b.*?)\s*:\s*(pass|fail|blocked)$/i
-const UNGUIDED = /^no testing instructions$/i
-
-/** The `## ` chunks of a prototype report; a heading in neither shape is prose, not an item. */
-export const reportOf = (text: string): Report => {
-  let unguided = false
-  const items: Item[] = []
-  const malformed: string[] = []
-  for (const { line, fenced } of markFenced(text)) {
-    const heading = fenced ? null : HEADING.exec(line)
-    if (heading?.[1] !== "##") continue
-    if (UNGUIDED.test(heading[2]!)) unguided = true
-    const chunk = CHUNK.exec(heading[2]!)
-    if (chunk === null && /^(ac-\d|problem)/i.test(heading[2]!)) malformed.push(heading[2]!)
-    if (chunk !== null)
-      items.push({
-        subject: /^ac-/i.test(chunk[1]!) ? chunk[1]!.toUpperCase() : chunk[1]!,
-        verdict: chunk[2]!.toLowerCase() as Verdict,
-      })
-  }
-  return { unguided, items, malformed }
-}
-
-/**
- * The report the testing turn left, refused unless it is the only change and
- * names each of `ids` once, with its open items: any other criterion is not
- * this test's to fix.
- */
-const requireReport = (
-  ids: readonly string[],
-  retest: boolean,
-): { readonly unguided: boolean; readonly open: readonly Item[] } => {
-  const others = changes()
-    .map((c) => c.path)
-    .filter((path) => path !== PROTOTYPE)
-  if (others.length > 0)
-    refuse(
-      `gtd land: prototype-report: test in a disposable place and change nothing but ${PROTOTYPE} — revert these:\n${others.map((path) => `  - ${path}`).join("\n")}`,
-    )
-  const text = read(PROTOTYPE)
-  if (text === undefined) return refuse(`gtd land: prototype-report: write ${PROTOTYPE}`)
-  const report = reportOf(text)
-  if (report.malformed.length > 0)
-    refuse(
-      `gtd land: prototype-report: head each chunk \`## <ID>: pass|fail|blocked\` or \`## Problem <title>: pass|fail|blocked\` — these miss it:\n${report.malformed.map((h) => `  - ${h}`).join("\n")}`,
-    )
-  // Only a first test with nothing else in it: a chunk beside it was tested after all, and a
-  // re-test's open items must reach a person, not slip past as untested.
-  if (report.unguided && report.items.length === 0 && !retest) return { unguided: true, open: [] }
-  const elsewhere = criterionIds(read(REQUIREMENTS) ?? "").filter((id) => !ids.includes(id))
-  const count = (id: string): number => report.items.filter((i) => i.subject === id).length
-  const wrong = ids.filter((id) => count(id) !== 1)
-  if (wrong.length > 0)
-    refuse(
-      `gtd land: prototype-report: ${PROTOTYPE} needs exactly one chunk headed \`## <ID>: pass|fail|blocked\` for ${wrong.join(", ")}`,
-    )
-  // A mistyped ID stays open: only a known criterion outside `ids` is not this test's to fix.
-  const open = report.items.filter((i) => i.verdict !== "pass" && !elsewhere.includes(i.subject))
-  return { unguided: false, open }
-}
-
-/**
- * The criteria a person can observe by using the change, by the judge: those
- * tagged `(no hands-on)` are never asked about.
- */
-const observable = async (): Promise<string[]> => {
-  const requirements = read(REQUIREMENTS) ?? ""
-  const own = handsOnIds(requirements)
-  const criteria = (criteriaOf(requirements) ?? []).filter((c) => own.includes(c.id))
-  if (criteria.length === 0) return []
-  const { answers } = await judge("observable", {
-    questions: criteria.map(t.observableQuestion),
-    evidence: { requirements },
-    message: t.observableMessage(),
-    label: "Judging which criteria to test by hand",
-  })
-  return own.filter((id) => !answered(answers[id], "no", UNOBSERVABLE_MIN_P))
-}
-
-const frozen = (): void => requireCriteriaFrozen(REQUIREMENTS)
-
-const testing = async (
-  ids: readonly string[],
-  retest: boolean,
-): Promise<ReturnType<typeof requireReport>> => {
-  const skipped = criterionIds(read(REQUIREMENTS) ?? "").filter((id) => !ids.includes(id))
-  await t.agentWithSkills("testing", t.prototypeTestingPrompt(skipped, retest), {
-    label: retest ? "Re-testing the change by hand" : "Testing the change by hand",
-    file: PROTOTYPE,
-    model: coder(),
-    system: t.testerSystem(),
-    // A test that saw exactly what the last round saw leaves the report as it was.
-    allowEmpty: true,
-  })
-  return requireReport(ids, retest)
-}
-
-const fixing = async (): Promise<void> => {
-  await scope("fix", () =>
-    t.agentWithSkills("fixing", t.prototypeFixingPrompt(), {
-      label: "Fixing what the hands-on test found",
-      file: PROTOTYPE,
-      model: coder(),
-      system: t.builderSystem(),
-      // A `fail` the tester got wrong has nothing to fix: the re-test says so, or the cap ends it.
-      allowEmpty: true,
-    }),
-  )
-  // The re-test may land empty: a report the fixer edited would pass untested.
-  if (changes().some((c) => c.path === PROTOTYPE))
-    refuse(`gtd land: prototype-fix: leave ${PROTOTYPE} as it is — the next round re-tests from it`)
-  frozen()
-}
-
-/** A person's rest; resolves `true` when they changed something to test again, `false` on a clean overrule. */
-const askPerson = async (name: string, message: string, label: string): Promise<boolean> => {
-  await human(name, { message, label, file: PROTOTYPE, acceptClean: true })
-  // A note in the report alone tests nothing new.
-  if (!changes().some((c) => c.path !== PROTOTYPE)) return false
-  frozen()
-  return true
-}
-
-/**
- * Use the change by hand: a testing turn reports on every criterion a person
- * can observe, a fix turn takes each failure, and the change is tested again —
- * until the report is clean, or `prototypeRounds` fixes are spent and a person
- * decides. A change with no such criterion is not tested by hand.
- */
-export const prototypeTest = async (): Promise<void> => {
-  const cap = prototypeRounds()
-  if (cap === 0) return
-  await scope("prototype", async () => {
-    const ids = await observable()
-    if (ids.length === 0) return
-    let fixes = 0
-    let retest = false
-    for (;;) {
-      const { unguided, open } = await testing(ids, retest)
-      retest = !unguided
-      if (unguided) {
-        const instructed = await askPerson(
-          "unguided",
-          t.prototypeUnguidedMessage(),
-          "No way to test by hand",
-        )
-        if (!instructed) return
-      } else if (open.length === 0) return
-      else if (fixes < cap && open.some((i) => i.verdict === "fail")) {
-        fixes++
-        await fixing()
-      } else {
-        const changed = await askPerson(
-          "open",
-          t.prototypeOpenMessage(open, fixes),
-          "Hands-on test still failing",
-        )
-        if (!changed) return
-        fixes = 0
-      }
-      await green()
-    }
-  })
-}