feat(normalization): add deterministic fast-path reruns - #88
Merged
Conversation
Why: - the downstream fast-path work needs an explicit proof that the implemented authoritative builders already replay deterministically before orchestration starts reusing persisted kernels - without these checks, later planner behavior could mask builder-level ordering drift and make rerun guarantees harder to trust What: - add replay and order-insensitivity tests for economic facts, reconciliation states, and checkpoint builders - assert stable ids, payloads, fingerprints, and canonical record ordering across unchanged and reordered inputs Checks: - make pytest ARGS='tests/unit/application/economics/test_builder.py tests/unit/application/reconciliation/test_builder.py tests/unit/application/checkpoint/test_builder.py tests/unit/domain/economics/test_models.py tests/unit/domain/reconciliation/test_models.py tests/unit/domain/checkpoint/test_models.py -q' - parity note: builder coverage is stronger now; the existing builder behavior remains covered in the same test modules with added replay and ordering assertions
Why: - normalization needed a clear application-owned seam for target-product execution before selective rerun behavior can land safely - explicit operator update modes and planning models need stable contracts before the runtime starts reusing persisted target products What: - replace the flat downstream_products module with a target_products package for service, planning, signatures, models, and cleanup helpers - add NormalizeUpdateMode to normalization contracts and source normalize CLI plumbing, plus planning and fingerprint tests for the new execution seam Checks: - make pytest ARGS='tests/unit/interfaces/test_cli_surface.py tests/unit/application/normalization/test_target_product_execution.py tests/unit/application/normalization/translation_inputs/test_normalization_integration.py tests/unit/application/normalization/translation_inputs/test_planner.py -q' - parity note: target-product integration coverage moved from test_downstream_target_integration.py to test_target_product_integration.py without weakening assertions; new planner and CLI checks strengthen the seam coverage
Why: - normalization still rebuilt authoritative downstream products on every planner-enabled rerun and left stale owned outputs behind - operators lacked explicit update controls for bounded reruns versus sidecar refreshes versus full rebuilds - the new target-product execution seam needed runtime proof, pruning, and deterministic replay coverage before the contract could be documented What: - wire normalization through the target-product execution service with auto, full-update, and rebuild modes plus execution summary payloads - add deterministic reuse, selective rebuild, stale-root pruning, and owned-output cleanup for economic facts, reconciliation states, and checkpoints - extend normalization, integration, compatibility, replay, and adapter-pack tests to lock the fast-path behavior and emitted summaries Checks: - tools.run_quality_gates - make pytest ARGS='tests/unit/application/normalization/test_target_product_execution.py tests/unit/application/normalization/test_normalization_service.py tests/unit/application/normalization/test_target_product_integration.py tests/unit/application/compatibility/test_economic_facts_projection.py tests/unit/application/normalization/test_source_assembly.py tests/unit/application/balances/test_check.py tests/unit/application/checkpoints/balance_submission/test_submit.py tests/unit/application/intake/test_apply_workflow.py -q' - make pytest ARGS='tests/e2e/test_validate_workspace_replay.py -q' - make pytest ARGS='tests/contract/test_source_adapter_packs.py tests/contract/test_pylint_contracts.py -q'
Why: - durable owner docs and repo-native validators still drifted from the automatic fast-path rerun contract now enforced by normalization - several forward docs still referenced retired accounting-boundary terms or planning-coupled phrasing on durable surfaces - docs-audit and target-naming needed to fail closed if replay routing, fast-path guarantees, or accounting vocabulary regressed What: - update durable architecture, contract, status, and operator docs to describe automatic recalculation, bounded fast-path reuse, explicit full-update and rebuild behavior, and developer-only replay proof tooling - retire remaining planning-doc owner references on durable surfaces and replace retired accounting-boundary aliases with accounting-owned terminology - extend docs-audit and target-naming enforcement plus synthetic tests so forbidden planning phrases, replay drift, and retired accounting aliases are rejected Checks: - make pytest ARGS='tests/unit/test_docs_audit.py tests/unit/test_target_naming.py -q' - make docs-check - make naming-check - make docs-audit
Why: - control-plane routes and repo guidance still lagged behind the new automatic rerun contract and accounting-boundary vocabulary - source-intake execution surfaces still needed explicit update-mode guidance and clearer developer-only replay positioning - the completed accounting-boundary planning slice and unreleased changelog entry needed to reflect the finished runtime and docs work What: - align AGENTS, README, skills, and command routes around durable owner docs, explicit source normalize update-mode guidance, and developer-only replay validation - clarify that planning docs beyond the main planning document may use ephemeral planning language when the surface itself is a planning document while durable metadata stays phase-free - retire the completed accounting-boundary planning slice into the finished pattern and add unreleased changelog entries for accounting-boundary alignment, deterministic fast-path reruns, operator controls, and validator enforcement Checks: - make pytest ARGS='tests/unit/test_repo_agent_skills.py tests/contract/test_standards_guards.py -q' - make docs-check - make naming-check - make docs-audit
Why: - auto reruns reused stage-owned detail files whenever they existed, even when the persisted execution metadata no longer matched the current compatibility signatures - target-product prune helpers lived outside the package boundary that claims cleanup ownership, which made the execution surface harder to review and reason about What: - refresh economic-facts compatibility rows, reconciliation snapshots, and checkpoint references when their current expected signatures drift from the last persisted execution summary - move target-product prune helpers into the cleanup module and keep the service importing them from the owned cleanup boundary - add a normalization-service regression test that proves auto reruns refresh drifted detail outputs while keeping authoritative refs stable Checks: - make pytest ARGS='tests/unit/application/normalization/test_normalization_service.py tests/unit/application/normalization/test_target_product_execution.py tests/unit/application/normalization/test_target_product_integration.py -q'
Why: - reruns that stopped emitting downstream target products left stale reconciliation and checkpoint roots behind without any execution metadata, which hid cleanup on the operator path - the update-mode CLI path was only covered indirectly, and some durable Phase 5A owner docs sat outside the new rerun-policy audit coverage - the broader docs audit still allowed an ephemeral work-track label on a durable status page What: - prune stale downstream roots and emit empty target-product execution metadata when a rerun no longer emits downstream products - add end-to-end CLI coverage for `auto`, `full-update`, and `rebuild`, and extend the docs-audit coverage to the touched owner docs plus operator quickstart fast-path wording - rename the adapter delivery plan's deferred work track to durable phase-free wording and tighten the docs-audit tests around the new rule coverage Checks: - make pytest ARGS='tests/unit/application/normalization/test_normalization_service.py tests/unit/application/normalization/test_target_product_execution.py tests/unit/application/normalization/test_target_product_integration.py tests/e2e/test_cli.py -q -k "update_modes_drive_target_product_execution or normalization" tests/contract/test_source_adapter_packs.py -q -k normalization_outputs_match_expected_goldens' - make pytest ARGS='tests/unit/test_docs_audit.py tests/unit/test_target_naming.py tests/unit/test_repo_agent_skills.py -q' - make docs-check - make naming-check - make docs-audit - make pr-review-full
Why: - the fast-path rerun path still refreshed checkpoint detail after an unchanged second run because refresh and reuse stored different signature formats - reused fact annotations silently dropped adapter metadata, and incompatible prior execution metadata was still accepted instead of failing closed What: - preserve annotation adapter metadata when reloading compatibility sidecars - store stable hashed target-product detail signatures across rebuild and reuse paths - ignore prior execution metadata when the signature version no longer matches and refresh the affected adapter-pack summary goldens - add regression coverage for the rerun package, normalization service, and CLI path Checks: - make pyright ARGS='src/tallylot/application/normalization/target_products/payloads.py' - make pytest ARGS='tests/unit/application/normalization/test_target_product_execution.py -q' - make pytest ARGS='tests/unit/application/normalization/test_normalization_service.py -q' - make pytest ARGS='tests/e2e/test_cli.py -k update_modes_drive_target_product_execution -q' - make pytest ARGS='tests/contract/test_source_adapter_packs.py -q'
Why: - the docs-audit phase-language guard still treated forward-looking owner docs as durable non-planning surfaces, which conflicted with the guidance you asked to make explicit - the workflow skills and implementation standard were still uneven about whether only one named planning document could carry planning language What: - narrow the docs-audit phase-language ban to current runtime and delivery-facing docs instead of forward-looking owner docs - update the implementation standard and workflow skills to say that forward-looking planning language is allowed on more than one planning surface - refresh the synthetic docs-audit expectations to match the repaired policy boundary Checks: - make pytest ARGS='tests/unit/test_docs_audit.py tests/unit/test_repo_agent_skills.py -q' - make docs-check - make docs-audit
Why: - the normalization test surface still carried the retired downstream-products label after the package and runtime boundary moved to target products What: - rename the remaining normalization tests to use target-product terminology Checks: - make pytest ARGS='tests/unit/application/normalization/test_normalization_service.py tests/unit/application/normalization/test_target_product_integration.py -q'
Why: - rerun execution still rebuilt every reconciliation state and checkpoint partition when an upstream sibling changed, which undercut the fast-path contract and left stale economic-facts roots behind on retargeted runs What: - reuse unchanged reconciliation-state and checkpoint partitions by comparing current fingerprints and detail signatures per emitted product instead of forcing stage-wide rebuilds - prune stale economic-facts roots when target execution retargets or disappears and add regression coverage for the mixed reuse/rebuild path plus cleanup behavior Checks: - make pytest ARGS='tests/unit/application/normalization/test_target_product_execution.py tests/unit/application/normalization/test_target_product_runtime.py tests/unit/application/normalization/test_normalization_service.py tests/unit/application/normalization/test_target_product_integration.py -q' - make pyright ARGS='tests/unit/application/normalization/test_target_product_runtime.py' - make pytest ARGS='tests/e2e/test_cli.py::test_source_normalize_cli_update_modes_drive_target_product_execution -q' - make pytest ARGS='tests/e2e/test_validate_workspace_replay.py -q'
Why: - control-plane standards still treated one planning document as the only allowed home for ephemeral planning language, which conflicted with the broader forward-looking planning-surface policy and invited drift What: - update delivery and engineering standards to allow ephemeral planning language on forward-looking planning surfaces beyond the main planning document while keeping durable metadata free of planning labels - tighten docs-audit policy alignment checks so those standards continue to enforce the clarified contract Checks: - make pytest ARGS=tests/unit/test_docs_audit.py\ -q - make docs-check - make naming-check - make docs-audit
Why: - malformed target-product summary files could crash reruns or drive unsafe product pruning instead of failing closed - first-run captures without target products now emit the stable execution summary shape, so the golden fixtures must match the runtime contract What: - ignore invalid prior target-product summary payloads and refuse to prune refs outside the workspace product tree - always write an empty target-product execution payload when normalization emits no target products, and add regression coverage for the new fail-closed paths - refresh normalize-capable adapter pack summary goldens to include the stable empty execution payload shape Checks: - make pytest ARGS='tests/unit/application/normalization/test_target_product_execution.py tests/unit/application/normalization/test_normalization_service.py -q' - make pytest ARGS='tests/contract/test_source_adapter_packs.py -q' - make pr-review
Why: - the repo standards already allow forward-looking docs beyond one single planning file to carry ephemeral planning language, but AGENTS and the planning skill still phrased that rule more narrowly - that wording drift risks sending later review and implementation work back into the same policy confusion this branch is trying to retire What: - align AGENTS and the planning skill with the repo-wide wording that forward-looking docs may carry planning language when they include future-oriented implementation detail - pin the planning-skill wording in the existing repo-local skill test Checks: - make pytest ARGS='tests/unit/test_repo_agent_skills.py -q' - make pr-review
Why: - auto-mode reruns could still fail on malformed stage-owned detail files even when the authoritative kernels were intact and reusable - the repair also pushed the target-product runtime module past the repo line cap, which would have left the branch structurally out of bounds What: - refresh corrupted economic-facts, reconciliation-state, and checkpoint detail sidecars from authoritative kernels when reused detail reads fail - split detail-refresh helpers into a bounded sibling module so target-product runtime stays under the repo line cap - add an end-to-end normalization regression that corrupts stage-owned detail files before rerun Checks: - make pytest ARGS='tests/unit/application/normalization/test_target_product_runtime.py tests/unit/application/normalization/test_normalization_service.py tests/contract/test_pylint_contracts.py -q' - make pr-review
Why: - automatic reruns could reuse stale reconciliation kernels when the evidence set changed but the claim-set lineage stayed the same - unreadable target-product kernels could block or misreport recovery instead of rebuilding from current authoritative truth - the target-product runtime hotspot had grown past the repo's structural guidance, which made the reuse policy harder to audit What: - reload prior evidence-set identity from normalization summary before reusing reconciliation kernels - rebuild unreadable economic facts, reconciliation state, and checkpoint kernels while preserving deterministic refs on unchanged inputs - extract kernel reuse and readability helpers into a dedicated target-products module and add regression coverage for evidence-change invalidation and corrupted-kernel recovery Checks: - make pytest ARGS='tests/unit/application/normalization/test_target_product_runtime.py tests/unit/application/normalization/test_normalization_service.py tests/unit/application/normalization/test_target_product_integration.py tests/e2e/test_cli.py -q' - make pytest ARGS='tests/unit/application/economics/test_builder.py tests/unit/application/reconciliation/test_builder.py tests/unit/application/checkpoint/test_builder.py tests/unit/application/compatibility/test_economic_facts_projection.py -q' - make pytest ARGS='tests/e2e/test_validate_workspace_replay.py -q' - make pytest ARGS='tests/unit/application/normalization/test_target_product_execution.py tests/unit/interfaces/test_cli_surface.py tests/unit/application/normalization/translation_inputs/test_normalization_integration.py tests/unit/application/normalization/translation_inputs/test_planner.py -q' - make pytest ARGS='tests/contract/test_pylint_contracts.py -q' - make pyright ARGS='src/tallylot/application/normalization/target_products/runtime.py src/tallylot/application/normalization/target_products/service.py src/tallylot/application/normalization/target_products/kernel_reuse.py' - make pylint ARGS='src/tallylot/application/normalization/target_products/runtime.py src/tallylot/application/normalization/target_products/service.py src/tallylot/application/normalization/target_products/kernel_reuse.py' - make coverage-hotspots
Why: - readable target-product kernels could drift semantically while staying parseable, which let reruns trust stale persisted truth instead of rebuilding from authoritative upstream inputs - the economic-facts resolver had also grown past the repo complexity and line-cap guardrails while this hardening work landed What: - validate persisted economic-facts, reconciliation-state, and checkpoint kernels against their recorded fingerprints before allowing reuse - rebuild and rewrite any kernel whose readable payload no longer matches the prior execution summary, then keep the economic-facts kernel selection logic in the reuse helper module - add runtime and normalization-service regressions for readable semantic drift, not just unreadable corruption Checks: - make pytest ARGS='tests/contract/test_pylint_contracts.py tests/unit/application/normalization/test_target_product_runtime.py tests/unit/application/normalization/test_normalization_service.py -q' - make pr-review
Why: - the target-product planner treated any upstream rebuild as a downstream rebuild trigger, which drifted from the live fast-path behavior after kernel-repair hardening - that mismatch weakened the planner contract and made repair-only rewrites look like semantic changes in tests and future planning work What: - teach planner candidates to distinguish reusable kernels from readable-but-invalid kernels - propagate upstream semantic changes instead of generic upstream rebuilds when planning downstream stage actions - add planner regressions for invalid readable kernels and for repair-only kernel rewrites that should still reuse unchanged downstream products Checks: - make pytest ARGS='tests/unit/application/normalization/test_target_product_execution.py tests/unit/application/normalization/test_target_product_runtime.py tests/unit/application/normalization/test_normalization_service.py tests/e2e/test_cli.py -k "target_product_execution or target_product_runtime or normalization_service or source_normalize_cli_update_modes_drive_target_product_execution" -q' - make pr-review
Why: - the agent-facing source-intake route exposed less of the real runtime and oracle workflow than the operator docs, which left gaps in assemble, balance, render, and screen-stage follow-through - the control-plane parity checks did not enforce that split ownership, so route drift could recur without the docs-audit layer catching it What: - expand the source-intake skill and command route to cover runtime follow-through and explicit handoff into round-verification for oracle work - widen the round-verification skill and command route to own `batch screen`, `batch stage`, `source diff`, `round scaffold`, and `verification compare` - add docs-audit and repo-skill tests that lock the split route contract and the required command surface Checks: - make pytest ARGS='tests/unit/test_repo_agent_skills.py tests/unit/test_docs_audit.py tests/contract/test_standards_guards.py -q' - make mypy ARGS='tests/unit/test_docs_audit.py tests/unit/test_repo_agent_skills.py repo_support/docs_audit/rules/runtime.py' - make pyright ARGS='tests/unit/test_docs_audit.py tests/unit/test_repo_agent_skills.py repo_support/docs_audit/rules/runtime.py' - make docs-audit - make pr-review
c-wri
marked this pull request as ready for review
April 22, 2026 18:03
c-wri
enabled auto-merge
April 22, 2026 18:03
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:
What:
Checks:
Issue linkage:
Included checkpoints:
test(reruns): lock deterministic target buildersrefactor(normalization): name target product execution seamsfeat(normalization): implement automatic fast-path rerunsdocs(contracts): lock rerun and accounting guaranteesdocs(control-plane): align rerun routes and retire slicefix(normalization): refresh drifted detail outputsfix(reruns): harden cleanup and owner-doc checkstest(reruns): harden target-product reuse proofsdocs(control-plane): align forward-doc planning policytest(naming): align target-product test labelsfix(normalization): reuse unchanged target partitionsdocs(standards): align planning-surface policyfix(normalization): harden target product summary reusedocs(control-plane): clarify planning language scopefix(normalization): refresh corrupted target detailsfix(normalization): harden target product rerun recoveryfix(normalization): rebuild drifted target kernelsfix(normalization): align planner repair semanticsfix(control-plane): align intake and oracle agent routes