featureparity 0.0.13 → 0.0.15

data/lib/fp/junit.rb

@@ -32,8 +32,13 @@ module Fp
     # One requirement's aggregated CI outcome for one surface, ready to hand to the
     # backend's ingest endpoint. This is what lets CI upload *resolved* results rather
     # than raw XML the server would have to re-scrape the repo to understand.
-    CiResult = Struct.new(:slug, :surface, :status, :file, :line, :test_count, :failure_count,
-                          keyword_init: true)
+    #
+    # `title` names a representative test — the first one that *failed* when the verdict
+    # is `failing`, otherwise the first that ran. Without it the evidence row keeps
+    # whatever title an earlier agent report left behind, and the web app then blames a
+    # test that is perfectly green for the failure.
+    CiResult = Struct.new(:slug, :surface, :test_type, :status, :file, :line, :title, :test_count,
+                          :failure_count, keyword_init: true)
 
     # A failing testcase that carries no fp:<slug> marker at all — a "loose end". Not a
     # cell on the parity grid (nothing binds it to a requirement) and not an orphan
@@ -47,25 +52,37 @@ module Fp
     # know *which* test the marker sits above (matched by line or by test name) or only
     # that the marker is somewhere in the same file — a title is only worth reporting in
     # the first case.
-    Match = Struct.new(:testcase, :marker, :precise, keyword_init: true)
+    #
+    # `repo_file` is the testcase's source file expressed relative to the *repository
+    # root*, which is what gets reported. The path in the report is relative to whatever
+    # directory the runner was invoked from (vitest reports `src/pages/Foo.test.jsx` from
+    # inside `frontend/`), so reporting it verbatim produces a link to a file that doesn't
+    # exist at that path in the repo.
+    Match = Struct.new(:testcase, :marker, :precise, :repo_file, keyword_init: true)
 
     # Evidence discovered by binding a testcase to a marker.
     # `line` is the 1-based line number of the test in its source file: the
     # testcase's own line when the runner reported one, otherwise the line of
     # the fp:<slug> marker that annotates it (markers sit directly above the
     # test, so the marker line is a close stand-in when the runner omits lines).
-    Binding = Struct.new(:slug, :surface, :file, :line, :title, :state, keyword_init: true)
+    Binding = Struct.new(:slug, :surface, :test_type, :file, :line, :title, :state, keyword_init: true)
 
     # Matches `fp:<slug>` inside a comment, with an optional `@surface` (or
-    # `@surface1,surface2`) suffix to target one or more specific surfaces:
+    # `@surface1,surface2`) suffix to target one or more specific surfaces, and an
+    # optional `:<type>` suffix to pin the kind of test:
     #
-    #   fp:print_qr                # uses the --surface flag as the default
+    #   fp:print_qr                # --surface flag default, unspecified type
     #   fp:print_qr@api            # reports evidence for the `api` surface
     #   fp:print_qr@api,web        # reports for both `api` and `web`
+    #   fp:print_qr@api:e2e        # the `api` surface, filed as an e2e test
+    #   fp:print_qr:unit           # --surface default, filed as a unit test
+    #   fp:print_qr@api,web:e2e    # both surfaces, each filed as an e2e test
     #
-    # Slugs and surfaces are lowercase letters, digits, underscores and hyphens
-    # (matching the propose/report convention).
-    MARKER_RE = /fp:([a-z0-9][a-z0-9_-]*)(?:@([a-z0-9_-]+(?:,[a-z0-9_-]+)*))?/.freeze
+    # The type pins the kind of test (unit, integration, e2e, manual, other) so a
+    # requirement that demands several kinds can tell them apart. It applies to every
+    # surface the marker names. Slugs, surfaces and types are lowercase letters, digits,
+    # underscores and hyphens (matching the propose/report convention).
+    MARKER_RE = /fp:([a-z0-9][a-z0-9_-]*)(?:@([a-z0-9_-]+(?:,[a-z0-9_-]+)*))?(?::([a-z0-9_-]+))?/.freeze
 
     # A marker only counts when it is a comment on its own line — the documented
     # convention ("the fp:<slug> comment sits immediately above its test"). Requiring a
@@ -174,7 +191,7 @@ module Fp
     #     unmatched: [TestCase, ...],     # testcases with no discoverable marker
     #     missing_surface: [Binding-ish], # markers with no surface and no default
     #   }
-    def bind_markers(testcases, base_dir: Dir.pwd, default_surface: nil)
+    def bind_markers(testcases, base_dir: Dir.pwd, default_surface: nil, default_test_type: nil)
       bindings = {}
       matched = {}
       missing_surface = []
