@pmelab/gtd 29.3.1 → 30.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "29.3.1",
+  "version": "30.1.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/skills/authoring/SKILL.md

@@ -74,7 +74,7 @@ current directory is the whole workflow. If one already exists, read it and edit
 it in place.
 
 Prefer the bundled workflow's own parts over re-implementing them — `healthy`,
-`escalation`, `gate`, `design`, `architecture`, `packages`, `qualityLap`,
+`escalation`, `gate`, `design`, `seamBuild`, `implement`, `qualityLap`,
 `buildTail`, and single steps like `triage` or `fixCheck`. Their full step names
 are versioned API.
 
@@ -222,41 +222,29 @@ workflow.
 
 ## Worked example: add an approval gate before building
 
-In the bundled default, `planAndBuild` runs the design phase, the architecture
-pass (which writes `.gtd/packages/`), then builds the packages. Add a human
-sign-off between the two:
+In the bundled default, `planAndBuild` runs the design phase, then
+`buildFeature`: the naive pass and its seam judge, then the implementation and
+review. Add a human sign-off before the first build (a review feedback lap
+re-runs design inside `buildFeature` and does not pass it again):
 
 ```ts
 const planAndBuild = async (firstBase: string): Promise<void> => {
-  let base = firstBase
-  let lap: "first" | "feedback" = "first"
-  for (;;) {
-    await design(base)
-    await architecture()
-    await human("approve-plan", {
-      message:
-        "The packages under .gtd/packages/ are ready. Edit them to adjust the plan, or change nothing — then run `gtd land` to start building.",
-      label: "Approve the plan",
-      acceptClean: true,
-    })
-    await packages()
-    const outcome = await buildTail(base, {
-      green: true,
-      ...(lap === "first" ? {} : { lap }),
-    })
-    if (outcome.verdict === "signoff") return
-    await reUnwind(outcome)
-    base = outcome.base
-    lap = "feedback"
-  }
+  await design(firstBase)
+  await human("approve-plan", {
+    message:
+      "`.gtd/REQUIREMENTS.md` is settled. Edit it to adjust the plan, or change nothing — then run `gtd land` to start building.",
+    label: "Approve the plan",
+    acceptClean: true,
+  })
+  await buildFeature(firstBase)
 }
 ```
 
 `acceptClean: true` is what makes an untouched landing approve; without it the
 gate would wait for an edit. `approve-plan` sits in the `root` scope and is a
 new, unique name. Verify: `gtd next` loads without errors, and in a scratch
-repository a landing at `architecture.decompose` now leads to `approve-plan`,
-and an untouched landing there to `packages.item.building`.
+repository a landing at `design.gate.answer` now leads to `approve-plan`, and an
+untouched landing there to `seam.naive`.
 
 ## No migration
 

package/src/cli/Cli.test.ts

@@ -1327,7 +1327,7 @@ export const side = async () => {
   await agent("working", "w")
 }
 
