featureparity 0.0.14 → 0.0.16

data/skills/fp/references/cli.md

@@ -130,36 +130,75 @@ In JUnit mode:
 
 ### fp propose
 
-Propose a new requirement as draft.
+Propose a new requirement as a draft. Before proposing, inventory the full request and compare
+it with both active and draft requirements. The catalog should tell a reviewer what the product
+promises, not preserve the first implementation idea somebody mentioned.
+
+Use one focused requirement per independently testable or failable product promise. Use a
+parent plus children for a broad capability with distinct behaviours, policies, or
+surface-specific promises. If the work makes an existing requirement inaccurate, use
+`fp propose-change` as well as adding anything new.
+
+Before adding or changing a requirement, compare its acceptance criteria with related active
+and draft requirements and their history. Ask whether both promises can be true for the same
+user, state, and conditions. A failing bound test or an implementation that requires changing
+an existing promise is a contradiction signal: decide which promise reflects product intent,
+then record that decision with `fp propose-change` or `--removal`. Do not weaken the test or add
+a second requirement around the conflict; ask a human when product intent is unclear.
 
 ```bash
 fp propose --project stowzilla \
-  --slug print_container_qr \
-  --name "Print QR on container label" \
-  --why "Staff scan the label to find a container; without a QR they key the ID by hand and mis-type it" \
-  --required api,customer_android \
-  --acceptance "QR scans to the container's detail page"
+  --slug current_shipment_status \
+  --name "Dispatchers see current shipment status" \
+  --why "Dispatchers need to spot delayed shipments before they miss a delivery window" \
+  --required api,web \
+  --acceptance "When a shipment's status changes, the dashboard shows the new status; if status is unavailable, it says so instead of presenting stale data as current" \
+  --source-type fizzy \
+  --source-url https://app.fizzy.do/123/cards/456
 ```
 
 | Flag | Required | Description |
 |------|----------|-------------|
 | `--project` | Yes | Project slug |
-| `--slug` | Yes | Requirement slug (immutable, choose carefully) |
-| `--name` | Yes | Human-readable name |
-| `--why` | No | One plain sentence: the user need or outcome the feature serves (see below) |
+| `--slug` | Yes | Initial requirement key (later corrections use `propose-change`) |
+| `--name` | Yes | Short product promise in present tense |
+| `--why` | No | User need, problem or risk, and valuable outcome |
 | `--required` | No | Comma-separated surfaces that must implement this |
-| `--acceptance` | No | The observable condition that proves it's done |
-
-**Writing `--why`:** brief, and it actually explains why. Whoever approves this should
-grasp in one read the user need or outcome the feature serves. Longer is fine when it
-earns its length; wordy is not. Avoid filler, and avoid describing *how* it works
-instead of *why* anyone wants it.
-
-- ✅ `"Staff scan the label to find a container; without a QR they key the ID by hand and mis-type it."`
-- ❌ `"Ensures a high-quality experience across all surfaces."` (filler)
-- ❌ `"The label renders a QR image encoding the container ID at print time."` (how it works, not why)
-
-**Agents always create requirements as draft.** A human must activate in the web app.
+| `--acceptance` | No | Observable behaviour and material boundaries |
+
+**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
+the intended outcome. Treat it as the current record of an ongoing conversation, not a finished
+decree from product to engineering. Humans decide value and priority; agents surface gaps,
+inconsistencies, alternatives, and useful splits. Prefer outcomes over feature lists.
+
+- **Title:** name the capability or outcome, not the work (`Dispatchers see current shipment
+  status`, not `Implement status polling`).
+- **Why:** use one or two natural sentences to say who needs this, the problem or risk, and the
+  outcome worth protecting. Do not repeat the title, sell the feature, explain the mechanism,
+  or pad it with phrases such as “ensure a seamless, robust experience.”
+- **Acceptance:** state the relevant trigger or situation, the observable result, and material
+  boundaries such as permissions, unavailable states, and affected surfaces. Concrete examples
+  and tests ground and double-check the rule; they do not define every case or replace the
+  general rule and continued conversation.
+- **Numbers and policy:** include prices, quotas, timeouts, counts, dates, roles, and fallbacks
+  only when the source made them real product decisions or external constraints. Never invent a
+  plausible value to fill silence; ask when the answer changes the promise.
+- **Implementation detail:** omit components, data models, algorithms, endpoints, polling
+  intervals, and UI controls unless the interface or constraint is itself part of the promise.
+
+Learn from observed user behaviour and other evidence when available: what people attempt,
+where they abandon a task, what they actually use, and what experiments reveal. The first
+proposed solution may point at the need without defining the right scope. Preserve meaningful
+uncertainty as a question instead of laundering a guess into acceptance criteria. Concise does
+not mean vague: keep every sentence that changes the decision and cut everything that only
+sounds thorough.
+
+Before saving, ask: Is the value clear? Can the result be observed? Are decided policies
+separated from guesses? Could clauses fail independently and need splitting? Does every sentence
+earn its place?
+
+**Agents always create requirements as draft.** A human must activate them in the web app.
 
 ### fp propose-change
 
