featureparity 0.0.5 → 0.0.7

data/lib/fp/project_config.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Fp
+  # ProjectConfig — the repo-local `.featureparity.yml`, which marks a checkout as
+  # tracked by FeatureParity and says which project it belongs to.
+  #
+  # This is deliberately a different thing from Fp::Config (`~/.config/fp/config.yml`).
+  # That one is per-machine and secret-bearing: API keys, profiles, and where each
+  # surface lives on *this* laptop. This one is committed to the repo and answers a
+  # question the machine can't: "which FeatureParity project is this code?"
+  #
+  # It exists because enforcement has to work in CI and in an agent's first minute in a
+  # fresh clone, where nobody has run `fp setup`. Without it, every workflow file and
+  # every agent prompt has to hardcode `--project <slug>`, and the answer drifts. With
+  # it, `fp check` in a fresh clone already knows what to check.
+  #
+  #   # .featureparity.yml
+  #   project: feature-parity
+  #   enforcement: regression
+  #   surface: api
+  #
+  # Discovery walks up from the working directory to the filesystem root, so the file
+  # is found from a subdirectory too (like .git or package.json).
+  class ProjectConfig
+    FILENAME = '.featureparity.yml'
+
+    # Also accepted when reading, so a repo that picked the dotless or .yaml spelling
+    # isn't silently ignored. `fp init` only ever writes FILENAME.
+    ALTERNATE_FILENAMES = ['.featureparity.yaml', 'featureparity.yml'].freeze
+
+    CANDIDATE_FILENAMES = ([FILENAME] + ALTERNATE_FILENAMES).freeze
+
+    attr_reader :path, :data
+
+    def initialize(path: nil, data: nil)
+      @path = path
+      @data = data || {}
+    end
+
+    # Find and load the nearest .featureparity.yml at or above `dir`.
+    # Always returns a ProjectConfig — an absent file is an empty one, so callers can
+    # treat "no config" and "config without this key" the same way.
+    def self.discover(dir = Dir.pwd)
+      found = find_file(dir)
+      return new unless found
+
+      new(path: found, data: parse(found))
+    end
+
+    # Walk up from `dir` looking for any candidate filename. Stops at the filesystem
+    # root; File.dirname('/') == '/' is the loop's terminator.
+    def self.find_file(dir)
+      current = File.expand_path(dir)
+
+      loop do
+        CANDIDATE_FILENAMES.each do |name|
+          candidate = File.join(current, name)
+          return candidate if File.file?(candidate)
+        end
+
+        parent = File.dirname(current)
+        return nil if parent == current
+
+        current = parent
+      end
+    end
+
+    # A malformed config must not take the CLI down — warn and behave as if absent,
+    # so a bad merge in .featureparity.yml doesn't break every fp command in the repo.
+    def self.parse(file)
+      loaded = YAML.safe_load_file(file, permitted_classes: [Symbol])
+      loaded.is_a?(Hash) ? loaded : {}
+    rescue StandardError => e
+      warn "Warning: Could not load #{file}: #{e.message}"
+      {}
+    end
+
+    # Serialize a config file body. Kept here (rather than in `fp init`) so the reader
+    # and the writer of this format live next to each other.
+    def self.render(project:, enforcement: nil, surface: nil)
+      body = +<<~HEADER
+        # FeatureParity — this repo is tracked for feature parity.
+        # Committed on purpose: it is how CI and agents know which project this code
+        # belongs to without anyone passing --project. See https://featureparity.dev
+        ---
+        project: #{project}
+      HEADER
+
+      body << "\n# Enforcement level the CI gate applies (off, regression, covered, strict).\n" \
+              "# Omit to use whatever the project is configured with server-side.\n" \
+              "enforcement: #{enforcement}\n" if enforcement
+
+      body << "\n# Default surface for this repo, used when --surface is not given.\n" \
+              "surface: #{surface}\n" if surface
+
+      body
+    end
+
+    def exists?
+      !path.nil?
+    end
+
+    # Project slug this checkout belongs to.
+    def project
+      fetch_string('project')
+    end
+
+    # Enforcement level override committed alongside the code. Nil means "use the
+    # project's configured level" — the normal case, since the point of storing the
+    # level server-side is that it only has to be raised in one place.
+    def enforcement
+      fetch_string('enforcement')
+    end
+
+    # Default surface for a single-surface repo. A monorepo leaves this out and passes
+    # --surface per job instead.
+    def surface
+      fetch_string('surface')
+    end
+
+    def to_h
+      { 'path' => path }.merge(data)
+    end
+
+    private
+
+    def fetch_string(key)
+      value = data[key]
+      return nil if value.nil?
+
+      string = value.to_s.strip
+      string.empty? ? nil : string
+    end
+  end
+end

