@pmelab/gtd 27.4.0 → 27.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "27.4.0",
+  "version": "27.6.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {

package/src/cli/Cli.test.ts

@@ -25,7 +25,7 @@ import {
 import { EXIT_CODES, EXIT_RUNTIME_ERROR, EXIT_USAGE_ERROR } from "../wire/index.js"
 import { Host } from "../platform/index.js"
 import { type CommandRequirements } from "./Cli.js"
-import { InMemRepo, testLayers } from "../testkit/index.js"
+import { InMemRepo, makeCapturingCliIo, testLayers } from "../testkit/index.js"
 import { CONFIG_SCAFFOLD } from "../install/index.js"
 
 const FLAG_NAMES = [
@@ -1241,6 +1241,54 @@ describe("runCli — a garbled GTD_FLAG_* value", () => {
   })
 })
 
+describe("runCli — StartFlags", () => {
+  const CONFIG = `import { agent, human } from "@pmelab/gtd/flows"
+
+export default async () => {
+  await human("idle")
+}
+
+export const side = async () => {
+  await agent("working", "w")
+}
+
+export const defaults = { flag_naive_pass: "0" }
+`
+  const start = async (
+    flags?: CliIo["flags"],
+    env: Record<string, string> = {},
+  ): Promise<string> => {
+    const repo = new InMemRepo()
+    repo.writeFile("gtd.config.ts", CONFIG)
+    repo.seedCommit("chore: add workflow")
+    const { io, result } = makeCapturingCliIo(repo, env)
+    await Effect.runPromise(
+      runCli(["node", "gtd.js", "--workflow", "side"], { ...io, ...(flags ? { flags } : {}) }),
+    )
+    return result().stdout
+  }
+
+  it("pins flag_naive_pass=1 with the flag on", async () => {
+    expect(await start(undefined, { GTD_FLAG_NAIVE_PASS: "1" })).toContain("flag_naive_pass=1")
+  })
+
+  it("honours defaultOn with GTD_FLAG_* unset", async () => {
+    const out = await start(
+      [
+        {
+          name: "naive_pass",
+          owner: "pmelab",
+          expiry: "2099-01-01",
+          kind: "release",
+          defaultOn: true,
+        },
+      ],
+      { GTD_FLAG_NAIVE_PASS: "" },
+    )
+    expect(out).toContain("flag_naive_pass=1")
+  })
+})
+
 describe("runCli — exit codes", () => {
   it("output plan: exit is never called (success) — --help and --version still exit 0", async () => {
     const { io, captured } = capturingIo(throwingLayers)

package/src/cli/Cli.ts

@@ -10,13 +10,19 @@ import {
   Workspace,
   CommandRunner,
 } from "../platform/index.js"
-import { resolveFlags, type FlagDeclaration } from "../flags/index.js"
+import {
+  flagSettings,
+  flagSettingValue,
+  resolveFlags,
+  type FlagDeclaration,
+} from "../flags/index.js"
 import { GTD_VERSION } from "../install/index.js"
 import {
   ConfigDiscovery,
   ConfigService,
   isSettingName,
   SETTING_NAME_RULE,
+  StartFlags,
 } from "../workflow/index.js"
 // The shared command types live in `Program.ts`, which imports nothing from
 // here, so this dependency stays one-directional.
@@ -282,6 +288,14 @@ const FLAGS: readonly FlagRow[] = [
           return Either.left(`gtd: --var ${name} specified more than once`)
         }
         seen.add(name)
+        if (name.startsWith("flag_")) {
+          const pinned = flagSettingValue(value)
+          if (pinned === undefined) {
+            return Either.left(`gtd: --var ${name} must be 1, 0, true or false`)
+          }
+          vars[name] = pinned
+          continue
+        }
         vars[name] = value
       }
       return Either.right(vars)
@@ -1451,12 +1465,15 @@ export const runCli = (argv: readonly string[], io: CliIo): Effect.Effect<void,
   const out = bufferedArtifactOut(io)
   return Effect.flatMap(Host, ({ env }) =>
     Effect.try({
-      // Validate only: the result is discarded so a garbled value fails before any command runs.
       try: () => resolveFlags(env, io.flags),
       catch: (e) => new GtdError((e as Error).message),
     }),
   ).pipe(
-    Effect.flatMap(() => runCommand(plan.command, plan.json, out)),
+    Effect.flatMap((flags) =>
+      runCommand(plan.command, plan.json, out).pipe(
+        Effect.provideService(StartFlags, flagSettings(flags)),
+      ),
+    ),
     // `flush()` fires here, on success, BEFORE `io.exit` — the one point
     // where the whole buffered artifact is known-complete and safe to hand
     // to stdout (a failure discards the buffer instead — see

package/src/edge/Edge.test.ts

@@ -21,8 +21,9 @@ import {
 import { GTD_VERSION } from "../install/index.js"
 import { keptRef, processHistoryRef } from "../platform/index.js"
 import { GitService, Workspace, type GitOperations, type WorkspaceOps } from "../platform/index.js"
+import type { Mark } from "../flows/index.js"
 import { formatCommitMessage, type CommitSpec } from "../replay/index.js"
-import { contentHash } from "../workflow/index.js"
+import { contentHash, StartFlags } from "../workflow/index.js"
 import {
   fakeGitOperations,
   InMemRepo,
@@ -537,6 +538,64 @@ describe("summaryRun", () => {
   })
 })
 
+describe("process marks", () => {
+  const SUMMARISED = `${LINEAR}
+export const summary = (it) => it.marks.map((m) => m.name + "=" + m.value).join("|")
+`
+  const opening = (marks: readonly Mark[]): CommitSpec => ({
+    actor: "human",
+    from: "idle",
+    to: "building",
+    step: { name: "idle", occurrence: 1 },
+    marks,
+  })
+
+  it("buildRun collects marks from the process's commits only, oldest first", async () => {
+    const repo = repoWith(SUMMARISED)
+    commit(
+      repo,
+      {
+        actor: "agent",
+        from: "checking",
+        to: "idle",
+        marks: [{ name: "risk-tier", value: "high" }],
+      },
+      { "old.txt": "o\n" },
+    )
+    commit(
+      repo,
+      opening([
+        { name: "production-signal", value: "one" },
+        { name: "production-signal", value: "two" },
+      ]),
+      { "a.txt": "a\n" },
+    )
+    commit(
+      repo,
+      {
+        actor: "agent",
+        from: "building",
+        to: "checking",
+        step: { name: "building", occurrence: 1 },
+        marks: [{ name: "production-signal", value: "three" }],
+      },
+      { "b.txt": "b\n" },
+    )
+    const run = await provide(currentRun, repo)
+    expect(run.marks).toEqual([
+      { name: "production-signal", value: "one" },
+      { name: "production-signal", value: "two" },
+      { name: "production-signal", value: "three" },
+    ])
+  })
+
+  it("is empty for a process whose commits carry no marks", async () => {
+    const repo = repoWith(SUMMARISED)
+    await land(repo, { "a.txt": "a\n" })
+    expect((await provide(currentRun, repo)).marks).toEqual([])
+  })
+})
+
 describe("restAt", () => {
   it("restAt(ref) resolves where the process rested at that commit", async () => {
     const repo = repoWith(LINEAR)
@@ -781,6 +840,50 @@ export const defaults = { deployTarget: "npm test", reviewer: "nobody" }
   })
 })
 
+describe("StartFlags", () => {
+  const FLAGGED = `import { agent, human } from "@pmelab/gtd/flows"
+
+export default async () => {
+  await human("idle")
+}
+
+export const side = async () => {
+  await agent("working", "w")
+}
+
+export const defaults = { flag_naive_pass: "0", other: "x" }
+`
+  const withFlags = <A>(
+    eff: Effect.Effect<A, Error, RestRequirements>,
+    repo: InMemRepo,
+    flags: Record<string, string>,
+  ): Promise<A> =>
+    Effect.runPromise(
+      eff.pipe(Effect.provideService(StartFlags, flags), Effect.provide(testLayers(repo, {}))),
+    )
+
+  it("a starting process takes the declared flag from StartFlags, never an undeclared one", async () => {
+    const rest = await withFlags(currentRest, repoWith(FLAGGED), {
+      flag_naive_pass: "1",
+      flag_other: "1",
+    })
+    expect(rest.vars).toEqual({ flag_naive_pass: "1", other: "x" })
+  })
+
+  it("a running process missing the pin resolves the declared default, never the live flag", async () => {
+    const repo = repoWith(FLAGGED.replace('flag_naive_pass: "0", ', ""))
+    await enter(repo, "side")
+    // a process started before the flag existed: its opening commit lacks the pin
+    repo.writeFile("gtd.config.ts", FLAGGED)
+    const rest = await withFlags(currentRest, repo, { flag_naive_pass: "1" })
+    expect(rest.vars.flag_naive_pass).toBe("0")
+  })
+
+  it("with no StartFlags provided, resolves the declared default", async () => {
+    expect((await provide(currentRest, repoWith(FLAGGED))).vars.flag_naive_pass).toBe("0")
+  })
+})
+
 describe("environment settings", () => {
   const ENVV = `import { agent, human } from "@pmelab/gtd/flows"
 
@@ -1529,3 +1632,55 @@ export default async () => {
     expect((await provide(currentRest, repo)).state).toBe("after")
   })
 })
+
+describe("marks on a landing", () => {
+  const MARKING = `import { agent, human, mark } from "@pmelab/gtd/flows"
+
+export default async () => {
+  await human("idle", { message: "idle-message" })
+  mark("risk-tier", "high")
+  mark("production-signal", "error rate")
+  await agent("building", "build-prompt")
+  await agent("checking", "check-prompt")
+}
+`
+
+  const landingOf = async (repo: InMemRepo) => {
+    const rest = await provide(currentRest, repo)
+    const snapshot = await provide(snapshotFromRest(rest), repo)
+    const landing = snapshot.landing
+    if (landing.kind !== "commit") throw new Error(`expected commit, got ${landing.kind}`)
+    return landing
+  }
+
+  it("writes the outcome's marks, in order, into the landing's commit spec", async () => {
+    const repo = repoWith(MARKING)
+    repo.writeFile("TODO.md", "go\n")
+    const landing = await landingOf(repo)
+    expect(landing.spec.marks).toEqual([
+      { name: "risk-tier", value: "high" },
+      { name: "production-signal", value: "error rate" },
+    ])
+  })
+
+  it("writes the marks of a flow that ends right after marking", async () => {
+    const repo = repoWith(`import { human, mark } from "@pmelab/gtd/flows"
+
+export default async () => {
+  await human("idle", { message: "idle-message" })
+  mark("done", "yes")
+}
+`)
+    repo.writeFile("TODO.md", "go\n")
+    const landing = await landingOf(repo)
+    expect(landing.spec.marks).toEqual([{ name: "done", value: "yes" }])
+  })
+
+  it("leaves marks off a landing the flow marked nothing on", async () => {
+    const repo = repoWith(MARKING)
+    await land(repo, { "TODO.md": "go\n" })
+    repo.writeFile("a.txt", "a\n")
+    const landing = await landingOf(repo)
+    expect(landing.spec.marks).toBeUndefined()
+  })
+})

package/src/edge/Edge.ts

@@ -16,6 +16,8 @@ import {
   contentHash,
   multilineSetting,
   resolveVars,
+  resolveStartVars,
+  StartFlags,
   resolveScopeAccess,
   resolveScopeSkills,
   type ConfigFingerprint,
@@ -42,7 +44,7 @@ import {
   type ReplayOutcome,
   type TreeView,
 } from "../replay/index.js"
-import type { ScopeAccess } from "../flows/index.js"
+import type { Mark, ScopeAccess } from "../flows/index.js"
 import { steeringFormatFor } from "../steering/index.js"
 import {
   judgeJson,
@@ -151,6 +153,8 @@ export interface ProcessRun {
   readonly trace: readonly TraceEntry[]
   readonly costEntries: readonly CostEntry[]
   readonly judgeVerdicts: readonly JudgeVerdictEntry[]
+  /** Every process commit's `Gtd-Mark`s, oldest first. */
+  readonly marks: readonly Mark[]
   /** Oldest first. */
   readonly approvals: readonly ApprovalEntry[]
   /** The process settings recorded in the process's first commit (empty for a process started before pinning existed). */
@@ -274,6 +278,7 @@ const buildRun = (
     trace: processCommits.map((c, i) => traceEntryOf(c.hash, parsed[i]!)),
     costEntries: parsed.flatMap(costEntriesOf),
     judgeVerdicts: parsed.flatMap((m) => m.judge),
+    marks: parsed.flatMap((m) => m.marks),
     approvals: processCommits.flatMap((c, i) => approvalEntryOf(c.hash, parsed[i]!)),
     pinnedVars: { ...first?.vars },
     pinnedConfig: pinnedConfigOf(history.slice(Math.max(location.baseIndex, 0))),
@@ -562,9 +567,11 @@ const settingsFor = (
   pinnedVars: Readonly<Record<string, string>>,
   hostEnv: Readonly<Record<string, string | undefined>>,
   startOverrides: Readonly<Record<string, string>> = {},
+  /** The live flags a STARTING process pins; a running one passes `{}` and replays its pins. */
+  startFlags: Readonly<Record<string, string>>,
 ): { readonly vars: Record<string, string>; readonly env: Record<string, string> } => ({
   vars: {
-    ...resolveVars(workflow.vars, startOverrides, hostEnv),
+    ...resolveStartVars(workflow.vars, startFlags, startOverrides, hostEnv),
     ...pinnedVars,
   },
   env: resolveVars(workflow.env, {}, hostEnv),
@@ -912,7 +919,14 @@ const setupFor = (
   Effect.gen(function* () {
     const resolved = yield* workflowOf(config, run)
     const def = resolved.def
-    const { vars, env } = settingsFor(resolved, run.pinnedVars, host.env, startOverrides)
+    const startFlags = run.trace.length === 0 ? yield* StartFlags : {}
+    const { vars, env } = settingsFor(
+      resolved,
+      run.pinnedVars,
+      host.env,
+      startOverrides,
+      startFlags,
+    )
     const skills = yield* resolveScopeSkills(def, vars)
     const access = yield* resolveScopeAccess(def, skills, vars)
     const budget = yield* Effect.try({
@@ -1067,7 +1081,7 @@ export const startRefusal = (
 > =>
   Effect.gen(function* () {
     const host = yield* Host
-    const { vars, env } = settingsFor(resolved, {}, host.env, startVars)
+    const { vars, env } = settingsFor(resolved, {}, host.env, startVars, yield* StartFlags)
     const skills = yield* resolveScopeSkills(resolved.def, vars)
     const access = yield* resolveScopeAccess(resolved.def, skills, vars)
     const workspace = rest.setup.workspace
@@ -1256,6 +1270,7 @@ const landingTo = (
   to: StateName,
   branch: Option.Option<string>,
   approver: Option.Option<AuthorIdent>,
+  marks: readonly Mark[],
 ): Landing => {
   if (isSettledNoop(rest, to)) return { kind: "noop", settled: true }
   // The landing that leaves the flow's first step starts the process: it
@@ -1276,8 +1291,9 @@ const landingTo = (
       from: rest.state,
       to,
       step: rest.step.id,
+      ...(marks.length > 0 && { marks }),
       ...approvedTrailer(rest, approver),
-      ...(starts ? { vars: rest.vars, config: rest.config } : {}),
+      ...startTrailers(rest, starts),
       ...(finishes ? closingTrailers(branch) : {}),
     },
     ...(finishes ? { keepHistory: processHistoryRef(rest.run.startHash) } : {}),
@@ -1285,6 +1301,12 @@ const landingTo = (
   }
 }
 
+const startTrailers = (rest: Rest, starts: boolean) =>
+  starts ? { vars: rest.vars, config: rest.config } : {}
+
+const outcomeMarks = (outcome: ReplayOutcome): readonly Mark[] =>
+  outcome.kind === "rest" || outcome.kind === "ended" ? outcome.marks : []
+
 /**
  * What landing the pending turn at `rest` does — a pure decision from a
  * replay with the working tree as the pending turn. The target step is
@@ -1317,7 +1339,7 @@ const decideLanding = (
     )
     const to = yield* landingTarget(outcome, rest)
     if (typeof to !== "string") return to
-    return landingTo(rest, to, branch, approver)
+    return landingTo(rest, to, branch, approver, outcomeMarks(outcome))
   })
 
 /** Where landing the pending turn would leave the process, or `undefined` when it would land nothing. */
@@ -1369,7 +1391,8 @@ export const summaryFor = (
         .map((entry) => ({ hash: entry.hash, state: entry.state })),
       processCost: run.costEntries.reduce((sum, entry) => sum + entry.cost, 0),
       processCostByModel: costByModel(run.costEntries),
-      ...settingsFor(resolved, run.pinnedVars, host.env),
+      marks: run.marks,
+      ...settingsFor(resolved, run.pinnedVars, host.env, {}, {}),
     })
   })
 

package/src/flags/index.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest"
-import { FLAGS, resolveFlags, type FlagDeclaration, type Flags } from "./index.js"
+import { FLAGS, flagSettings, resolveFlags, type FlagDeclaration, type Flags } from "./index.js"
 
 const registry = [
   { name: "alpha", owner: "pmelab", expiry: "2020-01-01", kind: "release" },
@@ -92,4 +92,30 @@ describe("FLAGS", () => {
     })
     expect(new Set(names).size).toBe(names.length)
   })
+
+  it("leaves naive_pass off by default", () => {
+    expect(resolveFlags({}).naive_pass).toBe(false)
+  })
+})
+
+describe("flagSettings", () => {
+  it('maps every flag to "1" or "0" under flag_<name>', () => {
+    expect(flagSettings({ alpha: true, new_review: false })).toEqual({
+      flag_alpha: "1",
+      flag_new_review: "0",
+    })
+  })
+})
+
+describe("risk_tier", () => {
+  it("is a release flag, off by default, resolved from GTD_FLAG_RISK_TIER", () => {
+    expect(FLAGS.find((f) => f.name === "risk_tier")).toMatchObject({ kind: "release" })
+    expect(resolveFlags({}).risk_tier).toBe(false)
+    expect(resolveFlags({ GTD_FLAG_RISK_TIER: "1" }).risk_tier).toBe(true)
+  })
+
+  it("is pinned as flag_risk_tier", () => {
+    expect(flagSettings(resolveFlags({ GTD_FLAG_RISK_TIER: "1" })).flag_risk_tier).toBe("1")
+    expect(flagSettings(resolveFlags({})).flag_risk_tier).toBe("0")
+  })
 })

package/src/flags/index.ts

@@ -1,5 +1,5 @@
-// A flag may change how a step runs, never which step comes next: flags are not recorded in
-// history, so replay must not read them. No lint rule enforces this.
+// Flags are not recorded in history, so replay must not read the live value: flow code may
+// branch on a flag only through its pinned `flag_<name>` setting. No lint rule enforces this.
 
 export type FlagKind = "release" | "ops" | "experiment"
 
@@ -13,7 +13,10 @@ export interface FlagDeclaration {
   readonly defaultOn?: boolean
 }
 
-export const FLAGS = [] as const satisfies readonly FlagDeclaration[]
+export const FLAGS = [
+  { name: "naive_pass", owner: "pmelab", expiry: "2027-01-15", kind: "release" },
+  { name: "risk_tier", owner: "pmelab", expiry: "2027-01-15", kind: "release" },
+] as const satisfies readonly FlagDeclaration[]
 
 /** A misspelt name is a compile error. */
 export type Flags<R extends readonly FlagDeclaration[] = typeof FLAGS> = {
@@ -22,6 +25,12 @@ export type Flags<R extends readonly FlagDeclaration[] = typeof FLAGS> = {
 
 const BOOL: Record<string, boolean> = { "0": false, false: false, "1": true, true: true }
 
+/** A `flag_<name>` setting's value as the pinned `"1"`/`"0"`, or undefined when garbled. */
+export const flagSettingValue = (raw: string): "0" | "1" | undefined => {
+  const key = raw.toLowerCase()
+  return Object.hasOwn(BOOL, key) ? (BOOL[key] ? "1" : "0") : undefined
+}
+
 export const resolveFlags = <const R extends readonly FlagDeclaration[] = typeof FLAGS>(
   env: Readonly<Record<string, string | undefined>>,
   registry: R = FLAGS as unknown as R,
@@ -41,3 +50,6 @@ export const resolveFlags = <const R extends readonly FlagDeclaration[] = typeof
   }
   return out as Flags<R>
 }
+
+export const flagSettings = (flags: Readonly<Record<string, boolean>>): Record<string, string> =>
+  Object.fromEntries(Object.entries(flags).map(([name, on]) => [`flag_${name}`, on ? "1" : "0"]))

package/src/flows/helpers.ts

@@ -152,12 +152,14 @@ export interface DiffShapeOptions {
   readonly changes: readonly Change[]
   /** Globs in the `changes(pattern)` / `gtd strays` dialect. */
   readonly allow: readonly string[]
+  /** Exact paths never strays; compared by equality, so a `*` in one covers nothing else. */
+  readonly exempt?: readonly string[] | undefined
   readonly minP?: number | undefined
 }
 
 export interface DiffShapeResult {
   readonly choice: DiffShape
-  /** Sorted, equal to `gtd strays` for the same range and globs. */
+  /** Sorted, equal to `gtd strays` for the same range and globs, minus `exempt`. */
   readonly strays: readonly string[]
   /** Strays with a side that could not be read (sorted); `refactor-first` skipped the judge. */
   readonly unreadable: readonly string[]
@@ -198,7 +200,9 @@ export const judgeDiffShape = async (
   options: DiffShapeOptions,
 ): Promise<DiffShapeResult> => {
   const { changes: all, allow } = options
-  const isStray = (c: Change): boolean => !allow.some((pattern) => matches(c.path, pattern))
+  const exempt = options.exempt ?? []
+  const isStray = (c: Change): boolean =>
+    !exempt.includes(c.path) && !allow.some((pattern) => matches(c.path, pattern))
   const strayChanges: Change[] = all
     .filter(isStray)
     .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
@@ -252,7 +256,7 @@ export const judgeDiffShape = async (
   return { choice, strays, unreadable: [], judgment }
 }
 
-const displayPath = (path: string): string =>
+export const displayPath = (path: string): string =>
   // eslint-disable-next-line no-control-regex -- the control range IS the point
   /[\x00-\x1f\x7f-\x9f]/.test(path) ? JSON.stringify(path) : path
 

package/src/flows/runtime.test.ts

@@ -5,6 +5,7 @@ import {
   head,
   installContext,
   kept,
+  mark,
   protocolMismatch,
   type FlowContext,
 } from "./runtime.js"
@@ -54,6 +55,47 @@ describe("the flows protocol handshake", () => {
   })
 })
 
+describe("mark()", () => {
+  const withMark = () => {
+    const calls: [string, string][] = []
+    installContext({ mark: (n: string, v: string) => calls.push([n, v]) } as unknown as FlowContext)
+    return calls
+  }
+
+  it("forwards name and value to the context", () => {
+    const calls = withMark()
+    mark("risk-tier", "high")
+    mark("production-signal", "error rate")
+    expect(calls).toEqual([
+      ["risk-tier", "high"],
+      ["production-signal", "error rate"],
+    ])
+  })
+
+  it("throws the upgrade message on a context without mark, protocol still 1", () => {
+    installContext(context)
+    expect(() => mark("a", "b")).toThrow(
+      "gtd: mark() needs a newer gtd — upgrade the gtd that runs it",
+    )
+    expect(FLOWS_PROTOCOL).toBe(1)
+  })
+
+  it.each(["", "Risk", "1a", "a_b", "-a", "risk-tier\n"])("rejects the name %j", (name) => {
+    const calls = withMark()
+    expect(() => mark(name, "v")).toThrow(/mark\(\)/)
+    expect(calls).toEqual([])
+  })
+
+  it.each(["", " ", " x ", "x\t", "a\nGtd-Approved: {}", "a\rb", "a\u001bb", "a\u2028b", "high\n"])(
+    "rejects the value %j",
+    (value) => {
+      const calls = withMark()
+      expect(() => mark("risk-tier", value)).toThrow(/one line/)
+      expect(calls).toEqual([])
+    },
+  )
+})
+
 describe("kept()", () => {
   const change = { path: "a.ts", status: "added", before: undefined, after: "a" } as const
   const withKept = (tip: unknown) =>

package/src/flows/runtime.ts

@@ -170,6 +170,8 @@ export interface FlowContext {
   readonly skillsFor: (localName: string) => readonly string[]
   /** The folded access the memory scope `localName` lands in resolves to; `file` is the step's own steering file. */
   readonly accessFor: (localName: string, file?: string) => AccessDef
+  /** Absent on an engine older than `mark`; FLOWS_PROTOCOL stays 1. */
+  readonly mark?: (name: string, value: string) => void
   /** Absent on an engine older than `kept`. */
   readonly kept?: (
     name: string,
@@ -343,6 +345,38 @@ export const kept = (name: string): KeptTip | undefined => {
   return tip === undefined ? undefined : { hash: tip.hash, changes: toChanges(tip.changes) }
 }
 
+export interface Mark {
+  readonly name: string
+  readonly value: string
+}
+
+const MARK_NAME = /^[a-z][a-z0-9-]*$/
+const MARK_VALUE =
+  // eslint-disable-next-line no-control-regex -- the control range IS the point
+  /^[^\s\x00-\x1f\x7f-\x9f\u2028\u2029]([^\x00-\x1f\x7f-\x9f\u2028\u2029]*[^\s\x00-\x1f\x7f-\x9f\u2028\u2029])?$/
+
+/**
+ * Record a fact on the landing that leaves the current rest: one
+ * `Gtd-Mark: <name>=<value>` trailer per call, in call order. Throws on an
+ * invalid name or value (a newline would inject a trailer) and on an older engine.
+ * A settled no-op landing (a clean script step landing on itself) drops its marks.
+ */
+export const mark = (name: string, value: string): void => {
+  const context = ctx()
+  if (typeof context.mark !== "function") {
+    throw new Error("gtd: mark() needs a newer gtd — upgrade the gtd that runs it")
+  }
+  if (!MARK_NAME.test(name)) {
+    throw new Error(`gtd: mark(): name ${JSON.stringify(name)} must match ${MARK_NAME}`)
+  }
+  if (!MARK_VALUE.test(value)) {
+    throw new Error(
+      `gtd: mark(${name}): value must be one line, no control characters, no surrounding whitespace`,
+    )
+  }
+  context.mark(name, value)
+}
+
 /** The commit the process stands on at this point of the flow. */
 export const head = (): string => ctx().head()
 
@@ -445,6 +479,8 @@ export interface SummaryContext {
   readonly humanCommits: readonly { readonly hash: string; readonly state: string }[]
   readonly processCost: number
   readonly processCostByModel: readonly { readonly model: string; readonly cost: number }[]
+  /** Every `Gtd-Mark` of the process's commits, oldest first. */
+  readonly marks: readonly Mark[]
   readonly vars: Readonly<Record<string, string>>
   readonly env: Readonly<Record<string, string>>
 }