@pmelab/gtd 56.0.0 → 58.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "56.0.0",
+  "version": "58.0.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {

package/src/workflows/feature/acceptance-criteria.feature

@@ -39,6 +39,10 @@ Feature: acceptance criteria carry stable IDs, and a sketch that states clear on
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: `greeting` reads "Hello, world".
@@ -67,6 +71,10 @@ Feature: acceptance criteria carry stable IDs, and a sketch that states clear on
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - `greeting` reads "Hello, world".
@@ -82,6 +90,10 @@ Feature: acceptance criteria carry stable IDs, and a sketch that states clear on
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: `greeting` reads "Hello, world".
@@ -98,6 +110,10 @@ Feature: acceptance criteria carry stable IDs, and a sketch that states clear on
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: `greeting` reads "Hello, world".
@@ -131,6 +147,10 @@ Feature: acceptance criteria carry stable IDs, and a sketch that states clear on
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: `greeting` reads "Hi".
@@ -150,6 +170,10 @@ Feature: acceptance criteria carry stable IDs, and a sketch that states clear on
         """
         # Requirements
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: `greeting` reads "Hello, world".
@@ -178,6 +202,10 @@ Feature: acceptance criteria carry stable IDs, and a sketch that states clear on
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: `greeting` reads "Hi".
@@ -226,6 +254,10 @@ Feature: acceptance criteria carry stable IDs, and a sketch that states clear on
 
         - the greeting module
 
+        ## Release Flag
+
+        new
+
         ## Acceptance Criteria
 
         - AC-1: `greeting` reads "Hello, world".

package/src/workflows/feature/criteria-coverage.feature

@@ -7,9 +7,7 @@ Feature: the criteria-coverage lens checks the change's tests against its criter
 
   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 "criteria-coverage"
-    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/criteria.test.ts

@@ -1,13 +1,6 @@
 import { describe, expect, it } from "vitest"
 import type { Change } from "../../flows/index.js"
-import {
-  criteriaOf,
-  criterionIds,
-  handsOnIds,
-  hasImpact,
-  statedCriteria,
-  unstableIds,
-} from "./criteria.js"
+import { criteriaOf, criterionIds, hasImpact, statedCriteria, unstableIds } from "./criteria.js"
 
 const added = (path: string, after: string): Change => ({
   path,
@@ -55,17 +48,6 @@ describe("criteriaOf", () => {
     ).toEqual([{ id: "AC-1", text: "exits 2 when config is bad - missing file" }])
   })
 
-  it("reads the (no hands-on) tag between an ID and its colon", () => {
-    expect(
-      criteriaOf(
-        "## Acceptance Criteria\n\n- AC-1: runs\n- AC-2 (no hands-on): the prompt says so\n",
-      ),
-    ).toEqual([
-      { id: "AC-1", text: "runs" },
-      { id: "AC-2", text: "the prompt says so", noHandsOn: true },
-    ])
-  })
-
   it("is undefined without the section", () => {
     expect(criteriaOf("# R\n\n- AC-1: x\n")).toBeUndefined()
   })
@@ -84,19 +66,6 @@ describe("statedCriteria", () => {
     })
   })
 
-  it("keeps a stated (no hands-on) tag, renumbered or not", () => {
-    const tagged = "## Acceptance criteria\n\n- AC-1: a\n- AC-2 (no hands-on): b\n"
-    expect(statedCriteria([added("TODO.md", tagged)], "abc")?.criteria).toEqual([
-      { id: "AC-1", text: "a" },
-      { id: "AC-2", text: "b", noHandsOn: true },
-    ])
-    const partial = "## Acceptance criteria\n\n- a\n- AC-7 (no hands-on): b\n"
-    expect(statedCriteria([added("TODO.md", partial)], "abc")?.criteria).toEqual([
-      { id: "AC-1", text: "a" },
-      { id: "AC-2", text: "b", noHandsOn: true },
-    ])
-  })
-
   it("renumbers when the stated IDs are partial or clash", () => {
     const sketch = [added("TODO.md", "## Acceptance criteria\n\n- AC-4: a\n- b\n")]
     expect(statedCriteria(sketch, "abc")?.criteria).toEqual([
@@ -144,15 +113,6 @@ describe("criterionIds", () => {
   })
 })
 
-describe("handsOnIds", () => {
-  const requirements =
-    "## Acceptance Criteria\n\n- AC-1: a\n- AC-2 (no hands-on): b\n- AC-3: c\n- AC-4 (no hands-on): d\n"
-
-  it("leaves out every criterion tagged (no hands-on)", () => {
-    expect(handsOnIds(requirements)).toEqual(["AC-1", "AC-3"])
-  })
-})
-
 describe("unstableIds", () => {
   const ids = { closed: ["AC-1", "AC-3"], used: ["AC-1", "AC-2", "AC-3"] }
 

package/src/workflows/feature/criteria.ts

@@ -13,12 +13,11 @@ import {
 import { HEADING, ITEM, markFenced } from "../shared/fences.js"
 import { planner, REQUIREMENTS } from "../shared/steps.js"
 import * as t from "../shared/text.js"
+import { requireReleaseFlag } from "./release-flag.js"
 
 export interface Criterion {
   readonly id: string
   readonly text: string
-  /** Tagged `(no hands-on)`: its tests prove it, so the hands-on test skips it. */
-  readonly noHandsOn?: true
 }
 
 /** Acceptance criteria the human's sketch stated outright, ready to normalise. */
@@ -33,13 +32,9 @@ export interface StatedCriteria {
 /** Below this the judge's `yes` is not trusted: a wrong skip builds against criteria nobody can check. */
 const CLEAR_MIN_P = 0.8
 
-const ID = /^(AC-\d+)(\s*\(no hands-on\))?:\s*(.*)$/
+const ID = /^(AC-\d+):\s*(.*)$/
 
-const criterion = (id: RegExpExecArray, as = id[1]!): Criterion => ({
-  id: as,
-  text: id[3]!,
-  ...(id[2] === undefined ? {} : { noHandsOn: true }),
-})
+const criterion = (id: RegExpExecArray, as = id[1]!): Criterion => ({ id: as, text: id[2]! })
 
 /** The list items under the first heading `title` matches (at `level` when given), up to the next heading; wrapped lines joined, fenced lines ignored. */
 const listUnder = (text: string, title: RegExp, level?: number): string[] | undefined => {
@@ -83,12 +78,6 @@ export const criteriaOf = (text: string): readonly Criterion[] | undefined =>
 export const criterionIds = (text: string): string[] =>
   (criteriaOf(text) ?? []).map((c) => c.id).filter((id) => id !== "")
 
-/** The ID'd criteria of `text` a person can try by hand: none tagged `(no hands-on)`. */
-export const handsOnIds = (text: string): string[] => {
-  const tagged = (criteriaOf(text) ?? []).filter((c) => c.noHandsOn).map((c) => c.id)
-  return criterionIds(text).filter((id) => !tagged.includes(id))
-}
-
 /** Items numbered `AC-1`…, unless every one already carries its own distinct ID. */
 const numbered = (items: readonly string[]): Criterion[] => {
   const ids = items.map((item) => ID.exec(item))
@@ -149,16 +138,20 @@ export const requireCriteria = (file: string): void => {
 const isImpactHeading = (h: RegExpExecArray | null): boolean =>
   h !== null && h[1]!.length === 2 && /^impact$/i.test(h[2]!.trim())
 
+// The skip path's impact turn may write both: a sketch can ask for a flag.
+const isImpactTurnHeading = (h: RegExpExecArray | null): boolean =>
+  h !== null && h[1]!.length === 2 && /^(impact|release flag)$/i.test(h[2]!.trim())
+
 /** Whether `text` has an unfenced, level-2 `## Impact` heading. */
 export const hasImpact = (text: string): boolean =>
   markFenced(text).some((l) => !l.fenced && isImpactHeading(HEADING.exec(l.line)))
 
-/** `text` without its `## Impact` section, whitespace collapsed. */
+/** `text` without its `## Impact` and `## Release Flag` sections, whitespace collapsed. */
 const withoutImpact = (text: string): string => {
   let inImpact = false
   const kept = markFenced(text).filter((l) => {
     const h = l.fenced ? null : HEADING.exec(l.line)
-    if (h !== null && h[1]!.length <= 2) inImpact = isImpactHeading(h)
+    if (h !== null && h[1]!.length <= 2) inImpact = isImpactTurnHeading(h)
     return !inImpact
   })
   return kept
@@ -184,13 +177,13 @@ export const requireImpact = (file: string): void => {
   )
 }
 
-/** Refuse a turn that changed `file` beyond its `## Impact` section. */
+/** Refuse a turn that changed `file` beyond its `## Impact` and `## Release Flag` sections. */
 export const requireImpactOnly = (file: string): void => {
   const change = changes().get(file)
   if (change === undefined) return
   if (withoutImpact(change.before ?? "") === withoutImpact(change.after ?? "")) return
   refuse(
-    `gtd land: impact-only: this turn may only add "## Impact" to ${file} — restore everything else`,
+    `gtd land: impact-only: this turn may only add "## Impact" (and "## Release Flag") to ${file} — restore everything else`,
   )
 }
 
@@ -252,6 +245,7 @@ const impact = async (): Promise<void> => {
   requireCriteriaFrozen(REQUIREMENTS)
   requireImpact(REQUIREMENTS)
   requireImpactOnly(REQUIREMENTS)
+  requireReleaseFlag(REQUIREMENTS)
 }
 
 /**

package/src/workflows/feature/fast-path.feature

@@ -8,7 +8,6 @@ Feature: a trivial change takes the same few beats at either risk tier
 
   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_FLAG_RISK_TIER" set to "1"
     And a file "src/greeting.ts" with:
@@ -42,6 +41,10 @@ Feature: a trivial change takes the same few beats at either risk tier
 
       - the greeting module
 
+      ## Release Flag
+
+      new
+
       ## Acceptance Criteria
 
       - AC-1: the change behaves as described.

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

@@ -302,38 +302,9 @@ describe("an in-flight process from before the architecture path was removed", (
   })
 })
 
-describe("flagMode", () => {
-  const config = (workflow: string): string =>
-    [
-      'import { feature } from "@pmelab/gtd/workflows/feature"',
-      'export { summary, steering, skills, access } from "@pmelab/gtd/workflows/feature"',
-      `export default ${workflow}`,
-      "",
-    ].join("\n")
-
-  const designed = async (workflow: string, env: Record<string, string> = {}) => {
-    const repo = testRepo({ workflow, env: { GTD_QUALITYREVIEWS: "", ...env } })
-    repo.write("src/calc.ts", CALC)
-    repo.commit("feat: add calculator")
-    repo.write("TODO.md", "# Add subtract\n")
-    return repo.drive({
-      unwind: () => undefined,
-      "start-gate.check": () => undefined,
-      "design.triage": (_, r) =>
-        r.write(
-          ".gtd/REQUIREMENTS.md",
-          "# Requirements\n\n## Concerns\n\n### S\n\n- `s`\n\n## Impact\n\n- the module\n\n## Acceptance Criteria\n\n- AC-1: done\n",
-        ),
-      "design.gate.answer": () => undefined,
-    })
-  }
-
-  it("set on explicitly, runs the naive pass like the default", async () => {
-    expect((await designed(config("feature({ flagMode: true })"))).state).toBe("seam.naive")
-  })
-
-  it("off through GTD_FLAGMODE=false, lands the naive pass with no seam judge", async () => {
-    const repo = testRepo({ workflow: CONFIG_SCAFFOLD, env: { GTD_FLAGMODE: "false" } })
+describe("release flag", () => {
+  it("with no Release Flag section, lands the naive pass with no seam judge", async () => {
+    const repo = testRepo({ workflow: CONFIG_SCAFFOLD })
     repo.write("src/calc.ts", CALC)
     repo.commit("feat: add calculator")
     repo.write("TODO.md", "# Add subtract\n")
@@ -357,13 +328,6 @@ describe("flagMode", () => {
     expect(repo.read("src/calc.ts")).toBe(`${CALC}// naive\n`)
     expect(repo.subjects().some((subject) => subject.includes("seam.judge"))).toBe(false)
   })
-
-  it("refuses a value other than true or false before the process starts", async () => {
-    const repo = testRepo({ workflow: CONFIG_SCAFFOLD, env: { GTD_FLAGMODE: "off" } })
-    repo.write("TODO.md", "# Add subtract\n")
-    await expect(repo.drive({})).rejects.toThrow('flagMode must be "true" or "false", got "off"')
-    expect(repo.subjects()).toEqual(["chore: initial commit"])
-  })
 })
 
 // pins the public re-exports from the feature entry point

package/src/workflows/feature/feature.ts

@@ -9,7 +9,7 @@ import {
   start,
 } from "../../flows/index.js"
 import { gate } from "../shared/health.js"
-import { flagModeOn, shipped } from "../shared/options.js"
+import { naiveTestOn, shipped } from "../shared/options.js"
 import { FEEDBACK, REQUIREMENTS } from "../shared/steps.js"
 import { refusePendingHandOff } from "../shared/tail.js"
 import * as t from "../shared/text.js"
@@ -23,16 +23,15 @@ import {
 } from "./criteria.js"
 import { design } from "./planning.js"
 import { buildTail, isCode, reUnwind, type ReviewOutcome } from "../shared/review.js"
-import { prototypeRounds } from "./prototype.js"
 import { implement, implementing, seamBuild } from "./seam.js"
 import { recordRisk, riskTierOn } from "./tier.js"
 
 // The ordinary start. Any change to the tree starts a process: `idle` →
 // `unwind` reverts the sketch (its intent survives in history) → a
-// green-baseline gate → design → a naive pass, judged with `flagMode` on: it
+// green-baseline gate → design → a naive pass, tried by a person with
+// `naiveTest` on and judged when the requirements ask for a release flag: it
 // lands as the implementation, or (refactoring first when the judge asks) is
-// built fresh from → the health loop → a hands-on test of every criterion,
-// fixed and re-tested → the triaged quality lap and its finding gate → a
+// built fresh from → the health loop → the triaged quality lap and its finding gate → a
 // reviewer's walkthrough of the whole change for the human, which signs off
 // (the episode ends back at `idle`) or sends a design → implement lap.
 
@@ -47,7 +46,7 @@ export const unwind = (): Promise<void> => {
 export { reUnwind }
 
 /**
- * A naive pass (judged only with `flagMode` on), then implement and the
+ * A naive pass (judged only when a release flag is asked for), then implement and the
  * quality lap, then the review; design must have run since `firstBase`.
  */
 export const buildFeature = async (firstBase: string): Promise<void> => {
@@ -140,8 +139,7 @@ export const ordinaryStart = async (): Promise<void> => {
   await human("idle", { message: t.idleMessage(), label: "Idle", file: ".gtd/TODO.md" })
   refusePendingHandOff()
   // Read right after idle, so a bad value refuses the landing that would pin it.
-  flagModeOn()
-  prototypeRounds()
+  naiveTestOn()
   const stated = statedCriteria(changes(), head())
   await unwind()
   if (changes(FEEDBACK).some((c) => c.status !== "deleted")) {

package/src/workflows/feature/lens-models.feature

@@ -11,8 +11,6 @@ Feature: each quality lens runs on its own model hint
       import { feature } from "@pmelab/gtd/workflows/feature"
       export { summary, steering, skills, access } from "@pmelab/gtd/workflows/feature"
       export default feature({
-        flagMode: false,
-        prototypeRounds: "0",
         qualityReviews: "correctness, conventions, test-audit=opus",
       })
       """

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

@@ -11,9 +11,7 @@ Feature: the quality lap's findings are triaged, then decided at the finding gat
 
   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:
       """
       export const add = (a: number, b: number) => a + b

package/src/workflows/feature/naive-acceptance.feature

@@ -31,6 +31,10 @@ Feature: a naive pass ends only when its tests reach no file it added and the su
 
       - the greeting module
 
+      ## Release Flag
+
+      new
+
       ## Acceptance Criteria
 
       - AC-1: `subtract(5, 3)` returns 2.