pi-plan-task 1.1.0 → 3.0.1

package/README.md

@@ -1,136 +1,701 @@
 # pi-plan-task
 
-[![npm version](https://img.shields.io/npm/v/pi-plan-task.svg)](https://www.npmjs.com/package/pi-plan-task)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+A safe, file-backed planning and execution workflow for [Pi](https://github.com/badlogic/pi-mono):
 
-One Pi package: `/plan`, `/build`, `/goal`, and `/tasks`. Progress lives on disk, so a new session or a Pi restart can continue from the next unfinished task.
+```text
+Plan → Review → Approve → Execute → Verify → Continue / Stop
+```
 
-Structured questions use [`@juicesharp/rpiv-ask-user-question`](https://pi.dev/packages/@juicesharp/rpiv-ask-user-question). This package does not register `ask_user_question`.
+`pi-plan-task` separates planning from implementation, binds approval to the exact submitted plan structure, executes one focused task at a time, and persists enough state to resume after reloads or session changes.
 
-## Install
+[![npm version](https://img.shields.io/npm/v/pi-plan-task.svg)](https://www.npmjs.com/package/pi-plan-task)
+[![License](https://img.shields.io/badge/license-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+
+## Contents
+
+- [Highlights](#highlights)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Commands](#commands)
+  - [`/plan`](#plan--planning-and-approval)
+  - [`/build`](#build--execution)
+  - [`/tasks`](#tasks--inspection-and-rework)
+- [LLM tool: `plan_task`](#llm-tool-plan_task)
+- [Task file contract](#task-file-contract)
+- [Durable files](#durable-files)
+- [Lifecycle](#lifecycle)
+- [State v2](#state-v2)
+- [Resume and recovery](#resume-and-recovery)
+- [Configuration](#configuration)
+- [Events](#events)
+- [Optional Plannotator integration](#optional-plannotator-integration)
+- [Upgrading to v3](#upgrading-to-v3)
+- [Legacy command migration](#legacy-command-migration)
+- [Troubleshooting](#troubleshooting)
+- [Development](#development)
+- [Safety notes](#safety-notes)
+## Highlights
+
+- Only three user-facing commands: `/plan`, `/build`, and `/tasks`.
+- Planning writes to an isolated `.plan_task/draft/` area.
+- Explicit approval is required before implementation.
+- Approval is revoked if submitted plan or task structure changes.
+- Task implementation and verification are separate states.
+- `task.md` is the single source of truth for execution progress.
+- One task can run here, in a new session, or in a clean session.
+- All remaining tasks can run here or one-per-session.
+- State updates are validated and serialized; multi-file changes use transactional replacement with rollback.
+- State v1 projects are backed up and migrated safely.
+- Optional Plannotator integration provides browser-based plan review.
+
+## Requirements
+
+- Pi with extension/package support.
+- `ask_user_question` is required at runtime when planning or execution reaches a consequential user decision.
+- Plannotator is optional and only needed for `/plan review`.
+
+## Installation
 
 ```bash
 pi install npm:@juicesharp/rpiv-ask-user-question
 pi install npm:pi-plan-task
 ```
 
-Restart Pi or run `/reload`. If juicesharp is missing, this package warns on session start.
+Restart Pi or run `/reload` after installation.
 
-Local checkout (development):
+For local development:
 
 ```bash
 pi install /absolute/path/to/pi-plan-task
 ```
 
-Or add the source to `packages` in `~/.pi/agent/settings.json`.
+Alternatively, add the package path to `packages` in `~/.pi/agent/settings.json`.
+
+## Quick start
+
+```text
+/plan Add OAuth login
+```
+
+When the draft is valid, choose one of:
+
+```text
+current  approve and execute in this session
+new      approve and execute in a normal new session
+fresh    approve and execute in a clean session
+review   open optional Plannotator review
+revise   edit a new draft with feedback
+reject   reject and revise with feedback
+later    leave the submitted plan ready for later approval
+```
+
+A typical flow is:
+
+1. Run `/plan <request>`.
+2. The agent writes `.plan_task/draft/plan.md` and `.plan_task/draft/task.md`.
+3. The extension validates both draft files.
+4. The valid draft is transactionally submitted as `.plan_task/plan.md` and `.plan_task/task.md`, with rollback on failure.
+5. Review or approve the submitted plan.
+6. Run one task with `/build`, or all remaining tasks with `/build all`.
+7. Each task follows `pending → implementation-complete → verified`.
+8. Only verification checks the task and permits progression.
+
+Execution is approval-gated. A missing, changed, or unapproved plan cannot start implementation.
 
 ## Commands
 
-| Command | What it does |
+The extension registers exactly three user-facing slash commands:
+
+```text
+/plan   create, review, and approve plans
+/build  execute one or all tasks
+/tasks  inspect and manage tasks
+```
+
+### `/plan` — planning and approval
+
+| Command | Description |
 | --- | --- |
-| `/plan [file or goal]` | Read-only planning. Writes `.plan_task/plan.md` and `.plan_task/task.md`. |
-| `/build` | Execute the next unfinished task in this session, then ask whether to continue here or in a new session. |
-| `/build new` | Same as `/build`, but start that task in a new session. |
-| `/goal` | Execute remaining tasks until `task.md` is complete. No session prompts. All in this session. |
-| `/goal new` | Same as `/goal`, but each remaining task starts in a new session. |
-| `/tasks` | Show the current task list and progress. |
+| `/plan` | Plan from the current conversation and repository. |
+| `/plan <request>` | Plan from a free-text request. |
+| `/plan <file> [notes]` | Use a repository spec file with optional guidance. |
+| `/plan request <text>` | Force text beginning with a reserved subcommand to be treated as a request. |
+| `/plan review` | Open the submitted `plan.md` in optional Plannotator. |
+| `/plan approve` | Interactively choose `current`, `new`, `fresh`, `revise`, or `cancel`. |
+| `/plan approve current` | Approve and execute the next task in this session. |
+| `/plan approve new` | Approve and execute the next task in a normal new session. |
+| `/plan approve fresh` | Approve and execute the next task in a clean session without parent conversation context. |
+| `/plan reject [feedback]` | Reject the submitted plan and initialize a revision draft. |
+| `/plan revise` | Initialize a revision draft and ask for revision feedback. |
+| `/plan status` | Show lifecycle state, work identity, progress, hash, and current task. |
+| `/plan history` | List immutable submitted-plan snapshots. |
+| `/plan diff` | Compare current submitted files with the newest valid snapshot. |
+
+The first argument to `/plan` is reserved when it is one of:
+
+```text
+review approve reject revise status history diff request
+```
 
-Restarting Pi does not auto-start work. Run `/build` or `/goal` again.
+If the actual request starts with one of those words, use `/plan request ...`:
 
-Session prompts only happen after a `/build` task finishes. `/goal` and `/goal new` never ask. Those prompts use this package's `select` dialog, not `ask_user_question`.
+```text
+/plan request review the login page accessibility
+```
+
+#### Draft behavior
+
+- New work receives a new `workId` and does not inherit old blocked/task runtime state.
+- Revision preserves the current submitted files until the new draft validates successfully.
+- An unchanged draft is not resubmitted.
+- Invalid or half-written drafts never replace current files.
+- Only draft files are writable during Plan mode.
 
-### `/plan` arguments
+### `/build` — execution
 
+| Command | Description |
+| --- | --- |
+| `/build` | Execute one pending task in this session. |
+| `/build new` | Execute one task in a normal new session. |
+| `/build fresh` | Execute one task in a clean session. |
+| `/build all` | Execute all remaining tasks in this session. |
+| `/build all new` | Execute one task per new session and continue automatically. |
+| `/build all fresh` | Start in a clean session, then execute all remaining tasks in that clean session. |
+| `/build all --approval` | Execute here and pause for approval after every verified task. |
+| `/build all new --approval` | Use one new session per task and pause after every verified task. |
+| `/build all fresh --approval` | Start in a clean session and pause after every verified task. |
+
+Long-form aliases are accepted:
+
+```text
+--all --new --fresh --approval
 ```
-/plan
-/plan Add login with OAuth
-/plan docs/auth-spec.md
-/plan docs/auth-spec.md focus on the callback flow
-/plan @docs/auth-spec.md
+
+Unknown, duplicate, and conflicting options are rejected. For example, `/build new fresh` is invalid.
+
+`--approval` applies only to all-task execution. In non-UI modes, per-task approval cannot prompt, so execution stops safely after the current task.
+
+#### Session placement
+
+- `new` records the current session as parent and opens a replacement session.
+- `fresh` opens a clean session without the planning conversation as parent context.
+- `/build all new` persists its continuation policy, so reloads and subsequent session handoffs resume one task per session.
+- If initial session creation is cancelled, the plan remains approved and can be started again.
+
+### `/tasks` — inspection and rework
+
+| Command | Description |
+| --- | --- |
+| `/tasks` | Show the canonical checklist and progress. |
+| `/tasks review [id]` | Show a task, its criteria, unstaged/staged changes, and untracked files. |
+| `/tasks rework <id>` | Reopen a verified task and every later task. |
+
+`/tasks review` truncates output at approximately 50 KB or 2000 lines. Use `git diff`, `git diff --cached`, and `git status --short` for complete output.
+
+Rework is intentionally strict:
+
+- The target must exist and already be verified.
+- The target and every later task return to `pending`.
+- Their top-level checklist items are unchecked.
+- Verification, completion, and block metadata are cleared.
+- Approval is revoked.
+- The plan returns to `ready` and must be approved again.
+
+Legacy standalone command names are not aliases. See [Legacy command migration](#legacy-command-migration).
+
+## LLM tool: `plan_task`
+
+`plan_task` is callable by the model; it is not a slash command.
+
+### Status
+
+```json
+{"action":"status"}
 ```
 
-If the first argument is an existing file — or looks like a path such as `./spec.md`, `notes.txt`, or `@spec.md` — that file is the spec. Anything after it is extra planning guidance. Missing explicit paths are rejected instead of being treated as a prompt.
+Returns the canonical checklist and progress.
 
-### `/build` and `/goal`
+### Complete implementation
 
+```json
+{"action":"complete","id":1}
 ```
-/build
-/build new
-/goal
-/goal new
+
+Valid only when:
+
+- the plan is `executing`;
+- the ID is the current task;
+- the task exists and is `pending`;
+- the submitted structure still matches the approved hash.
+
+`complete` changes task runtime state to `implementation-complete`. It does **not** check the task and does **not** advance execution.
+
+### Verify
+
+```json
+{"action":"verify","id":1,"reason":"Focused tests and typecheck passed"}
 ```
 
-`new` and `--new` are equivalent.
+Valid only for the current `implementation-complete` task and requires a non-empty verification result. A successful verification performs one serialized transaction that:
 
-- `/build` runs one task here. After it is marked complete, Pi asks whether to continue in this session or a new session.
-- `/build new` opens a new session for that one task, then asks the same question when it finishes.
-- `/goal` runs every remaining task in this session.
-- `/goal new` opens a new session for the next unfinished task, then another new session after each completed task, until the list is done.
+1. records `verified` state and evidence;
+2. checks the matching top-level item in `task.md`;
+3. persists state;
+4. emits `pi-plan-task:task-verified`;
+5. allows execution to continue.
 
-## Planning method
+### Block
 
-`/plan` uses `extensions/planning-and-task-breakdown.md` as the planning prompt.
+```json
+{"action":"block","id":1,"reason":"Waiting for API decision"}
+```
+
+Valid only for the current `pending` or `implementation-complete` task and requires a non-empty reason. The pre-block state is retained so the task can return to the correct state later.
 
-That file keeps the same section headings as `planning-and-task-breakdown.md`, so later methodology edits can be copied section-by-section from that source. Plan-task only changes output paths and the checklist form `/build` and `/goal` need:
+### Unblock
 
-- `.plan_task/plan.md` and `.plan_task/task.md`
-- checklist lines in the form `- [ ] N. Title`
+```json
+{"action":"unblock","id":1}
+```
 
-This package does not install or load a skill. It also does not modify Pi's system prompt.
+Restores a blocked task to `pending` or `implementation-complete`. It does not automatically start execution. If the whole plan was blocked, unblocking restores it to an approved, buildable state.
 
-## Prompt injection
+Invalid tool actions fail without changing files, state, or emitting success events.
 
-Phase instructions are conversation messages, not system-prompt patches:
+## Task file contract
 
-- `/plan`, `/build`, and `/goal` send a short visible user message to start the turn.
-- The planning method or current-task instructions are injected once, as a hidden message, when that phase or task starts.
-- Later turns in the same phase inject nothing unless the checklist actually changed; then a small build-status message is appended.
-- `context` keeps only the newest framing for the current phase. Stale plan/build messages are dropped from the model context. While idle, every injected message is filtered out.
+`.plan_task/task.md` is the canonical execution queue and completion source. It must begin with numbered top-level checklist items:
 
-Session history still stores the injected messages. Filtering is non-destructive.
+```markdown
+# Tasks
 
-## Ask user
+- [ ] 1. Add the login API
+- [ ] 2. Add the login UI
 
-`/plan`, `/build`, and `/goal` keep juicesharp's `ask_user_question` available and tell the model to call it for consequential choices the repo cannot answer:
+## Task 1: Add the login API
 
-- 1-4 questions per call, each with a short `header` and 2-4 described options
-- recommended option first, with `(Recommended)` on the label
-- do not author `Other` or `Type something.` — juicesharp appends a custom-answer row
+**Description:** Create the endpoint.
 
-Do not also register another `ask_user_question` tool. The names collide and the schemas differ.
+**Acceptance criteria:**
+- [ ] Requests validate input.
+- [ ] Valid requests return 200.
 
-## Files
+**Verification:**
+- [ ] Run the focused API tests.
+- [ ] Run the typecheck.
 
-Created in the current project:
+## Task 2: Add the login UI
 
+**Description:** Create the login form.
+
+**Acceptance criteria:**
+- [ ] The form submits valid credentials.
+
+**Verification:**
+- [ ] Run the focused UI tests.
 ```
-.plan_task/plan.md
-.plan_task/task.md
+
+Validation requires:
+
+- exact top-level format `- [ ] N. Title` or `- [x] N. Title`;
+- unique positive task IDs;
+- one matching `## Task N: Title` section per checklist item;
+- heading titles matching checklist titles;
+- a description, acceptance criteria, and verification instructions for every task;
+- no orphan or duplicate task headings.
+
+Nested acceptance/verification checkboxes are not execution tasks.
+
+Do not manually check top-level task items. Only a successful `plan_task verify` should do that.
+
+## Durable files
+
+```text
+.plan_task/
+├── plan.md       # submitted plan; immutable during execution
+├── task.md       # canonical queue and completion truth
+├── state.json    # validated state v2 and task runtime metadata
+├── draft/        # exists only while planning or revising
+│   ├── plan.md
+│   └── task.md
+├── history/      # immutable snapshots and migration backups
+└── .lock/        # short-lived cross-process workflow lock
 ```
 
-`task.md` must start with numbered checklist lines:
+Writes use:
 
-```markdown
-- [ ] 1. Add login API
-- [ ] 2. Add login UI
+- an in-process serial queue;
+- a project workflow lock;
+- random temporary file names;
+- atomic replacement with rollback for multi-file changes.
+
+A stale lock older than ten minutes may be removed during recovery.
+
+### Approval hash
+
+Approval stores a SHA-256 structure hash computed from:
+
+- the exact `plan.md` content;
+- the exact `task.md` content, except top-level `[ ]`/`[x]` progress markers are normalized.
+
+As a result:
+
+- normal verified-task progress does not invalidate approval;
+- changing task titles, bodies, criteria, verification steps, or plan context revokes approval;
+- `/build`, task mutation tools, task progression, and session recovery all enforce the approved hash;
+- a mismatch fails closed and returns the plan to `ready`.
+
+`plan.md` is not updated as tasks complete. Runtime progress exists only in `task.md` and `state.json`.
+
+## Lifecycle
+
+### Plan lifecycle
+
+```text
+idle → planning → ready → approved → executing → completed
+                    ↑          ↘         ↘
+                    └─ rework   blocked ──┘
 ```
 
-`/build` and `/goal` resume from the first unchecked item.
+Important rules:
 
-## Config
+- `planning → ready` only happens after a valid changed draft is submitted.
+- `ready → approved` recomputes and stores the approved structure hash.
+- `approved → executing` occurs only after files, state, hash, and queue are validated.
+- `executing → completed` requires every task to be checked **and** have `verified` runtime state.
+- If every remaining unchecked task is blocked, the plan becomes `blocked`; it is never reported complete.
+- Revision or rework clears approval.
+
+### Task lifecycle
+
+```text
+pending → implementation-complete → verified
+    ↘               ↘
+          blocked
+```
 
-Allowed `/plan` tools:
+`unblock` restores the task to whichever active state existed before blocking.
 
-- Global: `~/.pi/agent/plan_task.json`
-- Project override: `.pi/plan_task.json`
+## State v2
+
+`state.json` is validated before use. Unknown versions, malformed statuses, invalid IDs, invalid hashes, invalid dates, verified tasks without evidence, and blocked tasks without reasons fail closed.
+
+Example:
 
 ```json
 {
-  "planTools": ["read", "bash", "grep", "find", "ls", "pwsh", "rg"]
+  "version": 2,
+  "status": "executing",
+  "workId": "f2f0c9b4e4c1a2d3",
+  "planningRequest": "Add OAuth login",
+  "currentTaskId": 2,
+  "continueMode": "all-new",
+  "approvalEachTask": true,
+  "executionMode": "automatic",
+  "draftStructureHash": "0000000000000000000000000000000000000000000000000000000000000000",
+  "approvedStructureHash": "1111111111111111111111111111111111111111111111111111111111111111",
+  "sessionFile": "...",
+  "updatedAt": "2026-01-01T00:00:00.000Z",
+  "tasks": {
+    "1": {
+      "status": "verified",
+      "verification": "Focused tests passed",
+      "verifiedAt": "2026-01-01T00:00:00.000Z"
+    },
+    "2": {
+      "status": "implementation-complete",
+      "completedAt": "2026-01-01T00:05:00.000Z"
+    },
+    "3": {
+      "status": "blocked",
+      "reason": "Needs API decision",
+      "blockedFrom": "pending"
+    }
+  }
 }
 ```
 
-During `/plan`, `write` and `edit` stay available but can only touch the two plan files. Bash is limited to read-only commands. `plan_task` and `ask_user_question` stay available in every mode.
+Do not hand-edit `state.json` to bypass workflow checks.
+
+## Resume and recovery
+
+The extension restores persisted behavior during startup, reload, resume, and fork:
+
+| Persisted state | Restored behavior |
+| --- | --- |
+| `planning` | Restores Plan mode, draft write boundary, and planning request framing. |
+| `ready` | Leaves the submitted plan ready for review/approval. |
+| `approved` | Leaves the plan approved and ready to build after hash verification. |
+| `executing` | Restores current task, build framing, continuation policy, and task approval mode. |
+| `blocked` | Restores blocked state and reasons without reporting completion. |
+| `completed` | Preserves completed history; verified work can be explicitly reopened. |
+
+If approved files changed while Pi was not running, approval is revoked during recovery. If `state.json` is malformed, execution is disabled rather than guessing or overwriting the damaged state.
+
+## Configuration
+
+Configuration is merged in this order:
+
+1. defaults;
+2. global `~/.pi/agent/plan_task.json`;
+3. project `.pi/plan_task.json`.
+
+Example:
+
+```json
+{
+  "planTools": ["read", "grep", "find", "ls", "rg"],
+  "executionMode": "automatic"
+}
+```
+
+### `planTools`
+
+Read-only tools that may be used during Plan mode. Values are filtered through the extension's safe allowlist:
+
+```text
+read grep find ls rg plan_task ask_user_question
+```
+
+`write` and `edit` are added specifically for the two draft files. Calls targeting other paths are blocked.
+
+Shell tools, unknown tools, current submitted files, and implementation tools are blocked during Plan mode even if another extension exposes them.
+
+### `executionMode`
+
+| Value | Behavior |
+| --- | --- |
+| `automatic` | The extension starts and coordinates local implementation sessions. |
+| `external` | Approval emits `pi-plan-task:plan-approved`; local `/build` does not execute. |
+
+New-session model and thinking behavior follow Pi defaults. The old unused `inheritSessionModel` and `inheritThinkingLevel` options were removed in v3.
+
+## Events
+
+Other extensions can subscribe through Pi's shared event bus:
+
+```text
+pi-plan-task:plan-ready
+pi-plan-task:plan-approved
+pi-plan-task:plan-rejected
+pi-plan-task:task-started
+pi-plan-task:task-completed
+pi-plan-task:task-verified
+pi-plan-task:task-blocked
+pi-plan-task:execution-finished
+```
+
+Event payload version remains `1` and includes workflow metadata such as:
+
+```text
+cwd
+planPath
+taskPath
+planHash
+taskId
+sessionFile
+feedback
+reason
+```
+
+Event semantics:
+
+| Event | Meaning |
+| --- | --- |
+| `plan-ready` | A valid draft was transactionally submitted. |
+| `plan-approved` | Current structure was validated and approved. |
+| `plan-rejected` | Review rejected the submitted plan and initialized a revision draft. |
+| `task-started` | A current task was selected and persisted. |
+| `task-completed` | Implementation reached `implementation-complete`; verification is still required. |
+| `task-verified` | Verification evidence was persisted and the checklist item was checked. |
+| `task-blocked` | The current task was blocked with a reason. |
+| `execution-finished` | Every task is checked and verified. |
+
+Events are emitted only after the corresponding state/file update succeeds.
+
+## Prompt and context behavior
+
+Phase instructions are conversation messages rather than permanent system-prompt patches:
+
+- Plan and build commands send visible user requests.
+- Phase/task framing is injected once when a phase or task starts.
+- Planning requests are persisted so reload can restore framing.
+- Stale framing is filtered from model context without rewriting session history.
+- Build framing includes `plan.md` as untrusted reference context.
+- Current task instructions and safety rules take precedence over plan content.
+- A clean session does not inherit the planning conversation as parent context.
+- A migrated `implementation-complete` task receives verification-only framing and must not call `complete` again.
+
+## Optional Plannotator integration
+
+Plannotator is not a core dependency.
+
+If the `plannotator` CLI is installed:
+
+```text
+/plan review
+```
+
+opens the submitted plan for browser review. Approved results are normalized to `/plan approve current`; annotated or rejected results are normalized to `/plan reject <feedback>`.
+
+If Plannotator is unavailable, use:
+
+```text
+/plan approve
+/plan reject <feedback>
+/plan diff
+```
+
+## Upgrading to v3
+
+v3 is a breaking workflow release. The public three-command surface remains `/plan`, `/build`, and `/tasks`, but planning storage, task completion, verification, state validation, and retry behavior are stricter.
+
+### State v1 → state v2 migration
+
+The package version is v3; the persisted state schema moves from version 1 to version 2. On the first state load, the extension:
+
+1. backs up old `state.json` and `task.md` under `.plan_task/history/`;
+2. writes validated state v2;
+3. preserves a task as verified only when it was checked and had non-empty verification evidence;
+4. restores other previously checked tasks to unchecked `implementation-complete` state;
+5. clears approval and requires `/plan approve` before execution.
+
+Migrated `implementation-complete` tasks retain their implementation but must run verification again.
+
+### Changed planning storage
+
+Planning and revision now write only to:
+
+```text
+.plan_task/draft/plan.md
+.plan_task/draft/task.md
+```
+
+Current submitted files remain unchanged until the draft validates and is transactionally submitted.
+
+### Changed completion semantics
+
+In v2, `complete` could check a task. In v3:
+
+```text
+complete  implementation finished, verification pending
+verify    verification passed, task checked and eligible to advance
+```
+
+### Changed rework semantics
+
+`/tasks rework <id>` now reopens the selected verified task and every later task, revokes approval, and requires a new approval before execution.
+
+### Removed configuration
+
+The unused options below are ignored and should be deleted:
+
+```json
+{
+  "inheritSessionModel": true,
+  "inheritThinkingLevel": true
+}
+```
+
+## Legacy command migration
+
+If upgrading from a release older than the three-command interface, use these replacements:
+
+| Removed | Replacement |
+| --- | --- |
+| `/plan-review` | `/plan review` |
+| `/plan-approve` | `/plan approve` |
+| `/plan-reject` | `/plan reject` |
+| `/plan-status` | `/plan status` |
+| `/plan-history` | `/plan history` |
+| `/plan-diff` | `/plan diff` |
+| `/goal` | `/build all` |
+| `/task-review` | `/tasks review` |
+| `/task-rework` | `/tasks rework` |
+| `/build-next-session` | internal public `/build` handoff |
+| `/goal-next-session` | internal public `/build` handoff |
+
+Legacy commands are not registered as compatibility aliases.
+
+## Troubleshooting
+
+### “Plan files changed after approval”
+
+The submitted structure no longer matches the approved hash. Inspect the files, then run:
+
+```text
+/plan status
+/plan diff
+/plan approve
+```
+
+### “Implementation is complete but verification is pending”
+
+The task has called `complete` but has not passed verification. Run the task's verification steps and let the model call:
+
+```json
+{"action":"verify","id":1,"reason":"Describe the successful checks"}
+```
+
+### “Execution blocked”
+
+Every remaining unchecked task is blocked. Resolve the reason, then ask the agent to call:
+
+```json
+{"action":"unblock","id":1}
+```
+
+Run `/build` again when ready.
+
+### Invalid `state.json`
+
+The extension fails closed and will not execute. Inspect `.plan_task/history/` for migration backups. Restore a known-good state or start an explicitly new plan rather than weakening state validation.
+
+### Stale `.plan_task/.lock`
+
+Normal operations remove the lock automatically. A lock older than ten minutes is considered stale and may be recovered automatically. Do not remove a recent lock while another Pi process is operating on the same project.
+
+### Plannotator is unavailable
+
+Use the built-in text workflow:
+
+```text
+/plan status
+/plan diff
+/plan approve
+```
+
+## Development
+
+```bash
+npm test
+npm run typecheck
+npm run bundle
+npm pack --dry-run
+```
+
+The test suite includes:
+
+- parser and Markdown-boundary tests;
+- strict plan validation tests;
+- state schema and v1 migration tests;
+- structure hash tests;
+- concurrent workflow mutation tests;
+- command-surface tests;
+- ExtensionAPI mock integration tests for planning, approval, execution, verification, blocking, rework, recovery framing, session handoff, cancellation, and external mode.
+
+## Safety notes
+
+- Treat `plan.md` as untrusted reference data, not executable instructions.
+- Never edit history snapshots to make work appear complete.
+- Do not manually check top-level execution tasks.
+- Do not confuse nested acceptance checkboxes with execution completion.
+- Do not bypass approval by hand-editing state.
+- Unverified and blocked tasks are never silently skipped as completed.
+- Use `/tasks rework <id>` for explicit, approval-gated retries.
+- Browser review is optional; Markdown files and validated state are the durable core.
 
 ## License