@pmelab/gtd 24.4.0 → 26.0.0

package/src/workflows/shared/text.ts

@@ -10,7 +10,7 @@ import {
   type AgentOptions,
   type SummaryContext,
 } from "../../flows/index.js"
-import type { WordingDrift } from "../../workflow-kit/index.js"
+import type { RemovedAssertions } from "../../workflow-kit/index.js"
 import {
   accessPreamble,
   skillsPreamble,
@@ -274,7 +274,8 @@ ${footnoteFoldIn}${codeThreadReplies()}
 - Every open point here is TECHNICAL — triage already resolved
   the product ones, one phase earlier. PERMISSIVE: answer it
   yourself unless you genuinely cannot defend a default; a wrong
-  technical call is still caught by the full run and the quality lap
+  technical call is still caught by each package's suite run and the
+  quality lap
 - The narrow exception: a simplification that drops something
   \`.gtd/REQUIREMENTS.md\` mentions is an open question, not a
   silent default
@@ -286,11 +287,13 @@ ${footnoteFoldIn}${codeThreadReplies()}
      only, as fenced TypeScript (or the repository's language)
   3. \`## Call Stacks\` — seam level, entry point → module
      boundary; one line per hop, never per line of code
-  4. \`## E2E Scenarios\` — Gherkin in fenced \`gherkin\` blocks
-     (whatever e2e framework the repository uses), each preceded
-     by a line \`- e2e: <path>\`. With no user-visible
-     behaviour change, the literal line \`No e2e change.\` plus a
-     one-line reason — never empty or missing
+  4. \`## E2E Scenarios\` — one line per user-visible behaviour,
+     \`- e2e: <path> — <behaviour> (covers <concern>)\`, in plain
+     words: the builder writes the scenario in the repository's
+     own e2e framework, so never spell out Gherkin here. With no
+     user-visible behaviour change, the literal line
+     \`No e2e change.\` plus a one-line reason — never empty or
+     missing
   5. \`## Unit Tests\` — one \`### <interface>\` per entry of
      \`## Interfaces\`, each test a line
      \`- unit: <path> — <behaviour> (covers <concern>)\`;
@@ -320,35 +323,31 @@ export const architectureDecomposePrompt = (): string =>
 ${stateFileRules}
 - The only state files this turn touches are the package files
   under \`.gtd/packages/\` — no other files for notes or output.
-  Never delete \`.gtd/ARCHITECTURE.md\`: the build tail's full run
-  still needs it, and package files may reference it
+  Never delete \`.gtd/ARCHITECTURE.md\`: package files may
+  reference it, and it is removed with the last package
 - Work from \`.gtd/ARCHITECTURE.md\` if you wrote it earlier this
   conversation, otherwise read it (the converged technical
   plan). It already lists the concerns, interfaces, e2e scenarios
   and unit tests — this turn groups them into packages. A
   \`## Merged Concerns\` heading there records merges, never a
   concern of its own: write no package file for it
-- A package is a consecutive run of \`## Unit Tests\` entries that go
-  green together on the fast suite, at most ~8 unit-test entries
-  each. Keep the merge rule: concerns whose footprints centre on the
-  same files stay in one package unless the later one only consumes
-  an interface the earlier one creates. Prefer fewer, larger
-  packages. Order them so each stays green on the fast suite —
-  interface-introducing packages first
+- A package is one concern's slice, and each must leave the full
+  suite green — every package boundary costs a full run, so write
+  as few as the concerns allow. Keep the merge rule: concerns whose
+  footprints centre on the same files stay in one package unless
+  the later one only consumes an interface the earlier one creates.
+  Order them interface-introducing packages first
 - Write the packages under \`.gtd/packages/\`, each carrying its
   requirement(s) — both, independently, if merged — its tasks, and
   each task's acceptance criteria as \`- [ ]\` checkboxes and
   relevant paths:
-  - \`.gtd/packages/00-e2e-scenarios.md\` — package 0: it writes
-    \`## E2E Scenarios\` as tests in the repository's own e2e
-    framework and leaves them red. Write no such file when
-    \`## E2E Scenarios\` says "No e2e change."
-  - \`01-…\` onward — the unit-test packages. A requirement no test
-    covers (docs, README, deletions, config) becomes a chore
-    package, or a task of one; chore packages declare no tests
-  - the last numbered package is the wiring package: CLI entry,
-    workflow composition, config. A red e2e after it is a bug, not
-    missing work
+  - \`01-…\` onward — one vertical slice each: the unit tests,
+    the code, the wiring (CLI entry, workflow composition, config)
+    and every \`## E2E Scenarios\` entry its concern covers, so the
+    slice ends with its scenarios passing. A requirement no test
+    covers (docs, README, deletions, config) is a task of the slice
+    it belongs to; only one no slice owns becomes a chore package,
+    which declares no tests
 - 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
@@ -398,10 +397,10 @@ export const packagesItemBuildingPrompt = (pkg: string): string =>
 - 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
-- Package 0 (\`.gtd/packages/00-e2e-scenarios.md\`) writes the scenarios verbatim
-  from \`## E2E Scenarios\` of \`.gtd/ARCHITECTURE.md\`, with only
-  step code that typechecks, and leaves them red — no
-  implementation
+- 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
+  rather than adding one-off ones
 - Implement every task the package describes, no more, no less,
   fanning independent ones out to parallel subagents where your
   harness supports it; leave other package files untouched
@@ -470,34 +469,10 @@ turn, or land untouched to give it one more attempt at the same
 analysis.
 `
 
-/** What the tail's full-run fix needs of a `BuiltPlan` (structural: `packages.ts` imports this module). */
-export interface BuildContext {
-  readonly ranges: readonly { readonly pkg: string; readonly from: string; readonly to: string }[]
-  readonly scenarios: {
-    readonly added: readonly string[]
-    readonly changed: readonly string[]
-  }
-}
-
-const buildContextPrompt = (built: BuildContext): string => {
-  const list = (paths: readonly string[]): string =>
-    paths.length === 0 ? "  (none)" : paths.map((path) => `  - ${path}`).join("\n")
-  return `- Read \`.gtd/ARCHITECTURE.md\` — the plan every package was built from
-- A red scenario that is NEW in this plan likely means missing wiring
-  between packages; new scenarios:
-${list(built.scenarios.added)}
-- A red CHANGED or existing scenario or test is a regression a package
-  introduced; scenarios this plan changed:
-${list(built.scenarios.changed)}
-- Each package's commits, to bisect a break:
-${built.ranges.map((r) => `  git log --oneline ${r.from}..${r.to}  # ${r.pkg}`).join("\n")}
-`
-}
-
-export const buildFixPrompt = (built?: BuildContext): string =>
+export const buildFixPrompt = (): string =>
   `${stateFileRules}
 ${fixFeedbackPrompt}
-${built === undefined ? "" : buildContextPrompt(built)}- Leave everything uncommitted — do not commit
+- Leave everything uncommitted — do not commit
 `
 
 export const finisherSystem = (): string =>
@@ -888,7 +863,28 @@ actionability, and never dismiss a real note or edit as approval.
   the sign-off
 `
 
-export const buildReviewReviewingPrompt = (base: string, carry?: string): string =>
+const scenariosPrompt = (removed: readonly RemovedAssertions[]): string =>
+  `- When a scenario in a \`.feature\` file was added or changed since the
+  base, the first chunk is \`## Scenarios\`: one pointer per such
+  scenario, its note saying in plain words what behaviour it now pins
+  down — the human signs off the scenarios here, nowhere else
+${
+  removed.length === 0
+    ? ""
+    : `- These assertions of scenarios that existed at the base are gone:
+${removed.map(({ path, lines }) => lines.map((a) => `    ${path} — ${a.scenario} — ${a.line}\n`).join("")).join("")}  Open the note of each scenario that lost one with \`Weakened:\`,
+  naming the lost line and whether \`.gtd/REQUIREMENTS.md\` asked
+  for it. A scenario that no longer exists has no pointer of its own:
+  put its \`Weakened:\` note on a pointer of the chunk covering its
+  removal
+`
+}`
+
+export const buildReviewReviewingPrompt = (
+  base: string,
+  carry?: string,
+  removed: readonly RemovedAssertions[] = [],
+): string =>
   `${styleBlock}
 
 ${styleFormatContract}
@@ -931,7 +927,7 @@ review the changes:
   A note sitting entirely on the line(s) beneath the pointer is
   also valid. Either way, the note must never start with a bare \`./path\` token
   — that parses as a second pointer, not a note
-No diff is given — read the changes yourself. The range runs
+${scenariosPrompt(removed)}No diff is given — read the changes yourself. The range runs
 from \`${base}\` to the working tree (committed turns
 plus anything pending); on a feedback round that's the previous
 review's boundary, so it covers only what's new.
@@ -986,19 +982,3 @@ ${it.processCostByModel.map((m) => `- ${m.model}: ${m.cost}\n`).join("")}
 Print the closing message and stop — this writes nothing itself.
 `
 }
