@pmelab/gtd 27.1.0 → 27.3.0

package/src/workflows/shared/registry.ts

@@ -0,0 +1,158 @@
+import { read, refuse } from "../../flows/index.js"
+
+// The registry is read as TEXT: workflows may not import `src/flags/`, and this
+// also lets a repository point at its own registry file.
+
+export interface RegistryEntry {
+  readonly kind: string
+  readonly defaultOn: boolean
+}
+
+// Filler for masked text: a non-word char, so `/*x*/kind` still has a `\b` before `kind`.
+const FILL = "\u0001"
+
+// Same length as `text`, with string contents and comments filled with FILL, so
+// a hit inside either (a JSDoc example, `owner: "defaultOn: true"`) is rejected.
+const commentLength = (rest: string): number => {
+  const end = rest.startsWith("//") ? rest.indexOf("\n") : rest.indexOf("*/") + 2
+  return end <= 0 ? rest.length : end
+}
+
+// Index of the closing quote of the string opened at `i` (or text end).
+const stringEnd = (text: string, i: number, quote: string): number => {
+  let j = i + 1
+  while (j < text.length && text[j] !== quote) j += text[j] === "\\" ? 2 : 1
+  return Math.min(j, text.length)
+}
+
+const mask = (text: string): string => {
+  let out = ""
+  let i = 0
+  while (i < text.length) {
+    const c = text[i] as string
+    const rest = text.slice(i)
+    if (rest.startsWith("//") || rest.startsWith("/*")) {
+      const len = commentLength(rest)
+      out += FILL.repeat(len)
+      i += len
+    } else if (c === '"' || c === "'" || c === "`") {
+      const j = stringEnd(text, i, c)
+      out += c + FILL.repeat(j - i - 1) + (j < text.length ? c : "")
+      i = j + 1
+    } else {
+      out += c
+      i += 1
+    }
+  }
+  return out
+}
+
+const escapeRegExp = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+
+// Entries are flat object literals, so the nearest braces around the name delimit one.
+const entrySpan = (text: string, name: string) => {
+  const quoted = escapeRegExp(name)
+  const re = new RegExp(`\\bname\\s*:\\s*(["'\`])${quoted}\\1`, "g")
+  const masked = mask(text)
+  for (const hit of text.matchAll(re)) {
+    if (masked[hit.index] === FILL) continue
+    const start = masked.lastIndexOf("{", hit.index)
+    const close = masked.indexOf("}", hit.index)
+    return start < 0 || close < 0 ? undefined : { start, end: close + 1 }
+  }
+  return undefined
+}
+
+const DEFAULT_ON = /\bdefaultOn\s*:\s*(true|false)\s*,?/
+
+// `defaultOn` as a property of `body`, never one inside a string or comment.
+const defaultOnHit = (body: string) => DEFAULT_ON.exec(mask(body))
+
+const defaultOnValue = (body: string): string | undefined => defaultOnHit(body)?.[1]
+
+const KIND = /\bkind\s*:\s*["'`]/
+
+export const registryEntry = (text: string, name: string): RegistryEntry | undefined => {
+  const span = entrySpan(text, name)
+  if (span === undefined) return undefined
+  const body = text.slice(span.start, span.end)
+  const hit = KIND.exec(mask(body))
+  const kind = hit === null ? null : /^(\w+)["'`]/.exec(body.slice(hit.index + hit[0].length))
+  return {
+    kind: kind?.[1] ?? "",
+    defaultOn: defaultOnValue(body) === "true",
+  }
+}
+
+// Drops the `defaultOn` property, then whitespace and trailing commas outside strings.
+const canonical = (body: string): string => {
+  const hit = defaultOnHit(body)
+  const kept =
+    hit === null ? body : body.slice(0, hit.index) + body.slice(hit.index + hit[0].length)
+  const masked = mask(kept)
+  // UTF-16 units, to match `masked` indexing; code points would drift after a surrogate pair
+  return kept
+    .split("")
+    .filter(
+      (c, i) =>
+        masked[i] === FILL || !(/\s/.test(c) || (c === "," && /^\s*}/.test(masked.slice(i + 1)))),
+    )
+    .join("")
+}
+
+/**
+ * [] when `after` differs from `before` only by the named entry's `defaultOn`
+ * going absent/false → true (whitespace and trailing commas inside that entry
+ * ignored, so oxfmt re-wrapping it passes); else one line per fault.
+ */
+export const flipProblems = (before: string, after: string, name: string): readonly string[] => {
+  const was = entrySpan(before, name)
+  const now = entrySpan(after, name)
+  if (was === undefined) return [`no entry "${name}" before the turn`]
+  if (now === undefined) return [`entry "${name}" is gone`]
+  const faults: string[] = []
+  if (before.slice(0, was.start) !== after.slice(0, now.start)) {
+    faults.push("text before the entry changed")
+  }
+  if (before.slice(was.end) !== after.slice(now.end)) faults.push("text after the entry changed")
+  const oldBody = before.slice(was.start, was.end)
+  const newBody = after.slice(now.start, now.end)
+  if (canonical(oldBody) !== canonical(newBody))
+    faults.push(`entry "${name}" changed beyond defaultOn`)
+  if (defaultOnValue(newBody) !== "true") faults.push(`"${name}" is not set to defaultOn: true`)
+  return faults
+}
+
+/** `path:line` for every `GTD_FLAG_<NAME>` in shipped sources; re-states scripts/lint-flags.ts' rule by hand. */
+export const flagReferences = (
+  files: readonly { readonly path: string; readonly text: string }[],
+  name: string,
+): readonly string[] => {
+  const pattern = new RegExp(`\\bGTD_FLAG_${escapeRegExp(name.toUpperCase())}\\b`)
+  return files
+    .filter(({ path }) => !/\.(test|fixture|stories)\.tsx?$/.test(path))
+    .flatMap(({ path, text }) =>
+      text.split("\n").flatMap((line, i) => (pattern.test(line) ? [`${path}:${i + 1}`] : [])),
+    )
+}
+
+export const requireFlag = (
+  workflow: "rollout" | "cleanup",
+  registryPath: string,
+  name: string,
+  defaultOn: boolean,
+): void => {
+  if (name === "") return refuse(`gtd: ${workflow} needs --var flag=<name>`)
+  const entry = registryEntry(read(registryPath) ?? "", name)
+  if (entry === undefined) return refuse(`gtd: ${workflow}: no flag "${name}" in ${registryPath}`)
+  if (entry.kind !== "release") {
+    return refuse(`gtd: ${workflow}: flag "${name}" is ${entry.kind}, not release`)
+  }
+  if (entry.defaultOn !== defaultOn) {
+    return refuse(
+      defaultOn
+        ? `gtd: ${workflow}: flag "${name}" is not default-on — roll it out first`
+        : `gtd: ${workflow}: flag "${name}" is already default-on`,
+    )
+  }
+}

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/tail.test.ts

@@ -5,6 +5,7 @@ import {
   type CodeThreadInfo,
   type StepRequest,
 } from "../../flows/index.js"
+import type { Guard } from "./health.js"
 import { handOffReview, REVIEW_ORIG } from "./tail.js"
 import { fixtureContext } from "./text.fixture.js"
 
@@ -30,7 +31,11 @@ const reviewDoc = (note: string): string =>
  */
 const handOff = async (
   after: string | "deleted" | "unwritten",
-  extra: { paths?: readonly string[]; codeThreads?: readonly CodeThreadInfo[] } = {},
+  extra: {
+    paths?: readonly string[]
+    codeThreads?: readonly CodeThreadInfo[]
+    guard?: Guard
+  } = {},
 ) => {
   const log: string[] = []
   const scripts = new Map<string, string>()
@@ -87,7 +92,7 @@ const handOff = async (
       },
     ),
   )