-export const defaults = { flag_naive_pass: "0" }
+export const defaults = { flag_risk_tier: "0" }
 `
   const start = async (
     flags?: CliIo["flags"],
@@ -1343,24 +1343,24 @@ export const defaults = { flag_naive_pass: "0" }
     return result().stdout
   }
 
-  it("pins flag_naive_pass=1 with the flag on", async () => {
-    expect(await start(undefined, { GTD_FLAG_NAIVE_PASS: "1" })).toContain("flag_naive_pass=1")
+  it("pins flag_risk_tier=1 with the flag on", async () => {
+    expect(await start(undefined, { GTD_FLAG_RISK_TIER: "1" })).toContain("flag_risk_tier=1")
   })
 
   it("honours defaultOn with GTD_FLAG_* unset", async () => {
     const out = await start(
       [
         {
-          name: "naive_pass",
+          name: "risk_tier",
           owner: "pmelab",
           expiry: "2099-01-01",
           kind: "release",
           defaultOn: true,
         },
       ],
-      { GTD_FLAG_NAIVE_PASS: "" },
+      { GTD_FLAG_RISK_TIER: "" },
     )
-    expect(out).toContain("flag_naive_pass=1")
+    expect(out).toContain("flag_risk_tier=1")
   })
 })
 

package/src/edge/Edge.test.ts

@@ -1272,7 +1272,7 @@ export const side = async () => {
   await agent("working", "w")
 }
 
-export const defaults = { flag_naive_pass: "0", other: "x" }
+export const defaults = { flag_risk_tier: "0", other: "x" }
 `
   const withFlags = <A>(
     eff: Effect.Effect<A, Error, RestRequirements>,
@@ -1285,23 +1285,23 @@ export const defaults = { flag_naive_pass: "0", other: "x" }
 
   it("a starting process takes the declared flag from StartFlags, never an undeclared one", async () => {
     const rest = await withFlags(currentRest, repoWith(FLAGGED), {
-      flag_naive_pass: "1",
+      flag_risk_tier: "1",
       flag_other: "1",
     })
-    expect(rest.vars).toEqual({ flag_naive_pass: "1", other: "x" })
+    expect(rest.vars).toEqual({ flag_risk_tier: "1", other: "x" })
   })
 
   it("a running process missing the pin resolves the declared default, never the live flag", async () => {
-    const repo = repoWith(FLAGGED.replace('flag_naive_pass: "0", ', ""))
+    const repo = repoWith(FLAGGED.replace('flag_risk_tier: "0", ', ""))
     await enter(repo, "side")
     // a process started before the flag existed: its opening commit lacks the pin
     repo.writeFile("gtd.config.ts", FLAGGED)
-    const rest = await withFlags(currentRest, repo, { flag_naive_pass: "1" })
-    expect(rest.vars.flag_naive_pass).toBe("0")
+    const rest = await withFlags(currentRest, repo, { flag_risk_tier: "1" })
+    expect(rest.vars.flag_risk_tier).toBe("0")
   })
 
   it("with no StartFlags provided, resolves the declared default", async () => {
-    expect((await provide(currentRest, repoWith(FLAGGED))).vars.flag_naive_pass).toBe("0")
+    expect((await provide(currentRest, repoWith(FLAGGED))).vars.flag_risk_tier).toBe("0")
   })
 })
 

package/src/flags/index.test.ts

@@ -92,10 +92,6 @@ describe("FLAGS", () => {
     })
     expect(new Set(names).size).toBe(names.length)
   })
