@pmelab/gtd 29.0.0 → 29.1.1

package/src/workflows/feature/packages.ts

@@ -15,46 +15,129 @@ import { build, fixSuite } from "./steps.js"
 export interface DeclaredTest {
   readonly level: "unit" | "e2e"
   readonly path: string
+  readonly unchanged: boolean
 }
 
-const TEST_LINE = /^\s*-\s+(unit|e2e):\s+`([^`]+)`/
+const TEST_LINE = /^-\s+(unit|e2e):\s+`([^`]+)`(.*)$/
+const MARKER = /^[ \t]+\(unchanged\)(?=\s|$)/i
+const ITEM = /^\s*-\s/
 
-/** The `## Tests` entries of a package file; malformed lines are ignored. */
+/** The `## Tests` entries of a package file; malformed entries are ignored. */
 export const declaredTests = (packageText: string): readonly DeclaredTest[] => {
   const found: DeclaredTest[] = []
   let inTests = false
-  for (const line of packageText.split("\n")) {
-    if (/^##\s/.test(line)) inTests = /^##\s+Tests\s*$/.test(line)
-    else if (inTests) {
-      const match = TEST_LINE.exec(line)
-      if (match) found.push({ level: match[1] as DeclaredTest["level"], path: match[2]! })
-    }
+  let entry: string | undefined
+  const flush = () => {
+    const match = entry === undefined ? null : TEST_LINE.exec(entry)
+    if (match)
+      found.push({
+        level: match[1] as DeclaredTest["level"],
+        path: match[2]!,
+        unchanged: MARKER.test(match[3]!),
+      })
+    entry = undefined
+  }
+  // An entry is a list line plus its indented continuation lines (oxfmt wraps
+  // long ones); a blank line, a new item or a heading ends it.
+  for (const line of packageText.replace(/\r\n?/g, "\n").split("\n")) {
+    if (/^##\s/.test(line)) {
+      flush()
+      inTests = /^##\s+Tests\s*$/.test(line)
+    } else if (!inTests) continue
+    else if (ITEM.test(line)) {
+      flush()
+      entry = line.trim()
+    } else if (entry !== undefined && /^\s/.test(line) && line.trim() !== "")
+      entry = `${entry} ${line.trim()}`
+    else flush()
   }
+  flush()
   return found
 }
 
+export type DeclaredTestsTurn = "build" | "fix"
+
+type Unmet = "notInDiff" | "modifiedMarked" | "addedMarked" | "deletedMarked" | "notInTree"
+
+type Declared = { path: string; unchanged: boolean }
+
+const diffBucket = (
+  test: Declared,
+  status: string | undefined,
+  turn: DeclaredTestsTurn,
+  satisfied: boolean,
+): Unmet | undefined => {
+  if (test.unchanged) {
+    if (turn !== "build") return undefined
+    if (status === "modified") return "modifiedMarked"
+    return status === "added" ? "addedMarked" : undefined
+  }
+  return !satisfied && (status === undefined || status === "deleted") ? "notInDiff" : undefined
+}
+
+const treeBucket = (test: Declared, status: string | undefined): Unmet | undefined => {
+  if (read(test.path) !== undefined) return undefined
+  return test.unchanged && status === "deleted" ? "deletedMarked" : "notInTree"
+}
+
+const unmetBucket = (
+  test: Declared,
+  change: { status: string } | undefined,
+  turn: DeclaredTestsTurn,
+  satisfied: boolean,
+): Unmet | undefined =>
+  diffBucket(test, change?.status, turn, satisfied) ?? treeBucket(test, change?.status)
+
 /**
  * Refuse a build or fix turn unless every test `pkg` declares exists and is in the
  * diff since `since`. The package text is read as of `since`, so a builder
- * editing its own `## Tests` cannot dodge the guard; with `.gtd/SATISFIED.md`
- * written, existing in the tree suffices.
+ * editing its own `## Tests` (or adding `(unchanged)`) cannot dodge the guard;
+ * with `.gtd/SATISFIED.md` written, or the line marked, existing suffices. The
+ * build turn must neither modify nor add a marked test; a fix turn may edit it.
  */
-export const requireDeclaredTests = (pkg: string, since: string): void => {
+export const requireDeclaredTests = (
+  pkg: string,
+  since: string,
+  turn: DeclaredTestsTurn = "fix",
+): void => {
   const range = changesSince(since)
   const text = range.get(pkg)?.before ?? read(pkg) ?? ""
   const satisfied = read(".gtd/SATISFIED.md") !== undefined
-  const missing = declaredTests(text)
-    .map((test) => test.path)
-    .filter((path) =>
-      satisfied
-        ? read(path) === undefined
-        : range.get(path) === undefined ||
-          range.get(path)?.status === "deleted" ||
-          read(path) === undefined,
-    )
-  if (missing.length === 0) return
+  const buckets = {
+    notInDiff: [] as string[],
+    modifiedMarked: [] as string[],
+    addedMarked: [] as string[],
+    deletedMarked: [] as string[],
+    notInTree: [] as string[],
+  }
+  const entries = declaredTests(text)
+  const seen = new Set<string>()
+  for (const test of entries) {
+    // A file listed both ways is written by the package: the unmarked entry wins.
+    if (test.unchanged && entries.some((e) => !e.unchanged && e.path === test.path)) continue
+    const bucket = unmetBucket(test, range.get(test.path), turn, satisfied)
+    if (bucket && !seen.has(test.path)) {
+      seen.add(test.path)
+      buckets[bucket].push(test.path)
+    }
+  }
+  const { notInDiff, modifiedMarked, addedMarked, deletedMarked, notInTree } = buckets
+  const groups = [
+    ["not in the package's diff — write them", notInDiff],
+    ["marked (unchanged) but modified — revert them", modifiedMarked],
+    [
+      "marked (unchanged) but added by this turn — the marker promises an existing test; stop and leave it to a person",
+      addedMarked,
+    ],
+    ["marked (unchanged) but deleted — restore them", deletedMarked],
+    ["missing from the tree", notInTree],
+  ] as const
+  const reasons = groups.filter(([, paths]) => paths.length > 0)
+  if (reasons.length === 0) return
   refuse(
-    `gtd land: declared-tests: ${pkg} declares tests that are ${satisfied ? "missing from the tree" : "not in the package's diff"} — write them first:\n${missing.map((path) => `  - ${path}`).join("\n")}`,
+    `gtd land: declared-tests: ${pkg} declares tests this turn left unmet:\n${reasons
+      .map(([reason, paths]) => `${reason}:\n${paths.map((path) => `  - ${path}`).join("\n")}`)
+      .join("\n")}`,
   )
 }
 
@@ -66,12 +149,12 @@ export const packageItem = async (pkg: string): Promise<void> => {
   const from = head()
   // Rechecked after every fix too: a fix deleting a red declared test would
   // otherwise green the suite.
-  const declared = (turn: () => Promise<void>) => async () => {
+  const declared = (turn: () => Promise<void>, kind: DeclaredTestsTurn) => async () => {
     await turn()
-    requireDeclaredTests(pkg, from)
+    requireDeclaredTests(pkg, from, kind)
   }
-  await declared(() => build(pkg))()
-  await healthy(declared(fixSuite))
+  await declared(() => build(pkg), "build")()
+  await healthy(declared(fixSuite, "fix"))
   const last = glob(".gtd/packages/*.md").length === 1
   await run("closing", removeScript([pkg, ".gtd/SATISFIED.md", ...(last ? [ARCHITECTURE] : [])]), {
     label: "Closing out the package",

package/src/workflows/feature/refactor.ts

@@ -216,7 +216,13 @@ const refactorLap = async (p: Plan, guard: Guard, feedback?: string): Promise<vo
   )
   await t.agentWithSkills(
     "building",
-    t.refactorBuildingPrompt(REFACTOR_PACKAGE, strays, pattern, reference, feedback !== undefined),
+    t.refactorBuildingPrompt({
+      pkg: REFACTOR_PACKAGE,
+      strays,
+      pattern,
+      reference,
+      feedback: feedback !== undefined,
+    }),
     { label: "Refactoring", model: coder(), system: t.builderSystem() },
   )
   guard()
@@ -275,7 +281,8 @@ export const reviewedRefactor = async (
     for (;;) {
       await refactorLap(p, guard, collected)
       // A person's edit at an escalation rest is never refused, as in the lap.
-      const outcome = await buildTail(false, entry, true, {
+      const outcome = await buildTail(entry, {
+        green: true,
         guard,
         guardRests: false,
         lenses: lensesOf(vars.refactorQualityReviews ?? ""),

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
+  /** Skip keeping green; default `false`. */
+  readonly green?: boolean
   /** 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,36 @@ 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,
+  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> {
+  const base = typeof first === "string" ? first : (second as string)
+  const options: BuildTailOptions =
+    typeof first === "string"
+      ? ((second as BuildTailOptions | undefined) ?? {})
+      : { ...fourth, fixFirst: first, green: third }
+  return tail(
+    options.fixFirst ?? false,
     (escalations) => review(base, escalations, options),
-    green,
+    options.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.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/shared/text.test.ts

@@ -9,6 +9,8 @@ import {
   buildReviewReviewingPrompt,
   agentWithSkills,
   architectureAuthorPrompt,
+  architectureDecomposePrompt,
+  packagesItemBuildingPrompt,
   architectureGateAnswerMessage,
   buildFixPrompt,
   buildFixQualityPrompt,
@@ -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,44 @@ ${strays.map((path) => `  - \`${displayPath(path)}\``).join("\n")}
 
 const withRules = (rules?: string): string => (rules === undefined ? "" : `${rules}\n`)
 
-export const refactorBuildingPrompt = (
+interface RefactorBuildingArgs {
+  pkg: string
+  strays: readonly string[]
+  pattern: string
+  reference?: string | undefined
+  feedback?: boolean | undefined
+}
+
+export function refactorBuildingPrompt(args: RefactorBuildingArgs): string
+/** @deprecated Pass `refactorBuildingPrompt({ pkg, strays, pattern, reference, feedback })`. */
+export function refactorBuildingPrompt(
   pkg: string,
   strays: readonly string[],
   pattern: string,
   reference?: string,
+  feedback?: boolean,
+): string
+export function refactorBuildingPrompt(
+  first: string | RefactorBuildingArgs,
+  strays?: readonly string[],
+  pattern?: string,
+  reference?: string,
+  feedback?: boolean,
+): string {
+  return refactorBuildingPromptOf(
+    typeof first === "string"
+      ? { pkg: first, strays: strays ?? [], pattern: pattern ?? "", reference, feedback }
+      : first,
+  )
+}
+
+const refactorBuildingPromptOf = ({
+  pkg,
+  strays,
+  pattern,
+  reference,
   feedback = false,
-): string =>
+}: RefactorBuildingArgs): string =>
   `${stateFileRules}
 - The package to implement is \`${pkg}\`; never delete it
 ${