@pmelab/gtd 27.3.0 → 27.5.0

package/src/wire/BeatDocument.test.ts

@@ -10,6 +10,7 @@ import {
   type StatusChange,
   DEMAND_BRIEFING,
   renderBeatPlain,
+  type ApprovalEntry,
   type ModelCost,
   type RenderedDemandSource,
   WIRE_SCHEMA,
@@ -34,6 +35,7 @@ interface DocumentInput {
   readonly next?: NextMatch | null
   readonly cost?: number
   readonly costByModel?: readonly ModelCost[]
+  readonly approvals?: readonly ApprovalEntry[]
 }
 
 /** `demandOf`'s own input, isolated so `documentFor` stays a flat two-call body — `session`/`validate` are only spread in when the caller actually passed one, since `demandOf`'s `prompt` variant forbids an explicit `undefined`. */
@@ -61,6 +63,7 @@ const statusInput = (
   next: input.next ?? null,
   cost: input.cost ?? 0,
   costByModel: input.costByModel ?? [],
+  approvals: input.approvals ?? [],
 })
 
 /** Builds one full `BeatDocument` in one call, mirroring the pre-split `beatFields` call shape so every golden below reads the same as before this package. */
@@ -87,6 +90,7 @@ describe("beatDocument / renderBeatJson", () => {
       workflow: "feature",
       changes: [],
       next: null,
+      approvals: [],
     })
   })
 
@@ -267,9 +271,29 @@ describe("beatDocument / renderBeatJson", () => {
       "judge",
       "skills",
       "access",
+      "approvals",
     ])
   })
 
+  it("emits approvals always, [] when none, at every kind", () => {
+    for (const kind of BEAT_KINDS) {
+      const parsed = JSON.parse(renderJsonLine({ kind })) as Record<string, unknown>
+      expect(parsed.approvals).toEqual([])
+    }
+  })
+
+  it("carries approvals verbatim, in the order given", () => {
+    const approvals = [
+      { step: "gate#1", name: "Ada", email: "ada@x.io", commit: "a".repeat(40) },
+      { step: "gate#2", name: "Bo", email: "bo@x.io", commit: "b".repeat(40) },
+    ]
+    const parsed = JSON.parse(renderJsonLine({ kind: "message", approvals })) as Record<
+      string,
+      unknown
+    >
+    expect(parsed.approvals).toEqual(approvals)
+  })
+
   it("emits access at kind prompt, null per side when unrestricted", () => {
     const bare = JSON.parse(renderJsonLine({ kind: "prompt" })) as Record<string, unknown>
     expect(bare.access).toEqual({ read: null, write: null })
@@ -377,6 +401,7 @@ describe("golden bytes", () => {
         workflow: "feature",
         changes: [],
         next: null,
+        approvals: [],
       }) + "\n",
     )
   })

package/src/wire/BeatDocument.ts

@@ -1,6 +1,6 @@
 import type { BeatKind, Demand, DemandSession } from "./Demand.js"
 import type { BeatStatus, NextMatch, StatusChange } from "./BeatStatus.js"
-import type { Actor, ModelCost, StateMode, StateName, StepAccess } from "./types.js"
+import type { Actor, ApprovalEntry, ModelCost, StateMode, StateName, StepAccess } from "./types.js"
 import { WIRE_SCHEMA } from "./constants.js"
 
 /** `gtd next --json`'s `next` key — `null` when landing would commit nothing. */
