@pmelab/gtd 29.1.0 → 29.2.0

package/src/workflows/feature/review.ts

@@ -256,6 +256,10 @@ export interface FeedbackTarget {
 }
 
 export interface BuildTailOptions {
+  /** Fix first when entered red; default `false`. */
+  readonly fixFirst?: boolean | undefined
+  /** Asserts the tree is already green, so the tail skips keep-green; default `false`. */
+  readonly green?: boolean | undefined
   /** Runs after every code-changing turn: fix-check, quality fix, risk fix, nit fix, escalation describe. */
   readonly guard?: Guard
   /** `false`: `guard` skips the escalation's human rests. */
@@ -274,22 +278,44 @@ export interface BuildTailOptions {
 }
 
 /** The build tail: fix (when entered red), keep green unless `green`, the quality lap, then human review since `base`. */
-export const buildTail = (
+export function buildTail(base: string, options?: BuildTailOptions): Promise<kit.ReviewOutcome>
+/** @deprecated Pass `buildTail(base, { fixFirst, green, ...options })`. */
+export function buildTail(
   fixFirst: boolean,
   base: string,
-  green = false,
-  options: BuildTailOptions = {},
-): Promise<kit.ReviewOutcome> =>
-  tail(
-    fixFirst,
-    (escalations) => review(base, escalations, options),
-    green,
+  green?: boolean,
+  options?: Omit<BuildTailOptions, "fixFirst" | "green">,
+): Promise<kit.ReviewOutcome>
+export function buildTail(
+  first: boolean | string,
+  second?: string | BuildTailOptions,
+  third = false,
+  fourth: Omit<BuildTailOptions, "fixFirst" | "green"> = {},
+): Promise<kit.ReviewOutcome> {
+  // Before any step runs, so a bad call never leaves a half-walked flow.
+  if (typeof first !== "string" && typeof first !== "boolean" && typeof second !== "string") {
+    return Promise.reject(
+      new Error(
+        "buildTail takes buildTail(base, options?) or the deprecated buildTail(fixFirst, base, green?, options?); this call fits neither",
+      ),
+    )
+  }
+  const [base, options]: [string, BuildTailOptions] =
+    typeof first === "string"
+      ? [first, (second as BuildTailOptions | undefined) ?? {}]
+      : [second as string, { ...fourth, fixFirst: first, green: third }]
+  const { fixFirst, green, ...reviewOptions } = options
+  return tail(
+    fixFirst ?? false,
+    (escalations) => review(base, escalations, reviewOptions),
+    green ?? false,
     options.guard,
     options.lenses,
     options.guardRests,
     options.lensBase,
     options.rules,
   )
+}
 
 /**
  * Undo the human's review-round code edits. A path changed since the human

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

@@ -225,6 +225,7 @@ describe("implement", () => {
     reference: string | undefined,
     tier?: "low" | "high",
     amend?: boolean,
+    call: () => Promise<void> = () => implement({ reference, tier, amend }),
   ) => {
     const requests: StepRequest[] = []
     installContext(
@@ -241,12 +242,25 @@ describe("implement", () => {
         },
       ),
     )
-    await implement(reference, tier, amend)
+    await call()
     const request = requests.find((r) => r.kind === "agent" && r.name === "building")
     if (request?.kind !== "agent") throw new Error("no building turn")
     return request.prompt
   }
 
+  it("the deprecated positional form renders the same prompt as the options form", async () => {
+    const modern = await building("abc", "low")
+    const legacy = await building("abc", "low", undefined, () => implement("abc", "low"))
+    expect(legacy).toBe(modern)
+    expect(legacy).toContain("git show abc")
+    const amended = await building(undefined, undefined, true)
+    expect(
+      await building(undefined, undefined, undefined, () => implement(undefined, undefined, true)),
+    ).toBe(amended)
+    const bare = await building(undefined, undefined, undefined, () => implement())
+    expect(bare).toBe(await building(undefined))
+  })
+
   it("names the reference with a git show line", async () => {
     expect(await building("abc")).toContain("git show abc")
   })

package/src/workflows/feature/seam.ts

@@ -41,17 +41,36 @@ export const naivePass = (rejection?: t.SeamRejection): Promise<void> =>
     system: t.builderSystem(),
   })
 
-export const implement = (
+export interface ImplementOptions {
+  readonly reference?: string | undefined
+  readonly tier?: RiskTier | undefined
+  readonly amend?: boolean | undefined
+}
+
+export function implement(options?: ImplementOptions): Promise<void>
+/** @deprecated Pass `implement({ reference, tier, amend })`. */
+export function implement(
   reference: string | undefined,
   tier?: RiskTier,
   amend?: boolean,
-): Promise<void> =>
-  scope("implement", async () => {
-    await t.agentWithSkills("building", t.implementBuildingPrompt(reference, tier, amend), {
-      label: "Implementing",
-      model: coder(),
-      system: t.builderSystem(),
-    })
+): Promise<void>
+export function implement(
+  first?: string | ImplementOptions,
+  tier?: RiskTier,
+  amend?: boolean,
+): Promise<void> {
+  const options: ImplementOptions =
+    typeof first === "object" && first !== null ? first : { reference: first, tier, amend }
+  return scope("implement", async () => {
+    await t.agentWithSkills(
+      "building",
+      t.implementBuildingPrompt(options.reference, options.tier, options.amend),
+      {
+        label: "Implementing",
+        model: coder(),
+        system: t.builderSystem(),
+      },
+    )
     await healthy(() =>
       t.agentWithSkills("fix.suite.fixing", t.implementFixPrompt(), {
         label: "Fixing the check",
@@ -62,6 +81,7 @@ export const implement = (
     )
     await run("closing", removeScript([REQUIREMENTS]), { label: "Closing out the implementation" })
   })
+}
 
 interface Decision {
   readonly reference: string

package/src/workflows/index.ts

@@ -24,7 +24,7 @@ export * from "./feature/planning.js"
 export * from "./feature/packages.js"
 export * from "./feature/refactor.js"
 export * from "./feature/seam.js"
-export { buildTail, type ReviewOutcome } from "./feature/review.js"
+export { buildTail, type BuildTailOptions, type ReviewOutcome } from "./feature/review.js"
 export * from "./feature/feature.js"
 export { base, review, reviewFlow } from "./review/review.js"
 export { fix, fixFlow, fixReviewNotes } from "./fix/fix.js"

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

@@ -1,4 +1,5 @@
 import { describe, expect, it } from "vitest"
+import { FLAGS, type FlagDeclaration } from "../../flags/index.js"
 import { configure, type WorkflowDoors } from "../../flows/index.js"
 import * as workflows from "../index.js"
 import * as options from "./options.js"
@@ -10,13 +11,19 @@ describe("the shipped workflow factories", () => {
   it("take exactly the settings the shipped workflows declare as options", () => {
     expect(Object.keys(ShippedOptions.fields).sort()).toEqual(
       [...Object.keys(defaults), ...Object.keys(envDefaults)]
-        .filter((name) => name !== "flag_naive_pass" && name !== "flag_risk_tier")
+        .filter((name) => !name.startsWith("flag_"))
         .sort(),
     )
   })
 
+  it("declare a flag_<name> default for exactly the registered flags", () => {
+    const declared = Object.keys(defaults).filter((name) => name.startsWith("flag_"))
+    expect(declared.sort()).toEqual(FLAGS.map(({ name }) => `flag_${name}`).sort())
+    for (const { name, defaultOn } of FLAGS as readonly FlagDeclaration[])
+      expect(defaults).toHaveProperty(`flag_${name}`, defaultOn ? "1" : "0")
+  })
+
   it("declare seamAllow and flag_naive_pass defaults; flag_naive_pass is no option", () => {
-    expect(defaults.flag_naive_pass).toBe("0")
     expect(Object.keys(ShippedOptions.fields)).not.toContain("flag_naive_pass")
     expect(configure(feature({ seamAllow: "docs/**" }))).toMatchObject({
       ok: true,
@@ -25,7 +32,6 @@ describe("the shipped workflow factories", () => {
   })
 
   it("declare flag_risk_tier off by default; it is no factory option", () => {
-    expect(defaults.flag_risk_tier).toBe("0")
     expect(Object.keys(ShippedOptions.fields)).not.toContain("flag_risk_tier")
   })
 

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

@@ -9,6 +9,8 @@ import {
   buildReviewReviewingPrompt,
   agentWithSkills,
   architectureAuthorPrompt,
+  architectureDecomposePrompt,
+  packagesItemBuildingPrompt,
   architectureGateAnswerMessage,
   buildFixPrompt,
   buildFixQualityPrompt,
@@ -1061,7 +1063,7 @@ describe("the refactor prompts", () => {
 
   it("building and fix rules forbid every test file, with no stray exception", () => {
     for (const prompt of renderText(() => [
-      refactorBuildingPrompt(".gtd/REFACTOR.md", strays, pattern),
+      refactorBuildingPrompt({ pkg: ".gtd/REFACTOR.md", strays, pattern }),
       refactorFixPrompt(strays, pattern),
     ])) {
       expect(prompt).toContain("never a test file")
@@ -1071,8 +1073,8 @@ describe("the refactor prompts", () => {
 
   it("building adds the act-on-review-feedback line only when asked", () => {
     const [plain, feedback] = renderText(() => [
-      refactorBuildingPrompt(".gtd/REFACTOR.md", strays, pattern),
-      refactorBuildingPrompt(".gtd/REFACTOR.md", strays, pattern, undefined, true),
+      refactorBuildingPrompt({ pkg: ".gtd/REFACTOR.md", strays, pattern }),
+      refactorBuildingPrompt({ pkg: ".gtd/REFACTOR.md", strays, pattern, feedback: true }),
     ])
     expect(plain).not.toContain("## Review feedback")
     expect(feedback).toContain("## Review feedback")
@@ -1266,3 +1268,45 @@ describe("buildReviewReviewingPrompt lap wording", () => {
     },
   )
 })
+
+describe("architectureDecomposePrompt tests rule", () => {
+  it("states one rule: write-or-change, relied-on marked (unchanged), no other untouched", () => {
+    const prompt = renderText(() => architectureDecomposePrompt()).replace(/\s+/g, " ")
+    expect(prompt).toContain("List every test the package writes or changes")
+    expect(prompt).toContain("also list an existing test a criterion relies on")
+    expect(prompt).toContain("list no other untouched test")
+    expect(prompt).toContain("- unit: \\`<path>\\` (unchanged)")
+    expect(prompt).toContain("- e2e: \\`<path>\\` (unchanged)")
+    expect(prompt).toContain("only decompose places the marker")
+  })
+})
+
+describe("packagesItemBuildingPrompt", () => {
+  const prompt = renderText(() => packagesItemBuildingPrompt(".gtd/packages/01-a.md")).replace(
+    /\s+/g,
+    " ",
+  )
+  it("carries the evidence kinds and the already-done check", () => {
+    for (const w of [
+      "evidence per criterion",
+      "commit, file, symbol, issue URL, or command output — and change nothing else",
+      "it was not already done",
+      "via `gh`",
+    ])
+      expect(prompt).toContain(w)
+  })
+  it("states the already-met, no-tests out-of-tree and implement-normally rules flat", () => {
+    expect(prompt).toContain("Every criterion already met in the tree")
+    expect(prompt).toContain("No `## Tests` and work outside the tree")
+    expect(prompt).toContain(
+      "Any other package**: implement normally, write no `.gtd/SATISFIED.md`",
+    )
+  })
+  it("says an (unchanged) line must exist and stay untouched", () => {
+    expect(prompt).toContain("(unchanged)")
+    expect(prompt).toContain("stay untouched")
+    expect(prompt).toContain("creating, editing or deleting it refuses the turn")
+    expect(prompt).toContain("must exist before the turn")
+    expect(prompt).toContain("stop without creating it")
+  })
+})

package/src/workflows/shared/text.ts

@@ -376,7 +376,12 @@ ${stateFileRules}
 - Every package with tests has a \`## Tests\` section, one line per
   declared test, copied from the architecture entries:
   \`- unit: \\\`<path>\\\`\` or \`- e2e: \\\`<path>\\\`\`. Chore packages have
-  none
+  none. List every test the package writes or changes; also list an
+  existing test a criterion relies on, marked \`(unchanged)\` —
+  \`- unit: \\\`<path>\\\` (unchanged)\` or
+  \`- e2e: \\\`<path>\\\` (unchanged)\`; list no other untouched test;
+  never mark a file the package also writes or changes — list it once,
+  unmarked; only decompose places the marker
 - Leave everything uncommitted and finish
 `
 
@@ -413,15 +418,26 @@ export const packagesItemBuildingPrompt = (pkg: string): string =>
   never delete the package file (the declared-tests guard reads it
   after you)
 - The package to implement is \`${pkg}\`
-- First check its acceptance criteria against the current tree —
-  an earlier fix turn may already satisfy them. If **every**
-  criterion is met, implement nothing: write \`.gtd/SATISFIED.md\`
-  with each criterion's concrete evidence (commit, file, or
-  symbol), change nothing else, and finish. Otherwise implement
-  normally and skip that file
+- First check the acceptance criteria against the current tree —
+  an earlier fix turn may already meet them
+- **Every criterion already met in the tree**: write
+  \`.gtd/SATISFIED.md\` with evidence per criterion — commit, file,
+  symbol, issue URL, or command output — and change nothing else
+- **No \`## Tests\` and work outside the tree**: first check it was
+  not already done by an earlier attempt (e.g. an existing issue
+  with the same title via \`gh\`) and reuse that as evidence, or do
+  the work; then write \`.gtd/SATISFIED.md\` with that evidence and
+  change nothing else in the tree
+- **Any other package**: implement normally, write no
+  \`.gtd/SATISFIED.md\`
 - Write the tests the package declares under \`## Tests\` first,
   then the code that makes them pass; the turn is refused unless
-  every declared test is in your diff
+  every declared test is in your diff — except a line marked
+  \`(unchanged)\`, which must exist before the turn and stay
+  untouched — creating, editing or deleting it refuses the turn. If
+  it does not exist yet, or the marker is wrong because the package
+  must change that test, stop without creating it and leave it to
+  a person
 - A declared e2e test is a scenario in the repository's own e2e
   framework for the behaviour its \`## E2E Scenarios\` entry names.
   Word it to fit the existing steps — reuse and generalise them
@@ -457,13 +473,19 @@ ${strays.map((path) => `  - \`${displayPath(path)}\``).join("\n")}
 
 const withRules = (rules?: string): string => (rules === undefined ? "" : `${rules}\n`)
 
-export const refactorBuildingPrompt = (
-  pkg: string,
-  strays: readonly string[],
-  pattern: string,
-  reference?: string,
+export const refactorBuildingPrompt = ({
+  pkg,
+  strays,
+  pattern,
+  reference,
   feedback = false,
-): string =>
+}: {
+  pkg: string
+  strays: readonly string[]
+  pattern: string
+  reference?: string | undefined
+  feedback?: boolean | undefined
+}): string =>
   `${stateFileRules}
 - The package to implement is \`${pkg}\`; never delete it
 ${