@pmelab/gtd 24.2.0 → 24.4.0

package/src/replay/Trailers.test.ts

@@ -92,6 +92,38 @@ describe("the commit-message codec", () => {
     expect(read('deadbeefdeadbeef "a\\u001b.ts"')).toEqual({})
   })
 
+  it("round-trips Gtd-Branch and Gtd-Version, after Gtd-Judge and before Gtd-Format", () => {
+    const message = formatCommitMessage({
+      actor: "agent",
+      to: "idle",
+      judge: [{ id: "q1", answer: true, p: 0.9 }],
+      branch: "feat/x",
+      version: "1.2.3",
+    })
+    const lines = message.split("\n")
+    const at = (prefix: string) => lines.findIndex((l) => l.startsWith(prefix))
+    expect(at("Gtd-Judge:")).toBeLessThan(at("Gtd-Branch:"))
+    expect(at("Gtd-Branch:")).toBeLessThan(at("Gtd-Version:"))
+    expect(at("Gtd-Version:")).toBeLessThan(at("Gtd-Format:"))
+    const parsed = parseCommitMessage(message)
+    expect(parsed.branch).toBe("feat/x")
+    expect(parsed.version).toBe("1.2.3")
+  })
+
+  it("omits Gtd-Branch and Gtd-Version when unset, and reads them as undefined", () => {
+    const message = formatCommitMessage({ actor: "agent", to: "idle" })
+    expect(message).not.toContain("Gtd-Branch")
+    expect(message).not.toContain("Gtd-Version")
+    const parsed = parseCommitMessage(message)
+    expect(parsed.branch).toBeUndefined()
+    expect(parsed.version).toBeUndefined()
+  })
+
+  it("keeps Gtd-Format at 1 when branch and version are written", () => {
+    const message = formatCommitMessage({ actor: "a", to: "b", branch: "m", version: "1" })
+    expect(message.endsWith("Gtd-Format: 1")).toBe(true)
+  })
+
   it("writes Gtd-Format last on every message, even one with no other trailer", () => {
     const message = formatCommitMessage({ actor: "agent", to: "building" })
     expect(message).toBe("gtd(agent): building\n\nGtd-Format: 1")

package/src/replay/Trailers.ts

@@ -72,6 +72,9 @@ export interface CommitMessage {
   readonly config: Readonly<Record<string, string>>
   readonly reviewBase: string | undefined
   readonly cost: readonly CostEntry[]
+  /** Written only on a process's finishing landing. */
+  readonly branch: string | undefined
+  readonly version: string | undefined
   readonly format: number
 }
 
@@ -116,6 +119,8 @@ interface Trailers {
   step: StepId | undefined
   workflow: string | undefined
   reviewBase: string | undefined
+  branch: string | undefined
+  version: string | undefined
   readonly judge: JudgeVerdict[]
   readonly vars: Record<string, string>
   readonly config: Record<string, string>
@@ -146,6 +151,12 @@ const TRAILER_READERS: Readonly<Record<string, (value: string, into: Trailers) =
   "Gtd-Review-Base": (value, into) => {
     into.reviewBase ??= value.split(/\s/)[0]
   },
+  "Gtd-Branch": (value, into) => {
+    if (value !== "") into.branch ??= value
+  },
+  "Gtd-Version": (value, into) => {
+    if (value !== "") into.version ??= value
+  },
   "Gtd-Format": (value, into) => {
     if (FORMAT_RE.test(value)) into.format ??= Number(value)
   },
@@ -162,6 +173,8 @@ export const parseCommitMessage = (message: string): CommitMessage => {
     step: undefined,
     workflow: undefined,
     reviewBase: undefined,
+    branch: undefined,
+    version: undefined,
     judge: [],
     vars: {},
     config: {},
@@ -187,6 +200,8 @@ export interface CommitSpec {
   readonly config?: Readonly<Record<string, string>>
   readonly cost?: { readonly cost: number; readonly model?: string }
   readonly judge?: readonly JudgeVerdict[]
+  readonly branch?: string
+  readonly version?: string
 }
 
 const sortedEntries = (record: Readonly<Record<string, string>> = {}): [string, string][] =>
@@ -207,6 +222,8 @@ export const formatCommitMessage = (spec: CommitSpec): string => {
     )
   }
   for (const verdict of spec.judge ?? []) lines.push(`Gtd-Judge: ${JSON.stringify(verdict)}`)
+  if (spec.branch !== undefined) lines.push(`Gtd-Branch: ${spec.branch}`)
+  if (spec.version !== undefined) lines.push(`Gtd-Version: ${spec.version}`)
   lines.push(`Gtd-Format: ${HISTORY_FORMAT}`)
   const subject = formatSubject(spec.actor, spec.to, spec.from)
   return `${subject}\n\n${lines.join("\n")}`

package/src/steering/FORMATS.md

@@ -47,7 +47,7 @@ Breaking — committed files, or files an older gtd must read, are affected:
   questions, options, chunks, hunks, ticks, threads or notes.
 - A writer (a tick, a note, a reply) produces text an older gtd cannot read.
 - Renaming or removing a marker: `## Open Questions`, `_your answer_`,
-  `# Review:`, `<!-- base: -->`, `Risk:`, `H:` / `A:`.
+  `# Review:`, `<!-- base: -->`, `Risk:`, a leading `! `, `H:` / `A:`.
 
 ## Format changes bump `Gtd-Format`
 

package/src/steering/SteeringFormat.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest"
-import { steeringFormatFor } from "./index.js"
+import { formatFinding, steeringFormatFor } from "./index.js"
 import type { SteeringFinding, SteeringFormat } from "./SteeringFormat.js"
 
 const QA_FORMAT = steeringFormatFor("qa")!
@@ -89,3 +89,11 @@ describe("SteeringFinding range invariants", () => {
     assertRangeInvariants(findings)
   })
 })
+
+describe("formatFinding", () => {
+  it("a line-carrying finding with no range prints '<file>:<line>: <message>' — the flat-shape fallback no built-in format reaches", () => {
+    expect(formatFinding("FAKE.md", { message: "positioned but rangeless", line: 4 })).toBe(
+      "FAKE.md:5: positioned but rangeless",
+    )
+  })
+})

package/src/steering/SteeringFormat.ts

@@ -41,6 +41,13 @@ export interface SteeringFinding {
   }
 }
 
