@pmelab/gtd 27.2.0 → 27.3.0

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

@@ -13,6 +13,8 @@ describe("retryQuestion", () => {
   })
 })
 
+type W = { write(p: string, c: string): void }
+
 describe("gate guard", () => {
   const config = (guard: string) =>
     [
@@ -23,9 +25,8 @@ describe("gate guard", () => {
     ].join("\n")
 
   const red = {
-    first: (_: unknown, r: { write(p: string, c: string): void }) => r.write("f", "1\n"),
-    "suite.check": (_: unknown, r: { write(p: string, c: string): void }) =>
-      r.write(".gtd/FEEDBACK.md", "red\n"),
+    first: (_: unknown, r: W) => r.write("f", "1\n"),
+    "suite.check": (_: unknown, r: W) => r.write(".gtd/FEEDBACK.md", "red\n"),
   }
 
   it("runs the guard after a blocked landing and lets its refusal stop it", async () => {
@@ -50,3 +51,66 @@ describe("gate guard", () => {
     expect(rest.state).toBe("suite.blocked")
   })
 })
+
+describe("healthy describeGuard", () => {
+  const config = (options: string) =>
+    [
+      `import { healthy } from "@pmelab/gtd/workflows"`,
+      `import { agent, read, refuse } from "@pmelab/gtd/flows"`,
+      `const describeGuard = () => { refuse("describe-guarded: nope") }`,
+      `const guard = () => { refuse("guarded: nope") }`,
+      `export const held = async () => { await agent("first", "go"); await healthy(() => agent("fix", "go"), ${options}) }`,
+      `export default held`,
+    ].join("\n")
+
+  let runs = 0
+  const handlers = (extra: Record<string, unknown>) => ({
+    "health.check": (_: unknown, r: W) => r.write(".gtd/FEEDBACK.md", `red ${runs++}\n`),
+    "health.judge": () => '[{"id":"verdict","answer":"progress","p":0.9}]',
+    fix: (_: unknown, r: W) => r.write("f", `${runs}\n`),
+    first: (_: unknown, r: W) => r.write("start", "1\n"),
+    ...extra,
+  })
+  const make = (options: string) =>
+    testRepo({ workflow: config(options), env: { GTD_TEST_COMMAND: "true" } })
+
+  it("runs after a describe landing and its refusal stops the turn", async () => {
+    runs = 0
+    const repo = make("{ describeGuard }")
+    await repo.start("held")
+    await expect(repo.drive(handlers({ "health.describe": () => undefined }))).rejects.toThrow(
+      "describe-guarded: nope",
+    )
+  })
+
+  it("never runs after the human stop rest", async () => {
+    runs = 0
+    // Refuses only once a person's edit exists, which only a post-stop run can see.
+    const repo = make(
+      '{ describeGuard: () => { if (read("human.txt") !== undefined) refuse("describe-guarded: late") } }',
+    )
+    await repo.start("held")
+    const rest = await repo.drive(handlers({ "health.describe": () => undefined }))
+    expect(rest.state).toBe("health.stop")
+    const after = await repo.drive(
+      handlers({ "health.stop": (_: unknown, r: W) => r.write("human.txt", "edit\n") }),
+    )
+    expect(after.state).not.toBe("health.stop")
+  })
+
+  it("keeps guard running after describe", async () => {
+    runs = 0
+    // Refuses only once the describe turn has written its analysis.
+    const repo = make(
+      '{ guard: () => { if (read(".gtd/ESCALATION.md") !== undefined) refuse("guarded: nope") } }',
+    )
+    await repo.start("held")
+    await expect(
+      repo.drive(
+        handlers({
+          "health.describe": (_: unknown, r: W) => r.write(".gtd/ESCALATION.md", "why\n"),
+        }),
+      ),
+    ).rejects.toThrow("guarded: nope")
+  })
+})

package/src/workflows/shared/health.ts

@@ -38,9 +38,9 @@ export const guarded =
     guard?.()
   }
 
-const guardedSteps = (guard?: Guard): kit.EscalationSteps => ({
+const guardedSteps = (guard?: Guard, describeGuard?: Guard): kit.EscalationSteps => ({
   limit: escalationSteps.limit,
-  describe: guarded(escalationSteps.describe, guard),
+  describe: guarded(guarded(escalationSteps.describe, guard), describeGuard),
   stop: guarded(escalationSteps.stop, guard),
   exhausted: guarded(escalationSteps.exhausted, guard),
 })
@@ -98,6 +98,8 @@ export interface HealthOptions {
   readonly sweepOnGreen?: readonly string[]
   /** Runs after every fix and escalation turn. */
   readonly guard?: Guard | undefined
+  /** Runs after the escalation's agent turn only; the human rests stay unguarded. */
+  readonly describeGuard?: Guard | undefined
 }
 
 const runSuite = (options: HealthOptions): Promise<boolean> =>
@@ -121,7 +123,7 @@ export const healthy = (fix: () => Promise<void>, options: HealthOptions = {}):
     fixesSoFar: options.fixesSoFar ?? 0,
     sameFailure,
     escalations: options.escalations ?? { rounds: 0 },
-    escalation: guardedSteps(options.guard),
+    escalation: guardedSteps(options.guard, options.describeGuard),
   })
 
 /**

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

@@ -32,6 +32,14 @@ describe("the shipped workflow factories", () => {
     })
   })
 
+  it("default refactorFlagPattern to GTD_FLAG_ matches and let a factory override win", () => {
+    expect(defaults.refactorFlagPattern).toBe("\\bGTD_FLAG_\\w+")
+    expect(configure(feature({ refactorFlagPattern: "\\bFF_\\w+" }))).toMatchObject({
+      ok: true,
+      build: { defaults: { refactorFlagPattern: "\\bFF_\\w+" } },
+    })
+  })
+
   it("build the shipped settings unchanged with no options", () => {
     for (const factory of [feature, fix, review]) {
       expect(configure(factory)).toMatchObject({ ok: true, build: { defaults, envDefaults } })

package/src/workflows/shared/options.ts

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

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

@@ -26,6 +26,9 @@ describe("the bundled workflow's skills export", () => {
         "build.review.fix.nits",
         "build.review.fix.risks",
         "notes",
+        "refactor",
+        "refactor.fix.suite",
+        "refactor.health",
         "build.quality.correctness",
         "build.quality.owasp-security",
         "build.quality.ponytail-review",
@@ -57,6 +60,9 @@ describe("the bundled workflow's skills export", () => {
       "build.review.fix.nits": ["incremental-implementation", "code-simplification"],
       "build.review.fix.risks": ["debugging-and-error-recovery", "incremental-implementation"],
       notes: ["incremental-implementation", "code-simplification"],
+      refactor: ["ponytail"],
+      "refactor.fix.suite": ["ponytail", "debugging-and-error-recovery"],
+      "refactor.health": ["ponytail", "debugging-and-error-recovery"],
     })
   })
 

package/src/workflows/shared/skills.ts

@@ -4,7 +4,7 @@ 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
 // nested scope with no entry inherits its parent's; group scopes
-// (`packages.item.fix`, `build.fix`, `build.review.fix`, `build.quality`) run
+// (`packages.item.fix`, `build.fix`, `build.review.fix`, `build.quality`, `refactor.fix`) run
 // no turn and carry no key. `build.quality.<lens>` is one key per
 // `qualityReviews` entry, so the export is a function of the vars.
 export const skills = (
@@ -25,6 +25,10 @@ export const skills = (
   "build.review.fix.risks": ["debugging-and-error-recovery", "incremental-implementation"],
   // `fix`'s turn over the notes a review handed on.
   notes: ["incremental-implementation", "code-simplification"],
+  // Every refactor agent turn loads `ponytail`.
+  refactor: ["ponytail"],
+  "refactor.fix.suite": ["ponytail", "debugging-and-error-recovery"],
+  "refactor.health": ["ponytail", "debugging-and-error-recovery"],
   ...lensScopes(
     "build.quality",
     lensesOf(vars.qualityReviews ?? ""),

package/src/workflows/shared/text.ts

@@ -422,6 +422,41 @@ ${fixFeedbackPrompt}
 - Leave everything uncommitted and finish your turn — do not commit
 `
 
+const refactorRules = (strays: readonly string[], pattern: string): string =>
+  `- Behaviour-neutral: the suite's outcome must not change
+- Change only these paths, nothing else — a test file only when it is
+  one of them:
+${strays.map((path) => `  - \`${path}\``).join("\n")}
+- Introduce no new flag read and add no second read of an existing one:
+  every match of \`${pattern}\` may move, never increase in number`
+
+export const refactorBuildingPrompt = (
+  pkg: string,
+  strays: readonly string[],
+  pattern: string,
+  reference?: string,
+): string =>
+  `${stateFileRules}
+- The package to implement is \`${pkg}\`; never delete it
+${refactorRules(strays, pattern)}
+${
+  reference === undefined
+    ? ""
+    : `- Reference only: \`git show ${reference} -- ${strays.map(quote).join(" ")}\` shows an
+  earlier attempt at this change. Read it for ideas; never apply,
+  cherry-pick or check it out — write a fresh refactor
+`
+}- Leave everything uncommitted and finish your turn — do not commit
+`
+
+export const refactorFixPrompt = (strays: readonly string[], pattern: string): string =>
+  `${stateFileRules}
+${fixFeedbackPrompt}
+${refactorRules(strays, pattern)}
+- Never do another package's work, even when it would green the suite
+- Leave everything uncommitted and finish your turn — do not commit
+`
+
 export const healthJudgeMessage = (): string =>
   `The check is still red, and this isn't the first round —
 \`.gtd/FEEDBACK.md\` holds this round's output, and the previous round's

package/src/workflows/shared/vars.ts

@@ -11,6 +11,7 @@ export const defaults: Readonly<Record<string, string>> = {
   judgeIdenticalMinP: "0.7",
   reviewNoteActionable: "0.7",
   reviewSeverityMinP: "0.7",
+  refactorFlagPattern: "\\bGTD_FLAG_\\w+",
   // Decides the turn count: one `build.quality.<lens>` scope per entry, each
   // keyed in `./skills.ts`.
   qualityReviews: