pi-anchorloop 2.2.0 → 2.2.1

package/README.md

@@ -25,7 +25,7 @@ shared           grilling · domain-modeling · human-feedback · agent-terse
 
 | File | What it does |
 | --- | --- |
-| `pi/book.ts` | The loop book. The first `todo` create opens a loop, so it needs the `todo` tool of [`@juicesharp/rpiv-todo`](https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-todo#readme) (its `tool_result` details `{tasks, nextId}` and `rpiv-todo-state` entries); without it no loop opens. The agent declares only what the extension cannot observe with `anchorloop_stage`: `kind` (`quick`, `inline`, `reviewed`, `durable`, with an intent and the anchor command), `verify` (a check not run in bash), `fresh-read`, `friction` (`tried`, `found`, `led_by`), `reflect`, `skip`, `back`, `close`, and the query `read`. Everything else is read from evidence: production edits, the exit code of the bash call that ran the anchor command (failed-then-passed runs become retry pairs), reviewer `Blocking: P0=<n> P1=<m>` counts, summaries of `docs/specs/*/` artifacts as they are edited, and a returned subagent that Jev judges to have been a fresh-context read of the spec. A phase machine over that evidence gives each kind a fixed sequence (`quick` act → check; `inline` anchor → act → verify; `reviewed` adds review; `durable` adds decide → grill → spec → read → approve → design; every kind ends with reflect → close), and `read` shows `<kind> · phase <current> ✓ → <next> (missing: …) · skipped: …`. A phase that starts before an earlier one is complete warns once in one line and names the `skip` escape; phases regress when evidence changes or on `back`. The book also records each todo with its `anchor`, `ref` (`<path>#<heading>`, resolved to line ranges), and `followup` metadata. One YAML book per open loop lives under `~/.pi/agent/anchorloop/books/` (`ANCHORLOOP_BOOKS_DIR` overrides it), subagent books under `agents/` (a child that closes keeps its book for the main session); `session_start` sweeps books whose session is gone or that have not changed in 7 days. `close` never refuses over phases or friction, only while a pending or in-progress todo lacks `metadata.followup` (a ticket id, `memory`, or `drop — <reason>`). |
+| `pi/book.ts` | The loop book. The first `todo` create or `kind` call opens a loop; task records need the `todo` tool of [`@juicesharp/rpiv-todo`](https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-todo#readme) (its `tool_result` details `{tasks, nextId}` and `rpiv-todo-state` entries). The agent declares only what the extension cannot observe with `anchorloop_stage`: `kind` (`quick`, `inline`, `reviewed`, `durable`, with an intent and the anchor command), `verify` (a check not run in bash), `fresh-read`, `friction` (`tried`, `found`, `led_by`), `reflect`, `skip`, `back`, `close`, and the query `read`. Everything else is read from evidence: production edits (a write or edit in any git repo, outside its `scratch/` and `docs/specs/`; a linked child's edits and a successful `git merge`, `cherry-pick`, or `pull` count too), the exit code of the bash call that ran the anchor command (failed-then-passed runs become retry pairs), reviewer `Blocking: P0=<n> P1=<m>` counts, summaries of `docs/specs/*/` artifacts as they are edited, and a returned subagent that Jev judges to have been a fresh-context read of the spec. A phase machine over that evidence gives each kind a fixed sequence (`quick` act → check; `inline` anchor → act → verify; `reviewed` adds review; `durable` adds decide → grill → spec → read → approve → design; every kind ends with reflect → close), and `read` shows `<kind> · phase <current> ✓ → <next> (missing: …) · skipped: …`. A phase that starts before an earlier one is complete warns once in one line and names the `skip` escape; phases regress when evidence changes or on `back`. The book also records each todo with its `anchor`, `ref` (`<path>#<heading>`, resolved to line ranges), and `followup` metadata. One YAML book per open loop lives under `~/.pi/agent/anchorloop/books/` (`ANCHORLOOP_BOOKS_DIR` overrides it; empty project and `agents/` directories are removed), subagent books under `agents/` (a child that closes keeps its book for the main session); `session_start` sweeps books whose session is gone or that have not changed in 7 days. `close` lists every phase as done, skipped, or auto-skipped and never refuses over phases or friction, only while a pending or in-progress todo lacks `metadata.followup` (a ticket id, `memory`, or `drop — <reason>`). |
 | `pi/anchor-gate.ts` | Inside an open loop, shows one warning line when `write` or `edit` starts the `act` phase while an earlier phase of the loop kind is incomplete: no anchor (`anchor` on the `kind` call, a `Reality anchor:` line, or a skip), and in a `durable` loop a missing decision, spec, fresh read, approval, or design, read from the `docs/specs/<folder>/` files (found from the book, the intent, or a todo `ref`). It warns again only when a new phase goes missing; the call still goes through. Outside a loop and in `quick` loops it stays silent. `.md`, `.txt`, and `.html` files, `scratch/`, `docs/specs/`, and temp files outside the project pass silently. Edits made through `bash` are not checked. |
 | `pi/decision-tool.ts` | The `anchorloop_decision` tool appends single-line, spreadsheet-safe rows to a decision trail TSV, or a `start` row when a run picks up another run's trail. |
 | `pi/second-thought.ts` | Inside an open loop, asks Jev (TypeSafe's typed-decision model, through pi's classifier registry) to check the phase machine when a run settles and the loop book gained an entry since the last judgment, and at a `close` declaration. The program computes the next phase from the book; Jev sees the kind, intent, anchor, diff summary (≤1200 chars), `phase` (current, next, missing), verify state, open todos, the task list, and friction (a child's under its name), and judges only whether the current phase's completion truly holds (`complete`) and whether to `advance`, go `back`, or `ask-user`, plus `done`, the review tier still needed, and quality. The one-line advisory leads with `next → <phase>`; a retry pair with no friction entry adds a `friction` hint. The run continues once, only when Jev agrees to advance and the next phase is a verify, review, or fix; an advisory identical to the last one is not repeated, and a `full` rating after a clean review that follows the last change shows a note instead of a recheck. A run that called `MonitorCreate`, `LoopCreate`, `goal_wait`, or a `subagent` tool is waiting and is not judged. Without a TypeSafe key it does nothing, and outside a loop it never runs. In a subagent session (`PI_SUBAGENT_ID` from pi-herdr-agents, or `PI_SUBAGENT_CHILD` from pi-subagents) it registers nothing, since the agent that spawned it judges the result. |

package/README.zh-TW.md

@@ -25,7 +25,7 @@ anchorloop            核心循環 · 原則 · playbook：autonomous-run、paus
 
 | 檔案 | 作用 |
 | --- | --- |
-| `pi/book.ts` | Loop book。第一次 `todo` create 會開啟一個 loop，所以需要 [`@juicesharp/rpiv-todo`](https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-todo#readme) 的 `todo` 工具（它的 `tool_result` details `{tasks, nextId}` 和 `rpiv-todo-state` 條目）；沒有它就不會開啟 loop。agent 只用 `anchorloop_stage` 宣告 extension 看不到的事：`kind`（`quick`、`inline`、`reviewed`、`durable`，附 intent 和 anchor 指令）、`verify`（不是指令的檢查）、`fresh-read`、`friction`（`tried`、`found`、`led_by`）、`reflect`、`skip`、`back`、`close`，以及查詢用的 `read`。其餘都從證據讀出：production 的修改、執行過 anchor 指令的那次 bash 的 exit code（失敗後又通過的執行會成為 retry pair）、reviewer 的 `Blocking: P0=<n> P1=<m>` 數字、`docs/specs/*/` 產出物每次編輯後的摘要，以及 Jev 判定為「全新 context 讀過 spec」的 subagent 回報。階段機依這些證據給每種 loop 固定的階段順序（`quick` 為 act → check；`inline` 為 anchor → act → verify；`reviewed` 加 review；`durable` 再加 decide → grill → spec → read → approve → design；每一種都以 reflect → close 結尾），`read` 顯示 `<種類> · phase <目前> ✓ → <下一個>（缺：…）· 已跳過：…`。前一個階段還沒完成就開始下一個階段，會用一行警告一次並指出 `skip` 的出口；證據改變或用 `back` 時階段會退回。book 也記錄每個 todo 的 `anchor`、`ref`（`<path>#<heading>`，解析成行號範圍）和 `followup` metadata。每個開啟中的 loop 有一份 YAML book，放在 `~/.pi/agent/anchorloop/books/`（可用 `ANCHORLOOP_BOOKS_DIR` 覆寫），subagent 的 book 放在 `agents/`（subagent 自己 close 時 book 留給主 session）；`session_start` 會清掉 session 已不存在或 7 天沒有更新的 book。`close` 不會因為階段或 friction 而拒絕，只在還有 pending 或 in-progress 的 todo 沒有 `metadata.followup`（票號、`memory` 或 `drop — <原因>`）時拒絕。 |
+| `pi/book.ts` | Loop book。第一次 `todo` create 或 `kind` 呼叫會開啟一個 loop；任務紀錄需要 [`@juicesharp/rpiv-todo`](https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-todo#readme) 的 `todo` 工具（它的 `tool_result` details `{tasks, nextId}` 和 `rpiv-todo-state` 條目）。agent 只用 `anchorloop_stage` 宣告 extension 看不到的事：`kind`（`quick`、`inline`、`reviewed`、`durable`，附 intent 和 anchor 指令）、`verify`（不是指令的檢查）、`fresh-read`、`friction`（`tried`、`found`、`led_by`）、`reflect`、`skip`、`back`、`close`，以及查詢用的 `read`。其餘都從證據讀出：production 的修改（任何 git repo 內、`scratch/` 與 `docs/specs/` 以外的 write 或 edit；已連結 child 的修改，以及成功的 `git merge`、`cherry-pick`、`pull` 也算）、執行過 anchor 指令的那次 bash 的 exit code（失敗後又通過的執行會成為 retry pair）、reviewer 的 `Blocking: P0=<n> P1=<m>` 數字、`docs/specs/*/` 產出物每次編輯後的摘要，以及 Jev 判定為「全新 context 讀過 spec」的 subagent 回報。階段機依這些證據給每種 loop 固定的階段順序（`quick` 為 act → check；`inline` 為 anchor → act → verify；`reviewed` 加 review；`durable` 再加 decide → grill → spec → read → approve → design；每一種都以 reflect → close 結尾），`read` 顯示 `<種類> · phase <目前> ✓ → <下一個>（缺：…）· 已跳過：…`。前一個階段還沒完成就開始下一個階段，會用一行警告一次並指出 `skip` 的出口；證據改變或用 `back` 時階段會退回。book 也記錄每個 todo 的 `anchor`、`ref`（`<path>#<heading>`，解析成行號範圍）和 `followup` metadata。每個開啟中的 loop 有一份 YAML book，放在 `~/.pi/agent/anchorloop/books/`（可用 `ANCHORLOOP_BOOKS_DIR` 覆寫），subagent 的 book 放在 `agents/`（subagent 自己 close 時 book 留給主 session）；`session_start` 會清掉 session 已不存在或 7 天沒有更新的 book。`close` 不會因為階段或 friction 而拒絕，只在還有 pending 或 in-progress 的 todo 沒有 `metadata.followup`（票號、`memory` 或 `drop — <原因>`）時拒絕。 |
 | `pi/anchor-gate.ts` | 只在開啟的 loop 內：`write` 或 `edit` 開始 `act` 階段、而這種 loop 前面的階段還沒完成時，顯示一行警告：沒有 anchor（kind 呼叫的 `anchor`、`Reality anchor:` 這一行，或已跳過），`durable` loop 則還缺決策、spec、全新 context 的閱讀、核准或設計（從 `docs/specs/<資料夾>/` 的檔案判斷，資料夾由 book、intent 或 todo 的 `ref` 找出）。只有新缺了一個階段時才會再警告；呼叫仍會放行。沒有 loop 或是 `quick` loop 時保持安靜。`.md`、`.txt`、`.html` 檔、`scratch/`、`docs/specs/` 和專案外的暫存檔不會觸發。透過 `bash` 做的修改不檢查。 |
 | `pi/decision-tool.ts` | `anchorloop_decision` 工具把一筆決策寫進 TSV 決策軌跡，每筆只佔一行，用試算表開啟也安全；接手別人的軌跡時寫一筆 `start`。 |
 | `pi/second-thought.ts` | 只在開啟的 loop 內：一次執行結束且 book 自上次判斷後多了條目時，以及宣告 `close` 時，透過 pi 的 classifier registry 請 Jev（TypeSafe 的型別化決策模型）複核階段機。下一個階段由程式從 book 算出；Jev 看到種類、intent、anchor、diff 摘要（≤1200 字元）、`phase`（目前、下一個、缺什麼）、verify 狀態、未完成 todo、任務清單和 friction（子 agent 的以它的名字列出），只判斷目前階段的完成條件是否真的達到（`complete`），以及要 `advance`、退回（`back`）還是 `ask-user`，另外還問 `done`、還需要哪一級 review 與品質。一行提醒以 `next → <階段>` 開頭；有 retry pair 卻沒有 friction 條目時，附上 `friction` 提示。只有 Jev 同意前進、而下一個階段是 verify、review 或 fix 時，才讓 agent 多跑一輪；與上一則相同的提醒不重複，最後一次修改之後已有無 blocking 發現的 review 時，`full` 評等只顯示備註、不要求複查。呼叫過 `MonitorCreate`、`LoopCreate`、`goal_wait` 或 `subagent` 工具的執行在等待中，不被判斷。沒有 TypeSafe key 時什麼都不做，沒有 loop 時不會執行。subagent session（pi-herdr-agents 的 `PI_SUBAGENT_ID`，或 pi-subagents 的 `PI_SUBAGENT_CHILD`）不註冊任何東西，因為由派它的 agent 判斷結果。 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-anchorloop",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "Agent workflow skills for pi: one entry skill per task type, each with playbooks, over a shared Align → Anchor → Act → Verify loop, plus loop extensions (loop book, anchor gate, decision trail tool, Jev second thought, skill validator, stream rules).",
   "author": "Wei Hung",
   "license": "MIT",

package/pi/book.ts

@@ -1,5 +1,5 @@
 /**
- * pi extension: the loop book. The first `todo` create opens a loop and its book. The agent declares only
+ * pi extension: the loop book. The first `todo` create or `kind` declaration opens a loop and its book. The agent declares only
  * what the program cannot observe (`kind` with its intent and anchor command, a non-command `verify`,
  * `fresh-read`, `friction`, `reflect`, `skip`, `back`, `close`); the extension derives the rest from
  * evidence: production edits, the exit code of the anchor command, reviewer results, durable artifacts,
@@ -48,7 +48,8 @@ import {
 	verifyAfterLastAct,
 } from "./support/book.ts";
 import { classify } from "./support/jev.ts";
-import { JumpMemory, SEQUENCES, computePhases, describe, incompleteBefore, jumpLine, outsideWork } from "./support/phases.ts";
+import { SEQUENCES, computePhases, describe, incompleteBefore, outsideWork } from "./support/phases.ts";
+import { type Snapshot, snapshot } from "./support/snapshot.ts";
 import { isSubagent } from "./support/subagent.ts";
 
 export const SESSION_ENTRY = "anchorloop-loop";
@@ -113,6 +114,30 @@ export function bashExit(event: { isError?: boolean; structuredContent?: unknown
 	return named ? Number(named[1]) : null;
 }
 
+/**
+ * The exit to record for a bash call that ran `anchor`: the call's exit code, except `unknown` when something after the anchor
+ * can replace it: `||`, `;`, a newline, or a pipe straight after the anchor unless the command starts with `set -o pipefail`.
+ * A chain `anchor && other` keeps a failed anchor's code, so it stands.
+ */
+export function anchorExit(command: string, anchor: string, exit: number | null): number | "unknown" {
+	if (exit === null) return "unknown";
+	const at = command.indexOf(anchor);
+	// `! anchor` inverts the code and `x || anchor` may never run it.
+	if (at < 0 || /(!|\|\|)\s*$/.test(command.slice(0, at))) return "unknown";
+	const rest = command.slice(at + anchor.length);
+	const pipefail = /^\s*set\s+-o\s+pipefail\b/.test(command);
+	let chained = false;
+	// `&&` keeps a failed anchor's exit; `||`, `;`, and a newline can replace it, and so can a pipe
+	// straight after the anchor unless pipefail is set.
+	for (const [separator] of rest.matchAll(/&&|\|\||\||(?<![<>&])&(?![&>])|;|\n/g)) {
+		if (separator === "&&") chained = true;
+		else if (separator === "|") {
+			if (!chained && !pipefail) return "unknown";
+		} else return "unknown";
+	}
+	return exit;
+}
+
 /** The text a `Reality anchor:` line states in an assistant message, if any. */
 function statedAnchor(message: { role?: string; content?: unknown } | undefined): string | undefined {
 	if (message?.role !== "assistant") return undefined;
@@ -124,8 +149,6 @@ const reply = (text: string) => ({ content: [{ type: "text" as const, text }], d
 
 export default function (pi: ExtensionAPI) {
 	const subagent = isSubagent();
-	const jumps = new JumpMemory();
-
 	function todosOf(ctx: ExtensionContext) {
 		return replayTodos(ctx.sessionManager.getBranch());
 	}
@@ -134,6 +157,13 @@ export default function (pi: ExtensionAPI) {
 		return computePhases(book, { cwd: ctx.cwd, todos: todosOf(ctx) });
 	}
 
+	/** The line that tells the agent Jev did not accept a returned subagent as the fresh read, while the read is still open. */
+	function freshReadLine(book: Book, phases: ReturnType<typeof phasesOf>): string[] {
+		const last = [...book.entries].reverse().find((entry) => entry.stage === "goldfish");
+		const open = phases.statuses.find((status) => status.name === "read")?.state === "missing";
+		return open && last?.source === "jev" && last.ok === false ? [`fresh read by ${String(last.child || "a subagent")} judged not fresh — declare \`fresh-read\` if it was`] : [];
+	}
+
 	function summaryLines(book: Book, ctx: ExtensionContext): string[] {
 		const phases = phasesOf(book, ctx);
 		const verify = [...book.entries].reverse().find((entry) => entry.stage === "verify" || entry.stage === "check");
@@ -147,6 +177,7 @@ export default function (pi: ExtensionAPI) {
 			...childLines(book.entries).map((line) => `child ${line}`),
 			...friction.filter((item) => item.owner !== "main").map((item) => `friction ${item.ref}: ${item.tried} → ${item.found}${item.reflected ? ` [${item.class}]` : ""}`),
 			...phases.hints,
+			...freshReadLine(book, phases),
 		];
 	}
 
@@ -185,7 +216,7 @@ export default function (pi: ExtensionAPI) {
 		}
 	}
 
-	function close(book: Book, ctx: ExtensionContext, verdict: string): string {
+	function close(book: Book, ctx: ExtensionContext, verdict: string): { text: string; snapshot?: Snapshot } {
 		const todos = replayTodos(ctx.sessionManager.getBranch());
 		const undisposed = todos.filter((task) => isOpenTask(task) && !validFollowup(task.metadata?.followup));
 		if (undisposed.length > 0) {
@@ -198,21 +229,16 @@ export default function (pi: ExtensionAPI) {
 		const kind = currentKind(book.entries);
 		const phases = phasesOf(book, ctx);
 		const missing = incompleteBefore(phases, "close");
-		const bookId = String(book.header.id);
-		const fresh = jumps.fresh(bookId, "close", missing.map((status) => status.name));
-		const warning =
-			verdict !== "landed" || !missing.length || !fresh
-				? undefined
-				: kind === "quick"
-					? `anchorloop: closing a quick loop with ${missing.map((status) => `${status.name} (${status.note})`).join("; ")} open.`
-					: jumpLine("close", missing);
+		const notice = verdict === "landed" && missing.length ? `anchorloop: closed with phases not shown complete: ${missing.map((status) => `${status.name} (${status.note})`).join("; ")}.` : undefined;
 		const diff = diffAgainstBases(book.entries);
 		const friction = allFriction(book.entries);
+		const phaseList = phases.statuses.map((status) => ({ phase: status.name, state: status.state === "skipped" && status.auto ? "auto-skipped" : status.state === "missing" ? "not shown complete" : status.state, ...(status.state === "skipped" ? { note: status.note } : {}) }));
 		const summary = {
 			intent: currentIntent(book.entries) ?? null,
 			kind: kind ?? null,
 			verdict,
 			stages: stagesDone(book.entries),
+			phases: phaseList,
 			reviewRounds: reviews(book.entries).length,
 			reviewTrend: reviewTrend(book.entries),
 			diff: diff.summary,
@@ -225,20 +251,24 @@ export default function (pi: ExtensionAPI) {
 		const tail = unreflected.length
 			? ` Unreflected friction for the Reflexive Pass: ${unreflected.map((item) => `${item.ref} (${item.found})`).join("; ")}.`
 			: "";
-		const extra = [summary.skipped.length ? `skipped ${summary.skipped.join(", ")}` : "", summary.back.length ? `back ${summary.back.join(", ")}` : ""].filter(Boolean).join("; ");
-		const text = `Loop closed (${verdict}): ${summary.stages.join(", ")}; ${summary.reviewTrend}; diff ${diff.summary}${extra ? `; ${extra}` : ""}.${tail}`;
+		const shown = phaseList.map((item) => `${item.phase} ${item.state}${item.note ? ` (${item.note})` : ""}`).join(", ");
+		const back = summary.back.length ? `; back ${summary.back.join(", ")}` : "";
+		const text = `Loop closed (${verdict}): phases ${shown}; ${summary.reviewTrend}; diff ${diff.summary.split("\n").join("; ")}${back}.${tail}`;
+		const after = notice ? `\n${notice}` : "";
 		if (kept) {
 			// A child's book stays for the main session to read and delete.
 			appendEntry(book.path, "close", { verdict, summary: text.slice(0, 500) });
-			return `${text} The book stays for the main session.${warning ? `\n${warning}` : ""}`;
+			return { text: `${text} The book stays for the main session.${after}` };
 		}
+		// Jev judges the loop as it stood at close; the book is gone by the time the result is judged.
+		const snap = kind === "quick" ? undefined : snapshot(book, ctx);
 		pi.appendEntry(SESSION_ENTRY, summary);
 		for (const id of childIds(book.entries)) {
 			const child = findChildBook(id);
 			if (child) deleteBook(child.path);
 		}
 		deleteBook(book.path);
-		return `${text} The book is deleted. Clear the todo list now (todo action: clear).${warning ? `\n${warning}` : ""}`;
+		return { text: `${text} The book is deleted. Clear the todo list now (todo action: clear).${after}`, snapshot: snap };
 	}
 
 	pi.registerTool({
@@ -275,10 +305,16 @@ export default function (pi: ExtensionAPI) {
 		},
 		async execute(_toolCallId: string, raw: unknown, _signal: unknown, _onUpdate: unknown, ctx: ExtensionContext) {
 			const params = raw as Params;
-			const book = openLoop(ctx);
-			if (!book) return reply("No loop is open, so nothing was recorded. A loop opens with the first `todo` create.");
 			const { stage } = params;
 			if (!(STAGES as readonly string[]).includes(stage)) throw new Error(`unknown stage \`${String(stage)}\`; declare one of ${STAGES.join(", ")}`);
+			let book = openLoop(ctx);
+			if (!book && stage === "kind") {
+				// A todo create in the same batch may not have landed yet; whichever comes first opens the loop.
+				if (!params.kind || !params.intent) throw new Error("the first kind declaration needs `kind` and a one-line `intent`");
+				book = createBook(ctx);
+				recordPriorAnchor(book, ctx);
+			}
+			if (!book) return reply("No loop is open, so nothing was recorded. A loop opens with the first `todo` create or `kind`.");
 			const had = currentKind(book.entries);
 			const sequence = SEQUENCES[had ?? "inline"];
 			if (stage === "read") {
@@ -288,7 +324,8 @@ export default function (pi: ExtensionAPI) {
 			}
 			if (stage === "close") {
 				if (!params.verdict) throw new Error("close needs a verdict: landed, blocked, or abandoned");
-				return reply(close(book, ctx, params.verdict));
+				const closed = close(book, ctx, params.verdict);
+				return { content: [{ type: "text" as const, text: closed.text }], details: closed.snapshot ? { snapshot: closed.snapshot } : undefined };
 			}
 			if (stage === "kind") {
 				if (!params.kind && !params.intent && !params.anchor) throw new Error("kind needs `kind`, `intent`, or `anchor`");
@@ -373,11 +410,13 @@ export default function (pi: ExtensionAPI) {
 		const anchor = anchorCommand(book.entries);
 		if (anchor && command.includes(anchor)) {
 			const recorded = childId() !== undefined || currentKind(book.entries) === "quick" ? "check" : "verify";
-			const piped = command.slice(command.indexOf(anchor) + anchor.length).includes("|");
-			book.entries.push(appendEntry(book.path, recorded, { command: anchor.slice(0, 200), exit: piped ? "unknown" : (exit ?? "unknown"), last }));
+			book.entries.push(appendEntry(book.path, recorded, { command: anchor.slice(0, 200), exit: anchorExit(command, anchor, exit), last }));
 		}
 		for (const task of latestTasks(book.entries)) {
-			if (typeof task.anchor === "string" && command.includes(task.anchor)) appendEntry(book.path, "taskrun", { id: task.id, exit: exit ?? "unknown", last });
+			if (typeof task.anchor === "string" && command.includes(task.anchor)) appendEntry(book.path, "taskrun", { id: task.id, exit: anchorExit(command, task.anchor, exit), last });
+		}
+		if (exit === 0 && /\bgit(\s+-C\s+\S+)?\s+(merge|cherry-pick|pull)(?=\s|$)(?![^|;&]*--(abort|quit)\b)/.test(command) && !/Already up to date/i.test(last ?? "") && book.entries.at(-1)?.stage !== "edit") {
+			book.entries.push(appendEntry(book.path, "edit", { via: "merge" }));
 		}
 		if (exit === 0 && /\bgit\b[^|;&]*\bcommit\b/.test(command) && !book.entries.some((entry) => entry.stage === "edit")) {
 			const cwd = String(book.header.cwd ?? "");
@@ -459,7 +498,22 @@ export default function (pi: ExtensionAPI) {
 		if (reviewsStalled(book.entries)) ctx.ui.notify("anchorloop: two consecutive review rounds still raised blocking findings; stop and hand the trend to the user.", "warning");
 	}
 
-	/** Jev judges whether a returned subagent was a fresh-context read of the spec; the spec path in its brief is only a pre-filter. */
+	const HOST_LINE = /^\s*(Parent action:|Requested model|Session:|Resume:)/i;
+
+/** The text without the lines pi-herdr adds around a subagent brief or result. */
+function strip(text: string): string {
+	return text
+		.split("\n")
+		.filter((line) => !HOST_LINE.test(line))
+		.join("\n")
+		.trim();
+}
+
+function headAndTail(text: string): string {
+	return text.length <= 2500 ? text : `${text.slice(0, 1000)}\n…\n${text.slice(-1500)}`;
+}
+
+/** Jev judges whether a returned subagent was a fresh-context read of the spec; the spec path in its brief is only a pre-filter. */
 	async function detectFreshRead(ctx: ExtensionContext, book: Book, details: { name?: unknown; task?: unknown; resultContent?: unknown }): Promise<void> {
 		const phases = phasesOf(book, ctx);
 		const read = phases.statuses.find((status) => status.name === "read");
@@ -467,11 +521,11 @@ export default function (pi: ExtensionAPI) {
 		const folder = specFolder(book.entries, todosOf(ctx), ctx.cwd);
 		const brief = String(details.task ?? "");
 		if (!folder || !(brief.includes(`${folder}/spec.md`) || brief.includes(resolve(ctx.cwd, folder, "spec.md")))) return;
-		const { answers } = await classify(ctx, { brief: brief.slice(0, 1500), result: textOf(details.resultContent).slice(-2000) }, {
+		const { answers } = await classify(ctx, { brief: strip(brief).slice(0, 1500), result: headAndTail(strip(textOf(details.resultContent))) }, {
 			fresh_read: {
 				type: "bool",
-				instructions: "Was this subagent a fresh-context read of the spec: did its `brief` hand it the spec without the author's reasoning and ask it to restate the contract and list its guesses, and does its `result` do so?",
-				criteria: { true: "the result restates the contract in its own words and lists what it had to guess", false: "the subagent did other work, had the author's context, or only summarized the spec" },
+				instructions: "Did this subagent read the spec and report on it: does its `result` restate the spec, or list gaps, guesses, or questions about it? The `brief` only needs to have handed it the spec.",
+				criteria: { true: "the result restates the spec or lists gaps, guesses, or questions about it", false: "the subagent did other work and its result does not report on the spec" },
 			},
 		});
 		const probability = answers?.fresh_read?.type === "bool" ? answers.fresh_read.probability : undefined;

package/pi/second-thought.ts

@@ -12,31 +12,13 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import {
-	type Book,
-	allFriction,
-	childLines,
-	currentIntent,
-	currentKind,
-	diffAgainstBases,
-	diffText,
-	guarded,
-	isOpenTask,
-	latestAnchor,
-	openLoop,
-	replayTodos,
-	reviewClearAfterLastAct,
-	reviewTrend,
-	stagesDone,
-	TASK_LEGEND,
-	taskLines,
-	verifyAfterLastAct,
-} from "./support/book.ts";
+import { currentKind, guarded, openLoop } from "./support/book.ts";
 import { type Answers, classify } from "./support/jev.ts";
-import { computePhases } from "./support/phases.ts";
+import { type Snapshot, snapshot } from "./support/snapshot.ts";
 import { isSubagent } from "./support/subagent.ts";
 
-export { isSubagent };
+export { isSubagent, snapshot };
+export type { Snapshot };
 
 export const ENTRY_TYPE = "anchorloop-second-thought";
 const WAIT_TOOLS = new Set(["MonitorCreate", "LoopCreate", "goal_wait", "subagent", "subagent_resume", "subagent_send"]);
@@ -114,52 +96,6 @@ export function readVerdict(answers: Answers): Verdict | undefined {
 	};
 }
 
-export type Snapshot = {
-	state: Record<string, string>;
-	/** The program's next phase and what it lacks, in a few words. */
-	next: string;
-	missing: string;
-	/** Advisory hints that are not phases, such as an unrecorded friction. */
-	hints: string[];
-	/** The last phase the book shows complete. */
-	current: string;
-	/** A review recorded after the last change with no blocking finding on it. */
-	reviewClear: boolean;
-};
-
-export function snapshot(book: Book, ctx: { cwd: string; sessionManager: { getBranch(): unknown[] } }): Snapshot {
-	const { entries } = book;
-	const todos = replayTodos(ctx.sessionManager.getBranch());
-	const open = todos.filter(isOpenTask).length;
-	const phases = computePhases(book, { cwd: ctx.cwd, todos });
-	const check = verifyAfterLastAct(entries);
-	const verify = [
-		`stages: ${stagesDone(entries).join(", ") || "none"}`,
-		`last check: ${check ? `${check.declared ? `declared ${check.result}` : `exit ${check.exit ?? "unknown"}`}${check.last ? ` — ${check.last}` : ""}` : "none after the last change"}`,
-		`reviews: ${reviewTrend(entries)}`,
-		...childLines(entries).map((line) => `child ${line}`),
-	].join("; ");
-	const friction = allFriction(entries).map((item) => `${item.ref}: ${item.tried} → ${item.found} [${item.reflected ? item.class : "unreflected"}]`);
-	return {
-		state: {
-			kind: currentKind(entries) ?? "not declared",
-			intent: (currentIntent(entries) ?? "not declared").slice(0, 500),
-			anchor: (latestAnchor(entries) ?? "none").slice(0, 500),
-			diff: diffText(diffAgainstBases(entries)),
-			phase: `current: ${phases.current}; next: ${phases.next}${phases.missing ? `; missing: ${phases.missing}` : ""}${phases.skipped.length ? `; skipped: ${phases.skipped.join(", ")}` : ""}`.slice(0, 600),
-			verify: verify.slice(0, 1200),
-			todos: `${open} open of ${todos.length}`,
-			tasks: [`legend: ${TASK_LEGEND}`, ...taskLines(entries, todos, ctx.cwd)].join("\n").slice(0, 1500),
-			friction: (friction.join("\n") || "none").slice(0, 800),
-		},
-		next: phases.next,
-		missing: phases.missing,
-		hints: phases.hints,
-		current: phases.current,
-		reviewClear: reviewClearAfterLastAct(entries),
-	};
-}
-
 export function assess(verdict: Verdict, snap: Snapshot): { found: string[]; notes: string[] } {
 	const found: string[] = [];
 	const notes: string[] = [];
@@ -229,15 +165,17 @@ export default function (pi: ExtensionAPI) {
 	pi.on(
 		"tool_result",
 		guarded(async (event, ctx) => {
-			const snap = closing.get(event.toolCallId);
-			if (!snap) return;
-			closing.delete(event.toolCallId);
+			const called = closing.get(event.toolCallId);
+			if (called) closing.delete(event.toolCallId);
 			if (event.isError) return;
+			// The close tool reports the loop as it stood when it closed, after any reflect that ran beside it.
+			const snap = (event.details as { snapshot?: Snapshot } | undefined)?.snapshot ?? called;
+			if (!snap) return;
 			const judgment = await judge(ctx, snap);
 			if (!judgment?.verdict) return;
 			const { found, notes } = assess(judgment.verdict, snap);
 			pi.appendEntry(ENTRY_TYPE, { ...judgment.verdict, at: "close", concerns: found });
-			return { content: [...event.content, { type: "text" as const, text: message(judgment.verdict, snap, found, notes, true) }] };
+			return { content: [...event.content, { type: "text" as const, text: `\n${message(judgment.verdict, snap, found, notes, true)}` }] };
 		}),
 	);
 

package/pi/support/book.ts

@@ -7,7 +7,7 @@
 
 import { createHash, randomUUID } from "node:crypto";
 import { execFileSync } from "node:child_process";
-import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, realpathSync, statSync, unlinkSync, writeSync } from "node:fs";
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, realpathSync, rmdirSync, statSync, unlinkSync, writeSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 
@@ -120,8 +120,19 @@ export function openLoop(who: Who, env: NodeJS.ProcessEnv = process.env): Book |
 	return book && !isClosed(book) ? book : undefined;
 }
 
+function openForAppend(path: string): number {
+	try {
+		return openSync(path, "a");
+	} catch (error) {
+		// Another session's sweep may remove the directory between mkdir and open; recreate it once.
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		mkdirSync(dirname(path), { recursive: true });
+		return openSync(path, "a");
+	}
+}
+
 function appendBytes(path: string, text: string): void {
-	const fd = openSync(path, "a");
+	const fd = openForAppend(path);
 	try {
 		const bytes = Buffer.from(text);
 		const written = writeSync(fd, bytes);
@@ -133,8 +144,8 @@ function appendBytes(path: string, text: string): void {
 
 export function createBook(who: Who, env: NodeJS.ProcessEnv = process.env): Book {
 	const path = bookPath(who, env);
-	mkdirSync(dirname(path), { recursive: true });
 	if (existsSync(path)) deleteBook(path);
+	mkdirSync(dirname(path), { recursive: true });
 	const child = childId(env);
 	const header = {
 		// Unique per loop: the file name follows the session, so a reopened loop must not reuse an old id.
@@ -166,12 +177,29 @@ export function findChildBook(id: string, env: NodeJS.ProcessEnv = process.env):
 	return undefined;
 }
 
+function removeIfEmpty(dir: string): boolean {
+	try {
+		rmdirSync(dir);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** Removes the `agents/` and project directories a deleted book leaves empty. */
+function tidy(dir: string): void {
+	if (!removeIfEmpty(dir)) return;
+	const parent = dirname(dir);
+	if (basename(dir) === "agents") removeIfEmpty(parent);
+}
+
 export function deleteBook(path: string): void {
 	try {
 		unlinkSync(path);
 	} catch {
 		// Already gone.
 	}
+	tidy(dirname(path));
 }
 
 export type Sweep = { deleted: string[]; open: string[] };
@@ -194,33 +222,47 @@ export function sweep(env: NodeJS.ProcessEnv = process.env, cwd?: string): Sweep
 	const slug = cwd ? projectSlug(cwd) : undefined;
 	const linked = new Set<string>();
 	const children: Book[] = [];
+	// Other sessions create and tidy books concurrently, so a directory or file can vanish mid-walk; skip it.
 	for (const project of readdirSync(root)) {
-		const dir = join(root, project);
-		if (!statSync(dir).isDirectory()) continue;
-		for (const file of readdirSync(dir)) {
-			if (!file.endsWith(".yml")) continue;
-			const book = parseBook(join(dir, file));
-			if (!book) continue;
-			if (sessionGone(book)) {
-				deleteBook(book.path);
-				result.deleted.push(book.path);
-				continue;
+		try {
+			const dir = join(root, project);
+			if (!statSync(dir).isDirectory()) continue;
+			for (const file of readdirSync(dir)) {
+				if (!file.endsWith(".yml")) continue;
+				const book = parseBook(join(dir, file));
+				if (!book) continue;
+				if (sessionGone(book)) {
+					deleteBook(book.path);
+					result.deleted.push(book.path);
+					continue;
+				}
+				if (!slug || project === slug) result.open.push(`${book.path} (${currentKind(book.entries) ?? "no kind"}: ${currentIntent(book.entries) ?? "no intent"})`);
+				for (const entry of book.entries) if (entry.stage === "link" && typeof entry.child === "string") linked.add(safe(entry.child));
 			}
-			if (!slug || project === slug) result.open.push(`${book.path} (${currentKind(book.entries) ?? "no kind"}: ${currentIntent(book.entries) ?? "no intent"})`);
-			for (const entry of book.entries) if (entry.stage === "link" && typeof entry.child === "string") linked.add(safe(entry.child));
-		}
-		const agents = join(dir, "agents");
-		if (existsSync(agents)) {
-			for (const file of readdirSync(agents)) {
-				const child = file.endsWith(".yml") ? parseBook(join(agents, file)) : undefined;
-				if (child) children.push(child);
+			const agents = join(dir, "agents");
+			if (existsSync(agents)) {
+				for (const file of readdirSync(agents)) {
+					const child = file.endsWith(".yml") ? parseBook(join(agents, file)) : undefined;
+					if (child) children.push(child);
+				}
 			}
+		} catch {
+			// Vanished under a concurrent tidy.
 		}
 	}
 	for (const child of children) {
-		if (linked.has(basename(child.path, ".yml")) || !sessionGone(child)) continue;
-		deleteBook(child.path);
-		result.deleted.push(child.path);
+		try {
+			if (linked.has(basename(child.path, ".yml")) || !sessionGone(child)) continue;
+			deleteBook(child.path);
+			result.deleted.push(child.path);
+		} catch {
+			// Vanished under a concurrent tidy.
+		}
+	}
+	for (const project of readdirSync(root)) {
+		const dir = join(root, project);
+		removeIfEmpty(join(dir, "agents"));
+		removeIfEmpty(dir);
 	}
 	return result;
 }
@@ -255,6 +297,26 @@ export function lastIndex(entries: Entry[], ...stages: string[]): number {
 	return -1;
 }
 
+/**
+ * The book's entries with the change entries of its linked children merged in by time, each marked `child`, so a coordinator
+ * whose edits are all made by children still shows an act. Indexes into the result differ from indexes into `entries`.
+ */
+export function withChildActs(entries: Entry[], env: NodeJS.ProcessEnv = process.env): Entry[] {
+	const acts: Entry[] = [];
+	for (const id of childIds(entries)) {
+		const child = findChildBook(id, env);
+		if (child) acts.push(...child.entries.filter((entry) => entry.stage === "edit").map((entry) => ({ ...entry, child: id })));
+	}
+	if (acts.length === 0) return entries;
+	acts.sort((a, b) => a.ts.localeCompare(b.ts));
+	const merged: Entry[] = [];
+	for (const entry of entries) {
+		while (acts.length && acts[0].ts < entry.ts) merged.push(acts.shift() as Entry);
+		merged.push(entry);
+	}
+	return [...merged, ...acts];
+}
+
 /** The index of the latest change entry (a production write or edit, a commit), or -1. */
 export function lastActIndex(entries: Entry[]): number {
 	return lastIndex(entries, "edit");
@@ -281,7 +343,8 @@ export function reviewTrend(entries: Entry[]): string {
 }
 
 /** A review recorded after the last change with no blocking finding on it. */
-export function reviewClearAfterLastAct(entries: Entry[]): boolean {
+export function reviewClearAfterLastAct(raw: Entry[]): boolean {
+	const entries = withChildActs(raw);
 	const review = lastIndex(entries, "review");
 	return review >= 0 && review > lastActIndex(entries) && entries[review].blocking === false;
 }
@@ -302,7 +365,8 @@ function evidenceLine(entry: Entry): string {
 }
 
 /** The latest check or verify entry after the last change, or undefined when none follows it. */
-export function verifyAfterLastAct(entries: Entry[]): Entry | undefined {
+export function verifyAfterLastAct(raw: Entry[]): Entry | undefined {
+	const entries = withChildActs(raw);
 	const index = lastIndex(entries, "check", "verify");
 	return index >= 0 && index > lastActIndex(entries) ? entries[index] : undefined;
 }
@@ -369,18 +433,23 @@ export function allFriction(entries: Entry[], env: NodeJS.ProcessEnv = process.e
 
 export type RetryPair = { key: string; fail: number; pass: number };
 
-/** Runs that failed and later passed, per anchor and per task anchor, found from the recorded exit codes. */
+/** Regressions: a run that failed after the same command had passed in this loop, and then passed again. A failure before any pass is red-first work, not a retry. */
 export function retryPairs(entries: Entry[]): RetryPair[] {
 	const pairs: RetryPair[] = [];
+	const passed = new Set<string>();
 	const failed = new Map<string, number>();
 	entries.forEach((entry, index) => {
-		const key = entry.stage === "taskrun" ? `task#${entry.id}` : entry.stage === "verify" || entry.stage === "check" ? "anchor" : undefined;
+		if (entry.declared === true) return;
+		const key = entry.stage === "taskrun" ? `task#${entry.id}` : entry.stage === "verify" || entry.stage === "check" ? `anchor:${String(entry.command ?? "")}` : undefined;
 		if (!key || typeof entry.exit !== "number") return;
 		if (entry.exit !== 0) {
-			if (!failed.has(key)) failed.set(key, index);
-		} else if (failed.has(key)) {
-			pairs.push({ key, fail: failed.get(key) as number, pass: index });
-			failed.delete(key);
+			if (passed.has(key) && !failed.has(key)) failed.set(key, index);
+		} else {
+			if (failed.has(key)) {
+				pairs.push({ key, fail: failed.get(key) as number, pass: index });
+				failed.delete(key);
+			}
+			passed.add(key);
 		}
 	});
 	return pairs;
@@ -456,6 +525,12 @@ export function repoOf(path: string): { repo: string; head: string } | undefined
 	return repo && head ? { repo: real(repo), head } : undefined;
 }
 
+/** The root of the git repo containing `path`, or undefined outside a repo. */
+export function repoRootOf(path: string): string | undefined {
+	const repo = git(existingDir(dirname(resolve(path))), ["rev-parse", "--show-toplevel"]);
+	return repo ? real(repo) : undefined;
+}
+
 export function bases(entries: Entry[]): { repo: string; head: string }[] {
 	return entries.filter((entry) => entry.stage === "base").map((entry) => ({ repo: String(entry.repo), head: String(entry.head) }));
 }
@@ -485,11 +560,11 @@ export function diffAgainstBases(entries: Entry[]): Diff {
 			lines.push(`${basename(repo)}: diff unavailable`);
 			continue;
 		}
-		lines.push(`${basename(repo)}: ${stat || "no tracked changes"}${untracked.length ? `; ${untracked.length} untracked` : ""}`);
+		if (stat) lines.push(`${basename(repo)}: ${stat}`);
 		files.push(...names.map((name) => `${basename(repo)}/${name}`), ...untracked.map((name) => `${basename(repo)}/${name}`));
 		paths.push(...[...names, ...untracked].map((name) => join(repo, name)));
 	}
-	return { summary: lines.join("\n") || "no repository", files, paths };
+	return { summary: lines.join("\n") || (bases(entries).length ? "no tracked changes" : "no repository"), files, paths };
 }
 
 export function diffText(diff: Diff, limit = 1200): string {
@@ -633,19 +708,33 @@ export function artifactOnDisk(folder: string, name: string, cwd: string): Entry
 
 // --- todo links ----------------------------------------------------------------------------------
 
-/** The `ref` metadata of a task as a list of `<path>#<heading>` pointers. */
+const MARKDOWN = /\.(md|markdown)$/i;
+
+const isMarkdownRef = (ref: string): boolean => MARKDOWN.test(ref.split("#")[0]);
+
+/** The `ref` metadata of a task as pointers: `<path>#<heading>` into markdown, or the path of any other file. */
 export function refsOf(metadata: Record<string, unknown> | undefined): string[] {
 	const ref = metadata?.ref;
 	const list = Array.isArray(ref) ? ref : [ref];
-	return list.filter((item): item is string => typeof item === "string" && item.includes("#"));
+	return list.filter((item): item is string => typeof item === "string" && item.trim() !== "" && (item.includes("#") || !isMarkdownRef(item)));
 }
 
-/** The line range of the section `<path>#<heading>` names, such as `L88-L101`, or `missing` when the file or heading is gone. */
+/**
+ * The line range of the section `<path>#<heading>` names, such as `L88-L101`, or `missing` when the file or heading is gone.
+ * A ref to a file that is not markdown has no headings to resolve and returns "" (shown as given). Relative paths resolve against
+ * the cwd, the loop's repos, and the folders of recorded artifacts.
+ */
 export function resolveRef(ref: string, cwd: string, entries: Entry[]): string {
+	if (!isMarkdownRef(ref)) return "";
 	const split = ref.indexOf("#");
+	if (split < 0) return "";
 	const path = ref.slice(0, split);
 	const heading = ref.slice(split + 1).trim();
-	const dirs = [cwd, ...new Set(entries.filter((entry) => typeof entry.path === "string").map((entry) => dirname(resolve(cwd, entry.path as string))))];
+	const dirs = [
+		cwd,
+		...bases(entries).map((base) => base.repo),
+		...new Set(entries.filter((entry) => typeof entry.path === "string").map((entry) => dirname(resolve(cwd, entry.path as string)))),
+	];
 	for (const dir of dirs) {
 		let lines: string[];
 		try {
@@ -692,7 +781,11 @@ export function taskLines(entries: Entry[], todos: Task[], cwd: string): string[
 			const task = live.get(entry.id as number);
 			const run = exits.get(entry.id as number);
 			const anchor = typeof entry.anchor === "string" ? `${entry.anchor}${run ? ` (exit ${run.exit})` : ""}` : "loop anchor";
-			const refs = ((entry.refs ?? []) as { ref: string }[]).map((item) => `${item.ref} → ${resolveRef(item.ref, cwd, entries)}`);
-			return [`#${entry.id} ${task?.status} ${task?.subject}`, anchor, ...(refs.length ? [refs.join(", ")] : [])].join(" — ");
+			const refs = ((entry.refs ?? []) as { ref: string }[]).map((item) => {
+				const range = resolveRef(item.ref, cwd, entries);
+				return range ? `${item.ref} → ${range}` : item.ref;
+			});
+			const followup = task?.metadata?.followup ?? entry.followup;
+			return [`#${entry.id} ${task?.status} ${task?.subject}`, anchor, ...(refs.length ? [refs.join(", ")] : []), ...(followup !== undefined ? [`followup: ${String(followup)}`] : [])].join(" — ");
 		});
 }

package/pi/support/phases.ts

@@ -19,8 +19,10 @@ import {
 	currentKind,
 	lastActIndex,
 	lastIndex,
+	repoRootOf,
 	retryWithoutFriction,
 	specFolder,
+	withChildActs,
 } from "./book.ts";
 
 export const SEQUENCES: Record<Kind, readonly string[]> = {
@@ -30,7 +32,7 @@ export const SEQUENCES: Record<Kind, readonly string[]> = {
 	durable: ["decide", "grill", "spec", "read", "approve", "design", "anchor", "act", "verify", "review", "reflect", "close"],
 };
 
-export type Status = { name: string; state: "done" | "skipped" | "missing"; note: string };
+export type Status = { name: string; state: "done" | "skipped" | "missing"; note: string; /** Skipped by the evidence itself (no open rows, no friction), not by a `skip` declaration. */ auto?: boolean };
 
 export type Phases = {
 	kind: Kind | "undeclared";
@@ -66,11 +68,17 @@ function within(root: string, target: string): boolean {
 	return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
 }
 
-/** Scratch and spec folders in the project and temp files outside it; a project that lives in a temp dir is still counted. */
+/**
+ * True for a file that is not code work: scratch and spec folders of the project or of any git repo the file lives in, and
+ * temp files outside every repo. A file inside a git repo counts as work wherever the repo is, even under a temp dir.
+ */
 export function outsideWork(filePath: string, cwd: string): boolean {
 	const root = real(cwd);
 	const target = real(resolve(cwd, filePath));
-	if (within(root, target)) return EXEMPT_IN_PROJECT.some((dir) => within(join(root, dir), target));
+	const inFolders = (base: string) => EXEMPT_IN_PROJECT.some((dir) => within(join(base, dir), target));
+	if (within(root, target)) return inFolders(root);
+	const repo = repoRootOf(target);
+	if (repo) return inFolders(repo);
 	return EXEMPT_ROOTS.some((tmp) => within(real(tmp), target));
 }
 
@@ -155,7 +163,7 @@ function evaluate(name: string, ctx: Ctx): Status {
 			const open = Number((decision.counts as Record<string, number>).open ?? 0);
 			if (open > 0) return missing(name, `${open} open decision row${open === 1 ? "" : "s"}`);
 			const first = entries.find((entry) => entry.stage === "decision" && entry.auto === true);
-			return first && Number((first.counts as Record<string, number>).open ?? 0) === 0 ? { name, state: "skipped", note: "no open rows" } : done(name);
+			return first && Number((first.counts as Record<string, number>).open ?? 0) === 0 ? { name, state: "skipped", note: "no open rows", auto: true } : done(name);
 		}
 		case "spec": {
 			const spec = artifact(ctx, "spec", from);
@@ -194,8 +202,10 @@ function evaluate(name: string, ctx: Ctx): Status {
 				return missing(name, command ? `a passing run of \`${command}\` after the last change` : "a verify declaration or a run of the anchor");
 			}
 			const entry = entries[index];
-			if (entry.declared === true) return entry.result === "fail" ? missing(name, "the declared verify failed") : done(name, "declared");
-			return entry.exit === 0 ? done(name) : missing(name, `the anchor exited ${entry.exit ?? "unknown"} after the last change`);
+			if (entry.declared === true && entry.result === "fail") return missing(name, "the declared verify failed");
+			if (entry.declared !== true && entry.exit !== 0) return missing(name, `the anchor exited ${entry.exit ?? "unknown"} after the last change`);
+			if (ctx.seq.includes("decide") && !artifact(ctx, "verification", from)) return missing(name, `${ctx.folder ?? "docs/specs/<folder>"}/verification.md (a durable loop's verify also needs it)`);
+			return done(name, entry.declared === true ? "declared" : "");
 		}
 		case "review": {
 			const index = lastWhere(entries, Math.max(from, ctx.lastAct + 1), (entry) => entry.stage === "review");
@@ -208,7 +218,7 @@ function evaluate(name: string, ctx: Ctx): Status {
 		}
 		case "reflect": {
 			const items = allFriction(entries, ctx.env);
-			if (items.length === 0) return { name, state: "skipped", note: "no friction" };
+			if (items.length === 0) return { name, state: "skipped", note: "no friction", auto: true };
 			const open = items.filter((item) => !item.reflected).length;
 			return open === 0 ? done(name) : missing(name, `${open} friction entr${open === 1 ? "y" : "ies"} without a reflect`);
 		}
@@ -221,7 +231,8 @@ function evaluate(name: string, ctx: Ctx): Status {
 export function computePhases(book: Pick<Book, "entries">, inputs: Omit<Inputs, "entries">): Phases {
 	const kind = currentKind(book.entries);
 	const seq = SEQUENCES[kind ?? "inline"];
-	const ctx: Ctx = { ...inputs, entries: book.entries, seq, folder: specFolder(book.entries, inputs.todos, inputs.cwd), lastAct: lastActIndex(book.entries) };
+	const entries = withChildActs(book.entries);
+	const ctx: Ctx = { ...inputs, entries, seq, folder: specFolder(entries, inputs.todos, inputs.cwd), lastAct: lastActIndex(entries) };
 	const statuses = seq.filter((name) => name !== "close").map((name) => evaluate(name, ctx));
 	let prefix = 0;
 	while (prefix < statuses.length && statuses[prefix].state !== "missing") prefix++;
@@ -230,8 +241,8 @@ export function computePhases(book: Pick<Book, "entries">, inputs: Omit<Inputs,
 	let next = first ? first.name : "close";
 	let note = first ? first.note : "";
 	const last = ctx.lastAct;
-	const verify = book.entries.map((entry, index) => ({ entry, index })).filter(({ entry, index }) => index > last && (entry.stage === "verify" || entry.stage === "check")).at(-1)?.entry;
-	const review = book.entries.map((entry, index) => ({ entry, index })).filter(({ entry, index }) => index > last && entry.stage === "review").at(-1)?.entry;
+	const verify = entries.map((entry, index) => ({ entry, index })).filter(({ entry, index }) => index > last && (entry.stage === "verify" || entry.stage === "check")).at(-1)?.entry;
+	const review = entries.map((entry, index) => ({ entry, index })).filter(({ entry, index }) => index > last && entry.stage === "review").at(-1)?.entry;
 	if ((next === "verify" || next === "check") && last >= 0 && verify && verify.exit !== 0 && verify.declared !== true) next = "fix";
 	else if (next === "review" && last >= 0 && review?.blocking === true) next = "fix";
 	if (next === "fix") note = first?.note ?? "";

package/pi/support/snapshot.ts

@@ -0,0 +1,71 @@
+/** The loop state Jev judges, read from the book, the todo list, and the phase machine. */
+
+import {
+	type Book,
+	allFriction,
+	childLines,
+	currentIntent,
+	currentKind,
+	diffAgainstBases,
+	diffText,
+	isOpenTask,
+	latestAnchor,
+	replayTodos,
+	reviewClearAfterLastAct,
+	reviewTrend,
+	stagesDone,
+	TASK_LEGEND,
+	taskLines,
+	verifyAfterLastAct,
+} from "./book.ts";
+import { computePhases } from "./phases.ts";
+
+export type Snapshot = {
+	state: Record<string, string>;
+	/** The program's next phase and what it lacks, in a few words. */
+	next: string;
+	missing: string;
+	/** Advisory hints that are not phases, such as an unrecorded friction. */
+	hints: string[];
+	/** The last phase the book shows complete. */
+	current: string;
+	/** A review recorded after the last change with no blocking finding on it. */
+	reviewClear: boolean;
+};
+
+export function snapshot(book: Book, ctx: { cwd: string; sessionManager: { getBranch(): unknown[] } }): Snapshot {
+	const { entries } = book;
+	const todos = replayTodos(ctx.sessionManager.getBranch());
+	const open = todos.filter(isOpenTask).length;
+	const phases = computePhases(book, { cwd: ctx.cwd, todos });
+	const check = verifyAfterLastAct(entries);
+	const verify = [
+		`stages: ${stagesDone(entries).join(", ") || "none"}`,
+		`last check: ${check ? `${check.declared ? `declared ${check.result}` : `exit ${check.exit ?? "unknown"}`}${check.last ? ` — ${check.last}` : ""}` : "none after the last change"}`,
+		`reviews: ${reviewTrend(entries)}`,
+		...childLines(entries).map((line) => `child ${line}`),
+	].join("; ");
+	const items = allFriction(entries);
+	const friction = [
+		...(items.length ? [`${items.length} recorded, ${items.filter((item) => item.reflected).length} reflected`] : []),
+		...items.map((item) => `${item.ref}: ${item.tried} → ${item.found} [${item.reflected ? `${item.class}${item.action ? `: ${item.action}` : ""}` : "unreflected"}]`),
+	];
+	return {
+		state: {
+			kind: currentKind(entries) ?? "not declared",
+			intent: (currentIntent(entries) ?? "not declared").slice(0, 500),
+			anchor: (latestAnchor(entries) ?? "none").slice(0, 500),
+			diff: diffText(diffAgainstBases(entries)),
+			phase: `current: ${phases.current}; next: ${phases.next}${phases.missing ? `; missing: ${phases.missing}` : ""}${phases.skipped.length ? `; skipped: ${phases.skipped.join(", ")}` : ""}`.slice(0, 600),
+			verify: verify.slice(0, 1200),
+			todos: `${open} open of ${todos.length}`,
+			tasks: [`legend: ${TASK_LEGEND}`, ...taskLines(entries, todos, ctx.cwd)].join("\n").slice(0, 1500),
+			friction: (friction.join("\n") || "none").slice(0, 800),
+		},
+		next: phases.next,
+		missing: phases.missing,
+		hints: phases.hints,
+		current: phases.current,
+		reviewClear: reviewClearAfterLastAct(entries),
+	};
+}