Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions docs/ARTIFACT_CONTRACT.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
16 changes: 16 additions & 0 deletions docs/LIFECYCLE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
158 changes: 158 additions & 0 deletions src/pharabius/core/connectors/candidate.py
Original file line number Diff line number Diff line change
@@ -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)
9 changes: 9 additions & 0 deletions src/pharabius/core/lifecycle.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -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,
Expand All @@ -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,
Expand Down
74 changes: 74 additions & 0 deletions src/pharabius/core/reporter.py
Original file line number Diff line number Diff line change
Expand Up @@ -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]:
Expand Down Expand Up @@ -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,
)


Expand Down Expand Up @@ -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(
[
"",
Expand Down Expand Up @@ -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("")
11 changes: 11 additions & 0 deletions src/pharabius/core/status_reader.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Loading
Loading