@@ -187,11 +204,17 @@ module Fp
         surfaces = marker[:surfaces]
         surfaces = [default_surface] if surfaces.empty?
 
+        # The marker's own type pin wins; otherwise the --test-type default (nil → the
+        # server files it as `unspecified`).
+        test_type = marker[:test_type] || default_test_type
+
         surfaces.each do |surface|
           if surface.nil? || surface.empty?
             missing_surface << { slug: marker[:slug], file: tc.file }
           else
-            record_binding(bindings, marker[:slug], surface, tc, marker, titles_reliable: match.precise)
+            record_binding(bindings, marker[:slug], surface, tc, marker,
+                           titles_reliable: match.precise, file: match.repo_file,
+                           test_type: test_type)
           end
         end
       end
@@ -212,7 +235,7 @@ module Fp
     # it was skipped (a skipped test is not proof of anything), and `passing` otherwise.
     #
     # Returns { results: [CiResult, ...], unmatched: [TestCase], missing_surface: [...] }.
-    def ci_results(testcases, base_dir: Dir.pwd, default_surface: nil)
+    def ci_results(testcases, base_dir: Dir.pwd, default_surface: nil, default_test_type: nil)
       aggregates = {}
       matched = {}
       missing_surface = []
@@ -225,31 +248,47 @@ module Fp
         surfaces = marker[:surfaces]
         surfaces = [default_surface] if surfaces.empty?
 
+        # The marker's own type pin wins; otherwise the --test-type default (nil → the
+        # server files it as `unspecified`). One CI verdict per (slug, surface, type).
+        test_type = marker[:test_type] || default_test_type
+
         surfaces.each do |surface|
           if surface.nil? || surface.empty?
             missing_surface << { slug: marker[:slug], file: tc.file }
             next
           end
 
-          key = [marker[:slug], surface]
-          agg = aggregates[key] ||= { file: tc.file, line: tc.line || marker[:line], ran: 0, failed: 0, skipped: 0 }
+          key = [marker[:slug], surface, test_type]
+          agg = aggregates[key] ||= { file: match.repo_file, line: tc.line || marker[:line],
+                                      title: nil, failing_title: nil, ran: 0, failed: 0, skipped: 0 }
           if tc.stub?
             agg[:skipped] += 1
           else
             agg[:ran] += 1
             agg[:failed] += 1 if tc.failed?
           end
+
+          # Name a test for the evidence row. The first *failing* test is the one a human
+          # wants to see when the cell goes red; otherwise the first that ran will do.
+          # Only when we know which test the marker annotates — a guess here is worse
+          # than no title.
+          if match.precise && (title = presence(tc.name))
+            agg[:title] ||= title
+            agg[:failing_title] ||= title if tc.failed?
+          end
         end
       end
 
-      results = aggregates.map do |(slug, surface), agg|
+      results = aggregates.map do |(slug, surface, test_type), agg|
         status =
           if agg[:failed].positive? then 'failing'
           elsif agg[:ran].zero? then 'stub'
           else 'passing'
           end
 
