@pmelab/gtd 30.0.0 → 31.0.0

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

@@ -0,0 +1,106 @@
+import { describe, expect, it } from "vitest"
+import type { Change } from "../../flows/index.js"
+import { criteriaOf, statedCriteria } from "./criteria.js"
+
+const added = (path: string, after: string): Change => ({
+  path,
+  status: "added",
+  before: undefined,
+  after,
+})
+
+describe("criteriaOf", () => {
+  it("reads ID'd items, joining wrapped lines, and stops at the next section", () => {
+    expect(
+      criteriaOf(
+        "# R\n\n## Acceptance Criteria\n\n- AC-1: one\n  continued\n- two\n\n## Notes\n\n- AC-9: not one\n",
+      ),
+    ).toEqual([
+      { id: "AC-1", text: "one continued" },
+      { id: "", text: "two" },
+    ])
+  })
+
+  it("skips fenced lines, reads an indented item, and stops at a subheading", () => {
+    expect(
+      criteriaOf(
+        "## Acceptance Criteria\n\n- AC-1: runs\n\n```sh\n# setup\n- key: v\n```\n - AC-2: two\n\n### Notes\n\n- note\n",
+      ),
+    ).toEqual([
+      { id: "AC-1", text: "runs" },
+      { id: "AC-2", text: "two" },
+    ])
+  })
+
+  it("reads only the level-2 section and joins an unindented wrapped line", () => {
+    expect(
+      criteriaOf(
+        "### Acceptance criteria\n\n- x\n\n## Acceptance Criteria\n\n- AC-1: exits 2 when the config\nfile is missing\n",
+      ),
+    ).toEqual([{ id: "AC-1", text: "exits 2 when the config file is missing" }])
+  })
+
+  it("folds a nested sub-bullet into its criterion", () => {
+    expect(
+      criteriaOf(
+        "## Acceptance Criteria\n\n- AC-1: exits 2 when config is bad\n  - missing file\n",
+      ),
+    ).toEqual([{ id: "AC-1", text: "exits 2 when config is bad - missing file" }])
+  })
+
+  it("is undefined without the section", () => {
+    expect(criteriaOf("# R\n\n- AC-1: x\n")).toBeUndefined()
+  })
+})
+
+describe("statedCriteria", () => {
+  it("numbers a stated checklist from AC-1", () => {
+    const sketch = [added("TODO.md", "# T\n\n### Acceptance criteria:\n\n- [ ] a\n* b\n\nprose\n")]
+    expect(statedCriteria(sketch, "abc")).toMatchObject({
+      path: "TODO.md",
+      commit: "abc",
+      criteria: [
+        { id: "AC-1", text: "a" },
+        { id: "AC-2", text: "b" },
+      ],
+    })
+  })
+
+  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([
+      { id: "AC-1", text: "a" },
+      { id: "AC-2", text: "b" },
+    ])
+  })
+
+  it("ignores a list the sketch left unchanged, a file other than TODO.md, a sketch with more in it, and an ambiguous pair", () => {
+    const list = "## Acceptance criteria\n\n- a\n"
+    expect(
+      statedCriteria(
+        [{ path: "TODO.md", status: "modified", before: list, after: `${list}\nmore\n` }],
+        "abc",
+      ),
+    ).toBeUndefined()
+    expect(
+      statedCriteria(
+        [
+          {
+            path: "TODO.md",
+            status: "modified",
+            before: `${list}- \n`,
+            after: `${list}- \n\nmore\n`,
+          },
+        ],
+        "abc",
+      ),
+    ).toBeUndefined()
+    expect(statedCriteria([added("docs/guide.md", list)], "abc")).toBeUndefined()
+    expect(
+      statedCriteria([added("TODO.md", list), added("src/a.ts", "x\n")], "abc"),
+    ).toBeUndefined()
+    expect(
+      statedCriteria([added("TODO.md", list), added(".gtd/TODO.md", list)], "abc"),
+    ).toBeUndefined()
+  })
+})

package/src/workflows/feature/criteria.ts

