pi-anchorloop 2.2.3 → 2.3.0

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 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/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; a later call changes the kind only with a `reason`), `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: …`. An anchor run or declared verify of a `quick` or `inline` loop also measures the diff's reach: source files (not tests, lockfiles, specs, or prose), the top-level directories they sit in, and a README, changelog, or `*.schema.json` changed beside them. Files already changed when a repo joined the loop count only once their content changes, and a file at a repository root counts as a file, not a directory. At 3 source files, 2 directories, or one such file, the result carries one line asking to re-classify, and verify waits for a `kind` call with `reason` that answers each threshold crossed; a later threshold asks again. 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 to `advance`, go `back`, or `ask-user`, plus `done`, the review tier still needed, and quality; phase completion comes from the program's evidence alone. 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 或 `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/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 指令；之後要改種類，必須附 `reason`）、`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 <目前> ✓ → <下一個>（缺：…）· 已跳過：…`。`quick` 或 `inline` loop 跑 anchor 或宣告 verify 時，也會量 diff 的影響範圍：原始碼檔案（不含測試、lockfile、spec 與文字檔）、它們所在的頂層目錄，以及跟原始碼一起改的 README、changelog 或 `*.schema.json`。repo 加入 loop 時就已經改過的檔案，要等內容再變動才算；repo 根目錄的檔案只算檔案數，不算一個目錄。達到 3 個原始碼檔案、2 個目錄或 1 個這類檔案時，結果會附一行請 agent 重新分類；verify 要等到以 `reason` 呼叫 `kind`、回應每一個跨過的門檻才算完成，之後再跨過新的門檻會再問一次。前一個階段還沒完成就開始下一個階段，會用一行警告一次並指出 `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 的以它的名字列出），只判斷要 `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.3",
+  "version": "2.3.0",
   "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

@@ -13,6 +13,7 @@ import { join, resolve } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
 	type Book,
+	type Entry,
 	KINDS,
 	allFriction,
 	anchorCommand,
@@ -50,7 +51,7 @@ import {
 	verifyAfterLastAct,
 } from "./support/book.ts";
 import { classify } from "./support/jev.ts";
-import { SEQUENCES, computePhases, describe, incompleteBefore, outsideWork } from "./support/phases.ts";
+import { REVIEWLESS, SEQUENCES, computePhases, describe, incompleteBefore, outsideWork, reachLine, reachOf, unansweredReach } from "./support/phases.ts";
 import { type Snapshot, snapshot } from "./support/snapshot.ts";
 import { isSubagent } from "./support/subagent.ts";
 
@@ -434,7 +435,8 @@ export default function (pi: ExtensionAPI) {
 		label: "Loop stage",
 		description:
 			"Declare only what the extension cannot observe in the anchorloop loop book. " +
-			"`kind` (kind, intent, optional anchor command; call again to upgrade the kind or set the anchor): quick (act, check), inline (anchor, act, verify), reviewed (adds review), durable (adds decide, grill, spec, read, approve, design); every kind ends with reflect, close. " +
+			"`kind` (kind, intent, optional anchor command; call again to set the anchor, or with `reason` to change the kind or answer a re-classification): quick (act, check), inline (anchor, act, verify), reviewed (adds review), durable (adds decide, grill, spec, read, approve, design); every kind ends with reflect, close. " +
+			"When an anchor run or declared verify of a quick or inline loop finds the change reaching 3 source files, 2 modules, or a README, changelog, or *.schema.json beside code, its verify waits for a `kind` call with `reason`. " +
 			"`verify` (note; only for an anchor that is not a command), `fresh-read` (a fresh-context read of the spec is done), `friction` (tried, found, led_by), `reflect` (friction ids, class misdirection|gap|resolved, action), " +
 			"`skip` / `back` (phase, reason), `close` (verdict), `read` (view the book). Edits, anchor runs, reviews, and spec files are read from evidence. " +
 			"A loop opens with the first `todo` create; `close` refuses while a pending or in-progress todo lacks metadata.followup.",
@@ -442,7 +444,7 @@ export default function (pi: ExtensionAPI) {
 			type: "object",
 			properties: {
 				stage: { type: "string", enum: [...STAGES] },
-				kind: { type: "string", enum: [...KINDS], description: "stage kind: the loop kind; a second call upgrades it" },
+				kind: { type: "string", enum: [...KINDS], description: "stage kind: the loop kind; a later call with `reason` changes it" },
 				intent: { type: "string", description: "stage kind: one line on what the loop delivers" },
 				anchor: { type: "string", description: "stage kind: the check command whose exit code observes the result" },
 				note: { type: "string", description: "stage verify: what was observed; stage fresh-read: who read the spec" },
@@ -454,7 +456,7 @@ export default function (pi: ExtensionAPI) {
 				class: { type: "string", enum: ["misdirection", "gap", "resolved"], description: "stage reflect" },
 				action: { type: "string", description: "stage reflect: what was done, such as solid-loop, memory, or a commit" },
 				phase: { type: "string", description: "stage skip or back: the phase" },
-				reason: { type: "string", description: "stage skip or back: why" },
+				reason: { type: "string", description: "stage skip or back: why; stage kind: why the kind changes, or why it still fits the measured reach" },
 				verdict: { type: "string", enum: ["landed", "blocked", "abandoned"], description: "stage close" },
 				view: { type: "string", enum: ["summary", "all"], description: "stage read; default summary" },
 			},
@@ -486,26 +488,33 @@ export default function (pi: ExtensionAPI) {
 				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`");
