Skip to content

WhyGraph 2.6.0

/whygraph-plan now runs each step's Verify before you read the plan, checks the user's path through the screens, and lists a web pitfall the plan walks into as a risk. /whygraph-implement sees each Test first test fail before the change, says how many steps are proven, polishes small quality findings, and gets past a slow test suite or a wrong red run on its own. Every constraint on a rationale card now names its source, and a constraint note can carry a check that runs after every step.

Upgrading and rolling back

From 2.5.0, run whygraph update, then Settings > Update agent files in each project to pick up the new plan and implement commands. Each project's database gets three columns on first use. A linked portal and its platform must both run 2.6.0: the platform API is now version 2, and an older linked portal shows Update required until it is updated. To go back, see Rolling back after this release.

What's new

  • A web pitfall that the plan walks into is now a risk. The best-practices source reports each finding as do: or avoid:, and an avoid: item must name when it fails and what goes wrong. When the plan's own approach meets that condition, and nothing in your repository contradicts it, the plan lists it under ## Risks called out across the change, tagged (external). It still never changes a step or becomes a Blocker. Run Settings > Update agent files to pick it up, and see Best practices from the web.
  • A polish run applies the small quality findings. After the quality evaluation, Claude Code and Cursor apply its findings to files the plan lists. They run the plan's new - Format: Setup command on the changed files, then run Acceptance again, which decides. The planner now reads the working set from a file, which makes a deep plan faster. Pass --no-polish to skip the run. Run Settings > Update agent files to pick it up, and see The polish run.
  • UI capture works behind a login. Set WHYGRAPH_UI_USER and WHYGRAPH_UI_PASSWORD, or run node capture.mjs --login once to save a session in .whygraph/profiles/ui-auth.json. The profile gets login_route and login_fields, and the planner no longer skips a project with a login. Both ways work only on a loopback host. A saved login that expired ends a step as not run, not a halt. The variables are visible to commands the agent runs itself: use a throwaway dev account. Run Settings > Update agent files to pick it up, and see Capturing behind a login.
  • A UI plan can carry a browser test, seen red before the feature exists. When the project has browser tests (profile key e2e_run), one step writes a test for the user's path and runs it red, and the step that completes the path runs it green. Acceptance gets an e2e: item. The planner first runs one existing browser test once, so a missing database, seed or login is a Blocker at plan time. In Claude Code and Cursor, begin prints a trust: hash and end --trust stops a later step that changed an earlier step's record. VS Code and Codex have no such check. Pass --no-e2e to either command to skip it. Run Settings > Update agent files to pick it up, and see End-to-end tests.
  • A Test first test is seen red, and cannot be edited to pass. plan-tool.sh red runs the test before the change and writes steps/<N>.red. verify and end compare the test with a copy and stop on an edit, with the first line verify: test first edited. proof takes the class of a Test first step from that record (proven, not proven or edited), and each step's diff adds tests: lines for a skip marker, removed assertions, a changed snapshot or runner config. The dry run no longer reports an existing Test first test that fails by design. Run Settings > Update agent files to pick it up, and see Verify evidence.
  • The run summary says how many steps are proven. plan-tool.sh proof <plan> prints one line for each step (proven, unproven, carried, not proven, no test, failed, not run or unknown) and two total lines. The run summary of /whygraph-implement in Claude Code and Cursor shows the totals as - Proof:, and the implementor logs them under - Acceptance: in VS Code and Codex. An unproven step asks a person to read its diff first. Run Settings > Update agent files to pick it up, and see Verify evidence.
  • A plan checks the user's path through the screens. When a task moves the user between screens, the plan gets a ## User journey section (the actor, the entry control, one line per hop tied to a step or to existing code, the outcome, what holds on refresh, back, cancel and a direct link, and what the user sees while slow work runs). In Claude Code a journey reviewer checks it against the router and the code, and plan-tool.sh check lints its lines. A plan's ## UI profile now also carries **Auth:**, so the UX/UI reviewer asks for a no-permission state when a login is required. Run Settings > Update agent files to pick it up, and see Plan review.
  • Every constraint on a rationale card names its source. Each item of a card's constraints and risks is now an object with its text, a basis (quoted, cited, inferred or unknown) and the commits, PRs or issues behind it. The planning agents quote the text as before and end each quote with a tag, such as (quoted: 1a2b3c4d) or (inferred). A constraint the model only inferred never becomes a Blocker, and in Claude Code a review-gate verdict on one is printed and does not hold the step. A card cached before this release reads unknown until it is generated again. Run Settings > Update agent files to pick it up, and see Where a constraint comes from.
  • A plan can change a recorded constraint on purpose. When the task itself asks to change a constraint, the step gets a Changes on purpose line with the quote and the reason, in place of a Blocker. The implementor does not guard it, and in Claude Code the review gate reports it as Changed on purpose and goes on. Run Settings > Update agent files to pick it up.
  • A plan runs before you read it, so it can be trusted to run. The planner now runs each Verify once and hands over the result (the dry run), and a plan can carry a ## Setup section of install and generate commands. A run that finds a Verify failing before any change runs the Setup, tries again, and stops with Verify fails before any change or setup failed instead of failing late. A manual: span in backticks is no longer run as a command. The dry run executes commands from your repository before you read the plan, with a smaller set of secrets and no package download. Pass --no-dry-run to skip it. Run Settings > Update agent files to pick it up, and see The dry run and Running unattended.
  • A run proposes the note it made stale. After a /whygraph-implement run whose Acceptance passed, Claude Code and Cursor propose a note for each step with a Changes on purpose line, at most three per run: a revision of the note the step changed (its (note #<id>) tag stays on the line), or a decision note that says the quoted constraint no longer holds. Nothing counts until a person confirms it, and confirming a revision retires the old note. VS Code and Codex print one line per step instead. See Limits on agent proposals.
  • A Verify that ran no test is marked, and a run starts with a brief. A Verify that exits 0 while its output says no test ran (such as collected 0 items or 0 passing) is recorded at baseline as pass (no test ran): still a pass, but now visible. In Claude Code and Cursor, /whygraph-implement first prints a one-page brief of the plan, built with no model by the new plan-tool.sh brief <plan>. Run Settings > Update agent files to pick both up, and see Running unattended.
  • A constraint note can carry a check. Add a check to a constraint note: a text that must not appear, or must appear, in the files a glob names. The Notes page shows it and, on a single note, whether it holds. /whygraph-plan copies it into the plan and /whygraph-implement searches for it after every step; a broken check sends the run to the constraint rung (Claude Code) or fails the step's Verify (the other editors), unless the step's Changes on purpose names the note. A check is a text search and never runs a command. See A check on a constraint.
  • /whygraph-implement handles a slow suite and a wrong red run. A Test first test that fails in its own setup gets one fix and a second red run before any code changes. A second wrong red stops the run with the Test first test fails for a reason the step does not change. The spec evaluator's "Verify exercises the change" check also passes when the Test first test was red before the change and the Verify passes after it. A Verify or Check is capped at 580 s. When the dry run finds that Acceptance item 1 (the full test command) does not finish, the single-pass planner now makes item 1 the steps' test files and adds a manual: item with the full command, for CI, instead of writing a Blocker. Run Settings > Update agent files to pick it up, and see The red run of a Test first step and Running unattended.

Changes to know about

  • The platform API is version 2. A rationale card's constraints and risks are lists of items with their sources, so a linked portal and its platform must both run this release. An older linked portal shows Update required until it is updated.

Rolling back

This release adds three columns to each project's WhyGraph database (the portal's own database is unchanged). An older image cannot open an upgraded project database: to go back, restore each project's backups/whygraph-c4e7a2d9b1f6.db, which the portal writes beside its whygraph.db before upgrading it, then re-run the installer from the v2.5.0 tag and whygraph up (whygraph update refuses a downgrade). A linked portal on 2.5.0 cannot talk to a 2.6.0 platform.

For developers

  • Project database migration e9b3d6a1c5f8 (project_note.check_kind, check_text, check_glob): the optional check of a constraint note. All three are nullable; no data migration.
  • API_VERSION is 2 (src/whygraph/api_v1.py): each card constraints / risks item is an object, and both sides compare the version at /meta.