The Trilogy Times

## Summary

AI-160/AI-469 unattended spec-authoring draft for AI-582, proposed from a disposable git worktree — the invoking checkout was never written to.

## Why It's Needed

This is not an implementer PR — it proposes a draft task spec for human review, not a code change. farm.ts's spec-authoring stage produced this so an operator can review/edit/promote it instead of it existing only on an orchestrator's local disk.

## Changes

- Adds tasks/proposed/ai582-fix-windows-spawn-timeout-flakes-in-doctor-task-and-triage-h.md under tasks/proposed/.

## Breaking Changes

None — tasks/proposed/ is excluded from every dispatch selection path (isUnderProposedSpecsDir in task-file.ts) until a human moves the file out. This PR being open, draft, or even merged does not make the spec fireable.

## Test Plan

- [ ] Human reviews the draft's Problem / Scope / Acceptance criteria / Assumptions sections before moving it out of tasks/proposed/.

## Verification Artifact

The farm tick's own spec-authoring receipt (runs/farm-tick-receipt-*.json).

<!-- drones-spec-draft:ticket=AI-582 -->

## Summary

- Move Aerie REBL3 reads, sync, and agent data tools to the v2 resource API

- Move Due Diligence status writes to v2 merge semantics with explicit clear tombstones and Aerie-owned projections

- Preserve existing Aerie-facing DTOs through bounded, fail-closed compatibility adapters

## Why

REBL3 v1 is being deprecated. Aerie depended on v1 list, resolve, site, status, and Due Diligence write behavior across the web app, Convex, and analytics sync. This migration switches those boundaries to v2 while preserving downstream contracts and failing closed where v2 no longer offers an equivalent endpoint.

## Business Value

Keeps Aerie property discovery, agent tools, analytics sync, and Due Diligence workflows operational after the REBL3 v1 retirement without exposing tier-gated upstream data.

## Breaking changes

- Runtime reads prefer a least-privilege REBL3_READ_KEY; governed Due Diligence writes prefer REBL3_WRITE_KEY. REBL3_CONSUMER_KEY remains a deprecated rolling-deploy fallback.

- Due Diligence writes use POST /api/v2/sites/{id}/status; cleared Aerie-owned fields are sent as explicit null tombstones because v2 merges omitted keys.

- Address resolution scans a bounded v2 inventory and requires exactly one normalized match; incomplete, missing, or ambiguous scans fail closed.

## Test plan

- [x] Repository formatting and architecture boundary checks

- [x] Contracts, sync, chat, and Convex typechecks

- [x] 267 targeted tests passed; 17 retired tests skipped

- [x] Credentialed read-only v2 smoke: list, expanded site, and status resources

- [x] Seven-lane adversarial review completed; material findings fixed or explicitly reconciled

- [ ] No live Due Diligence write was executed

## Summary

- Add an explicit full-run retirement declaration for removed FinalSite tenants

- Record retired sites atomically with the accepted ingestion boundary

- Preserve fail-closed boundary validation and all historical raw observations

## Why

The FinalSite source catalogue deliberately rejects boundary contraction, but no retirement workflow existed. That made it impossible to remove the CLONE tenant safely while adding the newly confirmed active tenants.

## Business Value

FinalSite ingestion can track the actual active tenant estate without silently retaining special-purpose sites or deleting historical evidence.

## Test plan

- [x] uv run ruff check .

- [x] uv run python scripts/generate_ddl.py --check

- [x] uv run pytest -q (103 passed)

- [ ] Deploy, remove alphaschools from the secret while adding the 11 confirmed tenants, then invoke a full run with retire_sites: ["alphaschools"]

- [ ] Verify 59 complete sites, one retired boundary row, and successful raw publication

## Summary

- Remove the broad try/except around enrich_and_load in both handlers so a total enrichment failure fails the Lambda invocation instead of returning SUCCESS with an enrichment_error field.

- Add an autouse conftest.py fixture per pipeline resetting the Anthropic API key/client module-level cache between tests (a latent test-isolation bug this change surfaced).

