@pmelab/gtd 55.0.0 → 56.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "55.0.0",
+  "version": "56.0.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {

package/skills/authoring/SKILL.md

@@ -109,9 +109,9 @@ workflow that fails to load breaks every gtd command in the repository.
   step you add must fit one of them; there is no sixth.
 
 Options (all optional): `label`, `file` (a `.gtd/` path), `mode` (needs `file`;
-`qa`, `review`, or a `config.modes` name), `message` (human/judge), `model`,
-`system` (agent), `allowEmpty` (agent), `acceptClean` (human), `base` (the
-commit the step reviews since — what `gtd base` prints).
+`qa`, `review`, `findings`, or a `config.modes` name), `message` (human/judge),
+`model`, `system` (agent), `allowEmpty` (agent), `acceptClean` (human), `base`
+(the commit the step reviews since — what `gtd base` prints).
 
 Helpers — pure reads of the commit replay stands on (the tree the last step
 left, never the live working tree): `read(path)`, `glob(pattern)`,

package/src/cli/Cli.ts

@@ -539,11 +539,11 @@ const COMMAND_ROWS: readonly CommandRow[] = [
     arity: { names: ["mode", "file"] },
     details: [
       "Read <file> and run the built-in steering format named",
-      "<mode> (see `gtd validate`'s modes: qa, review) over its",
-      "contents, printing each finding one per line and exiting",
-      "non-zero when there are any. Resolves no workflow state and",
-      "reads no config — standalone, runnable from any directory",
-      "with <mode>/<file> given explicitly. This is what a",
+      "<mode> (see `gtd validate`'s modes: qa, review, findings)",
+      "over its contents, printing each finding one per line and",
+      "exiting non-zero when there are any. Resolves no workflow",
+      "state and reads no config — standalone, runnable from any",
+      "directory with <mode>/<file> given explicitly. This is what a",
       "workflow's emitted validation script invokes as a leaf step.",
       "--open-questions runs the qa unanswered-questions predicate",
       "instead (see --help); --open-threads lists open threads.",

package/src/edge/Edge.test.ts

@@ -754,7 +754,7 @@ export default async () => {
 `)
     const exit = await provideExit(currentRest, repo)
     expect(Exit.isFailure(exit) && String(exit.cause)).toContain(
-      'step "idle": mode "adr" is not a mode this workflow knows (qa, review)',
+      'step "idle": mode "adr" is not a mode this workflow knows (qa, review, findings)',
     )
   })
 

package/src/steering/FORMATS.md

@@ -18,9 +18,13 @@ read them.
   its decision. A `## Findings` or `## Walkthrough` heading groups the `###`
   chunks under it; a walkthrough chunk takes no decision. Any other `##` is a
   chunk of its own.
+- **`findings`**: the finding gate's file. `## ` entries, those under a
+  `# Dropped as noise` heading being the noise; each holds exactly one
+  `- [ ] fix` box. A ticked box fixes the finding; text below the box is the
+  human's guidance, valid only under a ticked one.
 - **Free-form**: any markdown, for a file with no mode or an unknown one. Only
   its threads are validated.
-- **Threads**, shared by all three: a footnote whose definition is a list of
+- **Threads**, shared by all of them: a footnote whose definition is a list of
   alternating `- H:` / `- A:` entries. Any other footnote is a one-shot note.
 - **Code threads**: `H:` / `A:` line comments (`//`, `#`, `--`, `;`, chosen by
   file extension) in a changed code file. A comment run is a thread only when

package/src/steering/SteeringFormats.test.ts

@@ -11,8 +11,8 @@ const QA_FORMAT = steeringFormatFor("qa")!
 const REVIEW_FORMAT = steeringFormatFor("review")!
 
 describe("BUILT_IN_MODE_NAMES", () => {
-  it("lists the two built-in format names", () => {
-    expect(BUILT_IN_MODE_NAMES).toEqual(["qa", "review"])
+  it("lists the built-in format names", () => {
+    expect(BUILT_IN_MODE_NAMES).toEqual(["qa", "review", "findings"])
   })
 })
 

package/src/steering/contract.test.ts

@@ -34,6 +34,7 @@ const fixture = (path: string): string => {
 const FORMATS: readonly (readonly [dir: string, format: SteeringFormat, ticks: boolean])[] = [
   ["qa", steeringFormatFor("qa")!, true],
   ["review", steeringFormatFor("review")!, true],
+  ["findings", steeringFormatFor("findings")!, true],
   ["free-form", freeFormFormat, false],
 ]
 

package/src/steering/findings.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest"
+import { applySteeringEdits, findingEntries, steeringFormatFor } from "./index.js"
+
+const format = steeringFormatFor("findings")!
+
+const gate = (box: string, guidance = ""): string =>
+  `# Quality\n\n## a\n\nBody.\n\n${box}\n${guidance === "" ? "" : `\n${guidance}\n`}`
+
+const messages = (content: string): string[] => format.validate(content).map((f) => f.message)
+
+describe("the findings format", () => {
+  it("reads a ticked box and the guidance below it", () => {
+    expect(findingEntries(gate("- [x] fix", "Round half up."))).toEqual([
+      expect.objectContaining({ title: "a", body: "Body.", fix: true, guidance: "Round half up." }),
+    ])
+  })
+
+  it("reads guidance a formatter folded into the box's own line", () => {
+    expect(findingEntries(gate("- [x] fix use a map"))[0]).toMatchObject({
+      fix: true,
+      guidance: "use a map",
+    })
+  })
+
+  it("refuses guidance under an unticked box", () => {
+    expect(messages(gate("- [ ] fix", "Round half up."))).toEqual([
+      '"a" has guidance under an unticked box — tick it to fix the finding, or delete the text to drop it',
+    ])
+  })
+
+  it("refuses a finding with no box, or with two", () => {
+    expect(messages(gate("- [ ] maybe"))[0]).toContain("has no `- [ ] fix` box")
+    expect(messages(gate("- [ ] fix\n- [x] fix"))[0]).toContain("has 2 `fix` boxes")
+  })
+
+  it("ticks with guidance, and unticking drops the guidance with the tick", () => {
+    const write = (content: string, opts: { checked?: boolean; text?: string }): string => {
+      const result = format.apply(content, { kind: "chunk", index: 0 }, opts)
+      if (!result.ok) throw new Error(result.reason)
+      return applySteeringEdits(content, result.edits)
+    }
+    const ticked = write(gate("- [ ] fix"), { checked: true, text: "Round half up." })
+    expect(ticked).toBe(gate("- [x] fix", "Round half up."))
+    expect(write(ticked, { checked: false })).toBe(gate("- [ ] fix"))
+    expect(write(ticked, { checked: true, text: "Round half up." })).toBe(ticked)
+  })
+})

package/src/steering/findings.ts

@@ -0,0 +1,350 @@
+import type { List, ListItem, Node, Root, RootContent } from "mdast"
+import { blockNodesOfRun } from "./Blocks.js"
+import { eolOf } from "./Eol.js"
+import {
+  footnoteAttachEdits,
+  noteLookup,
+  openThreadsOf,
+  threadFindings,
+  threadOutlineNodes,
+  threadReplyActions,
+} from "./Footnotes.js"
+import { headingText, lineRange, parseMarkdown, spanRange, toLspPosition } from "./MarkdownTree.js"
+import type {
+  SteeringAnnotateResult,
+  SteeringFinding,
+  SteeringFormat,
+  SteeringOutlineNode,
+  SteeringView,
+  SteeringViewNode,
+} from "./SteeringFormat.js"
+
+/** The `# ` heading the findings a judge called noise sit under. */
+export const NOISE_HEADING = "Dropped as noise"
+/** The label of the one box under each finding. */
+export const FIX_BOX = "fix"
+
+const OPEN_GROUP = "Open"
+
+/** One `## ` finding of a finding-gate file. */
+export interface FindingEntry {
+  readonly title: string
+  /** The finding's markdown between its heading and its box. */
+  readonly body: string
+  /** Under `# Dropped as noise`. */
+  readonly noise: boolean
+  /** Its box is ticked. */
+  readonly fix: boolean
+  /** The human's text below the box; `""` when none. */
+  readonly guidance: string
+  /** How many `fix` boxes it holds; valid only with exactly one. */
+  readonly boxes: number
+  readonly headingLine: number
+}
+
+interface Parsed extends FindingEntry {
+  readonly bodyNodes: readonly RootContent[]
+  readonly box?: ListItem
+  /** The box and the items after it, kept out of the body when its list starts in the body. */
+  readonly notBody: ReadonlySet<ListItem>
+  /** The guidance's last line, or the box's when there is none. */
+  readonly lastLine: number
+  readonly endLine: number
+}
+
+const MARKER = /\[\^[^\]\s]+\]/g
+
+const isBox = (item: ListItem, content: string): boolean => {
+  if (typeof item.checked !== "boolean") return false
+  const first = item.children[0]
+  if (first?.type !== "paragraph" || first.position === undefined) return false
+  const text = content.slice(first.position.start.offset, first.position.end.offset)
+  return new RegExp(`^${FIX_BOX}(?![\\w-])`).test(text)
+}
+
+const slice = (content: string, node: Node): string =>
+  content.slice(node.position!.start.offset, node.position!.end.offset)
+
+const lineOf = (node: Node, end = false): number =>
+  toLspPosition(end ? node.position!.end : node.position!.start).line
+
+/** The box item's own text past its label: a formatter may fold a guidance line into it. */
+const inlineGuidance = (content: string, item: ListItem): string => {
+  const first = item.children[0]!
+  const text = content.slice(first.position!.start.offset, item.position!.end.offset)
+  return text
+    .slice(FIX_BOX.length)
+    .replace(/^[\s:—–-]+/, "")
+    .trim()
+}
+
+interface Split {
+  readonly bodyNodes: readonly RootContent[]
+  readonly body: string
+  readonly notBody: readonly ListItem[]
+  readonly guidance: string
+  readonly last?: Node
+}
+
+const guidanceOf = (parts: readonly string[]): string =>
+  parts
+    .map((p) => p.replace(MARKER, "").trim())
+    .filter((p) => p !== "")
+    .join("\n\n")
+
+/** `nodes` split at `box`: the body before it, the guidance after it. */
+const splitAtBox = (content: string, nodes: readonly RootContent[], box: ListItem): Split => {
+  const at = nodes.findIndex((n) => n.type === "list" && n.children.includes(box))
+  const list = nodes[at] as List
+  const boxAt = list.children.indexOf(box)
+  // A body ending in a list runs on into the box's own list: its items before the box are body.
+  const bodyNodes = nodes.slice(0, boxAt > 0 ? at + 1 : at)
+  const trailing = list.children.slice(boxAt + 1)
+  const after = nodes.slice(at + 1)
+  return {
+    bodyNodes,
+    body: bodyNodes
+      .map((n) =>
+        n === list
+          ? content.slice(n.position!.start.offset, box.position!.start.offset).trimEnd()
+          : slice(content, n),
+      )
+      .join("\n\n"),
+    notBody: list.children.slice(boxAt),
+    guidance: guidanceOf([
+      inlineGuidance(content, box),
+      ...[...trailing, ...after].map((n) => slice(content, n)),
+    ]),
+    last: after.at(-1) ?? trailing.at(-1) ?? box,
+  }
+}
+
+const entryOf = (
+  content: string,
+  title: string,
+  noise: boolean,
+  headingLine: number,
+  nodes: readonly RootContent[],
+  endLine: number,
+): Parsed => {
+  const notes = nodes.filter((n) => n.type !== "footnoteDefinition")
+  const boxes = notes.flatMap((n) =>
+    n.type === "list" ? n.children.filter((i) => isBox(i, content)) : [],
+  )
+  const box = boxes[0]
+  const split: Split =
+    box === undefined
+      ? {
+          bodyNodes: notes,
+          body: notes.map((n) => slice(content, n)).join("\n\n"),
+          notBody: [],
+          guidance: "",
+        }
+      : splitAtBox(content, notes, box)
+  return {
+    title,
+    body: split.body,
+    noise,
+    fix: box?.checked === true,
+    guidance: split.guidance,
+    boxes: boxes.length,
+    headingLine,
+    bodyNodes: split.bodyNodes,
+    ...(box === undefined ? {} : { box }),
+    notBody: new Set(split.notBody),
+    lastLine: split.last === undefined ? headingLine : lineOf(split.last, true),
+    endLine,
+  }
+}
+
+const parse = (content: string): readonly Parsed[] => {
+  const tree: Root = parseMarkdown(content)
+  const entries: Parsed[] = []
+  let noise = false
+  let open: { title: string; line: number; nodes: RootContent[] } | undefined
+  const close = (endLine: number): void => {
+    if (open !== undefined)
+      entries.push(entryOf(content, open.title, noise, open.line, open.nodes, endLine))
+    open = undefined
+  }
+  for (const node of tree.children) {
+    if (node.type === "heading" && node.depth <= 2) {
+      close(lineOf(node) - 1)
+      const text = headingText(content, node, (t) => t.replace(MARKER, ""))
+      if (node.depth === 1) noise = text === NOISE_HEADING
+      else open = { title: text, line: lineOf(node), nodes: [] }
+      continue
+    }
+    open?.nodes.push(node)
+  }
+  close(content.split(/\r?\n/).length - 1)
+  return entries
+}
+
+/** Every `## ` finding in a finding-gate file, in file order. */
+export const findingEntries = (content: string): readonly FindingEntry[] =>
+  parse(content).map(
+    ({ title, body, noise, fix, guidance, boxes, headingLine }): FindingEntry => ({
+      title,
+      body,
+      noise,
+      fix,
+      guidance,
+      boxes,
+      headingLine,
+    }),
+  )
+
+const entryFindings = (content: string): readonly SteeringFinding[] =>
+  parse(content).flatMap((e): SteeringFinding[] => {
+    if (e.boxes === 0)
+      return [
+        {
+          message: `"${e.title}" has no \`- [ ] ${FIX_BOX}\` box — restore it, ticked to fix the finding or unticked to drop it`,
+          line: e.headingLine,
+        },
+      ]
+    if (e.boxes > 1)
+      return [
+        {
+          message: `"${e.title}" has ${e.boxes} \`${FIX_BOX}\` boxes — keep exactly one`,
+          line: e.headingLine,
+        },
+      ]
+    if (!e.fix && e.guidance !== "")
+      return [
+        {
+          message: `"${e.title}" has guidance under an unticked box — tick it to fix the finding, or delete the text to drop it`,
+          line: lineOf(e.box!),
+        },
+      ]
+    return []
+  })
+
+const findingsView = (content: string): SteeringView => {
+  const noteAt = noteLookup(content)
+  return {
+    nodes: parse(content).map((e, index): SteeringViewNode => {
+      const note = noteAt(e.headingLine)
+      return {
+        title: e.title,
+        anchor: { kind: "chunk", index },
+        group: e.noise ? NOISE_HEADING : OPEN_GROUP,
+        ...(e.boxes === 1 ? { checked: e.fix } : {}),
+        ...(e.guidance === "" ? {} : { note: e.guidance }),
+        ...(note?.thread !== undefined ? { thread: note.thread } : {}),
+        body: blockNodesOfRun(content, e.bodyNodes, { skipListItem: (i) => e.notBody.has(i) }),
+      }
+    }),
+  }
+}
+
+const findingsOutline = (content: string): readonly SteeringOutlineNode[] => {
+  const lines = content.split(/\r?\n/)
+  return [
+    ...parse(content).map(
+      (e): SteeringOutlineNode => ({
+        name: e.title,
+        detail: e.noise ? "noise" : e.fix ? FIX_BOX : "drop",
+        range: spanRange(lines, e.headingLine, Math.max(e.headingLine, e.endLine)),
+        selectionRange: lineRange(lines, e.headingLine),
+      }),
+    ),
+    ...threadOutlineNodes(content).map((t) => t.node),
+  ]
+}
+
+const findingsAnnotate: SteeringFormat["annotate"] = (
+  content,
+  anchor,
+  text,
+): SteeringAnnotateResult => {
+  const entries = parse(content)
+  const lines = content.split(/\r?\n/)
+  const resolved = ((): { line: number; blockEndLine: number; key: string } | undefined => {
+    if (anchor.kind === "chunk") {
+      const e = entries[anchor.index]
+      return e && { line: e.headingLine, blockEndLine: e.headingLine, key: `chunk:${anchor.index}` }
+    }
+    if (anchor.kind !== "paragraph") return undefined
+    const block = entries
+      .flatMap((e) => e.bodyNodes)
+      .find((n) => anchor.line >= lineOf(n) && anchor.line <= lineOf(n, true))
+    return (
+      block && {
+        line: anchor.line,
+        blockEndLine: lineOf(block, true),
+        key: `paragraph:${anchor.line}`,
+      }
+    )
+  })()
+  if (resolved === undefined) return { ok: false, reason: "anchor-not-found" }
+  const result = footnoteAttachEdits(
+    content,
+    { ...resolved, endCharacter: (lines[resolved.line] ?? "").length },
+    text,
+  )
+  return result.ok ? { ok: true, edits: result.edits } : result
+}
+
+/** Ticks or unticks a finding's box; `text` replaces its guidance, and unticking drops it. */
+// fallow-ignore-next-line complexity
+const findingsApply: SteeringFormat["apply"] = (content, anchor, opts): SteeringAnnotateResult => {
+  if (anchor.kind !== "chunk") return { ok: false, reason: "anchor-not-found" }
+  const e = parse(content)[anchor.index]
+  if (e?.box === undefined || e.boxes !== 1) return { ok: false, reason: "anchor-not-found" }
+  const fix = opts.checked ?? e.fix
+  const guidance = fix ? (opts.text ?? e.guidance).trim() : ""
+  if (fix === e.fix && guidance === e.guidance) return { ok: true, edits: [] }
+  const lines = content.split(/\r?\n/)
+  const eol = eolOf(content)
+  const start = lineOf(e.box)
+  const box = `${lines[start]!.match(/^\s*[-*+]\s+/)![0]}[${fix ? "x" : " "}] ${FIX_BOX}`
+  const text = guidance === "" ? box : `${box}${eol}${eol}${guidance.split(/\r?\n/).join(eol)}`
+  return {
+    ok: true,
+    edits: [
+      {
+        range: { start: { line: start, character: 0 }, end: lineRange(lines, e.lastLine).end },
+        newText: text,
+      },
+    ],
+  }
+}
+
+const FINDINGS_SAMPLE = `# Quality
+
+## A finding a lens wrote[^nafind1]
+
+[^nafind1]:
+    Attached via the phone UI, this note shows a comment on a finding with a
+    \`multi word code span\` that runs past eighty characters in total length.
+
+What the lens found, and where.
+
+- [x] fix
+
+Fix it the simple way.
+
+# Dropped as noise
+
+## A finding the judge called noise
+
+Why the judge dropped it.
+
+- [ ] fix
+`
+
+/** The finding gate's file: one `## ` finding each, with one `fix` box and optional guidance below it. */
+export const findingsDescriptor: SteeringFormat = {
+  sample: FINDINGS_SAMPLE,
+  validate: (content) => [...entryFindings(content), ...threadFindings(content)],
+  outline: findingsOutline,
+  actions: (content, range) => threadReplyActions(content, range.start),
+  view: findingsView,
+  annotate: findingsAnnotate,
+  apply: findingsApply,
+  // Its ticks are the human's decisions, never read-progress.
+  clearTicks: (content) => content,
+  openThreads: openThreadsOf,
+}

package/src/steering/fixtures/findings/gate.md

@@ -0,0 +1,34 @@
+# Quality
+
+## AC-1 ignores floating point
+
+_From lens correctness._
+
+Should subtract round? The criterion does not say.
+
+```ts
+// - [ ] fix, inside a fence, is no box
+```
+
+- [x] fix
+
+Round half up.
+
+## add has no test
+
+_From lens test-audit. The fixer left it unresolved._
+
+- a list in the finding's body
+- with two items
+
+- [ ] fix
+
+# Dropped as noise
+
+## add could be a method
+
+_From lens correctness. The judge called it noise (p=0.85)._
+
+A class would read better.
+
+- [ ] fix

package/src/steering/fixtures/findings/gate.read.json

@@ -0,0 +1,87 @@
+{
+  "nodes": [
+    {
+      "title": "AC-1 ignores floating point",
+      "anchor": {
+        "kind": "chunk",
+        "index": 0
+      },
+      "group": "Open",
+      "checked": true,
+      "note": "Round half up.",
+      "body": [
+        {
+          "title": "_From lens correctness._",
+          "anchor": {
+            "kind": "paragraph",
+            "line": 4
+          }
+        },
+        {
+          "title": "Should subtract round? The criterion does not say.",
+          "anchor": {
+            "kind": "paragraph",
+            "line": 6
+          }
+        },
+        {
+          "title": "// - [ ] fix, inside a fence, is no box",
+          "anchor": {
+            "kind": "paragraph",
+            "line": 8
+          }
+        }
+      ]
+    },
+    {
+      "title": "add has no test",
+      "anchor": {
+        "kind": "chunk",
+        "index": 1
+      },
+      "group": "Open",
+      "checked": false,
+      "body": [
+        {
+          "title": "_From lens test-audit. The fixer left it unresolved._",
+          "anchor": {
+            "kind": "paragraph",
+            "line": 18
+          }
+        },
+        {
+          "title": "a list in the finding's body with two items",
+          "anchor": {
+            "kind": "paragraph",
+            "line": 20
+          }
+        }
+      ]
+    },
+    {
+      "title": "add could be a method",
+      "anchor": {
+        "kind": "chunk",
+        "index": 2
+      },
+      "group": "Dropped as noise",
+      "checked": false,
+      "body": [
+        {
+          "title": "_From lens correctness. The judge called it noise (p=0.85)._",
+          "anchor": {
+            "kind": "paragraph",
+            "line": 29
+          }
+        },
+        {
+          "title": "A class would read better.",
+          "anchor": {
+            "kind": "paragraph",
+            "line": 31
+          }
+        }
+      ]
+    }
+  ]
+}

package/src/steering/index.test.ts

@@ -14,8 +14,8 @@ describe("steeringFormatFor / BUILT_IN_MODE_NAMES", () => {
     expect(steeringFormatFor("bogus")).toBeUndefined()
   })
 
-  it("lists both built-in mode names, in registry order", () => {
-    expect(BUILT_IN_MODE_NAMES).toEqual(["qa", "review"])
+  it("lists the built-in mode names, in registry order", () => {
+    expect(BUILT_IN_MODE_NAMES).toEqual(["qa", "review", "findings"])
   })
 })
 

package/src/steering/index.ts

@@ -8,6 +8,8 @@ import type {
 export { formatFinding } from "./SteeringFormat.js"
 import { qaDescriptor } from "./qa.js"
 import { reviewDescriptor } from "./review.js"
+import { findingsDescriptor } from "./findings.js"
+export { findingEntries, FIX_BOX, NOISE_HEADING, type FindingEntry } from "./findings.js"
 export {
   ANSWER_FIX,
   ANSWER_LEAD,
@@ -18,8 +20,6 @@ export {
   reviewRisks,
   reviewSections,
   REVIEW_SECTIONS,
-  sectionedReview,
-  severityLine,
   unansweredNotes,
   type ReviewChoice,
   type ReviewDecision,
@@ -50,10 +50,11 @@ export type {
   SteeringViewThread,
 } from "./SteeringFormat.js"
 
-/** The built-in registry: mode name → its format, in registry order. The single place `qa` and `review` are wired into names — everything else in this module dispatches over a resolved `SteeringFormat`, never a mode-name string. */
+/** The built-in registry: mode name → its format, in registry order. The single place the built-in formats are wired into names — everything else in this module dispatches over a resolved `SteeringFormat`, never a mode-name string. */
 const REGISTRY: ReadonlyMap<string, SteeringFormat> = new Map([
   ["qa", qaDescriptor],
   ["review", reviewDescriptor],
+  ["findings", findingsDescriptor],
 ])
 
 /** Every built-in format name, in registry order. */