@@ -0,0 +1,168 @@
+import {
+  answered,
+  changes,
+  judge,
+  read,
+  refuse,
+  run,
+  scope,
+  type Change,
+} from "../../flows/index.js"
+import { markFenced } from "../shared/fences.js"
+import { REQUIREMENTS } from "../shared/steps.js"
+import * as t from "../shared/text.js"
+
+export interface Criterion {
+  readonly id: string
+  readonly text: string
+}
+
+/** Acceptance criteria the human's sketch stated outright, ready to normalise. */
+export interface StatedCriteria {
+  readonly path: string
+  readonly commit: string
+  /** The file as the sketch left it: `unwind` reverts it out of the tree. */
+  readonly text: string
+  readonly criteria: readonly Criterion[]
+}
+
+/** 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 HEADING = /^ {0,3}(#{1,6})\s+(.*?)\s*#*\s*$/
+const ITEM = /^ ?(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]\s+)?(.*)$/
+const ID = /^(AC-\d+):\s*(.*)$/
+
+/** 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 => {
+  const lines = markFenced(text)
+  const at = lines.findIndex((l) => {
+    const heading = l.fenced ? null : HEADING.exec(l.line)
+    return (
+      heading !== null &&
+      (level === undefined || heading[1]!.length === level) &&
+      title.test(heading[2]!)
+    )
+  })
+  if (at === -1) return undefined
+  const items: string[] = []
+  let open = false
+  for (const { line, fenced } of lines.slice(at + 1)) {
+    if (fenced) {
+      open = false
+      continue
+    }
+    if (HEADING.test(line)) break
+    const item = ITEM.exec(line)
+    if (item !== null) {
+      items.push(item[1]!.trim())
+      open = true
+    } else if (open && line.trim() !== "") {
+      items[items.length - 1] = `${items.at(-1)!} ${line.trim()}`.trim()
+    } else open = false
+  }
+  return items
+}
+
+/** The `- AC-<n>: …` list of `## Acceptance Criteria`, or `undefined` when the section is missing. */
+export const criteriaOf = (text: string): readonly Criterion[] | undefined =>
+  listUnder(text, /^acceptance criteria$/i, 2)?.map((item) => {
+    const id = ID.exec(item)
+    return id === null ? { id: "", text: item } : { id: id[1]!, text: id[2]! }
+  })
+
+/** 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))
+  const own = ids.every((id) => id !== null) && new Set(ids.map((id) => id![1])).size === ids.length
+  return items.map((item, i) =>
+    own
+      ? { id: ids[i]![1]!, text: ids[i]![2]! }
+      : { id: `AC-${i + 1}`, text: item.replace(ID, "$2") },
+  )
+}
+
+const STATED = /^acceptance criteria:?$/i
+
+const statedItems = (text: string | undefined): string[] =>
+  text === undefined ? [] : (listUnder(text, STATED) ?? []).filter((item) => item !== "")
+
+/**
+ * The criteria a `TODO.md` in the sketch `sketch` (the idle turn's changes)
+ * added or changed under an `Acceptance criteria` heading. More than one such
+ * file is ambiguous, and any other change in the sketch is input only triage
+ * folds in, so none.
+ */
+export const statedCriteria = (
+  sketch: readonly Change[],
+  commit: string,
+): StatedCriteria | undefined => {
+  const found = sketch.flatMap((change) => {
+    if (!/(^|\/)TODO\.md$/.test(change.path) || change.after === undefined) return []
+    const items = statedItems(change.after)
+    if (items.length === 0 || items.join("\n") === statedItems(change.before).join("\n")) return []
+    return [{ path: change.path, commit, text: change.after, criteria: numbered(items) }]
+  })
+  return found.length === 1 && sketch.length === 1 ? found[0] : undefined
+}
+
+const listing = (criteria: readonly Criterion[]): string => criteria.map(t.criterionLine).join("\n")
+
+/** Refuse a turn that leaves `file` without ID'd acceptance criteria. A deleted file is `requireProgress`'s call. */
+export const requireCriteria = (file: string): void => {
+  const text = read(file)
+  if (text === undefined) return
+  const criteria = criteriaOf(text) ?? []
+  const unnamed = criteria.filter((c) => c.id === "")
+  const ids = criteria.map((c) => c.id).filter((id) => id !== "")
+  const twice = ids.filter((id, i) => ids.indexOf(id) !== i)
+  if (criteria.length > 0 && unnamed.length === 0 && twice.length === 0) return
+  const why =
+    criteria.length === 0
+      ? `no "## Acceptance Criteria" list`
+      : unnamed.length > 0
+        ? `${unnamed.length} criterion without an ID:\n${unnamed.map((c) => `  - ${c.text}`).join("\n")}`
+        : `duplicate IDs: ${[...new Set(twice)].join(", ")}`
+  refuse(
+    `gtd land: acceptance-criteria: ${file} has ${why} — list every criterion under "## Acceptance Criteria" as "- AC-<n>: <checkable criterion>", each ID unique and never reused`,
+  )
+}
+
+/** Refuse a turn that changed the acceptance criteria in `file`: after the design gate only another design lap may. */
+export const requireCriteriaFrozen = (file: string): void => {
+  const change = changes().get(file)
+  if (change === undefined) return
+  const before = listing(criteriaOf(change.before ?? "") ?? [])
+  if (before === listing(criteriaOf(change.after ?? "") ?? [])) return
+  refuse(
+    `gtd land: criteria-frozen: the acceptance criteria in ${file} are settled — restore them; only a design lap changes them`,
+  )
+}
+
+/** Whether the judge trusts `stated` as clear and checkable, every criterion of it. Truncated evidence never is. */
+const clear = async (stated: StatedCriteria): Promise<boolean> => {
+  const { answers, truncated } = await judge("clear", {
+    questions: [t.clearCriteriaQuestion],
+    evidence: { criteria: listing(stated.criteria), sketch: stated.text },
+    message: t.clearCriteriaMessage(),
+    label: "Judging the stated acceptance criteria",
+  })
+  return truncated.length === 0 && answered(answers.clear, "yes", CLEAR_MIN_P)
+}
+
+/**
+ * The skip path: when the sketch stated clear, checkable criteria, write them
+ * to `.gtd/REQUIREMENTS.md` as they are and resolve `true` — no triage, no
+ * design gate. `false` when design must run.
+ */
+export const skipDesign = (stated: StatedCriteria | undefined): Promise<boolean> =>
+  stated === undefined
+    ? Promise.resolve(false)
+    : scope("design", async () => {
+        if (!(await clear(stated))) return false
+        await run("normalise", t.normaliseCriteriaScript(stated), {
+          label: "Recording the stated acceptance criteria",
+          file: REQUIREMENTS,
+        })
+        return true
+      })

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

