pi-anchorloop 2.4.1 → 2.7.0

package/README.md

@@ -25,12 +25,12 @@ 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; 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 (an anchor that passed, failed, and passed again records its own friction entry: the rerun command and the failed run's key line, at most 120 characters and never a stack trace, still waiting for a `reflect`), 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: …`. The pi footer shows `anchorloop <kind> · <current> ✓ → <next>`, with the friction still to reflect, after every tool call and on `session_start`, and clears when the loop closes. 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>`. 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. |
+| `pi/book.ts` | The loop book. The first `todo` create opens an `inline` loop (intent from the first todo's subject, anchor from a `Reality anchor:` line or the todo's `metadata.anchor`), and a `kind` call opens or changes one; 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` (to choose `quick`, `reviewed`, or `durable`, with an intent and the anchor command; changing a kind the agent chose takes 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 (an anchor that passed, failed, and passed again records its own friction entry, already reflected as `resolved`: the rerun command and the failed run's key line, at most 120 characters and never a stack trace; the agent is told nothing), 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 widget below the editor shows `⚓ <kind> · <current> ✓ → <next>`, with `· N friction` while friction waits for a `reflect`, after every tool call, on `session_start`, and when a `Reality anchor:` line is stated, and clears when the loop closes. 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; 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). A child is linked only through [pi-herdr-agents](https://github.com/wayne930242/pi-herdr-agents) (`PI_SUBAGENT_ID` in the child, `details.id` on the parent's `subagent` result; pi itself has no subagents): a linked child's edits are the parent's act, and its anchor runs, recorded as `check`, carry the working-state tree of each repo it works in (tracked and untracked files, ignored files and `scratch/` left out). When a parent's `git merge`, `cherry-pick` or `pull` succeeds, or a subagent result returns, and the parent's working-state trees are exactly the trees of a child's latest run of the same anchor (a leading `cd` into a repo root aside), and that run passed, the parent records it as its own verify (`adopted`): a fast-forward of a worker's branch, or a child that worked in the parent's checkout, needs no second run, while a merge onto a base that moved, a parent edit or repo the child never saw, or a file the child ran with but did not commit does; `session_start` sweeps books whose session is gone or that have not changed in 7 days. `close` answers `closed (landed). Clear the todo list.`, adding only the phases not shown complete and the unreflected friction, 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, appends one warning line to the edit's tool result (where the agent reads it) 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 for forks, pivots, and blockers (completed units come from `git log`), 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, the open todos by id and subject, 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 advisory is `next: <phase> (<missing>)` plus Jev's concerns, with no scores. It is sent only when Jev has a concern, todos are open without a followup, or the run continues, and stays silent when Jev agrees with nothing to add (the verdict is still recorded in the session); at close it carries concerns only. Away from close it also names the loop's open todos that have no valid `metadata.followup` (the first three, subjects cut to 60 characters, then `+N more`) and asks the agent to continue each, complete it, or set that followup. The run continues once, when Jev agrees to advance and the next phase is a verify, review, or fix, or when such todos are open and Jev's move is not `ask-user` (then the advisory tells the agent to ask the user instead); an advisory with the same next phase, concerns, and open todo ids as the last one is not repeated, and a `full` rating after a clean review that follows the last change is not a concern. 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` (at most three red-line advisories per edit), 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`. Each injected rule arrives as `<rule name="…">body</rule>`. 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. |
 
 ## Install
 

package/README.zh-TW.md

@@ -25,12 +25,12 @@ 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 指令；之後要改種類，必須附 `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（anchor 通過後失敗、又再通過時，extension 會自己記一筆 friction：重跑的指令，加上失敗那次最關鍵的一行輸出，最多 120 字元，不放 stack trace；這筆仍要 `reflect` 分類）、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 <目前> ✓ → <下一個>（缺：…）· 已跳過：…`。pi 的 footer 會顯示 `anchorloop <種類> · <目前> ✓ → <下一個>`，以及還沒 reflect 的 friction 數；每次工具呼叫後和 `session_start` 時更新，loop 結案後清掉。`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 → <階段>` 開頭。只有 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` 列出已載入的規則。 |
+| `pi/book.ts` | Loop book。第一次 `todo` create 會以 `inline` 開啟 loop（intent 取第一個 todo 的標題，anchor 取 `Reality anchor:` 這一行或該 todo 的 `metadata.anchor`），`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`、`reviewed` 或 `durable`，附 intent 和 anchor 指令；改掉 agent 自己選的種類時，必須附 `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（anchor 通過後失敗、又再通過時，extension 會自己記一筆 friction，並直接 reflect 為 `resolved`：重跑的指令，加上失敗那次最關鍵的一行輸出，最多 120 字元，不放 stack trace；不會通知 agent）、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 <目前> ✓ → <下一個>（缺：…）· 已跳過：…`。編輯器下方的 widget 會顯示 `⚓ <種類> · <目前> ✓ → <下一個>`，還有 friction 等著 `reflect` 時附 `· N friction`；每次工具呼叫後、`session_start` 時，以及 agent 寫出 `Reality anchor:` 這一行時更新，loop 結案後清掉。`quick` 或 `inline` loop 跑 anchor 或宣告 verify 時，也會量 diff 的影響範圍：原始碼檔案（不含測試、lockfile、spec 與文字檔）、它們所在的頂層目錄，以及跟原始碼一起改的 README、changelog 或 `*.schema.json`。repo 加入 loop 時就已經改過的檔案，要等內容再變動才算；repo 根目錄的檔案只算檔案數，不算一個目錄。達到 3 個原始碼檔案、2 個目錄或 1 個這類檔案時，結果會附一行請 agent 重新分類；verify 要等到以 `reason` 呼叫 `kind`、回應每一個跨過的門檻才算完成，之後再跨過新的門檻會再問一次。前一個階段還沒完成就開始下一個階段，會用一行警告一次；證據改變或用 `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）。子代理只透過 [pi-herdr-agents](https://github.com/wayne930242/pi-herdr-agents) 關聯（子行程的 `PI_SUBAGENT_ID`、父 session `subagent` 結果的 `details.id`；pi 本身沒有 subagent）：關聯的子代理，其改動算父 loop 的 act；其 anchor 執行記為 `check`，並附上它所在各 repo 的工作狀態 tree（含已追蹤與未追蹤檔案，不含 ignored 檔案與 `scratch/`）。父 session 的 `git merge`、`cherry-pick`、`pull` 成功時，或收到子代理結果時，若父 session 的工作狀態 tree 正好等於子代理最近一次同一 anchor 執行（忽略開頭切到 repo 根目錄的 `cd`）的 tree，且那次通過，就把它記為父 loop 自己的 verify（`adopted`）：fast-forward 合入 worker 分支、或子代理直接在父 checkout 裡工作，都不必再跑一次；合到已前進的 base、父 session 有子代理沒看過的改動或 repo、或子代理跑測試時有沒 commit 的檔案，則要自己跑；`session_start` 會清掉 session 已不存在或 7 天沒有更新的 book。`close` 回覆 `closed (landed). Clear the todo list.`，只多列沒有完成的階段和還沒 reflect 的 friction；它不會因為階段或 friction 而拒絕，只在還有 pending 或 in-progress 的 todo 沒有 `metadata.followup`（票號、`memory` 或 `drop — <原因>`）時拒絕。 |
+| `pi/anchor-gate.ts` | 只在開啟的 loop 內：`write` 或 `edit` 開始 `act` 階段、而這種 loop 前面的階段還沒完成時，把一行警告附在該次編輯的 tool result 後面（agent 在那裡讀到它）：沒有 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 決策軌跡（記岔路、轉向與卡點；完成的工作單元看 `git log`），每筆只佔一行，用試算表開啟也安全；接手別人的軌跡時寫一筆 `start`。 |
+| `pi/second-thought.ts` | 只在開啟的 loop 內：一次執行結束且 book 自上次判斷後多了條目時，以及宣告 `close` 時，透過 pi 的 classifier registry 請 Jev（TypeSafe 的型別化決策模型）複核階段機。下一個階段由程式從 book 算出；Jev 看到種類、intent、anchor、diff 摘要（≤1200 字元）、`phase`（目前、下一個、缺什麼）、verify 狀態、未完成 todo（id 與標題）、任務清單和 friction（子 agent 的以它的名字列出），只判斷要 `advance`、退回（`back`）還是 `ask-user`，另外還問 `done`、還需要哪一級 review 與品質；階段是否完成只由程式依證據判定。提醒是 `next: <階段>（<缺什麼>）` 加上 Jev 的疑慮，不附分數；只在 Jev 有疑慮、有 todo 未完成而沒有 followup、或這次會讓 agent 多跑一輪時才送出，Jev 同意且沒有補充時保持安靜（判斷結果仍記在 session 裡）；結案時只附疑慮。離開 close 時，提醒也會點名 loop 中還沒有有效 `metadata.followup` 的未完成 todo（前三個，標題截成 60 字元，其餘以 `+N more` 帶過），請 agent 逐一繼續、完成，或設定該 followup。Jev 同意前進、而下一個階段是 verify、review 或 fix，或有這類 todo 未完成且 Jev 的判斷不是 `ask-user`（此時提醒改請 agent 去問使用者）時，才讓 agent 多跑一輪；下一個階段、疑慮和未完成 todo 的 id 都與上一則相同的提醒不重複；最後一次修改之後已有無 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`。注入的規則以 `<rule name="…">內容</rule>` 送出。預設每條規則每個 session 只觸發一次。不支援 `astCondition`、`question`、`agents`，用到的規則會被跳過並回報。`/ttsr` 列出已載入的規則。 |
 
 ## 安裝
 

package/hooks/validate_tool_use.py

@@ -72,7 +72,7 @@ def main() -> None:
                 rel = target_path
 
             lines = "\n".join(f"  - {w}" for w in warnings)
-            msg = f"⚠ [anchorloop] Validation suggestions for {rel}:\n{lines}"
+            msg = f"validator {rel}:\n{lines}"
             print(json.dumps({"additionalContext": msg}))
         else:
             print(json.dumps({}))

package/hooks/validators/constants.py

@@ -29,6 +29,7 @@ RED_LINE_MARKERS = (
     r"\b(never|must not|do not|don't|forbidden|barred|prohibited|avoid)\b"
     r"|不要|禁止|不得|不准|嚴禁"
 )
+MAX_ADVISORIES = 3
 RED_LINE_MIN_BUDGET = 3
 RED_LINE_DENSITY = 0.10
 # Emphatic capitals are matched case-sensitively and need a reason on the same or next line.

package/hooks/validators/durable_validator.py

@@ -8,7 +8,7 @@ from .utils import find_defensive_phrases
 
 
 def check_decision_md(path: Path) -> list[str]:
-    """Check decision.md for required structure and pre-flight skill/rule readiness."""
+    """Check decision.md for its decision table."""
     warnings: list[str] = []
     text = path.read_text(encoding="utf-8")
 
@@ -16,18 +16,11 @@ def check_decision_md(path: Path) -> list[str]:
     if not re.search(r"\|\s*Question\s*\|\s*Answer\s*\|\s*Basis\s*\|\s*Status\s*\|", text, re.IGNORECASE):
         warnings.append("decision.md should include a Question | Answer | Basis | Status table (Status: grounded, confirmed, or open).")
 
-    # Check for pre-flight readiness (core rules)
-    lower = text.lower()
-    if "rule" not in lower and "readiness" not in lower and "prerequisite" not in lower and "core" not in lower:
-        warnings.append(
-            "confirm core rules readiness before implementation; note readiness in decision.md."
-        )
-
     return warnings
 
 
 def check_spec_md(path: Path) -> list[str]:
-    """Check spec.md for approval status and reality anchor definition."""
+    """Check spec.md for its approval status."""
     warnings: list[str] = []
     text = path.read_text(encoding="utf-8")
 
@@ -35,10 +28,6 @@ def check_spec_md(path: Path) -> list[str]:
     if not re.search(r"Status:\s*(proposed|approved)", text, re.IGNORECASE):
         warnings.append("spec.md must declare 'Status: proposed' or 'Status: approved' at the top.")
 
-    # Reality anchor declaration
-    if "reality anchor" not in text.lower() and "anchor" not in text.lower():
-        warnings.append("spec.md should name the chosen reality anchor and its checkpoint.")
-
     return warnings
 
 
@@ -62,16 +51,14 @@ def check_verification_md(path: Path) -> list[str]:
         ]
         if invalid_results:
             warnings.append(
-                f"invalid verification Result values found: {', '.join(set(invalid_results))}. "
-                "Result must be one of: pass, fail, unknown."
+                f"invalid verification Result values found: {', '.join(set(invalid_results))} (use pass, fail, unknown)"
             )
 
     # 2. Review of newly added rules or skills (tuning vs defensive vocabulary)
     found_defensive = find_defensive_phrases(text, DEFENSIVE_PATTERNS)
     if found_defensive:
         warnings.append(
-            f"detected defensive wording in verification/review: {', '.join(found_defensive)}. "
-            "Reviews of new rules and skills must focus on adjustment and tuning, not adding defensive red lines."
+            f"detected defensive wording in verification/review: {', '.join(found_defensive)}"
         )
 
     return warnings

package/hooks/validators/rule_validator.py

@@ -18,16 +18,14 @@ def check_rules_file(path: Path) -> list[str]:
     found_patterns = find_defensive_phrases(text, DEFENSIVE_PATTERNS)
     if found_patterns:
         warnings.append(
-            f"detected defensive wording: {', '.join(found_patterns)}. "
-            "State desired behavior directly; modern models do not need excessive red lines."
+            f"detected defensive wording: {', '.join(found_patterns)}"
         )
 
     # 2. Rule proliferation / bloat check
     lines = [line.strip() for line in text.splitlines() if line.strip() and not line.strip().startswith("#")]
     if len(lines) > 200:
         warnings.append(
-            f"rule file has {len(lines)} non-empty lines. Consider consolidating into higher-level principles "
-            "or separating into specialized modules rather than accumulating micro-rules."
+            f"rule file has {len(lines)} non-empty lines (over 200)"
         )
 
     # 3. Check for Simplified Chinese common distinctive characters
@@ -36,7 +34,7 @@ def check_rules_file(path: Path) -> list[str]:
     found_sc = [c for c in simplified_chinese_chars if c in text]
     if found_sc:
         warnings.append(
-            f"possible Simplified Chinese detected ({''.join(found_sc[:5])}). Always use Traditional Chinese."
+            f"possible Simplified Chinese detected ({''.join(found_sc[:5])})"
         )
 
     return warnings

