@pmelab/gtd 18.0.0 → 19.0.0

package/src/workflows/text.ts

@@ -3,12 +3,15 @@ import {
   codeThreads,
   env,
   head,
+  quote,
+  accessFor,
   skillsFor,
   start,
   type AgentOptions,
   type SummaryContext,
 } from "../flows/index.js"
 import {
+  accessPreamble,
   skillsPreamble,
   styleBlock,
   styleFormatContract,
@@ -16,7 +19,6 @@ import {
   designPersona,
   architectPersona,
   reviewerPersona,
-  specReviewerPersona,
   builderPersona,
   finisherPersona,
   escalationPersona,
@@ -37,12 +39,16 @@ export const withSkills = (skills: string | undefined, prompt: string): string =
   return `${skillsPreamble.replaceAll("{skills}", skills)}\n\n${prompt}`
 }
 
-/** An `agent()` step whose prompt opens with the preamble naming its scope's skills. */
+/** An `agent()` step whose prompt opens with the preamble naming its scope's skills, then its restricted file access. */
 export const agentWithSkills = (
   name: string,
   prompt: string,
   options: AgentOptions = {},
-): Promise<void> => agent(name, withSkills(skillsFor(name).join(", "), prompt), options)
+): Promise<void> => {
+  const access = accessPreamble(accessFor(name, options.file))
+  const body = access === "" ? prompt : `${access}\n\n${prompt}`
+  return agent(name, withSkills(skillsFor(name).join(", "), body), options)
+}
 
 export const unwindFailure = (commit: string): string =>
   `gtd could not unwind ${commit} out of your working tree.`