+/** `file:line:col: message` — the shape editors and grep already jump on. Stored 0-based, printed 1-based. A finding with a `line` but no `range`, or none at all, degrades to the shorter forms. */
+export const formatFinding = (file: string, finding: SteeringFinding): string => {
+  if (finding.line === undefined) return finding.message
+  const col = finding.range !== undefined ? `:${finding.range.start.character + 1}` : ""
+  return `${file}:${finding.line + 1}${col}: ${finding.message}`
+}
+
 /** A hunk pointer's document-link target: `range` covers the pointer token itself; `line` is 0-based, so a `#42` suffix resolves down by one and a bare `./path` lands at 0. */
 export interface SteeringLink {
   readonly range: {

package/src/steering/contract.test.ts

@@ -174,6 +174,7 @@ describe("review notes, the review → fix hand-off", () => {
         anchor: "Parser accepts CRLF",
         before: "**Line endings are normalized before the split.**",
         text: "**Line endings are normalized before the split.** Also normalize in the writer.",
+        forced: false,
       },
       {
         id: "note-2",
@@ -181,6 +182,7 @@ describe("review notes, the review → fix hand-off", () => {
         anchor: "Parser accepts CRLF ./src/parse.ts#30-31",
         before: "Risk: a lone `\\r` is still kept as content",
         text: "Risk: a lone `\\r` is still kept as content. Treat it as a line break too.",
+        forced: false,
       },
       {
         id: "note-3",
@@ -188,6 +190,7 @@ describe("review notes, the review → fix hand-off", () => {
         anchor: "- [x] ./src/parse.test.ts#1-40 — one case per line ending[^fn1]",
         before: "",
         text: "Add a mixed-endings case.",
+        forced: false,
       },
     ])
   })

package/src/steering/index.ts

@@ -5,6 +5,7 @@ import type {
   SteeringOutlineNode,
   SteeringPointer,
 } from "./SteeringFormat.js"
+export { formatFinding } from "./SteeringFormat.js"
 import { qaDescriptor } from "./qa.js"
 import { reviewDescriptor } from "./review.js"
 export { reviewNotes, reviewRisks, type ReviewNote } from "./review.js"

package/src/steering/review.test.ts

@@ -1733,6 +1733,7 @@ describe("reviewNotes", async () => {
         anchor: "Chunk one ./src/a.ts#1-3",
         before: "",
         text: "rename this",
+        forced: false,
       },
     ])
   })