+				if (!params.kind && !params.intent && !params.anchor && !params.reason) throw new Error("kind needs `kind`, `intent`, `anchor`, or `reason`");
 				if (!had && (!params.kind || !params.intent)) throw new Error("the first kind declaration needs `kind` and a one-line `intent`");
+				const changed = had !== undefined && params.kind !== undefined && had !== params.kind;
+				if (changed && !params.reason) throw new Error(`changing the kind from ${had} to ${params.kind} needs \`reason\`: the reach grew, the user added scope, a user-owned decision appeared, or the change turned out smaller`);
+				touchRepo(book, join(ctx.cwd, "_"));
 				const notes: string[] = [];
-				if (params.kind || params.intent) {
-					appendEntry(book.path, "kind", { kind: params.kind ?? had, ...(params.intent ? { intent: params.intent } : {}) });
-					notes.push(had && params.kind && had !== params.kind ? `kind changed: ${had} → ${params.kind}` : `kind: ${params.kind ?? had}`);
+				if (params.kind || params.intent || params.reason) {
+					// A reason answers the reach measured now, so a later threshold asks again.
+					const answer = params.reason ? { reason: params.reason, crossed: reachOf(book.entries, ctx.cwd).crossed } : {};
+					appendEntry(book.path, "kind", { kind: params.kind ?? had, ...(params.intent ? { intent: params.intent } : {}), ...answer });
+					const why = params.reason ? ` (${params.reason})` : "";
+					notes.push(changed ? `kind changed: ${had} → ${params.kind}${why}` : `kind: ${params.kind ?? had}${why}`);
 				}
 				if (params.anchor) {
 					appendEntry(book.path, "anchor", { check: params.anchor });
 					notes.push(`anchor: ${params.anchor}`);
 				}
-				touchRepo(book, join(ctx.cwd, "_"));
 				return reply(notes.join("\n"));
 			}
 			if (stage === "verify") {
 				if (!params.note) throw new Error("verify needs a `note` saying what was observed");
 				const result = params.result ?? "pass";
 				const recorded = childId() !== undefined || had === "quick" ? "check" : "verify";
-				appendEntry(book.path, recorded, { declared: true, note: params.note, result, exit: result === "pass" ? 0 : 1 });
-				return reply(`${recorded} declared: ${result} — ${params.note}`);
+				const entry = appendEntry(book.path, recorded, { declared: true, note: params.note, result, exit: result === "pass" ? 0 : 1, ...reachField(book, ctx.cwd) });
+				book.entries.push(entry);
+				const notice = reachNotice(book, entry);
+				return reply(`${recorded} declared: ${result} — ${params.note}${notice ? `\n${notice}` : ""}`);
 			}
 			if (stage === "fresh-read") {
 				appendEntry(book.path, "goldfish", { source: "declared", ...(params.note ? { note: params.note } : {}) });
@@ -558,17 +567,34 @@ export default function (pi: ExtensionAPI) {
 		}),
 	);
 
