@gavin-hu/my-pi-agent 0.18.0 → 0.19.0

package/{extensions/plan/README.md → docs/extensions/plan.md}

@@ -6,13 +6,70 @@ but the only thing it may write is the plan file itself. The plan is saved under
 the agent directory; the user reviews that file, and it is the artifact the model
 executes.
 
+## Capabilities
+
+Status records what a reader can rely on: **Shipped** is in a tagged release, **Unreleased** is complete in the current tree but not yet tagged, and **Partial** has one released part and one unreleased part. Rows are ordered by user value, highest first.
+
+### Planning lifecycle
+
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| Read-only planning | `enter_plan_mode`, `/plan`, `Ctrl+Alt+P`, `--plan` | The session keeps only its readers, so the model investigates and proposes without touching the tree. | Shipped |
+| Confirmed model entry | `enter_plan_mode` | The model asks before it takes write access away, and the user answers first. | Shipped |
+| Read-only git shell | `bash` with the read-only git allowlist | Plan mode can inspect `git status`, `diff`, `log`, and `show`; pipes, redirects, and non-git commands are refused. | Shipped |
+| Read-only delegation | `subagent` with forced `readOnly: true` | A delegated agent can read and search but cannot write, edit, or run a shell while the plan is being researched. | Shipped |
+| Absolute-path guard | `path-guard.ts` | A path outside the project is refused unless it is a known plan-safe reader, so planning cannot write through an absolute path. | Shipped |
+| One writable artifact | `write_plan` | The plan lands as markdown under the agent directory, one store per repository, shared by its worktrees. | Shipped |
+| Approval gate | `exit_plan_mode` | The plan is read back and presented; nothing is written until the user approves it. | Shipped |
+| Session goal at approval | `goal` at approval | A `planning` goal is promoted to the plan's objective, and a session with none gets it, without a second dialog; an active goal is left alone. | Shipped |
+| Steps as todos | `exit_plan_mode` | Approval seeds the plan's steps into the todo list, with the verification section as the last item. | Shipped |
+| Plan kept current | `set_plan_steps` | Ticking a step rewrites its checkbox in the file and its todo item in one call. | Shipped |
+| Stale-step protection | `expected` in `set_plan_steps` | A step whose number moved, is out of range, or no longer matches its text refuses the whole batch instead of ticking the wrong line. | Shipped |
+| Cancel without a plan | `cancel_plan_mode`, `/plan cancel` | Write access returns, and no todo items or goal are recorded. | Shipped |
+| Plans index | `/plan list` | Every saved plan with its title, modified time, and step progress, newest first, under a header naming the store's size and its oldest plan. | Shipped |
+| Plan-store migration | `<repo>/.pi/plans` to the agent-dir store | A store left by an older version is moved in once, with a notice, so worktrees and main see the same index. | Shipped |
+| Instruction-file bootstrap | `/skill:init` | The packaged `init` skill plans and gates a project's `AGENTS.md`, writing only after approval. | Shipped |
+| Branch-following mode | the `plan-mode` session entry | `/resume` and `/tree` restore the mode and its tool set for the branch they land on. | Shipped |
+
+### Review
+
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| Review screen | `exit_plan_mode` | A scrollable, themed plan with approve, refine, keep, browser, and exit in the footer. | Shipped |
+| Browser page | `/plan review`, `w` on the review screen | The plan opens in a local browser as a reading-first page with live section and step progress. | Shipped |
+| Approval in the browser | the `/plan review` page's **Approve & run** | The plan is approved without returning to the terminal, and the steps are seeded. | Shipped |
+| Inline comments | the page's `+ Comment`, **Save feedback** | Comments are saved into the plan file as `> [!REVIEW]` lines and returned to the model. | Shipped |
+| Live page | the page's `events` stream, the plan-file poll | An edit made elsewhere repaints every open page without a reload. | Shipped |
+| Changed sections | the `exit_plan_mode` review screen, the `/plan review` outline | After a refinement, only the sections that changed are marked. | Shipped |
+| Section navigation | the review screen, `n`/`p` | The screen names the section you are in and jumps between headings. | Shipped |
+| Remote review | `exit_plan_mode` on a WeChat turn | The plan file is sent, then one compact prompt to approve, keep planning, or exit. | Shipped |
+
+### Collaboration
+
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| Shared review | `/plan share`, **Share** | A reviewer link, with a QR a phone can scan, opens the same plan from another machine on this Wi-Fi. | Shipped |
+| One link per teammate | **New link**, **Revoke**, `/plan share stop` | Each teammate holds a link of their own, and one is revoked without disturbing the rest. | Shipped |
+| Two roles | the owner's `token`, a reviewer's link | Only the owner saves, approves, cancels, and manages links; a reviewer reads and comments. | Shipped |
+| Signed comments | the page's `name` control | A reviewer's name binds to her link on its first post, so her notes are hers and the file records who wrote them. | Shipped |
+
+## Quickstart
+
 ```bash
 pi --extension ./extensions/plan   # load just this extension
 pi -e .                            # load the whole @gavin-hu/my-pi-agent package
-pi --plan                          # start in plan mode
+pi install ./                      # install the package for a user
+```
+
+```text
+/plan                                       # toggle plan mode
+/plan add rate limiting to the public API   # enter plan mode and send the task
 ```
 
-## Tool rendering
+The model calls `enter_plan_mode` before a non-trivial task; `/plan` and
+`Ctrl+Alt+P` are the user's own switch.
+
+## Tools
 
 How the `write_plan` and `exit_plan_mode` calls and their results look in the transcript — the call line as a headline and the body indented under it:
 
@@ -20,207 +77,158 @@ How the `write_plan` and `exit_plan_mode` calls and their results look in the tr
 
 <img src="../../assets/tools/exit_plan_mode.png" alt="The exit_plan_mode tool's call and result: the call line and an indented body with the approval line and the approved plan preview" width="100%">
 
-## What it does
-
-- **Read-only gating, with one exception.** Tools that are not read-only are
-  removed from the active set or blocked. `write` and `edit` are hidden, raw
-  shell is limited to read-only git commands through `bash` (chained with
-  `&&`/`;`), `powershell` is blocked outright, and other mutating tools (worktree
-  mutations, MCP tools) are blocked until you exit plan mode. `subagent` stays
-  active but is forced read-only. The only permitted write is the plan control
-  tool `write_plan`, which can only create or overwrite markdown plan files
-  directly inside the plans directory — never dotfiles and never through a
-  symlink. Classification defaults to *deny* and is driven by the shared
-  [`lib/policy.ts`](../../lib/policy.ts), so unknown tools are safe by default
-  and the MCP `readOnlyHint` is the only thing that opens one up. A refused
-  shell command explains the fix: the working directory is already the project
-  root (so `cd` is unnecessary), and files belong to the `read`, `grep`, `find`,
-  and `ls` tools.
-- **Model entry point.** The model can call `enter_plan_mode` to ask for plan
-  mode before a non-trivial task; the user confirms.
-- **AGENTS.md bootstrap.** The packaged `init` skill (`/skill:init`) enters plan
-  mode, reconnoiters the repository, runs one built-in interview of at
-  most four questions, creates or updates `AGENTS.md`, gates the draft through a
-  quality checklist, and writes only after plan approval. It supports existing and
-  empty repositories, and falls back to evidence with recorded assumptions when
-  the interview is unavailable or cancelled; it never invents commands.
-- **Plan files, shared by the whole repository.** The model saves the plan with
-  `write_plan`; the file lands in
-  `<agent-dir>/plans/<repo-key>/<YYYY-MM-DD-HHmm>-<slug>.md`, keyed by the
-  repository's common git directory, so a plan approved in one worktree is the
-  same plan from the main checkout and from every other session. Outside a
-  repository the store is `<agent-dir>/plans`. Plans are outside the project, so
-  they are never untracked files and never appear in a `rewind` snapshot; a store
-  an older version left in `<repo>/.pi/plans` is moved in once, with a notice.
-- **A discoverable index.** `/plan list` walks the plans directory and shows
-  every plan with its title, modified time, and step progress, newest first — in
-  the TUI as a docked list where `Enter` opens the plan's review, elsewhere as a
-  notice with each plan's path. The directory stays the index: no registry file,
-  one bounded read per plan.
-- **A shape that reads.** `write_plan` documents a canonical outline — a
-  `# <Title>`, then `## Goal`, `## Context`, `## Approach`, `## Visual`,
-  `## Steps`, `## Risks`, and `## Verification` — and the model is guided to
-  follow it. Every example in the template is the shape wanted rather than a
-  description of it, and each section has one job: the goal is one sentence, the
-  context is the facts that force the approach, the approach names the
-  alternative it rejected, and verification is a fence of the commands to run.
-  `Visual` carries the end state in an untagged fence, with one line naming what to
-  look at: the same surface before and after when the change alters one that
-  already exists, one frame when the surface is new, because a reviewer judges the
-  result before the steps that build it; a change with no visible surface drops it.
-  The description calls the shape a guide rather than a form: `Context`,
-  `Approach`, `Visual`, and `Risks` are dropped when they have nothing to say,
-  while `Steps` and `Verification` are kept, because the steps are read from that
-  section (without it, the shallowest list anywhere becomes the steps) and
-  Verification becomes the last todo item. Within `Steps` only the shallowest
-  list is tracked, so nested bullets stay notes instead of becoming todos. This
-  is guidance only: any markdown is accepted, stored, and rendered as written,
-  and a refinement is asked to keep its section headings so the review can still
-  mark only what changed.
-- **Trackable steps.** Steps are written as `- [ ]` checkboxes in the `## Steps`
-  section; approval seeds them into `todo`, with the `## Verification` section as
-  the last item so the definition of done travels with the work. A plan with more
-  than 50 top-level steps is refused rather than truncated, so approval never
-  drops a step you reviewed.
-- **A navigable review.** The review screen splits the body at its headings,
-  names the section you are in, and jumps between sections with `n`/`p`.
-- **What changed since the last review.** After a refinement, the review screen
-  names how many sections changed, marks the current one in the scroll row, and
-  the browser outline dots each changed section, so a re-review does not mean
-  re-reading the whole plan. The baseline is one digest per heading section of
-  what the previous review showed, kept as a session entry, so a resumed session
-  or a `/tree` restore marks only what changed on its own branch.
-- **Kept current.** After approval, `set_plan_steps` flips the checkboxes of
-  the steps you name in the file, so the plan mirrors what has actually been
-  done, and ticks the todo item approval seeded from that step with it, so the
-  widget and the plan do not drift apart. Pass the step's text as `expected` and
-  an update whose step number moved is refused instead of ticking the wrong line.
-- **Reviewable plan.** `exit_plan_mode` reads the plan file back and presents
-  it for approval. The user approves, keeps planning, asks for a refinement, or
-  exits plan mode without approving; the last keeps the plan file for a later
-  review and records no todo items or goal.
-  On a remote turn (WeChat) the plan file is sent first, then one compact editor
-  prompt: the title, step count, first steps, mode status, and three actions
-  (approve, keep, exit). Any other reply is a refinement request; if the file
-  upload fails, its text is sent instead.
-- **Browser review on demand.** Press `w` on the review screen (or run
-  `/plan review [path]`) to open the plan in a local browser: a reading-first
-  page with the plan's H1 as its title, GitHub's Markdown content column, a
-  comment rail in
-  the left margin, and live section and step progress — the step count comes from
-  the same `Steps` section list approval seeds. Select text to leave an
-  inline comment, and save them back into the plan file itself as
-  `> [!REVIEW]` lines. Saved comments return to the model as a refinement
-  request.
-- **The file is the source of truth.** On approval the model follows the plan
-  file's steps; refinements rewrite the same file (`write_plan` with
-  `plan_path`), so the reviewed artifact is the executed artifact.
-- **Steps become todos.** On approval, the top-level numbered/bulleted items of
-  the plan's `Steps` section are recorded with the `todo` tool (via
-  `ctx.executeTool`); steps marked `- [x]` (or `[DONE:n]`) seed as completed, and
-  nested sub-bullets are treated as notes while an indented line continues its
-  step. The list is a merge, not a replacement: existing items keep their place
-  and status, a step whose text is already there is skipped, and the tool's item
-  cap defers the rest instead of dropping anything. The plan's `## Verification`
-  section follows as the **last**
-  todo item, summarized on one line (`Verify: …`) — a fenced block contributes its
-  commands, not its fence lines. It is not a plan step, so it is ticked in the todo
-  list rather than with `set_plan_steps`, and it never counts against the 50-step
-  cap. A plan without a `Steps` heading keeps the older rule —
-  the shallowest list in the document — so prose bullets in a plan that follows the
-  outline never become todos, and its verification bullets are already covered.
-  Each seeded item is matched back to its step by text, so ticking a step with
+All five tools are `executionMode: "sequential"` and closed-world. Two are active
+in normal mode and three are `defaultActive: false`, so the plan-mode tool set
+stays small.
+
+| Tool | Active | Purpose |
+|---|---|---|
+| `enter_plan_mode` | normal mode | Ask to enter plan mode; empty schema, confirmed with `ctx.ui.confirm`. |
+| `write_plan` | plan mode | Save the plan: `title` (file-name slug), `content` (full markdown in the documented outline), optional `plan_path` to overwrite a refinement. Returns the absolute path. |
+| `exit_plan_mode` | plan mode | Read the plan file (`plan_path`) and present it for approval. |
+| `cancel_plan_mode` | plan mode | Leave plan mode without a plan file or a review. Empty schema. |
+| `set_plan_steps` | normal mode | Set the checkboxes of the given top-level steps of an approved plan in one write, and their todo items with them. |
+
+### `enter_plan_mode`
+
+No parameters. It confirms with `ctx.ui.confirm` before switching the tool set,
+because the model is changing the mode on the user's behalf; a declined confirm
+answers "stayed in normal mode" and the session keeps write access. Already
+planning, it says so. With no UI it fails with an actionable message instead of
+deciding for the user.
+
+On a remote turn the confirmation is a short consent sentence in the peer's
+language, and the notice names how to leave.
+
+### `write_plan`
+
+`title` is the file-name slug, `content` the full markdown, and `plan_path`
+overwrites an existing plan when refining. The result carries the absolute path,
+the relative path, and the byte count — the absolute path is what `exit_plan_mode`
+takes.
+
+The file lands in
+`<agent-dir>/plans/<repo-key>/<YYYY-MM-DD-HHmm>-<slug>.md`, keyed by the
+repository's common git directory, so a plan approved in one worktree is the
+same plan from the main checkout and from every other session. Outside a
+repository the store is `<agent-dir>/plans`. Plans are outside the project, so
+they are never untracked files and never appear in a `rewind` snapshot; a store
+an older version left in `<repo>/.pi/plans` is moved in once, with a notice.
+
+The description documents a canonical outline — a `# <Title>`, then `## Goal`,
+`## Context`, `## Approach`, `## Visual`, `## Steps`, `## Risks`, and
+`## Verification` — and the model is guided to follow it. Every example in the
+template is the shape wanted rather than a description of it, and each section
+has one job: the goal is one sentence, the context is the facts that force the
+approach, the approach names the alternative it rejected, and verification is a
+fence of the commands to run. `Visual` carries the end state in an untagged
+fence, with one line naming what to look at: the same surface before and after
+when the change alters one that already exists, one frame when the surface is
+new, because a reviewer judges the result before the steps that build it; a
+change with no visible surface drops it. The description calls the shape a guide
+rather than a form: `Context`, `Approach`, `Visual`, and `Risks` are dropped when
+they have nothing to say, while `Steps` and `Verification` are kept, because the
+steps are read from that section (without it, the shallowest list anywhere
+becomes the steps) and Verification becomes the last todo item. Within `Steps`
+only the shallowest list is tracked, so nested bullets stay notes instead of
+becoming todos. This is guidance only: any markdown is accepted, stored, and
+rendered as written, and a refinement is asked to keep its section headings so
+the review can still mark only what changed.
+
+A plan with more than 50 top-level steps in its `Steps` section is refused with
+the cap and the fix named, and nothing is written.
+
+The file is the source of truth. On approval the model follows the plan file's
+steps, and refinements rewrite the same file (`write_plan` with `plan_path`), so
+the reviewed artifact is the executed artifact.
+
+### `exit_plan_mode`
+
+`plan_path` names the file `write_plan` returned; the tool reads it back and
+presents it for approval. A hand-edited or older file whose step list is over the
+cap is refused before the review screen. The user approves, keeps planning, asks
+for a refinement, or exits plan mode without approving; the last keeps the plan
+file for a later review and records no todo items or goal. The review also offers
+**Exit plan mode (discard)**, which leaves plan mode without approving.
+
+On approval, plan mode ends, write access returns, and the plan's steps go into
+the todo list:
+
+- Steps are the top-level numbered/bulleted items of the plan's `Steps` section,
+  and approval records them with the `todo` tool (via `ctx.executeTool`). Steps
+  marked `- [x]` (or `[DONE:n]`) seed as completed, nested sub-bullets are notes,
+  and an indented line continues its step.
+- The list is a merge, not a replacement: existing items keep their place and
+  status, a step whose text is already there is skipped, and the tool's item cap
+  defers the rest instead of dropping anything.
+- The plan's `## Verification` section follows as the **last** todo item,
+  summarized on one line (`Verify: …`) — a fenced block contributes its
+  commands, not its fence lines. It is not a plan step, so it is ticked in the
+  todo list rather than with `set_plan_steps`, and it never counts against the
+  50-step cap.
+- A plan without a `Steps` heading keeps the older rule — the shallowest list in
+  the document — so prose bullets in a plan that follows the outline never become
+  todos, and its verification bullets are already covered.
+- Each seeded item is matched back to its step by text, so ticking a step with
   `set_plan_steps` completes the item too.
-- **Goal-aware.** While planning, the injected context restates a pursued
-  session goal as one bullet, so the plan is designed against the objective
-  instead of beside it. On approval, a goal the goal workflow left as a draft
-  (`planning`) is finalized from the plan's own `## Goal` section — falling back
-  to the title — through the `goal` tool, with no extra dialog, because approving
-  the plan *is* the decision. A session with no goal at all is given the same
-  objective, also without asking. An `active` or `achieved` goal is never
-  rewritten: a final objective is the user's. No path spends a model turn.
-- **A split, when the switch is on.** With `plan.split` enabled (off by default;
-  a `/bytefly settings` row), `exit_plan_mode` also accepts `units`: the plan's
-  slices, each with a name, path prefixes, a test, and the units it depends on.
-  The split is validated *before* the review opens, so a refusal costs no review,
-  and the review screen shows it as a read-only `Split` section. On approval the
-  team is written into the plan as a `## Team` table — a sentence naming the lead's
-  unit, then one row per unit — and the result carries a roster card: the exact
-  commands for the sessions this package cannot start, the merge order, which unit
-  is the lead's own, and the lead's own label or the rename that sets it. The team
-  section is what a joining session reads, so it appears only after approval; a
-  refinement rewrites the plan, and with it the team ceases to exist until the plan
-  is approved again. Refusals name the pair: fewer than two units (with the
-  skeleton advice), overlapping prefixes, a `dependsOn` cycle, more than two owners
-  plus the lead, a unit with no test, an owner unit that claims a shared file, and a
-  value that would break the table. See [Splitting a plan](#splitting-a-plan).
-- **Branch-aware.** The enabled flag and the review baseline are custom session
-  entries, so `/resume` and `/tree` restore the right mode and keep the
-  changed-section markers.
-
-## Splitting a plan
-
-Off by default: enable **Split plans into slices** in `/bytefly settings`, or set
-`"plan": { "split": true }` in the project's `.pi/bytefly.json` so a repository
-switches its own team on.
 
-```text
-exit_plan_mode({
-  plan_path: "~/.pi/agent/plans/a1f9c02/2026-11-04-1802-billing.md",
-  units: [
-    { name: "contract", paths: ["src/billing/contract"], test: "bun test src/billing/contract", lead: true },
-    { name: "core", paths: ["src/billing/core"], test: "bun test src/billing/core", dependsOn: ["contract"] }
-  ]
-})
-```
+**Goal-aware.** While planning, the injected context restates a pursued session
+goal as one bullet, so the plan is designed against the objective instead of
+beside it. On approval, a goal the goal workflow left as a draft (`planning`) is
+finalized from the plan's own `## Goal` section — falling back to the title —
+through the `goal` tool, with no extra dialog, because approving the plan *is*
+the decision. A session with no goal at all is given the same objective, also
+without asking. An `active` or `achieved` goal is never rewritten: a final
+objective is the user's. No path spends a model turn.
 
-The result prints the roster card, which is all the package can do for the sessions
-it cannot start — and the one line it can act on for the session it is in:
+### `cancel_plan_mode`
 
-```text
-Split: 2 units · ~/.pi/agent/plans/a1f9c02/2026-11-04-1802-billing.md
-  You start and switch every session; nothing here can.
-  core: enter_worktree core · /sessions name core · /sessions watch wake
-    session({action:"join", team:"2026-11-04-1802-billing", unit:"core"})
-  merge order: contract → core · your unit: contract
-  your label: none — name this session: session({action:"name", label:"contract"})
-```
+Leaves plan mode without a plan file or a review. Restores write access, records
+no todo items or goal, and keeps any saved plan. Empty schema.
 
-The last line is the lead's own label. The card's other lines are for the sessions
-the user starts; this one is the lead's own, so it names the label when the session
-already has one, and otherwise prints the rename to run. Once set, it reads
-`your label: billing-lead — owners send their report there`, which is what an
-owner addresses its completion report to.
+### `set_plan_steps`
 
-What the gate enforces, and why each rule is a refusal rather than a warning:
+Keep an approved plan current: `plan_path`, plus `updates`, each a 1-based `step`
+in the order `exit_plan_mode` listed, a `status` of `pending` or `completed`, and
+`expected` — the step's text, so an update whose step number moved is refused
+instead of ticking the wrong line. It is a single all-or-nothing write: a step out
+of range, or an `expected` text that no longer matches the file, refuses every
+entry. Only the checkboxes change, and a reopened step drops its `[DONE:n]`
+marker.
 
-| Refusal | Why |
-|---|---|
-| fewer than two units | One path is not a split: approve as one flow, or build the thinnest end-to-end path first. |
-| overlapping prefixes | Two owners on one path is a merge conflict by construction. |
-| a `dependsOn` cycle | No unit can start. |
-| more than two owners | The user switches to every owner each round; three means the split is wrong. |
-| a unit with no test | The unit's definition of done would be undocumented. |
-| an owner unit claiming a shared file | `package.json`, the changelog, the test manifests, and the shared name modules belong to the lead. |
-| no unit marked lead | The approving session needs a unit of its own, or it is a queue. |
-
-The table itself is a wire format: [`session-bus`](../session-bus/) parses it with
-the same module that writes it, so a hand-edited or stale section is refused
-rather than half-read. The browser review cannot approve a split plan — a section
-written at approval has no source lines for its comments to anchor to — so the
-terminal review is where a split is approved.
+The todo item approval seeded from a step is ticked with it: the file is written
+first and is authoritative, a renamed item is left alone and reported as
+unmatched, and a failed todo write is reported in the result. The tool refuses
+while plan mode is on — refine the plan with `write_plan` instead.
 
-## Tools
+### Transcript
 
-| Tool | Active | Purpose |
-|---|---|---|
-| `enter_plan_mode` | normal mode | Ask to enter plan mode; empty schema, confirmed with `ctx.ui.confirm`. |
-| `write_plan` | plan mode | Save the plan: `title` (file-name slug), `content` (full markdown in the documented outline), optional `plan_path` to overwrite a refinement. Returns the absolute path. A plan with more than 50 top-level steps in its `Steps` section is refused, with the cap and the fix named, and nothing is written. |
-| `exit_plan_mode` | plan mode | Read the plan file (`plan_path`) and present it for approval. Optional `units` proposes a split when `plan.split` is on; it is validated before the review, written into the plan on approval, and ignored with one note while the switch is off. The review also offers **Exit plan mode (discard)**, which leaves plan mode without approving. Refuses a file whose step list is over the cap, before the review screen. |
-| `cancel_plan_mode` | plan mode | Leave plan mode without a plan file or a review. Restores write access; records no todo items or goal; keeps any saved plan. Empty schema. |
-| `set_plan_steps` | normal mode | Keep an approved plan current: set the checkboxes of the given top-level steps (`updates`, each a 1-based `step` in the order `exit_plan_mode` listed, plus `status`, and `expected` — the step's text, so a reordered plan is refused) to `pending` or `completed` in one write. Only the checkboxes change, and a reopened step drops its `[DONE:n]` marker. The todo item approval seeded from a step is ticked with it: the file is written first and is authoritative, a renamed item is left alone, and a failed todo write is reported in the result. |
+The three tool rows reuse the transcript component, and `exit_plan_mode`
+separates the plan body from its header with a blank line; the collapse hint
+binds to `app.tools.expand` (`ctrl+o` by default).
+
+```
+enter_plan_mode requested plan mode
+✓ Plan mode enabled
+```
 
-### Commands and flags
+```
+write_plan Add rate limiting
+✓ Saved plan ~/.pi/agent/plans/a1f9c02/2026-10-09-1809-add-rate-limiting.md
+```
+
+```
+exit_plan_mode submitted a plan
+✓ Plan approved
+~/.pi/agent/plans/a1f9c02/2026-10-09-1809-add-rate-limiting.md
+
+# Add rate limiting
+1. Add a token bucket …
+
+… 12 more lines (ctrl+o to expand)
+```
+
+## Commands and flags
 
 | Path | Who starts it | Confirmation |
 |---|---|---|
@@ -229,6 +237,7 @@ terminal review is where a split is approved.
 | `/plan <prompt>` | the user, with the task | immediate |
 | `/plan list` | the user, browsing the plans directory | immediate |
 | `/plan review [path]` | the user, reviewing a plan in the browser | immediate |
+| `/plan share [stop]` | the user, handing the review to a teammate | immediate |
 | `/plan cancel` | the user, leaving plan mode without approving | immediate |
 | `/skill:init` | the user, creating or updating `AGENTS.md` | enters plan mode; write waits for plan approval |
 | `Ctrl+Alt+P` | the user | immediate |
@@ -248,13 +257,28 @@ the toggle that works in every terminal (for example Zed's integrated terminal,
 which does not forward `Ctrl+Alt+P`). The footer shows `≡ plan` while plan mode
 is on, and `≡ plan · <plan-file>` once the model has written a plan.
 
-`/plan review` is the one reserved subcommand. Bare `/plan review` reviews the
-plan this session wrote, or, in a later session, the newest plan file in the
-plans directory (newest modification time); `/plan review <path>.md` (or a path
-with a separator) reviews that plan. A line that merely starts with the word —
-`review the auth flow` — is still treated as a planning task, so the subcommand
+`/plan list` walks the plans directory and shows every plan with its title,
+modified time, and step progress, newest first — in the TUI as a docked list
+where `Enter` opens the plan's review, elsewhere as a notice with each plan's
+path. The header carries the store's own footprint for this repository: the bytes
+its plans hold and how old the oldest one is, both derived from the walk that just
+happened. The directory stays the index: no registry file, nothing deletes a plan,
+and one bounded read per plan.
+
+`/plan review` is the only subcommand that takes an argument. Bare `/plan review`
+reviews the plan this session wrote, or, in a later session, the newest plan file
+in the plans directory (newest modification time); `/plan review <path>.md` (or a
+path with a separator) reviews that plan. A line that merely starts with the word
+— `review the auth flow` — is still treated as a planning task, so the subcommand
 never swallows one.
 
+`/plan share` prints the reviewer link and its QR, and `/plan share stop` revokes
+every link; the page's **Share** button does the same. With no browser review open
+it says so and points at `/plan review`. `/plan cancel` leaves plan mode without
+approving, exactly like `cancel_plan_mode`: write access returns and the plan file
+stays for a later review. Both are exact words — `share the tokens` and `cancel
+that idea` stay tasks — as is `list`.
+
 ### `/skill:init`
 
 `/skill:init` loads the packaged `init` skill. The skill enters plan mode itself
@@ -300,51 +324,53 @@ The quality reference is
 [`skills/init/references/agents-md-quality.md`](../../skills/init/references/agents-md-quality.md).
 An existing instruction file is reviewed and updated only after approval, a root
 override is edited in place or removed explicitly when consolidating, an accurate
-file can produce a no-op plan, and an empty repository gets only known facts.
+file can produce a no-op plan, and an empty repository gets only known facts. It
+never invents commands.
 The skill needs the plan extension for its review gate. It also ships with the
 package, so load the whole package (`pi -e .`) or install it; loading only
 `./extensions/plan` leaves `/skill:init` unavailable.
 
+## Routes
+
+The browser review serves these routes on its loopback origin; `…` is the
+session token, and the owner's token is the one that opened the page.
+
+| Route | Result |
+|---|---|
+| `GET /?token=…` | the review page (a JSON data island plus `/theme.js` and `/client.js`) |
+| `GET /theme.js` | the shared pre-paint theme bootstrap |
+| `GET /client.js` | the first-party client script |
+| `GET /events?token=…` | Server-Sent Events stream: a `comment`, `plan`, or `share` frame when something changed, `closed` when the review ends, `revoked` when sharing stops, and a dropped stream to detect a closed tab |
+| `POST /api/comment?token=…` | reviewer only: write their own comments into the plan, replacing only their own; never ends the review |
+| `POST /api/feedback?token=…` | owner only: write the owner's comments and return to the model |
+| `POST /api/approve?token=…` | owner only: save, then approve |
+| `POST /api/cancel?token=…` | owner only: end the session without saving |
+| `POST /api/share?token=…` | owner only: mint the first reviewer link and its QR |
+| `POST /api/share/link?token=…` | owner only: mint one more reviewer link, so each teammate holds their own |
+| `POST /api/share/revoke?token=…` | owner only: revoke one link by `{ id }`, leaving the others answering |
+| `POST /api/share/stop?token=…` | owner only: revoke every reviewer link |
+
 ## Behaviour by mode
 
-The review screen is TUI-only. `exit_plan_mode` opens `PlanViewComponent`: a
-scrollable, width-safe view of the plan with approve/refine/keep/exit in the footer.
-The body is rendered with Pi's own `Markdown` component and `getMarkdownTheme()`,
-so headings, lists, inline code, code blocks, links, and quotes carry the active
-theme's colors; task items get the shared `◼` (done) or `◻` (pending) marker,
-like the bytefly screen and the question dialog. The footer colors the primary
-actions (`a approve & run` in `success`, `r refine` in `accent`).
-`a` asks `y/N` in the footer, then ends plan mode, restores write access, and
-seeds `todo`; `y` or `Enter` approves and `n`, `q`, or `Esc` goes back to
-reading. `r` keeps the plan
-mounted and opens an inline editor beneath it (`Enter` submits, an empty buffer
-does nothing, `Esc` returns to the plan); `Esc` keeps planning and tells the
-model the plan was not approved; `x` leaves plan mode without approving and
-keeps the plan file. The dialog path is one editor prompt: `1` approve, `2` full
-plan, `3` keep, `4` exit; any other text refines the plan. Dismissing or timing
-out the prompt exits without approving. When the plan changed since the previous review
-on this branch, a summary line under the title names how many sections changed
-and the scroll row appends `· changed` to the current section. Scroll with `↑`/`↓` or `j`/`k`, `space`/`b` or
-`PgUp`/`PgDn`, `d`/`u`, `g`/`G`, and the mouse wheel. Press `n`/`p` to jump to
-the next or previous heading; the scroll row names the current section when the
-plan has more than one. When the plan overflows,
-a gauge row above the hints shows the scroll position, the percent, and the
-visible line range (the range drops first on a narrow terminal); the gauge comes
-from the design system's `gaugeBar` and stays
-visible while the refine editor is open, since the body above is still clipped.
-Hints are
-dropped whole as the terminal narrows, and each footer leads with its safe exit
-(`Esc keep plan` in the review, `Esc back to plan` in the inline editor) so
-the exit survives even when only one hint fits.
-
-Dialog-capable non-TUI modes (RPC/WeChat) use one editor prompt; a non-action
-reply is the refinement, so “select Refine, then type” is gone. A WeChat turn
-takes the same dialog path and is answered over WeChat, even though the session
-is in TUI mode: the choice comes from `askHuman(ctx, { custom, dialogs, body })`
-in `lib/interaction.ts`, not from `ctx.mode`. No plan file is attached; **full
-plan** posts the text and asks again.
-Without any UI the tools fail with an actionable message instead of deciding for
-the user.
+The review screen is TUI-only: `exit_plan_mode` opens `PlanViewComponent`, and `w`
+on it opens the browser review. RPC and other non-interactive runs get no screen.
+
+Dialog-capable non-TUI modes (RPC/WeChat) use one editor prompt instead: on a
+remote turn the plan file is sent first, then a compact prompt carrying the
+title, step count, first steps, mode status, and three actions — `1` approve,
+`2` keep planning, `3` exit. If the upload fails, the plan's text is sent
+instead. Any other reply is a refinement, so "select Refine, then type" is gone.
+A WeChat turn takes the same dialog path and is answered over
+WeChat, even though the session is in TUI mode: the choice comes from
+`askHuman(ctx, { custom, dialogs, body })` in `lib/interaction.ts`, not from
+`ctx.mode`. Without any UI the tools fail with an actionable message instead of
+deciding for the user.
+
+`/plan list` is a docked list screen in the TUI and a notice with each plan's
+path everywhere else; both name the store's size and its oldest plan. The dock is
+the list's alone while it is open — the goal and todo rails hide, as they do for
+the other list screens — and the screen counts its own frame, so a full list keeps
+its closing rule on a short terminal.
 
 Browser review is a local-turn feature: the server binds `127.0.0.1`, so a remote
 (WeChat) turn cannot reach it and `/plan review` there refuses with a notice
@@ -356,49 +382,35 @@ Aborting the turn closes a browser review. `exit_plan_mode` forwards the call's
 abort signal to the review server, so an aborted turn returns "not approved"
 and stops listening instead of waiting on a page nobody is watching.
 
-### Transcript
-
-The three tool rows reuse the transcript component, and `exit_plan_mode`
-separates the plan body from its header with a blank line; the collapse hint
-binds to `app.tools.expand` (`ctrl+o` by default).
-
-```
-enter_plan_mode requested plan mode
-✓ Plan mode enabled
-```
-
-```
-write_plan Add rate limiting
-✓ Saved plan ~/.pi/agent/plans/a1f9c02/2026-10-09-1809-add-rate-limiting.md
-```
-
-```
-exit_plan_mode submitted a plan
-✓ Plan approved
-~/.pi/agent/plans/a1f9c02/2026-10-09-1809-add-rate-limiting.md
-
-# Add rate limiting
-1. Add a token bucket …
-
-… 12 more lines (ctrl+o to expand)
-```
-
 ## Security
 
 Plan mode is a **guard rail, not a sandbox**: extensions run with Pi's OS
 permissions, so it prevents accidental writes while planning, not a hostile
 command. The read-only guarantee is layered:
 
+- **Tool set at entry.** Tools that are not read-only are removed from the active
+  set or blocked. `write` and `edit` are hidden, raw shell is limited to read-only
+  git commands through `bash` (chained with `&&`/`;`), `powershell` is blocked
+  outright, and other mutating tools (worktree mutations, MCP tools) are blocked
+  until you exit plan mode. `subagent` stays active but is forced read-only. The
+  only permitted write is the plan control tool `write_plan`, which can only
+  create or overwrite markdown plan files directly inside the plans directory —
+  never dotfiles and never through a symlink.
 - **Capability policy.** A tool is allowed only when it is a known structured
   reader or declares the MCP `readOnlyHint`; `write`, `edit`, and unknown
-  mutators are denied.
+  mutators are denied. Classification defaults to *deny* and is driven by the
+  shared [`lib/policy.ts`](../../lib/policy.ts), so unknown tools are safe by
+  default and the MCP `readOnlyHint` is the only thing that opens one up.
 - **Path backstop.** A `readOnlyHint` is only a claim, so a tool that takes a
   file path is refused unless it is a known plan-safe reader. `path-guard.ts`
   scans nested arguments and path-shaped values, not just fixed top-level keys.
-- **Control-tool identity.** The `tool_call` guard exempts `write_plan` /
-  `exit_plan_mode` only when the registered tool is this extension's own,
-  matched by source path, so a same-named tool from another extension cannot
-  borrow the exemption.
+- **Control-tool identity.** The `tool_call` guard exempts plan's own tools —
+  `enter_plan_mode`, `cancel_plan_mode`, `write_plan`, and `exit_plan_mode` — only
+  when the registered tool is this extension's, matched by source path, so a
+  same-named tool from another extension cannot borrow the exemption.
+  `enter_plan_mode` is exempted so a call already in flight when plan mode came on
+  is answered with "Already in plan mode" instead of being refused as not
+  read-only; the policy still denies it, so it stays hidden while planning.
 - **Contained writes.** `write_plan` only writes markdown non-dotfiles whose
   real parent resolves inside the plans directory, and every plan write —
   create, refine, `set_plan_steps`, browser feedback — goes through a hidden
@@ -428,9 +440,10 @@ conservative allowlist in `git-bash.ts`. `powershell` is not allowed at all, so
 plan mode uses Git Bash on native Windows: the same read-only git commands work
 there, and a backslash before an ordinary character is accepted as a Windows
 path separator while a backslash that escapes a metacharacter is still refused.
-Everything else uses `read`, `grep`, `find`,
-`ls`, and the other read-only tools already available (`web_search`,
-`web_fetch`, `ask_user_question`, `todo`, `goal`).
+Everything else uses the structured readers — `read`, `grep`, `find`, `ls`, and
+`read_doc` for a PDF, Word, OpenDocument, RTF, or Excel file — and the other
+read-only tools already available (`web_search`, `web_fetch`,
+`ask_user_question`, `todo`, `goal`).
 
 ```bash
 git status && git diff --stat     # allowed: two read-only git commands
@@ -441,6 +454,10 @@ git status | sh                   # blocked: pipes are never allowed
 git diff > out.patch              # blocked: redirection is a write
 ```
 
+A refused shell command explains the fix: the working directory is already the
+project root (so `cd` is unnecessary), and files belong to the `read`, `grep`,
+`find`, and `ls` tools.
+
 A string parser can never be the boundary, so capability gating replaced the
 earlier segment-based command allowlist. The git shell guard is a narrow,
 deliberate exception — an allowlist over read-only git command shapes, not a
@@ -452,7 +469,7 @@ first or wait for approval.
 While planning, `subagent` stays available but every call is **forced
 read-only**. Plan mode sets `readOnly: true` on the call in the `tool_call`
 guard, and `subagent` in turn gives each spawned agent a reader-only `--tools`
-list (`read`, `grep`, `find`, `ls`, `web_search`, `web_fetch`). The child
+list (`read`, `grep`, `find`, `ls`, `read_doc`, `web_search`, `web_fetch`). The child
 process enforces it, so a delegated `explorer`, `researcher`, or even `worker`
 cannot write, edit, or run a shell — regardless of its prompt or an external
 agent file that overrides it.
@@ -472,20 +489,46 @@ agent file that overrides it.
 
 ## Review screen
 
-<img src="../../assets/plan.png" alt="The terminal plan review: a Plan Review title rule, a notice that one section changed since the last review, the plan body with its headings and ◼/◻ task checkboxes, a scroll gauge naming the current section and the visible line range, and the Esc/a/r/w, scroll, and section-jump hints" width="100%">
+<img src="../../assets/screens/plan.png" alt="The terminal plan review: a Plan Review title rule, a notice that one section changed since the last review, the plan body with its headings and ◼/◻ task checkboxes, a scroll gauge naming the current section and the visible line range, and the Esc/a/r/w, scroll, and section-jump hints" width="100%">
 
 `exit_plan_mode` opens this screen on the plan file it just wrote. The body is
-Pi's Markdown renderer with the active theme, so headings, lists, code, and
-links read as they do in the transcript; the checkboxes in `Steps` use the
-shared `◼`/`◻` vocabulary. A plan taller than the terminal scrolls under a gauge
-that names the section at the top of the viewport and the line range it shows,
-and the footer lists only the keys that apply. `Esc` keeps planning, `a` asks
-`y/N` and then approves and runs, `r` refines inline, and `w` opens the browser
-review below.
+rendered with Pi's own `Markdown` component and `getMarkdownTheme()`, so
+headings, lists, inline code, code blocks, links, and quotes carry the active
+theme's colours; task items get the shared `◼` (done) or `◻` (pending) marker,
+like the bytefly screen and the question dialog. A plan taller than the terminal
+scrolls under a gauge that names the section at the top of the viewport and the
+line range it shows, and the footer lists only the keys that apply.
+
+- **Actions.** The footer colours the primary actions (`a approve & run` in
+  `success`, `r refine` in `accent`). `a` asks `y/N` in the footer, then ends
+  plan mode, restores write access, and seeds `todo`; `y` or `Enter` approves and
+  `n`, `q`, or `Esc` goes back to reading. `r` keeps the plan mounted and opens
+  an inline editor beneath it (`Enter` submits, an empty buffer does nothing,
+  `Esc` returns to the plan); `Esc` keeps planning and tells the model the plan
+  was not approved; `x` leaves plan mode without approving and keeps the plan
+  file; `w` opens the browser review.
+- **Sections.** The screen splits the body at its headings, names the section you
+  are in, and jumps between sections with `n`/`p`; the scroll row names the
+  current section when the plan has more than one.
+- **What changed since the last review.** After a refinement, the screen names
+  how many sections changed, marks the current one in the scroll row, and the
+  browser outline dots each changed section, so a re-review does not mean
+  re-reading the whole plan. The baseline is one digest per heading section of
+  what the previous review showed, kept as a session entry, so a resumed session
+  or a `/tree` restore marks only what changed on its own branch.
+- **Scrolling.** `↑`/`↓` or `j`/`k`, `space`/`b` or `PgUp`/`PgDn`, `d`/`u`,
+  `g`/`G`, and the mouse wheel. When the plan overflows, a gauge row above the
+  hints shows the scroll position, the percent, and the visible line range (the
+  range drops first on a narrow terminal); the gauge comes from the design
+  system's `gaugeBar` and stays visible while the refine editor is open, since the
+  body above is still clipped.
+- **Narrow widths.** Hints are dropped whole as the terminal narrows, and each
+  footer leads with its safe exit (`Esc keep plan` in the review, `Esc back to
+  plan` in the inline editor) so the exit survives even when only one hint fits.
 
 ## Browser review
 
-<img src="../../assets/plan-review.png" alt="The browser-based plan review: a sticky header with the plan title, a status chip, and the Approve & run, Save feedback, and Back to Pi actions, a Share action, a side panel with step progress and a section outline, and the plan as one measured column with a comment rail holding the owner's own comment and a teammate's @priya comment" width="100%">
+<img src="../../assets/screens/plan-review.png" alt="The browser-based plan review: a sticky header with the plan title, a status chip, and the Approve & run, Save feedback, and Back to Pi actions, a Share action, a side panel with step progress and a section outline, and the plan as one measured column with a comment rail holding the owner's own comment and a teammate's @priya comment" width="100%">
 
 Press `w` on the review screen — or run `/plan review [path]` — to open the plan
 in the default browser on `127.0.0.1`. The page is a reading-first review
@@ -500,7 +543,7 @@ text first to quote it. **Save feedback** writes the comments into the plan
 file and returns them to the model.
 
 - **Shared theme.** The page uses the same Bytefly tokens, base rules, and
-  syntax-token colors as `file-browse` (`lib/web/`), follows the system light/dark
+  syntax-token colours as `file-browse` (`lib/web/`), follows the system light/dark
   preference until the header toggle sets an explicit choice, and remembers that
   choice under the shared `pi-web-theme` key.
 - **One content column, one rail.** The document is GitHub's Markdown content
@@ -556,7 +599,6 @@ file and returns them to the model.
 - **Highlighted code.** Fenced code is tokenized by the shared
   `lib/highlight.ts`; the client copies only text and `tok-*` spans through
   `DOMParser`, so a code line is never parsed as markup.
-
 - **The file is the store.** Each comment is written as
   `> [!REVIEW] <comment>` on the line after the block it anchors to, tagged with
   its author when a teammate wrote it (`> [!REVIEW] @alice: <comment>`). Saving is
@@ -568,10 +610,14 @@ file and returns them to the model.
 - **A revision keeps the review.** `write_plan` passes the file it is replacing
   through `carryFeedback`, which re-attaches each comment by the strongest evidence
   that survived: the anchored block's text, per occurrence, so a plan that repeats
-  a step keeps the comments apart; then the same section at the same position, so a
-  reworded step keeps its note; then the end of that section. A comment whose
-  section is gone too moves to the end of the file, where the page shows it as
-  unattached, rather than disappearing.
+  a step keeps the comments apart; then the block whose wording still overlaps it —
+  half the longer block's words — so a reworded step keeps its note, and a step
+  that shifted down under an inserted one keeps it too; then the gap it left
+  between the steps that survived; then the last block that section still has. A
+  comment whose section is gone too moves to the plan's last block rather than
+  disappearing, and every one of those placements lands beside a block, never after
+  a blank line, so the page keeps the thread under its block. Only a plan with no
+  block at all leaves a comment in the unattached list.
 - **Anchored to source.** `blocks.ts` splits the plan (fence-aware) into
   source-line ranges; a comment is placed after the whole anchored block, so a
   fenced code block is never split. A save re-checks the file against what the
@@ -594,20 +640,7 @@ file and returns them to the model.
   so refreshing or reloading a conflicted page does not end the review. A
   reviewer's tab opening or closing is not the review's lifetime.
 
-| Route | Result |
-|---|---|
-| `GET /?token=…` | the review page (a JSON data island plus `/theme.js` and `/client.js`) |
-| `GET /theme.js` | the shared pre-paint theme bootstrap |
-| `GET /client.js` | the first-party client script |
-| `GET /events?token=…` | Server-Sent Events stream: a `comment`, `plan`, or `share` frame when something changed, `closed` when the review ends, `revoked` when sharing stops, and a dropped stream to detect a closed tab |
-| `POST /api/comment?token=…` | reviewer only: write their own comments into the plan, replacing only their own; never ends the review |
-| `POST /api/feedback?token=…` | owner only: write the owner's comments and return to the model |
-| `POST /api/approve?token=…` | owner only: save, then approve |
-| `POST /api/cancel?token=…` | owner only: end the session without saving |
-| `POST /api/share?token=…` | owner only: mint the first reviewer link and its QR |
-| `POST /api/share/link?token=…` | owner only: mint one more reviewer link, so each teammate holds their own |
-| `POST /api/share/revoke?token=…` | owner only: revoke one link by `{ id }`, leaving the others answering |
-| `POST /api/share/stop?token=…` | owner only: revoke every reviewer link |
+The routes it serves are in [Routes](#routes).
 
 ## Shared review
 
@@ -716,9 +749,9 @@ both.
 
 | Integration point | How |
 |---|---|
-| Tools | `enter_plan_mode`, `write_plan`, `exit_plan_mode`, and `set_plan_steps` registered with `executionMode: "sequential"`. `enter_plan_mode` is active normally with `readOnlyHint: true`; `write_plan` (`readOnlyHint: false`) and `exit_plan_mode` (`readOnlyHint: true`) are `defaultActive: false`. `set_plan_steps` is active normally (`readOnlyHint: false`, `idempotentHint: true`); the read-only policy default-denies it in plan mode. Each returns typed `details` (`EnterPlanModeDetails`, `WritePlanDetails`, `ExitPlanModeDetails`, `SetPlanStepsDetails`), and `ExitPlanModeDetails` carries the review's `annotations` when a browser approval or save supplied comments; no `outputSchema`/`structuredContent`. |
-| Commands and flags | `/plan` (toggle, or enter and send a task), `/plan list` (plans index), `/plan review [path]` (browser review), `/skill:init` (skill-backed `AGENTS.md` bootstrap), `--plan` launch flag, `Ctrl+Alt+P` shortcut. |
-| State | Enabled flag and the tools it hid persisted with `pi.appendEntry("plan-mode", { enabled, removed })`, and each review's baseline persisted with `pi.appendEntry("plan-baseline", { path, sections })` as one digest per heading section; both rebuilt from `ctx.sessionManager.getBranch()`, so `/resume` and `/tree` restore the mode and the changed markers of the branch they land on. Plan writes a goal only at approval, through `ctx.executeTool("goal", { objective })`: a `planning` goal is promoted to the plan's `## Goal`, a session with none is given the same objective, and an `active`/`achieved` goal is left alone — no path asks first. A review that shows the same content appends nothing. The last plan path lives in runtime memory for the footer chip, and a bare `/plan review` falls back to the newest plan file in the directory. |
+| Tools | `enter_plan_mode` (active; `readOnlyHint: true`), `write_plan` (`defaultActive: false`; `readOnlyHint: false`, `destructiveHint: true`), `exit_plan_mode` (`defaultActive: false`; `readOnlyHint: true`), `cancel_plan_mode` (`defaultActive: false`; `readOnlyHint: true`), `set_plan_steps` (active; `readOnlyHint: false`, `idempotentHint: true`). All five are `executionMode: "sequential"` and closed-world, and the read-only policy default-denies `set_plan_steps` while planning. Each returns typed `details` (`EnterPlanModeDetails`, `WritePlanDetails`, `ExitPlanModeDetails`, `CancelPlanModeDetails`, `SetPlanStepsDetails`), and `ExitPlanModeDetails` carries the review's `annotations` when a browser approval or save supplied comments; no `outputSchema`/`structuredContent`. |
+| Commands and flags | `/plan` (toggle, or enter and send a task), `/plan list` (plans index), `/plan review [path]` (browser review), `/plan share [stop]` (reviewer link), `/plan cancel` (leave without approving), `/skill:init` (skill-backed `AGENTS.md` bootstrap), `--plan` launch flag, `Ctrl+Alt+P` shortcut. |
+| State | Enabled flag and the tools it hid persisted with `pi.appendEntry("plan-mode", { enabled, removed })`, and each review's baseline persisted with `pi.appendEntry("plan-baseline", { path, sections })` as one digest per heading section; both rebuilt from `ctx.sessionManager.getBranch()`, so `/resume` and `/tree` restore the mode and the changed markers of the branch they land on. Plan writes a goal only at approval, through `ctx.executeTool("goal", { objective })` when the `goal` tool is registered: a `planning` goal is promoted to the plan's `## Goal`, a session with none is given the same objective, and an `active`/`achieved` goal is left alone — no path asks first. A review that shows the same content appends nothing. The last plan path lives in runtime memory for the footer chip, and a bare `/plan review` falls back to the newest plan file in the directory. |
 | Entry requests | `pi.events` channel `PLAN_ENTER_REQUEST` from `lib/plan-entry.ts`: the `goal` workflow asks, with the shared consent sentence, and plan enables the mode on the caller's context without a second dialog. Subscribed on `session_start`, released on `session_shutdown`. |
 | Hooks | `tool_call` blocks non-read-only calls and forces `subagent` read-only; `before_agent_start` injects the hidden `[PLAN MODE ACTIVE]` context, with a pursued session goal read from the branch through `lib/goal-state.ts`; `context` keeps only the newest plan context while enabled and drops stale ones otherwise. |
 | Lifecycle | `session_start`/`session_tree` restore state; `session_shutdown` clears the footer status and closes any browser review server. |
@@ -861,30 +894,32 @@ both.
 | File | Responsibility |
 |---|---|
 | `index.ts` | Wiring: tools, command, flag, shortcut, events, context injection. |
-| `types.ts` | `PlanModeEntry`, `EnterPlanModeDetails`, `WritePlanDetails`, `ExitPlanModeDetails`, `SetPlanStepsDetails`. |
+| `types.ts` | `PlanModeEntry`, `EnterPlanModeDetails`, `WritePlanDetails`, `ExitPlanModeDetails`, `CancelPlanModeDetails`, `SetPlanStepsDetails`. |
 | `policy.ts` | Plan mode's read-only policy, the shared prompt summary, and the bash-refusal guidance. |
 | `git-bash.ts` | `checkReadOnlyGit`: the pure allowlist that restricts `bash` to read-only git commands. |
 | `plans.ts` | Plan-file store: slug/stamp naming, directory resolution (repository, active worktree, or agent directory), containment, atomic `write`/`setSteps`/`saveFeedback`, and `read`/`latest`. |
 | `todos.ts` | Approval-time todo merge (pure): the last list replayed from the branch, and the merge of the plan's steps into it with the cap respected. |
-| `steps.ts` | Plan-document structure (pure): the outline, step extraction and the `Steps`-section scope, heading sections, the plan's own goal (`goalSection`), and the checkbox edit. |
+| `steps.ts` | Plan-document structure: the outline, step extraction and the `Steps`-section scope, the plan's own goal (`goalSection`), and the checkbox edit. |
+| `sections.ts` | The one fence-aware heading scan: `extractSections`, `sectionKeys` (the key that tells two identically titled sections apart), and the `HEADING` / `FENCE` / `normalizeHeadingText` vocabulary `blocks.ts` reads a heading through. |
 | `format.ts` | Pure result/approval text: the plan preview, the step-cap diagnosis, step labels, the merge summary, and the verification note. |
-| `plan-text.ts` | The plan text a review shows and compares: `sanitizePlanText`, the one normalization both sides use, the per-section `sectionDigests`, and `changedSections`. |
+| `plan-text.ts` | The plan text a review shows and compares: `sanitizePlanText`, the one normalization both sides use, the per-section `sectionDigests`, and `changedSections`, which hands each section back with its flag. |
 | `runtime.ts` | Enabled state, tool gating, persistence (mode and review baseline), control-tool identity, footer status. |
-| `tools.ts` | Registration entry: composes the four tool registrations in the order the session sees them. |
-| `tools/` | One module per tool (`enter.ts`, `write.ts`, `exit.ts`, `steps.ts`), plus `todo-seed.ts` (the two nested `todo` writes) and `nested.ts` (reading a nested result). |
+| `tools.ts` | Registration entry: composes the five tool registrations in the order the session sees them. |
+| `tools/` | One module per tool (`enter.ts`, `write.ts`, `exit.ts`, `cancel.ts`, `steps.ts`), plus `todo-seed.ts` (the two nested `todo` writes) and `nested.ts` (reading a nested result). |
 | `review.ts` | The review gate: one decision from the TUI screen, a dialog, or the browser, the shared browser lifecycle, and the "mark what was shown" baseline rule. |
-| `commands.ts` | `/plan` (enter, optional task), `/plan review [path]`, and `/plan share [stop]`. |
+| `review-prompt.ts` | Pure rendering and parsing for the compact remote review: one action table behind both the prompt and the reply parser. |
+| `commands.ts` | `/plan` (enter, optional task), `/plan review [path]`, `/plan list`, `/plan share [stop]`, and `/plan cancel`. |
 | `tui.ts` | `PlanViewComponent` (sectioned Markdown body, changed-section summary and marker, section jump, scroll gauge, the approve `y/N` question, approve/refine/browser/keep). |
-| `plan-index.ts` | `/plan list`: the notice text and the docked index screen (title, step progress, age, focused path; Enter reviews). |
-| `blocks.ts` | Source-line block model (fence-aware headings, paragraphs, list items, code, quotes, tables, rules, blanks). |
-| `feedback.ts` | Comment codec: authored markers, `stripFeedback`, `parseFeedback`, `formatFeedback` (writer-scoped), `displayFeedback`, `carryFeedback`, `resolveAnchor`, `feedbackSummary`, and payload validation. |
-| `web.ts` | `createPlanWebReview`: the review session (per-token roles, the change stream, the plan-file poll, the body cap, settle-after-flush, abort) over the shared bind, writer, and close. |
+| `plan-index.ts` | `/plan list`: the notice text and the docked index screen (store size and oldest plan, title, step progress, age, focused path; Enter reviews). |
+| `blocks.ts` | Source-line block model (fence-aware headings, paragraphs, list items, code, quotes, tables, rules, blanks), and `contentBlockAt`: the block with content a comment beside blank space belongs to. |
+| `feedback.ts` | Comment codec: authored markers, `stripFeedback`, `readFeedback`/`parseFeedback` (body, blocks, and comments out of one parse), `formatFeedback` (writer-scoped), `displayFeedback`, `carryFeedback`, `feedbackSummary`, and payload validation. |
+| `web.ts` | `createPlanWebReview`: the review session (per-token roles, the change stream, the plan-file poll, the body cap, settle-after-flush, abort) over `lib/http`'s one loopback server. |
 | `web-tokens.ts` | The token table: the role each token names, the collision rule that keeps two roles off one token, and the names the other live links have bound. |
 | `web-streams.ts` | The event streams: who is listening, what a frame is addressed to, and the closed-tab grace that ends the review when the owner's page goes away. |
 | `web-router.ts` | Pure request handler: token role, `Host` allowlist, origin, and method checks through one POST-and-role guard, then the page, comment, owner-save, approve, cancel, and the four share routes. |
 | `web-page.ts` | The review page shell (header, reading progress, review facts, section outline, shortcut sheet, approve confirmation, share and name dialogs), its data island, and inline CSS. |
 | `web-share.ts` | Pure sharing rules: the reachable LAN addresses from an injected snapshot, one tokenized URL, the link table (mint, find, revoke, list, state) with its cap, and the reasons a share is unavailable. |
-| `web-share-session.ts` | The shared listener's lifecycle: its bound address, the link table over the session's tokens, `ShareState`, and invite/revoke/stop/close, injected with the request handler, role map, and frame hooks. |
+| `web-share-session.ts` | The shared listener: its bound address, the link table over the session's tokens, `ShareState`, and invite/revoke/stop/close, injected with the request handler, role map, and frame hooks. |
 | `web-client.ts` | The `/client.js` source: state and wiring (comment rail, save/approve/back, keyboard nav, the stream's lifetime) over the three fragments below. |
 | `web-comments.ts` | The client's comment half: selection quotes, the composer, authored cards and who may edit them, delete-with-undo. |
 | `web-collab.ts` | The client's collaboration half: the link list with copy and per-link revoke, the reviewer's name, and the island refetch a stream frame triggers. |
@@ -896,8 +931,46 @@ both.
 | [`../../lib/shell.ts`](../../lib/shell.ts) | The shell-escape rule the read-only git guard shares with the worktree isolation guard. |
 | [`../../lib/highlight.ts`](../../lib/highlight.ts) | First-party escape-first syntax tokenizer (shared with `file-browse`). |
 | [`../../lib/qr.ts`](../../lib/qr.ts) | QR matrix, terminal half-blocks, and inline SVG for the share link (shared with `wechat`). |
-| [`../../lib/http/`](../../lib/http/) | The bind, `Host` allowlist, header sets, and response kit both browser surfaces serve through. |
+| [`../../lib/http/`](../../lib/http/) | The one loopback server entry, the bind, `Host` allowlist, header sets, and response kit both browser surfaces serve through. |
 | [`../../lib/web/index.ts`](../../lib/web/index.ts) | Shared Bytefly web brand system: tokens, base rules, `tok-*` colors, layout, the bootstrap, the toggle wiring, the shortcut sheet (`keysSheet`, `keysDialogScript`), and shared markup. |
 | [`../../lib/http/index.ts`](../../lib/http/index.ts) | Loopback HTTP layer shared with `file-browse`: the page policy and header sets, `ServeResponse`, the request-envelope helpers, bind/respond/close. |
 | `../../lib/policy.ts` | Shared read-only capability policy (default-deny + `readOnlyHint`). |
 | `../../lib/tui/chrome.ts` | Shared screen header, viewport-row helper, and styled key-hint footer. |
+
+## Testing
+
+```bash
+bun test extensions/plan
+```
+
+Eleven co-located suites, declared in `test/suite-manifest.ts`:
+
+- `plans.test.ts` — the plan-file store: naming, directory resolution, atomic
+  writes, `read`/`latest`/`index`, containment, `setSteps`, `saveFeedback`, and
+  step extraction.
+- `feedback.test.ts` — the comment codec: authored markers, stripping and
+  parsing, who a reviewer's write is signed by, carrying feedback onto a
+  revision, and displaying stored comments.
+- `tools.test.ts` — registration and all five tools, the approval merge into
+  `todo`, the session goal, and the call/result renderings.
+- `review-prompt.test.ts` — the compact remote prompt and its reply parser
+  against one action table.
+- `web.test.ts` — the browser review: the comment codec, the router, the page
+  roles and page shell, the client script, the stream, the plan-file poll, the
+  share rules, and a real loopback session.
+- `web-share.test.ts` — the LAN address selector, `shareUrl`, the link table with
+  its cap, and the reasons a share is unavailable.
+- `commands.test.ts` — `/plan review`, `/plan list`, `/plan share`, and the one
+  review gate shared by `exit_plan_mode` and the browser, including the abort and
+  baseline rules.
+- `runtime.test.ts` — tool gating, persistence and status, control-tool identity,
+  the review baseline, branch restore, the read-only git allowlist, and the
+  path-argument scan.
+- `tui.test.ts` — the review screen at fixed widths: Markdown body, scrolling,
+  section navigation, the gauge, footer hints, the approve question, the inline
+  refine editor, and the changed-section markers.
+- `sections.test.ts` — the fence-aware scan: heading shape, fences, the preamble,
+source lines and levels, and the occurrence key.
+- `extension.test.ts` — the Pi wiring: registration, the entry request, the
+  session lifecycle, the tool-call guard, injected context, the command, and the
+  shortcut.