-        CiResult.new(slug: slug, surface: surface, status: status, file: agg[:file], line: agg[:line],
+        CiResult.new(slug: slug, surface: surface, test_type: test_type, status: status,
+                     file: agg[:file], line: agg[:line],
+                     title: agg[:failing_title] || agg[:title],
                      test_count: agg[:ran], failure_count: agg[:failed])
       end
 
@@ -274,21 +313,66 @@ module Fp
     # can never disagree about which test a marker annotates.
     def walk_matches(testcases, base_dir)
       marker_cache = {}
+      root = repo_root_for(base_dir)
 
       # Group testcases by their source file so we can reason about ordering.
-      testcases.group_by(&:file).each do |_file, cases|
+      testcases.group_by(&:file).each do |file, cases|
         markers = markers_for(cases.first, base_dir, marker_cache)
         next if markers.empty?
 
+        repo_file = repo_relative_path(file, base_dir, root)
+
         cases.each do |tc|
           marker, precise = marker_for(tc, cases, markers)
           next unless marker
 
-          yield Match.new(testcase: tc, marker: marker, precise: precise)
+          yield Match.new(testcase: tc, marker: marker, precise: precise, repo_file: repo_file)
         end
       end
     end
 
+    # The repository root containing `dir`, or nil when `dir` isn't inside one.    #
+    # Found by walking up for a `.git` entry rather than shelling out to git, so it also
+    # works in a worktree (where `.git` is a file) and costs nothing.
+    def repo_root_for(dir)
+      current = File.expand_path(dir)
+
+      loop do
+        return current if File.exist?(File.join(current, '.git'))
+
+        parent = File.dirname(current)
+        return nil if parent == current
+
+        current = parent
+      end
+    end
+
+    # Express a report's test-file path relative to the repository root.
+    #
+    # The path in a JUnit report is relative to wherever the runner ran, which is not
+    # necessarily the repo root — vitest invoked in `frontend/` reports
+    # `src/pages/Matrix.test.jsx`, and `--base-dir frontend` is what makes that resolvable
+    # locally. Evidence is rendered as a GitHub link built from the repo plus this path,
+    # so reporting it verbatim links to a path that doesn't exist (a 404).
+    #
+    # Falls back to the path as given when there's no repo to relativise against, or when
+    # the file resolves outside it.
+    def repo_relative_path(file, base_dir, root = repo_root_for(base_dir))
+      return file if file.nil? || file.empty? || root.nil?
+
+      absolute = File.expand_path(file, base_dir)
+      prefix = "#{root}#{File::SEPARATOR}"
+      return file unless absolute.start_with?(prefix)
+
+      absolute.delete_prefix(prefix)
+    end
+
+    # nil for blank, the stripped value otherwise.
+    def presence(value)
+      stripped = value.to_s.strip
+      stripped.empty? ? nil : stripped
+    end
+
     # Determine the marker (slug + surfaces) that annotates a testcase.
     # Returns [marker, precise] — or [nil, false] when nothing can be tied to it.
     def marker_for(testcase, sibling_cases, markers)
@@ -363,9 +447,12 @@ module Fp
       candidate
     end
 
-    def record_binding(bindings, slug, surface, testcase, marker, titles_reliable: true)
-      rel_file = testcase.file
-      key = [slug, surface, rel_file]
+    def record_binding(bindings, slug, surface, testcase, marker, titles_reliable: true, file: nil,
+                       test_type: nil)
+      rel_file = file || testcase.file
+      # test_type is part of the key: a unit test and an e2e test for the same
+      # slug/surface/file are distinct evidence rows, so they mustn't collapse into one.
+      key = [slug, surface, test_type, rel_file]
       state = testcase.stub? ? 'stub' : 'present'
 
       # The test's line: prefer the runner-reported testcase line; fall back to
@@ -377,8 +464,8 @@ module Fp
       # Prefer a concrete 'present' state over 'stub' when a slug has both.
       return if existing && !(existing.state == 'stub' && state == 'present')
 
-      bindings[key] = Binding.new(slug: slug, surface: surface, file: rel_file, line: line,
-                                  title: (testcase.name if titles_reliable), state: state)
+      bindings[key] = Binding.new(slug: slug, surface: surface, test_type: test_type, file: rel_file,
+                                  line: line, title: (testcase.name if titles_reliable), state: state)
     end
 
     # Load and cache the fp:<slug> markers (with line numbers) for a testcase's
@@ -400,9 +487,10 @@ module Fp
       cache[file] = markers
     end
 
-    # Scan file contents for fp:<slug>[@surface[,surface...]] markers, returning
-    # [{ slug:, surfaces: [..], line:, title:, title_kind: }, ...] (1-based line numbers).
-    # `surfaces` is [] when the marker pins none (use the default surface).
+    # Scan file contents for fp:<slug>[@surface[,surface...]][:type] markers, returning
+    # [{ slug:, surfaces: [..], test_type:, line:, title:, title_kind: }, ...]
+    # (1-based line numbers). `surfaces` is [] when the marker pins none (use the default
+    # surface). `test_type` is nil when the marker pins none (filed as `unspecified`).
     #
     # `title` is the name of the test (or describe block) declared below the marker, used
     # to bind markers to results from runners that report no line numbers. It is nil when
@@ -415,10 +503,11 @@ module Fp
       lines.each_with_index do |line, idx|
         next unless line.match?(COMMENT_LINE_RE)
 
-        line.scan(MARKER_RE) do |(slug, surface_list)|
+        line.scan(MARKER_RE) do |(slug, surface_list, test_type)|
           surfaces = surface_list ? surface_list.split(',').map(&:strip).reject(&:empty?) : []
           title, kind = declared_test_after(lines, idx)
-          markers << { slug: slug, surfaces: surfaces, line: idx + 1, title: title, title_kind: kind }
+          markers << { slug: slug, surfaces: surfaces, test_type: presence(test_type),
+                       line: idx + 1, title: title, title_kind: kind }
         end
       end
       markers

data/lib/fp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fp
-  VERSION = '0.0.13'
+  VERSION = '0.0.15'
 end

data/skills/fp/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fp
-description: "Use the fp CLI to track feature parity: report evidence linking tests to requirements, propose new requirements as drafts, view the parity matrix, and upload test results from JUnit XML when CI isn't available."
+description: "Use the fp CLI as a complete product specification: write decision-ready requirements, inventory and decompose scope, manage changes through review, bind tests to focused promises, report evidence, and inspect parity."
 license: MIT
 compatibility: Requires the fp executable on PATH (gem install featureparity)
 metadata:
@@ -41,17 +41,50 @@ If not set, ask the user for their API key or have them run `fp setup`.
 
 ## Core workflows
 
-### 1. Check existing requirements
+### 1. Inventory and model the complete requirement scope
 
 ```bash
 fp list --project stowzilla                    # All active requirements
+fp list --project stowzilla --status draft     # Proposed work; avoid duplicates
 fp list --project stowzilla --gaps             # Requirements with a required surface lacking evidence
-fp show <slug> --project stowzilla             # Requirement details
+fp show <slug> --project stowzilla             # Requirement details and evidence
+fp history <slug> --project stowzilla          # Origins and pending changes
 fp matrix --project stowzilla                  # ASCII parity matrix
 fp matrix --project stowzilla --csv            # Export as CSV
 fp check --project stowzilla                   # Enforce parity (exits 1 on violations)
 ```
 
+Treat FeatureParity as the human-readable product specification, not a bookkeeping step.
+Before coding, inventory the entire request: user-visible behaviours, policies, limits,
+plans, deadlines, state transitions, permissions, failure modes, and affected surfaces.
+Compare all of it with active and draft requirements, including adjacent requirements the
+change might make inaccurate.
+
+Model that scope deliberately:
+
+- One independently testable or independently failable product promise per focused
+  requirement. Split an acceptance sentence when its clauses could pass or fail separately.
+- Use a parent for a broad capability and children for distinct behaviours, policies, or
+  surface-specific promises. Do not model implementation details with no product promise.
+- Record concrete decisions such as prices, quotas, dates, roles, and fallbacks in acceptance
+  criteria rather than leaving them as assumptions in code or a pull request.
+- Propose changes to existing requirements whose meaning moved; adding a new requirement is
+  not enough if it leaves an old one false.
+- Reconcile again before finishing: every shipped behaviour maps to a current requirement,
+  every changed promise is recorded, and every focused requirement has marked evidence or
+  remains an explicit gap. Never let one broad marker imply coverage of untested clauses.
+
+**Prevent contradictions before they enter the catalog.** Before proposing a new or changed
+promise, compare its intended acceptance criteria with related active and draft requirements
+and read their history. Ask whether both promises can be true at the same time for the same
+user, state, and conditions. If not, do not add another requirement.
+
+A failing test bound to an existing requirement, or an implementation that only works by
+changing one, is a contradiction signal — not permission to weaken the test or write a second
+requirement around it. Identify which promise matches product intent, then use
+`fp propose-change` (or `--removal`) with the source and reason to put that decision before a
+human. If the intent is unclear, stop and ask rather than making the catalog say both things.
+
 ### 2. Add the fp:<slug> marker to tests
 
 Place a comment immediately before the test to bind it to a requirement:
@@ -106,31 +139,82 @@ fp report --junit junit.xml \
 - `--surface` is the default; markers can override with `@suffix`
 - `--base-dir DIR` sets where relative paths resolve from
 
-### 5. Propose new requirements
+### 5. Write and propose decision-ready requirements
+
+A requirement is a product decision a reviewer can approve, not a design task for an
+engineer to carry out. It should sound like a capable teammate wrote it: natural, direct,
+and specific enough to protect an outcome without dictating an accidental solution.
+
+Treat the catalog as the current record of shared understanding, not a finished specification
+handed from a product owner to implementers. Requirements are discovered and refined through
+ongoing conversation among customers, domain experts, and builders. The human product owner
+makes the final value and priority decisions; agents participate by exposing gaps,
+inconsistencies, alternatives, and useful splits. Prefer customer outcomes over devotion to a
+feature list.
+
+Before drafting:
+
+- Learn from the request, related requirements and history, support reports, research, and
+  observed user behaviour when available. Look for what people attempt, where they abandon a
+  task, what they actually use, and what experiments reveal. That evidence may expose a
+  different need from the first solution they suggested.
+- Separate facts and decided policy from open questions. Never turn a missing decision into
+  a plausible-sounding price, quota, timeout, count, date, role, or fallback. Ask when the
+  answer changes the product promise.
+- Identify the actor, the situation that triggers the need, the valuable outcome, and material
+  boundaries such as permissions, failures, and affected surfaces.
+- Keep one independently failable promise per requirement. Use a parent and focused children
+  when a capability contains several decisions.
+
+Write each field for a reviewer, not for the implementation:
+
+- **Title:** one clear product promise in present tense. Name the capability or outcome, not
+  the project (`Dispatchers see current shipment status`, not `Implement status polling`).
+- **Why:** one or two natural sentences saying who needs this, the problem or risk, and the
+  outcome worth protecting. Do not repeat the title, advertise the feature, or explain how
+  it will be built. Delete AI filler such as “ensure a seamless, robust experience.”
+- **Acceptance:** observable behaviour that lets someone decide whether the promise is true.
+  State the relevant trigger or situation, the result, and material boundaries. Include
+  failure behaviour, permissions, or cross-surface consistency when those affect the promise.
+- **Examples:** use concrete examples or Given/When/Then cases when they clarify a rule or an
+  edge. Examples and executable tests ground and double-check the specification; they do not
+  define every case or replace the general rule and continued conversation.
+- **Numbers and policy:** include a number only when the source made it a real product decision
+  or an external constraint requires it. Do not invent implementation defaults and present
+  them as scope.
+- **Implementation detail:** omit components, data models, algorithms, endpoints, polling
+  intervals, and UI controls unless that interface or constraint is itself user-visible policy.
+
+A good requirement is concise, not merely short. Keep every sentence that changes a decision;
+remove everything that only sounds thorough.
+
+- ✅ **Title:** `Dispatchers see current shipment status`
+  **Why:** `Dispatchers need to spot delayed shipments before they miss a delivery window.`
+  **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.`
+- ❌ **Title:** `Implement Redis-backed 30-second status polling`
+  **Why:** `This important feature ensures a seamless, robust experience.`
+  **Acceptance:** `Use a background worker and refresh every 30 seconds.`
+  This invents policy, prescribes a design, and never states the outcome.
+
+Before saving, read the draft as a manager deciding scope: Is the value clear? Can the result
+be observed? Are real product decisions distinguished from guesses? Could every clause fail
+independently and, if so, should it be split? Does every sentence earn its place? Revise or ask
+before creating the record if the answer is no.
+
+Then create the proposal as a draft:
 
 ```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
 ```
 
-**Writing `--why`: brief, and it actually explains why.** Whoever approves this
-requirement should grasp in one read why the product needs it — the user problem it
-solves or the outcome it protects. State that and stop. Longer is fine when it earns
-its length; wordy is not. Avoid two things: filler that says nothing specific, and
-describing *how* the feature works instead of *why* anyone wants it.
-
-- ✅ `--why "Staff scan the label to find a container; without a QR they key the ID by hand and mis-type it."`
-- ❌ `--why "Ensures a high-quality experience across all surfaces."` (filler — says nothing specific)
-- ❌ `--why "The label renders a QR image encoding the container ID at print time."` (how it works, not why anyone needs it)
-
-Same rule for `--acceptance`: the observable condition that proves it's done, not a
-restatement of the title.
-
-**Agents always create requirements as draft.** A human must activate in the web app.
+**Agents always create requirements as draft.** A human must activate them in the web app.
 
 ### 6. Propose a change to an existing requirement
 
@@ -158,8 +242,9 @@ Rules:
 
 - Always pass `--reason` and, where one exists, `--source-type`/`--source-url`. The whole
   point of a proposal is that the *why* is recorded next to the *what*.
-- Agents cannot change `--slug` (it's the join to every `fp:<slug>` marker) or remove a
-  required surface. Both come back as a 403, printed verbatim.
+- Agents may correct `--name` (the title) or `--slug` through a proposal. Existing
+  evidence follows a proposed slug, but every `fp:<slug>` marker still needs the same
+  correction. Agents still cannot remove a required surface.
 - Agents cannot approve or reject. Only humans review.
 - One open proposal per requirement — review the current one before proposing another.
 

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 |

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.13
+  version: 0.0.15
 platform: ruby
 authors:
 - Stowzilla
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-21 00:00:00.000000000 Z
+date: 2026-10-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-http
@@ -94,10 +94,13 @@ 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/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