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
22 changes: 22 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,28 @@

All notable changes to Pharabius are documented in this file.

## [3.8.0] - Unreleased

### Candidate Decision Reporting and Audit Trail

Makes candidate review decisions auditable and visible across reports, status, and governance export surfaces.

### Added

- **Report candidate decision summary** — Review Decision Summary table in foundation report
- **Lifecycle audit trail** — Candidate Lifecycle Audit Trail section with transitions, actors, rationale
- **Orphaned decision warnings** — Warns about review decisions for unknown candidate IDs
- **Governance export candidate decisions** — `build_candidate_decisions_summary()` helper, `candidate_decisions` field
- **Status reader review summary** — accepted/rejected/deferred/pending counts
- **23 new tests** covering report, audit, export, orphan detection, no-mutation

### Design Rules

- Reporting is read-only — no mutation of any artifact
- No debt-register promotion from candidate reporting
- Governance export is additive-only (`candidate_decisions` added, no existing fields changed)
- No forbidden field names in candidate export data

## [3.7.0] - Unreleased

### Candidate Review and Promotion Workflow
Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,7 @@ Pharabius is a mature CLI engine with an early-stage platform. Current limitatio
- _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._
- _v3.8.0 adds **candidate decision reporting**: audit trail, review summary in reports and governance export. Read-only — no mutation._
- **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
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.7.0"
version = "3.8.0"
description = "Repository-first technical debt intelligence platform"
readme = "README.md"
requires-python = ">=3.11"
Expand Down
30 changes: 30 additions & 0 deletions src/pharabius/core/governance_export.py
Original file line number Diff line number Diff line change
Expand Up @@ -64,13 +64,15 @@ def build_governance_export(
signal_summary: dict | None = None,
governance_quality: GovernanceQualityMetrics | None = None,
governance_trends: GovernanceTrendSummary | None = None,
candidate_decisions: dict | None = None,
run_id: str | None = None,
families_governed: int = 10,
) -> dict:
"""Build governance analytics export dictionary.

Stable schema: schema_version, export_type, and all governance data.
Does not introduce policy interpretation.
v3.8.0: Adds optional candidate_decisions summary.
"""
quality_dict = None
if governance_quality is not None:
Expand Down Expand Up @@ -103,6 +105,10 @@ def build_governance_export(
},
}

# Candidate decisions summary (v3.8.0)
if candidate_decisions is not None:
export["candidate_decisions"] = candidate_decisions

return export


Expand Down Expand Up @@ -139,3 +145,27 @@ def write_governance_export_jsonl(
encoding="utf-8",
)
return output_path


def build_candidate_decisions_summary(
*,
total_candidates: int = 0,
accepted: int = 0,
rejected: int = 0,
deferred: int = 0,
pending: int = 0,
by_connector: dict[str, int] | None = None,
) -> dict:
"""Build candidate decisions summary for governance export.

Additive-only: new fields may be added, existing fields never removed.
Does not include forbidden field names.
"""
return {
"total_candidates": total_candidates,
"accepted": accepted,
"rejected": rejected,
"deferred": deferred,
"pending": pending,
"by_connector": by_connector or {},
}
121 changes: 119 additions & 2 deletions src/pharabius/core/reporter.py
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,8 @@ class ReportContext:
evidence_store: EvidenceStore
debt_register: DebtRegister
candidate_artifact: Any = None # CandidateFindingsArtifact, optional
lifecycle_history: Any = None # LifecycleHistory, optional
candidate_decisions: Any = None # list[dict], optional


def _load_json(path: Path) -> dict[str, Any]:
Expand Down Expand Up @@ -99,12 +101,41 @@ def _context(repository_root: Path) -> ReportContext:
except Exception:
candidate_artifact = None

# Load lifecycle history (optional, v3.8.0)
lifecycle_history = None
lh_path = root / ".ai-debt" / "lifecycle-history.json"
if lh_path.exists():
try:
from pharabius.schemas.lifecycle import LifecycleHistory

lifecycle_history = LifecycleHistory.model_validate_json(
lh_path.read_text(encoding="utf-8")
)
except Exception:
lifecycle_history = None

# Load candidate review decisions (optional, v3.8.0)
candidate_decisions = None
review_path = root / ".ai-debt" / "review" / "decisions.json"
if review_path.exists():
try:
review_data = json.loads(review_path.read_text(encoding="utf-8"))
candidate_decisions = [
d
for d in review_data.get("decisions", [])
if isinstance(d, dict) and d.get("finding_id", "").startswith("CAND")
]
except Exception:
candidate_decisions = 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,
lifecycle_history=lifecycle_history,
candidate_decisions=candidate_decisions,
)