data/lib/fp/version.rb

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

data/lib/fp.rb

@@ -2,6 +2,8 @@
 
 require_relative 'fp/version'
 require_relative 'fp/config'
+require_relative 'fp/project_config'
+require_relative 'fp/parity'
 require_relative 'fp/client'
 require_relative 'fp/junit'
 require_relative 'fp/output'

data/skills/fp/SKILL.md

@@ -45,10 +45,11 @@ If not set, ask the user for their API key or have them run `fp setup`.
 
 ```bash
 fp list --project stowzilla                    # All active requirements
-fp list --project stowzilla --gaps             # Requirements without evidence
+fp list --project stowzilla --gaps             # Requirements with a required surface lacking evidence
 fp show <slug> --project stowzilla             # Requirement details
 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)
 ```
 
 ### 2. Add the fp:<slug> marker to tests
@@ -118,16 +119,123 @@ fp propose --project stowzilla \
 
 **Agents always create requirements as draft.** A human must activate in the web app.
 
+### 6. Propose a change to an existing requirement
+
+When a requirement no longer says the right thing, don't silently edit it — propose the
+change and say what prompted it. The requirement drops back to **draft** and a human
+reviews the old-vs-new diff before it counts again.
+
+```bash
+fp propose-change print_container_qr --project stowzilla \
+  --why "Labels must survive a freezer" \
+  --acceptance "QR scans after 24h at -20C" \
+  --reason "Cold-chain rollout changed the requirement" \
+  --source-type fizzy \
+  --source-url https://app.fizzy.do/6098707/cards/1377
+```
+
+To propose deleting one instead (nothing is destroyed — a human decides):
+
+```bash
+fp propose-change print_container_qr --project stowzilla \
+  --removal --reason "Superseded by print_container_label"
+```
+
+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 cannot approve or reject. Only humans review.
+- One open proposal per requirement — review the current one before proposing another.
+
+### 7. See what changed and why
+
+```bash
+fp history print_container_qr --project stowzilla
+fp history print_container_qr --project stowzilla --pending   # just what's awaiting review
+```
+
+Shows the timeline (who changed what, when, and what prompted it), the field-by-field
+diff, and a diff of the **test evidence** — so you can see which tests were written
+against wording that has since moved.
+
+### 8. Verify you didn't break the gate
+
+```bash
+fp check                                       # exits non-zero on violations
+fp check --surface api --json                  # machine-readable violations
+```
+
+`fp check` is the enforcement gate. It asks the API whether the project violates its
+enforcement level and **exits 1 if it does**, which is what makes it usable as a required
+status check on a pull request. Run it after reporting evidence to confirm your change
+left parity intact.
+
+Levels, from most to least forgiving:
+
+| Level | Fails the build when |
+|-------|----------------------|
+| `off` | never — report only |
+| `regression` | a test that was passing has gone red |
+| `covered` | any required surface lacks real (non-stub) evidence |
+| `strict` | any required surface isn't green in CI |
+
+The level is configured on the project, so don't hardcode one. `--level` overrides it for
+a single run; `--warn-only` prints violations but still exits 0.
+
+**A requirement you proposed a change to still counts.** It drops to `draft` until a human
+reviews it, but the gate keeps measuring it — otherwise proposing a change would be a way
+to make a red gate green. What relaxes is only evidence *freshness*: proposing marks the
+existing evidence `suspect`, and `suspect` doesn't fail a build below `strict`. Re-write the
+tests against the new wording and re-report to clear it. `fp check` lists everything
+awaiting review so you can tell that apart from a plain gap.
+
+**Gating a branch on its own results.** Plain `fp check` sees only what has been recorded,
+which on a pull request is the default branch's state — it cannot see what your branch
+changed. Pass the run's JUnit to evaluate your results without saving them:
+
+```bash
+fp check --surface api --junit junit.xml
+```
+
+This also catches the one regression a green test suite can't: a test that was deleted,
+renamed, or had its `fp:` marker stripped. Every remaining test passes, so CI is happy,
+while the requirement quietly lost its only proof.
+
+### Repo-local config (`.featureparity.yml`)
+
+If a repo has a `.featureparity.yml`, `--project` is optional — `fp` reads the slug from
+it. Check for one before asking the user which project to use:
+
+```bash
+cat .featureparity.yml 2>/dev/null
+```
+
+To onboard a repo that has no such file (writes the config, a CI gate workflow, and a
+FeatureParity section in `AGENTS.md`):
+
+```bash
+fp init --project <slug> --surface <surface>
+```
+
 ## Quick reference
 
 | Task | Command |
 |------|---------|
