pi-anchorloop 2.1.0 → 2.2.0

package/README.md

@@ -17,7 +17,7 @@ anchorloop            core loop · principles · playbooks: autonomous-run, paus
 shared           grilling · domain-modeling · human-feedback · agent-terse
 ```
 
-- **`anchorloop`** holds what is true for every task type: restate the task, pick the entry's playbook and copy its steps into `todo`, state a `Reality anchor:` before the first change, work in small increments deleting before adding, verify against the anchor, and record friction notes. The Reflexive pass hands friction notes to `solid-loop`. `PRINCIPLES.md` names the principles playbooks cite and the user can steer with. The lifecycle playbooks cover unattended runs, clean pauses, and picking up a prior run.
+- **`anchorloop`** holds what is true for every task type: restate the task, pick the entry's playbook, keep real work items in `todo` (its first create opens a loop), declare the loop with `anchorloop_stage` (kind, intent, anchor command) before the first change, work in small increments deleting before adding, verify against the anchor, and record friction in the loop book. The Reflexive pass hands reflected friction to `solid-loop`. `PRINCIPLES.md` names the principles playbooks cite and the user can steer with. The lifecycle playbooks cover unattended runs, clean pauses, and picking up a prior run.
 - **Entry skills** each name the anchor for their task type and index their playbooks. A playbook has an ownership line, numbered steps, and a `Reply:` line that sets what the final report contains.
 - **Shared skills** are called by entries: `grilling` for user-owned decisions, `domain-modeling` for terms and ADRs, `human-feedback` for reactions to working output, `agent-terse` for text only agents read: briefs, reports, and agent messages.
 
@@ -25,9 +25,10 @@ shared           grilling · domain-modeling · human-feedback · agent-terse
 
 | File | What it does |
 | --- | --- |
-| `pi/anchor-gate.ts` | Shows one warning per user message when `write` or `edit` runs before the assistant states `Reality anchor:`; the call still goes through. `.md`, `.txt`, and `.html` files, `scratch/`, `docs/specs/`, and temp files outside the project pass silently. Edits made through `bash` are not checked. |
+| `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/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` | Before a run that called `write`, `edit`, or `bash` settles, asks Jev (TypeSafe's typed-decision model, through pi's classifier registry) whether the final reply shows the request met, which review tier it needs, and its quality. Jev also says whether the reply is a checkpoint that hands work back to the user; a reply that only acknowledges, reports progress, or waits gets no reminder. At a checkpoint, when quality < 1.5 or the tier is `full`, it adds one visible advisory message and one continuation per run; the agent may disagree and finish. When only done < 0.25, the message is shown without a continuation. The request is the latest message the user typed; messages extensions send (intercom, monitor wakes) do not replace it. A run such a message starts is sent with `trigger: wake` and that message, and is judged on what it asks; its checkpoint question adds that a reply to a routine check the wake asked for (status, health, load, progress of running work) is not a checkpoint. A run that called `MonitorCreate`, `LoopCreate`, `goal_wait`, or a `subagent` tool is waiting on a wake and is not judged. Only the request, the trigger, the wake message, and the final reply are sent. Without a TypeSafe key it records `unknown` and does nothing. 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. |
+| `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. |
 | `pi/validate-tool-use.ts` | After each `write` or `edit`, validates the file in-process (`pi/support/validators.ts`, a port of `hooks/validators/`) and appends suggestions for `SKILL.md`, instruction files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `rules/`), and `docs/specs/` artifacts. Needs no Python; the Python validators in `hooks/` remain for `validate_all.py` and the parity test. |
 | `pi/ttsr.ts` | A port of oh-my-pi's Time Traveling Stream Rules. A Markdown rule in `~/.pi/agent/rules/` or `<project>/.pi/rules/` whose frontmatter has a `condition` regex is watched during the run. A match in streamed assistant text aborts the response, drops it, and retries with the rule injected; a match in tool arguments (the command for `bash`, the new text for `write` and `edit`) blocks the call with the rule as its reason. Frontmatter fields follow oh-my-pi: `condition`, `scope` (`text`, `thinking`, `tool`, `tool:bash`, `tool:edit(*.ts)`), `globs`, and `interruptMode` (`always`, `prose-only`, `tool-only`, `never`), plus `repeatMode` (`once` or `after-gap`) and `repeatGap`. A rule fires once per session by default. `astCondition`, `question`, and `agents` are not supported; a rule that uses them is skipped and reported. `/ttsr` lists the loaded rules. |
 

package/README.zh-TW.md

