@pmelab/gtd 50.0.0 → 51.0.0

package/src/workflows/feature/slice-findings.feature

@@ -9,6 +9,7 @@ Feature: every slice's quality lap is triaged, and its leftovers wait for the re
 
   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 "correctness"
     And an environment variable "GTD_FLAGMODE" set to "false"
     And an environment variable "GTD_SLICEMAXCRITERIA" set to "1"

package/src/workflows/feature/slicing-cap.feature

@@ -12,3 +12,12 @@ Feature: a bad sliceMaxCriteria refuses the landing that would pin it
       # Something
       """
     Then driving the process is refused with "sliceMaxCriteria must be a positive integer, got \"0\""
+
+  Scenario: a prototypeRounds that is not a whole number refuses the idle landing
+    Given the shipped workflows, as gtd install scaffolds them
+    And an environment variable "GTD_PROTOTYPEROUNDS" set to "-1"
+    And a file "TODO.md" with:
+      """
+      # Something
+      """
+    Then driving the process is refused with "prototypeRounds must be a non-negative integer, got \"-1\""

package/src/workflows/feature/slicing.feature

@@ -8,6 +8,7 @@ Feature: a change with more criteria than the cap is built in coarse slices
 
   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"

package/src/workflows/feature/standards.feature

@@ -11,6 +11,7 @@ Feature: the review learns standards from the human's answers
 
   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 "correctness"
     And an environment variable "GTD_FLAGMODE" set to "false"
     And a file "src/calc.ts" with:

package/src/workflows/shared/options.ts

@@ -27,6 +27,7 @@ export const ShippedOptions = Schema.Struct({
   qualityReviews: setting,
   refactorQualityReviews: setting,
   continuations: setting,
+  prototypeRounds: setting,
   continuationStall: setting,
   testCommand: setting,
   plannerModel: setting,

package/src/workflows/shared/prose.ts

@@ -88,6 +88,12 @@ things when redirected — a failing check, or reviewer feedback. Stay
 strictly inside that task; never touch code outside it. Treat feedback as the
 diagnosis to act on; discard it, with reason, only when simply wrong.`
 
+export const testerPersona = `You are the hands-on tester in gtd's build pipeline: use what was just
+built the way a person would — run the real program, open the real
+page, call the real endpoint — and report exactly what you did and
+what you saw. Never fix anything yourself, and never pass a criterion
+you did not watch hold.`
+
 export const finisherPersona = `You are the closing identity in gtd's build pipeline — the last coder
 before it closes. Fix a late-breaking failing check after sign-off,
 focused and minimal. Every turn lands its own commit — nothing here

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

@@ -29,6 +29,10 @@ describe("the bundled workflow's skills export", () => {
         "implement",
         "implement.fix.suite",
         "implement.health",
+        "implement.prototype",
+        "implement.prototype.fix",
+        "implement.prototype.fix.suite",
+        "implement.prototype.health",
         "build.quality.correctness",
         "build.quality.owasp-security",
         "build.quality.ponytail-review",

package/src/workflows/shared/skills.ts

@@ -33,6 +33,11 @@ export const skills = (
     seam: ["incremental-implementation"],
     implement: ["test-driven-development", "incremental-implementation"],
     "implement.fix.suite": ["debugging-and-error-recovery"],
+    // The hands-on tester runs the program, never the suite: no TDD.
+    "implement.prototype": [],
+    "implement.prototype.fix": ["test-driven-development", "incremental-implementation"],
+    "implement.prototype.fix.suite": ["debugging-and-error-recovery"],
+    "implement.prototype.health": ["debugging-and-error-recovery"],
     // `health` is shared code reached from both `implement` and `build`.
     "implement.health": ["debugging-and-error-recovery"],
     ...lensScopes(

package/src/workflows/shared/steps.ts

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

package/src/workflows/shared/text.ts

@@ -41,6 +41,7 @@ import {
   reviewerPersona,
   builderPersona,
   finisherPersona,
+  testerPersona,
   escalationPersona,
   stateFileRules,
   questionBar,
@@ -485,8 +486,11 @@ const acceptanceCriteriaBlock = `
 Whichever lap this is, \`.gtd/REQUIREMENTS.md\` carries a
 \`## Acceptance Criteria\` section: one \`- AC-<n>: <criterion>\` line
 per criterion, numbered from \`AC-1\`. They bind every later step —
-the build is done when each one holds — so each must be checkable: a
-test or a command shows it holds or not. A later lap keeps every ID:
+the build is done when each one holds — so each must be behaviour a
+test can pin: one that fails when it does not hold. A green suite, a
+passing typecheck or lint, a generator or build that runs — the health
+check enforces those on every lap, so none is a criterion; fold what it
+must produce into a behaviour a test can observe. A later lap keeps every ID:
 reword a criterion in place, append a new one with the next unused
 number, delete a dropped one — never renumber, never reuse an ID. When
 the file holds no list (a review loop-back rewrites it), recover the
@@ -600,7 +604,7 @@ export const clearCriteriaQuestion: JudgeQuestion = {
   instructions:
     "state.criteria lists the acceptance criteria the human's sketch (state.sketch) stated, as gtd numbered them. Decide whether they can stand as the binding definition of done, with no design conversation.",
   criteria:
-    "yes: every criterion is clear and checkable — a test or a command can show it holds or not — and together they say what to build. no: any one criterion is vague, subjective or untestable, or the sketch leaves an open product question. Unsure means no.",
+    "yes: every criterion is clear behaviour a test can pin — a test would fail if it did not hold — and together they say what to build. no: any one criterion is vague, subjective or untestable, only a command can check it (a suite, typecheck, lint, build or generator run that passes), or the sketch leaves an open product question. Unsure means no.",
 }
 
 export const clearCriteriaMessage = (): string =>
@@ -1980,3 +1984,100 @@ Two ways forward (then run \`gtd land\`):
 - **Overrule** — land a clean tree to finish without them. The slice records
   the IDs it covers and, as \`uncovered\`, the ones it does not
 `
+
+export const testerSystem = (): string =>
+  `${testerPersona}
+
+${agentConduct}`
+
+const PROTOTYPE_FORMAT = `- Write \`.gtd/PROTOTYPE.md\`, replacing any earlier report: one \`## \` chunk
+  per criterion, headed \`## AC-<n>: pass\`, \`## AC-<n>: fail\` or
+  \`## AC-<n>: blocked\`, then one chunk per problem you found outside any
+  criterion, headed \`## Problem <short title>: fail\` (\`: pass\` once a
+  re-test shows it fixed). Under each: the exact steps you ran, what you
+  observed (output, a screenshot path, the error), and for a failure what
+  you expected instead
+- \`blocked\` is for a criterion you could not exercise, or one whose
+  expected behaviour itself looks wrong — say which and why: a person
+  decides it, never a fixer`
+
+export const prototypeTestingPrompt = (
+  slice: readonly string[] | undefined,
+  retest: boolean,
+): string =>
+  `${stateFileRules}
+- Read \`.gtd/REQUIREMENTS.md\`: the settled requirements for this change
+${sliceLine(slice)}- The change is built and its suite is green. Now test it by hand: use
+  every acceptance criterion the way a person would and watch what
+  happens. Running the test suite is not this — it already ran
+- Find how this project is exercised for real, in this order: a project
+  skill that launches or drives it (e.g. \`.claude/skills/*\`); a manual
+  testing or running section in \`AGENTS.md\`, \`CLAUDE.md\` or \`README.md\`;
+  failing those, the project's shape — a browser or Playwright for a web
+  project, the built CLI in a scratch directory for a CLI, a request client
+  for an API
+- Found none and recognised no shape: write only a chunk headed
+  \`## No testing instructions\` saying what you looked for, and finish —
+  a person is asked; never guess
+- Test in a disposable place only — a scratch directory outside this
+  repository, a throwaway repository, a dev server on a free port — never
+  against the user's real data or this working tree. Point every tool's
+  output (screenshots, traces, test results) outside the repository too
+${
+  retest
+    ? `- This is a re-test: \`.gtd/PROTOTYPE.md\` holds the last round's report and
+  a fix turn or a person has changed the code since. Re-test every failed or blocked criterion and
+  every problem it lists in full, then re-run the passed ones quickly
+`
+    : ""
+}${PROTOTYPE_FORMAT}
+- Change nothing but \`.gtd/PROTOTYPE.md\` — a turn that does is refused
+- Leave everything uncommitted and finish your turn — do not commit
+`
+
+export const prototypeFixingPrompt = (slice: readonly string[] | undefined): string =>
+  `${stateFileRules}
+- Read \`.gtd/REQUIREMENTS.md\`: the settled requirements for this change
+${sliceLine(slice)}${criteriaBinding(true)}
+- Read \`.gtd/PROTOTYPE.md\`: a hands-on test of the change. Fix every
+  \`fail\` chunk of this change's criteria${slice === undefined ? "" : " (this slice's only)"} or a problem found
+  beside them, at its cause, with a test that shows it; leave \`blocked\`
+  ones to the person
+- A \`fail\` the code does not explain (the tester misread what it saw) has
+  nothing to fix: leave it and change nothing for it — the next round re-tests
+- Leave \`.gtd/PROTOTYPE.md\` as it is: the next round re-tests from it
+- Run \`${env.testCommand}\` and finish only once it is green
+- Leave everything uncommitted and finish your turn — do not commit
+`
+
+const openItems = (items: readonly { subject: string; verdict: string }[]): string =>
+  items.map((item) => `- ${item.subject}: ${item.verdict}`).join("\n")
+
+export const prototypeOpenMessage = (
+  items: readonly { subject: string; verdict: string }[],
+  rounds: number,
+): string =>
+  `The hands-on test of this slice still has open items${rounds > 0 ? ` after ${rounds} fix round${rounds === 1 ? "" : "s"}` : ", and none a fixer can take"}:
+${openItems(items)}
+
+\`.gtd/PROTOTYPE.md\` holds the last report: the steps run and what was seen.
+
+Two ways forward (then run \`gtd land\`):
+- **Fix** — change the code, or the testing instructions, yourself (the
+  criteria are settled: an edit to them is refused); the suite runs and the
+  slice is tested again, with a fresh round budget
+- **Overrule** — land a clean tree to go on to the quality lap with these
+  items open
+`
+
+export const prototypeUnguidedMessage = (): string =>
+  `The hands-on test found no way to exercise this project for real — no
+project skill, no manual testing section in \`AGENTS.md\`, \`CLAUDE.md\` or
+\`README.md\`, and no project shape it recognised. \`.gtd/PROTOTYPE.md\` says
+what it looked for.
+
+Two ways forward (then run \`gtd land\`):
+- **Instruct** — add testing instructions (a project skill, or a manual
+  testing section); the slice is tested again
+- **Skip** — land a clean tree to go on to the quality lap untested
+`

package/src/workflows/shared/vars.ts

@@ -41,6 +41,9 @@ export const defaults: Readonly<Record<string, string>> = {
   // stopped at its context limit before a person is asked, and how many in a
   // row may close nothing still open.
   continuations: "3",
+  // Fix-and-retest rounds of a slice's prototype test before a person is
+  // asked; "0" skips the test.
+  prototypeRounds: "3",
   continuationStall: "2",
 }