-  const refusal = await handOffReview("base", { rounds: 0 }).then(
+  const refusal = await handOffReview("base", { rounds: 0 }, extra.guard).then(
     () => undefined,
     (e: unknown) => (e as Error).message,
   )
@@ -162,4 +167,33 @@ describe("the hand-off review", () => {
     expect(run.refusal).toMatch(/was deleted — restore it, or leave a note to hand to fix/)
     expect(run.log).toEqual(["review.reviewing", "review.await-review"])
   })
+
+  describe("guard", () => {
+    it("runs after the reviewing turn and never after the human's await-review landing", async () => {
+      const seen: string[] = []
+      const run = await handOff(reviewDoc("new add function"), {
+        guard: () => seen.push("guard"),
+      })
+      expect(run.log).toEqual(["review.reviewing", "review.await-review", "review.closing"])
+      expect(seen).toEqual(["guard"])
+    })
+
+    it("a refusal after reviewing stops the round before the human gate", async () => {
+      const run = await handOff(reviewDoc("new add function"), {
+        guard: () => {
+          throw new Error("guarded: nope")
+        },
+      })
+      expect(run.refusal).toBe("guarded: nope")
+      expect(run.log).toEqual(["review.reviewing"])
+    })
+
+    it("does not run after review-missing", async () => {
+      let calls = 0
+      const run = await handOff("unwritten", { guard: () => void calls++ })
+      expect(run.log).toContain("review.review-missing")
+      // the fixture aborts the second reviewing turn: only the first was guarded
+      expect(calls).toBe(1)
+    })
+  })
 })

