Docs · fp CLI
fp changelog
What changed in each release of the fp CLI, newest first. Run fp update to install the latest; updating fp covers what to refresh afterwards.
0.0.38 (2026-11-18)
- A requirement an open proposal demoted has one name in every command: awaiting review (Fizzy #2043).
fp showprintsStatus: awaiting review (modification proposed)and says it is still enforced.fp listshows it with that status among the active requirements and leaves it out of--status draft.fp coveragenames it under the drafts table, andfp coverage --allgives its row the same status. Before,fp showsaiddraft,fp listsaid "No requirements found (active)" and then named it in a footnote,fp coveragesaid only "No draft requirements", andfp matrixmarked it with✎. In--jsonthe storedstatusis unchanged;fp list --jsonandfp show --jsoncarryunder_review, andfp coverage --jsonaddsawaiting_review. - A never-approved draft with a proposal against it is no longer described as "still enforced by the gate" by
fp list. It readsdraft (modification proposed). fp matrix --csvwrites<slug> (awaiting review)for such a row. It wrote<slug> (under review); a script that matched that suffix needs the new one.- The
fp list --gapsfooter prints the✎once. It printed it twice. - Server side, shipped with this release: surfaces come back in the showroom's order (placed surfaces first, then alphabetically by name), so
fp matrixandfp coveragecolumns andfp surfacesall agree. They used to follow the order of an unsorted database read. Requirement listings carryunder_review, decided by the same rule as the gate.
0.0.37 (2026-11-17)
- The changelog is published at https://featureparity.dev/changelog (Fizzy #2044). Every release in this file is on that page, newest first, and the site's llms.txt lists it. /docs/changelog leads there too. Before, both addresses were a 404 and no public page said what changed.
fp updatenames the changelog (Fizzy #2044). After it installs a newer fp, and with--checkwhen one exists, it printsWhat changed: https://featureparity.dev/changelog;--jsoncarries it aschangelog_url.- The gem lists the changelog as its
changelog_uriagain, now that it points at a public page (Fizzy #2044). The old link went to the private repository and was removed in 0.0.33. - The CLI reference's "Updating fp" section and the docs' "Update the CLI" section link to the changelog.
0.0.36 (2026-11-17)
fp surfaces add <key> --from <source>carries over draft requirements as well as active ones (Fizzy #2040). On a project an agent had just onboarded, where every requirement is still a draft, it said "No requirements on 'api' to draft" and created the surface anyway. It now proposes the new surface through the same endpoint asfp surfaces batch-draft, parents before their children, and names anything the server skipped.fp surfaces add --fromchecks everything before it creates the surface (Fizzy #2040). An unknown source surface, a key that is already taken, or no requirement to carry over each exit 1 with nothing created. Before, an empty result left an empty surface behind.fp surfaces add --from --evaluateon a project without AI access says so once, exits 1, and creates nothing (Fizzy #2040). Before, it created the surface, printed the paid-plan message once per requirement, and exited 0. The evaluation now runs before the surface is created. The help text no longer names the model behind it.fp reportandfp runread--repofrom the checkout's git origin remote when it isn't given (Fizzy #2040).fp runsettles the repo before it starts the test command, so a checkout with no origin remote and no--repois refused in a second. Before, the whole suite ran and then the report failed with "--repo is required".fp markwarns when no requirement has the slug (Fizzy #2040). In a checkout whose.featureparity.ymlnames the project, with a key configured, a slug that matches no requirement gets a warning on stderr that the marker binds nothing yet. The marker is still written, because marking beforefp proposeis fine. With no key or no network, fp says nothing.fp list --gapson a project with no approved requirement says there is nothing to measure yet and points tofp list --status draft --gapsandfp coverage, and an emptyfp matrixpoints tofp coverage(Fizzy #2040). Before, "No gaps found" read as "nothing left to test" on a project full of untested drafts.fp doctorshows the project named in.featureparity.ymlinstead of suggesting a slug from the directory name (Fizzy #2040).- The skill has an "Add a platform" section, and the CLI reference says
fp updateexists from fp 0.0.34 (it said 0.0.35). - Server side, shipped with this release: proposing a new required surface no longer marks a requirement's existing tests
suspect, and the gate doesn't ask for tests on the new surface until a human approves it. Before,fp surfaces add tablet --from webturned every passing, failing and stub cell on the affected requirementssuspectand added amissingviolation per requirement.
0.0.35 (2026-11-16)
fp matrixandfp coverageshow every surface by default (Fizzy #2008). The surface pinned in.featureparity.ymlno longer narrows them; pass--surfaceto narrow.fp checkstill gates the pinned surface.fp surfaces add <key> --from <source>creates a surface and drafts requirements from an existing surface (Fizzy #2009). When you add a new platform (like Android when you already have web),--from webfinds every active requirement that namesweb, proposes adding the new surface to each, and returns a gap list. The drafts await human review — an agent can't approve its own surface additions — and the gap list tells the agent which requirements need test coverage on the new surface. This is the "add a platform" workflow: create the surface, see what applies, write the tests.fp surfaces add <key> --from <source> --evaluateruns each candidate requirement through Jev to determine if it applies to the new platform (Fizzy #2009). Instead of mass-drafting everything,--evaluateasks the AI "Does this web requirement apply to android?" for each requirement, returning applicability verdicts with reasoning. The agent sees which requirements apply (✅), which don't (❌), and why — then makes the final call on what to draft. Nothing is drafted automatically; the evaluation data lets an agent filter the 10% that are platform-specific (browser resize, web-only APIs) from the 90% that transfer to any client. Requires a Pro plan or a project whose owner has AI access.fp surfaces batch-draft <key> --slugs slug1,slug2or--slugs-file applying.jsondrafts multiple requirements for a surface in one request (Fizzy #2009). This is the second half of the agent workflow: runfp surfaces add android --from web --evaluate -f json > /tmp/eval.json, filter the JSON to requirements whereapplies: true, and send the slugs tobatch-draft. The endpoint skips requirements that already include the surface, have a pending change, or are archived, and reports what it drafted, skipped, and failed. The--slugs-fileaccepts the--evaluateoutput format (array of objects withslug) or a plain array of strings.
0.0.34 (2026-11-13)
fp updateinstalls the newest fp (Fizzy #1993). It reads the latest version from the API's public version endpoint, so it needs no key, and installs the gem under the Ruby that is running fp.fp update --checkonly says whether a newer one exists. Afterwards it namesfp skill installandfp init --force, which refresh a repo's agent skill and itsAGENTS.mdsection. Before, there was no update command andgem update featureparitywas mentioned once, in the changed-test upgrade notes.- fp says when a newer version is published (Fizzy #1993).
fp doctorshows the newest version and, when the installed one is behind, the command that installs it. At most once a day, any other command that finds a newer version prints one line on stderr after its own output. The line never appears with--json, whenCIis set, or withFP_NO_UPDATE_CHECK=1. The lookup is one unauthenticated request with a 2-second limit, and a failed one is silent. - The CLI reference has an "Updating fp" section.
0.0.33 (2026-11-13)
fp markallows for the markers it added itself (Fizzy #1991). Marking three tests in three calls, top to bottom, with line numbers from one read of the file, put the second and third markers above the wrong lines, because each insert pushes the lines below it down. fp now remembers the marker lines it inserted into a file for 30 minutes. While nothing else has edited that file, a line number that no longer points at a test is also read as it was numbered before those markers went in, and when exactly one reading lands on a test, that test is marked and fp says the line moved. If the number could mean two tests, fp names both as<file>::<test name>and writes nothing. A number that points at a test as the file stands is used as given.fp initandfp init --detectrecognise pytest from the test files alone (Fizzy #1991). A repo withtests/test_*.pyand nopyproject.toml,requirements.txtorpytest.inigot "No test runner recognised" and the Ruby marker example. Files namedtest_*.pyor*_test.pyin the root,tests/ortest/that define adef test_or import pytest now count.- The
AGENTS.mdsection fromfp initgives the report shortcut for the repo's detected runner (Fizzy #1991): a pytest repo readsfp run ... -- pytestand the pytest JUnit command instead of a note about RSpec's JSON report. The onboarding text no longer saysfp doctorchecks "the repo's Ruby". fp skill installinstalls the agent skill that ships inside the gem (Fizzy #1984). The docs sent agents tonpx skills add stowzilla/feature_parity --skill fp, which 404s because that repository is private. It copiesskills/fpinto.claude/skills/fp(Claude Code) and.agents/skills/fp(Codex, Cursor, Gemini CLI and the other agents that read the shared location) in the working directory;--agent claude|agentspicks one,--diranother repo,--globalyour home directory,--pathany skills directory. It needs no network or key, and re-running after a gem upgrade refreshes the copy. It won't replace a directory namedfpthat isn't the fp skill without--force.fp skill pathprints where the bundled skill lives.- The gem no longer lists
source_code_uriandchangelog_uri, which pointed at the private repository and 404'd (Fizzy #1984). It lists the docs at featureparity.dev/docs instead. fp marktakes a test by name,<file>::<test name>, and several targets in one call (Fizzy #1987). An agent that read a file once and marked three of its tests by line number put the later markers on the wrong lines, because each insert pushes the lines below it down. A name is found in the file as it is when the command runs (a pytest id likefile.py::TestClass::test_x[case]works too); a name that isn't there, or that two tests share, is refused with the file's test names. Line numbers given in one call all refer to the file before that call, every target is checked before anything is written, and--jsonanswers several targets with{ "marks": [...] }.fp whoamisays who the key acts as (Fizzy #1989): an Acting as line names the agent key and the person who owns it, from a newGET /whoami. If the API can't be reached or the key is bad, the line says so and the local config still prints.
0.0.32 (2026-11-13)
- A base API URL that ends in
/apiworks (Fizzy #1980). The site hands peoplehttps://api.featureparity.dev/api(and the same with a preview environment's host), and fp then asked for/api/api/projects. fp now drops trailing slashes and one trailing/apisegment wherever the URL comes from (--api-url,FP_API_URL, a profile or the global setting), sofp whoamishows the host and every command reaches the right path. Any other path is left alone. fp tutorialno longer asks for an API key (Fizzy #1980). It writes the sample repo and makes no API calls, but a first-time user with no key yet was stopped before it started.fp --helpandfp -hprint the help, likefp help, instead of "Unknown command: --help" (Fizzy #1980).fp help --json(andfp --json help) prints a machine-readable index in the usual envelope: the fp version and every command with its summary and usage (Fizzy #1980). Before, it printed the prose page. Without--jsonthe output is unchanged.fp init --forcesays "refreshed FeatureParity section" when it replaced an existing section in AGENTS.md, and keeps "appended" for a section it really added (Fizzy #1980). Before, both were reported as appended.fp showprints a requirement's source type and context in the Source Trail when it has them but no URL (Fizzy #1980). Before, it said "no sources recorded" for a requirement whose JSON carried both.- The
AGENTS.mdsection fromfp initleads its marker example with the language of the repo's detected test runner (Fizzy #1980):def test_...under a# fp:slugcomment for pytest,it(...)under// fp:slugfor jest, vitest and Playwright. Any other repo still gets the Ruby/RSpec example. A pytest repo was shown RSpec first. - Help examples, the skill and its CLI reference use the project slug
acmeinstead of the company's own (Fizzy #1980). fp mark's help and the skill's CLI reference now say that each insert shifts the lines below it by one, so a file's tests should be marked from the bottom up (or line numbers re-read between marks), and that theIt binds to:line is the check (Fizzy #1980).
0.0.31 (2026-11-11)
fp propose-change <slug> --tags a,bproposes new tags for an existing requirement (Fizzy #1960). Before, tags could only be set byfp proposewhen a requirement was created, so a missing tag meant retiring the requirement and proposing the same promise again. The proposal replaces the whole list in the order given (--tags ""clears it) and is reviewed like any other field. Order counts:units,rules→rules,unitsis a change, and rejecting or withdrawing puts back the original tags in their original order.fp historyand the web Change History show the tag diff.
0.0.30 (2026-11-05)
fp ci-report --localrecords a suite's real results without CI (Fizzy #1837). A team out of CI minutes, or with no pipeline yet, runs the suite on a laptop and reports it the way CI would, with--localin place of--ci-url. The verdict is recorded againstHEAD, so--localrefuses a working tree with uncommitted tracked changes, and the receipt shows the commit with no "View Run" link. Everything else is the same ingest, including--prfor a branch. It's for a person standing in for CI; agents still report withfp report.
0.0.29 (2026-11-02)
- The skill and the
AGENTS.mdsectionfp initwrites now explain optional visual evidence (Fizzy #1786). A UI test's recorded screenshots and videos can be attached withfp report --junit ... --attach-media(Playwright) orfp attach <slug> <file> --surface <surface> --example-title "<test name>". Agents are told this is optional, needs permission from the person they work for because the files are stored in FeatureParity, and must never capture someone's own screen. Only what an automated test drove can be attached.references/cli.mdnow documentsfp attachandfp attachments. fp propose --dry-runvalidates and lints a requirement without writing it (Fizzy #1786). It checks for a title that names the work instead of the promise, commentary openings, filler, a missing why or acceptance, noExample:, several sentences of rule, and a number nobody may have decided. It also checks the catalog for a slug that's taken or a parent that's missing. Notes are advice; catalog problems exit 1. A normalfp proposeprints the same notes on stderr and still creates the draft.fp propose --file reqs.ymlproposes a batch from YAML or JSON. Every entry is checked first (unknown fields, category, source type, duplicate or existing slugs, parents), and if anything is wrong nothing is created. Parents named within the file are created before their children, and the result is one table. Flags and adefaults:block apply to every entry. Before, a 23-draft onboarding was 23 hand-quotedfp proposecalls.fp mark <slug> <file>:<line>inserts the marker above the test in the file's own comment syntax and indentation, then names the test it binds to. Running it twice is harmless, and it needs no API key.--source-ref path:line(repeatable) onfp proposeandfp propose-changerecords the places in the repository a requirement was read from. They are stored on the requirement, shown in its source trail on the web and infp show, and accepted assource_refsin a--fileentry.fp doctorchecks whether fp will work here, with no API key (Fizzy #1786). It shows the Ruby running fp, the gem's version and path, and whether the directory pins a different Ruby in.ruby-version,.tool-versionsormise.toml. When it does, doctor prints the fix: install the gem under the pinned Ruby, or put the running Ruby's bin directory first onPATH. A repo pinned to Ruby 3.4.12 with fp installed only under 3.4.9 failed withmise ERROR No version is set for shim: fpand worked from /tmp. The shim fails before fp starts, so the skill and the generatedAGENTS.mdsection now describe that case for the agent that hits it. Doctor also shows the API environment (warning off production), whether a key is set, which.featureparity.ymlapplies, which fp wrote theAGENTS.mdsection, and a summary of the repo.fp init --detectsuggests a project slug, surfaces and test commands without writing anything (--jsontoo). It reads the Gemfile, package.json, Podfile and Xcode projects, Android manifests, Python manifests, Rails routes andconfig/database.yml, and docker-compose, in the root and one directory down. For each test runner (rspec, minitest, jest, vitest, playwright, pytest, xctest, gradle) it gives the command that writes a report fp reads and the dependency to add, or says none is needed. It says whether the tests need a database server and whether there's a.devcontainer, and prints the rubric for surfaces: somewhere a user interacts with the product, so an internal API with no separate client isn't one. A plainfp initprints the detected test command and the database note at the end, and when the tests need a database the generated workflow's report recipe gets a TODO and a commented-out service. Init now also says outright that committing the workflow before theFP_API_KEYsecret exists is fine, because the gate skips with an explanation.fp report --junit,fp ci-reportandfp check --junitaccept RSpec's own--format jsonreport, recognised by its content, so an RSpec suite can report withoutrspec_junit_formatterin the Gemfile. Passed examples are present, pending ones are stubs, and failed ones are failing for CI.fp run [report flags] -- <test command>runs rspec, pytest, vitest or playwright with a report formatter fp adds itself, then reports exactly asfp report --junitwould. If the tests failed, it reports first and then exits with the test command's status. Any other runner gets an error naming the supported ones and pointing atfp report --junit. Global flags after--now belong to the command after it, sofp run -- pytest -p no:cacheproviderkeeps its-p.- pytest's JUnit lines (
junit_family=xunit1, the only family that records a test's file) count from 0, and fp now reads them that way. Before, a test directly under itsfp:marker bound to the marker above that one. - The
AGENTS.mdsectionfp initwrites opens with the fp version that wrote it, adds an Onboarding a repo first-run path (create the project, pick surfaces by the rubric, propose drafts, mark tests, report,fp coverage,fp question) and a Troubleshooting list, and points first-run agents at the onboarding path instead of the per-task loop. Its modeling, requirement-writing, onboarding and troubleshooting text now comes from the bundled skill'sSKILL.md, the one source, betweenfp-sharedcomments. The two copies had drifted, and an agent with both read the same guidance twice. The skill says so at the top.fp init --forcerefreshes an existing section.
fp report --junitaccounts for every bound test (Fizzy #1786). The summary opens withN bound test(s) → M receipt(s), and when several tests feed one receipt (the server keeps one per requirement, surface and test type) it lists each of them, with its line and whether it was skipped, under that receipt. Before, three tests proving one requirement printed as one line and the other two looked dropped.--jsoncarries each receipt'stestsand the run'stests_bound.fp projects create,fp propose,fp propose-changeandfp reportprint a one-line warning on stderr before writing when the resolved API isn't production, naming the environment, URL and profile. A leftoverFP_PROFILEorFP_API_URLused to put a new project on a dev environment with nothing to say so. The command still runs, and--jsonoutput is unchanged.fp question <slug> "<question>"attaches an open question for a human to the draft it concerns, andfp questions <slug>lists them with their answers (--openfor only the unanswered ones). An agent proposing a batch of drafts used to hand its questions back in the chat, cut off from the drafts, and the person reviewing a draft never saw them. Now Quick Review shows a draft's open questions on its card, where the reviewer answers or dismisses each one, andfp showlists the open ones. Agents can ask but not answer. Draft and active requirements take questions (Fizzy #1786).--source-type repo_scanrecords that an agent derived a requirement from reading the code, forfp propose,fp propose-changeandfp comment.ai_chatwas the nearest fit, and it misstated where the promise came from.fp coverageshows which draft requirements have evidence on which surfaces, and ends with the drafts that have none (Fizzy #1786). The gate measures only active requirements, so on a freshly onboarded project, where everything is still a draft,fp checksaid "Nothing to enforce yet" andfp list --gapssaid "No gaps found", and the agent that marked the tests had no way to confirm its work.--alladds the measured rows,--surfacenarrows it,--jsoncarriesdraftsanduntested.fp list --status draft --gapsnow lists drafts lacking evidence instead of ignoring the draft filter, andfp check --include-draftsprints the same table after the verdict. Drafts are reported, never gated: none of this changes an exit code.
0.0.28 (2026-11-02)
fp spot-check [<slug>]spot-checks your evidence, like a random drug test (Fizzy #1787). It picks an active requirement with evidence at random (--seedrepeats a pick,--surfacenarrows it), prints the acceptance next to the source of everyfp:<slug>test in the checkout, and gives the agent a four-step brief: list what the acceptance promises, match each clause to an assertion, break the product code to confirm a test fails, then revert.--jsongives an agent on a schedule the same thing. Instead of one at random you can name several (fp spot-check a b), pick--count Nat random, check--allof them, or start from a test with--test <file>[:<line>](repeatable): every marked test in that file, or just the one spanning that line, along with the requirements they're bound to.--promptprints the spot check as instructions to hand an agent (fp spot-check --count 3 --prompt | claude -p), ending with what to report for each requirement: a verdict, the unasserted clauses, the probe made, and a cleangit status.--jevasks Jev, before the agent starts, whether each requirement's tests appear to cover its acceptance, how likely each test is to check the promise, and which gap is likeliest (an unasserted clause, an assertion that can't fail, a test of a mock...). It's a hint for where to aim the probe, not a verdict. Jev is for paid plans: a person on Pro or Lifetime, or a project whose owner is, which is what lets an agent use it. Without one the spot check says so and carries on. It's read-only. A test that stays green under the probe goes to a human, and the command never rewrites a test or requirement.
fp tutorialwrites Hexhaven, a pocket-sized sample repository for the web app's Tutorial (Fizzy #1446). Its tests run on Ruby alone, two rules are already bound byfp:markers, and the tallest-tower test is left for you to mark andfp report, which turns that Server cell in your sample matrix from missing to present. Makes no API calls and never writes over an existing directory (--dirpicks another place).
- When the API address answers with a web page instead of the API (FPAPIURL pointed at the site, say), every command now says so and suggests the API host, instead of crashing with
undefined method '[]' for nil. fp projectscoming back empty while the active profile's key was made for another environment says that a key only works where it was minted, instead of suggesting you create a project.fp whoami's environment warning says the same, and so does a "project not found".fp report --junitrun from outside the checkout (fp report --junit hexhaven/junit.xml) reads the project from the report's own.featureparity.ymland, when nothing resolves from the working directory, finds the test files beside the report.
fp tutorialwrites anAGENTS.mdinto Hexhaven: a short note about the sample, followed by exactly the FeatureParity sectionfp initwrites (the same code produces both), so asking an agent to bind a test works there.fp tutorial --restartdeals a fresh Hexhaven over an existing one, and only over a Hexhaven checkout.fp comments <slug>reads the team's comments on a requirement and lists who can be tagged;fp comments <slug> --body "..." --tag who,...posts one (Fizzy #1494).--tagtakes a teammate's email or name, or one of the team's agents by name or key name. Tagged people get an email with a link to the requirement; each tagged agent fires the project'srequirement.agent_mentionedwebhook, so whatever runs that agent can start it on the requirement. Not to be confused withfp comment, which threads a comment onto an open change proposal and is unchanged.fp historyprints the text of comments and who they tagged, instead of a bare "commented".fp proposeprints the new draft's quality feedback (verdict, issues, suggestions) in the same run, and--jsoncarries it asanalysis. When analysis is unavailable the draft is still created and the output says the feedback couldn't be produced.
0.0.27 (2026-11-02)
- Publishes the refreshed requirement-writing guidance that shipped in #248. No new commands, flags, or behaviour — the embedded prose in
fp help,fp init's generatedAGENTS.mdsection, and the bundledfpagent skill now read naturally and teach the decision-ready title/why/acceptance style. Cutting a release pushes a gem sogem update featureparityandfp init --forcehand agents the current text, rather than it living only on the repo's master until the next functional change.
0.0.26 (2026-10-27)
- A pull request's CI no longer turns the matrix red, and no longer rewrites the merged run's receipt (Fizzy #1631).
fp ci-report --prrecords what the branch said as the row's branch verdict — status, PR, run, commit — beside the default branch's verdict, which stays the cell's state and the receipt a reader sees. The only state a PR may still add is provisional: a green test on a cell the default branch's CI has never judged ispr_passing, as before; a red run withdraws one. A red test on an open PR used to writefailingover the mergedpassingfor everyone, with the PR's run, commit and card in place of the merged run's — so a requirement nobody had touched looked broken on master, and "View Card" led to whichever card last ran the suite. The matrix now shows a corner mark and names the PR in the cell's hint; the requirement page shows the PR's verdict under the merged receipt;fp showprintsOn PR: failing <url> (not merged). The PR itself is still judged byfp check --junit --pr, exactly as before. fp report --junitputs--prand--work-itemonly on the tests in files this branch changed — the commits since it left the default branch, plus anything uncommitted — and says how many receipts got them. A suite run covers every marker in the repo, and stamping the card on all of them rewrote the work item on every requirement the branch never touched. On the default branch the HEAD commit's files count as the change; without git, every receipt is stamped as before, with a note.--stamp-allrestores the old behaviour.--shastill applies to every receipt: it is where the run was observed, not what prompted it.fp ci-reportsends the checkout commit (--sha, orgit rev-parse HEAD) at the top level too, so the evidence — or a PR run's branch verdict — links the exact revision the suite ran at. Before, the receipt's commit was whatever an agent'sfp report --shalast left on it.
0.0.25 (2026-10-22)
fp check --junit <report> --pr [url]asks the pull-request question — "does this change make parity worse?" — instead of the standing one. The server judges the run against what the default branch has recorded and fails only on what the run introduced: a bound test gone red, a bound test that vanished, or a non-green test added where there was none. Everything the default branch already owed (an unapproved removal proposal'ssuspect, amissingcell nobody has written a test for, apresentmarker CI has never run) is listed as "already on the default branch" and not counted. Previously a PR was asked whether the whole project was in parity, so on astrictproject every PR failed with master's own standing violations — none of which it touched — and a reviewer couldn't tell from the gate whether a PR was safe to merge. Without--pr,fp check --junitstill gives the standing verdict, which is what a push to the default branch should gate on: it stays red until a human approves or rejects the pending proposals, and that is where that signal belongs.--prneeds--junit; a server that predates it is reported rather than silently answering the other question.fp check --pralso tells an agent what its branch did: a "cells this change fixed" table (violating on the default branch, green with the run applied) and a "results bound to draft requirements" table for tests whose requirement a human hasn't activated yet, so a branch that proposed a requirement and wrote its test isn't met with silence. Both are in--jsonasimprovementsandunmeasured.- Every violation
fp checkprints now ends with Next steps, grouped by who acts: "An agent can fix" (write_test,fix_test,replace_stub,run_in_ci,reverify) and "Waiting on a human" (await_reviewfor a suspect cell under an open proposal,await_mergeforpr_passing), each with a one-line hint. The server names theactionandowneron each violation in--json, so an agent asked to bring the default branch up to parity can take theagentrows and leave the rest. - A pull request's CI no longer loses the default branch's verdict. Evidence keeps
merged_status(what the default branch last recorded) next tostatus; a default-branch run or an agent'sfp reportwrites both, a PR run writes onlystatus. The PR gate judges cells a PR's CI has written againstmerged_status, so a test the branch skips or turns red where master passes is a regression even though the PR's ownfp ci-report --prran first.fp showprintsMerged:when the two differ. fp ci-reportsends the fp markers that bind to no requirement (slug, surface, file, line). A default-branch run records them per surface, replace-on-run, like loose ends; a PR run never does.fp check --prthen lists an orphan the default branch already has as "already on the default branch" and doesn't fail the PR for it — a slug rename that left markers behind no longer fails every open PR. The matrix shows the recorded markers in their own panel.- A bound test that goes missing from a run is now also flagged when its evidence is
suspect— unless the requirement has an open removal proposal. Proposing a change marks the evidencesuspect, so deleting the test and proposing any change at all used to turn a red cell into one that doesn't fail belowstrict. A modification asks for the test to be rewritten, not removed; only a removal proposal excuses the test's absence, and only until a human decides. Applies to bothfp ci-report(recorded asfailing) andfp check --junit.
0.0.24 (2026-10-21)
fp showroom media add <image> --surface <key> --iconsets the surface's own icon in the client showroom, replacing the built-in logo for its kind (the Android robot, the Apple logo, a globe for web). A surface has one icon, so adding another replaces the first, andfp showroom media remove <id>puts the built-in logo back. An icon must be a png, jpg/jpeg, gif or webp of up to 5 MB, on a surface, with no--captionor--position. Anything else is refused before anything is sent.fp showroom mediashows the surface's icon withiconin the position column.
0.0.23 (2026-10-21)
fp showroom mediamanages the screenshots and videos on the client showroom — on a surface's card, or in the project gallery under the welcome note — so the agent that recorded a run can show a client the product without them opening the demo.fp showroom medialists the gallery and then each surface's media in the order a client sees them (id, kind, filename, caption, position).fp showroom media add <file> [--surface <key>] [--caption "..."] [--position N]uploads one (no--surfacemeans the gallery); png, jpg/jpeg, gif, webp, mp4, webm, and mov up to 100 MB are accepted, and anything else — SVG and PDF included — is refused with the reason before anything is sent, as is a position that isn't a whole number of 1 or more.fp showroom media edit <id> [--caption "..."] [--position N]changes the caption or order — positions run 1..n within a card or the gallery, so--position Ntakes slot N and shifts the others; an empty caption clears it and an empty position moves the item to the end, andfp showroom media remove <id>takes one down, asking you to type the filename back in a terminal and refusing non-interactively without--yes.fp showroomprints the gallery and each card's media (counts and captions), and a surface with media but no link or instructions is now shown, not listed as hidden.fp surfaces edit <key> --showroom-position Nsets where the surface sits in the client showroom (1 is first; the showroom opens on the first). Surfaces with no position follow the placed ones alphabetically, which is the whole order until someone picks one. Pass an empty value to clear it; anything but a whole number of 1 or more is refused before anything is sent.fp surfaces show/editprint the position, andfp showroomlists cards in the order a client sees them.
0.0.22 (2026-10-21)
fp <command> --help(and-h, andfp help <command>) now prints that command's usage, its flags, and the global flags instead of running the command. Previously a command's flags were only discoverable by reading the gem's source — there was no per-command help, sofp report --helpjust ranfp reportand failed validation. Help needs no API key and never trips required-flag validation, so you can discover a command's flags before you can run it.fp --versionandfp -vnow print the installed version, as aliases forfp version. Previously a bare version flag reportedUnknown command: --version.fp <command> --help --jsonemits the command's flag schema (name, description, required-ness, usage, and examples) as JSON, so agents and the Agent Skills package can read a command's real flags straight from the installed gem instead of scrapingKNOWN_FLAGS.fp report --junitnow warns when two or more distinct test files in one run resolve to the same evidence cell (same slug, surface, and test type). Server-side, evidence identity is(slug, surface, repo, test_type)and does not include the file, so those reports share one row and the last one posted silently overwrites the others — exactly what happens when a unit suite and an e2e suite both land on theunspecifiedtest type. The warning names the colliding slug/surface/type and the files, and points at the fix: give each kind of test its own test type (a:typemarker suffix likefp:slug@api:e2e, or--test-type).fp helpnow documents--test-typeon the--junitexample.fp report --junitandfp ci-reportunderstand Playwright's JUnit reporter natively, so an unmodified report binds without a hand-rolled annotation script. Titles joined with›(Playwright) or::(pytest-style ids) bind by name the same way>already did. When a report gives no file and its path-likeclassnameis relative to the runner's testDir (Playwright writesloyalty.spec.js, note2e/loyalty.spec.js), fp searches for the file — thetestDirfrom aplaywright.config.*under--base-dir, then common test directories (e2e/,tests/,test/,spec/), then a bounded unique-match glob — and prints which location it used.fp report --junit --attach-mediauploads the videos and screenshots a run recorded (Playwright's[[ATTACHMENT|…]]entries) as visual evidence, one per bound test, with the test's name set as the example title so each capture nests under the receipt it proves. Paths resolve against--base-dir; unknown requirements and unsupported or oversized files are skipped with a reason rather than aborting the batch.fp report --junitwarns when a bound testcase has an empty name — a receipt with no title is almost always an upstream reporter problem — naming the slug, surface, and file instead of filing nameless receipts silently.fp propose-change <slug> --no-parentproposes un-nesting a child requirement back to the top level. It clears the parent (recorded as a parent change to none) and, like any proposal, drops the requirement to draft for a human to review.--parentand--no-parentcan't be combined.fp propose-change <slug> --withdrawtakes back an open proposal you opened. The single-open-proposal rule means you can't open a second one to amend the first — so you withdraw it (restoring the requirement to exactly what it was, including its evidence binding) and propose again. Only the proposal's author can withdraw it; someone else's proposal still goes through review or a comment.- A change proposal's
--source-type/--source-url/--source-contextare recorded as the provenance of that proposal in the history and no longer overwrite the requirement's own origin fields. Previously, proposing a change citing a different card silently erased where the requirement first came from. fp surfaces edit <key>takes--showroom-url,--showroom-label, and--showroom-instructions(or--showroom-instructions-filefor anything longer than a line) to write the surface's card on the client showroom: the link a client opens, the button text, and how to sign in and try it. Pass an empty value to clear a field; a surface with neither a link nor instructions leaves the showroom. Links must be http(s), checked before anything is sent.fp surfaces showprints the card and says whether the surface is shown to clients.fp projects edit <slug>takes--showroom-welcome/--showroom-welcome-filefor the note at the top of the showroom.fp showroom --project <slug>prints the showroom as a client will see it — welcome, each card, instructions with their line breaks — and then the surfaces that are not shown and why, so a card that dropped out is noticed. The share link is reported as unknown: only a person can see or change it.- The skill gains a "fill in the client showroom when a surface is deployed" step. Leaving feedback and managing the share link stay human-only.
0.0.21 (2026-10-20)
fp surfaces edit <key>changes an existing surface's name, kind, audience, repo, default branch, or key, sending only the flags you pass. Use it to fill in the kind and repo of surfaces thatfp projects create --surfacesmade with defaults.fp surfaces delete <key>removes a surface. Likefp projects delete, it asks you to type the key back in a terminal and refuses non-interactively unless--yesis passed.- A surface key is now unique within a project.
fp surfaces addon a key that already exists used to create a silent duplicate; the server now refuses it with a conflict, and the CLI points you atfp surfaces editinstead. Changing a surface's key to one another surface uses is refused the same way. fp surfaces delete, andfp surfaces edit --key, are refused for a surface that any non-archived requirement still requires; the error names those requirements. Take the surface off them first.fp historyshows a member's request for changes (requests changes, with their note saying what to change). Members ask for changes in the web app when they'd neither approve a requirement as written nor reject it outright.fp historyshows each project member's own decision on a requirement (approves/rejects, with their note). Members record these in the web app on requirements that already have a status; a later decision from the same person replaces their earlier one, and both stay in the history. Agents can read decisions but can't record them.
0.0.20 (2026-10-17)
fp projects create <slug> --name "..." [--surfaces api,web]creates a project from the CLI, so an agent can onboard a repo FeatureParity has never seen without waiting on a human in the web app. The project is owned by the person who minted the key and counts against their plan allowance; the same key reaches it immediately.fp projects show,fp projects edit, andfp projects deleteround out project management. Delete is guarded likegh repo delete: it asks you to type the slug back, refuses non-interactively without--yes, and the server only admits a project owner or a key minted by one.
0.0.19 (2026-10-17)
- API keys are account-level. A key belongs to the person who minted it and works across every project they are a member of, including projects created later, so an agent is set up once rather than once per project. Mint keys under Account → Agents & API keys in the web app; project settings no longer manages keys.
fp setup,fp projects, and the bundled skill docs reflect the change. Existing keys keep working with no re-minting.
0.0.18 (2026-10-16)
fp attachaccepts PNG/JPEG/GIF/WebP screenshots and MP4/WebM/MOV recordings up to 100 MB, streams them directly to private S3, and records surface, capture time, observed deployment time/URL/commit, and test-run URL. Requirement detail renders safe raster images and videos inline with exact deployment recency; SVG and document attachments remain downloads.fp analyze [<slug>]triages requirement quality — duplicates (naming the requirement they duplicate), fragments of a broader promise, vague wording, and possible conflicts — one requirement at a time, reusing cached results. It is read-only and never files proposals; the bundled skill explains how to turn findings into proposals a human picks.
0.0.17 (2026-10-13)
fp ci-reportnow sends one SHA-256 source receipt per bound testcase, using an isolated-test range when it can determine one reliably and an explicitly labelled whole-file fallback otherwise. FeatureParity preserves the accepted baseline, opens a changed-test audit finding for a different fingerprint without changing the CI outcome, and treats every test type uniformly.fp changed-testslists every unresolved finding with requirement, outcome, scope, accepted/candidate revisions, locations, and links.fp changed-tests assessrecords a plain-languagestill_proves,no_longer_proves, oruncertainassessment for an exact candidate fingerprint; stale candidates are rejected, only still-proves resolves the finding, and PR candidates advance the baseline only when the default branch reports the same digest.- Agent guidance now treats existing tests as protected product evidence: edits to passing proof must be called out, behavior-changing edits wait for human approval, FP-detected revisions are assessed against the requirement through the CLI, and a new draft or active requirement never authorizes changing a pre-existing failing test.
- Existing hosted projects need no data or configuration migration. Upgrade CI to fp 0.0.17 or newer and run the existing
fp ci-reporton the default branch once to establish accepted source baselines lazily; add trusted PR reporting with--prto discover later revisions before merge.
0.0.16 (2026-10-12)
fp changes --github-prwrites the linked requirement-change table into one managed section of a pull request's description, and--github-summarymirrors it into the job summary. It reads work-item URLs from the PR body, lists the requirement creations, edits, and modification/removal proposals tracing to them, and replaces its managed section on re-run rather than duplicating it. When GitHub can't be read or updated the step fails instead of silently dropping the table; when the PR links no work item, or the linked item has no activity, it says so explicitly.- Work-item URL detection is now source-agnostic. A heuristic recognises common ticket-tracker URLs (paths with
/issues/,/cards/,/browse/,/tickets/,/pull/,/merge_requests/,/story/, etc., or ending in a numeric id), covering Fizzy, GitHub, GitLab, Jira, Linear, Shortcut, Azure DevOps, Trello, YouTrack, ClickUp, and Discord without configuration. For URLs it can't recognise (Notion, Asana, internal tools), an explicitfp-source: <url>marker anywhere in the PR body takes precedence. - The PR change table shows one row per requirement — its latest event, by title — so a requirement created and later changed under the same work item no longer appears as a duplicate.
0.0.15 (2026-10-09)
fp propose-changecan propose corrections to a requirement's title (--name) and key (--slug) for human review. Existing evidence follows a proposed key and returns to the original key if the proposal is rejected; test markers still need to be updated in the affected repositories.- Expanded the bundled requirement-authoring guidance around evolving requirements, human ownership of value and priority, observed customer behaviour, outcome-oriented discovery, and examples/tests as checks on a general rule rather than substitutes for one.
0.0.14 (2026-09-21)
- Reported test-file paths are now relative to the repository root instead of to the runner's working directory. A JUnit report names files relative to wherever the runner ran — vitest invoked in
frontend/reportssrc/pages/Matrix.test.jsx— andfpuploaded that verbatim, so the web app built a GitHub blob link from a path that does not exist in the repo and every web-surface evidence link was a 404.--base-dirstill says where those paths resolve from; the path that gets reported is now translated against the repo root (found by walking up for.git, so worktrees work), falling back to the path as given when there is no repo to relativise against. Applies to bothfp report --junitandfp ci-report. fp ci-reportnow names the test behind each verdict, and names the failing one when a requirement's cell goes red. Evidence is keyed by slug + surface, so a row outlives any single test; because CI never sent a title, afailingrow kept whatever name an earlier agent report had left on it and the detail page showed a green test's name beside the failure.
0.0.13 (2026-09-21)
fp ci-reportnow surfaces loose ends: tests that failed in CI but carry nofp:<slug>marker, so no requirement tracks them. A red test nobody is tracking is exactly the failure a green-looking gate can hide (the failures aren't bound to a requirement, so nothing goes red). The CLI ships these failing-and-unmarked tests to the server on ingest, warns about them in CI (stderr + a::warning::annotation, the same way orphan markers are surfaced), and the web matrix shows them in a collapsible "N tests failing with no requirement" panel below the grid. Informational only — loose ends never fail the gate. Green unmarked tests are ignored; only failures are surfaced. A PR run never records them (a pull request is a different branch and must not overwrite the merged truth), and a later clean run for a surface clears its loose ends.
0.0.9 (2026-09-17)
fp surfaces show <key> --project <slug>— view a single surface's details. Looks the surface up by its key (agents speak keys, not the stored id, the same wayfp showspeaks requirement slugs) and prints its full configuration: name, key, kind, audience, repo, default branch, owner, team, and resolved test globs. An unknown key returns a not-found error.fp surfaces(bare) still lists, so existing callers are unaffected.
0.0.8 (2026-09-17)
fp ci-report --pr <url>— mark a run as a pull request's CI. Passing tests are recorded aspr_passing("would pass once merged") instead ofpassing, and no merged evidence is demoted.pr_passingranks betweenpresentandpassing: it reads on the matrix as its own state (glyph◐), counts as covered at thecoveredlevel, but is a violation atstrict, which holds out for the merged-green truth. On merge, the plainfp ci-report(no--pr) records the realpassing, superseding thepr_passinga prior PR left behind. Lets a reviewer see, on the PR, that a requirement would go green once merged.fp whoami— show the resolved configuration this invocation would use: the active profile (and where it came from), the environment, the API URL (with its source: flag / env / profile / global / default), and whether an API key is present (masked, never the full token). Makes no API calls, so it works without a valid key. Also available asfp config whoami. Supports--json,--profile, and--api-url.- Environment-tagged API keys — profiles now record the environment they target.
fp profile addandfp setupaccept--environment; when omitted it's derived from the API URL host following the Belt DNS convention (api.staging.featureparity.dev→staging,api.featureparity.dev→production, nested/ephemeralapi-abc-1234.dev.featureparity.dev→abc-1234,localhost→local).fp profile listshows the tag, andfp whoamiwarns when a profile's tagged environment doesn't match the resolved API URL. fp setupnow prompts for (and records) the API URL interactively, so users targeting a non-default/self-hosted/ephemeral environment configure it up front instead of silently defaulting to production.--api-url/--profilepassed as global flags are now honored byfp setupandfp profile add.- Fall back to a profile named
defaultwhen no--profileflag and noFP_PROFILEenv var are set. Matches AWS/git/gcloud behavior —fp setupalready creates adefaultprofile, sofp <command>now uses it automatically. Profile resolution priority:--profileflag >FP_PROFILEenv >defaultprofile (if it exists).FP_API_KEYstill overrides all profiles. - Ship Agent Skills package (
skills/fp/) for cross-agent compatibility. Install withnpx skills add stowzilla/feature_parity --skill fpto teach any AI agent (Claude Code, Codex, Cursor, Gemini, Kiro, etc.) how to use thefpCLI.
0.0.3 (2026-08-30)
Upload evidence without CI.
fp report --junit <file>— parse a JUnit XML report, discover thefp:<slug>markers in the referenced test files, and upload evidence for every requirement the suite covered. Run your suite locally, emit JUnit XML, and report evidence without waiting on CI (e.g. GitHub is offline).- Per-marker surfaces:
fp:<slug>@apiorfp:<slug>@api,webpin one or more surfaces right in the test comment (handy when a backend test satisfies several surfaces). Each surface produces its own evidence upload. Markers without an@surfacefall back to--surface;--surfaceis only required when a matched marker pins none. --base-dirflag to resolve relative test file paths from the JUnit report.- Skipped tests are reported as
stub; everything else aspresent. Agents never reportpassing/failing— that stays CI's job. - Unknown slugs (no matching requirement) and markerless testcases are skipped with a warning instead of aborting the batch.
fp report --sha <sha>is now forwarded to the evidence payload.- Per-marker surface pinning:
fp:print_qr@apiorfp:print_qr@api,webpins surfaces directly in the test file. One marker can report to multiple surfaces.
0.0.2 (2026-08-25)
Custom API URL support and global settings.
fp config set|get|unset|list— manage global CLI settingsfp config set api_url https://api.dev.featureparity.dev— pin all requests to a custom API--api-urlglobal flag to override API URL for a single invocation- Global
api_urlsetting in~/.config/fp/config.yml(applies without a profile) - API URL priority:
--api-urlflag >FP_API_URLenv > profileapi_url> globalapi_url> default
0.0.1 (2026-08-25)
Initial release.
fp setup— interactive guided setup (validates API key, saves profile)fp projects— list accessible projectsfp surfaces— list surfaces for a projectfp list— list active requirements (with--gapsfilter)fp show— show requirement detailsfp propose— propose new requirements (as draft)fp report— report evidence for a requirementfp matrix— display parity matrix (ASCII or CSV)fp profile— manage named profiles--jsonflag on all commands for machine-readable output--profile/-pflag for multi-project setups