@pmelab/gtd 18.1.0 → 20.0.0

package/src/workflows/scenarios.test.ts

@@ -0,0 +1,256 @@
+import { afterEach, describe, expect, it } from "vitest"
+import { installContext, type StepRequest } from "../flows/index.js"
+import {
+  driftedScenarios,
+  freezeScenarios,
+  guarded,
+  holdWording,
+  scenarioText,
+} from "./scenarios.js"
+import { fixtureContext, renderText } from "./text.fixture.js"
+
+afterEach(() => installContext(undefined))
+
+const tree = (files: Record<string, string>) => ({
+  read: (path: string) => files[path],
+})
+
+describe("scenarioText", () => {
+  it("ignores comments, tags, blank lines and indentation", () => {
+    const loose = [
+      "@wip @slow",
+      "Feature: x",
+      "",
+      "  # a comment",
+      "    @tag",
+      "  Scenario: y",
+      "      Given a thing",
+    ].join("\n")
+    const tight = "Feature: x\nScenario: y\nGiven a thing"
+    expect(scenarioText(loose)).toBe(scenarioText(tight))
+  })
+
+  it("keeps changed wording", () => {
+    expect(scenarioText("Given a")).not.toBe(scenarioText("Given b"))
+  })
+
+  it.each([
+    ["a # line", "# Review: abc"],
+    ["an @ line", "@mention"],
+    ["a blank line", ""],
+  ])("keeps %s inside a doc string", (_, line) => {
+    const doc = (body: string[]) =>
+      ["Given a file with:", '  """', ...body.map((l) => (l === "" ? "" : `  ${l}`)), '  """'].join(
+        "\n",
+      )
+    expect(scenarioText(doc(["top", line, "end"]))).not.toBe(scenarioText(doc(["top", "end"])))
+  })
+
+  it("keeps indentation inside a doc string", () => {
+    const doc = (line: string) => ["Given a file with:", '  """', `  ${line}`, '  """'].join("\n")
+    expect(scenarioText(doc("  nested"))).not.toBe(scenarioText(doc("nested")))
+  })
+
+  it("ignores a doc string re-indented together with its delimiters", () => {
+    const at = (indent: string) =>
+      [
+        "Given a file with:",
+        `${indent}\`\`\``,
+        `${indent}# Review`,
+        `${indent}  - x`,
+        `${indent}\`\`\``,
+      ].join("\n")
+    expect(scenarioText(at("      "))).toBe(scenarioText(at("  ")))
+  })
+})
+
+describe("freezeScenarios", () => {
+  it("snapshots wording at head, nothing frozen is undefined", () => {
+    const files = { "a.feature": "@t\nGiven a" }
+    renderText(() => {
+      expect(freezeScenarios([])).toBeUndefined()
+    })
+    installContext(fixtureContext({ head: "h1" }, tree(files)))
+    expect(freezeScenarios(["a.feature"])).toEqual({
+      at: "h1",
+      texts: { "a.feature": scenarioText("Given a") },
+    })
+  })
+
+  it("merges over previous, a new path overriding an old one", () => {
+    installContext(
+      fixtureContext({ head: "h2" }, tree({ "b.feature": "Given b", "a.feature": "Given a2" })),
+    )
+    const merged = freezeScenarios(["a.feature", "b.feature"], {
+      at: "h1",
+      texts: { "a.feature": "Given a", "c.feature": "Given c" },
+    })
+    expect(merged).toEqual({
+      at: "h2",
+      texts: {
+        "a.feature": "Given a2",
+        "b.feature": "Given b",
+        "c.feature": "Given c",
+      },
+    })
+  })
+
+  it("keeps previous untouched when no paths are given", () => {
+    const previous = { at: "h1", texts: { "a.feature": "Given a" } }
+    installContext(fixtureContext({ head: "h2" }, tree({})))
+    expect(freezeScenarios([], previous)).toBe(previous)
+  })
+})
+
+describe("driftedScenarios", () => {
+  const frozen = { at: "h1", texts: { "a.feature": "Given a", "b.feature": "Given b" } }
+
+  it("flags edited and deleted files, ignores comment-only edits and other paths", () => {
+    installContext(
+      fixtureContext({}, tree({ "a.feature": "# note\nGiven a2", "other.feature": "Given z" })),
+    )
+    expect(driftedScenarios(frozen)).toEqual(["a.feature", "b.feature"])
+  })
+
+  it("is empty while wording is unchanged", () => {
+    installContext(
+      fixtureContext({}, tree({ "a.feature": "  @x\n  Given a", "b.feature": "Given b" })),
+    )
+    expect(driftedScenarios(frozen)).toEqual([])
+  })
+})
+
+describe("holdWording", () => {
+  const run = async (
+    files: () => Record<string, string>,
+    frozen: Parameters<typeof holdWording>[0],
+    head = "h2",
+  ): Promise<StepRequest[]> => {
+    const steps: StepRequest[] = []
+    installContext(
+      fixtureContext(
+        { head },
+        {
+          read: (path) => files()[path],
+          step: (request) => {
+            steps.push(request)
+            return Promise.resolve()
+          },
+        },
+      ),
+    )
+    await holdWording(frozen)
+    return steps
+  }
+
+  it("does nothing without a freeze or without drift", async () => {
+    expect(await run(() => ({}), undefined)).toEqual([])
+    const frozen = { at: "h1", texts: { "a.feature": "Given a" } }
+    expect(await run(() => ({ "a.feature": "Given a" }), frozen)).toEqual([])
+  })
+
+  it("rests at scenario-wording with the removed and added lines and the restore command", async () => {
+    const frozen = { at: "h1", texts: { "my dir/a.feature": "Given a\nThen ok" } }
+    const steps = await run(() => ({ "my dir/a.feature": "Given a\nThen better" }), frozen)
+    const [step] = steps
+    if (step?.kind !== "human") throw new Error("expected a human step")
+    expect(step.name).toBe("scenario-wording")
+    expect(step.options.acceptClean).toBe(true)
+    expect(step.options.base).toBe("h1")
+    const message = step.options.message ?? ""
+    expect(message).toContain("- Then ok")
+    expect(message).toContain("+ Then better")
+    expect(message).toContain("git checkout h1 -- 'my dir/a.feature'")
+    expect(message).toContain("partial accept")
+  })
+
+  const shownDiff = async (before: string, after: string): Promise<string[]> => {
+    const frozen = { at: "h1", texts: { "a.feature": before } }
+    const [step] = await run(() => ({ "a.feature": after }), frozen)
+    if (step?.kind !== "human") throw new Error("expected a human step")
+    return (step.options.message ?? "").split("\n").filter((l) => /^[-+] /.test(l))
+  }
+
+  it("shows a moved step as one removal and one addition of it, in place", async () => {
+    expect(await shownDiff("Given a\nWhen b\nThen c", "When b\nGiven a\nThen c")).toEqual([
+      "- Given a",
+      "+ Given a",
+    ])
+  })
+
+  it("shows a blank line added inside a doc string", async () => {
+    expect(await shownDiff('"""\na\nb\n"""', '"""\na\n\nb\n"""')).toEqual(["+ "])
+  })
+
+  it("shows a repeated step as its added copy", async () => {
+    expect(await shownDiff("Given a\nThen c", "Given a\nGiven a\nThen c")).toEqual(["+ Given a"])
+  })
+
+  it("accepts still-differing files by moving the snapshot to head", async () => {
+    const frozen = { at: "h1", texts: { "a.feature": "Given a", "b.feature": "Given b" } }
+    await run(() => ({ "a.feature": "Given a2", "b.feature": "Given b2" }), frozen)
+    expect(frozen).toEqual({
+      at: "h2",
+      texts: { "a.feature": "Given a2", "b.feature": "Given b2" },
+    })
+  })
+
+  it("rejects restored files, keeping the original wording frozen", async () => {
+    const frozen = { at: "h1", texts: { "a.feature": "Given a", "b.feature": "Given b" } }
+    let files: Record<string, string> = { "a.feature": "Given a2", "b.feature": "Given b2" }
+    installContext(
+      fixtureContext(
+        { head: "h2" },
+        {
+          read: (path) => files[path],
+          step: () => {
+            files = { "a.feature": "Given a", "b.feature": "Given b2" }
+            return Promise.resolve()
+          },
+        },
+      ),
+    )
+    await holdWording(frozen)
+    expect(frozen.texts).toEqual({ "a.feature": "Given a", "b.feature": "Given b2" })
+  })
+
+  it("drops an accepted deletion from the snapshot", async () => {
+    const frozen = { at: "h1", texts: { "a.feature": "Given a" } }
+    await run(() => ({}), frozen)
+    expect(frozen.texts).toEqual({})
+  })
+})
+
+describe("guarded", () => {
+  it("runs the turn, then holds wording", async () => {
+    const order: string[] = []
+    const frozen = { at: "h1", texts: { "a.feature": "Given a" } }
+    installContext(
+      fixtureContext(
+        { head: "h2" },
+        {
+          read: () => "Given changed",
+          step: (request) => {
+            order.push(request.kind)
+            return Promise.resolve()
+          },
+        },
+      ),
+    )
+    await guarded(frozen, () => {
+      order.push("turn")
+      return Promise.resolve()
+    })()
+    expect(order).toEqual(["turn", "human"])
+  })
+
+  it("is the bare turn without a freeze", async () => {
+    const order: string[] = []
+    installContext(fixtureContext())
+    await guarded(undefined, () => {
+      order.push("turn")
+      return Promise.resolve()
+    })()
+    expect(order).toEqual(["turn"])
+  })
+})

