@pmelab/gtd 24.3.0 → 24.4.0

package/src/steering/contract.test.ts

@@ -174,6 +174,7 @@ describe("review notes, the review → fix hand-off", () => {
         anchor: "Parser accepts CRLF",
         before: "**Line endings are normalized before the split.**",
         text: "**Line endings are normalized before the split.** Also normalize in the writer.",
+        forced: false,
       },
       {
         id: "note-2",
@@ -181,6 +182,7 @@ describe("review notes, the review → fix hand-off", () => {
         anchor: "Parser accepts CRLF ./src/parse.ts#30-31",
         before: "Risk: a lone `\\r` is still kept as content",
         text: "Risk: a lone `\\r` is still kept as content. Treat it as a line break too.",
+        forced: false,
       },
       {
         id: "note-3",
@@ -188,6 +190,7 @@ describe("review notes, the review → fix hand-off", () => {
         anchor: "- [x] ./src/parse.test.ts#1-40 — one case per line ending[^fn1]",
         before: "",
         text: "Add a mixed-endings case.",
+        forced: false,
       },
     ])
   })

package/src/steering/index.ts

@@ -5,6 +5,7 @@ import type {
   SteeringOutlineNode,
   SteeringPointer,
 } from "./SteeringFormat.js"
+export { formatFinding } from "./SteeringFormat.js"
 import { qaDescriptor } from "./qa.js"
 import { reviewDescriptor } from "./review.js"
 export { reviewNotes, reviewRisks, type ReviewNote } from "./review.js"

package/src/steering/review.test.ts

@@ -1733,6 +1733,7 @@ describe("reviewNotes", async () => {
         anchor: "Chunk one ./src/a.ts#1-3",
         before: "",
         text: "rename this",
+        forced: false,
       },
     ])
   })
@@ -1753,6 +1754,7 @@ describe("reviewNotes", async () => {
         anchor: "- [ ] ./src/a.ts#1-3[^n1]",
         before: "",
         text: "please split",
+        forced: false,
       },
     ])
   })
@@ -1774,6 +1776,34 @@ describe("reviewNotes", async () => {
     expect(reviewNotes(answered, more).map((n) => n.kind)).toEqual(["footnote"])
   })
 
+  it("a leading ! forces a pointer note and keeps its text", () => {
+    const [n] = reviewNotes(base, base.replace("#1-3", "#1-3 !  rename this"))
+    expect(n).toMatchObject({ kind: "pointer", text: "! rename this", forced: true })
+  })
+
+  it("a leading ! forces a footnote note", () => {
+    const after = base.replace("#1-3", "#1-3[^n1]") + "\n[^n1]: ! please split\n"
+    expect(reviewNotes(base, after)[0]).toMatchObject({ text: "! please split", forced: true })
+  })
+
+  it("a leading ! forces chunk prose", () => {
+    const [n] = reviewNotes(base, doc("! Prose is wrong."))
+    expect(n).toMatchObject({ kind: "chunk", text: "! Prose is wrong.", forced: true })
+  })
+
+  it("a ! glued to the next word is not a marker", () => {
+    const [n] = reviewNotes(base, base.replace("#1-3", "#1-3 != should be ==="))
+    expect(n).toMatchObject({ text: "!= should be ===", forced: false })
+  })
+
+  it("a mid-text ! or a ! in the pointer path does not force", () => {
+    const [n] = reviewNotes(base, base.replace("#1-3", "#1-3 rename this!"))
+    expect(n).toMatchObject({ text: "rename this!", forced: false })
+    const [m] = reviewNotes(base, base.replace("./src/a.ts#1-3", "./src/a!b.ts#1-3 x"))
+    expect(m).toMatchObject({ forced: false })
+    expect(m!.anchor).toContain("a!b.ts")
+  })
+
   it("ids run in document order", () => {
     const after = base.replace("#1-3", "#1-3 a[^n1]") + "\n[^n1]: b\n"
     expect(reviewNotes(base, after).map((n) => [n.id, n.kind])).toEqual([

package/src/steering/review.ts

@@ -1085,12 +1085,14 @@ export interface ReviewNote {
   readonly before: string
   /** The human's text. */
   readonly text: string
+  /** The human opened `text` with `! ` (kept in `text`; the feature review strips it). */
+  readonly forced?: boolean
 }
 
 const pointerLabel = (f: ReviewFile): string =>
   `${f.path}${f.line === undefined ? "" : `#${f.line}${f.rangeEnd === undefined ? "" : `-${f.rangeEnd}`}`}`
 
-type Found = { line: number; note: Omit<ReviewNote, "id"> }
+type Found = { line: number; note: Omit<ReviewNote, "id" | "forced"> }
 
 const chunkNote = (chunk: Changeset, prior: Changeset | undefined): Found[] =>
   chunk.description === (prior?.description ?? "")
@@ -1162,7 +1164,11 @@ export const reviewNotes = (before: string, after: string): readonly ReviewNote[
     }),
     ...footnoteNotes(before, after),
   ]
-  return found.sort((a, b) => a.line - b.line).map((f, i) => ({ id: `note-${i + 1}`, ...f.note }))
+  return found
+    .sort((a, b) => a.line - b.line)
+    .map((f, i) => {
+      return { id: `note-${i + 1}`, ...f.note, forced: /^!(\s|$)/.test(f.note.text) }
+    })
 }
 
 /** Pointer notes the reviewer opened with `Risk:`, in document order — the ones the workflow fixes before the human gate. */

package/src/testkit/EmittedScriptRecognizer.test.ts

@@ -42,7 +42,7 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
     const result = applyEmittedScript(repo, NO_COMMANDS, commitAll("gtd(agent): building"))
     twin.commitAllWithPrefix("gtd(agent): building")
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(snapshot(repo)).toEqual(snapshot(twin))
   })
 
