@pmelab/gtd 64.3.0 → 66.0.0

package/src/steering/review.test.ts

@@ -27,6 +27,7 @@ describe("parseReviewDoc", () => {
           title: "Add calculator",
           headingLine: 4,
           description: "New add function for the calculator.",
+          detail: "New add function for the calculator.",
           descriptionInline: [{ kind: "text", value: "New add function for the calculator." }],
           descriptionNodes: [
             {
@@ -1557,6 +1558,23 @@ describe("review.apply", () => {
     ).toEqual({ ok: false, reason: "anchor-not-found" })
   })
 
+  it("a chunk anchor on a findings chunk refuses anchor-not-found", () => {
+    const doc = [
+      "# Review: abc1234",
+      "",
+      "## Findings",
+      "",
+      "### Token check",
+      "",
+      "- ./src/auth.ts#1-2",
+      "",
+    ].join("\n")
+    expect(review.apply(doc, { kind: "chunk", index: 0 }, { checked: true })).toEqual({
+      ok: false,
+      reason: "anchor-not-found",
+    })
+  })
+
   it("a question anchor — not this format's own kind — refuses anchor-not-found", () => {
     expect(review.apply(NESTED_CONTENT, { kind: "question", index: 0 }, { checked: true })).toEqual(
       { ok: false, reason: "anchor-not-found" },
@@ -1574,7 +1592,7 @@ describe("review decisions — a finding's answer boxes", () => {
     "",
     "### Token check",
     "",
-    "- [ ] ./src/auth.ts#1-2",
+    "- ./src/auth.ts#1-2",
     "",
     "Tick exactly one:",
     "",
@@ -2169,7 +2187,7 @@ describe("review — sectioned layout", async () => {
       "",
       "Leaks a token.",
       "",
-      "- [ ] ./src/a.ts#1-2 — here",
+      "- ./src/a.ts#1-2 — here",
       "",
       ...boxes(ticked),
       "",
@@ -2228,16 +2246,16 @@ describe("review — sectioned layout", async () => {
   it("outlines the sections as containers, each finding's decision a node of its own", () => {
     const outline = viewOf(review, sectioned()).outline
     expect(outline.map((n) => n.name)).toEqual(["Findings", "Walkthrough", "Fixed automatically"])
-    expect(outline[0]!.children!.map((n) => n.name)).toEqual(["A finding (0/1)"])
+    expect(outline[0]!.children!.map((n) => n.name)).toEqual(["A finding"])
     expect(outline[0]!.children![0]!.children!.map((n) => n.name)).toEqual(["Decision: open"])
     expect(outline[0]!.children![0]!.children![0]!.selectionRange.start.line).toBe(14)
     // A fully ticked walkthrough chunk is reviewed: its section is left empty.
     expect(outline[1]!.children).toEqual([])
   })
 
-  it("names the ticked decision, and keeps a decided finding while a hunk is unticked", () => {
+  it("drops a decided finding from the outline: its location carries no read tick", () => {
     const outline = viewOf(review, sectioned(1)).outline
-    expect(outline[0]!.children![0]!.children!.map((n) => n.name)).toEqual(["Decision: won't fix"])
+    expect(outline[0]!.children).toEqual([])
   })
 
   it("groups the view's chunks by section, anchors unchanged", () => {
@@ -2256,3 +2274,161 @@ describe("review — sectioned layout", async () => {
     expect(titles.some((t) => t.includes("A finding"))).toBe(false)
   })
 })
+
+describe("review — finding locations and decision actions", () => {
+  const finding = (pointer: string, ticked?: 0 | 1 | 2): string =>
+    [
+      "# Review: abc1234",
+      "",
+      "<!-- base: abc1234def5678901234567890123456789abcd -->",
+      "",
+      "## Findings",
+      "",
+      "### A finding",
+      "",
+      pointer,
+      "",
+      "Tick exactly one:",
+      "",
+      `- [${ticked === 0 ? "x" : " "}] fix as suggested`,
+      `- [${ticked === 1 ? "x" : " "}] won't fix`,
+      `- [${ticked === 2 ? "x" : " "}] _your answer_`,
+      "",
+    ].join("\n")
+  const at = (content: string, line: number) =>
+    review.actions!(content, { start: { line, character: 0 }, end: { line, character: 0 } })
+
+  it("links a plain location and resolves go-to-definition to its line", () => {
+    const content = finding("- ./src/a.ts#5-6 — here")
+    expect(review.validate(content)).toEqual([])
+    expect(review.documentLinks!(content)).toEqual([
+      expect.objectContaining({ path: "./src/a.ts", line: 4 }),
+    ])
+    expect(review.pointerAt!(content, { line: 8, character: 3 })).toEqual({
+      path: "./src/a.ts",
+      line: 4,
+    })
+  })
+
+  it("refuses a checkbox pointer in a finding at its own line", () => {
+    for (const box of ["[ ]", "[x]"]) {
+      const found = review.validate(finding(`- ${box} ./src/a.ts#5-6`))
+      expect(found.some((f) => f.line === 8)).toBe(true)
+    }
+  })
+
+  it("offers no hunk tick and no read count for a finding location", () => {
+    const content = finding("- ./src/a.ts#5-6")
+    const titles = at(content, 8).map((a) => a.title)
+    expect(titles.some((t) => t.includes("hunk"))).toBe(false)
+    expect(viewOf(review, content).outline[0]!.children![0]!.name).toBe("A finding")
+    const hunk = review.view(content).nodes[0]!.children![0]!
+    expect(hunk.checked).toBeUndefined()
+    expect(review.apply(content, hunk.anchor, { checked: true }).ok).toBe(false)
+  })
+
+  it("accepts, rejects and answers from any line, leaving out the current tick's action", () => {
+    const content = finding("- ./src/a.ts#5-6")
+    for (const line of [6, 8, 12]) {
+      expect(at(content, line).map((a) => a.title)).toEqual(
+        expect.arrayContaining([
+          "gtd: accept finding",
+          "gtd: reject finding",
+          "gtd: answer finding",
+        ]),
+      )
+    }
+    const run = (title: string, text: string) =>
+      applySteeringEdits(text, at(text, 8).find((a) => a.title === title)!.edits)
+    const accepted = run("gtd: accept finding", finding("- ./src/a.ts#5-6", 1))
+    expect(accepted).toBe(finding("- ./src/a.ts#5-6", 0))
+    expect(at(accepted, 8).map((a) => a.title)).not.toContain("gtd: accept finding")
+    expect(run("gtd: reject finding", accepted)).toBe(finding("- ./src/a.ts#5-6", 1))
+    expect(run("gtd: answer finding", accepted)).toBe(finding("- ./src/a.ts#5-6", 2))
+  })
+
+  it("selects the whole free-text slot on answer", () => {
+    const content = finding("- ./src/a.ts#5-6")
+    const answer = at(content, 8).find((a) => a.title === "gtd: answer finding")!
+    expect(answer.select).toEqual({
+      start: { line: 14, character: 6 },
+      end: { line: 14, character: 19 },
+    })
+  })
+
+  it("offers no finding actions on a top-level comments chunk", () => {
+    const content = finding("- ./src/a.ts#5-6").replace(
+      "## Findings\n\n### A finding",
+      "## Your comments:",
+    )
+    expect(
+      at(content, 6)
+        .map((a) => a.title)
+        .join(),
+    ).not.toContain("finding")
+  })
+})
+
+describe("review view drafted comment", () => {
+  const doc = (pointer: string) => `# Review
+
+## Findings
+
+### Token check
+
+_correctness · judge: fix_
+
+${pointer}Draft PR comment:
+
+> nit: Uses \`==\`.
+> Impact: Timing leak.
+> Fix: Use \`timingSafeEqual\`.
+>
+> \`\`\`suggestion
+> return ok
+> \`\`\`
+
+Tick exactly one:
+
+- [ ] fix as suggested
+- [ ] won't fix
+- [ ] _your answer_
+`
+  for (const [name, pointer] of [
+    ["with a pointer", "- [ ] ./src/auth.ts#1-3\n\n"],
+    ["without a pointer", ""],
+  ] as const) {
+    it(`splits the comment into What, Impact and Fix ${name}`, () => {
+      const node = steeringFormatFor("review")!.view(doc(pointer)).nodes[0]!
+      expect(node.comment?.map((s) => s.label)).toEqual(["What", "Impact", "Fix"])
+      const fix = node.comment![2]!.body
+      expect(fix.some((n) => n.block?.kind === "code" && n.block.text === "return ok")).toBe(true)
+      expect(node.detail).not.toContain("Draft PR comment")
+    })
+  }
+
+  it("keeps an unlabelled comment as one What", () => {
+    const node = steeringFormatFor("review")!.view(
+      doc("")
+        .replace(/Impact:[^]*?```\n\nTick/, "Plain.\n\nTick")
+        .replace("> nit: Uses `==`.\n> ", "> nit: Uses."),
+    ).nodes[0]!
+    expect(node.comment?.map((s) => s.label)).toEqual(["What"])
+  })
+
+  it("keeps a Fix: line inside a suggestion fence in its code block", () => {
+    const node = steeringFormatFor("review")!.view(
+      doc("").replace("> return ok", "> Fix: inside\n> return ok"),
+    ).nodes[0]!
+    expect(node.comment?.map((s) => s.label)).toEqual(["What", "Impact", "Fix"])
+    const code = node.comment![2]!.body.find((n) => n.block?.kind === "code")
+    expect(code?.block?.text).toContain("Fix: inside")
+  })
+
+  it("leaves the comment in the body of a chunk with no answer list", () => {
+    const node = steeringFormatFor("review")!.view(doc("").replace(/Tick exactly one:[^]*$/, ""))
+      .nodes[0]!
+    expect(node.comment).toBeUndefined()
+    expect(node.detail).toContain("Draft PR comment")
+  })
+})

package/src/steering/review.ts

@@ -37,6 +37,7 @@ import {
 } from "./MarkdownTree.js"
 import { FREE_TEXT_PLACEHOLDER, normalizeFreeTextAnswer } from "./qa.js"
 import type {
+  SteeringAction,
   SteeringAnchor,
   SteeringAnnotateResult,
   SteeringEdit,
@@ -46,6 +47,7 @@ import type {
   SteeringOutlineNode,
   SteeringView,
   SteeringViewNode,
+  SteeringViewSection,
 } from "./SteeringFormat.js"
 
 interface ReviewFile {
@@ -55,6 +57,8 @@ interface ReviewFile {
   /** 1-based post-image end line of a `#<start>-<end>` range — `line` holds the start. Absent for a bare `#<line>` pointer or a `#`-less one. */
   readonly rangeEnd?: number
   readonly checked: boolean
+  /** A finding's location: a plain list item with no tick box. */
+  readonly plain?: boolean
   /** The pointer's explanation: same-line text (if any) first, then the lines gathered from BELOW it, joined with " ". */
   readonly note?: string
   /** `note`'s own inline structure, image-collapsed (R2) — feeds the hunk node's `detailInline`. Absent exactly where `note` is. */
@@ -68,10 +72,14 @@ interface ReviewFile {
 interface Changeset {
   readonly title: string
   readonly description: string
+  /** `description` without the drafted comment: what the view shows. */
+  readonly detail: string
   /** The same leading run collapsed into `description`, projected as block nodes (`Blocks.ts#blockNodesOfRun`) instead of flattened text — `Review.tsx`'s chunk screen renders these through the shared prose-block rendering. */
   readonly descriptionNodes: readonly SteeringViewNode[]
   /** `description`'s own inline structure, image-collapsed (R2) — feeds the chunk node's `detailInline`. */
   readonly descriptionInline: readonly InlineNode[]
+  /** The drafted PR comment (de-quoted markdown) of a decision chunk, when it carries one. */
+  readonly comment?: string
   readonly files: readonly ReviewFile[]
   /** 0-based index of this chunk's `##` heading. */
   readonly headingLine: number
@@ -375,6 +383,7 @@ const buildHunkFile = (
     ...(parsed.line !== undefined ? { line: parsed.line } : {}),
     ...(parsed.rangeEnd !== undefined ? { rangeEnd: parsed.rangeEnd } : {}),
     checked: item.checked === true,
+    ...(item.checked === null ? { plain: true } : {}),
     sourceLine,
     endLine: hunkOwnEndLine(item, sourceLine),
     ...(note.length > 0 ? { note, noteInline } : {}),
@@ -530,6 +539,31 @@ const answerListOf = (
   return { lead, list, options }
 }
 
+const COMMENT_LABEL_RE = /^(Impact|Fix):[ \t]*/
+
+/** Splits a drafted comment at its `Impact:` / `Fix:` lines (outside fences) into labelled block sections; no labels is one What. */
+const commentSections = (comment: string): readonly SteeringViewSection[] => {
+  const parts: { label: string; lines: string[] }[] = [{ label: "What", lines: [] }]
+  let fence: string | undefined
+  for (const line of comment.split("\n")) {
+    const marker = /^\s*(`{3,}|~{3,})/.exec(line)?.[1]
+    if (marker !== undefined) {
+      if (fence === undefined) fence = marker
+      else if (marker.startsWith(fence)) fence = undefined
+    }
+    const label = fence === undefined && marker === undefined ? COMMENT_LABEL_RE.exec(line) : null
+    if (label) parts.push({ label: label[1]!, lines: [line.slice(label[0].length)] })
+    else parts.at(-1)!.lines.push(line)
+  }
+  return parts
+    .map(({ label, lines }) => ({ label, text: lines.join("\n").trim() }))
+    .filter(({ text }) => text.length > 0)
+    .map(({ label, text }) => ({
+      label,
+      body: blockNodesOfRun(text, parseMarkdown(text).children),
+    }))
+}
+
 /** A leading severity line is the chunk's tier, never its prose. */
 const splitSeverity = (
   content: string,
@@ -550,17 +584,32 @@ const splitSeverity = (
   }
 }
 
+/** Every `listItem` under `node`, task or plain, at any depth. */
+const allListItems = (node: RootContent): readonly ListItem[] => {
+  const items: ListItem[] = []
+  const walk = (n: { type: string; children?: readonly unknown[] }): void => {
+    if (n.type === "listItem") items.push(n as unknown as ListItem)
+    n.children?.forEach((c) => walk(c as { type: string; children?: readonly unknown[] }))
+  }
+  walk(node)
+  return items
+}
+
 /** Splits one chunk's body nodes into its file pointers (hunk pointers are task items, collected recursively at ANY nesting depth via `taskItems` — a nested hunk is the same kind of hunk as a top-level one) and description prose. The description is the chunk's own leading run and never a node that contains a hunk pointer: it stops at the first node whose `taskItems` include a real pointer (at any depth — a blockquote wrapping a pointer list stops it just as a top-level list would). Every node kind in what's left before that point contributes — a `footnoteDefinition` is the one exception, excluded by `blockNodesOfRun` itself (it's a note, never document content). */
+// fallow-ignore-next-line complexity
 const parseChunkBody = (
   content: string,
   lines: readonly string[],
   title: string,
   body: readonly RootContent[],
   answerable: boolean,
+  finding: boolean,
 ): {
   readonly description: string
+  readonly detail: string
   readonly descriptionNodes: readonly SteeringViewNode[]
   readonly descriptionInline: readonly InlineNode[]
+  readonly comment?: string
   readonly files: readonly ReviewFile[]
   readonly errors: readonly SteeringFinding[]
   readonly answers?: readonly AnswerOption[]
@@ -573,33 +622,70 @@ const parseChunkBody = (
   const answer = answerable ? answerListOf(content, body) : undefined
   const isAnswer = (n: RootContent): boolean =>
     answer !== undefined && (n === answer.list || n === body[answer.lead])
+  const pointerItems = (n: RootContent): readonly ListItem[] =>
+    finding ? allListItems(n) : taskItems(n)
   const firstPointerIndex = body.findIndex(
-    (n) => !isAnswer(n) && taskItems(n).some((item) => hasPointerToken(content, item)),
+    (n) => !isAnswer(n) && pointerItems(n).some((item) => hasPointerToken(content, item)),
   )
   const run = (firstPointerIndex === -1 ? body : body.slice(0, firstPointerIndex)).filter(
     (n) => !isAnswer(n),
   )
-  const { severity, leadingRun } = splitSeverity(content, run)
+  // The drafted comment: the blockquote right after a `Draft PR comment:` line, wherever the pointer sits.
+  const draftIndex =
+    answer !== undefined
+      ? body.findIndex(
+          (n, i) =>
+            !isAnswer(n) &&
+            n.type === "blockquote" &&
+            body[i - 1]?.type === "paragraph" &&
+            /^draft pr comment:?$/i.test(sourceText(content, body[i - 1]!).trim()),
+        )
+      : -1
+  const comment =
+    draftIndex === -1
+      ? undefined
+      : content
+          .slice(body[draftIndex]!.position!.start.offset!, body[draftIndex]!.position!.end.offset!)
+          .split("\n")
+          .map((l) => l.replace(/^\s*> ?/, ""))
+          .join("\n")
+          .trim()
+  const draftNodes = new Set(draftIndex === -1 ? [] : [body[draftIndex], body[draftIndex - 1]])
+  const { severity, leadingRun: fullRun } = splitSeverity(content, run)
+  const leadingRun = fullRun.filter((n) => !draftNodes.has(n))
   const descriptionNodes = blockNodesOfRun(content, leadingRun)
   const descriptionInline = collapseImages(blockRunInline(content, leadingRun))
-  const description = leadingRun
-    .filter((n) => n.type !== "footnoteDefinition")
-    .map((n) => sourceText(content, n))
-    .join(" ")
-    .trim()
+  const textOf = (nodes: readonly RootContent[]): string =>
+    nodes
+      .filter((n) => n.type !== "footnoteDefinition")
+      .map((n) => sourceText(content, n))
+      .join(" ")
+      .trim()
+  // `description` stays whole: it is the decision body gtd hands to the fixer.
+  const description = textOf(fullRun)
+  const detail = textOf(leadingRun)
 
   const files: ReviewFile[] = []
   const errors: SteeringFinding[] = []
-  for (const item of body.filter((n) => !isAnswer(n)).flatMap((n) => taskItems(n))) {
+  for (const item of body.filter((n) => !isAnswer(n)).flatMap((n) => pointerItems(n))) {
     const parsed = parseHunk(content, lines, title, item)
     if (!parsed) continue
+    if (finding && item.checked !== null) {
+      errors.push({
+        message: `Chunk "${title}" finding location ${pointerDisplay(parsed.file)} must be a plain list item — drop the checkbox`,
+        line: parsed.file.sourceLine,
+        range: lineRange(lines, parsed.file.sourceLine),
+      })
+    }
     files.push(parsed.file)
     errors.push(...parsed.errors)
   }
   return {
     description,
+    detail,
     descriptionNodes,
     descriptionInline,
+    ...(comment === undefined ? {} : { comment }),
     files,
     errors,
     ...(answer === undefined
@@ -690,15 +776,24 @@ const parseChangesets = (
     const title = headingText(content, heading)
     const {
       description,
+      detail,
       descriptionNodes,
       descriptionInline,
+      comment,
       files,
       answers,
       answerLine,
       severity,
       boxed,
       errors: bodyErrors,
-    } = parseChunkBody(content, lines, title, body, section !== "walkthrough")
+    } = parseChunkBody(
+      content,
+      lines,
+      title,
+      body,
+      section !== "walkthrough",
+      section === "findings",
+    )
     errors.push(...bodyErrors)
     // A prose-only chunk is a note gtd composed; a box with no pointer is a pointer gone wrong.
     if (files.length === 0 && boxed) {
@@ -711,8 +806,10 @@ const parseChangesets = (
     changesets.push({
       title,
       description,
+      detail,
       descriptionNodes,
       descriptionInline,
+      ...(comment === undefined ? {} : { comment }),
       files,
       headingLine,
       ...(answers === undefined ? {} : { answers, answerLine: answerLine! }),
@@ -878,7 +975,7 @@ const decisionNodes = (
 }
 
 const isOpenChunk = (chunk: Changeset, markers: number): boolean =>
-  chunk.files.some((file) => !file.checked) ||
+  chunk.files.some((file) => !file.plain && !file.checked) ||
   markers > 0 ||
   (chunk.answers !== undefined && decisionOf(chunk) === undefined)
 
@@ -917,7 +1014,7 @@ const reviewOutline = (content: string): readonly SteeringOutlineNode[] => {
     if (!listed && !isOpenChunk(chunk, chunkMarkers.length)) return []
     const node: SteeringOutlineNode = {
       name:
-        chunk.files.length === 0
+        chunk.files.length === 0 || chunk.section === "findings"
           ? chunk.title
           : `${chunk.title} (${checkedCount}/${chunk.files.length})`,
       range: spanRange(lines, start, end),
@@ -991,6 +1088,39 @@ const footnoteBlockEnd = (content: string, tree: Root, cursorLine: number): numb
   return block?.position ? toLspPosition(block.position.end).line : cursorLine
 }
 
+const FINDING_ACTIONS = [
+  { title: "gtd: accept finding", index: 0 },
+  { title: "gtd: reject finding", index: 1 },
+  { title: "gtd: answer finding", index: 2 },
+] as const
+
+/** Accept / reject / answer for one finding chunk; the one matching its single current tick is left out. */
+const findingActions = (
+  content: string,
+  chunk: Changeset,
+  chunkIndex: number,
+): Array<{ title: string; edits: readonly SteeringEdit[]; select?: SteeringAction["select"] }> => {
+  if (chunk.answers?.length !== 3) return []
+  const ticked = chunk.answers.flatMap((o, i) => (o.checked ? [i] : []))
+  const current = ticked.length === 1 ? ticked[0] : undefined
+  const items = answerItemsOf(content, chunkIndex)
+  return FINDING_ACTIONS.filter((a) => a.index !== current).flatMap((a) => {
+    const result = decisionEdits(content, chunkIndex, a.index, {})
+    if (!result.ok) return []
+    const slot = items[2]
+    const from = slot ? firstParagraphContentOffset(slot) : undefined
+    const to = slot?.children.find((c) => c.type === "paragraph")?.position?.end.offset
+    const select =
+      a.index === 2 && from !== undefined && to !== undefined
+        ? {
+            start: toLspPositionFromOffset(content, from),
+            end: toLspPositionFromOffset(content, to),
+          }
+        : undefined
+    return [{ title: a.title, edits: result.edits, ...(select ? { select } : {}) }]
+  })
+}
+
 /**
  * Actions for `.gtd/REVIEW.md`: "check/uncheck this hunk" when `range` sits
  * on a hunk line, "check/uncheck all hunks" when `range` sits anywhere in a
@@ -1014,7 +1144,7 @@ const reviewActions: SteeringFormat["actions"] = (content, range) => {
     const hunk = chunk.files.find(
       (file) => cursorLine >= file.sourceLine && cursorLine <= file.endLine,
     )
-    if (hunk) {
+    if (hunk && !hunk.plain) {
       const edit = toggleFilePointer(content, hunk.sourceLine)
       if (edit) {
         actions.push({
@@ -1029,7 +1159,15 @@ const reviewActions: SteeringFormat["actions"] = (content, range) => {
       chunk.section === undefined
         ? Math.max(chunk.headingLine, (changesets[i + 1]?.headingLine ?? lines.length) - 1)
         : (endLines.get(chunk.headingLine) ?? chunk.headingLine)
-    if (chunk.files.length > 0 && cursorLine >= chunk.headingLine && cursorLine <= chunkEnd) {
+    if (chunk.section === "findings" && cursorLine >= chunk.headingLine && cursorLine <= chunkEnd) {
+      actions.push(...findingActions(content, chunk, i))
+    }
+    if (
+      chunk.section !== "findings" &&
+      chunk.files.length > 0 &&
+      cursorLine >= chunk.headingLine &&
+      cursorLine <= chunkEnd
+    ) {
       const edits = toggleChunkEdits(content, chunk.headingLine)
       if (edits.length > 0) {
         const checkedCount = chunk.files.filter((file) => file.checked).length
@@ -1113,7 +1251,10 @@ const reviewDocumentLinks = (content: string): readonly SteeringLink[] => {
   const tree = parseMarkdown(content)
   const links: SteeringLink[] = []
   for (const block of splitChunks(tree, content).chunks) {
-    for (const item of block.body.flatMap((n) => taskItems(n))) {
+    const items = block.body.flatMap((n) =>
+      block.section === "findings" ? allListItems(n) : taskItems(n),
+    )
+    for (const item of items) {
       const link = hunkLinkFor(content, item)
       if (link) links.push(link)
     }
@@ -1129,9 +1270,10 @@ const reviewView = (content: string): SteeringView => {
     ...(shortHash ? { header: shortHash } : {}),
     nodes: changesets.map((chunk, chunkIndex) => ({
       title: chunk.title,
-      detail: chunk.description,
+      detail: chunk.detail,
       detailInline: chunk.descriptionInline,
       body: chunk.descriptionNodes,
+      ...(chunk.comment === undefined ? {} : { comment: commentSections(chunk.comment) }),
       ...(chunk.severity === undefined ? {} : { status: chunk.severity.label }),
       anchor: { kind: "chunk", index: chunkIndex },
       ...(chunk.section === undefined ? {} : { group: REVIEW_SECTIONS[chunk.section] }),
@@ -1151,7 +1293,7 @@ const reviewView = (content: string): SteeringView => {
         path: file.path,
         ...(file.line !== undefined ? { line: file.line } : {}),
         ...(file.rangeEnd !== undefined ? { endLine: file.rangeEnd } : {}),
-        checked: file.checked,
+        ...(file.plain ? {} : { checked: file.checked }),
         ...(file.note !== undefined
           ? { detail: file.note, detailInline: file.noteInline ?? [] }
           : {}),
@@ -1339,12 +1481,12 @@ const reviewApply: SteeringFormat["apply"] = (content, anchor, opts) => {
   const checked = opts.checked ?? true
   if (anchor.kind === "hunk") {
     const file = changesets[anchor.chunkIndex]?.files[anchor.index]
-    if (!file) return { ok: false, reason: "anchor-not-found" }
+    if (!file || file.plain) return { ok: false, reason: "anchor-not-found" }
     return { ok: true, edits: setFileTickEdits(content, [file], checked) }
   }
   if (anchor.kind === "chunk") {
     const chunk = changesets[anchor.index]
-    if (!chunk) return { ok: false, reason: "anchor-not-found" }
+    if (!chunk || chunk.section === "findings") return { ok: false, reason: "anchor-not-found" }
     return { ok: true, edits: setFileTickEdits(content, chunk.files, checked) }
   }
   return { ok: false, reason: "anchor-not-found" }

package/src/step/LandStep.ts

@@ -12,6 +12,18 @@ export type GitWrite =
   | { readonly kind: "commitClean"; readonly message: string }
   | { readonly kind: "updateRef"; readonly ref: string; readonly target: "HEAD" }
   | { readonly kind: "keepTurn"; readonly ref: string; readonly message: string }
+  | { readonly kind: "switchBranch"; readonly branch: string }
+  | { readonly kind: "switchTo"; readonly branch: string }
+  | { readonly kind: "pushRef"; readonly remote: string; readonly ref: string }
+  | ({ readonly kind: "ship"; readonly message: string } & ShipSpec)
+
+/** A ship step's squash: `shipMessage` on `branch`, CAS against `parent`, its `Gtd-History` naming `historyRef`. */
+export interface ShipSpec {
+  readonly branch: string
+  readonly parent: string
+  readonly shipMessage: string
+  readonly historyRef: string
+}
 
 /** A landed step's trailing report, rendered by `GitScript.ts` into a `printf` line. */
 export type Outcome =

package/src/step/RepoSnapshot.ts

@@ -1,5 +1,6 @@
 import type { CommitSpec } from "../replay/index.js"
 import type { PendingChange, StateName, StepDef } from "../workflow/index.js"
+import type { ShipSpec } from "./LandStep.js"
 
 /**
  * What landing the pending turn does, decided at the edge by replaying the
@@ -19,8 +20,22 @@ export type Landing =
       readonly keepHistory?: string
       /** The kept ref this landing's turn goes to; the branch gets a marker commit instead. */
       readonly keepTurn?: string
+      /** The `gtd/<b>` branch a starting landing switches to before it commits. */
+      readonly startBranch?: string
+      /** The user's branch `<b>` a finishing landing switches back to, after its history ref. */
+      readonly leaveBranch?: string
+      /** A remote the closing or shipping landing force-pushes its history ref to, after the commit. */
+      readonly pushHistory?: string
+      /** A ship step's squash onto the user's branch, made ahead of the landing commit. */
+      readonly ship?: ShipSpec
+      /** The history ref of a landing that only records an earlier ship (`ship` is unset). */
+      readonly recordedHistory?: string
+      /** Printed after the landing: why a ship step shipped nothing. */
+      readonly note?: string
       /** The one path this landing commits; every other pending change stays pending. */
       readonly only?: string
+      /** Review-gate landing into an agent turn: the human's ticks are committed. */
+      readonly keepTicks?: boolean
     }
 
 /**

package/src/step/index.ts

@@ -1,6 +1,7 @@
 export { planStep, type JudgeVerdict } from "./planStep.js"
 export { accessRefusal } from "./accessRefusal.js"
 export { planStart } from "./planStart.js"
+export { startBranchFor, GTD_BRANCH_PREFIX, userBranchOf } from "./startBranch.js"
 export type { GitWrite, LandStep, Outcome } from "./LandStep.js"
 export type { Landing, RepoSnapshot } from "./RepoSnapshot.js"
 export { strayPaths } from "./strayPaths.js"