@pmelab/gtd 24.0.0 → 24.1.0

package/src/emit/OutcomeScript.test.ts

@@ -0,0 +1,238 @@
+import { execFileSync, execSync } from "node:child_process"
+import { mkdtempSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join, resolve } from "node:path"
+import { describe, expect, it } from "vitest"
+import fc from "fast-check"
+import {
+  abandonedOutcome,
+  abandonNoopOutcome,
+  abandonNoopText,
+  commitOutcome,
+  noteOutcome,
+  OUTCOME_MARKER,
+  renderFormat,
+  restoredOutcome,
+  transitionOutcome,
+} from "./OutcomeScript.js"
+
+const runShCheckSyntax = (script: string): number => {
+  try {
+    execFileSync("sh", ["-n"], { input: script })
+    return 0
+  } catch (error) {
+    return (error as { status?: number }).status ?? 1
+  }
+}
+
+describe("transitionOutcome", () => {
+  it("emits one printf naming both states", () => {
+    expect(transitionOutcome("plan.planning", "plan.await-plan")).toBe(
+      `${OUTCOME_MARKER}\nprintf '%s %s → %s\\n' '->' 'plan.planning' 'plan.await-plan'`,
+    )
+  })
+
+  it("is syntactically valid sh on its own — no preamble to define first", () => {
+    expect(runShCheckSyntax(transitionOutcome("a", "b"))).toBe(0)
+  })
+})
+
+describe("commitOutcome", () => {
+  it("emits one printf naming the subject", () => {
+    expect(commitOutcome("gtd(agent): x")).toBe(
+      `${OUTCOME_MARKER}\nprintf '%s %s\\n' '[commit]' 'gtd(agent): x'`,
+    )
+  })
+
+  it("is syntactically valid sh on its own", () => {
+    expect(runShCheckSyntax(commitOutcome("gtd(agent): x"))).toBe(0)
+  })
+})
+
+describe("noteOutcome", () => {
+  it("emits a single printf of the text", () => {
+    expect(noteOutcome('nothing to do at "idle"')).toBe(
+      `${OUTCOME_MARKER}\nprintf '%s\\n' 'nothing to do at "idle"'`,
+    )
+  })
+})
+
+describe("abandonedOutcome / restoredOutcome", () => {
+  it("resolves the short hash and subject in-script, since the reset has not happened yet when gtd emits this", () => {
+    expect(abandonedOutcome("build.fix", "abc123", "idle")).toContain(
+      "\"$(git rev-parse --short 'abc123')\"",
+    )
+    expect(abandonedOutcome("build.fix", "abc123", "idle")).toContain(
+      "\"$(git log -1 --format=%s 'abc123')\"",
+    )
+  })
+
+  it("both are syntactically valid sh on their own", () => {
+    expect(runShCheckSyntax(abandonedOutcome("build.fix", "abc123", "idle"))).toBe(0)
+    expect(runShCheckSyntax(restoredOutcome("abc123", "idle"))).toBe(0)
+  })
+})
+
+describe("abandonNoopOutcome", () => {
+  it("carries the same wording as abandonNoopText", () => {
+    expect(abandonNoopOutcome("idle")).toBe(noteOutcome(abandonNoopText("idle")))
+  })
+})
+
+describe("plain-text twins", () => {
+  it("abandonNoopText names the initial state", () => {
+    expect(abandonNoopText("idle")).toBe(
+      'no gtd process is underway (resting at "idle") — nothing to abandon\n',
+    )
+  })
+})
+
+describe("renderFormat", () => {
+  it("substitutes %s placeholders in order", () => {
+    expect(renderFormat("%s and %s", "a", "b")).toBe("a and b")
+  })
+
+  it("leaves a literal % that isn't followed by s untouched", () => {
+    expect(renderFormat("100%% done, %s", "ok")).toBe("100%% done, ok")
+  })
+})
+
+/**
+ * The emitted statements carry no ANSI at all now, so there is no tty /
+ * `NO_COLOR` / `TERM=dumb` branch left to gate: output is byte-identical on a
+ * pipe and on a real terminal. `run-in-pty.py` is what proves that rather than
+ * assumes it — it allocates a throwaway pty pair, the one context where a
+ * colour branch (if one came back) would actually fire.
+ */
+describe("no ANSI, on a pipe or a real tty", () => {
+  const PTY_RUNNER = resolve(import.meta.dirname, "../../tests/tooling/support/run-in-pty.py")
+  const ESC = "\x1b"
+
+  const initRepo = (dir: string): void => {
+    execFileSync("git", ["init", "-q"], { cwd: dir })
+    execFileSync("git", ["config", "user.email", "test@example.com"], { cwd: dir })
+    execFileSync("git", ["config", "user.name", "Test"], { cwd: dir })
+    execFileSync("git", ["config", "commit.gpgsign", "false"], { cwd: dir })
+    execFileSync("git", ["commit", "-q", "--allow-empty", "-m", "gtd(human): idle"], { cwd: dir })
+  }
+
+  it("emits no escape byte under a real tty with a colour-capable TERM", () => {
+    const dir = mkdtempSync(join(tmpdir(), "outcome-pty-"))
+    initRepo(dir)
+    const script = commitOutcome("gtd(human): idle")
+    const runOnce = (): string =>
+      execFileSync("python3", [PTY_RUNNER, `cd ${JSON.stringify(dir)} && ${script}`], {
+        encoding: "utf8",
+        env: { PATH: process.env.PATH ?? "", TERM: "xterm" },
+      })
+    // A real pty allocation under severe host-wide CPU contention (many
+    // concurrent `npm test` runs across sibling worktrees) can rarely come
+    // back with zero captured bytes despite the child exiting cleanly — an
+    // OS/scheduler-level hiccup in the fork-exec-pty path itself, not a bug
+    // in `run-in-pty.py`'s own read loop (which blocks to real EOF, see its
+    // own comment) or in this repo's code. Retrying absorbs that one-off
+    // without weakening the assertion: a genuine regression still reproduces
+    // every attempt.
+    let out = runOnce()
+    for (let attempt = 0; attempt < 2 && out.length === 0; attempt++) out = runOnce()
+    expect(out).not.toContain(ESC)
+    expect(out).toContain("[commit] gtd(human): idle")
+  })
+
+  it("contains no ANSI source text either — nothing for a driver's stdout to leak", () => {
+    for (const statement of [
+      transitionOutcome("a", "b"),
+      commitOutcome("gtd(human): x"),
+      noteOutcome("ok"),
+      abandonedOutcome("build.fix", "abc123", "idle"),
+      restoredOutcome("abc123", "idle"),
+    ]) {
+      expect(statement).not.toContain("\\033[")
+      expect(statement).not.toContain("$'")
+    }
+  })
+
+  it("contains no bash-only local declarations or process substitution", () => {
+    const statement = commitOutcome("gtd(human): x")
+    expect(statement).not.toContain(" local ")
+    expect(statement).not.toContain("<(")
+  })
+})
+
+describe("%-safety and quoting", () => {
+  it("a subject containing %s survives commitOutcome round-tripped through printf", () => {
+    const tricky = "gtd(agent): 50%s off deal's price"
+    const dir = mkdtempSync(join(tmpdir(), "outcome-safety-"))
+    execFileSync("git", ["init", "-q"], { cwd: dir })
+    const out = execSync("sh", { input: commitOutcome(tricky), cwd: dir, encoding: "utf8" })
+    expect(out).toContain(tricky)
+  })
+
+  // 120s, not the default 30s: each of the 200 `fc.assert` runs below spawns
+  // a REAL `sh` subprocess via `execSync` — shell startup overhead alone
+  // pushes 200 sequential spawns past 30s on a loaded machine, with nothing
+  // about the test itself hanging (it reliably completes, just slowly).
+  it("round-trips arbitrary subjects (including % and quotes) through noteOutcome", () => {
+    fc.assert(
+      fc.property(
+        fc.string({ unit: "binary" }).filter((s) => !s.includes("\0") && !s.includes("\n")),
+        (subject) => {
+          const out = execSync("sh", { input: noteOutcome(subject), encoding: "utf8" })
+          expect(out).toBe(`${subject}\n`)
+        },
+      ),
+      { numRuns: 200 },
+    )
+  }, 120_000)
+})
+
+describe("abandonedOutcome / restoredOutcome — real repo", () => {
+  const initRepo = (): string => {
+    const dir = mkdtempSync(join(tmpdir(), "outcome-abandon-"))
+    execFileSync("git", ["init", "-q"], { cwd: dir })
+    execFileSync("git", ["config", "user.email", "test@example.com"], { cwd: dir })
+    execFileSync("git", ["config", "user.name", "Test"], { cwd: dir })
+    execFileSync("git", ["config", "commit.gpgsign", "false"], { cwd: dir })
+    execFileSync("git", ["commit", "-q", "--allow-empty", "-m", "gtd(human): idle"], { cwd: dir })
+    return dir
+  }
+
+  it("resolves the short hash/subject post-hoc from the given commitish", () => {
+    const dir = initRepo()
+    const head = execFileSync("git", ["rev-parse", "HEAD"], { cwd: dir, encoding: "utf8" }).trim()
+    const short = execFileSync("git", ["rev-parse", "--short", "HEAD"], {
+      cwd: dir,
+      encoding: "utf8",
+    }).trim()
+    const out = execSync("sh", {
+      input: abandonedOutcome("build.fix", head, "idle"),
+      cwd: dir,
+      encoding: "utf8",
+    })
+    expect(out).toBe(
+      `abandoned the process resting at "build.fix" — HEAD is back at ${short} ` +
+        '("gtd(human): idle"), resting at "idle".\n' +
+        "Everything the process produced is kept as uncommitted changes (`git status`); " +
+        "discard them with `git checkout -- . && git clean -fd .gtd` for a clean tree.\n",
+    )
+  })
+
+  it("restoredOutcome resolves the short hash/subject post-hoc from the given commitish", () => {
+    const dir = initRepo()
+    const head = execFileSync("git", ["rev-parse", "HEAD"], { cwd: dir, encoding: "utf8" }).trim()
+    const short = execFileSync("git", ["rev-parse", "--short", "HEAD"], {
+      cwd: dir,
+      encoding: "utf8",
+    }).trim()
+    const out = execSync("sh", {
+      input: restoredOutcome(head, "await-review"),
+      cwd: dir,
+      encoding: "utf8",
+    })
+    expect(out).toBe(
+      `restored the retained history — HEAD is back at ${short} ("gtd(human): idle"), ` +
+        'resting at "await-review". Resume with the loop, or `git reset` to any earlier ' +
+        "turn to restart from there.\n",
+    )
+  })
+})

