featureparity 0.0.6 → 0.0.8

data/lib/fp/parity.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Fp
+  # Presentation vocabulary for the parity grid.
+  #
+  # These are the cell states the API's parity report can return, with the glyph and
+  # ordering used to render them. This list is a copy of the server's
+  # ParityReport::STATE_SEVERITY keys, which is unavoidable across the gem/API boundary
+  # — but it is only ever used for *display*: which glyph to draw, and what order to
+  # list counts in.
+  #
+  # The CLI deliberately does not decide what a violation is. The server returns
+  # `violations` and `passing` already computed, and `fp check` exits on those. If it
+  # decided locally, every repo would enforce whichever gem version its CI installed,
+  # and raising a project's level would silently do nothing until every consumer
+  # upgraded. So an unknown state arriving from a newer API degrades to a bare glyph
+  # here rather than changing any verdict.
+  module Parity
+    # Worst → best, matching the server's severity order. Used for stable output.
+    STATES = %w[failing missing suspect stub present pr_passing passing].freeze
+
+    GLYPHS = {
+      'passing' => '✓',
+      'pr_passing' => '◐',
+      'failing' => '✗',
+      'present' => '●',
+      'stub' => '○',
+      'suspect' => '⚠',
+      'missing' => '·'
+    }.freeze
+
+    # Drawn for a surface a requirement does not require — not a state, an absence.
+    NOT_REQUIRED = '-'
+
+    # Marks a requirement whose proposed change is awaiting human review. Not a cell
+    # state: the requirement is still measured, and its cells still say what the evidence
+    # says. It's a row-level annotation so a reader can tell "uncovered" from "covered,
+    # but the wording just moved under the tests".
+    UNDER_REVIEW = '✎'
+
+    # Fallback for a state this gem version doesn't know about.
+    UNKNOWN_GLYPH = '?'
+
+    LEVELS = %w[off regression covered strict].freeze
+
+    LEGEND = 'Legend: ✓ passing  ◐ pr-passing  ✗ failing  ● present  ○ stub  ⚠ suspect  · missing  - not required'
+
+    # Appended to the legend only when the grid actually contains one, so the common
+    # case isn't cluttered by vocabulary nothing on screen uses.
+    UNDER_REVIEW_LEGEND = "#{UNDER_REVIEW} awaiting review of a proposed change"
+
+    def self.glyph(state)
+      GLYPHS.fetch(state.to_s, UNKNOWN_GLYPH)
+    end
+
+    # Row-level annotation for a requirement, or nil when there's nothing to say.
+    def self.row_marker(row)
+      UNDER_REVIEW if row['under_review'] || row[:under_review]
+    end
+
+    # "2 modifications, 1 deletion" for a pending_reviews list.
+    def self.pending_summary(pending_reviews)
+      kinds = Array(pending_reviews).map { |p| p['kind'] || p[:kind] }
+      removals = kinds.count('removal')
+      modifications = kinds.size - removals
+
+      parts = []
+      parts << "#{modifications} modification#{'s' unless modifications == 1}" if modifications.positive?
+      parts << "#{removals} deletion#{'s' unless removals == 1}" if removals.positive?
+      parts.join(', ')
+    end
+
+    # State counts in severity order, skipping zeros, as "✗ 2 failing" strings.
+    def self.count_labels(summary)
+      STATES.filter_map do |state|
+        count = summary[state].to_i
+        "#{glyph(state)} #{count} #{state}" if count.positive?
+      end
+    end
+  end
+end

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.6'
+  VERSION = '0.0.8'
 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
@@ -111,23 +112,143 @@ fp report --junit junit.xml \
 fp propose --project stowzilla \
   --slug print_container_qr \
   --name "Print QR on container label" \
-  --why "Enables scanning containers in the warehouse" \
+  --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 "Label shows scannable QR code"
+  --acceptance "QR scans to the container's detail page"
 ```
 
+**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.
 
+### 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
 
@@ -131,9 +136,9 @@ Propose a new requirement as draft.
 fp propose --project stowzilla \
   --slug print_container_qr \
   --name "Print QR on container label" \
-  --why "Enables scanning containers" \
+  --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 "Label shows scannable QR code"
+  --acceptance "QR scans to the container's detail page"
 ```
 
 | Flag | Required | Description |
@@ -141,22 +146,205 @@ fp propose --project stowzilla \
 | `--project` | Yes | Project slug |
 | `--slug` | Yes | Requirement slug (immutable, choose carefully) |
 | `--name` | Yes | Human-readable name |
-| `--why` | No | Why this requirement matters |
+| `--why` | No | One plain sentence: the user need or outcome the feature serves (see below) |
 | `--required` | No | Comma-separated surfaces that must implement this |
-| `--acceptance` | No | How to verify completion |
+| `--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.
 
+### 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 +410,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