package/src/workflows/scenarios.ts

@@ -0,0 +1,137 @@
+import { head, human, read, scope } from "../flows/index.js"
+import * as t from "./text.js"
+
+/** Mutable: an accepted change moves the snapshot forward. */
+export interface FrozenScenarios {
+  at: string
+  texts: Record<string, string>
+}
+
+const DOC_STRING = /^(\s*)("""|```)/
+
+/**
+ * Gherkin wording only: lines trimmed; blank, `#` comment and `@` tag lines
+ * dropped — except inside a doc string, whose content is test input: kept
+ * whole, indented relative to its opening delimiter (as Gherkin reads it).
+ */
+export const scenarioText = (source: string): string => {
+  const out: string[] = []
+  let doc: { readonly indent: number; readonly fence: string } | undefined
+  for (const line of source.split("\n")) {
+    const delimiter = DOC_STRING.exec(line)
+    if (doc === undefined && delimiter !== null) {
+      doc = { indent: delimiter[1]!.length, fence: delimiter[2]! }
+      out.push(line.trim())
+    } else if (doc !== undefined && line.trim().startsWith(doc.fence)) {
+      doc = undefined
+      out.push(line.trim())
+    } else if (doc !== undefined) {
+      const lead = line.length - line.trimStart().length
+      out.push(line.slice(Math.min(lead, doc.indent)).trimEnd())
+    } else {
+      const trimmed = line.trim()
+      if (trimmed !== "" && !trimmed.startsWith("#") && !trimmed.startsWith("@")) out.push(trimmed)
+    }
+  }
+  return out.join("\n")
+}
+
+const textOf = (path: string): string | undefined => {
+  const source = read(path)
+  return source === undefined ? undefined : scenarioText(source)
+}
+
+/** Snapshot `.feature` paths at `head()`, merged over `previous`; `undefined` when nothing is frozen. */
+export const freezeScenarios = (
+  paths: readonly string[],
+  previous?: FrozenScenarios,
+): FrozenScenarios | undefined => {
+  if (paths.length === 0) return previous
+  const texts: Record<string, string> = { ...previous?.texts }
+  for (const path of paths) {
+    const text = textOf(path)
+    if (text !== undefined) texts[path] = text
+  }
+  return Object.keys(texts).length === 0 ? previous : { at: head(), texts }
+}
+
+/** Paths whose wording differs from the snapshot (a deleted file counts). */
+export const driftedScenarios = (frozen: FrozenScenarios): readonly string[] =>
+  Object.entries(frozen.texts)
+    .filter(([path, text]) => textOf(path) !== text)
+    .map(([path]) => path)
+
+// Blank lines survive only inside doc strings, where they are wording.
+const lines = (text: string | undefined): string[] =>
+  text === undefined || text === "" ? [] : text.split("\n")
+
+/** `table[i][j]`: the longest common subsequence of `a[i..]` and `b[j..]`. */
+const lcsTable = (a: readonly string[], b: readonly string[]): number[][] => {
+  const table = Array.from({ length: a.length + 1 }, () => Array<number>(b.length + 1).fill(0))
+  for (let i = a.length - 1; i >= 0; i--) {
+    for (let j = b.length - 1; j >= 0; j--) {
+      table[i]![j] =
+        a[i] === b[j] ? table[i + 1]![j + 1]! + 1 : Math.max(table[i + 1]![j]!, table[i]![j + 1]!)
+    }
+  }
+  return table
+}
+
+/** Changed lines in file order, `- ` / `+ `-prefixed, so a moved or repeated step still shows. */
+const lineDiff = (a: readonly string[], b: readonly string[]): string[] => {
+  const table = lcsTable(a, b)
+  const out: string[] = []
+  let i = 0
+  let j = 0
+  while (i < a.length && j < b.length) {
+    if (a[i] === b[j]) {
+      i++
+      j++
+    } else if (table[i + 1]![j]! >= table[i]![j + 1]!) out.push(`- ${a[i++]}`)
+    else out.push(`+ ${b[j++]}`)
+  }
+  return [...out, ...a.slice(i).map((l) => `- ${l}`), ...b.slice(j).map((l) => `+ ${l}`)]
+}
+
+export const wordingDrift = (frozen: FrozenScenarios, path: string): t.WordingDrift => ({
+  path,
+  lines: lineDiff(lines(frozen.texts[path]), lines(textOf(path))),
+})
+
+/** After a turn: stop at `scenario-wording` while wording drifted; accept moves the snapshot. */
+export const holdWording = async (frozen: FrozenScenarios | undefined): Promise<void> => {
+  if (frozen === undefined) return
+  const drifted = driftedScenarios(frozen)
+  if (drifted.length === 0) return
+  await human("scenario-wording", {
+    message: t.scenarioWordingMessage(
+      frozen.at,
+      drifted.map((path) => wordingDrift(frozen, path)),
+    ),
+    label: "Scenario wording changed",
+    acceptClean: true,
+    base: frozen.at,
+  })
+  // Still differing is accepted; restored is rejected and stays frozen as it was.
+  const accepted = driftedScenarios(frozen)
+  if (accepted.length === 0) return
+  for (const path of accepted) {
+    const text = textOf(path)
+    if (text === undefined) delete frozen.texts[path]
+    else frozen.texts[path] = text
+  }
+  frozen.at = head()
+}
+
+/** `turn`, then `holdWording`; `within` names the scope the gate rests in. */
+export const guarded =
+  (
+    frozen: FrozenScenarios | undefined,
+    turn: () => Promise<void>,
+    within?: string,
+  ): (() => Promise<void>) =>
+  async () => {
+    await turn()
+    if (within === undefined) await holdWording(frozen)
+    else await scope(within, () => holdWording(frozen))
+  }

package/src/workflows/skills.test.ts

@@ -1,8 +1,8 @@
 import { describe, expect, it } from "vitest"
 import { skills } from "./skills.js"
-import { unified } from "./index.js"
+import { bundled as workflow } from "./index.js"
 
-const { defaults } = unified
+const { defaults } = workflow
 
 const bundled = skills(defaults)
 
@@ -18,8 +18,6 @@ describe("the bundled workflow's skills export", () => {
         "architecture.decompose",
         "packages.item",
         "packages.item.fix.suite",
-        "packages.item.fix.spec",
-        "packages.item.spec",
         "packages.item.health",
         "build",
         "build.health",
@@ -50,8 +48,6 @@ describe("the bundled workflow's skills export", () => {
       "architecture.decompose": ["incremental-implementation", "planning-and-task-breakdown"],
       "packages.item": ["test-driven-development", "incremental-implementation"],
       "packages.item.fix.suite": ["debugging-and-error-recovery"],
-      "packages.item.fix.spec": ["incremental-implementation", "code-simplification"],
-      "packages.item.spec": ["code-review-and-quality", "spec-driven-development"],
       "packages.item.health": ["debugging-and-error-recovery"],
       build: ["debugging-and-error-recovery"],
       "build.health": ["debugging-and-error-recovery"],

package/src/workflows/skills.ts

@@ -15,8 +15,6 @@ export const skills = (
   "architecture.decompose": ["incremental-implementation", "planning-and-task-breakdown"],
   "packages.item": ["test-driven-development", "incremental-implementation"],
   "packages.item.fix.suite": ["debugging-and-error-recovery"],
-  "packages.item.fix.spec": ["incremental-implementation", "code-simplification"],
-  "packages.item.spec": ["code-review-and-quality", "spec-driven-development"],
   // `health` is shared code reached from both `packages.item` and `build`.
   "packages.item.health": ["debugging-and-error-recovery"],
   build: ["debugging-and-error-recovery"],

package/src/workflows/steps.test.ts

@@ -40,18 +40,8 @@ describe("the bundled workflow's steps declare skills — a bundled step's rende
     expect(prompt).toContain("debugging-and-error-recovery")
   })
 
-  it("fixSpec carries packages.item.fix.spec's bundled skills", async () => {
-    const prompt = agentPrompt(await capture(() => steps.fixSpec("pkg"), "packages.item"))
-    expect(prompt).toContain("incremental-implementation, code-simplification")
-  })
-
-  it("reviewPackage carries packages.item.spec.review's bundled skills", async () => {
-    const prompt = agentPrompt(await capture(() => steps.reviewPackage("pkg"), "packages.item"))
-    expect(prompt).toContain("code-review-and-quality, spec-driven-development")
-  })
-
   it("fix carries build.fix's bundled skills", async () => {
-    const prompt = agentPrompt(await capture(() => steps.fix(), "build"))
+    const prompt = agentPrompt(await capture(() => steps.fixCheck(), "build"))
     expect(prompt).toContain("debugging-and-error-recovery")
   })
 
@@ -120,7 +110,7 @@ describe("the bundled workflow's steps declare skills — a bundled step's rende
   })
 
   it("an empty configured list leaves that step's skills empty, and its rendered prompt bare", async () => {
-    const request = await capture(() => steps.fix(), "build", { build: [] })
+    const request = await capture(() => steps.fixCheck(), "build", { build: [] })
     if (request.kind !== "agent") throw new Error("unreachable")
     expect(request.prompt).not.toContain("Load whatever's listed here")
   })

package/src/workflows/steps.ts

@@ -12,7 +12,6 @@ export const REQUIREMENTS = ".gtd/REQUIREMENTS.md"
 export const ARCHITECTURE = ".gtd/ARCHITECTURE.md"
 export const REVIEW = ".gtd/REVIEW.md"
 export const QUALITY = ".gtd/QUALITY.md"
-export const SPEC_FEEDBACK = ".gtd/SPEC_FEEDBACK.md"
 
 const planner = (): string => env.plannerModel ?? ""
 const coder = (): string => env.coderModel ?? ""
@@ -80,27 +79,10 @@ export const fixSuite = (): Promise<void> =>
     system: t.builderSystem(),
   })
 
-export const fixSpec = (pkg: string): Promise<void> =>
-  t.agentWithSkills("fix.spec.fixing", t.packagesItemFixSpecPrompt(pkg), {
-    label: "Fixing review feedback",
-    file: SPEC_FEEDBACK,
-    model: coder(),
-    system: t.builderSystem(),
-  })
-
-/** Review `pkg` against its spec, focused on the `failing` sections the pre-judge could not clear. */
-export const reviewPackage = (pkg: string, failing: readonly string[] = []): Promise<void> =>
-  t.agentWithSkills("spec.review", t.packagesItemSpecReviewPrompt(pkg, failing), {
-    label: "Reviewing the package",
-    model: planner(),
-    system: t.specReviewerSystem(),
-    allowEmpty: true,
-  })
-
 // ── Keeping the suite green ─────────────────────────────────────────────────
 
-export const fix = (): Promise<void> =>
-  t.agentWithSkills("fix", t.buildFixPrompt(), {
+export const fixCheck = (built?: t.BuildContext): Promise<void> =>
+  t.agentWithSkills("fix", t.buildFixPrompt(built), {
     label: "Fixing the check",
     file: FEEDBACK,
     model: coder(),

package/src/workflows/text.test.ts

@@ -4,6 +4,7 @@ import {
   agentWithSkills,
   architectureAuthorPrompt,
   architectureGateAnswerMessage,
+  buildFixPrompt,
   buildFixQualityPrompt,
   buildQualityReviewingPrompt,
   buildReviewAwaitReviewMessage,
@@ -160,6 +161,65 @@ describe("architectureAuthorPrompt", () => {
     const prompt = renderText(() => architectureAuthorPrompt())
     expect(prompt).toContain("is an open question, not a")
   })
+  it("names the four content sections in order and the entry forms", () => {
+    const prompt = renderText(() => architectureAuthorPrompt())
+    const at = ["## Interfaces", "## Call Stacks", "## E2E Scenarios", "## Unit Tests"].map((h) =>
+      prompt.indexOf(h),
+    )
+    expect(at.every((i) => i >= 0)).toBe(true)
+    expect([...at].sort((a, b) => a - b)).toEqual(at)
+    expect(prompt).toContain("- unit: <path>")
+    expect(prompt).toContain("- e2e: <path>")
+    expect(prompt).toContain("- chore: <path>")
+    expect(prompt).toContain("No e2e change.")
+  })
+})
+
+describe("buildFixPrompt with build context", () => {
+  const built = {
+    ranges: [
+      { pkg: "00-scenarios", from: "aaa1111", to: "bbb2222" },
+      { pkg: "01-engine", from: "bbb2222", to: "ccc3333" },
+    ],
+    scenarios: { added: ["tests/new.feature"], changed: ["tests/old.feature"] },
+  }
+
+  it("points at the architecture document", () => {
+    expect(renderText(() => buildFixPrompt(built))).toContain(".gtd/ARCHITECTURE.md")
+  })
+
+  it("lists new scenario paths as likely missing wiring", () => {
+    const prompt = renderText(() => buildFixPrompt(built))
+    expect(prompt).toContain("tests/new.feature")
+    expect(prompt).toContain("missing wiring")
+  })
+
+  it("lists changed or existing scenarios as regressions", () => {
+    const prompt = renderText(() => buildFixPrompt(built))
+    expect(prompt).toContain("regression")
+    expect(prompt).toContain("tests/old.feature")
+  })
+
+  it("lists one range line per package", () => {
+    const prompt = renderText(() => buildFixPrompt(built))
+    expect(prompt).toContain("git log --oneline aaa1111..bbb2222  # 00-scenarios")
+    expect(prompt).toContain("git log --oneline bbb2222..ccc3333  # 01-engine")
+  })
+
+  it("is today's prompt without a build context", () => {
+    const prompt = renderText(() => buildFixPrompt())
+    expect(renderText(() => buildFixPrompt(undefined))).toBe(prompt)
+    expect(prompt).toMatch(/\n- Leave everything uncommitted — do not commit\n$/)
+    expect(prompt).toContain("writes its own\n- Leave")
+    expect(prompt).not.toContain("ARCHITECTURE")
+    expect(prompt).not.toContain("git log --oneline")
+  })
+
+  it("starts each bullet on its own line", () => {
+    const prompt = renderText(() => buildFixPrompt(built))
+    expect(prompt).toMatch(/^- Read `\.gtd\/ARCHITECTURE\.md`/m)
+    expect(prompt).toMatch(/^- Leave everything uncommitted/m)
+  })
 })
 
 describe("buildFixQualityPrompt", () => {