@@ -60,7 +60,7 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
 
     const result = applyEmittedScript(repo, NO_COMMANDS, commitAll(message))
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(repo.lastCommitMessage()).toBe(message)
   })
 
@@ -77,7 +77,7 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
     const result = applyEmittedScript(repo, NO_COMMANDS, commitAsIs("gtd(agent): as-is"))
     twin.commitAsIs("gtd(agent): as-is")
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(snapshot(repo)).toEqual(snapshot(twin))
   })
 
@@ -97,7 +97,7 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
     const result = applyEmittedScript(repo, NO_COMMANDS, softResetTo(first))
     twin.softResetTo(first)
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(snapshot(repo)).toEqual(snapshot(twin))
     expect(repo.resolveRef("HEAD")).toBe(first)
   })
@@ -118,7 +118,7 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
     const result = applyEmittedScript(repo, NO_COMMANDS, mixedResetTo(first))
     twin.mixedResetTo(first)
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(snapshot(repo)).toEqual(snapshot(twin))
   })
 
@@ -138,7 +138,7 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
     const result = applyEmittedScript(repo, NO_COMMANDS, hardResetTo(first))
     twin.hardResetTo(first)
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(snapshot(repo)).toEqual(snapshot(twin))
     expect(repo.hasPath("b.txt")).toBe(false)
   })
@@ -158,7 +158,7 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
     const result = applyEmittedScript(repo, NO_COMMANDS, discardPending())
     twin.discardPending()
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(snapshot(repo)).toEqual(snapshot(twin))
     expect(repo.readFile("a.txt")).toBe("1")
     expect(repo.hasPath("untracked.txt")).toBe(false)
@@ -176,7 +176,7 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
     const result = applyEmittedScript(repo, NO_COMMANDS, updateRef("refs/gtd/base", hash))
     twin.updateRef("refs/gtd/base", hash)
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(repo.resolveRef("refs/gtd/base")).toBe(hash)
     expect(snapshot(repo)).toEqual(snapshot(twin))
   })
@@ -194,7 +194,7 @@ describe("applyEmittedScript — the 8 GitScript builders", () => {
     const result = applyEmittedScript(repo, NO_COMMANDS, deleteRef("refs/gtd/base"))
     twin.deleteRef("refs/gtd/base")
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(repo.resolveRef("refs/gtd/base")).toBeNull()
     expect(snapshot(repo)).toEqual(snapshot(twin))
   })
@@ -210,7 +210,7 @@ describe("applyEmittedScript — gtd check <mode> <file>", () => {
 
     const result = applyEmittedScript(repo, NO_COMMANDS, "gtd check qa '.gtd/TODO.md'")
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
   })
 
   it("fails on invalid qa-mode content (a bare ### heading with no question text)", () => {
@@ -220,7 +220,7 @@ describe("applyEmittedScript — gtd check <mode> <file>", () => {
     const result = applyEmittedScript(repo, NO_COMMANDS, "gtd check qa '.gtd/TODO.md'")
 
     expect(result.ok).toBe(false)
-    expect(result.error).toContain("gtd check qa")
+    expect(result.output).toContain('.gtd/TODO.md is not valid under mode "qa"')
   })
 })
 
