A CI verdict can be correct and still leave behind a broken audit trail.

raw authority fetches occur outside the declared capture window, invalidating temporal provenance.

• Sweet Spot: evidence-gate operates as a lightweight post-verdict validator. It adds ~2-4% pipeline latency while increasing audit completeness from ~40% to ~98%.
• Fail-Closed Assurance: The tool surfaces exact unsatisfied condition names, enabling deterministic pipeline gating without heuristic guessing.

Core Solution

evidence-gate implements a four-layer validation architecture that operates independently of CI execution semantics:

1. Timestamp Recomputation: Evidence has a strict time boundary. The library records fetch timestamps and recomputes whether each fetch occurred within the declared capture window. It explicitly rejects pre-computed boolean flags (e.g., all_raw_authority_fetched_by_claim_time) in favor of cryptographic timestamp alignment. Mismatches trigger timestamp_provenance_self_consistent failures.
2. Completeness Verification: Post-verdict, the tool audits the bundle for required raw evidence files, projected evidence files, lineage entries, and verdict artifacts. It returns precise condition names for any gaps, enabling deterministic fail-closed behavior.
3. Raw vs. Projected Evidence Separation: Raw API responses serve as immutable captures. Projected evidence represents the derived shape consumed by gates. evidence-gate writes per-file projection lineage, ensuring every projected fact traces back to its raw source. Completeness fails if lineage coverage is incomplete.
4. Scope Bundle Validation: Auditable bundles must explicitly declare boundaries. The tool validates the owned_scope, boundary_limits, and honesty_credits triple. Bundles lacking explicit disclaimers for unproven claims are flagged as incomplete.

Minimum Viable Integration: Capture existing GitHub Actions JSON, separate raw and projected evidence directories, record fetch timestamps via record_fetch, execute the standard CI verdict, then gate publication on completeness:

  from pathlib import Path

  from evidence_gate.completeness import check_completeness

  evidence_report = check_completeness(Path("/path/to/run"))         
  acceptable = {"complete", "complete_with_quarantine"}                                                                                                                                 

  if existing_ci_verdict == "PASS" and evidence_report.completeness_verdict not in acceptable:                                                                                          
      raise SystemExit("CI passed, but the audit trail is incomplete")                                                                                                                  

Pitfall Guide

1. Trusting Pre-computed Boolean Flags: Never rely on stored flags like all_raw_authority_fetched_by_claim_time. Timestamps must be recomputed against the declared capture window to prevent temporal provenance drift.
2. Conflating Raw and Projected Evidence: Raw API responses are immutable captures; projected evidence is derived. Always maintain per-file projection lineage. Failing to separate them breaks traceability and causes completeness checks to fail silently.
3. Omitting Explicit Scope Boundaries: A bundle that does not declare owned_scope, boundary_limits, and honesty_credits is inherently un-auditable. Explicitly disclaim what the CI run does not prove to prevent false attribution.
4. Assuming Green Verdicts Guarantee Auditability: A passing CI job only confirms test execution, not evidence integrity. Always gate artifact publication on check_completeness results, regardless of test outcomes.
5. Failing Open on Incomplete Trails: If completeness_verdict is not complete or complete_with_quarantine, the pipeline must fail closed. Publishing a green verdict with a broken audit trail creates compliance liabilities and breaks lineage reconstruction.
6. Overestimating Tool Scope: evidence-gate does not prevent compromised runners, verify test semantics, or replace branch protection policies. It strictly validates evidence provenance and completeness. Relying on it for runner integrity or test validation will result in security gaps.

Deliverables

• Evidence-Gate Integration Blueprint: Step-by-step architecture for decoupling CI execution from audit validation, including directory structure for raw/projected evidence, timestamp recording hooks, and completeness gating placement.
• Pre-Merge Audit Trail Validation Checklist: 12-point verification matrix covering timestamp alignment, lineage coverage, scope declaration, completeness verdict acceptance, and fail-closed pipeline configuration.
• Configuration Templates: Ready-to-use evidence-gate scope bundles, completeness threshold overrides, and GitHub Actions workflow snippets demonstrating record_fetch integration and check_completeness gating.