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:oravoid:, and anavoid: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-polishto 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_USERandWHYGRAPH_UI_PASSWORD, or runnode capture.mjs --loginonce to save a session in.whygraph/profiles/ui-auth.json. The profile getslogin_routeandlogin_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 asnot 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 ane2e: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,beginprints atrust:hash andend --truststops a later step that changed an earlier step's record. VS Code and Codex have no such check. Pass--no-e2eto 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 redruns the test before the change and writessteps/<N>.red.verifyandendcompare the test with a copy and stop on an edit, with the first lineverify: test first edited.prooftakes the class of a Test first step from that record (proven,not provenoredited), and each step's diff addstests: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-implementin Claude Code and Cursor shows the totals as- Proof:, and the implementor logs them under- Acceptance:in VS Code and Codex. Anunprovenstep 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 journeysection (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, andplan-tool.sh checklints its lines. A plan's## UI profilenow 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
constraintsandrisksis now an object with itstext, abasis(quoted,cited,inferredorunknown) and the commits, PRs or issues behind it. The planning agents quote thetextas 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 readsunknownuntil 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
Verifyonce and hands over the result (the dry run), and a plan can carry a## Setupsection of install and generate commands. A run that finds aVerifyfailing before any change runs the Setup, tries again, and stops withVerify fails before any changeorsetup failedinstead of failing late. Amanual: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-runto 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-implementrun 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 adecisionnote 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
Verifythat exits 0 while its output says no test ran (such ascollected 0 itemsor0 passing) is recorded at baseline aspass (no test ran): still a pass, but now visible. In Claude Code and Cursor,/whygraph-implementfirst prints a one-page brief of the plan, built with no model by the newplan-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
constraintnote: 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-plancopies it into the plan and/whygraph-implementsearches 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-implementhandles a slow suite and a wrong red run. A Test first test that fails in its own setup gets one fix and a secondredrun before any code changes. A second wrong red stops the run withthe 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 theVerifypasses after it. AVerifyor 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 amanual: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
constraintsandrisksare 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_VERSIONis 2 (src/whygraph/api_v1.py): each cardconstraints/risksitem is an object, and both sides compare the version at/meta.