-	/** Records what a finished bash call shows: runs of the loop anchor, of task anchors, and a first commit as the change. */
-	function recordBash(book: Book, event: { input: unknown; isError?: boolean; structuredContent?: unknown; content?: unknown }): void {
+	/** The reach of an unreviewed loop's diff, recorded on its verify or check entry; a reviewed loop is never measured. */
+	function reachField(book: Book, cwd: string): { reach?: ReturnType<typeof reachOf> } {
+		return REVIEWLESS.has(currentKind(book.entries) ?? "inline") ? { reach: reachOf(book.entries, cwd) } : {};
+	}
+
+	/** The line that asks the loop to re-classify after a verify or check entry whose reach no `kind` answer covers. */
+	function reachNotice(book: Book, entry: Entry): string | undefined {
+		const reach = entry.reach as ReturnType<typeof reachOf> | undefined;
+		return reach && unansweredReach(book.entries, reach).length > 0 ? `anchorloop: ${reachLine(reach, currentKind(book.entries))}.` : undefined;
+	}
+
+	/**
+	 * Records what a finished bash call shows: runs of the loop anchor, of task anchors, and a first commit as the change.
+	 * Returns the re-classification line when an anchor run of an unreviewed loop measured a reach no `kind` answer covers.
+	 */
+	function recordBash(book: Book, event: { input: unknown; isError?: boolean; structuredContent?: unknown; content?: unknown }, cwd: string): string | undefined {
 		const structured = event.structuredContent as { output?: unknown } | undefined;
 		const output = typeof structured?.output === "string" ? structured.output : textOf(event.content);
 		const command = String((event.input as { command?: unknown }).command ?? "");
 		const exit = bashExit(event);
 		const last = lastLine(output);
 		const anchor = anchorCommand(book.entries);
+		let notice: string | undefined;
 		if (anchor && anchorRun(command, anchor)) {
 			const recorded = childId() !== undefined || currentKind(book.entries) === "quick" ? "check" : "verify";
-			book.entries.push(appendEntry(book.path, recorded, { command: anchor.slice(0, 200), exit: anchorExit(command, anchor, exit), last }));
+			const entry = appendEntry(book.path, recorded, { command: anchor.slice(0, 200), exit: anchorExit(command, anchor, exit), last, ...reachField(book, cwd) });
+			book.entries.push(entry);
+			notice = reachNotice(book, entry);
 		}
 		for (const task of latestTasks(book.entries)) {
 			if (typeof task.anchor === "string" && anchorRun(command, task.anchor)) appendEntry(book.path, "taskrun", { id: task.id, exit: anchorExit(command, task.anchor, exit), last });
@@ -582,6 +608,7 @@ export default function (pi: ExtensionAPI) {
 			const cwd = String(book.header.cwd ?? "");
 			if (diffAgainstBases(book.entries).paths.some((path) => !outsideWork(path, cwd))) appendEntry(book.path, "edit", { via: "commit" });
 		}
+		return notice;
 	}
 
 	pi.on(
@@ -589,8 +616,9 @@ export default function (pi: ExtensionAPI) {
 		guarded((event, ctx) => {
 			if (event.toolName === "bash") {
 				const book = openLoop(ctx);
-				if (book) recordBash(book, event);
-				return;
+				const notice = book ? recordBash(book, event, ctx.cwd) : undefined;
+				// The line only appends text, so the bash call's structured output passes on unchanged.
+				return notice ? { content: [...((event.content as unknown[]) ?? []), { type: "text", text: notice }], structuredContent: event.structuredContent } : undefined;
 			}
 			if (event.isError) return;
 			if (event.toolName === "todo") {

package/pi/support/book.ts

@@ -579,12 +579,34 @@ 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) }));
 }
 
-/** Adds the repo of `path` to the book with its HEAD when the book has no base for it yet. */
+/**
+ * The content hash of each of `names` in `repo`, `deleted` for a path that is gone, and `unknown` for one git cannot hash
+ * (a directory or submodule). One such path fails the batch, so the batch falls back to hashing each path alone.
+ */
+export function contentHashes(repo: string, names: string[]): Record<string, string> {
+	const found: Record<string, string> = {};
+	const present = names.filter((name) => existsSync(join(repo, name)));
+	for (const name of names) if (!present.includes(name)) found[name] = "deleted";
+	const batch = present.length ? git(repo, ["hash-object", "--", ...present])?.split("\n") : [];
+	present.forEach((name, index) => {
+		found[name] = (batch ? batch[index] : git(repo, ["hash-object", "--", name])) || "unknown";
+	});
+	return found;
+}
+
+/** The paths already changed or untracked in `repo` against `head`, with their content hashes: work the loop found, not made. */
+function dirtyAt(repo: string, head: string): Record<string, string> {
+	const changed = git(repo, ["diff", "--name-only", head])?.split("\n") ?? [];
+	const untracked = git(repo, ["ls-files", "--others", "--exclude-standard"])?.split("\n") ?? [];
+	return contentHashes(repo, [...new Set([...changed, ...untracked].filter(Boolean))].slice(0, 500));
+}
+
+/** Adds the repo of `path` to the book with its HEAD, and the paths already dirty there, when the book has no base for it yet. */
 export function touchRepo(book: Book, path: string): boolean {
 	const found = repoOf(path);
 	if (!found) return false;
 	if (bases(book.entries).some((base) => base.repo === found.repo)) return false;
-	const entry = appendEntry(book.path, "base", found);
+	const entry = appendEntry(book.path, "base", { ...found, dirty: dirtyAt(found.repo, found.head) });
 	book.entries.push(entry);
 	return true;
 }
@@ -602,8 +624,9 @@ export function touchRepoBeforeMerge(book: Book, dir: string, verb: string): boo
 	const first = reflog.findIndex((line) => !ofVerb(line));
 	const before = reflog.length > 0 && ofVerb(reflog[0]) && first > 0 ? reflog[first].slice(0, 40) : undefined;
 	// A rebasing pull leaves the old HEAD off HEAD's history; their merge base keeps the pulled commits in the diff.
+	// The dirty snapshot is the uncommitted work against HEAD, so the merged files stay the loop's change.
 	const base = before === undefined ? undefined : git(found.repo, ["merge-base", before, "HEAD"]);
-	book.entries.push(appendEntry(book.path, "base", { repo: found.repo, head: base || found.head }));
+	book.entries.push(appendEntry(book.path, "base", { repo: found.repo, head: base || found.head, dirty: dirtyAt(found.repo, found.head) }));
 	return true;
 }
 

package/pi/support/phases.ts

@@ -16,7 +16,10 @@ import {
 	allFriction,
 	anchorCommand,
 	artifactOnDisk,
+	bases,
+	contentHashes,
 	currentKind,
+	diffAgainstBases,
 	lastActIndex,
 	lastIndex,
 	repoRootOf,
@@ -87,6 +90,99 @@ export function exempt(filePath: string, cwd: string): boolean {
 	return EXEMPT_EXTENSIONS.includes(extname(filePath).toLowerCase()) || outsideWork(filePath, cwd);
 }
 
+// --- reach -----------------------------------------------------------------------------------------
+
+/** What a change reaches, measured from its diff: the count an unreviewed loop is re-classified at, not the author's confidence. */
+export type Reach = { source: string[]; modules: string[]; behavior: string[]; crossed: string[] };
+
+/** The kinds that never run a review; a change past the reach thresholds asks them to re-classify. */
+export const REVIEWLESS: ReadonlySet<string> = new Set(["quick", "inline"]);
+const REACH_FILES = 3;
+const REACH_MODULES = 2;
+
+// `spec/` and `specs/` count as tests, the RSpec and Jasmine layout; a durable spec folder is outside work anyway.
+const TEST_PATH = /(?:^|\/)(?:tests?|__tests__|testdata|fixtures|specs?)\/|\.(?:test|spec)\.[^/]+$|(?:^|\/)(?:test_[^/]+|conftest)\.py$|_test\.(?:py|go)$/i;
+const LOCKFILE =
+	/(?:^|\/)(?:package-lock\.json|npm-shrinkwrap\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb?|uv\.lock|poetry\.lock|Pipfile\.lock|Cargo\.lock|go\.sum|Gemfile\.lock|composer\.lock|flake\.lock|pubspec\.lock|mix\.lock|packages\.lock\.json|Package\.resolved)$/;
+/** Files that describe behavior to its users: a change to one beside source code changes what users were told. */
+const BEHAVIOR = /(?:^|\/)(?:(?:README|CHANGELOG)(?:\.[a-z0-9]+)?|\.changelog\/[^/]+|[^/]+\.schema\.json)$/i;
+
+/** Each path of the diff with its repo and repo-relative POSIX name, leaving out work outside the loop's code and paths still as the loop found them. */
+function loopPaths(entries: Entry[], cwd: string): { repo: string; rel: string }[] {
+	const repos = bases(entries).map((base) => base.repo);
+	const found = new Map<string, Record<string, string>>();
+	for (const entry of entries) if (entry.stage === "base" && entry.dirty && typeof entry.dirty === "object") found.set(String(entry.repo), entry.dirty as Record<string, string>);
+	const paths = diffAgainstBases(entries)
+		.paths.filter((path) => !outsideWork(path, cwd))
+		.map((path) => {
+			const repo = repos.find((root) => within(root, path)) ?? cwd;
+			return { repo, rel: relative(repo, path).split("\\").join("/") };
+		});
+	const unchanged = new Set<string>();
+	for (const repo of repos) {
+		const dirty = found.get(repo) ?? {};
+		const names = paths.filter((path) => path.repo === repo && path.rel in dirty).map((path) => path.rel);
+		const now = names.length ? contentHashes(repo, names) : {};
+		// An `unknown` hash proves nothing, so that path counts.
+		for (const name of names) if (dirty[name] !== "unknown" && now[name] === dirty[name]) unchanged.add(`${repo}\0${name}`);
+	}
+	return paths.filter((path) => !unchanged.has(`${path.repo}\0${path.rel}`));
+}
+
+/**
+ * The reach of the loop's diff against its bases: source files (not tests, lockfiles, behavior files, or what `exempt`
+ * names), the top-level directories they sit in, and the behavior files changed beside them. Paths already dirty when
+ * a base was recorded count once their content changes. A file at a repository root counts as a file, not a module.
+ * `crossed` names each threshold passed: `files` at three source files, `modules` at two directories, `behavior` at one
+ * behavior file.
+ */
+export function reachOf(entries: Entry[], cwd: string): Reach {
+	const several = bases(entries).length > 1;
+	const source: string[] = [];
+	const behavior: string[] = [];
+	const modules = new Set<string>();
+	for (const { repo, rel } of loopPaths(entries, cwd)) {
+		const shown = several ? `${basename(repo)}/${rel}` : rel;
+		if (BEHAVIOR.test(rel)) behavior.push(shown);
+		else if (!TEST_PATH.test(rel) && !LOCKFILE.test(rel) && !exempt(join(repo, rel), cwd)) {
+			source.push(shown);
+			if (rel.includes("/")) modules.add(`${several ? `${basename(repo)}/` : ""}${rel.slice(0, rel.indexOf("/"))}`);
+		}
+	}
+	const counted = source.length > 0 ? behavior : [];
+	const crossed = [
+		...(source.length >= REACH_FILES ? ["files"] : []),
+		...(modules.size >= REACH_MODULES ? ["modules"] : []),
+		...(counted.length > 0 ? ["behavior"] : []),
+	];
+	return { source: source.sort(), modules: [...modules].sort(), behavior: counted.sort(), crossed };
+}
+
+/** The thresholds a `kind` call with a `reason` has answered so far. */
+function answeredReach(entries: Entry[]): Set<string> {
+	const answered = new Set<string>();
+	for (const entry of entries) if (entry.stage === "kind" && typeof entry.reason === "string" && Array.isArray(entry.crossed)) for (const name of entry.crossed) answered.add(String(name));
+	return answered;
+}
+
+/** The thresholds the reach crossed that no `kind` answer covers yet; empty for a reviewed or durable loop. */
+export function unansweredReach(entries: Entry[], reach: Reach | undefined): string[] {
+	if (!reach || !REVIEWLESS.has(currentKind(entries) ?? "inline")) return [];
+	const answered = answeredReach(entries);
+	return reach.crossed.filter((name) => !answered.has(name));
+}
+
+/** The one line that asks an unreviewed loop to re-classify; an undeclared loop is asked to declare its kind. */
+export function reachLine(reach: Reach, kind: string | undefined): string {
+	const files = `${reach.source.length} source file${reach.source.length === 1 ? "" : "s"}`;
+	const modules = `${reach.modules.length} module${reach.modules.length === 1 ? "" : "s"} (${reach.modules.slice(0, 4).join(", ")}${reach.modules.length > 4 ? ", …" : ""})`;
+	const told = reach.behavior.length ? ` and changes ${reach.behavior.slice(0, 3).join(", ")}${reach.behavior.length > 3 ? ", …" : ""}` : "";
+	const ask = kind
+		? `call \`kind\` with \`reason\`: upgrade to reviewed, or say why ${kind} still fits`
+		: "declare `kind` with `intent` and `reason`: reviewed when it reaches past its files, or inline and why it still fits";
+	return `the change reaches ${files} across ${modules}${told}; ${ask}`;
+}
+
 // --- evidence ------------------------------------------------------------------------------------
 
 type Ctx = Inputs & { seq: readonly string[]; folder?: string; lastAct: number };
@@ -206,6 +302,8 @@ function evaluate(name: string, ctx: Ctx): Status {
 			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)`);
+			const reach = entry.reach as Reach | undefined;
+			if (unansweredReach(entries, reach).length > 0) return missing(name, reachLine(reach as Reach, currentKind(entries)));
 			return done(name, entry.declared === true ? "declared" : "");
 		}
 		case "review": {

package/skills/anchorloop/SKILL.md

@@ -9,7 +9,7 @@ Every entry skill (`answering`, `investigating`, `inspecting`, `coding`, `writin
 
 ## Align
 
-Pick the entry's playbook from its index; with none fitting, run the loop bare. `todo` holds real work items only, optionally with `metadata.anchor` (a task's own check) and `metadata.ref` (`<path>#<heading>`). The first `todo` create opens a loop. Declare with `anchorloop_stage` only what the extension cannot observe: `kind` (`quick`, `inline`, `reviewed`, `durable`; `intent`, the task and its outcome in one line; `anchor`, the check command), `verify` (a check not run in bash), `fresh-read`, `friction`, `reflect`, `skip` or `back` (phase, reason), and `close`. Edits, anchor runs, reviews, and spec files are read from evidence; a phase that starts before an earlier one is complete warns once (`read` if you disagree), and `close` refuses only while an open todo lacks `metadata.followup` (a ticket id, `memory`, or `drop — <reason>`).
+Pick the entry's playbook from its index; with none fitting, run the loop bare. `todo` holds real work items only, optionally with `metadata.anchor` (a task's own check) and `metadata.ref` (`<path>#<heading>`). The first `todo` create opens a loop. Declare with `anchorloop_stage` only what the extension cannot observe: `kind` (`quick`, `inline`, `reviewed`, `durable`; `intent`, the task and its outcome in one line; `anchor`, the check command; `reason` when a later call changes the kind or answers the reach an anchor run reports), `verify` (a check not run in bash), `fresh-read`, `friction`, `reflect`, `skip` or `back` (phase, reason), and `close`. Edits, anchor runs, reviews, and spec files are read from evidence; a phase that starts before an earlier one is complete warns once (`read` if you disagree), and `close` refuses only while an open todo lacks `metadata.followup` (a ticket id, `memory`, or `drop — <reason>`).
 
 ## Anchor
 