-
-  it("leaves naive_pass off by default", () => {
-    expect(resolveFlags({}).naive_pass).toBe(false)
-  })
 })
 
 describe("flagSettings", () => {

package/src/flags/index.ts

@@ -14,7 +14,6 @@ export interface FlagDeclaration {
 }
 
 export const FLAGS = [
-  { name: "naive_pass", owner: "pmelab", expiry: "2027-01-15", kind: "release" },
   { name: "risk_tier", owner: "pmelab", expiry: "2027-01-15", kind: "release" },
 ] as const satisfies readonly FlagDeclaration[]
 

package/src/workflow/load.test.ts

@@ -853,7 +853,7 @@ describe("ConfigService", () => {
     it("names the key and lists every known scope", async () => {
       const message = await loadError(keyed("nope"))
       expect(message).toContain('"skills.nope" is not a scope that runs a turn — known scopes: ')
-      expect(message).toContain("architecture, architecture.decompose, build,")
+      expect(message).toContain("known scopes: build, build.fix.quality,")
     })
 
     it("gives a group key the same plain error", async () => {

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

@@ -1,7 +1,7 @@
 @inmem
 Feature: a trivial change takes the same few beats at either risk tier, flag-free at low
 
-  With GTD_FLAG_NAIVE_PASS and GTD_FLAG_RISK_TIER on, a one-line copy fix goes
+  With GTD_FLAG_RISK_TIER on, a one-line copy fix goes
   from idle through the naive pass, the seam judge's land, implement and human
   review back to idle. Low tier walks exactly the steps high does; only the
   implementation prompt and the summary differ.
@@ -9,7 +9,6 @@ Feature: a trivial change takes the same few beats at either risk tier, flag-fre
   Background:
     Given the shipped workflows, as gtd install scaffolds them
     And an environment variable "GTD_QUALITYREVIEWS" set to "correctness"
-    And an environment variable "GTD_FLAG_NAIVE_PASS" set to "1"
     And an environment variable "GTD_FLAG_RISK_TIER" set to "1"
     And a file "src/greeting.ts" with:
       """

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

@@ -47,13 +47,12 @@ const review = (text?: string): string =>
 
 const CALC = "export const add = (a: number, b: number) => a + b\n"
 
-const naivePlanned = (flag: "0" | "1") => {
+const naivePlanned = () => {
   const repo = testRepo({
     workflow: CONFIG_SCAFFOLD,
     env: {
       GTD_QUALITYREVIEWS: "",
       GTD_REFACTORQUALITYREVIEWS: "",
-      GTD_FLAG_NAIVE_PASS: flag,
       GTD_FLAG_RISK_TIER: "0",
     },
   })
@@ -63,9 +62,9 @@ const naivePlanned = (flag: "0" | "1") => {
   return repo
 }
 
-describe("planAndBuild on the naive pass", () => {
+describe("planAndBuild", () => {
   it("a refactor that carried the whole feature: the empty implement turn passes and the review covers the whole change", async () => {
-    const repo = naivePlanned("1")
+    const repo = naivePlanned()
     const SUBTRACT = `${CALC}export const subtract = (a: number, b: number) => a - b\n`
     expect(
       (
@@ -99,7 +98,7 @@ describe("planAndBuild on the naive pass", () => {
   })
 
   it("after land, feedback rests next at design.triage, then implement.building, never seam.naive", async () => {
-    const repo = naivePlanned("1")
+    const repo = naivePlanned()
     const requirements = (_: unknown, r: typeof repo) =>
       r.write(
         ".gtd/REQUIREMENTS.md",
@@ -149,20 +148,6 @@ describe("planAndBuild on the naive pass", () => {
   })
 })
 
-describe("planAndBuild without the naive pass", () => {
-  it("runs the design → architecture path: no seam, no implement", async () => {
-    const repo = naivePlanned("0")
-    const rest = await repo.drive({
-      unwind: () => undefined,
-      "start-gate.check": () => undefined,
-      "design.triage": (_, r) => r.write(".gtd/REQUIREMENTS.md", "# Requirements\n"),
-      "design.gate.answer": () => undefined,
-    })
-    expect(rest.state).toBe("architecture.author")
-    expect(repo.subjects().some((subject) => /seam|implement/.test(subject))).toBe(false)
-  })
-})
-
 describe("afterTail feedback lap", () => {
   const TAIL = [
     `import { start } from "@pmelab/gtd/flows"`,
@@ -176,14 +161,13 @@ describe("afterTail feedback lap", () => {
 
   const prompts: string[] = []
 
-  const feedbackLap = async (flag: "0" | "1") => {
+  const feedbackLap = async () => {
     prompts.length = 0
     const repo = testRepo({
       workflow: TAIL,
       env: {
         GTD_QUALITYREVIEWS: "",
         GTD_REFACTORQUALITYREVIEWS: "",
-        GTD_FLAG_NAIVE_PASS: flag,
         GTD_FLAG_RISK_TIER: "0",
       },
     })
@@ -219,8 +203,8 @@ describe("afterTail feedback lap", () => {
     "design.gate.answer": () => undefined,
   }
 
-  it("flag_naive_pass=1 rests at design.triage, then implement.building, reaching no seam step", async () => {
-    const repo = await feedbackLap("1")
+  it("rests at design.triage, then implement.building, reaching no seam step", async () => {
+    const repo = await feedbackLap()
     expect(
       (await repo.drive({ "build.review.closing": runsItsScript, "re-unwind": runsItsScript }))
         .state,
@@ -232,46 +216,30 @@ describe("afterTail feedback lap", () => {
     expect(repo.subjects().some((subject) => subject.includes("seam."))).toBe(false)
   })
 
-  it("flag_naive_pass=0 re-plans through architecture and packages", async () => {
-    const repo = await feedbackLap("0")
-    const rest = await repo.drive(afterFeedback)
-    expect(rest.state).toBe("architecture.author")
+  it("the first review says everything since base, the one after feedback only what is new", async () => {
+    const repo = await feedbackLap()
+    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"],
+      "implement.building": () => ["src/calc.ts", `${CALC}// again\n`],
+    }
+    const actors = new Proxy({} as Record<string, Actor>, {
+      get: (_, state: string): Actor | undefined =>
+        state === "build.review.await-review" || state === "idle"
+          ? undefined
+          : (beat, r) => {
+              if (state === "build.review.reviewing") {
+                prompts.push(beat.content)
+                r.write(".gtd/REVIEW.md", review())
+              } else if (writes[state]) r.write(...writes[state]())
+              else if (state.endsWith("closing") || state === "re-unwind") r.runScript(beat.content)
+            },
+    })
+    await repo.drive(actors, { maxBeats: 80 })
+    expect(prompts[1]).toContain("it covers only what is new since the previous review")
+    expect(prompts[1]).not.toContain("everything since the base")
   })
-
-  it.each(["0", "1"] as const)(
-    "flag_naive_pass=%s: the first review says everything since base, the one after feedback only what is new",
-    async (flag) => {
-      const repo = await feedbackLap(flag)
-      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"],
-        "implement.building": () => ["src/calc.ts", `${CALC}// again\n`],
-        "packages.item.building": () => ["src/calc.ts", `${CALC}// package\n`],
-        "architecture.author": () => [".gtd/ARCHITECTURE.md", "# Architecture\n\nmultiply\n"],
-        "architecture.decompose.decomposing": () => [
-          ".gtd/packages/01-multiply.md",
-          "# 01 multiply\n",
-        ],
-      }
-      const actors = new Proxy({} as Record<string, Actor>, {
-        get: (_, state: string): Actor | undefined =>
-          state === "build.review.await-review" || state === "idle"
-            ? undefined
-            : (beat, r) => {
-                if (state === "build.review.reviewing") {
-                  prompts.push(beat.content)
-                  r.write(".gtd/REVIEW.md", review())
-                } else if (writes[state]) r.write(...writes[state]())
-                else if (state.endsWith("closing") || state === "re-unwind")
-                  r.runScript(beat.content)
-              },
-      })
-      await repo.drive(actors, { maxBeats: 80 })
-      expect(prompts[1]).toContain("it covers only what is new since the previous review")
-      expect(prompts[1]).not.toContain("everything since the base")
-    },
-  )
 })
 
 describe("an in-flight 28.0.0 naive-pass process", () => {
@@ -340,7 +308,7 @@ describe("an in-flight 28.0.0 naive-pass process", () => {
 
   /** The repo at the judge's rest, then `trail` forged edge by edge as `Gtd-Step:` commits. */
   const forged = async (trail: readonly Edge[], upTo: number) => {
-    const repo = naivePlanned("1")
+    const repo = naivePlanned()
     await repo.drive({
       unwind: () => undefined,
       "start-gate.check": () => undefined,
@@ -386,3 +354,87 @@ 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"
+
+  /** Its history up to the design gate, forged with the old opening commit's `flag_naive_pass=0`. */
+  const atDesignGate = async () => {
+    const live = naivePlanned()
+    await live.drive({ unwind: () => undefined, "start-gate.check": () => undefined })
+    const opening = live.messages().find((m) => m.startsWith("gtd(human): idle → unwind"))!
+    const repo = naivePlanned()
+    repo.commit(
+      opening.replace(
+        "Gtd-Var: flag_risk_tier=0",
+        "Gtd-Var: flag_naive_pass=0\nGtd-Var: flag_risk_tier=0",
+      ),
+    )
+    repo.remove("TODO.md")
+    repo.commit("gtd(check): unwind → start-gate.check\n\nGtd-Step: unwind#1\nGtd-Format: 1")
+    repo.commit(
+      "gtd(check): start-gate.check → design.triage\n\nGtd-Step: start-gate.check#1\nGtd-Format: 1",
+    )
+    repo.write(".gtd/REQUIREMENTS.md", REQUIREMENTS)
+    repo.commit(
+      "gtd(agent): design.triage → design.gate.answer\n\nGtd-Step: design.triage#1\nGtd-Format: 1",
+    )
+    return repo
+  }
+
+  it("resting at the design gate, replays onto the naive pass", async () => {
+    const repo = await atDesignGate()
+    expect((await repo.next()).state).toBe("design.gate.answer")
+    await repo.land()
+    expect((await repo.next()).state).toBe("seam.naive")
+  })
+
+  it("past the design gate on the architecture path, fails replay", async () => {
+    const repo = await atDesignGate()
+    repo.commit(
+      "gtd(human): design.gate.answer → architecture.author\n\nGtd-Step: design.gate.answer#1\nGtd-Format: 1",
+    )
+    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"),
+      "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

@@ -7,24 +7,23 @@ import {
   run,
   slice,
   start,
-  vars,
 } 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 { packages } from "./packages.js"
-import { architecture, design } from "./planning.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, architecture and one package per concern →
-// the quality lap → human review, which signs off (the episode ends back at
-// `idle`) or sends a full re-plan lap.
+// green-baseline gate → design → a judged naive pass (refactoring first when
+// 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,33 +35,14 @@ export const unwind = (): Promise<void> => {
 
 export { reUnwind }
 
-/** Plan, build and review until a review round signs off; feedback re-plans from scratch. */
-export const planAndBuild = async (
-  firstBase: string,
-  firstLap: t.ReviewRange = "first",
-): Promise<void> => {
-  // GTD_FLAG_NAIVE_PASS: the record is pinned at the process start, so a mid-process flip never moves a process.
-  if (vars.flag_naive_pass === "1") return naivePlanAndBuild(firstBase)
-  let base = firstBase
-  let lap = firstLap
-  for (;;) {
-    await design(base)
-    await architecture()
-    await packages()
-    const outcome = await buildTail(base, { green: true, lap })
-    if (outcome.verdict === "signoff") return
-    await reUnwind(outcome)
-    base = outcome.base
-    lap = "feedback"
-  }
-}
-
 // 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.
-const naivePlanAndBuild = async (firstBase: string): Promise<void> => {
-  await design(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.
@@ -74,6 +54,12 @@ const naivePlanAndBuild = async (firstBase: string): Promise<void> => {
   })
 }
 
+/** Design, then `buildFeature`. */
+export const planAndBuild = async (firstBase: string): Promise<void> => {
+  await design(firstBase)
+  await buildFeature(firstBase)
+}
+
 const featureFeedback = async (first: ReviewOutcome, lensBase?: string): Promise<void> => {
   let outcome = first
   while (outcome.verdict === "feedback") {
@@ -86,17 +72,14 @@ const featureFeedback = async (first: ReviewOutcome, lensBase?: string): Promise
 }
 
 /** After a tail that skipped planning: stop on sign-off, re-plan on feedback. Opens no slice: slices cannot nest. */
-export const afterTail = async (outcome: ReviewOutcome): Promise<void> => {
-  if (outcome.verdict === "signoff") return
-  if (vars.flag_naive_pass === "1") return featureFeedback(outcome)
-  await reUnwind(outcome)
-  await planAndBuild(outcome.base, "feedback")
-}
+export const afterTail = (outcome: ReviewOutcome): Promise<void> => featureFeedback(outcome)
 
 /** An ordinary start: wait at `idle`, unwind the sketch, check the baseline, then plan and build. */
 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()
   await unwind()
   if (changes(FEEDBACK).some((c) => c.status !== "deleted")) {
     await human("unwind-failed", {