package/src/workflows/shared/tail.ts

@@ -1,6 +1,13 @@
 import { read, refuse, removeScript, run, scope, showScript, vars } from "../../flows/index.js"
 import * as kit from "../../workflow-kit/index.js"
-import { escalation, FIX_CAP, healthy, type EscalationCount } from "./health.js"
+import {
+  escalation,
+  FIX_CAP,
+  guarded,
+  healthy,
+  type EscalationCount,
+  type Guard,
+} from "./health.js"
 import {
   awaitReview,
   fixCheck,
@@ -22,16 +29,16 @@ export const REVIEW_ORIG = ".gtd/REVIEW.orig.md"
  * finding to `.gtd/QUALITY.md`. Resolves `"findings"` when that file
  * has any.
  */
-export const qualityLap = (): Promise<"clean" | "findings"> =>
-  kit.qualityLap(kit.lensesOf(vars.qualityReviews ?? ""), reviewQuality, QUALITY)
+export const qualityLap = (guard?: Guard): Promise<"clean" | "findings"> =>
+  kit.qualityLap(kit.lensesOf(vars.qualityReviews ?? ""), guarded(reviewQuality, guard), QUALITY)
 
 /** Resolves `true` once `.gtd/QUALITY.md` is resolved, `false` when the fix cap escalated instead. */
-export const fixQualityFindings = (escalations: EscalationCount): Promise<boolean> =>
+export const fixQualityFindings = (escalations: EscalationCount, guard?: Guard): Promise<boolean> =>
   kit.fixFindings({
-    fix: fixQuality,
+    fix: guarded(fixQuality, guard),
     findings: QUALITY,
     cap: FIX_CAP,
-    escalate: () => escalation(escalations),
+    escalate: () => escalation(escalations, guard),
   })
 
 /** `.gtd/REVIEW.md` removed at the end of a round at commit `round`. */
@@ -59,21 +66,22 @@ export const tail = <T>(
   fixFirst: boolean,
   finish: (escalations: EscalationCount) => Promise<T>,
   green = false,
+  guard?: Guard,
 ): Promise<T> =>
   scope("build", async () => {
     const escalations: EscalationCount = { rounds: 0 }
     const fix = fixCheck
     const repair = async () => {
-      await fix()
-      await healthy(fix, { fixesSoFar: 1, escalations })
+      await guarded(fix, guard)()
+      await healthy(fix, { fixesSoFar: 1, escalations, guard })
     }
     // fixFirst's own fix + healthy below already is the full run.
     if (fixFirst) await repair()
-    else if (!green) await healthy(fix, { escalations })
+    else if (!green) await healthy(fix, { escalations, guard })
     // The lap runs once a tail: after its findings are fixed, review follows.
-    if ((await qualityLap()) === "findings") {
-      if (await fixQualityFindings(escalations)) {
-        await healthy(fix, { escalations })
+    if ((await qualityLap(guard)) === "findings") {
+      if (await fixQualityFindings(escalations, guard)) {
+        await healthy(fix, { escalations, guard })
       } else await repair()
     }
     return finish(escalations)
@@ -84,12 +92,16 @@ export const tail = <T>(
  * `.gtd/REVIEW.md`; a note leaves it, with the reviewer's own version as
  * `REVIEW_ORIG`, for the next `fix` to read — never a re-plan.
  */
-export const handOffReview = (base: string, escalations: EscalationCount): Promise<void> =>
+export const handOffReview = (
+  base: string,
+  escalations: EscalationCount,
+  guard?: Guard,
+): Promise<void> =>
   kit.reviewToHandOff(base, {
     file: REVIEW,
-    reviewing,
-    fixRisks,
-    keepGreen: () => healthy(fixCheck, { escalations }),
+    reviewing: guarded(reviewing, guard),
+    fixRisks: guarded(fixRisks, guard),
+    keepGreen: () => healthy(fixCheck, { escalations, guard }),
     awaitReview: (b) => awaitReview(b, t.handOffAwaitReviewMessage(b)),
     reviewMissing,
     close: closeReview,
@@ -107,5 +119,5 @@ export const handOffReview = (base: string, escalations: EscalationCount): Promi
   })
 
 /** The tail the review and fix workflows run: ends at the hand-off review since `base`. */
-export const handOffTail = (fixFirst: boolean, base: string): Promise<void> =>
-  tail(fixFirst, (escalations) => handOffReview(base, escalations))
+export const handOffTail = (fixFirst: boolean, base: string, guard?: Guard): Promise<void> =>
+  tail(fixFirst, (escalations) => handOffReview(base, escalations, guard), false, guard)

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: