@pmelab/gtd 56.0.0 → 58.0.0

package/src/workflows/feature/release-flag.ts

@@ -0,0 +1,46 @@
+import { read, refuse } from "../../flows/index.js"
+import { HEADING, markFenced } from "../shared/fences.js"
+import { REQUIREMENTS } from "../shared/steps.js"
+import type { ReleaseFlag } from "../shared/text.js"
+
+const NAME = /^existing:\s*`?([A-Za-z_][\w.-]*)`?$/i
+
+const isFlagHeading = (h: RegExpExecArray | null): boolean =>
+  h !== null && h[1]!.length === 2 && /^release flag$/i.test(h[2]!.trim())
+
+/** The first line under `## Release Flag`, `undefined` without the section. */
+const requestLine = (text: string): string | undefined => {
+  const lines = markFenced(text)
+  const at = lines.findIndex((l) => !l.fenced && isFlagHeading(HEADING.exec(l.line)))
+  if (at === -1) return undefined
+  const body = lines.slice(at + 1)
+  const end = body.findIndex((l) => !l.fenced && HEADING.test(l.line))
+  return (end === -1 ? body : body.slice(0, end)).find((l) => l.line.trim() !== "")?.line.trim()
+}
+
+/** What `text` asks for, or why it cannot be read. No section asks for no flag. */
+export const releaseFlagOf = (text: string): ReleaseFlag | { readonly unreadable: string } => {
+  const line = requestLine(text)
+  if (line === undefined || /^none$/i.test(line)) return { kind: "none" }
+  if (/^new$/i.test(line)) return { kind: "new" }
+  const name = NAME.exec(line)?.[1]
+  return name === undefined ? { unreadable: line } : { kind: "existing", name }
+}
+
+/** Refuse `file` when its `## Release Flag` section is neither `none`, `new` nor `existing: <NAME>`. */
+export const requireReleaseFlag = (file: string): void => {
+  const request = releaseFlagOf(read(file) ?? "")
+  if (!("unreadable" in request)) return
+  refuse(
+    `gtd land: release-flag: ${file}'s "## Release Flag" reads ${JSON.stringify(request.unreadable)} — its first line must be \`new\`, \`existing: <NAME>\` or \`none\`, or leave the section out for no flag`,
+  )
+}
+
+/** What `.gtd/REQUIREMENTS.md` asks for now; a person's unreadable edit is refused. */
+export const requestedFlag = (): ReleaseFlag => {
+  requireReleaseFlag(REQUIREMENTS)
+  return releaseFlagOf(read(REQUIREMENTS) ?? "") as ReleaseFlag
+}
+
+/** Whether the change goes behind a release flag: only then does the seam judge rule. */
+export const flagged = (): boolean => requestedFlag().kind !== "none"

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

@@ -4,15 +4,13 @@ Feature: a feature process ends at the human review
   After the quality lap the process rests at the review gate,
   `.gtd/REVIEW.md`. A sign-off ends the process. A note asking for a change in
   behaviour starts a feedback lap — design, then implement with no new naive
-  pass or seam judge, the hands-on test, the quality lap — and the review
+  pass or seam judge, the quality lap — and the review
   again. Its design keeps a built criterion's ID and numbers
   new behaviour above every ID handed out.
 
   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 a file "src/calc.ts" with:
       """
       export const add = (a: number, b: number) => a + b

package/src/workflows/feature/reviewer-walkthrough.feature

@@ -10,9 +10,7 @@ Feature: a reviewer walks the human through the feature's code
 
   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 a file "src/calc.ts" with:
       """
       export const add = (a: number, b: number) => a + b

package/src/workflows/feature/risk-tier.feature

