@pmelab/gtd 15.6.0 → 15.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "15.6.0",
+  "version": "15.7.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/flows/helpers.ts

@@ -1,10 +1,12 @@
 import {
   changes,
+  codeThreads,
   head,
   openQuestions,
   read,
   refuse,
   run,
+  threads,
   type Change,
   type JudgeAnswer,
 } from "./runtime.js"
@@ -82,6 +84,50 @@ export const requireAnswers = (file: string): void => {
   )
 }
 
+/** Footnote threads in `file` waiting on `waitingOn`, plus any with a syntax fault — a fault refuses both ways. */
+const threadLines = (file: string, waitingOn: "human" | "agent"): string[] =>
+  threads(read(file) ?? "")
+    .filter((t) => t.waitingOn === waitingOn || t.faults.length > 0)
+    .flatMap((t) => [
+      `  - ${file}:${t.line}: [^${t.name}]`,
+      ...t.faults.map((fault) => `    ${fault}`),
+    ])
+
+/** Code threads waiting on `waitingOn`, plus any with a syntax fault — a fault refuses both ways. */
+const codeThreadLines = (waitingOn: "human" | "agent"): string[] =>
+  codeThreads()
+    .filter((t) => t.waitingOn === waitingOn || t.faults.length > 0)
+    .flatMap((t) => [
+      `  - ${t.path}:${t.line}: ${t.first}`,
+      ...t.faults.map((fault) => `    ${fault}`),
+    ])
+
+const countOf = (lines: readonly string[]): number =>
+  lines.filter((line) => line.startsWith("  - ")).length
+
+/** Whether a thread waits on `waitingOn`: one in footnote file `file`, or any code thread in the process's changed files. */
+export const hasThreadFor = (waitingOn: "human" | "agent", file?: string): boolean =>
+  (file !== undefined && threads(read(file) ?? "").some((t) => t.waitingOn === waitingOn)) ||
+  codeThreads().some((t) => t.waitingOn === waitingOn)
+
+/** Refuse any landing while a thread in `file` or a code thread in a changed file waits on the human (its last entry is the agent's), or has a syntax fault. */
+export const requireThreadsClosed = (file: string): void => {
+  const open = [...threadLines(file, "human"), ...codeThreadLines("human")]
+  if (open.length === 0) return
+  refuse(
+    `gtd land: open-threads: ${countOf(open)} thread(s) in ${file} or code comments wait on you — reply with a conclusion, or delete the thread:\n${open.join("\n")}`,
+  )
+}
+
+/** Refuse an agent turn that leaves a thread in `file`, or a code thread in a changed file, waiting on the agent (its last entry is `H:`) or with a syntax fault. */
+export const requireReplies = (file: string): void => {
+  const open = [...threadLines(file, "agent"), ...codeThreadLines("agent")]
+  if (open.length === 0) return
+  refuse(
+    `gtd land: unanswered-threads: ${countOf(open)} thread(s) in ${file} or code comments still wait on the agent — append one "- A:" reply to each (one "A:" comment line, same token and indentation, directly below a code thread's last line), or fold a concluded thread and delete it:\n${open.join("\n")}`,
+  )
+}
+
 /** Refuse a turn that did not undo the code edits `edited` recorded, back to their content before `base`. */
 export const requireRevert = (edited: readonly Change[], base: string): void => {
   const residue = edited.filter((c) => read(c.path) !== c.before).map((c) => c.path)

package/src/flows/runtime.ts

@@ -133,6 +133,8 @@ export interface FlowContext {
   readonly sections: (text: string) => readonly string[]
   readonly sectionBodies: (text: string) => readonly Section[]
   readonly openQuestions: (text: string) => readonly OpenQuestion[]
+  readonly threads: (text: string) => readonly ThreadInfo[]
+  readonly codeThreads: () => readonly CodeThreadInfo[]
   readonly vars: Readonly<Record<string, string>>
   readonly head: () => string
   readonly start: () => string
@@ -275,6 +277,34 @@ export interface OpenQuestion {
   readonly line: number
 }
 
+export interface ThreadInfo {
+  readonly name: string
+  /** The 1-based line of the thread's `[^name]:` definition. */
+  readonly line: number
+  /** `"human"` means the last entry is the agent's: the thread is open. */
+  readonly waitingOn: "human" | "agent"
+  /** Syntax faults, each already prefixed `Footnote thread "[^name]":`. */
+  readonly faults: readonly string[]
+}
+
+/** Every `H:`/`A:` thread (a footnote) in `text`. */
+export const threads = (text: string): readonly ThreadInfo[] => ctx().threads(text)
+
+export interface CodeThreadInfo {
+  readonly path: string
+  /** The 1-based line of the thread's first comment line. */
+  readonly line: number
+  /** `"human"` means the last entry is the agent's: the thread is open. */
+  readonly waitingOn: "human" | "agent"
+  /** The text of the opening `H:` entry. */
+  readonly first: string
+  /** Syntax faults, each already prefixed `Code thread at <path>:<line>:`. */
+  readonly faults: readonly string[]
+}
+
+/** Every `H:`/`A:` thread in line comments of the files changed since the process's diff base. */
+export const codeThreads = (): readonly CodeThreadInfo[] => ctx().codeThreads()
+
 /** The qa-format questions in `text` that are still unanswered. */
 export const openQuestions = (text: string): readonly OpenQuestion[] => ctx().openQuestions(text)
 

package/src/flows/scripts.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest"
+import { restoreScript } from "./scripts.js"
+
+describe("restoreScript", () => {
+  const paths = { restore: ["a.ts"], remove: [] }
+
+  it("restores from <commit>~1 by default", () => {
+    expect(restoreScript("abc", paths)).toContain("--source='abc~1'")
+  })
+
+  it("restores from the given source commit", () => {
+    const script = restoreScript("abc", paths, "def")
+    expect(script).toContain("--source='def'")
+    expect(script).not.toContain("abc~1")
+  })
+})

package/src/flows/scripts.ts

@@ -87,6 +87,7 @@ export const revertScript = (commit: string, report: string, failure: string): s
 export const restoreScript = (
   commit: string,
   paths: { readonly restore: readonly string[]; readonly remove: readonly string[] },
+  source?: string,
 ): string => {
   const unchanged = (path: string): string => `git diff --quiet ${quote(commit)} -- ${quote(path)}`
   return [
@@ -94,7 +95,7 @@ export const restoreScript = (
     "set +e",
     ...paths.restore.map(
       (path) =>
-        `${unchanged(path)} && git restore --source=${quote(`${commit}~1`)} --worktree -- ${quote(path)}`,
+        `${unchanged(path)} && git restore --source=${quote(source ?? `${commit}~1`)} --worktree -- ${quote(path)}`,
     ),
     ...paths.remove.map((path) => `${unchanged(path)} && rm -f -- ${quote(path)}`),
     "",

package/src/workflows/planning.ts

@@ -1,13 +1,15 @@
 import {
   answered,
   changes,
+  hasThreadFor,
   judge,
   moveScript,
   numeric,
-  openQuestions,
   read,
   refuse,
   requireAnswers,
+  requireReplies,
+  requireThreadsClosed,
   requireProgress,
   run,
   scope,
@@ -26,15 +28,16 @@ import {
 import * as t from "./text.js"
 
 /**
- * Stop for a human only while `file` is missing or still has open questions.
- * Resolves `true` when the human answered (the author revises), `false` when
- * no question was left.
+ * Always stop for the human. Resolves `true` when the round changed anything
+ * (the author revises), `false` on a clean re-run. Open threads refuse every
+ * landing; unticked questions only refuse a round with no thread for the
+ * agent to answer.
  */
-const questionGate = async (file: string, answer: () => Promise<void>): Promise<boolean> => {
-  const content = read(file)
-  if (content !== undefined && openQuestions(content).length === 0) return false
+const noteGate = async (file: string, answer: () => Promise<void>): Promise<boolean> => {
   await answer()
-  requireAnswers(file)
+  requireThreadsClosed(file)
+  if (changes().length === 0) return false
+  if (!hasThreadFor("agent", file)) requireAnswers(file)
   return true
 }
 
@@ -44,14 +47,17 @@ export const design = (base: string): Promise<void> =>
     do {
       await triage(base)
       requireProgress(REQUIREMENTS)
-    } while (await questionGate(REQUIREMENTS, answerProductQuestions))
+      requireReplies(REQUIREMENTS)
+    } while (await noteGate(REQUIREMENTS, answerProductQuestions))
   })
 
 /** Work out the technical plan, then decompose it into package files. */
 export const architecture = (): Promise<void> =>
   scope("architecture", async () => {
-    do await author()
-    while (await questionGate(ARCHITECTURE, answerTechnicalQuestions))
+    do {
+      await author()
+      requireReplies(ARCHITECTURE)
+    } while (await noteGate(ARCHITECTURE, answerTechnicalQuestions))
     await decompose()
     if (changes(".gtd/packages/**").length === 0) {
       refuse("gtd land: decompose: write at least one package under .gtd/packages/")

package/src/workflows/prose.ts

@@ -42,7 +42,13 @@ export const agentConduct = `- You have shell and file tools — bash, read, wri
 - The turn's message names a commit, a range, or a file to go inspect
   yourself — never a diff or summary inlined into the conversation
 - Across turns one conversation may span, work from what you already
-  read and settled, unless told this is a fresh, cold pass`
+  read and settled, unless told this is a fresh, cold pass
+- Your turn ends when you return, and nothing you leave running survives
+  it in any useful way — never detach or background work you intend to
+  act on, never end a turn planning to "check back": no later turn
+  inherits your intent. Run it in the foreground and wait, however long
+  it takes. If it genuinely cannot finish inside one turn, write down
+  where it stands and what to resume, so the tree carries the state`
 
 export const designPersona = `You are the product-facing planning voice in gtd's build pipeline: turn
 a raw sketch — a hand-edit, a scratch note, or both — into an ordered,
@@ -211,14 +217,34 @@ export const footnoteRules = `- Leave a footnote anywhere: mark the exact spot w
 - A footnote is a comment on that exact spot — the hunk, line, or
   paragraph it marks — never a whole-file remark
 - \`name\` is yours to pick; only a definition's name must be unique in
-  this document — the same name may mark more than one spot`
+  this document — the same name may mark more than one spot
+- To start a conversation, open the definition with a list: \`[^name]:\`
+  then an indented \`- H: <your question>\`. The agent answers with
+  \`- A: <reply>\`. Reply with a new \`- H:\` entry to continue; to
+  close the thread, reply with a conclusion (the agent folds it in and
+  deletes the thread) or delete the thread yourself. Entries alternate
+  \`H:\`/\`A:\` and the agent never starts a thread
+- While a thread's last entry is the agent's, it is open and moving on
+  is refused: reply with a conclusion, or delete it
+- The same conversation works as \`// H: <question>\` comment lines in a
+  file changed in this process (\`#\`, \`--\` or \`;\` by language); the phone UI does not show them,
+  and \`gtd check --open-threads\` lists the open ones`
 
 export const footnoteFoldIn = `- A footnote (\`[^name]\` plus its \`[^name]:\` definition) is a comment on
   its exact anchor — fold it in as a mandatory concern described
   against that anchor's hunk or paragraph, never flattened into a
   whole-file remark
-- DELETE it in this same turn — marker and definition together — the
-  way a transient hand-written code comment is already treated. Never
-  re-read a footnote already acted on
-- A footnote is human input only — you reply in prose; never write one
-  yourself`
+- A one-shot footnote needs no reply: fold it in and DELETE it in this
+  same turn — marker and definition together. Never re-read a footnote
+  already acted on. A one-shot footnote that asks a question becomes a
+  thread instead: rewrite its definition as \`- H: <its body>\` then
+  \`- A: <your reply>\`, keeping the marker
+- A thread is a definition whose body is a list of \`- H:\`/\`- A:\`
+  entries. Handle each by its last entry:
+  - last is \`- H:\` and asks something — reply with exactly one
+    \`- A: <reply>\` entry and change nothing else for it
+  - last concludes or advises — fold it in like a one-shot footnote,
+    then delete marker and definition
+  - last is \`- A:\` — it waits on the human; leave it alone
+- Never start a thread yourself, and never leave a thread whose last
+  entry is \`- H:\` — a turn that does is refused`

package/src/workflows/review.ts

@@ -1,21 +1,24 @@
 import {
   answered,
   changes,
-  codeChanges,
+  changesSince,
+  hasThreadFor,
   head,
   judge,
   numeric,
   read,
   refuse,
   removeScript,
+  requireReplies,
+  requireThreadsClosed,
   run,
   scope,
   sectionBodies,
   vars,
-  wrote,
   type Change,
   type JudgeQuestion,
 } from "../flows/index.js"
+import { stripCodeThreads } from "../steering/index.js"
 import { escalation, FIX_CAP, healthy, type EscalationCount } from "./health.js"
 import {
   awaitReview,
@@ -59,9 +62,11 @@ export type ReviewOutcome =
   | { readonly verdict: "signoff" }
   | {
       readonly verdict: "feedback"
-      /** The commit the human's review edit landed as. */
+      /** The last round's commit, the re-plan base. */
       readonly base: string
-      /** The code paths that edit changed, with their content before it. */
+      /** The commit `.gtd/REVIEW.md` was written at; edits are restored from it. */
+      readonly restoreFrom: string
+      /** The code paths the rounds changed, with their content before. */
       readonly edited: readonly Change[]
     }
 
@@ -98,48 +103,118 @@ const actionable = async (review: string): Promise<boolean> => {
   )
 }
 
+const isCode = (path: string): boolean => path !== ".gtd" && !path.startsWith(".gtd/")
+
+/** A code edit, not a thread-only change: lines that only add, answer or remove code threads don't count. */
+const isCodeEdit = (c: Change): boolean =>
+  isCode(c.path) &&
+  stripCodeThreads(c.path, c.before ?? "") !== stripCodeThreads(c.path, c.after ?? "")
+
 const collect = async (capture: string): Promise<"signoff" | "feedback"> => {
   await collecting(capture)
-  if (wrote(REQUIREMENTS)) return "feedback"
+  if (read(REQUIREMENTS) !== undefined) return "feedback"
   if (changes().length === 0) return "signoff"
   return refuse(
     "gtd land: no declared pattern matches the pending changes — write .gtd/REQUIREMENTS.md from the feedback, or change nothing when it asks for nothing",
   )
 }
 
+/** A review with ticks, footnote markers and thread definitions removed: what is left is line notes. */
+const notesOf = (text: string): string =>
+  text
+    .replace(/^\[\^[^\]]+\]:[^\n]*(\n(?: {2,}|\t)[^\n]*|\n(?=\s*\n(?: {2,}|\t)))*/gm, "")
+    .replace(/\[\^[^\]]+\]/g, "")
+    .replace(/\[x\]/gi, "[ ]")
+    .replace(/\s+/g, " ")
+    .trim()
+
+/** Whether anything but thread edits and ticks landed in `.gtd/REVIEW.md` since `commit`. */
+const notedSince = (commit: string): boolean =>
+  changesSince(commit).some(
+    (c) => c.path === REVIEW && notesOf(c.before ?? "") !== notesOf(read(REVIEW) ?? ""),
+  )
+
 /**
- * A reviewer writes `.gtd/REVIEW.md` over everything since `base`, a human
- * reviews and signs off or comments, and a comment is classified into
- * requirements for another lap.
+ * The human gate and its reply rounds: a question gets an answer inside
+ * `.gtd/REVIEW.md` and rests at the gate again, without a lap. Resolves the
+ * commit of the last `review.collecting` turn, `"missing"` when the round
+ * left no review, or `undefined` when no such turn ran.
  */
-export const review = async (base: string): Promise<ReviewOutcome> => {
+const converse = async (base: string): Promise<string | undefined> => {
+  let collectedAt: string | undefined
   for (;;) {
-    await reviewing(base)
     await awaitReview(base)
     if (changes(REVIEW).some((c) => c.status === "deleted")) {
       refuse(
         "gtd land: review-doc: .gtd/REVIEW.md was deleted — restore it, or leave a note (or edit code) to request changes.",
       )
     }
-    const edited = codeChanges()
-    const round = head()
-    const record = read(REVIEW)
-    if (record === undefined) {
-      await reviewMissing(round)
-      continue
+    if (read(REVIEW) === undefined) {
+      await reviewMissing(head())
+      return "missing"
     }
-    // The review gate clears every tick before its commit, so a changed
-    // REVIEW.md is a note, never a tick.
-    const noted = changes(REVIEW).length > 0
-    const outcome = (verdict: "signoff" | "feedback"): ReviewOutcome =>
-      verdict === "signoff" ? { verdict } : { verdict, base: round, edited }
-    await run("review.closing", removeScript([REVIEW]), {
-      label: "Closing the review",
-      base: round,
-    })
-    if (edited.length > 0) return outcome(await collect(t.reviewEditsCapture(round)))
-    if (!noted || !(await actionable(record))) return { verdict: "signoff" }
-    return outcome(await collect(t.reviewNotesCapture(round)))
+    requireThreadsClosed(REVIEW)
+    if (!hasThreadFor("agent", REVIEW)) return collectedAt
+    await collecting(t.reviewEditsCapture(head()))
+    collectedAt = head()
+    requireReplies(REVIEW)
+    if (!hasThreadFor("human", REVIEW)) return collectedAt
+  }
+}
+
+/**
+ * What the in-loop `review.collecting` turn left: `folded` when it wrote
+ * REQUIREMENTS.md (those folds need their lap whatever is judged later),
+ * `settled` when only thread edits and ticks landed after it.
+ */
+const afterCollect = (collectedAt: string | undefined): { folded: boolean; settled: boolean } =>
+  // While the collecting turn is still pending its commit has no hash, so no
+  // range can start there; the flow rests at `review.closing` before it matters.
+  collectedAt === "" ? { folded: false, settled: false } : settledAfter(collectedAt)
+
+const settledAfter = (collectedAt: string | undefined): { folded: boolean; settled: boolean } => ({
+  folded: collectedAt !== undefined && read(REQUIREMENTS) !== undefined,
+  settled:
+    collectedAt !== undefined &&
+    changesSince(collectedAt).every((c) => !isCodeEdit(c)) &&
+    !notedSince(collectedAt),
+})
+
+const finish = async (
+  reviewed: string,
+  collectedAt: string | undefined,
+): Promise<ReviewOutcome> => {
+  const round = head()
+  const since = changesSince(reviewed)
+  const edited = since.filter(isCodeEdit)
+  const record = read(REVIEW) ?? ""
+  const { folded, settled } = afterCollect(collectedAt)
+  // The review gate clears every tick before its commit, so a changed
+  // REVIEW.md is a note, never a tick.
+  const noted = since.some((c) => c.path === REVIEW)
+  const outcome = (verdict: "signoff" | "feedback"): ReviewOutcome =>
+    verdict === "signoff" ? { verdict } : { verdict, base: round, restoreFrom: reviewed, edited }
+  await run("review.closing", removeScript([REVIEW]), {
+    label: "Closing the review",
+    base: round,
+  })
+  if (settled) return outcome(folded ? "feedback" : "signoff")
+  if (edited.length > 0) return outcome(await collect(t.reviewEditsCapture(round)))
+  if (!noted || !(await actionable(record))) return outcome(folded ? "feedback" : "signoff")
+  return outcome(await collect(t.reviewNotesCapture(round)))
+}
+
+/**
+ * A reviewer writes `.gtd/REVIEW.md` over everything since `base`, a human
+ * reviews and signs off or comments, and a comment is classified into
+ * requirements for another lap.
+ */
+export const review = async (base: string): Promise<ReviewOutcome> => {
+  for (;;) {
+    await reviewing(base)
+    const reviewed = head()
+    const collectedAt = await converse(base)
+    if (collectedAt !== "missing") return finish(reviewed, collectedAt)
   }
 }
 

package/src/workflows/text.fixture.ts

@@ -1,10 +1,11 @@
-import { installContext, type StepRequest } from "../flows/index.js"
+import { installContext, type CodeThreadInfo, type StepRequest } from "../flows/index.js"
 import { defaults } from "./vars.js"
 
 export interface TextContext {
   readonly vars?: Readonly<Record<string, string>>
   readonly head?: string
   readonly start?: string
+  readonly codeThreads?: readonly CodeThreadInfo[]
   readonly read?: (path: string) => string | undefined
 }
 
@@ -27,6 +28,8 @@ export const renderText = <T>(text: () => T, context: TextContext = {}): T => {
     sections: () => [],
     sectionBodies: () => [],
     openQuestions: () => [],
+    threads: () => [],
+    codeThreads: () => context.codeThreads ?? [],
     vars: { ...defaults, ...context.vars },
     head: () => context.head ?? "",
     start: () => context.start ?? "",
@@ -60,6 +63,8 @@ export const captureStep = async (
     sections: () => [],
     sectionBodies: () => [],
     openQuestions: () => [],
+    threads: () => [],
+    codeThreads: () => context.codeThreads ?? [],
     vars: { ...defaults, ...context.vars },
     head: () => context.head ?? "",
     start: () => context.start ?? "",

package/src/workflows/text.test.ts

@@ -2,7 +2,11 @@ import { describe, expect, it } from "vitest"
 import {
   agentWithSkills,
   architectureAuthorPrompt,
+  architectureGateAnswerMessage,
   buildFixQualityPrompt,
+  buildReviewAwaitReviewMessage,
+  buildReviewCollectingPrompt,
+  designGateAnswerMessage,
   designTriagePrompt,
   splitSkills,
   summaryPrompt,
@@ -136,3 +140,67 @@ describe("summaryPrompt", () => {
     expect(prompt).toContain("Token cost: 12\n- smart: 5\n- base: 7\n\nPrint the closing message")
   })
 })
+
+describe("the thread rules", () => {
+  it("are in all three answering prompts and no longer say a footnote is human input only", () => {
+    const prompts = renderText(() => [
+      designTriagePrompt("base"),
+      architectureAuthorPrompt(),
+      buildReviewCollectingPrompt("capture"),
+    ])
+    for (const prompt of prompts) {
+      expect(prompt).toContain("- A: <reply>")
+      expect(prompt).toContain("Never start a thread yourself")
+      expect(prompt).not.toContain("human input only")
+    }
+  })
+
+  it("make the review collector write requirements, reply in the review and run the review check", () => {
+    const prompt = renderText(() => buildReviewCollectingPrompt("capture"))
+    expect(prompt).toContain("gtd check review .gtd/REVIEW.md")
+  })
+})
+
+describe("code threads in prompts", () => {
+  const waiting = [
+    { path: "src/a.ts", line: 4, waitingOn: "agent", first: "why?", faults: [] },
+    { path: "src/b.ts", line: 9, waitingOn: "human", first: "done", faults: [] },
+  ] as const
+
+  it("lists the code threads waiting on the agent in the three gates", () => {
+    const prompts = renderText(
+      () => [
+        designTriagePrompt("base"),
+        architectureAuthorPrompt(),
+        buildReviewCollectingPrompt("capture"),
+      ],
+      { codeThreads: waiting },
+    )
+    for (const prompt of prompts) {
+      expect(prompt).toContain("src/a.ts:4: why?")
+      expect(prompt).not.toContain("src/b.ts:9")
+    }
+  })
+
+  it("says nothing when none wait", () => {
+    const prompt = renderText(() => designTriagePrompt("base"))
+    expect(prompt).not.toContain("Code threads waiting on you")
+  })
+
+  it("separates a thread from a one-shot code comment at the review collector", () => {
+    const prompt = renderText(() => buildReviewCollectingPrompt("capture"))
+    expect(prompt).toContain("exactly one `A:` comment line")
+    expect(prompt).toContain("one-shot")
+  })
+
+  it("teaches the syntax once in the footnote rules", () => {
+    for (const message of renderText(() => [
+      designGateAnswerMessage(),
+      architectureGateAnswerMessage(),
+      buildReviewAwaitReviewMessage("base"),
+    ])) {
+      expect(message).toContain("gtd check --open-threads")
+      expect(message).toContain("phone UI does not show them")
+    }
+  })
+})