package/src/emit/OutcomeScript.ts

@@ -0,0 +1,73 @@
+import { shellQuote } from "./GitScript.js"
+import { renderFormat } from "../wire/index.js"
+
+export { renderFormat }
+
+/**
+ * A `printf '<fmt>' <args...>` bash statement — `args` are already-valid bash
+ * tokens (a `shellQuote`d literal, a `"$(git …)"` substitution), never
+ * re-quoted here: a value reaches the script as a printf ARGUMENT, never
+ * interpolated into the format itself, so a subject or state name containing
+ * `%` can never be read as a conversion spec. Markers like `->` are arguments
+ * too, keeping every format string free of a leading `-` that a shell's
+ * `printf` could mistake for an option. A real newline in `fmt` is emitted as
+ * the two-character `\n` escape `printf` itself expands, keeping every emitted
+ * statement on one line.
+ */
+const printfLine = (fmt: string, args: readonly string[]): string =>
+  `${OUTCOME_MARKER}\nprintf ${shellQuote(fmt.replace(/\n/g, "\\n"))} ${args.join(" ")}`
+
+/**
+ * Marks an emitted block as print-only. Load-bearing beyond documentation:
+ * `src/testkit/EmittedScriptRecognizer.ts` recognizes an outcome block by
+ * this line, and a bare `printf` would be ambiguous with a workflow
+ * `script:` command that happens to start the same way.
+ */
+export const OUTCOME_MARKER = "# gtd: outcome (print-only)"
+
+const FMT_ABANDON_NOOP = 'no gtd process is underway (resting at "%s") — nothing to abandon\n'
+const FMT_ABANDONED =
+  'abandoned the process resting at "%s" — HEAD is back at %s ("%s"), resting at "%s".\n' +
+  "Everything the process produced is kept as uncommitted changes (`git status`); " +
+  "discard them with `git checkout -- . && git clean -fd .gtd` for a clean tree.\n"
+const FMT_RESTORED =
+  'restored the retained history — HEAD is back at %s ("%s"), resting at "%s". Resume ' +
+  "with the loop, or `git reset` to any earlier turn to restart from there.\n"
+
+/** `no gtd process is underway (resting at "<initial>") — nothing to abandon` — `gtd abandon`'s no-op plain-text line. */
+export const abandonNoopText = (initial: string): string => renderFormat(FMT_ABANDON_NOOP, initial)
+
+/** A landed self-loop/target-change transition. */
+export const transitionOutcome = (from: string, to: string): string =>
+  printfLine("%s %s → %s\n", ["'->'", shellQuote(from), shellQuote(to)])
+
+/** A bare capture (a self-loop commit). */
+export const commitOutcome = (subject: string): string =>
+  printfLine("%s %s\n", ["'[commit]'", shellQuote(subject)])
+
+/** One already-rendered plain line. */
+export const noteOutcome = (text: string): string => printfLine("%s\n", [shellQuote(text)])
+
+/**
+ * Resolves the post-hoc short hash/subject from `head` (a commitish) in-script
+ * — this line runs AFTER the reset that made `head` the new HEAD, so neither
+ * value is knowable when gtd generates it.
+ */
+export const abandonedOutcome = (from: string, head: string, state: string): string =>
+  printfLine(FMT_ABANDONED, [
+    shellQuote(from),
+    `"$(git rev-parse --short ${shellQuote(head)})"`,
+    `"$(git log -1 --format=%s ${shellQuote(head)})"`,
+    shellQuote(state),
+  ])
+
+/** `gtd abandon`'s no-op outcome — the same wording `abandonNoopText` renders. */
+export const abandonNoopOutcome = (initial: string): string => noteOutcome(abandonNoopText(initial))
+
+/** Resolves the post-hoc short hash/subject from `to` (a commitish) in-script, for the same reason `abandonedOutcome` does. */
+export const restoredOutcome = (to: string, state: string): string =>
+  printfLine(FMT_RESTORED, [
+    `"$(git rev-parse --short ${shellQuote(to)})"`,
+    `"$(git log -1 --format=%s ${shellQuote(to)})"`,
+    shellQuote(state),
+  ])

