@pmelab/gtd 27.2.0 → 27.4.0

package/src/replay/Replay.ts

@@ -236,7 +236,7 @@ const STEERING_OPTIONS = ["file", "mode", "label", "base"]
 // type check, so a misspelt key would otherwise be silently ignored.
 const KNOWN_OPTIONS: Readonly<Record<StepKind, ReadonlySet<string>>> = {
   agent: new Set([...STEERING_OPTIONS, "model", "system", "allowEmpty", "keep"]),
-  human: new Set([...STEERING_OPTIONS, "message", "acceptClean"]),
+  human: new Set([...STEERING_OPTIONS, "message", "acceptClean", "approve"]),
   run: new Set(STEERING_OPTIONS),
   judge: new Set([...STEERING_OPTIONS, "message"]),
 }
@@ -249,6 +249,14 @@ const unknownOptions = (step: ReachedStep): string | undefined => {
   return `gtd: step "${step.name}": unknown key(s) ${unknown.join(", ")} in ${step.kind}() options`
 }
 
+const approveConflict = (step: ReachedStep): string | undefined => {
+  const request = step.request
+  if (request.kind !== "human" || request.options.approve !== true) return undefined
+  const keys = (["mode", "file"] as const).filter((key) => request.options[key] !== undefined)
+  if (keys.length === 0) return undefined
+  return `gtd: step "${step.name}": approve cannot be combined with ${keys.join(", ")} in human() options — an approval records exactly the judged tree, and a steering file is rewritten on landing`
+}
+
 export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
   const commits: readonly ParsedCommit[] = input.episode.commits.map((c) => ({
     ...c,
@@ -485,10 +493,20 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
         message: `gtd: commit ${short(expected.hash)} names "${expected.name}" as the next step, but replay reached "${step.name}" — ${DIVERGED}`,
       }
     }
-    const error = unknownOptions(step) ?? checkIdentity(step)
+    const error = unknownOptions(step) ?? approveConflict(step) ?? checkIdentity(step)
     return error === undefined ? undefined : { kind: "failed", message: error }
   }
 
+  const missingApproval = (step: ReachedStep, commit: ParsedCommit, expected: string) => {
+    if (step.request.kind !== "human" || step.request.options.approve !== true) return undefined
+    const approved = commit.parsed.approved
+    if (approved !== undefined && formatStepId(approved.step) === expected) return undefined
+    return {
+      kind: "divergence" as const,
+      message: `gtd: commit ${short(commit.hash)} completes approval gate "${expected}" but records no Gtd-Approved for it — ${DIVERGED}`,
+    }
+  }
+
   const consumeCommit = (step: ReachedStep, commit: ParsedCommit): unknown => {
     const recorded = commit.parsed.step
     const expected = formatStepId(step.id)
@@ -500,6 +518,8 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
         message: `gtd: commit ${short(commit.hash)} ${what}, but replay expected "${expected}" — ${DIVERGED}`,
       })
     }