## Why

Follow-up to #1566 (issue #1564). That PR fixed the immediate symptom (an unbounded anthropic version pin drifting to one that rejected the temperature kwarg); this fixes why the resulting 100%-enrichment-failure went unnoticed for two days.

enrich_and_load deliberately raises when every row in a batch fails enrichment — specifically to abort and preserve the existing enriched table rather than let a half-written run silently wipe it. Both handlers caught that abort in a bare except Exception, logged it, and returned a normal SUCCESS summary — downgrading a deliberate hard-stop into a silently-ignored warning.

This mirrors mercy's own finding on the related PR #1540: its handler.py fix (same propagate-the-failure change) was correct, but its enrichment.py fix (removing the temperature kwarg) was not — temperature is a valid, standard parameter; the real problem was the dependency-version drift already fixed in #1566.

Test-isolation bug found along the way: both enrichment.py modules cache the Anthropic API key resolution in a module-level global with no reset between tests. A truthy value set by test_enrichment.py was leaking into test_handler.py's "no API key configured" test cases, which then attempted real, unmocked Redshift/boto3 calls — previously masked by the same broad except Exception this PR removes. Fixed with an autouse fixture.

## Business Value

Closes the actual alerting gap behind the two pipelines' silent data-integrity failure — any future total enrichment failure (API outage, another dependency drift, model deprecation) will now fail the run and page instead of shipping a stale table silently.

## Manual Effort Estimate

