@pmelab/gtd 18.0.0 → 19.0.0

package/src/workflows/packages.ts

@@ -1,109 +1,129 @@
 import {
-  answered,
-  changes,
   changesSince,
+  type Change,
   glob,
   head,
-  judge,
-  numeric,
   read,
   refuse,
   removeScript,
   run,
   scope,
-  sectionBodies,
-  vars,
-  wrote,
-  type JudgeQuestion,
 } from "../flows/index.js"
-import { packageDiff } from "./diff.js"
 import { healthy } from "./health.js"
-import { ARCHITECTURE, build, fixSpec, fixSuite, reviewPackage, SPEC_FEEDBACK } from "./steps.js"
-import * as t from "./text.js"
+import { freezeScenarios, guarded, type FrozenScenarios } from "./scenarios.js"
+import { build, fixSuite } from "./steps.js"
 
-const MAX_SECTIONS = 8
-const DIFF_KEY = "diff"
+/** Package 0: the e2e scenarios, written red. */
+export const SCENARIO_PACKAGE = ".gtd/packages/00-e2e-scenarios.md"
 
-const sectionQuestion = (id: string, title: string): JudgeQuestion => ({
-  id,
-  primitive: "noul",
-  instructions: `Is the requirement "${title}" — the "${id}" evidence — already fully satisfied by the code in the "${DIFF_KEY}" evidence?`,
-  criteria:
-    "Judge from the requirement text and the diff evidence alone. Only answer yes at a probability clearing the threshold below if genuinely confident nothing in this section is missing.",
-})
+export interface DeclaredTest {
+  readonly level: "unit" | "e2e"
+  readonly path: string
+}
+
+const TEST_LINE = /^\s*-\s+(unit|e2e):\s+`([^`]+)`/
+
+/** The `## Tests` entries of a package file; malformed lines 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]! })
+    }
+  }
+  return found
+}
 
 /**
- * Review one freshly built package against its spec: a pre-judge per
- * section, then an agent review of the sections it did not confidently
- * clear. `since` is the commit the package's own build started from — the
- * pre-judge's evidence is a diff over exactly that range, never an earlier
- * package's commits. Resolves `true` when approved.
+ * 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.
  */
