@pmelab/gtd 27.5.0 → 27.7.0

package/src/replay/Replay.ts

@@ -10,6 +10,7 @@ import {
   type ScopeOptions,
   type StepRequest,
   type Flow,
+  type Mark,
 } from "../flows/index.js"
 import {
   headingSectionBodies,
@@ -114,12 +115,15 @@ export type ReplayOutcome =
       readonly trace: readonly ReachedStep[]
       /** The step the pending turn completed, when one was supplied. */
       readonly landed: ReachedStep | undefined
+      /** Marks the flow made after the pending turn's step resolved; [] without a pending turn. */
+      readonly marks: readonly Mark[]
     }
   | {
       readonly kind: "ended"
       readonly via: "return" | "restart"
       readonly trace: readonly ReachedStep[]
       readonly landed: ReachedStep | undefined
+      readonly marks: readonly Mark[]
     }
   | { readonly kind: "divergence"; readonly message: string }
   | { readonly kind: "refused"; readonly message: string }
@@ -292,6 +296,7 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
     { readonly hash: string; readonly before: TreeView; readonly after: TreeView }
   >()
   let landed: ReachedStep | undefined
+  const marks: Mark[] = []
   let outcome: ReplayOutcome | undefined
   let signal: (() => void) | undefined
   const settled = new Promise<void>((resolve) => {
@@ -553,7 +558,7 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
     const commit = commits[cursor]
     if (commit !== undefined) return consumeCommit(step, commit)
     if (input.pending === undefined || pendingUsed) {
-      return finish({ kind: "rest", rest: step, trace, landed })
+      return finish({ kind: "rest", rest: step, trace, landed, marks })
     }
     return landPending(step, input.pending)
   }
@@ -598,7 +603,7 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
           kind: "divergence",
           message: `gtd: the flow ended, but commit ${short(commits[cursor]!.hash)} continues the episode — ${DIVERGED}`,
         }
-      : { kind: "ended", via, trace, landed }
+      : { kind: "ended", via, trace, landed, marks }
 
   const changesSince = (hash: string): readonly Change[] => {
     const tree = treeAt(hash)
@@ -670,6 +675,9 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
               .map((f) => f.message),
           }))
         }),
+    mark: (name, value) => {
+      if (pendingUsed) marks.push({ name, value })
+    },
     kept: (name) => {
       const tip = keptTips.get(scoped(name))
       return tip === undefined

package/src/replay/Trailers.test.ts

@@ -282,3 +282,57 @@ describe("isRecordableApproval", () => {
     expect(isRecordableApproval(of("Ada", "a@x.io", 0))).toBe(false)
   })
 })
+
+describe("Gtd-Mark", () => {
+  const body = (...lines: string[]) => `gtd(human): a → b\n\n${lines.join("\n")}`
+
+  it("round-trips in order, names repeating", () => {
+    const message = formatCommitMessage({
+      actor: "human",
+      from: "a",
+      to: "b",
+      marks: [
+        { name: "risk-tier", value: "high" },
+        { name: "production-signal", value: "error rate = 0" },
+        { name: "production-signal", value: "p95" },
+      ],
+    })
+    expect(parseCommitMessage(message).marks).toEqual([
+      { name: "risk-tier", value: "high" },
+      { name: "production-signal", value: "error rate = 0" },
+      { name: "production-signal", value: "p95" },
+    ])
+  })
+
+  it("is written after Gtd-Judge and before Gtd-Approved, with no Gtd-Format bump", () => {
+    const lines = formatCommitMessage({
+      actor: "human",
+      to: "b",
+      judge: [{ id: "v", answer: "x", p: 1 }],
+      marks: [{ name: "risk-tier", value: "high" }],
+      approved: { step: { name: "s", occurrence: 1 }, name: "Ada", email: "a@x.io" },
+    }).split("\n")
+    const at = lines.findIndex((l) => l.startsWith("Gtd-Mark:"))
+    expect(lines[at - 1]).toMatch(/^Gtd-Judge:/)
+    expect(lines[at + 1]).toMatch(/^Gtd-Approved:/)
+    expect(lines).toContain("Gtd-Format: 1")
+  })
+
+  it("writes nothing without marks", () => {
+    expect(formatCommitMessage({ actor: "human", to: "b" })).not.toContain("Gtd-Mark")
+    expect(parseCommitMessage("gtd(human): a → b").marks).toEqual([])
+  })
+
+  it("skips a malformed line, a missing =, an empty value or a control character", () => {
+    const parsed = parseCommitMessage(
+      body(
+        "Gtd-Mark: no-equals",
+        "Gtd-Mark: Bad_Name=x",
+        "Gtd-Mark: empty=",
+        "Gtd-Mark: ctl=a\u001bb",
+        "Gtd-Mark: ok=fine",
+      ),
+    )
+    expect(parsed.marks).toEqual([{ name: "ok", value: "fine" }])
+  })
+})