+    const unapproved = missingApproval(step, commit, expected)
+    if (unapproved !== undefined) return finish(unapproved)
     cursor++
     advance(commit)
     if (commit.parsed.kept !== undefined) {

package/src/replay/Trailers.test.ts

@@ -1,5 +1,10 @@
 import { describe, expect, it } from "vitest"
-import { formatCommitMessage, parseCommitMessage, parseSubject } from "./Trailers.js"
+import {
+  formatCommitMessage,
+  isRecordableApproval,
+  parseCommitMessage,
+  parseSubject,
+} from "./Trailers.js"
 
 describe("the commit-message codec", () => {
   it("round-trips a step commit's subject and trailers", () => {
@@ -173,3 +178,107 @@ describe("Gtd-Kept", () => {
     expect(parsed.format).toBe(1)
   })
 })
+
+describe("Gtd-Approved", () => {
+  const approved = {
+    step: { name: "seam", occurrence: 2 },
+    name: "Ada Lovelace",
+    email: "ada@x.io",
+  }
+  const line = (value: string) => `gtd(human): a → b\n\nGtd-Approved: ${value}`
+
+  it("is written as one JSON line between Gtd-Judge and Gtd-Branch and round-trips", () => {
+    const message = formatCommitMessage({
+      actor: "human",
+      to: "next",
+      from: "seam",
+      step: { name: "seam", occurrence: 2 },
+      judge: [{ id: "v", answer: "yes", p: 1 }],
+      branch: "feat",
+      approved,
+    })
+    const lines = message.split("\n")
+    const at = lines.indexOf(
+      'Gtd-Approved: {"step":"seam#2","name":"Ada Lovelace","email":"ada@x.io"}',
+    )
+    expect(at).toBeGreaterThan(-1)
+    expect(lines[at - 1]).toMatch(/^Gtd-Judge:/)
+    expect(lines[at + 1]).toBe("Gtd-Branch: feat")
+    expect(parseCommitMessage(message).approved).toEqual(approved)
+  })
+
+  it.each([
+    ["a plain step", "seam"],
+    ["a step with a space and hash", "phase#1 review"],
+    ["a step with angle brackets", "a <b> c"],
+    ["a scoped step", "pkg.seam"],
+    ["a quote/backslash approver name", "seam", 'Ada "A" \\ L'],
+  ])("round-trips %s", (_label, stepName, approver = "Ada") => {
+    const a = { step: { name: stepName, occurrence: 3 }, name: approver, email: "a@x.io" }
+    expect(
+      parseCommitMessage(formatCommitMessage({ actor: "human", to: "b", approved: a })).approved,
+    ).toEqual(a)
+  })
+
+  it("reads undefined for the old shape, non-objects and bad fields", () => {
+    for (const value of [
+      "seam#1 Ada <a@x.io>",
+      "",
+      "[]",
+      '"x"',
+      "null",
+      '{"step":"seam#1","name":"Ada"}',
+      '{"step":"seam#1","name":"Ada","email":1}',
+      '{"step":"seam","name":"Ada","email":"a@x.io"}',
+      '{"step":"seam#0","name":"Ada","email":"a@x.io"}',
+    ]) {
+      expect(parseCommitMessage(line(value)).approved).toBe(undefined)
+    }
+  })
+
+  it("reads undefined for a control character in any field", () => {
+    for (const json of [
+      '{"step":"se\\u001bam#1","name":"Ada","email":"a@x.io"}',
+      '{"step":"seam#1","name":"Ada\\u0007","email":"a@x.io"}',
+      '{"step":"seam#1","name":"Ada","email":"a\\u0085@x.io"}',
+    ]) {
+      expect(parseCommitMessage(line(json)).approved).toBe(undefined)
+    }
+  })
+
+  it("reads undefined when absent", () => {
+    expect(parseCommitMessage(formatCommitMessage({ actor: "agent", to: "b" })).approved).toBe(
+      undefined,
+    )
+  })
+})
+
+describe("isRecordableApproval", () => {
+  const of = (name: string, email: string, occurrence = 1) => ({
+    step: { name: "gate", occurrence },
+    name,
+    email,
+  })
+
+  it("accepts ordinary, quoted, backslashed and angle-bracketed identities", () => {
+    for (const name of ["Ada", 'A "B"', "A\\B", "A <B>"]) {
+      expect(isRecordableApproval(of(name, "a@x.io"))).toBe(true)
+    }
+    expect(isRecordableApproval(of("Ada", "a<b>@x.io"))).toBe(true)
+  })
+
+  it("refuses a C1 control character in name or email", () => {
+    expect(isRecordableApproval(of("Ada\u0085", "a@x.io"))).toBe(false)
+    expect(isRecordableApproval(of("Ada", "a\u0085@x.io"))).toBe(false)
+  })
+
+  it("refuses a JS line terminator that would split the trailer on read", () => {
+    const name = "x\u2028Gtd-Branch: forged\u2028"
+    expect(isRecordableApproval(of(name, "a@x.io"))).toBe(false)
+    expect(isRecordableApproval(of("Ada", "a\u2029@x.io"))).toBe(false)
+  })
+
+  it("refuses an occurrence that does not read back", () => {
+    expect(isRecordableApproval(of("Ada", "a@x.io", 0))).toBe(false)
+  })
+})

package/src/replay/Trailers.ts

@@ -60,6 +60,12 @@ export interface CostEntry {
   readonly model: string | undefined
 }
 
+export interface Approval {
+  readonly step: StepId
+  readonly name: string
+  readonly email: string
+}
+
 export interface CommitMessage {
   readonly subject: string
   readonly parsed: ParsedSubject | undefined
@@ -77,6 +83,8 @@ export interface CommitMessage {
   readonly version: string | undefined
   /** The off-branch tip a keep step set aside; a non-hash value is skipped. */
   readonly kept: string | undefined
+  /** `Gtd-Approved`; a malformed or control-character value is skipped. */
+  readonly approved: Approval | undefined
   readonly format: number
 }
 
@@ -106,7 +114,7 @@ const CONFIG_RE = /^([0-9a-f]{16}) (.+)$/
 // JSON string. A control character is refused on read: history written by
 // someone else must never put escape sequences on a terminal.
 // eslint-disable-next-line no-control-regex -- the control range IS the point
-const CONTROL_CHARACTER = /[\x00-\x1f\x7f-\x9f]/
+const CONTROL_CHARACTER = /[\x00-\x1f\x7f-\x9f\u2028\u2029]/
 const encodePath = (path: string): string =>
   path.trim() !== path || path.startsWith('"') || CONTROL_CHARACTER.test(path)
     ? JSON.stringify(path)
@@ -115,6 +123,24 @@ const decodePath = (raw: string): string | undefined => {
   const path = raw.startsWith('"') ? parseJson(raw) : raw
   return typeof path === "string" && path !== "" && !CONTROL_CHARACTER.test(path) ? path : undefined
 }
+const decodeApproval = (raw: string): Approval | undefined => {
+  const parsed = parseJson(raw)
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return undefined
+  const { step, name, email } = parsed as Record<string, unknown>
+  if (typeof step !== "string" || typeof name !== "string" || typeof email !== "string")
+    return undefined
+  if ([step, name, email].some((field) => CONTROL_CHARACTER.test(field))) return undefined
+  const id = parseStepId(step)
+  return id === undefined ? undefined : { step: id, name, email }
+}
+const encodeApproval = ({ step, name, email }: Approval): string =>
+  JSON.stringify({ step: formatStepId(step), name, email })
+// The land-time refusal relies on this: an approval that would not read back
+// unchanged must never be written.
+export const isRecordableApproval = (approval: Approval): boolean => {
+  const back = decodeApproval(encodeApproval(approval))
+  return back !== undefined && encodeApproval(back) === encodeApproval(approval)
+}
 const FORMAT_RE = /^[1-9][0-9]*$/
 const HASH_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/
 
@@ -125,6 +151,7 @@ interface Trailers {
   branch: string | undefined
   version: string | undefined
   kept: string | undefined
+  approved: Approval | undefined
   readonly judge: JudgeVerdict[]
   readonly vars: Record<string, string>
   readonly config: Record<string, string>
@@ -164,6 +191,9 @@ const TRAILER_READERS: Readonly<Record<string, (value: string, into: Trailers) =
   "Gtd-Kept": (value, into) => {
     if (HASH_RE.test(value)) into.kept ??= value
   },
+  "Gtd-Approved": (value, into) => {
+    into.approved ??= decodeApproval(value)
+  },
   "Gtd-Format": (value, into) => {
     if (FORMAT_RE.test(value)) into.format ??= Number(value)
   },
@@ -183,6 +213,7 @@ export const parseCommitMessage = (message: string): CommitMessage => {
     branch: undefined,
     version: undefined,
     kept: undefined,
+    approved: undefined,
     judge: [],
     vars: {},
     config: {},
@@ -208,6 +239,8 @@ 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`. */
+  readonly approved?: Approval
   readonly branch?: string
   readonly version?: string
 }
@@ -230,6 +263,9 @@ export const formatCommitMessage = (spec: CommitSpec): string => {
     )
   }
   for (const verdict of spec.judge ?? []) lines.push(`Gtd-Judge: ${JSON.stringify(verdict)}`)
+  if (spec.approved !== undefined) {
+    lines.push(`Gtd-Approved: ${encodeApproval(spec.approved)}`)
+  }
   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}`)

package/src/replay/index.ts

@@ -2,7 +2,9 @@ export { replay, type EpisodeCommit, type ReachedStep, type ReplayOutcome } from
 export { treeFromRecord, type TreeView } from "./Tree.js"
 export {
   formatCommitMessage,
+  formatStepId,
   formatSubject,
+  isRecordableApproval,
   parseCommitMessage,
   type CommitSpec,
   type JudgeVerdict,

package/src/replay/seamGate.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest"
+import { human, seamGate, type DiffShape, type DiffShapeResult, type Flow } from "../flows/index.js"
+import { replay, treeFromRecord } from "./index.js"
+
+// Lives in replay, which drives a flow to its rest (flows tests may not import replay).
+const shape = (
+  choice: DiffShape,
+  strays: string[] = [],
+  unreadable: string[] = [],
+): DiffShapeResult => ({ choice, strays, unreadable, judgment: undefined })
+
+const restOf = async (result: DiffShapeResult) => {
+  const flow: Flow = async () => {
+    await seamGate("seam", result)
+    await human("next")
+  }
+  const outcome = await replay({
+    flow,
+    episode: { base: { hash: "0".repeat(40), tree: treeFromRecord({}) }, commits: [] },
+    vars: {},
+    env: {},
+    start: "0".repeat(40),
+    budgetBytes: 1024,
+  })
+  if (outcome.kind !== "rest") throw new Error(`expected a rest, got ${outcome.kind}`)
+  return outcome.rest
+}
+
+describe("seamGate", () => {
+  for (const choice of ["land", "reject"] as const) {
+    it(`reaches no step on ${choice}: the flow's next step is the rest`, async () => {
+      const rest = await restOf(shape(choice, ["a.ts"]))
+      expect(rest.name).toBe("next")
+    })
+  }
+
+  it("rests at an approve human step named after the caller on refactor-first", async () => {
+    const rest = await restOf(shape("refactor-first", ["a.ts"]))
+    expect(rest.name).toBe("seam")
+    expect(rest.request).toMatchObject({ kind: "human", options: { approve: true } })
+  })
+
+  it("lists every stray in order, marks only the unreadable, names gtd land and gtd abandon", async () => {
+    const rest = await restOf(shape("refactor-first", ["a.ts", "b/c.ts", "z.bin"], ["b/c.ts"]))
+    if (rest.request.kind !== "human") throw new Error("expected a human step")
+    const message = rest.request.options.message ?? ""
+    const lines = message.split("\n")
+    const strays = lines.filter((line) => line.startsWith("- "))
+    expect(strays).toEqual(["- a.ts", "- b/c.ts (unreadable — not judged)", "- z.bin"])
+    expect(message).toMatch(/`gtd land`[^\n]*approve/)
+    expect(message).toContain("`gtd abandon`")
+  })
+
+  it("quotes a stray path with a control character", async () => {
+    const rest = await restOf(shape("refactor-first", ["a\nb", "c\u001b[2K"]))
+    if (rest.request.kind !== "human") throw new Error("expected a human step")
+    const strays = (rest.request.options.message ?? "")
+      .split("\n")
+      .filter((line) => line.startsWith("- "))
+    expect(strays).toEqual(['- "a\\nb"', '- "c\\u001b[2K"'])
+  })
+})

package/src/step/LandStep.ts

@@ -8,6 +8,7 @@ import type { StateName } from "../workflow/index.js"
  */
 export type GitWrite =
   | { readonly kind: "commitAll"; readonly message: string }
+  | { readonly kind: "commitClean"; readonly message: string }
   | { readonly kind: "updateRef"; readonly ref: string; readonly target: "HEAD" }
   | { readonly kind: "keepTurn"; readonly ref: string; readonly message: string }
 

package/src/step/planStep.test.ts

@@ -131,6 +131,38 @@ describe("planStep — keepHistory", () => {
   })
 })
 
+describe("planStep — approval landing", () => {
+  const approved = { step: { name: "gate", occurrence: 1 }, name: "Ada", email: "ada@x.io" }
+
+  it("commits with commitClean when the landing records an approval", () => {
+    const base = commitTo("gate", "again")
+    const s = snapshot({
+      state: "gate",
+      stepDef: {},
+      landing: { ...base, spec: { ...base.spec, approved } },
+    })
+    const outcome = planStep(s)
+    if (outcome.kind !== "commit") throw new Error(`expected commit, got ${outcome.kind}`)
+    expect(outcome.steps[0]).toMatchObject({ write: { kind: "commitClean" } })
+  })
+
+  it("a finishing approval still points the history ref after the commitClean write", () => {
+    const base = commitTo("gate", "idle")
+    const s = snapshot({
+      state: "gate",
+      stepDef: {},
+      landing: { ...base, spec: { ...base.spec, approved }, 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((x) => (x.kind === "gitWrite" ? x.write.kind : x.kind))).toEqual([
+      "commitClean",
+      "updateRef",
+      "outcome",
+    ])
+  })
+})
+
 describe("planStep — keepTurn", () => {
   const kept = "refs/gtd/kept/abc/building"
 

package/src/step/planStep.ts

@@ -87,7 +87,9 @@ export const planStep = (
         write:
           landing.keepTurn !== undefined
             ? { kind: "keepTurn", ref: landing.keepTurn, message }
-            : { kind: "commitAll", message },
+            : landing.spec.approved !== undefined
+              ? { kind: "commitClean", message }
+              : { kind: "commitAll", message },
       },
       ...(landing.keepHistory !== undefined
         ? [

package/src/testkit/EmittedScriptRecognizer.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest"
 import {
   commitAll,
   commitAsIs,
+  commitClean,
   deleteRef,
   discardPending,
   hardResetTo,
@@ -664,3 +665,29 @@ describe("applyEmittedScript — keepTurn", () => {
     expect(repo.resolveRef(REF)).toBeNull()
   })
 })
+
+describe("applyEmittedScript — commitClean", () => {
+  const MESSAGE = 'gtd(human): gate → again\n\nGtd-Approved: {"step":"gate#1"}'
+
+  it("applies the rendered block as an empty commit over HEAD", () => {
+    const repo = new InMemRepo()
+    repo.writeFile("base.txt", "0")
+    repo.seedCommit("chore: first")
+    const result = applyEmittedScript(repo, NO_COMMANDS, commitClean(MESSAGE))
+    expect(result).toMatchObject({ ok: true })
+    expect(repo.lastCommitMessage()).toBe(MESSAGE)
+    expect(repo.statusPorcelain()).toBe("")
+  })
+
+  it("fails loudly on a one-character near-miss and applies nothing", () => {
+    const repo = new InMemRepo()
+    repo.writeFile("base.txt", "0")
+    repo.seedCommit("chore: first")
+    const before = snapshot(repo)
+    const nearMiss = commitClean(MESSAGE).replace("update-ref -m", "update-ref -n")
+    const result = applyEmittedScript(repo, NO_COMMANDS, nearMiss)
+    expect(result.ok).toBe(false)
+    expect(result.error).toContain("unrecognized script block")
+    expect(snapshot(repo)).toEqual(before)
+  })
+})

package/src/testkit/EmittedScriptRecognizer.ts

@@ -6,6 +6,7 @@
 import {
   commitAll,
   commitAsIs,
+  commitClean,
   deleteRef,
   discardPending,
   hardResetTo,
@@ -185,6 +186,17 @@ const recognizeGitBuilders = (repo: InMemRepo, block: string): BlockOutcome | un
     return undefined
   }
 
+  if (block.startsWith("gtd_head=$(git rev-parse --verify HEAD) || exit 1\nif [ -n ")) {
+    const [message] = extractQuotedTokens(block.slice(block.indexOf('"$gtd_head" -m ')))
+    if (message !== undefined && commitClean(message) === block) {
+      const failure = repo.commitClean(message)
+      return failure === undefined
+        ? { kind: "applied" }
+        : { kind: "failed", error: failure, status: 1 }
+    }
+    return undefined
+  }
+
   if (block.startsWith("if ! out=$(git commit --allow-empty -m ")) {
     const [message] = extractQuotedTokens(conditionLine)
     if (message !== undefined && commitAsIs(message) === block) {
@@ -667,6 +679,26 @@ const recognizeDeferNotes = (repo: InMemRepo, block: string): BlockOutcome | und
   return { kind: "applied" }
 }
 
+/** `mkdir -p <dir>` then `printf '%s\n' <quoted lines> > <path>`: a flow's one-file write. Re-rendered from what was extracted, so any other shape stays unrecognized. */
+const recognizeWriteLines = (repo: InMemRepo, block: string): BlockOutcome | undefined => {
+  const [mkdir, printf, ...rest] = block.split("\n")
+  if (
+    rest.length > 0 ||
+    !mkdir?.startsWith("mkdir -p ") ||
+    !printf?.startsWith("printf '%s\\n' ")
+  ) {
+    return undefined
+  }
+  const tokens = extractQuotedTokens(printf.slice("printf '%s\\n' ".length))
+  const path = tokens.pop()
+  if (path === undefined || !path.includes("/")) return undefined
+  const dir = path.slice(0, path.lastIndexOf("/"))
+  const rendered = `mkdir -p ${dir}\nprintf '%s\\n' ${tokens.map(shellQuote).join(" ")} > ${shellQuote(path)}`
+  if (rendered !== block) return undefined
+  repo.writeFile(path, `${tokens.join("\n")}\n`)
+  return { kind: "applied" }
+}
+
 /** Every recognizer `applyEmittedScript` tries, first match wins — `recognizeScriptedCommand` stays last since it's the exact-hit fallback for anything the rest don't claim. */
 const recognizersFor = (
   repo: InMemRepo,
@@ -679,6 +711,7 @@ const recognizersFor = (
   (block) => recognizeBinaryGuard(commands, block),
   (block) => recognizeGitBuilders(repo, block),
   (block) => recognizeDeferNotes(repo, block),
+  (block) => recognizeWriteLines(repo, block),
   (block) => recognizeFailurePromptWrapper(repo, commands, block),
   (block) => recognizePresentationSubshell(repo, commands, block),
   (block) => recognizeModeContradictionSkipNotice(block),

package/src/testkit/EmittedScripts.test.ts

@@ -275,6 +275,15 @@ for (const makeTier of gitTiers) {
       })
     })
 
+    it("a mkdir + printf write lands one line per token, whatever the token holds", () => {
+      const lines = String.raw`mkdir -p .gtd/packages
+printf '%s\n' 'a' '' 'it'\''s' '100%' '-x' 'a\b' '.gtd/packages/00-x.md' > '.gtd/packages/00-x.md'`
+      expect(run(lines).ok).toBe(true)
+      expect(read(".gtd/packages/00-x.md")).toBe(
+        "a\n\nit's\n100%\n-x\na\\b\n.gtd/packages/00-x.md\n",
+      )
+    })
+
     describe("commitAll", () => {
       it("a staging hook's edit lands in the commit", () => {
         t.seed.stagingHook("readme.txt", "hooked")

package/src/testkit/FakeGitOperations.ts

@@ -77,7 +77,12 @@ const makeGitReaderOps = (repo: InMemRepo, root: string): GitReaderOperations =>
 
   changedPaths: (base?: string) => Effect.succeed(repo.changedPathsWorktree(base)),
 
+  stagedPaths: () => Effect.succeed(repo.stagedPaths()),
+
   diffPaths: (base: string, tip: string) => tryCatch(() => repo.diffPaths(base, tip)),
+
+  // The identity `GitTiers`' live tier configures; the fake commits as no one in particular.
+  authorIdent: () => Effect.succeed(Option.some({ name: "Test", email: "test@test.com" })),
 })
 
 const failOn = (output: string | undefined): void => {