@@ -48,6 +48,10 @@ Feature: a trivial change takes the same few beats at either risk tier, flag-fre
       ## Risk Tier
 
       <tier> — one-line copy fix
+
+      ## Acceptance Criteria
+
+      - AC-1: the change behaves as described.
       """
     When the process is driven
     Then the process rests at "seam.naive"

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

@@ -72,7 +72,10 @@ describe("planAndBuild", () => {
           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"),
+            r.write(
+              ".gtd/REQUIREMENTS.md",
+              "# Requirements\n\n## Concerns\n\n### S\n\n- `s`\n\n## Acceptance Criteria\n\n- AC-1: done\n",
+            ),
           "design.gate.answer": () => undefined,
           "seam.naive": (_, r) => r.write("src/calc.ts", SUBTRACT),
           "seam.judge": () => '[{"id":"shape","answer":"refactor-first","p":0.9}]',
@@ -102,7 +105,7 @@ describe("planAndBuild", () => {
     const requirements = (_: unknown, r: typeof repo) =>
       r.write(
         ".gtd/REQUIREMENTS.md",
-        "# Requirements\n\n## Concerns\n\n### Subtract\n\n- `subtract`\n",
+        "# Requirements\n\n## Concerns\n\n### Subtract\n\n- `subtract`\n\n## Acceptance Criteria\n\n- AC-1: done\n",
       )
     const lap = {
       unwind: () => undefined,
@@ -134,7 +137,11 @@ describe("planAndBuild", () => {
     const rest = await repo.drive({
       "build.review.closing": runsItsScript,
       "re-unwind": runsItsScript,
-      "design.triage": (_, r) => r.write(".gtd/REQUIREMENTS.md", "# Requirements\n\n- multiply\n"),
+      "design.triage": (_, r) =>
+        r.write(
+          ".gtd/REQUIREMENTS.md",
+          "# Requirements\n\n- multiply\n\n## Acceptance Criteria\n\n- AC-1: done\n",
+        ),
       "design.gate.answer": () => undefined,
     })
     expect(rest.state).toBe("implement.building")
@@ -186,7 +193,10 @@ describe("afterTail feedback lap", () => {
     await repo.land()
     await repo.drive({
       "build.review.collecting": (_, r) => {
-        r.write(".gtd/REQUIREMENTS.md", "# Requirements\n\n- multiply\n")
+        r.write(
+          ".gtd/REQUIREMENTS.md",
+          "# Requirements\n\n- multiply\n\n## Acceptance Criteria\n\n- AC-1: done\n",
+        )
         r.write(".gtd/REVIEW.md", `${review("also export multiply")}    - A: noted.\n`)
       },
     })
@@ -199,7 +209,10 @@ describe("afterTail feedback lap", () => {
     "build.review.closing": runsItsScript,
     "re-unwind": runsItsScript,
     "design.triage": (_: unknown, r: ReturnType<typeof testRepo>) =>
-      r.write(".gtd/REQUIREMENTS.md", "# Requirements\n\n- multiply, designed\n"),
+      r.write(
+        ".gtd/REQUIREMENTS.md",
+        "# Requirements\n\n- multiply, designed\n\n## Acceptance Criteria\n\n- AC-1: done\n",
+      ),
     "design.gate.answer": () => undefined,
   }
 
@@ -221,7 +234,10 @@ describe("afterTail feedback lap", () => {
     expect(prompts[0]).toContain("it covers everything since the base")
     expect(prompts[0]).not.toContain("only what is new since the previous review")
     const writes: Record<string, () => [string, string]> = {
-      "design.triage": () => [".gtd/REQUIREMENTS.md", "# Requirements\n\n- multiply, designed\n"],
+      "design.triage": () => [
+        ".gtd/REQUIREMENTS.md",
+        "# Requirements\n\n- multiply, designed\n\n## Acceptance Criteria\n\n- AC-1: done\n",
+      ],
       "implement.building": () => ["src/calc.ts", `${CALC}// again\n`],
     }
     const actors = new Proxy({} as Record<string, Actor>, {
@@ -295,13 +311,20 @@ describe("an in-flight 28.0.0 naive-pass process", () => {
     from: string,
     to: string,
   ) => {
-    if (from === "seam.steer") repo.write(".gtd/REQUIREMENTS.md", "# Requirements\n\n- steered\n")
+    if (from === "seam.steer")
+      repo.write(
+        ".gtd/REQUIREMENTS.md",
+        "# Requirements\n\n- steered\n\n## Acceptance Criteria\n\n- AC-1: done\n",
+      )
     if (from === "build.review.reviewing") repo.write(".gtd/REVIEW.md", review())
     if (to === "build.review.collecting")
       repo.write(".gtd/REVIEW.md", review("also export multiply"))
     if (from === "build.review.collecting") {
       repo.write(".gtd/REVIEW.md", `${review("also export multiply")}    - A: noted.\n`)
-      repo.write(".gtd/REQUIREMENTS.md", "# Requirements\n\n- multiply\n")
+      repo.write(
+        ".gtd/REQUIREMENTS.md",
+        "# Requirements\n\n- multiply\n\n## Acceptance Criteria\n\n- AC-1: done\n",
+      )
     }
     if (to === "build.review.closing") repo.write(".gtd/REVIEW.md", review())
   }
@@ -313,7 +336,10 @@ describe("an in-flight 28.0.0 naive-pass process", () => {
       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"),
+        r.write(
+          ".gtd/REQUIREMENTS.md",
+          "# Requirements\n\n## Concerns\n\n### S\n\n- `s`\n\n## Acceptance Criteria\n\n- AC-1: done\n",
+        ),
       "design.gate.answer": () => undefined,
       "seam.naive": (_, r) => r.write("src/calc.ts", `${CALC}// naive\n`),
     })
@@ -356,7 +382,8 @@ describe("an in-flight 28.0.0 naive-pass process", () => {
 })
 
 describe("an in-flight process from before the architecture path was removed", () => {
-  const REQUIREMENTS = "# Requirements\n\n## Concerns\n\n### Subtract\n\n- `subtract`\n"
+  const REQUIREMENTS =
+    "# Requirements\n\n## Concerns\n\n### Subtract\n\n- `subtract`\n\n## Acceptance Criteria\n\n- AC-1: done\n"
 
   /** Its history up to the design gate, forged with the old opening commit's `flag_naive_pass=0`. */
   const atDesignGate = async () => {
@@ -397,3 +424,47 @@ describe("an in-flight process from before the architecture path was removed", (
     await expect(repo.next()).rejects.toThrow("the workflow changed under this process")
   })
 })
+
+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## 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, skips the naive pass and the seam judge", async () => {
+    const rest = await designed(CONFIG_SCAFFOLD, { GTD_FLAGMODE: "false" })
+    expect(rest.state).toBe("implement.building")
+    expect(rest.content).toContain("this project ships without release flags")
+  })
+
+  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"])
+  })
+})

package/src/workflows/feature/feature.ts

@@ -9,20 +9,22 @@ import {
   start,
 } from "../../flows/index.js"
 import { gate } from "../shared/health.js"
-import { shipped } from "../shared/options.js"
+import { flagModeOn, shipped } from "../shared/options.js"
 import { FEEDBACK } from "../shared/steps.js"
 import { refusePendingHandOff } from "../shared/tail.js"
 import * as t from "../shared/text.js"
+import { skipDesign, statedCriteria, type StatedCriteria } from "./criteria.js"
 import { design } from "./planning.js"
 import { buildTail, isCode, reUnwind, type ReviewOutcome } from "./review.js"
-import { implement, seamBuild } from "./seam.js"
+import { implement, seamBuild, type SeamOutcome } 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 judged naive pass (refactoring first when
-// the judge asks) → implement → the quality lap → human review, which signs
-// off (the episode ends back at `idle`) or sends a design → implement lap.
+// the judge asks; with `flagMode` off, neither) → implement → the quality lap
+// → human review, which signs off (the episode ends back at `idle`) or sends a
+// design → implement lap.
 
 /** Revert the sketch that started the process out of the working tree; its intent survives in history. */
 export const unwind = (): Promise<void> => {
@@ -36,10 +38,12 @@ export { reUnwind }
 
 // seam.naive / seam.judge run once: a feedback lap is design → implement on every verdict, so a
 // seam a re-plan turns up is built unjudged and unrefactored.
-/** A judged naive pass, then implement and review until a review round signs off; design must have run since `firstBase`. */
+/** A judged naive pass (none with `flagMode` off), then implement and review until a review round signs off; design must have run since `firstBase`. */
 export const buildFeature = async (firstBase: string): Promise<void> => {
   const tier = riskTierOn() ? recordRisk() : undefined
-  const seam = await seamBuild(firstBase)
+  const seam: Omit<SeamOutcome, "reference"> & { reference?: string } = flagModeOn()
+    ? await seamBuild(firstBase)
+    : { base: firstBase }
   await slice("feature", async () => {
     await implement({ reference: seam.reference, tier, afterRefactor: seam.refactored })
     // An empty feature slice: the refactor carried the feature, so review the whole change.
@@ -51,9 +55,10 @@ export const buildFeature = async (firstBase: string): Promise<void> => {
   })
 }
 
-/** Design, then `buildFeature`. */
-export const planAndBuild = async (firstBase: string): Promise<void> => {
-  await design(firstBase)
+/** Design — skipped when the sketch's own criteria are judged clear — then `buildFeature`. */
+export const planAndBuild = async (firstBase: string, stated?: StatedCriteria): Promise<void> => {
+  // GTD_FLAG_RISK_TIER: the tier is proposed at triage and set at the design gate, so no skip.
+  if (!(await skipDesign(riskTierOn() ? undefined : stated))) await design(firstBase)
   await buildFeature(firstBase)
 }
 
@@ -75,6 +80,9 @@ export const afterTail = (outcome: ReviewOutcome): Promise<void> => featureFeedb
 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()
+  const stated = statedCriteria(changes(), head())
   await unwind()
   if (changes(FEEDBACK).some((c) => c.status !== "deleted")) {
     await human("unwind-failed", {
@@ -84,7 +92,7 @@ export const ordinaryStart = async (): Promise<void> => {
     })
   }
   await gate("start-gate", t.startGateBlockedMessage())
-  await planAndBuild(start())
+  await planAndBuild(start(), stated)
 }
 
 export const feature = shipped(ordinaryStart)