pi-plan-task 1.1.0 → 4.0.0

package/README.md

@@ -1,136 +1,603 @@
 # 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](#state)
+- [Resume and recovery](#resume-and-recovery)
+- [Configuration](#configuration)
+- [Events](#events)
+- [Optional Plannotator integration](#optional-plannotator-integration)
+- [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.
+- 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. After a plan is submitted, choose `review` if the CLI is installed.
+
+## 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
+approve  lock the submitted plan (then choose here/new/fresh, or run /build later)
+review   open optional Plannotator review
+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, approve, and reject 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 approve` | Approve the submitted plan. Does not start execution. |
+| `/plan reject [feedback]` | Reject the submitted plan and initialize a revision draft. |
+
+The first argument to `/plan` is reserved when it is one of:
+
+```text
+approve reject request
+```
 
-Restarting Pi does not auto-start work. Run `/build` or `/goal` again.
+If the actual request starts with a reserved word, 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
+```
+
+`/plan approve` only locks the submitted structure. In a UI session it then asks where the next task should run (`here`, `new`, or `fresh`). In non-UI mode it stops after approval; run `/build` or `/build all` to execute. `/plan reject` works from `ready`, `approved`, `blocked`, or `completed`.
+
+#### 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.
+
+### `/build` — execution
 
-### `/plan` arguments
+| Command | Description |
+| --- | --- |
+| `/build` | Execute one pending task in this session. |
+| `/build all` | Execute all remaining tasks in this session. |
+
+`--all` is accepted as an alias for `all`. Unknown and duplicate options are rejected.
+
+After a single task is verified, a UI session asks:
 
+```text
+Continue in this session
+Continue in a new session
+Stop
 ```
-/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
+
+Choosing a new session persists `continueMode: "all-new"` and opens a replacement session that runs `/build` for the next task. `/build all` continues remaining tasks here without prompting. In non-UI modes, `/build` stops after the current task.
+
+#### Session placement
+
+Placement is chosen in UI prompts, not as `/build` flags:
+
+- `here` continues in the current session.
+- `new` records the current session as parent and opens a replacement session.
+- `fresh` is offered after `/plan approve` and opens a clean session without the planning conversation as parent context.
+- If session creation is cancelled, the plan remains approved and can be started again with `/build`.
+
+### `/tasks` — inspection and rework
+
+| Command | Description |
+| --- | --- |
+| `/tasks` | Show lifecycle status, work identity, approved hash, current task, and the canonical checklist. |
+| `/tasks rework <id>` | Reopen a verified task and every later task. |
+
+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.
+
+
+## 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"}
+```
 
-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:
+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.
 
-- `.plan_task/plan.md` and `.plan_task/task.md`
-- checklist lines in the form `- [ ] N. Title`
+### Unblock
 
-This package does not install or load a skill. It also does not modify Pi's system prompt.
+```json
+{"action":"unblock","id":1}
+```
 
-## Prompt injection
+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.
 
-Phase instructions are conversation messages, not system-prompt patches:
+Invalid tool actions fail without changing files, state, or emitting success events.
+
+## Task file contract
+
+`.plan_task/task.md` is the canonical execution queue and completion source. It must begin with numbered top-level checklist items:
+
+```markdown
+# Tasks
 
-- `/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.
+- [ ] 1. Add the login API
+- [ ] 2. Add the login UI
 
-Session history still stores the injected messages. Filtering is non-destructive.
+## Task 1: Add the login API
 
-## Ask user
+**Description:** Create the endpoint.
 
-`/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:
+**Acceptance criteria:**
+- [ ] Requests validate input.
+- [ ] Valid requests return 200.
 
-- 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
+**Verification:**
+- [ ] Run the focused API tests.
+- [ ] Run the typecheck.
 
-Do not also register another `ask_user_question` tool. The names collide and the schemas differ.
+## Task 2: Add the login UI
 
-## Files
+**Description:** Create the login form.
 
-Created in the current project:
+**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 workflow state and task runtime metadata
+├── draft/        # exists only while planning or revising
+│   ├── plan.md
+│   └── task.md
+├── history/      # immutable submitted-plan snapshots
+└── .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.
 
-Allowed `/plan` tools:
+### Task lifecycle
+
+```text
+pending → implementation-complete → verified
+    ↘               ↘
+          blocked
+```
 
-- Global: `~/.pi/agent/plan_task.json`
-- Project override: `.pi/plan_task.json`
+`unblock` restores the task to whichever active state existed before blocking.
+
+## State
+
+`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",
+  "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, and continuation policy. |
+| `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.
+
+## 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 payloads include 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.
+- An `implementation-complete` task that is resumed for verification 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, choose `review` after a plan is submitted. That opens the submitted plan for browser review. Approved results are normalized to `/plan approve`; annotated or rejected results are normalized to `/plan reject <feedback>`.
+
+If Plannotator is unavailable, use:
+
+```text
+/tasks
+/plan approve
+/plan reject <feedback>
+```
+
+## Troubleshooting
+
+### “Plan files changed after approval”
+
+The submitted structure no longer matches the approved hash. Inspect the files, then run:
+
+```text
+/tasks
+/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 snapshots. 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
+/tasks
+/plan approve
+/plan reject <feedback>
+```
+
+## 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 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