@pmelab/gtd 43.0.0 → 45.0.0

package/src/workflows/shared/learn.ts

@@ -0,0 +1,206 @@
+import {
+  answered,
+  changesSince,
+  judge,
+  numeric,
+  read,
+  run,
+  vars,
+  writeScript,
+  type JudgeQuestion,
+} from "../../flows/index.js"
+import type { ReviewDecision } from "../../steering/index.js"
+import {
+  conflictBody,
+  conflictFor,
+  conflictTitle,
+  isConflictTitle,
+  oneLine,
+  parseStandards,
+  standardKey,
+  renderStandards,
+  STANDARDS,
+  type Conflict,
+  type Standards,
+} from "./standards.js"
+import { REVIEW } from "./steps.js"
+
+interface Candidate {
+  readonly decision: ReviewDecision
+  readonly text: string
+}
+
+const SUMMARY_MAX = 200
+
+// The banners composedReview opens a note with say nothing about the finding; the
+// parsed body has its paragraphs joined, so they are matched by their own text.
+const BANNER =
+  /^_(?:The fixer left this unresolved\.|A fix turn removed this while renaming another finding — check whether it was fixed\.|No detail given\.)_\s*/
+
+const summary = (body: string): string => {
+  const text = oneLine(body).replace(BANNER, "")
+  return text.length > SUMMARY_MAX ? `${text.slice(0, SUMMARY_MAX - 1)}…` : text
+}
+
+/** The standard a won't-fix or an own answer would make; a fix states none. */
+const candidateOf = (d: ReviewDecision): Candidate[] => {
+  const anchor = oneLine(d.anchor)
+  if (d.choice === "wontfix") {
+    const why = summary(d.body)
+    return [{ decision: d, text: `Won't fix: ${anchor}${why === "" ? "" : ` — ${why}`}` }]
+  }
+  if (d.choice === "answer") return [{ decision: d, text: `${oneLine(d.text)} (re: ${anchor})` }]
+  return []
+}
+
+// By key, as everywhere else: a hand-edit to case or emphasis still names the same standard.
+const without = (list: readonly string[], drop: readonly string[]): string[] => {
+  const keys = new Set(drop.map(standardKey))
+  return list.filter((s) => !keys.has(standardKey(s)))
+}
+
+const adding = (list: readonly string[], text: string): string[] =>
+  list.some((s) => standardKey(s) === standardKey(text)) ? [...list] : [...list, text]
+
+/**
+ * Keep the new one, keep the old one, or replace both with the human's own
+ * wording. Another open conflict stops naming a replaced standard: the human
+ * never judged it against the replacement, so keeping it must not drop that.
+ */
+const resolve = (standards: Standards, d: ReviewDecision): Standards => {
+  const c = conflictFor(standards, d.anchor)
+  if (c === undefined) return standards
+  const others = standards.undecided.filter((u) => u !== c)
+  if (d.choice === "wontfix") return { decided: standards.decided, undecided: others }
+  const kept = d.choice === "fix" ? c.text : oneLine(d.text)
+  const undecided = others.map((u) => ({ text: u.text, olds: without(u.olds, c.olds) }))
+  return { decided: adding(without(standards.decided, c.olds), kept), undecided }
+}
+
+const contradicts = (i: number, id: string, other: string): JudgeQuestion => ({
+  id: `standard-${i}.contradicts-${id}`,
+  primitive: "noul",
+  instructions: `Does the "Standard:" line of evidence "standard-${i}" contradict ${other}?`,
+  criteria:
+    "yes: following one breaks the other. no: both can be followed — they are compatible or unrelated.",
+})
+
+// Each candidate against every kept standard and every candidate before it.
+const questionsFor = (i: number, anchor: string, decided: readonly string[]): JudgeQuestion[] => [
+  {
+    id: `standard-${i}`,
+    primitive: "noul",
+    instructions: `Is the human's answer to review note "${anchor}" (evidence "standard-${i}") a reusable standard for this codebase — a rule later changes and reviews should follow — rather than a call about this one note? Its "Standard:" line is the wording gtd would keep.`,
+    criteria:
+      "yes: it states a rule or preference that applies beyond this note. no: it is specific to this note, a one-off call, or unclear.",
+  },
+  ...decided.map((_, k) =>
+    contradicts(i, `${k + 1}`, `kept standard ${k + 1} (evidence "kept-${k + 1}")`),
+  ),
+  ...Array.from({ length: i - 1 }, (_, j) =>
+    contradicts(i, `new-${j + 1}`, `the "Standard:" line of evidence "standard-${j + 1}"`),
+  ),
+]
+
+const evidenceOf = (c: Candidate): string =>
+  [
+    `Note: ${c.decision.anchor}`,
+    `Reviewer's text: ${c.decision.body}`,
+    `Human's answer: ${c.decision.choice === "wontfix" ? "won't fix" : c.decision.text}`,
+    `Standard: ${c.text}`,
+  ].join("\n")
+
+/**
+ * One judge rest over every candidate. Only a confident `yes` on uncut
+ * evidence makes a standard; a contradiction the judge does not confidently
+ * rule out goes to the human instead of overwriting what they decided before.
+ * A cut kept standard leaves the round unlearned: raise `judgeBudgetBytes`.
+ */
+const judged = async (
+  candidates: readonly Candidate[],
+  decided: readonly string[],
+  minP: number,
+): Promise<{ added: string[]; raised: Conflict[] }> => {
+  const { answers, truncated } = await judge("review.standards.judge", {
+    questions: candidates.flatMap((c, i) => questionsFor(i + 1, c.decision.anchor, decided)),
+    evidence: Object.fromEntries([
+      ...candidates.map((c, i) => [`standard-${i + 1}`, evidenceOf(c)]),
+      ...decided.map((s, k) => [`kept-${k + 1}`, s]),
+    ]),
+    message:
+      "Judging whether your answers are standards to keep: run `gtd judge run`, or land without a verdict, which keeps none.",
+    label: "Learning your standards",
+  })
+  const ruledOut = (i: number, id: string): boolean =>
+    answered(answers[`standard-${i}.contradicts-${id}`], "no", minP)
+  const added: { i: number; text: string }[] = []
+  const raised: Conflict[] = []
+  candidates.forEach((c, n) => {
+    const i = n + 1
+    if (truncated.includes(`standard-${i}`)) return
+    if (decided.some((_, k) => truncated.includes(`kept-${k + 1}`))) return
+    if (!answered(answers[`standard-${i}`], "yes", minP)) return
+    const olds = [
+      ...decided.filter((_, k) => !ruledOut(i, `${k + 1}`)),
+      ...added.filter((a) => !ruledOut(i, `new-${a.i}`)).map((a) => a.text),
+    ]
+    if (olds.length === 0) added.push({ i, text: c.text })
+    else raised.push({ text: c.text, olds })
+  })
+  return { added: added.map((a) => a.text), raised }
+}
+
+/**
+ * Settles every answer to a standard conflict, then learns standards from
+ * the won't-fix ticks and own answers: kept in `.gtd/STANDARDS.md`, a
+ * contradicting one as a new conflict note in `.gtd/REVIEW.md`.
+ */
+export const learnStandards = async (decisions: readonly ReviewDecision[]): Promise<void> => {
+  const before = parseStandards(read(STANDARDS) ?? "")
+  const rest = decisions.filter((d) => !isConflictTitle(d.anchor))
+  const settled = decisions.filter((d) => isConflictTitle(d.anchor)).reduce(resolve, before)
+  const known = new Set(
+    [...settled.decided, ...settled.undecided.map((c) => c.text)].map(standardKey),
+  )
+  const candidates = rest.flatMap(candidateOf).filter((c) => {
+    const key = standardKey(c.text)
+    if (known.has(key)) return false
+    known.add(key)
+    return true
+  })
+  // Blank keeps none, so there is nothing to ask.
+  const minP = numeric(vars.standardMinP, Infinity)
+  const { added, raised } =
+    candidates.length === 0 || !Number.isFinite(minP)
+      ? { added: [], raised: [] }
+      : await judged(candidates, settled.decided, minP)
+  const after: Standards = {
+    decided: [...settled.decided, ...added],
+    undecided: [...settled.undecided, ...raised],
+  }
+  if (renderStandards(after) !== renderStandards(before)) {
+    await run("review.standards.recording", writeScript(STANDARDS, renderStandards(after)), {
+      label: "Recording your standards",
+    })
+  }
+  if (raised.length > 0) {
+    const chunks = raised.map((c) => `## ${conflictTitle(c)}\n\n${conflictBody(c)}`)
+    await run(
+      "review.standards.raising",
+      writeScript(REVIEW, `${(read(REVIEW) ?? "").trimEnd()}\n\n${chunks.join("\n\n")}\n`),
+      { label: "Asking about a contradicting standard", file: REVIEW },
+    )
+  }
+}
+
+export const settlesStandard = (d: ReviewDecision): boolean => isConflictTitle(d.anchor)
+
+export const standardsPending = (): boolean =>
+  parseStandards(read(STANDARDS) ?? "").undecided.length > 0
+
+export const standardsAddedSince = (base: string): readonly string[] => {
+  const change = changesSince(base).get(STANDARDS)
+  if (change === undefined) return []
+  const was = new Set(parseStandards(change.before ?? "").decided)
+  return parseStandards(change.after ?? "").decided.filter((s) => !was.has(s))
+}