+| Onboard a repo | `fp init --project X` |
 | List requirements | `fp list --project X` |
 | Show gaps | `fp list --project X --gaps` |
 | Show details | `fp show <slug> --project X` |
 | Report evidence | `fp report <slug> --project X --surface Y --file Z --repo A/B` |
 | Report from JUnit | `fp report --junit file.xml --project X --surface Y --repo A/B` |
 | Propose requirement | `fp propose --project X --slug Y --name "..."` |
+| 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` |
+| 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` |
 | List surfaces | `fp surfaces --project X` |
 | List projects | `fp projects` |

data/skills/fp/references/cli.md

@@ -49,17 +49,22 @@ List requirements.
 
 ```bash
 fp list --project stowzilla              # All active requirements
-fp list --project stowzilla --gaps       # Requirements without evidence
+fp list --project stowzilla --gaps       # Requirements with a required surface lacking evidence
 fp list --project stowzilla --status draft
 fp list --project stowzilla --json
 ```
 
 | Flag | Description |
 |------|-------------|
-| `--project` | Project slug (required) |
-| `--gaps` | Show only requirements without evidence |
+| `--project` | Project slug (optional if `.featureparity.yml` declares one) |
+| `--gaps` | Show only requirements with an uncovered required surface |
 | `--status` | Filter by status: active, draft, archived |
 | `--category` | Filter by category |
+| `--surface` | Restrict to one surface |
+
+`--gaps` reports a requirement when one of its required surfaces has no real evidence —
+missing, stubbed, or failing. The table's UNCOVERED column names those surfaces and their
+state.
 
 ### fp show
 
@@ -147,16 +152,190 @@ fp propose --project stowzilla \
 
 **Agents always create requirements as draft.** A human must activate in the web app.
 
