@pmelab/gtd 18.1.0 → 19.0.0

package/src/workflows/prose.ts

@@ -77,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
@@ -89,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
     }
   })

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

@@ -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"],