package/skills/coding/SKILL.md

@@ -9,14 +9,17 @@ Run the loop in [../anchorloop/SKILL.md](../anchorloop/SKILL.md) with one of the
 
 ## Classify
 
-Before the first production edit, declare the change **Inline** or **Durable**:
+Before the first production edit, classify the change by what it reaches, not by how settled the approach feels:
 
-- **Inline:** requirements and approach are clear, impact is bounded, and implementation and verification fit this run; a lasting behavior or public contract can still be Inline when the change is simple. The `intent` on the `kind` call states the observable behavior after the change; the user's source-change request approves it, and approval already given is not asked again.
-- **Durable:** the work needs a persistent design record because of material ambiguity, consequential trade-offs, cross-component coordination, migration risk, or a user-requested spec. Read [MINI-SDD.md](MINI-SDD.md) and create or resume its folder, which keeps no `tasks.md`; Spec waits for the user's approval before any production edit.
+- **Inline:** the change stays inside the files it edits: no export another file uses, no behavior its users are told about, and no behavior the requirement leaves open. The `intent` on the `kind` call states the observable behavior after the change; the user's source-change request approves it, and approval already given is not asked again.
+- **Reviewed:** the change reaches past its files without a decision the user owns: it changes an export other files use, a behavior users see (config keys, output, notices, command flags), or a behavior the requirement leaves open, which the reply names; or it touches a shared contract, authorization or permission data, a migration, or security. Before the first edit, write its premises in the todo's `metadata.premises`: three to five lines on what the change assumes holds, such as where its results land, what names may contain, and how paths are spelled. It needs no spec and no further approval.
+- **Durable:** the work needs a persistent design record because of material ambiguity, a trade-off the user owns, cross-component coordination, migration risk, or a user-requested spec. Read [MINI-SDD.md](MINI-SDD.md) and create or resume its folder, which keeps no `tasks.md`; Spec waits for the user's approval before any production edit.
+
+Re-classify when the reach changes: the user adds scope, an anchor run reports the diff's reach, or the change turns out smaller. Call `kind` with a `reason` naming the kind that now fits, or why the current one still fits. Verified work carries over; an upgrade adds only the new kind's phases, the premises and review for Reviewed, and for Durable the record from decide on, with the code so far as prototype evidence.
 
 ## Anchor
 
-Point the anchor at what the change touches: a one-line edit anchors on the tests that assert that file; a shared code path anchors on its callers' tests. For Inline work, a green anchor plus a read of your own diff completes Verify; report the contract with its observed output in one line. Durable work verifies into `verification.md` as MINI-SDD describes.
+Point the anchor at what the change touches: a one-line edit anchors on the tests that assert that file; a shared code path anchors on its callers' tests and the repository's tree-wide checks, such as lint, config sweeps, ratchets, and changelog checks. For Inline work, a green anchor plus a read of your own diff completes Verify; report the contract with its observed output in one line. Reviewed work adds an independent review whose brief carries the premises and asks the reviewer to test each premise against the code, to sweep each finding's class across the change, and to confirm the tree-wide checks ran. Durable work verifies into `verification.md` as MINI-SDD describes.
 
 ## Playbooks