feat(evidence): land evidence set authority - #82
Merged
Conversation
Why: - durable contract and sequencing guidance was still split across planning surfaces, owner docs, and docs-audit control-plane checks - that made evidence-authority review harder because contract retirement proof and forward-contract semantics were still coupled to planning surfaces instead of the owner docs that now hold the durable rules What: - move the bounded contract and sequencing references onto the renamed owner docs and remove planning-coupled docs-audit authority - update migration, architecture, naming, and adapter guidance to use bounded contract vocabulary instead of first-slice shorthand - retune docs-audit, target-naming, and review-verification tests and catalogs around the new owner-doc boundaries Checks: - make pr-review-full
Why: - evidence authority needs a frozen kernel and repository boundary before normalization can persist authoritative selections without widening the bridge scope - stable ids, fingerprints, and serialization rules need their own bounded checkpoint so later integration changes do not hide contract drift What: - add EvidenceSet domain models, stable-id helpers, fingerprint assembly, and JSON payload generation - add the EvidenceSet repository port plus the filesystem repository and export the new surface through the existing package boundaries - add unit coverage for kernel semantics and repository round trips, including schema-version rejection paths Checks: - make pytest ARGS='tests/unit/domain/evidence/test_models.py tests/unit/infrastructure/storage/test_evidence_set_repository.py -q --no-cov' - make mypy ARGS='src/tallylot/domain/evidence/models.py src/tallylot/domain/evidence/__init__.py src/tallylot/domain/__init__.py src/tallylot/ports/evidence_sets.py src/tallylot/ports/__init__.py src/tallylot/infrastructure/storage/evidence_sets.py src/tallylot/infrastructure/storage/__init__.py tests/unit/domain/evidence/test_models.py tests/unit/infrastructure/storage/test_evidence_set_repository.py'
Why: - the statement evidence path was reparsing and reselecting documents inside the balance-reference flow, which made the new EvidenceSet builder duplicate selection logic and risk drift - the evidence-authority slice needs one reusable statement collection result so recognized, superseded, and blocked documents stay consistent across evidence and bridge consumers What: - add a reusable statement-document collection seam and route the existing balance-reference extraction through that shared collection result - add the bounded EvidenceSet builder for retail members plus selected statement observations, including contract-local observation keys and blocking gap refs - add focused builder coverage while preserving the existing PDF extraction tests as the regression path for the refactored statement workflow Checks: - make pytest ARGS='tests/unit/application/checkpoints/test_pdf_extract_service.py tests/unit/application/evidence/test_evidence_set_builder.py -q --no-cov' - make mypy ARGS='src/tallylot/application/evidence/statement_extraction/collection.py src/tallylot/application/evidence/statement_extraction/__init__.py src/tallylot/application/evidence/statement_extraction/models.py src/tallylot/application/evidence/statement_extraction/service.py src/tallylot/application/evidence/statement_extraction/source_evidence.py src/tallylot/application/evidence/evidence_sets/__init__.py src/tallylot/application/evidence/evidence_sets/builder.py tests/unit/application/evidence/test_evidence_set_builder.py' - make pylint ARGS='src/tallylot/application/evidence/statement_extraction/collection.py src/tallylot/application/evidence/statement_extraction/models.py src/tallylot/application/evidence/statement_extraction/service.py src/tallylot/application/evidence/statement_extraction/source_evidence.py src/tallylot/application/evidence/evidence_sets/builder.py tests/unit/application/evidence/test_evidence_set_builder.py'
Why: - normalization still wrote the legacy translation plan straight from planner output instead of from the new EvidenceSet authority path, which left the branch short of the intended evidence-authority cutover - the compatibility view also needed exact same-run decision detail for legacy ordering, relations, and candidate-specific blocked reasons without turning the planner back into persisted authority What: - add product-path helpers plus the compatibility reconstruction layer, and wire normalization to persist EvidenceSets, product-local compatibility plans, and workspace-relative evidence set refs - route normalization and runtime composition through the EvidenceSet repository and shared statement-collection result while keeping legacy planner artifacts and blocked-run behavior intact - extend unit coverage for exact compatibility reconstruction, successful product outputs, blocked-run retained artifacts, and empty evidence-set fields on non-planner flows Checks: - make pytest ARGS='tests/unit/application/evidence/test_evidence_set_builder.py tests/unit/application/compatibility/test_translation_inputs.py tests/unit/application/normalization/test_evidence_set_integration.py tests/unit/application/normalization/translation_inputs/test_normalization_integration.py -q --no-cov' - make mypy ARGS='src/tallylot/application/evidence/evidence_sets/builder.py src/tallylot/application/compatibility/translation_inputs.py src/tallylot/application/normalization/translation.py tests/unit/application/evidence/test_evidence_set_builder.py tests/unit/application/compatibility/test_translation_inputs.py tests/unit/application/normalization/test_evidence_set_integration.py tests/unit/application/normalization/translation_inputs/test_normalization_integration.py' - make pylint ARGS='src/tallylot/application/evidence/evidence_sets/builder.py src/tallylot/application/compatibility/translation_inputs.py src/tallylot/application/normalization/translation.py tests/unit/application/evidence/test_evidence_set_builder.py tests/unit/application/compatibility/test_translation_inputs.py tests/unit/application/normalization/test_evidence_set_integration.py tests/unit/application/normalization/translation_inputs/test_normalization_integration.py'
Why: - the runtime now emits evidence set ids, refs, and retained product artifacts, but the outward-facing tests still left those surfaces largely unpinned - without direct CLI, service, and adapter-pack expectations, the new evidence-authority path could drift while the branch still looked green What: - refresh adapter-pack normalization summary goldens to include evidence set fields and keep exact normalization-summary comparisons - extend normalization-service and CLI coverage to assert evidence set ids and refs on successful planner runs, empty fields on non-planner runs, and retained EvidenceSet artifacts on blocked Coinbase runs - keep the blocked legacy plan files and product-local compatibility outputs explicitly covered in the public-facing test surface Checks: - make pytest ARGS='tests/unit/application/normalization/test_normalization_service.py tests/e2e/test_cli.py tests/contract/test_source_adapter_packs.py -q --no-cov' - make mypy ARGS='tests/unit/application/normalization/test_normalization_service.py tests/e2e/test_cli.py tests/contract/test_source_adapter_packs.py'
Why: - the branch now lands a bounded EvidenceSet authority path, but the workspace and current-state docs still described only the legacy normalized-output sidecars - the evidence-authority handoff needs durable runtime docs that describe exactly where the authoritative kernel lives and what still remains compatibility-only What: - add the working/products reference page and link it from the workspace docs - document the split between retained normalized-output compatibility files and the authoritative EvidenceSet product root - update current-state notes to record the bounded EvidenceSet authority scope, empty evidence-set fields on non-planner runs, and retained blocked-run artifacts Checks: - make docs-sync - make docs-check - make naming-check - make docs-audit
Why: - PR hardening surfaced contract drift in EvidenceSet manifest identity, lost statement-extraction row diagnostics after the collection refactor, and stale bounded-slice wording that still leaked older slice shorthand into forward docs - the same review pass also showed adapter-pack expectations were pinned to the old incorrect EvidenceSet ids What: - source EvidenceSet manifest fingerprints from capture metadata and keep multi-member retail selections on the coverage basis - preserve row-level statement extraction issues and reviews through the shared collection path and strengthen regression coverage for manifest provenance, coverage basis, row-level diagnostics, and adapter-pack identity outputs - refresh the affected Coinbase normalization summary goldens and clean the remaining old slice wording in the pipeline-stage contract doc Checks: - make pr-review-full
Why: - archive-member statement documents could share selection identity and issue routing, which let one document incorrectly inherit another document's selection or blocking state - Coinbase runs with no in-scope evidence members were still emitting empty EvidenceSet kernels, which drifted from the bounded evidence contract and current-state intent - the EvidenceSet builder had grown into a review hotspot, and repo guidance expects a split well before the hard 500-line guard What: - track statement documents by full archive-aware identity during collection and issue matching, and emit per-document missing-date blockers - skip empty EvidenceSet emission for missing-retail runs and update the affected normalization golden - split statement record assembly into a dedicated evidence-sets module and add regression coverage for archive-member and missing-input cases Checks: - make pr-review
Why: - planning-surface-only diffs could skip docs-audit even though current rules still read that control-plane contract set - malformed EvidenceSet files could fail with raw attribute errors instead of explicit repository validation What: - treat the planning-only contract index as a docs-audit substrate and keep planning-surface verification plans on docs-audit - validate the top-level evidence-set payload shape before reading schema fields and pin the behavior with focused tests Checks: - make pytest ARGS='-q tests/unit/test_docs_audit.py tests/unit/test_audit_pr_review.py tests/unit/test_run_pr_review_checks.py tests/unit/infrastructure/storage/test_evidence_set_repository.py'
c-wri
marked this pull request as ready for review
April 20, 2026 02:42
c-wri
enabled auto-merge
April 20, 2026 02:43
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why:
EvidenceSetneeds to become the authoritative surface for in-scope evidence selection while keeping current translation-plan readers stable.What:
EvidenceSetkernels plus product-localtranslation_input_plan.jsoncompatibility views during planner-enabled Coinbase normalizationevidence_set_idandevidence_set_refChecks:
make audit-pr-reviewmake pr-reviewmake pr-review-fullIssue linkage:
Included checkpoints:
docs(migration): shift contract authority to owner docsfeat(evidence): add evidence set kernelfeat(evidence): collect statement documents oncefeat(compatibility): derive plan from evidence setstest(normalization): pin evidence set public outputsdocs(runtime): record evidence set authorityfix(review): harden evidence-set authority semanticsfix(evidence): harden statement evidence selectionfix(pr-review): restore planning-surface audits and payload guards