@@ -231,7 +231,7 @@ describe("applyEmittedScript — Emit.ts's fileExistsGuard", () => {
 
     const result = applyEmittedScript(repo, NO_COMMANDS, fileExistsGuard(".gtd/PLAN.md"))
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
   })
 
   it("stops the whole script (successfully) when the file is absent — unlike every other guard, it does not fail", () => {
@@ -240,7 +240,7 @@ describe("applyEmittedScript — Emit.ts's fileExistsGuard", () => {
     const script = [fileExistsGuard(".gtd/PLAN.md"), "gtd check qa '.gtd/PLAN.md'"].join("\n\n")
     const result = applyEmittedScript(repo, NO_COMMANDS, script)
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
   })
 
   it("a subsequent block after the guard trips is never applied", () => {
@@ -262,7 +262,7 @@ describe("applyEmittedScript — ModeContradiction.ts's skip notice", () => {
 
     const result = applyEmittedScript(repo, NO_COMMANDS, modeContradictionSkipNotice("adr"))
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
   })
 })
 
@@ -284,7 +284,7 @@ describe("applyEmittedScript — ModeContradiction.ts's contradiction round-trip
 
     const result = applyEmittedScript(repo, commands, block)
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(repo.readFile(samplePath)).toBeUndefined()
   })
 
@@ -359,7 +359,7 @@ describe("applyEmittedScript — the scripted-command table", () => {
 
     const result = applyEmittedScript(repo, commands, "./run-check.sh")
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
   })
 
   it("an 'exit' hit with a non-zero status fails the script", () => {
@@ -370,8 +370,7 @@ describe("applyEmittedScript — the scripted-command table", () => {
 
     const result = applyEmittedScript(repo, commands, "./run-check.sh")
 
-    expect(result.ok).toBe(false)
-    expect(result.error).toContain("./run-check.sh")
+    expect(result).toMatchObject({ ok: false, status: 1, output: "boom\n" })
   })
 
   it("a 'rewrite' hit mutates the repo's file", () => {
@@ -383,7 +382,7 @@ describe("applyEmittedScript — the scripted-command table", () => {
 
     const result = applyEmittedScript(repo, commands, "./format-feedback.sh")
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(repo.readFile("FEEDBACK.md")).toBe("new")
   })
 })
@@ -434,7 +433,7 @@ describe("applyEmittedScript — a tripped precondition stops the script", () =>
 
     const result = applyEmittedScript(repo, NO_COMMANDS, script)
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(repo.lastCommitMessage()).toBe("gtd(agent): lands")
   })
 })
@@ -455,7 +454,7 @@ describe("applyEmittedScript — a realistic assembled multi-block script", () =
 
     const result = applyEmittedScript(repo, NO_COMMANDS, script)
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(repo.lastCommitMessage()).toBe("gtd(agent): second")
     expect(repo.resolveRef("refs/gtd/base")).toBe(first)
   })
@@ -479,7 +478,7 @@ describe("applyEmittedScript — a realistic src/emit/Emit.ts-assembled script",
     const result = applyEmittedScript(repo, NO_COMMANDS, required)
     twin.commitAllWithPrefix("gtd(agent): building")
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(snapshot(repo)).toEqual(snapshot(twin))
   })
 
@@ -505,7 +504,7 @@ describe("applyEmittedScript — a realistic src/emit/Emit.ts-assembled script",
     const { required } = emitScripts(steps)
     const result = applyEmittedScript(repo, NO_COMMANDS, required)
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(repo.resolveRef("refs/worktree/gtd/history")).toBe(tip)
     expect(repo.lastCommitMessage()).toBe("chore: squashed")
     expect(repo.hasPath(".gtd/TODO.md")).toBe(false)
@@ -520,7 +519,7 @@ describe("applyEmittedScript — outcome blocks are inert (no git effect to miss
 
     const result = applyEmittedScript(repo, NO_COMMANDS, transitionOutcome("idle", "working"))
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(snapshot(repo)).toEqual(before)
   })
 
@@ -531,7 +530,7 @@ describe("applyEmittedScript — outcome blocks are inert (no git effect to miss
 
     const result = applyEmittedScript(repo, NO_COMMANDS, commitOutcome("gtd(agent): x"))
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(snapshot(repo)).toEqual(before)
   })
 
@@ -553,7 +552,7 @@ describe("applyEmittedScript — outcome blocks are inert (no git effect to miss
     const result = applyEmittedScript(repo, NO_COMMANDS, required)
     twin.commitAllWithPrefix("gtd(agent): building")
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(snapshot(repo)).toEqual(snapshot(twin))
   })
 
@@ -567,7 +566,7 @@ describe("applyEmittedScript — outcome blocks are inert (no git effect to miss
     ])
     const result = applyEmittedScript(repo, NO_COMMANDS, required)
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(snapshot(repo)).toEqual(before)
   })
 })
@@ -583,7 +582,7 @@ describe("applyEmittedScript — Emit.ts's combinedScript (the whole stdout of a
     const script = combinedScript(required, "")
     const result = applyEmittedScript(repo, NO_COMMANDS, script)
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(repo.lastCommitMessage()).toBe("gtd(human): idle")
   })
 
@@ -605,7 +604,7 @@ describe("applyEmittedScript — Emit.ts's combinedScript (the whole stdout of a
 
     const result = applyEmittedScript(repo, NO_COMMANDS, script)
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(repo.lastCommitMessage()).toBe("gtd(human): idle")
     expect(repo.resolveRef("refs/gtd/marker")).toBe(repo.resolveRef("HEAD"))
   })
@@ -625,7 +624,7 @@ describe("applyEmittedScript — Emit.ts's combinedScript (the whole stdout of a
 
     const result = applyEmittedScript(repo, NO_COMMANDS, script)
 
-    expect(result).toEqual({ ok: true })
+    expect(result).toMatchObject({ ok: true })
     expect(repo.lastCommitMessage()).toBe("gtd(human): idle")
   })