The Trilogy Times

## Summary

New daily pipeline that ingests per-user-per-day spend and token usage from the Claude Enterprise Analytics API (user_cost_report + user_usage_report, grouped by product) into core_finance.ai_spend_claude_ai_chat_usage. Finalizes Spec 3 Part A.

- Per-day loop with 1-day windows (the per-user endpoints don't time-bucket / reject bucket_width).

- Cost stored verbatim from the API (amount/list_amount ÷100) — discount is not recomputed. Verified against live data: effective discount is exactly 10%/row, and per-user sums reconcile to the org cost_report total.

- 7-day trailing re-pull + is_provisional flag (API has ~3-day lag, reconciles ~30 days).

- BU left NULL on ingest, attributed downstream via email→dim_user.

## Verification

- ruff check clean, 16 unit tests pass.

- Shapes/units/grain confirmed against org org_0193Pqkb… (2026-05-12→18) — see spec A.7.

## Deploy checklist (do in order)

- [ ] Create the Redshift table — run scripts/sql/create_ai_spend_claude_ai_chat_usage.sql against finance_dw / core_finance before deploy (and GRANT SELECT to the consuming role/MCP_user if it'll be queried).

- [ ] Create the secret surtr/claude-ai-analytics-key (JSON {"api_key":"..."}, scope read:analytics, minted at claude.ai/analytics/api-keys by a Primary Owner).

- [ ] Confirm src/requirements.txt present (bundling rule) — ✅ included.

- [ ] CI green (ruff + pytest).

- [ ] Deploy: promote main → production (CD only deploys on the production branch).

- [ ] Post-deploy smoke test: single-day sync invoke, verify rows land + per-user sum matches org cost_report.

- [ ] Then rely on the daily cron(0 6 * * ? *) schedule.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

## Summary

The savings layer over the TF-gateway + claude.ai data — both Max20x and negotiated-discount savings, as Redshift reference tables + views. Consumed via the Klair query_max20x_savings MCP tool (separate PR).

Roster-free — Max access is read from gateway routing (claude-max-group/claude-pro-group), so realized + potential savings come from the data and auto-track who has/loses 20x. Only "seat held, zero usage" is invisible.

### New tables (manual seeds)

- ai_spend_subject_identity — supplementary slug→email override; unmapped users pass through "dumb"; seeded with leonardo only, add rows by hand.

- ai_spend_list_prices — public $/MTok per model/token_type (Anthropic published rates, effective-dated).

- ai_spend_discount_rules — discount % per provider/token_type (Anthropic 10% input+output, cache 0%).

### New views

- vw_ai_spend_claude_atomic, vw_ai_spend_max_migration_candidates, vw_ai_spend_max_savings, vw_ai_spend_negotiated_savings.

### Validated on prod data

leonardo merges to #1 ($12.7k); realized Max ~$8k/mo; claude.ai negotiated 9.99%; TF 0.98%.

### Deploy checklist

- [x] Tables + views applied to Redshift (Data API) — done in build session.

- [x] GRANT SELECT to MCP_user + ediechitac — done.

- [ ] Re-run artifacts/*.sql in other environments as needed (idempotent).

- [ ] Maintain ai_spend_list_prices / ai_spend_discount_rules when rates/rules change (row edits).

- [ ] Klair query_max20x_savings PR (#2848) merged + MCP redeployed.

⚠️ Redshift gotcha captured in the view: divide token counts by 1000000.0, not 1e6 (integer division).

## Summary

- Add a bulk Aerie read endpoint for per-operating-site P2 freshness

- Persist durable WUG/task activity timestamps on create/update/status changes

- Document the new /sync/aerie/listSiteFreshness contract

## Why

Aerie Accountability needs to classify operating sites as Current, Aging, Stale, or Never without N+1 detail calls. The freshness source must be Rhodes-owned P2 Quality Bar execution activity, not site metadata, notes, P1/buildout work, or request fetch time.

## Business Value

Aerie can now render an accurate portfolio freshness dashboard from one Rhodes read call, with freshness derived from durable operational activity timestamps.

## Test plan

- [x] CONVEX_DEPLOYMENT=dev:kindly-rook-978 npx convex codegen --typecheck disable

- [x] npx tsx --test convex/aerieHttpHelpers.test.ts convex/aerieProvisionPayload.test.ts convex/qualityBars.test.ts (55/55 passing)

- [x] git diff --check

- [ ] Full tsc currently has pre-existing unrelated failures in convex/rebl3DdReconciliation.ts and convex/scripts/backfillWrikeCurrentCapacity.ts

## Summary

- Source Operating Accountability freshness from Rhodes' listSiteFreshness endpoint

- Join freshness by Rhodes site id and remove the old chat-local status-update dependency

- Keep the dashboard export label aligned to P2 activity freshness

## Why

The Accountability view was showing every site as never updated because it was reading Aerie-local site status updates. For the Operating P2 team, "last update" should reflect durable activity under Rhodes Quality Bar work unit groups and tasks.

## Business Value

Operators can now see accurate site freshness in the Accountability view, with stale/aging/never buckets driven by the same Rhodes WUG/task activity the Operating team monitors.

## Test plan

- [x] pnpm --filter @bran/chat test lib/__tests__/rhodes-operating-server.test.ts app/api/operating-sites/__tests__/route.test.ts lib/__tests__/operating-sites.test.ts components/dashboards/school-ops/__tests__/school-ops-view.test.tsx

- [x] pnpm --filter @bran/chat typecheck

- [x] git diff --check

- [x] Browser spot check: Operating Accountability loads with All Sites 25, Never 0, and real last-update dates

- [x] Rhodes spot check: freshness endpoint returned 26 rows, with the extra row excluded by Aerie's existing test-site filter

### Summary

The EBITDA memo's AI narrative was instructed to "generate plausible" revenue/cost splits per BU and to invent vendor names for the Central Functions detail bullet, which produced numbers and driver names that didn't match the source data. This change extends fetch_bu_details with Recurring / Non-Recurring revenue and HC / NHC / CF cost sub-aggregations, adds a new fetch_central_vendor_variances query for vendor-level Central Functions cost variances, threads both through the prompt builder, deterministic narrative builders, and the provenance panel, and rewrites the prompt guidance so the LLM cites real components instead of fabricating them. Also clarifies an ambiguity in section_2_question where "X% margin" and "X% pt delta" were being confused with the unrelated section_1_question "75% − unadjusted" expectation miss.

### Business Value

The monthly EBITDA memo is a CFO-facing artifact — when the AI narrative invents vendor names ("Engine Yard", "Khoros") or splits that don't reconcile to Finance's source data, authors waste time rewriting the memo and lose trust in the tool. Grounding every cited dollar amount and driver name in Redshift makes the first-pass memo defensible and shortens the author's edit cycle.

### Changes

- [financial_data_service.py](vscode-webview://15qdonnjjcq9q3pcmufmg5fa0asnqc6qnceup60m8cm6igoedkcj/klair-api/services/financial_data_service.py): extend fetch_bu_details query and BUDetailsRow TypedDict with Actual/Budget Recurring & Non-Recurring revenue and HC / NHC / CF cost columns (bad-debt excluded to match the "Actual excl BD" margin definition)

- [financial_data_service.py](vscode-webview://15qdonnjjcq9q3pcmufmg5fa0asnqc6qnceup60m8cm6igoedkcj/klair-api/services/financial_data_service.py): add fetch_central_vendor_variances(period, threshold_usd, top_n) — QTD vendor-level Actual vs Budget cost across Central Functions BUs, filtered by |variance| >= threshold and sorted by absolute variance

- [ebitda_memo.py](vscode-webview://15qdonnjjcq9q3pcmufmg5fa0asnqc6qnceup60m8cm6igoedkcj/klair-api/services/docx_reports/memo_data/ebitda_memo.py): thread the new split fields through _bu_row_from_fetch, _null_bu_row, _total_row, and the margin-mix synthetic plug via new _BU_DETAIL_SPLIT_FIELDS / _BU_DETAIL_SPLIT_SOURCE_KEYS constants

- [ebitda_defaults.py](vscode-webview://15qdonnjjcq9q3pcmufmg5fa0asnqc6qnceup60m8cm6igoedkcj/klair-api/services/docx_reports/memo_data/ebitda_defaults.py): best-effort fetch_central_vendor_variances call in both _fetch_ebitda_data (upload path) and _fetch_ebitda_data_from_redshift (live path), with warning + empty-list fallback so a vendor-query failure doesn't block memo generation

- [ebitda_defaults.py](vscode-webview://15qdonnjjcq9q3pcmufmg5fa0asnqc6qnceup60m8cm6igoedkcj/klair-api/services/docx_reports/memo_data/ebitda_defaults.py): new _format_bu_split_lines helper emits a Revenue / Cost split block under each BU detail line in the LLM prompt; new CENTRAL FUNCTIONS VENDOR VARIANCES block lists top vendor variances with explicit "do not invent vendor names" guidance

- [ebitda_defaults.py](vscode-webview://15qdonnjjcq9q3pcmufmg5fa0asnqc6qnceup60m8cm6igoedkcj/klair-api/services/docx_reports/memo_data/ebitda_defaults.py): new _dominant_split_driver identifies the component (recurring revenue, non-recurring revenue, HC / NHC / CF cost) responsible for at least 60% of a BU's miss_v_budget with matching sign — used by _build_bu_variance_bullets to phrase the deterministic miss/beat sentence with the real driver instead of "revenue shortfall and overspend on costs"

- [ebitda_defaults.py](vscode-webview://15qdonnjjcq9q3pcmufmg5fa0asnqc6qnceup60m8cm6igoedkcj/klair-api/services/docx_reports/memo_data/ebitda_defaults.py): _build_central_variance_bullets now cites the top one or two vendor names with their real variance amounts when available; _build_investment_variance_bullets attributes net Investment variance to the dominant entity (XO / XO 3rd Party / TU / CloudFix) by per-entity miss_v_budget; _build_affiliates_variance_bullets includes the real Virtasant revenue / cost split when live data is present

- [ebitda_defaults.py](vscode-webview://15qdonnjjcq9q3pcmufmg5fa0asnqc6qnceup60m8cm6igoedkcj/klair-api/services/docx_reports/memo_data/ebitda_defaults.py): prompt guidance rewritten — replaces "generate plausible splits" with explicit NUMBER SOURCING RULES that forbid inventing splits or vendor names and require [TBD] when data is missing

- [ebitda_defaults.py](vscode-webview://15qdonnjjcq9q3pcmufmg5fa0asnqc6qnceup60m8cm6igoedkcj/klair-api/services/docx_reports/memo_data/ebitda_defaults.py): section_2_question Pattern clarified — "X% margin" is now the Core margin (from the bridge), "Y% pt delta" is the margin delta from target, both explicitly distinguished from the section_1_question 75%-vs-unadjusted "Expectation miss"

- [ebitda_defaults.py](vscode-webview://15qdonnjjcq9q3pcmufmg5fa0asnqc6qnceup60m8cm6igoedkcj/klair-api/services/docx_reports/memo_data/ebitda_defaults.py): provenance panel (_build_ebitda_provenance) now surfaces the per-BU split components and per-vendor Actual / Budget / Variance lines so the details panel matches what the LLM was given

- [test_ebitda_defaults.py](vscode-webview://15qdonnjjcq9q3pcmufmg5fa0asnqc6qnceup60m8cm6igoedkcj/klair-api/tests/test_ebitda_defaults.py): update fixture expectation to include the new central_vendor_variances: [] key on the live-path return shape

### Testing

- [ ] cd klair-api && pytest tests/test_ebitda_defaults.py — unit tests pass with updated fixture

- [ ] cd klair-api && uv run ruff format services/docx_reports/memo_data/ebitda_defaults.py services/docx_reports/memo_data/ebitda_memo.py services/financial_data_service.py tests/test_ebitda_defaults.py

- [ ] cd klair-api && uv run ruff check services/docx_reports/memo_data/ebitda_defaults.py services/docx_reports/memo_data/ebitda_memo.py services/financial_data_service.py tests/test_ebitda_defaults.py

- [ ] cd klair-api && uv run pyright services/docx_reports/memo_data/ebitda_defaults.py services/docx_reports/memo_data/ebitda_memo.py services/financial_data_service.py

- [ ] Generate an EBITDA memo for a recent live-data period and verify: per-BU bullets cite a real dominant driver (e.g. "non-recurring revenue miss of $1.5M") not generic phrasing; Central Functions detail bullet names actual vendors from the variance list; Investment bullet attributes net variance to the dominant entity; provenance panel shows the same split values that fed the prompt

- [ ] Generate an EBITDA memo for an upload-only period and verify the memo still renders with generic phrasing and [TBD] for vendor-level attribution (no crash when fetch_central_vendor_variances returns empty)

- [ ] Verify section 2 question now reads "Why did we hit X% margin? What contributed to the Y% pt delta?" and the narrative uses Core margin % vs target margin delta, not the section 1 "75% − unadjusted" figure

http://localhost:3001/monthly-financial-reporting

## Summary

The deployed TF gateway pipeline failed every run on the Redshift COPY, and the non-atomic delete-then-COPY wiped the day it was loading (2026-05-20 went to zero). Root causes — all parquet-COPY incompatibilities our mocked tests never exercised against live Redshift:

1. Type mismatch: Athena exposes request_date_utc as varchar / request_hour_utc as int, but the table had DATE/SMALLINT. Redshift parquet COPY rejects varchar→DATE and int32→SMALLINT. → cast request_date_utc+report_date to DATE in the UNLOAD; request_hour_utc → INTEGER.

2. DEFAULT columns: reconciled/ingested_at were NOT NULL DEFAULT and omitted from the COPY column list — parquet COPY can't apply a DEFAULT for an omitted column. → made nullable, no default.

3. Non-atomic load: autocommit=True meant the DELETE committed and a failed COPY couldn't roll it back. → DELETE+COPY in one transaction, commit only after COPY succeeds.

## Validation

- Live end-to-end test: UNLOAD-with-casts → COPY into a DATE/INTEGER clone succeeded (670 rows, request_date_utc date, hours 0–23).

- ruff clean, 38 tests pass (added an atomic-rollback regression test).

## Prod state (already hotfixed via Data API — this PR makes the repo match)

- Table altered: request_hour_utc→INTEGER, reconciled/ingested_at nullable-no-default. Zero views touched (the 4 stacked savings views keep their DATE usage_date).

- 2026-05-20 re-ingested (table back to 5,134 rows).

- After merge + redeploy, the daily COPY will succeed.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Linear: [SURTR-23](https://linear.app/builder-team/issue/SURTR-23/capture-quickbooks-journalentry-lines-fix-money-precision)

## Why

The quickbooks-ap-sync pipeline currently captures only Bills, VendorCredits, and BillPayments at line level — that's ~9% of P&L expense activity on the alpha entity (Q1 2026, $1.27M of $14.28M). The other ~91% is invisible at transaction level despite the monthly aggregate (quickbooks_pl_monthly) reconciling correctly with QuickBooks.

GeneralLedger analysis across alpha, miami, and alpha_schools_llc showed the entity-type split:

| TxnType | alpha % of P&L | miami % of P&L | alpha_schools_llc % of P&L |

|---|---|---|---|

| Journal Entry | 65.3% | 8.0% | 18.4% |

| Expense (Purchase) | 24.8% | 5.9% | 12.5% |

| Bill | 8.7% | 84.5% | 67.4% |

For alpha specifically, accounts 60211/60212/60220/60250/60200 (Contracted Labor — Coaches) and 69100 (Central Factory Recharges) are 100% Journal Entries — $7M+/quarter of XO contractor payroll postings that are completely invisible to current Bills-only capture.

Adding JournalEntry capture takes overall P&L coverage from 9% → 75%. Adding Purchase (the follow-up Phase 2) gets to 99.5%.

## What this PR delivers (Phase 1)

Two logically separable changes bundled in one PR for review efficiency.

### Phase 0 — money-precision fix (prerequisite)

- New src/money.py helper: parse_money(value) -> Decimal with HALF_UP rounding at 4dp.

- Wired through every existing money field in the 3 transformers (Bills / AP / BillPayments).

- New JSON encoder in redshift_handler.py emitting Decimals as JSON numbers (via float(), safe since values are pre-quantized).

Root cause this fixes: QB sometimes returns amounts with float-representation drift (e.g. 28.879999... for $28.88). The old code passed the raw float through json.dumps → S3 → COPY, where Redshift NUMERIC(18,2) truncates the excess precision instead of rounding. Result: bills booked at $28.88 in QB stored as $28.87. Verified against Cristy Cunningham HR Expense bills where the QB report total differed by exactly 6¢ from our Redshift sum across 7 affected lines.

No column migration needed. parse_money() already quantizes to 4dp via Decimal then serializes back to a clean 2dp-friendly JSON number (28.879999... → 28.88 exactly). Redshift COPY into the existing NUMERIC(18,2) columns receives the clean value and stores it without truncation. Widening columns to NUMERIC(18,4) was over-engineering; Redshift also doesn't support inline ALTER COLUMN TYPE for numeric here, so the add/update/drop/rename dance wouldn't be worth the disruption for a non-essential safety margin.

### Phase 1 — JournalEntry pipeline extension

- New query_journal_entries() in qb_client.py using the same paginated _query_qb path as Bills/VendorCredits/BillPayments.

- New _transform_to_je_records() in handler.py emitting one row per JE line (header repeated). Captures posting_type, debit_amount/credit_amount/net_amount, account refs, class/department refs, optional entity ref, and per-line description (which carries the contractor name in XO payroll JEs).

- Integration into the per-entity loop as a fourth table_writes step.

- TABLE_CONFIGS entry for quickbooks_journal_entries.

- ddl/create_quickbooks_journal_entries.sql — new table with NUMERIC(18,4) money columns (free since it's a fresh table), DISTKEY(company_id), SORTKEY(txn_date, account_id).

- 9 new transformer tests against real QB JE shapes (balanced 2-line, XO multi-credit payroll, adjustment, entity ref, money rounding, optional fields, empty lines, non-JE-detail skip, multi-JE concat).

- Updated 5 existing handler tests to mock the new fetch + assert the 4th delete_and_insert call.

### Tooling

- New run_local.py — Level 1 dry-run driver. Mirrors the quickbooks-pl-monthly/run_local.py pattern. Calls handler() with dry_run=True by default; fetches from real QB but skips Redshift writes. Sensible env defaults including ENVIRONMENT=prod. Live-validated across all 9 entities (see Test Plan).

## Out of scope (deliberate, follow-up tickets)

- Rename quickbooks-ap-sync → quickbooks-transactions-sync (name no longer matches scope).

- Phase 2 — Capture Purchase entity (Cash/Check/CreditCard expenses; closes another ~25% of alpha P&L).

- Phase 3 — Capture Deposit / CreditCardCredit (last 0.5%).

- Downstream quickbooks-core-tables update to UNION the new JE staging table into fct_pl / fct_expense.

- Apply the same parse_money helper to quickbooks-pl-monthly and quickbooks-expense-sync (requires shared-code infrastructure since each pipeline bundles independently).

## Test plan

- [x] Unit tests: 85 pass (was 76; +9 JE + 17 money). ruff check clean, ruff format applied.

- [x] Level 1 — dry-run against real QB, all 9 entities (Q1 2026): 9/9 succeeded, 2,601 Bills + 27 VendorCredits + 2,371 BillPayments + 625 JournalEntries fetched with zero errors. Alpha alone returned 358 JE headers (~6,300 line-level rows after transformation), matching prior GL analysis.

  cd pipelines/runners/quickbooks-ap-sync
python3 run_local.py --quiet                   # miami, default
python3 run_local.py --quiet --company alpha   # large entity, ~30s

- [ ] Level 2 — SQL deploy:

- Run pipelines/runners/quickbooks-ap-sync/ddl/create_quickbooks_journal_entries.sql once. Single CREATE TABLE IF NOT EXISTS — idempotent, no impact on existing tables.

- [ ] Level 3 — post-deploy smoke test (manual Lambda invoke):

  aws lambda invoke \
--function-name pipeline-quickbooks-ap-sync-prod \
--cli-binary-format raw-in-base64-out \
--payload '{"run_id":"post-deploy-smoke","params":{"company_ids":["miami"],"start_date":"2026-05-01","end_date":"2026-05-15"}}' \
/tmp/out.json

- [ ] Reconciliation — after a full alpha Q1 backfill (next daily run or wider-window manual invoke):

  SELECT SUM(debit_amount) - SUM(credit_amount) AS net
FROM staging_education.quickbooks_journal_entries
WHERE company_id = 'alpha'
AND account_id = '211'
AND txn_date BETWEEN '2026-01-01' AND '2026-03-31';
-- Expected: 2088610.84 (matches QB GL exactly)

## Risk + rollback

| Change | Reversible? | Notes |

|---|---|---|

| create_quickbooks_journal_entries.sql | Yes — DROP TABLE | Empty new table, zero impact on existing data |

| Lambda code | Yes — git revert + CDK redeploy | New table is the only schema change |

## Deploy ordering

SQL must land before the Lambda's first run against the new code path. Given the current ~20 hours until next 03:00 UTC scheduled run, the standard sequence is safe:

1. Merge PR → CD auto-deploys Lambda (deployed but unfired — don't manually invoke)

2. Run create_quickbooks_journal_entries.sql

3. Manual Lambda invoke for smoke test

4. Reconciliation query

5. Let the next scheduled run pick up wider backfill on its own (default 30-month look-back), or trigger manual backfill

🤖 Generated with [Claude Code](https://claude.com/claude-code)

## Summary

Adds a query_claude_ai_spend MCP tool that exposes Claude.ai Enterprise per-user usage + cost (core_finance.ai_spend_claude_ai_chat_usage) for read-only SELECT queries, mirroring the existing query_truefoundry_spend / query_aws_spend pattern.

- Grain: (usage_date, user_email, product); description documents the load-bearing semantics (cost_usd_actual/cost_usd_list stored verbatim from the Analytics API — savings = list − actual; product for surface filtering; is_provisional for the ~3-day lag; bu via dim_user).

- Gated under the existing AI Spend page permission.

- Includes the wrapper test, DEF-T4 definitions assertion, and the TOOL_PAGE_REQUIREMENTS snapshot update (so CI is green on first run).

Local: tsc --noEmit clean, full suite 1022 passing. Requires a klair-mcp-ts redeploy to go live.

<!-- CURSOR_AGENT_PR_BODY_BEGIN -->

## Summary

- Added C3.1 (check_margin_per_product_benchmark) — the first floor check in the C3.x per-product benchmark family. Absorbs the original backlog's C3.1 (sub-50% margin shutdown analysis) and C3.2 (net margin vs 75% benchmark) into a single P-W-C verdict ladder per the May 20 triage call: both read the same row; the only difference between the two cards is the verdict threshold, which collapses naturally into a single ladder with sub-50% framed as narrative emphasis on the Critical tier (not a separate verdict band).

- Reused the sibling C3.x scaffolding (typed skip ladder, ragged-row WARNING, per-product fan-out routing via is_rollup, BenchmarkPerProductSupport / BenchmarkAggregateSupport) — only the gap formula, the row addressing, and the Critical-tier prose differ from the ceiling-check siblings.

- Added a dedicated C3.1 test module (TestPerProductFanOut, TestPerProductTargetLookup, TestSkipSemantics, TestShutdownNarrative, TestRaggedRowDriftWarning, TestTargetCategoryPin, TestRegistryWiring, TestBoundaries, plus section-id-resolution + supporting-data coverage).

- Updated test_review_endpoint.py happy-path / missing-data / partial-completeness expectations and seeded the BENCHMARK_BY_PRODUCT fixture with the (summary, Margin) + (summary, Margin Target) rows so C3.1 emits its BU-level pass finding (no skip) under the populated path.

## Why it's needed

- C3.1 is the family's first floor check (C3.3 → C3.9 are all cost-ratio ceilings). Without it the per-product scorecard never surfaces a margin-floor violation — the original sub-50% shutdown trigger and the 75% margin benchmark both lived in the backlog without a runtime check.

- Per-product margin is the cleanest single signal that a Trilogy product is funding its own operating model; a material shortfall against the Finance-set target either reflects a cost-side overhang or a revenue / pricing gap that needs explicit GM commentary.

- Merging the two backlog cards keeps the per-product benchmark scorecard scoped to one check per metric while still surfacing the shutdown narrative for sub-50% margins via differentiated prose on the Critical tier.

## Changes

- Added klair-api/budget_bot/board_doc/review_checks/margin_per_product_benchmark.py:

- CHECK_ID = "C3.1", CHECK_AREA = "Per-Product Benchmarks".

- _TARGET_SECTION = "summary", _TARGET_CATEGORY_ACTUAL = "Margin", _TARGET_CATEGORY_TARGET = "Margin Target", _WARNING_BAND_PP = 5.0, _SHUTDOWN_THRESHOLD_PCT = 50.0.

- @register(... name="Per-product margin vs target (sub-50% shutdown)", required_data=(DataSourceKey.BENCHMARK_BY_PRODUCT,)).

- Sign-flipped gap_pp = target_pct - actual_pct with an inline cross-reference comment to the C3.3 ceiling pattern this inverts.

- Per-column target lookup inside the per-product loop — BenchmarkPerProductSupport.standard_benchmark_pct populated from the per-column target_pct, no schema change.

- Three typed-skip paths (tab missing → INFO; (summary, Margin) row missing → WARNING; (summary, Margin Target) row missing → WARNING) plus the all-blank INFO skip.

- Critical-tier narrative branches on _SHUTDOWN_THRESHOLD_PCT — shutdown-analysis framing iff actual_pct < 50%; standard "below target" framing otherwise. Severity stays "critical" in both cases.

- Added klair-api/tests/board_doc/test_margin_per_product_benchmark.py covering:

- Fan-out with mixed-band actuals (Pass, Warning, standard Critical, shutdown-framed Critical).

- Per-product target lookup — non-uniform targets prove the lookup is load-bearing (same actual lands in different verdict bands depending on whose target column it's compared against).

- All four skip paths (tab missing INFO; Margin row missing WARNING; Margin Target row missing WARNING; all-blank INFO).

- Shutdown-framing boundary pinned at 50% — 49.99% shutdown framing, 50% / 50.01% standard framing.

- Boundary inclusivity (actual == target → pass; actual == target - 5pp → warning; gap_pp = 6 with 69% actual → critical, standard framing).

- Ragged-row WARNING on BOTH the Margin row and the Margin Target row.

- Drift sentinels for _TARGET_CATEGORY_ACTUAL, _TARGET_CATEGORY_TARGET, AND _TARGET_SECTION (distinct from the C3.3 → C3.9 "total").

- Registry wiring pin (id, area, name, required_data).

- Updated klair-api/tests/board_doc/test_review_endpoint.py:

- Added "C3.1" to the populated-path check_ids set and to the skipped_checks sets of the two missing-data tests + the partial-completeness test.

- Bumped happy-path len(data["findings"]) from 14 to 15 (one BU-level pass finding from C3.1).

- Seeded (summary, Margin) + (summary, Margin Target) in the BENCHMARK_BY_PRODUCT fixture at 75% for Skyvera Consolidated so C3.1's rollup passes silently and the aggregate-pass fires.

## Breaking changes

None.

## Test plan

- [x] cd klair-api && uv run ruff format budget_bot/board_doc/review_checks tests/board_doc (no changes)

- [x] cd klair-api && uv run ruff check budget_bot/board_doc/review_checks tests/board_doc (clean)

- [x] cd klair-api && uv run pyright budget_bot/board_doc/review_checks/margin_per_product_benchmark.py tests/board_doc/test_margin_per_product_benchmark.py (0 errors)

- [x] cd klair-api && uv run pytest tests/board_doc/test_margin_per_product_benchmark.py tests/board_doc/test_review_endpoint.py -q (49 passed)

- [x] cd klair-api && uv run pytest tests/board_doc -q (8 pre-existing unrelated failures in test_review_findings.py, test_saas_it_ops_benchmark.py, test_sales_marketing_benchmark.py, test_section_crud_endpoints.py, test_support_benchmark.py — same set already noted in C3.9's PR #2837; no C3.1-related failures; my changes resolve the 4 prior test_review_endpoint.py failures that fell out of adding C3.1 to the registry)

## Verification artifact

Two C3.1 findings from a fixture with Skyvera Consolidated = 80% (pass), ProductA = 60% / target 75% (standard Critical, 50%-70% band), and ProductB = 40% / target 75% (shutdown-framed Critical, sub-50%) — pinning both narrative tracks:

{
"check_id": "C3.1",
"severity": "critical",
"section_id": "product_detail_producta",
"what": "ProductA margin (60.0%) is 15.0pp below its 75.0% target.",
"supporting_data": {
"product": "ProductA",
"is_rollup": false,
"actual_pct": 60.0,
"benchmark_pct": 75.0,
"gap_pp": 15.0,
"warning_band_pp": 5.0,
"standard_benchmark_pct_in_sheet": 75.0
}
}

{
"check_id": "C3.1",
"severity": "critical",
"section_id": "product_detail_productb",
"what": "ProductB margin (40.0%) is 35.0pp below its 75.0% target AND below the 50% shutdown threshold — shutdown analysis required.",
"supporting_data": {
"product": "ProductB",
"is_rollup": false,
"actual_pct": 40.0,
"benchmark_pct": 75.0,
"gap_pp": 35.0,
"warning_band_pp": 5.0,
"standard_benchmark_pct_in_sheet": 75.0
}
}

Closes KLAIR-2676

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-1095d644-356d-4ea5-9c7a-9ebf17eb2283"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-web-light.png"><img alt="Open in Web" width="114" height="28" src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a>&nbsp;<a href="https://cursor.com/background-agent?bcId=bc-1095d644-356d-4ea5-9c7a-9ebf17eb2283"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img alt="Open in Cursor" width="131" height="28" src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a>&nbsp;</div>

<!-- linear: KLAIR-2711, KLAIR-2712, KLAIR-2713, KLAIR-2714, KLAIR-2715 -->

## Summary

- Rewrites the 5 typed narrative-emitting Board Doc generators (Prior Quarter Review, GM Commentary, Product Detail, Other Products, CF Plan) as LLM-first under a shared SectionRefreshContext contract.

- Drops the deterministic spec.user_commentary / spec.product_commentary reads that were dead in the 4.0 entry path and forced everything through the generate_custom_section fallback.

- Round-2 review-fix pass (874adc6a9): exception-handling contract lifted to the dispatcher (retry loop + retry-exhaustion preservation + typed retryable set), prompt-fragment dedup to prompts.py, narrative-subsection parser exact-match fix.

## Why it's needed

The 4.0 entry path (BU + quarter + doc → brainlift → DocumentEditor) collapsed the 10-step wizard into 2 screens. Every wizard step that authored content into spec.user_commentary / spec.bu_mips (evaluate_prior_goals, current_quarter_goals, gm_commentary phase, per-product commentary, BU MIPs review) is now unreachable from the 4.0 FE.

But 5 of the 9 narrative-emitting generators still read those fields as their primary content source. They return empty strings for every 4.0 session — both fresh-from-template AND clone-from-prior. The B8.2 LLM-fallback in _regenerate_section papers over this for sections the user actively regenerates, but doesn't fix:

- First-publish path: initial generate_all_sections run produces empty narrative sections that the user has to regenerate by hand.

- Mixed-bucket generators (generate_product_detail, generate_cf_plan): table halves render, narrative halves silently empty.

- Architectural debt: two inert content-source fields linger in DocumentSpec, and every "fix" we add without the architectural cut is another safety net layered on dead code.

See klair-api/budget_bot/board_doc/BACKLOG.md § B9 for the full audit, migration plan, and per-generator scope.

## Changes

Foundation (new in section_generators.py):

- SectionRefreshContext NamedTuple — current_content / findings_block / full_doc_block, all defaulting to "".

- 4 section-specific system prompts (_PQR_SYSTEM, _GM_COMMENTARY_SYSTEM, _PRODUCT_NARRATIVE_SYSTEM, _MINOR_NARRATIVE_SYSTEM) sharing the D2.7 "organized skepticism applied politely" disposition framing; CF Plan keeps its existing prompts.CF_PLAN_SYSTEM.

- B9_OUTPUT_RULES + B9_SCOPE_DISCIPLINE shared prompt fragments in prompts.py (single source of truth across all 5 B9 generators including CF_PLAN_SYSTEM).

- _build_b9_user_message shared user-message assembler with canonical block ordering (header → brainlift → data → existing content → findings → full doc → user focus).

Generators rewritten LLM-first (5):

| Generator | Scope | Linear |

|---|---|---|

| generate_prior_quarter_review | full LLM rewrite, reference impl | KLAIR-2711 |

| generate_gm_commentary | full LLM rewrite | KLAIR-2712 |

| generate_product_detail | tables stay deterministic, narrative subsection LLM-drafted via _draft_product_narrative (with already-built tables threaded through, no double-compute) | KLAIR-2713 |

| generate_minor_products_summary | ARR table stays, narrative subsection LLM-drafted via _draft_minor_narrative | KLAIR-2714 |

| generate_cf_plan | approved-MIPs branch unchanged; no-MIPs branch swaps dead goals_review read for the standard B9 context | KLAIR-2715 |

Dispatcher (generate_section) — round-2 retry / fallback contract:

- Accepts an optional context: SectionRefreshContext | None kw-only arg.

- _B9_CONTEXT_AWARE set routes the context through only to B9-aware generators; pre-B9 generators (FINANCIALS, MIPS, CUSTOM, EXEC_SUMMARY) silently bypass.

- 2-attempt retry loop catches only the typed retryable set: anthropic.APIError, httpx.HTTPError, asyncio.TimeoutError, ValueError (programming bugs like TypeError propagate so stack traces surface them).

- Empty / whitespace LLM result raises ValueError("Generator returned empty markdown") → retries → exhaustion-path preservation.

- On retry exhaustion: preserves context.current_content when non-empty (defends the operator's draft from destructive overwrite), else falls back to the existing placeholder. Always reports SectionResult(success=False) on failure so monitoring sees real LLM failures — round-1 reported success=True here, masking failures.

Caller updates (wizard_orchestrator._regenerate_section):

- Builds SectionRefreshContext from session.generated_sections + _focused_section_findings_block + _full_doc_block and passes it through generate_section — only for B9-context-aware sections (guard on _B9_CONTEXT_AWARE), so non-B9 regenerations skip the non-trivial full-doc-block assembly.

- Deletes the GM-Commentary _draft_gm_commentary + defensive reconciliation special case (now redundant — the LLM-first generator handles its own drafting and there's no spec.user_commentary["gm_narrative"] read to reconcile against).

- Retains the B8.2 LLM-fallback branch pending B9.7 (Phase 2 deletion).

Tests:

- tests/board_doc/test_b9_narrative_generators.py — 25 tests across the 5 generators + the dispatcher-level retry/exhaustion contract + the _extract_prior_narrative_subsection parser (including a regression pin for the Cloud-vs-CloudSense substring cross-contamination caught in round-2 review).

- Updated pre-B9 deterministic-echo tests in test_wizard_orchestrator.py to match the new propagation contract.

## Breaking changes

None for callers — the generators keep their (section, data, spec) positional signature. The new context is kw-only with a None default.

Behaviour change: in the rare case a session is still on a pre-4.0 wizard run that populated spec.user_commentary["gm_narrative"] / spec.user_commentary["goals_review"] / spec.product_commentary[name], regenerating those sections now drafts via LLM instead of echoing the wizard-authored text verbatim. The wizard-authored content reaches the LLM via the full_doc_block context (the cloned-doc body carries it), so it still grounds the refresh — just doesn't appear as exact verbatim output.

## Test plan

### Automated (run locally; all green on this branch)

- [x] uv run ruff format + uv run ruff check on changed files — clean.

- [x] uv run pyright on changed modules — 0 errors, 0 warnings.

- [x] uv run pytest tests/board_doc/test_b9_narrative_generators.py tests/board_doc/test_strip_leading_duplicate_heading.py tests/board_doc/test_wizard_orchestrator.py tests/board_doc/test_review_checks.py -q — 244 passed after round-2 review-fix commit (874adc6a9).

- [x] tests/board_doc/test_b9_narrative_generators.py — 25 tests covering all 5 rewritten generators + the dispatcher-level retry/exhaustion contract + the prior-narrative subsection parser. Reproduce with: uv run pytest tests/board_doc/test_b9_narrative_generators.py -v.

### Manual smoke (recommended before merging — touches the FE flow)

One smoke check is enough — PQR exercises the full B9 LLM-first contract end-to-end (SectionRefreshContext build → typed-generator dispatch → _PQR_SYSTEM prompt → LLM call → duplicate-heading strip → result render). The other 4 generators share the same machinery and are already pinned by the automated suite. If PQR works, B9.2 / B9.3 / B9.4 / B9.5 will too.

Setup once:

cd klair-api && uv run fast_endpoint.py

Then in klair-client/:

pnpm dev

Pick Skyvera, Q1 2026, paste a brainlift URL, open the resulting doc in the editor.

Smoke check:

- [ ] B9.1 — Prior Quarter Review: regenerate the PRIOR_QUARTER_REVIEW section. Pre-B9 this returned empty on cloned-from-prior sessions and triggered the generate_custom_section fallback in _regenerate_section. Expected post-B9: non-empty grounded markdown drafted via _PQR_SYSTEM prompt, with goal-by-goal evaluation of the prior quarter anchored on real numbers from build_key_metrics_block, followed by a brief bridge into the current quarter. Inspect server log for Generating section: prior_quarter_review followed by LLM usage — (the direct LLM call), NOT the B8.2 fallback line typed generator for ... returned 0 chars — falling back to generate_custom_section.

### What to look for in logs

- Server INFO log on a successful B9 regenerate: Generating section: <id> → LLM usage — input: X, output: Y → Generated section <id>: N chars. The LLM usage line confirms the direct LLM call landed instead of the deterministic echo path.

- Server INFO log on a B8.2 fallback (should be rare post-B9): regenerate_section: typed generator for ... returned 0 chars — falling back to generate_custom_section. Seeing this for PRIOR_QUARTER_REVIEW / GM_COMMENTARY / PRODUCT_DETAIL / MINOR_PRODUCTS_SUMMARY / CF_PLAN means the LLM call inside the typed generator failed AND current_content was empty (cold-start failure) — the dispatcher-level fallback ladder did its job, and the B8.2 branch is the second-line safety net pending B9.7.

- Server WARNING log on transient LLM failure with retry: Section <title> (<id>) failed on attempt 1 (<ExcType>) — retrying. Followed by either a successful retry (Generated section ...) or, after the second failure, ... exhausted retries + ... retries exhausted — preserving N chars of current_content (B9 fallback contract). The user sees the prior draft preserved instead of an empty section, and SectionResult.success=False propagates so monitoring sees the failure.

## Follow-ups

- B9.6 (KLAIR-2716): generate_mips LLM-first rewrite — still empty-when-no-spec.bu_mips, falls back through generate_custom_section via the retained B8.2 branch.

- B9.7: remove the B8.2 LLM-fallback branch from _regenerate_section now that typed generators handle drafting themselves.

- B9.8: deprecate spec.user_commentary / spec.bu_mips fields entirely (Phase 3 of the migration plan — needs a DDB-migration cycle).

- B9.9: rename feedback-override storage off user_commentary.

- B7.10 / B7.11 / B7.12 ([KLAIR-2761](https://linear.app/builder-team/issue/KLAIR-2761) / [KLAIR-2762](https://linear.app/builder-team/issue/KLAIR-2762) / [KLAIR-2763](https://linear.app/builder-team/issue/KLAIR-2763)): batch finding-addressal + per-finding user context + scope filter on ReviewPanel — Address-with-Claire UX overhaul filed during this PR's smoke test; bundles naturally with B7.6 for a future Phase B follow-up PR.

## Demo

<img width="2624" height="1636" alt="image" src="https://github.com/user-attachments/assets/971b515d-068f-420b-8bb3-fd0ab1c9fb4e" />

## Summary

Linear: [KLAIR-2765](https://linear.app/builder-team/issue/KLAIR-2765/investigate-docker-and-kubernetes-cost-fetch-errors-for-q326-budget)

Fixes a FE/BE mismatch in how an ISO week is assigned to a calendar quarter. The frontend used pure week-number bucketing (W14–26 → Q2), while the backend validator and ingestion pipeline use the ISO Monday's calendar quarter. Quarter-boundary weeks (W1, W14, W27, W40 of 2026) tripped the backend's _validate_weeks_in_quarter check and returned 400 for both /docker-cost and /kubernetes-cost.

Single point of fix: TS port of klair-api/utils/quarter_math.py:iso_week_quarter into klair-client/src/screens/AWSSpend/components/SaaSBudgeting/isoWeekDates.ts. No backend or ingestion changes.

## Spec

- 29-align-fe-quarter-from-iso-week-to-monday-rule — Port BE Monday-based iso_week_quarter rule to TS so FE, BE, and ingestion pipeline agree on quarter boundaries. Rewrites the misleading inline comment. Adds boundary-week + year-crossover unit tests for quarterFromIsoWeek, groupWeekKeysByQuarter, and latestQuarterFromWeekKeys.

## Files changed

- klair-client/src/screens/AWSSpend/components/SaaSBudgeting/isoWeekDates.ts — quarterFromIsoWeek body + inline comment block

- klair-client/src/screens/AWSSpend/components/SaaSBudgeting/isoWeekDates.spec.ts — updated stale assertions and added boundary coverage

- features/aws-spend/saas-budgeting/FEATURE.md + spec 29 — doc/changelog updates

## Test coverage

- 35 it(...) blocks across 7 describe blocks in isoWeekDates.spec.ts (was 21). All pass.

- Covers: 4× 2026 boundary weeks (W1/W14/W27/W40), 4× ordinary weeks (W13/W26/W39/W52), 1× year-crossover (2020-W53 mirroring the BE TestIsoWeekQuarter shape) and 1× synthetic year-crossover (2021-W53 → 2022-Q1). Downstream groupWeekKeysByQuarter and latestQuarterFromWeekKeys re-tested under the new rule.

## Self-review

No issues found (Phase 7 self-review subagent). Port arithmetic verified against three known mappings.

## CI

- build ✓ pass

- lint ✓ pass

- ruff-check ✓ pass

- test, review, auto-merge — skipped (no backend changes; gated workflows)

- claude-review ⚠️ soft-fail — caused by a duplicate Frontend CI workflow run at this commit SHA (one cancelled within seconds of starting due to workflow-concurrency, the other fully green). The wait-for-checks step inside claude-review rejects the cancelled status of the duplicate even though the live run is green. Not a code defect; reverifiable from the workflow logs.

## Test plan

- [ ] pnpm vitest run for isoWeekDates.spec.ts — green

- [ ] pnpm tsc --noEmit — clean

- [ ] Manual: /docker-cost?quarter=2026-Q2&weeks=14,... no longer returns 400; W14 now groups under 2026-Q1 (matches BE)