@pmelab/gtd 24.0.0 → 24.1.0

package/src/emit/GitScript.test.ts

@@ -0,0 +1,260 @@
+import { execFileSync, spawnSync } from "node:child_process"
+import { chmodSync, mkdtempSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { describe, expect, it } from "vitest"
+import fc from "fast-check"
+import {
+  commitAll,
+  commitAsIs,
+  deleteRef,
+  discardPending,
+  hardResetTo,
+  mixedResetTo,
+  pathspec,
+  ScriptSurface,
+  shellQuote,
+  softResetTo,
+  updateRef,
+} from "./GitScript.js"
+import type { LandStep } from "../step/index.js"
+
+const runBashCheckSyntax = (script: string): number => {
+  try {
+    execFileSync("bash", ["-n"], { input: script })
+    return 0
+  } catch (error) {
+    return (error as { status?: number }).status ?? 1
+  }
+}
+
+/**
+ * A fake `git` on `PATH` that behaves per invocation count (tracked in a
+ * counter file), so a script's real retry/discrimination logic can be
+ * exercised against real bash without a real repo. `firstBehavior`/
+ * `secondBehavior` are shell snippets run in place of the real command.
+ */
+const withFakeGit = (
+  firstBehavior: string,
+  secondBehavior = `exit 0`,
+): { readonly binDir: string; readonly counterFile: string } => {
+  const binDir = mkdtempSync(join(tmpdir(), "gitscript-fakebin-"))
+  const counterFile = join(binDir, "count")
+  const gitPath = join(binDir, "git")
+  writeFileSync(
+    gitPath,
+    [
+      "#!/bin/bash",
+      `count=$(( $(cat '${counterFile}' 2>/dev/null || echo 0) + 1 ))`,
+      `echo "$count" > '${counterFile}'`,
+      `if [ "$count" -eq 1 ]; then`,
+      `  ${firstBehavior}`,
+      `else`,
+      `  ${secondBehavior}`,
+      `fi`,
+    ].join("\n"),
+    { mode: 0o755 },
+  )
+  chmodSync(gitPath, 0o755)
+  return { binDir, counterFile }
+}
+
+const runWithFakeGit = (script: string, binDir: string): { status: number | null } =>
+  spawnSync("bash", ["-c", script], {
+    env: { ...process.env, PATH: `${binDir}:${process.env["PATH"]}` },
+    encoding: "utf8",
+  })
+
+const allBuilders: ReadonlyArray<[string, string]> = [
+  ["commitAll", commitAll("gtd(agent): working")],
+  ["commitAsIs", commitAsIs("gtd(agent): working")],
+  ["softResetTo", softResetTo("HEAD~1")],
+  ["mixedResetTo", mixedResetTo("HEAD~1")],
+  ["hardResetTo", hardResetTo("HEAD~1")],
+  ["discardPending", discardPending()],
+  ["updateRef", updateRef("refs/worktree/gtd/review-head", "abc123")],
+  ["deleteRef", deleteRef("refs/worktree/gtd/review-head")],
+]
+
+describe("commitAll", () => {
+  it("stages everything then commits with --allow-empty, retrying without hooks", () => {
+    const script = commitAll("gtd(agent): working")
+    expect(script).toContain("git add -A")
+    expect(script).toContain("git commit --allow-empty -m 'gtd(agent): working'")
+    expect(script).toContain("--no-verify")
+  })
+
+  it("short-circuits: a failed git add never reaches the commit", () => {
+    const { binDir, counterFile } = withFakeGit(`exit 1`)
+    const result = runWithFakeGit(commitAll("msg"), binDir)
+    expect(result.status).not.toBe(0)
+    expect(execFileSync("cat", [counterFile], { encoding: "utf8" }).trim()).toBe("1")
+  })
+})
+
+describe("commitAsIs", () => {
+  it("commits the staged index as-is with --allow-empty, without an add", () => {
+    const script = commitAsIs("gtd(agent): working")
+    expect(script).not.toContain("git add -A")
+    expect(script).toContain("git commit --allow-empty -m 'gtd(agent): working'")
+    expect(script).toContain("--no-verify")
+  })
+})
+
+describe("commitAllowEmpty retry discrimination (via commitAsIs)", () => {
+  it("retries without hooks on the hook's own empty-git-commit rejection", () => {
+    const { binDir, counterFile } = withFakeGit(
+      `echo "fatal: rejecting an empty git commit" >&2; exit 1`,
+      `case "$*" in *--no-verify*) exit 0 ;; *) exit 1 ;; esac`,
+    )
+    const result = runWithFakeGit(commitAsIs("msg"), binDir)
+    expect(result.status).toBe(0)
+    expect(execFileSync("cat", [counterFile], { encoding: "utf8" }).trim()).toBe("2")
+  })
+
+  it("does NOT retry — and stays failed — on a non-hook commit failure", () => {
+    const { binDir, counterFile } = withFakeGit(`echo "some other failure" >&2; exit 1`)
+    const result = runWithFakeGit(commitAsIs("msg"), binDir)
+    expect(result.status).not.toBe(0)
+    expect(execFileSync("cat", [counterFile], { encoding: "utf8" }).trim()).toBe("1")
+  })
+})
+
+describe("softResetTo", () => {
+  it("emits git reset --soft <ref>", () => {
+    expect(softResetTo("HEAD~1")).toBe("git reset --soft 'HEAD~1'")
+  })
+})
+
+describe("mixedResetTo", () => {
+  it("emits git reset --mixed <ref>", () => {
+    expect(mixedResetTo("HEAD~1")).toBe("git reset --mixed 'HEAD~1'")
+  })
+})
+
+describe("hardResetTo", () => {
+  it("emits git reset --hard <ref>", () => {
+    expect(hardResetTo("HEAD~1")).toBe("git reset --hard 'HEAD~1'")
+  })
+})
+
+describe("discardPending", () => {
+  it("stages everything then hard-resets to HEAD", () => {
+    const script = discardPending()
+    expect(script).toContain("git add -A")
+    expect(script).toContain("git reset --hard HEAD")
+  })
+
+  it("short-circuits: a failed git add never reaches the hard reset", () => {
+    const { binDir, counterFile } = withFakeGit(`exit 1`)
+    const result = runWithFakeGit(discardPending(), binDir)
+    expect(result.status).not.toBe(0)
+    expect(execFileSync("cat", [counterFile], { encoding: "utf8" }).trim()).toBe("1")
+  })
+})
+
+describe("updateRef", () => {
+  it("emits git update-ref <ref> <hash>", () => {
+    expect(updateRef("refs/worktree/gtd/review-head", "abc123")).toBe(
+      "git update-ref 'refs/worktree/gtd/review-head' 'abc123'",
+    )
+  })
+})
+
+describe("deleteRef", () => {
+  it("emits git update-ref -d <ref> verbatim (tolerant of a missing ref already in real git)", () => {
+    expect(deleteRef("refs/worktree/gtd/review-head")).toBe(
+      "git update-ref -d 'refs/worktree/gtd/review-head'",
+    )
+  })
+})
+
+describe("pathspec", () => {
+  it("quotes every path and space-joins them", () => {
+    expect(pathspec(["src/a.ts", "src/b.ts"])).toBe("'src/a.ts' 'src/b.ts'")
+  })
+
+  it("returns an empty string for an empty list", () => {
+    expect(pathspec([])).toBe("")
+  })
+})
+
+describe("shellQuote", () => {
+  it.each([
+    ["a newline", "gtd(agent): line one\nline two"],
+    ["a backtick", "gtd(agent): `echo hi`"],
+    ["a double quote", 'gtd(agent): say "hi"'],
+    ["a dollar sign", "gtd(agent): $HOME expansion"],
+    ["an arrow", "gtd(agent): design.product-author → design.product-answer"],
+    ["a single quote", "gtd(agent): it's done"],
+    ["a command substitution", "$(touch PWNED_MARKER)"],
+    ["a semicolon-chained command", "host; touch PWNED_MARKER"],
+  ])("round-trips a message containing %s", (_label, s) => {
+    const out = execFileSync("bash", ["-c", `printf %s ${shellQuote(s)}`], { encoding: "utf8" })
+    expect(out).toBe(s)
+  })
+
+  // 500 samples through 500 bash spawns starved the 30s test timeout whenever
+  // the suite ran under turbo's parallel task load. The property is unchanged;
+  // all samples now round-trip through a SINGLE bash, NUL-delimited on the way
+  // back out (NUL is filtered from the inputs, so it can't collide).
+  it("round-trips arbitrary strings — including newlines and non-ASCII — through a real bash printf", () => {
+    const samples = fc.sample(
+      // `unit: "binary"` covers the full Unicode code-point range (control
+      // chars, newlines, non-ASCII) in one code point per unit, unlike the
+      // default `"grapheme-ascii"` unit fast-check 4.8 otherwise samples,
+      // which never produces a newline or a non-ASCII byte. NUL can't
+      // survive an argv round-trip (bash/exec truncate at the first NUL),
+      // so it's filtered out here deliberately rather than left to chance.
+      fc.string({ unit: "binary" }).filter((s) => !s.includes("\0")),
+      500,
+    )
+    const script = samples.map((s) => `printf '%s\\0' ${shellQuote(s)}`).join("\n")
+    const out = execFileSync("bash", ["-c", script], { encoding: "utf8" })
+    expect(out.split("\0").slice(0, -1)).toEqual(samples)
+  })
+})
+
+describe("every builder's output", () => {
+  it.each(allBuilders)("%s is syntactically valid bash", (_name, script) => {
+    expect(runBashCheckSyntax(script)).toBe(0)
+  })
+})
+
+describe("ScriptSurface.render", () => {
+  const steps: readonly LandStep[] = [
+    { kind: "command", command: `echo hi` },
+    { kind: "gitWrite", write: { kind: "commitAll", message: "gtd(human): building" } },
+    { kind: "outcome", outcome: { kind: "commit", subject: "gtd(human): building" } },
+  ]
+
+  it("renders every step in order ", () => {
+    const script = ScriptSurface.render(steps)
+    expect(script).toContain("set -eu")
+    expect(script).toContain("echo hi")
+    expect(script).toContain("git add -A")
+    expect(script).toContain("# gtd: outcome (print-only)")
+    expect(runBashCheckSyntax(script)).toBe(0)
+  })
+
+  it("renders the empty script for no steps", () => {
+    expect(ScriptSurface.render([])).toBe("")
+  })
+
+  it("renders a `command` step's onFailure wrapper", () => {
+    const script = ScriptSurface.render([
+      { kind: "command", command: "false", onFailure: "custom prompt" },
+    ])
+    expect(script).toContain("custom prompt")
+    expect(runBashCheckSyntax(script)).toBe(0)
+  })
+
+  it("renders a transition outcome naming both states", () => {
+    const script = ScriptSurface.render([
+      { kind: "outcome", outcome: { kind: "transition", from: "building", to: "done" } },
+    ])
+    expect(script).toContain("building")
+    expect(script).toContain("done")
+    expect(runBashCheckSyntax(script)).toBe(0)
+  })
+})

package/src/emit/GitScript.ts

@@ -0,0 +1,131 @@
+import type { GitWrite, LandStep, Outcome } from "../step/index.js"
+
+// POSIX single-quote escaping for a shell command; every builder below routes its interpolated values through this.
+export const shellQuote = (value: string): string => `'${value.replace(/'/g, "'\\''")}'`
+
+export const pathspec = (paths: ReadonlyArray<string>): string => paths.map(shellQuote).join(" ")
+
+/**
+ * `--allow-empty` because gtd's workflow commits may be empty on purpose.
+ * Mirrors `Git.ts`'s retry: only re-tries without hooks on the specific
+ * "empty git commit" rejection message, discriminated from the captured
+ * output rather than the exit code, so a genuinely rejected commit (a lint
+ * error, a commit-msg hook) still fails.
+ */
+const commitAllowEmpty = (message: string): string => {
+  const m = shellQuote(message)
+  return [
+    `if ! out=$(git commit --allow-empty -m ${m} 2>&1); then`,
+    `  case "$out" in`,
+    `    *"empty git commit"*) git commit --allow-empty --no-verify -m ${m} ;;`,
+    `    *) printf '%s\\n' "$out" >&2; exit 1 ;;`,
+    `  esac`,
+    `fi`,
+  ].join("\n")
+}
+
+/** `git add -A` then `commitAllowEmpty`, joined with `&&` so a failing `git add` never reaches the commit. */
+export const commitAll = (message: string): string => `git add -A &&\n${commitAllowEmpty(message)}`
+
+/** No current caller — see `Git.ts`'s `GitWriterOperations.commitAsIs` for why it's kept anyway. */
+export const commitAsIs = (message: string): string => commitAllowEmpty(message)
+
+/** No current caller — see `Git.ts`'s `GitWriterOperations.softResetTo` for why it's kept anyway. */
+export const softResetTo = (ref: string): string => `git reset --soft ${shellQuote(ref)}`
+
+export const mixedResetTo = (ref: string): string => `git reset --mixed ${shellQuote(ref)}`
+
+export const hardResetTo = (ref: string): string => `git reset --hard ${shellQuote(ref)}`
+
+/**
+ * `git add -A` then `git reset --hard HEAD` — discards every pending change,
+ * tracked or untracked. Joined with `&&`: a failed stage must not reach the
+ * hard reset, or untracked survivors remain — the exact outcome this builder
+ * exists to avoid. No current caller — see `Git.ts`'s
+ * `GitWriterOperations.discardPending` for why it's kept anyway.
+ */
+export const discardPending = (): string => `git add -A && git reset --hard HEAD`
+
+export const updateRef = (ref: string, hash: string): string =>
+  `git update-ref ${shellQuote(ref)} ${shellQuote(hash)}`
+
+/** `git update-ref -d <ref>` — idempotent: deleting a missing ref is already a no-op in real git. */
+export const deleteRef = (ref: string): string => `git update-ref -d ${shellQuote(ref)}`
+
+// ── ScriptSurface: LandStep[] → shell ────────────────────────────────────────
+//
+// The sole place `src/step/`'s `LandStep` data becomes runnable shell text.
+// Deliberately does NOT import `src/emit/OutcomeScript.ts`/`src/emit/Emit.ts` (both
+// import `shellQuote` from this file already) — a reverse import back into
+// either would be a real cycle, not just a lint nit, so the two `printf`
+// builders below are a small, load-bearing duplication of
+// `OutcomeScript.ts`'s `transitionOutcome`/`commitOutcome`, not shared code.
+// No test asserts the two stay byte-identical; a drift between them is a
+// review-time risk this boundary accepts.
+
+/** Marks an emitted block as print-only — mirrors `OutcomeScript.ts`'s `OUTCOME_MARKER` verbatim, so `src/testkit/EmittedScriptRecognizer.ts` recognizes either path's output identically. */
+const OUTCOME_MARKER = "# gtd: outcome (print-only)"
+
+const printfLine = (fmt: string, args: readonly string[]): string =>
+  `${OUTCOME_MARKER}\nprintf ${shellQuote(fmt.replace(/\n/g, "\\n"))} ${args.join(" ")}`
+
+const renderOutcome = (outcome: Outcome): string => {
+  switch (outcome.kind) {
+    case "transition":
+      return printfLine("%s %s → %s\n", ["'->'", shellQuote(outcome.from), shellQuote(outcome.to)])
+    case "commit":
+      return printfLine("%s %s\n", ["'[commit]'", shellQuote(outcome.subject)])
+    case "note":
+      return printfLine("%s\n", [shellQuote(outcome.text)])
+  }
+}
+
+const renderGitWrite = (write: GitWrite): string => {
+  switch (write.kind) {
+    case "commitAll":
+      return commitAll(write.message)
+  }
+}
+
+/**
+ * Wraps `command` so a non-zero exit prints `prompt` plus the command's
+ * captured output before propagating that exit code — mirrors `Emit.ts`'s
+ * `failurePromptWrapper` (same reverse-import concern as `renderOutcome`
+ * above: `Emit.ts` imports `shellQuote` from here already).
+ */
+const failurePromptWrapper = (command: string, prompt: string): string => {
+  const promptQ = shellQuote(prompt)
+  return [
+    `gtd_validate_status=0`,
+    `gtd_validate_out="$( {`,
+    command,
+    `} 2>&1 )" || gtd_validate_status=$?`,
+    `if [ "$gtd_validate_status" -ne 0 ]; then`,
+    `  printf '%s\\n\\n%s\\n' ${promptQ} "$gtd_validate_out"`,
+    `  exit "$gtd_validate_status"`,
+    `fi`,
+  ].join("\n")
+}
+
+const renderLandStep = (step: LandStep): string => {
+  if (step.kind === "gitWrite") return renderGitWrite(step.write)
+  if (step.kind === "outcome") return renderOutcome(step.outcome)
+  if (step.kind === "uncheck") return `gtd uncheck ${shellQuote(step.file)}`
+  return step.onFailure !== undefined
+    ? failurePromptWrapper(step.command, step.onFailure)
+    : step.command
+}
+
+/**
+ * A rendered landing script — a plain `string` at runtime, constructible only
+ * by `ScriptSurface.render`, so a bare string cannot reach `gtd land`'s
+ * emitted output by construction.
+ */
+export type RunnableScript = string & { readonly guarded: unique symbol }
+
+export const ScriptSurface = {
+  render: (steps: readonly LandStep[]): RunnableScript => {
+    const rendered = steps.map(renderLandStep)
+    return (rendered.length === 0 ? "" : ["set -eu", ...rendered].join("\n\n")) as RunnableScript
+  },
+}

package/src/emit/ModeContradiction.test.ts

@@ -0,0 +1,120 @@
+import { execFileSync } from "node:child_process"
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { describe, expect, it } from "vitest"
+import {
+  buildModeContradictionCheck,
+  contradictionMessage,
+  modeContradictionSkipNotice,
+} from "./ModeContradiction.js"
+import { shellQuote } from "./index.js"
+
+describe("buildModeContradictionCheck", () => {
+  const inputs = {
+    mode: "qa",
+    samplePath: "/fixture-scratch/gtd-mode-sample-qa-12345.md",
+    sample: "Sample plan.\n",
+    formatCommand: "npx oxfmt --write '/fixture-scratch/gtd-mode-sample-qa-12345.md'",
+  }
+
+  it("pins the block's exact bytes against a path the test supplies", () => {
+    const block = buildModeContradictionCheck(inputs)
+    const pathQ = shellQuote(inputs.samplePath)
+    const messageQ = shellQuote(contradictionMessage(inputs.mode, inputs.formatCommand))
+    expect(block).toBe(
+      [
+        `printf '%s' ${shellQuote(inputs.sample)} > ${pathQ}`,
+        inputs.formatCommand,
+        `gtd check qa ${pathQ} >/dev/null 2>&1 || {`,
+        `  printf '%s\\n' ${messageQ} >&2`,
+        `  cat ${pathQ} >&2`,
+        `  rm -f ${pathQ}`,
+        `  exit 1`,
+        `}`,
+        `rm -f ${pathQ}`,
+      ].join("\n"),
+    )
+  })
+
+  it("shell-quotes a sample containing single quotes and newlines safely", () => {
+    const sample = "a 'quoted' sample\nwith two lines\n"
+    const block = buildModeContradictionCheck({ ...inputs, sample })
+    expect(
+      block.startsWith(`printf '%s' ${shellQuote(sample)} > ${shellQuote(inputs.samplePath)}`),
+    ).toBe(true)
+  })
+})
+
+describe("contradictionMessage", () => {
+  const message = contradictionMessage("review", "npx oxfmt --write '<file>'")
+
+  it("names the mode", () => {
+    expect(message).toContain('"review"')
+  })
+
+  it("tells the agent this is a configuration bug and not the steering file", () => {
+    expect(message.toLowerCase()).toContain("configuration bug")
+    expect(message).toContain("Do NOT edit the steering file")
+  })
+
+  it("tells the agent to stop and end its turn", () => {
+    expect(message.toLowerCase()).toContain("stop and end your turn")
+  })
+
+  it("names the exact rendered format: command", () => {
+    expect(message).toContain("npx oxfmt --write '<file>'")
+  })
+
+  it("is not fixPromptInstruction's text and shares no wording that blames the turn", () => {
+    expect(message).not.toContain("Your last turn")
+    expect(message).not.toContain("Fix these format violations")
+  })
+})
+
+describe("modeContradictionSkipNotice", () => {
+  it("is a single printf-to-stderr line naming the mode", () => {
+    const line = modeContradictionSkipNotice("adr")
+    expect(line.split("\n").length).toBe(1)
+    expect(line).toContain(">&2")
+    expect(line).toContain("adr")
+    expect(line.toLowerCase()).toContain("skip")
+  })
+})
+
+describe("buildModeContradictionCheck, run for real (a stub `gtd check` standing in for a reflow-broken validator)", () => {
+  it("fails loudly, naming the mode and printing the rendered format: command, when the mode's validator rejects the (simulated) reflowed sample", () => {
+    const dir = mkdtempSync(join(tmpdir(), "gtd-mode-contradiction-run-"))
+    try {
+      // A stub `gtd` on PATH ahead of the real one: `check` always fails,
+      // standing in for a `format:` command whose reflow broke the sample.
+      writeFileSync(join(dir, "gtd"), '#!/bin/sh\nif [ "$1" = check ]; then exit 1; fi\nexit 0\n', {
+        mode: 0o755,
+      })
+      const samplePath = join(dir, "sample.md")
+      const script = buildModeContradictionCheck({
+        mode: "review",
+        samplePath,
+        sample: "irrelevant, only shape matters here",
+        formatCommand: "true", // the "format:" command itself is a no-op; the stub `gtd check` simulates the break it would cause
+      })
+      let result: { readonly status: number | null; readonly stderr: string }
+      try {
+        execFileSync("bash", ["-c", script], {
+          env: { ...process.env, PATH: `${dir}:${process.env.PATH}` },
+          stdio: ["ignore", "pipe", "pipe"],
+        })
+        result = { status: 0, stderr: "" }
+      } catch (error) {
+        const err = error as { status: number | null; stderr: Buffer }
+        result = { status: err.status, stderr: err.stderr.toString() }
+      }
+      expect(result.status).not.toBe(0)
+      expect(result.stderr).toContain('"review"')
+      expect(result.stderr).toContain("CONFIGURATION BUG")
+      expect(result.stderr).toContain("true") // the rendered format: command
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+})

package/src/emit/ModeContradiction.ts

@@ -0,0 +1,66 @@
+import { shellQuote } from "./GitScript.js"
+
+/** Every value `buildModeContradictionCheck` needs, already resolved/rendered by the caller. */
+export interface ModeContradictionInputs {
+  readonly mode: string
+  /** Absolute scratch path the sample is written to, formatted at, and removed from. */
+  readonly samplePath: string
+  /** The format's own canonical sample (`SteeringFormat.sample`), written verbatim via `printf '%s'`. */
+  readonly sample: string
+  /** The mode's `format:` command, run with `$GTD_FILE` set to `samplePath`. */
+  readonly formatCommand: string
+}
+
+/**
+ * Written for two readers at once, since gtd validate's exit code carries no
+ * second meaning to distinguish them: the agent (this is a CONFIGURATION BUG,
+ * not the steering file — stop, don't edit it, or a fix-retry loop will
+ * thrash on the document) and the human (which mode, and the exact rendered
+ * `format:` command, to fix `gtd.config.ts` without reproducing the failure).
+ */
+export const contradictionMessage = (mode: string, formatCommand: string): string =>
+  `gtd: mode "${mode}"'s format: command breaks its own validator — this is a ` +
+  `CONFIGURATION BUG, not a problem with the steering file. Do NOT edit the ` +
+  `steering file — stop and end your turn now.\n` +
+  `The rendered format: command that ran:\n${formatCommand}\n` +
+  `What it turned mode "${mode}"'s own canonical sample into:`
+
+/**
+ * Formats a copy of the mode's own canonical sample and re-validates it with
+ * `gtd check <mode>`, failing loudly when the round-trip breaks it — detects a
+ * mode whose `format:` contradicts its own `validate:` without ever touching
+ * the real steering file. `printf '%s'` over a `shellQuote`d sample, never a
+ * heredoc, since no delimiter chosen ahead of time can collide with the
+ * sample's own bytes. One bash fragment with no blank lines (so
+ * `src/emit/Emit.ts`'s `assembleScript` never splits it from a sibling step), meant
+ * to run BEFORE `[ -f <file> ] || exit 0` in the emitted validate script so it
+ * still fires at a first-write beat where the real steering file doesn't
+ * exist yet.
+ */
+export const buildModeContradictionCheck = (inputs: ModeContradictionInputs): string => {
+  const { mode, samplePath, sample, formatCommand } = inputs
+  const pathQ = shellQuote(samplePath)
+  const messageQ = shellQuote(contradictionMessage(mode, formatCommand))
+  return [
+    `printf '%s' ${shellQuote(sample)} > ${pathQ}`,
+    formatCommand,
+    `gtd check ${mode} ${pathQ} >/dev/null 2>&1 || {`,
+    `  printf '%s\\n' ${messageQ} >&2`,
+    `  cat ${pathQ} >&2`,
+    `  rm -f ${pathQ}`,
+    `  exit 1`,
+    `}`,
+    `rm -f ${pathQ}`,
+  ].join("\n")
+}
+
+/**
+ * Skip notice for a mode whose validator is EXTERNAL (a user `validate:`
+ * command, not one of the two built-in modes) — there's no in-process parser
+ * to round-trip a sample through. Printed to stderr since silence would read
+ * as a clean bill of health.
+ */
+export const modeContradictionSkipNotice = (mode: string): string => {
+  const message = `gtd: mode "${mode}" has an external validate: command — skipping the format/validate contradiction check`
+  return `printf '%s\\n' ${shellQuote(message)} >&2`
+}