featureparity 0.0.27 → 0.0.29

data/skills/fp/references/cli.md

@@ -210,17 +210,74 @@ fp report --junit junit.xml \
 
 | Flag | Required | Description |
 |------|----------|-------------|
-| `--junit` | Yes | Path to JUnit XML report |
+| `--junit` | Yes | Path to a JUnit XML report, or RSpec's own `--format json` report |
 | `--project` | Yes | Project slug |
 | `--surface` | Conditional | Default surface for markers without `@suffix`. Required if any matched marker pins no surface. |
 | `--repo` | Yes | GitHub repo as `org/repo` |
 | `--base-dir` | No | Where to resolve relative file paths (defaults to cwd) |
+| `--attach-media` | No | Upload the screenshots and videos the run recorded (Playwright's `[[ATTACHMENT|…]]` entries) as visual evidence, one set per bound test, titled with the test's name. Unknown slugs and unsupported or oversized files are skipped with a reason |
 
 In JUnit mode:
 - Slugs come from `fp:<slug>` markers in the test files referenced by the report
 - A marker binds to the test directly below it
 - Skipped/pending tests become `stub`; all others `present`
 - Unknown slugs and unmarked tests are skipped with a warning
+- A JSON report from `rspec --format json --out rspec.json` works as-is (recognised by its
+  content, no extra flag), so an RSpec suite needs no `rspec_junit_formatter`. `fp ci-report`
+  and `fp check --junit` take it the same way.
+
+### fp run
+
+Run a test command with a report formatter fp adds itself, then report the results exactly
+as `fp report --junit` would. Nothing is added to the project under test.
+
+```bash
+fp run --surface api --repo stowzilla/marketplace -- bundle exec rspec
+fp run --surface api --repo stowzilla/marketplace -- pytest tests/
+(cd frontend && fp run --surface web --repo stowzilla/marketplace -- npx vitest run)
+fp run --surface web --repo stowzilla/marketplace -- npx playwright test
+```
+
+| Runner | What fp adds |
+|--------|--------------|
+| rspec | `--format json --out <tmp>`, plus `--format progress` when the command names no formatter |
+| pytest | `-o junit_family=xunit1 --junitxml=<tmp>` (xunit1 carries each test's file and line) |
+| vitest | `--reporter=default --reporter=junit --outputFile.junit=<tmp>` |
+| playwright | `--reporter=list,junit`, with `PLAYWRIGHT_JUNIT_OUTPUT_NAME=<tmp>` |
+
+Everything before `--` is an `fp report` flag (`--surface`, `--repo`, `--project`,
+`--test-type`, `--work-item`, `--pr`, `--base-dir`, ...); everything after it is the test
+command, left alone (global flags like `--json` or `-p` there belong to the runner). Agents
+still report `present`/`stub` only. When the tests fail, fp reports first and then exits with
+the test command's status. Any other runner errors with the supported list: make it write
+JUnit XML and use `fp report --junit <file>`.
+
+### fp attach / fp attachments
+
+Attach a screenshot, video or file to a requirement as evidence. Visual captures sit under the
+receipt of the test they prove on the requirement page, and the team can copy one into the
+client showroom. This is optional and stores the file in FeatureParity, so an agent uploads
+only with permission from the person it works for, and never captures someone's own screen.
+
+```bash
+fp attach checkout_flow e2e/results/checkout.webm --project stowzilla --surface web \
+  --example-title "pays by card" --sha $(git rev-parse HEAD)
+fp attachments checkout_flow --project stowzilla          # list
+fp attachments checkout_flow <id> --project stowzilla     # download URL
+fp attach rm checkout_flow <id> --project stowzilla       # delete
+```
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--surface` | For images/videos | Surface the capture is for |
+| `--example-title` | No | Name of the test this capture proves (nests it under that receipt) |
+| `--evidence-key` | No | Bind to a specific receipt (`surface:repo:test_type`) |
+| `--deployment-url` / `--deployed-at` | No | The deployment the capture observed |
+| `--captured-at` / `--sha` / `--test-run-url` | No | When, at which commit, and in which run |
+
+Images and video: png, jpg, gif, webp, mp4, webm, mov. Files: txt, md, json, svg, pdf. Up to
+100 MB each, and several files per call. For a Playwright run, `fp report --junit ... --attach-media`
+does this for every bound test at once (with the same permission). A capture never changes a cell's state.
 
 ### fp propose
 
@@ -265,6 +322,20 @@ fp propose --project stowzilla \
 | `--why` | No | User need, problem or risk, and valuable outcome |
 | `--required` | No | Comma-separated surfaces that must implement this |
 | `--acceptance` | No | Observable behaviour and material boundaries |
+| `--required-types` | No | Comma-separated kinds of test each surface needs |
+| `--parent` | No | Parent requirement's slug (nests one level) |
+| `--category` | No | `functional`, `non-functional`, `ux`, `performance`, `security`, `compliance` |
+| `--tags` | No | Comma-separated labels |
+| `--source-type` / `--source-url` / `--source-context` | No | Where it came from |
+| `--source-ref` | No | A repository place it was read from, e.g. `app/models/order.rb:42`. Repeatable |
+| `--dry-run` | No | Validate and lint the wording, and check the catalog for a taken slug or missing parent. Writes nothing |
+| `--file` | No | YAML or JSON batch (below). Other flags become defaults for every entry |
+
+After creating the draft, `fp propose` prints its quality feedback — a verdict, the issues
+found, and suggestions — in the same run (`analysis` in `--json`). Act on it: revise a weak
+draft with `fp propose-change`, or withdraw one that shouldn't be a requirement. When analysis
+is unavailable the draft is still created, and the output says the feedback couldn't be
+produced (`analysis_error`).
 
 **Write for a decision-maker, not an implementer.** The result should sound natural and be
 ready for management review without someone translating AI boilerplate or reverse-engineering
@@ -300,6 +371,53 @@ earn its place?
 
 **Agents always create requirements as draft.** A human must activate them in the web app.
 
+#### Checking wording first: `--dry-run`
+
+`fp propose ... --dry-run` prints what would be created and a list of wording notes. These
+cover a title that names the work (`Implement…`), commentary openings (`This feature…`,
+`Users should be able to…`), filler (`seamless`, `robust`), a missing why or acceptance, an
+acceptance with no `Example:`, several sentences of rule that may be separate promises, and a
+number in the rule that a source has to have decided. Notes are advice, not errors. A taken
+slug or a missing parent is an error, and it exits 1. Without `--dry-run`, the notes go to
+stderr and the draft is still created.
+
+#### A batch: `--file`
+
+```yaml
+defaults:                 # optional; merged into every entry
+  required: [api, web]
+  source_type: repo_scan
+requirements:
+  - slug: profile_editing
+    name: People keep their profile current
+    why: ...
+    acceptance: "... Example: ..."
+  - slug: profile_required_fields
+    parent: profile_editing          # another entry, or a requirement already in the project
+    name: A profile can't be saved without a school
+    source_refs: [app/models/academic_experience.rb:12]
+```
+
+Every entry is checked before anything is written: an unknown field (a typo like
+`acceptence`), a bad category or source type, a slug that appears twice or already exists, and
+a parent that isn't found or is itself a child. If any of these fails, nothing is created.
+Parents in the file are created before their children, and the created drafts are printed as
+one table. Run with `--dry-run` first to hand a human the batch for review.
+
+### fp mark
+
+```bash
+fp mark academic_experience_required_fields spec/models/academic_experience_spec.rb:52
+fp mark checkout_flow e2e/checkout.spec.ts:10 --surface web --type e2e
+```
+
+Inserts `fp:<slug>` (with `@surfaces` and `:type` when given) directly above the test on that
+line, using the file's own comment syntax (`#`, `//` or `--`) and indentation, then names the
+test it binds to. Running it again on the same marker changes nothing. `--comment` sets the
+prefix for an extension fp doesn't know, and `--dry-run` shows the line without writing it.
+This is purely local and needs no API key. Never mark a failing test to make a requirement
+look covered.
+
 ### fp propose-change
 
 Propose a change to a requirement that already exists — or propose deleting it.
@@ -332,9 +450,10 @@ fp propose-change print_container_qr --project stowzilla \
 | `--parent` | No | Proposed parent requirement, by slug |
 | `--slug` | No | Proposed new key; evidence follows it, but existing `fp:<slug>` markers must be updated |
 | `--reason` | No | Why the change is needed |
-| `--source-type` | No | `fizzy`, `discord`, `github_issue`, `jira`, `notion`, `manual`, `ai_chat` |
+| `--source-type` | No | `fizzy`, `discord`, `github_issue`, `jira`, `notion`, `manual`, `ai_chat`, `repo_scan` (an agent derived it from the code) |
 | `--source-url` | No | Link to the card/message/issue that prompted it |
 | `--source-context` | No | Free-text context |
+| `--source-ref` | No | A repository place that prompted it, e.g. `app/models/order.rb:42`. Repeatable |
 
 At least one proposed value (or `--removal`) is required — a bare invocation would knock a
 live requirement back to draft for nothing, so it errors instead.
@@ -370,6 +489,54 @@ the review decision where one was made. An open proposal is called out at the en
 
 `--project` is optional when the repo has a `.featureparity.yml`.
 
+### fp question / fp questions
+
+Attach an open question for a human to the requirement it concerns, and read the answers.
+Use it for the decisions a draft can't settle by itself, instead of leaving them in chat.
+
+```bash
+fp question upload_limits "Is the 5 MB cap per file or per upload?"
+fp question upload_limits --body "Does the cap apply to admins?" --project stowzilla
+fp questions upload_limits                 # every question, open and resolved, with answers
+fp questions upload_limits --open --json   # only the open ones
+```
+
+Asking never changes the requirement's status or wording. The human reviewing it sees the
+question in Quick Review and on the requirement page, and answers it (the answer is kept
+with the question) or dismisses it. `fp show <slug>` lists the open questions, and `fp
+history` shows each question and its answer in the timeline. Agents can ask but cannot
+answer or dismiss; there is no CLI command for that.
+
+Draft and active requirements take questions, including a draft awaiting review of a
+proposed change. Refusals, printed verbatim:
+
+| Situation | Status |
+|-----------|--------|
+| No question text, or more than 2000 characters | 422 |
+| Requirement is archived or rejected | 422 |
+
+`--project` is optional when the repo has a `.featureparity.yml`.
+### fp comments
+
+Read or join the team's conversation on a requirement, and tag people or agents in it.
+
+```bash
+fp comments print_container_qr --project stowzilla              # comments + who can be tagged
+fp comments print_container_qr --body "The label redesign dropped this — retire it?" \
+  --tag andy@example.com
+fp comments print_container_qr --body "Can you re-check this against the new label?" --tag claude
+```
+
+A comment never changes the requirement. `--tag` takes a teammate's email or name, or one of
+the team's agents by name or key name; an unknown or ambiguous tag stops the command and
+posts nothing. Tagged people get an email; each tagged agent fires the project's
+`requirement.agent_mentioned` webhook, whose payload names the agent, the requirement and
+the comment, plus the `fp` commands to read and answer it. If a human tagged you, answer
+with `fp comments <slug> --body "..."` — and if the question means the requirement is
+wrong, propose the change with `fp propose-change` rather than settling it in a comment.
+
+`fp comment` (singular) is different: it threads a comment onto an open change proposal.
+
 ### fp analyze
 
 Triage requirement quality: duplicates, fragments of a broader promise, vague wording,
@@ -459,6 +626,52 @@ classifications remain open for a human product decision. A stale candidate is r
 later fingerprint always requires a new assessment. Assessing never changes the requirement
 wording or CI outcome.
 
+### fp spot-check
+
+A random drug test for evidence. A green receipt proves a marked test ran and passed, not
+that it checks what the requirement promises. `fp spot-check` picks one active requirement
+that has evidence on record, at random, and prints its why and acceptance, its receipts, and
+the source of every `fp:<slug>` test it finds in the checkout, then a brief.
+
+```bash
+fp spot-check                         # random pick; prints the seed
+fp spot-check --seed 4821             # repeat that pick
+fp spot-check --surface cli --json    # narrow to one surface; machine-readable
+fp spot-check print_container_qr print_label   # chosen requirements, any status
+fp spot-check --count 5               # five distinct requirements at random
+fp spot-check --all                   # every active requirement with evidence
+fp spot-check --test test/qr_test.rb      # every marked test in the file
+fp spot-check --test test/qr_test.rb:42   # only the test spanning that line
+fp spot-check --path ../android       # look for the tests in another checkout
+```
+
+Use one way of choosing per run: slugs, `--count`, `--all`, or `--test` (which may be
+repeated). The seed is printed only for the random picks. In `--json` the result is
+`checks` (one entry per requirement, each with `requirement`, `evidence` and `tests`), plus
+a single `brief` that applies to every check.
+
+`--prompt` prints the whole spot check as instructions for an agent, so a person or a
+schedule can hand it over as is (`fp spot-check --count 3 --prompt | claude -p`). It ends
+with what to report for each requirement: `proves`, `does_not_prove` or `uncertain`, the
+clauses no assertion checks, the probe made and the tests that failed, and a clean
+`git status`. It can't be combined with `--json`.
+
+`--jev` first sends each requirement's marked tests (up to 10) to Jev and adds its read:
+`agree`, `gaps` or `uncertain`, how likely the tests are to cover the acceptance, the
+likeliest gap (`unasserted_clause`, `asserts_other_behaviour`, `cannot_fail`,
+`tests_a_double`), and a per-test likelihood. Treat it as a hint about where to aim the
+probe. It doesn't replace the probe. Jev is for paid plans: a person on Pro or Lifetime,
+or a project whose owner is (that is what lets an agent use it). Otherwise the spot check
+prints a note and carries on without it. Nothing Jev reads is stored.
+
+The brief: list each result and boundary the acceptance promises; name the clause each
+test's assertions actually check; make one small change to the *product code* that breaks
+the promise, run only those tests, and confirm one fails; revert and confirm `git status` is
+clean. A test that stays green under the probe, or checks something the acceptance doesn't
+say, doesn't prove the requirement. Report that to a human with what you tried. Don't
+rewrite the test or the requirement as part of a spot check. The command itself is
+read-only.
+
 #### Upgrading an existing project
 
 Changed-test auditing requires fp 0.0.17 or newer and the corresponding backend deployment.
@@ -506,6 +719,45 @@ A slug suffixed with `✎` has a proposed change awaiting review — it is still
 the gate, and its evidence is `suspect` until someone reviews the change. `--csv` writes
 `<slug> (under review)` instead of the glyph.
 
+`--status draft --gaps` lists *drafts* with a required surface lacking real evidence
+(missing, stubbed, or failing). Plain `--gaps` reads the gate, which never measures a
+never-approved draft, so on a freshly onboarded project it says "No gaps found". See
+`fp coverage` for the full drafts × surfaces table.
+
+### fp coverage
+
+Draft coverage: which draft requirements have marked tests or evidence on which surfaces,
+and which have none. The gate measures only active requirements (plus ones an open
+proposal demoted), so on a new project where every requirement is still a draft `fp check`
+says "Nothing to enforce yet". This is how an onboarding agent confirms its work before a
+human activates anything.
+
+```bash
+fp coverage                        # drafts × surfaces, then the drafts with no evidence
+fp coverage --surface api
+fp coverage --all                  # also the measured (active / under review) rows
+fp coverage --json                 # drafts, untested, and with --all, measured
+```
+
+| Flag | Description |
+|------|-------------|
+| `--project` | Project slug (optional if `.featureparity.yml` declares one) |
+| `--surface` | Restrict to one surface |
+| `--all` | Also list the requirements the gate measures |
+
+Each cell is resolved from evidence exactly as the matrix will resolve it once the draft is
+active. The command ends with a plain list — the "requirements with no test" section to hand
+the human:
+
+```
+2 draft(s) with no evidence on a required surface:
+  export_csv — no evidence on: web
+  bulk_delete — no evidence on: api, web
+```
+
+"No evidence" means `missing`: nothing at all is filed, not even a stub. Drafts are
+reported, never gated — this command exits 0 on a successful read, whatever it shows.
+
 ### fp check
 
 The enforcement gate. Exits **1** when the project violates its enforcement level, so it
@@ -528,6 +780,7 @@ fp check --surface api --junit junit.xml  # gate on this run's results (preview)
 | `--junit` | Evaluate this run's JUnit results without saving them (repeatable) |
 | `--pr [url]` | With `--junit`: this run is a pull request — fail only on parity it makes worse |
 | `--warn-only` | Report violations but exit 0 |
+| `--include-drafts` | After the verdict, print draft coverage (as `fp coverage`); never changes the exit code. `--json` adds `drafts` |
 
 **Enforcement levels** (the level is configured on the project; don't hardcode one):
 
@@ -616,6 +869,8 @@ Onboard a repo onto FeatureParity. Writes three files and makes no API calls (so
 before a key is configured).
 
 ```bash
+fp init --detect                             # suggest slug, surfaces, test commands; writes nothing
+fp init --detect --json
 fp init --project stowzilla --surface api
 fp init --project stowzilla --no-workflow    # skip the CI workflow
 fp init --project stowzilla --no-agents      # skip the AGENTS.md section
@@ -635,7 +890,53 @@ marker comments and recognised on re-run, so it is never duplicated.
 The `AGENTS.md` section tells agents to bind a test to a requirement with `fp:<slug>`, to
 propose a new requirement when none covers the work, and to use `fp propose-change`
 instead of editing or ignoring a requirement that no longer says the right thing — plus
-the guards they would otherwise learn from a 403.
+the guards they would otherwise learn from a 403. It opens with the fp version that wrote
+it (`Written by fp X.Y.Z`), has an *Onboarding a repo* first-run path and a
+*Troubleshooting* list, and copies its modeling, writing, onboarding and troubleshooting
+blocks from the skill's `SKILL.md` (between `fp-shared` comments) rather than keeping a
+second copy.
+
+`--detect` reads the checkout (Gemfile, package.json, Podfile and Xcode projects, Android
+manifests, pyproject/requirements, Rails routes and `config/database.yml`, docker-compose),
+in the root and one directory down, and prints:
+
+- a suggested slug (the git remote's repo name, else the directory name);
+- suggested surfaces with the reason for each, and the rubric to judge them by: a surface is
+  somewhere a user interacts with the product, and an internal API with no separate client
+  isn't one;
+- each test runner (rspec, minitest, jest, vitest, playwright, pytest, xctest, gradle), the
+  command that makes it write a report fp reads, the dependency that needs adding (or none),
+  and the `fp run` form where there is one;
+- whether the tests need a database server, and whether there's a `.devcontainer`.
+
+A plain `fp init` prints the detected test command and the database note in its closing
+guidance. When the tests need a database server, the generated workflow's report recipe gets
+a TODO and a commented-out service block. Committing the workflow before the `FP_API_KEY`
+secret exists is fine: the gate skips with an explanation and stays green.
+
+### fp doctor
+
+Check that fp works here, with no API key and no API calls.
+
+```bash
+fp doctor
+fp doctor --dir path/to/repo
+fp doctor --json
+```
+
+- **Ruby:** the Ruby running fp, the gem's version and path, the `fp` on `PATH` (and whether
+  it's a version-manager shim), and whether this directory pins a different Ruby in
+  `.ruby-version`, `.tool-versions`, `mise.toml` or `.mise.toml`. On a mismatch it prints
+  the fix: install the gem under the pinned Ruby (`mise exec ruby@<pinned> -- gem install
+  featureparity`, or `gem install featureparity` in the repo), or put the running Ruby's bin
+  directory first on `PATH`.
+- **Config:** the API environment (warning when it isn't production), whether a key is
+  present, which `.featureparity.yml` applies, and which fp wrote the `AGENTS.md` section.
+- **Repo:** the same summary as `fp init --detect`.
+
+`mise ERROR No version is set for shim: fp` comes from the shim, before fp runs, so doctor
+can't catch it from inside that repo. Run it from somewhere fp works (another directory, or
+with the other Ruby's bin directory on `PATH`) to get the commands.
 
 ### fp profile
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: featureparity
 version: !ruby/object:Gem::Version
-  version: 0.0.27
+  version: 0.0.29
 platform: ruby
 authors:
 - Stowzilla
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-11-02 00:00:00.000000000 Z
+date: 2026-11-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-http
@@ -103,25 +103,33 @@ files:
 - lib/fp/commands/check.rb
 - lib/fp/commands/ci_report.rb
 - lib/fp/commands/comment.rb
+- lib/fp/commands/comments.rb
 - lib/fp/commands/config_cmd.rb
 - lib/fp/commands/conversation.rb
+- lib/fp/commands/coverage.rb
+- lib/fp/commands/doctor.rb
 - lib/fp/commands/export.rb
 - lib/fp/commands/help.rb
 - lib/fp/commands/history.rb
 - lib/fp/commands/init.rb
 - lib/fp/commands/list.rb
+- lib/fp/commands/mark.rb
 - lib/fp/commands/matrix.rb
 - lib/fp/commands/profile.rb
 - lib/fp/commands/projects.rb
 - lib/fp/commands/propose.rb
 - lib/fp/commands/propose_change.rb
+- lib/fp/commands/question.rb
 - lib/fp/commands/report.rb
 - lib/fp/commands/repos.rb
+- lib/fp/commands/run.rb
 - lib/fp/commands/setup.rb
 - lib/fp/commands/show.rb
 - lib/fp/commands/showroom.rb
 - lib/fp/commands/showroom_media.rb
+- lib/fp/commands/spot_check.rb
 - lib/fp/commands/surfaces.rb
+- lib/fp/commands/tutorial.rb
 - lib/fp/commands/version.rb
 - lib/fp/commands/whoami.rb
 - lib/fp/config.rb
@@ -129,7 +137,16 @@ files:
 - lib/fp/output.rb
 - lib/fp/parity.rb
 - lib/fp/project_config.rb
+- lib/fp/repo_detector.rb
+- lib/fp/requirement_lint.rb
+- lib/fp/rspec_json.rb
 - lib/fp/source_fingerprint.rb
+- lib/fp/tutorial/hexhaven/AGENTS.md
+- lib/fp/tutorial/hexhaven/README.md
+- lib/fp/tutorial/hexhaven/lib/hexhaven.rb
+- lib/fp/tutorial/hexhaven/test/junit_reporter.rb
+- lib/fp/tutorial/hexhaven/test/rules_test.rb
+- lib/fp/tutorial/hexhaven/test/test_helper.rb
 - lib/fp/version.rb
 - skills/fp/SKILL.md
 - skills/fp/references/cli.md