@pmelab/gtd 23.1.0 → 24.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "23.1.0",
+  "version": "24.0.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {
@@ -23,6 +23,7 @@
     "dist/",
     "src/flows/",
     "src/workflows/",
+    "src/workflow-kit/",
     "README.md",
     "LICENSE",
     ".claude-plugin/plugin.json",

package/skills/authoring/SKILL.md

@@ -145,10 +145,11 @@ the pending landing — call it right after the step whose turn you reject.
   process waits (the bundled one is `human("idle", …)`).
 - `gtd --workflow <name>` starts a process on the exported workflow `<name>` (an
   unknown name is a usage error); `gtd door <name> [args]` starts one through a
-  `doors` entry `{ workflow, args?, vars? }` (`gtd doors` lists them; bundled:
-  `fix`, `review [base]`; yours merge over them). An
-  `export const base = (workflow, vars) => commitish | undefined` fixes a
-  started process's diff base (blank = default-branch merge-base).
+  `doors` entry `{ workflow, args?, vars? }` (`gtd doors` lists them). A
+  factory's build may return `doors` without `workflow`; exporting the bundled
+  `fix` and `review` brings `fix` and `review [base]`, and yours merge over
+  them. An `export const base = (workflow, vars) => commitish | undefined` fixes
+  a started process's diff base (blank = default-branch merge-base).
   `--var <name>=<value>` only pins process settings: names the workflow's
   `defaults` declare — never an environment setting.
 

package/src/flows/factory.ts

@@ -1,5 +1,5 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec"
-import type { Flow } from "./runtime.js"
+import type { Flow, WorkflowBase, WorkflowDoors } from "./runtime.js"
 
 // Registered, so a factory made by any copy of this file is recognised by the
 // engine's copy — the same reason the replay context is.
