Skip to content

v3.6.0: Evidence-to-Finding Candidate Promotion - #78

Merged
Alajmah merged 1 commit into
masterfrom
roadmap/v3.6.0-evidence-to-finding-promotion
Jun 6, 2026
Merged

Alajmah merged 1 commit into
masterfrom
roadmap/v3.6.0-evidence-to-finding-promotion

Conversation

@Alajmah

@Alajmah Alajmah commented Jun 6, 2026

Copy link
Copy Markdown
Collaborator

Summary

Adds controlled bridge from external connector evidence to candidate findings. Candidates are review artifacts, NOT accepted debt findings.

What's new

Component File Purpose
Candidate proposal core/connectors/candidate.py propose_candidates() pure function
Candidate schema schemas/candidate.py CandidateFinding, CandidateProvenance
Lifecycle state core/lifecycle.py FindingStatus.CANDIDATE (8th state)
Report section reporter.py Candidate Findings with "review required"
Status reader status_reader.py Shows candidate count

Key design: Separate artifact

debt-register.json         → Accepted findings (unchanged)
candidate-findings.json    → Candidate findings (separate)

total_findings excludes candidates. candidate_count is reported separately.

Candidate lifecycle

CANDIDATE → Acknowledged (promote after review)
CANDIDATE → Won't Fix     (reject after review)
CANDIDATE → Deferred      (defer review)

Candidate ≠ Detected. Candidate is pre-review.

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 (get_candidate_provenance())
  • 19. Candidate proposal is explicit — does not change analyze behavior
  • 20. Existing exports exclude candidates
  • 21. Governance metrics exclude candidates
  • 22. Quality gates exclude candidates
  • 23. Candidate report sections say "review required"

Tests: 3,268 passed, 7 skipped (+55 new)

Boundaries preserved

No auto-promotion. No auto-approval.
No scanner execution. No historical artifact mutation.
No new CLI commands.

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>
@gitwire-hq gitwire-hq Bot added the size/XL label Jun 6, 2026
@Alajmah
Alajmah merged commit 389a6c6 into master Jun 6, 2026
5 checks passed
@Alajmah
Alajmah deleted the roadmap/v3.6.0-evidence-to-finding-promotion branch June 6, 2026 21:02
Alajmah added a commit that referenced this pull request Jun 13, 2026
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant