Wire the declared capital-gain-distributions memo stage into the PUF base build

CONTRACT_FINDINGS.md

@@ -0,0 +1,99 @@
+# Contract findings: populace#462 fix 3
+
+## Original stop state (subsequently adjudicated)
+
+Implementation stopped at the task's explicit contract-safety condition. The
+declared `capital_gain_distributions` stage and its registered executor cannot
+produce the requested conserved split or reduce the verified $30.27B
+`non_sch_d_capital_gains` total into the $10–14B direct-route class.
+
+The user has since adjudicated these findings as correct and withdrawn the
+conservation requirement. The executor's existing memo-component behavior is
+now the authoritative contract for scope 3a.
+
+## Contract findings
+
+- The manifest declares a tax-unit stage that reads the `tax_unit` table, then
+  uses `long_term_capital_gains_before_response` as its source, writes
+  `schedule_d_capital_gain_distributions`, and treats
+  `non_sch_d_capital_gains` only as an eligibility exclusion
+  (`packages/populace-build/src/populace/build/us/source_stages.json:742-764`).
+- The packaged share is `0.09852561497474391`. It is specifically the TY2015
+  Schedule-D CGD residual divided by long-term net gains excluding the direct
+  route; it is not a share for repartitioning the existing $30.27B CGD total
+  (`packages/populace-build/src/populace/build/us/soca_capital_gain_distribution_shares.json:16-22`).
+- The executor computes, for source `L`, direct-route value `D`, and declared
+  share `q`:
+
+  ```text
+  eligible = L > 0 and D <= 0
+  schedule_d = L * q if eligible else 0
+  direct_after = D
+  ```
+
+  It copies the frame, adds only the output, and never subtracts from or
+  otherwise changes `non_sch_d_capital_gains`
+  (`packages/populace-build/src/populace/build/us_runtime/capital_gain_distributions.py:203-214`).
+- Consequently, whenever the stage emits a positive Schedule-D value,
+  `non_sch_d_after + schedule_d` is greater than the pre-stage
+  `non_sch_d_capital_gains` value. The requested per-tax-unit conservation
+  assertion cannot hold. The existing unit test also explicitly pins the
+  current memo-component behavior and an untouched source
+  (`packages/populace-build/tests/test_us_capital_gain_distributions.py:81-120`).
+- Wiring the executor leaves the verified $30.27B direct-route total at
+  $30.27B. Even if the declared 9.8526% share were incorrectly applied to that
+  total with subtraction, it would produce about $2.98B Schedule-D and
+  $27.29B direct-route amounts, still outside the required $10–14B direct-route
+  class.
+- The executor already fails loudly when its output exists, so a second run is
+  rejected as requested
+  (`packages/populace-build/src/populace/build/us_runtime/capital_gain_distributions.py:191-195`).
+  It provides no separate signal or conservation gate; inventing one would not
+  repair the incompatible transform.
+
+## Builder findings
+
+- `tools/build_us_asec_pooled_source_base.py` only constructs the pooled ASEC
+  source and cannot run this PUF-dependent stage.
+- In `tools/build_us_puf_support_base.py`, the earliest logical insertion point
+  would be immediately after `qrf_finalization` and before
+  `qbi_reconciliation` (`:134-156`, `:981-1004`, and `:1840-1868`). Adding an
+  outer stage there would make checkpointed builds record it automatically in
+  `stage_run_context.json` under `pipeline`, `completed`, and `stage_records`
+  (`packages/populace-build/src/populace/build/outer_stage_runtime.py:437-575`).
+- There is an additional grain seam: both input columns produced by the PUF
+  QRF are person-grain outputs
+  (`packages/populace-build/src/populace/build/us_runtime/puf_support.py:94-105`),
+  while the manifest reads a tax-unit table. No existing wrapper declares how
+  to aggregate the inputs and place the output, and no later builder transform
+  performs the missing subtraction.
+
+## Why no implementation was made
+
+The task says the executor and declaration are the contract, prohibits
+improvising parameters or changing the declaration's share source, and directs
+the run to stop with `BLOCKED.md` if those parameters cannot produce the
+SOI-consistent split. Altering the executor to subtract a route, changing its
+source column, or inventing a different share would violate those constraints;
+wiring it unchanged would knowingly violate the required conservation and
+direct-route acceptance tests.
+
+No production, test, or generated manifest files were changed. The requested
+test commands were not run because the mandated stop condition was reached
+before an implementable change existed.
+
+## Original questions resolved by adjudication
+
+The source-stage contract needs an approved clarification or revision that
+defines:
+
+1. whether the split source is the existing all-route CGD amount or long-term
+   gains used to create a separate memo component;
+2. which route column is reduced so conservation holds, including the
+   person-to-tax-unit aggregation and output-placement rule; and
+3. the approved, provenance-backed parameter for dividing the $30.27B total if
+   that total is the intended source.
+
+The adjudication resolves these questions for scope 3a by directing the stage
+to be wired unchanged at the identified post-QRF insertion point, using the
+existing executor semantics and neighboring outer-stage grain handling.