~1.5 hours (trace the swallow site, verify against mercy's review of the related PR to avoid repeating its flawed diagnosis, then chase down and fix the test pollution this change exposed).

## Test plan

- [x] uv run pytest tests/ — 95/95 (netsuite-unrealized-gains) + 85/85 (netsuite-gl-detail) passed

- [x] uv run ruff format --check .

- [x] uv run ruff check .

## Summary

- Life-to-date capex queries currently filter to account_type = 'Fixed Asset' only, which silently excludes account 62700 Other Expenses:CAPEX — $9,189,369.83 net of real SY22-24 capex (Alpha Austin/Spyglass, Alpha Brownsville, Alpha Highland Park, NextGen Academy, Alpha Miami) that Finance deliberately expensed rather than capitalized, and will not restate.

- Adds a guidance note to the Produce life-to-date capex by school workflow so an agent includes these 226 real postings, excludes the 72 net-zero "Allocation - Facilities/Support" pass-through legs, and knows the account is a closed population (last posting 2024-05-31) so a new posting there is an anomaly, not routine capex.

- Documents the two class-mapping cases from Finance's handoff sheet: 'Dallas (deleted)' → Alpha Highland Park (confirmed still unresolved live) and the esports_academy_llc no-class line → NextGen Academy (confirmed already resolved live, no action needed).

- Also drops a named-individual citation on the adjacent CAC rule in favor of a plain Finance-team attribution, for consistency (no rule in this file should cite a specific person).

## Context

Finance sent a policy decision plus a 4-tab handoff sheet ("Q22 capex handoff for dev team (26 Aug 2026)") explaining that 62700 mixes a net-zero allocation pass-through with real, deliberately-expensed capex, and asked that this be encoded in the semantic layer so an "uninstructed AI" doesn't misread the expensing as a data error. This is a guidance-only change — no data-model or pipeline change is included (the still-open crosswalk gap for 'Dallas (deleted)' is called out explicitly in the guidance rather than patched here).

## Test plan

- [x] npm run typecheck — clean

- [x] npx jest tests/unit/routes/data-api-contract.test.ts — 7/7 pass

- [x] npx eslint src/routes/data-api-ontology.ts — clean

- [x] npx prettier --check src/routes/data-api-ontology.ts — clean

- [ ] CI

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

<!-- CURSOR_AGENT_PR_BODY_BEGIN -->

## Summary

listPortfolioHealthInsights (the public-API v2 portfolio-health list) previously enumerated only active and paused sites when no status filter was supplied, and rejected status=open as an invalid filter value. This silently omitted campuses whose operational status is already open — including ones still in the diligence or buildout lifecycle stage — from portfolio readiness views. This PR extends portfolio-health list/detail membership to include open sites, alongside active/paused, while continuing to exclude cancelled (and closed) sites. getPortfolioSiteHealthInsight (site detail) was already status-unbound and is unchanged. Quality-bar membership, the v1 operating lens, and listOverdueWorkInsights's own active/paused default are explicitly left untouched.

## Context

- chat/convex/publicApi/v2/domains/insightsData.ts's portfolioSourceSites hard-coded the active/paused union for unfiltered enumeration and rejected open as an explicit filter.

- chat/lib/public-api/v2/domains/insights.ts exposed the matching narrowed status enum, operationalStatus schema enum, and agent-context copy.

- Fixes AERIE-1163.

## Changes

- chat/convex/publicApi/v2/domains/insightsData.ts: generalized portfolioSourceSites to union an arbitrary set of statuses (queried per-status via the existing by_status / by_status_and_stage indexes, each capped at MAX_PORTFOLIO_SOURCE_SITES + 1) instead of a hard-coded active/paused pair. listPortfolioHealth's unfiltered case now uses PORTFOLIO_HEALTH_ENUMERATION_STATUSES = ["active", "paused", "open"]; its status arg validator now accepts "open". listOverdueWork's unscoped buildout call keeps its own OVERDUE_WORK_ENUMERATION_STATUSES = ["active", "paused"] default, so this change is scoped to the portfolio-health surface only. The combined-count overflow check (combinedCount > MAX_PORTFOLIO_SOURCE_SITES) still fails closed regardless of how many statuses are unioned, and no single per-status query can silently truncate the union (each is still capped at +1 over the limit).

- chat/convex/publicApi/v2/domains/insights.ts: updated the listPortfolioHealth handler's response meta.methodology.summary/limitations to name the expanded (active/paused/open) membership and the continued cancelled/closed exclusion.

- chat/lib/public-api/v2/domains/insights.ts: widened the status query parameter schema/description and the operationalStatus response schema enum to include "open"; updated the insights.portfolioHealth agent-context lifecycle text, traps, and workflow emptyResult guidance to describe the expanded membership, using the shared OPEN_CAMPUS_MEMBERSHIP_BOUNDARY copy so this doesn't overclaim resolved canonical open-campus membership (AERIE-1017 stays unresolved).

- Tests: updated chat/lib/public-api/v2/domains/insights.test.ts's contract assertions to match the new membership wording, and added coverage in chat/convex/publicApi/v2/insights.test.ts for: one open site per lifecycle stage (diligence/buildout/operating) appearing in unfiltered enumeration, cancelled-site exclusion, status=open combined with stage narrowing the same cohort, combined per-status source overflow (167+167+167 = 501 rows, each individually under the 500 cap) failing closed with insight_source_limit_exceeded, and deterministic cursor ordering/paging when open-status rows are interleaved with active/paused rows.

## Testing

- npx vitest run convex/publicApi/v2/insights.test.ts lib/public-api/v2/domains/insights.test.ts — 19/19 passed (15 + 4).

- npx vitest run convex/publicApi (public API contract regression sweep) — 365/370 passed; the 5 failures are pre-existing and unrelated ([REDACTED] Content-Location header assertions in documentsHttp.test.ts, http.test.ts, portfolioDomain.test.ts, lifecycleProperty.test.ts), confirmed by reproducing the same failures on this branch's pre-change base commit (git stash + rerun) — not touched by this diff.

- pnpm typecheck (tsc --noEmit && tsc -p convex/tsconfig.json --noEmit) — passed with no errors.

- npx biome check on all changed files — passed (after applying --write formatting).

- Pre-commit hooks (convex-paths, biome, typecheck-chat) — passed.

## Acceptance Criteria

- [x] Public status query parameter and internal validator accept active, paused, open.

- [x] Unfiltered list includes public-identity sites in all three statuses, excludes cancelled.

- [x] status=open returns open sites across diligence/buildout/operating; stage narrows the same cohort.

- [x] Detail behavior unchanged; list/detail share the same milestone projection.

- [x] Combined source-count overflow fails closed before pagination; no per-status query truncates silently.

- [x] Cursor ordering/page boundaries stay deterministic with the third status interleaved.

- [x] Tests cover: one open site per stage, cancelled exclusion, status+stage filtering, overflow, multi-page ordering.

- [x] Agent-context grain/lifecycle, parameter description, empty-result guidance, and methodology limitations name the expanded membership.

- [x] No status normalization, production data mutation, quality-bar cohort change, or v1 route change.

## Out of Scope

- Redefining what makes a campus "open" (canonical open-campus membership stays unresolved per AERIE-1017).

- Changing site lifecycle stage or production records.

- Expanding quality-bar scoring to non-operating sites.

- Modifying v1 operating routes or listOverdueWorkInsights's own default cohort.

## Risk & Rollback

Low risk: the change is additive to an internal-only, capability-gated read API (operations.portfolio.read) and only widens membership for the unfiltered/status=open case. Non-open, non-cancelled/closed behavior is unchanged, existing indexes (by_status, by_status_and_stage) are reused with no schema migration, and the overflow/pagination safety checks are preserved (generalized, not weakened). Revert is a straightforward single-commit revert of this PR.

Closes AERIE-1163

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-fcbeb074-4d88-45ab-b297-7bbb04fb00a7?cursor_ref=pr_footer&cursor_cta=open_in_web"><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-fcbeb074-4d88-45ab-b297-7bbb04fb00a7&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><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>

## Summary

- Treat an empty REBL3 page with a continuation cursor as an incomplete scan

- Add regression coverage for the fail-closed pagination invariant

## Why

REBL3 can return an empty page while still advertising a continuation cursor. The sync previously treated any empty page as a clean end of inventory, which could silently leave the local catalog stale while reporting a successful refresh.

## Business Value

Prevents incomplete REBL3 inventories from being accepted as fresh and keeps operators informed when upstream pagination is inconsistent.

## Test plan

- [x] pnpm --dir sync exec vitest run src/upstream/rebl3/sync.test.ts

- [x] pnpm exec biome check sync/src/upstream/rebl3/sync.ts sync/src/upstream/rebl3/sync.test.ts

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

## Summary

Migrate QuickBooks Expense AI Generation from its Lambda implementation to a

one-shot ECS/Fargate task behind the existing Step Functions execution. This

removes Lambda's 15-minute ceiling while leaving legacy writers, consumers, and

the existing publication semantics unchanged. Anthropic is pinned to 0.117.1

in the dependency used by the ECS image.

### Changes

- pipelines/runners/quickbooks-expense-ai-generation/pipeline.json —

switch the pipeline to ECS with 1 vCPU, 2 GB memory, a two-hour timeout,

21 GB ephemeral storage, and a required terminal run-result object.

- pipelines/runners/quickbooks-expense-ai-generation/Dockerfile *(new)*

— build the production image from the runner's src/requirements.txt and

run it as a non-root user.

- src/main.py and src/run_result.py *(new)* — adapt the existing

handler to the ECS entrypoint and publish the standard S3 terminal-result

envelope consumed by orchestration.

- pipelines/cdk/lib/pipeline-stack.ts — preserve the existing Lambda

construct identities for the QuickBooks log group and state machine during

the compute migration.

- Dependency metadata, tests, and README — pin Anthropic in

src/requirements.txt, pyproject.toml, and uv.lock; add ECS contract and

entrypoint coverage; document the new runtime.

### Design Decisions

- The migration keeps legacy construct IDs so CloudFormation updates the

existing named resources instead of treating the ECS resources as unrelated

replacements.

- The Docker build reads src/requirements.txt, so the exact Anthropic pin is

present in the actual production image input as well as local dependency

metadata.

- A duplicate idempotency result is normalized to orchestration success without

generating or publishing new AI output. Failure notifications remain enabled

by default; suppression is available only through the existing per-run

operator option.

## Business value

QuickBooks Expense AI Generation can complete workloads that exceed Lambda's

900-second limit, while preserving provenance, atomic publication, and the

legacy pipeline's consumers. This turns the production-tested ECS migration

into a reviewable, repeatable deployment path.

## Estimated manual effort

2–3 focused engineering days.

## Test Plan

- [x] 63 QuickBooks Python tests passed with uv run pytest.

- [x] Ruff lint and format checks passed.

- [x] CDK TypeScript build passed with npm run build.

- [x] QuickBooks CDK Jest suite passed (4 tests).

- [x] Production ECS run completed successfully; the follow-up same-input run

completed as an idempotent duplicate in about 55 seconds.

- [ ] Run the full repository CI suite and review its results.

- [ ] Merge to main; production deployment remains governed by the repository

workflow's production branch promotion.

## Summary

- Regenerate the guide-platform contract against the live catalog: capture_images gained 3 nullable columns (mm_group_id uuid, motivational_model_id uuid, mm_reward_tier text).

- Update contracts/legacy_clean_compatibility.json accordingly.

- Prod clean view staging_education_guide_platform.capture_images already recreated and verified (svv_columns) ahead of this merge.

## Why

guide-platform-raw-sync has been hard-failing daily for 15 days (SourceValidationError: schema drifted from the checked contract). New columns live inside source_record SUPER, so the raw table needs no schema change — only the clean-view projection and checked contract needed regenerating.

## Business Value

Restores the daily GuidePlatform raw sync, which has had zero successful runs since 2026-08-12.

## Manual Effort Estimate

~1 hour (regenerate against live catalog, identify the affected table/columns, update compat file, recreate + verify the prod view before merge to avoid a deploy-ordering gap).

## Test plan

- [x] uv run pytest tests/ — 77/77 passed

- [x] uv run ruff format --check .

- [x] uv run ruff check .

- [x] Prod view recreated and columns verified via svv_columns before opening this PR

<!-- CURSOR_AGENT_PR_BODY_BEGIN -->

## Summary

- Adds a bounded, side-effect-free preflight package at klair-api/budget_bot/board_doc/provisioning/ that builds a deterministic, reviewable campaign-manifest candidate for an explicit (year, quarter) — no wall-clock default anywhere in the call chain.

- Enumerates the 9 BU / 12 CF active roster, drafts recipients from the canonical owner mapping, resolves each entity's Q3 seed strategy (roll_forward / blank_no_prior) and Q4 target-source mapping, and produces a row-order-independent canonical JSON + SHA-256, a human-readable table, and a reconciliation summary.

- Ships a --dry-run-only CLI surface; no other mode is accepted.

## Why it's needed

The Q4 2026 Budget Bot rollout covers 21 entities (9 BU + 12 CF). Before any document is created, permission is granted, campaign row is written, or email is sent, we need a reviewable, reproducible candidate that a human can approve — one that fails closed on every ambiguous or missing input rather than guessing (e.g. picking the "newest" of several prior-quarter documents, or silently falling back to blank when a source search actually failed).

## Changes

- entities.py — active roster (BusinessUnit minus INACTIVE_BUS), plus a checked-in, reviewed APPROVED_EXCLUSIONS hook. A stale or duplicate exclusion entry surfaces as a missing_entity / duplicate_entity finding rather than being silently applied or ignored.

- recipients.py — drafts recipients via budget_bot.access_control.get_owner_emails_for_bu (the canonical KLAIR-3219 mapping — Colin Guilfoyle's exact address for AI Engineering & Builder Team comes from this function, not a local special case). Distinct missing_owner / invalid_recipient findings.

- sources.py — fail-closed Q3 seed-strategy resolution behind an injected Q3SourceReader protocol (mirrors find_prior_docs's shape without touching DynamoDB/Drive). Zero candidates → blank_no_prior with recorded evidence; exactly one → roll_forward with the exact doc id/revision; multiple distinct documents, conflicting revisions for the same document, malformed rows, or an inaccessible search each block with a distinct finding code and never auto-select or fall back to blank.

- targets.py — Q4 target-source mapping behind an injected Q4TargetReader protocol, using the existing resolve_bu_name alias resolver. Distinct missing_q4_source, alias_conflict (same entity, disagreeing alias rows), and duplicate_target_document (two different entities, same target) findings.

- manifest.py — ProvisioningManifest/ManifestRow models; canonical_json() sorts rows and findings before dumping (with sort_keys=True) so the SHA-256 digest is stable regardless of input row order or repeated runs; render_table() for human review; reconciliation_summary() accounts for every entity as ready/excluded/blocked.

- preflight.py — build_provisioning_manifest(*, year, quarter, q3_reader, q4_reader, approved_exclusions=...), the single orchestrator. Both readers are always caller-injected; this package ships no network-backed reader implementation.

- cli.py — --dry-run-only argparse surface; --execute and omitting --dry-run both exit 2 with a clear message before any manifest is built.

The returned manifest is the sole authority a future provisioning/send step should consult — not EMAIL_TO_BU_MAP or either raw reader output directly.

## Breaking changes

None — this is a new, self-contained package with no changes to existing modules.

## Risks and mitigations

- Risk: a future caller could wire a network-backed reader that leaks a real Drive/DynamoDB call into what looks like a "preflight". Mitigation: both Q3SourceReader and Q4TargetReader are Protocols with no shipped implementation, and test_provisioning_side_effects.py patches every known write/network seam (boto3 client/resource construction, DynamoDBWizardStorage, gdoc_sync clone/sync, outbound sockets/DNS) to raise on first use, then asserts the full preflight still completes.

- Risk: the fail-closed policy in sources.py/targets.py could be loosened later to "just pick one" under rollout time pressure. Mitigation: each fail-closed branch has a focused, named test (test_provisioning_sources.py, test_provisioning_targets.py) asserting the specific finding code fires and that no strategy/target is set alongside it.

- Risk: the checked-in APPROVED_EXCLUSIONS mechanism could be misused to silently drop entities. Mitigation: it ships empty, requires a non-empty reason per entry, and a stale/duplicate entry produces a missing_entity/duplicate_entity finding instead of applying silently.

## Test plan

Focused provisioning tests (all new, all passing):

cd klair-api
uv run pytest tests/board_doc/test_provisioning_entities.py tests/board_doc/test_provisioning_recipients.py \
tests/board_doc/test_provisioning_sources.py tests/board_doc/test_provisioning_targets.py \
tests/board_doc/test_provisioning_manifest.py tests/board_doc/test_provisioning_preflight.py \
tests/board_doc/test_provisioning_cli.py tests/board_doc/test_provisioning_side_effects.py -v
# 63 passed

Full board_doc suite (regression check, network-denied by the existing autouse fixture):

uv run pytest tests/board_doc/ -q
# 3627 passed, 2 deselected (the two allowlisted live-network integration tests), 111.90s

Ruff + Pyright, scoped to the new package:

uv run ruff format budget_bot/board_doc/provisioning/ tests/board_doc/test_provisioning_*.py --check
uv run ruff check budget_bot/board_doc/provisioning/ tests/board_doc/test_provisioning_*.py
# All checks passed!
uv run pyright budget_bot/board_doc/provisioning/
# 0 errors, 0 warnings, 0 informations

test_provisioning_side_effects.py specifically patches boto3.client/boto3.resource, DynamoDBWizardStorage.save/_ensure_table_exists, gdoc_sync.clone_google_doc/sync_to_google_doc, and outbound sockets/DNS to raise on first use, then asserts the full preflight (and CLI dry-run) still completes — proving no Drive write, permission change, session/DynamoDB campaign write, SES send, or network call occurs. It also asserts services.budget_notification_service (which constructs a live SES client at import time) is never imported as a side effect of building a manifest.

- [x] Focused provisioning tests pass (63/63)

- [x] Full tests/board_doc/ suite still passes (3627/3627, 2 deselected)

- [x] Ruff format/check clean on all new files

- [x] Pyright clean on the new package (tests excluded from pyright per repo config)

- [ ] Manual/computer-use testing — not applicable; this is a pure backend/CLI change with no UI surface

## Follow-ups

- A future ticket must implement production, network-backed Q3SourceReader/Q4TargetReader implementations (e.g. wrapping find_prior_docs-equivalent search and a real target-source registry) — deliberately out of scope here.

- Actual provisioning execution (creating documents, granting permissions, writing campaign rows, sending mail) driven off a *reviewed* manifest is a separate, later ticket.

Closes KLAIR-3246

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-00bf4a2d-59dc-4c68-bb9e-1077ba43d958?cursor_ref=pr_footer&cursor_cta=open_in_web"><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-00bf4a2d-59dc-4c68-bb9e-1077ba43d958&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><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>

<!-- CURSOR_AGENT_PR_BODY_BEGIN -->

## Summary

- Adds D2.2 (forecast_vs_actual_lookback), a coaching/forecast-accountability review check that compares each supported prior-quarter *stated target* (Total Revenue, EBITDA) against the metric's current-quarter *actual*, reporting the single largest signed deterioration.

- Introduces the typed, versioned dependency contract this check consumes (PriorQuarterTargetActual + DataSourceKey.PRIOR_QUARTER_TARGET_ACTUALS) so the check never has to parse narrative text to find a number.

- Registers the check through the existing @register / discover_checks() convention — zero edits to a hand-maintained registry.

## Why It's Needed

A prior plan's stated commitment (e.g. "we will hit $X revenue / EBITDA") and the resulting actual currently have no first-class comparison on the review rail — a BU can miss a target it stated last quarter with no automated call-out, so material forecast misses can go unexplained into the board doc. D2.2 makes that comparison explicit and auditable, mirroring the calibrated severity policy already proven out by C2.3 (plan-on-plan revenue) and C2.4 (plan-on-plan EBITDA).

Dependency note: the typed producer that actually populates prior-quarter stated targets from an upstream sheet/report (parsing + persistence) has not landed yet — that is tracked separately and is out of scope here. This PR ships the typed *contract* (PriorQuarterTargetActual) and the *consumer* (D2.2) so nothing has to change in the check once that producer exists; until then, PlanFinancials.prior_quarter_target_actuals is empty for every real plan and D2.2 reports a typed skip in production (proved by the endpoint test below).

## Changes

- budget_bot/board_doc/models.py: adds PriorQuarterTargetActual (fields: metric, target_value, actual_value, unit, prior_quarter, current_quarter, source provenance identifier, schema_version) and DataSourceKey.PRIOR_QUARTER_TARGET_ACTUALS.

- budget_bot/board_doc/canonical_plan.py: adds PlanFinancials.prior_quarter_target_actuals (defaults to []) and _coerce_prior_quarter_target_actuals (mirrors _coerce_rr_summary / _coerce_ar_aging), wired into build_canonical_plan. Deliberately not added to any _CANONICAL_*_KEYS set or data_orchestrator._FETCHER_MAP entry, so /review never asks the orchestrator to fetch this key for a real workbook — that avoids either crashing on a missing fetcher or building the not-yet-landed producer.

- budget_bot/board_doc/review_checks/forecast_vs_actual_lookback.py (new): check_forecast_vs_actual_lookback, registered as CHECK_ID = "D2.2", CHECK_AREA = "Coaching — Forecast Accountability", THEME_KEYS = ("forecast-accountability",). Bands mirror C2.3/C2.4 exactly (Total Revenue: pass ≥ -1.0%, warning -5.0%–-1.0%, critical < -5.0%; EBITDA: pass ≥ -2.0%, warning -10.0%–-2.0%, critical < -10.0%). Selects the metric with the most negative signed delta among usable comparisons; supporting_data["compared_metrics"] carries every supported metric's disposition (used or individually skipped, with its own reason) so the winning selection is auditable.

- budget_bot/board_doc/review_checks/_registry.py: adds the D2.2 citation-string entry to _CHECK_PROMPT_METADATA.

- Tests: new tests/board_doc/test_forecast_vs_actual_lookback.py (33 cases — skip ladder, both metrics' bands at every inclusive boundary and just past it, winner selection, supporting_data completeness); new coercion tests in tests/board_doc/test_canonical_plan.py; tests/board_doc/test_review_endpoint.py fixture now seeds PRIOR_QUARTER_TARGET_ACTUALS (D2.2 appears in the happy path) plus a dedicated test proving D2.2 alone degrades to a typed skip when that source is absent.

## Breaking Changes

None.

## Test Plan

- [x] uv run pytest tests/board_doc/test_forecast_vs_actual_lookback.py -v — 33 passed.

- [x] uv run pytest tests/board_doc/test_review_endpoint.py -v — updated/added cases (test_returns_findings_for_populated_session, test_skipped_checks_when_data_missing, test_partial_completeness_some_run_some_skip, test_partial_cached_data_package_is_topped_up, new test_forecast_lookback_skips_when_dependency_source_absent) pass; a pre-existing set of 6 tests in this file fail in this sandbox with "Google Sheets credentials not configured" regardless of this change (confirmed identical failures on main via git stash -u) — unrelated environment/credentials gap, not a regression.

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

- [x] uv run pyright on all changed source files — 0 errors, 0 warnings.

- [x] Narrowed suite: uv run pytest tests/board_doc/ — 3807 passed, 2 deselected, 0 failed (run twice for stability).

## Verification Artifact

Redacted critical Total Revenue finding (8% miss against a stated prior-quarter target):

{
"check_id": "D2.2",
"check_area": "Coaching — Forecast Accountability",
"severity": "critical",
"what": "Q2'26 actual Total Revenue (92000.0) is 8.0% below the Q1'26 stated target (100000.0); a 8000.0-unit miss.",
"preferred_action": "Explain the 8.0% miss against the Q1'26 stated Total Revenue target in MIPs / Risks.",
"supporting_data": {
"metric": "Total Revenue",
"target_value": 100000.0,
"actual_value": 92000.0,
"unit": "USD",
"source": "budget-bot-targets:<redacted-bu>:2026Q1",
"prior_quarter": "Q1'26",
"current_quarter": "Q2'26",
"delta_pct": -8.0,
"flat_band_pp": 1.0,
"critical_band_pp": 5.0,
"compared_metrics": [ { "metric": "Total Revenue", "status": "usable", "delta_pct": -8.0, "severity": "critical", "...": "..." } ]
}
}

Typed skip when the dependency source (KLAIR-2742-style producer) hasn't populated any records yet — the current production state for every real plan today:

{
"check_id": "D2.2",
"skipped": true,
"skip_reason": "no prior-quarter target/actual records available for this BU/quarter (upstream producer not yet wired)"
}

Both outputs were generated by directly invoking check_forecast_vs_actual_lookback against synthetic plans (see test_forecast_vs_actual_lookback.py for the full boundary-case matrix).

## Impact Estimate

Business value: Makes a prior plan commitment and the resulting actual comparable in the review rail, so material forecast misses cannot remain unexplained.

Pre-AI estimate: 3 points — new dependency-bound data contract consumption, metric-specific severity logic, registry plumbing, and boundary-heavy tests.

Closes KLAIR-2743

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-16d92b14-18ef-4e6d-b5a0-fe26745189f0?cursor_ref=pr_footer&cursor_cta=open_in_web"><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-16d92b14-18ef-4e6d-b5a0-fe26745189f0&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><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>