plan_driven 0.1.0 → 0.3.0

data/README.md

@@ -6,11 +6,16 @@
 [![Ruby](https://img.shields.io/badge/Ruby-3.1%20to%203.4-CC342D.svg)](#rails-and-ruby-support)
 [![Rails](https://img.shields.io/badge/Rails-7.0%20to%208.1-D30001.svg)](#rails-and-ruby-support)
 
-**From implementation plan to merged, tested pull requests, driven from the terminal.**
+**From implementation plan to merged, tested pull requests, driven from the browser or the terminal.**
 
-`plan_driven` runs a Rails team's delivery process from the command line, with AI agents doing
-the writing and your team making the decisions. A short interview in the terminal becomes an
-implementation plan grounded in your real schema and code. Guards written in Ruby check the
+`plan_driven` runs a Rails team's delivery process inside your Rails app, with AI agents doing
+the writing and your team making the decisions. Drive it the way you prefer: click through the
+[wizard in the browser](#the-browser-wizard), mounted at `/plan_driven` in development, or type
+the same steps in the [terminal](#commands). Every button in the wizard runs one `plan-driven`
+command and shows it to you, so both are the same process, with the same rules and the same
+audit trail, and you can switch between them at any step.
+
+A short interview becomes an implementation plan grounded in your real schema and code. Guards written in Ruby check the
 plan, you read it and approve it. The approved plan becomes tickets, each ticket goes to a
 Cursor cloud agent that opens a pull request, and only the pull requests you approve are
 merged. Acceptance criteria map to Cucumber scenarios, so the delivery report shows which
@@ -24,10 +29,50 @@ Zagreb. [Need Rails engineers?](#about-rubycode)
 
 ## Watch it deliver a feature
 
-[![Watch the plan_driven demo (25 min)](docs/images/demo.png)](https://github.com/blaz1988/plan-driven/releases/download/v0.1.0/plan-driven-demo.mp4)
+[![Watch the plan_driven wizard demo (12 min)](docs/images/wizard-demo.png)](https://github.com/blaz1988/plan-driven/releases/download/v0.1.0/plan-driven-wizard.mp4)
+
+**[▶ Watch the wizard demo](https://github.com/blaz1988/plan-driven/releases/download/v0.1.0/plan-driven-wizard.mp4)**
+(12 minutes, narrated, with captions). One feature, comments on events, is delivered from
+the [browser wizard](#the-browser-wizard) in [Gather](https://github.com/blaz1988/gather):
+the plan drafted and one section redrafted, six tickets as issues
+([#34](https://github.com/blaz1988/gather/issues/34) to
+[#39](https://github.com/blaz1988/gather/issues/39)), six agents and six pull requests
+([#40](https://github.com/blaz1988/gather/pull/40) to
+[#45](https://github.com/blaz1988/gather/pull/45)), one round of feedback, and 42 of 42
+acceptance criteria proven by a passing scenario. After every click the video zooms into the
+wizard's terminal panel, which shows the `plan-driven` command that ran and its output. The
+wizard ships with 0.2.0.
+
+<details>
+<summary>Chapters</summary>
+
+| Time | Chapter |
+| ---: | --- |
+| 0:00 | What plan_driven is |
+| 0:24 | Installing it, and how the wizard works |
+| 1:13 | `doctor`, from the wizard |
+| 1:48 | The interview as a form, and the draft |
+| 2:43 | Reading the plan, redrafting a section, submitting and approving |
+| 3:51 | Tickets drafted and approved, as GitHub issues |
+| 4:37 | Starting the agents |
+| 5:18 | Refreshing, and `review` |
+| 6:01 | Reading the first pull request |
+| 6:46 | Approving and merging, and the next agent starts |
+| 7:43 | Feedback to the agent on T3 |
+| 8:24 | Every ticket merged |
+| 8:53 | Evidence (42 of 42), tokens, and the delivery report |
+| 9:47 | Reading the delivery report |
+| 10:11 | The feature in the app |
+| 10:46 | The same commands in a terminal |
+| 11:22 | Recap |
+
+</details>
+
+### The CLI deep dive
 
-**[▶ Watch the demo](https://github.com/blaz1988/plan-driven/releases/download/v0.1.0/plan-driven-demo.mp4)**
-(25 minutes, narrated, with captions). One feature, RSVPs with a waitlist, goes from an
+**[▶ Watch the CLI demo](https://github.com/blaz1988/plan-driven/releases/download/v0.1.0/plan-driven-demo.mp4)**
+(28 minutes, narrated, with captions), for everything the wizard runs, typed in a terminal.
+One feature, RSVPs with a waitlist, goes from an
 idea to production code in a new Rails 8 app,
 [Gather](https://github.com/blaz1988/gather). Nothing in it is staged: the plan, the five
 tickets, the five pull requests ([#8](https://github.com/blaz1988/gather/pull/8) to
@@ -44,18 +89,20 @@ repository. The planner and the five agents ran on Claude Opus 5.5 through Curso
 | 2:49 | `doctor`: keys, repository and the Cursor connection |
 | 3:15 | The interview |
 | 4:14 | Reading the implementation plan |
-| 6:05 | Deciding the open questions, then approving |
-| 7:20 | Tickets: drafted, steered to five, read and approved |
-| 9:42 | The tickets as GitHub issues |
-| 10:12 | What the agent is told, and starting the first agent |
-| 11:08 | Reading the first pull request, `review`, `approve-pr` and `merge` |
-| 13:18 | The model and its rules (T2) |
-| 15:22 | The RSVP card, tried on the branch before merging (T3) |
-| 17:41 | Feedback: a behind-main warning and a refactor (T5) |
-| 20:12 | The organizer's attendee list (T4) |
-| 21:47 | Evidence: 33 of 33 acceptance criteria, and the delivery report |
-| 23:01 | The finished feature in the app |
-| 24:12 | Recap |
+| 6:05 | Deciding the open questions with `redraft` |
+| 6:50 | Every section can be changed: Database changes redrafted and edited in vim (PD-2) |
+| 9:51 | Submitting and approving the plan |
+| 10:23 | Tickets: drafted, steered to five, read and approved |
+| 12:44 | The tickets as GitHub issues |
+| 13:15 | What the agent is told, and starting the first agent |
+| 14:10 | Reading the first pull request, `review`, `approve-pr` and `merge` |
+| 16:21 | The model and its rules (T2) |
+| 18:25 | The RSVP card, tried on the branch before merging (T3) |
+| 20:44 | Feedback: a behind-main warning and a refactor (T5) |
+| 23:15 | The organizer's attendee list (T4) |
+| 24:50 | Evidence: 33 of 33 acceptance criteria, and the delivery report |
+| 26:04 | The finished feature in the app |
+| 27:15 | Recap |
 
 </details>
 
@@ -65,11 +112,16 @@ repository. The planner and the five agents ran on Claude Opus 5.5 through Curso
 - [Requirements](#requirements)
 - [Installation](#installation)
 - [Getting your app ready](#getting-your-app-ready)
+- [The browser wizard](#the-browser-wizard)
 - [Walkthrough: one feature from idea to merged](#walkthrough-one-feature-from-idea-to-merged)
 - [Guards](#guards)
 - [What the agent is told](#what-the-agent-is-told)
 - [Commands](#commands)
 - [Configuration](#configuration)
+- [Choosing the coding agents](#choosing-the-coding-agents)
+- [Tokens and cost](#tokens-and-cost)
+- [Statistics](#statistics)
+- [How it compares](#how-it-compares)
 - [Keys](#keys)
 - [Working as a team](#working-as-a-team)
 - [Troubleshooting](#troubleshooting)
@@ -93,7 +145,7 @@ repository. The planner and the five agents ran on Claude Opus 5.5 through Curso
  plan-driven approve-tickets  ─▶ tickets approved     GitHub issues created
         │
         ▼
- plan-driven develop      one Cursor cloud agent per ready ticket, one PR each
+ plan-driven develop      one agent per ready ticket (Cursor cloud, or a local CLI), one PR each
  plan-driven status       agent finished ─▶ PR open
  plan-driven review       PrGuard: scope, specs, Cucumber scenarios, CI, up to date
  plan-driven feedback     the same agent pushes a fix to the same PR
@@ -102,7 +154,7 @@ repository. The planner and the five agents ran on Claude Opus 5.5 through Curso
         │
         ▼
  plan-driven evidence     Cucumber results mapped to acceptance criteria
- plan-driven report       docs/plans/pd-1-…/delivery-report.pdf
+ plan-driven report       docs/plans/pd-1-…/delivery-report.pdf, with tokens and cost
 ```
 
 Phases are stored in your application's database, so a plan can't skip a step. Tickets can't
@@ -119,9 +171,12 @@ model as a list to fix, and a plan that still fails isn't accepted.
 
 - Ruby 3.1+ and Rails 7.0+ (see [support](#rails-and-ruby-support)).
 - The application on GitHub, with CI running on pull requests.
-- A [Cursor](https://cursor.com) account with the GitHub integration connected to that
-  repository, and a Cursor API key (Cursor dashboard, Integrations). The agents run as
-  Cursor cloud agents.
+- Coding agents, one of (see [Choosing the coding agents](#choosing-the-coding-agents)):
+  - **Cursor cloud agents** (the default): a [Cursor](https://cursor.com) account with the
+    GitHub integration connected to that repository, and a Cursor API key (Cursor dashboard,
+    Integrations).
+  - **A local agent CLI** (`agent_provider :local`): Claude Code, Codex, the Cursor CLI or any
+    command that edits files in its working directory, plus `git` push access to the repository.
 - A model for drafting plans and tickets, one of:
   - **Cursor** (`llm_provider :cursor`): any model on your Cursor account, Claude Opus 5.5 by
     default. Needs Node 22.13+ and the Cursor SDK. No other LLM key.
@@ -204,7 +259,7 @@ into your application. See [Keys](#keys).
 ```
 $ bin/plan-driven doctor
 
-plan-driven 0.1.0
+plan-driven 0.2.0
 ✓ Rails application: plan_driven tables present
 LLM: cursor/claude-opus-5-5
 ✓ Cursor SDK: Node v24.21.0, @cursor/sdk found
@@ -263,6 +318,81 @@ config.extra_context = "Gather lists community events. An event has an organizer
 **Who approves.** `plan_approvals` and `ticket_approvals` list the roles that must sign off,
 for example `%w[review qa devops director]`. One person can hold every role on a small team.
 
+## The browser wizard
+
+Not everyone wants to drive a delivery from the terminal. The install generator mounts a
+wizard in your app, in development only:
+
+```ruby
+# config/routes.rb
+mount PlanDriven::Wizard::Engine, at: "/plan_driven" if Rails.env.development?
+```
+
+Start the app and open `http://localhost:3000/plan_driven`. It walks a plan through the same
+five steps, with Back and Next: **Plan** (the interview, then read, edit or redraft any section
+and submit), **Approve**, **Tickets**, **Agents & PRs** and **Proof & report**. A step opens
+once the plan has reached it.
+
+The wizard is a front end for the CLI, not a second implementation. Every button runs one
+`plan-driven` command in the background, and the panel on the right shows that command and its
+output as it runs, exactly as you'd see it in a terminal:
+
+![The wizard's Approve step, with the command it ran and its output](docs/images/18-wizard.png)
+
+```
+$ bin/plan-driven edit PD-3 database_changes --from tmp/plan_driven/wizard/sections/PD-3-database_changes-1f2e.md --yes
+✓ Database changes updated; PD-3 is now revision 2 (draft)
+✓ All checks passed
+```
+
+So anything done in the browser can be repeated, scripted or reviewed from the terminal, and
+the audit trail is the same either way. A few things to know:
+
+- Only a fixed list of commands can run, built from the form fields as an argument list, never
+  through a shell. A key pasted on the Configuration page goes to `plan-driven connect` on
+  stdin, so it's never in the command line, the panel or the logs.
+- It answers local requests only, and only in development. `config.wizard_enabled = true`
+  turns it on in another environment, still for local requests only.
+- "Acting as" at the top sets `PLAN_DRIVEN_ACTOR` for the commands it runs, so approvals are
+  recorded under the name you give; it defaults to your git identity.
+- Each run is kept in `tmp/plan_driven/wizard/`: the command, its output and its exit status.
+
+### Configuration: connections and the interview
+
+**Configuration**, at the top of every page, has two parts.
+
+**Connections** shows which services this app's configuration uses (Cursor for cloud agents
+or drafting, OpenAI or Anthropic for drafting, GitHub for issues and pull requests), whether
+each one has a key, and where the key comes from. Paste a key and click Connect:
+`plan-driven connect cursor` checks it with the service first (for Cursor, the account it
+belongs to) and only then stores it in `~/.plan_driven/config`. A refused key is never stored.
+**Check every connection** runs `doctor`. The same works in the terminal:
+
+```
+$ bin/plan-driven connect cursor
+Cursor key:
+Checking the key with Cursor...
+✓ Cursor: connected as ana@example.com
+  stored in ~/.plan_driven/config (0600), never in the app
+```
+
+Which model drafts and which agents write the code are still set in the initializer (see
+[Choosing the coding agents](#choosing-the-coding-agents)); the page shows the current choice.
+
+**Interview questions** lists what `plan-driven new` and the New plan form ask. Change a
+question's title or wording, make it required or optional, add your own questions, or put one
+back to the default. Each Save runs `plan-driven question`:
+
+```
+$ bin/plan-driven question success_metric --title "Success metric" --ask "How will we know it worked?" --optional
+✓ Question success_metric added
+```
+
+The changes are written to `config/plan_driven/interview.yml` in your app. Commit it, and the
+whole team gets the same interview, in the wizard and in the terminal. An added question goes
+to the model with the other answers, and it's a section of the plan under the group you pick.
+Drafted sections (Database changes, Risks...) belong to the model and can't be changed here.
+
 ## Walkthrough: one feature from idea to merged
 
 This is the run from the demo video, in [Gather](https://github.com/blaz1988/gather), with the
@@ -319,8 +449,22 @@ column it cites exists.
 
 ![The plan, grounded in the real schema](docs/images/03-plan.png)
 
-Change what isn't right. `edit` opens a section in `$EDITOR`. `redraft` has the model rewrite
-one section from an instruction, which is the quickest way to record decisions:
+**Every section of the plan can be changed**, not only Outstanding questions: What, Why,
+Database changes, Application changes, Risks, Testing, any of them (the keys are listed under
+[Commands](#commands)). The draft is the model's proposal, and your team has the final say.
+There are two ways to change a section:
+
+- `edit PLAN SECTION` opens the section in `$VISUAL` or `$EDITOR` as Markdown. Use it for exact
+  changes: a column, a name, a step, a test case.
+- `redraft PLAN SECTION "instruction"` has the model rewrite only that section, following your
+  instruction. It reads the rest of the plan and the code while it does.
+
+Either way the change becomes a new revision, the plan goes back to draft, the guards run again
+and the Markdown, HTML and PDF are written again. `plan-driven log PLAN` lists every change.
+Change the plan through these commands, not by editing `plan.md`: the database is the source,
+and the files are rendered from it.
+
+`redraft` is also the quickest way to record decisions:
 
 ```
 $ bin/plan-driven redraft PD-1 outstanding_questions "Record my answers under Decided and keep only
@@ -337,6 +481,80 @@ Redrafting outstanding_questions...
 
 ![The decisions, recorded in the plan](docs/images/04-plan-decided.png)
 
+#### Example: changing the database design
+
+The agent's draft is a starting point, and the database design is where teams most often
+disagree with it. In Gather's second plan, PD-2 (event categories), the model suggested a string
+column on `events`:
+
+```
+$ bin/plan-driven show PD-2 --section database_changes
+### Step 1: Expand (migration `AddCategoryToEvents`)
+
+On table `events`:
+- Add column `category`: type `string`, **nullable**, default `'meetup'`.
+- Add composite index `index_events_on_category_and_starts_at` on `[:category, :starts_at]`. ...
+```
+
+The team wanted a table instead. `redraft` rewrites the section to that design, keeping the
+expand and contract steps:
+
+```
+$ bin/plan-driven redraft PD-2 database_changes "Use a categories table instead of a string column:
+  name and slug, seeded with meetup, workshop, talk and conference, and a category_id reference on events."
+Redrafting database_changes...
+Categories live in their own `categories` table, and each event points to one of them through
+`events.category_id`. ...
+### Step 1: Expand
+#### Migration `CreateCategories`
+New table `categories`:
+- `name` string, **not null**, no default. ...
+- `slug` string, **not null**, no default. ...
+...
+### Step 5: Contract (migration `EnforceCategoryOnEvents`)
+- `change_column_null :events, :category_id, false`.
+✓ All checks passed
+```
+
+A small change doesn't need the model. `edit` opens the section in your editor. Here, a `color`
+column is added to the new table, in the column list, the migration and the resulting schema:
+
+```
+$ EDITOR=vim bin/plan-driven edit PD-2 database_changes
+✓ Database changes updated; PD-2 is now revision 3 (draft)
+✓ All checks passed
+```
+
+![Adding a column to the plan in vim](docs/images/04b-edit-section.png)
+
+The guards check your edit the same way they check the model's draft (see [Guards](#guards)),
+and anything that fails is listed right after you save. `submit` refuses a plan with errors.
+
+Other sections that depend on the change follow the same way. The model reads the whole plan,
+so it picks up the new table and the `color` column:
+
+```
+$ bin/plan-driven redraft PD-2 application_changes "Follow the new Database changes: a Category model,
+  events.category_id instead of an enum, and the category colour on the card badge."
+...
+✓ All checks passed
+
+$ bin/plan-driven submit PD-2
+✓ PD-2 revision 4 is in review
+
+$ bin/plan-driven log PD-2
+When              Event         Ticket  By                         Details
+2026-09-30 10:07  plan.drafted          Ivan Blažević <ivan...>    model=cursor/claude-opus-5-5 ...
+2026-09-30 10:10  plan.revised          Ivan Blažević <ivan...>    sections=database_changes
+2026-09-30 10:16  plan.revised          Ivan Blažević <ivan...>    sections=database_changes
+...
+```
+
+You can change a plan in draft, in review and after it's approved. An approval belongs to a
+revision, so a changed plan must be approved again. Once its tickets are drafted, the plan is
+locked, because the tickets and pull requests were built from it. Changes after that go into a
+follow-up plan.
+
 ### 3. Submit and approve
 
 ```
@@ -505,8 +723,9 @@ $ bin/plan-driven report PD-1
 
 `evidence` runs the plan's scenarios on your machine and stores the result with the commit it
 ran on; `--from cucumber.json` imports a run from CI instead. The delivery report lists each
-ticket with its pull request, merge commit and approver, then every acceptance criterion with
-the scenario that proves it, the guard findings, every approval and the full timeline. Commit
+ticket with its pull request, merge commit and approver, the [statistics](#statistics) with
+their charts, then every acceptance criterion with the scenario that proves it, marked passed
+or failed in colour, the guard findings, every approval and the full timeline. Commit
 `docs/plans/` with it, and the plan and its proof stay next to the code.
 
 ![The delivery report](docs/images/15-delivery-report.png)
@@ -530,8 +749,12 @@ An error blocks the next step and a warning is shown and recorded.
 
 **MigrationGuard** reads the database changes:
 
-- removing or renaming a column or table in one step is an error, unless the plan stages it
-  with `ignored_columns`, expand and contract, or a later release;
+- removing or renaming a column or table in one step is an error. Each change is judged on its
+  own, sentence by sentence and line by line in migration code: it's accepted only when that
+  sentence stages it (`ignored_columns`, a later release, after the backfill) or when it sits
+  under a contract, cleanup or later step. Mentioning "expand" somewhere else in the section
+  doesn't excuse it. Headings, negated sentences ("No column is removed"), rollback notes and
+  tables the plan itself creates don't count as removals;
 - NOT NULL on an existing table without a default or backfill is a warning;
 - on PostgreSQL, an index that isn't built concurrently is a warning.
 
@@ -623,14 +846,19 @@ key such as `PD-1`, and `PLAN/TICKET` is a ticket such as `PD-1/T3`.
 | `evidence PLAN [--from FILE]` | Run or import Cucumber results |
 | `report PLAN` | Write the delivery report |
 | `log PLAN` | The audit trail |
+| `usage PLAN` | Tokens, time and cost per step and per agent run |
+| `stats PLAN` | Where the time went: phases, agents and people, each ticket |
+| `questions` | The interview's questions, and which ones the team changed or added |
+| `question KEY [--title T] [--ask Q] [--group G] [--required \| --optional] [--remove]` | Change or add an interview question, or put it back |
 | `configure` | Store keys in `~/.plan_driven/config` |
-| `doctor` | Check keys, repository, PDF browser and the Cursor connection |
+| `connect SERVICE` | Check a key with `cursor`, `openai`, `anthropic` or `github`, then store it |
+| `doctor` | Check keys, repository, PDF browser, and the Cursor connection or local agent command |
 
 Section keys for `show --section`, `edit` and `redraft`: `what`, `why`, `where`, `who`,
 `when`, `background`, `existing_data_structure`, `architecture`, `database_changes`,
 `application_changes`, `infrastructure_changes`, `out_of_scope`, `risks`, `performance`,
-`security`, `monitoring`, `outstanding_questions` and `testing`. `edit PLAN` without a section
-lists them.
+`security`, `monitoring`, `outstanding_questions` and `testing`, plus any question the team
+added. `edit PLAN` without a section lists them.
 
 `--yes` skips confirmations, for scripts. `merge` still needs the ticket key typed unless
 `--yes` is given.
@@ -657,11 +885,17 @@ PlanDriven.configure do |config|
   config.plan_approvals = %w[review]            # e.g. %w[review qa devops director]
   config.ticket_approvals = %w[review]
 
-  # Cursor cloud agents
-  config.agent_model = nil                      # nil uses your Cursor default
+  # Coding agents
+  config.agent_provider = :cursor               # or :local, see "Choosing the coding agents"
+  config.agent_command = nil                    # :local only, e.g. "claude -p --permission-mode acceptEdits --output-format json"
+  config.agent_timeout = 3600                   # :local only; seconds before a run is stopped
+  config.agent_model = nil                      # :cursor; nil uses your Cursor default
   config.base_branch = "main"
   config.max_parallel_agents = 3
-  config.skip_reviewer_request = false          # true: the agent doesn't request you as reviewer
+  config.skip_reviewer_request = false          # :cursor; true: the agent doesn't request you as reviewer
+
+  # Tokens and cost: dollars per million tokens, by model id. None ship with the gem.
+  config.token_prices = {}                      # { "model-id" => { input: 3.0, output: 15.0, cache_write: 3.75, cache_read: 0.3 } }
 
   # GitHub
   config.github_repository = nil                # "owner/name"; read from the origin remote when nil
@@ -695,6 +929,172 @@ plan and can't change a file.
 
 `config.template` replaces the plan's sections if your template differs.
 
+## Choosing the coding agents
+
+Every ticket goes to one agent, which works on its own branch and opens one pull request. The
+rest of the workflow is the same whichever agents you use: `review`, `feedback`, `approve-pr`
+and `merge` see only the pull request.
+
+**Cursor cloud agents** (`agent_provider :cursor`, the default) run on Cursor-hosted machines
+against a fresh clone of the repository, so nothing runs on your laptop and several tickets
+can run at once. `config.agent_model` picks the model.
+
+**A local agent CLI** (`agent_provider :local`) runs a command on your machine. Each ticket
+gets its own git worktree and branch under `tmp/plan_driven/agents`, so tickets don't touch
+your working copy or each other. The command gets the same prompt a cloud agent gets, on stdin,
+or wherever the command says `{prompt_file}`. When it exits cleanly, plan_driven commits what
+it left, pushes the branch and opens the pull request, using the description the agent wrote
+to `PR_DESCRIPTION.md`. Feedback runs the command again in the same worktree and pushes to the
+same pull request. After the merge, the worktree and the local branch are removed.
+
+```ruby
+config.agent_provider = :local
+
+# Claude Code
+config.agent_command = "claude -p --permission-mode acceptEdits --output-format json"
+# Codex
+config.agent_command = "codex exec --full-auto -"
+# The Cursor CLI
+config.agent_command = 'cursor-agent -p --force --output-format json "$(cat {prompt_file})"'
+```
+
+A local agent runs with your permissions and your shell, so give it only the tools it needs to
+edit and to run the test suite, and read the pull request as carefully as a cloud agent's.
+Runs longer than `config.agent_timeout` (an hour by default) are stopped. The Cursor CLI setup
+is the one tested end to end; flags change between CLI versions, so check your CLI's `--help`.
+`plan-driven doctor` checks that the command is on the `PATH`.
+
+## Tokens and cost
+
+Every model call and every agent run is recorded with the tokens it used: drafting the plan,
+each `redraft`, drafting the tickets, and each agent run and follow-up, with its duration.
+`plan-driven usage PD-1` prints them, and the delivery report has a Tokens and cost table.
+
+Prices change and differ per account, so the gem ships none: put what your provider charges in
+`config.token_prices` (dollars per million tokens, with separate cache prices), and the report
+shows dollars next to the tokens. Without a price you still get the tokens and the time.
+
+Cursor reports tokens for every cloud agent run. A local CLI's tokens are recorded when it
+prints them the way Claude Code's `--output-format json` does; otherwise only the time is.
+
+For scale, these are the five cloud agents from the demo, read back from Cursor's usage API
+(T4 and T5 include their feedback runs):
+
+| Ticket | Runs | Output tokens | Cache reads | Total tokens |
+| --- | ---: | ---: | ---: | ---: |
+| T1 migration | 1 | 13,861 | 738,595 | 791,861 |
+| T2 model rules | 1 | 21,037 | 1,519,826 | 1,596,409 |
+| T3 RSVP card | 1 | 16,611 | 1,161,514 | 1,242,945 |
+| T4 attendee list | 2 | 10,957 | 1,083,671 | 1,149,274 |
+| T5 seats on the index | 2 | 12,725 | 1,154,333 | 1,248,462 |
+| **Total** | 7 | **75,191** | **5,657,939** | **6,028,951** |
+
+94% of the tokens are cache reads, which cost a fraction of fresh input, and only 75 thousand
+are code and text the agents wrote. Most of an agent's tokens go into reading the codebase, so
+a small, conventional one is cheaper to work on.
+
+## Statistics
+
+Where did the time go? Was it the agents writing code, or the pull requests waiting for a
+person? The same numbers are in three places:
+
+- **In the wizard:** every plan has a Statistics page, linked under its title and from the
+  Proof & report step. In development that's `http://localhost:3000/plan_driven/plans/PD-1/statistics`.
+- **In the terminal:** `bin/plan-driven stats PD-1`.
+- **In the delivery report:** a Statistics section with the same charts, in the Markdown, the
+  HTML and the PDF.
+
+![The Statistics page in the wizard, for a delivered plan](docs/images/statistics.png)
+
+This is PD-3 from the demo: six tickets delivered in 1 h 20 min, 42 of 42 criteria proven.
+
+- **Cards:** idea to delivery, development time, criteria proven, pull requests approved the
+  first time, the agents' share of the work, and tokens.
+- **Acceptance criteria, merged and proven:** a burn-up against the plan's scope. The blue
+  line rises as each ticket merges with its criteria, and the green line rises when an
+  evidence run proves them. Every run is a dot, red when it failed. Here, two runs failed
+  around 14:50 and the third proved all 42.
+- **Where the time went, ticket by ticket:** one row per ticket on a shared clock. Grey is
+  queued, waiting for the tickets it depends on. Blue is an agent coding, amber is the pull
+  request waiting for review, purple is an agent fixing feedback, and green is approved but
+  not merged. T3 has one round of feedback, and each ticket waited for the one before it.
+- **Agents and people:** how the time tickets were worked on splits. Here agents took 91% of
+  it and reviews took 7%. On a plan where the donut is mostly amber, the bottleneck is review,
+  not code.
+- **Ticket by ticket, and the phases:** the same times as a table, with the estimate and the
+  review rounds, and how long planning, tickets, development and proof took.
+
+```
+$ bin/plan-driven stats PD-3
+PD-3 Comments on events: statistics
+  Planning              2 min
+  Tickets               2 min
+  Development           1 h 20 min
+  Proof                 10 min
+  Idea to delivery      1 h 25 min
+  Tickets merged        6 of 6, 5 approved the first time
+✓ 42 of 42 acceptance criteria proven
+
+Where the time went while tickets were worked on (agents 91%):
+  Agent coding           1 h 2 min  ████████████████████ 79%
+  Waiting for review         5 min  ██ 7%
+  Agent fixing feedback      9 min  ███ 12%
+  Approved, not merged       1 min  █ 2%
+
+#   Est  Queued      Agent   Review  Fixes  Merge  Rounds  Total
+T1  2    53s         10 min  4 min   -      23s    0       16 min
+T2  2    17 min      10 min  8s      -      12s    0       10 min
+T3  3    28 min      11 min  28s     9 min  10s    1       21 min
+...
+```
+
+### How it's worked out
+
+Nothing is estimated, and no model is asked. Every number is the time between two events that
+plan-driven already records in the audit trail:
+
+| From | To | Counts as |
+| --- | --- | --- |
+| `tickets.approved` | `ticket.agent_started` | Queued |
+| `ticket.agent_started` | `ticket.pr_opened` | Agent coding |
+| `ticket.pr_opened` | `ticket.pr_approved` or `ticket.changes_requested` | Waiting for review |
+| `ticket.changes_requested` | the next `ticket.pr_opened` | Agent fixing feedback |
+| `ticket.pr_approved` | `ticket.merged` | Approved, not merged |
+
+The phases run from `plan.drafted` to the last `plan.approved` (planning), then to
+`tickets.approved` (tickets), then to `plan.delivered` (development), then to the first
+passing evidence run (proof). A plan still in development is counted up to now. A plan whose
+tickets aren't approved yet shows only its planning time.
+
+The charts are SVG drawn in Ruby, with no JavaScript and nothing to install. `report` writes
+them next to `delivery-report.md` (`statistics-burnup.svg`, `statistics-timeline.svg`,
+`statistics-time.svg`, `statistics-proof.svg`), so GitHub shows them in the Markdown, and it
+inlines them in the HTML and the PDF so both stand alone.
+
+The report also marks every acceptance criterion's result in colour: a green, red, amber or
+grey pill with a matching edge on its row, and failed rows tinted red. On GitHub, the Markdown
+shows ✅, ❌, ⏸️ or ⚠️ instead.
+
+![Acceptance criteria and proof in the delivery report](docs/images/statistics-report.png)
+
+## How it compares
+
+plan_driven sits next to spec-driven tools such as GitHub's Spec Kit and Kiro, which also start
+from a written spec before an agent writes code. As we understand them, those are
+language-agnostic and focus on producing the spec, the design and the task list for an agent to
+follow. plan_driven is narrower and goes further on the Rails side:
+
+- the plan is drafted from your Rails schema, models and routes, and Existing Data Structure is
+  checked against them;
+- the rules are Ruby code that blocks the next step (expand and contract, ticket size and
+  order, pull request scope, CI), rather than guidance in a prompt;
+- phases and approvals are stored in your database, per revision, with an audit trail;
+- each acceptance criterion is mapped to a Cucumber scenario, and the delivery report shows
+  the proof, the approvals and the cost.
+
+If your stack isn't Rails, or you only want a spec for a single agent session, a general tool
+is the better fit.
+
 ## Keys
 
 | Key | Used for | Environment |

data/app/controllers/plan_driven/wizard/application_controller.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  module Wizard
+    # The wizard runs commands on this machine, so it only answers local requests in development
+    # (or wherever config.wizard_enabled says).
+    class ApplicationController < ActionController::Base
+      protect_from_forgery with: :exception
+      layout "plan_driven/wizard/application"
+      before_action :local_only!
+      helper_method :acting_as, :current_job
+
+      helper do
+        # A button that runs one command for the plan on the page, e.g. run_button("Submit", "submit").
+        def run_button(label, action, fields = {}, primary: false, disabled: false)
+          button_to label, run_plan_path(@plan.key),
+                    params: fields.merge(do: action, step: @step), disabled: disabled,
+                    class: primary ? "primary" : nil, form: { style: "display:inline" }
+        end
+
+        def markdown(text)
+          PlanDriven::Renderer::HTML.convert(text).html_safe
+        end
+
+        def guard_list(report)
+          safe_join([
+            (tag.ul(safe_join(report.errors.map { |e| tag.li(e) }), class: "errors") if report.errors.any?),
+            (tag.ul(safe_join(report.warnings.map { |w| tag.li(w) }), class: "warnings") if report.warnings.any?),
+            (tag.p("#{report.passes.size} checks passed.", class: "muted") if report.passes.any?)
+          ].compact)
+        end
+      end
+
+      private
+
+      def local_only!
+        enabled = PlanDriven.configuration.wizard_enabled
+        enabled = Rails.env.development? if enabled.nil?
+        head :forbidden unless enabled && request.local?
+      end
+
+      def acting_as
+        session[:plan_driven_actor].presence || PlanDriven.actor
+      end
+
+      def current_job
+        return @current_job if defined?(@current_job)
+
+        @current_job = params[:job].present? ? Job.find(params[:job]) : nil
+      rescue ArgumentError
+        @current_job = nil
+      end
+
+      def start(argv, stdin: nil)
+        Job.start(argv, stdin: stdin, actor: session[:plan_driven_actor])
+      end
+    end
+  end
+end