@pmelab/gtd 27.5.0 → 27.6.0

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/workflows/feature/feature.ts

@@ -18,6 +18,7 @@ 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
@@ -56,9 +57,10 @@ export const planAndBuild = async (firstBase: string): Promise<void> => {
   let base = firstBase
   for (;;) {
     await design(base)
+    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()
+      await seamBuild(tier)
     } else {
       await architecture()
       await packages()

package/src/workflows/feature/risk-tier.feature

@@ -0,0 +1,301 @@
+@inmem
+Feature: the risk tier is proposed at triage and recorded behind GTD_FLAG_RISK_TIER
+
+  With GTD_FLAG_NAIVE_PASS and GTD_FLAG_RISK_TIER both on, design.triage asks
+  for a risk tier and production signals, and the design gate's exit lands them
+  as Gtd-Mark trailers: one `risk-tier=<low|high>`, one `production-signal`
+  per signal. A missing or unreadable tier is high. With the flag off, nothing
+  is asked and no commit carries a Gtd-Mark.
+
+  Background:
+    Given the shipped workflows, as gtd install scaffolds them
+    And an environment variable "GTD_QUALITYREVIEWS" set to ""
+    And an environment variable "GTD_FLAG_NAIVE_PASS" set to "1"
+
+  Rule: with GTD_FLAG_RISK_TIER on
+
+    Background:
+      Given an environment variable "GTD_FLAG_RISK_TIER" set to "1"
+      And a file "src/calc.ts" with:
+        """
+        export const add = (a: number, b: number) => a + b
+        """
+      And a file "src/calc.test.ts" with:
+        """
+        import { expect, it } from "vitest"
+        it("adds", () => expect(1 + 1).toBe(2))
+        """
+      And the working tree is committed as "feat: add calculator"
+      And a file "TODO.md" with:
+        """
+        # Add subtract
+
+        subtract(a, b) returns the difference.
+        """
+      And step "unwind" changes nothing
+      And step "start-gate.check" changes nothing
+
+    Scenario: with both flags on the triage prompt asks for the tier and the signals
+      When the process is driven
+      Then the process rests at "design.triage"
+      And the resting step's content contains "## Risk Tier"
+      And the resting step's content contains "## Production Signals"
+      And the resting step's content contains "unsure means `high`"
+
+    Scenario: a low tier marks risk-tier=low on the design-exit commit
+      Given step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        ## Risk Tier
+
+        low — trivial copy change
+        """
+      And step "design.gate.answer" changes nothing
+      When the process is driven
+      Then the process rests at "seam.naive"
+      And the last commit subject is "gtd(human): design.gate.answer → seam.naive"
+      And the last commit body contains "Gtd-Mark: risk-tier=low"
+
+    Scenario: a high tier marks the design-exit commit
+      Given step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        ## Risk Tier
+
+        high — touches payments
+        """
+      And step "design.gate.answer" changes nothing
+      When the process is driven
+      Then the process rests at "seam.naive"
+      And the last commit subject is "gtd(human): design.gate.answer → seam.naive"
+      And the last commit body contains "Gtd-Mark: risk-tier=high"
+
+    Scenario Outline: a missing section or an unknown word counts as high
+      Given step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        <tier section>
+        ## Concerns
+
+        ### Subtract
+        """
+      And step "design.gate.answer" changes nothing
+      When the process is driven
+      Then the process rests at "seam.naive"
+      And the last commit body contains "Gtd-Mark: risk-tier=high"
+
+      Examples:
+        | tier section                  |
+        |                               |
+        | ## Risk Tier\n\nmedium — hmm |
+        | ```\n## Risk Tier\n\nlow\n```\n |
+
+    Scenario Outline: signals written at triage land as marks for either tier
+      Given step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        ## Risk Tier
+
+        <tier> — reason
+
+        ## Production Signals
+
+        - error rate on /subtract stays flat
+        - p95 latency
+        """
+      And step "design.gate.answer" changes nothing
+      When the process is driven
+      Then the process rests at "seam.naive"
+      And the last commit body contains "Gtd-Mark: production-signal=error rate on /subtract stays flat"
+      And the last commit body contains "Gtd-Mark: production-signal=p95 latency"
+
+      Examples:
+        | tier |
+        | low  |
+        | high |
+
+    Scenario Outline: low and high processes produce the same commit subjects to implement.building
+      Given step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        ## Risk Tier
+
+        <tier> — reason
+        """
+      And step "design.gate.answer" changes nothing
+      And step "seam.naive" writes "src/calc.ts" with:
+        """
+        export const add = (a: number, b: number) => a + b
+        export const subtract = (a: number, b: number) => a - b
+        """
+      And judge step "seam.judge" answers:
+        """
+        [{"id":"shape","answer":"land","p":0.9}]
+        """
+      When the process is driven
+      Then the process rests at "implement.building"
+      And the commit subjects end with:
+        """
+        gtd(agent): design.triage → design.gate.answer
+        gtd(human): design.gate.answer → seam.naive
+        gtd(agent): seam.naive → seam.judge
+        gtd(judge): seam.judge → implement.building
+        """
+
+      Examples:
+        | tier |
+        | low  |
+        | high |
+
+    Scenario Outline: the implementation prompt demands a flag for high and none for low
+      Given step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        ## Risk Tier
+
+        <tier> — reason
+        """
+      And step "design.gate.answer" changes nothing
+      And step "seam.naive" writes "src/calc.ts" with:
+        """
+        export const add = (a: number, b: number) => a + b
+        export const subtract = (a: number, b: number) => a - b
+        """
+      And judge step "seam.judge" answers:
+        """
+        [{"id":"shape","answer":"land","p":0.9}]
+        """
+      When the process is driven
+      Then the process rests at "implement.building"
+      And the resting step's content contains "<demand>"
+      And the resting step's content does not contain "<absent>"
+
+      Examples:
+        | tier | demand                                                | absent                |
+        | high | Put the new behaviour behind a new release flag       | Add no release flag   |
+        | low  | Add no release flag — this change is low risk tier    | new release flag      |
+
+    Scenario: the tier comes from the requirements the final design gate lap accepted
+      Given step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        ## Risk Tier
+
+        low — trivial copy change
+        """
+      And step "seam.naive" writes "src/calc.ts" with:
+        """
+        export const add = (a: number, b: number) => a + b
+        export const subtract = (a: number, b: number) => a - b
+        """
+      And judge step "seam.judge" answers:
+        """
+        [{"id":"shape","answer":"land","p":0.9}]
+        """
+      When the process is driven
+      Then the process rests at "design.gate.answer"
+      Given a file ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        ## Risk Tier
+
+        high — touches payments
+        """
+      And step "design.triage" from now on changes nothing
+      And step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        ## Risk Tier
+
+        high — touches payments
+
+        ## Concerns
+
+        ### Subtract
+        """
+      And step "design.gate.answer" changes nothing
+      When the process is driven
+      Then the process rests at "implement.building"
+      And the resting step's content contains "Put the new behaviour behind a new release flag"
+      And the resting step's content does not contain "Add no release flag"
+
+  Rule: with GTD_FLAG_RISK_TIER off
+
+    Background:
+      Given an environment variable "GTD_FLAG_RISK_TIER" set to "0"
+      And a file "src/calc.ts" with:
+        """
+        export const add = (a: number, b: number) => a + b
+        """
+      And a file "src/calc.test.ts" with:
+        """
+        import { expect, it } from "vitest"
+        it("adds", () => expect(1 + 1).toBe(2))
+        """
+      And the working tree is committed as "feat: add calculator"
+      And a file "TODO.md" with:
+        """
+        # Add subtract
+
+        subtract(a, b) returns the difference.
+        """
+      And step "unwind" changes nothing
+      And step "start-gate.check" changes nothing
+
+    Scenario: the flag-off twin asks for no tier and marks no commit
+      Given step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        ## Risk Tier
+
+        low — trivial
+
+        ## Production Signals
+
+        - error rate stays flat
+        """
+      And step "design.gate.answer" changes nothing
+      When the process is driven
+      Then the process rests at "seam.naive"
+      And no commit body contains "Gtd-Mark"
+
+    Scenario: the flag-off twin's triage prompt has no tier section
+      When the process is driven
+      Then the process rests at "design.triage"
+      And the resting step's content does not contain "## Risk Tier"
+      And the resting step's content does not contain "## Production Signals"
+
+
+    Scenario: the flag-off twin keeps today's flag demand
+      Given step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+        """
+        # Requirements
+
+        ## Risk Tier
+
+        low — trivial
+        """
+      And step "design.gate.answer" changes nothing
+      And step "seam.naive" writes "src/calc.ts" with:
+        """
+        export const add = (a: number, b: number) => a + b
+        export const subtract = (a: number, b: number) => a - b
+        """
+      And judge step "seam.judge" answers:
+        """
+        [{"id":"shape","answer":"land","p":0.9}]
+        """
+      When the process is driven
+      Then the process rests at "implement.building"
+      And the resting step's content contains "Put the new behaviour behind a new release flag"
+      And the resting step's content does not contain "Add no release flag"

package/src/workflows/feature/seam.ts

@@ -16,6 +16,7 @@ import { coder, FEEDBACK, REQUIREMENTS } from "../shared/steps.js"
 import * as t from "../shared/text.js"
 import { defaults } from "../shared/vars.js"
 import { refactorFirst } from "./refactor.js"
+import type { RiskTier } from "./tier.js"
 
 /** Naive-pass retries after a `reject`; the next `reject` rests at `seam.steer`. */
 const NAIVE_RETRIES = 2
@@ -39,9 +40,9 @@ export const naivePass = (rejection?: t.SeamRejection): Promise<void> =>
     system: t.builderSystem(),
   })
 