Expand Down Expand Up @@ -1305,17 +1336,38 @@ def _add_lifecycle_summary(lines: list[str], ctx: ReportContext) -> None:


def _add_candidate_findings_section(lines: list[str], ctx: ReportContext) -> None:
"""Add candidate findings section to the foundation report (v3.6.0).
"""Add candidate findings section to the foundation report (v3.6.0, v3.8.0).

Candidate findings are review artifacts, NOT accepted findings.
This section makes them visible for review without affecting
severity/priority summaries or governance metrics.
v3.8.0: Adds review decision audit trail and orphan warnings.
"""
artifact = ctx.candidate_artifact
if artifact is None or not artifact.candidates:
return

summary = artifact.summary
candidate_ids = {c.id for c in artifact.candidates}

# Build decision lookup
decided_ids: set[str] = set()
decision_map: dict[str, dict] = {}
if ctx.candidate_decisions:
for d in ctx.candidate_decisions:
fid = d.get("finding_id", "")
if fid in candidate_ids and fid not in decided_ids:
decided_ids.add(fid)
decision_map[fid] = d

pending_ids = sorted(candidate_ids - decided_ids)
accepted_count = sum(1 for d in decision_map.values() if d.get("status") == "accepted")
rejected_count = sum(
1
for d in decision_map.values()
if d.get("status") in ("rejected", "risk-accepted", "duplicate", "already-fixed")
)
deferred_count = sum(1 for d in decision_map.values() if d.get("status") == "deferred")

lines.extend(
[
Expand Down Expand Up @@ -1346,6 +1398,24 @@ def _add_candidate_findings_section(lines: list[str], ctx: ReportContext) -> Non
for category, count in sorted(summary.by_category.items()):
lines.append(f"| {category} | {count} |")

# Review decision summary (v3.8.0)
if decided_ids or pending_ids:
lines.extend(
[
"",
"### Review Decision Summary",
"",
"| Status | Count |",
"|---|---:|",
f"| CandidateAccepted | {accepted_count} |",
f"| CandidateRejected | {rejected_count} |",
f"| CandidateDeferred | {deferred_count} |",
f"| Pending review | {len(pending_ids)} |",
"",
"> CandidateAccepted is review-level only, not debt-register promotion.",
]
)

lines.extend(
[
"",
Expand All @@ -1354,7 +1424,54 @@ def _add_candidate_findings_section(lines: list[str], ctx: ReportContext) -> Non
]
)
for c in artifact.candidates[:20]: # Cap at 20 for report readability
lines.append(f"- **{c.id}**: {c.title} ({c.provenance.connector_name})")
decision_info = ""
if c.id in decision_map:
d = decision_map[c.id]
status = d.get("status", "unknown")
reviewer = d.get("reviewer", "")
reviewer_str = f" by {reviewer}" if reviewer else ""
decision_info = f" → {status}{reviewer_str}"
lines.append(f"- **{c.id}**: {c.title} ({c.provenance.connector_name}){decision_info}")
if summary.total_candidates > 20:
lines.append(f"- ... and {summary.total_candidates - 20} more")

# Audit trail from lifecycle history (v3.8.0)
if ctx.lifecycle_history:
candidate_entries = [
e
for e in ctx.lifecycle_history.entries
if e.artifact_type == "candidate" and e.artifact_id in candidate_ids
]
if candidate_entries:
lines.extend(
[
"",
"### Candidate Lifecycle Audit Trail",
"",
"| ID | From | To | Actor | Rationale |",
"|---|---|---|---|---|",
]
)
for entry in candidate_entries:
rationale = entry.rationale[:50] if entry.rationale else "-"
lines.append(
f"| {entry.artifact_id} | {entry.from_status} "
f"| {entry.to_status} | {entry.actor} | {rationale} |"
)

# Orphaned decision warnings (v3.8.0)
if ctx.candidate_decisions:
orphaned = [
d for d in ctx.candidate_decisions if d.get("finding_id", "") not in candidate_ids
]
if orphaned:
orphan_ids = ", ".join(d.get("finding_id", "?") for d in orphaned[:5])
lines.extend(
[
"",
f"**Warning:** {len(orphaned)} review decision(s) reference ",
f"unknown candidate IDs: {orphan_ids}",
]
)

lines.append("")
2 changes: 1 addition & 1 deletion tests/test_cli_command_surface.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.7.0" in result.output
assert "3.8.0" in result.output
2 changes: 1 addition & 1 deletion tests/test_release_consistency.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
# ruff: noqa: E402
from validate_release_consistency import validate_release_consistency

EXPECTED = "3.7.0"
EXPECTED = "3.8.0"


class TestVersionSources:
Expand Down
Loading
Loading