package/src/emit/SteeringMode.test.ts

@@ -0,0 +1,274 @@
+import { describe, expect, it } from "vitest"
+import { Effect } from "effect"
+import { resolveMode, validateScriptFor, type ModeResolution } from "./SteeringMode.js"
+import { Host } from "../platform/index.js"
+import { steeringFormatFor } from "../steering/index.js"
+import { seededValidateCommand, type WorkflowDefinition } from "../workflow/index.js"
+
+const QA_FORMAT = steeringFormatFor("qa")!
+const REVIEW_FORMAT = steeringFormatFor("review")!
+
+type ModesDef = Pick<WorkflowDefinition, "modes">
+
+const commandsDef = (modes: WorkflowDefinition["modes"]): ModesDef => ({ modes })
+
+const envVarsLayer = Host.layer({ root: "/repo", home: "/repo", env: { PATH: "/usr/bin:/bin" } })
+
+const runScript = (resolved: ModeResolution, file: string) => {
+  if (resolved.kind !== "resolved") throw new Error("expected a resolved mode")
+  return Effect.runPromise(validateScriptFor(resolved, file).pipe(Effect.provide(envVarsLayer)))
+}
+
+describe("resolveMode", () => {
+  it("resolves the two built-in names to their in-process validator, their format, and to no formatter", () => {
+    const def: ModesDef = { modes: {} }
+    expect(resolveMode(def, "drafting", "qa")).toEqual({
+      kind: "resolved",
+      mode: "qa",
+      format: QA_FORMAT,
+      validate: { kind: "builtin", format: QA_FORMAT },
+      capabilities: { format: QA_FORMAT, liveValidate: QA_FORMAT.validate },
+    })
+    expect(resolveMode(def, "drafting", "review")).toEqual({
+      kind: "resolved",
+      mode: "review",
+      format: REVIEW_FORMAT,
+      validate: { kind: "builtin", format: REVIEW_FORMAT },
+      capabilities: { format: REVIEW_FORMAT, liveValidate: REVIEW_FORMAT.validate },
+    })
+  })
+
+  it("resolves a declared mode to its commands", () => {
+    const def = commandsDef({ adr: { validate: "adr-lint $GTD_FILE" } })
+    expect(resolveMode(def, "drafting", "adr")).toEqual({
+      kind: "resolved",
+      mode: "adr",
+      validate: { kind: "command", command: "adr-lint $GTD_FILE" },
+      capabilities: { externalValidate: true },
+    })
+  })
+
+  it("adds a formatter to a built-in WITHOUT displacing its validation", () => {
+    const def = commandsDef({ qa: { format: "npx prettier --write $GTD_FILE" } })
+    expect(resolveMode(def, "drafting", "qa")).toEqual({
+      kind: "resolved",
+      mode: "qa",
+      format: QA_FORMAT,
+      formatCommand: "npx prettier --write $GTD_FILE",
+      validate: { kind: "builtin", format: QA_FORMAT },
+      capabilities: { format: QA_FORMAT, liveValidate: QA_FORMAT.validate },
+    })
+  })
+
+  it("lets a declared `validate:` override a built-in's parser, WITHOUT losing the format identity", () => {
+    const def = commandsDef({ qa: { validate: "my-qa-linter $GTD_FILE" } })
+    expect(resolveMode(def, "drafting", "qa")).toEqual({
+      kind: "resolved",
+      mode: "qa",
+      format: QA_FORMAT,
+      validate: { kind: "command", command: "my-qa-linter $GTD_FILE" },
+      capabilities: { format: QA_FORMAT, externalValidate: true },
+    })
+  })
+
+  it("resolves a non-built-in mode with only a `format:` to no validator at all", () => {
+    const def = commandsDef({ adr: { format: "fmt $GTD_FILE" } })
+    expect(resolveMode(def, "drafting", "adr")).toEqual({
+      kind: "resolved",
+      mode: "adr",
+      formatCommand: "fmt $GTD_FILE",
+      capabilities: {},
+    })
+  })
+
+  it("resolves nothing for an undefined mode, and names what IS known", () => {
+    const def = commandsDef({ adr: { validate: "adr-lint" } })
+    expect(resolveMode(def, "drafting", "nope")).toEqual({
+      kind: "unknown",
+      message:
+        'state "drafting": mode "nope" is not defined by the active workflow (known modes: adr)',
+    })
+  })
+
+  it("resolves nothing for `prose` with no declared entry — it is not in the built-in registry", () => {
+    const def: ModesDef = { modes: {} }
+    expect(resolveMode(def, "drafting", "prose").kind).toBe("unknown")
+  })
+
+  it("resolves a declared `prose` entry with only a `format:` to a formatter-only, validator-less mode", () => {
+    const def = commandsDef({ prose: { format: "npx prettier --write $GTD_FILE" } })
+    expect(resolveMode(def, "drafting", "prose")).toEqual({
+      kind: "resolved",
+      mode: "prose",
+      formatCommand: "npx prettier --write $GTD_FILE",
+      capabilities: {},
+    })
+  })
+
+  it("resolves the two built-in names against the registry alone, with no definition (`def: undefined`) — the LSP's basename fallback", () => {
+    expect(resolveMode(undefined, "", "qa")).toEqual({
+      kind: "resolved",
+      mode: "qa",
+      format: QA_FORMAT,
+      validate: { kind: "builtin", format: QA_FORMAT },
+      capabilities: { format: QA_FORMAT, liveValidate: QA_FORMAT.validate },
+    })
+    expect(resolveMode(undefined, "", "review")).toEqual({
+      kind: "resolved",
+      mode: "review",
+      format: REVIEW_FORMAT,
+      validate: { kind: "builtin", format: REVIEW_FORMAT },
+      capabilities: { format: REVIEW_FORMAT, liveValidate: REVIEW_FORMAT.validate },
+    })
+  })
+
+  it("resolves nothing for a name the registry doesn't know, with no definition", () => {
+    expect(resolveMode(undefined, "", "prose").kind).toBe("unknown")
+    expect(resolveMode(undefined, "", "adr").kind).toBe("unknown")
+  })
+
+  it("keeps liveValidate (using format.validate) and drops externalValidate when a built-in mode's declared `validate:` IS its own seeded command", () => {
+    const def = commandsDef({ qa: { validate: seededValidateCommand("qa") } })
+    const resolved = resolveMode(def, "drafting", "qa")
+    expect(resolved).toEqual({
+      kind: "resolved",
+      mode: "qa",
+      format: QA_FORMAT,
+      validate: { kind: "command", command: seededValidateCommand("qa") },
+      capabilities: { format: QA_FORMAT, liveValidate: QA_FORMAT.validate },
+    })
+  })
+
+  it("recognizes the seeded command for `review` too, keyed to its own mode name", () => {
+    const def = commandsDef({ review: { validate: seededValidateCommand("review") } })
+    const resolved = resolveMode(def, "drafting", "review")
+    if (resolved.kind !== "resolved") throw new Error("expected resolved")
+    expect(resolved.capabilities.format).toBe(REVIEW_FORMAT)
+    expect(resolved.capabilities.liveValidate).toBe(REVIEW_FORMAT.validate)
+    expect(resolved.capabilities.externalValidate).toBeUndefined()
+  })
+
+  it("still reports externalValidate for a genuine user override even when the command text merely resembles the seeded one", () => {
+    const def = commandsDef({ qa: { validate: `${seededValidateCommand("qa")} --extra` } })
+    const resolved = resolveMode(def, "drafting", "qa")
+    if (resolved.kind !== "resolved") throw new Error("expected resolved")
+    expect(resolved.capabilities.format).toBe(QA_FORMAT)
+    expect(resolved.capabilities.liveValidate).toBeUndefined()
+    expect(resolved.capabilities.externalValidate).toBe(true)
+  })
+})
+
+describe("validateScriptFor — built-in modes", () => {
+  it("`qa` embeds a `gtd check` invocation, never a bare execution", async () => {
+    const resolved = resolveMode(undefined, "", "qa")
+    const { script } = await runScript(resolved, ".gtd/TODO.md")
+    expect(script).toContain(".gtd/TODO.md")
+    expect(script).not.toMatch(/^\s*$/)
+  })
+
+  it("a format-only mode with no validator emits just the file-existence guard", async () => {
+    const def = commandsDef({ adr: { format: "true" } })
+    const resolved = resolveMode(def, "drafting", "adr")
+    if (resolved.kind !== "resolved") throw new Error("expected resolved")
+    const { script } = await runScript(resolved, "docs/adr.md")
+    expect(script).toContain("docs/adr.md")
+  })
+})
+
+describe("validateScriptFor — a workflow-declared command", () => {
+  it("runs the validate command with $GTD_FILE set to the file, wrapped with the fix-prompt instruction", async () => {
+    const def = commandsDef({ adr: { validate: 'echo "saw $GTD_FILE"; exit 1' } })
+    const resolved = resolveMode(def, "drafting", "adr")
+    const { script } = await runScript(resolved, "docs/adr.md")
+    expect(script).toContain("export GTD_FILE='docs/adr.md'\necho \"saw $GTD_FILE\"; exit 1")
+    expect(script).toContain("Fix these format violations in docs/adr.md")
+  })
+
+  it("runs format THEN validate, in that order", async () => {
+    const def = commandsDef({
+      adr: {
+        format: "fmt $GTD_FILE",
+        validate: "adr-lint $GTD_FILE",
+      },
+    })
+    const resolved = resolveMode(def, "drafting", "adr")
+    const { script } = await runScript(resolved, "docs/adr.md")
+    expect(script.indexOf("fmt $GTD_FILE")).toBeGreaterThanOrEqual(0)
+    expect(script.indexOf("fmt $GTD_FILE")).toBeLessThan(script.indexOf("adr-lint $GTD_FILE"))
+  })
+})
+
+describe("validateScriptFor — the binary-presence guard", () => {
+  it("emits a binaryGuard immediately ahead of a plain format: command, naming ITS OWN leading word", async () => {
+    const def = commandsDef({ adr: { format: "adr-fmt $GTD_FILE" } })
+    const resolved = resolveMode(def, "drafting", "adr")
+    const { script } = await runScript(resolved, "docs/adr.md")
+    const guardIndex = script.indexOf(`command -v 'adr-fmt'`)
+    const commandIndex = script.indexOf("adr-fmt $GTD_FILE")
+    expect(guardIndex).toBeGreaterThanOrEqual(0)
+    expect(guardIndex).toBeLessThan(commandIndex)
+    expect(script).toContain('mode "adr": "format" command not found: adr-fmt')
+  })
+
+  it("emits a binaryGuard immediately ahead of a plain validate: command, naming ITS OWN leading word", async () => {
+    const def = commandsDef({ adr: { validate: "adr-lint $GTD_FILE" } })
+    const resolved = resolveMode(def, "drafting", "adr")
+    const { script } = await runScript(resolved, "docs/adr.md")
+    const guardIndex = script.indexOf(`command -v 'adr-lint'`)
+    const commandIndex = script.indexOf("adr-lint $GTD_FILE")
+    expect(guardIndex).toBeGreaterThanOrEqual(0)
+    expect(guardIndex).toBeLessThan(commandIndex)
+    expect(script).toContain('mode "adr": "validate" command not found: adr-lint')
+  })
+
+  it("guards format AND validate independently, each naming its OWN binary", async () => {
+    const def = commandsDef({
+      adr: { format: "adr-fmt $GTD_FILE", validate: "adr-lint $GTD_FILE" },
+    })
+    const resolved = resolveMode(def, "drafting", "adr")
+    const { script } = await runScript(resolved, "docs/adr.md")
+    expect(script).toContain('mode "adr": "format" command not found: adr-fmt')
+    expect(script).toContain('mode "adr": "validate" command not found: adr-lint')
+  })
+
+  it("emits no guard at all for a pipeline command", async () => {
+    const def = commandsDef({ adr: { validate: "adr-lint $GTD_FILE | tee /dev/null" } })
+    const resolved = resolveMode(def, "drafting", "adr")
+    const { script } = await runScript(resolved, "docs/adr.md")
+    expect(script).not.toContain("command -v")
+  })
+
+  it("emits no guard at all for a VAR=x-prefixed command", async () => {
+    const def = commandsDef({ adr: { validate: "FOO=1 adr-lint $GTD_FILE" } })
+    const resolved = resolveMode(def, "drafting", "adr")
+    const { script } = await runScript(resolved, "docs/adr.md")
+    expect(script).not.toContain("command -v")
+  })
+})
+
+describe("validateScriptFor — the mode/format contradiction round-trip", () => {
+  it("embeds a contradiction round-trip block when a built-in mode gets its own formatter", async () => {
+    const def = commandsDef({ qa: { format: "npx prettier --write $GTD_FILE" } })
+    const resolved = resolveMode(def, "drafting", "qa")
+    const { script } = await runScript(resolved, ".gtd/TODO.md")
+    expect(script).toContain("gtd check qa")
+    expect(script).toContain("CONFIGURATION BUG")
+  })
+
+  it("prints a skip notice instead of a round-trip when the validator is external", async () => {
+    const def = commandsDef({
+      adr: { format: "fmt $GTD_FILE", validate: "adr-lint $GTD_FILE" },
+    })
+    const resolved = resolveMode(def, "drafting", "adr")
+    const { script } = await runScript(resolved, "docs/adr.md")
+    expect(script).toContain("skipping the format/validate contradiction check")
+  })
+
+  it("has no round-trip at all when there is no `format:` command", async () => {
+    const def = commandsDef({ adr: { validate: "adr-lint $GTD_FILE" } })
+    const resolved = resolveMode(def, "drafting", "adr")
+    const { script } = await runScript(resolved, "docs/adr.md")
+    expect(script).not.toContain("CONFIGURATION BUG")
+    expect(script).not.toContain("skipping the format/validate contradiction check")
+  })
+})