phax 0.28.0
Changes since 0.27.0: v0.27.0...v0.28.0.
Highlights
- Test strategy as data, and the plan overview — The overview shows what the plan says, read without a model, and it never writes or starts anything.
- Artifact decide from verdicts — The person decides and phax checks the transcription: what the file says is applied as given, nothing it does not name moves, and nothing is approved.
Upgrading
- A spec or plan option named
other.otheris now a reserved id, implicit on every question. A live spec or plan that lists an option, or a recommendation, with the idotheris refused: an authored answer exits 5,phax artifact approveanddecideon the artifact exit 12, andphax artifact statusreports a §9 that does not parse. Rename that option (in the sidecar and in the Markdown alike) before upgrading. ADecision: other — …line, and a verdict that choosesother, are accepted. - Plan sidecars:
testStrategybecomes a list of test lines. Runphax artifact migrate-documentsonce in each repository with plans underdocs/. A sidecar whose every test strategy follows the line format is lifted and committed. One holding prose is refused, naming the phase and the line: rewrite it in the line format in the sidecar and in plan.md alike, or re-author the plan, then run the command again. Until then,phax artifact approve,reopenanddeciderefuse and name the command. Archived plans are not touched and still read. - Hand-written plans. Write each
### Test strategyentry in the line format:<guarantee> — <size> · <technique> · <oracle> · <loop>[ · <criterion>].phax plans lintreports a departing line as atestserror.phax run,phax plans overlap,phax adjust-planandphax plans statusrefuse such a plan before any model call, naming the line andphax plans lint, andphax plans overviewexits 1. A phase with no section, or with- (none), has no line. - Runs in flight. A
phax-plan.jsonextracted by an older phax is refused byphax resumeandphax validate --plan. Finish the run with the release that started it, or archive it withphax archive <run> --forceand run its plan again.phax lsandphax session-infostill show it. - New
testswarnings inphax plans lint. Nothing to do. An uncovered acceptance criterion, or a source spec without a readable sidecar, is a warning that never fails lint or refuses a run.
What's new
Test strategy as data, and the plan overview
The overview shows what the plan says, read without a model, and it never writes or starts anything.
-
A plan's test strategy is a list of test lines a tool can read, each with its size, technique, oracle, loop and the criterion it proves.
plan sidecar docs/plans/<stamp>-<slug>-plan.json, phase testStrategyNow:
Before
-
The extracted plan carries each phase's test lines, so scripts and later commands can see what each phase tests.
phax-plan.json, phase test linesNow:
Before
-
You write each test of a phase as one line (the guarantee, then size, technique, oracle, loop and an optional criterion), and phax reads it.
plan.md ### Test strategy sectionNow:
Before
-
Linting a plan now flags test lines that break the format, misuse the oracle loop or cite a criterion the spec lacks, and warns about spec criteria no test proves.
phax plans lint <plan> — new test line findingsNow:
Before
-
You can see a whole plan at a glance before running it: each phase's model, oracle role, files and tests.
phax plans overview <plan> [--json]Now:
-
The overview lists each phase in turn with its model, its oracle role, its files grouped by architecture part and its test lines.
phax plans overview — rendered layoutNow:
-
A script or review tool can read the plan overview as JSON.
phax plans overview --jsonNow:
-
Migrating documents refuses a plan whose test strategy is still prose, naming the line and how to rewrite it in the line format.
phax artifact migrate-documents — refusing a prose test strategyNow:
-
Agents writing plans with the phax-planning skill write test strategies in the line format that lint checks and the overview shows.
.claude/skills/phax-planning/SKILL.mdNow:
Before
Artifact decide from verdicts
Transcribing decisions already made.
The person decides and phax checks the transcription: what the file says is applied as given, nothing it does not name moves, and nothing is approved.
-
You can record decisions you have already made on a spec's or plan's questions from a file, without an interactive session.
phax artifact decide --verdictsNow:
Before
-
You write your decisions in one small file that names, for each question, the option you chose and an optional note.
verdicts file (given as --verdicts <file|->)Now:
-
You can choose none of a question's options and say what you want instead, and the spec shows that choice and why.
docs/specs/<stamp>-<slug>.json a verdict choosing other, and the rendered §9Now:
Before
-
You can print the verdicts file's JSON Schema to check or generate a verdicts file.
phax artifact schema verdictsNow:
Before
-
A script can read what decide recorded: each verdict, whether it departs from the recommendation, and which sections changed.
phax artifact decide --verdicts --jsonNow:
-
The decide commit says the decisions came from a verdicts file, and who made them.
the decide commit (git log)Now:
Before
-
The records say a decision was transcribed from a verdicts file, which questions it settled and how many departed from the recommendation.
decision record on phax/records/v1Now:
Before
Also in this release
Release notes from specs
At the release cut, phax's release notes are written from what the release's runs delivered: each completed spec with its guiding rule and the surfaces it changed, each plan without a spec, the commits made outside any run, and the release's upgrade steps. The cut writes them to docs/releases/<X.Y.Z>.md in the release commit, the same file becomes a page of the docs site, its short form (the file without its folded before/after blocks, plus a link to that page) becomes the GitHub release body, and pnpm release:notes previews them at any time without writing anything.
Readable release notes
The release notes read as an announcement. A Highlights section opens them, each spec's surfaces are bullets that start with their sentence, a surface's current example is labelled Now: with the earlier one folded under Before, and nothing is said about work that has not shipped. The builder in scripts/releaseNotes.ts, the GitHub release body and the docs site page follow the new layout.