@@ -54,6 +54,10 @@ Feature: the risk tier is proposed at triage and recorded behind GTD_FLAG_RISK_T
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: the change behaves as described.
@@ -77,6 +81,10 @@ Feature: the risk tier is proposed at triage and recorded behind GTD_FLAG_RISK_T
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: the change behaves as described.
@@ -101,6 +109,10 @@ Feature: the risk tier is proposed at triage and recorded behind GTD_FLAG_RISK_T
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: the change behaves as described.
@@ -134,6 +146,10 @@ Feature: the risk tier is proposed at triage and recorded behind GTD_FLAG_RISK_T
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: the change behaves as described.
@@ -162,6 +178,10 @@ Feature: the risk tier is proposed at triage and recorded behind GTD_FLAG_RISK_T
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: the change behaves as described.
@@ -211,6 +231,10 @@ Feature: the risk tier is proposed at triage and recorded behind GTD_FLAG_RISK_T
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: the change behaves as described.
@@ -261,6 +285,10 @@ Feature: the risk tier is proposed at triage and recorded behind GTD_FLAG_RISK_T
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: the change behaves as described.
@@ -290,6 +318,10 @@ Feature: the risk tier is proposed at triage and recorded behind GTD_FLAG_RISK_T
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: the change behaves as described.

package/src/workflows/feature/seam-rejection.feature

@@ -9,7 +9,6 @@ Feature: rejected naive passes walk one fixed path through the steer gate to the
 
   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_FLAG_RISK_TIER" set to "0"
     And a file "src/calc.ts" with:
@@ -39,6 +38,10 @@ Feature: rejected naive passes walk one fixed path through the steer gate to the
 
       - the greeting module
 
+      ## Release Flag
+
+      new
+
       ## Acceptance Criteria
 
       - AC-1: the change behaves as described.
@@ -84,6 +87,10 @@ Feature: rejected naive passes walk one fixed path through the steer gate to the
 
       - the greeting module
 
+      ## Release Flag
+
+      new
+
       ## Acceptance Criteria
 
       - AC-1: the change behaves as described.

package/src/workflows/feature/seam.feature

@@ -7,7 +7,6 @@ Feature: the naive pass and seam judge decide how a feature is built
 
   Background:
     Given the shipped workflows, as gtd install scaffolds them