@@ -11,6 +11,10 @@ export interface WorkflowBuild {
   readonly defaults?: Readonly<Record<string, string>> | undefined
   /** Environment settings this workflow declares, over its file's `envDefaults` export. */
   readonly envDefaults?: Readonly<Record<string, string>> | undefined
+  /** Doors onto this workflow. Two workflows building the same door is a load error unless the config's `doors` export declares that name; a declared door always wins. */
+  readonly doors?: WorkflowDoors | undefined
+  /** This workflow's diff base; the config's `base` export wins when it answers, `undefined` falls through to this. */
+  readonly base?: WorkflowBase | undefined
 }
 
 interface FactoryInternals {

package/src/flows/runtime.ts

@@ -434,3 +434,6 @@ export interface Door {
 
 /** A workflow module's reserved `doors` export. */
 export type Doors = Readonly<Record<string, Door>>
+
+/** Doors a workflow factory declares on itself: each starts whatever name the config exports the workflow under. */
+export type WorkflowDoors = Readonly<Record<string, Omit<Door, "workflow">>>

package/src/workflow-kit/health.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest"
+import { escalation, untilSettled } from "./health.js"
+
+describe("escalation", () => {
+  it("describes and stops until `limit` rounds are spent, then reports exhaustion", async () => {
+    const log: string[] = []
+    const steps = {
+      limit: 2,
+      describe: async () => void log.push("describe"),
+      stop: async () => void log.push("stop"),
+      exhausted: async () => void log.push("exhausted"),
+    }
+    const count = { rounds: 0 }
+    for (let i = 0; i < 3; i++) await escalation(count, steps)
+    expect(log).toEqual(["describe", "stop", "describe", "stop", "exhausted"])
+    expect(count.rounds).toBe(2)
+  })
+})
+
+describe("untilSettled", () => {
+  it("reruns while pending and resolves the first run that counts", async () => {
+    const results = [false, false, true]
+    let pending = 2
+    const green = await untilSettled(
+      async () => results.shift()!,
+      () => pending-- > 0,
+    )
+    expect(green).toBe(true)
+  })
+})

package/src/workflow-kit/health.ts

@@ -0,0 +1,86 @@
+import { read, scope } from "../flows/index.js"
+
+/** How many escalation rounds a run of red checks has spent — reset once the suite goes green. */
+export interface EscalationCount {
+  rounds: number
+}
+
+export interface EscalationSteps {
+  /** Rounds a person narrows before `exhausted` replaces them. */
+  readonly limit: number
+  readonly describe: () => Promise<void>
+  readonly stop: () => Promise<void>
+  readonly exhausted: () => Promise<void>
+}
+
+/** Hand a red suite that repeated attempts could not fix to a person, until `limit` rounds are spent. */
+export const escalation = async (count: EscalationCount, steps: EscalationSteps): Promise<void> => {
+  if (count.rounds >= steps.limit) return steps.exhausted()
+  count.rounds++
+  await steps.describe()
+  await steps.stop()
+}
+
+/** Run `check` again while `pending()` holds — a run then does not count — and resolve the first run that does. */
+export const untilSettled = async (
+  check: () => Promise<boolean>,
+  pending: () => boolean,
+): Promise<boolean> => {
+  for (;;) {
+    const green = await check()
+    if (!pending()) return green
+  }
+}
+
+export interface Health {
+  /** One counted run of the suite; resolves `true` when green. */
+  readonly check: () => Promise<boolean>
+  /** Where `check` leaves a red run's output. */
+  readonly report: string
+  readonly fixCap: number
+  readonly fixesSoFar?: number
+  /** Whether two consecutive red reports are the same failure; `true` escalates at once. */
+  readonly sameFailure: (previous: string, current: string) => Promise<boolean>
+  /** Shared with other callers in the same run of red checks. */
+  readonly escalations: EscalationCount
+  readonly escalation: EscalationSteps
+}
+
+// check() stamps the report with the commit it ran at, so equal failures differ there.
+const STAMP = /\n<!-- gtd check [0-9a-f]+ -->\n?$/
+const stripStamp = (text: string): string => text.replace(STAMP, "\n")
+
+/**
+ * Loop until the suite is green: check, and on red run `fix` — escalating
+ * first once `fixCap` fixes are spent, or `sameFailure` calls the failure
+ * identical to the previous round's.
+ */
+export const healthy = async (fix: () => Promise<void>, health: Health): Promise<void> => {
+  let fixes = health.fixesSoFar ?? 0
+  let previous: string | undefined
+  for (;;) {
+    if (await health.check()) {
+      health.escalations.rounds = 0
+      return
+    }
+    const current = stripStamp(read(health.report) ?? "")
+    const stuck = previous !== undefined && (await health.sameFailure(previous, current))
+    previous = current
+    if (stuck || fixes >= health.fixCap) {
+      await escalation(health.escalations, health.escalation)
+      fixes = 0
+    }
+    fixes++
+    await fix()
+  }
+}
+
+/** Hold the process in scope `name` until `passes` resolves `true`, resting at `blocked` between tries. */
+export const gate = (
+  name: string,
+  passes: () => Promise<boolean>,
+  blocked: () => Promise<void>,
+): Promise<void> =>
+  scope(name, async () => {
+    while (!(await passes())) await blocked()
+  })

package/src/workflow-kit/index.ts

@@ -0,0 +1,7 @@
+// Building blocks the shipped workflows share. Policy-free: every skill list,
+// lens, prompt, step, path and threshold arrives as a parameter, so a new
+// workflow composes these without inheriting the shipped one's choices.
+export * from "./health.js"
+export * from "./quality.js"
+export * from "./scenarios.js"
+export * from "./review.js"

package/src/workflow-kit/quality.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest"
+import { lensesOf, lensScopes } from "./quality.js"
+
+describe("lensesOf", () => {
+  it("splits on commas, trims, drops blanks", () => {
+    expect(lensesOf(" a ,, b,")).toEqual(["a", "b"])
+  })
+})
+
+describe("lensScopes", () => {
+  it("keys one entry per lens under the given scope", () => {
+    expect(lensScopes("x.quality", ["a", "b"], (lens) => [lens])).toEqual({
+      "x.quality.a": ["a"],
+      "x.quality.b": ["b"],
+    })
+  })
+})

package/src/workflow-kit/quality.ts

@@ -0,0 +1,45 @@
+import { read } from "../flows/index.js"
+
+/** Split a comma-separated lens list: trimmed, blanks dropped. */
+export const lensesOf = (value: string): readonly string[] =>
+  value
+    .split(",")
+    .map((lens) => lens.trim())
+    .filter((lens) => lens.length > 0)
+
+/** One `<scope>.<lens>` entry per lens — the per-lens part of a skills or access export. */
+export const lensScopes = <T>(
+  scope: string,
+  lenses: readonly string[],
+  entry: (lens: string) => T,
+): Record<string, T> => Object.fromEntries(lenses.map((lens) => [`${scope}.${lens}`, entry(lens)]))
+
+/** One `review` turn per lens, each appending its findings to `findings`; resolves `"findings"` when that file has any. */
+export const qualityLap = async (
+  lenses: readonly string[],
+  review: (lens: string) => Promise<void>,
+  findings: string,
+): Promise<"clean" | "findings"> => {
+  for (const lens of lenses) await review(lens)
+  return (read(findings) ?? "").length > 0 ? "findings" : "clean"
+}
+
+export interface FindingsFix {
+  /** One fix turn; it removes `findings` once every finding is resolved. */
+  readonly fix: () => Promise<void>
+  readonly findings: string
+  readonly cap: number
+  /** Runs once `cap` turns left findings. */
+  readonly escalate: () => Promise<void>
+}
+
+/** Resolves `true` once `findings` is gone, `false` when `cap` turns escalated instead. */
+export const fixFindings = async (f: FindingsFix): Promise<boolean> => {
+  for (let turns = 0; turns < f.cap; turns++) {
+    await f.fix()
+    // Not `changes()`: a wording gate after the fix would be the last step.
+    if (read(f.findings) === undefined) return true
+  }
+  await f.escalate()
+  return false
+}

package/src/workflow-kit/review.ts

@@ -0,0 +1,324 @@
+import {
+  changes,
+  changesSince,
+  hasThreadFor,
+  head,
+  read,
+  refuse,
+  requireReplies,
+  requireThreadsClosed,
+  type Change,
+} from "../flows/index.js"
+import { reviewNotes, reviewRisks, stripCodeThreads, type ReviewNote } from "../steering/index.js"
+
+/** How a review round ended. `feedback` carries what the human edited, for the re-unwind to undo. */
+export type ReviewOutcome =
+  | { readonly verdict: "signoff" }
+  | {
+      readonly verdict: "feedback"
+      /** The last round's commit, the re-plan base. */
+      readonly base: string
+      /** The commit the review file was written at; edits are restored from it. */
+      readonly restoreFrom: string
+      /** The code paths the rounds changed, with their content before. */
+      readonly edited: readonly Change[]
+    }
+
+export type Verdict = "edit" | "question" | "nit" | "praise"
+
+export type ReviewRisk = ReturnType<typeof reviewRisks>[number]
+
+/** Everything a review round decides or says, passed in: its files, steps, judge and texts. */
+export interface ReviewPolicy {
+  /** The review steering file the reviewer writes and the human annotates. */
+  readonly file: string
+  /** The file a collecting turn folds feedback into; its presence means feedback. */
+  readonly feedback: string
+  /** Whether a path is code, as opposed to steering state. */
+  readonly isCode: (path: string) => boolean
+  /** Write `file` over everything since `base`, carrying the answers of commit `carry` when given. */
+  readonly reviewing: (base: string, carry?: string) => Promise<void>
+  readonly fixRisks: (risks: readonly ReviewRisk[]) => Promise<void>
+  readonly keepGreen: () => Promise<void>
+  readonly awaitReview: (base: string) => Promise<void>
+  /** The round at commit `round` left no `file`. */
+  readonly reviewMissing: (round: string) => Promise<void>
+  /** Turn the round `capture` describes into `feedback`, or change nothing. */
+  readonly collecting: (capture: string) => Promise<void>
+  /** One verdict per note, keyed by note id; a note without one is an edit. */
+  readonly triage: (notes: readonly ReviewNote[]) => Promise<ReadonlyMap<string, Verdict>>
+  readonly answerQuestions: (notes: readonly ReviewNote[]) => Promise<void>
+  readonly fixNits: (notes: readonly ReviewNote[]) => Promise<void>
+  /** Remove `file` at the end of a round at commit `round`. */
+  readonly close: (round: string) => Promise<void>
+  /** What a collecting turn reads. */
+  readonly captures: {
+    readonly edits: (round: string) => string
+    readonly notes: (round: string) => string
+    readonly editNotes: (
+      round: string,
+      edits: readonly ReviewNote[],
+      answeredAt: string | undefined,
+    ) => string
+  }
+  readonly refusals: {
+    /** `file` was deleted at the gate. */
+    readonly deleted: string
+    /** The collecting turn changed something without writing `feedback`. */
+    readonly unmatched: string
+  }
+}
+
+const collect = async (p: ReviewPolicy, capture: string): Promise<"signoff" | "feedback"> => {
+  await p.collecting(capture)
+  if (read(p.feedback) !== undefined) return "feedback"
+  if (changes().length === 0) return "signoff"
+  return refuse(p.refusals.unmatched)
+}
+
+/** A review with ticks, footnote markers and thread definitions removed: what is left is line notes. */
+const notesOf = (text: string): string =>
+  text
+    .replace(/^\[\^[^\]]+\]:[^\n]*(\n(?: {2,}|\t)[^\n]*|\n(?=\s*\n(?: {2,}|\t)))*/gm, "")
+    .replace(/\[\^[^\]]+\]/g, "")
+    .replace(/\[x\]/gi, "[ ]")
+    .replace(/\s+/g, " ")
+    .trim()
+
+/**
+ * The human gate and its reply rounds: a question gets an answer inside
+ * the review file and rests at the gate again, without a lap. Resolves the
+ * commit of the last collecting turn, `"missing"` when the round left no
+ * review, or `undefined` when no such turn ran.
+ */
+const converse = async (
+  p: ReviewPolicy,
+  base: string,
+  collectedBefore?: string,
+): Promise<string | undefined> => {
+  let collectedAt = collectedBefore
+  for (;;) {
+    await p.awaitReview(base)
+    if (changes(p.file).some((c) => c.status === "deleted")) refuse(p.refusals.deleted)
+    if (read(p.file) === undefined) {
+      await p.reviewMissing(head())
+      return "missing"
+    }
+    requireThreadsClosed(p.file)
+    if (!hasThreadFor("agent", p.file)) return collectedAt
+    await p.collecting(p.captures.edits(head()))
+    collectedAt = head()
+    requireReplies(p.file)
+    if (!hasThreadFor("human", p.file)) return collectedAt
+  }
+}
+
+/** What `finish` hands back to `review`: an outcome, or another lap at the gate. */
+type Finish =
+  | ReviewOutcome
+  | { readonly next: "await"; readonly reviewed: string }
+  | { readonly next: "rereview"; readonly carry: string | undefined }
+
+/** What a round's routing needs from `finish`: its closing step and the ways it ends. */
+interface Round {
+  readonly round: string
+  readonly close: () => Promise<void>
+  readonly outcome: (verdict: "signoff" | "feedback") => ReviewOutcome
+  readonly unfolded: () => Promise<Finish>
+}
+
+/** Judge every note, then run each verdict's route: answers, then nit fixes, then the edits' lap. */
+const routeNotes = async (
+  p: ReviewPolicy,
+  notes: readonly ReviewNote[],
+  r: Round,
+): Promise<Finish> => {
+  const verdicts = await p.triage(notes)
+  const of = (v: Verdict): ReviewNote[] => notes.filter((n) => (verdicts.get(n.id) ?? "edit") === v)
+  const [edits, questions, nits] = [of("edit"), of("question"), of("nit")]
+  if (edits.length + questions.length + nits.length === 0) return r.unfolded()
+
+  let answeredAt: string | undefined
+  if (questions.length > 0) {
+    await p.answerQuestions(questions)
+    answeredAt = head()
+  }
+  if (nits.length > 0) {
+    await p.fixNits(nits)
+    await p.keepGreen()
+  }
+  if (edits.length > 0) {
+    await r.close()
+    return r.outcome(await collect(p, p.captures.editNotes(r.round, edits, answeredAt)))
+  }
+  if (nits.length > 0) {
+    await r.close()
+    return { next: "rereview", carry: answeredAt }
+  }
+  return { next: "await", reviewed: answeredAt! }
+}
+
+/** A code edit, not a thread-only change: lines that only add, answer or remove code threads don't count. */
+const isCodeEdit = (p: ReviewPolicy, c: Change): boolean =>
+  p.isCode(c.path) &&
+  stripCodeThreads(c.path, c.before ?? "") !== stripCodeThreads(c.path, c.after ?? "")
+
+/** Whether anything but thread edits and ticks landed in the review file since `commit`. */
+const notedSince = (p: ReviewPolicy, commit: string): boolean =>
+  changesSince(commit).some(
+    (c) => c.path === p.file && notesOf(c.before ?? "") !== notesOf(read(p.file) ?? ""),
+  )
+
+/**
+ * What the in-loop collecting turn left: `folded` when it wrote `feedback`
+ * (those folds need their lap whatever is judged later), `settled` when only
+ * thread edits and ticks landed after it.
+ */
+const afterCollect = (
+  p: ReviewPolicy,
+  collectedAt: string | undefined,
+): { folded: boolean; settled: boolean } =>
+  // While the collecting turn is still pending its commit has no hash, so no
+  // range can start there; the flow rests at the close before it matters.
+  collectedAt === "" ? { folded: false, settled: false } : settledAfter(p, collectedAt)
+
+const settledAfter = (
+  p: ReviewPolicy,
+  collectedAt: string | undefined,
+): { folded: boolean; settled: boolean } => ({
+  folded: collectedAt !== undefined && read(p.feedback) !== undefined,
+  settled:
+    collectedAt !== undefined &&
+    changesSince(collectedAt).every((c) => !isCodeEdit(p, c)) &&
+    !notedSince(p, collectedAt),
+})
+
+const finish = async (
+  p: ReviewPolicy,
+  reviewed: string,
+  collectedAt: string | 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.
+  const round = head()
+  const since = changesSince(reviewed)
+  const edited = since.filter((c) => isCodeEdit(p, c))
+  const baselineText = since.get(p.file)?.before ?? ""
+  const record = read(p.file) ?? ""
+  const { folded, settled } = afterCollect(p, collectedAt)
+  // The review gate clears every tick before its commit, so a changed
+  // review file is a note, never a tick.
+  const noted = since.some((c) => c.path === p.file)
+  const close = (): Promise<void> => p.close(round)
+  const outcome = (verdict: "signoff" | "feedback"): ReviewOutcome =>
+    verdict === "signoff" ? { verdict } : { verdict, base: round, restoreFrom: reviewed, edited }
+  const unfolded = async (): Promise<Finish> => {
+    await close()
+    return outcome(folded ? "feedback" : "signoff")
+  }
+
+  const collectWith = async (capture: string): Promise<Finish> => {
+    await close()
+    return outcome(await collect(p, capture))
+  }
+  if (settled || (edited.length === 0 && !noted)) return unfolded()
+  if (edited.length > 0) return collectWith(p.captures.edits(round))
+  const notes = reviewNotes(baselineText, record)
+  if (notes.length === 0) return collectWith(p.captures.notes(round))
+  return routeNotes(p, notes, { round, 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. */
+const reviewOnce = async (
+  p: Pick<ReviewPolicy, "file" | "reviewing" | "fixRisks" | "keepGreen">,
+  base: string,
+  carry: string | undefined,
+) => {
+  await p.reviewing(base, carry)
+  const risks = reviewRisks(read(p.file) ?? "")
+  if (risks.length === 0) return
+  await p.fixRisks(risks)
+  await p.keepGreen()
+  await p.reviewing(base, carry)
+}
+
+/**
+ * A reviewer writes the review over everything since `base`, a human
+ * reviews and signs off or comments, and each note is judged: edits go to
+ * another lap, questions are answered in place, nits fixed in one batch,
+ * praise dropped.
+ */
+export const review = async (base: string, p: ReviewPolicy): Promise<ReviewOutcome> => {
+  let carry: string | undefined
+  for (;;) {
+    await reviewOnce(p, base, carry)
+    carry = undefined
+    let reviewed = head()
+    let collectedAt: string | undefined
+    for (;;) {
+      collectedAt = await converse(p, base, collectedAt)
+      if (collectedAt === "missing") break
+      const result = await finish(p, reviewed, collectedAt)
+      if (!("next" in result)) return result
+      if (result.next === "rereview") {
+        carry = result.carry
+        break
+      }
+      reviewed = result.reviewed
+    }
+  }
+}
+
+/** What a review round that hands its notes on decides or says, passed in. */
+export interface HandOffPolicy extends Pick<
+  ReviewPolicy,
+  "file" | "reviewing" | "fixRisks" | "keepGreen" | "awaitReview" | "reviewMissing" | "close"
+> {
+  /** Keep `file` with the human's notes for another workflow; `reviewed` holds the reviewer's own version. */
+  readonly handOff: (reviewed: string) => Promise<void>
+  /** `file` was deleted at the gate. */
+  readonly deleted: string
+  /** A thread waits on the agent at the gate, and no turn here answers it. */
+  readonly threadsPending: string
+  /** The review was edited but the edit parses to no note, so `fix` would have nothing to act on. */
+  readonly unparsed: string
+}
+
+/**
+ * A reviewer writes the review over everything since `base` and a human
+ * reviews it. No note signs off and closes; any note ends the round with the
+ * review left in place, for another workflow to read its notes — nothing is
+ * judged or re-planned here.
+ */
+export const reviewToHandOff = async (base: string, p: HandOffPolicy): Promise<void> => {
+  for (;;) {
+    await reviewOnce(p, base, undefined)
+    const reviewed = head()
+    await p.awaitReview(base)
+    if (changes(p.file).some((c) => c.status === "deleted")) refuse(p.deleted)
+    const record = read(p.file)
+    if (record === undefined) {
+      await p.reviewMissing(head())
+      continue
+    }
+    // `fix` runs in a new process, where a code thread is no longer "changed"
+    // and nothing answers it — so none may be left waiting on the agent.
+    requireThreadsClosed(p.file)
+    if (hasThreadFor("agent", p.file)) refuse(p.threadsPending)
+    const since = changesSince(reviewed)
+    const before = since.get(p.file)?.before ?? record
+    if (notesOf(before) === notesOf(record)) {
+      // A hand edit in a sign-off round was never checked or reviewed.
+      if (since.paths.some((f) => !f.startsWith(".gtd/"))) {
+        await p.keepGreen()
+      }
+      await p.close(head())
+      return
+    }
+    // `fix` acts only on parsed notes: an edit with none (a deleted chunk,
+    // stray prose) would be closed away unread, so it is refused here.
+    if (reviewNotes(before, record).length === 0) refuse(p.unparsed)
+    await p.handOff(reviewed)
+    return
+  }
+}

package/src/{workflows → workflow-kit}/scenarios.ts

@@ -1,5 +1,4 @@
-import { head, human, read, scope } from "../flows/index.js"
-import * as t from "./text.js"
+import { head, read } from "../flows/index.js"
 
 /** Mutable: an accepted change moves the snapshot forward. */
 export interface FrozenScenarios {
@@ -93,26 +92,33 @@ const lineDiff = (a: readonly string[], b: readonly string[]): string[] => {
   return [...out, ...a.slice(i).map((l) => `- ${l}`), ...b.slice(j).map((l) => `+ ${l}`)]
 }
 
-export const wordingDrift = (frozen: FrozenScenarios, path: string): t.WordingDrift => ({
+export interface WordingDrift {
+  readonly path: string
+  /** `- `/`+ `-prefixed, in file order. */
+  readonly lines: readonly string[]
+}
+
+export const wordingDrift = (frozen: FrozenScenarios, path: string): 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> => {
+/**
+ * After a turn: rest at `stop` while wording drifted from `frozen`. Whatever
+ * still differs after it is accepted and moves the snapshot; what was
+ * restored stays frozen as it was.
+ */
+export const holdWording = async (
+  frozen: FrozenScenarios | undefined,
+  stop: (at: string, drifted: readonly WordingDrift[]) => Promise<void>,
+): 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.
+  await stop(
+    frozen.at,
+    drifted.map((path) => wordingDrift(frozen, path)),
+  )
   const accepted = driftedScenarios(frozen)
   if (accepted.length === 0) return
   for (const path of accepted) {
@@ -122,16 +128,3 @@ export const holdWording = async (frozen: FrozenScenarios | undefined): Promise<
   }
   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))
-  }