+### fp propose-change
+
+Propose a change to a requirement that already exists — or propose deleting it.
+Recorded with what the requirement *was*, a field-by-field diff, and what prompted the
+change. The requirement drops back to **draft** until a human approves or rejects.
+
+```bash
+fp propose-change print_container_qr --project stowzilla \
+  --why "Labels must survive a freezer" \
+  --acceptance "QR scans after 24h at -20C" \
+  --reason "Cold-chain rollout" \
+  --source-type fizzy \
+  --source-url https://app.fizzy.do/6098707/cards/1377
+
+# Propose deletion instead
+fp propose-change print_container_qr --project stowzilla \
+  --removal --reason "Superseded by print_container_label"
+```
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `<slug>` | Yes | Positional: the requirement to change |
+| `--project` | No | Project slug (optional if `.featureparity.yml` declares one) |
+| `--removal` | No | Propose deleting the requirement instead of modifying it |
+| `--name` | No | Proposed title |
+| `--why` | No | Proposed justification |
+| `--acceptance` | No | Proposed acceptance criteria |
+| `--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 |
+| `--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 |
+| `--source-context` | No | Free-text context |
+
+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.
+
+Refusals, all printed verbatim:
+
+| Situation | Status |
+|-----------|--------|
+| Agent tries to change `--slug` | 403 |
+| Agent tries to remove a required surface | 403 |
+| Proposed values match the current text | 422 |
+| Requirement already has a proposal awaiting review | 409 |
+| Requirement is archived | 422 |
+
+**Agents cannot approve or reject.** Reviewing is a human action in the web app.
+
+### fp history
+
+Show a requirement's change history: what changed, who changed it, what prompted it, and
+how the test evidence moved.
+
+```bash
+fp history print_container_qr --project stowzilla
+fp history print_container_qr --project stowzilla --pending    # only what awaits review
+fp history print_container_qr --project stowzilla --limit 5    # most recent 5 entries
+fp history print_container_qr --project stowzilla --json
+```
+
+Entries are printed oldest first. Each shows the event (created, edited, approved,
+change proposed, deletion proposed, change approved/rejected, archived, deleted), the
+actor and whether they were a human or an agent, the field diff, the evidence diff, and
+the review decision where one was made. An open proposal is called out at the end.
+
+`--project` is optional when the repo has a `.featureparity.yml`.
+
 ### fp matrix
 
-Display the parity matrix.
+Display the parity matrix. Cells show the state of the evidence filed for each
+(requirement, surface) pair.
 
 ```bash
 fp matrix --project stowzilla           # ASCII table
-fp matrix --project stowzilla --csv     # CSV export
+fp matrix --project stowzilla --csv     # CSV export (state names, not glyphs)
 fp matrix --project stowzilla --json    # JSON
+fp matrix --project stowzilla --surface api
+```
+
+| Glyph | State | Meaning |
+|-------|-------|---------|
+| `✓` | passing | CI ran the test and it was green |
+| `✗` | failing | CI ran the test and it was red, or the marker vanished |
+| `●` | present | an agent found the `fp:` marker; no CI verdict yet |
+| `○` | stub | reported as a stub / skipped test |
+| `⚠` | suspect | the requirement changed; evidence needs re-verification |
+| `·` | missing | no evidence for this surface |
+| `-` | — | the requirement does not require this surface |
+
+A slug suffixed with `✎` has a proposed change awaiting review — it is still measured by
+the gate, and its evidence is `suspect` until someone reviews the change. `--csv` writes
+`<slug> (under review)` instead of the glyph.
+
+### fp check
+
+The enforcement gate. Exits **1** when the project violates its enforcement level, so it
+can be a required status check on a pull request.
+
+```bash
+fp check                                  # project from .featureparity.yml
+fp check --project stowzilla --surface api
+fp check --level covered                  # override the project's level for this run
+fp check --warn-only                      # print violations, still exit 0
+fp check --json
+fp check --surface api --junit junit.xml  # gate on this run's results (preview)
 ```
 
