spec-kitty / spec-kitty/spec-kitty
Configurable-strictness reviewer independence (advisory ↔ hard-block self-review) via the gate-outcome severity seam
- Dominant language
- Python
- Stars
- 1.6k
- Forks
- 165
- Avg merge
- 14h 52m
- Merged PRs (30d)
- 303
Description
## Summary
Make **reviewer independence** (the same identity implementing *and* reviewing a work package) a **configurable-strictness** policy rather than a fixed advisory, routed through the gate-outcome **severity seam** (ADR `docs/adr/3.x/2026-08-13-6-gate-outcomes-carry-severity-operator-strategy-decides-effect.md`).
## Background
The mission **`review-claim-role-aware-gate`** fixes the `for_review → in_review` review-claim so a *distinct* profile can review another profile's work (it was wrongly blocked because the claim guard compared the implementer's stamp). That mission deliberately keeps genuine same-identity self-review **advisory** (existing `doctor`/`preflight` `REVIEW_INDEPENDENCE` warning + the `--self-review-fallback` record) — it does not introduce a hard self-review block. See its `FR-005` / `NFR-004`.
The maintainer asked to capture the stronger option as a follow-up: some teams will want self-review to be a **hard gate**, others a warning, others off entirely.
## Proposal
Instead of a boolean hard-block, express reviewer-independence as a **gate outcome carrying a severity**, and let **operator strategy decide the effect** — exactly the model the severity ADR establishes:
- The independence check emits a finding with a severity/band (e.g. `info` / `warn` / `block`).
- Operator/project strategy maps that severity to an effect: advisory-only (today's behavior), soft-gate (requires `--self-review-fallback` acknowledgement), or hard-block (refused unless `--self-review-fallback --force`).
- Default remains today's **advisory** behavior so this is non-breaking.
## Why the seam, not a bespoke flag
- Reuses the canonical `Severity`/gate-outcome design (`src/specify_cli/status/doctor.py::Severity`, ADR 2026-08-13-6) so independence strictness is configured the same way as every other gate, rather than a one-off toggle.
- Keeps the review-claim guard itself simple (it stays role-aware and collision-only); *strictness* becomes a strategy decision on the finding's severity, not guard logic.
## Scope notes / dependencies
- Depends on the review-claim guard landing first (mission `review-claim-role-aware-gate`).
- Must compose with the existing `--self-review-fallback` / `--intended-reviewer` / `--reviewer-failure-reason` contract and its `force_count` accounting — note that accounting is currently reported inverted (track that separately before wiring a hard-block onto it).
- Out of scope: the cross-profile review-claim fix itself (owned by the mission above).
Related: the role-aware review-claim mission (`review-claim-role-aware-gate`), ADR `2026-08-13-6-gate-outcomes-carry-severity-operator-strategy-decides-effect`.
Contributor guide
Research direction
Start with src/specify_cli/status/doctor.py::Severity and ADR 2026-08-13-6 to understand the gate-outcome severity seam. Then trace the existing doctor/preflight REVIEW_INDEPENDENCE warning and the --self-review-fallback, --intended-reviewer, and --reviewer-failure-reason contract. Done means independence severity maps to configurable advisory, soft-gate, or hard-block behavior while preserving the advisory default and force_count accounting.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- cli, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100