-export const implement = (reference: string): Promise<void> =>
+export const implement = (reference: string, tier?: RiskTier): Promise<void> =>
   scope("implement", async () => {
-    await t.agentWithSkills("building", t.implementBuildingPrompt(reference), {
+    await t.agentWithSkills("building", t.implementBuildingPrompt(reference, tier), {
       label: "Implementing",
       model: coder(),
       system: t.builderSystem(),
@@ -94,7 +95,7 @@ const decide = (): Promise<Decision> =>
     }
   })
 
-export const seamBuild = async (): Promise<void> => {
+export const seamBuild = async (tier?: RiskTier): Promise<void> => {
   const { reference, shape } = await decide()
   if (shape !== undefined && !(await refactorFirst(shape, { reference }))) {
     // Unreadable strays were never judged, and no refactor runs: a person reads the diff.
@@ -106,5 +107,5 @@ export const seamBuild = async (): Promise<void> => {
       }),
     )
   }
-  await implement(reference)
+  await implement(reference, tier)
 }

package/src/workflows/feature/steps.ts

@@ -1,10 +1,11 @@
 import { human, run } from "../../flows/index.js"
 import * as t from "../shared/text.js"
+import { riskTierOn } from "./tier.js"
 import { ARCHITECTURE, coder, FEEDBACK, planner, REQUIREMENTS, REVIEW } from "../shared/steps.js"
 
 /** Turn the sketch since `base` into `.gtd/REQUIREMENTS.md`. */
 export const triage = (base: string): Promise<void> =>
-  t.agentWithSkills("triage", t.designTriagePrompt(base), {
+  t.agentWithSkills("triage", t.designTriagePrompt(base, riskTierOn()), {
     label: "Triaging the change",
     file: REQUIREMENTS,
     mode: "qa",
@@ -30,7 +31,7 @@ export const decompose = (): Promise<void> =>
 
 export const answerProductQuestions = (): Promise<void> =>
   human("gate.answer", {
-    message: t.designGateAnswerMessage(),
+    message: t.designGateAnswerMessage(riskTierOn()),
     label: "Awaiting your product answers",
     file: REQUIREMENTS,
     mode: "qa",