package/src/workflows/shared/options.ts

@@ -20,6 +20,7 @@ export const ShippedOptions = Schema.Struct({
   reviewNoteActionable: setting,
   reviewSeverityMinP: setting,
   qualityTriageMinP: setting,
+  standardMinP: setting,
   refactorFlagPattern: setting,
   seamAllow: setting,
   sliceMaxCriteria: setting,

package/src/workflows/{feature → shared}/review.test.ts

@@ -9,7 +9,7 @@ import {
 } from "../../flows/index.js"
 import {
   buildTail,
-  review,
+  humanReview,
   reUnwind,
   severityOf,
   type BuildTailOptions,
@@ -17,8 +17,7 @@ import {
 } from "./review.js"
 import type { ReviewNote } from "../../steering/index.js"
 import * as bundled from "../index.js"
-import type * as featureEntry from "./index.js"
-import { fixtureContext } from "../shared/text.fixture.js"
+import { fixtureContext } from "./text.fixture.js"
 import { toRequest } from "../../judges/index.js"
 
 afterEach(() => installContext(undefined))
@@ -155,7 +154,7 @@ const drive = async (d: Drive): Promise<Run> => {
   installContext(context)
   let result: ReviewOutcome | "stopped"
   try {
-    result = await review("base", undefined, {
+    result = await humanReview("base", undefined, {
       ...d.options,
       ...(d.guarded ? { guard: () => void log.push("guard") } : {}),
     })
@@ -975,11 +974,8 @@ describe("BuildTailOptions.lensBase", () => {
   })
 })
 
-// pins the public re-exports from the feature entry point and the published workflows entry
+// pins the public re-exports from the published workflows entry
 export type _PublicBuildTailOptions = [
-  featureEntry.BuildTailOptions,
-  featureEntry.FeedbackTarget,
-  featureEntry.ReviewRange,
   bundled.BuildTailOptions,
   bundled.FeedbackTarget,
   bundled.ReviewRange,

package/src/workflows/{feature → shared}/review.ts

@@ -4,6 +4,7 @@ import {
   head,
   judge,
   numeric,
+  read,
   requireRevert,
   restoreScript,
   run,
@@ -16,20 +17,24 @@ import {
 } from "../../flows/index.js"
 import type { ReviewNote } from "../../steering/index.js"
 import * as kit from "../../workflow-kit/index.js"
-import { guarded, healthy, type EscalationCount } from "../shared/health.js"
-import { NO_FINDINGS, type LensReport } from "../shared/lenses.js"
+import { guarded, healthy, type EscalationCount } from "./health.js"
+import { NO_FINDINGS, type LensReport } from "./lenses.js"
 import {
+  answerReviewQuestions,
   awaitReview,
+  collecting,
   fixCheck,
+  fixNits,
   fixRisks,
   QUALITY,
   REQUIREMENTS,
   REVIEW,
   reviewMissing,
-} from "../shared/steps.js"
-import { closeReview, isOptionalObject, tail, type TailOptions } from "../shared/tail.js"
-import * as t from "../shared/text.js"
-import { answerReviewQuestions, collecting, fixNits } from "./steps.js"
+} from "./steps.js"
+import { learnStandards, settlesStandard, standardsAddedSince, standardsPending } from "./learn.js"
+import { parseStandards, STANDARDS } from "./standards.js"
+import { closeReview, isOptionalObject, tail, type TailOptions } from "./tail.js"
+import * as t from "./text.js"
 
 export type { ReviewOutcome } from "../../workflow-kit/index.js"
 
@@ -189,6 +194,10 @@ const composing = (
             weakened: kit.removedAssertions(changesSince(base)),
             nitFix,
             answered,
+            standards: {
+              added: standardsAddedSince(base),
+              undecided: parseStandards(read(STANDARDS) ?? "").undecided,
+            },
           }),
           [QUALITY],
         )
@@ -200,10 +209,11 @@ const composing = (
  * The quality lap's notes reach a human over everything since `base`, who
  * answers each one — fix as suggested, won't fix, or their own answer — and
  * may comment. A fix joins the nit batch, a won't-fix is dropped, and an own
- * answer or comment is judged: edits go to another planning lap, questions
- * are answered in place, nits fixed in one batch, praise dropped.
+ * answer or comment is judged: edits end the review as `feedback` for the
+ * caller to build, questions are answered in place, nits fixed in one batch,
+ * praise dropped.
  */
-export const review = (
+export const humanReview = (
   base: string,
   escalations: EscalationCount = { rounds: 0 },
   options: Omit<BuildTailOptions, "fixFirst" | "green"> = {},
@@ -236,6 +246,9 @@ export const review = (
     collecting: feedback.collecting,
     triage: triage(severities),
     decided: (decisions) => decisions.forEach((d) => answered.add(d.anchor)),
+    settles: settlesStandard,
+    learn: learnStandards,
+    pending: standardsPending,
     answerQuestions: answerReviewQuestions,
     fixNits: async (notes) => {
       await guarded((n: typeof notes) => fixNits(n, fixAccess, rules), guard)(notes)
@@ -316,7 +329,7 @@ export function buildTail(
     )
   }
   const [base, form] = options
-  return tail((escalations, report) => review(base, escalations, { ...form, report }), {
+  return tail((escalations, report) => humanReview(base, escalations, { ...form, report }), {
     ...form,
     triage: true,
   })

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

@@ -21,6 +21,7 @@ describe("the bundled workflow's skills export", () => {
         "build.review.fix.nits",
         "build.review.fix.risks",
         "notes",
+        "feedback",
         "refactor",
         "refactor.fix.suite",
         "refactor.health",
@@ -71,6 +72,7 @@ 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"],
+      feedback: ["test-driven-development", "incremental-implementation"],
       refactor: ["ponytail"],
       "refactor.fix.suite": ["ponytail", "debugging-and-error-recovery"],
       "refactor.health": ["ponytail", "debugging-and-error-recovery"],

package/src/workflows/shared/skills.ts

@@ -22,6 +22,8 @@ export const skills = (
     design: ["spec-driven-development", "planning-and-task-breakdown"],
     // `fix`'s turn over the notes a review handed on.
     notes: ["incremental-implementation", "code-simplification"],
+    // `review`'s turn building what a review round collected.
+    feedback: ["test-driven-development", "incremental-implementation"],
     // The refactor's own turns load `ponytail`; `refactor.build.*` carry the `build.*` lists.
     ...build,
     ...Object.fromEntries(Object.entries(build).map(([name, list]) => [`refactor.${name}`, list])),

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

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest"
+import {
+  conflictFor,
+  conflictTitle,
+  parseStandards,
+  renderStandards,
+  standardsBlock,
+} from "./standards.js"
+
+const conflict = { text: "Calculators are functions.", olds: ["Calculators are classes."] }
+
+describe("standards file", () => {
+  it("round-trips decided and undecided standards", () => {
+    const standards = { decided: ["Prefer early returns."], undecided: [conflict] }
+    expect(parseStandards(renderStandards(standards))).toEqual(standards)
+  })
+
+  it("reads a hand-edited file: any heading groups decided ones, wrapped lines join", () => {
+    const text = [
+      "# Standards",
+      "",
+      "Some prose.",
+      "",
+      "## Testing",
+      "",
+      "1. Every bug fix",
+      "  gets a test.",
+      "",
+      "## Undecided",
+      "",
+      "- New",
+      "  - contradicts: Old",
+    ].join("\n")
+    expect(parseStandards(text)).toEqual({
+      decided: ["Every bug fix gets a test."],
+      undecided: [{ text: "New", olds: ["Old"] }],
+    })
+  })
+})
+
+describe("a formatter-wrapped file", () => {
+  it("keeps a wrapped contradicts line with its old standard", () => {
+    const text = [
+      "## Undecided",
+      "",
+      "- Calculators are plain functions. (re: subtract has no class)",
+      "  - contradicts: Won't fix: subtract has no class — Calculators read better as",
+      "    classes.",
+    ].join("\n")
+    expect(parseStandards(text).undecided).toEqual([
+      {
+        text: "Calculators are plain functions. (re: subtract has no class)",
+        olds: ["Won't fix: subtract has no class — Calculators read better as classes."],
+      },
+    ])
+  })
+})
+
+describe("conflict notes", () => {
+  it("keep their title when a formatter rewrites the emphasis", () => {
+    const standards = { decided: [], undecided: [{ text: "Use _named_ exports.", olds: [] }] }
+    expect(
+      conflictFor(standards, conflictTitle({ text: "Use *named* exports.", olds: [] })),
+    ).toBeDefined()
+  })
+
+  it("are one per standard, however often the file lists it", () => {
+    const text = "## Undecided\n\n- New\n  - contradicts: Old\n- New\n  - contradicts: Old\n"
+    expect(parseStandards(text).undecided).toHaveLength(1)
+  })
+
+  it("title back to the conflict it asks about", () => {
+    const standards = { decided: [], undecided: [conflict] }
+    expect(conflictFor(standards, conflictTitle(conflict))).toBe(conflict)
+    expect(conflictFor(standards, "Standard conflict 00000000")).toBeUndefined()
+  })
+})
+
+describe("standardsBlock", () => {
+  it("is empty without decided standards", () => {
+    expect(standardsBlock(undefined)).toBe("")
+    expect(standardsBlock(renderStandards({ decided: [], undecided: [conflict] }))).toBe("")
+  })
+
+  it("lists only the decided ones", () => {
+    const block = standardsBlock(renderStandards({ decided: ["A."], undecided: [conflict] }))
+    expect(block).toContain("- A.")
+    expect(block).not.toContain(conflict.text)
+  })
+})

package/src/workflows/shared/standards.ts

@@ -0,0 +1,156 @@
+import { ANSWER_LEAD, FREE_TEXT_PLACEHOLDER } from "../../steering/index.js"
+
+export const STANDARDS = ".gtd/STANDARDS.md"
+
+/** A learned standard that contradicts decided ones, waiting on the human. */
+export interface Conflict {
+  readonly text: string
+  /** The decided standards it contradicts. */
+  readonly olds: readonly string[]
+}
+
+export interface Standards {
+  readonly decided: readonly string[]
+  readonly undecided: readonly Conflict[]
+}
+
+const UNDECIDED = "Undecided"
+
+// The same class as the review's `Gtd-Mark` anchors, so a title reads alike in both.
+export const oneLine = (text: string): string =>
+  // eslint-disable-next-line no-control-regex -- the control range IS the point
+  text.replace(/[\s\x00-\x1f\x7f-\x9f\u2028\u2029]+/g, " ").trim()
+
+const ITEM = /^(?:[-*+]|\d+[.)])\s+(.*)$/
+const CONTRADICTS = /^\s+[-*+]\s+contradicts:\s*(.*)$/i
+
+interface Item {
+  text: string
+  /** Set under `## Undecided`. */
+  olds?: string[]
+}
+
+// A formatter wraps long lines: the tail belongs to the last `contradicts:` once there is one.
+const wrapped = (item: Item, line: string): void => {
+  const olds = item.olds
+  if (olds !== undefined && olds.length > 0) olds[olds.length - 1] += ` ${line.trim()}`
+  else item.text += ` ${line.trim()}`
+}
+
+/** What tells two standards apart: not the emphasis or spacing a formatter may rewrite. */
+export const standardKey = (text: string): string =>
+  oneLine(text.replace(/[*_`\\]/g, "")).toLowerCase()
+
+// Each standard once, so every conflict note gets a title of its own.
+const toStandards = (items: readonly Item[]): Standards => {
+  const seen = new Set<string>()
+  const fresh = (text: string): boolean => {
+    const key = standardKey(text)
+    if (key === "" || seen.has(key)) return false
+    seen.add(key)
+    return true
+  }
+  const decided = items.filter((i) => i.olds === undefined).map((i) => oneLine(i.text))
+  const undecided = items.flatMap((i) =>
+    i.olds === undefined
+      ? []
+      : [{ text: oneLine(i.text), olds: i.olds.map(oneLine).filter((o) => o !== "") }],
+  )
+  return { decided: decided.filter(fresh), undecided: undecided.filter((c) => fresh(c.text)) }
+}
+
+/**
+ * Every top-level bullet is one standard, those under `## Undecided` waiting
+ * on the human; a hand-edited file may group the rest under any heading.
+ */
+export const parseStandards = (text: string): Standards => {
+  const items: Item[] = []
+  let pending = false
+  let last: Item | undefined
+  for (const line of text.split("\n")) {
+    const heading = /^(#{1,6})\s+(.*)$/.exec(line)
+    const item = ITEM.exec(line)
+    const old = CONTRADICTS.exec(line)
+    if (heading !== null) {
+      pending = heading[1]!.length > 1 && heading[2]!.trim() === UNDECIDED
+      last = undefined
+    } else if (item !== null) {
+      last = pending ? { text: item[1]!, olds: [] } : { text: item[1]! }
+      items.push(last)
+    } else if (old !== null && last?.olds !== undefined) last.olds.push(old[1]!)
+    else if (/^\s+\S/.test(line) && last !== undefined) wrapped(last, line)
+    else if (line.trim() !== "") last = undefined
+  }
+  return toStandards(items)
+}
+
+export const renderStandards = ({ decided, undecided }: Standards): string => {
+  const parts = [
+    "# Standards",
+    "Kept from your review answers for every agent turn. One standard per bullet.",
+    ...(decided.length === 0 ? [] : [decided.map((s) => `- ${s}`).join("\n")]),
+    ...(undecided.length === 0
+      ? []
+      : [
+          `## ${UNDECIDED}`,
+          undecided
+            .map((c) => [`- ${c.text}`, ...c.olds.map((o) => `  - contradicts: ${o}`)].join("\n"))
+            .join("\n"),
+        ]),
+  ]
+  return `${parts.join("\n\n")}\n`
+}
+
+// FNV-1a over the key: a conflict's chunk title must survive markdown parsing and a
+// formatter's rewrite of STANDARDS.md, which its text may not.
+const hash = (raw: string): string => {
+  const text = standardKey(raw)
+  let h = 0x811c9dc5
+  for (let i = 0; i < text.length; i++) h = Math.imul(h ^ text.charCodeAt(i), 0x01000193)
+  return (h >>> 0).toString(16).padStart(8, "0")
+}
+
+const CONFLICT_TITLE = /^Standard conflict ([0-9a-f]{8})$/
+
+export const conflictTitle = (c: Conflict): string => `Standard conflict ${hash(c.text)}`
+
+export const conflictFor = (standards: Standards, title: string): Conflict | undefined => {
+  const id = CONFLICT_TITLE.exec(title)?.[1]
+  return id === undefined ? undefined : standards.undecided.find((c) => hash(c.text) === id)
+}
+
+export const isConflictTitle = (title: string): boolean => CONFLICT_TITLE.test(title)
+
+const KEEP_NEW = "keep the new one (drop the old)"
+const KEEP_OLD = "keep the old one (discard the new)"
+
+/** A conflict's chunk body; its three boxes read as fix / won't fix / own answer by position. */
+export const conflictBody = (c: Conflict): string =>
+  [
+    ...(c.olds.length === 0
+      ? [
+          `A standard learned from your answers contradicted ones another answer since replaced in \`${STANDARDS}\`. Keep it, discard it, or reword it.`,
+          `New: ${c.text}`,
+        ]
+      : [
+          `A standard learned from your answers contradicts ${c.olds.length === 1 ? "one" : "some"} already in \`${STANDARDS}\`. Your own answer replaces both with its wording.`,
+          `New: ${c.text}`,
+          `Old:\n\n${c.olds.map((o) => `- ${o}`).join("\n")}`,
+        ]),
+    `${ANSWER_LEAD}\n\n- [ ] ${KEEP_NEW}\n- [ ] ${KEEP_OLD}\n- [ ] ${FREE_TEXT_PLACEHOLDER}`,
+  ].join("\n\n")
+
+/** What every agent turn is told while `.gtd/STANDARDS.md` holds decided standards. */
+export const standardsBlock = (text: string | undefined): string => {
+  const { decided } = parseStandards(text ?? "")
+  if (decided.length === 0) return ""
+  return `## Standards
+
+\`${STANDARDS}\` holds the standards the human set in earlier reviews.
+Follow every one in what you write. Reviewing, never raise a finding a
+standard rules out — a \`Won't fix:\` standard is a finding the human
+rejected, so never raise it or one like it again — and raise breaking a
+standard as a finding.
+
+${decided.map((s) => `- ${s}`).join("\n")}`
+}