@@ -76,16 +82,6 @@ What each change does next (then run \`gtd land\`):
 - **Continue** — having undone the sketch by hand, check the test baseline is green and start triage (**start-gate.check**).
 `
 
-export const architecturePreMessage = (): string =>
-  `Judging whether \`.gtd/REQUIREMENTS.md\`'s settled concerns need a
-dedicated architecture pass — real structural decisions, multiple
-integration points, or a non-obvious tradeoff — before packages
-are written. Run \`gtd judge answer\` and pipe a verdict for
-\`architectureWarranted\` — or land untouched to run the full pass
-(the conservative default; a skipped judgment never suppresses
-it).
-`
-
 export const startGateBlockedMessage = (): string =>
   `The test baseline is red — gtd will not start new work on a broken suite.
 \`.gtd/FEEDBACK.md\` holds the failing output.
@@ -263,22 +259,46 @@ ${footnoteFoldIn}${codeThreadReplies()}
   authority is to merge only, never to split — the whole problem
   is over-granularity
 - Record every merge under \`## Merged Concerns\`,
-  carrying both merged requirements verbatim so spec review
-  still covers each independently
+  carrying both merged requirements verbatim so each requirement
+  stays traceable to its tests
 - A merge raises no open question and stops for no
   human — do not route it to \`architecture.gate\` for a veto; the
-  human sees it when reviewing the plan, and spec review is the
-  real safety net
+  human sees it when reviewing the plan
 - Prefer fewer, larger packages — the smallest independently
   valuable change, not the smallest change that compiles
 - 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 at spec review
+  technical call is still caught by the full 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
 
+- \`.gtd/ARCHITECTURE.md\` is the acceptance spec the human signs
+  off. It carries these sections, in this order:
+  1. \`## Open Questions\` (qa format, first, only when present)
+  2. \`## Interfaces\` — new and changed signatures/contracts
+     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
+  5. \`## Unit Tests\` — one \`### <interface>\` per entry of
+     \`## Interfaces\`, each test a line
+     \`- unit: <path> — <behaviour> (covers <concern>)\`;
+     never against an internal helper. A requirement no test can
+     cover (docs, README, deletions, config) goes under a
+     \`### Chores\` heading in this section as
+     \`- chore: <path> — <what> (covers <concern>)\`
+  6. \`## Merged Concerns\` — kept, when any merge happened
+  7. \`## Answered Questions\` — last
+- Coverage rule: every concern in \`.gtd/REQUIREMENTS.md\` appears
+  in at least one \`(covers …)\` tail, as a test or a chore. Each
+  test entry carries its file path and level (unit / e2e)
+
 ${questionBar}
 ## Return lap
 
@@ -294,26 +314,41 @@ export const architectureDecomposePrompt = (): string =>
 
 ${stateFileRules}
 - The only state files this turn touches are the package files
-  under \`.gtd/packages/\` and \`.gtd/ARCHITECTURE.md\` (deleted) —
-  no other files for notes or output
+  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
 - Work from \`.gtd/ARCHITECTURE.md\` if you wrote it earlier this
   conversation, otherwise read it (the converged technical
-  plan). It already lists an ordered set of concerns with every
-  merge/split judgement made — this turn is a mechanical
-  write-out, not a planning one. A \`## Merged Concerns\` heading
-  there records those merges, never a concern of its own: write
-  no package file for it
-- Write one package file per concern, in the settled order,
-  under \`.gtd/packages/\` (e.g. \`.gtd/packages/01-name.md\`,
-  \`02-name.md\`, ...), each carrying that concern's
-  requirement(s) — both, independently, if merged — its
-  independent tasks, and each task's acceptance criteria as
-  \`- [ ]\` checkboxes and relevant paths
-- Do not merge or split concerns here — that judgement already
-  happened; carry the settled grouping over verbatim. No
-  package file may reference any other \`.gtd/\` file
-- Once written, delete \`.gtd/ARCHITECTURE.md\`. Leave everything
-  uncommitted and finish
+  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
+- 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
+- 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
+- Leave everything uncommitted and finish
 `
 
 export const architectureGateAnswerMessage = (): string =>
@@ -346,7 +381,7 @@ What each change does next (then run \`gtd land\`):
 export const packagesItemBuildingPrompt = (pkg: string): string =>
   `${stateFileRules}
 - The only state file this turn may write is \`.gtd/SATISFIED.md\`;
-  never delete the package file (the spec-review gate reads it
+  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 —
@@ -355,6 +390,13 @@ export const packagesItemBuildingPrompt = (pkg: string): string =>
   with each criterion's concrete evidence (commit, file, or
   symbol), change nothing else, and finish. Otherwise implement
   normally and skip that file
+- 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
 - 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
@@ -376,17 +418,6 @@ ${fixFeedbackPrompt}
 - Leave everything uncommitted and finish your turn — do not commit
 `
 
-export const packagesItemFixSpecPrompt = (pkg: string): string =>
-  `${stateFileRules}
-- The only state file this turn touches is
-  \`.gtd/SPEC_FEEDBACK.md\` — address it, then delete it
-- Read it (the reviewer's concerns) and the package spec
-  (\`${pkg}\`), then fix the code to
-  resolve every concern
-- Delete \`.gtd/SPEC_FEEDBACK.md\` once resolved; leave everything
-  else uncommitted and finish your turn
-`
-
 export const healthJudgeMessage = (): string =>
   `The check is still red, and this isn't the first round —
 \`.gtd/FEEDBACK.md\` holds this round's output, and the previous round's
@@ -434,59 +465,34 @@ turn, or land untouched to give it one more attempt at the same
 analysis.
 `
 
-export const packagesItemSpecPreMessage = (): string =>
-  `Judging whether the code already satisfies each requirement in the
-package spec, before spending a full review turn. Run \`gtd judge
-answer\` and pipe a verdict per section — or land untouched to run
-the full review (the conservative default; a skipped judgment
-never suppresses anything).
-`
-
-/** The sections a pre-judge could not clear, when it cleared the rest. */
-const specScope = (failing: readonly string[]): string =>
-  failing.length > 0
-    ? `- A pre-judge already found the other sections satisfied. Confine
-  your review to only these sections:
-${failing.map((title) => `  - ${title}\n`).join("")}`
-    : ""
-
-export const packagesItemSpecReviewPrompt = (
-  pkg: string,
-  failing: readonly string[] = [],
-): string =>
-  `${styleBlock}
-
-You are reviewing a freshly-built work package against its own
-spec.
-
-${stateFileRules}
-- The only state file this turn touches is
-  \`.gtd/SPEC_FEEDBACK.md\` — write it only when you find problems
-- The package spec is \`${pkg}\`
-${specScope(failing)}- Verify the implementation against it: tasks done, criteria
-  met, code sound and consistent with the codebase. No diff is
-  given — read the range yourself, from \`${start()}\`
-  to the working tree, process-wide (it can span earlier
-  packages)
-- You own that bar; nothing downstream re-weighs your findings
-- Write nothing when the package fully satisfies its spec —
-  silence is your approval. Otherwise write
-  \`.gtd/SPEC_FEEDBACK.md\` listing what would violate the spec if
-  it shipped unaddressed, specific enough to act on, each as its
-  own \`## \` heading
-- Never fix anything yourself and never delete the package
-  file — a later step owns that
-`
-
-export const specReviewerSystem = (): string =>
-  `${specReviewerPersona}
+/** 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[]
+  }
+}
 
-${agentConduct}`
+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 = (): string =>
+export const buildFixPrompt = (built?: BuildContext): string =>
   `${stateFileRules}
 ${fixFeedbackPrompt}
-- Leave everything uncommitted — do not commit
+${built === undefined ? "" : buildContextPrompt(built)}- Leave everything uncommitted — do not commit
 `
 
 export const finisherSystem = (): string =>
@@ -877,3 +883,25 @@ ${it.processCostByModel.map((m) => `- ${m.model}: ${m.cost}\n`).join("")}
 Print the closing message and stop — this writes nothing itself.
 `
 }
+
+export interface WordingDrift {
+  readonly path: string
+  /** `- `/`+ `-prefixed, in file order. */
+  readonly lines: readonly string[]
+}
+
+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/unified.ts

@@ -14,7 +14,8 @@ import {
 } from "../flows/index.js"
 import { baseline, gate } from "./health.js"
 import { packages } from "./packages.js"
-import { architecturePass, design } from "./planning.js"
+import { architecture, design } from "./planning.js"
+import type { FrozenScenarios } from "./scenarios.js"
 import { buildTail, type ReviewOutcome } from "./review.js"
 import { ARCHITECTURE, FEEDBACK, REQUIREMENTS, REVIEW } from "./steps.js"
 import * as t from "./text.js"
@@ -33,11 +34,13 @@ import * as t from "./text.js"
 export { threads, type ThreadInfo } from "../flows/index.js"
 export { defaults, envDefaults } from "./vars.js"
 export { skills } from "./skills.js"
+export { access } from "./access.js"
 export { agentWithSkills } from "./text.js"
 export * from "./steps.js"
 export * from "./health.js"
 export * from "./planning.js"
 export * from "./packages.js"
+export * from "./scenarios.js"
 export * from "./review.js"
 
 /** Revert the sketch that started the process out of the working tree; its intent survives in history. */
@@ -69,11 +72,13 @@ export const reUnwind = async (
 /** Plan, build and review until a review round signs off; feedback re-plans from scratch. */
 export const planAndBuild = async (firstBase: string): Promise<void> => {
   let base = firstBase
+  let carried: FrozenScenarios | undefined
   for (;;) {
     await design(base)
-    await architecturePass()
-    await packages()
-    const outcome = await buildTail(false, base)
+    await architecture()
+    const built = await packages(carried)
+    carried = built.frozen
+    const outcome = await buildTail(false, base, built)
     if (outcome.verdict === "signoff") return
     await reUnwind(outcome)
     base = outcome.base

package/src/workflows/vars.ts

@@ -9,9 +9,7 @@ export const defaults: Readonly<Record<string, string>> = {
   reviewBase: "",
   judgeBudgetBytes: "32768",
   judgeIdenticalMinP: "0.7",
-  specPreJudge: "0.9",
   reviewNoteActionable: "0.7",
-  architectureSkipMinP: "0.85",
   // Decides the turn count: one `build.quality.<lens>` scope per entry, each
   // keyed in `./skills.ts`.
   qualityReviews:
@@ -21,6 +19,7 @@ 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/diff.test.ts

@@ -1,115 +0,0 @@
-import { describe, expect, it } from "vitest"
-import type { Change } from "../flows/index.js"
-import { filterChanges, packageDiff } from "./diff.js"
-
-const change = (over: Partial<Change> & Pick<Change, "path" | "status">): Change => ({
-  before: undefined,
-  after: undefined,
-  ...over,
-})
-
-// A cap high enough that nothing is ever dropped, for cases exercising the
-// rendering pipeline rather than the byte-budget behavior itself.
-const NO_CAP = 10_000
-
-describe("packageDiff / rendering", () => {
-  it("renders a normal edit as hunks with three lines of context", () => {
-    const before = Array.from({ length: 10 }, (_, i) => `line ${i + 1}`).join("\n")
-    const after = before.replace("line 5", "line five")
-    const text = packageDiff([change({ path: "a.ts", status: "modified", before, after })], NO_CAP)
-    expect(text).toContain("--- a/a.ts")
-    expect(text).toContain("+++ b/a.ts")
-    expect(text).toContain("-line 5")
-    expect(text).toContain("+line five")
-    // three lines of context on either side of the one changed line
-    expect(text).toContain(" line 2")
-    expect(text).toContain(" line 8")
-    expect(text).not.toContain(" line 1\n")
-  })
-
-  it("degrades a 1500+ line change to its summary line", () => {
-    const before = Array.from({ length: 2000 }, (_, i) => `line ${i}`).join("\n")
-    const after = Array.from({ length: 2000 }, (_, i) => `changed ${i}`).join("\n")
-    const text = packageDiff(
-      [change({ path: "big.ts", status: "modified", before, after })],
-      NO_CAP,
-    )
-    expect(text).toBe("big.ts: +2000/-2000 lines, too large to inline")
-  })
-
-  it("renders files in path order for byte-identical output across replays", () => {
-    const a = change({ path: "z.ts", status: "added", after: "z" })
-    const b = change({ path: "a.ts", status: "added", after: "a" })
-    expect(packageDiff([a, b], NO_CAP)).toBe(packageDiff([b, a], NO_CAP))
-    expect(packageDiff([a, b], NO_CAP).indexOf("a.ts")).toBeLessThan(
-      packageDiff([a, b], NO_CAP).indexOf("z.ts"),
-    )
-  })
-})
-
-describe("filterChanges / exclusion list", () => {
-  it("excludes a lockfile change entirely", () => {
-    const c = change({ path: "package-lock.json", status: "modified", before: "a", after: "b" })
-    expect(filterChanges([c])).toEqual([])
-    expect(packageDiff([c], NO_CAP)).toBe("")
-  })
-
-  it("excludes .gtd/** paths", () => {
-    const c = change({ path: ".gtd/PLAN.md", status: "added", after: "x" })
-    expect(filterChanges([c])).toEqual([])
-  })
-
-  it("excludes a binary file by extension", () => {
-    const c = change({ path: "logo.png", status: "added", after: "binary-ish" })
-    expect(filterChanges([c])).toEqual([])
-  })
-
-  it("excludes a binary file by content, separately from extension", () => {
-    const c = change({ path: "weird.txt", status: "added", after: "abc\0def" })
-    expect(filterChanges([c])).toEqual([])
-  })
-
-  it("keeps an ordinary source file", () => {
-    const c = change({ path: "src/a.ts", status: "added", after: "export const a = 1\n" })
-    expect(filterChanges([c])).toEqual([c])
-  })
-})
-
-describe("packageDiff", () => {
-  it("drops whole files from the end and names them in a trailer", () => {
-    const a = change({ path: "a.ts", status: "added", after: "export const a = 1\n" })
-    const b = change({
-      path: "b.ts",
-      status: "added",
-      after: Array.from({ length: 50 }, (_, i) => `line ${i}`).join("\n"),
-    })
-    const text = packageDiff([a, b], 120)
-    expect(text).toContain("--- /dev/null")
-    expect(text).toContain("+++ b/a.ts")
-    expect(text).not.toContain("b.ts\n")
-    expect(text).toContain("1 file(s) omitted for the judge's byte budget: b.ts")
-  })
-
-  it("counts the omission trailer itself against the cap, so many dropped paths never push the total past it", () => {
-    const kept = change({ path: "a.ts", status: "added", after: "export const a = 1\n" })
-    const rest = Array.from({ length: 6 }, (_, i) =>
-      change({ path: `f${i}.ts`, status: "added", after: "y" }),
-    )
-    // A naive cap check (size the kept text alone, append the trailer
-    // afterwards) would keep a.ts plus two of the small files here — 150
-    // bytes of text — then tack on an unbudgeted trailer for the other four,
-    // landing well past capBytes. Budgeting the trailer itself must instead
-    // drop enough files that the total, trailer included, stays at or under it.
-    const capBytes = 150
-    const text = packageDiff([kept, ...rest], capBytes)
-    expect(Buffer.byteLength(text, "utf8")).toBeLessThanOrEqual(capBytes)
-    expect(text).toContain("omitted")
-  })
-
-  it("keeps every file when the cap is not exceeded", () => {
-    const a = change({ path: "a.ts", status: "added", after: "x" })
-    const text = packageDiff([a], 10_000)
-    expect(text).not.toContain("omitted")
-    expect(text).toContain("a.ts")
-  })
-})