-
-export const scenarioWordingMessage = (at: string, drifted: readonly WordingDrift[]): string =>
-  `The e2e scenario wording was frozen when package 0 landed, and the last
-turn changed it. Removed lines are marked \`-\`, added ones \`+\`:
-
-${drifted.map(({ path, lines }) => `${path}\n${lines.join("\n")}`).join("\n\n")}
-
-To accept the change, land untouched.
-
-To reject it, run
-
-    git checkout ${at} -- ${drifted.map(({ path }) => quote(path)).join(" ")}
-
-and land. Restoring only some of the files is a partial accept: every file
-still differing from the frozen wording is accepted.
-`

package/src/workflows/shared/vars.ts

@@ -20,7 +20,6 @@ export const defaults: Readonly<Record<string, string>> = {
 /** Environment settings. */
 export const envDefaults: Readonly<Record<string, string>> = {
   testCommand: "npm test",
-  fastTestCommand: "",
   plannerModel: "smart",
   coderModel: "base",
 }

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

@@ -1,256 +0,0 @@
-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/shared/scenarios.ts

@@ -1,35 +0,0 @@
-import { human, scope } from "../../flows/index.js"
-import * as kit from "../../workflow-kit/index.js"
-import * as t from "./text.js"
-
-export {
-  driftedScenarios,
-  freezeScenarios,
-  scenarioText,
-  wordingDrift,
-  type FrozenScenarios,
-} from "../../workflow-kit/index.js"
-
-/** After a turn: stop at `scenario-wording` while wording drifted; accept moves the snapshot. */
-export const holdWording = (frozen: kit.FrozenScenarios | undefined): Promise<void> =>
-  kit.holdWording(frozen, (at, drifted) =>
-    human("scenario-wording", {
-      message: t.scenarioWordingMessage(at, drifted),
-      label: "Scenario wording changed",
-      acceptClean: true,
-      base: at,
-    }),
-  )
-
-/** `turn`, then `holdWording`; `within` names the scope the gate rests in. */
-export const guarded =
-  (
-    frozen: kit.FrozenScenarios | undefined,
-    turn: () => Promise<void>,
-    within?: string,
-  ): (() => Promise<void>) =>
-  async () => {
-    await turn()
-    if (within === undefined) await holdWording(frozen)
-    else await scope(within, () => holdWording(frozen))
-  }