@@ -72,10 +72,11 @@ export interface BeatDocument {
   readonly judge: string | undefined
   readonly skills: readonly string[] | undefined
   readonly access: StepAccess | undefined
+  readonly approvals: readonly ApprovalEntry[]
 }
 
 /**
- * Flatten a `Demand` plus its `BeatStatus` into the single 24-key document
+ * Flatten a `Demand` plus its `BeatStatus` into the single 25-key document
  * `gtd next --json` emits — the ONLY place the two are joined. `cost`/
  * `costByModel` are omitted together, exactly when no cost was recorded
  * (`cost <= 0`).
@@ -108,6 +109,7 @@ export const beatDocument = (demand: Demand, status: BeatStatus): BeatDocument =
     judge: status.judge,
     skills,
     access,
+    approvals: status.approvals,
   }
 }
 

package/src/wire/BeatPlain.test.ts

@@ -28,6 +28,7 @@ const documentFor = (kind: BeatKind, content: string, rest: Partial<RenderedDema
     next: { target: "idle" },
     cost: 0,
     costByModel: [],
+    approvals: [],
   })
   return beatDocument(demand, status)
 }

package/src/wire/BeatStatus.test.ts

@@ -19,6 +19,7 @@ const baseInput = (overrides: Partial<RenderedDemandSource> = {}) => ({
   next: null,
   cost: 0,
   costByModel: [],
+  approvals: [],
 })
 
 describe("statusOf", () => {
@@ -47,6 +48,7 @@ describe("statusOf", () => {
       next: { target: "idle" },
       cost: 12,
       costByModel: [{ model: "opus", cost: 12 }],
+      approvals: [],
     })
     expect(status.workflow).toBe("feature")
     expect(status.idle).toBe(true)

package/src/wire/BeatStatus.ts

@@ -1,4 +1,11 @@
-import type { Actor, ModelCost, RenderedDemandSource, StateMode, StateName } from "./types.js"
+import type {
+  ApprovalEntry,
+  Actor,
+  ModelCost,
+  RenderedDemandSource,
+  StateMode,
+  StateName,
+} from "./types.js"
 
 /** One pending change — `gtd next --json`'s `changes` entries. */
 export interface StatusChange {
@@ -39,6 +46,7 @@ export interface BeatStatus {
   readonly cost: number
   readonly costByModel: readonly ModelCost[]
   readonly judge: string | undefined
+  readonly approvals: readonly ApprovalEntry[]
 }
 
 /**
@@ -57,8 +65,10 @@ export const statusOf = (input: {
   readonly next: NextMatch | null
   readonly cost: number
   readonly costByModel: readonly ModelCost[]
+  readonly approvals: readonly ApprovalEntry[]
 }): BeatStatus => {
-  const { rendered, idle, initial, workflow, log, changes, next, cost, costByModel } = input
+  const { rendered, idle, initial, workflow, log, changes, next, cost, costByModel, approvals } =
+    input
   return {
     idle,
     initial,
@@ -77,5 +87,6 @@ export const statusOf = (input: {
     cost,
     costByModel,
     judge: rendered.judge,
+    approvals,
   }
 }

package/src/wire/WireSchema.test.ts

@@ -86,6 +86,7 @@ const beat = (kind: BeatKind): string => {
     next: { target: "idle" },
     cost: 12,
     costByModel: [{ model: "opus", cost: 12 }],
+    approvals: [{ step: "gate#1", name: "Ada", email: "ada@x.io", commit: "a".repeat(40) }],
   })
   return renderBeatJson(beatDocument(demand, status))
 }
@@ -129,6 +130,15 @@ describe(`wire schema ${WIRE_SCHEMA}`, () => {
     })
   }
 
+  it("approvals is an additive field: present on every beat, WIRE_SCHEMA unchanged", () => {
+    expect(WIRE_SCHEMA).toBe(1)
+    for (const kind of BEAT_KINDS) {
+      expect(JSON.parse(documents[`beat-${kind}.json`]!)).toHaveProperty("approvals", [
+        { step: "gate#1", name: "Ada", email: "ada@x.io", commit: "a".repeat(40) },
+      ])
+    }
+  })
+
   describe("the shape check", () => {
     const land = JSON.parse(documents["land.json"]!) as Record<string, unknown>
     const { subject, ...rest } = land

package/src/wire/types.ts

@@ -30,6 +30,14 @@ export interface StepAccess {
   readonly write: readonly string[] | null
 }
 
+/** One approval commit of the process: `step` is the formatted `<name>#<n>`, `commit` the approving commit's hash. */
+export interface ApprovalEntry {
+  readonly step: string
+  readonly name: string
+  readonly email: string
+  readonly commit: string
+}
+
 export interface RenderedDemandSource {
   readonly state: StateName
   readonly actor: Actor

package/src/workflow/Workflow.ts

@@ -41,6 +41,7 @@ export interface StepDef {
   readonly allowEmpty?: boolean
   readonly keep?: boolean
   readonly acceptClean?: boolean
+  readonly approve?: boolean
   readonly skills?: readonly string[]
   readonly access?: StepAccess
 }

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,7 @@ 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"
 
 // The ordinary start. Any change to the tree starts a process: `idle` →
 // `unwind` reverts the sketch (its intent survives in history) → a
@@ -54,8 +56,13 @@ export const planAndBuild = async (firstBase: string): Promise<void> => {
   let base = firstBase
   for (;;) {
     await design(base)
-    await architecture()
-    await packages()
+    // 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()
+    } 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"

package/src/workflows/feature/seam-pin.feature

@@ -0,0 +1,52 @@
+@inmem
+Feature: a process keeps the path it started on when GTD_FLAG_NAIVE_PASS changes
+
+  The flag is recorded in the opening commit, so flipping it mid-process never
+  moves a process between the architecture path and the naive-pass path.
+
+  Background:
+    Given the shipped workflows, as gtd install scaffolds them
+    And an environment variable "GTD_QUALITYREVIEWS" set to ""
+    And a file "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => a + b
+      """
+    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
+    And step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+      """
+      # Requirements
+
+      ## Concerns
+
+      ### Subtract
+
+      - `subtract(a, b)` returns `a - b`.
+      """
+
+  Scenario: a process started with the flag off stays on architecture after the flag turns on
+    Given the ambient environment variable "GTD_FLAG_NAIVE_PASS" is "0"
+    When the process is driven
+    Then the process rests at "design.gate.answer"
+    Given the ambient environment variable "GTD_FLAG_NAIVE_PASS" is "1"
+    And step "design.gate.answer" changes nothing
+    When the process is driven
+    Then the process rests at "architecture.author"
+    And the commit "gtd(human): idle → unwind" has a body containing "Gtd-Var: flag_naive_pass=0"
+
+  Scenario: a process started with the flag on stays on the naive pass after the flag turns off
+    Given the ambient environment variable "GTD_FLAG_NAIVE_PASS" is "1"
+    When the process is driven
+    Then the process rests at "design.gate.answer"
+    Given the ambient environment variable "GTD_FLAG_NAIVE_PASS" is "0"
+    And step "design.gate.answer" changes nothing
+    When the process is driven
+    Then the process rests at "seam.naive"
+    And the commit "gtd(human): idle → unwind" has a body containing "Gtd-Var: flag_naive_pass=1"