@pmelab/gtd 51.0.0 → 52.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "51.0.0",
+  "version": "52.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/src/edge/Edge.ts

@@ -37,6 +37,7 @@ import {
   isRecordableApproval,
   parseCommitMessage,
   replay,
+  scopeRunStart,
   sliceRanges,
   treeFromRecord,
   type EpisodeCommit,
@@ -791,36 +792,6 @@ const stepDefOf = (step: ReachedStep): StepDef => {
   }
 }
 
-/** Is `name` inside `scope`'s subtree? The root scope `""` holds everything. */
-const inScope = (name: string, scope: string): boolean =>
-  scope === "" || name === scope || name.startsWith(`${scope}.`)
-
-/**
- * Where the current unbroken run of rests inside `scope`'s subtree began —
- * a dip into a descendant scope does not break it, a sibling or ancestor
- * does, and so does a fresh `scope()` call of the same scope.
- */
-const scopeRunStart = (trace: readonly ReachedStep[], scope: string): number => {
-  let start = -1
-  for (let k = 0; k < trace.length; k++) {
-    if (!inScope(trace[k]!.memoryScope, scope)) continue
-    const previous = trace[k - 1]
-    const unbroken =
-      previous !== undefined &&
-      inScope(previous.memoryScope, scope) &&
-      scopeCallOf(previous, scope) === scopeCallOf(trace[k]!, scope)
-    if (!unbroken) start = k
-  }
-  return start
-}
-
-/** The innermost `scope()` call enclosing `scope` at `step` — a new call is a new conversation. */
-const scopeCallOf = (step: ReachedStep, scope: string): number | undefined => {
-  let call: number | undefined
-  for (const entry of step.scopeCalls) if (inScope(scope, entry.prefix)) call = entry.call
-  return call
-}
-
 // Shown for the root scope, which has no name of its own.
 const ROOT_MEMORY_SCOPE_NAME = "root"
 

package/src/replay/Replay.test.ts

@@ -940,7 +940,7 @@ describe("replay: skills resolution", () => {
     expect(await wireSkills(inScope({ name: "a" }, step), { skills: { a: [] } })).toBeUndefined()
   })
 