@@ -17,7 +17,7 @@ anchorloop            核心循環 · 原則 · playbook：autonomous-run、paus
 共用             grilling · domain-modeling · human-feedback · agent-terse
 ```
 
-- **`anchorloop`** 放每一種任務都成立的做法：重述任務、選入口的 playbook 並把步驟抄進 `todo`、第一筆修改前寫出 `Reality anchor:`、以小步前進且先刪後加、依 anchor 驗證，並記下 friction note。Reflexive pass 會把 friction note 交給 `solid-loop`。`PRINCIPLES.md` 列出 playbook 引用的原則，使用者也可以用這些名稱中途修正方向。三本生命週期 playbook 處理無人看管的執行、乾淨的暫停，以及接手前一輪的工作。
+- **`anchorloop`** 放每一種任務都成立的做法：重述任務、選入口的 playbook、只把真正的工作項目放進 `todo`（第一次 create 會開啟一個 loop）、第一筆修改前用 `anchorloop_stage` 宣告 loop（種類、intent、anchor 指令）、以小步前進且先刪後加、依 anchor 驗證，並把 friction 記在 loop book。Reflexive pass 會把已 reflect 的 friction 交給 `solid-loop`。`PRINCIPLES.md` 列出 playbook 引用的原則，使用者也可以用這些名稱中途修正方向。三本生命週期 playbook 處理無人看管的執行、乾淨的暫停，以及接手前一輪的工作。
 - **入口 skill** 各自寫出這類任務的 anchor，並列出自己的 playbook。每本 playbook 先用一句話說明它負責什麼，接著是編號步驟，最後一行 `Reply:` 規定回報要包含什麼。
 - **共用 skill** 由入口呼叫：`grilling` 處理使用者要做的決定，`domain-modeling` 處理術語和 ADR，`human-feedback` 處理對成品的反應，`agent-terse` 處理只給 agent 讀的文字：任務 brief、回報、agent 之間的訊息。
 
@@ -25,9 +25,10 @@ anchorloop            核心循環 · 原則 · playbook：autonomous-run、paus
 
 | 檔案 | 作用 |
 | --- | --- |
-| `pi/anchor-gate.ts` | 使用者最新一則訊息之後，assistant 還沒寫出 `Reality anchor:` 就執行 `write` 或 `edit` 時，每則訊息顯示一次警告，但不擋下呼叫。`.md`、`.txt`、`.html` 檔、`scratch/`、`docs/specs/` 和專案外的暫存檔不警告。透過 `bash` 改檔不在檢查範圍內。 |
+| `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/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` | 呼叫過 `write`、`edit` 或 `bash` 的執行結束前，透過 pi 的 classifier registry 問 Jev（TypeSafe 的型別化決策模型）：最後的回覆有沒有證明需求已達成、需要哪一級 review、品質如何。Jev 也會判斷這則回覆是不是提醒點，也就是把工作交回給使用者的地方；只是確認收到、回報進度或等待中的回覆不提醒。在提醒點上，quality < 1.5 或 review 是 `full` 時，加一則看得到的提醒並讓 agent 多跑一輪，每輪最多一次；agent 可以不同意，直接結束。只有 done < 0.25 時，只顯示提醒，不多跑一輪。需求是使用者最新打的訊息；extension 送進來的訊息（intercom、monitor 喚醒）不會取代它。由這類訊息開始的那一輪，會連同 `trigger: wake` 和那則訊息一起送出，依那則訊息要求的事評估；這時的提醒點問題會多說明：回覆喚醒訊息要求的例行檢查（狀態、健康、負載、還在跑的工作進度）不算提醒點。呼叫過 `MonitorCreate`、`LoopCreate`、`goal_wait` 或 `subagent` 類工具的執行是在等喚醒，不評估。只送出需求、trigger、喚醒訊息和最後的回覆。沒有 TypeSafe key 時記為 `unknown`，不做任何事。在 subagent session 裡（pi-herdr-agents 的 `PI_SUBAGENT_ID`，或 pi-subagents 的 `PI_SUBAGENT_CHILD`）完全不啟用，結果交給派出它的 agent 判斷。 |
+| `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 判斷結果。 |
 | `pi/validate-tool-use.ts` | 每次 `write` 或 `edit` 後在行程內驗證該檔（`pi/support/validators.ts`，移植自 `hooks/validators/`），替 `SKILL.md`、指令檔（`AGENTS.md`、`CLAUDE.md`、`GEMINI.md`、`rules/`）和 `docs/specs/` 產出物附上建議。不需要 Python；`hooks/` 的 Python 驗證器仍供 `validate_all.py` 和對照測試使用。 |
 | `pi/ttsr.ts` | 移植自 oh-my-pi 的 Time Traveling Stream Rules。`~/.pi/agent/rules/` 或 `<專案>/.pi/rules/` 裡 frontmatter 帶有 `condition` regex 的 Markdown 規則，會在執行過程中被監看。assistant 串流文字命中時，中斷回應、丟棄那段輸出，並注入規則後重試；工具參數命中時（`bash` 看指令，`write`／`edit` 看新寫入的文字），直接擋下呼叫，以規則內容作為理由。frontmatter 欄位沿用 oh-my-pi：`condition`、`scope`（`text`、`thinking`、`tool`、`tool:bash`、`tool:edit(*.ts)`）、`globs`、`interruptMode`（`always`、`prose-only`、`tool-only`、`never`），另加 `repeatMode`（`once` 或 `after-gap`）與 `repeatGap`。預設每條規則每個 session 只觸發一次。不支援 `astCondition`、`question`、`agents`，用到的規則會被跳過並回報。`/ttsr` 列出已載入的規則。 |
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-anchorloop",
-  "version": "2.1.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 (anchor gate, decision trail tool, Jev second thought, skill validator, stream rules).",
+  "version": "2.2.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",
   "type": "module",
