@pmelab/gtd 44.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/shared/review.ts

@@ -4,6 +4,7 @@ import {
   head,
   judge,
   numeric,
+  read,
   requireRevert,
   restoreScript,
   run,
@@ -30,6 +31,8 @@ import {
   REVIEW,
   reviewMissing,
 } 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"
 
@@ -191,6 +194,10 @@ const composing = (
             weakened: kit.removedAssertions(changesSince(base)),
             nitFix,
             answered,
+            standards: {
+              added: standardsAddedSince(base),
+              undecided: parseStandards(read(STANDARDS) ?? "").undecided,
+            },
           }),
           [QUALITY],
         )
@@ -239,6 +246,9 @@ export const humanReview = (
     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)

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")}`
+}

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

@@ -31,7 +31,7 @@ import {
   withSkills,
   composedReview,
 } from "./text.js"
-import { steeringFormatFor, unansweredNotes } from "../../steering/index.js"
+import { reviewDecisions, steeringFormatFor, unansweredNotes } from "../../steering/index.js"
 import { captureStep, renderText } from "./text.fixture.js"
 
 describe("withSkills", () => {
@@ -68,6 +68,28 @@ describe("agentWithSkills", () => {
     expect(request.options).not.toHaveProperty("skills")
   })
 
+  it("ends every prompt with the kept standards, never the undecided ones", async () => {
+    const standards = [
+      "# Standards",
+      "",
+      "- Prefer early returns.",
+      "",
+      "## Undecided",
+      "",
+      "- Use classes.",
+      "  - contradicts: Prefer early returns.",
+    ].join("\n")
+    const request = await captureStep(() => agentWithSkills("name", "do-the-work"), {
+      scope: "a",
+      skills: { a: [] },
+      read: (path) => (path === ".gtd/STANDARDS.md" ? standards : undefined),
+    })
+    if (request.kind !== "agent") throw new Error("unreachable")
+    expect(request.prompt.startsWith("do-the-work\n\n## Standards")).toBe(true)
+    expect(request.prompt.endsWith("- Prefer early returns.")).toBe(true)
+    expect(request.prompt).not.toContain("Use classes.")
+  })
+
   it("leaves the prompt bare when the scope resolves to an empty list", async () => {
     const request = await capture(() => agentWithSkills("name", "do-the-work"), { a: [] })
     if (request.kind !== "agent") throw new Error("unreachable")
@@ -1244,6 +1266,41 @@ describe("buildReviewCollectingPrompt answer boxes", () => {
 describe("composedReview", () => {
   const BASE = "0123456789abcdef0123456789abcdef01234567"
 
+  describe("standards", () => {
+    const conflict = { text: "Calculators are functions.", olds: ["Calculators are classes."] }
+    const withConflict = composedReview(BASE, {
+      notes: [],
+      fixed: [],
+      noise: [],
+      standards: { added: [], undecided: [conflict] },
+    })
+
+    it("asks about each undecided standard in a note that blocks sign-off", () => {
+      expect(withConflict).toMatch(/^## Standard conflict [0-9a-f]{8}$/m)
+      expect(withConflict).toContain("- [ ] keep the new one (drop the old)")
+      expect(unansweredNotes(withConflict)).toHaveLength(1)
+    })
+
+    it("reads its boxes by position, like a note's", () => {
+      const ticked = withConflict.replace("- [ ] keep the old one", "- [x] keep the old one")
+      expect(unansweredNotes(ticked)).toEqual([])
+      expect(reviewDecisions(withConflict, ticked)).toEqual([
+        expect.objectContaining({ choice: "wontfix" }),
+      ])
+    })
+
+    it("lists the standards added", () => {
+      const doc = composedReview(BASE, {
+        notes: [],
+        fixed: [],
+        noise: [],
+        standards: { added: ["Prefer early returns."], undecided: [] },
+      })
+      expect(doc).toContain("## Standards added")
+      expect(doc).toContain("- Prefer early returns.")
+    })
+  })
+
   it("is a valid review with unique chunk titles, so every note matches its own chunk", () => {
     const doc = composedReview(BASE, {
       notes: [

package/src/workflows/shared/text.ts

@@ -1,6 +1,7 @@
 import {
   agent,
   codeThreads,
+  read,
   displayPath,
   env,
   head,
@@ -19,6 +20,13 @@ import {
   FREE_TEXT_PLACEHOLDER,
 } from "../../steering/index.js"
 import { escapeRegExp } from "./registry.js"
+import {
+  conflictBody,
+  conflictTitle,
+  standardsBlock,
+  STANDARDS,
+  type Conflict,
+} from "./standards.js"
 import { defaultFlagRegistry } from "./vars.js"
 import type { CollectRound, RemovedAssertions, Requested } from "../../workflow-kit/index.js"
 import {
@@ -57,7 +65,8 @@ export const agentWithSkills = (
   options: AgentOptions = {},
 ): Promise<void> => {
   const access = accessPreamble(accessFor(name, options.file))
-  const body = access === "" ? prompt : `${access}\n\n${prompt}`
+  const standards = standardsBlock(read(STANDARDS))
+  const body = [access, prompt, standards].filter((part) => part !== "").join("\n\n")
   return agent(name, withSkills(skillsFor(name).join(", "), body), options)
 }
 
@@ -124,12 +133,17 @@ export interface ComposedReview {
   readonly nitFix?: string | undefined
   /** Titles of notes the human already answered, left out. */
   readonly answered?: ReadonlySet<string> | undefined
+  /** Standards added since the review base, and the conflicts still waiting on the human. */
+  readonly standards?:
+    | { readonly added: readonly string[]; readonly undecided: readonly Conflict[] }
+    | undefined
 }
 
 const SUMMARY_TITLES = [
   "Weakened scenarios",
   "Fixed from your notes",
   "Fixed automatically",
+  "Standards added",
   "Dropped as noise",
   "Nothing to note",
 ]
@@ -157,6 +171,10 @@ export const composedReview = (base: string, report: ComposedReview): string =>
   const chunk = (title: string, body: string): string => `## ${title}\n\n${body.trim()}`
   // The lead-in line keeps a body that ends in a list from absorbing the boxes.
   const answerBoxes = `${ANSWER_LEAD}\n\n- [ ] ${ANSWER_FIX}\n- [ ] ${ANSWER_WONT_FIX}\n- [ ] ${FREE_TEXT_PLACEHOLDER}`
+  const conflicts = (report.standards?.undecided ?? []).map((c) =>
+    chunk(unique(conflictTitle(c)), conflictBody(c)),
+  )
+  const added = report.standards?.added ?? []
   const notes = report.notes
     .map((n) => ({ ...n, title: unique(n.title) }))
     .filter((n) => report.answered?.has(n.title) !== true)
@@ -180,6 +198,7 @@ export const composedReview = (base: string, report: ComposedReview): string =>
             `These scenarios lost an assertion the review base had:\n\n${weakened.join("\n")}`,
           ),
         ]),
+    ...conflicts,
     ...notes.map((n) =>
       chunk(
         n.title,
@@ -200,6 +219,14 @@ export const composedReview = (base: string, report: ComposedReview): string =>
             report.fixed.map((f) => `- ${f.title} (${short(f.commit)})`).join("\n"),
           ),
         ]),
+    ...(added.length === 0
+      ? []
+      : [
+          chunk(
+            "Standards added",
+            `Learned from your answers and kept in \`${STANDARDS}\`:\n\n${added.map((s) => `- ${s}`).join("\n")}`,
+          ),
+        ]),
     ...(report.noise.length === 0
       ? []
       : [chunk("Dropped as noise", report.noise.map((f) => `- ${f.title} (p=${f.p})`).join("\n"))]),

package/src/workflows/shared/vars.ts

@@ -24,6 +24,8 @@ export const defaults: Readonly<Record<string, string>> = {
   reviewNoteActionable: "0.7",
   reviewSeverityMinP: "0.7",
   qualityTriageMinP: "0.7",
+  // How sure the judge must be that an answer at the review gate is a reusable standard.
+  standardMinP: "0.8",
   refactorFlagPattern: "\\bGTD_FLAG_\\w+",
   seamAllow: [...testFileGlobs, ".gtd/**"].join(", "),
   flagMode: "true",