@pmelab/gtd 27.5.0 → 27.7.0

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

@@ -0,0 +1,146 @@
+# One SDLC path per file, so a changed path reds exactly one fixture — do not merge.
+@inmem
+Feature: rejected naive passes walk one fixed path through the steer gate to idle
+
+  With GTD_FLAG_NAIVE_PASS on and GTD_FLAG_RISK_TIER off, three rejected naive
+  passes rest at the steer gate, where a human edit restarts the seam and the
+  steered rerun lands. The flags are pinned so the per-flag test runs never
+  move it off its path.
+
+  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"
+    And 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 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`.
+      """
+    And step "design.gate.answer" changes nothing
+
+  Scenario: three rejects rest at the steer gate, a steered rerun lands and runs to idle
+    Given step "seam.naive" writes "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => b + a
+      """
+    And step "implement.health.check" changes nothing
+    And step "implement.closing" runs its script
+    And step "build.review.reviewing" writes ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## calc
+
+      - [ ] ./src/calc.ts#1-2
+        subtract added
+      """
+    And step "build.review.closing" runs its script
+    When the process is driven
+    Then the process rests at "seam.judge"
+
+    Given step "seam.naive" is prompted with "Your previous attempt was rejected"
+    And judge step "seam.judge" answers:
+      """
+      [{"id":"shape","answer":"reject","p":0.9}]
+      """
+    When the process is driven
+    Then the process rests at "seam.steer"
+    And the resting step's content contains "Overrule"
+    And the resting step's content contains "src/calc.ts"
+
+    Given a file ".gtd/REQUIREMENTS.md" with:
+      """
+      # Requirements
+
+      ## Concerns
+
+      ### Subtract
+
+      - `subtract(a, b)` returns `a - b`, in the calculator module.
+      """
+    And step "seam.naive" from now on 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}]
+      """
+    And step "implement.building" writes "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => a + b
+      export const subtract = (a: number, b: number) => a - b
+      export const SUBTRACT = true
+      """
+    When gtd lands
+    And the process is driven
+    Then the process rests at "build.review.await-review"
+
+    Given a file ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## calc
+
+      - [x] ./src/calc.ts#1-2
+        subtract added
+      """
+    When gtd lands
+    And the process is driven
+    Then the process rests at "idle"
+    And the commit subjects end with:
+      """
+      gtd(human): idle → unwind
+      gtd(check): unwind → start-gate.check
+      gtd(check): start-gate.check → design.triage
+      gtd(agent): design.triage → design.gate.answer
+      gtd(human): design.gate.answer → seam.naive
+      gtd(agent): seam.naive → seam.judge
+      gtd(judge): seam.judge → seam.naive
+      gtd(agent): seam.naive → seam.judge
+      gtd(judge): seam.judge → seam.naive
+      gtd(agent): seam.naive → seam.judge
+      gtd(judge): seam.judge → seam.steer
+      gtd(human): seam.steer → seam.naive
+      gtd(agent): seam.naive → seam.judge
+      gtd(judge): seam.judge → implement.building
+      gtd(agent): implement.building → implement.health.check
+      gtd(check): implement.health.check → implement.closing
+      gtd(check): implement.closing → build.review.reviewing
+      gtd(agent): build.review.reviewing → build.review.await-review
+      gtd(human): build.review.await-review → build.review.closing
+      gtd(check): build.review.closing → idle
+      """
+    And the commit "gtd(human): idle → unwind" has a body containing "Gtd-Var: flag_naive_pass=1"
+    And the commit "gtd(human): idle → unwind" has a body containing "Gtd-Var: flag_risk_tier=0"
+    And the commit "gtd(agent): seam.naive → seam.judge" has a body containing "Gtd-Kept:"
+    And the commit "gtd(judge): seam.judge → seam.naive" has a body containing "\"answer\":\"reject\""
+    And the commit "gtd(judge): seam.judge → seam.steer" has a body containing "\"answer\":\"reject\""
+    And the commit "gtd(judge): seam.judge → implement.building" has a body containing "\"answer\":\"land\""
+    And no commit body contains "Gtd-Approved:"
+    And no commit body contains "Gtd-Workflow:"

package/src/workflows/feature/seam.feature

@@ -166,73 +166,6 @@ Feature: the naive pass and seam judge replace architecture behind GTD_FLAG_NAIV
     And the resting step's content contains "src/calc.ts"
     And the resting step's content does not contain "src/calc*.ts"
 
-  Scenario: a refactor-first judgment rests at the approval gate, then refactors, then implements
-    Given 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":"refactor-first","p":0.9}]
-      """
-    And step "refactor.deriving" writes ".gtd/REFACTOR.md" with:
-      """
-      # Behaviour-neutral refactor
-
-      ## Scope (read-only)
-
-      - `src/calc.ts` # gtd-path-exempt: scenario fixture, not a repo file
-      """
-    And step "refactor.building" writes "src/calc.ts" with:
-      """
-      export const add = (a: number, b: number) => a + b
-      export const op = (a: number, b: number, sign: number) => a + sign * b
-      """
-    And step "refactor.health.check" changes nothing
-    And step "refactor.closing" runs its script
-    When the process is driven
-    Then the process rests at "seam.approve"
-    And the resting step's content contains "src/calc.ts"
-    When gtd lands
-    Then the last commit subject is "gtd(human): seam.approve → refactor.deriving"
-    And the last commit body contains "Gtd-Approved:"
-    When the process is driven
-    Then the process rests at "implement.building"
-    And the commit subjects end with:
-      """
-      gtd(judge): seam.judge → seam.approve
-      gtd(human): seam.approve → refactor.deriving
-      gtd(check): refactor.deriving → refactor.building
-      gtd(agent): refactor.building → refactor.health.check
-      gtd(check): refactor.health.check → refactor.closing
-      gtd(check): refactor.closing → implement.building
-      """
-
-  Scenario: three rejects retry the naive pass twice, then rest at the steer gate
-    Given step "seam.naive" writes "src/calc.ts" with:
-      """
-      export const add = (a: number, b: number) => b + a
-      """
-    And judge step "seam.judge" answers:
-      """
-      [{"id":"shape","answer":"reject","p":0.9}]
-      """
-    When the process is driven
-    Then the process rests at "seam.steer"
-    And the resting step's content contains "Overrule"
-    And the resting step's content contains "src/calc.ts"
-    And the commit subjects end with:
-      """
-      gtd(human): design.gate.answer → seam.naive
-      gtd(agent): seam.naive → seam.judge
-      gtd(judge): seam.judge → seam.naive
-      gtd(agent): seam.naive → seam.judge
-      gtd(judge): seam.judge → seam.naive
-      gtd(agent): seam.naive → seam.judge
-      gtd(judge): seam.judge → seam.steer
-      """
-
   Scenario: an edit at the steer gate runs the naive pass again with a fresh retry budget
     Given step "seam.naive" writes "src/calc.ts" with:
       """

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",

package/src/workflows/feature/tier.test.ts

@@ -0,0 +1,164 @@
+import { afterEach, describe, expect, it } from "vitest"
+import { installContext, type FlowContext } from "../../flows/index.js"
+import { fixtureContext } from "../shared/text.fixture.js"
+import { productionSignals, readRiskTier, recordRisk, riskTierOn } from "./tier.js"
+
+afterEach(() => installContext(undefined))
+
+const withVars = (vars: Record<string, string>) => installContext(fixtureContext({ vars }))
+
+describe("riskTierOn", () => {
+  it.each([
+    [{ flag_naive_pass: "1", flag_risk_tier: "1" }, true],
+    [{ flag_naive_pass: "1", flag_risk_tier: "0" }, false],
+    [{ flag_naive_pass: "0", flag_risk_tier: "1" }, false],
+    [{ flag_naive_pass: "0", flag_risk_tier: "0" }, false],
+    [{ flag_naive_pass: "1" }, false],
+  ])("%j is %s", (vars, expected) => {
+    withVars(vars)
+    expect(riskTierOn()).toBe(expected)
+  })
+})
+
+describe("readRiskTier", () => {
+  const doc = (body: string) =>
+    `# Requirements\n\n## Risk Tier\n\n${body}\n\n## Answered Questions\n`
+
+  it.each(["low", "`low`", "**Low** — trivial copy", "LOW - copy", "_low_ — x"])(
+    "reads %j as low",
+    (body) => expect(readRiskTier(doc(body))).toBe("low"),
+  )
+
+  it.each(["high", "medium", "lower", "", "   \n\n"])("reads %j as high", (body) =>
+    expect(readRiskTier(doc(body))).toBe("high"),
+  )
+
+  it("reads a missing section and undefined as high", () => {
+    expect(readRiskTier("# Requirements\n\n## Other\n\nlow\n")).toBe("high")
+    expect(readRiskTier(undefined)).toBe("high")
+  })
+
+  it("takes the first non-blank line only and stops at the next section", () => {
+    expect(readRiskTier("## Risk Tier\n\nhigh — why\nlow\n")).toBe("high")
+    expect(readRiskTier("## Risk Tier\n\n## Other\n\nlow\n")).toBe("high")
+  })
+})
+
+describe("readRiskTier fences", () => {
+  it("ignores a backtick-fenced example above the real section", () => {
+    const text = "```\n## Risk Tier\n\nlow\n```\n\n## Risk Tier\n\nhigh\n"
+    expect(readRiskTier(text)).toBe("high")
+  })
+
+  it("reads a fenced example with no real section as high", () => {
+    expect(readRiskTier("```md\n## Risk Tier\n\nlow\n```\n")).toBe("high")
+  })
+
+  it("keeps the signals section open across a fence and skips fenced items", () => {
+    const signals = "## Production Signals\n- before\n```\n# x\n- fake\n```\n- after\n"
+    expect(productionSignals(signals)).toEqual(["before", "after"])
+  })
+
+  it("ignores a tilde-fenced example above the real section", () => {
+    const text = "~~~\n## Risk Tier\n\nlow\n~~~\n\n## Risk Tier\n\nhigh\n"
+    expect(readRiskTier(text)).toBe("high")
+  })
+
+  it("does not read a fence opener's info string as the tier", () => {
+    expect(readRiskTier("## Risk Tier\n\n```low\nhigh\n```\n")).toBe("high")
+    expect(readRiskTier("## Risk Tier\n\n~~~low\nlow\n~~~\n")).toBe("high")
+  })
+
+  it("fails closed on an unclosed fence before the real section", () => {
+    expect(readRiskTier("```\nstray\n\n## Risk Tier\n\nlow\n")).toBe("high")
+  })
+
+  it("does not close a 4-backtick fence with 3 backticks", () => {
+    const text = "````\n```\n## Risk Tier\n\nlow\n````\n"
+    expect(readRiskTier(text)).toBe("high")
+  })
+})
+
+describe("readRiskTier fence closers", () => {
+  it.each([
+    ["a tilde line does not close a backtick fence", "```\n~~~\n## Risk Tier\n\nlow\n```\n"],
+    ["a closer with an info string does not close", "```\n```js\n## Risk Tier\n\nlow\n```\n"],
+  ])("%s", (_, text) => {
+    expect(readRiskTier(text)).toBe("high")
+  })
+})
+
+describe("productionSignals", () => {
+  it("lists top-level items only, skipping blanks and indented lines", () => {
+    const text = `## Production Signals
+
+- error rate on /pay
+  not a signal
+  - nested detail
+-
+-    spaced   out\t signal
+* star item
+
+## Answered Questions
+
+- not a signal
+`
+    expect(productionSignals(text)).toEqual([
+      "error rate on /pay",
+      "spaced out signal",
+      "star item",
+    ])
+  })
+
+  it("skips a fenced Production Signals example", () => {
+    const text = "```\n## Production Signals\n- fake\n```\n\n## Production Signals\n- real\n"
+    expect(productionSignals(text)).toEqual(["real"])
+  })
+
+  it("drops control characters", () => {
+    expect(productionSignals("## Production Signals\n- a\u001bb\u0085c\n")).toEqual(["abc"])
+  })
+
+  it("is empty for a missing section or undefined", () => {
+    expect(productionSignals("## Risk Tier\nlow\n")).toEqual([])
+    expect(productionSignals(undefined)).toEqual([])
+  })
+})
+
+describe("recordRisk", () => {
+  const record = (requirements: string | undefined) => {
+    const marks: [string, string][] = []
+    installContext({
+      ...fixtureContext({ read: () => requirements }),
+      mark: (name: string, value: string) => marks.push([name, value]),
+    } as unknown as FlowContext)
+    return { tier: recordRisk(), marks }
+  }
+
+  it("marks the tier first, then one production-signal each", () => {
+    const { tier, marks } = record(
+      "## Risk Tier\nhigh — payments\n\n## Production Signals\n- a\n- b\n",
+    )
+    expect(tier).toBe("high")
+    expect(marks).toEqual([
+      ["risk-tier", "high"],
+      ["production-signal", "a"],
+      ["production-signal", "b"],
+    ])
+  })
+
+  it("marks risk-tier=low too", () => {
+    const { tier, marks } = record("## Risk Tier\nlow — copy\n\n## Production Signals\n- a\n")
+    expect(tier).toBe("low")
+    expect(marks).toEqual([
+      ["risk-tier", "low"],
+      ["production-signal", "a"],
+    ])
+  })
+
+  it("treats a missing file as high", () => {
+    const { tier, marks } = record(undefined)
+    expect(tier).toBe("high")
+    expect(marks).toEqual([["risk-tier", "high"]])
+  })
+})

