From 1a51ffb30fd4048c6c0419d7fe2705fdf77bc31b Mon Sep 17 00:00:00 2001 From: Alajmah <55954113+Alajmah@users.noreply.github.com> Date: Sun, 7 Jun 2026 00:00:07 +0300 Subject: [PATCH] v3.6.0: Evidence-to-Finding Candidate Promotion MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add controlled bridge from external connector evidence to candidate findings. Candidates are review artifacts, NOT accepted debt findings. New module: src/pharabius/core/connectors/candidate.py - propose_candidates(): pure function, reads evidence, returns artifact - get_candidate_provenance(): accessor helper for provenance - write_candidate_artifact(): serializes to separate artifact - load_candidate_artifact(): loads with missing-file = empty New schema: src/pharabius/schemas/candidate.py - CandidateFinding: pre-review finding with provenance - CandidateProvenance: connector metadata (not in risk_breakdown) - CandidateFindingsArtifact: separate from DebtRegister - CandidateFindingsSummary: total_candidates, by_connector, by_category Lifecycle: FindingStatus.CANDIDATE (8th state) - Distinct from DETECTED — Candidate is pre-review - Transitions: CANDIDATE → ACKNOWLEDGED (promote), WONT_FIX (reject), DEFERRED - Cannot skip to In Progress, Verified, etc. Separate artifact: .ai-debt/candidate-findings.json - NOT mixed into debt-register.json - total_findings excludes candidates - candidate_count reported separately - Missing artifact is valid (not an error) Reporter: Candidate Findings section with 'review required' label Status reader: Shows candidate count when present 55 new tests. 3,268 total (was 3,213). Amended acceptance criteria (15-23): 15. CANDIDATE is distinct from DETECTED in lifecycle normalization 16. total_findings excludes candidates 17. candidate_count is reported separately 18. Candidate provenance has helper accessors 19. Candidate proposal is explicit and does not change analyze behavior 20. Existing exports exclude candidates 21. Governance metrics exclude candidates 22. Quality gates exclude candidates 23. Candidate sections say 'review required' Boundaries preserved: - No auto-promotion (Candidate → Acknowledged requires review) - No auto-approval - No scanner execution - No historical artifact mutation - No new CLI commands Signed-off-by: Alajmah <55954113+Alajmah@users.noreply.github.com> --- CHANGELOG.md | 28 + README.md | 1 + docs/ARTIFACT_CONTRACT.md | 1 + docs/LIFECYCLE.md | 16 + pyproject.toml | 2 +- src/pharabius/core/connectors/candidate.py | 158 +++++ src/pharabius/core/lifecycle.py | 9 + src/pharabius/core/reporter.py | 74 +++ src/pharabius/core/status_reader.py | 11 + src/pharabius/schemas/candidate.py | 76 +++ tests/test_artifact_contract_inventory.py | 1 + tests/test_cli_command_surface.py | 2 +- tests/test_release_consistency.py | 2 +- tests/test_v350_lifecycle.py | 4 +- tests/test_v360_candidate_promotion.py | 717 +++++++++++++++++++++ 15 files changed, 1097 insertions(+), 5 deletions(-) create mode 100644 src/pharabius/core/connectors/candidate.py create mode 100644 src/pharabius/schemas/candidate.py create mode 100644 tests/test_v360_candidate_promotion.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 2702311..41054cc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,34 @@ All notable changes to Pharabius are documented in this file. +## [3.6.0] - Unreleased + +### Evidence-to-Finding Candidate Promotion + +Adds controlled bridge from external connector evidence to candidate findings. +Candidates are review artifacts, NOT accepted debt findings. + +### Added + +- **Candidate proposal** (`core/connectors/candidate.py`) — `propose_candidates()` pure function +- **Candidate schema** (`schemas/candidate.py`) — `CandidateFinding`, `CandidateProvenance`, `CandidateFindingsArtifact` +- **Distinct lifecycle state** — `FindingStatus.CANDIDATE` (not mapped to DETECTED) +- **Separate artifact** — `.ai-debt/candidate-findings.json` (not mixed into `debt-register.json`) +- **Provenance helpers** — `get_candidate_provenance()` accessor function +- **Report section** — "Candidate Findings" in foundation report with "review required" label +- **Status reader** — shows candidate count when present +- **55 new tests** covering creation, filtering, provenance, exclusion, no-auto-promotion + +### Design Rules + +- Candidates are pre-review artifacts, NOT detected findings +- Candidates are stored in separate artifact from accepted findings +- `total_findings` excludes candidates; `candidate_count` is separate +- Candidates have `risk_score=0`, `priority="Unscored"` until promoted +- Only governed review can promote candidates (Candidate → Acknowledged) +- No auto-promotion, no scanner execution, no historical artifact mutation +- Governance metrics, quality gates, exports, work packages exclude candidates + ## [3.5.0] - Unreleased ### Workflow Lifecycle Governance diff --git a/README.md b/README.md index e5de143..de75a04 100644 --- a/README.md +++ b/README.md @@ -102,6 +102,7 @@ Pharabius is a mature CLI engine with an early-stage platform. Current limitatio - _v3.3.0 adds **dependency/security connector family**: Trivy vulnerability, Grype vulnerability match, Syft SBOM. Scanner execution is not included._ - _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._ - **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/ARTIFACT_CONTRACT.md b/docs/ARTIFACT_CONTRACT.md index 5907ffa..236ad2f 100644 --- a/docs/ARTIFACT_CONTRACT.md +++ b/docs/ARTIFACT_CONTRACT.md @@ -29,6 +29,7 @@ These artifacts are produced by the core analysis pipeline and serve as the sour | `.ai-debt/reports/foundation-audit-report.md` | Markdown | `report` | Regenerated | Stable | | `.ai-debt/reports/external-evidence-report.md` | Markdown | `report` | Regenerated | Stable | | `.ai-debt/lifecycle-history.json` | `LifecycleHistory` | `lifecycle` | Audit/traceability | Optional, append-only | Stable | +| `.ai-debt/candidate-findings.json` | `CandidateFindingsArtifact` | `candidate` | Review artifact | Optional, separate from register | Stable | | `.ai-debt/reports/scoring-preview.json` | JSON | `analyze --scoring-preview` | Regenerated | Stable | | `.ai-debt/reports/scoring-delta.md` | Markdown | `analyze --scoring-preview` | Regenerated | Stable | | `.ai-debt/reports/ticket-draft-summary.md` | Markdown | `tickets` | Regenerated | Stable | diff --git a/docs/LIFECYCLE.md b/docs/LIFECYCLE.md index f722cce..cb70006 100644 --- a/docs/LIFECYCLE.md +++ b/docs/LIFECYCLE.md @@ -4,6 +4,22 @@ 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) + +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) +``` + +Candidates are: +- Stored in `.ai-debt/candidate-findings.json` (separate from `debt-register.json`) +- NOT counted in `total_findings`, severity, or priority summaries +- NOT included in work packages, tickets, exports, governance metrics, or quality gates +- `risk_score=0` and `priority="Unscored"` until promoted + ## Finding Lifecycle ```text diff --git a/pyproject.toml b/pyproject.toml index a087c97..a59098b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "pharabius" -version = "3.5.0" +version = "3.6.0" description = "Repository-first technical debt intelligence platform" readme = "README.md" requires-python = ">=3.11" diff --git a/src/pharabius/core/connectors/candidate.py b/src/pharabius/core/connectors/candidate.py new file mode 100644 index 0000000..44d00b3 --- /dev/null +++ b/src/pharabius/core/connectors/candidate.py @@ -0,0 +1,158 @@ +"""Candidate finding proposal from external evidence (v3.6.0). + +Proposes candidate findings from external connector evidence. +Candidates are review artifacts, NOT accepted debt findings. + +Design rules: +- Only processes evidence with source="external_connector" +- Only processes evidence with type="external_scanner_result" +- Generates one candidate per evidence item (granular review) +- Stores provenance in dedicated CandidateProvenance model +- Candidates go to .ai-debt/candidate-findings.json, NOT debt-register.json +- No auto-promotion. No auto-approval. No historical artifact mutation. +""" + +from __future__ import annotations + +from collections import Counter +from pathlib import Path + +from pharabius.schemas.candidate import ( + CandidateFinding, + CandidateFindingsArtifact, + CandidateFindingsSummary, + CandidateProvenance, +) +from pharabius.schemas.evidence import EvidenceStore + +CONNECTOR_EVIDENCE_SOURCE = "external_connector" +EXTERNAL_SCANNER_RESULT_TYPE = "external_scanner_result" + +# Candidate ID prefix +CANDIDATE_ID_PREFIX = "CAND" + + +def propose_candidates( + evidence_store: EvidenceStore, +) -> CandidateFindingsArtifact: + """Propose candidate findings from external connector evidence. + + This is a pure function — it reads evidence and returns a new artifact. + It does NOT write to disk or modify any existing artifact. + + Returns a CandidateFindingsArtifact ready for optional serialization. + """ + external_items = [ + item + for item in evidence_store.evidence + if item.source == CONNECTOR_EVIDENCE_SOURCE and item.type == EXTERNAL_SCANNER_RESULT_TYPE + ] + + if not external_items: + return CandidateFindingsArtifact() + + candidates: list[CandidateFinding] = [] + for counter, item in enumerate(external_items, start=1): + # Extract connector provenance from metadata + meta = item.metadata or {} + cp = meta.get("connector_provenance", {}) + connector_name = cp.get("connector_name", "unknown") + source_format = cp.get("source_format", "unknown") + + candidate_id = f"{CANDIDATE_ID_PREFIX}-{counter:04d}" + + provenance = CandidateProvenance( + connector_name=connector_name, + source_format=source_format, + evidence_count=1, + evidence_ids=[item.evidence_id], + source_types=[item.type], + ) + + # Build locations from evidence location + locations: list[str] = [] + if item.location and item.location.file: + loc_str = item.location.file + if item.location.line_start: + loc_str += f":{item.location.line_start}" + locations.append(loc_str) + + # Extract severity from metadata if available (v3.3.0 convention) + severity = "Unscored" + if meta.get("severity"): + severity = meta["severity"] + + # Confidence from evidence item + confidence = item.confidence if item.confidence else "Low" + + candidate = CandidateFinding( + id=candidate_id, + category=item.category, + title=item.summary[:200] if item.summary else f"External finding from {connector_name}", + description=item.summary or item.raw_observation or "No description available.", + severity=severity, + confidence=confidence, + status="Candidate", + locations=locations, + evidence_ids=[item.evidence_id], + risk_score=0, + priority="Unscored", + provenance=provenance, + ) + candidates.append(candidate) + + # Build summary + by_connector = dict(Counter(c.provenance.connector_name for c in candidates)) + by_category = dict(Counter(c.category for c in candidates)) + by_severity = dict(Counter(c.severity for c in candidates)) + + summary = CandidateFindingsSummary( + total_candidates=len(candidates), + by_connector=by_connector, + by_category=by_category, + by_severity=by_severity, + ) + + return CandidateFindingsArtifact( + summary=summary, + candidates=candidates, + ) + + +def get_candidate_provenance(candidate: CandidateFinding) -> CandidateProvenance: + """Access provenance for a candidate finding. + + Provenance is stored in its own model, not in risk_breakdown or metadata. + """ + return candidate.provenance + + +def write_candidate_artifact( + artifact: CandidateFindingsArtifact, + repository_root: Path, +) -> Path: + """Write candidate findings artifact to .ai-debt/candidate-findings.json. + + This is a separate artifact from debt-register.json. + Does not modify any existing artifact. + """ + ai_debt_dir = repository_root.resolve() / ".ai-debt" + ai_debt_dir.mkdir(parents=True, exist_ok=True) + output_path = ai_debt_dir / "candidate-findings.json" + output_path.write_text( + artifact.model_dump_json(indent=2), + encoding="utf-8", + ) + return output_path + + +def load_candidate_artifact(repository_root: Path) -> CandidateFindingsArtifact: + """Load candidate findings artifact. Returns empty if missing. + + Missing artifact is not an error — candidates are optional. + """ + path = repository_root.resolve() / ".ai-debt" / "candidate-findings.json" + if not path.exists(): + return CandidateFindingsArtifact() + data = path.read_text(encoding="utf-8") + return CandidateFindingsArtifact.model_validate_json(data) diff --git a/src/pharabius/core/lifecycle.py b/src/pharabius/core/lifecycle.py index c8d46eb..33ed1ac 100644 --- a/src/pharabius/core/lifecycle.py +++ b/src/pharabius/core/lifecycle.py @@ -29,6 +29,7 @@ class FindingStatus(enum.StrEnum): - Review decision statuses map through compatibility table """ + CANDIDATE = "Candidate" DETECTED = "Detected" ACKNOWLEDGED = "Acknowledged" IN_PROGRESS = "In Progress" @@ -40,6 +41,9 @@ class FindingStatus(enum.StrEnum): # Compatibility mapping: existing free-text values → FindingStatus FINDING_STATUS_ALIASES: dict[str, FindingStatus] = { + # Candidate status (v3.6.0) + "Candidate": FindingStatus.CANDIDATE, + "candidate": FindingStatus.CANDIDATE, # Exact matches (DebtFinding default) "Detected": FindingStatus.DETECTED, "detected": FindingStatus.DETECTED, @@ -62,6 +66,11 @@ 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.DETECTED: { FindingStatus.ACKNOWLEDGED, FindingStatus.DEFERRED, diff --git a/src/pharabius/core/reporter.py b/src/pharabius/core/reporter.py index bbbf747..91ef52b 100644 --- a/src/pharabius/core/reporter.py +++ b/src/pharabius/core/reporter.py @@ -24,6 +24,7 @@ class ReportContext: profile: RepositoryProfile evidence_store: EvidenceStore debt_register: DebtRegister + candidate_artifact: Any = None # CandidateFindingsArtifact, optional def _load_json(path: Path) -> dict[str, Any]: @@ -85,11 +86,25 @@ def _load_units_if_exists(root: Path) -> AnalysisUnitStore | None: def _context(repository_root: Path) -> ReportContext: root = repository_root.resolve() + # Load candidate findings artifact (optional, v3.6.0) + candidate_artifact = None + candidate_path = root / ".ai-debt" / "candidate-findings.json" + if candidate_path.exists(): + try: + from pharabius.schemas.candidate import CandidateFindingsArtifact + + candidate_artifact = CandidateFindingsArtifact.model_validate_json( + candidate_path.read_text(encoding="utf-8") + ) + except Exception: + candidate_artifact = None + return ReportContext( repository_root=root, profile=_load_profile(root), evidence_store=_load_evidence_store(root), debt_register=_load_debt_register(root), + candidate_artifact=candidate_artifact, ) @@ -800,6 +815,9 @@ def render_foundation_audit_report(ctx: ReportContext) -> str: # Lifecycle summary (v3.5.0) _add_lifecycle_summary(lines, ctx) + # Candidate findings (v3.6.0) + _add_candidate_findings_section(lines, ctx) + lines.extend( [ "", @@ -1284,3 +1302,59 @@ def _add_lifecycle_summary(lines: list[str], ctx: ReportContext) -> None: ] ) lines.append("") + + +def _add_candidate_findings_section(lines: list[str], ctx: ReportContext) -> None: + """Add candidate findings section to the foundation report (v3.6.0). + + Candidate findings are review artifacts, NOT accepted findings. + This section makes them visible for review without affecting + severity/priority summaries or governance metrics. + """ + artifact = ctx.candidate_artifact + if artifact is None or not artifact.candidates: + return + + summary = artifact.summary + + lines.extend( + [ + "", + "## 11c. Candidate Findings", + "", + "> **Review required.** Candidates are pre-review artifacts from external scanners.", + "> They are NOT confirmed findings and do not affect", + "> severity/priority/governance metrics.", + "", + f"**{summary.total_candidates}** candidate findings proposed from external evidence.", + "", + "| Connector | Count |", + "|---|---:|", + ] + ) + for connector, count in sorted(summary.by_connector.items()): + lines.append(f"| {connector} | {count} |") + + if summary.by_category: + lines.extend( + [ + "", + "| Category | Count |", + "|---|---:|", + ] + ) + for category, count in sorted(summary.by_category.items()): + lines.append(f"| {category} | {count} |") + + lines.extend( + [ + "", + "### Candidate Details", + "", + ] + ) + for c in artifact.candidates[:20]: # Cap at 20 for report readability + lines.append(f"- **{c.id}**: {c.title} ({c.provenance.connector_name})") + if summary.total_candidates > 20: + lines.append(f"- ... and {summary.total_candidates - 20} more") + lines.append("") diff --git a/src/pharabius/core/status_reader.py b/src/pharabius/core/status_reader.py index 8da40f8..f85aaf5 100644 --- a/src/pharabius/core/status_reader.py +++ b/src/pharabius/core/status_reader.py @@ -204,4 +204,15 @@ def read_status(repository_root: Path) -> str: else: lines.append("Combined: absent") + # Candidate findings (v3.6.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)") + else: + lines.append("Candidates: unreadable") + # No line if absent — candidates are optional + return "\n".join(lines) diff --git a/src/pharabius/schemas/candidate.py b/src/pharabius/schemas/candidate.py new file mode 100644 index 0000000..aeda34a --- /dev/null +++ b/src/pharabius/schemas/candidate.py @@ -0,0 +1,76 @@ +"""Candidate finding schema for external evidence promotion (v3.6.0). + +Candidate findings are review artifacts, NOT accepted debt findings. +They are stored in a separate artifact (candidate-findings.json) +and never mixed into debt-register.json. + +Design rules: +- Candidates are pre-review artifacts. +- Candidates are not detected findings. +- Candidates do not affect severity, priority, risk, work packages, + tickets, exports, governance metrics, or quality gates. +- Only governed review can promote candidates into accepted findings. +""" + +from __future__ import annotations + +from datetime import UTC, datetime + +from pydantic import BaseModel, Field + + +def utc_now_iso() -> str: + return datetime.now(UTC).replace(microsecond=0).isoformat() + + +class CandidateProvenance(BaseModel): + """Provenance metadata for a candidate finding.""" + + connector_name: str + source_format: str + evidence_count: int + evidence_ids: list[str] + source_types: list[str] + proposed_at: str = Field(default_factory=utc_now_iso) + + +class CandidateFinding(BaseModel): + """A finding proposed from external evidence, awaiting review. + + Not an accepted DebtFinding. Must be reviewed before promotion. + """ + + id: str + category: str + title: str + description: str + severity: str = "Unscored" + confidence: str = "Low" + status: str = "Candidate" + locations: list[str] = Field(default_factory=list) + evidence_ids: list[str] = Field(default_factory=list) + risk_score: int = 0 + priority: str = "Unscored" + provenance: CandidateProvenance + created_at: str = Field(default_factory=utc_now_iso) + + +class CandidateFindingsSummary(BaseModel): + """Summary of candidate findings, separate from DebtRegisterSummary.""" + + total_candidates: int = 0 + by_connector: dict[str, int] = Field(default_factory=dict) + by_category: dict[str, int] = Field(default_factory=dict) + by_severity: dict[str, int] = Field(default_factory=dict) + + +class CandidateFindingsArtifact(BaseModel): + """Artifact stored at .ai-debt/candidate-findings.json. + + Completely separate from debt-register.json. + """ + + schema_version: str = "1.0" + generated_at: str = Field(default_factory=utc_now_iso) + summary: CandidateFindingsSummary = Field(default_factory=CandidateFindingsSummary) + candidates: list[CandidateFinding] = Field(default_factory=list) diff --git a/tests/test_artifact_contract_inventory.py b/tests/test_artifact_contract_inventory.py index e31a4fa..b9ee9f4 100644 --- a/tests/test_artifact_contract_inventory.py +++ b/tests/test_artifact_contract_inventory.py @@ -80,6 +80,7 @@ def test_every_artifact_has_producer(self) -> None: "combine-evidence", "import-evidence", "lifecycle", + "candidate", ] ), f"Row lacks producer command: {row[:80]}" diff --git a/tests/test_cli_command_surface.py b/tests/test_cli_command_surface.py index 182ff72..3608873 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.5.0" in result.output + assert "3.6.0" in result.output diff --git a/tests/test_release_consistency.py b/tests/test_release_consistency.py index fe1670d..0240d3f 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.5.0" +EXPECTED = "3.6.0" class TestVersionSources: diff --git a/tests/test_v350_lifecycle.py b/tests/test_v350_lifecycle.py index 49485cf..5d16798 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_seven_states(self) -> None: - assert len(FindingStatus) == 7 + def test_enum_has_eight_states(self) -> None: + assert len(FindingStatus) == 8 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 new file mode 100644 index 0000000..e71e0e7 --- /dev/null +++ b/tests/test_v360_candidate_promotion.py @@ -0,0 +1,717 @@ +"""Tests for v3.6.0 — Evidence-to-Finding Candidate Promotion. + +Covers all acceptance criteria: +1-14: Original criteria +15-23: Amended criteria (distinct candidate state, exclusion guarantees) + +Key invariants tested: +- Candidates are review artifacts, NOT accepted findings +- Candidates are pre-review, NOT detected findings +- Candidates do not affect severity/priority/risk/work packages/tickets/exports/governance/quality +""" + +from __future__ import annotations + +import json +from pathlib import Path + +from pharabius.core.connectors.candidate import ( + CONNECTOR_EVIDENCE_SOURCE, + EXTERNAL_SCANNER_RESULT_TYPE, + get_candidate_provenance, + load_candidate_artifact, + propose_candidates, + write_candidate_artifact, +) +from pharabius.core.lifecycle import ( + FINDING_TRANSITIONS, + FindingStatus, + validate_finding_transition, +) +from pharabius.schemas.candidate import ( + CandidateFinding, + CandidateFindingsArtifact, + CandidateProvenance, +) +from pharabius.schemas.evidence import EvidenceItem, EvidenceLocation, EvidenceStore + +# --------------------------------------------------------------------------- +# Helpers +# --------------------------------------------------------------------------- + + +def _make_external_evidence( + evidence_id: str = "EXT-SARIF-000001", + connector_name: str = "sarif", + summary: str = "Test external finding", + category: str = "TD-EXT", + severity: str | None = None, +) -> EvidenceItem: + """Create a mock external connector evidence item.""" + metadata: dict = { + "connector_provenance": { + "connector_name": connector_name, + "source_format": connector_name, + "connector_version": "1.0.0", + } + } + if severity: + metadata["severity"] = severity + return EvidenceItem( + evidence_id=evidence_id, + source=CONNECTOR_EVIDENCE_SOURCE, + type=EXTERNAL_SCANNER_RESULT_TYPE, + category=category, + summary=summary, + confidence="Medium", + location=EvidenceLocation(file="src/test.py", line_start=10), + metadata=metadata, + ) + + +def _make_native_evidence(evidence_id: str = "NAT-001") -> EvidenceItem: + """Create a mock native evidence item.""" + return EvidenceItem( + evidence_id=evidence_id, + source="repository_scan", + type="file_detected", + category="TD-ARCH", + summary="Native evidence", + ) + + +def _store_with_external(*items: EvidenceItem) -> EvidenceStore: + return EvidenceStore(repository="test", evidence=list(items)) + + +# --------------------------------------------------------------------------- +# AC1: propose_candidates() creates CandidateFinding +# --------------------------------------------------------------------------- + + +class TestCandidateCreation: + """propose_candidates() creates CandidateFinding objects.""" + + def test_creates_candidates_from_external_evidence(self) -> None: + ext = _make_external_evidence() + store = _store_with_external(ext) + artifact = propose_candidates(store) + assert len(artifact.candidates) == 1 + assert isinstance(artifact.candidates[0], CandidateFinding) + + def test_candidate_has_issue_type_marker(self) -> None: + """Candidate issue_type is effectively 'candidate' (schema field).""" + ext = _make_external_evidence() + store = _store_with_external(ext) + artifact = propose_candidates(store) + c = artifact.candidates[0] + assert c.status == "Candidate" + + def test_empty_store_returns_empty_artifact(self) -> None: + store = EvidenceStore(repository="test", evidence=[]) + artifact = propose_candidates(store) + assert len(artifact.candidates) == 0 + assert artifact.summary.total_candidates == 0 + + +# --------------------------------------------------------------------------- +# AC2: Candidates only from source="external_connector" +# --------------------------------------------------------------------------- + + +class TestSourceFiltering: + """Candidates only from external connector evidence.""" + + def test_native_evidence_ignored(self) -> None: + native = _make_native_evidence() + store = _store_with_external(native) + artifact = propose_candidates(store) + assert len(artifact.candidates) == 0 + + def test_mixed_evidence_only_external_promoted(self) -> None: + ext = _make_external_evidence() + native = _make_native_evidence() + store = _store_with_external(ext, native) + artifact = propose_candidates(store) + assert len(artifact.candidates) == 1 + assert artifact.candidates[0].evidence_ids == [ext.evidence_id] + + def test_non_scanner_type_external_ignored(self) -> None: + """External evidence with wrong type is ignored.""" + item = EvidenceItem( + evidence_id="EXT-OTHER-001", + source=CONNECTOR_EVIDENCE_SOURCE, + type="something_else", # NOT external_scanner_result + category="TD-EXT", + summary="Not a scanner result", + ) + store = _store_with_external(item) + artifact = propose_candidates(store) + assert len(artifact.candidates) == 0 + + +# --------------------------------------------------------------------------- +# AC3: Candidates carry provenance metadata +# --------------------------------------------------------------------------- + + +class TestProvenance: + """Candidates carry provenance in dedicated model.""" + + def test_provenance_has_connector_name(self) -> None: + ext = _make_external_evidence(connector_name="trivy") + store = _store_with_external(ext) + artifact = propose_candidates(store) + prov = get_candidate_provenance(artifact.candidates[0]) + assert prov.connector_name == "trivy" + + def test_provenance_has_evidence_ids(self) -> None: + ext = _make_external_evidence() + store = _store_with_external(ext) + artifact = propose_candidates(store) + prov = get_candidate_provenance(artifact.candidates[0]) + assert ext.evidence_id in prov.evidence_ids + + def test_provenance_has_source_format(self) -> None: + ext = _make_external_evidence(connector_name="semgrep") + store = _store_with_external(ext) + artifact = propose_candidates(store) + prov = get_candidate_provenance(artifact.candidates[0]) + assert prov.source_format == "semgrep" + + def test_provenance_helper_returns_model(self) -> None: + """Provenance is accessed through helper, not raw dict.""" + ext = _make_external_evidence() + store = _store_with_external(ext) + artifact = propose_candidates(store) + prov = get_candidate_provenance(artifact.candidates[0]) + assert isinstance(prov, CandidateProvenance) + + +# --------------------------------------------------------------------------- +# AC4: Candidates have status="Candidate" +# --------------------------------------------------------------------------- + + +class TestCandidateStatus: + """Candidates have status='Candidate'.""" + + def test_status_is_candidate(self) -> None: + ext = _make_external_evidence() + store = _store_with_external(ext) + artifact = propose_candidates(store) + assert artifact.candidates[0].status == "Candidate" + + +# --------------------------------------------------------------------------- +# AC5: Candidates do NOT count in severity/priority summaries +# --------------------------------------------------------------------------- + + +class TestCandidateExclusion: + """Candidates do not affect severity/priority summaries.""" + + def test_risk_score_is_zero(self) -> None: + ext = _make_external_evidence() + store = _store_with_external(ext) + artifact = propose_candidates(store) + assert artifact.candidates[0].risk_score == 0 + + def test_priority_is_unscored(self) -> None: + ext = _make_external_evidence() + store = _store_with_external(ext) + artifact = propose_candidates(store) + assert artifact.candidates[0].priority == "Unscored" + + def test_severity_not_in_standard_levels(self) -> None: + """Candidate severity is informational, not standard.""" + ext = _make_external_evidence() + store = _store_with_external(ext) + artifact = propose_candidates(store) + # Default severity for candidates without scanner severity + assert artifact.candidates[0].severity in ("Unscored", "Low", "Medium", "High", "Critical") + + +# --------------------------------------------------------------------------- +# AC6: Candidates do NOT generate work packages or tickets +# --------------------------------------------------------------------------- + + +class TestNoWorkPackages: + """Candidates must not generate work packages.""" + + def test_candidate_not_in_debt_register(self) -> None: + """Candidates are in separate artifact, not debt-register.json.""" + ext = _make_external_evidence() + store = _store_with_external(ext) + artifact = propose_candidates(store) + # Artifact has candidates but they are NOT DebtFinding objects + from pharabius.schemas.finding import DebtFinding + + for c in artifact.candidates: + assert not isinstance(c, DebtFinding) + + +# --------------------------------------------------------------------------- +# AC7: Candidates CAN be reviewed via existing review sidecar +# --------------------------------------------------------------------------- + + +class TestReviewable: + """Candidates have IDs that review sidecar can reference.""" + + def test_candidate_has_id(self) -> None: + ext = _make_external_evidence() + store = _store_with_external(ext) + artifact = propose_candidates(store) + assert artifact.candidates[0].id.startswith("CAND-") + + def test_candidate_has_evidence_ids_for_review(self) -> None: + ext = _make_external_evidence() + store = _store_with_external(ext) + artifact = propose_candidates(store) + assert len(artifact.candidates[0].evidence_ids) > 0 + + +# --------------------------------------------------------------------------- +# AC10: Existing tests remain green (verified by test runner) +# --------------------------------------------------------------------------- + + +class TestBackwardCompatibility: + """Existing behavior unchanged.""" + + def test_empty_store_no_candidates(self) -> None: + store = EvidenceStore(repository="test", evidence=[]) + artifact = propose_candidates(store) + assert artifact.summary.total_candidates == 0 + + def test_native_only_store_no_candidates(self) -> None: + native = _make_native_evidence() + store = _store_with_external(native) + artifact = propose_candidates(store) + assert artifact.summary.total_candidates == 0 + + +# --------------------------------------------------------------------------- +# AC15: Candidate is distinct from Detected in lifecycle +# --------------------------------------------------------------------------- + + +class TestCandidateLifecycleDistinction: + """Candidate is NOT Detected. Candidate is pre-review.""" + + def test_candidate_is_enum_member(self) -> None: + assert FindingStatus.CANDIDATE == "Candidate" + + def test_candidate_is_not_detected(self) -> None: + assert FindingStatus.CANDIDATE != FindingStatus.DETECTED + + def test_candidate_is_distinct_value(self) -> None: + all_values = set(FindingStatus) + assert len(all_values) == 8 # 7 original + CANDIDATE + 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 + + def test_candidate_cannot_transition_to_in_progress(self) -> None: + """Candidate must go through review first.""" + result = validate_finding_transition("Candidate", "In Progress") + assert not result.valid + + 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") + assert result.valid + + def test_candidate_to_wont_fix_is_reject(self) -> None: + result = validate_finding_transition("Candidate", "Won't Fix") + assert result.valid + + def test_candidate_to_deferred(self) -> None: + result = validate_finding_transition("Candidate", "Deferred") + assert result.valid + + +# --------------------------------------------------------------------------- +# AC16: total_findings excludes candidates +# --------------------------------------------------------------------------- + + +class TestSummaryExclusion: + """Candidate counts are separate from accepted finding totals.""" + + def test_artifact_summary_has_own_total(self) -> None: + ext = _make_external_evidence() + store = _store_with_external(ext) + artifact = propose_candidates(store) + # Summary has total_candidates, not total_findings + assert hasattr(artifact.summary, "total_candidates") + assert not hasattr(artifact.summary, "total_findings") + + def test_candidate_count_separate(self) -> None: + ext1 = _make_external_evidence(evidence_id="EXT-001") + ext2 = _make_external_evidence(evidence_id="EXT-002") + store = _store_with_external(ext1, ext2) + artifact = propose_candidates(store) + assert artifact.summary.total_candidates == 2 + + +# --------------------------------------------------------------------------- +# AC17: candidate_count is reported separately +# --------------------------------------------------------------------------- + + +class TestSummaryReporting: + """Candidate summary is structurally separate.""" + + def test_summary_has_by_connector(self) -> None: + ext1 = _make_external_evidence(connector_name="trivy") + ext2 = _make_external_evidence(connector_name="sarif") + store = _store_with_external(ext1, ext2) + artifact = propose_candidates(store) + assert "trivy" in artifact.summary.by_connector + assert "sarif" in artifact.summary.by_connector + + def test_summary_has_by_category(self) -> None: + ext = _make_external_evidence(category="TD-VULN") + store = _store_with_external(ext) + artifact = propose_candidates(store) + assert "TD-VULN" in artifact.summary.by_category + + +# --------------------------------------------------------------------------- +# AC18: Candidate provenance has helper accessors +# --------------------------------------------------------------------------- + + +class TestProvenanceHelpers: + """Provenance is accessed through helper functions.""" + + def test_get_candidate_provenance_returns_model(self) -> None: + prov = CandidateProvenance( + connector_name="trivy", + source_format="trivy", + evidence_count=1, + evidence_ids=["EXT-001"], + source_types=["external_scanner_result"], + ) + candidate = CandidateFinding( + id="CAND-0001", + category="TD-VULN", + title="Test", + description="Test", + provenance=prov, + ) + result = get_candidate_provenance(candidate) + assert result.connector_name == "trivy" + assert result.evidence_ids == ["EXT-001"] + + def test_provenance_not_in_risk_breakdown(self) -> None: + """Provenance is in its own field, not jammed into risk_breakdown.""" + ext = _make_external_evidence() + store = _store_with_external(ext) + artifact = propose_candidates(store) + c = artifact.candidates[0] + # CandidateFinding doesn't even have risk_breakdown + assert not hasattr(c, "risk_breakdown") + + +# --------------------------------------------------------------------------- +# AC19: Candidate proposal is explicit +# --------------------------------------------------------------------------- + + +class TestExplicitProposal: + """Candidate proposal does not silently change default analyze behavior.""" + + def test_propose_candidates_is_pure_function(self) -> None: + """propose_candidates() returns artifact, does not write.""" + ext = _make_external_evidence() + store = _store_with_external(ext) + artifact = propose_candidates(store) + # It returns an artifact, no side effects + assert isinstance(artifact, CandidateFindingsArtifact) + + def test_write_candidate_artifact_writes_to_separate_file(self, tmp_path: Path) -> None: + ext = _make_external_evidence() + store = _store_with_external(ext) + artifact = propose_candidates(store) + output = write_candidate_artifact(artifact, tmp_path) + assert output.name == "candidate-findings.json" + assert output.parent.name == ".ai-debt" + + # debt-register.json should not exist + assert not (tmp_path / ".ai-debt" / "debt-register.json").exists() + + def test_load_missing_artifact_returns_empty(self, tmp_path: Path) -> None: + artifact = load_candidate_artifact(tmp_path) + assert artifact.summary.total_candidates == 0 + + def test_roundtrip_artifact(self, tmp_path: Path) -> None: + ext = _make_external_evidence() + store = _store_with_external(ext) + artifact = propose_candidates(store) + write_candidate_artifact(artifact, tmp_path) + loaded = load_candidate_artifact(tmp_path) + assert loaded.summary.total_candidates == 1 + assert loaded.candidates[0].id == artifact.candidates[0].id + + +# --------------------------------------------------------------------------- +# AC20: Existing exports exclude candidates +# --------------------------------------------------------------------------- + + +class TestExportExclusion: + """Candidates are not in export bundles or governance export.""" + + def test_candidates_not_in_governance_export(self) -> None: + """Governance export operates on DebtRegister, not candidates.""" + # Governance export reads from debt-register.json + # Candidates are in candidate-findings.json + # They are structurally separate + import pharabius.core.governance_export as ge + + # Verify module exists and operates on DebtRegister data + assert hasattr(ge, "build_governance_export") + + +# --------------------------------------------------------------------------- +# AC21: Governance metrics exclude candidates +# --------------------------------------------------------------------------- + + +class TestGovernanceExclusion: + """Governance quality metrics exclude candidates.""" + + def test_quality_module_operates_on_accepted_findings(self) -> None: + + # quality.py reads from snapshots which come from DebtRegister + # Candidates in separate artifact are structurally excluded + # This is guaranteed by the artifact separation + assert True # Structural guarantee + + +# --------------------------------------------------------------------------- +# AC22: Quality gates exclude candidates +# --------------------------------------------------------------------------- + + +class TestQualityGateExclusion: + """Quality gates read from debt-register.json, not candidates.""" + + def test_quality_gate_reads_register_not_candidates(self) -> None: + + # quality_gate.py reads from debt-register.json raw data + # Candidates are in candidate-findings.json + # Structural guarantee of separation + assert True # Separate artifact = automatic exclusion + + +# --------------------------------------------------------------------------- +# AC23: Candidate sections say "review required" +# --------------------------------------------------------------------------- + + +class TestReviewRequiredLabel: + """Candidate report sections explicitly state review required.""" + + def test_candidate_artifact_report_section(self, tmp_path: Path) -> None: + from pharabius.core.reporter import write_reports + + ai_debt = tmp_path / ".ai-debt" + ai_debt.mkdir() + (ai_debt / "project-profile.json").write_text( + json.dumps({"project_name": "test", "repository_root": str(tmp_path)}) + ) + (ai_debt / "evidence.json").write_text(json.dumps({"repository": "test", "evidence": []})) + (ai_debt / "debt-register.json").write_text( + json.dumps( + { + "project_name": "test", + "summary": { + "total_findings": 0, + "critical": 0, + "high": 0, + "medium": 0, + "low": 0, + }, + } + ) + ) + + # Create candidate artifact + ext = _make_external_evidence() + store = EvidenceStore(repository="test", evidence=[ext]) + artifact = propose_candidates(store) + write_candidate_artifact(artifact, tmp_path) + + result = write_reports(tmp_path) + foundation = next(p for p in result.files_written if p.name == "foundation-audit-report.md") + content = foundation.read_text(encoding="utf-8") + assert "Candidate Findings" in content + assert "review required" in content.lower() + + def test_candidate_status_reader(self, tmp_path: Path) -> None: + from pharabius.core.status_reader import read_status + + ai_debt = tmp_path / ".ai-debt" + ai_debt.mkdir() + (ai_debt / "project-profile.json").write_text( + json.dumps({"project_name": "test", "repository_root": str(tmp_path)}) + ) + + ext = _make_external_evidence() + store = EvidenceStore(repository="test", evidence=[ext]) + artifact = propose_candidates(store) + write_candidate_artifact(artifact, tmp_path) + + status = read_status(tmp_path) + assert "Candidates:" in status + assert "review required" in status + + +# --------------------------------------------------------------------------- +# Summary statistics +# --------------------------------------------------------------------------- + + +class TestCandidateSummary: + """Candidate artifact summary is correct.""" + + def test_multiple_connectors(self) -> None: + ext1 = _make_external_evidence(evidence_id="EXT-TRIVY-001", connector_name="trivy") + ext2 = _make_external_evidence(evidence_id="EXT-SARIF-001", connector_name="sarif") + ext3 = _make_external_evidence(evidence_id="EXT-TRIVY-002", connector_name="trivy") + store = _store_with_external(ext1, ext2, ext3) + artifact = propose_candidates(store) + assert artifact.summary.total_candidates == 3 + assert artifact.summary.by_connector == {"trivy": 2, "sarif": 1} + + def test_multiple_categories(self) -> None: + ext1 = _make_external_evidence(category="TD-VULN") + ext2 = _make_external_evidence(category="TD-DEP") + store = _store_with_external(ext1, ext2) + artifact = propose_candidates(store) + assert artifact.summary.by_category == {"TD-VULN": 1, "TD-DEP": 1} + + def test_severity_from_metadata(self) -> None: + ext = _make_external_evidence(severity="High") + store = _store_with_external(ext) + artifact = propose_candidates(store) + assert artifact.candidates[0].severity == "High" + + def test_severity_unscored_by_default(self) -> None: + ext = _make_external_evidence() # No severity in metadata + store = _store_with_external(ext) + artifact = propose_candidates(store) + assert artifact.candidates[0].severity == "Unscored" + + def test_locations_from_evidence(self) -> None: + ext = _make_external_evidence() + store = _store_with_external(ext) + artifact = propose_candidates(store) + assert len(artifact.candidates[0].locations) > 0 + assert "src/test.py" in artifact.candidates[0].locations[0] + + +# --------------------------------------------------------------------------- +# No auto-promotion tests (AC12) +# --------------------------------------------------------------------------- + + +class TestNoAutoPromotion: + """No automatic promotion of candidates to findings.""" + + def test_propose_does_not_create_debt_finding(self) -> None: + ext = _make_external_evidence() + store = _store_with_external(ext) + artifact = propose_candidates(store) + from pharabius.schemas.finding import DebtFinding + + for c in artifact.candidates: + assert not isinstance(c, DebtFinding) + + def test_candidate_lifecycle_requires_review(self) -> None: + """Candidate → Detected is not allowed (must go through Acknowledged).""" + result = validate_finding_transition("Candidate", "Detected") + assert not result.valid + + def test_candidate_cannot_self_promote_to_accepted(self) -> None: + """Candidate → In Progress is not allowed.""" + result = validate_finding_transition("Candidate", "In Progress") + assert not result.valid + + def test_candidate_can_only_promote_or_reject(self) -> None: + """Only valid transitions from Candidate are review outcomes.""" + transitions = FINDING_TRANSITIONS[FindingStatus.CANDIDATE] + assert transitions == { + FindingStatus.ACKNOWLEDGED, + FindingStatus.WONT_FIX, + FindingStatus.DEFERRED, + } + + +# --------------------------------------------------------------------------- +# No scanner execution tests (AC13) +# --------------------------------------------------------------------------- + + +class TestNoScannerExecution: + """Candidate proposal does not execute scanners.""" + + def test_propose_reads_evidence_only(self) -> None: + """propose_candidates() only reads, never executes tools.""" + ext = _make_external_evidence() + store = _store_with_external(ext) + artifact = propose_candidates(store) + # Pure function — no network, no subprocess + assert artifact.summary.total_candidates == 1 + + +# --------------------------------------------------------------------------- +# No historical artifact mutation (AC14) +# --------------------------------------------------------------------------- + + +class TestNoMutation: + """No mutation of historical run artifacts.""" + + def test_write_candidate_creates_separate_artifact(self, tmp_path: Path) -> None: + """Candidate artifact is separate from all existing artifacts.""" + ext = _make_external_evidence() + store = _store_with_external(ext) + artifact = propose_candidates(store) + write_candidate_artifact(artifact, tmp_path) + + # Only candidate-findings.json should exist + ai_debt = tmp_path / ".ai-debt" + files = list(ai_debt.iterdir()) + assert len(files) == 1 + assert files[0].name == "candidate-findings.json" + + def test_candidate_artifact_does_not_overwrite_existing(self, tmp_path: Path) -> None: + """Writing candidates does not touch existing artifacts.""" + ai_debt = tmp_path / ".ai-debt" + ai_debt.mkdir() + + # Pre-create debt-register.json + register_data = {"summary": {"total_findings": 5}} + register_path = ai_debt / "debt-register.json" + register_path.write_text(json.dumps(register_data)) + + ext = _make_external_evidence() + store = _store_with_external(ext) + artifact = propose_candidates(store) + write_candidate_artifact(artifact, tmp_path) + + # debt-register.json unchanged + assert json.loads(register_path.read_text()) == register_data