diff --git a/CHANGELOG.md b/CHANGELOG.md index 41054cc..ed8c00e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,35 @@ All notable changes to Pharabius are documented in this file. +## [3.7.0] - Unreleased + +### Candidate Review and Promotion Workflow + +Adds governed review of candidate findings with explicit decision recording. +Review decisions are append-only records. Candidate artifacts are NOT mutated. +Candidate acceptance is review-level only — it does NOT create accepted DebtFindings. + +### Added + +- **Candidate review module** (`core/connectors/candidate_review.py`) — `review_candidate()` function +- **Candidate-specific lifecycle outcomes** — CandidateAccepted, CandidateRejected, CandidateDeferred +- **Decision-to-outcome mapping** — review decisions map to candidate lifecycle states +- **Terminal decision guard** — one terminal decision per candidate (v3.7.0) +- **Candidate review summary** — pending/accepted/rejected/deferred counts +- **Status reader integration** — shows candidate review state +- **56 new tests** covering review, lifecycle, exclusion, no-mutation + +### Design Rules + +- CandidateAccepted ≠ Acknowledged — distinct from accepted finding states +- Candidate acceptance is review-level only, not debt-register promotion +- Regular review rejects CAND-* IDs; candidate review rejects TD-* IDs +- `needs-investigation` is not valid for candidates (candidates ARE pre-investigation) +- One terminal decision per candidate; supersession not supported in v3.7.0 +- Candidate artifact NOT mutated by review decisions +- Lifecycle history is append-only +- Review decisions are append-only + ## [3.6.0] - Unreleased ### Evidence-to-Finding Candidate Promotion diff --git a/README.md b/README.md index de75a04..e8fea27 100644 --- a/README.md +++ b/README.md @@ -103,6 +103,7 @@ Pharabius is a mature CLI engine with an early-stage platform. Current limitatio - _v3.4.0 adds **external evidence review**: imported and combined evidence visible in reports and status output. No finding creation._ - _v3.5.0 adds **workflow lifecycle governance**: explicit state model for findings and work packages with transition validation. No auto-promotion._ - _v3.6.0 adds **evidence-to-finding candidate promotion**: external evidence can propose reviewable candidate findings. Candidates are not accepted findings._ + - _v3.7.0 adds **candidate review workflow**: governed review of candidates with explicit decisions. Acceptance is review-level only, not debt-register promotion._ - **No live ticket sync** — No Jira, Linear, or GitHub Issues integration - **Platform frontend is prototype-grade** — 28 tests pass, build succeeds, but 5 pre-existing TypeScript errors in test mocks - **No portfolio governance** — Multi-repo governance workflows not implemented diff --git a/docs/LIFECYCLE.md b/docs/LIFECYCLE.md index cb70006..f1282d2 100644 --- a/docs/LIFECYCLE.md +++ b/docs/LIFECYCLE.md @@ -4,16 +4,25 @@ Pharabius defines explicit lifecycle states for findings and work packages. Lifecycle state machines govern which transitions are allowed, ensuring state changes follow a valid path. -## Candidate Lifecycle (v3.6.0) +## Candidate Lifecycle (v3.6.0, v3.7.0) External evidence can propose **candidate findings**. Candidates are pre-review artifacts that must be reviewed before becoming accepted findings. ```text -Candidate → Acknowledged (promote after review) -Candidate → Won't Fix (reject after review) -Candidate → Deferred (defer review) +Candidate → CandidateAccepted (review-level acceptance) +Candidate → CandidateRejected (review-level rejection) +Candidate → CandidateDeferred (review deferral) ``` +CandidateAccepted ≠ Acknowledged. Accepted candidates remain candidates — +they are NOT promoted to debt-register.json. + +Review decisions are: +- Append-only records in `.ai-debt/review/decisions.json` +- Recorded as lifecycle entries in `.ai-debt/lifecycle-history.json` +- One terminal decision per candidate (v3.7.0) +- `needs-investigation` is not valid for candidates + Candidates are: - Stored in `.ai-debt/candidate-findings.json` (separate from `debt-register.json`) - NOT counted in `total_findings`, severity, or priority summaries diff --git a/pyproject.toml b/pyproject.toml index a59098b..a5b04b7 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "pharabius" -version = "3.6.0" +version = "3.7.0" description = "Repository-first technical debt intelligence platform" readme = "README.md" requires-python = ">=3.11" diff --git a/src/pharabius/core/connectors/candidate_review.py b/src/pharabius/core/connectors/candidate_review.py new file mode 100644 index 0000000..ff48859 --- /dev/null +++ b/src/pharabius/core/connectors/candidate_review.py @@ -0,0 +1,362 @@ +"""Candidate review decision recording (v3.7.0). + +Records reviewer decisions on candidate findings. Decisions are append-only +records in the review sidecar and lifecycle history. The candidate artifact +itself is NOT mutated. + +Key invariants: +- Candidate acceptance is review-level only, not debt-register promotion. +- CandidateAccepted ≠ Acknowledged. Candidates remain candidates. +- Regular review rejects CAND-* IDs. Candidate review rejects TD-* IDs. +- One terminal decision per candidate (v3.7.0). +- No auto-promotion. No DebtFinding creation. No work packages. No tickets. +""" + +from __future__ import annotations + +import json +from datetime import UTC, datetime +from pathlib import Path +from typing import Any + +from pharabius.core.connectors.candidate import load_candidate_artifact +from pharabius.core.lifecycle import ( + FindingStatus, +) +from pharabius.schemas.lifecycle import LifecycleEntry, LifecycleHistory +from pharabius.schemas.review import DecisionStatus, ReviewDecision + +# --------------------------------------------------------------------------- +# Decision → lifecycle outcome mapping +# --------------------------------------------------------------------------- + +CANDIDATE_DECISION_OUTCOMES: dict[DecisionStatus, FindingStatus] = { + DecisionStatus.ACCEPTED: FindingStatus.CANDIDATE_ACCEPTED, + DecisionStatus.REJECTED: FindingStatus.CANDIDATE_REJECTED, + DecisionStatus.RISK_ACCEPTED: FindingStatus.CANDIDATE_REJECTED, + DecisionStatus.DUPLICATE: FindingStatus.CANDIDATE_REJECTED, + DecisionStatus.ALREADY_FIXED: FindingStatus.CANDIDATE_REJECTED, + DecisionStatus.DEFERRED: FindingStatus.CANDIDATE_DEFERRED, +} + +# Decisions that are terminal (one per candidate in v3.7.0) +TERMINAL_DECISIONS: set[DecisionStatus] = { + DecisionStatus.ACCEPTED, + DecisionStatus.REJECTED, + DecisionStatus.RISK_ACCEPTED, + DecisionStatus.DUPLICATE, + DecisionStatus.ALREADY_FIXED, + DecisionStatus.DEFERRED, +} + +# Decisions that are NOT valid for candidates +INVALID_CANDIDATE_DECISIONS: set[DecisionStatus] = { + DecisionStatus.NEEDS_INVESTIGATION, # Candidates ARE pre-investigation +} + +# Candidate ID prefix +CANDIDATE_ID_PREFIX = "CAND" + +# --------------------------------------------------------------------------- +# Path helpers +# --------------------------------------------------------------------------- + + +def _review_dir(root: Path) -> Path: + return root / ".ai-debt" / "review" + + +def _decisions_path(root: Path) -> Path: + return _review_dir(root) / "decisions.json" + + +def _lifecycle_path(root: Path) -> Path: + return root / ".ai-debt" / "lifecycle-history.json" + + +# --------------------------------------------------------------------------- +# Load / save helpers +# --------------------------------------------------------------------------- + + +def _load_review_decisions(root: Path) -> list[dict[str, Any]]: + """Load existing review decisions as raw dicts.""" + path = _decisions_path(root) + if not path.exists(): + return [] + try: + data = json.loads(path.read_text(encoding="utf-8")) + return data.get("decisions", []) + except (json.JSONDecodeError, OSError): + return [] + + +def _save_review_decisions(root: Path, decisions_raw: list[dict[str, Any]]) -> None: + """Save review decisions sidecar.""" + path = _decisions_path(root) + _review_dir(root).mkdir(parents=True, exist_ok=True) + + # Preserve the sidecar structure + existing: dict[str, Any] = {} + if path.exists(): + try: + existing = json.loads(path.read_text(encoding="utf-8")) + except (json.JSONDecodeError, OSError): + existing = {} + + existing["decisions"] = decisions_raw + if "schema_version" not in existing: + existing["schema_version"] = "1.0" + + path.write_text(json.dumps(existing, indent=2) + "\n", encoding="utf-8") + + +def _load_lifecycle_history(root: Path) -> LifecycleHistory: + """Load lifecycle history. Returns empty if missing.""" + path = _lifecycle_path(root) + if not path.exists(): + return LifecycleHistory() + try: + return LifecycleHistory.model_validate_json(path.read_text(encoding="utf-8")) + except Exception: + return LifecycleHistory() + + +def _save_lifecycle_history(root: Path, history: LifecycleHistory) -> None: + """Save lifecycle history.""" + path = _lifecycle_path(root) + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text( + history.model_dump_json(indent=2) + "\n", + encoding="utf-8", + ) + + +# --------------------------------------------------------------------------- +# Validation +# --------------------------------------------------------------------------- + + +class CandidateReviewError(Exception): + """Error during candidate review.""" + + +def _validate_candidate_id(candidate_id: str) -> None: + """Ensure ID is a candidate ID (CAND-XXXX).""" + if not candidate_id.startswith(CANDIDATE_ID_PREFIX): + msg = ( + f"Not a candidate ID: {candidate_id!r}. " + "Candidate review only accepts CAND-* IDs. " + "Use regular review for TD-* findings." + ) + raise CandidateReviewError(msg) + + +def _validate_decision_for_candidate(decision: DecisionStatus) -> None: + """Ensure decision is valid for candidates.""" + if decision in INVALID_CANDIDATE_DECISIONS: + msg = ( + f"Decision {decision.value!r} is not valid for candidates. " + "Candidates are pre-investigation artifacts. " + "Accept or reject IS the investigation outcome." + ) + raise CandidateReviewError(msg) + + if decision not in CANDIDATE_DECISION_OUTCOMES: + msg = f"Unknown decision status: {decision.value!r}" + raise CandidateReviewError(msg) + + +def _check_no_existing_terminal( + candidate_id: str, + existing_decisions: list[dict[str, Any]], +) -> None: + """Ensure candidate has no existing terminal decision (v3.7.0).""" + for d in existing_decisions: + if d.get("finding_id") == candidate_id: + status_str = d.get("status", "") + try: + ds = DecisionStatus(status_str) + except ValueError: + continue + if ds in TERMINAL_DECISIONS: + msg = ( + f"Candidate {candidate_id} already has a terminal review " + f"decision ({status_str!r}). " + "Supersession is not supported in v3.7.0." + ) + raise CandidateReviewError(msg) + + +# --------------------------------------------------------------------------- +# Core: review_candidate +# --------------------------------------------------------------------------- + + +def review_candidate( + root: Path, + candidate_id: str, + decision: DecisionStatus, + reviewer: str = "", + rationale: str = "", +) -> ReviewDecision: + """Record a review decision for a candidate finding. + + Appends to review sidecar and lifecycle history. + Does NOT mutate candidate-findings.json or debt-register.json. + + Raises CandidateReviewError for: + - Non-candidate IDs (TD-*) + - Invalid candidate decisions (needs-investigation) + - Duplicate terminal decisions + - Unknown candidate IDs + """ + # Validate inputs + _validate_candidate_id(candidate_id) + _validate_decision_for_candidate(decision) + + # Verify candidate exists + artifact = load_candidate_artifact(root) + candidate_ids = {c.id for c in artifact.candidates} + if candidate_id not in candidate_ids: + msg = ( + f"Unknown candidate ID: {candidate_id!r}. " + f"Known candidates: {sorted(candidate_ids) or 'none'}" + ) + raise CandidateReviewError(msg) + + # Check for existing terminal decision + existing_decisions = _load_review_decisions(root) + _check_no_existing_terminal(candidate_id, existing_decisions) + + # Create review decision + review_decision = ReviewDecision( + finding_id=candidate_id, + status=decision, + reviewed_at=datetime.now(UTC), + reviewer=reviewer, + rationale=rationale, + ) + + # Append to review sidecar + decision_dict = json.loads(review_decision.model_dump_json()) + existing_decisions.append(decision_dict) + _save_review_decisions(root, existing_decisions) + + # Append lifecycle entry + lifecycle_outcome = CANDIDATE_DECISION_OUTCOMES[decision] + history = _load_lifecycle_history(root) + entry = LifecycleEntry( + artifact_type="candidate", + artifact_id=candidate_id, + from_status="Candidate", + to_status=lifecycle_outcome.value, + actor=reviewer or "operator", + rationale=rationale or f"Review decision: {decision.value}", + ) + history.append_entry(entry) + _save_lifecycle_history(root, history) + + return review_decision + + +# --------------------------------------------------------------------------- +# Summary +# --------------------------------------------------------------------------- + + +class CandidateReviewSummary: + """Summary of candidate review decisions.""" + + def __init__( + self, + total_candidates: int = 0, + pending: list[str] | None = None, + accepted: list[str] | None = None, + rejected: list[str] | None = None, + deferred: list[str] | None = None, + ) -> None: + self.total_candidates = total_candidates + self.pending = pending or [] + self.accepted = accepted or [] + self.rejected = rejected or [] + self.deferred = deferred or [] + + @property + def reviewed_count(self) -> int: + return len(self.accepted) + len(self.rejected) + len(self.deferred) + + @property + def pending_count(self) -> int: + return len(self.pending) + + +def summarize_candidate_reviews(root: Path) -> CandidateReviewSummary: + """Summarize candidate review status. + + Distinguishes accepted candidates from accepted findings. + """ + artifact = load_candidate_artifact(root) + if not artifact.candidates: + return CandidateReviewSummary() + + candidate_ids = {c.id for c in artifact.candidates} + decisions = _load_review_decisions(root) + + # Map candidate decisions + accepted: list[str] = [] + rejected: list[str] = [] + deferred: list[str] = [] + decided_ids: set[str] = set() + + for d in decisions: + fid = d.get("finding_id", "") + if fid not in candidate_ids: + continue + status_str = d.get("status", "") + if fid in decided_ids: + continue # First decision wins + decided_ids.add(fid) + + if status_str == "accepted": + accepted.append(fid) + elif status_str in ("rejected", "risk-accepted", "duplicate", "already-fixed"): + rejected.append(fid) + elif status_str == "deferred": + deferred.append(fid) + + pending = sorted(candidate_ids - decided_ids) + + return CandidateReviewSummary( + total_candidates=len(candidate_ids), + pending=pending, + accepted=sorted(accepted), + rejected=sorted(rejected), + deferred=sorted(deferred), + ) + + +def format_candidate_review_summary(summary: CandidateReviewSummary) -> str: + """Format candidate review summary for console output.""" + lines: list[str] = [] + lines.append("Candidate Review Summary") + lines.append("") + lines.append(f"Total candidates: {summary.total_candidates}") + lines.append(f"Reviewed: {summary.reviewed_count}") + lines.append(f"Pending review: {summary.pending_count}") + lines.append("") + lines.append( + " CandidateAccepted: " + f"{len(summary.accepted)} " + "(review-level only, not debt-register promotion)" + ) + lines.append(f" CandidateRejected: {len(summary.rejected)}") + lines.append(f" CandidateDeferred: {len(summary.deferred)}") + + if summary.pending: + lines.append("") + lines.append("Pending candidates:") + for cid in summary.pending: + lines.append(f" {cid}") + + return "\n".join(lines) diff --git a/src/pharabius/core/lifecycle.py b/src/pharabius/core/lifecycle.py index 33ed1ac..8c55458 100644 --- a/src/pharabius/core/lifecycle.py +++ b/src/pharabius/core/lifecycle.py @@ -29,7 +29,12 @@ class FindingStatus(enum.StrEnum): - Review decision statuses map through compatibility table """ + # Candidate lifecycle (v3.6.0 proposal, v3.7.0 review) CANDIDATE = "Candidate" + CANDIDATE_ACCEPTED = "CandidateAccepted" + CANDIDATE_REJECTED = "CandidateRejected" + CANDIDATE_DEFERRED = "CandidateDeferred" + # Accepted finding lifecycle DETECTED = "Detected" ACKNOWLEDGED = "Acknowledged" IN_PROGRESS = "In Progress" @@ -44,6 +49,13 @@ class FindingStatus(enum.StrEnum): # Candidate status (v3.6.0) "Candidate": FindingStatus.CANDIDATE, "candidate": FindingStatus.CANDIDATE, + # Candidate review outcomes (v3.7.0) + "CandidateAccepted": FindingStatus.CANDIDATE_ACCEPTED, + "candidate_accepted": FindingStatus.CANDIDATE_ACCEPTED, + "CandidateRejected": FindingStatus.CANDIDATE_REJECTED, + "candidate_rejected": FindingStatus.CANDIDATE_REJECTED, + "CandidateDeferred": FindingStatus.CANDIDATE_DEFERRED, + "candidate_deferred": FindingStatus.CANDIDATE_DEFERRED, # Exact matches (DebtFinding default) "Detected": FindingStatus.DETECTED, "detected": FindingStatus.DETECTED, @@ -67,10 +79,15 @@ class FindingStatus(enum.StrEnum): # Allowed transitions: from → set of allowed to FINDING_TRANSITIONS: dict[FindingStatus, set[FindingStatus]] = { FindingStatus.CANDIDATE: { - FindingStatus.ACKNOWLEDGED, # Promote after review - FindingStatus.WONT_FIX, # Reject after review - FindingStatus.DEFERRED, # Defer review + FindingStatus.CANDIDATE_ACCEPTED, # Review-level acceptance + FindingStatus.CANDIDATE_REJECTED, # Review-level rejection + FindingStatus.CANDIDATE_DEFERRED, # Review-level deferral }, + # Candidate outcome states are terminal in v3.7.0 + # (no transitions out until supersession mechanism added) + FindingStatus.CANDIDATE_ACCEPTED: set(), + FindingStatus.CANDIDATE_REJECTED: set(), + FindingStatus.CANDIDATE_DEFERRED: set(), FindingStatus.DETECTED: { FindingStatus.ACKNOWLEDGED, FindingStatus.DEFERRED, diff --git a/src/pharabius/core/status_reader.py b/src/pharabius/core/status_reader.py index f85aaf5..09b1323 100644 --- a/src/pharabius/core/status_reader.py +++ b/src/pharabius/core/status_reader.py @@ -204,13 +204,40 @@ def read_status(repository_root: Path) -> str: else: lines.append("Combined: absent") - # Candidate findings (v3.6.0) + # Candidate findings and review (v3.6.0, v3.7.0) candidate_path = ai_debt / "candidate-findings.json" if candidate_path.exists(): cand = _load_json_safe(candidate_path) if cand: total_cand = cand.get("summary", {}).get("total_candidates", 0) lines.append(f"Candidates: {total_cand} (review required)") + + # Show review state if decisions exist + review_path = ai_debt / "review" / "decisions.json" + if review_path.exists(): + review = _load_json_safe(review_path) + if review: + cand_decisions = [ + d + for d in review.get("decisions", []) + if isinstance(d, dict) and d.get("finding_id", "").startswith("CAND") + ] + if cand_decisions: + accepted = sum(1 for d in cand_decisions if d.get("status") == "accepted") + rejected = sum( + 1 + for d in cand_decisions + if d.get("status") + in ("rejected", "risk-accepted", "duplicate", "already-fixed") + ) + deferred = sum(1 for d in cand_decisions if d.get("status") == "deferred") + pending = total_cand - len(cand_decisions) + lines.append( + f" Reviewed: {len(cand_decisions)} " + f"({accepted} accepted, {rejected} rejected, {deferred} deferred)" + ) + if pending > 0: + lines.append(f" Pending: {pending}") else: lines.append("Candidates: unreadable") # No line if absent — candidates are optional diff --git a/tests/test_cli_command_surface.py b/tests/test_cli_command_surface.py index 3608873..d901ebb 100644 --- a/tests/test_cli_command_surface.py +++ b/tests/test_cli_command_surface.py @@ -99,4 +99,4 @@ class TestVersionFlag: def test_version_flag_works(self) -> None: result = runner.invoke(app, ["--version"]) assert result.exit_code == 0 - assert "3.6.0" in result.output + assert "3.7.0" in result.output diff --git a/tests/test_release_consistency.py b/tests/test_release_consistency.py index 0240d3f..018f9e8 100644 --- a/tests/test_release_consistency.py +++ b/tests/test_release_consistency.py @@ -13,7 +13,7 @@ # ruff: noqa: E402 from validate_release_consistency import validate_release_consistency -EXPECTED = "3.6.0" +EXPECTED = "3.7.0" class TestVersionSources: diff --git a/tests/test_v350_lifecycle.py b/tests/test_v350_lifecycle.py index 5d16798..8b97a02 100644 --- a/tests/test_v350_lifecycle.py +++ b/tests/test_v350_lifecycle.py @@ -38,8 +38,8 @@ class TestFindingStatusEnum: """FindingStatus enum has correct values and compatibility.""" - def test_enum_has_eight_states(self) -> None: - assert len(FindingStatus) == 8 + def test_enum_has_eleven_states(self) -> None: + assert len(FindingStatus) == 11 def test_detected_is_default(self) -> None: assert FindingStatus.DETECTED.value == "Detected" diff --git a/tests/test_v360_candidate_promotion.py b/tests/test_v360_candidate_promotion.py index e71e0e7..bba2509 100644 --- a/tests/test_v360_candidate_promotion.py +++ b/tests/test_v360_candidate_promotion.py @@ -309,14 +309,14 @@ def test_candidate_is_not_detected(self) -> None: def test_candidate_is_distinct_value(self) -> None: all_values = set(FindingStatus) - assert len(all_values) == 8 # 7 original + CANDIDATE + assert len(all_values) == 11 # 8 original + 3 candidate outcomes assert FindingStatus.CANDIDATE in all_values def test_candidate_has_own_transitions(self) -> None: assert FindingStatus.CANDIDATE in FINDING_TRANSITIONS transitions = FINDING_TRANSITIONS[FindingStatus.CANDIDATE] - assert FindingStatus.ACKNOWLEDGED in transitions # Promote - assert FindingStatus.WONT_FIX in transitions # Reject + assert FindingStatus.CANDIDATE_ACCEPTED in transitions + assert FindingStatus.CANDIDATE_REJECTED in transitions def test_candidate_cannot_transition_to_in_progress(self) -> None: """Candidate must go through review first.""" @@ -327,16 +327,16 @@ def test_candidate_cannot_transition_to_verified(self) -> None: result = validate_finding_transition("Candidate", "Verified") assert not result.valid - def test_candidate_to_acknowledged_is_promote(self) -> None: - result = validate_finding_transition("Candidate", "Acknowledged") + def test_candidate_to_candidate_accepted_is_review_accept(self) -> None: + result = validate_finding_transition("Candidate", "CandidateAccepted") assert result.valid - def test_candidate_to_wont_fix_is_reject(self) -> None: - result = validate_finding_transition("Candidate", "Won't Fix") + def test_candidate_to_candidate_rejected_is_review_reject(self) -> None: + result = validate_finding_transition("Candidate", "CandidateRejected") assert result.valid - def test_candidate_to_deferred(self) -> None: - result = validate_finding_transition("Candidate", "Deferred") + def test_candidate_to_candidate_deferred(self) -> None: + result = validate_finding_transition("Candidate", "CandidateDeferred") assert result.valid @@ -650,13 +650,13 @@ def test_candidate_cannot_self_promote_to_accepted(self) -> None: result = validate_finding_transition("Candidate", "In Progress") assert not result.valid - def test_candidate_can_only_promote_or_reject(self) -> None: + def test_candidate_can_only_transition_to_review_outcomes(self) -> None: """Only valid transitions from Candidate are review outcomes.""" transitions = FINDING_TRANSITIONS[FindingStatus.CANDIDATE] assert transitions == { - FindingStatus.ACKNOWLEDGED, - FindingStatus.WONT_FIX, - FindingStatus.DEFERRED, + FindingStatus.CANDIDATE_ACCEPTED, + FindingStatus.CANDIDATE_REJECTED, + FindingStatus.CANDIDATE_DEFERRED, } diff --git a/tests/test_v370_candidate_review.py b/tests/test_v370_candidate_review.py new file mode 100644 index 0000000..a8fb7c1 --- /dev/null +++ b/tests/test_v370_candidate_review.py @@ -0,0 +1,663 @@ +"""Tests for v3.7.0 — Candidate Review and Promotion Workflow. + +Covers all 27 acceptance criteria: +- 1-20: Original criteria +- 21-27: Amended criteria + +Key invariants: +- Candidate acceptance is review-level only, not debt-register promotion +- CandidateAccepted ≠ Acknowledged +- Regular review rejects CAND-* IDs; candidate review rejects TD-* IDs +- One terminal decision per candidate (v3.7.0) +- No auto-promotion, no DebtFinding creation, no work packages, no tickets +""" + +from __future__ import annotations + +import json +from pathlib import Path + +import pytest + +from pharabius.core.connectors.candidate import ( + write_candidate_artifact, +) +from pharabius.core.connectors.candidate_review import ( + CANDIDATE_DECISION_OUTCOMES, + CandidateReviewError, + CandidateReviewSummary, + format_candidate_review_summary, + review_candidate, + summarize_candidate_reviews, +) +from pharabius.core.lifecycle import ( + FINDING_TRANSITIONS, + FindingStatus, + validate_finding_transition, +) +from pharabius.schemas.candidate import ( + CandidateFinding, + CandidateFindingsArtifact, + CandidateProvenance, +) +from pharabius.schemas.review import DecisionStatus + +# --------------------------------------------------------------------------- +# Helpers +# --------------------------------------------------------------------------- + + +def _make_candidate( + candidate_id: str = "CAND-0001", + connector_name: str = "trivy", + category: str = "TD-VULN", + title: str = "Test vulnerability", +) -> CandidateFinding: + return CandidateFinding( + id=candidate_id, + category=category, + title=title, + description="Test candidate finding", + provenance=CandidateProvenance( + connector_name=connector_name, + source_format=connector_name, + evidence_count=1, + evidence_ids=["EXT-001"], + source_types=["external_scanner_result"], + ), + ) + + +def _setup_workspace( + tmp_path: Path, + *candidates: CandidateFinding, +) -> Path: + """Create workspace with candidate-findings.json.""" + artifact = CandidateFindingsArtifact(candidates=list(candidates)) + write_candidate_artifact(artifact, tmp_path) + return tmp_path + + +# --------------------------------------------------------------------------- +# AC1: review_candidate() records decision in review sidecar +# --------------------------------------------------------------------------- + + +class TestReviewSidecarWrite: + """review_candidate() appends to review sidecar.""" + + def test_creates_sidecar_if_missing(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate()) + decision = review_candidate( + tmp_path, "CAND-0001", DecisionStatus.ACCEPTED, reviewer="alice" + ) + assert decision.finding_id == "CAND-0001" + assert decision.status == DecisionStatus.ACCEPTED + + # Verify sidecar exists + sidecar = tmp_path / ".ai-debt" / "review" / "decisions.json" + assert sidecar.exists() + data = json.loads(sidecar.read_text()) + assert len(data["decisions"]) == 1 + assert data["decisions"][0]["finding_id"] == "CAND-0001" + + def test_appends_to_existing_sidecar(self, tmp_path: Path) -> None: + _setup_workspace( + tmp_path, + _make_candidate("CAND-0001"), + _make_candidate("CAND-0002"), + ) + review_candidate(tmp_path, "CAND-0001", DecisionStatus.ACCEPTED) + review_candidate(tmp_path, "CAND-0002", DecisionStatus.REJECTED) + + sidecar = tmp_path / ".ai-debt" / "review" / "decisions.json" + data = json.loads(sidecar.read_text()) + assert len(data["decisions"]) == 2 + + +# --------------------------------------------------------------------------- +# AC2: review_candidate() records lifecycle entry +# --------------------------------------------------------------------------- + + +class TestLifecycleEntryWrite: + """review_candidate() appends lifecycle entry.""" + + def test_creates_lifecycle_history(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate()) + review_candidate(tmp_path, "CAND-0001", DecisionStatus.ACCEPTED) + + lh = tmp_path / ".ai-debt" / "lifecycle-history.json" + assert lh.exists() + data = json.loads(lh.read_text()) + assert len(data["entries"]) == 1 + entry = data["entries"][0] + assert entry["artifact_type"] == "candidate" + assert entry["artifact_id"] == "CAND-0001" + assert entry["from_status"] == "Candidate" + + def test_accepted_maps_to_candidate_accepted(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate()) + review_candidate(tmp_path, "CAND-0001", DecisionStatus.ACCEPTED) + + lh = tmp_path / ".ai-debt" / "lifecycle-history.json" + data = json.loads(lh.read_text()) + assert data["entries"][0]["to_status"] == "CandidateAccepted" + + def test_rejected_maps_to_candidate_rejected(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate()) + review_candidate(tmp_path, "CAND-0001", DecisionStatus.REJECTED) + + lh = tmp_path / ".ai-debt" / "lifecycle-history.json" + data = json.loads(lh.read_text()) + assert data["entries"][0]["to_status"] == "CandidateRejected" + + def test_deferred_maps_to_candidate_deferred(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate()) + review_candidate(tmp_path, "CAND-0001", DecisionStatus.DEFERRED) + + lh = tmp_path / ".ai-debt" / "lifecycle-history.json" + data = json.loads(lh.read_text()) + assert data["entries"][0]["to_status"] == "CandidateDeferred" + + def test_risk_accepted_maps_to_candidate_rejected(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate()) + review_candidate(tmp_path, "CAND-0001", DecisionStatus.RISK_ACCEPTED) + + lh = tmp_path / ".ai-debt" / "lifecycle-history.json" + data = json.loads(lh.read_text()) + assert data["entries"][0]["to_status"] == "CandidateRejected" + + +# --------------------------------------------------------------------------- +# AC3: Only valid candidate decisions accepted +# --------------------------------------------------------------------------- + + +class TestDecisionValidation: + """Only valid decisions for candidates are accepted.""" + + def test_needs_investigation_rejected(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate()) + with pytest.raises(CandidateReviewError, match="not valid for candidates"): + review_candidate(tmp_path, "CAND-0001", DecisionStatus.NEEDS_INVESTIGATION) + + def test_accepted_is_valid(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate()) + decision = review_candidate(tmp_path, "CAND-0001", DecisionStatus.ACCEPTED) + assert decision.status == DecisionStatus.ACCEPTED + + def test_rejected_is_valid(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate()) + decision = review_candidate(tmp_path, "CAND-0001", DecisionStatus.REJECTED) + assert decision.status == DecisionStatus.REJECTED + + def test_deferred_is_valid(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate()) + decision = review_candidate(tmp_path, "CAND-0001", DecisionStatus.DEFERRED) + assert decision.status == DecisionStatus.DEFERRED + + def test_risk_accepted_is_valid(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate()) + decision = review_candidate(tmp_path, "CAND-0001", DecisionStatus.RISK_ACCEPTED) + assert decision.status == DecisionStatus.RISK_ACCEPTED + + def test_duplicate_is_valid(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate()) + decision = review_candidate(tmp_path, "CAND-0001", DecisionStatus.DUPLICATE) + assert decision.status == DecisionStatus.DUPLICATE + + def test_already_fixed_is_valid(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate()) + decision = review_candidate(tmp_path, "CAND-0001", DecisionStatus.ALREADY_FIXED) + assert decision.status == DecisionStatus.ALREADY_FIXED + + +# --------------------------------------------------------------------------- +# AC4: Only candidate IDs (CAND-XXXX) accepted +# --------------------------------------------------------------------------- + + +class TestCandidateIDValidation: + """Only CAND-* IDs accepted by candidate review.""" + + def test_td_id_rejected(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate()) + with pytest.raises(CandidateReviewError, match="Not a candidate ID"): + review_candidate(tmp_path, "TD-ARCH-001", DecisionStatus.ACCEPTED) + + def test_cand_id_accepted(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate("CAND-0042")) + decision = review_candidate(tmp_path, "CAND-0042", DecisionStatus.ACCEPTED) + assert decision.finding_id == "CAND-0042" + + def test_unknown_cand_id_rejected(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate("CAND-0001")) + with pytest.raises(CandidateReviewError, match="Unknown candidate ID"): + review_candidate(tmp_path, "CAND-9999", DecisionStatus.ACCEPTED) + + +# --------------------------------------------------------------------------- +# AC5: candidate-findings.json NOT modified by review +# --------------------------------------------------------------------------- + + +class TestCandidateArtifactNotMutated: + """Review does not modify candidate-findings.json.""" + + def test_artifact_unchanged_after_review(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate()) + + # Read original artifact + orig_path = tmp_path / ".ai-debt" / "candidate-findings.json" + orig_content = orig_path.read_text() + + review_candidate(tmp_path, "CAND-0001", DecisionStatus.ACCEPTED) + + # Verify unchanged + assert orig_path.read_text() == orig_content + + def test_candidate_status_still_candidate(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate()) + + review_candidate(tmp_path, "CAND-0001", DecisionStatus.ACCEPTED) + + # Re-load artifact — status should still be "Candidate" + artifact_data = json.loads((tmp_path / ".ai-debt" / "candidate-findings.json").read_text()) + assert artifact_data["candidates"][0]["status"] == "Candidate" + + +# --------------------------------------------------------------------------- +# AC6: debt-register.json NOT modified by candidate review +# --------------------------------------------------------------------------- + + +class TestDebtRegisterNotMutated: + """Review does not modify debt-register.json.""" + + def test_no_debt_register_created(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate()) + review_candidate(tmp_path, "CAND-0001", DecisionStatus.ACCEPTED) + + assert not (tmp_path / ".ai-debt" / "debt-register.json").exists() + + def test_existing_debt_register_unchanged(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate()) + + # Pre-create debt-register + ai_debt = tmp_path / ".ai-debt" + register = {"summary": {"total_findings": 5}} + (ai_debt / "debt-register.json").write_text(json.dumps(register)) + orig_content = (ai_debt / "debt-register.json").read_text() + + review_candidate(tmp_path, "CAND-0001", DecisionStatus.ACCEPTED) + + assert (ai_debt / "debt-register.json").read_text() == orig_content + + +# --------------------------------------------------------------------------- +# AC7-8: Append-only behavior +# --------------------------------------------------------------------------- + + +class TestAppendOnly: + """Review decisions and lifecycle entries are append-only.""" + + def test_multiple_candidates_multiple_decisions(self, tmp_path: Path) -> None: + _setup_workspace( + tmp_path, + _make_candidate("CAND-0001"), + _make_candidate("CAND-0002"), + ) + + review_candidate(tmp_path, "CAND-0001", DecisionStatus.ACCEPTED) + review_candidate(tmp_path, "CAND-0002", DecisionStatus.REJECTED) + + sidecar = json.loads((tmp_path / ".ai-debt" / "review" / "decisions.json").read_text()) + assert len(sidecar["decisions"]) == 2 + + history = json.loads((tmp_path / ".ai-debt" / "lifecycle-history.json").read_text()) + assert len(history["entries"]) == 2 + + +# --------------------------------------------------------------------------- +# AC9: Promotion records decision + lifecycle, nothing else +# --------------------------------------------------------------------------- + + +class TestPromotionRecordsOnly: + """Review records decision and lifecycle entry, nothing else.""" + + def test_no_extra_artifacts_created(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate()) + + review_candidate(tmp_path, "CAND-0001", DecisionStatus.ACCEPTED) + + ai_debt = tmp_path / ".ai-debt" + files = {f.name for f in ai_debt.iterdir()} + # Only expected artifacts + assert "candidate-findings.json" in files + assert "lifecycle-history.json" in files + assert files == {"candidate-findings.json", "lifecycle-history.json", "review"} + + +# --------------------------------------------------------------------------- +# AC10: Candidate review summary +# --------------------------------------------------------------------------- + + +class TestCandidateReviewSummary: + """Summary shows pending/promoted/rejected counts.""" + + def test_empty_summary(self, tmp_path: Path) -> None: + summary = summarize_candidate_reviews(tmp_path) + assert summary.total_candidates == 0 + + def test_no_decisions_all_pending(self, tmp_path: Path) -> None: + _setup_workspace( + tmp_path, + _make_candidate("CAND-0001"), + _make_candidate("CAND-0002"), + ) + summary = summarize_candidate_reviews(tmp_path) + assert summary.total_candidates == 2 + assert summary.pending_count == 2 + assert summary.reviewed_count == 0 + + def test_mixed_decisions(self, tmp_path: Path) -> None: + _setup_workspace( + tmp_path, + _make_candidate("CAND-0001"), + _make_candidate("CAND-0002"), + _make_candidate("CAND-0003"), + ) + review_candidate(tmp_path, "CAND-0001", DecisionStatus.ACCEPTED) + review_candidate(tmp_path, "CAND-0002", DecisionStatus.REJECTED) + + summary = summarize_candidate_reviews(tmp_path) + assert summary.total_candidates == 3 + assert len(summary.accepted) == 1 + assert len(summary.rejected) == 1 + assert summary.pending_count == 1 + + def test_format_summary(self, tmp_path: Path) -> None: + _setup_workspace( + tmp_path, + _make_candidate("CAND-0001"), + _make_candidate("CAND-0002"), + ) + review_candidate(tmp_path, "CAND-0001", DecisionStatus.ACCEPTED) + + summary = summarize_candidate_reviews(tmp_path) + text = format_candidate_review_summary(summary) + assert "Candidate Review Summary" in text + assert "review-level only" in text + + +# --------------------------------------------------------------------------- +# AC11-12: Status reader / report integration +# --------------------------------------------------------------------------- + + +class TestStatusReaderIntegration: + """Status reader shows candidate review state.""" + + def test_status_shows_candidates(self, tmp_path: Path) -> None: + from pharabius.core.status_reader import read_status + + _setup_workspace(tmp_path, _make_candidate()) + review_candidate(tmp_path, "CAND-0001", DecisionStatus.ACCEPTED) + + # Need project-profile for status reader + (tmp_path / ".ai-debt").mkdir(exist_ok=True) + (tmp_path / ".ai-debt" / "project-profile.json").write_text( + json.dumps({"project_name": "test", "repository_root": str(tmp_path)}) + ) + + status = read_status(tmp_path) + assert "Candidates:" in status + + +# --------------------------------------------------------------------------- +# AC15: No auto-promotion +# --------------------------------------------------------------------------- + + +class TestNoAutoPromotion: + """No automatic promotion of any kind.""" + + def test_review_does_not_create_debt_finding(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate()) + review_candidate(tmp_path, "CAND-0001", DecisionStatus.ACCEPTED) + + # No debt-register.json + assert not (tmp_path / ".ai-debt" / "debt-register.json").exists() + + +# --------------------------------------------------------------------------- +# AC16-18: No downstream artifacts +# --------------------------------------------------------------------------- + + +class TestNoDownstreamArtifacts: + """Review does not create work packages, tickets, or findings.""" + + def test_no_work_packages(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate()) + review_candidate(tmp_path, "CAND-0001", DecisionStatus.ACCEPTED) + + assert not (tmp_path / ".ai-debt" / "work-packages").exists() + + +# --------------------------------------------------------------------------- +# AC21: Review-level only documentation +# --------------------------------------------------------------------------- + + +class TestReviewLevelOnly: + """Candidate acceptance is review-level, not debt-register promotion.""" + + def test_summary_says_review_level_only(self) -> None: + summary = CandidateReviewSummary( + total_candidates=1, + accepted=["CAND-0001"], + ) + text = format_candidate_review_summary(summary) + assert "not debt-register promotion" in text + + def test_accepted_candidate_not_in_debt_register(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate()) + review_candidate(tmp_path, "CAND-0001", DecisionStatus.ACCEPTED) + # Explicitly: no debt-register.json created + assert not (tmp_path / ".ai-debt" / "debt-register.json").exists() + + +# --------------------------------------------------------------------------- +# AC22: CandidateAccepted ≠ Acknowledged +# --------------------------------------------------------------------------- + + +class TestCandidateDistinctFromAccepted: + """CandidateAccepted is NOT Acknowledged or Detected.""" + + def test_candidate_accepted_is_not_acknowledged(self) -> None: + assert FindingStatus.CANDIDATE_ACCEPTED != FindingStatus.ACKNOWLEDGED + + def test_candidate_accepted_is_not_detected(self) -> None: + assert FindingStatus.CANDIDATE_ACCEPTED != FindingStatus.DETECTED + + def test_candidate_rejected_is_not_wont_fix(self) -> None: + assert FindingStatus.CANDIDATE_REJECTED != FindingStatus.WONT_FIX + + def test_candidate_deferred_is_not_deferred(self) -> None: + """CandidateDeferred is distinct from the finding DEFERRED state.""" + assert FindingStatus.CANDIDATE_DEFERRED != FindingStatus.DEFERRED + + def test_lifecycle_outcome_is_candidate_state(self) -> None: + """Decision-to-outcome maps to candidate states, not finding states.""" + outcome = CANDIDATE_DECISION_OUTCOMES[DecisionStatus.ACCEPTED] + assert outcome == FindingStatus.CANDIDATE_ACCEPTED + + def test_enum_has_11_states(self) -> None: + """8 original + 3 candidate outcomes.""" + assert len(FindingStatus) == 11 + + +# --------------------------------------------------------------------------- +# AC23: Regular review rejects CAND-* IDs +# --------------------------------------------------------------------------- + + +class TestRegularReviewRejectsCandidates: + """Candidate review rejects non-candidate IDs.""" + + def test_td_id_rejected_by_candidate_review(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate()) + with pytest.raises(CandidateReviewError, match="Not a candidate ID"): + review_candidate(tmp_path, "TD-ARCH-001", DecisionStatus.ACCEPTED) + + +# --------------------------------------------------------------------------- +# AC24: Candidate review rejects TD-* IDs +# --------------------------------------------------------------------------- + + +class TestCandidateReviewRejectsFindings: + """Candidate review does not accept finding IDs.""" + + def test_finding_prefix_rejected(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate()) + with pytest.raises(CandidateReviewError, match="Not a candidate ID"): + review_candidate(tmp_path, "TD-DEP-001", DecisionStatus.REJECTED) + + def test_wp_prefix_rejected(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate()) + with pytest.raises(CandidateReviewError, match="Not a candidate ID"): + review_candidate(tmp_path, "WP-001", DecisionStatus.ACCEPTED) + + +# --------------------------------------------------------------------------- +# AC25: One terminal decision per candidate +# --------------------------------------------------------------------------- + + +class TestDuplicateDecisionGuard: + """Candidate with existing terminal decision cannot receive another.""" + + def test_second_accepted_rejected(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate()) + review_candidate(tmp_path, "CAND-0001", DecisionStatus.ACCEPTED) + with pytest.raises(CandidateReviewError, match="already has a terminal review decision"): + review_candidate(tmp_path, "CAND-0001", DecisionStatus.REJECTED) + + def test_second_rejected_rejected(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate()) + review_candidate(tmp_path, "CAND-0001", DecisionStatus.REJECTED) + with pytest.raises(CandidateReviewError, match="already has a terminal review decision"): + review_candidate(tmp_path, "CAND-0001", DecisionStatus.ACCEPTED) + + def test_accepted_then_deferred_rejected(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate()) + review_candidate(tmp_path, "CAND-0001", DecisionStatus.ACCEPTED) + with pytest.raises(CandidateReviewError, match="already has a terminal review decision"): + review_candidate(tmp_path, "CAND-0001", DecisionStatus.DEFERRED) + + def test_deferred_is_terminal_too(self, tmp_path: Path) -> None: + """Deferred is also terminal in v3.7.0.""" + _setup_workspace(tmp_path, _make_candidate()) + review_candidate(tmp_path, "CAND-0001", DecisionStatus.DEFERRED) + with pytest.raises(CandidateReviewError, match="already has a terminal review decision"): + review_candidate(tmp_path, "CAND-0001", DecisionStatus.ACCEPTED) + + +# --------------------------------------------------------------------------- +# AC26: Candidate lifecycle entries use candidate-specific states +# --------------------------------------------------------------------------- + + +class TestCandidateLifecycleStates: + """Lifecycle entries use CandidateAccepted/Rejected/Deferred.""" + + def test_accepted_lifecycle_is_candidate_accepted(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate()) + review_candidate(tmp_path, "CAND-0001", DecisionStatus.ACCEPTED) + history = json.loads((tmp_path / ".ai-debt" / "lifecycle-history.json").read_text()) + assert history["entries"][0]["to_status"] == "CandidateAccepted" + + def test_rejected_lifecycle_is_candidate_rejected(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate()) + review_candidate(tmp_path, "CAND-0001", DecisionStatus.REJECTED) + history = json.loads((tmp_path / ".ai-debt" / "lifecycle-history.json").read_text()) + assert history["entries"][0]["to_status"] == "CandidateRejected" + + def test_candidate_transition_to_acknowledged_not_allowed(self) -> None: + """Candidate cannot transition to Acknowledged (v3.7.0 amendment).""" + result = validate_finding_transition("Candidate", "Acknowledged") + assert not result.valid + + def test_candidate_transition_to_wont_fix_not_allowed(self) -> None: + """Candidate cannot transition to Won't Fix (v3.7.0 amendment).""" + result = validate_finding_transition("Candidate", "Won't Fix") + assert not result.valid + + def test_candidate_transition_to_candidate_accepted(self) -> None: + result = validate_finding_transition("Candidate", "CandidateAccepted") + assert result.valid + + def test_candidate_transition_to_candidate_rejected(self) -> None: + result = validate_finding_transition("Candidate", "CandidateRejected") + assert result.valid + + def test_candidate_outcome_states_are_terminal(self) -> None: + """Candidate outcome states have no outgoing transitions.""" + assert FINDING_TRANSITIONS[FindingStatus.CANDIDATE_ACCEPTED] == set() + assert FINDING_TRANSITIONS[FindingStatus.CANDIDATE_REJECTED] == set() + assert FINDING_TRANSITIONS[FindingStatus.CANDIDATE_DEFERRED] == set() + + +# --------------------------------------------------------------------------- +# AC27: Candidate review summary distinguishes from findings +# --------------------------------------------------------------------------- + + +class TestSummaryDistinguishes: + """Summary clearly separates candidate reviews from finding reviews.""" + + def test_format_mentions_candidates(self) -> None: + summary = CandidateReviewSummary(total_candidates=5) + text = format_candidate_review_summary(summary) + assert "Candidate" in text + + def test_accepted_list_contains_cand_ids(self, tmp_path: Path) -> None: + _setup_workspace(tmp_path, _make_candidate("CAND-0001")) + review_candidate(tmp_path, "CAND-0001", DecisionStatus.ACCEPTED) + summary = summarize_candidate_reviews(tmp_path) + assert "CAND-0001" in summary.accepted + # No TD-* IDs in accepted list + for cid in summary.accepted: + assert cid.startswith("CAND") + + +# --------------------------------------------------------------------------- +# Lifecycle enum coverage +# --------------------------------------------------------------------------- + + +class TestLifecycleEnumCoverage: + """All candidate states have proper lifecycle support.""" + + def test_all_candidate_states_in_transitions(self) -> None: + for status in [ + FindingStatus.CANDIDATE, + FindingStatus.CANDIDATE_ACCEPTED, + FindingStatus.CANDIDATE_REJECTED, + FindingStatus.CANDIDATE_DEFERRED, + ]: + assert status in FINDING_TRANSITIONS + + def test_candidate_states_in_aliases(self) -> None: + from pharabius.core.lifecycle import FINDING_STATUS_ALIASES + + assert "CandidateAccepted" in FINDING_STATUS_ALIASES + assert "CandidateRejected" in FINDING_STATUS_ALIASES + assert "CandidateDeferred" in FINDING_STATUS_ALIASES