package/src/workflows/feature/tier.ts

@@ -0,0 +1,74 @@
+import { mark, read, vars } from "../../flows/index.js"
+import { REQUIREMENTS } from "../shared/steps.js"
+
+export type RiskTier = "low" | "high"
+
+/** GTD_FLAG_NAIVE_PASS, GTD_FLAG_RISK_TIER: both pinned at process start, so a mid-process flip never moves a process. */
+export const riskTierOn = (): boolean => vars.flag_naive_pass === "1" && vars.flag_risk_tier === "1"
+
+// An unclosed fence runs to end of file, so the tier reads `high` (fail-closed). A backtick
+// opener with a backtick in its info string still counts as a fence: deviates from CommonMark,
+// worst case is `high`.
+const markFenced = (text: string): readonly { line: string; fenced: boolean }[] => {
+  let fence: string | undefined // the opener run, e.g. "````"
+  return text.split(/\r?\n/).map((line) => {
+    const run = /^ {0,3}(`{3,}|~{3,})/.exec(line)?.[1]
+    const fenced = fence !== undefined || run !== undefined
+    if (fence === undefined) fence = run
+    else if (
+      run !== undefined &&
+      run[0] === fence[0] &&
+      run.length >= fence.length &&
+      /^ {0,3}(`+|~+)[ \t]*$/.test(line)
+    )
+      fence = undefined
+    return { line, fenced }
+  })
+}
+
+const sectionLines = (
+  text: string | undefined,
+  title: string,
+): readonly { line: string; fenced: boolean }[] => {
+  if (text === undefined) return []
+  const heading = new RegExp(`^##[ \\t]+${title}[ \\t]*$`, "i")
+  const lines = markFenced(text)
+  const start = lines.findIndex((l) => !l.fenced && heading.test(l.line))
+  if (start < 0) return []
+  const rest = lines.slice(start + 1)
+  const end = rest.findIndex((l) => !l.fenced && /^#{1,2}[ \t]/.test(l.line))
+  return end < 0 ? rest : rest.slice(0, end)
+}
+
+/** Anything but a legible `low` is `high`: under-tiering is the risky direction. */
+export const readRiskTier = (requirements: string | undefined): RiskTier => {
+  const first = sectionLines(requirements, "Risk Tier").find(
+    (l) => !l.fenced && l.line.trim() !== "",
+  )?.line
+  const word = first?.trim().split(/\s+/)[0]?.replace(/[`*_]/g, "").toLowerCase()
+  return word === "low" ? "low" : "high"
+}
+
+// eslint-disable-next-line no-control-regex -- the control range IS the point
+const CONTROL = /[\x00-\x1f\x7f-\x9f\u2028\u2029]/g
+
+const tidy = (text: string): string => text.replace(/\s+/g, " ").replace(CONTROL, "").trim()
+
+export const productionSignals = (requirements: string | undefined): readonly string[] => {
+  const items: string[] = []
+  for (const { line, fenced } of sectionLines(requirements, "Production Signals")) {
+    if (fenced) continue
+    const top = /^[-*+][ \t]+(.*)$/.exec(line)
+    if (top !== null) items.push(top[1]!)
+  }
+  return items.map(tidy).filter((item) => item !== "")
+}
+
+/** The tier is always marked, first, so the last `risk-tier` mark opens the current lap's marks. */
+export const recordRisk = (): RiskTier => {
+  const requirements = read(REQUIREMENTS)
+  const tier = readRiskTier(requirements)
+  mark("risk-tier", tier)
+  for (const signal of productionSignals(requirements)) mark("production-signal", signal)
+  return tier
+}

package/src/workflows/shared/options.test.ts

@@ -10,7 +10,7 @@ describe("the shipped workflow factories", () => {
   it("take exactly the settings the shipped workflows declare as options", () => {
     expect(Object.keys(ShippedOptions.fields).sort()).toEqual(
       [...Object.keys(defaults), ...Object.keys(envDefaults)]
-        .filter((name) => name !== "flag_naive_pass")
+        .filter((name) => name !== "flag_naive_pass" && name !== "flag_risk_tier")
         .sort(),
     )
   })
@@ -24,6 +24,11 @@ describe("the shipped workflow factories", () => {
     })
   })
 
+  it("declare flag_risk_tier off by default; it is no factory option", () => {
+    expect(defaults.flag_risk_tier).toBe("0")
+    expect(Object.keys(ShippedOptions.fields)).not.toContain("flag_risk_tier")
+  })
+
   it("lay each option over the shipped setting of its own kind", () => {
     const result = configure(feature({ qualityReviews: "correctness", testCommand: "npm run ci" }))
     expect(result).toMatchObject({