@@ -191,7 +230,7 @@ fp propose-change print_container_qr --project stowzilla \
 | `--required` | No | Proposed surfaces (comma-separated; agents cannot remove existing ones) |
 | `--category` | No | Proposed category |
 | `--parent` | No | Proposed parent requirement, by slug |
-| `--slug` | No | Proposed new slug — **humans only**; breaks existing `fp:<slug>` markers |
+| `--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-url` | No | Link to the card/message/issue that prompted it |
@@ -204,7 +243,7 @@ Refusals, all printed verbatim:
 
 | Situation | Status |
 |-----------|--------|
-| Agent tries to change `--slug` | 403 |
+| Proposed key belongs to another requirement | 422 |
 | Agent tries to remove a required surface | 403 |
 | Proposed values match the current text | 422 |
 | Requirement already has a proposal awaiting review | 409 |
@@ -231,6 +270,31 @@ 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 changes
+
+Show requirement activity prompted by a work item, rather than opening every requirement's
+history separately.
+
+```bash
+fp changes --source-url https://app.fizzy.do/6098707/cards/1434
+fp changes --project stowzilla --source-url https://github.com/acme/app/issues/42
+fp changes --github-pr --github-summary
+```
+
+`--source-url` may be repeated. The API matches the URL exactly against the source recorded
+when a requirement was created, directly edited, proposed for modification, or proposed for
+removal. Results include the requirement, activity kind, review state, actor, and a link to the
+requirement.
+
+In a GitHub pull-request workflow, `--github-pr` reads the live PR through the GitHub API and
+writes or replaces one marker-managed requirement table in its description. It requires
+`GITHUB_TOKEN`, `GITHUB_REPOSITORY`, `GITHUB_EVENT_PATH`, and `pull-requests: write`; inability
+to read or update the PR is an error, so a missing table cannot silently pass. Add
+`--github-summary` to keep the same table in `GITHUB_STEP_SUMMARY`. A PR with no linked work
+item says FeatureParity cannot determine the activity; a linked work item with no events
+explicitly says no requirement changes were recorded. Generated `fp init` workflows configure
+both outputs before the parity gate.
+
 ### fp matrix
 
 Display the parity matrix. Cells show the state of the evidence filed for each
@@ -334,7 +398,7 @@ fp init --project stowzilla --dir path/to/repo
 | File | Purpose |
 |------|---------|
 | `.featureparity.yml` | declares the project slug, so `--project` becomes optional |
-| `.github/workflows/feature-parity.yml` | the CI gate |
+| `.github/workflows/feature-parity.yml` | the CI gate and PR requirement-change summary |
 | `AGENTS.md` (appended) | instructions telling agents to mark and report their tests |
 
 Existing files are skipped unless `--force`. The `AGENTS.md` section is appended between

data/skills/fp/references/markers.md

@@ -26,6 +26,31 @@ Examples:
 
 When using `fp report --junit`, each pinned surface produces a separate evidence upload.
 
+## Test-type pinning
+
+A requirement can demand several *kinds* of test (a unit test and an end-to-end test,
+say). Pin a marker's kind with a `:type` suffix, after the surfaces if any:
+
+```
+fp:<slug>:<type>
+fp:<slug>@<surface>:<type>
+fp:<slug>@<surface1>,<surface2>:<type>
+```
+
+Valid types: `unit`, `integration`, `e2e`, `manual`, `other`.
+
+Examples:
+- `fp:print_qr` — unspecified type (and the `--surface` default)
+- `fp:print_qr:unit` — filed as a unit test
+- `fp:print_qr@api:e2e` — the `api` surface, filed as an e2e test
+- `fp:print_qr@api,web:e2e` — both surfaces, each filed as an e2e test
+
+A marker that pins no type takes the `--test-type` flag's value (if given), otherwise
+`unspecified`. A requirement declares which kinds it needs with
+`fp propose --required-types unit,e2e`; a surface is covered only once every demanded
+kind has evidence. A requirement naming no types inherits the project default, and when
+neither is set any one test satisfies a surface.
+
 ## Language examples
 
 ### Ruby/RSpec

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: featureparity
 version: !ruby/object:Gem::Version
-  version: 0.0.14
+  version: 0.0.16
 platform: ruby
 authors:
 - Stowzilla
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-21 00:00:00.000000000 Z
+date: 2026-10-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-http
@@ -94,10 +94,14 @@ files:
 - lib/fp/cli.rb
 - lib/fp/client.rb
 - lib/fp/commands.rb
+- lib/fp/commands/attach.rb
+- lib/fp/commands/attachments.rb
 - lib/fp/commands/base.rb
+- lib/fp/commands/changes.rb
 - lib/fp/commands/check.rb
 - lib/fp/commands/ci_report.rb
 - lib/fp/commands/config_cmd.rb
+- lib/fp/commands/conversation.rb
 - lib/fp/commands/export.rb
 - lib/fp/commands/help.rb
 - lib/fp/commands/history.rb