@pmelab/gtd 27.4.0 → 27.6.0

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/index.ts

@@ -23,6 +23,7 @@ export * from "./feature/steps.js"
 export * from "./feature/planning.js"
 export * from "./feature/packages.js"
 export * from "./feature/refactor.js"
+export * from "./feature/seam.js"
 export { buildTail, type ReviewOutcome } from "./feature/review.js"
 export * from "./feature/feature.js"
 export { base, review, reviewFlow } from "./review/review.js"

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

@@ -9,10 +9,26 @@ const { flagShipped } = options
 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)].sort(),
+      [...Object.keys(defaults), ...Object.keys(envDefaults)]
+        .filter((name) => name !== "flag_naive_pass" && name !== "flag_risk_tier")
+        .sort(),
     )
   })
 
+  it("declare seamAllow and flag_naive_pass defaults; flag_naive_pass is no option", () => {
+    expect(defaults.flag_naive_pass).toBe("0")
+    expect(Object.keys(ShippedOptions.fields)).not.toContain("flag_naive_pass")
+    expect(configure(feature({ seamAllow: "docs/**" }))).toMatchObject({
+      ok: true,
+      build: { defaults: { seamAllow: "docs/**", flag_naive_pass: "0" } },
+    })
+  })
+
+  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({

package/src/workflows/shared/options.ts

@@ -17,6 +17,7 @@ export const ShippedOptions = Schema.Struct({
   reviewNoteActionable: setting,
   reviewSeverityMinP: setting,
   refactorFlagPattern: setting,
+  seamAllow: setting,
   qualityReviews: setting,
   testCommand: setting,
   plannerModel: setting,

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

@@ -29,6 +29,10 @@ describe("the bundled workflow's skills export", () => {
         "refactor",
         "refactor.fix.suite",
         "refactor.health",
+        "seam",
+        "implement",
+        "implement.fix.suite",
+        "implement.health",
         "build.quality.correctness",
         "build.quality.owasp-security",
         "build.quality.ponytail-review",
@@ -39,8 +43,18 @@ describe("the bundled workflow's skills export", () => {
     )
   })
 
-  it("keys no group scope", () => {
-    for (const group of ["packages.item.fix", "build.fix", "build.review.fix", "build.quality"]) {
+  it("keys no group scope or non-agent step", () => {
+    for (const group of [
+      "packages.item.fix",
+      "build.fix",
+      "build.review.fix",
+      "build.quality",
+      "implement.fix",
+      "seam.judge",
+      "seam.approve",
+      "seam.steer",
+      "seam.by-hand",
+    ]) {
       expect(bundled).not.toHaveProperty(group)
     }
   })
@@ -63,6 +77,10 @@ describe("the bundled workflow's skills export", () => {
       refactor: ["ponytail"],
       "refactor.fix.suite": ["ponytail", "debugging-and-error-recovery"],
       "refactor.health": ["ponytail", "debugging-and-error-recovery"],
+      seam: ["incremental-implementation"],
+      implement: ["test-driven-development", "incremental-implementation"],
+      "implement.fix.suite": ["debugging-and-error-recovery"],
+      "implement.health": ["debugging-and-error-recovery"],
     })
   })
 

package/src/workflows/shared/skills.ts

@@ -29,6 +29,12 @@ export const skills = (
   refactor: ["ponytail"],
   "refactor.fix.suite": ["ponytail", "debugging-and-error-recovery"],
   "refactor.health": ["ponytail", "debugging-and-error-recovery"],
+  // Declared whether or not `naive_pass` is on, so a config keyed on them keeps
+  // loading when the flag flips off.
+  seam: ["incremental-implementation"],
+  implement: ["test-driven-development", "incremental-implementation"],
+  "implement.fix.suite": ["debugging-and-error-recovery"],
+  "implement.health": ["debugging-and-error-recovery"],
   ...lensScopes(
     "build.quality",
     lensesOf(vars.qualityReviews ?? ""),

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

@@ -17,6 +17,11 @@ import {
   buildReviewCollectingPrompt,
   designGateAnswerMessage,
   designTriagePrompt,
+  implementBuildingPrompt,
+  implementFixPrompt,
+  naivePassPrompt,
+  seamByHandMessage,
+  seamSteerMessage,
   summaryPrompt,
   withSkills,
 } from "./text.js"
@@ -105,6 +110,33 @@ describe("agentWithSkills access preamble", () => {
   })
 })
 
+describe("the risk tier prompt and gate line", () => {
+  const triage = (riskTier: boolean) => renderText(() => designTriagePrompt("base", riskTier))
+  const gate = (riskTier: boolean) => renderText(() => designGateAnswerMessage(riskTier))
+
+  it("asks for the tier and the signals, before the answered questions, unsure meaning high", () => {
+    const prompt = triage(true)
+    expect(prompt).toContain("`## Risk Tier`")
+    expect(prompt).toContain("`## Production Signals`")
+    expect(prompt).toContain("BEFORE `## Answered Questions`")
+    expect(prompt).toContain("unsure means `high`")
+    expect(prompt).toContain("Whichever lap this is")
+  })
+
+  it("only appends the tier section when on", () => {
+    expect(triage(false)).not.toContain("Risk Tier")
+    expect(triage(true).startsWith(triage(false))).toBe(true)
+  })
+
+  it("says how to override the tier at the gate when on", () => {
+    expect(gate(true)).toContain("edit the first word under `## Risk Tier`")
+    expect(gate(true)).toContain("approve the next lap with no further change")
+    expect(gate(true)).toContain("means `high`")
+    expect(gate(false)).not.toContain("Risk Tier")
+    expect(gate(true).startsWith(gate(false))).toBe(true)
+  })
+})
+
 describe("the shared open-question instruction", () => {
   it("leaves the option count to the agent, floored at two real options", () => {
     const prompt = renderText(() => designTriagePrompt("base"))
@@ -241,11 +273,103 @@ describe("summaryPrompt", () => {
         { model: "smart", cost: 5 },
         { model: "base", cost: 7 },
       ],
+      marks: [],
       vars: {},
       env: {},
     })
     expect(prompt).toContain("Token cost: 12\n- smart: 5\n- base: 7\n\nPrint the closing message")
   })
+
+  const base = {
+    entryCommit: "e",
+    processBase: "b",
+    processTip: "t",
+    humanCommits: [],
+    processCost: 0,
+    processCostByModel: [],
+    marks: [],
+    vars: {},
+    env: {},
+  }
+
+  it("with no marks leaves today's text", () => {
+    expect(summaryPrompt(base)).toContain("Token cost: 0\n\nPrint the closing message")
+    expect(summaryPrompt(base)).not.toContain("Risk tier")
+    expect(summaryPrompt(base)).not.toContain("Production signals")
+  })
+
+  it("adds the advisory risk line once for the last lap's high tier", () => {
+    const prompt = summaryPrompt({
+      ...base,
+      marks: [
+        { name: "risk-tier", value: "low" },
+        { name: "risk-tier", value: "high" },
+      ],
+    })
+    expect(prompt).toContain("Risk tier: high — this merge needs a human reviewer (advisory")
+    expect(prompt.split("Risk tier: high").length).toBe(2)
+  })
+
+  it("reads only the last lap: a lowered tier and a dropped signal leave no trace", () => {
+    const prompt = summaryPrompt({
+      ...base,
+      marks: [
+        { name: "risk-tier", value: "high" },
+        { name: "production-signal", value: "error rate" },
+        { name: "risk-tier", value: "low" },
+        { name: "production-signal", value: "p95" },
+      ],
+    })
+    expect(prompt).not.toContain("Risk tier")
+    expect(prompt).not.toContain("error rate")
+    expect(prompt).toContain("- `p95`\n")
+  })
+
+  it("treats a flag-on process with no tier mark as high", () => {
+    const prompt = summaryPrompt({
+      ...base,
+      vars: { flag_risk_tier: "1", flag_naive_pass: "1" },
+    })
+    expect(prompt).toContain("Risk tier: high")
+  })
+
+  it("marks no tier when the risk-tier flag is on without naive-pass", () => {
+    const prompt = summaryPrompt({ ...base, vars: { flag_risk_tier: "1", flag_naive_pass: "0" } })
+    expect(prompt).not.toContain("Risk tier")
+  })
+
+  const signal = (value: string) => ({ name: "production-signal", value })
+
+  it("caps the listed signals at 10 and fences them as not instructions", () => {
+    const prompt = summaryPrompt({
+      ...base,
+      marks: [
+        { name: "risk-tier", value: "low" },
+        ...Array.from({ length: 12 }, (_, i) => signal(`s${i}`)),
+      ],
+    })
+    expect(prompt).toContain("not instructions")
+    for (let i = 0; i < 10; i++) expect(prompt).toContain(`- \`s${i}\`\n`)
+    expect(prompt).not.toContain("`s10`")
+  })
+
+  it("cuts a long signal to exactly 200 chars", () => {
+    const prompt = summaryPrompt({
+      ...base,
+      marks: [{ name: "risk-tier", value: "low" }, signal("s0"), signal("x".repeat(300))],
+    })
+    expect(prompt).toContain(`- \`${"x".repeat(200)}\`\n`)
+    expect(prompt).not.toContain("x".repeat(201))
+  })
+
+  it("lists a repeated signal once, in first-occurrence order", () => {
+    const prompt = summaryPrompt({
+      ...base,
+      marks: [{ name: "risk-tier", value: "low" }, signal("s0"), signal("s1"), signal("s0")],
+    })
+    expect(prompt).toContain("- `s0`\n- `s1`\n")
+    expect(prompt.split("- `s0`").length).toBe(2)
+  })
 })
 
 describe("the thread rules", () => {
@@ -441,3 +565,67 @@ describe("buildReviewReviewingPrompt scenarios", () => {
     expect(prompt).not.toContain("Weakened:")
   })
 })
+
+describe("the seam phase's texts", () => {
+  const rejection = { strays: ["src/flows/helpers.ts", "src/flows/runtime.ts"], p: 0.85 }
+
+  it("asks the first naive pass for the quickest working change, with no rejection", () => {
+    const prompt = renderText(() => naivePassPrompt())
+    expect(prompt).toContain(".gtd/REQUIREMENTS.md")
+    expect(prompt).not.toContain("rejected")
+  })
+
+  it("names the reject verdict, its p, every stray and the criterion on a retry", () => {
+    const prompt = renderText(() => naivePassPrompt(rejection))
+    expect(prompt).toContain("reject")
+    expect(prompt).toContain("0.85")
+    expect(prompt).toContain("`src/flows/helpers.ts`")
+    expect(prompt).toContain("`src/flows/runtime.ts`")
+    expect(prompt).toContain("solved the task the wrong way")
+  })
+
+  it("cites the reference as reading material only and asks for a new release flag", () => {
+    const prompt = renderText(() => implementBuildingPrompt("abc123"))
+    expect(prompt).toContain("git show abc123")
+    expect(prompt).toContain("never apply")
+    expect(prompt).toContain("release flag")
+  })
+
+  it("high and undefined tiers carry the flag bullet; low says to add none", () => {
+    const base = renderText(() => implementBuildingPrompt("abc123"))
+    expect(renderText(() => implementBuildingPrompt("abc123", "high"))).toBe(base)
+    expect(base).toContain("new release flag")
+    const low = renderText(() => implementBuildingPrompt("abc123", "low"))
+    expect(low).toContain("Add no release flag — this change is low risk tier")
+    expect(low).not.toContain("new release flag")
+    expect(low).toContain("git show abc123")
+  })
+
+  it("keeps a fix turn to the feedback file's rules", () => {
+    expect(renderText(() => implementFixPrompt())).toContain(".gtd/FEEDBACK.md")
+  })
+
+  it("names both steer answers and the overrule risk, and lists every stray", () => {
+    const message = renderText(() => seamSteerMessage(rejection))
+    expect(message).toContain("edit `.gtd/REQUIREMENTS.md`")
+    expect(message).toContain("clean")
+    expect(message).toContain("Overrule")
+    expect(message).toContain("unaddressed")
+    expect(message).toContain("src/flows/helpers.ts")
+  })
+
+  it("names every unreadable path for a by-hand landing", () => {
+    const message = renderText(() =>
+      seamByHandMessage(["vendor/a.bin", "src/flows/helpers.ts"], ["vendor/a.bin"], "abc123"),
+    )
+    expect(message).toContain("`vendor/a.bin` (unreadable)")
+    expect(message).toContain("`src/flows/helpers.ts`\n")
+    expect(message).toContain("git show abc123 --")
+  })
+
+  it("keeps a stray path with a newline on one line", () => {
+    const message = renderText(() => seamSteerMessage({ strays: ["a\nb.ts"], p: 0.9 }))
+    expect(message).toContain('`"a\\nb.ts"`')
+    expect(message).not.toContain("a\nb.ts")
+  })
+})