@pmelab/gtd 27.4.0 → 27.5.0

package/src/edge/Edge.test.ts

@@ -22,7 +22,7 @@ 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 { formatCommitMessage, type CommitSpec } from "../replay/index.js"
-import { contentHash } from "../workflow/index.js"
+import { contentHash, StartFlags } from "../workflow/index.js"
 import {
   fakeGitOperations,
   InMemRepo,
@@ -781,6 +781,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"
 

package/src/edge/Edge.ts

@@ -16,6 +16,8 @@ import {
   contentHash,
   multilineSetting,
   resolveVars,
+  resolveStartVars,
+  StartFlags,
   resolveScopeAccess,
   resolveScopeSkills,
   type ConfigFingerprint,
@@ -562,9 +564,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 +916,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 +1078,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
@@ -1369,7 +1380,7 @@ 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),
+      ...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,17 @@ 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",
+    })
+  })
 })

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,9 @@ 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" },
+] as const satisfies readonly FlagDeclaration[]
 
 /** A misspelt name is a compile error. */
 export type Flags<R extends readonly FlagDeclaration[] = typeof FLAGS> = {
@@ -22,6 +24,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 +49,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/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,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"