+| Flag | Description |
+|------|-------------|
+| `--project` | Project slug (optional if `.featureparity.yml` declares one) |
+| `--surface` | Gate one surface only |
+| `--level` | Override the project's enforcement level |
+| `--junit` | Evaluate this run's JUnit results without saving them (repeatable) |
+| `--warn-only` | Report violations but exit 0 |
+
+**Enforcement levels** (the level is configured on the project; don't hardcode one):
+
+| Level | A build fails when |
+|-------|--------------------|
+| `off` | never — report only |
+| `regression` | a test that was passing has gone red |
+| `covered` | any required surface lacks real (non-stub) evidence |
+| `strict` | any required surface isn't green in CI |
+
+`suspect` only violates at `strict`: it means the requirement's wording moved, not that
+the test broke.
+
+**Requirements awaiting review still count.** `fp propose-change` demotes a requirement to
+`draft`, but the gate keeps measuring it — otherwise proposing a change would be a way to
+turn a red gate green. Coverage is still demanded; only evidence freshness relaxes, because
+proposing marks the evidence `suspect`. `fp check` lists them separately from violations:
+
+```
+1 requirement(s) awaiting review of a proposed change (1 modification):
+  SLUG           PROPOSED      TITLE
+  print_qr       modification  Print QR on container label
+These still count toward the gate — proposing a change is not a way out of it.
+```
+
+`fp matrix` marks the same rows with `✎`, and `fp list` names them even when the default
+`--status active` filter would otherwise hide them.
+
+**Preview mode (`--junit`).** Without it, `fp check` sees only what has been recorded —
+on a pull request, that's the default branch's state, not what the branch changed. With
+it, the run's results are applied on top of the recorded grid and then discarded, so a
+branch is judged on its own results without writing evidence that would churn the live
+matrix for everyone.
+
+Preview also catches the regression a green suite can't: a test that was deleted,
+renamed, or had its `fp:` marker removed. The remaining tests all pass, so CI is happy,
+while the requirement silently lost its only proof. Pass one `--junit` per surface —
+`--surface` tells the server which cells the run had a chance to cover, and pooling
+surfaces into one call would misattribute vanished tests.
+
+### fp init
+
+Onboard a repo onto FeatureParity. Writes three files and makes no API calls (so it works
+before a key is configured).
+
+```bash
+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
+fp init --project stowzilla --force          # refresh files written previously
+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 |
+| `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
+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.
+
 ### fp profile
 
 Manage named profiles. Each profile stores an API key and (optionally) the
@@ -222,14 +401,32 @@ fp repos unset customer_android --project stowzilla
 |------|---------|
 | 0 | Success |
 | 1 | General error (invalid flags, missing required args, API error) |
+| 1 | `fp check`: the parity gate failed (violations) |
+| 130 | Interrupted (Ctrl-C) |
+
+`fp check` deliberately reuses exit 1 for a failed gate rather than a distinct code: CI
+treats any non-zero as a failure, and a special code would only invite scripts to ignore
+it. Use `--json` to distinguish a gate failure (`ok: true`, `passing: false`) from a
+request failure (`ok: false`).
 
 ## Configuration files
 
-- `~/.config/fp/config.yml` — Profiles and global settings
+- `~/.config/fp/config.yml` — Profiles and global settings (per-machine, holds API keys)
+- `.featureparity.yml` — Repo-local, committed. Declares which project a checkout belongs
+  to so CI and agents don't need `--project`. Discovered by walking up from the working
+  directory. Written by `fp init`.
 - `FP_API_KEY` environment variable overrides all profiles
 - `FP_API_URL` environment variable overrides API URL
 - `FP_PROFILE` environment variable selects a profile
 
+### .featureparity.yml
+
+```yaml
+project: stowzilla        # required — the project slug
+enforcement: regression   # optional — usually omit; the level lives on the project
+surface: api              # optional — default surface for a single-surface repo
+```
+
 ## API URL priority
 
 1. `--api-url` flag

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: featureparity
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.7
 platform: ruby
 authors:
 - Stowzilla
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-14 00:00:00.000000000 Z
+date: 2026-09-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-http
@@ -95,13 +95,19 @@ files:
 - lib/fp/client.rb
 - lib/fp/commands.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/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/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/report.rb
 - lib/fp/commands/repos.rb
 - lib/fp/commands/setup.rb
@@ -112,6 +118,8 @@ files:
 - lib/fp/config.rb
 - lib/fp/junit.rb
 - lib/fp/output.rb
+- lib/fp/parity.rb
+- lib/fp/project_config.rb
 - lib/fp/version.rb
 - skills/fp/SKILL.md
 - skills/fp/references/cli.md