@@ -1753,6 +1754,7 @@ describe("reviewNotes", async () => {
         anchor: "- [ ] ./src/a.ts#1-3[^n1]",
         before: "",
         text: "please split",
+        forced: false,
       },
     ])
   })
@@ -1774,6 +1776,34 @@ describe("reviewNotes", async () => {
     expect(reviewNotes(answered, more).map((n) => n.kind)).toEqual(["footnote"])
   })
 
+  it("a leading ! forces a pointer note and keeps its text", () => {
+    const [n] = reviewNotes(base, base.replace("#1-3", "#1-3 !  rename this"))
+    expect(n).toMatchObject({ kind: "pointer", text: "! rename this", forced: true })
+  })
+
+  it("a leading ! forces a footnote note", () => {
+    const after = base.replace("#1-3", "#1-3[^n1]") + "\n[^n1]: ! please split\n"
+    expect(reviewNotes(base, after)[0]).toMatchObject({ text: "! please split", forced: true })
+  })
+
+  it("a leading ! forces chunk prose", () => {
+    const [n] = reviewNotes(base, doc("! Prose is wrong."))
+    expect(n).toMatchObject({ kind: "chunk", text: "! Prose is wrong.", forced: true })
+  })
+
+  it("a ! glued to the next word is not a marker", () => {
+    const [n] = reviewNotes(base, base.replace("#1-3", "#1-3 != should be ==="))
+    expect(n).toMatchObject({ text: "!= should be ===", forced: false })
+  })
+
+  it("a mid-text ! or a ! in the pointer path does not force", () => {
+    const [n] = reviewNotes(base, base.replace("#1-3", "#1-3 rename this!"))
+    expect(n).toMatchObject({ text: "rename this!", forced: false })
+    const [m] = reviewNotes(base, base.replace("./src/a.ts#1-3", "./src/a!b.ts#1-3 x"))
+    expect(m).toMatchObject({ forced: false })
+    expect(m!.anchor).toContain("a!b.ts")
+  })
+
   it("ids run in document order", () => {
     const after = base.replace("#1-3", "#1-3 a[^n1]") + "\n[^n1]: b\n"
     expect(reviewNotes(base, after).map((n) => [n.id, n.kind])).toEqual([

package/src/steering/review.ts

@@ -1085,12 +1085,14 @@ export interface ReviewNote {
   readonly before: string
   /** The human's text. */
   readonly text: string
+  /** The human opened `text` with `! ` (kept in `text`; the feature review strips it). */
+  readonly forced?: boolean
 }
 
 const pointerLabel = (f: ReviewFile): string =>
   `${f.path}${f.line === undefined ? "" : `#${f.line}${f.rangeEnd === undefined ? "" : `-${f.rangeEnd}`}`}`
 
-type Found = { line: number; note: Omit<ReviewNote, "id"> }
+type Found = { line: number; note: Omit<ReviewNote, "id" | "forced"> }
 
 const chunkNote = (chunk: Changeset, prior: Changeset | undefined): Found[] =>
   chunk.description === (prior?.description ?? "")
@@ -1162,7 +1164,11 @@ export const reviewNotes = (before: string, after: string): readonly ReviewNote[
     }),
     ...footnoteNotes(before, after),
   ]
-  return found.sort((a, b) => a.line - b.line).map((f, i) => ({ id: `note-${i + 1}`, ...f.note }))
+  return found
+    .sort((a, b) => a.line - b.line)
+    .map((f, i) => {
+      return { id: `note-${i + 1}`, ...f.note, forced: /^!(\s|$)/.test(f.note.text) }
+    })
 }
 
 /** Pointer notes the reviewer opened with `Risk:`, in document order — the ones the workflow fixes before the human gate. */

package/src/step/LandStep.ts

@@ -6,7 +6,9 @@ import type { StateName } from "../workflow/index.js"
  * that module, which is what makes writing a live git call inside the core
  * impossible rather than merely discouraged.
  */
-export type GitWrite = { readonly kind: "commitAll"; readonly message: string }
+export type GitWrite =
+  | { readonly kind: "commitAll"; readonly message: string }
+  | { readonly kind: "updateRef"; readonly ref: string; readonly target: "HEAD" }
 
 /** A landed step's trailing report, rendered by `GitScript.ts` into a `printf` line. */
 export type Outcome =

package/src/step/RepoSnapshot.ts

@@ -11,7 +11,13 @@ export type Landing =
   | { readonly kind: "noop"; readonly settled: boolean }
   /** An empty agent turn: recorded, but the process stays at the step. */
   | { readonly kind: "attempt"; readonly subject: string }
-  | { readonly kind: "commit"; readonly to: StateName; readonly spec: CommitSpec }
+  | {
+      readonly kind: "commit"
+      readonly to: StateName
+      readonly spec: CommitSpec
+      /** The full history ref a finishing landing points at its own commit. */
+      readonly keepHistory?: string
+    }
 
 /**
  * Everything `planStep` needs, already resolved

package/src/step/planStart.test.ts

@@ -108,7 +108,8 @@ describe("planStart", () => {
       const plan = await start(repo, "idle", "human", { ...REVIEW, vars: {} })
       if (plan.kind !== "start") throw new Error(`expected start, got ${JSON.stringify(plan)}`)
       const write = plan.steps.find((s) => s.kind === "gitWrite")
-      if (write?.kind !== "gitWrite") throw new Error("expected a gitWrite step")
+      if (write?.kind !== "gitWrite" || write.write.kind !== "commitAll")
+        throw new Error("expected a gitWrite step")
       expect(write.write.message).toContain(`Gtd-Review-Base: ${fork}`)
     })
 
@@ -124,7 +125,8 @@ describe("planStart", () => {
       const plan = await start(repo, "idle", "human", { ...REVIEW, vars: { base: "other" } })
       if (plan.kind !== "start") throw new Error(`expected start, got ${JSON.stringify(plan)}`)
       const write = plan.steps.find((s) => s.kind === "gitWrite")
-      if (write?.kind !== "gitWrite") throw new Error("expected a gitWrite step")
+      if (write?.kind !== "gitWrite" || write.write.kind !== "commitAll")
+        throw new Error("expected a gitWrite step")
       expect(write.write.message).toContain(`Gtd-Review-Base: ${fork}`)
     })
 
@@ -189,7 +191,8 @@ describe("planStart", () => {
     })
     if (plan.kind !== "start") throw new Error(`expected start, got ${plan.kind}`)
     const write = plan.steps.find((s) => s.kind === "gitWrite")
-    if (write?.kind !== "gitWrite") throw new Error("expected a gitWrite step")
+    if (write?.kind !== "gitWrite" || write.write.kind !== "commitAll")
+      throw new Error("expected a gitWrite step")
     expect(write.write.message).toBe(
       "gtd(human): work\n\nGtd-Workflow: working\nGtd-Var: base=main\nGtd-Format: 1",
     )

package/src/step/planStep.test.ts

@@ -92,7 +92,8 @@ describe("planStep — commit", () => {
     })
     if (outcome.kind !== "commit") throw new Error(`expected commit, got ${outcome.kind}`)
     const write = outcome.steps.find((step) => step.kind === "gitWrite")
-    if (write?.kind !== "gitWrite") throw new Error("expected a git write")
+    if (write?.kind !== "gitWrite" || write.write.kind !== "commitAll")
+      throw new Error("expected a git write")
     const trailers = write.write.message.split("\n").slice(2)
     expect(trailers[0]).toBe("Gtd-Step: a#1")
     expect(trailers[1]).toBe("Gtd-Cost: 1.5 m")
@@ -102,3 +103,30 @@ describe("planStep — commit", () => {
     expect(trailers).toHaveLength(5)
   })
 })
+
+describe("planStep — keepHistory", () => {
+  it("writes the history ref right after the commit, before the outcome", () => {
+    const s = snapshot({
+      state: "building",
+      stepDef: {},
+      landing: { ...commitTo("building", "done"), keepHistory: "refs/gtd/history/abc" },
+    })
+    const outcome = planStep(s)
+    if (outcome.kind !== "commit") throw new Error(`expected commit, got ${outcome.kind}`)
+    expect(outcome.steps.map((step) => step.kind)).toEqual(["gitWrite", "gitWrite", "outcome"])
+    expect(outcome.steps[0]).toMatchObject({ write: { kind: "commitAll" } })
+    expect(outcome.steps[1]).toEqual({
+      kind: "gitWrite",
+      write: { kind: "updateRef", ref: "refs/gtd/history/abc", target: "HEAD" },
+    })
+  })
+
+  it("without keepHistory no updateRef is emitted", () => {
+    const s = snapshot({ state: "building", stepDef: {}, landing: commitTo("building", "done") })
+    const outcome = planStep(s)
+    if (outcome.kind !== "commit") throw new Error(`expected commit, got ${outcome.kind}`)
+    expect(
+      outcome.steps.some((step) => step.kind === "gitWrite" && step.write.kind === "updateRef"),
+    ).toBe(false)
+  })
+})

package/src/step/planStep.ts

@@ -83,6 +83,14 @@ export const planStep = (
     steps: [
       ...uncheckStep(snapshot),
       { kind: "gitWrite", write: { kind: "commitAll", message } },
+      ...(landing.keepHistory !== undefined
+        ? [
+            {
+              kind: "gitWrite",
+              write: { kind: "updateRef", ref: landing.keepHistory, target: "HEAD" },
+            } as const,
+          ]
+        : []),
       outcome,
     ],
   }

package/src/testkit/EmittedScriptRecognizer.test.ts

@@ -42,7 +42,7 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
     const result = applyEmittedScript(repo, NO_COMMANDS, commitAll("gtd(agent): building"))
     twin.commitAllWithPrefix("gtd(agent): building")
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(snapshot(repo)).toEqual(snapshot(twin))
   })
 
@@ -60,7 +60,7 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
 
     const result = applyEmittedScript(repo, NO_COMMANDS, commitAll(message))
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(repo.lastCommitMessage()).toBe(message)
   })
 
@@ -77,7 +77,7 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
     const result = applyEmittedScript(repo, NO_COMMANDS, commitAsIs("gtd(agent): as-is"))
     twin.commitAsIs("gtd(agent): as-is")
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(snapshot(repo)).toEqual(snapshot(twin))
   })
 
@@ -97,7 +97,7 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
     const result = applyEmittedScript(repo, NO_COMMANDS, softResetTo(first))
     twin.softResetTo(first)
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(snapshot(repo)).toEqual(snapshot(twin))
     expect(repo.resolveRef("HEAD")).toBe(first)
   })
@@ -118,7 +118,7 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
     const result = applyEmittedScript(repo, NO_COMMANDS, mixedResetTo(first))
     twin.mixedResetTo(first)
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(snapshot(repo)).toEqual(snapshot(twin))
   })
 
@@ -138,7 +138,7 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
     const result = applyEmittedScript(repo, NO_COMMANDS, hardResetTo(first))
     twin.hardResetTo(first)
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(snapshot(repo)).toEqual(snapshot(twin))
     expect(repo.hasPath("b.txt")).toBe(false)
   })
@@ -158,7 +158,7 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
     const result = applyEmittedScript(repo, NO_COMMANDS, discardPending())
     twin.discardPending()
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(snapshot(repo)).toEqual(snapshot(twin))
     expect(repo.readFile("a.txt")).toBe("1")
     expect(repo.hasPath("untracked.txt")).toBe(false)
@@ -176,7 +176,7 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
     const result = applyEmittedScript(repo, NO_COMMANDS, updateRef("refs/gtd/base", hash))
     twin.updateRef("refs/gtd/base", hash)
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(repo.resolveRef("refs/gtd/base")).toBe(hash)
     expect(snapshot(repo)).toEqual(snapshot(twin))
   })
@@ -194,7 +194,7 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
     const result = applyEmittedScript(repo, NO_COMMANDS, deleteRef("refs/gtd/base"))
     twin.deleteRef("refs/gtd/base")
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(repo.resolveRef("refs/gtd/base")).toBeNull()
     expect(snapshot(repo)).toEqual(snapshot(twin))
   })
@@ -210,7 +210,7 @@ describe("applyEmittedScript — gtd check <mode> <file>", () => {
 
     const result = applyEmittedScript(repo, NO_COMMANDS, "gtd check qa '.gtd/TODO.md'")
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
   })
 
   it("fails on invalid qa-mode content (a bare ### heading with no question text)", () => {
@@ -220,7 +220,7 @@ describe("applyEmittedScript — gtd check <mode> <file>", () => {
     const result = applyEmittedScript(repo, NO_COMMANDS, "gtd check qa '.gtd/TODO.md'")
 
     expect(result.ok).toBe(false)
-    expect(result.error).toContain("gtd check qa")
+    expect(result.output).toContain('.gtd/TODO.md is not valid under mode "qa"')
   })
 })
 
@@ -231,7 +231,7 @@ describe("applyEmittedScript — Emit.ts's fileExistsGuard", () => {
 
     const result = applyEmittedScript(repo, NO_COMMANDS, fileExistsGuard(".gtd/PLAN.md"))
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
   })
 
   it("stops the whole script (successfully) when the file is absent — unlike every other guard, it does not fail", () => {
@@ -240,7 +240,7 @@ describe("applyEmittedScript — Emit.ts's fileExistsGuard", () => {
     const script = [fileExistsGuard(".gtd/PLAN.md"), "gtd check qa '.gtd/PLAN.md'"].join("\n\n")
     const result = applyEmittedScript(repo, NO_COMMANDS, script)
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
   })
 
   it("a subsequent block after the guard trips is never applied", () => {
@@ -262,7 +262,7 @@ describe("applyEmittedScript — ModeContradiction.ts's skip notice", () => {
 
     const result = applyEmittedScript(repo, NO_COMMANDS, modeContradictionSkipNotice("adr"))
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
   })
 })
 
@@ -284,7 +284,7 @@ describe("applyEmittedScript — ModeContradiction.ts's contradiction round-trip
 
     const result = applyEmittedScript(repo, commands, block)
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(repo.readFile(samplePath)).toBeUndefined()
   })
 
@@ -359,7 +359,7 @@ describe("applyEmittedScript — the scripted-command table", () => {
 
     const result = applyEmittedScript(repo, commands, "./run-check.sh")
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
   })
 
   it("an 'exit' hit with a non-zero status fails the script", () => {
@@ -370,8 +370,7 @@ describe("applyEmittedScript — the scripted-command table", () => {
 
     const result = applyEmittedScript(repo, commands, "./run-check.sh")
 
-    expect(result.ok).toBe(false)
-    expect(result.error).toContain("./run-check.sh")
+    expect(result).toMatchObject({ ok: false, status: 1, output: "boom\n" })
   })
 
   it("a 'rewrite' hit mutates the repo's file", () => {
@@ -383,7 +382,7 @@ describe("applyEmittedScript — the scripted-command table", () => {
 
     const result = applyEmittedScript(repo, commands, "./format-feedback.sh")
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(repo.readFile("FEEDBACK.md")).toBe("new")
   })
 })
@@ -434,7 +433,7 @@ describe("applyEmittedScript — a tripped precondition stops the script", () =>
 
     const result = applyEmittedScript(repo, NO_COMMANDS, script)
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(repo.lastCommitMessage()).toBe("gtd(agent): lands")
   })
 })
@@ -455,7 +454,7 @@ describe("applyEmittedScript — a realistic assembled multi-block script", () =
 
     const result = applyEmittedScript(repo, NO_COMMANDS, script)
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(repo.lastCommitMessage()).toBe("gtd(agent): second")
     expect(repo.resolveRef("refs/gtd/base")).toBe(first)
   })
@@ -479,7 +478,7 @@ describe("applyEmittedScript — a realistic src/emit/Emit.ts-assembled script",
     const result = applyEmittedScript(repo, NO_COMMANDS, required)
     twin.commitAllWithPrefix("gtd(agent): building")
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(snapshot(repo)).toEqual(snapshot(twin))
   })
 
@@ -505,7 +504,7 @@ describe("applyEmittedScript — a realistic src/emit/Emit.ts-assembled script",
     const { required } = emitScripts(steps)
     const result = applyEmittedScript(repo, NO_COMMANDS, required)
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(repo.resolveRef("refs/worktree/gtd/history")).toBe(tip)
     expect(repo.lastCommitMessage()).toBe("chore: squashed")
     expect(repo.hasPath(".gtd/TODO.md")).toBe(false)
@@ -520,7 +519,7 @@ describe("applyEmittedScript — outcome blocks are inert (no git effect to miss
 
     const result = applyEmittedScript(repo, NO_COMMANDS, transitionOutcome("idle", "working"))
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(snapshot(repo)).toEqual(before)
   })
 
@@ -531,7 +530,7 @@ describe("applyEmittedScript — outcome blocks are inert (no git effect to miss
 
     const result = applyEmittedScript(repo, NO_COMMANDS, commitOutcome("gtd(agent): x"))
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(snapshot(repo)).toEqual(before)
   })
 
@@ -553,7 +552,7 @@ describe("applyEmittedScript — outcome blocks are inert (no git effect to miss
     const result = applyEmittedScript(repo, NO_COMMANDS, required)
     twin.commitAllWithPrefix("gtd(agent): building")
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(snapshot(repo)).toEqual(snapshot(twin))
   })
 
@@ -567,7 +566,7 @@ describe("applyEmittedScript — outcome blocks are inert (no git effect to miss
     ])
     const result = applyEmittedScript(repo, NO_COMMANDS, required)
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(snapshot(repo)).toEqual(before)
   })
 })
@@ -583,7 +582,7 @@ describe("applyEmittedScript — Emit.ts's combinedScript (the whole stdout of a
     const script = combinedScript(required, "")
     const result = applyEmittedScript(repo, NO_COMMANDS, script)
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(repo.lastCommitMessage()).toBe("gtd(human): idle")
   })
 
@@ -605,7 +604,7 @@ describe("applyEmittedScript — Emit.ts's combinedScript (the whole stdout of a
 
     const result = applyEmittedScript(repo, NO_COMMANDS, script)
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(repo.lastCommitMessage()).toBe("gtd(human): idle")
     expect(repo.resolveRef("refs/gtd/marker")).toBe(repo.resolveRef("HEAD"))
   })
@@ -625,7 +624,7 @@ describe("applyEmittedScript — Emit.ts's combinedScript (the whole stdout of a
 
     const result = applyEmittedScript(repo, NO_COMMANDS, script)
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(repo.lastCommitMessage()).toBe("gtd(human): idle")
   })