-  it("fails two agent steps in one memory scope with different lists", async () => {
+  it("runs two scope() calls of one memory scope with different lists as two conversations", async () => {
     const flow: Flow = async () => {
       await scope({ name: "a", skills: ["one"] }, async () => {
         await agent("first", "prompt")
@@ -959,9 +959,7 @@ describe("replay: skills resolution", () => {
       start: hashOf(0),
       budgetBytes: 1024,
     })
-    expect(outcome.kind === "failed" && outcome.message).toContain(
-      "different model, system prompt, skills or file access",
-    )
+    expect(outcome.kind).toBe("rest")
   })
 })
 
@@ -1084,7 +1082,7 @@ describe("replay: access resolution", () => {
     expect(outcome.rest.access).toEqual({ read: null, write: ["src/a.ts"] })
   })
 
-  it("fails two agent steps in one memory scope with different scope access", async () => {
+  it("runs two scope() calls of one memory scope with different access as two conversations", async () => {
     const flow: Flow = async () => {
       await scope({ name: "a", access: { write: ["one"] } }, () => agent("first", "prompt"))
       await scope({ name: "a", access: { write: ["two"] } }, () => agent("second", "prompt"))
@@ -1092,9 +1090,7 @@ describe("replay: access resolution", () => {
     const history = new History()
     history.land("agent", "a.first", 1, "a.second", { "x.txt": "x" })
     const outcome = await restOf(flow, {}, history)
-    expect(outcome.kind === "failed" && outcome.message).toContain(
-      "different model, system prompt, skills or file access",
-    )
+    expect(outcome.kind).toBe("rest")
   })
 
   it("does not conflict two steps that differ only in steering file", async () => {

package/src/replay/Replay.ts

@@ -139,6 +139,36 @@ const memoryScopeOf = (name: string): string => {
   return dot === -1 ? "" : name.slice(0, dot)
 }
 
+/** Is `name` inside `scope`'s subtree? The root scope `""` holds everything. */
+const inScope = (name: string, scope: string): boolean =>
+  scope === "" || name === scope || name.startsWith(`${scope}.`)
+
+/**
+ * Where the current unbroken run of rests inside `scope`'s subtree began —
+ * a dip into a descendant scope does not break it, a sibling or ancestor
+ * does, and so does a fresh `scope()` call of the same scope.
+ */
+export const scopeRunStart = (trace: readonly ReachedStep[], scope: string): number => {
+  let start = -1
+  for (let k = 0; k < trace.length; k++) {
+    if (!inScope(trace[k]!.memoryScope, scope)) continue
+    const previous = trace[k - 1]
+    const unbroken =
+      previous !== undefined &&
+      inScope(previous.memoryScope, scope) &&
+      scopeCallOf(previous, scope) === scopeCallOf(trace[k]!, scope)
+    if (!unbroken) start = k
+  }
+  return start
+}
+
+/** The innermost `scope()` call enclosing `scope` at `step` — a new call is a new conversation. */
+const scopeCallOf = (step: ReachedStep, scope: string): number | undefined => {
+  let call: number | undefined
+  for (const entry of step.scopeCalls) if (inScope(scope, entry.prefix)) call = entry.call
+  return call
+}
+
 class Stop extends Error {}
 
 const short = (hash: string): string => hash.slice(0, 7)
@@ -505,14 +535,16 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
       skills: step.skills,
       access: unfoldedAccess.get(step),
     }
-    const seen = personas.get(step.memoryScope)
+    // Keyed like the memory key: a fresh scope() call is a fresh conversation, free to differ.
+    const conversation = `${step.memoryScope}#${scopeRunStart(trace, step.memoryScope)}`
+    const seen = personas.get(conversation)
     if (seen === undefined) {
-      personas.set(step.memoryScope, identity)
+      personas.set(conversation, identity)
       return undefined
     }
     return samePersona(seen, identity)
       ? undefined
-      : `gtd: "${step.name}" runs with a different model, system prompt, skills or file access than an earlier agent step in memory scope "${step.memoryScope || "root"}" — one scope is one conversation, and a conversation has one identity`
+      : `gtd: "${step.name}" runs with a different model, system prompt, skills or file access than an earlier agent step in its conversation in memory scope "${step.memoryScope || "root"}" — a conversation has one identity`
   }
 
   const DIVERGED = "the workflow changed under this process; run `gtd abandon` to start over"

package/src/replay/index.ts

@@ -1,4 +1,10 @@
-export { replay, type EpisodeCommit, type ReachedStep, type ReplayOutcome } from "./Replay.js"
+export {
+  replay,
+  scopeRunStart,
+  type EpisodeCommit,
+  type ReachedStep,
+  type ReplayOutcome,
+} from "./Replay.js"
 export { treeFromRecord, type TreeView } from "./Tree.js"
 export {
   formatCommitMessage,

package/src/steering/FORMATS.md

@@ -14,7 +14,10 @@ read them.
   `<!-- base: <sha> -->` comment, then `##` chunks with prose and `- [ ]` hunk
   pointers (`./path`, `./path#start-end`), each optionally followed by
   `— <note>`. A pointer note starting `Risk:` is a reviewer's risk. A ticked
-  pointer is a hunk the human has read.
+  pointer is a hunk the human has read. A chunk's `Tick exactly one:` list is
+  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.
 - **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

package/src/steering/SteeringFormat.ts

@@ -64,6 +64,8 @@ export interface SteeringLink {
  * format-agnostic: `review`'s chunk/hunk and `qa`'s question/option are the
  * same two things here (a container and one of its numbered children), plus
  * `paragraph`, which a client resolves from its cursor rather than the view.
+ * A `review` finding's answer boxes are `option`s too, `questionIndex` being
+ * the chunk's index.
  */
 export type SteeringAnchor =
   | { readonly kind: "chunk"; readonly index: number }
@@ -110,7 +112,7 @@ export interface SteeringViewNode {
   readonly detail?: string
   /** A free-form status label, when the format has one (`qa`'s `"open"`/`"answered"`). */
   readonly status?: string
-  /** `true` when this node's own condition is fully satisfied (`qa`'s answered-question flag) — distinct from `checked`, which is a per-item tick. */
+  /** `true` when this node's own condition is fully satisfied (`qa`'s answered question, `review`'s decided finding) — distinct from `checked`, which is a per-item tick. */
   readonly answered?: boolean
   /** This node's own checkbox state, when it has one (a hunk's tick, an option's tick). */
   readonly checked?: boolean
@@ -138,6 +140,10 @@ export interface SteeringViewNode {
   readonly endLine?: number
   /** Where `annotate` attaches a NEW note to this node. */
   readonly anchor: SteeringAnchor
+  /** The section a top-level node sits in, when the format groups them (`review`'s `Findings` / `Walkthrough`). */
+  readonly group?: string
+  /** A `review` finding's answer boxes, in order — fix as suggested, won't fix, and the free-text slot, whose `title` is the human's text (`""` while unfilled). Kept out of `children`, which are its hunks. */
+  readonly decision?: readonly SteeringViewNode[]
   readonly children?: readonly SteeringViewNode[]
   /**
    * A node's body, a SIBLING of `children` and never a reuse of it: a `qa`

package/src/steering/contract.test.ts

@@ -97,7 +97,8 @@ describe.each(FORMATS)("the %s format", (dir, format, ticks) => {
 
     if (ticks)
       it("round-trips every tick: writing back what was read leaves the bytes unchanged", () => {
-        for (const node of nodesOf(format.view(content).nodes)) {
+        const nodes = nodesOf(format.view(content).nodes)
+        for (const node of [...nodes, ...nodes.flatMap((n) => n.decision ?? [])]) {
           if (node.checked === undefined || node.anchor.kind === "chunk") continue
           const anchor: SteeringAnchor = node.anchor
           const same = write(

package/src/steering/fixtures/review/sectioned.md

@@ -0,0 +1,31 @@
+# Review: 1a2b3c4
+
+<!-- base: 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b -->
+
+## Findings
+
+### A lone CR is kept
+
+_should: contract_
+
+The parser keeps a lone `\r` as content.
+
+In the code:
+
+- [x] ./src/parse.ts#30-31 — where it is kept
+
+Tick exactly one:
+
+- [ ] fix as suggested
+- [x] won't fix
+- [ ] _your answer_
+
+## Walkthrough
+
+### Parser accepts CRLF
+
+- [ ] ./src/parse.ts#10-14 — normalizes `\r\n` first
+
+## Fixed automatically
+
+- a test name typo (0123456)

package/src/steering/fixtures/review/sectioned.read.json

@@ -0,0 +1,119 @@
+{
+  "header": "1a2b3c4",
+  "nodes": [
+    {
+      "title": "A lone CR is kept",
+      "detail": "The parser keeps a lone `\\r` as content. In the code:",
+      "body": [
+        {
+          "title": "The parser keeps a lone `\\r` as content.",
+          "anchor": {
+            "kind": "paragraph",
+            "line": 10
+          }
+        },
+        {
+          "title": "In the code:",
+          "anchor": {
+            "kind": "paragraph",
+            "line": 12
+          }
+        }
+      ],
+      "status": "should: contract",
+      "anchor": {
+        "kind": "chunk",
+        "index": 0
+      },
+      "group": "Findings",
+      "answered": true,
+      "decision": [
+        {
+          "title": "fix as suggested",
+          "checked": false,
+          "anchor": {
+            "kind": "option",
+            "questionIndex": 0,
+            "index": 0
+          }
+        },
+        {
+          "title": "won't fix",
+          "checked": true,
+          "anchor": {
+            "kind": "option",
+            "questionIndex": 0,
+            "index": 1
+          }
+        },
+        {
+          "title": "",
+          "checked": false,
+          "anchor": {
+            "kind": "option",
+            "questionIndex": 0,
+            "index": 2
+          }
+        }
+      ],
+      "children": [
+        {
+          "title": "./src/parse.ts#30-31",
+          "path": "./src/parse.ts",
+          "line": 30,
+          "endLine": 31,
+          "checked": true,
+          "detail": "where it is kept",
+          "anchor": {
+            "kind": "hunk",
+            "chunkIndex": 0,
+            "index": 0
+          }
+        }
+      ]
+    },
+    {
+      "title": "Parser accepts CRLF",
+      "detail": "",
+      "body": [],
+      "anchor": {
+        "kind": "chunk",
+        "index": 1
+      },
+      "group": "Walkthrough",
+      "children": [
+        {
+          "title": "./src/parse.ts#10-14",
+          "path": "./src/parse.ts",
+          "line": 10,
+          "endLine": 14,
+          "checked": false,
+          "detail": "normalizes `\\r\\n` first",
+          "anchor": {
+            "kind": "hunk",
+            "chunkIndex": 1,
+            "index": 0
+          }
+        }
+      ]
+    },
+    {
+      "title": "Fixed automatically",
+      "detail": "- a test name typo (0123456)",
+      "body": [
+        {
+          "title": "a test name typo (0123456)",
+          "anchor": {
+            "kind": "paragraph",
+            "line": 30
+          }
+        }
+      ],
+      "anchor": {
+        "kind": "chunk",
+        "index": 2
+      },
+      "children": []
+    }
+  ]
+}

package/src/steering/index.ts

@@ -16,11 +16,15 @@ export {
   reviewDecisions,
   reviewNotes,
   reviewRisks,
+  reviewSections,
+  REVIEW_SECTIONS,
+  sectionedReview,
   severityLine,
   unansweredNotes,
   type ReviewChoice,
   type ReviewDecision,
   type ReviewNote,
+  type ReviewSection,
 } from "./review.js"
 export { applySteeringEdits } from "./Edits.js"
 

package/src/steering/qa.ts

@@ -830,7 +830,7 @@ const replaceOptionTextEdit = (
  * offset for, breaking this anchor's `apply` forever. The placeholder reads
  * back as `""`, so an erase still reads as unanswered.
  */
-const normalizeFreeTextAnswer = (text: string): string => {
+export const normalizeFreeTextAnswer = (text: string): string => {
   const normalized = text.replace(/\s+/g, " ").trim()
   return normalized.length === 0 ? FREE_TEXT_PLACEHOLDER : normalized
 }