refactor(processor): move pre-gain calculation before Pass 3

[flexiondotorg]

Summary

Move ceiling and pre-gain calculation before Pass 3 so loudnorm measures the post-limiter signal directly, closing the 1.3 LU LUFS measurement gap.

Changes

• Extract calculatePreGain() and buildPreLimiterPrefix() for reuse
• Simplify buildLoudnormFilterSpec() to accept pre-computed ceiling/pre-gain values
• Reorder ApplyNormalisation() to compute ceiling before Pass 3 measurement
• Thread pre-computed values through applyLoudnormAndMeasure()
• Add Pass3FilterPrefix field to NormalisationResult for diagnostics
• Update AGENTS.md to document optional volume+alimiter prefix
• Update LUFS-GAP-SUMMARY.md with resolution notes

Testing

• All existing unit tests pass
• New tests for calculatePreGain() and buildPreLimiterPrefix()
• Lint and build verification clean

Technical Details

Pass 2 produces ebur128 measurements (OutputI, OutputTP). Previously, Pass 3 measured the raw signal and Pass 4 applied pre-gain/limiting without reflecting those changes in Pass 3's measurements. This created a 1.3 LU gap because loudnorm used unadjusted InputI as measured_I while the actual audio entering loudnorm had been modified.

Now: compute ceiling/pre-gain from Pass 2's ebur128 before Pass 3. Pass 3 measures through the same volume+alimiter prefix that Pass 4 applies, so its measurement.InputI reflects the post-limiter signal. loudnorm receives the correct measured values, eliminating the adjustment arithmetic.

[cubic-dev-ai]

1 issue found across 4 files

Confidence score: 4/5

• This PR looks safe to merge with minimal risk: the reported issue is in a test assertion rather than production logic, so runtime behavior is unlikely to break directly.
• The most significant concern is in internal/processor/normalise_test.go: the assertion still checks Pass 2 values even though buildLoudnormFilterSpec now expects Pass 3 post-limiter measurements, which can mask regressions in limiting edge cases.
• Given the moderate severity (5/10) and high confidence (9/10), this is worth fixing soon to restore accurate coverage, but it is not strongly merge-blocking by itself.
• Pay close attention to internal/processor/normalise_test.go - assertion is validating outdated pass metrics and may miss real behavior changes.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="internal/processor/normalise_test.go">

<violation number="1" location="internal/processor/normalise_test.go:444">
P2: This assertion checks the old Pass 2 values, but `buildLoudnormFilterSpec` now expects Pass 3's post-limiter measurements. In limiting cases that makes the test validate the wrong behavior and weakens coverage for the regression this PR is fixing.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}