-export const specReview = async (pkg: string, since: string): Promise<boolean> => {
-  const found = sectionBodies(read(pkg) ?? "")
-  const titles = found.map((section) => section.title)
-  const judged = titles.length > 0 && titles.length <= MAX_SECTIONS
-  const evidence: Record<string, string> = {}
-  const questions: JudgeQuestion[] = []
-  if (judged) {
-    found.forEach(({ title, body }, i) => {
-      evidence[`section-${i + 1}`] = body
-      questions.push(sectionQuestion(`section-${i + 1}`, title))
-    })
-    // The diff's own even share of the budget: one key per section plus
-    // `diff` itself, so this cap equals what `budgeted` gives it below.
-    const capBytes = Math.floor(numeric(vars.judgeBudgetBytes, 32768) / (found.length + 1))
-    evidence[DIFF_KEY] = packageDiff(changesSince(since), capBytes)
-  }
-  const { answers, truncated } = await judge("spec.pre", {
-    questions,
-    evidence,
-    message: t.packagesItemSpecPreMessage(),
-    label: "Judging spec coverage",
-  })
-  // A section is cleared only by a confident yes on evidence that was not
-  // cut — its own body, or the diff every question is judged against.
-  const clearMinP = numeric(vars.specPreJudge, Infinity)
-  const failing = titles.filter((_, i) => {
-    const id = `section-${i + 1}`
-    return (
-      !judged ||
-      truncated.includes(id) ||
-      truncated.includes(DIFF_KEY) ||
-      !answered(answers[id], "yes", clearMinP)
+export const requireDeclaredTests = (pkg: string, since: string): 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 (titles.length > 0 && failing.length === 0) return true
-  await reviewPackage(pkg, failing)
-  if (wrote(SPEC_FEEDBACK)) return false
-  if (changes(SPEC_FEEDBACK).length > 0 || changes().length === 0) return true
-  return refuse(
-    "gtd land: no declared pattern matches the pending changes — write .gtd/SPEC_FEEDBACK.md to request changes, or change nothing to approve",
+  if (missing.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")}`,
   )
 }
 
-/** Build `pkg`, keep the suite green, review it against its spec, and close it out, which removes it. */
-export const packageItem = async (pkg: string): Promise<void> => {
-  const since = head()
-  await build(pkg)
-  for (;;) {
-    await healthy(fixSuite)
-    if (await specReview(pkg, since)) break
-    await fixSpec(pkg)
+export interface PackageRange {
+  readonly pkg: string
+  readonly from: string
+  readonly to: string
+}
+
+export interface BuiltPlan {
+  readonly ranges: readonly PackageRange[]
+  /** Paths package 0 added / modified outside `.gtd/`. */
+  readonly scenarios: { readonly added: readonly string[]; readonly changed: readonly string[] }
+  /** The wording snapshot after this run, to guard the tail and later laps. */
+  readonly frozen: FrozenScenarios | undefined
+}
+
+/** Build `pkg`, check its declared tests, keep the fast suite green, and close it out, which removes it. */
+export const packageItem = async (pkg: string, frozen?: FrozenScenarios): Promise<PackageRange> => {
+  const from = head()
+  // Rechecked after every fix too: a fix deleting a red declared test would
+  // otherwise green the suite. Before the wording gate, so it refuses the turn.
+  const declared = (turn: () => Promise<void>) => async () => {
+    await turn()
+    requireDeclaredTests(pkg, from)
   }
-  // The spent technical plan goes with the first package built from it.
-  await run("closing", removeScript([pkg, SPEC_FEEDBACK, ".gtd/SATISFIED.md", ARCHITECTURE]), {
+  await guarded(
+    frozen,
+    declared(() => build(pkg)),
+  )()
+  await healthy(guarded(frozen, declared(fixSuite)), { suite: "fast" })
+  await run("closing", removeScript([pkg, ".gtd/SATISFIED.md"]), {
     label: "Closing out the package",
   })
+  return { pkg, from, to: head() }
 }
 
 /** The first queued package — the one a package step works on. */
 export const nextPackage = (): string | undefined => [...glob(".gtd/packages/*.md")].sort()[0]
 
+const outsideGtd = (path: string): boolean => path !== ".gtd" && !path.startsWith(".gtd/")
+
 /** Build every package file under `.gtd/packages/`, in name order. */
-export const packages = (): Promise<void> =>
+export const packages = (carried?: FrozenScenarios): Promise<BuiltPlan> =>
   scope("packages", async () => {
+    let frozen = carried
+    const ranges: PackageRange[] = []
+    // Captured right after package 0: a later diff to the tree would also hold what 01…N touch.
+    let touched: readonly Change[] = []
     for (let pkg = nextPackage(); pkg !== undefined; pkg = nextPackage()) {
-      await scope("item", () => packageItem(pkg))
+      const range = await scope("item", () =>
+        packageItem(pkg, pkg === SCENARIO_PACKAGE ? undefined : frozen),
+      )
+      ranges.push(range)
+      if (pkg === SCENARIO_PACKAGE) {
+        touched = changesSince(range.from).filter(
+          (c) => outsideGtd(c.path) && c.status !== "deleted",
+        )
+        frozen = freezeScenarios(
+          touched.filter((c) => c.path.endsWith(".feature")).map((c) => c.path),
+          frozen,
+        )
+      }
     }
+    const paths = (status: string): string[] =>
+      touched.filter((c) => c.status === status).map((c) => c.path)
+    return { ranges, scenarios: { added: paths("added"), changed: paths("modified") }, frozen }
   })

package/src/workflows/planning.ts

@@ -1,20 +1,12 @@
 import {
-  answered,
   changes,
   hasThreadFor,
-  judge,
-  moveScript,
-  numeric,
-  read,
   refuse,
   requireAnswers,
   requireReplies,
   requireThreadsClosed,
   requireProgress,
-  run,
   scope,
-  sections,
-  vars,
 } from "../flows/index.js"
 import {
   answerProductQuestions,
@@ -25,7 +17,6 @@ import {
   REQUIREMENTS,
   triage,
 } from "./steps.js"
-import * as t from "./text.js"
 
 /**
  * Always stop for the human. Resolves `true` when the round changed anything
@@ -62,44 +53,9 @@ export const architecture = (): Promise<void> =>
     if (changes(".gtd/packages/**").length === 0) {
       refuse("gtd land: decompose: write at least one package under .gtd/packages/")
     }
+    if (changes(ARCHITECTURE).some((c) => c.status === "deleted")) {
+      refuse(
+        "gtd land: decompose: keep .gtd/ARCHITECTURE.md — the build tail's full run needs it; it is removed only once that run is green",
+      )
+    }
   })
-
-/** A package file name from a plan's first heading. */
-const slug = (title: string): string =>
-  title
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "") || "package"
-
-/** Whether the settled plan needs its own architecture pass, or goes straight to one package. */
-export const architecturePass = async (): Promise<void> => {
-  const { answers, truncated } = await judge("architecture-pre", {
-    questions: [
-      {
-        id: "architectureWarranted",
-        primitive: "noul",
-        instructions:
-          "Given the settled concerns in `.gtd/REQUIREMENTS.md` (in state), does this plan warrant a dedicated architecture pass — real structural decisions, multiple integration points, or a non-obvious tradeoff — before packages are written?",
-        criteria:
-          "Answer yes if uncertain; a trivial, single-concern, mechanical plan with no real design decision answers no.",
-      },
-    ],
-    evidence: { requirements: read(REQUIREMENTS) ?? "" },
-    message: t.architecturePreMessage(),
-    label: "Judging whether this plan warrants an architecture pass",
-  })
-  // A plan the budget cut can hide its structural concerns from the judge:
-  // never skip the architecture pass on it, however confident the "no".
-  const skip =
-    truncated.length === 0 &&
-    answered(answers.architectureWarranted, "no", numeric(vars.architectureSkipMinP, Infinity))
-  const plan = read(REQUIREMENTS)
-  if (skip && plan !== undefined) {
-    const target = `.gtd/packages/01-${slug(sections(plan)[0] ?? "")}.md`
-    await run("architecture-promote", moveScript(REQUIREMENTS, target), {
-      label: "Promoting the plan straight to a package",
-    })
-    return
-  }
-  await architecture()
-}

package/src/workflows/prose.ts

@@ -12,6 +12,23 @@ export const skillsPreamble = `- Load whatever's listed here that your harness a
 - Never let a loaded skill turn this turn interactive — answer nothing,
   ask nothing; this runs unattended, with no one at a keyboard`
 
+/** One bullet per restricted side; empty when neither is. An empty glob list reads "nothing". */
+export const accessPreamble = (access: {
+  readonly read: readonly string[] | null
+  readonly write: readonly string[] | null
+}): string => {
+  const globs = (list: readonly string[]): string =>
+    list.length === 0 ? "nothing" : list.join(", ")
+  return [
+    ...(access.read === null ? [] : [`- This turn may read only: ${globs(access.read)}`]),
+    ...(access.write === null
+      ? []
+      : [
+          `- This turn may write only: ${globs(access.write)} — anything else is refused when the turn lands`,
+        ]),
+  ].join("\n")
+}
+
 export const styleBlock = `- A deliverable, not a chat reply — size follows the work; cut padding
 - Lead with the answer; never circle back to restate it
 - Flat, commanding sentences — commit to the claim, never hedge
@@ -60,8 +77,7 @@ export const architectPersona = `You are the technical planning voice in gtd's b
 once product concerns are settled, reading them cold, no carried
 conversation. Work out the *how* per concern — structure, data models,
 tech-stack choices, error handling — raise the technical open
-questions, then write one package spec per concern with no further
-judgement call: the grouping is already decided.`
+questions, then pin interfaces and tests in the architecture document.`
 
 export const reviewerPersona = `You are the independent reviewing mind in gtd's build pipeline —
 deliberately separate from whoever wrote the code, with no attachment
@@ -72,13 +88,6 @@ and, when asked, fix the small nits the human flagged and the risks
 you marked yourself, each in one batch.
 Beyond that you never fix or build anything yourself.`
 
-export const specReviewerPersona = `You are the adversarial spec-conformance checker in gtd's build
-pipeline, checking one freshly-built package against its spec. Verify
-only: tasks done, criteria met, code sound and consistent with the
-codebase. Write feedback only when something is genuinely wrong —
-otherwise write nothing; a clean turn IS the approval. Never fix what
-you find — naming it precisely enough for a fix turn is the whole job.`
-
 export const builderPersona = `You are the TDD implementer in gtd's build pipeline: build one
 package's declared scope end to end, tests first, and come back to fix
 things when redirected — a failing check, or reviewer feedback. Stay

package/src/workflows/review.test.ts

@@ -1,6 +1,6 @@
 import { afterEach, describe, expect, it } from "vitest"
 import { installContext, type Change, type JudgeAnswer, type StepRequest } from "../flows/index.js"
-import { review, type ReviewOutcome } from "./review.js"
+import { fixQualityFindings, review, type ReviewOutcome } from "./review.js"
 import { unified } from "./index.js"
 import { fixtureContext } from "./text.fixture.js"
 
@@ -331,3 +331,90 @@ describe("the default quality lenses", () => {
     ])
   })
 })
+
+describe("scenario wording in review's fix turns", () => {
+  const frozen = { at: "h1", texts: { "e2e/a.feature": "Given a" } }
+  const risky = doc(["Risk: drops the carry", "sub"])
+
+  it("a green-keeping fix after a risk fix that rewrites a scenario stops at review.scenario-wording", async () => {
+    const log: string[] = []
+    let red = false
+    let drifted = false
+    installContext(
+      fixtureContext(
+        {},
+        {
+          step: (request: StepRequest) => {
+            if (request.kind === "restart") return Promise.resolve()
+            log.push(request.name)
+            if (request.name === "health.check") red = !red && !drifted
+            if (request.name === "fix") drifted = true
+            if (request.name === "scenario-wording") throw new Stop()
+            return Promise.resolve()
+          },
+          pushScope: () => undefined,
+          popScope: () => undefined,
+          read: (path) =>
+            path === REVIEW
+              ? risky
+              : path === "e2e/a.feature"
+                ? drifted
+                  ? "Given b"
+                  : "Given a"
+                : undefined,
+          changes: (): readonly Change[] =>
+            red
+              ? [{ path: ".gtd/FEEDBACK.md", status: "added", before: undefined, after: "red" }]
+              : [],
+          matches: (path, pattern) => path === pattern,
+          head: () => "h2",
+          start: () => "h0",
+        },
+      ),
+    )
+    await review("base", undefined, frozen).catch((e: unknown) => {
+      if (!(e instanceof Stop)) throw e
+    })
+    expect(log.slice(-2)).toEqual(["fix", "scenario-wording"])
+  })
+})
+
+describe("the quality fix loop", () => {
+  it("a fix that resolves QUALITY.md and rewrites a scenario ends after the wording gate", async () => {
+    const QUALITY = ".gtd/QUALITY.md"
+    const log: string[] = []
+    const files = new Map([
+      [QUALITY, "- finding"],
+      ["e2e/a.feature", "Given a"],
+    ])
+    let last: readonly Change[] = []
+    installContext(
+      fixtureContext(
+        {},
+        {
+          step: (request: StepRequest) => {
+            if (request.kind === "restart") return Promise.resolve()
+            log.push(request.name)
+            last = []
+            if (request.name === "fix.quality.fixing") {
+              files.delete(QUALITY)
+              files.set("e2e/a.feature", "Given b")
+              last = [{ path: QUALITY, status: "deleted", before: "- finding", after: undefined }]
+            }
+            return Promise.resolve()
+          },
+          pushScope: () => undefined,
+          popScope: () => undefined,
+          read: (path) => files.get(path),
+          changes: () => last,
+          matches: (path, pattern) => path === pattern,
+          head: () => "h2",
+          start: () => "h0",
+        },
+      ),
+    )
+    const frozen = { at: "h1", texts: { "e2e/a.feature": "Given a" } }
+    expect(await fixQualityFindings({ rounds: 0 }, frozen)).toBe(true)
+    expect(log).toEqual(["fix.quality.fixing", "scenario-wording"])
+  })
+})

package/src/workflows/review.ts

@@ -19,8 +19,11 @@ import {
 } from "../flows/index.js"
 import { reviewNotes, reviewRisks, stripCodeThreads, type ReviewNote } from "../steering/index.js"
 import { escalation, FIX_CAP, healthy, type EscalationCount } from "./health.js"
+import type { BuiltPlan } from "./packages.js"
+import { guarded, type FrozenScenarios } from "./scenarios.js"
 import {
   answerReviewQuestions,
+  ARCHITECTURE,
   awaitReview,
   collecting,
   fix,
@@ -54,10 +57,14 @@ export const qualityLap = async (): Promise<"clean" | "findings"> => {
 }
 
 /** Resolves `true` once `.gtd/QUALITY.md` is resolved, `false` when the fix cap escalated instead. */
-export const fixQualityFindings = async (escalations: EscalationCount): Promise<boolean> => {
+export const fixQualityFindings = async (
+  escalations: EscalationCount,
+  frozen?: FrozenScenarios,
+): Promise<boolean> => {
   for (let turns = 0; turns < FIX_CAP; turns++) {
-    await fixQuality()
-    if (changes(QUALITY).some((c) => c.status === "deleted")) return true
+    await guarded(frozen, fixQuality)()
+    // Not `changes()`: a wording gate after the fix would be the last step.
+    if (read(QUALITY) === undefined) return true
   }
   await escalation(escalations)
   return false
@@ -203,6 +210,7 @@ type Finish =
 interface Round {
   readonly round: string
   readonly escalations: EscalationCount
+  readonly frozen: FrozenScenarios | undefined
   readonly close: () => Promise<void>
   readonly outcome: (verdict: "signoff" | "feedback") => ReviewOutcome
   readonly unfolded: () => Promise<Finish>
@@ -221,8 +229,8 @@ const routeNotes = async (notes: readonly ReviewNote[], r: Round): Promise<Finis
     answeredAt = head()
   }
   if (nits.length > 0) {
-    await fixNits(nits)
-    await healthy(fix, { escalations: r.escalations })
+    await guarded(r.frozen, () => fixNits(nits), "review")()
+    await healthy(guarded(r.frozen, fix, "review"), { escalations: r.escalations })
   }
   if (edits.length > 0) {
     await r.close()
@@ -239,6 +247,7 @@ const finish = async (
   reviewed: string,
   collectedAt: string | undefined,
   escalations: EscalationCount,
+  frozen: FrozenScenarios | undefined,
 ): Promise<Finish> => {
   // Everything the human did is read before any agent turn runs, so a nit fix
   // is never counted as a hand-edit.
@@ -268,7 +277,7 @@ const finish = async (
   if (edited.length > 0) return collectWith(t.reviewEditsCapture(round))
   const notes = reviewNotes(baselineText, record)
   if (notes.length === 0) return collectWith(t.reviewNotesCapture(round))
-  return routeNotes(notes, { round, escalations, close, outcome, unfolded })
+  return routeNotes(notes, { round, escalations, frozen, close, outcome, unfolded })
 }
 
 /** Write the review; if it marks risks, fix them, keep green, and write it again — once, so the re-review's own risks reach the human unfixed. */
@@ -276,12 +285,13 @@ const reviewOnce = async (
   base: string,
   carry: string | undefined,
   escalations: EscalationCount,
+  frozen: FrozenScenarios | undefined,
 ): Promise<void> => {
   await reviewing(base, carry)
   const risks = reviewRisks(read(REVIEW) ?? "")
   if (risks.length === 0) return
-  await fixRisks(risks)
-  await healthy(fix, { escalations })
+  await guarded(frozen, () => fixRisks(risks), "review")()
+  await healthy(guarded(frozen, fix, "review"), { escalations })
   await reviewing(base, carry)
 }
 
@@ -294,17 +304,18 @@ const reviewOnce = async (
 export const review = async (
   base: string,
   escalations: EscalationCount = { rounds: 0 },
+  frozen?: FrozenScenarios,
 ): Promise<ReviewOutcome> => {
   let carry: string | undefined
   for (;;) {
-    await reviewOnce(base, carry, escalations)
+    await reviewOnce(base, carry, escalations, frozen)
     carry = undefined
     let reviewed = head()
     let collectedAt: string | undefined
     for (;;) {
       collectedAt = await converse(base, collectedAt)
       if (collectedAt === "missing") break
-      const result = await finish(reviewed, collectedAt, escalations)
+      const result = await finish(reviewed, collectedAt, escalations, frozen)
       if (!("next" in result)) return result
       if (result.next === "rereview") {
         carry = result.carry
@@ -316,22 +327,36 @@ export const review = async (
 }
 
 /** The build tail: fix (when entered red), keep green, the quality lap, then human review since `base`. */
-export const buildTail = (fixFirst: boolean, base: string): Promise<ReviewOutcome> =>
+export const buildTail = (
+  fixFirst: boolean,
+  base: string,
+  built?: BuiltPlan,
+): Promise<ReviewOutcome> =>
   scope("build", async () => {
+    const frozen = built?.frozen
     const escalations: EscalationCount = { rounds: 0 }
+    const guardedFix = guarded(frozen, () => fix())
     let redFirst = fixFirst
+    // fixFirst's own fix + healthy below already is the full run.
+    if (!fixFirst) {
+      await healthy(
+        guarded(frozen, () => fix(built)),
+        { escalations, sweepOnGreen: [ARCHITECTURE] },
+      )
+    }
     // The lap runs once a tail: after its findings are fixed, review follows.
     let lapped = false
     for (;;) {
       if (redFirst) {
-        await fix()
-        await healthy(fix, { fixesSoFar: 1, escalations })
+        await guardedFix()
+        await healthy(guardedFix, { fixesSoFar: 1, escalations })
         redFirst = false
       }
       const lap = lapped ? "clean" : await qualityLap()
       lapped = true
-      if (lap === "clean") return review(base, escalations)
-      if (await fixQualityFindings(escalations)) await healthy(fix, { escalations })
-      else redFirst = true
+      if (lap === "clean") return review(base, escalations, frozen)
+      if (await fixQualityFindings(escalations, frozen)) {
+        await healthy(guardedFix, { escalations })
+      } else redFirst = true
     }
   })