-    And an environment variable "GTD_PROTOTYPEROUNDS" set to "0"
     And the gtd config ends with:
       """
       export const config = {
@@ -49,6 +48,10 @@ Feature: the naive pass and seam judge decide how a feature is built
 
       - the greeting module
 
+      ## Release Flag
+
+      new
+
       ## Acceptance Criteria
 
       - AC-1: the change behaves as described.
@@ -242,6 +245,10 @@ Feature: the naive pass and seam judge decide how a feature is built
 
       - the greeting module
 
+      ## Release Flag
+
+      new
+
       ## Acceptance Criteria
 
       - AC-1: the change behaves as described.

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

@@ -234,18 +234,24 @@ interface Seamed {
   readonly outcome: SeamOutcome | Error
 }
 
+const FLAGGED = "# Requirements\n\n## Release Flag\n\nnew\n"
+
 /** Runs `seamBuild` against a scripted context: the judge answers `answer`, every review signs off. */
 const driveSeam = async (
   answer: string,
   stray: Change = change("src/a.ts", "modified"),
   vars: Record<string, string> = {},
   reds = 0,
+  requirements = FLAGGED,
 ): Promise<Seamed> => {
   let red = false
   let redsLeft = reds
   const names: string[] = []
   const stack: string[] = []
-  const files = new Map<string, string>([["src/a.ts", "a"]])
+  const files = new Map<string, string>([
+    ["src/a.ts", "a"],
+    [".gtd/REQUIREMENTS.md", requirements],
+  ])
   let current = "c0"
   const effects: Record<string, () => void> = {
     note: () => void files.set(NOTE, "Seam: a shared op"),
@@ -302,8 +308,8 @@ describe("seamBuild", () => {
     expect(h.names).toEqual(["seam.naive", "seam.check", "seam.judge"])
   })
 
-  it("with flagMode off resolves a vetted pass to land with no judge", async () => {
-    const h = await driveSeam("reject", undefined, { flagMode: "false" })
+  it("with no release flag asked for resolves a vetted pass to land with no judge", async () => {
+    const h = await driveSeam("reject", undefined, {}, 0, "# Requirements\n")
     expect(h.outcome).toEqual({ reference: "abc", base: "c-base", land: true })
     expect(h.names).toEqual(["seam.naive", "seam.check"])
   })
@@ -393,6 +399,7 @@ describe("seamBuild", () => {
 
 describe("implement", () => {
   let lastOptions: Extract<StepRequest, { kind: "agent" }>["options"] | undefined
+  let requirements = FLAGGED
   const building = async (
     reference: string | undefined,
     tier?: "low" | "high",
@@ -403,8 +410,7 @@ describe("implement", () => {
     lastOptions = undefined
     installContext(
       fixtureContext(
-        // The hands-on test has its own scenarios.
-        { vars: { prototypeRounds: "0" } },
+        {},
         {
           step: (request: StepRequest) => {
             requests.push(request)
@@ -415,6 +421,7 @@ describe("implement", () => {
           pushScope: () => undefined,
           popScope: () => undefined,
           changesSince: () => [],
+          read: (path: string) => (path === ".gtd/REQUIREMENTS.md" ? requirements : undefined),
         },
       ),
     )
@@ -507,9 +514,14 @@ describe("implement", () => {
     expect(prompt).toContain("otherwise put")
   })
 
-  it("amend on tier low says to add no release flag", async () => {
-    const prompt = await building(undefined, "low", true)
-    expect(prompt).toContain("Add no release flag")
-    expect(prompt).toContain("amend")
+  it("asks for no release flag when the requirements ask for none, whatever the tier", async () => {
+    requirements = "# Requirements\n"
+    try {
+      const prompt = await building(undefined, "high", true)
+      expect(prompt).toContain("Add no release flag")
+      expect(prompt).toContain("amend")
+    } finally {
+      requirements = FLAGGED
+    }
   })
 })

package/src/workflows/feature/seam.ts

@@ -3,6 +3,7 @@ import {
   agent,
   applyScript,
   changes,
+  changesSince,
   check,
   codeChanges,
   env,
@@ -14,6 +15,7 @@ import {
   read,
   refuse,
   removeScript,
+  restoreScript,
   run,
   scope,
   vars,
@@ -22,11 +24,10 @@ import {
   type DiffShapeResult,
   type KeptTip,
 } from "../../flows/index.js"
-import { coder, FEEDBACK, PROTOTYPE, REFACTOR_NOTE, REQUIREMENTS } from "../shared/steps.js"
+import { coder, FEEDBACK, NAIVE_TEST, REFACTOR_NOTE, REQUIREMENTS } from "../shared/steps.js"
 import * as t from "../shared/text.js"
 import { defaults } from "../shared/vars.js"
 import { green } from "./green.js"
-import { prototypeTest } from "./prototype.js"
 import { criterionIds, requireCriteria, requireCriteriaFrozen } from "./criteria.js"
 import {
   COMMENT,
@@ -36,7 +37,8 @@ import {
   reviewedRefactor,
 } from "./refactor.js"
 import { isCode } from "../shared/review.js"
-import { flagModeOn } from "../shared/options.js"
+import { naiveTestOn } from "../shared/options.js"
+import { flagged, requestedFlag } from "./release-flag.js"
 import type { RiskTier } from "./tier.js"
 
 /** Naive-pass retries after a `reject` or a red suite; the next one rests at `seam.steer`. */
@@ -53,7 +55,7 @@ export const judgeSeam = (tip: KeptTip): Promise<DiffShapeResult> =>
     exempt: tip.changes.filter((c) => c.status === "added").map((c) => c.path),
   })
 
-export const naivePass = (retry?: t.NaiveRetry): Promise<void> =>
+export const naivePass = (retry?: t.NaiveRetry | t.NaiveTested): Promise<void> =>
   t.agentWithSkills("naive", t.naivePassPrompt(retry), {
     label: retry === undefined ? "Writing the naive pass" : "Rewriting the naive pass",
     keep: true,
@@ -186,10 +188,9 @@ const build = async (options: ImplementOptions): Promise<void> => {
     "building",
     t.implementBuildingPrompt(
       options.reference,
-      options.tier,
       options.amend,
       options.afterRefactor,
-      flagModeOn(),
+      requestedFlag(),
       options.rebuild,
     ),
     {
@@ -226,9 +227,8 @@ export const implementing = (options: ImplementOptions): Promise<readonly string
     if (built) await build(options)
     else requireCriteriaFrozen(REQUIREMENTS)
     await green()
-    await prototypeTest()
     const ids = criterionIds(read(REQUIREMENTS) ?? "")
-    await run("closing", removeScript([REQUIREMENTS, REFACTOR_NOTE, PROTOTYPE]), {
+    await run("closing", removeScript([REQUIREMENTS, REFACTOR_NOTE]), {
       label: "Closing out the implementation",
     })
     return ids
@@ -237,14 +237,14 @@ export const implementing = (options: ImplementOptions): Promise<readonly string
 interface Decision {
   readonly reference: string
   readonly tip: KeptTip
-  /** Absent on `land` (or with `flagMode` off, unjudged): the pass itself is the implementation. */
+  /** Absent on `land` (or unjudged, with no release flag asked for): the pass itself is the implementation. */
   readonly shape?: DiffShapeResult
 }
 
 /** Resolves `true` when the human steered (edited), `false` on a clean overrule. */
 const steer = async (retry: t.NaiveRetry): Promise<boolean> => {
   await human("steer", {
-    message: t.seamSteerMessage(retry, flagModeOn()),
+    message: t.seamSteerMessage(retry, flagged()),
     label: "Steer or overrule the naive pass",
     file: REQUIREMENTS,
     acceptClean: true,
@@ -277,7 +277,7 @@ const budget = (): ((next: t.NaiveRetry) => Promise<Verdict>) => {
 }
 
 interface Vetting {
-  readonly again: ReturnType<typeof budget>
+  again: ReturnType<typeof budget>
   /** Set once a human overrules a test fault: the rule does not fit this change, so later passes skip it. */
   waived: boolean
 }
@@ -304,16 +304,62 @@ const ruled = async (tip: KeptTip, again: Vetting["again"]): Promise<Decision |
   return next.kind === "overruled" ? { reference: tip.hash, tip } : next
 }
 
+/** Back to `before`: every code path, and the notes file. `.gtd/` edits (the requirements) stay. */
+const untryScript = (before: string): string => {
+  const code = changesSince(before).filter((c) => isCode(c.path))
+  return restoreScript(
+    head(),
+    {
+      restore: code.filter((c) => c.status !== "added").map((c) => c.path),
+      remove: [...code.filter((c) => c.status === "added").map((c) => c.path), NAIVE_TEST],
+    },
+    before,
+  )
+}
+
+/**
+ * A person tries the green pass `tip` in the working tree. Resolves
+ * `undefined` on a clean landing (signed off), else what they sent back;
+ * either way the pass, their code edits and the notes file leave the tree.
+ */
+const tried = async (tip: KeptTip): Promise<t.NaiveTested | undefined> => {
+  const before = head()
+  await run("applying", applyScript(tip.hash, FEEDBACK, t.naiveApplyFailure(tip.hash), [".gtd"]), {
+    label: "Applying the naive pass to try it",
+  })
+  await human("try", {
+    message: t.naiveTryMessage(flagged()),
+    label: "Try the naive pass",
+    file: NAIVE_TEST,
+    acceptClean: true,
+  })
+  const landed = changes()
+  const edits = landed.some((c) => isCode(c.path)) ? head() : undefined
+  const notes = read(NAIVE_TEST)?.trim() || undefined
+  if (landed.some((c) => c.path === REQUIREMENTS)) requireCriteria(REQUIREMENTS)
+  await run("restoring", untryScript(before), { label: "Taking the naive pass out again" })
+  return landed.length === 0 ? undefined : { tested: tip.hash, notes, edits }
+}
+
 const decide = (): Promise<Decision> =>
   scope("seam", async () => {
     const vetting: Vetting = { again: budget(), waived: false }
-    let retry: t.NaiveRetry | undefined
+    let retry: t.NaiveRetry | t.NaiveTested | undefined
     for (;;) {
       await naivePass(retry)
       const tip = kept("naive")!
+      const verdict = await vetted(tip, vetting)
+      if (verdict === undefined && naiveTestOn()) {
+        const sentBack = await tried(tip)
+        if (sentBack !== undefined) {
+          // A person's feedback is no failed attempt: the next pass gets a full retry budget.
+          vetting.again = budget()
+          retry = sentBack
+          continue
+        }
+      }
       const outcome =
-        (await vetted(tip, vetting)) ??
-        (flagModeOn() ? await ruled(tip, vetting.again) : { reference: tip.hash, tip })
+        verdict ?? (flagged() ? await ruled(tip, vetting.again) : { reference: tip.hash, tip })
       if (!("kind" in outcome)) return outcome
       retry = outcome.kind === "retry" ? outcome.retry : undefined
     }

package/src/workflows/feature/standards.feature

@@ -11,9 +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 ""
-    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

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

@@ -30,16 +30,9 @@ describe("the shipped workflow factories", () => {
     })
   })
 
-  it("default flagMode on and lay a boolean factory option over it as a string", () => {
-    expect(defaults.flagMode).toBe("true")
-    expect(configure(feature({ flagMode: false }))).toMatchObject({
-      ok: true,
-      build: { defaults: { flagMode: "false" } },
-    })
-    expect(configure(review({ flagMode: true }))).toMatchObject({
-      ok: true,
-      build: { defaults: { flagMode: "true" } },
-    })
+  it("refuse the removed flagMode option", () => {
+    expect(defaults.flagMode).toBeUndefined()
+    expect(configure(feature({ flagMode: false } as never))).toMatchObject({ ok: false })
   })
 
   it("declare flag_risk_tier off by default; it is no factory option", () => {

package/src/workflows/shared/options.ts

@@ -24,11 +24,10 @@ export const ShippedOptions = Schema.Struct({
   seamAllow: setting,
   qualityReviews: setting,
   refactorQualityReviews: setting,
-  prototypeRounds: setting,
   testCommand: setting,
   plannerModel: setting,
   coderModel: setting,
-  flagMode: Schema.optionalWith(Schema.Boolean, { exact: true }),
+  naiveTest: Schema.optionalWith(Schema.Boolean, { exact: true }),
 })
 
 export type ShippedOptions = Schema.Schema.Encoded<typeof ShippedOptions>
@@ -45,11 +44,11 @@ const over = (
   ),
 })
 
-/** The `flagMode` setting, pinned at process start. Anything but true/false fails rather than guess a side. */
-export const flagModeOn = (): boolean => {
-  const value = vars.flagMode ?? defaults.flagMode!
+/** The `naiveTest` setting, pinned at process start. Anything but true/false fails rather than guess. */
+export const naiveTestOn = (): boolean => {
+  const value = vars.naiveTest ?? defaults.naiveTest!
   if (value !== "true" && value !== "false")
-    refuse(`gtd: flagMode must be "true" or "false", got ${JSON.stringify(value)}`)
+    refuse(`gtd: naiveTest must be "true" or "false", got ${JSON.stringify(value)}`)
   return value === "true"
 }
 

package/src/workflows/shared/prose.ts

@@ -88,12 +88,6 @@ 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,10 +29,6 @@ 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,11 +33,6 @@ 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

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