featureparity 0.0.28 → 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,14 @@ 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
@@ -306,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.
@@ -338,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.
@@ -376,6 +489,33 @@ 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.
@@ -579,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
@@ -601,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):
 
@@ -689,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
@@ -708,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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: featureparity
 version: !ruby/object:Gem::Version
-  version: 0.0.28
+  version: 0.0.29
 platform: ruby
 authors:
 - Stowzilla
@@ -106,18 +106,23 @@ files:
 - 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
@@ -132,6 +137,9 @@ 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