PROGRESS.md

@@ -0,0 +1,61 @@
+# Progress
+
+## State
+
+Scope 3a is complete. The declared `capital_gain_distributions` executor now
+runs in both PUF support base paths after `qrf_finalization` and before
+`qbi_reconciliation`; focused end-to-end stage-record, semantic, rerun, and
+release-coverage tests are green. The branch is fully committed and remains
+unpushed.
+
+## Done
+
+- Confirmed the worktree is on `cgd-split-462` and starts clean.
+- Read the complete stage declaration, share resource, executor, runtime, base
+  builders, outer-stage manifest recorder, and relevant tests.
+- Confirmed the declared 9.8526% parameter is a Schedule-D share of eligible
+  long-term gains, not a partition share for the existing CGD total.
+- Confirmed the executor adds only the Schedule-D output, leaves the direct
+  route untouched, and fails loudly when the output already exists.
+- Located the otherwise-correct builder insertion point after PUF QRF
+  finalization and before QBI reconciliation, and confirmed how an outer stage
+  would be recorded in `stage_run_context.json`.
+- Documented the blocking semantic, magnitude, conservation, and grain
+  conflicts in `CONTRACT_FINDINGS.md` without changing implementation or tests.
+- Recorded the user's adjudication: the conservation requirement is withdrawn,
+  the existing executor behavior is authoritative, and QRF machinery is out of
+  scope.
+- Retitled the resolved adjudication record from `BLOCKED.md` to
+  `CONTRACT_FINDINGS.md` while retaining its analysis.
+- Traced the existing entity-grain convention: use `Frame.place` to sum PUF
+  person inputs to tax units, then first-person carry the memo output because
+  PolicyEngine re-aggregates that person input to the filing unit.
+- Added `capital_gain_distributions` to the outer pipeline and monolithic base
+  path at the adjudicated insertion point, calling the unchanged manifest
+  executor through `run_source_stage`.
+- Preserved both original PUF inputs and surfaced any pre-existing output to
+  the executor so its existing overwrite refusal remains the rerun contract.
+- Extended the existing capital-gain fixture through the actual named outer
+  stage: tax-unit memo semantics, unchanged PUF inputs, first-person output
+  placement, automatic pipeline/completed/stage-record entries, and the
+  executor-owned rerun failure are pinned end to end.
+- Updated the locked pipeline/base-order tests; the focused builder and
+  executor suites pass (58 tests), and Ruff is clean for the touched files.
+- Confirmed the release input-coverage generator is already byte-identical:
+  both capital-gain route legs are required independently of builder stage
+  presence, and its focused six-test sync/route guarantee suite passes. No
+  generated manifest rewrite is needed.
+- Ran the full suite through 100%. It reported the two declared pre-existing
+  release-parity `TestRegeneration` failures and two unrelated UK reference
+  regeneration failures caused by licensed artifacts being present in the
+  user cache while this worktree's virtual environment lacks
+  `policyengine_uk`; no failure traces to the scope-3a changes.
+- Confirmed the third declared pre-existing failure, educator `FakeQRF`, is
+  skipped in this environment because the `policyengine_us` optional
+  dependency is absent. This branch still predates its main-branch fix, so the
+  skip does not imply that the known issue disappeared.
+
+## Next
+
+- No scope-3a implementation work remains. Keep the committed branch unpushed
+  for review/integration.