package/src/replay/Trailers.ts

@@ -3,6 +3,7 @@
 // written by gtd) is skipped, not fatal — a corrupt line must never make every
 // command unusable.
 
+import type { Mark } from "../flows/index.js"
 import { HISTORY_FORMAT } from "./Format.js"
 
 const TRANSITION_SEP = " → "
@@ -73,6 +74,8 @@ export interface CommitMessage {
   /** Written only on a process's opening commit. */
   readonly workflow: string | undefined
   readonly judge: readonly JudgeVerdict[]
+  /** `Gtd-Mark`, in order; a malformed or control-character line is skipped. */
+  readonly marks: readonly Mark[]
   readonly vars: Readonly<Record<string, string>>
   /** Written only on a process's first commit. */
   readonly config: Readonly<Record<string, string>>
@@ -141,6 +144,7 @@ export const isRecordableApproval = (approval: Approval): boolean => {
   const back = decodeApproval(encodeApproval(approval))
   return back !== undefined && encodeApproval(back) === encodeApproval(approval)
 }
+const MARK_RE = /^([a-z][a-z0-9-]*)=(.+)$/
 const FORMAT_RE = /^[1-9][0-9]*$/
 const HASH_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/
 
@@ -153,6 +157,7 @@ interface Trailers {
   kept: string | undefined
   approved: Approval | undefined
   readonly judge: JudgeVerdict[]
+  readonly marks: Mark[]
   readonly vars: Record<string, string>
   readonly config: Record<string, string>
   readonly cost: CostEntry[]
@@ -170,6 +175,11 @@ const TRAILER_READERS: Readonly<Record<string, (value: string, into: Trailers) =
     const parsed = parseJson(value)
     if (isVerdict(parsed)) into.judge.push(parsed)
   },
+  "Gtd-Mark": (value, into) => {
+    const kv = MARK_RE.exec(value)
+    if (kv !== null && !CONTROL_CHARACTER.test(value))
+      into.marks.push({ name: kv[1]!, value: kv[2]! })
+  },
   "Gtd-Var": (value, into) => {
     const kv = VAR_RE.exec(value)
     if (kv !== null) into.vars[kv[1]!] = kv[2]!
@@ -215,6 +225,7 @@ export const parseCommitMessage = (message: string): CommitMessage => {
     kept: undefined,
     approved: undefined,
     judge: [],
+    marks: [],
     vars: {},
     config: {},
     cost: [],
@@ -239,7 +250,9 @@ export interface CommitSpec {
   readonly config?: Readonly<Record<string, string>>
   readonly cost?: { readonly cost: number; readonly model?: string }
   readonly judge?: readonly JudgeVerdict[]
-  /** Written after `Gtd-Judge`, before `Gtd-Branch`. */
+  /** Written after `Gtd-Judge`, before `Gtd-Approved`. */
+  readonly marks?: readonly Mark[]
+  /** Written after `Gtd-Mark`, before `Gtd-Branch`. */
   readonly approved?: Approval
   readonly branch?: string
   readonly version?: string
@@ -263,6 +276,7 @@ export const formatCommitMessage = (spec: CommitSpec): string => {
     )
   }
   for (const verdict of spec.judge ?? []) lines.push(`Gtd-Judge: ${JSON.stringify(verdict)}`)
+  for (const m of spec.marks ?? []) lines.push(`Gtd-Mark: ${m.name}=${m.value}`)
   if (spec.approved !== undefined) {
     lines.push(`Gtd-Approved: ${encodeApproval(spec.approved)}`)
   }

package/src/testkit/EmittedScriptRecognizer.test.ts

@@ -630,6 +630,18 @@ describe("applyEmittedScript — Emit.ts's combinedScript (the whole stdout of a
     expect(repo.lastCommitMessage()).toBe("gtd(human): idle")
   })
 
+  it("fails an unrecognized optional block under git: false", () => {
+    const repo = new InMemRepo()
+    const result = applyEmittedScript(
+      repo,
+      NO_COMMANDS,
+      combinedScript("set -eu", "totally-unrecognized-command"),
+      { git: false },
+    )
+    expect(result.ok).toBe(false)
+    expect(result.error).toContain("totally-unrecognized-command")
+  })
+
   it("still fails loudly on an unrecognized block outside the presentation-only subshell", () => {
     const repo = new InMemRepo()
     const script = `${combinedScript("totally-unrecognized-required-command", "")}`
@@ -691,3 +703,32 @@ describe("applyEmittedScript — commitClean", () => {
     expect(snapshot(repo)).toEqual(before)
   })
 })
+
+describe("applyEmittedScript — git: false reaches through the presentation subshell", () => {
+  it("refuses a git builder wrapped in combinedScript and changes nothing", () => {
+    const repo = new InMemRepo()
+    repo.writeFile("a.txt", "1")
+    const before = snapshot(repo)
+    const result = applyEmittedScript(
+      repo,
+      NO_COMMANDS,
+      combinedScript("set -eu", commitAll("chore: sneaky")),
+      { git: false },
+    )
+    expect(result.ok).toBe(false)
+    expect(result.error).toMatch(/unrecognized script block/)
+    expect(snapshot(repo)).toEqual(before)
+  })
+
+  it("still applies a non-git write-lines optional half", () => {
+    const repo = new InMemRepo()
+    const result = applyEmittedScript(
+      repo,
+      NO_COMMANDS,
+      combinedScript("set -eu", "mkdir -p d\nprintf '%s\\n' 'x' > 'd/a.txt'"),
+      { git: false },
+    )
+    expect(result).toMatchObject({ ok: true })
+    expect(repo.readFile("d/a.txt")).toBe("x\n")
+  })
+})

package/src/testkit/EmittedScriptRecognizer.ts

@@ -563,7 +563,7 @@ const recognizeGtdUncheck = (repo: InMemRepo, block: string): BlockOutcome | und
 const recognizeDidNotRunComment = (block: string): BlockOutcome | undefined =>
   block === DID_NOT_RUN_COMMENT ? { kind: "noop" } : undefined
 
-/** `combinedScript`'s optional half. ALWAYS reports `noop` whatever the inner result, mirroring bash's `( … ) || <warning>`, where the subshell's exit status is swallowed and must never fail the outer script. */
+/** `combinedScript`'s optional half. Reports `noop` whatever the inner result, mirroring bash's `( … ) || <warning>`. Exception: under `git: false` any unrecognized inner block fails the outer script (git or not), so the in-memory twin knowingly diverges from `sh` rather than run git unseen. */
 const PRESENTATION_FAILURE_TEXT = `${extractQuotedTokens(PRESENTATION_FAILURE_WARNING)[0]!.replace(/\\n$/, "")}\n`
 const PRESENTATION_SUBSHELL_PREFIX = `${PRESENTATION_ONLY_COMMENT}\n(\n`
 const PRESENTATION_SUBSHELL_SUFFIX = `\n) || ${PRESENTATION_FAILURE_WARNING}`
@@ -572,6 +572,7 @@ const recognizePresentationSubshell = (
   repo: InMemRepo,
   commands: ReadonlyMap<string, ScriptedCommand>,
   block: string,
+  git: boolean,
 ): BlockOutcome | undefined => {
   if (
     !block.startsWith(PRESENTATION_SUBSHELL_PREFIX) ||
@@ -583,8 +584,11 @@ const recognizePresentationSubshell = (
     PRESENTATION_SUBSHELL_PREFIX.length,
     block.length - PRESENTATION_SUBSHELL_SUFFIX.length,
   )
-  const result = applyEmittedScript(repo, commands, inner)
+  const result = applyEmittedScript(repo, commands, inner, { git })
   if (result.ok) return { kind: "noop", output: result.output }
+  if (!git && result.error?.startsWith(UNRECOGNIZED_PREFIX)) {
+    return { kind: "failed", error: `${result.output}${result.error}` }
+  }
   return { kind: "noop", output: `${result.output}${PRESENTATION_FAILURE_TEXT}` }
 }
 
@@ -703,17 +707,18 @@ const recognizeWriteLines = (repo: InMemRepo, block: string): BlockOutcome | und
 const recognizersFor = (
   repo: InMemRepo,
   commands: ReadonlyMap<string, ScriptedCommand>,
+  git: boolean,
 ): ReadonlyArray<(block: string) => BlockOutcome | undefined> => [
   (block) => recognizeSetFlags(block),
   (block) => recognizeDidNotRunComment(block),
   (block) => recognizePrecondition(repo, block),
   (block) => recognizeFileExistsGuard(repo, block),
   (block) => recognizeBinaryGuard(commands, block),
-  (block) => recognizeGitBuilders(repo, block),
+  (block) => (git ? recognizeGitBuilders(repo, block) : undefined),
   (block) => recognizeDeferNotes(repo, block),
   (block) => recognizeWriteLines(repo, block),
   (block) => recognizeFailurePromptWrapper(repo, commands, block),
-  (block) => recognizePresentationSubshell(repo, commands, block),
+  (block) => recognizePresentationSubshell(repo, commands, block, git),
   (block) => recognizeModeContradictionSkipNotice(block),
   (block) => recognizeModeContradictionCheck(repo, commands, block),
   (block) => recognizeGtdCheck(repo, block),
@@ -746,6 +751,7 @@ export const applyEmittedScript = (
   repo: InMemRepo,
   commands: ReadonlyMap<string, ScriptedCommand>,
   script: string,
+  { git = true }: { readonly git?: boolean } = {},
 ): AppliedScriptResult => {
   const flow = applyFlowScript(repo, commands, script)
   if (flow !== undefined) {
@@ -753,15 +759,16 @@ export const applyEmittedScript = (
       ? { ok: true, status: 0, output: flow.output }
       : { ok: false, status: 1, output: flow.output, error: flow.error ?? "" }
   }
-  return script.startsWith("#!") ? unrecognized(script) : applyBlocks(repo, commands, script)
+  return script.startsWith("#!") ? unrecognized(script) : applyBlocks(repo, commands, script, git)
 }
 
 const applyBlocks = (
   repo: InMemRepo,
   commands: ReadonlyMap<string, ScriptedCommand>,
   script: string,
+  git: boolean,
 ): AppliedScriptResult => {
-  const recognizers = recognizersFor(repo, commands)
+  const recognizers = recognizersFor(repo, commands, git)
   let output = ""
   for (const block of splitBlocks(script)) {
     const outcome = recognizeBlock(recognizers, block)
@@ -786,9 +793,11 @@ const failedAt = (
   }
 }
 
+const UNRECOGNIZED_PREFIX = "unrecognized script block: "
+
 const unrecognized = (block: string, output = ""): AppliedScriptResult => ({
   ok: false,
   status: 1,
   output,
-  error: `unrecognized script block: ${block.split("\n")[0]}`,
+  error: `${UNRECOGNIZED_PREFIX}${block.split("\n")[0]}`,
 })

package/src/testkit/TestRepo.test.ts

@@ -1,4 +1,17 @@
 import { describe, expect, it } from "vitest"
+import {
+  commitAll,
+  combinedScript,
+  commitAsIs,
+  commitClean,
+  deleteRef,
+  discardPending,
+  hardResetTo,
+  keepTurn,
+  mixedResetTo,
+  softResetTo,
+  updateRef,
+} from "../emit/index.js"
 import { agent, human, moveScript, read, removeScript, run } from "../flows/index.js"
 import { runsItsScript, testRepo } from "./TestRepo.js"
 
@@ -93,7 +106,72 @@ describe("testRepo", () => {
 
   it("refuses to fake a script it cannot run", () => {
     const repo = testRepo({ workflow: { default: tiny } })
-    expect(() => repo.runScript("npm test\n")).toThrow(/cannot run `npm test` in memory/)
+    expect(() => repo.runScript("npm test\n")).toThrow(/cannot run script in memory[\s\S]*npm test/)
+  })
+
+  it("carries the recognizer's error when a git-free fallback fails", () => {
+    const repo = testRepo({ workflow: { default: tiny } })
+    expect(() => repo.runScript("printf 'x' > 'y'\n")).toThrow(
+      "testkit: cannot run script in memory — give the step an actor instead\nunrecognized script block: printf 'x' > 'y'",
+    )
+  })
+
+  it("names the block that failed, not an earlier line that ran", () => {
+    const repo = testRepo({ workflow: { default: tiny } })
+    let message = ""
+    try {
+      repo.runScript("mkdir -p d\nprintf '%s\\n' 'x' > 'd/a.txt'\n\nnpm test\n")
+    } catch (e) {
+      message = (e as Error).message
+    }
+    expect(message).toContain("unrecognized script block: npm test")
+    expect(message).not.toContain("printf")
+  })
+
+  it.each([
+    ["commitAll", commitAll("chore: sneaky")],
+    ["commitClean", commitClean("chore: sneaky")],
+    ["commitAsIs", commitAsIs("chore: sneaky")],
+    ["keepTurn", keepTurn("refs/x", "chore: sneaky")],
+    ["discardPending", discardPending()],
+    ["softResetTo", softResetTo("HEAD~1")],
+    ["mixedResetTo", mixedResetTo("HEAD~1")],
+    ["hardResetTo", hardResetTo("HEAD~1")],
+    ["updateRef", updateRef("refs/x", "HEAD")],
+    ["deleteRef", deleteRef("refs/x")],
+  ])("refuses a %s script instead of mutating git in memory", (_, script) => {
+    const repo = testRepo({ workflow: { default: tiny } })
+    repo.write("a.txt", "dirty\n")
+    const before = repo.subjects()
+    expect(() => repo.runScript(script)).toThrow(/unrecognized script block/)
+    expect(repo.subjects()).toEqual(before)
+  })
+
+  it.each([
+    ["commitAll", commitAll("chore: sneaky")],
+    ["commitClean", commitClean("chore: sneaky")],
+    ["commitAsIs", commitAsIs("chore: sneaky")],
+    ["keepTurn", keepTurn("refs/x", "chore: sneaky")],
+    ["discardPending", discardPending()],
+    ["softResetTo", softResetTo("HEAD~1")],
+    ["mixedResetTo", mixedResetTo("HEAD~1")],
+    ["hardResetTo", hardResetTo("HEAD~1")],
+    ["updateRef", updateRef("refs/x", "HEAD")],
+    ["deleteRef", deleteRef("refs/x")],
+  ])("refuses a wrapped %s script instead of mutating git in memory", (_, script) => {
+    const repo = testRepo({ workflow: { default: tiny } })
+    repo.write("a.txt", "dirty\n")
+    const before = repo.subjects()
+    expect(() => repo.runScript(combinedScript("set -eu", script))).toThrow(
+      /cannot run script in memory[\s\S]*unrecognized script block/,
+    )
+    expect(repo.subjects()).toEqual(before)
+  })
+
+  it("applies a write block `LINES` lacks through the git-free recognizers", () => {
+    const repo = testRepo({ workflow: { default: tiny } })
+    repo.runScript("mkdir -p d\nprintf '%s\\n' 'echo $(git rev-parse HEAD)' > 'd/a.txt'\n")
+    expect(repo.read("d/a.txt")).toBe("echo $(git rev-parse HEAD)\n")
   })
 
   it("reads a file as committed", () => {

package/src/testkit/TestRepo.ts

@@ -150,12 +150,23 @@ const LINES: ReadonlyArray<readonly [RegExp, (repo: InMemRepo, words: string[])
   ],
 ]
 
-const runLine = (repo: InMemRepo, line: string): void => {
-  const known = LINES.find(([pattern]) => pattern.test(line))
-  if (known === undefined) {
-    throw new Error(`testkit: cannot run \`${line}\` in memory — give the step an actor instead`)
+const knownLine = (line: string) => LINES.find(([pattern]) => pattern.test(line))
+
+const cannotRun = (error: string): Error =>
+  new Error(`testkit: cannot run script in memory — give the step an actor instead\n${error}`)
+
+// A script with a line `LINES` lacks goes to the contract-tested recognizers
+// whole, minus the git builders: they would apply a commit/reset/update-ref in
+// memory, so any git-mutating block is refused whatever its spelling.
+const runLines = (repo: InMemRepo, script: string): void => {
+  const lines = script.split("\n").map((line) => line.trim())
+  const known = lines.map(knownLine)
+  if (known.every(Boolean)) {
+    known.forEach((k, i) => k![1](repo, words(lines[i]!)))
+    return
   }
-  known[1](repo, words(line))
+  const applied = applyEmittedScript(repo, new Map(), script, { git: false })
+  if (!applied.ok) throw cannotRun(applied.error ?? "")
 }
 
 const failed = (what: string, result: CapturedCliResult): Error =>
@@ -251,7 +262,7 @@ export const testRepo = (options: TestRepoOptions): TestRepo => {
     show: (ref, path) => repo.fileAtRef(ref, path) ?? undefined,
     runScript: (script) => {
       const flow = applyFlowScript(repo, new Map(), script)
-      if (flow === undefined) for (const line of script.split("\n")) runLine(repo, line.trim())
+      if (flow === undefined) runLines(repo, script)
       else if (!flow.ok) throw new Error(`testkit: ${flow.error ?? ""}`)
     },
     gtd,

package/src/testkit/steps.ts

@@ -70,7 +70,15 @@ export class TestkitWorld extends QuickPickleWorld {
         for (const action of actions) await action(beat, repo)
       }
     }
-    for (const [step, verdict] of this.verdicts) actors[step] = () => verdict
+    for (const [step, verdict] of this.verdicts) {
+      // A verdict would overwrite the queued actions, silently skipping their checks.
+      if (this.actions.has(step)) {
+        throw new Error(
+          `step "${step}" has a judge verdict and queued actions; the actions would never run`,
+        )
+      }
+      actors[step] = () => verdict
+    }
     await this.repo().drive(actors)
   }
 }
@@ -120,6 +128,19 @@ Given(
   },
 )
 
+// A standing assertion like any queued action: it applies on every later visit
+// to the step until `from now on` clears the list.
+Given(
+  "step {string} is prompted with {string}",
+  (world: TestkitWorld, step: string, text: string) => {
+    world.act(step, (beat) => {
+      if (!beat.content.includes(text)) {
+        throw new Error(`step "${step}" was not prompted with "${text}":\n${beat.content}`)
+      }
+    })
+  },
+)
+
 Given("step {string} runs its script", (world: TestkitWorld, step: string) => {
   world.act(step, runsItsScript)
 })
@@ -207,6 +228,28 @@ Then("the commit subjects end with:", (world: TestkitWorld, list: string) => {
   assert.deepStrictEqual(world.repo().subjects().slice(-expected.length), expected)
 })
 
+const outputOf = async (world: TestkitWorld, list: string): Promise<string> => {
+  const result = await world.repo().gtd(...args(list))
+  assert.strictEqual(result.exitCode, 0, result.stderr)
+  return result.stdout
+}
+
+Then(
+  "the output of gtd {string} contains {string}",
+  async (world: TestkitWorld, list: string, text: string) => {
+    const out = await outputOf(world, list)
+    assert.ok(out.includes(text), out)
+  },
+)
+
+Then(
+  "the output of gtd {string} does not contain {string}",
+  async (world: TestkitWorld, list: string, text: string) => {
+    const out = await outputOf(world, list)
+    assert.ok(!out.includes(text), out)
+  },
+)
+
 Then("{string} contains {string}", (world: TestkitWorld, path: string, text: string) => {
   assert.ok(world.repo().read(path)?.includes(text), `${path}: ${world.repo().read(path)}`)
 })

package/src/testkit/testkit.feature

@@ -1,3 +1,4 @@
+@inmem
 Feature: testkit drives any workflow against the real engine
 
   A workflow the scenario writes itself, never a shipped one: scripted actors
@@ -47,6 +48,8 @@ Feature: testkit drives any workflow against the real engine
       gtd(judge): ready → ship
       """
     And "PLAN.md" contains "add two numbers"
+    And the output of gtd "next" contains "ship"
+    And the output of gtd "next" does not contain "rework"
 
   Scenario: a red check sends the process to repair, and an unscripted step is where it rests
     Given step "plan" writes "PLAN.md" with:
@@ -63,6 +66,38 @@ Feature: testkit drives any workflow against the real engine
     And the resting step's content contains "Make the suite pass."
     And the last commit subject is "gtd(check): check → repair"
 
+  Scenario: a step's beat content is asserted as a queued actor
+    Given step "plan" is prompted with "Write PLAN.md."
+    And step "plan" writes "PLAN.md" with:
+      """
+      add two numbers
+      """
+    And step "check" changes nothing
+    And judge step "ready" answers:
+      """
+      [{ "id": "ready", "answer": true, "p": 0.9 }]
+      """
+    When gtd starts workflow "tiny"
+    And the process is driven
+    Then the process rests at "ship"
+    And "PLAN.md" contains "add two numbers"
+
+  Scenario: a judge step with queued actions refuses the drive
+    Given step "plan" changes nothing
+    And step "check" changes nothing
+    And step "ready" is prompted with "never seen"
+    And judge step "ready" answers:
+      """
+      [{ "id": "ready", "answer": true, "p": 0.9 }]
+      """
+    When gtd starts workflow "tiny"
+    Then driving the process is refused with "queued actions"
+
+  Scenario: a beat that lacks the expected text refuses the drive
+    Given step "plan" is prompted with "Write a poem"
+    When gtd starts workflow "tiny"
+    Then driving the process is refused with 'was not prompted with "Write a poem"'
+
   Scenario: a start the workflow refuses is reported with its message
     Then starting workflow "picky" with "--var mode=bad" is refused with "picky refuses every start"
 

package/src/workflows/cleanup/cleanup-path.feature

@@ -0,0 +1,94 @@
+# One SDLC path per file, so a changed path reds exactly one fixture — do not merge.
+@inmem
+Feature: cleanup walks one fixed path from the opening commit to idle
+
+  A default-on release flag is cleaned up by an agent that removes the registry
+  entry and the off path; health, review and closing follow and the process
+  rests at idle. Cleanup reads no release flag, so no flag is pinned here and
+  every flag state takes the same path.
+
+  Background:
+    Given the shipped workflows, as gtd install scaffolds them
+    And a gtd config with:
+      """
+      export {
+        feature as default,
+        feature,
+        defaults,
+        envDefaults,
+        summary,
+        steering,
+        skills,
+        access,
+      } from "@pmelab/gtd/workflows/feature"
+      import { cleanup } from "@pmelab/gtd/workflows"
+      export { cleanup }
+      """
+    And an environment variable "GTD_QUALITYREVIEWS" set to ""
+    And a file "src/flags/index.ts" with:
+      """
+      export const FLAGS = [
+        { name: "alpha", owner: "a", expiry: "2027-01-01", kind: "release" },
+        { name: "live", owner: "d", expiry: "2027-04-01", kind: "release", defaultOn: true },
+      ] as const
+      """
+    And a file "src/calc.ts" with:
+      """
+      export const on = process.env.GTD_FLAG_LIVE !== "0"
+      """
+    And the working tree is committed as "feat: registry"
+    And step "cleanup.removing" writes "src/flags/index.ts" with:
+      """
+      export const FLAGS = [
+        { name: "alpha", owner: "a", expiry: "2027-01-01", kind: "release" },
+      ] as const
+      """
+    And step "cleanup.removing" writes "src/calc.ts" with:
+      """
+      export const on = true
+      """
+    And step "build.health.check" changes nothing
+    And step "build.review.reviewing" writes ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## calc
+
+      - [ ] ./src/calc.ts#1-1
+        flag removed
+      """
+    And step "build.review.closing" runs its script
+
+  Scenario: removing the entry and the off path runs health, review and closing to idle
+    When gtd starts workflow "cleanup" with "--var flag=live"
+    And the process is driven
+    Then the process rests at "build.review.await-review"
+    Given a file ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## calc
+
+      - [x] ./src/calc.ts#1-1
+        flag removed
+      """
+    When gtd lands
+    And the process is driven
+    Then the process rests at "idle"
+    And "src/flags/index.ts" does not contain "live"
+    And "src/calc.ts" does not contain "GTD_FLAG_LIVE"
+    And the commit subjects end with:
+      """
+      gtd(human): cleanup.removing
+      gtd(agent): cleanup.removing → build.health.check
+      gtd(check): build.health.check → build.review.reviewing
+      gtd(agent): build.review.reviewing → build.review.await-review
+      gtd(human): build.review.await-review → build.review.closing
+      gtd(check): build.review.closing → idle
+      """
+    And the commit "gtd(human): cleanup.removing" has a body containing "Gtd-Workflow: cleanup"
+    And the commit "gtd(human): cleanup.removing" has a body containing "Gtd-Var: flag=live"