package/hooks/validators/skill_validator.py

@@ -6,6 +6,7 @@ from pathlib import Path
 
 from .constants import (
     DEFENSIVE_PATTERNS,
+    MAX_ADVISORIES,
     EMPHATIC_WORDS,
     REASON_WORDS,
     RED_LINE_DENSITY,
@@ -63,8 +64,7 @@ def check_skill_md(path: Path) -> list[str]:
         has_references = (skill_dir / "references").is_dir()
         if not has_references:
             warnings.append(
-                f"skill has {len(lines)} lines (exceeds recommended {SKILL_MAX_RECOMMENDED_LINES}). "
-                "Move detailed guidelines or templates to references/ to keep SKILL.md streamlined."
+                f"skill has {len(lines)} lines (over {SKILL_MAX_RECOMMENDED_LINES}) and no references/"
             )
 
     # 3. Broken markdown links, followed through every Markdown file SKILL.md reaches
@@ -98,8 +98,7 @@ def check_skill_md(path: Path) -> list[str]:
     found_patterns = find_defensive_phrases(text, DEFENSIVE_PATTERNS)
     if found_patterns:
         warnings.append(
-            f"detected defensive anti-pattern(s): {', '.join(found_patterns)}. "
-            "State expected behavior directly rather than constructing defensive red lines."
+            f"detected defensive anti-pattern(s): {', '.join(found_patterns)}"
         )
 
     return warnings
@@ -120,10 +119,7 @@ def check_skill_advisories(path: Path) -> list[str]:
     markers = len(re.findall(RED_LINE_MARKERS, body, re.IGNORECASE))
     budget = max(RED_LINE_MIN_BUDGET, int(sum(1 for line in lines if line.strip()) * RED_LINE_DENSITY))
     if markers > budget:
-        advisories.append(
-            f"{markers} red-line markers exceed the budget of {budget}. Keep a red line only when an "
-            "observed failure backs it, and delete the rest."
-        )
+        advisories.append(f"{markers} red-line markers exceed the budget of {budget}")
 
     # 2. Reasoned: an emphatic word carries its reason on the same or next line.
     # 3. Once: an emphatic word is spent a single time.
@@ -133,12 +129,9 @@ def check_skill_advisories(path: Path) -> list[str]:
             seen[word] += 1
             window = " ".join(lines[number - 1 : number + 1])
             if not re.search(REASON_WORDS, window, re.IGNORECASE):
-                advisories.append(
-                    f"line {number}: emphatic '{word}' has no reason beside it. "
-                    "State the consequence, or drop the emphasis."
-                )
+                advisories.append(f"line {number}: emphatic '{word}' has no reason beside it")
     for word, count in seen.items():
         if count > 1:
-            advisories.append(f"emphatic '{word}' appears {count} times. Spend emphasis once, on the rule that causes real damage.")
+            advisories.append(f"emphatic '{word}' appears {count} times")
 
-    return advisories
+    return advisories[:MAX_ADVISORIES]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-anchorloop",
-  "version": "2.4.1",
+  "version": "2.7.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/anchor-gate.ts

@@ -2,7 +2,8 @@
  * 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.
+ * warning is one line appended to the edit's tool result, which is the only place the agent reads it.
+ * Outside a loop, or in a `quick` one, it stays silent.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -11,6 +12,8 @@ import { JumpMemory, computePhases, exempt, incompleteBefore, jumpLine } from ".
 
 export default function (pi: ExtensionAPI) {
 	const jumps = new JumpMemory();
+	// The warning each write or edit call earned, held until its result arrives.
+	const pending = new Map<string, string>();
 
 	pi.on(
 		"tool_call",
@@ -22,7 +25,17 @@ export default function (pi: ExtensionAPI) {
 			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");
+			if (jumps.fresh(String(book.header.id), "act", missing.map((status) => status.name))) pending.set(event.toolCallId, jumpLine("act", missing));
+		}),
+	);
+
+	pi.on(
+		"tool_result",
+		guarded((event) => {
+			const line = pending.get(event.toolCallId);
+			if (line === undefined) return;
+			pending.delete(event.toolCallId);
+			return { content: [...event.content, { type: "text" as const, text: line }] };
 		}),
 	);
 }