@@ -32,6 +32,7 @@
     "extensions": [
       "./pi/validate-tool-use.ts",
       "./pi/ttsr.ts",
+      "./pi/book.ts",
       "./pi/anchor-gate.ts",
       "./pi/decision-tool.ts",
       "./pi/second-thought.ts"

package/pi/anchor-gate.ts

@@ -1,84 +1,28 @@
 /**
- * pi extension: warns once when write or edit runs before the assistant has
- * stated a `Reality anchor:` line since the user's latest message.
+ * pi extension: inside an open loop, warns once per jump when write or edit starts the `act` phase while an
+ * earlier phase of the loop kind is incomplete: no anchor, or in a durable loop a decision, spec, read,
+ * approval, or design still missing. The phase machine in support/phases.ts decides what is missing; the
+ * warning names it and the `skip` escape. Outside a loop, or in a `quick` one, it stays silent.
  */
 
-import { existsSync, realpathSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-
-const ANCHOR = /Reality anchor:/;
-const EXEMPT_IN_PROJECT = ["scratch", "docs/specs"];
-const EXEMPT_ROOTS = [tmpdir(), "/tmp", "/var/folders"];
-const EXEMPT_EXTENSIONS = [".md", ".txt", ".html", ".htm"];
-
-export const WARNING =
-	"anchorloop anchor gate: a change ran before the reply stated " +
-	"`Reality anchor: <the exact check that observes the result, and its checkpoint>`.";
-
-type Block = { type: string; text?: string };
-type Message = { role?: string; content?: string | Block[] };
-
-function statesAnchor(message: Message): boolean {
-	if (message.role !== "assistant" || !Array.isArray(message.content)) return false;
-	return message.content.some((block) => block.type === "text" && ANCHOR.test(block.text ?? ""));
-}
-
-/** The real path of `path`, resolving symlinks such as /var → /private/var through its nearest existing parent. */
-function real(path: string): string {
-	if (existsSync(path)) return realpathSync(path);
-	const parent = dirname(path);
-	return parent === path ? path : join(real(parent), basename(path));
-}
-
-function within(root: string, target: string): boolean {
-	const rel = relative(root, target);
-	return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
-}
-
-/** Markdown, text, and HTML files, scratch and spec folders in the project, and temp files outside it; a project that lives in a temp dir is still gated. */
-export function exempt(filePath: string, cwd: string): boolean {
-	if (EXEMPT_EXTENSIONS.includes(extname(filePath).toLowerCase())) return true;
-	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));
-	return EXEMPT_ROOTS.some((tmp) => within(real(tmp), target));
-}
+import { currentKind, guarded, openLoop, replayTodos } from "./support/book.ts";
+import { JumpMemory, computePhases, exempt, incompleteBefore, jumpLine } from "./support/phases.ts";
 
 export default function (pi: ExtensionAPI) {
-	let anchored = false;
-	let warned = false;
-
-	pi.on("session_start", (_event, ctx) => {
-		anchored = false;
-		const branch = ctx.sessionManager.getBranch() as Array<{ type: string; message?: Message }>;
-		for (let i = branch.length - 1; i >= 0; i--) {
-			const message = branch[i].type === "message" ? branch[i].message : undefined;
-			if (!message) continue;
-			if (message.role === "user") return;
-			if (statesAnchor(message)) {
-				anchored = true;
-				return;
-			}
-		}
-	});
-
-	// User messages that steer a running loop end here too, so the gate closes for each of them.
-	pi.on("message_end", (event) => {
-		const message = event.message as Message;
-		if (message.role === "user") {
-			anchored = false;
-			warned = false;
-		}
-		else if (statesAnchor(message)) anchored = true;
-	});
-
-	pi.on("tool_call", (event, ctx) => {
-		if (anchored || warned || (event.toolName !== "write" && event.toolName !== "edit")) return;
-		const filePath = (event.input as { path?: unknown }).path;
-		if (typeof filePath !== "string" || exempt(filePath, ctx.cwd)) return;
-		warned = true;
-		ctx.ui.notify(WARNING, "warning");
-	});
+	const jumps = new JumpMemory();
+
+	pi.on(
+		"tool_call",
+		guarded((event, ctx) => {
+			if (event.toolName !== "write" && event.toolName !== "edit") return;
+			const filePath = (event.input as { path?: unknown }).path;
+			if (typeof filePath !== "string") return;
+			const book = openLoop(ctx);
+			if (!book || exempt(filePath, ctx.cwd) || currentKind(book.entries) === "quick") return;
+			const phases = computePhases(book, { cwd: ctx.cwd, todos: replayTodos(ctx.sessionManager.getBranch()) });
+			const missing = incompleteBefore(phases, "act");
+			if (jumps.fresh(String(book.header.id), "act", missing.map((status) => status.name))) ctx.ui.notify(jumpLine("act", missing), "warning");
+		}),
+	);
 }