featureparity 0.0.14 → 0.0.16

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
@@ -46,9 +51,13 @@ module Fp
     # A testcase paired with the marker that annotates it. `precise` records whether we
     # 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. `repo_file` is the testcase's source path made relative to the git
-    # repo root (see repo_relative_file), so evidence links resolve regardless of the
-    # base_dir the runner reported paths against.
+    # the first case.
+    #
+    # `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.
@@ -56,18 +65,24 @@ module Fp
     # 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
@@ -176,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 = []
@@ -189,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, match.repo_file, 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
@@ -214,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 = []
@@ -227,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: match.repo_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
 
@@ -276,17 +313,14 @@ module Fp
     # can never disagree about which test a marker annotates.
     def walk_matches(testcases, base_dir)
       marker_cache = {}
-      prefix_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|
         markers = markers_for(cases.first, base_dir, marker_cache)
         next if markers.empty?
 
-        # The path we'll store as evidence: relative to the git root, not to base_dir,
-        # so a GitHub blob link resolves. base_dir's offset below the root is cached, so
-        # this is one shell-out per run, not per file.
-        repo_file = repo_relative_file(file, base_dir, prefix_cache)
+        repo_file = repo_relative_path(file, base_dir, root)
 
         cases.each do |tc|
           marker, precise = marker_for(tc, cases, markers)
@@ -297,6 +331,48 @@ module Fp
       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)
@@ -371,9 +447,12 @@ module Fp
       candidate
     end
 
-    def record_binding(bindings, slug, surface, testcase, marker, repo_file, titles_reliable: true)
-      rel_file = repo_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
@@ -385,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
@@ -408,73 +487,10 @@ module Fp
       cache[file] = markers
     end
 
-    # Rewrite a report-relative test-file path so it is relative to the git repo root.
-    #
-    # Runners report paths relative to wherever they ran: RSpec/minitest from the repo
-    # root, but vitest from its own package (frontend/), which is why the web job passes
-    # `--base-dir frontend`. That base_dir is enough to *find* the markers, but the path
-    # we then store as `source_file` was the raw report path (`src/pages/Matrix.test.jsx`),
-    # not the repo-root path (`frontend/src/pages/Matrix.test.jsx`). The web app builds a
-    # GitHub link as `blob/<sha>/<source_file>`, and a blob path is always relative to the
-    # git root — so the missing `frontend/` prefix produced a 404 on every web test link.
-    #
-    # The fix is purely additive: find how far base_dir sits below the git root and
-    # prepend that. When base_dir *is* the git root (the Ruby suites, run from the repo
-    # root), the prefix is empty and the original path is returned byte-for-byte — so this
-    # only ever corrects a subdirectory base_dir and never rewrites a path that was
-    # already right. Falls back to the raw path when there's no git checkout (an agent
-    # running from a tarball) or base_dir sits outside one.
-    def repo_relative_file(file, base_dir, cache = {})
-      return file if file.nil? || file.empty?
-
-      prefix = base_dir_prefix(base_dir, cache)
-      return file if prefix.nil? || prefix.empty?
-
-      File.join(prefix, file)
-    end
-
-    # base_dir's path relative to the git root that contains it: '' when base_dir is the
-    # root, 'frontend' when it's a package below it, nil when base_dir isn't in a checkout
-    # (or sits above the root). Cached per base_dir so a report shells out once.
-    def base_dir_prefix(base_dir, cache)
-      absolute = File.expand_path(base_dir)
-      return cache[absolute] if cache.key?(absolute)
-
-      root = git_toplevel_for(absolute)
-      prefix =
-        if root.nil?
-          nil
-        else
-          rel = relative_path(absolute, root)
-          rel == '.' || rel.start_with?('..') ? '' : rel
-        end
-      cache[absolute] = prefix
-    end
-
-    # The git repo root containing `dir`, or nil if `dir` isn't inside a checkout.
-    def git_toplevel_for(dir)
-      out = `git -C #{quote(dir)} rev-parse --show-toplevel 2>/dev/null`
-      root = out.strip
-      ($?&.success? && !root.empty?) ? File.expand_path(root) : nil
-    end
-
-    def relative_path(absolute, root)
-      require 'pathname'
-      Pathname.new(absolute).relative_path_from(Pathname.new(root)).to_s
-    rescue ArgumentError
-      # Different roots on Windows, or otherwise not relative — treat as outside.
-      '..'
-    end
-
-    # Minimal shell-quote for a path passed to `git -C`. The directory comes from
-    # --base-dir, not arbitrary report content, but quoting keeps spaces safe.
-    def quote(str)
-      "'#{str.gsub("'", "'\\\\''")}'"
-    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
@@ -487,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.14'
+  VERSION = '0.0.16'
 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,51 @@ 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 changes --source-url <work-item-url>         # Activity prompted by one card, issue, or thread
 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 +140,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 +243,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.
 
@@ -247,6 +333,7 @@ fp init --project <slug> --surface <surface>
 | Propose a change | `fp propose-change <slug> --project X --why "..." --reason "..."` |
 | Propose a deletion | `fp propose-change <slug> --project X --removal --reason "..."` |
 | View change history | `fp history <slug> --project X` |
+| View work-item activity | `fp changes --project X --source-url URL` |
 | Enforce parity | `fp check --project X` |
 | Gate on this run | `fp check --project X --surface Y --junit file.xml` |
 | View matrix | `fp matrix --project X` |