@pmelab/gtd 27.4.0 → 27.6.0

package/src/replay/Replay.test.ts

@@ -9,6 +9,7 @@ import {
   human,
   judge,
   kept,
+  mark,
   read,
   refuse,
   restart,
@@ -389,6 +390,48 @@ describe("replay", () => {
     expect(restName(outcome)).toBe("fix#1")
   })
 
+  it("collects marks made after the pending turn's step resolved, in call order", async () => {
+    const wf = async () => {
+      mark("before", "no-turn-yet")
+      await human("idle")
+      mark("risk-tier", "high")
+      mark("production-signal", "a")
+      mark("production-signal", "b")
+      await agent("next", "go")
+    }
+    const h = new History()
+    const outcome = await replayOf(wf, h, { pending: { "TODO.md": "go" } })
+    expect(outcome.kind === "rest" && outcome.marks).toEqual([
+      { name: "risk-tier", value: "high" },
+      { name: "production-signal", value: "a" },
+      { name: "production-signal", value: "b" },
+    ])
+  })
+
+  it("ignores marks made while replaying history, and has none without a pending turn", async () => {
+    const wf = async () => {
+      await human("idle")
+      mark("risk-tier", "high")
+      await agent("next", "go")
+      mark("late", "x")
+      await agent("last", "go")
+    }
+    const h = new History().land("human", "idle", 1, "next", { "TODO.md": "go" })
+    const resting = await replayOf(wf, h)
+    expect(resting.kind === "rest" && resting.marks).toEqual([])
+    const landing = await replayOf(wf, h, { pending: { "a.txt": "a" } })
+    expect(landing.kind === "rest" && landing.marks).toEqual([{ name: "late", value: "x" }])
+  })
+
+  it("carries marks on an ended outcome", async () => {
+    const wf = async () => {
+      await human("idle")
+      mark("done", "yes")
+    }
+    const outcome = await replayOf(wf, new History(), { pending: { "TODO.md": "go" } })
+    expect(outcome.kind === "ended" && outcome.marks).toEqual([{ name: "done", value: "yes" }])
+  })
+
   it("reads helpers against the replay position, not the working tree", async () => {
     const wf = async () => {
       await human("write")

package/src/replay/Replay.ts

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

package/src/replay/Trailers.test.ts

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

package/src/replay/Trailers.ts

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

package/src/replay/judgeDiffShape.test.ts

@@ -50,6 +50,49 @@ const naive = [
 ]
 
 describe("judgeDiffShape", () => {
+  describe("exempt", () => {
+    const changes = [
+      change("src/foo*bar.ts", "added", undefined, "new"),
+      change("src/foobar.ts", "modified", "a", "b"),
+    ]
+
+    it("never lets an exempt path glob over a modified sibling", async () => {
+      install({ shape: { answer: "land", p: 0.9 } })
+      const result = await judgeDiffShape("shape", {
+        changes,
+        allow: [],
+        exempt: ["src/foo*bar.ts"],
+      })
+      expect(result.strays).toEqual(["src/foobar.ts"])
+    })
+
+    it("lists exempt paths as in-allowlist evidence and keeps allow to the globs", async () => {
+      const requests = install({ shape: { answer: "land", p: 0.9 } })
+      await judgeDiffShape("shape", { changes, allow: ["docs/**"], exempt: ["src/foo*bar.ts"] })
+      const request = requests[0]
+      if (request?.kind !== "judge") throw new Error("expected a judge step")
+      expect(request.evidence.allow).toBe(JSON.stringify(["docs/**"], null, 2))
+      expect(request.evidence.inAllowlist).toBe(JSON.stringify(["src/foo*bar.ts"], null, 2))
+    })
+
+    it("lands with no judge step when every stray is exempt", async () => {
+      const requests = install("none")
+      const result = await judgeDiffShape("shape", {
+        changes: [changes[0]!],
+        allow: [],
+        exempt: ["src/foo*bar.ts"],
+      })
+      expect(result.choice).toBe("land")
+      expect(requests).toEqual([])
+    })
+
+    it("changes nothing when omitted", async () => {
+      install({ shape: { answer: "land", p: 0.9 } })
+      const result = await judgeDiffShape("shape", { changes, allow: [] })
+      expect(result.strays).toEqual(["src/foo*bar.ts", "src/foobar.ts"])
+    })
+  })
+
   it("answers land with no judge step when nothing strays", async () => {
     const requests = install("none")
     const result = await judgeDiffShape("shape", {

package/src/step/planStart.ts

@@ -4,7 +4,8 @@ import {
   ConfigDiscovery,
   ConfigService,
   multilineSetting,
-  resolveVars,
+  resolveStartVars,
+  StartFlags,
   type ConfigFingerprint,
   type ResolvedWorkflow,
 } from "../workflow/index.js"
@@ -109,7 +110,7 @@ export const planStart = (
     if (overrideRefusal !== undefined) return overrideRefusal
 
     const baseOf = workflow.def.base
-    const vars = resolveVars(workflow.vars, varOverrides, (yield* Host).env)
+    const vars = resolveStartVars(workflow.vars, yield* StartFlags, varOverrides, (yield* Host).env)
     const multiline = multilineSetting(vars)
     if (multiline !== undefined) {
       return refusal(

package/src/testkit/TestRepo.ts

@@ -70,6 +70,8 @@ export interface TestRepo {
   drive(actors?: Actors, options?: DriveOptions): Promise<BeatDocument>
   /** Oldest first. */
   subjects(): readonly string[]
+  /** Every commit's full message, subject and trailers, oldest first. */
+  messages(): readonly string[]
 }
 
 const REGISTRY = Symbol.for("@pmelab/gtd/testkit:modules")
@@ -272,6 +274,7 @@ export const testRepo = (options: TestRepoOptions): TestRepo => {
       throw new Error(`the process did not rest within ${maxBeats} beats`)
     },
     subjects: () => repo.commitHistory().map(({ message }) => message.split("\n")[0] ?? ""),
+    messages: () => repo.commitHistory().map(({ message }) => message),
   }
   return self
 }

package/src/testkit/steps.ts

@@ -36,6 +36,12 @@ export class TestkitWorld extends QuickPickleWorld {
     this.gtdConfig = config
   }
 
+  extendConfig(tail: string): void {
+    this.assertNotCreated("a gtd config")
+    if (this.gtdConfig === undefined) throw new Error("no gtd config to extend")
+    this.gtdConfig += `\n${tail}`
+  }
+
   setEnv(name: string, value: string): void {
     this.assertNotCreated(`the environment variable ${name}`)
     this.env[name] = value
@@ -79,6 +85,10 @@ Given("a gtd config with:", (world: TestkitWorld, source: string) => {
   world.configure(withNewline(source))
 })
 
+Given("the gtd config ends with:", (world: TestkitWorld, source: string) => {
+  world.extendConfig(withNewline(source))
+})
+
 Given(
   "an environment variable {string} set to {string}",
   (world: TestkitWorld, name: string, value: string) => {
@@ -180,6 +190,14 @@ Then("the resting step's content contains {string}", async (world: TestkitWorld,
   assert.ok(content.includes(text), content)
 })
 
+Then(
+  "the resting step's content does not contain {string}",
+  async (world: TestkitWorld, text: string) => {
+    const { content } = await world.repo().next()
+    assert.ok(!content.includes(text), content)
+  },
+)
+
 Then("the last commit subject is {string}", (world: TestkitWorld, subject: string) => {
   assert.strictEqual(world.repo().subjects().at(-1), subject)
 })

package/src/workflow/index.ts

@@ -13,7 +13,14 @@ export {
   walkUp,
 } from "./discovery.js"
 export { formatDiagnostic } from "./Diagnostic.js"
-export { resolveVars, multilineSetting, isSettingName, SETTING_NAME_RULE } from "./vars.js"
+export {
+  resolveVars,
+  resolveStartVars,
+  StartFlags,
+  multilineSetting,
+  isSettingName,
+  SETTING_NAME_RULE,
+} from "./vars.js"
 export { resolveScopeAccess, resolveScopeSkills } from "./skills.js"
 export { seededValidateCommand, isSeededValidateCommand } from "./SteeringFormats.js"
 export {

package/src/workflow/vars.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest"
-import { resolveVars } from "./vars.js"
+import { resolveStartVars, resolveVars } from "./vars.js"
 
 describe("resolveVars — GTD_FLAG_* belongs to feature flags", () => {
   it.each(["flag_x", "FLAG_X", "Flag_x"])("%s keeps its default with GTD_FLAG_X set", (name) => {
@@ -14,3 +14,25 @@ describe("resolveVars — GTD_FLAG_* belongs to feature flags", () => {
     expect(resolveVars({ [name]: "off" }, {}, { [key]: "on" })).toEqual({ [name]: "on" })
   })
 })
+
+describe("resolveStartVars", () => {
+  it("a declared flag_x takes the StartFlags value", () => {
+    expect(resolveStartVars({ flag_x: "0" }, { flag_x: "1" }, {}, {})).toEqual({ flag_x: "1" })
+  })
+
+  it("never introduces an undeclared flag", () => {
+    expect(resolveStartVars({ a: "1" }, { flag_x: "1" }, {}, {})).toEqual({ a: "1" })
+  })
+
+  it("--var flag_x beats the flag", () => {
+    expect(resolveStartVars({ flag_x: "0" }, { flag_x: "1" }, { flag_x: "0" }, {})).toEqual({
+      flag_x: "0",
+    })
+  })
+
+  it("GTD_FLAG_X never overrides, while GTD_<NAME> still does for other names", () => {
+    expect(
+      resolveStartVars({ flag_x: "0", a: "1" }, {}, {}, { GTD_FLAG_X: "1", GTD_A: "2" }),
+    ).toEqual({ flag_x: "0", a: "2" })
+  })
+})

package/src/workflow/vars.ts

@@ -1,5 +1,12 @@
+import { Context } from "effect"
+
 const PREFIX = "GTD_"
 
+/** The live release flags as `flag_<name>` settings, provided by the CLI; absent means no flags. */
+export class StartFlags extends Context.Reference<StartFlags>()("StartFlags", {
+  defaultValue: (): Readonly<Record<string, string>> => ({}),
+}) {}
+
 /**
  * One kind of setting, later wins: the workflow's own defaults, `--var`
  * overrides (process settings only; environment settings pass `{}`), then
@@ -22,6 +29,23 @@ export const resolveVars = (
   return merged
 }
 
+/**
+ * `resolveVars` for a process being STARTED: `flags` land between the workflow
+ * defaults and `--var`, for already-declared names only. A running process never
+ * calls this — it replays its pinned record.
+ */
+export const resolveStartVars = (
+  workflowVars: Readonly<Record<string, string>>,
+  flags: Readonly<Record<string, string>>,
+  entryVars: Readonly<Record<string, string>>,
+  env: Readonly<Record<string, string | undefined>>,
+): Record<string, string> => {
+  const declared = Object.fromEntries(
+    Object.entries(flags).filter(([name]) => Object.hasOwn(workflowVars, name)),
+  )
+  return resolveVars({ ...workflowVars, ...declared }, entryVars, env)
+}
+
 /** The first process setting whose value spans lines — a `Gtd-Var:` trailer cannot carry it. */
 export const multilineSetting = (vars: Readonly<Record<string, string>>): string | undefined =>
   Object.keys(vars)

package/src/workflows/feature/feature.ts

@@ -7,6 +7,7 @@ import {
   revertScript,
   run,
   start,
+  vars,
 } from "../../flows/index.js"
 import { gate } from "../shared/health.js"
 import { shipped } from "../shared/options.js"
@@ -16,6 +17,8 @@ import * as t from "../shared/text.js"
 import { packages } from "./packages.js"
 import { architecture, design } from "./planning.js"
 import { buildTail, type ReviewOutcome } from "./review.js"
+import { seamBuild } from "./seam.js"
+import { recordRisk, riskTierOn } from "./tier.js"
 
 // The ordinary start. Any change to the tree starts a process: `idle` →
 // `unwind` reverts the sketch (its intent survives in history) → a
@@ -54,8 +57,14 @@ export const planAndBuild = async (firstBase: string): Promise<void> => {
   let base = firstBase
   for (;;) {
     await design(base)
-    await architecture()
-    await packages()
+    const tier = riskTierOn() ? recordRisk() : undefined
+    // GTD_FLAG_NAIVE_PASS: the record is pinned at the process start, so a mid-process flip never moves a process.
+    if (vars.flag_naive_pass === "1") {
+      await seamBuild(tier)
+    } else {
+      await architecture()
+      await packages()
+    }
     const outcome = await buildTail(false, base, true)
     if (outcome.verdict === "signoff") return
     await reUnwind(outcome)

package/src/workflows/feature/index.ts

@@ -4,6 +4,7 @@ export * from "./steps.js"
 export * from "./planning.js"
 export * from "./packages.js"
 export * from "./refactor.js"
+export * from "./seam.js"
 export { buildTail, type ReviewOutcome } from "./review.js"
 export * from "./feature.js"
 export * from "../shared/reserved.js"