@pmelab/gtd 38.1.0 → 39.0.0

package/src/cli/Metrics.ts

@@ -0,0 +1,318 @@
+import { Effect, Option } from "effect"
+import { GitService } from "../platform/index.js"
+import { parseCommitMessage } from "../replay/index.js"
+import { UNATTRIBUTED_MODEL } from "../wire/index.js"
+import { historyEntries, resolveHistoryRef, type HistoryEntry } from "./History.js"
+import { writeJson, type ArtifactOut, type CommandRequirements, type JsonMode } from "./Output.js"
+
+// Read from commit subjects and trailers alone, never by replay: a metric over
+// old histories must not refuse because today's config has moved on. The step
+// names below are the bundled feature workflow's public ones.
+
+const QUALITY = ".gtd/QUALITY.md"
+
+export interface MetricCommit {
+  readonly message: string
+  /** Findings this commit added to the quality lap's file; only a reviewing turn's count is read. */
+  readonly findings: number
+}
+
+export interface Metrics {
+  readonly slices: {
+    readonly decided: number
+    readonly landed: number
+    readonly rebuilt: number
+    readonly refactored: number
+  }
+  /** `rebuilt / decided`, to three places; null without a decision. */
+  readonly refactorFirstRate: number | null
+  /** Continuation turns per phase, keyed by the step without its `continue` segment. */
+  readonly continuations: Readonly<Record<string, number>>
+  readonly cost: {
+    readonly total: number
+    readonly byModel: Readonly<Record<string, number>>
+    readonly byPhase: {
+      readonly naive: number
+      readonly refactor: number
+      readonly implement: number
+      readonly other: number
+    }
+    /** A rebuilt slice's naive pass and the implement turns that rebuilt it. */
+    readonly doubleWork: {
+      readonly naive: number
+      readonly rebuild: number
+      readonly total: number
+    }
+  }
+  readonly findings: { readonly total: number; readonly byLens: Readonly<Record<string, number>> }
+  /** Keyed by the re-check's full step name, from its subject: the mark's value is scope-relative. */
+  readonly flaky: { readonly total: number; readonly byStep: Readonly<Record<string, number>> }
+}
+
+type Phase = keyof Metrics["cost"]["byPhase"]
+
+// Keyed by the lap's path without `.reviewing`, so the refactor lap's lenses stay apart from the feature's.
+const LENS = /^((?:.*\.)?quality\.[^.]+)\.reviewing$/
+
+const CONTINUE = /(^|\.)continue\./
+
+const inSeam = (step: string): boolean => step.startsWith("seam.")
+
+// A naive retry after a continuation runs under `seam.fresh.naive`: any seam step named `naive` is the pass.
+const phaseOf = (step: string): Phase => {
+  const scope = step.split(".")[0]
+  if (inSeam(step) && step.endsWith(".naive")) return "naive"
+  if (step === "seam.note" || scope === "refactor") return "refactor"
+  if (scope === "implement") return "implement"
+  return "other"
+}
+
+const round = (n: number, places = 6): number => {
+  const f = 10 ** places
+  return Math.round(n * f) / f
+}
+
+// Keys are model, step and lens names from history: a prototype-free record keeps `constructor` a plain key.
+const record = (): Record<string, number> => Object.create(null) as Record<string, number>
+
+const add = (into: Record<string, number>, key: string, n: number): void => {
+  into[key] = (into[key] ?? 0) + n
+}
+
+const roundAll = (record: Record<string, number>): Record<string, number> =>
+  Object.fromEntries(Object.entries(record).map(([k, v]) => [k, round(v)]))
+
+interface Tally {
+  readonly slices: { decided: number; landed: number; rebuilt: number; refactored: number }
+  readonly continuations: Record<string, number>
+  readonly byModel: Record<string, number>
+  readonly byPhase: Record<Phase, number>
+  readonly doubleWork: { naive: number; rebuild: number }
+  readonly byLens: Record<string, number>
+  readonly flaky: Record<string, number>
+}
+
+const emptyTally = (): Tally => ({
+  slices: { decided: 0, landed: 0, rebuilt: 0, refactored: 0 },
+  continuations: record(),
+  byModel: record(),
+  byPhase: { naive: 0, refactor: 0, implement: 0, other: 0 },
+  doubleWork: { naive: 0, rebuild: 0 },
+  byLens: record(),
+  flaky: record(),
+})
+
+const sum = (record: Readonly<Record<string, number>>): number =>
+  Object.values(record).reduce((a, b) => a + b, 0)
+
+const finish = (t: Tally): Metrics => ({
+  slices: t.slices,
+  refactorFirstRate: t.slices.decided === 0 ? null : round(t.slices.rebuilt / t.slices.decided, 3),
+  continuations: t.continuations,
+  cost: {
+    total: round(sum(t.byModel)),
+    byModel: roundAll(t.byModel),
+    byPhase: roundAll(t.byPhase) as Metrics["cost"]["byPhase"],
+    doubleWork: {
+      naive: round(t.doubleWork.naive),
+      rebuild: round(t.doubleWork.rebuild),
+      total: round(t.doubleWork.naive + t.doubleWork.rebuild),
+    },
+  },
+  findings: { total: sum(t.byLens), byLens: t.byLens },
+  flaky: { total: sum(t.flaky), byStep: t.flaky },
+})
+
+/** The open slice: its naive cost so far, and whether its implement turns rebuild it. */
+interface Slice {
+  naive: number
+  rebuilding: boolean
+  /** Landed, not yet applied, with its naive cost: an apply that fails turns it into a rebuild. */
+  applying: number | undefined
+}
+
+const tallyCost = (
+  t: Tally,
+  open: Slice,
+  costs: ReturnType<typeof parseCommitMessage>["cost"],
+  phase: Phase,
+): void => {
+  for (const { cost, model } of costs) {
+    add(t.byModel, model ?? UNATTRIBUTED_MODEL, cost)
+    t.byPhase[phase] += cost
+    if (phase === "naive") open.naive += cost
+    if (phase === "implement" && open.rebuilding) t.doubleWork.rebuild += cost
+  }
+}
+
+/** A slice is decided where its turns leave the seam: for `implement.applying` the naive pass landed — unless it fails to apply and is built afresh — anywhere else it is rebuilt. */
+const tallyDecision = (t: Tally, open: Slice, at: string, to: string): void => {
+  // The slice's closing ends its rebuild: later implement turns (an amend after review) are new work.
+  if (at === "implement.closing") open.rebuilding = false
+  if (open.applying !== undefined && at === "implement.applying") {
+    const naive = open.applying
+    open.applying = undefined
+    if (to !== "implement.building") return
+    t.slices.landed--
+    rebuild(t, open, naive)
+    return
+  }
+  if (!inSeam(at) || inSeam(to)) return
+  t.slices.decided++
+  const naive = open.naive
+  open.naive = 0
+  if (to === "implement.applying") {
+    open.applying = naive
+    open.rebuilding = false
+    t.slices.landed++
+    return
+  }
+  rebuild(t, open, naive)
+  if (at === "seam.note") t.slices.refactored++
+}
+
+const rebuild = (t: Tally, open: Slice, naive: number): void => {
+  open.rebuilding = true
+  t.slices.rebuilt++
+  t.doubleWork.naive += naive
+}
+
+/** Oldest first; a commit gtd did not write is skipped. */
+export const processMetrics = (commits: readonly MetricCommit[]): Metrics => {
+  const t = emptyTally()
+  const open: Slice = { naive: 0, rebuilding: false, applying: undefined }
+  for (const commit of commits) {
+    const message = parseCommitMessage(commit.message)
+    const subject = message.parsed
+    if (subject === undefined) continue
+    const at = subject.from ?? subject.to
+    tallyCost(t, open, message.cost, phaseOf(at))
+    if (subject.actor === "agent" && CONTINUE.test(at))
+      add(t.continuations, at.replace(CONTINUE, "$1"), 1)
+    const lens = LENS.exec(at)?.[1]
+    if (lens !== undefined && commit.findings > 0) add(t.byLens, lens, commit.findings)
+    if (message.marks.some((m) => m.name === "flaky")) add(t.flaky, at, 1)
+    tallyDecision(t, open, at, subject.to)
+  }
+  return finish(t)
+}
+
+export const totalMetrics = (all: readonly Metrics[]): Metrics & { readonly processes: number } => {
+  const t = emptyTally()
+  for (const m of all) {
+    for (const key of Object.keys(t.slices) as (keyof Tally["slices"])[])
+      t.slices[key] += m.slices[key]
+    for (const [k, v] of Object.entries(m.continuations)) add(t.continuations, k, v)
+    for (const [k, v] of Object.entries(m.cost.byModel)) add(t.byModel, k, v)
+    for (const key of Object.keys(t.byPhase) as Phase[]) t.byPhase[key] += m.cost.byPhase[key]
+    t.doubleWork.naive += m.cost.doubleWork.naive
+    t.doubleWork.rebuild += m.cost.doubleWork.rebuild
+    for (const [k, v] of Object.entries(m.findings.byLens)) add(t.byLens, k, v)
+    for (const [k, v] of Object.entries(m.flaky.byStep)) add(t.flaky, k, v)
+  }
+  return { processes: all.length, ...finish(t) }
+}
+
+const chunks = (content: string | undefined): number =>
+  content === undefined ? 0 : (content.match(/^## /gm) ?? []).length
+
+export interface ProcessMetrics extends Metrics {
+  /** The opening commit's `Gtd-Workflow`; null for the default workflow. */
+  readonly workflow: string | null
+}
+
+export const readProcessMetrics = (
+  entry: Pick<HistoryEntry, "entry" | "tip">,
+): Effect.Effect<ProcessMetrics, Error, GitService> =>
+  Effect.gen(function* () {
+    const git = yield* GitService
+    const base = Option.getOrUndefined(yield* git.readRefOption(`${entry.entry}^`))
+    const commits = yield* git.commitHistory(base, entry.tip)
+    const quality = (hash: string) =>
+      git.readFileAtRef(hash, QUALITY).pipe(
+        Effect.map((content): string | undefined => content),
+        Effect.orElseSucceed(() => undefined),
+      )
+    // Only a commit that touched the file changes it: carry the last content forward.
+    let count = chunks(base === undefined ? undefined : yield* quality(base))
+    const read: MetricCommit[] = []
+    for (const { hash, message, touched } of commits) {
+      const before = count
+      if (touched.includes(QUALITY)) count = chunks(yield* quality(hash))
+      read.push({ message, findings: Math.max(0, count - before) })
+    }
+    const workflow =
+      commits[0] === undefined ? undefined : parseCommitMessage(commits[0].message).workflow
+    return { workflow: workflow ?? null, ...processMetrics(read) }
+  })
+
+// Keys come from fetched history: never let them put control bytes on a terminal.
+// eslint-disable-next-line no-control-regex -- the control range IS the point
+const printable = (s: string): string => s.replace(/[\x00-\x1f\x7f-\x9f\u2028\u2029]/g, "?")
+
+const listed = (record: Readonly<Record<string, number>>): string =>
+  Object.entries(record)
+    .map(([k, v]) => `${printable(k)} ${v}`)
+    .join(", ")
+
+const line = (label: string, m: Metrics): string => {
+  const { slices, cost } = m
+  const percent = m.refactorFirstRate === null ? "-" : `${Math.round(m.refactorFirstRate * 100)}%`
+  const continued = sum(m.continuations)
+  return [
+    `${label}: ${slices.decided} slices, ${slices.rebuilt} rebuilt (refactor-first ${percent}), ${slices.refactored} refactored`,
+    `${continued} continuations${continued > 0 ? ` (${listed(m.continuations)})` : ""}`,
+    `cost ${cost.total} (${listed(cost.byPhase)}; by model ${listed(cost.byModel) || "-"}), double work ${cost.doubleWork.total}`,
+    `${m.findings.total} findings${m.findings.total > 0 ? ` (${listed(m.findings.byLens)})` : ""}`,
+    `${m.flaky.total} flaky${m.flaky.total > 0 ? ` (${listed(m.flaky.byStep)})` : ""}`,
+  ].join("; ")
+}
+
+export const runHistoryMetricsCommand = (
+  refs: readonly string[],
+  json: JsonMode,
+  out: ArtifactOut,
+): Effect.Effect<void, Error, CommandRequirements> =>
+  Effect.gen(function* () {
+    const entries = yield* historyEntries
+    const chosen =
+      refs.length === 0
+        ? entries
+        : (yield* Effect.forEach(refs, (ref) =>
+            // A branch name means every process kept from it, not just its newest.
+            resolveHistoryRef(ref, entries).pipe(
+              Effect.map((hit) =>
+                hit.branch === ref ? entries.filter((e) => e.branch === ref) : [hit],
+              ),
+            ),
+          )).flat()
+    const unique = chosen.filter((e, i) => chosen.findIndex((o) => o.ref === e.ref) === i)
+    const processes = yield* Effect.forEach(
+      unique,
+      (e) =>
+        readProcessMetrics(e).pipe(
+          Effect.map((metrics) => ({
+            ref: e.ref,
+            entry: e.entry,
+            branch: e.branch,
+            tip: e.tip,
+            ...metrics,
+          })),
+        ),
+      { concurrency: 4 },
+    )
+    const document = { processes, total: totalMetrics(processes) }
+    if (yield* writeJson(json, out, document)) return
+    if (processes.length === 0) {
+      out.write("no history refs; run gtd history fetch | sh to pull them\n")
+      return
+    }
+    const lines = processes.map((p) =>
+      line(
+        `${p.entry.slice(0, 7)} ${printable(p.branch ?? "-")}${p.workflow === null ? "" : ` (${printable(p.workflow)})`}`,
+        p,
+      ),
+    )
+    lines.push(line(`total (${processes.length} processes)`, document.total))
+    out.write(`${lines.join("\n")}\n`)
+  })

package/src/cli/Output.ts

@@ -68,3 +68,16 @@ export type CommandRequirements =
   | ToolCommands
 
 export type SuccessExit = typeof EXIT_OK | typeof EXIT_STRAYS_FOUND
+
+/** Writes `document` per `json` (bare → whole, `=path` → one value); returns false for `off`. */
+export const writeJson = (
+  json: JsonMode,
+  out: ArtifactOut,
+  document: unknown,
+): Effect.Effect<boolean, Error> =>
+  Effect.gen(function* () {
+    if (json.kind === "off") return false
+    if (json.kind === "document") out.write(`${JSON.stringify(document)}\n`)
+    else yield* writeSelection(out, document, json.path)
+    return true
+  })

package/src/cli/Program.test.ts

@@ -1694,6 +1694,7 @@ describe("runCommand — refuses in a repository with no commits", () => {
     judgeRun: { kind: "judgeRun", provider: "fixed" },
     historyList: { kind: "historyList" },
     historyShow: { kind: "historyShow", ref: "x" },
+    historyMetrics: { kind: "historyMetrics", refs: [] },
     historyFetch: { kind: "historyFetch", remote: "origin" },
     strays: { kind: "strays", base: "HEAD", tip: "HEAD", globs: [] },
   }
@@ -1705,7 +1706,7 @@ describe("runCommand — refuses in a repository with no commits", () => {
   const NO_COMMITS_MESSAGE =
     "gtd requires a repository with at least one commit — make an initial commit, then run gtd again"
 
-  it("derives exactly the seventeen non-standalone kinds — a canary for the table-driven cases below", () => {
+  it("derives exactly the eighteen non-standalone kinds — a canary for the table-driven cases below", () => {
     expect(stateKinds.sort()).toEqual(
       [
         "abandon",
@@ -1724,6 +1725,7 @@ describe("runCommand — refuses in a repository with no commits", () => {
         "judgeAnswer",
         "historyList",
         "historyShow",
+        "historyMetrics",
         "historyFetch",
       ].sort(),
     )

package/src/cli/Program.ts

@@ -109,6 +109,7 @@ export {
 } from "./Output.js"
 import { runStraysCommand } from "./Strays.js"
 import { runHistoryFetchCommand, runHistoryListCommand, runHistoryShowCommand } from "./History.js"
+import { runHistoryMetricsCommand } from "./Metrics.js"
 
 /**
  * `Edge.ts`'s `Rest` is module-private (`.gtd/packages/05-step-core.md`
@@ -174,6 +175,7 @@ export type Command =
   | { readonly kind: "judgeAnswer" }
   | { readonly kind: "historyList" }
   | { readonly kind: "historyShow"; readonly ref: string }
+  | { readonly kind: "historyMetrics"; readonly refs: readonly string[] }
   | { readonly kind: "historyFetch"; readonly remote: string }
   | {
       readonly kind: "strays"
@@ -1320,6 +1322,8 @@ const dispatchVoidCommand = (
       return runHistoryListCommand(json, out)
     case "historyShow":
       return runHistoryShowCommand(command.ref, json, out)
+    case "historyMetrics":
+      return runHistoryMetricsCommand(command.refs, json, out)
     case "historyFetch":
       return runHistoryFetchCommand(command.remote, out)
   }

package/src/workflow-kit/health.ts

@@ -44,16 +44,24 @@ export interface Health {
   /** Shared with other callers in the same run of red checks. */
   readonly escalations: EscalationCount
   readonly escalation: EscalationSteps
+  /** Runs the suite once more before a person is asked; `true` ends the loop as if `check` had passed. */
+  readonly recheck?: () => Promise<boolean>
 }
 
 // check() stamps the report with the commit it ran at, so equal failures differ there.
 const STAMP = /\n<!-- gtd check [0-9a-f]+ -->\n?$/
 const stripStamp = (text: string): string => text.replace(STAMP, "\n")
 
+/** `true` when the re-check passed, else the red re-check's report — the one the escalation describes. */
+const recheckReport = async (health: Health): Promise<true | string | undefined> => {
+  if (health.recheck === undefined) return undefined
+  return (await health.recheck()) || stripStamp(read(health.report) ?? "")
+}
+
 /**
  * Loop until the suite is green: check, and on red run `fix` — escalating
  * first once `fixCap` fixes are spent, or `sameFailure` calls the failure
- * identical to the previous round's.
+ * identical to the previous round's, unless `recheck` passes.
  */
 export const healthy = async (fix: () => Promise<void>, health: Health): Promise<void> => {
   let fixes = health.fixesSoFar ?? 0
@@ -67,6 +75,12 @@ export const healthy = async (fix: () => Promise<void>, health: Health): Promise
     const stuck = previous !== undefined && (await health.sameFailure(previous, current))
     previous = current
     if (stuck || fixes >= health.fixCap) {
+      const rechecked = await recheckReport(health)
+      if (rechecked === true) {
+        health.escalations.rounds = 0
+        return
+      }
+      previous = rechecked ?? previous
       await escalation(health.escalations, health.escalation)
       fixes = 0
     }

package/src/workflows/cleanup/cleanup.test.ts

@@ -160,6 +160,7 @@ describe("the cleanup guard over every later agent turn", () => {
         "build.health.check": (_, r) => {
           if (!stopped) r.write(FEEDBACK, `failing ${runs++}\n`)
         },
+        "build.health.recheck": (_, r) => r.write(FEEDBACK, `failing ${runs++}\n`),
         "build.health.describe": () => undefined,
         "build.health.judge": () => '[{"id":"verdict","answer":"progress","p":0.9}]',
         "build.fix": (_, r) => r.write("src/other.ts", `export const n = ${runs}\n`),
@@ -176,6 +177,7 @@ describe("the cleanup guard over every later agent turn", () => {
     await expect(
       driven(guarded("", NO_ACCESS), {
         "build.health.check": (_, r) => r.write(FEEDBACK, `failing ${runs++}\n`),
+        "build.health.recheck": (_, r) => r.write(FEEDBACK, `failing ${runs++}\n`),
         "build.health.judge": () => '[{"id":"verdict","answer":"progress","p":0.9}]',
         "build.fix": (_, r) => r.write("src/other.ts", `export const n = ${runs}\n`),
         "build.health.describe": (_, r) => r.write("src/b.ts", NAMED),

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

@@ -436,6 +436,8 @@ const drive = async (
           checks++
           phase = "check"
         }
+        // Re-runs the red check it follows, so it reads red as well.
+        if (request.kind === "run" && name === "health.recheck") phase = "check"
         return Promise.resolve(
           request.kind === "judge" ? { answers: {}, truncated: [] } : undefined,
         )
@@ -806,6 +808,8 @@ const driveReviewed = async (
     // Red checks apply to the tail's own runs, never the refactor lap's.
     checking = request.name === "health.check" && stack.includes("build")
     if (checking && reds > 0) reds--
+    // Re-runs the red check it follows, so it reads red as well.
+    if (request.name === "health.recheck" && stack.includes("build")) checking = true
   }
   const lensEffects = ["correctness", "ponytail-review", "conventions"].map(
     (lens): [string, () => void] => [

package/src/workflows/rollout/rollout.feature

@@ -157,6 +157,10 @@ Feature: rollout turns one release flag default-on and touches nothing else
       """
       1 test failing
       """
+    And step "rollout.suite.recheck" writes ".gtd/FEEDBACK.md" with:
+      """
+      1 test still failing
+      """
     When gtd starts workflow "rollout" with "--var flag=alpha"
     And the process is driven
     Then the process rests at "rollout.suite.blocked"
@@ -176,6 +180,10 @@ Feature: rollout turns one release flag default-on and touches nothing else
       """
       1 test failing
       """
+    And step "rollout.suite.recheck" writes ".gtd/FEEDBACK.md" with:
+      """
+      1 test still failing
+      """
     When gtd starts workflow "rollout" with "--var flag=alpha"
     And the process is driven
     Then the process rests at "rollout.suite.blocked"
@@ -200,6 +208,10 @@ Feature: rollout turns one release flag default-on and touches nothing else
       """
       1 test failing
       """
+    And step "rollout.suite.recheck" writes ".gtd/FEEDBACK.md" with:
+      """
+      1 test still failing
+      """
     When gtd starts workflow "rollout" with "--var flag=alpha"
     And the process is driven
     Then the process rests at "rollout.suite.blocked"
@@ -229,6 +241,10 @@ Feature: rollout turns one release flag default-on and touches nothing else
       """
       1 test failing
       """
+    And step "rollout.suite.recheck" writes ".gtd/FEEDBACK.md" with:
+      """
+      1 test still failing
+      """
     When gtd starts workflow "rollout" with "--var flag=alpha"
     And the process is driven
     Then the process rests at "rollout.suite.blocked"

package/src/workflows/rollout/rollout.test.ts

@@ -114,6 +114,7 @@ describe("the rollout workflow", () => {
     const rest = await repo.drive({
       "rollout.flipping": (_, r) => r.write("src/flags/index.ts", FLIPPED),
       "rollout.suite.check": (_, r) => r.write(".gtd/FEEDBACK.md", "1 failing\n"),
+      "rollout.suite.recheck": (_, r) => r.write(".gtd/FEEDBACK.md", "still 1 failing\n"),
     })
     expect(rest).toMatchObject({ state: "rollout.suite.blocked", actor: "human" })
   })
@@ -125,6 +126,7 @@ describe("the rollout workflow", () => {
       await repo.drive({
         "rollout.flipping": (_, r) => r.write("src/flags/index.ts", FLIPPED),
         "rollout.suite.check": (_, r) => r.write(".gtd/FEEDBACK.md", "1 failing\n"),
+        "rollout.suite.recheck": (_, r) => r.write(".gtd/FEEDBACK.md", "still 1 failing\n"),
       })
       return repo
     }

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

@@ -27,6 +27,7 @@ describe("gate guard", () => {
   const red = {
     first: (_: unknown, r: W) => r.write("f", "1\n"),
     "suite.check": (_: unknown, r: W) => r.write(".gtd/FEEDBACK.md", "red\n"),
+    "suite.recheck": (_: unknown, r: W) => r.write(".gtd/FEEDBACK.md", "red again\n"),
   }
 
   it("runs the guard after a blocked landing and lets its refusal stop it", async () => {
@@ -66,6 +67,7 @@ describe("healthy describeGuard", () => {
   let runs = 0
   const handlers = (extra: Record<string, unknown>) => ({
     "health.check": (_: unknown, r: W) => r.write(".gtd/FEEDBACK.md", `red ${runs++}\n`),
+    "health.recheck": (_: 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"),

package/src/workflows/shared/health.ts

@@ -4,8 +4,10 @@ import {
   env,
   human,
   judge,
+  mark,
   numeric,
   vars,
+  type CheckOptions,
   type JudgeQuestion,
 } from "../../flows/index.js"
 import * as kit from "../../workflow-kit/index.js"
@@ -19,6 +21,24 @@ export const FIX_CAP = 3
 export const baseline = (name: string, label = "Checking the baseline"): Promise<boolean> =>
   check(name, env.testCommand ?? "", { report: FEEDBACK, label })
 
+/**
+ * Re-run a red check as step `name` before a person sees it. Green records
+ * `Gtd-Mark: flaky=<red>` on the re-check's landing and resolves `true`.
+ */
+export const recheck = async (
+  name: string,
+  red: string,
+  options: Pick<CheckOptions, "sweepOnGreen"> = {},
+): Promise<boolean> => {
+  const green = await check(name, env.testCommand ?? "", {
+    ...options,
+    report: FEEDBACK,
+    label: "Re-running checks",
+  })
+  if (green) mark("flaky", red)
+  return green
+}
+
 export type { EscalationCount } from "../../workflow-kit/index.js"
 
 const escalationSteps = (rules?: string): kit.EscalationSteps => ({
@@ -117,18 +137,24 @@ export interface HealthOptions {
   readonly rules?: string | undefined
 }
 
+// Swept only on green: an unresolved analysis survives every retry.
+const healthSweep = (options: HealthOptions): string[] => [
+  ESCALATION,
+  ...(options.sweepOnGreen ?? []),
+]
+
 const runSuite = (options: HealthOptions): Promise<boolean> =>
   check("health.check", env.testCommand ?? "", {
     report: FEEDBACK,
     label: "Running checks",
-    // Swept only on green: an unresolved analysis survives every retry.
-    sweepOnGreen: [ESCALATION, ...(options.sweepOnGreen ?? [])],
+    sweepOnGreen: healthSweep(options),
   })
 
 /**
  * Loop until the suite is green: check, and on red run `fix` — escalating
  * first once `FIX_CAP` fixes are spent, or a judge calls the failure
- * identical to the previous round's.
+ * identical to the previous round's. An escalation re-runs the suite once
+ * first; a green re-run ends the loop.
  */
 export const healthy = (fix: () => Promise<void>, options: HealthOptions = {}): Promise<void> =>
   kit.healthy(guarded(fix, options.guard), {
@@ -138,6 +164,8 @@ export const healthy = (fix: () => Promise<void>, options: HealthOptions = {}):
     fixesSoFar: options.fixesSoFar ?? 0,
     sameFailure,
     escalations: options.escalations ?? { rounds: 0 },
+    recheck: () =>
+      recheck("health.recheck", "health.check", { sweepOnGreen: healthSweep(options) }),
     escalation: guardedSteps(
       options.guard,
       options.describeGuard,
@@ -147,13 +175,14 @@ export const healthy = (fix: () => Promise<void>, options: HealthOptions = {}):
   })
 
 /**
- * Hold the process at `<name>.blocked` until the suite is green. `guard` runs
+ * Hold the process at `<name>.blocked` until the suite is green, re-running a
+ * red check once as `<name>.recheck` before resting. `guard` runs
  * after each `blocked` landing only — never after a check, whose refusal would
  * re-run the same script forever.
  */
 export const gate = (name: string, message: string, guard?: Guard): Promise<void> =>
   kit.gate(
     name,
-    () => baseline("check"),
+    async () => (await baseline("check")) || recheck("recheck", `${name}.check`),
     guarded(() => human("blocked", { message, label: "Baseline is red", file: FEEDBACK }), guard),
   )