@pmelab/gtd 23.2.0 → 24.1.0

package/src/workflows/review/review.ts

@@ -0,0 +1,33 @@
+import { start, type WorkflowBase } from "../../flows/index.js"
+import { gate } from "../shared/health.js"
+import { shipped } from "../shared/options.js"
+import { handOffTail, refusePendingHandOff } from "../shared/tail.js"
+import * as t from "../shared/text.js"
+
+/**
+ * Pure review of everything since `reviewBase`: a green gate, the quality
+ * lap, then the human review. A note ends the process with `.gtd/REVIEW.md`
+ * left for `fix`; it never re-plans.
+ */
+export const reviewFlow = async (): Promise<void> => {
+  refusePendingHandOff()
+  await gate("review-gate", t.reviewGateBlockedMessage())
+  await handOffTail(false, start())
+}
+
+export const review = shipped(
+  reviewFlow,
+  {
+    review: {
+      args: [{ name: "base", optional: true }],
+      // Annotated: inferred, the literal union only fits under exactOptionalPropertyTypes.
+      vars: ({ base }): Readonly<Record<string, string>> =>
+        base === undefined ? {} : { reviewBase: base },
+    },
+  },
+  (_workflow, vars) => vars.reviewBase || "",
+)
+
+/** @deprecated The `review` factory carries its own base; kept so a hand-written `review` re-exporting it still maps `reviewBase`. */
+export const base: WorkflowBase = (workflow, vars) =>
+  workflow === "review" ? (vars.reviewBase ?? "") : undefined

package/src/workflows/{access.test.ts → shared/access.test.ts}

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest"
 import { access } from "./access.js"
-import * as workflow from "./index.js"
+import * as workflow from "../index.js"
 
 const { defaults } = workflow
 

package/src/workflows/{access.ts → shared/access.ts}

@@ -1,5 +1,5 @@
-import type { ScopeAccess } from "../flows/index.js"
-import { lensesOf } from "./review.js"
+import type { ScopeAccess } from "../../flows/index.js"
+import { lensesOf, lensScopes } from "../../workflow-kit/index.js"
 
 // The bundled workflow's default file access, keyed by scope full name — the
 // name a `config.access` entry addresses. Only planning and review scopes
@@ -16,7 +16,5 @@ export const access = (
   // `{}` reopens what `build.review` restricted: the fixes edit code.
   "build.review.fix.nits": {},
   "build.review.fix.risks": {},
-  ...Object.fromEntries(
-    lensesOf(vars.qualityReviews ?? "").map((lens) => [`build.quality.${lens}`, { write: [] }]),
-  ),
+  ...lensScopes("build.quality", lensesOf(vars.qualityReviews ?? ""), () => ({ write: [] })),
 })

package/src/workflows/shared/config.fixture.ts

@@ -0,0 +1,12 @@
+/** A `.gtd/REVIEW.md` on the fixture calculator, one hunk per note. */
+export const reviewDoc = (...notes: string[]): string =>
+  [
+    "# Review: abc1234",
+    "",
+    "<!-- base: 0000000 -->",
+    "",
+    "## calc",
+    "",
+    ...notes.flatMap((note, i) => [`- [ ] ./src/calc.ts#${i + 1}-${i + 1}`, `  ${note}`]),
+    "",
+  ].join("\n")

package/src/workflows/{health.test.ts → shared/health.test.ts}

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest"
-import { toRequest } from "../judges/index.js"
+import { toRequest } from "../../judges/index.js"
 import { fastSuiteGuard, retryQuestion } from "./health.js"
 import { renderText } from "./text.fixture.js"
 

package/src/workflows/{health.ts → shared/health.ts}

@@ -8,10 +8,10 @@ import {
   numeric,
   quote,
   read,
-  scope,
   vars,
   type JudgeQuestion,
-} from "../flows/index.js"
+} from "../../flows/index.js"
+import * as kit from "../../workflow-kit/index.js"
 import { describeEscalation, escalate, escalationExhausted, ESCALATION, FEEDBACK } from "./steps.js"
 import * as t from "./text.js"
 
@@ -35,21 +35,23 @@ export const fastSuiteGuard = (): string[] =>
 /** Fix turns a run of red checks gets before it escalates. */
 export const FIX_CAP = 3
 
+const unconfigured = (): boolean => read(SETUP) !== undefined
+
 /** Run the suite as step `name`; resolves `true` when it passed. A failure is in `.gtd/FEEDBACK.md`. */
-export const baseline = async (name: string, label = "Checking the baseline"): Promise<boolean> => {
-  for (;;) {
-    const green = await check(name, env.testCommand ?? "", {
-      report: FEEDBACK,
-      label,
-      preamble: fastSuiteGuard(),
-    })
-    if (read(SETUP) === undefined) return green
-  }
-}
+export const baseline = (name: string, label = "Checking the baseline"): Promise<boolean> =>
+  kit.untilSettled(
+    () =>
+      check(name, env.testCommand ?? "", { report: FEEDBACK, label, preamble: fastSuiteGuard() }),
+    unconfigured,
+  )
 
-/** How many escalation rounds a run of red checks has spent — reset once the suite goes green. */
-export interface EscalationCount {
-  rounds: number
+export type { EscalationCount } from "../../workflow-kit/index.js"
+
+const escalationSteps: kit.EscalationSteps = {
+  limit: 2,
+  describe: describeEscalation,
+  stop: escalate,
+  exhausted: escalationExhausted,
 }
 
 /**
@@ -57,15 +59,8 @@ export interface EscalationCount {
  * agent writes `.gtd/ESCALATION.md`, a human narrows it. From the third round
  * on, the human is told the budget is spent instead.
  */
-export const escalation = async (count: EscalationCount): Promise<void> => {
-  if (count.rounds >= 2) return escalationExhausted()
-  count.rounds++
-  await describeEscalation()
-  await escalate()
-}
-
-const STAMP = /\n<!-- gtd check [0-9a-f]+ -->\n?$/
-const stripStamp = (text: string): string => text.replace(STAMP, "\n")
+export const escalation = (count: kit.EscalationCount): Promise<void> =>
+  kit.escalation(count, escalationSteps)
 
 /** "Is this red round the same failure as the last one?" — asked of two reports, or of nothing when one is empty. */
 export const retryQuestion = (comparable: boolean): JudgeQuestion =>
@@ -107,7 +102,7 @@ export interface HealthOptions {
   /** Fix turns already spent before this call. */
   readonly fixesSoFar?: number
   /** Escalation rounds shared with other callers in the same run of red checks. */
-  readonly escalations?: EscalationCount
+  readonly escalations?: kit.EscalationCount
   /** `fast` runs `fastTestCommand` (default `full`: `testCommand`). */
   readonly suite?: "full" | "fast"
   /** Paths removed on a green run. */
@@ -130,37 +125,25 @@ const runSuite = (options: HealthOptions): Promise<boolean> => {
  * first once `FIX_CAP` fixes are spent, or a judge calls the failure
  * identical to the previous round's.
  */
-export const healthy = async (
-  fix: () => Promise<void>,
-  options: HealthOptions = {},
-): Promise<void> => {
-  const escalations = options.escalations ?? { rounds: 0 }
-  let fixes = options.fixesSoFar ?? 0
-  let previous: string | undefined
-  for (;;) {
-    const green = await runSuite(options)
+export const healthy = (fix: () => Promise<void>, options: HealthOptions = {}): Promise<void> =>
+  kit.healthy(fix, {
     // Unconfigured: straight back to the check, no fix turn or count.
-    if (options.suite === "fast" && read(SETUP) !== undefined) continue
-    if (green) {
-      escalations.rounds = 0
-      return
-    }
-    const current = stripStamp(read(FEEDBACK) ?? "")
-    const stuck = previous !== undefined && (await sameFailure(previous, current))
-    previous = current
-    if (stuck || fixes >= FIX_CAP) {
-      await escalation(escalations)
-      fixes = 0
-    }
-    fixes++
-    await fix()
-  }
-}
+    check:
+      options.suite === "fast"
+        ? () => kit.untilSettled(() => runSuite(options), unconfigured)
+        : () => runSuite(options),
+    report: FEEDBACK,
+    fixCap: FIX_CAP,
+    fixesSoFar: options.fixesSoFar ?? 0,
+    sameFailure,
+    escalations: options.escalations ?? { rounds: 0 },
+    escalation: escalationSteps,
+  })
 
 /** Hold the process at `<name>.blocked` until the suite is green. */
 export const gate = (name: string, message: string): Promise<void> =>
-  scope(name, async () => {
-    while (!(await baseline("check"))) {
-      await human("blocked", { message, label: "Baseline is red", file: FEEDBACK })
-    }
-  })
+  kit.gate(
+    name,
+    () => baseline("check"),
+    () => human("blocked", { message, label: "Baseline is red", file: FEEDBACK }),
+  )

package/src/workflows/{options.test.ts → shared/options.test.ts}

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest"
-import { configure } from "../flows/index.js"
-import * as workflows from "./index.js"
+import { configure } from "../../flows/index.js"
+import * as workflows from "../index.js"
 
 const { defaults, envDefaults, feature, fix, review, ShippedOptions } = workflows
 

package/src/workflows/{options.ts → shared/options.ts}

@@ -1,5 +1,11 @@
 import { Schema } from "effect"
-import { defineWorkflow, type Flow, type WorkflowFactory } from "../flows/index.js"
+import {
+  defineWorkflow,
+  type Flow,
+  type WorkflowBase,
+  type WorkflowDoors,
+  type WorkflowFactory,
+} from "../../flows/index.js"
 import { defaults, envDefaults } from "./vars.js"
 
 const setting = Schema.optionalWith(Schema.String, { exact: true })
@@ -27,12 +33,18 @@ const over = (
 })
 
 /** A shipped flow as a factory: its options override the settings it declares, each in its own kind. */
-export const shipped = (flow: Flow): WorkflowFactory<ShippedOptions> =>
+export const shipped = (
+  flow: Flow,
+  doors?: WorkflowDoors,
+  base?: WorkflowBase,
+): WorkflowFactory<ShippedOptions> =>
   defineWorkflow(
     Schema.standardSchemaV1(ShippedOptions, { onExcessProperty: "error", errors: "all" }),
     (options) => ({
       flow,
       defaults: over(defaults, options),
       envDefaults: over(envDefaults, options),
+      doors,
+      base,
     }),
   )

package/src/workflows/shared/reserved.ts

@@ -0,0 +1,11 @@
+import type { Summary } from "../../flows/index.js"
+import * as t from "./text.js"
+import { ARCHITECTURE, REQUIREMENTS, REVIEW } from "./steps.js"
+
+export { defaults, envDefaults } from "./vars.js"
+export { skills } from "./skills.js"
+export { access } from "./access.js"
+
+export const summary: Summary = t.summaryPrompt
+
+export const steering = { [REQUIREMENTS]: "qa", [ARCHITECTURE]: "qa", [REVIEW]: "review" }

package/src/workflows/{scenarios.test.ts → shared/scenarios.test.ts}

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it } from "vitest"
-import { installContext, type StepRequest } from "../flows/index.js"
+import { installContext, type StepRequest } from "../../flows/index.js"
 import {
   driftedScenarios,
   freezeScenarios,

package/src/workflows/shared/scenarios.ts

@@ -0,0 +1,35 @@
+import { human, scope } from "../../flows/index.js"
+import * as kit from "../../workflow-kit/index.js"
+import * as t from "./text.js"
+
+export {
+  driftedScenarios,
+  freezeScenarios,
+  scenarioText,
+  wordingDrift,
+  type FrozenScenarios,
+} from "../../workflow-kit/index.js"
+
+/** After a turn: stop at `scenario-wording` while wording drifted; accept moves the snapshot. */
+export const holdWording = (frozen: kit.FrozenScenarios | undefined): Promise<void> =>
+  kit.holdWording(frozen, (at, drifted) =>
+    human("scenario-wording", {
+      message: t.scenarioWordingMessage(at, drifted),
+      label: "Scenario wording changed",
+      acceptClean: true,
+      base: at,
+    }),
+  )
+
+/** `turn`, then `holdWording`; `within` names the scope the gate rests in. */
+export const guarded =
+  (
+    frozen: kit.FrozenScenarios | undefined,
+    turn: () => Promise<void>,
+    within?: string,
+  ): (() => Promise<void>) =>
+  async () => {
+    await turn()
+    if (within === undefined) await holdWording(frozen)
+    else await scope(within, () => holdWording(frozen))
+  }

package/src/workflows/{skills.test.ts → shared/skills.test.ts}

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest"
 import { skills } from "./skills.js"
-import * as workflow from "./index.js"
+import * as workflow from "../index.js"
 
 const { defaults } = workflow
 
@@ -25,6 +25,7 @@ describe("the bundled workflow's skills export", () => {
         "build.review",
         "build.review.fix.nits",
         "build.review.fix.risks",
+        "notes",
         "build.quality.correctness",
         "build.quality.owasp-security",
         "build.quality.ponytail-review",
@@ -55,6 +56,7 @@ describe("the bundled workflow's skills export", () => {
       "build.review": ["code-review-and-quality"],
       "build.review.fix.nits": ["incremental-implementation", "code-simplification"],
       "build.review.fix.risks": ["debugging-and-error-recovery", "incremental-implementation"],
+      notes: ["incremental-implementation", "code-simplification"],
     })
   })
 

package/src/workflows/{skills.ts → shared/skills.ts}

@@ -1,5 +1,5 @@
 import { builtInLenses } from "./steps.js"
-import { lensesOf } from "./review.js"
+import { lensesOf, lensScopes } from "../../workflow-kit/index.js"
 
 // The bundled workflow's default skills, one list per SCOPE, keyed by the
 // scope's full name — the same name a `config.skills` entry addresses. A
@@ -23,10 +23,11 @@ export const skills = (
   "build.review": ["code-review-and-quality"],
   "build.review.fix.nits": ["incremental-implementation", "code-simplification"],
   "build.review.fix.risks": ["debugging-and-error-recovery", "incremental-implementation"],
-  ...Object.fromEntries(
-    lensesOf(vars.qualityReviews ?? "").map((lens) => [
-      `build.quality.${lens}`,
-      builtInLenses[lens]?.skills ?? [lens],
-    ]),
+  // `fix`'s turn over the notes a review handed on.
+  notes: ["incremental-implementation", "code-simplification"],
+  ...lensScopes(
+    "build.quality",
+    lensesOf(vars.qualityReviews ?? ""),
+    (lens) => builtInLenses[lens]?.skills ?? [lens],
   ),
 })

package/src/workflows/{steps.test.ts → shared/steps.test.ts}

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest"
-import type { StepRequest } from "../flows/index.js"
+import type { StepRequest } from "../../flows/index.js"
 import { captureStep } from "./text.fixture.js"
 import * as steps from "./steps.js"
 
@@ -15,31 +15,6 @@ const agentPrompt = (request: StepRequest): string => {
 }
 
 describe("the bundled workflow's steps declare skills — a bundled step's rendered prompt carries its bundled skills.ts preamble", () => {
-  it("triage carries design.triage's bundled skills", async () => {
-    const prompt = agentPrompt(await capture(() => steps.triage("base"), "design"))
-    expect(prompt).toContain("spec-driven-development, planning-and-task-breakdown")
-  })
-
-  it("author carries architecture.author's bundled skills", async () => {
-    const prompt = agentPrompt(await capture(() => steps.author(), "architecture"))
-    expect(prompt).toContain("api-and-interface-design, documentation-and-adrs, ponytail")
-  })
-
-  it("decompose carries architecture.decompose's bundled skills", async () => {
-    const prompt = agentPrompt(await capture(() => steps.decompose(), "architecture"))
-    expect(prompt).toContain("incremental-implementation, planning-and-task-breakdown")
-  })
-
-  it("build carries packages.item.building's bundled skills", async () => {
-    const prompt = agentPrompt(await capture(() => steps.build("pkg"), "packages.item"))
-    expect(prompt).toContain("test-driven-development, incremental-implementation")
-  })
-
-  it("fixSuite carries packages.item.fix.suite's bundled skills", async () => {
-    const prompt = agentPrompt(await capture(() => steps.fixSuite(), "packages.item"))
-    expect(prompt).toContain("debugging-and-error-recovery")
-  })
-
   it("fix carries build.fix's bundled skills", async () => {
     const prompt = agentPrompt(await capture(() => steps.fixCheck(), "build"))
     expect(prompt).toContain("debugging-and-error-recovery")
@@ -104,52 +79,12 @@ describe("the bundled workflow's steps declare skills — a bundled step's rende
     expect(prompt).toContain("code-review-and-quality")
   })
 
-  it("collecting carries build.review.collecting's bundled skills", async () => {
-    const prompt = agentPrompt(await capture(() => steps.collecting("capture"), "build"))
-    expect(prompt).toContain("code-review-and-quality")
-  })
-
   it("an empty configured list leaves that step's skills empty, and its rendered prompt bare", async () => {
     const request = await capture(() => steps.fixCheck(), "build", { build: [] })
     if (request.kind !== "agent") throw new Error("unreachable")
     expect(request.prompt).not.toContain("Load whatever's listed here")
   })
 
-  it("answerReviewQuestions answers inline in .gtd/REVIEW.md as the reviewer, with its bundled skills", async () => {
-    const request = await capture(
-      () =>
-        steps.answerReviewQuestions([{ id: "note-1", anchor: "calc ./a.ts#1-1", text: "why?" }]),
-      "build",
-    )
-    if (request.kind !== "agent") throw new Error("unreachable")
-    expect(request.name).toBe("review.answer-review-questions")
-    expect(request.options).toMatchObject({
-      file: ".gtd/REVIEW.md",
-      mode: "review",
-    })
-    expect(request.prompt).toContain("code-review-and-quality")
-    expect(request.prompt).toContain("note-1 — calc ./a.ts#1-1")
-    expect(request.prompt).toContain("`A: ` line")
-    expect(request.prompt).toContain("gtd check review .gtd/REVIEW.md")
-  })
-
-  it("fixNits fixes every nit in one turn and leaves .gtd/REVIEW.md alone", async () => {
-    const request = await capture(
-      () =>
-        steps.fixNits([
-          { id: "note-1", anchor: "calc ./a.ts#1-1", text: "typo" },
-          { id: "note-2", anchor: "calc ./a.ts#2-2", text: "semicolon" },
-        ]),
-      "build",
-    )
-    if (request.kind !== "agent") throw new Error("unreachable")
-    expect(request.name).toBe("review.fix.nits.fixing")
-    expect(request.prompt).toContain("incremental-implementation, code-simplification")
-    expect(request.prompt).toContain("typo")
-    expect(request.prompt).toContain("semicolon")
-    expect(request.prompt).toContain("Leave `.gtd/REVIEW.md` untouched")
-  })
-
   it("fixRisks fixes every risk, tolerates an empty turn, and leaves .gtd/REVIEW.md alone", async () => {
     const request = await capture(
       () => steps.fixRisks([{ id: "risk-1", anchor: "calc ./a.ts#1-1", text: "Risk: drops it" }]),

package/src/workflows/{steps.ts → shared/steps.ts}

@@ -1,4 +1,4 @@
-import { env, human } from "../flows/index.js"
+import { env, human } from "../../flows/index.js"
 import * as t from "./text.js"
 
 // The bundled workflow's single steps. A step's name is relative to the
@@ -13,71 +13,8 @@ export const ARCHITECTURE = ".gtd/ARCHITECTURE.md"
 export const REVIEW = ".gtd/REVIEW.md"
 export const QUALITY = ".gtd/QUALITY.md"
 
-const planner = (): string => env.plannerModel ?? ""
-const coder = (): string => env.coderModel ?? ""
-
-// ── Planning ────────────────────────────────────────────────────────────────
-
-/** Turn the sketch since `base` into `.gtd/REQUIREMENTS.md`. */
-export const triage = (base: string): Promise<void> =>
-  t.agentWithSkills("triage", t.designTriagePrompt(base), {
-    label: "Triaging the change",
-    file: REQUIREMENTS,
-    mode: "qa",
-    model: planner(),
-    system: t.designSystem(),
-  })
-
-export const author = (): Promise<void> =>
-  t.agentWithSkills("author", t.architectureAuthorPrompt(), {
-    label: "Refining the technical plan",
-    file: ARCHITECTURE,
-    mode: "qa",
-    model: planner(),
-    system: t.architectSystem(),
-  })
-
-export const decompose = (): Promise<void> =>
-  t.agentWithSkills("decompose.decomposing", t.architectureDecomposePrompt(), {
-    label: "Decomposing into packages",
-    model: planner(),
-    system: t.architectSystem(),
-  })
-
-export const answerProductQuestions = (): Promise<void> =>
-  human("gate.answer", {
-    message: t.designGateAnswerMessage(),
-    label: "Awaiting your product answers",
-    file: REQUIREMENTS,
-    mode: "qa",
-    acceptClean: true,
-  })
-
-export const answerTechnicalQuestions = (): Promise<void> =>
-  human("gate.answer", {
-    message: t.architectureGateAnswerMessage(),
-    label: "Awaiting your technical answers",
-    file: ARCHITECTURE,
-    mode: "qa",
-    acceptClean: true,
-  })
-
-// ── Packages ────────────────────────────────────────────────────────────────
-
-export const build = (pkg: string): Promise<void> =>
-  t.agentWithSkills("building", t.packagesItemBuildingPrompt(pkg), {
-    label: "Building",
-    model: coder(),
-    system: t.builderSystem(),
-  })
-
-export const fixSuite = (): Promise<void> =>
-  t.agentWithSkills("fix.suite.fixing", t.packagesItemFixSuitePrompt(), {
-    label: "Fixing the check",
-    file: FEEDBACK,
-    model: coder(),
-    system: t.builderSystem(),
-  })
+export const planner = (): string => env.plannerModel ?? ""
+export const coder = (): string => env.coderModel ?? ""
 
 // ── Keeping the suite green ─────────────────────────────────────────────────
 
@@ -162,25 +99,6 @@ export const reviewing = (base: string, carry?: string): Promise<void> =>
     base,
   })
 
-/** Answer every `question` note inline in `.gtd/REVIEW.md`. */
-export const answerReviewQuestions = (notes: readonly t.NoteInput[]): Promise<void> =>
-  t.agentWithSkills("review.answer-review-questions", t.buildReviewAnswerQuestionsPrompt(notes), {
-    label: "Answering your questions",
-    file: REVIEW,
-    mode: "review",
-    model: planner(),
-    system: t.reviewerSystem(),
-  })
-
-/** Fix every `nit` note in one turn. */
-export const fixNits = (notes: readonly t.NoteInput[]): Promise<void> =>
-  t.agentWithSkills("review.fix.nits.fixing", t.buildReviewFixNitsPrompt(notes), {
-    label: "Fixing your nits",
-    file: REVIEW,
-    model: planner(),
-    system: t.reviewerSystem(),
-  })
-
 /** Fix the `Risk:`-marked notes the reviewer named; an empty turn means the risk was judged false. */
 export const fixRisks = (notes: readonly t.NoteInput[]): Promise<void> =>
   t.agentWithSkills("review.fix.risks.fixing", t.buildReviewFixRisksPrompt(notes), {
@@ -191,9 +109,12 @@ export const fixRisks = (notes: readonly t.NoteInput[]): Promise<void> =>
     allowEmpty: true,
   })
 
-export const awaitReview = (base: string): Promise<void> =>
+export const awaitReview = (
+  base: string,
+  message = t.buildReviewAwaitReviewMessage(base),
+): Promise<void> =>
   human("review.await-review", {
-    message: t.buildReviewAwaitReviewMessage(base),
+    message,
     label: "Awaiting your review",
     file: REVIEW,
     mode: "review",
@@ -206,14 +127,3 @@ export const reviewMissing = (round: string): Promise<void> =>
     message: t.buildReviewReviewMissingMessage(round),
     label: "Nothing to review",
   })
-
-/** Turn the review round `capture` describes into `.gtd/REQUIREMENTS.md`, or change nothing. */
-export const collecting = (capture: string): Promise<void> =>
-  t.agentWithSkills("review.collecting", t.buildReviewCollectingPrompt(capture), {
-    label: "Collecting your feedback",
-    file: REQUIREMENTS,
-    mode: "qa",
-    model: planner(),
-    system: t.reviewerSystem(),
-    allowEmpty: true,
-  })