@pmelab/gtd 51.0.1 → 52.0.0

package/src/workflows/feature/prototype.ts

@@ -1,11 +1,21 @@
-import { changes, human, read, refuse, scope, vars } from "../../flows/index.js"
+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 type { Guard } from "../shared/health.js"
-import { green } from "./coverage.js"
-import { criterionIds, requireCriteriaFrozen, sliceIds, type CriteriaSlice } from "./criteria.js"
+import { green } from "./green.js"
+import {
+  criteriaOf,
+  criterionIds,
+  handsOnIds,
+  requireCriteriaFrozen,
+  sliceIds,
+  type CriteriaSlice,
+} 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 => {
@@ -55,11 +65,11 @@ export const reportOf = (text: string): Report => {
 
 /**
  * The report the testing turn left, refused unless it is the only change and
- * names every criterion once, with its open items: another slice's criteria
- * are not this slice's to fix.
+ * names each of `ids` once, with its open items: any other criterion is not
+ * this test's to fix.
  */
 const requireReport = (
-  slice: CriteriaSlice | undefined,
+  ids: readonly string[],
   retest: boolean,
 ): { readonly unguided: boolean; readonly open: readonly Item[] } => {
   const others = changes()
@@ -79,27 +89,45 @@ const requireReport = (
   // 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 requirements = read(REQUIREMENTS) ?? ""
-  const ids = criterionIds(requirements, slice)
-  const elsewhere = criterionIds(requirements).filter((id) => !ids.includes(id))
+  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 another slice's criteria are not this one's to fix.
+  // 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 slice's criteria a person can observe by using the change, by the
+ * judge: those tagged `(no hands-on)` are never asked about.
+ */
+const observable = async (slice: CriteriaSlice | undefined): Promise<string[]> => {
+  const requirements = read(REQUIREMENTS) ?? ""
+  const own = handsOnIds(requirements, slice)
+  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 (
   slice: CriteriaSlice | undefined,
+  ids: readonly string[],
   retest: boolean,
 ): Promise<ReturnType<typeof requireReport>> => {
-  await t.agentWithSkills("testing", t.prototypeTestingPrompt(sliceIds(slice), retest), {
+  const skipped = criterionIds(read(REQUIREMENTS) ?? "", slice).filter((id) => !ids.includes(id))
+  await t.agentWithSkills("testing", t.prototypeTestingPrompt(sliceIds(slice), skipped, retest), {
     label: retest ? "Re-testing the slice by hand" : "Testing the slice by hand",
     file: PROTOTYPE,
     model: coder(),
@@ -107,7 +135,7 @@ const testing = async (
     // A test that saw exactly what the last round saw leaves the report as it was.
     allowEmpty: true,
   })
-  return requireReport(slice, retest)
+  return requireReport(ids, retest)
 }
 
 const fixing = async (slice: CriteriaSlice | undefined, guard?: Guard): Promise<void> => {
@@ -138,10 +166,11 @@ const askPerson = async (name: string, message: string, label: string): Promise<
 }
 
 /**
- * Use the slice by hand: a testing turn reports on every criterion, a fix turn
- * takes each failure, and the slice is tested again — until the report is
- * clean, or `prototypeRounds` fixes are spent and a person decides. `guard`
- * holds every fix turn, as it holds the implementation's.
+ * Use the slice by hand: a testing turn reports on every criterion a person
+ * can observe, a fix turn takes each failure, and the slice is tested again —
+ * until the report is clean, or `prototypeRounds` fixes are spent and a person
+ * decides. A slice with no such criterion is not tested by hand. `guard` holds
+ * every fix turn, as it holds the implementation's.
  */
 export const prototypeTest = async (
   slice: CriteriaSlice | undefined,
@@ -150,10 +179,12 @@ export const prototypeTest = async (
   const cap = prototypeRounds()
   if (cap === 0) return
   await scope("prototype", async () => {
+    const ids = await observable(slice)
+    if (ids.length === 0) return
     let fixes = 0
     let retest = false
     for (;;) {
-      const { unguided, open } = await testing(slice, retest)
+      const { unguided, open } = await testing(slice, ids, retest)
       retest = !unguided
       if (unguided) {
         const instructed = await askPerson(

package/src/workflows/feature/refactor-absorbs.feature

@@ -96,9 +96,9 @@ Feature: a refactor that carried the whole feature still gets a quality lap over
 
       <!-- base: 0000000 -->
 
-      ## calc
+      ## Walkthrough
 
-      _critical: judge unsure_
+      ### calc
 
       - [x] ./src/calc.ts#1-2
         subtract next to add
@@ -109,10 +109,6 @@ Feature: a refactor that carried the whole feature still gets a quality lap over
       """
     And step "implement.health.check" changes nothing
     And step "implement.closing" runs its script
-    And judge step "implement.coverage" answers:
-      """
-      [{"id":"AC-1","answer":"yes","p":0.9}]
-      """
     When gtd lands
     And the process is driven
     Then the process rests at "build.quality.correctness.reviewing"
@@ -128,8 +124,7 @@ Feature: a refactor that carried the whole feature still gets a quality lap over
       gtd(human): refactor.build.review.await-review → refactor.build.review.closing
       gtd(check): refactor.build.review.closing → implement.building
       gtd(agent): implement.building → implement.health.check
-      gtd(check): implement.health.check → implement.coverage
-      gtd(judge): implement.coverage → implement.closing
+      gtd(check): implement.health.check → implement.closing
       gtd(check): implement.closing → build.quality.correctness.reviewing
       gtd(agent): build.quality.correctness.reviewing → build.review.reviewing
       """

package/src/workflows/feature/refactor-first.feature

@@ -100,9 +100,9 @@ Feature: a refactor-first judgment walks one fixed path to the review gate
 
       <!-- base: 0000000 -->
 
-      ## calc
+      ## Walkthrough
 
-      _critical: judge unsure_
+      ### calc
 
       - [x] ./src/calc.ts#1-2
         add built on the shared op
@@ -124,10 +124,6 @@ Feature: a refactor-first judgment walks one fixed path to the review gate
       """
     And step "implement.health.check" changes nothing
     And step "implement.closing" runs its script
-    And judge step "implement.coverage" answers:
-      """
-      [{"id":"AC-1","answer":"yes","p":0.9}]
-      """
     When the process is driven
     Then the process rests at "build.review.reviewing"
     And "src/calc.ts" contains "op(a, b, 1)"
@@ -153,8 +149,7 @@ Feature: a refactor-first judgment walks one fixed path to the review gate
       gtd(human): refactor.build.review.await-review → refactor.build.review.closing
       gtd(check): refactor.build.review.closing → implement.building
       gtd(agent): implement.building → implement.health.check
-      gtd(check): implement.health.check → implement.coverage
-      gtd(judge): implement.coverage → implement.closing
+      gtd(check): implement.health.check → implement.closing
       gtd(check): implement.closing → build.review.reviewing
       """
     And the commit "gtd(human): idle → unwind" has a body containing "Gtd-Var: flag_risk_tier=0"

package/src/workflows/feature/refactor-rebuild.feature

@@ -110,9 +110,9 @@ Feature: refactor-first writes a refactor note, refactors on its own, then rebui
 
       <!-- base: 0000000 -->
 
-      ## calc
+      ## Walkthrough
 
-      _critical: judge unsure_
+      ### calc
 
       - [x] ./src/calc.ts#1-2
         add built on the shared op
@@ -181,9 +181,9 @@ Feature: refactor-first writes a refactor note, refactors on its own, then rebui
 
       <!-- base: 0000000 -->
 
-      ## calc
+      ## Walkthrough
 
-      _critical: judge unsure_
+      ### calc
 
       - [x] ./src/calc.ts#1-2
         add built on the shared op
@@ -234,9 +234,9 @@ Feature: refactor-first writes a refactor note, refactors on its own, then rebui
 
       <!-- base: 0000000 -->
 
-      ## calc
+      ## Walkthrough
 
-      _critical: judge unsure_
+      ### calc
 
       - [x] ./src/calc.ts#1-2
         add built on the shared op
@@ -259,10 +259,6 @@ Feature: refactor-first writes a refactor note, refactors on its own, then rebui
       """
     And step "implement.health.check" changes nothing
     And step "implement.closing" runs its script
-    And judge step "implement.coverage" answers:
-      """
-      [{"id":"AC-1","answer":"yes","p":0.9}]
-      """
     When the process is driven
     Then the process rests at "build.review.reviewing"
     And "src/calc.ts" contains "op(a, b, -1)"
@@ -282,8 +278,7 @@ Feature: refactor-first writes a refactor note, refactors on its own, then rebui
       gtd(human): refactor.build.review.await-review → refactor.build.review.closing
       gtd(check): refactor.build.review.closing → implement.building
       gtd(agent): implement.building → implement.health.check
-      gtd(check): implement.health.check → implement.coverage
-      gtd(judge): implement.coverage → implement.closing
+      gtd(check): implement.health.check → implement.closing
       gtd(check): implement.closing → build.review.reviewing
       """
     And the output lines of gtd "slices" start with:

package/src/workflows/feature/refactor-review.feature

@@ -303,9 +303,9 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
 
         <!-- base: 0000000 -->
 
-        ## calc
+        ## Walkthrough
 
-        _critical: judge unsure_
+        ### calc
 
         - [ ] ./src/calc.ts#1-2
           add built on the shared op[^why]
@@ -342,9 +342,9 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
 
         <!-- base: 0000000 -->
 
-        ## calc
+        ## Walkthrough
 
-        _critical: judge unsure_
+        ### calc
 
         - [ ] ./src/calc.ts#1-2
           add built on the shared op
@@ -382,9 +382,9 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
 
         <!-- base: 0000000 -->
 
-        ## calc
+        ## Walkthrough
 
-        _critical: judge unsure_
+        ### calc
 
         - [ ] ./src/calc.ts#1-1
           why a shared op?
@@ -475,9 +475,9 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
 
         <!-- base: 0000000 -->
 
-        ## calc
+        ## Walkthrough
 
-        _critical: judge unsure_
+        ### calc
 
         - [ ] ./src/calc.ts#1-2
           add built on the shared op — this should change behaviour, not just structure
@@ -521,9 +521,9 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
 
         <!-- base: 0000000 -->
 
-        ## calc
+        ## Walkthrough
 
-        _critical: judge unsure_
+        ### calc
 
         - [ ] ./src/calc.ts#1-2 rename the helper
           add built on the shared op
@@ -550,9 +550,9 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
 
         <!-- base: 0000000 -->
 
-        ## calc
+        ## Walkthrough
 
-        _critical: judge unsure_
+        ### calc
 
         - [ ] ./src/calc.ts#1-2
           add built on the shared op, lovely work
@@ -571,9 +571,9 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
 
         <!-- base: 0000000 -->
 
-        ## calc
+        ## Walkthrough
 
-        _critical: judge unsure_
+        ### calc
 
         - [ ] ./src/calc.ts#1-2
           add built on the shared op[^q]
@@ -615,10 +615,6 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
         """
       And step "implement.health.check" changes nothing
       And step "implement.closing" runs its script
-      And judge step "implement.coverage" answers:
-        """
-        [{"id":"AC-1","answer":"yes","p":0.9}]
-        """
       When the process is driven
       Then the process rests at "refactor.build.review.await-review"
       Given a file ".gtd/REVIEW.md" with:
@@ -627,9 +623,9 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
 
         <!-- base: 0000000 -->
 
-        ## calc
+        ## Walkthrough
 
-        _critical: judge unsure_
+        ### calc
 
         - [ ] ./src/calc.ts#1-2
           add built on the shared op[^q]
@@ -661,9 +657,9 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
 
         <!-- base: 0000000 -->
 
-        ## calc
+        ## Walkthrough
 
-        _critical: judge unsure_
+        ### calc
 
         - [ ] ./src/calc.ts#1-2
           add built on the shared op[^q]
@@ -702,10 +698,6 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
         """
       And step "implement.health.check" changes nothing
       And step "implement.closing" runs its script
-      And judge step "implement.coverage" answers:
-        """
-        [{"id":"AC-1","answer":"yes","p":0.9}]
-        """
       When the process is driven
       Then the process rests at "refactor.build.review.await-review"
       Given a file ".gtd/REVIEW.md" with:
@@ -714,9 +706,9 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
 
         <!-- base: 0000000 -->
 
-        ## calc
+        ## Walkthrough
 
-        _critical: judge unsure_
+        ### calc
 
         - [ ] ./src/calc.ts#1-2
           add built on the shared op[^n1]
@@ -742,9 +734,9 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
 
         <!-- base: 0000000 -->
 
-        ## calc
+        ## Walkthrough
 
-        _critical: judge unsure_
+        ### calc
 
         - [ ] ./src/calc.ts#1-2
           add built on the shared op[^n1]
@@ -771,9 +763,9 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
 
         <!-- base: 0000000 -->
 
-        ## calc
+        ## Walkthrough
 
-        _critical: judge unsure_
+        ### calc
 
         - [ ] ./src/calc.ts#1-2
           add built on the shared op[^q]
@@ -805,9 +797,9 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
 
         <!-- base: 0000000 -->
 
-        ## calc
+        ## Walkthrough
 
-        _critical: judge unsure_
+        ### calc
 
         - [ ] ./src/calc.ts#1-2
           add built on the shared op[^n1]
@@ -833,9 +825,9 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
 
         <!-- base: 0000000 -->
 
-        ## calc
+        ## Walkthrough
 
-        _critical: judge unsure_
+        ### calc
 
         - [ ] ./src/calc.ts#1-2
           add built on the shared op - this should change behaviour, not just structure[^q]
@@ -867,9 +859,9 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
 
         <!-- base: 0000000 -->
 
-        ## calc
+        ## Walkthrough
 
-        _critical: judge unsure_
+        ### calc
 
         - [ ] ./src/calc.ts#1-2
           add built on the shared op - this should change behaviour, not just structure[^q]
@@ -914,9 +906,9 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
 
         <!-- base: 0000000 -->
 
-        ## calc
+        ## Walkthrough
 
-        _critical: judge unsure_
+        ### calc
 
         - [ ] ./src/calc.ts#1-2
           add built on the shared op[^q]
@@ -948,9 +940,9 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
 
         <!-- base: 0000000 -->
 
-        ## calc
+        ## Walkthrough
 
-        _critical: judge unsure_
+        ### calc
 
         - [ ] ./src/calc.ts#1-2
           add built on the shared op[^q]
@@ -988,10 +980,6 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
         """
       And step "implement.health.check" changes nothing
       And step "implement.closing" runs its script
-      And judge step "implement.coverage" answers:
-        """
-        [{"id":"AC-1","answer":"yes","p":0.9}]
-        """
       When the process is driven
       Then the process rests at "refactor.build.review.await-review"
       Given a file ".gtd/REVIEW.md" with:
@@ -1000,9 +988,9 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
 
         <!-- base: 0000000 -->
 
-        ## calc
+        ## Walkthrough
 
-        _critical: judge unsure_
+        ### calc
 
         - [ ] ./src/calc.ts#1-2
           add built on the shared op, lovely work[^q]
@@ -1034,9 +1022,9 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
 
         <!-- base: 0000000 -->
 
-        ## calc
+        ## Walkthrough
 
-        _critical: judge unsure_
+        ### calc
 
         - [ ] ./src/calc.ts#1-2
           add built on the shared op, lovely work[^q]
@@ -1079,10 +1067,6 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
         """
       And step "implement.health.check" changes nothing
       And step "implement.closing" runs its script
-      And judge step "implement.coverage" answers:
-        """
-        [{"id":"AC-1","answer":"yes","p":0.9}]
-        """
       When the process is driven
       Then the process rests at "refactor.build.review.await-review"
       Given a file ".gtd/REVIEW.md" with:
@@ -1091,9 +1075,9 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
 
         <!-- base: 0000000 -->
 
-        ## calc
+        ## Walkthrough
 
-        _critical: judge unsure_
+        ### calc
 
         - [x] ./src/calc.ts#1-2
           add built on the shared op
@@ -1116,9 +1100,9 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
 
         <!-- base: 0000000 -->
 
-        ## calc
+        ## Walkthrough
 
-        _critical: judge unsure_
+        ### calc
 
         - [ ] ./src/calc.ts#1-2
           add built on the shared op — rename `sign` to `direction`
@@ -1147,9 +1131,9 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
 
         <!-- base: 0000000 -->
 
-        ## calc
+        ## Walkthrough
 
-        _critical: judge unsure_
+        ### calc
 
         - [ ] ./src/calc.ts#1-2
           add built on the shared op — rename `sign` to `direction`
@@ -1180,9 +1164,9 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
       Then the process rests at "refactor.build.review.await-review"
       And ".gtd/REVIEW.md" contains:
         """
-        ## calc
+        ## Walkthrough
 
-        _critical: judge unsure_
+        ### calc
 
         - [ ] ./src/calc.ts#1-2
           add built on the shared op
@@ -1292,10 +1276,6 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
         """
       And step "implement.health.check" changes nothing
       And step "implement.closing" runs its script
-      And judge step "implement.coverage" answers:
-        """
-        [{"id":"AC-1","answer":"yes","p":0.9}]
-        """
       When the process is driven
       Then the process rests at "refactor.build.review.await-review"
       Given a file ".gtd/REVIEW.md" with:
@@ -1304,9 +1284,9 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
 
         <!-- base: 0000000 -->
 
-        ## calc
+        ## Walkthrough
 
-        _critical: judge unsure_
+        ### calc
 
         - [x] ./src/calc.ts#1-2
           add built on the shared op
@@ -1495,9 +1475,9 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
 
         <!-- base: 0000000 -->
 
-        ## calc
+        ## Walkthrough
 
-        _critical: judge unsure_
+        ### calc
 
         - [ ] ./src/calc.ts#1-2
           add built on the shared op[^why]
@@ -1537,9 +1517,9 @@ Feature: the refactor slice is reviewed on its own before the feature is impleme
 
         <!-- base: 0000000 -->
 
-        ## calc
+        ## Walkthrough
 
-        _critical: judge unsure_
+        ### calc
 
         - [ ] ./src/calc.ts#1-2
           add built on the shared op