## Summary
- add an on-demand ECS pipeline that generates native Google Docs school performance reports from six coherent education finance marts
- preserve the approved report topology, styling, tables, evidence register, permissions, and configurable consolidated email delivery
- add bounded Anthropic research over posting, budget, payroll, and full transaction evidence with an independent final audit and immutable retained receipts
- correct the owning marts for full-month cost phasing, ten-month tuition phasing, Timeback treatment, rent account 62200, and downstream refresh ordering
- isolate failures by school so valid reports remain available when another school has a data or research failure
## Business Value
Finance can generate the detailed school performance report through Surtr without depending on Klair's container action. The pipeline creates a reviewable native Google Doc, grounds its insights in retained source evidence, prevents incomplete inputs or unsupported narratives from being published, and gives operators one completion email with successful links and exact school failures.
## Live Validation
### Scottsdale baseline
- deployed only Pipeline-school-performance-reports-prod from the candidate branch with --exclusively; the deployed task uses revision 15 and image digest sha256:6e87e9505018d4e01f4f13546ff26a0d9467753c3637f19165c5c6014c566b38
- refreshed the required upstream marts through the separately authorized Aerie and unit-economics pipelines
- [Alpha Scottsdale](https://docs.google.com/document/d/1nPlodCp4EMQCCWG52ug3k89uE5_MBqlsxFrhuNQhYuI/edit) completed successfully: native readback, independent audit, accounting guard, exact private permissions, nine-page PDF visual review, email delivery, and lease release passed
### Eligible population
The full preflight evaluated 33 schools with nonzero published QuickBooks budgets:
- 9 passed the complete six-mart, deterministic render, and native reference checks
- 24 stopped before model research or document creation: 5 missing unit models, 10 unresolved facilities/Timeback allocations, 3 missing positive student counts, and 6 with no booked report-scope revenue reaching a nullable reconciliation defect
The nine-school ready-set run ced1e17c-9e6c-49fc-8576-6fb353ee5196 reached Step Functions SUCCEEDED with ECS exit code 0 and a partial_failure result. The consolidated email was sent only to Ashwanth and the lease was released.
| School | Result | Why |
| --- | --- | --- |
| Boston | Document created; visual rollout failed | Confidence paragraph spills onto a mostly blank page 10. |
| Chantilly | Passed | Clean nine-page report; sampled cover, per-student table, and evidence page pass. |
| Charlotte | Failed closed | Auditor used all 20,000 output tokens as reasoning and returned no structured verdict. |
| Dorado | Passed | Clean nine-page report; sampled cover, per-student table, and evidence page pass. |
| Palo Alto | Failed closed | Audit found transaction ID 658 mislabeled as document 658; evidence says document 301. Remaining token reserve could not cover correction plus fresh audit. |
| San Francisco | Failed closed | First audit caught class/description conflation. After correction, final audit rejected an unsupported higher-enrollment claim; both student counts were 34. |
| Santa Monica | Document created; visual rollout failed | Confidence paragraph spills onto a mostly blank page 10. |
| Scottsdale | Batch retry failed closed | Auditor used all 20,000 output tokens as reasoning without a verdict. The separately validated Scottsdale report above remains accepted. |
| The Woodlands | Document created; visual rollout failed | Confidence spill on page 10 and over-abbreviated per-student card metrics. |
All five created batch documents passed native topology/geometry, exact private permissions, approved final audit, retained PDF checksum, current PDF parsing, retained-versus-current page text, token cap, and evidence verification. Visual review found that the former PDF threshold did not reject longer paragraph-only spill pages. That validator gap and the nullable revenue defect are fixed in this PR; the remaining upstream readiness and model reliability work stays in the follow-up ticket.
### Review remediation
- all nine review findings were validated and fixed: private-note access, environment-scoped Drive folders, paragraph-only PDF spill detection, missing Timeback budget handling, pinned Ruff compatibility, nullable aggregate reconciliation, early delivery-role validation, independent template-contract drift detection, and structured negative audit coverage
- refreshed Aerie and reran the source/native preflight before the final candidate invocation
- the first strengthened-validator run failed closed on a real page containing findings 11–13; the report contract now keeps the ten highest-priority findings and bounds their title, body, and owner lengths
- final run 6c524c0f-837c-4a51-89b2-2c05c1ddbb05 succeeded on task definition revision 17 and image digest sha256:89bd66c35ffb323d410a74a30bce9fc9ff063ddf2c68d48aa3dd4d5dd3d2f5fd
- [final Scottsdale report](https://docs.google.com/document/d/1C5TyNuoAsmKMOvl11gQJb06vfMrFrgyVpQmqoZ1UbCk/edit) has nine visually reviewed pages; retained and current exports have identical normalized page text and pass the new layout gate
- Redshift confirms only surtr_school_reports_ro can select transaction-detail evidence; the document and School Performance Reports (prod) folder contain only the publisher owner and Ashwanth writer permissions
- the consolidated SES email was sent only to the configured test recipient
## Test Plan
- 107 school report tests
- 37 unit-economics/per-student contract tests
- 29 Aerie QTD contract tests
- Ruff on modified Python files
- git diff --check
- isolated candidate deployment and upstream refresh
- standalone Scottsdale live generation with all-page visual review
- 33-school preflight and nine-school live batch with per-school failure evidence
## Implementation Effort
An average engineer would likely need 4–6 weeks to trace the Klair implementation, define and correct the upstream finance contracts, build the Surtr infrastructure and evidence model, reproduce the native Google Doc layout, implement the bounded research/audit workflow, and complete live financial and visual validation.
## Follow-up work
The remaining all-school rollout fixes identified by population validation are intentionally outside this PR. They are tracked in [SURTR-1448](https://linear.app/builder-team/issue/SURTR-1448/harden-school-performance-reports-for-all-school-rollout) and will be carried forward in a separate follow-up PR. This PR remains the baseline Surtr migration and validation checkpoint.
## Linear
- Migration: https://linear.app/builder-team/issue/SURTR-1442/migrate-school-performance-reports-to-surtr
- Follow-up fixes: https://linear.app/builder-team/issue/SURTR-1448/harden-school-performance-reports-for-all-school-rollout