The Trilogy Times

## Summary

A1's sp_refresh_site_operational_metadata joined ISP data (classrooms, floor area, occupancy) via raw_sites.matterport_model_id directly -- a field written by Aerie's own EC2 write-back (matterport-from-isp-sync.ts) that's slated to retire once A7 (xref_site_matterport) is fully cut over. Reading it directly would mean this procedure silently freezes its ISP-derived fields the moment that write-back stops, while continuing to report "succeeded" — no error, no alert.

Not a straight swap. Verified against production (2026-08-31): xref_site_matterport alone resolves only 18 of the 40 sites the direct field resolves today — it deliberately quarantines ambiguous mappings rather than guessing. A pure swap would have silently dropped ISP data for 22 sites immediately. Ships instead as COALESCE(xref match, direct match): prefer the safer xref resolution, fall back to the direct field. Confirmed this recovers full 40-site coverage (18 via xref, 22 via fallback).

## Business Value

Closes a real, currently-live risk: A1 was one dependency-ordering mistake away from silently and permanently losing school-facility data (classroom counts, floor area, occupancy) the moment Aerie retires its old matterport sync, with no failure signal anywhere. Fixes it without any coverage regression today.

## Manual Effort Estimate

Proposing ~2-3 hours by hand (live data comparison to discover the coverage gap, designing/testing the fallback join, updating the test contract + README to this codebase's documentation standard) — Keval, please confirm/adjust.

## Test plan

- [x] uv run pytest — 63/63 passed

- [x] uv run ruff check / ruff format --check — clean

- [x] uv run python scripts/apply_ddl.py (dry run) — 25 statements, clean

- [x] Live Redshift comparison: direct-only = 40 matched, xref-only = 18 matched (0 gained over direct), fallback = 40 matched (18 via xref + 22 via fallback) — confirms zero regression

- [ ] Apply DDL to prod (CREATE OR REPLACE PROCEDURE, non-destructive) after merge — separate approval-gated step per this pipeline's existing rollout posture

Caller half of [AI-Builder-Team/mercy#56](https://github.com/AI-Builder-Team/mercy/pull/56).

⚠️ MERGE ORDER: mercy#56 must land first. A reusable workflow hard-fails when a caller passes a secret the callee hasn't declared.

## What changed

| | before | after |

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

| AWS credential | HEIMDALL_AWS_ENV dotenv blob | HEIMDALL_AWS_ACCESS_KEY_ID + HEIMDALL_AWS_SECRET_ACCESS_KEY |

| region | inside the blob | aws_region input — it isn't a secret |

## Why

The blob was provisioned with a correct key and still failed:

PartialCredentialsError: Partial credentials found in env, missing: AWS_SECRET_ACCESS_KEY

A leading space made that line fail the parser's key regex and it was skipped silently. The error then named the credential rather than the parse, sending the debugging at a key that was fine.

Two values never justified a format that could be got wrong. Nothing parses these now; GitHub masks each natively.

## After merge

gh secret set HEIMDALL_AWS_ACCESS_KEY_ID --repo AI-Builder-Team/Surtr
gh secret set HEIMDALL_AWS_SECRET_ACCESS_KEY --repo AI-Builder-Team/Surtr

Until then CloudWatch reads stay skipped — cleanly, exactly as before. HEIMDALL_AWS_ENV can then be deleted; nothing is lost with it, because that path never once produced a successful log fetch (boto3 was undeclared until this morning, and the parse failed after that).

## Business Value

Makes the credential impossible to paste wrong, on the one path whose entire job is explaining why a pipeline failed. The old design's cost was measured today: a full debugging round-trip chasing a key that was correct all along.

## Manual Effort Estimate

~30 minutes for the caller. *(Proposed by Claude — Keval to confirm.)*

Two changes to credential plumbing, both diagnosed from a live failure rather than a hypothetical.

## 1. The AWS blob becomes two discrete secrets

HEIMDALL_AWS_ENV was provisioned with a correct 40-character secret and the CloudWatch read still failed:

PartialCredentialsError: Partial credentials found in env, missing: AWS_SECRET_ACCESS_KEY

A single leading space made that line fail ^AWS_[A-Z_]+$, and || continue skipped it without a word. The blob half-loaded, boto3 got an id with no secret, and the error named the credential rather than the parse — so the debugging went at a key that was fine.

I inherited the blob pattern from HEIMDALL_REDSHIFT_ENV without asking whether it fitted, and it doesn't. Redshift carries five values and genuinely wants a blob. AWS carries two secrets and a region — and the region isn't a secret at all; keeping it in a credential blob only hid it from view.

Seventeen lines of parsing are gone. GitHub masks each secret natively and nothing sits between the secret and boto3.

Clean switch, not a fallback — there's nothing to migrate. That path has never once produced a successful log fetch: boto3 was undeclared until this morning, and the parse failed after that.

## 2. The Redshift blob keeps a hardened parser

Five values still warrant a blob, so that parser stays on the path — and must not fail silently either. Both key names are now trimmed of spaces/tabs/CR before matching, and a line that still doesn't match is warned about by key name, never by value.

Reproduced against same-shape fakes rather than guessed:

| blob variant | before | after |

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

| clean | parses | parses |

| CRLF | parses | parses |

| leading space | dropped silently | parses |

| tab-indented | dropped silently | parses |

| export FOO=... | dropped silently | warned by name |

## Why this matters beyond one paste

Same class as the missing boto3 two commits ago: the capability was configured, the failure was real, and nothing on the path said so. Half a credential loading in silence is worse than none loading — the error names the wrong culprit, so the person debugging re-checks something that was never the problem. Which is exactly what happened.

## Caller

Surtr side is [AI-Builder-Team/Surtr#1611](https://github.com/AI-Builder-Team/Surtr/pull/1611) — this must merge first, since a reusable workflow hard-fails on a secret the callee hasn't declared.

823 tests, ruff and actionlint clean.

## Business Value

Removes an entire class of misconfiguration from the AWS path rather than making it more forgiving, and converts the remaining blob's failures from silent into a one-line warning. The cost of the old design was measured today: a full debugging round-trip chasing a credential that was correct.

## Manual Effort Estimate

~2 hours, most of it reproducing the exact failure shape rather than patching the symptom. *(Proposed by Claude — Keval to confirm.)*

Linear: [AI-615](https://linear.app/builder-team/issue/AI-615/release-rollback-revert-forward-not-force-push)

Closes the gap [AI-605](https://linear.app/builder-team/issue/AI-605) left open. Merging the release PR is the deploy — so the job wasn't finished when the merge landed, it was finished when nothing had checked whether the deploy survived.

## Why not a force-push, which is what AI-605 originally specified

Surtr's production ruleset has non_fast_forward active with no bypass actors. Pushing back to the pre-release SHA is impossible for every actor, heimdall included.

So rollback is revert-forward: a revert commit travelling as a PR like any other change to that branch. CD re-runs, and because CDK is declarative, redeploying the previous tree *is* the infrastructure rollback.

The constraint produced a better design than the one it replaced — auditable, rewrites no history, needs no bypass granted to a bot.

## Every decision fails toward a human

| Situation | Behaviour | Why |

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

| CD run unreadable | rollback | production just changed and we can't confirm it survived — the least defensible moment to assume the best |

| still running past the window | failure | "still running after 30 minutes" is not evidence a deploy worked |

| cancelled | failed | unlike a cancelled CI check, a cancelled *deploy* left production half-applied |

| rollback already attempted | escalate | the rollback's own CD can fail; retrying turns one incident into several |

| revert conflicts | stop and notify | no improvising on production |

| unusable merge SHA | escalate | guessing which commit shipped is not a thing to do to production |

| GChat unreachable | wrapped | a notifier must never decide the outcome of a rollback |

-m 1 keeps the first parent — production as it was *before* the release merge. Without -m git errors; with -m 2 it would revert production instead of the release.

## Tests

32, of which five assert the workflow keeps the contract rather than just the module: the watch only runs when something actually shipped, no PAT fallback on the write path, no --force anywhere, the notifier can't decide the outcome, and a conflicted revert stops.

757 in the suite, ruff and actionlint clean.

## Merge conflict, resolved deliberately

This branch and #54 both appended to heimdall.yml. Order matters — the rollback steps are steps *of* the release job, so they must precede where the linear job begins. Verified after resolving: 11 jobs, release ends with the watch step, the linear job intact with its 8 steps.

## Still inert

HEIMDALL_RELEASE_ENABLED is unset and release enablement is on hold, so none of this runs. It merges as a no-op.

## Business Value

Without it, unattended release is only unattended while it works — the moment it fails it needs a human who may be asleep, and the deploy branch sits broken until they wake. This is the difference between automating the happy path and actually being able to leave the thing running.

## Manual Effort Estimate

~1 day — the revert mechanics are small; the care is in the failure modes (no loops, conflicted reverts, timeout-as-failure, an unreadable run counting against you). *(Proposed by Claude — Keval to confirm.)*

## Summary

Seeds gateway_sources for the 14 mart/core tables that already replace Aerie's EC2 sync workers (per the EC2-teardown tracking sheet), bundled under one new aerie entity for one-click key granting. Follows the exact pattern already shipped for ai-spend-raw (SURTR-885) — no new Gateway code, purely additive registration. No gwk_ key is issued by this PR.

All 14 target tables confirmed to exist and be visible under the pipeline warehouse role's grants (verified live via svv_tables, 2026-08-31).

## Business Value

Removes the last blocker to Aerie retiring its EC2 sync workers and direct Redshift credential: the data these workers/direct-reads consume is already live in Surtr (verified via the Pipeline Data Health API), but there was no API surface for Aerie to read it through. This makes that surface exist. Also surfaced, and flagged separately to the team: Aerie's contractor-pay sync (F1/F2) is silently querying a warehouse table that no longer exists — the tables registered here are the ready replacement.

## Manual Effort Estimate

Proposing ~3-4 hours by hand (cross-referencing 9 Aerie EC2 tasks against Surtr pipeline DDL to find real table names, verifying warehouse grants, writing/testing the seed script) — Keval, please confirm/adjust.

## Test plan

- [x] npx tsc --noEmit — clean

- [x] npx biome check src/seed-gateway-aerie.ts — clean

- [x] npx vitest run test/gateway/ — 38 passed (no gateway logic changed, sanity check only)

- [ ] Run pnpm run seed:gateway-aerie against prod after merge, verify all 14 sources + the aerie entity via the admin UI

Found while writing up where the two pending secrets should be pasted: both had nowhere to go.

The callee declares HEIMDALL_AWS_ENV and LINEAR_API_KEY and reads both, but this caller forwarded neither. Setting either secret would have changed nothing — silently, while looking done.

mode: linear also had no trigger at all. The existing :25 cron maps to release, so the queue sweep could never fire.

## What changed

| | Before | After |

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

| HEIMDALL_AWS_ENV | not forwarded | forwarded |

| LINEAR_API_KEY | not forwarded | forwarded |

| mode: linear trigger | none | :00/:15/:30/:45 cron |

| linear_assignee / _routing | unset | set |

Two crons in one workflow are told apart by github.event.schedule, which carries the expression that fired — the only way to distinguish them. The queue slot is deliberately off :25 so the two sweeps never contend, and polls more often because a ticket queue is a person's working day rather than a deploy cadence.

Routing stays configuration and is never derived from ticket content: a ticket must not be able to aim Heimdall at a repo by naming one.

## Still inert

- absent LINEAR_API_KEY → the queue sweep skips cleanly; it's meant to sit dormant until provisioned

- absent HEIMDALL_AWS_ENV → log requests are skipped, diagnosis carries on with what it has

- both additionally gated behind HEIMDALL_LINEAR_ENABLED and the repo-wide kill switch

So this merges as a no-op and stays one until someone sets a variable.

## Business Value

This is the difference between "the feature is built" and "the feature can be turned on". Without it the next person to set those secrets would have seen nothing happen and no error explaining why — the worst kind of dead end, because everything upstream reports success.

## Manual Effort Estimate

~1 hour. *(Proposed by Claude — Keval to confirm.)*

## Summary

- Reload the jointly published School reporting period after a successful shared upstream refresh.

- Pass the refreshed period and cutoff to School report generation instead of the pre-refresh snapshot.

- Add regression coverage for the stale-cutoff race.

## Business Value

Prevents the combined School & Education QTD workflow from failing every School report when the upstream refresh advances the School marts to a new published cutoff. This allows refreshed School reports, including Alpha New York and Scottsdale, to generate from the snapshot that actually exists.

## Implementation Effort

An average engineer would likely need about 1–2 hours to trace the refresh and School-generation sequencing, reproduce the stale-cutoff contract mismatch, implement the reload, add regression coverage, and run focused backend validation.

## Test Plan

- [x] uv run ruff format services/monthly_qtd_report/combined_performance_report.py tests/monthly_qtd_report/test_combined_performance_report.py

- [x] uv run ruff check services/monthly_qtd_report/combined_performance_report.py tests/monthly_qtd_report/test_combined_performance_report.py

- [x] uv run pyright services/monthly_qtd_report/combined_performance_report.py

- [x] ADMIN_TOKEN_SECRET=test-only-secret uv run pytest --import-mode=importlib tests/monthly_qtd_report/test_combined_performance_report.py — 16 passed.

- The full monthly QTD feature suite also passed locally: 945 passed, 7 deselected.

- The repository default pytest configuration excludes integration, eval, and allow-network tests; RedshiftHandler is globally mocked, so SQL correctness against the live schema is not covered by pytest.

## Linear

- KLAIR-3470: https://linear.app/builder-team/issue/KLAIR-3470/fix-combined-school-qtd-cutoff-after-upstream-refresh

## Context

- Follow-up to merged PR #3672, which handled nullable unmapped QuickBooks account categories.

- The updated worker image was already published to ash-dev for the regeneration test.

Linear: [AI-603](https://linear.app/builder-team/issue/AI-603/p41-linear-work-queue-poll-kevals-today-tickets) · stacked on #52 and #53 — merge those first.

The wiring that makes the queue and the callout protocol actually run. This is the last build piece of the software factory.

## A bridge, not a second pipeline

mode: issue already knows how to read an ask, decide whether a change is warranted, and deliver only when it is. Duplicating that for tickets would give the factory two intake paths to drift apart. So this does the smallest connecting thing:

pick a ticket → open a GitHub Issue carrying it → attach that Issue back to the ticket.

Everything downstream is the machinery that already exists.

## The attachment is the claim

Not a comment saying there should be one. linear_queue.is_claimed reads exactly that attachment, so writing it back is what stops the next sweep re-picking the ticket.

It's written immediately after the Issue exists and raises on failure: two agents on one ticket is the failure that matters, and an Issue missing its ticket link is trivially fixable next to that.

## Single-flight, as #52's docstring demands

#52 said single-flight is a requirement on the caller, because a claim written inside the module would still race between its own read and write. This is the caller meeting it — a constant concurrency group for linear mode, the only lock spanning the whole read-decide-write cycle.

A test asserts the workflow actually meets the contract, so a later edit can't quietly drop it.

## Ticket text is data

The Issue body quotes it inside a fence, labels it QUOTED MATERIAL, and states plainly that nothing inside grants scope or lifts a guard.

A ticket containing its own closing fence is neutralised with a zero-width space — otherwise an injected instruction escapes the quoting that's meant to defang it. Pinned by a test that checks the only bare fence in the body is the one closing the block.

The key holds to two steps, and no agent runs in this job at all.

## Inert until you want it

| Switch | Effect |

|---|---|

| TRIAGE_AGENT_RUN_ENABLED | repo-wide kill switch, unchanged |

| HEIMDALL_LINEAR_ENABLED | queue mode off by default |

| LINEAR_API_KEY absent | plain skip, not a failure — the feature sits dormant until provisioned |

| assignee/routing unset | refuses rather than guessing whose queue to work |

## Blast radius

Three mutations exist — attach, comment, set-state — and a test fails if a fourth appears, so what the key can do stays readable in one place. issueDelete, issueArchive and projectDelete are explicitly asserted absent.

640 tests, ruff clean.

## Business Value

Completes features 4 and 6 of the software factory. Heimdall gets a second work source — a person's actual queue, not just pipeline alarms — reusing the entire existing intake path rather than growing a parallel one. The design choice that matters is the bridge: it means ticket-driven work inherits every guard, every review, and every merge rule that failure-driven work already has, for free and permanently.

## Manual Effort Estimate

~5 hours — the job is largely boilerplate mirroring the release job; the time went into the claim ordering, the fence escaping, and asserting the single-flight contract from the test suite rather than trusting the comment. *(Proposed by Claude — Keval to confirm.)*

Reframes /heimdall around what got done, what set it off, and where it stands — without changing what any number means.

## Factory status replaces the Fix funnel

Same five values, read as a process rather than a staircase: backlog → in progress → in review → verified on one horizontal rail, with the two exits called out beneath it.

Rework and blocked are deliberately *not* on the rail. They aren't stages — they're where work leaves the forward path, and putting them in line would imply work flows through them.

| Phase | Source |

|---|---|

| Backlog | diagnosed + skipped — arrived, nothing built |

| In progress | attemptedFix |

| In review | prsOpened |

| Verified | verifiedGreen |

| ↩ rework | modeCounts.revise + avg rounds |

| ⤓ blocked | needsHuman + failed |

It reuses the funnel numbers the page already computes, so the timeline and the distributions below it can never disagree — same values, rendered twice. Counts stay monotone by construction (each phase counts work that reached *at least* that far), so the rail can't widen as it advances.

## "What set it off" — the dimension the page never had

mode in plain language: pipeline alarm, human ask, review feedback, housekeeping, release sweep, ticket queue.

Volume and outcome alone never explained a day's output. A run from a prod alarm and a run from someone's ticket are different work judged against different criteria, and until now the page couldn't tell you which you were looking at.

## Everything else is untouched

Day charts, the repo / outcome / fix-class breakdowns, the runs table, and the run drawer with its focus handling all stay exactly as they were.

## One unrelated change, deliberately kept

.gitignore now ignores /.clerk/. Running the app locally makes Clerk write that directory in keyless mode, it can contain secrets, and it wasn't ignored. Two lines against committing a credential seemed worth carrying here rather than leaving the hazard for whoever ran the dev server next. Happy to split it out if you'd rather.

## Verification

next build — compiles clean, /heimdall present in the route list. biome check clean.

Note that tsc -p tsconfig.json reports tRPC router-collision errors on this page — those are pre-existing and repo-wide (mercy, identity, search, relationships, pipelines all show them), not introduced here.

## Business Value

The page reported *volume and outcome*; it could not answer the two questions actually asked of it — what is the factory working on right now, and what put it there. Provenance in particular changes how the numbers read: a low fix rate on alarm-driven work means something very different from a low fix rate on ticket-driven work, and the old view collapsed both into one bar.

## Manual Effort Estimate

~3 hours. *(Proposed by Claude — Keval to confirm.)*

Linear: [AI-603](https://linear.app/builder-team/issue/AI-603/p41-linear-work-queue-poll-kevals-today-tickets)

Feature 4's foundation: Heimdall's second work source. Pipeline failures arrive as events; tickets don't — something has to go and look. This is the looking.

Pure logic and the network seam only. No workflow wiring, no mode: linear, nothing runs yet. That follows separately so each piece stays reviewable.

## The credential boundary, same as fetch_linear_context.py

The key lives in this trusted step and nowhere near the agent. The agent's input is untrusted text, so a credential in its process environment is one a prompt injection can reach. The query travels; the credential does not.

## Ticket text is data, not instructions

Anyone in the workspace can write a Linear issue, so a ticket body reaches the agent the way a CloudWatch log line does — material to reason about, never a directive that can widen scope or skip a gate.

Three concrete consequences in the code:

- Routing is configuration, never derived from ticket content. A ticket can't aim Heimdall at a repo by naming one.

- The identifier regex is anchored and case-sensitive. see surtr-1 for context in a body is not an identifier.

- Truncation is visible. A cut-off description says so, so the agent can tell "the ticket said no more" from "the ticket was cut off".

## The failure this is designed against

Picking up the wrong ticket. A wasted diagnose run is cheap; a PR opened against someone else's work, on a repo the ticket never named, is not.

| Situation | Behaviour |

|---|---|

| malformed response | raises — "could not read the queue" must never round to "the queue is empty" |

| ticket already has a PR attached | claimed, skipped — two agents can't open two PRs for one ticket |

| two runs race on one queue | sorted selection, so they agree on what's next |

| unrouted team key (AI-, AERIE-) | ignored, never defaulted to some repo |

| individual malformed entries | skipped, not fatal |

Assignee and state are filtered server-side, so the key never pulls a whole workspace back and a large workspace costs what a small one does. Redirects are refused — following one re-sends the raw key to whatever host the redirect names.

## A test that was testing the wrong thing

One test asserted "Bearer" not in inspect.getsource(...) to check the key is sent raw. It failed — because the source contains a *comment* saying not to use Bearer. It now asserts on the Request the client actually builds, plus a second test that the key never reaches the URL (where it would land in logs, proxies, and referrers).

32 tests, 575 in the suite, ruff clean.

## Note on overlap with #13

[#13](https://github.com/AI-Builder-Team/mercy/pull/13) (open since 2026-07-30) builds harness/fetch_linear_context.py with the same client shape for Mercy's *review context*. This is a different consumer — a work queue, not reference docs — and I deliberately didn't build on an unmerged month-old branch. The two LinearClients are worth consolidating once #13 lands; noting it rather than pre-emptively coupling them.

## Business Value

Feature 4 of the software factory: Heimdall works Keval's ticket queue, not just pipeline alarms. This is the half that decides *what* to work on, and it is the half where being wrong is expensive — hence the fail-closed selection. It's also inert until the key exists, so it can land and be reviewed on its own.

## Manual Effort Estimate

~4 hours — the GraphQL is small; the time is in the selection semantics (claiming, determinism, refusing to guess) and their tests. *(Proposed by Claude — Keval to confirm.)*

Linear: [AI-604](https://linear.app/builder-team/issue/AI-604/p42-callout-protocol-ask-on-linear-block-the-ticket-keep-working)

Feature 6: when Heimdall is genuinely stuck on a ticket, it asks — once, specifically, without stalling the queue. Pure logic only; the Linear mutations and the mode wiring follow separately.

## The bar, and why it's this high

Keval's constraint was *"make sure it's a genuine request and not just permission things."* The failure to design against is an agent that asks permission for everything and calls it collaboration.

A callout that could have been answered by reading the repo is worse than no callout: it costs a human's attention, it trains them to skim, and the next one — the real one — gets skimmed too.

So the taxonomy is explicit rather than left to judgement:

| Genuine — a human holds something the repo doesn't | Deferrable — answerable by looking |

|---|---|

| secret — a credential that must be minted or granted | permission — asking to do what the ticket asked for |

| decision — a business call with materially different outcomes | preference — two approaches that both satisfy the ticket |

| contradiction — ticket and code disagree on a fact | verifiable — checkable in the repo, warehouse, or CI |

| destructive — irreversible action needing sign-off | confidence — "I'm not sure" with nothing specific behind it |

| access — a system Heimdall can't reach at all | |

## The claimed kind isn't trusted on its own

An agent that wants to ask will reach for whichever label gets it asked. So the reason is checked too — a secret whose reason reads "should I", "not sure", or "would need to check" is refused as answerable:

classify("secret", "I am not sure whether the column is nullable...")
-> CalloutRefused: secret: reason reads as answerable ('not sure') — look, do not ask

classify deliberately never consults the agent's own confidence. "I am unsure" is the state a capable agent resolves by looking, not by asking.

A reason under 40 characters is refused too. A real blocker can be stated specifically; a one-liner is nearly always a permission ask wearing a better label.

## One trap worth naming in the reply-reading

is_unblocked compares against the time Heimdall asked, not merely "a human comment exists". A ticket with prior discussion would otherwise read as answered the instant the question was posted — and resume against a comment written *before* the question existed. Not knowing when we asked also counts as still blocked, rather than resuming on a guess.

## Protocol

Comment → set Blocked → move straight to the next ticket. Never wait. A reply is picked up on a later poll. The queue is never held by one stuck item.

29 tests, most of them about refusing. 572 in the suite, ruff clean.

## Business Value

This is what makes an autonomous queue-worker safe to leave running. Without a high bar, an agent with write access to Linear becomes a notification generator and people stop reading it — at which point the genuine blocker, the one that actually needs Keval, is indistinguishable from the noise. The value is in the refusals, not the callouts.

## Manual Effort Estimate

~4 hours — the code is small; the taxonomy and the reply-timing semantics are where the thought went. *(Proposed by Claude — Keval to confirm.)*

Automated fix for collections-tracker-sync-v2 — fix_class code_fix, scope tier draft.

Resolves https://github.com/AI-Builder-Team/Surtr/issues/1606

> Ready for review — verification is green; HEIMDALL_READY_PRS opens verified tier-draft fixes ready for review. A human still merges — auto-merge never applies outside tier auto.

## What's broken

Run 078ab7c4-c539-4586-bdb8-d0b7219412ff of collections-tracker-sync-v2 died on the second of eight tracker tabs with StructuralError: Tracker 'GFI': missing required header(s) ['invoice_balance', 'payment_status'] in the left block (found: ['Customer Name', 'Class', 'Invoice Number', 'Actual Due Date', 'Expected Collection Date', 'Old Expected Date']), raised at pipelines/runners/collections-tracker-sync-v2/src/parsers.py:204. This is the already-documented transient blank-header-cell mode, not new sheet drift: the GFI tab's real left block is 10 columns wide (tests/test_handler_transient_header.py:28 pins it), and the six headers the parser did find are exactly indices 0-5 of that block, which means the cell at index 6 — ' Invoice Balance ' — came back as an empty string on an otherwise-successful HTTP 200, so _left_block_width() (src/parsers.py:160) cut the block at the first blank cell and everything past it looked missing. Had the columns genuinely been deleted from the sheet, Collection Date and Comments would have shifted left into indices 6-7 and appeared in the found: list; they did not. The mitigation added by PR #968 fired and lost: the log shows structural error on attempt 1/3 ... re-reading in 2.0s and attempt 2/3 ... re-reading in 4.0s, then the run gave up after a total Duration: 7987.94 ms. Because parse_tracker raises inside fetch_and_parse (src/handler.py:26) before RedshiftLoader.full_replace is ever reached, the run wrote zero rows and never even read the six remaining tabs; staging_finance_gsheets.collections_tracker_invoices is intact but frozen at the last good 2-hourly load, so Klair's till-date collections view silently serves stale invoice balances and payment_status values until a later run succeeds.

Root cause. read_parse_with_retry in pipelines/runners/collections-tracker-sync-v2/src/google_client.py:74 still carries the original, too-small retry budget max_attempts: int = 3, base_delay: float = 2.0 with no delay cap, giving the transient only 2s + 4s = ~6 seconds to clear before the StructuralError propagates and fails the whole run. The identical defect was already diagnosed and fixed on the sibling runner: PR #1376 (2041107f, fix(collections-collectiq-sync-v2): widen transient #VALUE! retry budget) raised collections-collectiq-sync-v2 to max_attempts=8, base_delay=2.0, max_delay=30.0, and its docstring records the proof — collectiq failed after exhausting 3 attempts at 2026-08-17T18:15:22Z and then succeeded with zero retries at the very next scheduled run 2h later, because the source sheet's cross-sheet formula recalculation outlasts a few seconds of backoff. That widened budget was never back-ported to collections-tracker-sync-v2, which is ironically the runner where this failure mode was first reproduced live (2026-07-27 09:02:20Z, Khoros header width 5 not 10). The root cause is therefore a missing back-port of a reviewed and merged fix, not a defect in parse_tracker's header logic — the parser is behaving correctly by refusing to guess a column position, and the structural guard must stay loud so a genuine rename is never retried away.

## What this PR changes

Back-port the exact PR #1376 change into pipelines/runners/collections-tracker-sync-v2/src/google_client.py: change read_parse_with_retry's defaults to max_attempts: int = 8, add a max_delay: float = 30.0 parameter, and cap the backoff with delay = min(base_delay * (2**attempt), max_delay). The cap is the load-bearing half, not an ornament — uncapped exponential backoff over 8 attempts would sleep 2+4+8+16+32+64+128 = 254s and simply trade a StructuralError for a Lambda timeout, whereas the cap holds the worst case at 2+4+8+16+30+30+30 = 120s, comfortably inside this pipeline's timeout_seconds: 300 (the same 300s ceiling collectiq runs under). No timeout bump is needed: only one tab can ever exhaust the full budget, because exhausting it raises and ends the run, and a healthy full pass over all eight tabs takes ~8s. Do not touch _left_block_width or parse_tracker — widening the block would not recover a header whose text is blank, and loosening the required-header check would convert a loud failure into the silent partial load this repo cares most about avoiding. Add a test to tests/test_handler_transient_header.py covering recovery on an attempt beyond the old 3-attempt budget, and keep test_genuine_rename_still_fails_after_retries green so real drift still fails loudly.

Why this fixes it. This is a code change confined to the failing pipeline's own directory that ports a fix already reviewed and merged for the identical failure mode on a sibling runner, which makes it the lowest-risk option available: the diff is three lines of parameters plus one min() in src/google_client.py, and it leaves every structural guard, the parser, and the loader untouched. The blast radius is deliberately narrow — a longer retry window only ever delays a run that was going to fail anyway, and because test_genuine_rename_still_fails_after_retries still asserts that a real column rename propagates after the retries are spent, the change cannot mask genuine sheet drift into a silent partial load. Leaving it alone costs a failed 2-hourly run and a stale collections table every time Google's Sheets API blanks a header cell for more than six seconds, which the collectiq incident showed can last until the next scheduled run. The reviewer should confirm the worst-case sleep arithmetic against timeout_seconds: 300 in pipeline.json and check that the new test genuinely exercises an attempt index past 3 rather than passing under the old budget; note also as follow-up (deliberately out of scope here) that collections-target-forecast-sync-v2 and benchmark-refdata-sync still vendor the old max_attempts: int = 3 copy and will hit this same wall.

### Files changed

 .../src/google_client.py                           | 13 +++++++++--
.../tests/test_handler_transient_header.py         | 27 ++++++++++++++++++++++
2 files changed, 38 insertions(+), 2 deletions(-)

## Verification

### pytest (pipelines/runners/collections-tracker-sync-v2/tests) — exit 0

``

============================= test session starts ==============================

platform linux -- Python 3.11.16, pytest-9.1.1, pluggy-1.6.0 -- /opt/hostedtoolcache/Python/3.11.16/x64/bin/python

cachedir: .pytest_cache

rootdir: /home/runner/work/Surtr/Surtr/publish/pipelines/runners/collections-tracker-sync-v2

configfile: pyproject.toml

plugins: mock-3.15.1

collecting ... collected 22 items

tests/test_contract.py::test_identity_is_v2_and_scheduled PASSED [ 4%]

tests/test_contract.py::test_targets_new_gsheets_schema PASSED [ 9%]

tests/test_contract.py::test_isolated_s3_prefix_and_iam PASSED [ 13%]

tests/test_handler_tracker.py::TestTrackerHandler::test_all_tabs_quark_becomes_zax PASSED [ 18%]

tests/test_handler_transient_header.py::TestTransientHeaderRetry::test_transient_blank_invoice_balance_recovers_on_reread PASSED [ 22%]

tests/test_handler_transient_header.py::TestTransientHeaderRetry::test_transient_on_khoros_index_five_also_recovers PASSED [ 27%]

tests/test_handler_transient_header.py::TestTransientHeaderRetry::test_transient_lasting_past_old_three_attempt_budget_recovers PASSED [ 31%]

tests/test_handler_transient_header.py::TestTransientHeaderRetry::test_genuine_rename_still_fails_after_retries PASSED [ 36%]

tests/test_handler_transient_header.py::TestTransientHeaderRetry::test_exhausted_budget_stays_inside_the_lambda_timeout PASSED [ 40%]

tests/test_handler_transient_header.py::TestTransientHeaderRetry::test_healthy_sheet_reads_each_tab_once PASSED [ 45%]

tests/test_parsers_tracker.py::TestParseTracker::test_columns_constant PASSED [ 50%]

tests/test_parsers_tracker.py::TestParseTracker::test_skyvera_left_block_only PASSED [ 54%]

tests/test_parsers_tracker.py::TestParseTracker::test_khoros_no_class_extra_compliance_ignored PASSED [ 59%]

tests/test_parsers_tracker.py::TestParseTracker::test_missing_required_header_raises PASSED [ 63%]

tests/test_parsers_tracker.py::TestParseTracker::test_no_header_row_raises PASSED [ 68%]

tests/test_parsers_tracker.py::TestParseTracker::test_values_are_whitespace_stripped PASSED [ 72%]

tests/test_parsers_tracker.py::TestParseTracker::test_header_row_found_by_content_not_position PASSED [ 77%]

tests/test_parsers_tracker.py::TestParseTracker::test_totals_row_with_blank_customer_is_dropped PASSED [ 81%]

tests/test_parsers_tracker.py::TestParseTracker::test_header_found_but_zero_data_rows_raises PASSED [ 86%]

tes …_(truncated)_

<details>

<summary>Run metadata</summary>

| Field | Value |

| --- | --- |

| Pipeline | collections-tracker-sync-v2 |

| Failing run | 078ab7c4-c539-4586-bdb8-d0b7219412ff |

| Occurrence | 1 (times this exact failure signature has been seen) |

| Signature | 45fc0bf374398d85b20a54ff597bf0790d16f2796f8d84bafa177f30eba9b216 |

| Verify | green |

</details>

---

🤖 Opened by heimdall. mercy reviews this PR automatically; heimdall revises on REQUEST_CHANGES (bounded rounds). Tier-auto PRs may auto-merge on mercy approval when the consumer enables it; everything else waits for a human. Mention heimdall in a comment to direct it, or add the manual-dev` label to take the PR over and stop it entirely.

Automated fix for renewals-risk-assessment — fix_class code_fix, scope tier draft.

Resolves https://github.com/AI-Builder-Team/Surtr/issues/1603

> Ready for review — verification is green; HEIMDALL_READY_PRS opens verified tier-draft fixes ready for review. A human still merges — auto-merge never applies outside tier auto.

## What's broken

Run 2a1222fa-13c8-4567-b34e-f99ca4b3ffa2 of renewals-risk-assessment reported 763/763 assessed and 100% success, but three renewals in batches 2 and 7 first failed with modules.risk_assessment - ERROR - Failed to parse structured response: 1 validation error for ActiveRenewalAssessment / Invalid JSON: EOF while parsing a string at line 1 column 17659. That error is not schema drift: the JSON ends mid-string at ~17,659 characters (≈4.3k tokens), which is exactly the max_tokens=4096 ceiling set on the Claude call at pipelines/runners/renewals-pipeline/modules/risk_assessment.py:314, so the model's structured output was cut off by the output-token limit and pydantic then refused the incomplete JSON. This run lost no rows — the three renewals (006fu00000AYLkEAAX, 006Ih000004fjkaIAA, 0062x00000EZsBvAAL) succeeded on retry attempt 1 and their flags were cleared — but the failure was invisible to every downstream signal: the ERROR line does not name the affected renewal, the catch-all at risk_assessment.py:357-360 flattens truncation and genuine schema mismatch into one opaque string, and the __RISK_ASSESSMENT_RESULT__ marker emitted by _emit_result_marker in risk_assessment_container/app.py:932 carries only {total, successful, failed} with no truncation count for _classify_status in pipelines/runners/renewals-risk-assessment/src/main.py to act on.

Root cause. anthropic_client.beta.messages.parse(...) in generate_risk_assessment (pipelines/runners/renewals-pipeline/modules/risk_assessment.py:312-318) is called with max_tokens=4096, which is too low for the tail of the ActiveRenewalAssessment schema in modules/pydantic_schemas.py. That schema has five unbounded string-list fields (positive_signals, negative_signals, key_individuals, next_steps, churn_risks) plus several free-text explanations; a typical response is ~3.2 KB (see risk_assessment_container/sample_risk_assessment_active_schema.json), but a renewal with a long description and activity history produces a far larger one, and the three failures were each cut off at ~17.6 KB — the 4,096-token wall. Because structured-output JSON is emitted as one string, hitting that wall always yields unterminated JSON and a pydantic Invalid JSON: EOF while parsing error rather than a partially-valid object, so the truncation surfaces as a generic parse failure. The second half of the root cause is observability: the inner except Exception at risk_assessment.py:357 logs error_msg without renewal.sf_opportunity_id, so a reader cannot tell which renewal was degraded, and no truncation counter reaches the run summary, meaning the ceiling can be hit on every run without the pipeline ever reporting anything but green.

## What this PR changes

Two coordinated changes, both inside the renewals pipeline code the container reuses. First, raise max_tokens on the beta.messages.parse call at pipelines/runners/renewals-pipeline/modules/risk_assessment.py:314 from 4096 to 16384 — claude-sonnet-4-5 supports up to 64k output tokens, so 16384 gives roughly 4× headroom over the observed 17.6 KB truncation point while still bounding a runaway response; because max_tokens is a ceiling and not a target, this does not lengthen or slow normal responses. Second, make truncation legible rather than swallowed: in generate_risk_assessment, classify an unterminated-JSON validation error (Invalid JSON / EOF while parsing) as a distinct truncation error, tag the returned error string with a stable prefix, and include renewal.sf_opportunity_id in the logger.error line so the affected renewal is named. Then have risk_assessment_container/app.py count those tagged errors across the initial pass and all retry attempts and add truncated_responses to the _emit_result_marker payload at app.py:932-938; that dict flows verbatim through write_run_result in pipelines/runners/renewals-risk-assessment/src/main.py, so the counter reaches the run record with no wrapper change. Add a unit test under pipelines/runners/renewals-pipeline/tests/ that stubs the Anthropic client to raise the EOF-shaped validation error and asserts both the truncation tagging and the surfaced counter. Deliberately leave _classify_status alone — a truncation that later succeeds on retry is not a failed row, and conflating the two would flip healthy runs to PARTIAL.

Why this fixes it. This is a real code defect with a known, bounded fix, and the scope for this run is widened to any file, so the two files that actually hold the bug (modules/risk_assessment.py and risk_assessment_container/app.py under pipelines/runners/renewals-pipeline/, reused in place by this pipeline's Dockerfile) are both editable. Raising the token ceiling addresses the root cause rather than the symptom — the retry loop currently masks it by re-sampling until the model happens to answer more briefly, which is luck, not correctness, and each masked retry cost 70-97 seconds of wall clock in this run. The observability half matters more than the config half for Surtr's stated worst failure mode: today a truncation storm that survived all three retries would leave those renewals unassessed with stale risk data still served from the mart, and with PARTIAL_FAILURE_ABS = 10 and PARTIAL_FAILURE_PCT = 0.05 in renewals-risk-assessment/src/main.py a handful of them still records the run as green, so nobody would be paged. The blast radius stays correct because the change is additive — a larger ceiling, a named renewal ID in one log line, and one new key in a JSON summary the wrapper already passes through untouched — with no change to prompts, schemas, retry semantics, run-status classification, or any SQL.

### Files changed

 .../runners/renewals-pipeline/modules/config.py    |   4 +
.../renewals-pipeline/modules/risk_assessment.py   |  22 ++-
.../risk_assessment_container/app.py               |  52 ++++++-
.../tests/test_risk_assessment_truncation.py       | 150 +++++++++++++++++++++
.../runners/renewals-risk-assessment/src/main.py   |  14 +-
.../renewals-risk-assessment/tests/test_main.py    |  40 ++++++
6 files changed, 277 insertions(+), 5 deletions(-)

## Verification

### pytest (pipelines/runners/renewals-risk-assessment/tests) — exit 0

============================= test session starts ==============================
platform linux -- Python 3.11.16, pytest-9.1.1, pluggy-1.6.0
rootdir: /home/runner/work/Surtr/Surtr/publish/pipelines/runners/renewals-risk-assessment
plugins: mock-3.15.1
collected 7 items
tests/test_main.py .......                                               [100%]
============================== 7 passed in 0.02s ===============================

### verify: ruff check — exit 0

All checks passed!

### verify: ruff format --check — exit 0

1727 files already formatted

<details>

<summary>Run metadata</summary>

| Field | Value |

| --- | --- |

| Pipeline | renewals-risk-assessment |

| Failing run | 2a1222fa-13c8-4567-b34e-f99ca4b3ffa2 |

| Occurrence | 1 (times this exact failure signature has been seen) |

| Signature | 21eb740c026423a08c10d6ce251bde3a248933f39ee4e787f2c3d0f2a2971a90 |

| Verify | green |

</details>

---

🤖 Opened by heimdall. mercy reviews this PR automatically; heimdall revises on REQUEST_CHANGES (bounded rounds). Tier-auto PRs may auto-merge on mercy approval when the consumer enables it; everything else waits for a human. Mention heimdall in a comment to direct it, or add the manual-dev label to take the PR over and stop it entirely.

Automated fix for openai-usage-pipeline — fix_class code_fix, scope tier draft.

Resolves https://github.com/AI-Builder-Team/Surtr/issues/1601

> Ready for review — verification is green; HEIMDALL_READY_PRS opens verified tier-draft fixes ready for review. A human still merges — auto-merge never applies outside tier auto.

## What's broken

Run e9b62caa-e756-45ec-a3b3-17fc99de13ce of openai-usage-pipeline completed as outcome=partial (442 rows across 28 BUs) after the OpenAI /v1/organization/costs call exhausted its 5-attempt retry budget on HTTP 429 for three BUs: "Line-item cost fetch failed for BU Trilogy-Crossover-PROD, API key 1: 429 Client Error: Too Many Requests for url: https://api.openai.com/v1/organization/costs?...group_by=line_item&limit=180. Persisting the 8 usage record(s) with $0 billed cost; billed dollars self-heal on the next T-2 re-pull." (same for Trilogy-Academics, 78 records, and Trilogy-CNU-Innovations, 23 records). The data cost is worse than the log line claims: the except block at pipelines/runners/openai-usage-pipeline/src/handler.py:263-270 sets only bu_cost_fetch_failed and does NOT set bu_has_error, so the BU still gets its full bu_owned_windows and is published atomically — the log shows "BU Trilogy-Crossover-PROD Redshift: deleted=5, inserted=8", i.e. 5 previously-loaded rows carrying real billed dollars were DELETEd and replaced with 8 rows whose billed_cost_dollars is 0.0. So this run did not merely fail to add cost data; it overwrote correct cost data in staging_finance_ai_spend.raw_openai_token_usage with zeroes for 109 rows across three BUs.

Root cause. The only recovery a rate-limited /costs call gets is the in-request retry loop in _request_with_retries (src/openai_client.py:131-173), and that entire budget is spent inside the BU's single turn of the main loop: attempts at +2s, +4s, +8s and +65s (the RATE_LIMIT_WINDOW floor added by PR #1395), then raise_for_status(). When the org's rolling quota is saturated for longer than that — which it is here, because the shared token bucket is configured at exactly OpenAI's advertised ceiling (OPENAI_MAX_REQUESTS_PER_MINUTE=30 in pipeline.json:33, with a full 30-token burst allowance, so the client sustains requests right at the limit with zero headroom) — the BU is abandoned with line_item_costs = [] and every row gets billed_cost_dollars=0.0 via allocate_billed_to_keys. Nothing in the run ever revisits that BU, even though later BUs in the same run (e.g. Trilogy-Skyvera at 07:09:20) recovered from identical 429s, which proves the throttle clears within the run. The billed dollars self-heal on the next T-2 re-pull comment at src/handler.py:267 is only half true: the default window is [T-2, T) (src/handler.py:94-95), so tomorrow's run re-covers report_date 2026-08-29 but never re-covers 2026-08-28 — those zeroed rows are terminal for scheduled runs and need a manual backfill. The pure-throttling half of this is already addressed by open PR #1595 (commit dbb47285, adds OPENAI_RATE_LIMIT_SAFETY_FACTOR/OPENAI_MAX_BURST_REQUESTS); it is unmerged, and even once merged it only makes 429 exhaustion rarer rather than recoverable, so the missing in-run recovery is the remaining root cause.

## What this PR changes

Add an end-of-run cost catch-up pass to pipelines/runners/openai-usage-pipeline/src/handler.py, mirroring the approach already reviewed for the sibling pipeline in PR #1600 (openai-cost-pipeline) but narrowed to the cost endpoint exactly as the observer recommends — re-pulling only /costs costs one request per affected key instead of the ~10 a full BU re-process would spend, which matters when request volume is itself the failure. Concretely: when the except at src/handler.py:263 fires, retain the affected (bu, key, usage_records, enriched records, cost_pages) so the run can come back to it; after the main BU loop, sleep a cool-down that clears OpenAI's rolling window (new OPENAI_COST_RETRY_DELAY_SECONDS, ~90s), re-call fetch_line_item_costs for those keys only, and on success re-run allocate_billed_to_keys/split_billed_across_records, write the real billed_cost_dollars onto the retained records, and re-publish that BU with insert_usage_records(..., atomic=True, owned_windows=...) so the idempotent DELETE+INSERT replaces the $0 rows with billed ones. Guard the pass with a _remaining_seconds(context) check against a reserve (PR #1600's _remaining_seconds helper is the pattern) so it can never turn a partial run into a Lambda timeout — this run used 590s of its 900s budget, leaving ample room for a 90s cool-down plus three single-request re-pulls — and run it BEFORE the manifest/ledger write so a recovered BU is not recorded as outcome=partial. Report the pass in output_summary as cost_retry_pass ({attempted, recovered, still_failed, skipped}) and keep cost_fetch_failed_bus populated only for BUs that failed twice, so a recovered BU stops firing this CRITICAL finding while a genuinely-dead one stays loud. Add unit tests in tests/test_handler.py covering: cost fetch failing then succeeding on the catch-up (rows end with non-zero billed cost, partial_failure False), failing twice (behaviour unchanged, still partial), and the pass being skipped when the invocation budget is short.

Why this fixes it. This is a silent data failure of exactly the kind Surtr's conventions call out first: the run reported partial and 442 rows published while quietly regressing 109 rows' billed dollars to $0 and permanently losing 2026-08-28's billed cost for three BUs, so a finance consumer of staging_finance_ai_spend.raw_openai_token_usage reads understated spend with no missing-row signal. The change is confined to the pipeline's own directory (handler.py, pipeline.json env, tests), touches no shared code and no SQL, and reuses the pipeline's existing atomic owned-window publication so the re-publish is idempotent rather than a new write path — the Surtr rule against widening a fix into SQL rewrites is why the fix re-pulls and republishes instead of attempting a merge that preserves prior billed values in place. It is deliberately complementary to, not a duplicate of, open PR #1595: that PR lowers the odds of 429 exhaustion by giving the token bucket headroom, while this one makes an exhaustion that still happens recoverable inside the same run; the two are independent and neither conflicts with the other's diff (PR #1595 touches only src/openai_client.py and its tests).

### Files changed

 .../runners/openai-usage-pipeline/pipeline.json    |   4 +-
.../runners/openai-usage-pipeline/src/handler.py   | 360 ++++++++++++++++++++-
.../openai-usage-pipeline/tests/conftest.py        |  13 +
.../openai-usage-pipeline/tests/test_handler.py    | 190 ++++++++++-
.../tests/test_write_modes.py                      | 109 +++++++
5 files changed, 657 insertions(+), 19 deletions(-)

## Verification

### pytest (pipelines/runners/openai-usage-pipeline/tests) — exit 0

``

dows_still_deletes PASSED [ 82%]

tests/test_redshift_handler.py::TestAtomicPublish::test_atomic_owned_windows_merge_with_row_derived_pairs PASSED [ 83%]

tests/test_redshift_handler.py::TestAtomicPublish::test_atomic_invalid_owned_windows_are_skipped PASSED [ 84%]

tests/test_redshift_handler.py::TestAtomicPublish::test_empty_rows_without_owned_windows_is_a_noop PASSED [ 84%]

tests/test_secrets.py::TestGetOpenAiBuKeys::test_returns_bu_key_mapping PASSED [ 85%]

tests/test_secrets.py::TestGetOpenAiBuKeys::test_normalizes_single_key_to_list PASSED [ 86%]

tests/test_secrets.py::TestGetOpenAiBuKeys::test_raises_on_secrets_manager_error PASSED [ 86%]

tests/test_write_modes.py::TestWriteModes::test_old_mode_has_zero_secondary_side_effects PASSED [ 87%]

tests/test_write_modes.py::TestWriteModes::test_dual_mode_primary_first_then_secondary_lane_then_ledger PASSED [ 88%]

tests/test_write_modes.py::TestWriteModes::test_dual_mode_secondary_failure_is_partial_and_primary_intact PASSED [ 88%]

tests/test_write_modes.py::TestWriteModes::test_dual_mode_ledger_failure_is_partial PASSED [ 89%]

tests/test_write_modes.py::TestWriteModes::test_new_mode_writes_only_secondary_and_failures_raise PASSED [ 90%]

tests/test_write_modes.py::TestWriteModes::test_new_mode_cost_catch_up_republishes_atomically_and_replaces_manifest_entry PASSED [ 90%]

tests/test_write_modes.py::TestWriteModes::test_run_id_falls_back_to_lambda_request_id PASSED [ 91%]

tests/test_write_modes.py::TestWriteModes::test_dual_mode_incomplete_run_is_never_ledgered_as_published PASSED [ 92%]

tests/test_write_modes.py::TestWriteModes::test_invalid_mode_fails_loud PASSED [ 92%]

tests/test_write_modes.py::TestValidEmptyConvergence::test_valid_empty_fetch_converges_window_and_ledgers_zero_published[dual] PASSED [ 93%]

tests/test_write_modes.py::TestValidEmptyConvergence::test_valid_empty_fetch_converges_window_and_ledgers_zero_published[new] PASSED [ 94%]

tests/test_write_modes.py::TestValidEmptyConvergence::test_failed_bu_window_is_never_deleted[dual] PASSED [ 94%]

tests/test_write_modes.py::TestValidEmptyConvergence::test_failed_bu_window_is_never_deleted[new] PASSED [ 95%]

tests/test_write_modes.py::TestValidEmptyConvergence::test_no_bus_path_has_no_secondary_side_effects PASSED [ 96%]

tests/test_write_modes.py::TestLedgerModule::test_record_publication_inserts_row PASSED [ 96%]

tests/test_write_modes.py::TestLedgerModule::test_record_publication_ …_(truncated)_

<details>

<summary>Run metadata</summary>

| Field | Value |

| --- | --- |

| Pipeline | openai-usage-pipeline |

| Failing run | e9b62caa-e756-45ec-a3b3-17fc99de13ce |

| Occurrence | 1 (times this exact failure signature has been seen) |

| Signature | 4bec99fa0b9a809adddc95de596e0b155f5647aa90d901db0ef441ed9bc93655 |

| Verify | green |

</details>

---

🤖 Opened by heimdall. mercy reviews this PR automatically; heimdall revises on REQUEST_CHANGES (bounded rounds). Tier-auto PRs may auto-merge on mercy approval when the consumer enables it; everything else waits for a human. Mention heimdall in a comment to direct it, or add the manual-dev` label to take the PR over and stop it entirely.

Linear: [AI-614](https://linear.app/builder-team/issue/AI-614/arm-the-hourly-prod-release-sweep-on-surtr)

The Surtr half of the hourly production release. Every hour at :25, if main is ahead of production and every gate passes, Heimdall opens and merges the release PR. cd.yml runs on push to production, so that merge is the deploy.

⚠️ MERGE ORDER: [AI-Builder-Team/mercy#49](https://github.com/AI-Builder-Team/mercy/pull/49) must land first. A reusable workflow hard-fails when a caller passes inputs the callee has not declared.

## Inert on merge

HEIMDALL_RELEASE_ENABLED is unset. The gate step skips before reading any state at all — this merges as a no-op and stays one until someone sets the variable.

## The two values the central gate refuses to guess

release_manifest_pattern: '^pipelines/runners/([^/\s]+)/pipeline\.json$'
release_stack_paths: pipelines/cdk/bin pipelines/cdk/lib

bin/pipeline-cdk.ts scans pipelines/runners/ and builds one stack per directory containing a pipeline.json. So deleting that manifest isn't a hint that a stack might go away — it *is* the stack leaving the CDK app, which is exactly what broke prod CD in August.

Upstream has no default for this, on purpose: a repo laid out differently would match nothing, and "matched nothing" would be reported as "nothing is being destroyed".

Verified against the only two commits in this repo's history that ever deleted a pipeline manifest, using the pattern read back out of this YAML file:

| Commit | Result |

|---|---|

| 39eb97bb — removed p2-scorecard-sync | caught — Pipeline-p2-scorecard-sync |

| 195e87d8 — removed netsuite-income-statement | caught — Pipeline-netsuite-income-statement |

| origin/main~1..main | not destructive |

## Why :25

The top of the hour is both the busiest Actions queue and when Surtr's own scheduled pipelines fire.

## mode_override

Not a convenience input. The schedule trigger only ever fires from the default branch, so this is the only way to soak a release dry-run before this thing is allowed to merge anything.

## Kill switches

- HEIMDALL_RELEASE_HOLD=true — stops releases without silencing triage or revise

- TRIAGE_AGENT_RUN_ENABLED — still stops everything, unchanged

## Known gap: no automatic rollback yet

The plan was a --force-with-lease push back to the pre-release SHA. Reading production's ruleset first showed non_fast_forward is active with no bypass actors — that push is impossible for everyone, Heimdall included. Rollback has to be revert-forward through a PR, which is a better design anyway, and is its own change.

Until then a failed CD needs a human. The pre-release SHA is written into the release PR body and the job output so that human isn't doing archaeology on a bad day.

## Business Value

Removes the last human step in the deploy path. Releases currently go out when someone notices main is ahead — the two on 2026-08-28 landed at 19:04 and 22:08, which is the shape of "when someone got round to it", with merged work sitting undeployed in between. This bounds that lag to ~89 minutes worst case with nobody in the loop — the soak and the hourly cadence compounding — and adds a destructive-change check that no manual release has ever actually performed.

## Manual Effort Estimate

~0.5 days for the caller; the design work sits in the mercy PR. *(Proposed by Claude — Keval to confirm.)*

Feature 5 of the software factory: hourly, if there are undeployed changes on main, do the prod release. Surtr's cd.yml runs on push to production, so merging the release PR *is* the deploy. Everything upstream in this factory is revertible with a PR. This ships.

The preflight logic landed in #48. This is the workflow that uses it, plus the two pieces #48 could not have: how the state is gathered, and how the merge is actually performed.

## The job runs no agent and no consumer code

It reads git and the GitHub API, asks release.py for a verdict, and only a clear go opens and merges the PR. Nothing it executes comes from the branch it is shipping. Same posture as publish.

## What's new here

### A stack-removal detector that doesn't need prod deploy keys

A real cdk diff is the authoritative destructive check, but producing one hourly means handing an unattended job the production deploy credentials and paying a full synth --all every hour, forever.

It turns out the source diff answers the question exactly. pipelines/cdk/bin/pipeline-cdk.ts builds one stack per directory under pipelines/runners/ containing a pipeline.json. So a deleted manifest isn't a hint that a stack *might* go away — it is the stack leaving the CDK app. That's the August incident precisely: a stack left the app before the release and prod CD broke.

The manifest pattern has no default, deliberately. A repo laid out differently would match nothing, and "matched nothing" would be reported as "nothing is being destroyed" — a silent all-clear on the one gate guarding production. An unconfigured repo gets a refusal instead.

A real cdk diff still wins whenever one is supplied; the source check is the fallback, not a replacement.

### parse_check_run_pages() — a silent-blocker this would have shipped with

gh api --paginate --jq '.check_runs' emits one JSON array per page. A multi-page result is [...][...] — concatenated arrays, not a document.

Surtr's current main head returns 149 check runs across several pages. I ran json.loads on the real payload:

Extra data: line 2 column 1 (char 307367)

Caught, that exception returns [], summarise_checks reports pending, and every release is blocked forever by a gate that looks perfectly healthy in the logs. The decoder reads page by page, and a truncated tail yields a sentinel entry rather than a short list — having read *part* of the checks is not the same as having read them all.

### Merge mechanics read off the ruleset, not assumed

- --merge: production's ruleset sets allowed_merge_methods: ["merge"]. A squash would be rejected.

- --match-head-commit: if main moves while the job is deciding, the merge is refused server-side rather than shipping a commit that never passed a gate.

- A constant concurrency key for release mode. Falling through to github.sha would let an hourly run triggered at a newer main overlap one still merging.

- An already-open release PR is reused rather than stacking duplicates.

- BLOCKED/BEHIND/DIRTY is not a failure — the PR stays open with its reason visible and the next hour reconsiders.

## Validated against live Surtr, not fixtures

| Check | Result |

|---|---|

| Current main state gather | 149 runs decoded, required set of 7, CI success |

| Current verdict | no_commits — production is level with main. Correct. |

| 39eb97bb (removed p2-scorecard-sync) | caught — Pipeline-p2-scorecard-sync |

| 195e87d8 (removed netsuite-income-statement) | caught — Pipeline-netsuite-income-statement |

| An ordinary commit | not destructive |

Those are the only two commits in Surtr's history that ever deleted a pipeline manifest. Both are caught by name.

## A bug my own lint caught mid-write

The git_auth lint from #38 failed the suite on my new git fetch. It was right: the consumer checkout is persist-credentials: false, so the fetch would have failed against a private origin. Now routed through git_authed, which supplies the token per command via GIT_CONFIG_* rather than writing it into .git/config.

## Rollback is deliberately not here

The plan was --force-with-lease back to the pre-release SHA. Reading the ruleset first showed non_fast_forward is active on production with no bypass actors — that push is impossible for everyone, heimdall included. Rollback has to be revert-forward through a PR, which is a better design anyway (auditable, no history rewrite, no bypass to grant) but is its own change, not a rushed tail on this one.

The pre-release SHA is recorded in the PR body and the job output either way, so a human rolling back by hand isn't doing archaeology on a bad day.

## Not armed

HEIMDALL_RELEASE_ENABLED is unset everywhere, so the gate skips. The Surtr caller and its hourly schedule follow separately, and I'd like to run it on dry_run for a soak before it can merge anything.

Tests: 509 passed, 1 skipped. 20 new, covering the detector, the paginated decode, and the silent-pass traps in both.

## Business Value

Closes the last manual step in the deploy path. Releases currently wait on Keval noticing that main is ahead — the two releases on 2026-08-28 went out at 19:04 and 22:08, which is the shape of "when someone got round to it", and merged work sits undeployed in between. An hourly gate turns that into a bounded one-hour lag with no human in the loop, while adding a destructive-change check that no human release has ever actually performed.

## Manual Effort Estimate

~2 days — the workflow is a day, but the gate semantics are where the time goes: reading the ruleset before designing rollback, checking whether check runs paginate, and confirming the manifest→stack mapping rather than assuming it. *(Proposed by Claude — Keval to confirm.)*

Linear: [AI-602](https://linear.app/builder-team/issue/AI-602/p33-move-heimdall-onto-current-models)

Started as the model-allowlist refresh this ticket asks for. Found a bug underneath it.

## The revise job never resolved a model

Triage has a Resolve + validate model step. Revise doesn't — it set AGENT_MODEL to a literal, one per runtime:

AGENT_MODEL: claude-opus-4-8   # claude path
AGENT_MODEL: gpt-5-codex       # codex path

Three silent consequences:

1. The agent_model input was ignored entirely on that path. You could not override the model for a revise run.

2. The codex default drifted. Triage runs gpt-5.6-luna — the model the org migrated to on 2026-08-26. Revise was still running gpt-5-codex.

3. Every codex revise run was filed unpriced. gpt-5-codex has no row in harness/pricing.py, and rates_for() deliberately returns None for an unknown model rather than guessing — so price_usd returned nothing.

The third is the expensive one: a $0 that is indistinguishable from a run that genuinely cost nothing. Same failure mode as the Claude-5 pricing drift.

And the telemetry step made it worse by re-deriving the model rather than reading it:

MODEL=$([[ "${AGENT_RUNTIME}" == "codex" ]] && echo gpt-5-codex || echo claude-opus-4-8)

A second guess at the same question — which guessed differently from the step that actually ran the agent.

## The fix

Revise resolves exactly as triage does, exposes the result as a job output, and telemetry consumes that value.

## Allowlist, per the standing rule to prefer current models

| | Before | After |

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

| Claude default | claude-opus-4-8 | claude-opus-5 |

| Claude allowed | opus-4-8, opus-4-7, sonnet-4-6 | opus-5, sonnet-5, haiku-4-5; opus-4-8 kept as a pinned rollback |

| Codex default | gpt-5.6-luna (triage) / gpt-5-codex (revise) | gpt-5.6-luna everywhere |

No rate-card change needed on the Claude side — the CLI self-reports cost and that number takes precedence over anything computed.

## The test pins the invariant that actually failed

test_model_resolution.py: the two resolve blocks must stay identical modulo comments, no job may hardcode a model, telemetry must consume the resolved value, and the allowlist must not carry retired models. Two copies of one decision that stopped agreeing is the entire bug — so that's what's asserted, rather than just the current values.

## Business Value

Cost attribution for revise runs has been wrong since the Luna migration — not slightly wrong, absent. Every codex revise run recorded no spend, which understates Heimdall's real cost in exactly the reporting that decides whether this project is worth its budget. It also means the migration was never actually complete: half the agent runs stayed on the old model without anything saying so.

## Manual Effort Estimate

~2 hours — the fix is small; finding it meant tracing why a hardcoded default existed at all and checking it against the rate card. *(Proposed by Claude — Keval to confirm.)*

Linear: [AI-599](https://linear.app/builder-team/issue/AI-599/p23-de-timid-the-prompts-shrink-the-other-escape-hatch)

Heimdall refuses fixes its own configuration plainly permits. The cause turned out not to be the prompt's tone — it's that the diagnose stage was never told what it was allowed to touch.

## The gap

scope_note reached the fix and converse stages only. Diagnose got common_variables and nothing else. So at the exact moment it decides can_attempt_fix, it had no statement of scope and fell back to AGENTS.md's narrow-tier default.

And the failure is self-sealing: a can_attempt_fix: false means the fix stage never runs, so the one place the widening *was* stated could never be reached. The note arrived after the decision it was meant to inform.

The old wording made it worse by anchoring the decision to tiers unconditionally:

> Set can_attempt_fix to true only when you can confidently implement the fix within the scope tiers (prefer pipelines/runners/{{pipeline_id}}/**).

## The evidence, from Surtr issue #1518

Verbatim, on a repo with forbidden_paths: [] and HEIMDALL_ALL_FILES=true:

> "This is not fixable inside netsuite-saved-search-refresh's Tier A scope and should not be auto-fixed: the assertion lives in pipelines/ddl/2026-07-28_….sql (outside pipelines/runners/...)"

There is no Tier A limit on that repo. Nothing had told it.

## Demonstrated, not argued

Rendering the diagnose prompt against Surtr's real .heimdall.yml with ALL_FILES=true:

| | Scope statements in the rendered prompt |

|---|---|

| before | 0 |

| after | 1 — Scope: widened — you may edit any file. |

With ALL_FILES=false it correctly renders Scope: the repo's configured tiers. instead.

## Three changes

1. build_prompt.py — diagnose and intake get the same scope_note the fix stage already gets; the workflow passes HEIMDALL_ALL_FILES to that step. The fix stage's own comment already said *"the agent self-limits to the tiers and never makes the edit"* — that lesson just hadn't been carried to the stage where the decision is made.

2. diagnose.md — the go/no-go is anchored to the scope line printed directly above it, not to "the scope tiers". It says explicitly that *where* the fix lives inside that scope doesn't matter, and it names the wrong-refusal case: "it is outside Tier A" is not a reason unless the scope line says tiers apply.

3. AGENTS.md — said *"A correct refusal is a success"* with nothing on the other side of the ledger. Refusing for a listed reason is still a success; refusing for any other reason is now named as the failure it is — one that merely looks tidy, and costs exactly as much as never running.

## Scope of the change

Prompt/config wiring only. No change to the path guard, which still enforces the real setting — this closes the gap between what the guard permits and what the agent believes it may do, in the direction of the guard.

## Business Value

This is the mechanism behind "Heimdall is too weak, it avoids doing anything by itself." 72 of 104 triage issues end as other, and an unknown share of those are this: a fix that was available, permitted, and declined. Every one costs a full diagnose run and returns nothing. Widening scope in config achieves nothing while the agent deciding whether to act can't see that it was widened.

## Manual Effort Estimate

~3 hours — most of it tracing why a repo that had already set every widening flag still got refusals, rather than writing the fix. *(Proposed by Claude — Keval to confirm.)*

Linear: [AI-616](https://linear.app/builder-team/issue/AI-616/klair-give-heimdall-real-verification-verifycommands-was-empty)

.heimdall.yml had verify: commands: [], so every Heimdall fix in this repo was "verified" by nothing.

The cost of that is already on the record next door. Surtr PR #1580 was written by an agent with no shell, verified green because nothing checked it, opened ready for review, was approved by Mercy — and then sat unmergeable because CI's lint failed. A full review round and a human's attention, spent on a PR that could never merge.

## Mirroring ruff-check has to be exact

Klair's required ruff-check job lints only changed files. Three ways to get this wrong, each worse than leaving the block empty:

| | If got wrong | Consequence |

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

| Scope | ruff check klair-api whole-tree | Reports pre-existing findings the repo has never gated on → every verification fails → every Heimdall fix forced to draft. The opposite of the intent. |

| File set | miss the klair-udm/ half, or lint .venv/ | Verifies a different thing than CI gates on |

| Pin | unpinned ruff | 0.16.0 expanded the default rule set 59 → 413 rules and fails files that pass locally. CI pins 0.15.22 deliberately — the same gap in a subtler form. |

Changed files come from git diff --cached. The verify step runs in a clean checkout of the pinned base with the agent's tree rsynced over it and staged, so the index *is* the agent's edits — no network call needed to work out what changed.

pip rather than CI's uv: the verify job runs actions/setup-python but not setup-uv, so pip is the only tool guaranteed present.

## Tested against a real staged tree, not assumed

| Case | Result |

|---|---|

| clean klair-api change | exit 0, linted |

| klair-client only | exit 0, no-files branch |

| klair-api/.venv/ only | exit 0, no-files branch |

| unused imports (F401) | exit 1, linted |

| badly formatted file | exit 1, 1 file would be reformatted |

| no Python changes (format cmd) | exit 0, no-files branch |

The two exit-1 rows are the entire point. Verification that cannot fail is not verification — and an empty commands: [] cannot fail.

## Scope

One file, config only. No behaviour change to anything but Heimdall's own verification, and it can only make a fix *more* likely to open as a draft, never less.

## Business Value

Klair is one of the two repos in the factory's scope, and until now Heimdall could open a fix here ready-for-review having proven nothing about it. This makes the green checkmark mean something, and removes a failure that wastes a full Mercy review plus a human's attention every time it fires.

## Manual Effort Estimate

~2 hours — most of it reading Klair's CI closely enough to mirror it rather than approximate it, plus the six-case test matrix. *(Proposed by Claude — Keval to confirm.)*

Automated fix for netsuite-balance-sheet — fix_class code_fix, scope tier draft.

Resolves https://github.com/AI-Builder-Team/Surtr/issues/1597

> Ready for review — verification is green; HEIMDALL_READY_PRS opens verified tier-draft fixes ready for review. A human still merges — auto-merge never applies outside tier auto.

## What's broken

Run aed6f23f-3db7-4953-8c73-c0b99c8899b8 failed with ValueError: Accounting period from CSV header line 4 ('End of Jul 2026' -> 2026-07-31) does not match the S3 file-date month (2026-08-29). The upstream export likely emitted a stale header; refusing to load..., raised at pipelines/runners/netsuite-balance-sheet/src/s3_reader.py:148. This is a false positive from the month-equality guard added by PR #1139 (s3_reader.py:147, period_end_date[:7] != date_str[:7]): it assumes the S3 filename month equals the accounting-period month, but the upstream puller names every key by the email received date, not the period. The scheduled loop (handler.py:93) processes the EOM prefix first with fail-fast, so this ValueError aborts the entire run and it loaded ZERO rows for both prefixes.

Root cause. The guard at s3_reader.py:147 requires the CSV header period and the S3 filename to share the same calendar month, but that invariant is false by design for this pipeline. The upstream netsuite-wrapper-report-puller names each S3 key by the email received date — date_str = msg.received_date.strftime("%Y-%m-%d") at netsuite-wrapper-report-puller/src/handler.py:145 — while the loader's own docstring (handler.py:12-13) states the accounting period comes from the CSV header, not the filename. The Balance_Sheet_EOM/ prefix is the 'Last Period' report (handler.py:8), which always reports the previous closed month, so a file received 2026-08-29 correctly carries 'End of Jul 2026'; the guard therefore rejects a legitimate load. PR #1139 (merged 2026-08-28 23:05) introduced this regression and the first scheduled run afterward, 2026-08-29 13:00, failed — consistent with occurrence count 1.

## What this PR changes

In pipelines/runners/netsuite-balance-sheet/src/s3_reader.py, replace the exact month-equality check (period_end_date[:7] != date_str[:7]) with month-difference logic that computes whole months between the file date and the header period using real date arithmetic (so the December->January year boundary is handled). Accept an offset of 0 months (the 'As Of' current-month report) or 1 month behind (the EOM 'Last Period' report), and still raise for a genuinely stale header (2+ months behind) or a future period, preserving the original protection against a stale header mis-keying the DELETE-then-INSERT in redshift_handler.load_balance_sheet. Update tests/test_s3_reader.py accordingly: the existing test_header_month_drift_raises uses a 1-month offset (Feb header / Mar file) which is now the legitimate EOM case, so change it to assert on a genuinely stale (e.g. 3+ months back) and a future period, and add a case asserting the prior-month EOM offset now passes.

Why this fixes it. This is a code-level defect confined to the pipeline's own directory (Tier A): the guard's premise contradicts the upstream key-naming convention, so it blocks every scheduled load rather than only stale ones, costing the warehouse all rows for both prefixes each run. The fix is a real code change plus a test — widening the guard to tolerate the documented one-month EOM offset while still rejecting truly stale or future headers — which keeps the blast radius inside pipelines/runners/netsuite-balance-sheet/ and does not touch shared code, SQL, or config. A pure config tweak cannot express this since the correct behavior depends on the EOM-vs-As-Of period semantics encoded in the reader.

### Files changed

 .../netsuite-balance-sheet/src/s3_reader.py        | 27 +++++++----
.../netsuite-balance-sheet/tests/test_s3_reader.py | 52 +++++++++++++++++++---
2 files changed, 66 insertions(+), 13 deletions(-)

## Verification

### pytest (pipelines/runners/netsuite-balance-sheet/tests) — exit 0

``

heetExceptionHandling::test_connection_closed_on_success PASSED [ 45%]

tests/test_redshift_handler.py::TestLoadBalanceSheetExceptionHandling::test_connection_closed_on_failure PASSED [ 47%]

tests/test_redshift_handler.py::TestLoadBalanceSheetExceptionHandling::test_cursor_context_manager_exited_on_success PASSED [ 49%]

tests/test_s3_reader.py::TestParsePeriodLabel::test_abbreviated_month PASSED [ 50%]

tests/test_s3_reader.py::TestParsePeriodLabel::test_abbreviated_month_feb PASSED [ 52%]

tests/test_s3_reader.py::TestParsePeriodLabel::test_abbreviated_month_dec PASSED [ 54%]

tests/test_s3_reader.py::TestParsePeriodLabel::test_full_month_name PASSED [ 56%]

tests/test_s3_reader.py::TestParsePeriodLabel::test_leap_year_feb PASSED [ 57%]

tests/test_s3_reader.py::TestParsePeriodLabel::test_whitespace_stripped PASSED [ 59%]

tests/test_s3_reader.py::TestParsePeriodLabel::test_invalid_format_returns_none PASSED [ 61%]

tests/test_s3_reader.py::TestParsePeriodLabel::test_empty_string_returns_none PASSED [ 63%]

tests/test_s3_reader.py::TestParsePeriodLabel::test_invalid_month_returns_none PASSED [ 64%]

tests/test_s3_reader.py::TestParsePeriodLabel::test_short_format_abbreviated PASSED [ 66%]

tests/test_s3_reader.py::TestParsePeriodLabel::test_short_format_dec PASSED [ 68%]

tests/test_s3_reader.py::TestParsePeriodLabel::test_short_format_full_month PASSED [ 70%]

tests/test_s3_reader.py::TestParseCurrency::test_positive_amount PASSED [ 71%]

tests/test_s3_reader.py::TestParseCurrency::test_negative_amount PASSED [ 73%]

tests/test_s3_reader.py::TestParseCurrency::test_simple_amount PASSED [ 75%]

tests/test_s3_reader.py::TestParseCurrency::test_empty_string PASSED [ 77%]

tests/test_s3_reader.py::TestParseCurrency::test_no_digits PASSED [ 78%]

tests/test_s3_reader.py::TestParseCurrency::test_zero PASSED [ 80%]

tests/test_s3_reader.py::TestParseCurrency::test_multiple_dots_raises_valueerror PASSED [ 82%]

tests/test_s3_reader.py::TestReadBalanceSheetCsv::test_invalid_date_format_raises PASSED [ 84%]

tests/test_s3_reader.py::TestReadBalanceSheetCsv::test_invalid_date_no_dashes_raises PASSED [ 85%]

tests/test_s3_reader.py::TestReadBalanceSheetCsv::test_truncated_csv_raises PASSED [ 87%]

tests/test_s3_reader.py::TestReadBalanceSheetCsv::test_unparseable_period_raises PASSED [ 89%]

tests/test_s3_reader.py::TestReadBalanceSheetCsv::test_success PASSED [ 91%]

tests/test_s3_reader …_(truncated)_

<details>

<summary>Run metadata</summary>

| Field | Value |

| --- | --- |

| Pipeline | netsuite-balance-sheet |

| Failing run | aed6f23f-3db7-4953-8c73-c0b99c8899b8 |

| Occurrence | 1 (times this exact failure signature has been seen) |

| Signature | d80de6674cad1cc33f4224a48524da2ec8c0b9786edf2b4e02fcac9d213a06b6 |

| Verify | green |

</details>

---

🤖 Opened by heimdall. mercy reviews this PR automatically; heimdall revises on REQUEST_CHANGES (bounded rounds). Tier-auto PRs may auto-merge on mercy approval when the consumer enables it; everything else waits for a human. Mention heimdall in a comment to direct it, or add the manual-dev` label to take the PR over and stop it entirely.

- Define is_school_mapped as a canonical-school attribution coverage flag rather than a central-spend classification.

- Identify exact QuickBooks class Central as the Finance-approved central pool and keep it unallocated.

- Direct agents to follow each unmapped class's Finance disposition.

Linear: [AI-605](https://linear.app/builder-team/issue/AI-605/p5-hourly-automatic-surtr-production-release-with-rollback) · Project: [Heimdall Software Factory](https://linear.app/builder-team/project/heimdall-software-factory-4216613b8e5f)

## Why this gate matters more than the others

Surtr's cd.yml runs on push to production, so merging main → production is the deploy. Everything upstream in this project is revertible with a PR; this one ships. Keval chose fully automatic including rollback, so these gates are the whole safety story.

| Gate | Blocks when | Why |

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

| no_commits | production is level with main | nothing to do |

| too_fresh | newest commit < 30 min old | a commit merged seconds ago has had no chance to show a problem; hourly cadence means waiting costs at most an hour |

| ci_not_green | main's own CI isn't green | strict_required_status_checks is off on Surtr, so a red main is genuinely reachable |

| hold | a human said stop | explicit override |

| destructive_cdk | the diff destroys or replaces | 2026-08: deleting a stack before merge+release broke prod CD |

A destructive diff is not necessarily *wrong* — it is necessarily a human's call.

Every gate fails closed. An undateable commit is too fresh; an unreadable diff is destructive; an unreadable state refuses. *"We could not tell"* and *"nothing will be destroyed"* are different claims and only one is safe to act on unattended.

## Two traps caught by building against live data

Both would have shipped silently and looked fine.

1. The /status endpoint lies about Surtr. My first version read the combined commit status. Against real main:

combined /status API: pending (statuses: 0)
check-runs API:       Lint (Ruff)=success, Typecheck=success, … all green

Surtr has zero legacy statuses and uses check runs exclusively, so /status reports pending on every commit forever. A gate built on it would have blocked every release, permanently, while appearing healthy. summarise_checks reads check runs.

2. Advisory jobs were voting. Judging *every* check run, that same real SHA came back failure — because mercy's review / Review was cancelled, superseded by a newer run, which happens constantly under cancel-in-progress.

ALL runs      -> ('pending', ['review / Review (cancelled)', …])
REQUIRED only -> ('pending', ['Pipeline Runner Tests'])     <- the real blocker

Now filtered to the repo's required checks — the same set that decides mergeability — and cancelled counts as pending rather than failure, so the next hourly attempt reconsiders instead of demanding a human. Heimdall's own skipped jobs are non-blocking for the same reason: they appear on nearly every commit.

## Verification

Run against Surtr's actual state mid-development: 12 commits ahead, newest commit 3 minutes old, Pipeline Runner Tests still running → STOP, correctly, on two independent gates.

pytest heimdall/tests 479 passed (28 new) · ruff clean.

## Scope

Decision core only. The workflow that gathers state, takes the backup, opens and merges the release PR, watches CD and rolls back follows separately — that part reuses the existing /prod-release finalize logic, and this is the piece where the subtle correctness lives.

## Business Value

main is 12 commits ahead of production right now, and the last release was yesterday. Every hour of that is finished, reviewed, merged work users don't have. Now that Heimdall merges its own fixes, a manual release step would just move the queue one stage later — pipeline fixes would sit merged-but-undeployed exactly as they used to sit approved-but-unmerged. This is the gate that makes automating it defensible rather than reckless.

## Manual Effort Estimate

~4 hours for this piece — the gate logic is straightforward; discovering that /status is useless on this repo and that advisory jobs were silently vetoing releases is what took the time, and both were only findable by running it against live data. *(Proposed by Claude — Keval to confirm or adjust.)*

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

## Summary

- Keep committed Clerk deployments independent of Preview-only environment variables

- Regenerate the checked-in Convex API bindings with the release-pinned CLI

- Document Aerie's committed Convex generated-code policy

## Why

The provider-neutral auth change made ordinary Clerk codegen evaluate

AERIE_AUTH_PROVIDER, even though the documented contract says an unset value

means Clerk. Convex therefore rejected codegen on a correctly configured Clerk

dev deployment, and the same mismatch could block production Convex CD.

The release-head generated API was also missing existing Forge modules because

it had not been regenerated from the integrated source tree.

## Business Value

Keeps production Clerk deployment fail-closed while allowing codegen and CD

without Preview-only configuration, and ensures fresh checkouts receive complete

Convex API types.

## Test plan

- [x] pnpm --dir chat exec vitest run convex/authProviders.test.ts --maxWorkers=1

- [x] pnpm --dir chat typecheck

- [x] pnpm exec biome check chat/convex/auth.config.ts chat/convex/authProviders.ts chat/convex/authProviders.test.ts

- [x] pnpm --dir chat exec convex codegen --typecheck disable against dev:fleet-goat-601

- [x] Repeated codegen produced the same api.d.ts SHA-256

- [x] Pre-commit Convex path, Biome, and Chat typecheck hooks

## Summary

- Recognize the assessment and reshadow Application-family statuses in the shadow-appointment assertion

## Why

PR #1151 added cog_at_scheduled, cog_at_passed, and reshadow to the Application routing contract, but the older assertion retained its original allowlist. Once source data exercised one of those statuses, the hourly dbt build failed despite the model routing it correctly.

## Business Value

Restores hourly admissions mart refreshes while retaining the guard against moving downstream or terminal enrollments backward.

## Test plan

- [x] Parse the full dbt project with dbt 1.12.0 and dbt-redshift 1.11.0

- [x] Confirm dbt discovers assert_finalsite_pipeline_shadow_appt_only_from_app among all 145 tests

- [x] git diff --check

- [x] Isolated warehouse-backed PR dbt build passed in GitHub Actions

## Summary

- Add API v2 aggregate/detail coverage for the remaining Admissions dashboard surfaces

- Expose capability-filtered Agent tools that execute through the same API v2 contracts

- Preserve dashboard query semantics while restricting external detail projections and cursor data

## Why

Admissions users could inspect Pipeline, Community Funnel, Established Funnel, and Community Deposit data in dashboards, but the Aerie Agent could not access the same information. This creates API/dashboard/Agent drift and prevents the Agent from answering straightforward questions using the platform source of truth.

## Business Value

The Agent now receives dashboard-parity tools only when the current user has the matching capability, and every tool call is reauthorized through the user current grants. Reusing API v2 makes future API improvements flow directly to Agent users and gives one contract to validate.

## Test plan

- [x] Contracts, Chat, and both Flue worker typechecks

- [x] 233 dashboard and Agent-run tests

- [x] 55 API/OpenAPI contract tests

- [x] 79 shared contract tests

- [x] 40 Flue worker tests

- [x] Architecture, Convex path, read-bound, Biome, and diff checks

## Summary

- Add a provider-neutral authentication boundary with WorkOS support for isolated Convex Previews

- Add deterministic non-interactive Preview sign-in and full Preview verifier provisioning

- Move API-key management into the Tools surface while retaining URL compatibility

## Why

Aerie's Clerk/Google-specific authentication prevented Rookery's browser verifier from exercising signed-in product flows. This adds a fail-closed Preview-only WorkOS path that uses real provider sessions and canonical Convex authorization without changing production's Clerk boundary.

## Business Value

Rookery and ordinary developers can validate authenticated Aerie branches deterministically against isolated Convex Previews, including capability-gated and API-key flows.

## Breaking changes

None. Production remains Clerk-backed; WorkOS requires explicit Preview-only configuration.

## Test plan

- [x] pnpm check

- [x] Full Chat suite: 669 files, 9,787 passed, 18 skipped

- [x] Focused auth, Preview provisioning, token lifecycle, middleware, callback, bootstrap, and API-key tests

- [x] Manual Rookery browser verification of authenticated product flows

## Summary

- Resolve snapshot source publications from the authoritative ECS run-result envelope

- Grant read-only access to the exact run-result prefix while retaining fail-closed identity checks

## Why

The first production Finalsite freshness trigger failed because the snapshot runner expected source status and publication fields inside the Step Functions output. ECS orchestration exposes only its run ID there; the validated source result is stored in the standard S3 run-result side channel.

## Business Value

Restores automated Finalsite and SIS student school-year snapshot refreshes without weakening source lineage or allowing partial upstream runs to publish forecast data.

## Test plan

- [x] 51 focused snapshot runner tests

- [x] Real failed Finalsite execution resolves to an explicit no-write freshness success

- [x] Real successful SIS execution resolves to its accepted source run ID

- [x] Hosted Pipeline CDK and full runner suites

- [x] Ruff, Biome, typecheck, Surtr tests, and Mercy review

## Summary

- Restore bounded two-worker Vitest parallelism and split Chat tests into explicit Edge, Node, and browser projects

- Add executable routing and discovery guardrails so every test has one deterministic runtime

- Harden shared isolation and document the canonical test authoring and validation workflow

## Why

The Chat suite had grown to roughly nineteen minutes because every file ran serially through jsdom. Earlier attempts to parallelize exposed shared-state and timestamp assumptions, while ambiguous test naming made runtime selection difficult to reason about. This change repairs those isolation gaps, moves DOM-free tests out of jsdom, and makes the new architecture enforceable for future contributors.

## Business Value

Developers and agents receive repository-wide test feedback in roughly four minutes instead of roughly twenty, with clearer local commands and stronger protection against flaky, order-dependent, or accidentally undiscovered tests.

## Test plan

- [x] pnpm lint:test-architecture

- [x] pnpm --dir chat typecheck

- [x] pnpm --dir sync typecheck

- [x] pnpm test — full repository suite green in 4m06s on the rebased PR head

## Summary

- Promote Articles to stable art_* platform resources with API v2 read, create, edit, and publish operations

- Add structured @Article targeting with immutable run snapshots and bounded Flue context

- Route UI and API lifecycle changes through shared authorized Article writers

## Why

Articles were only usable through the Forge UI. Agents could not target them, API consumers could not manage them, and external identity, concurrency, and rollout controls were missing. This establishes one governed Article resource across UI, API, and agent execution while keeping unpublished content editor-only.

## Business Value

Users and automations can create and maintain the same versioned knowledge resources, and agents can reliably ground runs in explicitly targeted Articles without copying content into prompts.

## Test plan

- [x] pnpm check

- [x] 302 focused Chat tests covering UI, API, targeting, snapshots, authorization, idempotency, concurrency, OpenAPI, and route manifests

- [x] 33 focused Flue worker tests

- [x] 47 focused contracts tests

- [ ] Complete local UI/API runtime smoke after review hardening

## Summary

- Use normalized open status, rather than lifecycle stage, to decide whether Portfolio surfaces current enrollment

- Keep list, bulk, detail, and field-card payloads aligned on the same eligibility rule

- Add regression coverage for open buildout and non-open operating sites

## Why

Open campuses can legitimately remain in the buildout lifecycle stage while regulatory or expansion work continues. Portfolio previously withheld valid Admissions enrollment from those sites even though the UI identified them as open.

## Business Value

Portfolio dashboards and site details now show current enrollment consistently for every open campus without exposing it for non-open sites.

## Test plan

- [x] 89 focused Portfolio tests

- [x] Chat TypeScript typecheck

- [x] Biome check for all modified files

- [x] git diff --check

## Summary

- Define a canonical derived operational status for Backup Site assignments and expose it through REST and MCP catalogue reads

- Surface bounded linked-site evidence and completeness so consumers can distinguish active, inactive, and inconclusive results

- Add read-only status context to the Backup Sites admin catalogue with migration-safe compact projections and UTC-midnight refresh

## Why

Historical Backup Site contract terms remain useful records, but they were indistinguishable from assignments that are still operationally relevant. As a result, sites later marked Not Required could continue appearing as though they currently needed a backup. This change preserves historical catalogue records while making current assignment eligibility explicit and derived from the selected link, site requirement status, location state, resolvable location identity, and contract end date.

## Business Value

Users and agents can answer which sites currently have usable backups without conflating retained contract history with active need. The status is non-editable, follows source data automatically, refreshes at the UTC date boundary, and fails closed when migration evidence is incomplete.

## Test plan

- [x] 885 shared-contract tests

- [x] 55 focused Backup Sites UI, Convex, migration, REST, and OpenAPI tests

- [x] 34 Rhodes MCP parity and Portfolio contract tests

- [x] 9 Rhodes MCP Backup Site tool tests

- [x] Chat, Convex, contracts, and worker typechecks

- [x] Architecture boundaries, Convex paths, read bounds, Biome, and diff checks

- [x] Development Convex deployment; candidate and operational-snapshot backfills completed, then verifier checked the full one-row dataset with zero issues

- [x] UTC-midnight subscription-key regression and old-bundle query compatibility covered by focused tests

- [x] Authenticated development UI smoke on the initial feature head; final UI identity and incomplete-evidence behavior covered by focused tests

- [ ] Deploy Convex before the application bundle, run both Backup Site backfills, and exhaust every paginated verification page before treating inactive results as conclusive

Automated fix for netsuite-saved-search-refresh — fix_class code_fix, scope tier draft.

Resolves https://github.com/AI-Builder-Team/Surtr/issues/1259

> Ready for review — verification is green; HEIMDALL_READY_PRS opens verified tier-draft fixes ready for review. A human still merges — auto-merge never applies outside tier auto.

## What's broken

Run 7b57678c-8035-4ee8-81c6-3871cb7eda1c of netsuite-saved-search-refresh failed at pipelines/runners/netsuite-saved-search-refresh/src/handler.py:123 with RuntimeError: Required daily inputs do not share a complete netsuite-raw run: {'accounts_payable_accounting_line': ['d16863ed-10e8-437d-b596-aea0538c14ab', 'd16863ed-10e8-437d-b596-aea0538c14ab-transaction-line-deleted-parents'], 'vendor_purchase_order': [...]}. The two run ids in the error are the SAME base netsuite-raw run — they differ only by the deterministic -transaction-line-deleted-parents suffix — so the underlying raw data is complete, but the completeness guard rejects it as a split boundary. This is a false-positive gate, not missing data: the Lambda ran only 2.9s, refreshed no saved-search replacements, and skipped the Vendor Management purchase-order mart, so the run wrote zero rows to core_finance_netsuite.accounts_payable_accounting_line, core_finance_netsuite.vendor_purchase_order, and mart_finance.vendor_management_purchase_order.

Root cause. netsuite-raw publishes raw_transaction_line first in incremental mode under the base run id d16863ed-10e8-437d-b596-aea0538c14ab, then runs two follow-up reconciliation passes on the same table under derived ids {run_id}-transaction-line-parents and {run_id}-transaction-line-deleted-parents (pipelines/runners/netsuite-raw/src/handler.py:1329-1342), each writing a later-timestamped ingestion_ledger row for table_name='raw_transaction_line'. In the refresh, source_publications_query (pipelines/runners/netsuite-saved-search-refresh/src/sql.py:14-39) selects the newest publication per table via QUALIFY ROW_NUMBER() ... ORDER BY publication_timestamp DESC = 1, so raw_transaction_line resolves to the -transaction-line-deleted-parents reconciliation row while every sibling daily input resolves to the base run id. _validate_sources (handler.py:114-126) then builds daily_run_ids as a raw set of surtr_run_id values, finds two distinct ids, and raises — even though both derive from one complete netsuite-raw run.

## What this PR changes

In pipelines/runners/netsuite-saved-search-refresh/src, teach the source-completeness check that netsuite-raw's transaction-line reconciliation publications belong to their base run: normalize each publication's surtr_run_id by stripping the two deterministic reconciliation suffixes ('-transaction-line-parents' and '-transaction-line-deleted-parents', exactly as produced at pipelines/runners/netsuite-raw/src/handler.py:1329-1342) before building daily_run_ids in _validate_sources, and report the normalized base id in the returned source_runs mapping. Keep the change confined to handler.py (and/or a small helper in sql.py) and leave the age/staleness checks untouched — the newest reconciliation publication is only fresher, so staleness is unaffected. Critically, do NOT loosen the guard for arbitrary mismatches: two genuinely different base run ids (different UUIDs) must still fail; only the known derived suffixes collapse to their base. Add a unit test under tests/ that feeds a raw_transaction_line publication carrying the '-transaction-line-deleted-parents' suffix alongside base-id sibling inputs and asserts validation passes and that source_runs reports the base id.

Why this fixes it. The defect and its fix live entirely inside the pipeline's own Tier-A directory (pipelines/runners/netsuite-saved-search-refresh/src/handler.py and sql.py): the guard misclassifies netsuite-raw's suffixed reconciliation publications as a distinct run, so the correct blast radius is the guard's run-id comparison, not any SQL rewrite or upstream change. The suffixes are deterministic and emitted verbatim by netsuite-raw (handler.py:1329-1342: '-transaction-line-parents', '-transaction-line-deleted-parents'), so stripping exactly those before comparison is precise and preserves the safety invariant — mismatched base UUIDs still fail — while unblocking a run whose raw inputs are in fact complete. This warrants a substantial code_fix with a regression test rather than a config tweak, because the current behavior silently blocks every future daily refresh of the AP accounting-line and vendor-PO governed models the moment netsuite-raw emits its deleted-parent reconciliation, writing zero rows downstream.

### Files changed

 .../netsuite-saved-search-refresh/src/handler.py   | 33 +++++++++++++-
.../tests/test_handler.py                          | 52 ++++++++++++++++++++++
2 files changed, 83 insertions(+), 2 deletions(-)

## Verification

### pytest (pipelines/runners/netsuite-saved-search-refresh/tests) — exit 0

============================= test session starts ==============================
platform linux -- Python 3.11.15, pytest-9.1.1, pluggy-1.6.0
rootdir: /home/runner/work/Surtr/Surtr/publish/pipelines/runners/netsuite-saved-search-refresh
configfile: pyproject.toml
plugins: mock-3.15.1
collected 59 items
tests/test_accounts_payable_sql.py ....                                  [  6%]
tests/test_configuration.py ..                                           [ 10%]
tests/test_handler.py ..........................                         [ 54%]
tests/test_redshift_client.py .                                          [ 55%]
tests/test_sql.py ...........                                            [ 74%]
tests/test_vendor_management_mart.py ........                            [ 88%]
tests/test_vendor_purchase_order_sql.py .......                          [100%]
============================== 59 passed in 0.33s ==============================

<details>

<summary>Run metadata</summary>

| Field | Value |

| --- | --- |

| Pipeline | netsuite-saved-search-refresh |

| Failing run | 7b57678c-8035-4ee8-81c6-3871cb7eda1c |

| Occurrence | 1 (times this exact failure signature has been seen) |

| Signature | 2ecc63a9cbc93958d3cdfde8f0b9aef0ba9e90df69d1c35235663d14ca2a9c6a |

| Verify | green |

</details>

---

🤖 Opened by heimdall. mercy reviews this PR automatically; heimdall revises on REQUEST_CHANGES (bounded rounds). Tier-auto PRs may auto-merge on mercy approval when the consumer enables it; everything else waits for a human. Mention heimdall in a comment to direct it, or add the manual-dev label to take the PR over and stop it entirely.

Automated fix for aws-spend-insights — fix_class code_fix, scope tier auto.

Resolves https://github.com/AI-Builder-Team/Surtr/issues/1036

- Run: issue

- Signature: 7b25c001251c8da33e5a3bf1caefe09a3bfca0caa5399cdf0738616f3a27c5d0

- Verify: green

## Proof

### pytest (pipelines/runners/aws-spend-insights/tests) — exit 0

builder.py::TestQueryPortfolioSummary::test_param_count_matches_placeholders PASSED [ 55%]
tests/test_context_builder.py::TestQueryPortfolioSummary::test_returns_expected_shape PASSED [ 56%]
tests/test_context_builder.py::TestQueryPortfolioSummary::test_raises_when_v2_budget_returns_null PASSED [ 58%]
tests/test_context_builder.py::TestDetectCurrentQuarter::test_returns_quarter PASSED [ 60%]
tests/test_context_builder.py::TestDetectCurrentQuarter::test_raises_when_quarter_is_null PASSED [ 61%]
tests/test_handler.py::TestValidateInsights::test_valid_insight_passes PASSED [ 63%]
tests/test_handler.py::TestValidateInsights::test_empty_list_raises PASSED [ 64%]
tests/test_handler.py::TestValidateInsights::test_missing_section_raises PASSED [ 66%]
tests/test_handler.py::TestValidateInsights::test_invalid_section_raises PASSED [ 67%]
tests/test_handler.py::TestValidateInsights::test_missing_severity_raises PASSED [ 69%]
tests/test_handler.py::TestValidateInsights::test_invalid_severity_raises PASSED [ 70%]
tests/test_handler.py::TestValidateInsights::test_missing_headline_raises PASSED [ 72%]
tests/test_handler.py::TestValidateInsights::test_missing_details_raises PASSED [ 73%]
tests/test_handler.py::TestBuildOutput::test_all_fields_populated PASSED [ 75%]
tests/test_handler.py::TestBuildOutput::test_output_schema_structure PASSED [ 76%]
tests/test_handler.py::TestHandlerOrchestration::test_writes_byte_identical_s3_path PASSED [ 78%]
tests/test_handler.py::TestHandlerOrchestration::test_body_is_valid_json_matching_output_schema PASSED [ 80%]
tests/test_handler.py::TestHandlerOrchestration::test_quarter_override_from_params_skips_detection PASSED [ 81%]
tests/test_handler.py::TestHandlerOrchestration::test_zero_insights_fails_before_s3_write PASSED [ 83%]
tests/test_handler.py::TestHandlerOrchestration::test_context_failure_propagates PASSED [ 84%]
tests/test_prompts.py::TestBuildSystemPrompt::test_all_sections_injected PASSED [ 86%]
tests/test_tool_implementations.py::TestEmitAllInsights::test_batch_of_multiple_insights PASSED [ 87%]
tests/test_tool_implementations.py::TestEmitAllInsights::test_optional_fields_default PASSED [ 89%]
tests/test_tool_implementations.py::TestEmitAllInsights::test_return_value_counts PASSED [ 90%]
tests/test_tool_implementations.py::TestExecuteTool::test_dispatches_to_emit_all_insights PASSED [ 92%]
tests/test_tool_implementations.py::TestExecuteTool::test_dispatches_to_redshift_tool PASSED [ 93%]
tests/test_tool_implementations.py::TestExecuteTool::test_unknown_tool_returns_error PASSED [ 95%]
tests/test_tool_implementations.py::TestClassBreakdownMissingFlags::test_budget_missing_nulls_variance PASSED [ 96%]
tests/test_tool_implementations.py::TestClassBreakdownMissingFlags::test_standard_row_preserves_variance PASSED [ 98%]
tests/test_tool_implementations.py::TestAccountBreakdownMissingFlags::test_budget_missing_nulls_variance PASSED [100%]
============================== 65 passed in 1.08s ==============================

---

🤖 Opened by heimdall. mercy reviews this PR automatically; heimdall

revises on REQUEST_CHANGES (bounded rounds). Tier-auto PRs may

auto-merge on mercy approval when the consumer enables it; everything

else waits for a human.

Linear: [AI-606](https://linear.app/builder-team/issue/AI-606/p02-drain-the-14-mercy-approved-but-unmerged-heimdall-prs) · Project: [Heimdall Software Factory](https://linear.app/builder-team/project/heimdall-software-factory-4216613b8e5f)

My regression, shipped in [#46](https://github.com/AI-Builder-Team/mercy/pull/46) an hour ago. Found because it broke a live PR.

## What broke

Surtr [#1037](https://github.com/AI-Builder-Team/Surtr/pull/1037): Heimdall resolved the merge conflicts, Validate revision passed — and then publish died:

line 46: BASE_REF: unbound variable
##[error]Process completed with exit code 1.

The warning message I added used ${BASE_REF}; that step's env defines BASE_REF_ENV. Under set -u that is fatal, so the job failed *after* the agent had done all the work.

Ironic, given #46 was about making that step's failures diagnosable.

## Why nothing caught it

- bash -n can't — the syntax is perfectly valid.

- actionlint can't — it doesn't cross-reference run-block variables against step env.

- Mercy didn't — the mismatch is between a run block and a *different key* in the same step's env. Nothing diff-local connects those two lines.

It only appears at run time, in a step that runs last.

## So the fix ships with a lint

test_workflow_env_refs walks every step, collects what is genuinely defined for it — job env, step env, runner-provided, and assignments in the script — and fails on any ${VAR} that isn't among them.

Getting the assignment forms right was the actual work. The first draft anchored to line start and produced eleven false positives, which would have made the lint unusable and got it deleted within a week:

| Form | Example | First draft |

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

| multi-variable read | read -r HEAD_REF HEAD_SHA STATE … | only saw HEAD_REF |

| command position | if ! ISSUE_URL=$(gh issue create) | missed entirely |

Both are handled, and there are unit tests for each so a future simplification doesn't quietly reintroduce the noise.

## Verified both directions

clean workflow           -> passes
${BASE_REF} reinstated   -> FAILED: revise_publish/Push revision: ${BASE_REF}

A lint that has never been shown to fail is not evidence of anything.

pytest heimdall/tests 450 passed (4 new) · ruff clean · actionlint clean.

## Business Value

The immediate value is unblocking conflict resolution — three of the remaining stranded PRs are conflicting, and every one of them would have hit this. The larger value is the class: workflow logic lives in ~3,600 lines of embedded bash where a typo'd variable name is invisible to every tool in the pipeline until a production run fails at the last step. This makes that class a build failure instead, which matters more as Heimdall runs unattended — a job that dies after the agent has worked is expensive twice over.

## Manual Effort Estimate

~1.5 hours — the one-word fix took a minute; tracing a "Publish failed" with no visible error back to it, and then building a lint precise enough to be worth keeping, was the rest. *(Proposed by Claude — Keval to confirm or adjust.)*

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

## Summary

- Add source-backed Finalsite/SIS student snapshots, canonical Student identity, and governed Forecast detail contracts

- Rebuild HubSpot-backed Forecast marts from Clean/Core inputs with exact provenance and atomic fail-closed refreshes

- Add event and scheduled refresh ownership so accepted warehouse contracts remain current

## Why

The existing Forecast depended on opaque EDUCRM outputs and could not guarantee that its main values and drilldowns came from the same accepted detail facts. This establishes a source-backed baseline where Finalsite owns current enrollment, SIS supplies lifecycle evidence, HubSpot supplies the admissions pipeline and historical fallback, and QuickBooks supplies accounting evidence. Publication now stops when upstream Core and Clean boundaries do not reconcile.

## Business Value

Education Operations and Finance gain an auditable enrollment and admissions baseline that can support Forecast reporting without silently treating unknowns, stale inputs, or legacy marts as source truth.

## Test plan

- [x] 48 snapshot, 30 Forecast, 252 HubSpot Clean, 116 HubSpot Core, 120 HubSpot mart, and 66 ontology tests

- [x] Ruff lint and format checks across all pipelines

- [x] TypeScript build and 807 non-Docker CDK tests locally

- [x] 92-statement snapshot DDL dry-run and read-only Redshift lineage/crosswalk checks

- [x] Hosted CI, including the complete Docker-backed CDK and repository-wide runner suites

- [ ] Warehouse deployment and first scheduled refresh (separate post-merge operation)

Linear: [AI-606](https://linear.app/builder-team/issue/AI-606/p02-drain-the-14-mercy-approved-but-unmerged-heimdall-prs) · Project: [Heimdall Software Factory](https://linear.app/builder-team/project/heimdall-software-factory-4216613b8e5f)

Found while draining the stranded-PR backlog.

## What happened

Surtr [#1260](https://github.com/AI-Builder-Team/Surtr/pull/1260), today. I summoned Heimdall to fix a test that main had broken. It came back and declined, saying:

> The merge hasn't happened in my checkout … HEAD is the PR head (bed0f004); origin/main has moved to 7aa50a1e but is not merged in. The consolidation-rate coverage preflight you're describing … is completely absent from this branch.

It was right, and it behaved correctly. The base sync had run and failed:

##[warning]merge of main failed with no conflict entries — sync aborted.

That is the entire diagnostic record, because the step runs the merge as >/dev/null 2>&1. Why it failed is still unknown — the reason was thrown away.

The downstream behaviour is fine: sync aborts, the agent gets an unmerged tree, notices, and refuses rather than guessing. The failure is that nobody can find out why.

## The fix

Keep stderr. Both merge sites capture it and print it prefixed on failure:

::warning::merge of main failed with no conflict entries — sync aborted. git said:
git: <the actual reason>

The publish-side merge had the same shape and would silently push a revision with no merge parent — reported only as a warning with no cause.

A lint keeps every working git merge from discarding its error again. --abort is exempt: it is cleanup with a reset --hard fallback, so its failure genuinely doesn't matter.

## One thing I did NOT claim

I also set a committer identity in the sync step, which had none where the publish step does. That is defensive, not a diagnosis — I tested it, and git merge --no-commit --no-ff succeeds perfectly well without an identity:

no identity   -> SUCCEEDED
with identity -> SUCCEEDED

So it is not the cause. I nearly wrote a comment asserting it was, which would have left a confident and wrong explanation in the file for whoever hits this next. The cause remains unknown, and the point of this PR is that the next occurrence will say.

## Verification

pytest heimdall/tests 445 passed (1 new) · ruff clean · actionlint clean.

## Business Value

The base sync is what lets Heimdall revise a PR against a moved main — the single most common state for an agent PR more than a day old, and three of the remaining stranded PRs are conflicting right now. When it aborts silently, the agent looks like it is refusing work it could have done, which is exactly the "Heimdall is too timid" impression this project set out to fix. This one is unusually cheap: the diagnosis was already being produced and then discarded.

## Manual Effort Estimate

~1 hour — the change is small; the value was in tracing a correct-looking refusal back to a swallowed error, and in checking the obvious explanation rather than shipping it as fact. *(Proposed by Claude — Keval to confirm or adjust.)*

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

Automated fix for collections-collectiq-sync-v2 — fix_class code_fix, scope tier draft.

Resolves https://github.com/AI-Builder-Team/Surtr/issues/1579

> Ready for review — verification is green; HEIMDALL_READY_PRS opens verified tier-draft fixes ready for review. A human still merges — auto-merge never applies outside tier auto.

## What's broken

Run 25df35a6-04e7-4321-86d3-bb2be692d349 of collections-collectiq-sync-v2 failed with StructuralError: Unparseable money value: '#VALUE!' raised at pipelines/runners/collections-collectiq-sync-v2/src/parsers.py:97 (parse_money), reached via parse_collectiq at parsers.py:211 while reading the x_forecast cell of the CollectIQ tab. The CloudWatch tail shows the identical '#VALUE!' on all 8 read+parse attempts across ~120s of backoff (08:15:22 → 08:16:53), so this is a persistent Google Sheets formula-error literal in the source tab, not the transient recalculation blip the retry loop assumes; the run wrote zero rows because parse_collectiq raises before RedshiftLoader.full_replace runs, leaving staging_finance_gsheets.collections_collectiq_snapshot intact but stale. This is the 2nd occurrence of this exact signature, and prior PRs #1334 and #1376 already added and then widened the #VALUE! retry budget (3→8 attempts), which cannot help a value that stays broken across the entire window.

Root cause. A cell feeding one BU's money column on the source CollectIQ tab (Google Sheet 1C2BI7sWAjPoXPxN6fF7ZwSt64JrvGotuIdM0YB8LTDA) contains a persistent #VALUE! spreadsheet formula error, and parse_money at parsers.py:85-97 correctly refuses to coerce a present-but-non-numeric value to NULL, raising StructuralError to fail loud. The broken formula lives in the source sheet and no in-repo change makes those numbers parseable; however, the raised error is unactionable because parse_money carries only the offending value ('#VALUE!') and parse_collectiq at parsers.py:200-214 does NOT add the surrounding context, even though errors.py:6-8 explicitly states the caller that knows the sheet/tab/BU is responsible for adding it. As a result nobody can tell WHICH BU column or WHICH metric row (Collections Forecast / QTD / This Week) holds the broken cell, which is why this pipeline has accumulated open, unresolved other triage issues (#1329, #883, #1110).

## What this PR changes

Do NOT widen the retry budget again — PR #1376 already proved that path futile for a persistent #VALUE!, and burning 122s of Lambda time on a value that never clears only delays the same failure. Instead make the failure pinpoint the source cell: in parse_collectiq (pipelines/runners/collections-collectiq-sync-v2/src/parsers.py, the loop at lines 200-214), wrap each parse_money call so a StructuralError names the exact BU column (header[col_idx]) and metric row (Collections Forecast / QTD Collections / This Week's Collections) and re-raises with that context prepended, honoring the contract errors.py:6-8 already documents. Add a test in pipelines/runners/collections-collectiq-sync-v2/tests/test_parsers.py asserting that a #VALUE! in a given money column raises a StructuralError whose message contains both the BU name and the metric label, so triage issues become instantly actionable and the sheet owner can fix the one broken cell in seconds.

Why this fixes it. The change is confined to the pipeline's own directory (Tier A: src/parsers.py plus a test under tests/), matches the code_fix catalogue entry for missing structured failure reporting, and preserves the pipeline's fail-loud, never-load-wrong-data behavior — it does not paper over the failure, it makes the recurring failure diagnosable. It is the right blast radius because the defect this repo CAN fix is the missing context on the raised error (errors.py:6-8 assigns that responsibility to parse_collectiq, which currently neglects it), not the source spreadsheet and not the retry loop that two prior PRs already exhausted. Naming the BU and metric turns an opaque Unparseable money value: '#VALUE!' into a one-line pointer to the exact source cell, which is precisely what the unresolved other issues for this pipeline have lacked.

### Files changed

 .../collections-collectiq-sync-v2/src/parsers.py   | 27 +++++++++++++++--
.../tests/test_parsers.py                          | 34 ++++++++++++++++++++++
2 files changed, 58 insertions(+), 3 deletions(-)

## Verification

### pytest (pipelines/runners/collections-collectiq-sync-v2/tests) — exit 0

``

ests/test_handler.py::TestTransientValueErrorRetry::test_persistent_value_error_still_fails_after_retries PASSED [ 43%]

tests/test_handler.py::TestTransientValueErrorRetry::test_recovers_after_five_transient_reads PASSED [ 45%]

tests/test_handler.py::TestReadWithRetry::test_succeeds_first_try PASSED [ 47%]

tests/test_handler.py::TestReadWithRetry::test_retries_transient_then_succeeds PASSED [ 49%]

tests/test_handler.py::TestReadWithRetry::test_nonretryable_raises_immediately PASSED [ 50%]

tests/test_handler.py::TestReadWithRetry::test_gives_up_after_max_retries PASSED [ 52%]

tests/test_handler.py::TestReadWithRetry::test_retries_429_rate_limit PASSED [ 54%]

tests/test_handler.py::TestReadWithRetry::test_status_message_fallback_when_response_has_no_int_status PASSED [ 56%]

tests/test_handler.py::TestReadWithRetry::test_nonpositive_max_retries_raises PASSED [ 58%]

tests/test_parsers.py::TestParseMoney::test_plain PASSED [ 60%]

tests/test_parsers.py::TestParseMoney::test_parentheses_negative PASSED [ 61%]

tests/test_parsers.py::TestParseMoney::test_accounting_dash_is_zero PASSED [ 63%]

tests/test_parsers.py::TestParseMoney::test_blank_is_none PASSED [ 65%]

tests/test_parsers.py::TestParseMoney::test_two_decimal_rounding PASSED [ 67%]

tests/test_parsers.py::TestParseMoney::test_unparseable_nonblank_raises PASSED [ 69%]

tests/test_parsers.py::TestParseDate::test_day_mon_year PASSED [ 70%]

tests/test_parsers.py::TestParseDate::test_blank_is_none PASSED [ 72%]

tests/test_parsers.py::TestParseDate::test_unparseable_nonblank_raises PASSED [ 74%]

tests/test_parsers.py::TestFindColumn::test_exact_and_prefix PASSED [ 76%]

tests/test_parsers.py::TestMakeHeadersUnique::test_dedup PASSED [ 78%]

tests/test_parsers.py::TestParseCollectIQ::test_columns_constant PASSED [ 80%]

tests/test_parsers.py::TestParseCollectIQ::test_all_bus_emitted_cloudfix_skipped PASSED [ 81%]

tests/test_parsers.py::TestParseCollectIQ::test_vanished_canonical_bu_column_raises PASSED [ 83%]

tests/test_parsers.py::TestParseCollectIQ::test_quarter_suffix_mismatch_raises PASSED [ 85%]

tests/test_parsers.py::TestParseCollectIQ::test_missing_bu_header_raises PASSED [ 87%]

tests/test_parsers.py::TestParseCollectIQ::test_missing_metric_row_raises PASSED [ 89%]

tests/test_parsers.py::TestParseCollectIQ::test_unparseable_money_cell_names_bu_and_metric PASSED [ 90%]

tests/ …_(truncated)_

<details>

<summary>Run metadata</summary>

| Field | Value |

| --- | --- |

| Pipeline | collections-collectiq-sync-v2 |

| Failing run | 25df35a6-04e7-4321-86d3-bb2be692d349 |

| Occurrence | 2 (times this exact failure signature has been seen) |

| Signature | 0f1de19fa283672d036ee45e6ef1f1569c12bcb70166101210f68535d7364a4b |

| Verify | green |

</details>

---

🤖 Opened by heimdall. mercy reviews this PR automatically; heimdall revises on REQUEST_CHANGES (bounded rounds). Tier-auto PRs may auto-merge on mercy approval when the consumer enables it; everything else waits for a human. Mention heimdall in a comment to direct it, or add the manual-dev` label to take the PR over and stop it entirely.

Automated fix for aws-spend-pipeline — fix_class code_fix, scope tier auto.

Resolves https://github.com/AI-Builder-Team/Surtr/issues/1042

- Run: issue

- Signature: 0068f0b483cfe13daf09622bd316eee724913ffc3b156e5eeffac617182b0227

- Verify: green

## Proof

### pytest (pipelines/runners/aws-spend-pipeline/tests) — exit 0

============================= test session starts ==============================
platform linux -- Python 3.11.15, pytest-9.1.1, pluggy-1.6.0
rootdir: /home/runner/work/Surtr/Surtr/publish/pipelines/runners/aws-spend-pipeline
plugins: mock-3.15.1
collected 41 items
tests/test_cost_explorer.py ........                                     [ 19%]
tests/test_cost_records.py ............                                  [ 48%]
tests/test_handler.py ...                                                [ 56%]
tests/test_net_amortized_cost_explorer.py ...                            [ 63%]
tests/test_net_amortized_cost_records.py ........                        [ 82%]
tests/test_net_amortized_handler.py ...                                  [ 90%]
tests/test_redshift_handler.py ....                                      [100%]
============================== 41 passed in 0.42s ==============================

---

🤖 Opened by heimdall. mercy reviews this PR automatically; heimdall

revises on REQUEST_CHANGES (bounded rounds). Tier-auto PRs may

auto-merge on mercy approval when the consumer enables it; everything

else waits for a human.

Automated fix for netsuite-balance-sheet — fix_class code_fix, scope tier draft.

Resolves https://github.com/AI-Builder-Team/Surtr/issues/1138

> Draft — a human must promote this before merge. Because the diff lands in scope tier draft.

## What's broken

Run ba6df4dc-19cf-4e3b-9d37-c15fc3329d4c (a backfill of netsuite-balance-sheet) reported "Pipeline completed: 34/34 succeeded, 7851 total rows loaded" yet silently stored several months of data under the wrong accounting period. The offending log lines show files whose S3 filename month disagrees with the CSV line-4 header month, e.g. "Reading s3://netsuite-wrapper-reports/Balance_Sheet_EOM/2026-03-31.csv" immediately followed by "Period from CSV header: 'End of Feb 2026' -> 2026-02-28" and "Parsed 257 rows from Balance_Sheet_EOM/2026-03-31, accounting period: 2026-02-28". Because pipelines/runners/netsuite-balance-sheet/src/s3_reader.py derives period_end_date only from the header (parse_period_label) and never checks it against the filename date, March/May/June/July 2026 data was loaded under the prior month's key, and the DELETE-then-INSERT in redshift_handler.py then overwrote the genuine 2026-02-28 rows — wrong data with a SUCCESS verdict.

Root cause. read_balance_sheet_csv in src/s3_reader.py trusts the CSV line-4 period label as the sole source of period_end_date and performs no cross-check against the S3 filename date it is passed (date_str), so when the upstream NetSuite export emits a stale header — the historical invariant that file-month equals header-month (e.g. 2024-11-30.csv -> 'End of Nov 2024') broke starting with 2026-03-31.csv -> 'End of Feb 2026' — the wrong period key flows straight through _process_date in handler.py into load_balance_sheet. There load_balance_sheet in redshift_handler.py runs DELETE FROM ... WHERE period_end_date = %s followed by INSERT, so the mistagged March file did not merely add a duplicate but overwrote the correct February rows, and four distinct months (2026-02-28, 2026-04-30, 2026-05-31, 2026-06-30) now hold the wrong month's balance sheet.

## What this PR changes

In pipelines/runners/netsuite-balance-sheet/src/s3_reader.py, add a validation step in read_balance_sheet_csv that the parsed period_end_date falls in the same calendar year-month as the already-validated filename date_str, and raise ValueError (the exception _process_date/handler.py already catch and surface as a failed period) when they disagree, so a stale header fails loudly instead of silently writing under the wrong key. Add a focused unit test in tests/test_s3_reader.py covering both the matching case (2026-03-31.csv header 'End of Mar 2026' passes) and the drift case (2026-03-31.csv header 'End of Feb 2026' raises), and keep the change entirely within the pipeline directory. Do not touch the Redshift DELETE/INSERT logic or attempt the separate one-off data correction of the four mistagged periods — that backfill re-run is an operational task outside this code fix.

Why this fixes it. This is a silent wrong-data defect confined to the pipeline's own directory (Tier A), which the code_fix class exists for: the correct remedy is a real guard plus a test, not a config tweak. Validating that the header-derived period_end_date shares the file date's calendar month is the minimal, correct blast radius — it converts an invisible mis-keying into an explicit ValueError that handler.py's existing error path reports as a failed period, without altering the DELETE/INSERT loading semantics or widening into SQL rewrites or the historical data correction.

### Files changed

 .../netsuite-balance-sheet/src/s3_reader.py        | 13 +++++++++++
.../netsuite-balance-sheet/tests/test_s3_reader.py | 26 ++++++++++++++++++++++
2 files changed, 39 insertions(+)

## Verification

### pytest (pipelines/runners/netsuite-balance-sheet/tests) — exit 0

``

ric PASSED [ 42%]

tests/test_redshift_handler.py::TestLoadBalanceSheetAmountEdgeCases::test_malformed_amount_numeric_raises_valueerror PASSED [ 44%]

tests/test_redshift_handler.py::TestLoadBalanceSheetExceptionHandling::test_exception_triggers_rollback PASSED [ 46%]

tests/test_redshift_handler.py::TestLoadBalanceSheetExceptionHandling::test_connection_closed_on_success PASSED [ 48%]

tests/test_redshift_handler.py::TestLoadBalanceSheetExceptionHandling::test_connection_closed_on_failure PASSED [ 50%]

tests/test_redshift_handler.py::TestLoadBalanceSheetExceptionHandling::test_cursor_context_manager_exited_on_success PASSED [ 51%]

tests/test_s3_reader.py::TestParsePeriodLabel::test_abbreviated_month PASSED [ 53%]

tests/test_s3_reader.py::TestParsePeriodLabel::test_abbreviated_month_feb PASSED [ 55%]

tests/test_s3_reader.py::TestParsePeriodLabel::test_abbreviated_month_dec PASSED [ 57%]

tests/test_s3_reader.py::TestParsePeriodLabel::test_full_month_name PASSED [ 59%]

tests/test_s3_reader.py::TestParsePeriodLabel::test_leap_year_feb PASSED [ 61%]

tests/test_s3_reader.py::TestParsePeriodLabel::test_whitespace_stripped PASSED [ 62%]

tests/test_s3_reader.py::TestParsePeriodLabel::test_invalid_format_returns_none PASSED [ 64%]

tests/test_s3_reader.py::TestParsePeriodLabel::test_empty_string_returns_none PASSED [ 66%]

tests/test_s3_reader.py::TestParsePeriodLabel::test_invalid_month_returns_none PASSED [ 68%]

tests/test_s3_reader.py::TestParsePeriodLabel::test_short_format_abbreviated PASSED [ 70%]

tests/test_s3_reader.py::TestParsePeriodLabel::test_short_format_dec PASSED [ 72%]

tests/test_s3_reader.py::TestParsePeriodLabel::test_short_format_full_month PASSED [ 74%]

tests/test_s3_reader.py::TestParseCurrency::test_positive_amount PASSED [ 75%]

tests/test_s3_reader.py::TestParseCurrency::test_negative_amount PASSED [ 77%]

tests/test_s3_reader.py::TestParseCurrency::test_simple_amount PASSED [ 79%]

tests/test_s3_reader.py::TestParseCurrency::test_empty_string PASSED [ 81%]

tests/test_s3_reader.py::TestParseCurrency::test_no_digits PASSED [ 83%]

tests/test_s3_reader.py::TestParseCurrency::test_zero PASSED [ 85%]

tests/test_s3_reader.py::TestParseCurrency::test_multiple_dots_raises_valueerror PASSED [ 87%]

tests/test_s3_reader.py::TestReadBalanceSheetCsv::test_invalid_date_format_raises PASSED [ 88%]

tests/test_s3_reader.py::TestReadBalanceSheetCsv::test_invalid_date_n …_(truncated)_

<details>

<summary>Run metadata</summary>

| Field | Value |

| --- | --- |

| Pipeline | netsuite-balance-sheet |

| Failing run | ba6df4dc-19cf-4e3b-9d37-c15fc3329d4c |

| Occurrence | 1 (times this exact failure signature has been seen) |

| Signature | afbd17bdb67120bde3657d026068a7920f7efb2c62331aaaaad2cb1681de2a58 |

| Verify | green |

</details>

---

🤖 Opened by heimdall. mercy reviews this PR automatically; heimdall revises on REQUEST_CHANGES (bounded rounds). Tier-auto PRs may auto-merge on mercy approval when the consumer enables it; everything else waits for a human. Mention heimdall in a comment to direct it, or add the manual-dev` label to take the PR over and stop it entirely.

Automated fix for mart-education-hc-current-cost-refresh — fix_class code_fix, scope tier draft.

Resolves https://github.com/AI-Builder-Team/Surtr/issues/1450

> Ready for review — verification is green; HEIMDALL_READY_PRS opens verified tier-draft fixes ready for review. A human still merges — auto-merge never applies outside tier auto.

## What's broken

Run 82d87c24-d228-4374-b8b5-4e4333c563b2 of mart-education-hc-current-cost-refresh died at cold start with RuntimeError: upstream HC execution output lacks payload.run_id (handler.py line 41, raised from line 92). The upstream hc-forecast-refresh execution SUCCEEDED, so this is not an upstream data problem: _upstream_run_id in pipelines/runners/mart-education-hc-current-cost-refresh/src/handler.py reads the run_id from the wrong JSON path in the Step Functions execution output. Because the failure occurs before any Redshift CALL, the run published zero rows of immutable HC current-cost evidence — a hard, non-silent failure that leaves the downstream evidence mart un-refreshed.

Root cause. _upstream_run_id (src/handler.py:38-39) parses execution['output'] and reads output['payload']['run_id'], assuming the upstream execution output has a top-level payload key. But the platform's direct-flow state machine (pipelines/cdk/lib/constructs/step-function.ts:386-403, InvokePipelineLambda with resultPath: '$.output', resultSelector: {'payload.$': '$.Payload'}) nests the handler's return one level deeper, and the terminal UpdateRunSuccess state uses resultPath: DISCARD, so the execution output is the full state object {..., run: {...}, output: {payload: <hc-forecast handler return>}}. hc-forecast-refresh returns {'status':'success','run_id':...} from its handler (src/handler.py), so the run_id actually lives at output['output']['payload']['run_id'], not output['payload']['run_id']; the missing top-level payload key raises KeyError, which the except at line 40 converts into the observed RuntimeError. This is the pipeline's first real run (occurrence 1, disabled-by-default trigger), so the nesting assumption baked into both the handler and its tests was never validated against a real upstream execution.

## What this PR changes

In pipelines/runners/mart-education-hc-current-cost-refresh/src/handler.py, change the run_id lookup in _upstream_run_id from output['payload']['run_id'] to output['output']['payload']['run_id'] so it reads the handler return that the platform nests under the state's output key; keep the surrounding (KeyError, TypeError, json.JSONDecodeError) guard and the RUN_ID regex validation intact so a genuinely malformed or missing upstream output still fails closed. Update tests/test_handler.py to match the real execution output shape: the success mock at line 18 should be json.dumps({'output': {'payload': {'run_id': 'hc-1'}}}), and the rejection parametrize at line 92 should use nested-but-incomplete shapes (e.g. {'output': {'run_id': 'wrong'}}, {'output': {'payload': {}}}, {}) that still trigger the payload.run_id RuntimeError. The change is confined to the pipeline's own Tier A directory and does not touch the shared step-function construct.

Why this fixes it. The defect is a code-level contract bug fully contained in the pipeline's own directory, and the correct nesting is provable from the state-machine construct rather than guessed, so a real code change (not a config tweak) is both warranted and safe. Correcting the JSON path in _upstream_run_id plus its accompanying tests restores the pipeline's ability to resolve the upstream HC run_id and proceed to publish current-cost evidence, whereas leaving it unfixed means every triggered run fails before writing any rows and the HC current-cost evidence mart never refreshes. The blast radius is one path expression and its test fixtures inside pipelines/runners/mart-education-hc-current-cost-refresh/**, with no change to the shared platform construct, IAM, SQL, or environment.

### Files changed

 .../mart-education-hc-current-cost-refresh/src/handler.py    |  2 +-
.../tests/test_handler.py                                    | 12 ++++++++++--
2 files changed, 11 insertions(+), 3 deletions(-)

## Verification

### pytest (pipelines/runners/mart-education-hc-current-cost-refresh/tests) — exit 0

============================= test session starts ==============================
platform linux -- Python 3.11.15, pytest-9.1.1, pluggy-1.6.0
rootdir: /home/runner/work/Surtr/Surtr/publish/pipelines/runners/mart-education-hc-current-cost-refresh
configfile: pyproject.toml
plugins: mock-3.15.1
collected 83 items
tests/test_deadline.py .....                                             [  6%]
tests/test_handler.py .......                                            [ 14%]
tests/test_live_mapping_contract.py ..                                   [ 16%]
tests/test_model_a_repair_mutations.py ....................              [ 40%]
tests/test_reviewer_regressions.py .......                               [ 49%]
tests/test_semantic_mutations.py ..........                              [ 61%]
tests/test_sql_contracts.py .......................                      [ 89%]
tests/test_timing_fixture_batches.py .........                           [100%]
============================== 83 passed in 0.43s ==============================

<details>

<summary>Run metadata</summary>

| Field | Value |

| --- | --- |

| Pipeline | mart-education-hc-current-cost-refresh |

| Failing run | 82d87c24-d228-4374-b8b5-4e4333c563b2 |

| Occurrence | 1 (times this exact failure signature has been seen) |

| Signature | 386494da029f747e09fd3bfa24f61f9aadd957323b93fb79de20da1741138fcc |

| Verify | green |

</details>

---

🤖 Opened by heimdall. mercy reviews this PR automatically; heimdall revises on REQUEST_CHANGES (bounded rounds). Tier-auto PRs may auto-merge on mercy approval when the consumer enables it; everything else waits for a human. Mention heimdall in a comment to direct it, or add the manual-dev label to take the PR over and stop it entirely.

Automated fix for hubspot-raw-sync — fix_class code_fix, scope tier draft.

Resolves https://github.com/AI-Builder-Team/Surtr/issues/1453

> Ready for review — verification is green; HEIMDALL_READY_PRS opens verified tier-draft fixes ready for review. A human still merges — auto-merge never applies outside tier auto.

## What's broken

Run 3f740b48-cf0b-4186-8364-b36ffe418e5a of hubspot-raw-sync ended with the terminal finalize task reporting status=partial_failure (19/20 resources published) instead of a hard failure. The emails resource failed its atomic Redshift publication with the offending line 'RuntimeError: atomic HubSpot raw publication failed: ERROR: published snapshot count mismatch for emails: published 712804, expected 712815' (publication.py:286); that per-resource publish task correctly exited non-zero, but the fan-out is designed so an individual publication task failure does not stop the run. The finalize stage in pipelines/runners/hubspot-raw-sync/src/fanout_handler.py (FanoutRunner.finalize, ~lines 3859-3934) aggregates that failure into a soft {"status": "partial_failure", ...} dict and returns normally, so main.py writes the run record and the terminal ECS task exits 0. This is a silent data failure: the emails snapshot is 11 records short (stale, since the atomic CALL rolled back), yet the cohort/portal manifest is presented as complete and the run is not marked FAILED, so downstream consumers and the next incremental run will treat the incomplete emails snapshot as authoritative.

Root cause. FanoutRunner.finalize() in pipelines/runners/hubspot-raw-sync/src/fanout_handler.py collects per-resource publication outcomes and, when any resource has no success outcome, appends it to failures and returns a dict whose status is merely 'partial_failure' (line ~3924) — it never raises. main.py (pipelines/runners/hubspot-raw-sync/src/main.py, lines 47-50) then calls write_run_result with that status and prints, so the finalize task exits 0. Because the terminal task succeeds, the orchestrator records the run as complete rather than FAILED even though the emails resource publication aborted with a verified 11-record snapshot count mismatch. The publication.py:286 RuntimeError is not the defect — it correctly detects and rejects the mismatch and fails its own task; the defect is that the finalizer downgrades a failed resource to a soft partial success instead of failing the whole run, so no operator or downstream signal reflects the missing data.

## What this PR changes

In pipelines/runners/hubspot-raw-sync/src/fanout_handler.py, make the terminal run hard-fail whenever finalize reports one or more failed resources: after the run result is persisted so the partial_failure summary is still recorded, the finalize path must exit non-zero (e.g. finalize returns the summary as today, and main.py in pipelines/runners/hubspot-raw-sync/src/main.py raises after write_run_result when result['status'] != 'success' for the finalize/non-task-mode terminal task, or finalize itself writes the run result and then raises a RuntimeError naming the failed resources). Keep the existing partial_failure summary and cohort_manifests in the recorded run result for observability, but ensure the process exits non-zero so the orchestrator marks the run FAILED and downstream consumers do not treat the emails cohort as complete. Add a unit test under pipelines/runners/hubspot-raw-sync/tests asserting that a finalize outcome with a non-empty failures list produces a non-zero terminal exit (raises) while still writing the run record. Note: OPEN PR #1116 ('fail terminal run when finalize reports failed r...') targets this exact failure mode and location — prefer aligning with / consolidating that reviewed change rather than diverging from it.

Why this fixes it. This is a textbook Surtr silent data failure — the run reports success (exit 0) while the emails resource is 11 records short and its snapshot was never updated — and the correct blast radius is the pipeline's own finalize/terminal-exit logic, entirely within Tier A (pipelines/runners/hubspot-raw-sync/). The fix is a real code change (make finalize/main.py exit non-zero on any resource failure) plus a regression test, not a config tweak, so it is classified code_fix; it deliberately does not touch publication.py:286, whose count-mismatch RuntimeError is already the correct guard. It stays minimal and does not rewrite the fan-out orchestration or the atomic publish SQL — it only changes how an already-detected failure is surfaced at run level. The one caveat is that OPEN PR #1116 appears to implement the same change; the fix should be reconciled with it to avoid a duplicate, which a human reviewer can confirm at merge time.

### Files changed

 pipelines/runners/hubspot-raw-sync/src/main.py     | 32 +++++++++-
.../runners/hubspot-raw-sync/tests/test_main.py    | 73 ++++++++++++++++++++++
2 files changed, 104 insertions(+), 1 deletion(-)

## Verification

### pytest (pipelines/runners/hubspot-raw-sync/tests) — exit 0

============================= test session starts ==============================
platform linux -- Python 3.11.16, pytest-9.1.1, pluggy-1.6.0
rootdir: /home/runner/work/Surtr/Surtr/publish/pipelines/runners/hubspot-raw-sync
configfile: pyproject.toml
plugins: mock-3.15.1
collected 254 items
tests/test_apply_ddl.py ...................                              [  7%]
tests/test_clean_projection.py ............                              [ 12%]
tests/test_collector.py ................................................ [ 31%]
........                                                                 [ 34%]
tests/test_contract.py .........                                         [ 37%]
tests/test_event_windows.py ............                                 [ 42%]
tests/test_execution_proof.py .............................              [ 53%]
tests/test_fanout_handler.py ...................................         [ 67%]
tests/test_handler.py ..........                                         [ 71%]
tests/test_hubspot_client.py .......                                     [ 74%]
tests/test_incremental.py .............                                  [ 79%]
tests/test_landing.py .......                                            [ 82%]
tests/test_lanes.py ..........                                           [ 86%]
tests/test_main.py ......                                                [ 88%]
tests/test_orchestration.py .....                                        [ 90%]
tests/test_portal_manifest.py ...                                        [ 91%]
tests/test_publication.py .........                                      [ 95%]
tests/test_run_result.py ...                                             [ 96%]
tests/test_validate_clean_projection.py .........                        [100%]
============================= 254 passed in 2.25s ==============================

<details>

<summary>Run metadata</summary>

| Field | Value |

| --- | --- |

| Pipeline | hubspot-raw-sync |

| Failing run | 3f740b48-cf0b-4186-8364-b36ffe418e5a |

| Occurrence | 1 (times this exact failure signature has been seen) |

| Signature | 58864c15adbfbfb8e7870927f9cff0ccef24a921c48178f9af6a71824d7988fb |

| Verify | green |

</details>

---

🤖 Opened by heimdall. mercy reviews this PR automatically; heimdall revises on REQUEST_CHANGES (bounded rounds). Tier-auto PRs may auto-merge on mercy approval when the consumer enables it; everything else waits for a human. Mention heimdall in a comment to direct it, or add the manual-dev label to take the PR over and stop it entirely.

Linear: [AI-598](https://linear.app/builder-team/issue/AI-598/p22-cloudwatch-logs-read-for-ecslambda-pipelines) · Project: [Heimdall Software Factory](https://linear.app/builder-team/project/heimdall-software-factory-4216613b8e5f)

The other half of the evidence gap, after [#43](https://github.com/AI-Builder-Team/mercy/pull/43).

## Why

The dispatcher ships a 200-event tail over a 60-minute window. When the traceback falls outside that slice — or when the pipeline runs on ECS and the evidence is only the States.TaskFailed envelope — Heimdall is reasoning about a wrapper. Issue #1578, verbatim:

> the ECS/Fargate task-stopped state-change envelope … carries no application stderr, no container exit code, and no Python traceback … the specific failing stage cannot be pinned from the log line alone

Its own suggested next step was *"Pull the CloudWatch log stream for ECS task 66dcc899…"* — an action it could not take. Every ECS pipeline failure is an automatic other for this reason.

## Same shape as the warehouse work, deliberately

The agent states what it wants in log_requests; trusted harness code fetches it; only rendered lines come back. The fetch shares the enrichment step precisely because that step runs no agent — an AWS credential in the agent's process is one a prompt injection can reach, and its whole input is untrusted log text. Two tests pin that from both directions, matching the ones added in #43.

## Bounded rather than trusted

| Guard | Value | Why |

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

| log_group grammar | CloudWatch's own charset | a name is a name |

| window | ≤ 24h, default 2h | an unbounded FilterLogEvents over a busy group burns the job's clock |

| events | ≤ 300 | and floods the prompt |

| line length | 400 chars, newlines flattened | a log line must not close the fence it renders in, or open a heading |

| window_minutes: true | refused | bool subclasses int, so this would silently mean 1 minute |

end_iso anchors the window on the failure, not on now — a triage that starts twenty minutes late would otherwise look straight past the event it exists to explain.

## Two things I changed after testing the branching

Simulating all seven credential/request combinations surfaced both:

- Independent guards per source. A missing Redshift credential was cancelling a *successful* log fetch, because the SQL branch owned the early exit. Now logs asked + AWS present, sql asked + no Redshift correctly still re-runs.

- Both fetchers exit non-zero when every request failed, so the caller doesn't pay for another agent pass to hand it a page of errors it can't act on — the same waste the no-credential guard already prevented.

## Verification

pytest heimdall/tests 434 passed (28 new) · ruff clean · actionlint clean · bash -n on the extracted step · all seven branch combinations executed against the real step script.

## Before this does anything

HEIMDALL_AWS_ENV must be provisioned — a dotenv blob (AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_REGION) scoped to logs:FilterLogEvents and nothing else. Absent, log requests are skipped and behaviour is exactly as today.

## Business Value

ECS-based pipelines currently give Heimdall almost nothing to work with — it can see that a container exited non-zero and nothing about why — so every such failure is a diagnosis-only issue that lands back on Keval with the log query already written out for him. Together with #43 this closes the two gaps Heimdall names most often in its own declined diagnoses, which are 72 of 104 issues. It is also the difference between a guess and a fix on exactly the class of failure that is hardest to reproduce by hand.

## Manual Effort Estimate

~1 day of focused work with no AI — the fetcher and its bounds, the prompt-injection hardening on log lines, wiring two independent credential sources through one step without either cancelling the other, and 28 tests. *(Proposed by Claude — Keval to confirm or adjust.)*

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

Linear: [AI-601](https://linear.app/builder-team/issue/AI-601/p32-verify-driven-fix-loop-stop-shipping-untested-code) · Project: [Heimdall Software Factory](https://linear.app/builder-team/project/heimdall-software-factory-4216613b8e5f)

## What this PR changes

verify.commands in .heimdall.yml was [], so Heimdall's "verified green" meant only that the pipeline's own pytest passed — or, for a pipeline with no test directory, nothing at all.

[#1580](https://github.com/AI-Builder-Team/Surtr/pull/1580) is what that costs. An agent with no shell wrote it, verification reported green because nothing checked, it opened ready for review, Mercy approved it — and it has been sitting unmergeable ever since because Lint (Ruff) fails.

Verification that doesn't cover what CI gates on isn't verification; it's a green light with no bulb in it.

## The commands mirror the CI job exactly

verify:
commands:
- name: ruff check
run: python3 -m pip install --quiet ruff==0.15.22 && python3 -m ruff check pipelines
- name: ruff format --check
run: python3 -m ruff format --check pipelines

The pin matters. A different ruff is a different rule set, so verifying with one and gating with another would reintroduce the same gap in a subtler form. CI holds 0.15.22 deliberately — per its own comment, 0.16.0 stabilised ~60 preview rules and flags 2845 pre-existing findings across this repo.

pip rather than CI's uvx: Heimdall's verify job runs actions/setup-python but *not* setup-uv, so pip is the only tool guaranteed to be there. Using uvx would have failed on the runner and turned every Heimdall PR into a draft — a worse failure than the one being fixed.

## Verified

In a clean venv, so a pre-existing local ruff couldn't mask the result:

resolved version: ruff 0.15.22          <- matches CI's pin
ruff check pipelines        -> exit=0 (clean)
ruff format --check         -> exit=0 (clean)

Both pass on current main, which is the important part: this gates new findings without reddening every Heimdall PR on pre-existing ones. The harness's heimdall_config loader parses the new block and the scope tiers are unchanged.

## What happens now

A Heimdall fix that breaks lint verifies failing, which forces the PR to open as a draft — so it can't reach "approved but unmergeable" again. The steward's existing red-CI path then summons Heimdall to fix it, and promotes the draft once it's green.

## Business Value

This closes the most embarrassing failure mode in the agent loop: an approved PR that cannot merge because it doesn't lint. It also protects Mercy's review budget — a reviewer round spent on a mechanical failure a linter catches in two seconds is a round not spent on correctness, and under dismiss_stale_reviews_on_push each one costs a re-review too. Now that Heimdall merges its own work unattended, "verified" needs to mean something, and this is the cheapest way to make it mean what CI means.

## Manual Effort Estimate

~1 hour — the config is four lines; the substance is matching CI's pin exactly, choosing an installer the verify job actually has, and confirming in a clean environment that current main passes so this doesn't redden everything. *(Proposed by Claude — Keval to confirm or adjust.)*

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

Linear: [AI-597](https://linear.app/builder-team/issue/AI-597/p21-real-redshift-read-replace-the-stub-context-pack) · Project: [Heimdall Software Factory](https://linear.app/builder-team/project/heimdall-software-factory-4216613b8e5f)

## Why

72 of 104 triage issues end as other, and a large share are one SELECT away from a fix. Heimdall says so itself — #1518:

> a data operation a human with warehouse access must perform: confirm which subsidiary/period consolidated exchange rates are absent from raw_consolidated_exchange_rate

#1502 needs one ingestion_ledger lookup. It works out exactly which query would settle the matter, and stops.

The old build_redshift pack ran one hardcoded svv_table_info ORDER BY size LIMIT 25 — top-25 biggest tables — and its secret was never provisioned, so even that never ran.

## The design: the SQL travels, the credential does not

Handing the agent a database credential is the obvious move and the wrong one. Its entire input is untrusted — CloudWatch logs, error strings, file contents an attacker could have influenced. A credential in its environment is one a prompt injection can exfiltrate.

So the agent requests up to 5 read-only queries in sql_requests; trusted harness code validates and runs them and feeds back only rendered rows, for exactly one further diagnose pass. Arbitrary read power over the warehouse, and it never sees a password.

## What redshift_read.py refuses

Validation is defence in depth — the connection is opened read-only regardless — but *"it would have failed anyway"* is a poor answer to *why did we send DROP TABLE to production*.

| Case | Verdict | Why it matters |

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

| SELECT 1 -- \n DROP TABLE users | refused | a comment must not hide a keyword |

| SELECT 1; DELETE FROM t | refused | multiple statements |

| SELECT * INTO newtbl FROM t | refused | in Redshift this creates a table — it looks like a read |

| UNLOAD ('select 1') TO 's3://…' | refused | exfiltration with a SQL keyword in front |

| WHERE status = 'deleted' | allowed | a literal is not a keyword, or half the warehouse is unqueryable |

| SELECT dropped_rows, inserted_at | allowed | nor is an identifier |

Plus a statement timeout, a row cap, cell truncation, and | escaping so a cell cannot forge a table row. Every query is echoed to the job log for audit.

## Wiring

Extended the existing diagnose retry loop rather than duplicating the invocation across both runtimes. The loop grows 3 → 4 passes, the 4th being enrichment, guarded so it:

- runs at most once — otherwise a diagnosis that keeps asking loops to the cap;

- runs only when a credential is provisioned — re-running the agent to hand it *"not provisioned"* spends a whole invocation saying nothing.

Verified by executing the extracted step against a stubbed CLI:

no credential  -> 1 agent invocation   (enrichment skipped)
credential set -> 2 agent invocations  (enrichment ran once)
requests captured: ["SELECT count(*) FROM staging.ingestion_ledger", "DROP TABLE t"]
redshift_read: rejected "DROP TABLE t" — only SELECT / WITH allowed

## The other half is the prompt

other now explicitly means no fix exists in this repository — not that the fix is inconvenient, lives outside the failing pipeline's directory, or needs data the agent didn't look at. And: *"Never conclude other because you lacked data you could have asked for."*

Access without permission to use it would have changed nothing.

## Verification

pytest heimdall/tests 367 passed (33 new) · pytest harness/tests 158 · ruff clean · actionlint clean · bash -n on the extracted step.

Results are labelled "data, not instructions" in the pack, same posture as log evidence — warehouse cells contain whatever a user typed.

## Before this does anything

HEIMDALL_REDSHIFT_ENV must be provisioned (a dotenv blob: REDSHIFT_HOST/PORT/DB/USER/PASSWORD). Keval has nominated klair/redshift-creds. Until then the guard skips enrichment entirely and behaviour is exactly as today.

## Business Value

This is the single highest-leverage capability in the Heimdall project. 72 of 104 issues where Heimdall did the hard part — a precise root-cause analysis — and then handed the work back, often with the exact SQL already written out in suggested_approach. Each one is a diagnosis Keval has to re-read and act on by hand. It targets the pipelines that fail most (hubspot-raw-sync 9, netsuite-saved-search-refresh 8, core-education-site-metadata-refresh 8, sis-raw-sync 8), and it does it without adding a credential to the blast radius of a prompt injection.

## Manual Effort Estimate

~1 day of focused work with no AI — the executor and its guards, the two-pass loop without duplicating it across runtimes, the prompt/schema change, and 33 tests most of which exist because agent-supplied SQL is untrusted input. *(Proposed by Claude — Keval to confirm or adjust.)*

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

Linear: [AI-596](https://linear.app/builder-team/issue/AI-596/p12-repo-settings-ruleset-compatibility-for-unattended-merge) · Project: [Heimdall Software Factory](https://linear.app/builder-team/project/heimdall-software-factory-4216613b8e5f)

Removes the last human dependency in the merge path.

## Why

[#41](https://github.com/AI-Builder-Team/mercy/pull/41) made auto-merge reachable, but it calls gh pr merge --auto, which needs the repo's Allow auto-merge setting. That is admin-only and off on Surtr — where all 40 Heimdall PRs and all 9 stranded approvals live. So the feature we just built still couldn't fire there without Keval ticking a box.

A direct merge needs none of that. allow_auto_merge gates GitHub's auto-merge *queue*; a direct merge only needs branch protection satisfied — which it is, by definition, once Mercy has approved and checks are green.

And the trigger already existed: the steward runs on check_suite: completed. *"Checks just went green"* is precisely when to merge.

| | --auto | direct merge on green |

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

| Needs repo admin | yes | no |

| Works when the setting is off | no | yes |

| Who waits for checks | GitHub | the steward — already runs on that event |

| Could merge before checks finish | no | no — the trigger *is* checks finishing |

## Provenance is narrower for merging than for stewarding

driven includes the repo's blanket MERCY_HANDOFF_ALL_PRS variable. That must mean *"steward this PR"* and never *"merge everyone's PRs"*, so merging requires heimdall's own PR or a human's deliberate heimdall-driven label. There's a test for exactly that distinction.

## The floor is re-checked at merge time

Not trusted from the approval event. path_guard --all-files, so violation means only the forbidden floor — workflows, agent config, CODEOWNERS, credential-shaped paths. It fails closed: no config, no file listing, or an unreadable verdict each refuse the merge and post a comment saying why.

## What still blocks a merge

Shadow mode (HEIMDALL_AUTOMERGE_ENABLED off) · red checks · pending checks · unapproved · conflicting · behind · draft · the manual-dev stop label · forbidden floor.

Twelve new tests, one per path. pytest heimdall/tests 323 passed · ruff clean · actionlint clean.

One thing worth flagging: my new tests initially shadowed the existing _pr/CTX/_kinds helpers in that file. Python resolves module globals at *call* time, so the tests defined above mine silently started using my fixtures and 12 of them failed. Renamed; worth knowing if you add to that file.

## Business Value

Klair could already auto-merge; Surtr — the repo that actually generates the work — could not, and the fix was a setting only Keval can change. This makes the merge path self-sufficient on any repo, which matters more as Heimdall is installed more widely: no per-repo admin step, no silent dependency on a checkbox someone forgot. It closes the gap between "Mercy approved this fix" and "the fix is on main" without a human in it.

## Manual Effort Estimate

~4 hours — the planner and executor changes are small; the provenance distinction, the fail-closed floor re-check, and twelve path tests are the substance. *(Proposed by Claude — Keval to confirm or adjust.)*

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

Linear: [AI-610](https://linear.app/builder-team/issue/AI-610/p30b-price-codex-runs-they-report-tokens-never-dollars) · Project: [Heimdall Software Factory](https://linear.app/builder-team/project/heimdall-software-factory-4216613b8e5f)

Split out of [#40](https://github.com/AI-Builder-Team/mercy/pull/40) to keep that diff tight. This is the gate on making Codex the default runtime.

## Why

The Claude CLI self-reports total_cost_usd in its envelope and Heimdall's telemetry just copies it. Codex reports no dollar figure at all — only token counts, and only in its --json event stream, which Heimdall's codex calls did not even request.

Left unpriced, every Codex run books total_cost_usd as null, and the /heimdall dashboard sums null as $0. Silent cost-data loss — the same shape as the pricing drift that cost $143K earlier this year.

## What changed

All three codex exec sites now pass --json and capture the event stream; it travels with the telemetry inputs; the emitter reuses Mercy's parsers and rate card rather than copying them.

Loading Mercy's emitter by explicit path, not import. Both modules are named emit_telemetry, so a plain import emit_telemetry returns Heimdall's own half-initialised module from sys.modules and the lookups silently yield None — leaving Codex runs unpriced with nothing to show for it. I hit exactly that, and only caught it because I asserted the parsers were actually bound. There is now a test for it.

## Why reuse rather than copy

The logic is subtle in a way a second copy would drift on. From the harness's own docs:

> OpenAI/codex reports cached_input_tokens as a *subset of* input_tokens — the caller must subtract before calling here.

Skipping that subtraction both inflates the input count and bills cache hits at the full input rate — 10x over on Luna. A test pins the computed figure against the naive one.

## Verified end to end

Realistic Codex stream — 200k input of which 150k cached, 12k output, on gpt-5.6-luna:

last cumulative usage: {input 200000, cached 150000, output 12000}
tokens:  input 50000 (uncached), cache_read 150000, output 12000
cost:    $0.027400  source=computed
expected $0.027400  -> MATCH

| Case | Result |

|---|---|

| No usage event at all | cost=None — unknown, not $0 |

| Unpriced model | cost=None + loud stderr warning naming the model |

| Claude self-reported | 0.96, source=runtime_reported — runtime always wins |

The posture is inherited from harness/pricing.py: a runtime's own cost always wins, so this can never regress an already-correct claude-code figure; and an unknown model reports nothing rather than a confident zero.

ruff clean · actionlint clean · pytest heimdall/tests 298 passed (10 new) · pytest harness/tests 158 passed.

## One thing that is deliberately inert

cost_source (runtime_reported | computed | null) is emitted so a $0 from a missing rate card is distinguishable from a genuinely free run. Surtr's ingest uses a plain z.object(), which strips unknown keys rather than rejecting them — so this is safe to send today but goes nowhere until the Surtr-side schema learns the field. Flagging it rather than letting a reviewer wonder; the Surtr change is a one-liner and should be its own PR.

## Business Value

The entire cost argument for moving Heimdall to Codex — ~$0.008/review on Mercy against $0.96/run on Opus — is unmeasurable if Codex runs book $0. Worse, a silently-zero dashboard would make the migration look like a *bigger* win than it is while hiding real spend, which is precisely the class of bug the AI-spend work exists to catch. Landing this before the runtime flips means the first Codex run is priced correctly instead of needing a backfill later.

## Manual Effort Estimate

~3 hours of focused work with no AI — the wiring is routine, but the module-name collision is invisible until asserted, and getting the cache-subtraction right (rather than reimplementing it subtly wrong) is the part that actually protects the number. *(Proposed by Claude — Keval to confirm or adjust.)*

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

Linear: [AI-595](https://linear.app/builder-team/issue/AI-595/p11-provenance-based-auto-merge-replace-the-tier-gate) · Project: [Heimdall Software Factory](https://linear.app/builder-team/project/heimdall-software-factory-4216613b8e5f)

The headline change: Heimdall can now merge its own work to main.

## The gate was unreachable by construction

Auto-merge required scope tier auto. Surtr runs HEIMDALL_ALL_FILES=true, and path_guard.classify() says of that flag:

> The result can never be Tier A: an unscoped change always opens/stays DRAFT and a human merges.

So tier auto could never occur. Telemetry over 161 runs: draft 44, violation 2, auto 0. That is why Heimdall has auto-merged nothing, ever, while 9 Mercy-approved PRs sit open.

## The new rule

merge if  (author == the-heimdall[bot]  OR  PR carries heimdall-driven)
AND mercy APPROVED on the live head SHA
AND base == default branch
AND not a draft
AND HEIMDALL_AUTOMERGE_ENABLED == true
AND the change does not touch the forbidden floor

Any file. The agent/* branch prefix is still not provenance — any repo writer can create one.

## Scope survives as exactly one line

scope now computes a floor-only verdict by running path_guard a second time with --all-files. That flag reclassifies "path in no configured tier" from violation to Tier B, which leaves violation meaning precisely one thing: the forbidden floor. An unreadable verdict defaults to violation — fail closed.

Verified against Surtr's real .heimdall.yml:

| Path | Verdict |

|---|---|

| .github/workflows/ci.yml | 🚫 blocked |

| .heimdall.yml · .mercy.yml · CODEOWNERS | 🚫 blocked |

| infra/secrets/keys.ts | 🚫 blocked |

| pipelines/cdk/lib/stack.ts | ✅ allowed |

| pipelines/ddl/x.sql | ✅ allowed |

| pipelines/runners/foo/src/handler.py | ✅ allowed |

| Surtr/src/api/server.ts · infra/lib/… | ✅ allowed |

Heimdall can fix a pipeline, a CDK stack or a DDL file — but never the machinery that governs Heimdall.

## Also fixed

LABELED was computed in resolve and never emitted, so the gate could not have read it even if it wanted to. It is now an output.

## Verification

The real Enable auto-merge step, extracted from the parsed YAML and executed against a stubbed gh:

| Scenario | Result |

|---|---|

| heimdall-authored, floor ok | ✅ auto-merge enabled (heimdall-authored, floor=draft) |

| human-authored, no label | ⛔ refused |

| human-authored + drive label | ✅ auto-merge enabled (heimdall-driven label) |

| heimdall-authored, floor violation | ⛔ refused + comment |

| labelled PR, floor violation | ⛔ refused + comment |

| empty floor verdict | ⛔ refused — fails closed |

| stale approval (head moved) | ⛔ refused |

| draft PR | ⛔ refused |

| wrong base branch | ⛔ refused |

| shadow mode (flag unset) | ⛔ refused |

actionlint clean · ruff clean · pytest heimdall/tests 272 passed (11 new).

## This changes nothing until two switches flip

HEIMDALL_AUTOMERGE_ENABLED is unset on both repos, and Surtr has allow_auto_merge: false at the repo level. Both are AI-596, deliberately separate so this logic can land and be reviewed before anything starts merging on its own.

## Risk worth stating

heimdall-driven becomes a merge-authorising token: applying it to a PR makes that PR auto-mergeable to main on Mercy's approval alone. The P6 login allowlist restricts who can *summon* Heimdall, not who can apply a *label*. Today the label is effectively Keval's — 22 of 26 such PRs are his — but it is worth revisiting if it spreads.

## Business Value

Nine reviewed, CI-green, Mercy-approved fixes to real production pipeline failures are stranded right now purely because a human click is required, and the mechanism meant to remove that click could never fire. This is the change that turns Heimdall from a suggestion engine into a factory: from here, a pipeline that breaks at 02:00 can be diagnosed, fixed, reviewed and merged before anyone reads the alert. It is also the prerequisite for the automated production release (AI-605) — without it, fixes would simply queue one stage later.

## Manual Effort Estimate

~1 day of focused work with no AI — the gate rewrite is small, but working out *why* tier auto was unreachable, designing the floor-only verdict so provenance could widen without weakening the real boundary, and proving all ten paths is most of it. *(Proposed by Claude — Keval to confirm or adjust.)*

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

Linear: [AI-609](https://linear.app/builder-team/issue/AI-609/p30-repair-heimdalls-codex-runtime-it-would-401-today) · Project: [Heimdall Software Factory](https://linear.app/builder-team/project/heimdall-software-factory-4216613b8e5f)

Prerequisite for AI-600 (Codex sandbox infra), AI-601 (verify loop) and AI-602 (models).

## Why

Heimdall's codex path has never run — 0 of 161 telemetry records use it, all claude-code — and it was broken four ways. Switching agent_runtime to codex today would have failed on the first call.

| # | Blocker | Effect |

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

| 1 | No codex login anywhere in heimdall.yml | every request 401s |

| 2 | Caller passes OPENAI_API_KEY; mercy uses AGENT_OPENAI_API_KEY (org secret). The former is unset on Surtr | no key to log in with |

| 3 | Pinned @openai/codex@0.135.0; mercy is on 0.149.1 | stale CLI |

| 4 | Allowlist is gpt-5-codex\|gpt-5\|gpt-5-mini | gpt-5.6-luna refused outright |

On (1), from mercy's own fix (PR #35): Codex ignores OPENAI_API_KEY and reads CODEX_HOME/auth.json, so without a login *"the CLI sends NO auth header at all and every request 401s with 'Missing bearer or basic authentication in header' — which reads like a bad/expired key but is purely a missing login step."*

## What changed

- Login at all three call sites (diagnose, fix, revise), reading the key from STDIN so it never reaches argv (/proc/<pid>/cmdline) or the step log. A failed login is now fatal — otherwise every subsequent exec 401s and the agent looks like it simply had nothing to say.

- Secret: every site now uses ${{ secrets.AGENT_OPENAI_API_KEY || secrets.OPENAI_API_KEY }}. Both stay declared — a reusable workflow hard-fails when a caller passes an undeclared secret, so the deprecated name cannot just be deleted.

- Pin bumped to 0.149.1, matching mercy, at both occurrences.

- gpt-5.6-luna allowlisted and made the codex default.

## Verification

Every codex exec site, resolved from the parsed YAML:

triage/Diagnose (Codex): login=True before_exec=True
triage/Fix (Codex):      login=True before_exec=True
revise/Revise (Codex):   login=True before_exec=True

bash -n on all three extracted step scripts · actionlint clean · ruff clean · pytest heimdall/tests 262 passed (14 new).

The new tests are invariants rather than snapshots: exactly three codex sites exist, each logs in before exec, the key never appears in argv, login failure is fatal, both secret names stay declared, and — comparing against mercy.yml directly — heimdall's CLI pin must equal mercy's. That last one turns the stale-pin class of bug into a build failure.

## Deliberately not in this PR

Codex reports no dollar cost — only token counts, and only in the --json event stream. Left unpriced, every codex run records total_cost_usd as null and the /heimdall dashboard sums it as $0: a silent cost-data loss, which is a failure class this org treats as critical (and the same shape as the pricing drift that cost $143K earlier this year).

harness/pricing.py already solves this for mercy and can be reused, but wiring it means adding --json capture, an events artifact, and a pricing fallback in emit_telemetry.py — enough to deserve its own diff rather than bloating this one.

So: codex must not be made the default runtime until that lands. This PR only makes the path *capable* of running; it does not switch anything over. Tracked on AI-609.

## Business Value

Every argument for moving Heimdall to Codex — the OS-level sandbox that makes giving the agent a shell safe, the order-of-magnitude cost drop Mercy already sees at ~$0.008/review, and one runtime across both agents — is unavailable while the path 401s on its first call. This is the cheapest change standing between today's shell-less single-shot agent and a verify-driven loop, and three later tickets depend on it.

## Manual Effort Estimate

~3 hours of focused work with no AI — mostly discovering the four blockers (the auth one is invisible until you run it and misreads as a bad key) rather than the edits themselves. *(Proposed by Claude — Keval to confirm or adjust.)*

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

Linear: [AI-608](https://linear.app/builder-team/issue/AI-608/p03-retry-transient-model-errors-in-the-fixrevise-stages) · Project: [Heimdall Software Factory](https://linear.app/builder-team/project/heimdall-software-factory-4216613b8e5f)

Found while verifying [#38](https://github.com/AI-Builder-Team/mercy/pull/38) live.

## What this PR changes

With the base-sync auth fixed, the first revise run in 16 days went all the way through — checkout, base sync, agent, publish. It still produced nothing, because the model returned Repeated 529 Overloaded errors. The harness posted that string to the PR as heimdall's reply and logged outcome=no_change.

Diagnose retries. Mercy's review retries. The two stages that write code did not.

# diagnose — 3 attempts, only a schema-valid diagnosis counts
for attempt in 1 2 3; do claude -p ... && validate && exit 0; done
# fix / revise — one shot
claude -p ... ; echo $? > "$RUNNER_TEMP/fix_rc"

All four write-stage call sites — fix and revise × claude-code and codex — now share one retry contract: 3 attempts, 20s/40s backoff, each classified by heimdall/agent_retry.py.

## What is and isn't retried

| Signal | Verdict | Why |

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

| 429, 5xx, overloaded, rate limit, connection reset, timeout | transient → retry | the provider, not the prompt |

| bad/incorrect API key, 401/403, missing bearer, context too long, unknown model | terminal → stop | retrying spends money to be told twice |

| clean exit, no edits | ok → stop | a valid outcome, not a failure |

| non-zero exit, nothing recognisable | transient → retry | unattributable crashes are more often blips; the cap bounds the cost |

Terminal beats transient when both appear, so 401 Unauthorized (after connection reset) is not retried.

A clean exit can still be transient: both CLIs report API failures in-band and still exit 0 — which is precisely how #1580 was misread.

## Telemetry: agent_error

Exhausting the attempts forces rc=75, so tree extraction treats it as no-fix. The verdict is threaded step → job → telemetry, and a new terminal outcome agent_error separates *"the agent read it and nothing was needed"* from *"the agent never spoke"*. Today both land in no_change, which is why this failure was invisible on the dashboard.

## Revise rounds needed no change

count_rounds.current_round() derives the round from pushed commit subjects, and a failed attempt pushes nothing — so a blip cannot consume a round against max_revise_rounds. Verified in the source rather than assumed.

## Verification

The real Fix (Claude Code) step, extracted from the parsed YAML and executed against stubbed CLIs (sleep stubbed so backoff didn't cost 60s):

| Case | Attempts | rc | verdict |

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

| A. 529 twice, then success | 3 | 0 | ok — recovered |

| B. 529 every time | 3 | 75 | transient → agent_error |

| C. clean run, no edits | 1 | 0 | ok — no wasted retry |

| D. bad API key | 1 | 1 | terminal — no wasted retry |

My first attempt at this harness was wrong — I forgot to create full-prompt.md, so the shell redirect failed before the stub ever ran and all four cases collapsed onto the same path. The table above is from the corrected run.

Also: bash -n on all four extracted step scripts · ruff check harness heimdall clean · actionlint clean · pytest heimdall/tests 219 passed (26 new) · pytest harness/tests 158 passed.

Tests include the literal #1580 output as a regression case, and three structural tests asserting all four sites carry the contract, force rc=75, and clear the previous attempt's output file (a crashed retry that writes nothing would otherwise be classified from the prior attempt's file and look like success).

## Business Value

Transient provider errors are routine at this volume, and each one currently costs a revise round and reads to a human as "the agent had nothing to offer" — directly undermining trust in the loop this project is building. Worse, telemetry recorded them as no_change, so the failure was invisible in the /heimdall dashboard and in any reliability measure taken from it. This is the same contract diagnose and Mercy already had; the write stages simply never got it, and they are the expensive ones to lose.

## Manual Effort Estimate

~3 hours of focused work with no AI — the classifier and its terminal/transient precedence, four call sites kept identical, the step→job→telemetry wiring for a new outcome, and a stubbed-CLI harness to prove the loop actually retries and actually stops. *(Proposed by Claude — Keval to confirm or adjust.)*

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

Linear: [AI-594](https://linear.app/builder-team/issue/AI-594/p01-fix-the-revise-mode-checkout-auth-outage) · Project: [Heimdall Software Factory](https://linear.app/builder-team/project/heimdall-software-factory-4216613b8e5f)

## The outage

Every revise-mode run has failed since 2026-08-12 — 32 consecutive. Last success was 2026-08-10 (PR #1186). 34 of heimdall's 37 lifetime failed runs are this one bug.

Every checkout in heimdall.yml sets persist-credentials: false, deliberately — the agent must never inherit a usable git credential from the tree it edits. Two later steps then ran a bare git fetch:

| Site | Behaviour |

|---|---|

| revise → Sync with base branch | fatal: could not read Username for 'https://github.com' → exit 128 |

| revise_publish → Push revision | same call with \|\| true → silent |

The first kills the job before the agent is ever invoked. Mercy posts *"address the review findings"*, the run starts, dies in setup, and the PR rots. It is the largest single cause of the 9 mercy-approved-but-unmerged PRs on Surtr.

The second is worse in kind: || true swallowed the failure, git cat-file then missed the base tip, and the revision was pushed with no merge parent — reported only as a ::warning::.

## The fix

Both now route through git_authed, which supplies the token for a single process via GIT_CONFIG_* env:

AUTH_B64=$(printf 'x-access-token:%s' "${GH_TOKEN}" | base64 | tr -d '\n')
git_authed() {
GIT_CONFIG_COUNT=1 \
GIT_CONFIG_KEY_0="http.extraheader" \
GIT_CONFIG_VALUE_0="AUTHORIZATION: basic ${AUTH_B64}" \
git "$@"
}

Chosen over the alternatives because it is scoped to one command and leaks nowhere: never written to .git/config (which the agent can read), and never in argv (/proc/<pid>/cmdline is world-readable). base64 | tr -d '\n' rather than base64 -w0, which is GNU-only. The publish-side failure is now reported rather than swallowed.

## Making the rule mechanical

The bug is easy to reintroduce — persist-credentials: false is many lines away from the git fetch it breaks. So heimdall/git_auth.py turns it into a lint: find_unauthenticated_git_calls() flags any network-touching git command (fetch/push/clone/ls-remote/pull) not routed through git_authed or an inline x-access-token: URL.

Run against the unpatched workflow it found exactly the two real sites and nothing else:

unauthenticated git network calls BEFORE fix: 2
L2530: git fetch --quiet origin "${BASE_REF}"
L3280: git fetch --quiet origin "${BASE_REF_ENV}" || true
AFTER fix: 0

A test holds it at zero, and the detector has its own tests for comments, Bash(git push:*) tool strings, local-only commands, and substring near-misses (legit fetching, --prefetched).

## Verification

End-to-end against the real private repo, with credentials stripped (GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null):

| Step | Result |

|---|---|

| Bare git fetch | ❌ fails — unauthenticated |

| git_authed fetch | ✅ succeeds, FETCH_HEAD 25d5adb |

| .git/config after | ✅ clean — no credential written |

One honest note: locally the unauthenticated failure surfaces as remote: Repository not found rather than the runner's could not read Username. Same root cause — no credential on a private repo — but git picks a different message depending on whether it thinks it can prompt. The runner logs are the authority for the exact string.

Also verified:

- bash -n on both patched step scripts, extracted from the parsed YAML

- ruff check harness heimdall — clean

- actionlint — clean

- pytest heimdall/tests 193 passed (17 new) · pytest harness/tests 158 passed

## Not fixed here

The two existing git push "https://x-access-token:${TOKEN}@github.com/..." calls put the token in argv. The lint accepts them (they *are* authenticated) and no agent runs concurrently with those steps, so it is not the outage — but it is the same family and worth a follow-up.

## Business Value

Restores the automated review→fix→merge loop that has been silently dead for 16 days. Until this lands, every Mercy review finding on a Heimdall PR goes nowhere and a human has to finish the job by hand — the exact toil the Heimdall Software Factory project exists to remove. Nine reviewed, CI-green, approved fixes to real production pipeline failures are currently stranded because of it. This is also the cheapest fix in that project: two lines of real change, unblocking 32 runs' worth of lost capability, and it is a prerequisite for every later phase.

## Manual Effort Estimate

~3 hours of focused work with no AI — the diagnosis is the expensive part (32 identical-looking failures whose real error is buried mid-log in a setup step), then the scoped-token fetch, auditing sibling call sites, the regression lint, and an end-to-end credential test. *(Proposed by Claude — Keval to confirm or adjust.)*

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

Linear: [AI-593](https://linear.app/builder-team/issue/AI-593/p6-withdraw-heimdalls-org-wide-access-login-allowlist) · Project: [Heimdall Software Factory](https://linear.app/builder-team/project/heimdall-software-factory-4216613b8e5f)

First PR of the Heimdall Software Factory work. Lockdown lands before the autonomy phases, because every capability that follows makes the summon surface more valuable to get wrong.

## What this PR changes

Both @heimdall gates in heimdall.yml trusted any repo OWNER/MEMBER/COLLABORATOR — effectively every collaborator on Surtr and Klair. This adds a HEIMDALL_TRUSTED_LOGINS repo variable that, when set, replaces the association rule with an explicit login allowlist. When unset, behaviour is byte-for-byte what it was, so no consumer repo changes until its admin opts in.

The variable is a repo *variable*: only an admin sets it, it is never readable from a branch or by the agent, so nothing heimdall writes can widen its own trust set.

mercy[bot] and the-heimdall[bot] remain trusted under both postures — those two talking to each other *is* the revise loop, and App comments always report author_association=NONE.

## Why the check is inlined rather than imported

The Gate step deliberately runs before the trusted-harness checkout: roughly 3 in 4 triggered runs are ordinary chatter with no mention at all, and they must skip without paying for a checkout. So heimdall/trust.py holds the decision as GATE_SNIPPET and both gates embed it verbatim.

That inlining is only safe if it cannot drift, so test_trust.py does three things:

1. asserts the workflow contains exactly two TRUST_PY heredocs,

2. asserts they are identical to each other and to trust.GATE_SNIPPET,

3. executes the literal snippet as a subprocess and checks it agrees with is_trusted across a 10-case table.

I verified the drift test actually fails, not just passes: mutating one gate trips *"the intake and revise gates have drifted"*; mutating both identically trips *"no longer matches trust.GATE_SNIPPET"*.

## Verification

Both patched gate scripts were extracted from the parsed YAML and executed directly:

| Gate | Commenter | Association | Allowlist | Result |

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

| intake | kevalshahtrilogy | OWNER | set | runs |

| intake | someteammate | OWNER | set | ignored |

| intake | the-heimdall[bot] | NONE | set | runs |

| intake | someteammate | MEMBER | *unset* | runs (legacy rule intact) |

| intake | randomguy | NONE | *unset* | ignored |

| revise | kevalshahtrilogy | OWNER | set | action=revise |

| revise | someteammate | OWNER | set | action=none |

| revise | mercy[bot] | NONE | set | action=revise |

| revise | the-heimdall[bot] | NONE | set | action=revise |

- ruff check harness heimdall — clean

- actionlint on heimdall.yml — clean

- pytest heimdall/tests — 176 passed (29 new) · pytest harness/tests — 158 passed

- YAML parses and bash -n passes on both gate blocks

Note: a human who registered the username mercy must not match mercy[bot], so bot logins are compared exactly (case aside) — deliberately without the app/…[bot] slug normalisation used elsewhere for PR authors. There's a test for it.

## Follow-up (not in this PR)

HEIMDALL_TRUSTED_LOGINS=kevalshahtrilogy needs setting on Surtr and Klair. Until it is set, this PR changes nothing at runtime.

## Business Value

Heimdall is being turned into an autonomous software factory: unattended merge to main, full read access to the warehouse, a shell in CI, and automatic production releases. Each of those makes "who can summon it" a materially bigger decision than it was when heimdall only wrote diagnostic issues. Narrowing trust from ~every org collaborator to one named login is the cheapest available risk reduction and costs nothing in capability — of 26 heimdall-driven PRs to date, 22 are Keval's, 3 are heimdall's own, and 1 is Benji's. Doing it first means the rest of the project widens power inside a boundary that is already tight, rather than racing to close it afterwards.

## Manual Effort Estimate

~2 hours of focused work by hand with no AI — the helper and its tests, two call sites with fiddly heredoc-inside-YAML indentation, and the behavioural verification of both gates. *(Proposed by Claude — Keval to confirm or adjust.)*

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

## Summary

For the record: records the production correction for the 2026-08-27 saas-budgeting-pipeline failure. The noncentral_charges ingest failed closed with:

ValueError: account mapping is incomplete for 2026-Q3: ['673400066384']

The correction maps that account in core_finance.aws_spend_budget_account_mapping and is already applied and verified in production.

## Why

The account began reporting RDS cost on 2026-08-25 but had no governed account mapping, so the pipeline correctly refused to publish rather than silently omitting its noncentral charges. All other ingests (docker, k8s, database_units, mapping, server_costs) published successfully that run — this is the same pattern previously fixed in #1290 for the three Khoros reservation accounts.

## How the missing mapping was derived

Not a guess from the account ID:

1. core_finance.aws_spend_net_amortized_costs shows all RDS cost for the account arrives under master payer 286233338944, governed payer name TotogiMaster0.

2. Cost Explorer (via that payer's ESW-CO-ReadOnly-P2 role) reports the linked-account description exactly as Prod-Zax-qppnglumentecuat.

3. The naming family Prod-Zax-qppng* is uniformly mapped to class = Quark Product, bu = Zax in every quarter (e.g. Prod-Zax-qppnglumenuat / 448406925203 through 2030-Q4).

4. Of the payer's 30 accounts with 2026-Q3 RDS cost, 28 are mapped to Quark Product / Zax and one to Central Engineering. The complete all-payer Q3 RDS gap set is exactly this one account, so the mapping is both correct by family and complete.

## Production remediation completed

- Applied 18 rows: 2026-Q3 through 2030-Q4.

- Verified before and after COMMIT: zero all-payer 2026-Q3 RDS accounts missing a mapping.

- Ran noncentral_charges through the production Step Functions path:

- execution: manual-noncentral-673400066384-20260828T125030Z

- status: succeeded

- 192 → 193 accounts, source current through 2026-08-27

- 137 billable accounts / $137,000 quarterly charges

- mapping_gap_count: 0

- The new account now appears in the mart as Prod-Zax-qppnglumentecuat, Quark Product / Zax, billable with the standard $1,000 extra charge.

## Validation

- Rehearsal applied inside a rolled-back transaction and verified before the committed write.

- Post-commit anti-join returns zero missing Q3 mappings.

- Production rerun green.

No code change is needed; this is a governed-data correction, consistent with the ownership boundary: saas-budgeting-pipeline only reads core_finance.aws_spend_budget_account_mapping.

## Summary

- Move AWS Spend Insights from Claude Opus 4.6 to Claude Opus 4.8.

- Raise the per-request token budget from 16,000 to 20,000.

- Request structured insight output.

## Summary

- Refresh the GuidePlatform source contract for four reviewed nullable fields on limitless meetings and workshop progress

- Regenerate the raw and clean warehouse contract and rotate the pinned Guide roster consumer hash

## Why

Production run f50f3fa9-6016-435e-8b0b-1f37c3ea9c96 failed closed after GuidePlatform added idempotency_key to limitless_meetings and deletion metadata to workshop_progress. The exact-shape guard correctly preserved the last complete publication, but the pipeline cannot publish fresh data until the reviewed contract, warehouse views, and deployed runner are aligned.

## Business Value

Restores the supported path to fresh GuidePlatform staging data while preserving immutable landing, exact schema validation, atomic publication, and fail-closed downstream contract checks.

## Test plan

- [x] GuidePlatform raw sync: 77 tests passing

- [x] Guide roster refresh: 66 tests passing, 5 environment-gated integration tests skipped

- [x] Ruff lint and format checks passing

- [x] Live contract regeneration check passing

- [x] DDL dry run: 355 statements with only limitless_meetings and workshop_progress marked for guarded atomic recreation

- [ ] Apply guarded production DDL, deploy the runner, and verify a fresh production publication as separate rollout gates

## Summary\n- Add School Year selection across desktop and mobile Forecast views\n- Scope Finance, QS, Forecast, and later pipeline stages to the selected cohort\n- Preserve unassigned HubSpot Lead and Showcase counts across years with a clear scope tooltip\n\n## Why\nThe Forecast dashboard mixed hardcoded year assumptions with partially year-aware data, causing school-year changes and drilldowns to compare different populations. Early HubSpot stages also lack reliable intended-enrollment-year attribution, so treating them as year-specific hid valid pipeline records.\n\n## Business Value\nAdmissions can compare the available 2026/27 and 2027/28 cohorts consistently while retaining visibility into early demand that cannot yet be honestly assigned to a School Year.\n\n## Test plan\n- [x] 221 focused Forecast, Admissions, consistency, mobile, and worker tests\n- [x] Chat, Convex, and analytics worker typechecks\n- [x] Repository lint, architecture, Convex path, and read-bounds gates\n- [x] Seven-lane adversarial review plus targeted fix verification\n- [x] Local dashboard smoke across both School Years

## Summary

Update the CFO data API ontology so Q20 facilities analysis and Q44

single-school P&L reconciliation use the governed warehouse contracts and keep

reported QuickBooks actuals distinct from management-model adjustments.

### Changes

- Directs facilities questions to the latest school-year snapshot of

mart_education.agg_school_pl_breakdown, with correct rent, facilities, and

enrollment-divisor semantics.

- Replaces the Q44 Alpha-Miami-specific bridge with a reusable canonical-school

workflow over mart_education.agg_school_quickbooks_pl_reconciliation_by_month.

- Uses mart_education.agg_quickbooks_unmapped_actual_by_month alongside the

school reconciliation mart to disclose QuickBooks activity that cannot be

attributed to a school.

- Locks the workflow into unit contract tests.

### Design decisions

- Reported actual P&L is QuickBooks actual revenue less QuickBooks cost. Stripe

remains a cost; headcount repricing is not a reported-actual adjustment.

- Budgeted Timeback is optional, explicitly labelled management-model context.

- A missing rent row or enrollment divisor is unavailable evidence, not a zero

or invented ratio.

## Warehouse prerequisites

The reconciliation and unmapped-actuals marts are established Surtr warehouse

contracts and are ready for this ontology to use. This PR does not create,

migrate, or deploy Redshift tables; it teaches the CFO data API to query the

existing canonical sources.

## Test plan

- [x] npm test -- --runInBand tests/unit/routes/data-api-contract.test.ts —

7 passed.

- [x] npm run typecheck passes.

- [x] Targeted ESLint and Prettier checks pass.

- [x] git diff --check origin/main...HEAD passes.

## Summary

Publish governed QuickBooks contracts that let the CFO data API answer Q20

(school facilities spend) and Q44 (reported school P&L reconciliation) from

canonical, current warehouse data.

### Changes

- Finance-owned class-to-canonical-school crosswalk, separate from

unit-economics-model assignment.

- Monthly reported-actual school QuickBooks P&L reconciliation mart and

optional budgeted-Timeback comparison.

- New: mart_education.agg_quickbooks_unmapped_actual_by_month, which

reports the volume and P&L of actual postings outside canonical-school scope.

- Atomic refresh, validation, access audits, and documentation for the mapping,

reconciliation, and coverage contracts.

- Q20 facilities mart access and canonical school attribution.

### Design decisions

- Q44 reported actual P&L is exclusively QuickBooks revenue less QuickBooks

cost. Stripe stays in cost; headcount repricing is never a reported-actual

adjustment.

- A zero school reconciliation residual proves only the mapped-school QuickBooks

scope. Unmapped actuals are exposed separately; the pipeline does not fail

merely because central/company-level activity cannot be allocated to a school.

- Crosswalk and budget-detail implementation objects are intentionally not

exposed to MCP_user; the consumer reconciliation and coverage marts are.

- Q20 retains mart_education.agg_school_pl_breakdown as the facilities source.

Missing enrollment divisors remain unavailable per-student results.

## Test plan

- [x] uv run pytest tests/test_financial_core_ddl.py tests/test_handler.py —

66 passed.

- [x] uv run pytest tests/test_sql_contracts.py tests/test_handler.py — 64

passed.

- [x] ruff format --check pipelines and ruff check pipelines pass with the

CI-pinned Ruff 0.15.22.

- [x] git diff --check origin/main...HEAD passes.

- [x] Read-only live-source query confirmed a material unmapped QuickBooks

perimeter, validating the need for the new coverage mart.

- [ ] Review Finance's crosswalk and resulting canonical-school mapping policy

before merge.

## Summary

- Route newly observed Finalsite assessment and re-evaluation statuses into explicit admissions stages

- Preserve calendar-authoritative Shadowing promotion and add focused routing coverage

- Add status labels and scope seed column types to remove misleading dbt warnings

## Why

The scheduled dbt build is failing closed because newly observed tenant-local statuses have no explicit funnel classification and fall into the guarded catch-all. These statuses need deliberate semantics rather than catch-all membership.

## Business Value

Restores scheduled admissions mart refreshes while keeping assessment milestones, reopened evaluations, and terminal denials represented accurately.

## Test plan

- [x] dbt 1.12 full project parse

- [x] dbt compile for the changed pipeline model and new routing assertion

- [x] Read-only execution of compiled candidate logic against the affected status family

- [ ] Hosted PR dbt build against isolated PR-prefixed objects

<!-- CURSOR_AGENT_PR_BODY_BEGIN -->

## Summary

Adds hermetic evidence for the prior-quarter clone embed-loss boundary

(parent [KLAIR-2827](https://linear.app/klair/issue/KLAIR-2827)) and selects the smallest safe production fix, backed by executable

fixtures/tests instead of speculation.

## Why it's needed

Drive's files().copy() already preserves embeds initially, while Klair's

text-only session parse and the section-rewrite paths can remove them

later. The right implementation choice (additive edit vs. full round-trip

vs. a documented workaround) can't be made safely until those boundaries

are separately proven with evidence — this spike does exactly that, with

zero production behavior change.

## Changes

- Fixture: klair-api/tests/board_doc/fixtures/gdoc_embed_clone_fixture.json

— a hermetic documents().get()-shaped response with ordinary text, a

pasted-image inlineObjectElement, a linked Sheets-chart

inlineObjectElement (with sheetsChartReference identity), one changed

section (contains a quarter token) and one untouched section.

- Characterization tests: test_embed_safe_clone_spike.py pins, separately:

the copied doc retains both embed identities; the text-only parse drops

both while the tracked section range still spans them; and

sync_to_google_doc's delete range for a changed section fully contains

its embed while the untouched section is never referenced. Also pins an

additional finding: the router's *default* publish gate

(USE_CANONICAL_GDOC_WRITES_DEFAULT=False) resolves to the whole-document

legacy HTML re-import path, not the per-section path — the actual

dominant risk today.

- Prototype: budget_bot/board_doc/embed_safe_clone_prototype.py — a

pure, unwired additive-edit planner reusing the production

replaceAllText request shape. test_embed_safe_clone_prototype.py

proves this plan for a quarter/title substitution emits zero index

ranges (so it structurally cannot overlap an embed), in direct contrast

to sync_to_google_doc's request for the same substitution.

- Decision record: budget_bot/board_doc/EMBED_SAFE_CLONE_SPIKE.md —

observed behavior, fixture/test evidence, the selected next action

(additive copy-first implementation), exact files/functions to

change next, separate treatment of pasted images vs. linked charts, and

required follow-up tickets.

## Breaking changes

None. No production code path, API call, credential, or deployment

behavior changes — only new fixtures, tests, a spike-only unwired

prototype module, and a markdown decision record.

## Test plan

- [x] uv run pytest tests/board_doc/test_embed_safe_clone_spike.py tests/board_doc/test_embed_safe_clone_prototype.py -v — 20 passed

- [x] uv run pytest tests/board_doc/ -q — 3851 passed, 2 deselected (default -m 'not integration and not eval and not allow_network'), no regressions

- [x] ruff format --check / ruff check on all new files, using the CI-pinned ruff==0.15.22 (installed via uv tool install, not the ambient repo ruff==0.15.0) — clean

- [x] uv run pyright on all new files — 0 errors, 0 warnings

- [x] No live Google Docs/Drive/Sheets API called anywhere in this work; no credentials used

## Verification artifact

- Fixture object inventory: 2 sections, 1 pasted image (imageProperties.contentUri/sourceUri, no linked reference), 1 linked chart (linkedContentReference.sheetsChartReference with spreadsheetId+chartId, no image properties).

- Current-loss assertions: TestTextOnlyParseLosesEmbedIdentities (parse drops both embeds; tracked range still spans them) and TestFirstSyncRewritesTheEmbedRange (delete range for the changed section contains its embed).

- Additive request plan: TestAdditivePlanAvoidsUntouchedAndEmbeddedRanges — the replaceAllText-only plan contributes zero index ranges and does not overlap either embed, contrasted against sync_to_google_doc's overlapping request for the identical substitution.

- Selected next-action excerpt (EMBED_SAFE_CLONE_SPIKE.md §3): *"Decision: additive copy-first implementation."* — seed BBOT_SEC:: anchors at clone time (reusing assembler.py::_reseed_named_range_anchors's shape) plus route the clone-time quarter/title substitution through replaceAllText (reusing gdoc_service.py::replace_text's shape) instead of a queued section-body rewrite.

## Impact estimate

Business value: Replaces speculation with executable evidence and

prevents KLAIR-2827 from landing a costly embed model or a "fix" that

still destroys user documents on first sync.

Pre-AI estimate: 0.75 points — representative API fixtures,

loss-boundary characterization, additive-request prototype, and a

production decision record.

Closes KLAIR-3462

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-21392296-22ed-4b4b-9c20-44bcb433faf9?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-21392296-22ed-4b4b-9c20-44bcb433faf9&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

- Preserve legacy Due Diligence Phase 1 and Phase 2 CapEx totals when full-shaped PATCH payloads repeat null component placeholders

- Keep component-authoritative derivation, partial-data, and explicit-clear semantics unchanged

- Add contract and public API regressions for the Artemis-shaped failure path

## Why

Artemis sends a full GET-shaped Due Diligence PATCH. Legacy records can carry valid scalar CapEx totals while all four newer component fields are null. The shared patch helper incorrectly treated those null placeholders as component edits and removed the valid totals during unrelated changes.

## Business Value

Prevents silent loss of approved Due Diligence CapEx data during unrelated API edits while retaining the component breakdown as the authoritative model for new data.

## Test plan

- [x] pnpm --filter @bran/contracts exec vitest run src/due-diligence.test.ts

- [x] pnpm --filter @bran/chat exec vitest run convex/publicApi/v2/propertyHttp.test.ts

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

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

- [x] Targeted Biome and git diff checks

The one-time Phasing Plan backfill for already-clobbered production values is deliberately out of scope. No production data mutation, merge, or deployment is included.

<!-- CURSOR_AGENT_PR_BODY_BEGIN -->

## Summary

Adds four focused-section quick actions that prefill the Board Doc Coach Claire composer for user review and editing, scoped to the DocumentEditorPage editor chat surface only.

## Why It's Needed

Common rewrite and data questions currently require repetitive typing and are not discoverable. Prefills reduce friction while preserving the existing human-controlled send boundary — a click never auto-sends.

## Changes

- boardDocChatUtils.ts: new BOARD_DOC_CHAT_QUICK_ACTIONS typed constant (id/label/message) — single source of truth shared by the component and its tests.

- ChatPanel.tsx: two new optional props, showEditorQuickActions and sectionFocused (both default to false, so BoardDocModal's existing call site is unaffected). When showEditorQuickActions is true, renders a pill row above the composer with the four pinned actions. Clicking one replaces the draft outright (setInput, no merge/append) and focuses the textarea — onSend is never called from the click handler. Actions are disabled while isLoading or when !sectionFocused; in the no-focus case each button gets aria-describedby pointing at a sr-only "Scroll to a section first" span.

- DocumentEditorPage.tsx: passes showEditorQuickActions + sectionFocused={focusedSectionId !== null} to its ChatPanel mount, reusing the same focusedSectionId that free-form chat already sends on. BoardDocModal's mount is untouched.

- Tests: new ChatPanel.quickActions.spec.tsx (22 tests) covering pinned copy/order, all four prefills, draft replacement, no auto-send, edited Send/Enter, verbatim unedited send, loading/no-focus disabled gating, the accessible hint (present/absent + aria-describedby wiring), persistence across the thread, modal-shape exclusion, and Shift+Enter/IME regression. Extended DocumentEditorPage.chat.spec.tsx (+5 tests) for the real page-level wiring (disabled before focus, enabled after an H2 activates, click-then-send through sendChat).

## Breaking Changes

None.

## Test Plan

All commands run from klair-client/.

- pnpm exec vitest run src/screens/BoardDoc → 71 files / 760 tests passed (includes the 22 new quick-action tests + 5 new DocumentEditorPage wiring tests; every pre-existing composer/attachment/keyboard/Address-with-Claire test stayed green).

- pnpm exec tsc -b → clean, no errors.

- pnpm lint:pr → 0 warnings/errors on the 5 changed files (--max-warnings 0).

- pnpm exec prettier --check on the changed files → clean (formatting applied in the follow-up commit).

### Browser verification

Ran the app locally (backend uvicorn fast_endpoint:app --port 5000, frontend vite --port 3000 — see note below) authenticated as the sanctioned Klair test user, created a real Totogi Q4 2026 blank Board Doc session, and drove the full flow end-to-end in a real browser against the live app:

1. No section focused (editor still loading) → all four actions disabled, aria-describedby wired to a Scroll to a section first node in the DOM.

2. Section auto-focused → all four actions enabled.

3. Clicked Rewrite this section → textarea received exactly "Rewrite this section", took focus, no chat request fired.

4. Edited the draft to "Rewrite this section to lead with the ARR headline number." and clicked Send → real sendChat request fired with the edited text; Coach Claire replied contextually about the (empty) Executive Summary section.

5. During that request, all four actions were disabled again.

6. Narrow viewport (390px) → chip row wraps to two lines; textarea, Send, and attach button all stayed within the panel bounds (no clipping).

7. No unexpected console errors throughout (only the pre-existing, unrelated klair_comments WebSocket 500 in this environment, present before this change).

Note: the app was run on port 3000 instead of the documented 3001 because the sanctioned Clerk test session's authorized origin is localhost:3000; this was purely a local auth-environment detail, not a change to the app's default port.




## Impact Estimate

Business value: Turns four common Coach Claire edits into discoverable, editable one-click starting points without bypassing user control or section context.

Pre-AI estimate: 1 point — typed action definitions, composer wiring, accessibility and boundary-heavy component coverage, plus browser validation.

## Out of scope

- Auto-sending quick-action messages.

- Prompt libraries, saved/custom actions, or analytics.

- Backend/chat API changes.

- BoardDocModal, Budget Planner, global Claire Bot, or other chat products.

- Automatically selecting or scrolling to a section.

Closes KLAIR-2688

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-b10aff36-76c5-497e-8423-34c61c28df5c?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-b10aff36-76c5-497e-8423-34c61c28df5c&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

Clarifies that the v2 directory's aerie.directory.site.status field active value describes current source-owned directory projection membership only — not whether a site is operating, canonically open, or free of test/template records.

## Why It's Needed

The v2 directory intentionally uses identity lifecycle semantics that differ from Portfolio operating status. Without an explicit boundary, consumers could apply the wrong filter and draw operational conclusions from directory rows, or assume the directory silently excludes test/template rows.

## Changes

- chat/lib/public-api/v2/domains/directory.ts: added a Site-specific directorySiteStatusMeanings constant and traps on the aerie.directory.site.status field that state explicitly: active means present in the current source-owned directory projection; it does not prove the site is operating; it does not prove canonical open-campus membership (deferring to the existing OPEN_CAMPUS_MEMBERSHIP_BOUNDARY constant and naming AERIE-1891 as the separate owner, without redefining that predicate); and it is not a real-building-only or test/template exclusion signal.

- Named the existence of Aerie-owned test-site name patterns (chat/lib/test-site-patterns.ts) as an implementation fact only — the dictionary explicitly disclaims that this is a public directory contract or guaranteed filter on the endpoint.

- Updated the directory.read-canonical-identity workflow's routeAway/interpretation guidance to route operational/open questions to the Portfolio status/lifecycleStage surface.

- No API schemas, response rows, query filters, or status enum values changed.

## Breaking Changes

None. This is documentation and contract-validation only.

## Test Plan

- Added a focused describe("directory Site status boundary (AERIE-1892)", ...) block in chat/lib/public-api/v2/domains/directory.test.ts pinning: the positive active meaning, the "not operating" boundary, the "not canonical open-campus membership" boundary (including the AERIE-1891 reference and shared boundary text), the "not a test/template exclusion signal" boundary, the route-away guidance, and that no API schema/operation/filter changed.

- Ran vitest run lib/public-api/v2/domains/directory.test.ts (9/9 passing) and the broader lib/public-api + convex/publicApi suites — 6 pre-existing unrelated failures confirmed present on main before this change (secret-redaction artifact on an unrelated test URL string, not touched by this PR).

- Ran the DSS HTTP integration test (convex/publicApi/dss/http.test.ts), which recomputes the dictionary/enablement SHA-256 from live served bytes — passing, so no static hash needed refreshing.

- Ran pnpm typecheck (passing) and pnpm biome check on touched files (clean).

## Verification Artifact

All 9 focused tests pass:

✓ public API v2 Directory contract > directory Site status boundary (AERIE-1892) > defines active positively as current source-owned directory projection membership
✓ public API v2 Directory contract > directory Site status boundary (AERIE-1892) > states active is not evidence the Site is operating
✓ public API v2 Directory contract > directory Site status boundary (AERIE-1892) > states active is not evidence of canonical open-campus membership, and defers to AERIE-1891 without redefining it
✓ public API v2 Directory contract > directory Site status boundary (AERIE-1892) > states active is not a real-building-only or test/template exclusion signal
✓ public API v2 Directory contract > directory Site status boundary (AERIE-1892) > routes operational and open-campus questions to the Portfolio status/lifecycleStage surface
✓ public API v2 Directory contract > directory Site status boundary (AERIE-1892) > does not expose the test-site pattern list as a public contract or change API schemas/filters

## Impact Estimate

Business value: Prevents consumers from treating identity lifecycle as operational truth and accidentally including test/template records in real-site analysis.

Pre-AI estimate: 0.75 points — one semantic-catalog update, focused contract/hash tests, typecheck, and review.

## Out of scope

- Choosing canonical slugs for duplicate buildings.

- Merging, archiving, or tombstoning live records.

- Filtering directory API rows.

- Exposing test-site patterns as a public API contract.

- Changing the open-campus predicate owned by AERIE-1891.

Closes AERIE-1892

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-5359c4d6-1dc7-4d7e-ab43-40ea91a76a3f?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-5359c4d6-1dc7-4d7e-ab43-40ea91a76a3f&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

Carries forward the review fixes for PR #3674 after that PR was merged and its branch deleted while the addresser was still validating the changes.

## Why It's Needed

Persisted legacy Board Doc sessions could open an unusable modal, quarter rollover helpers lacked direct boundary tests, and legacy clone provenance could suppress the BrainLift review warning.

## Changes

- Route only modal-supported phases through BoardDocModal; legacy phases open the editor.

- Add direct rollover tests for nextQuarter and priorQuarter.

- Fail safe when old serialized sessions omit source_doc_auto_selected.

## Breaking Changes

None.

## Test Plan

- Full Board Doc backend suite: 4,022 tests passed.

- Full client Vitest suite: 6,757 tests passed.

- Ruff, pyright, ESLint, TypeScript, and Prettier passed.

## Verification Artifact

Address run run-b7055494-6594-484e-9be0-366c2565d0ab validated the changes on a fresh branch from post-merge main.

## Impact Estimate

Small, focused correctness follow-up covering legacy session routing and deserialization, plus direct quarter-boundary regression coverage.

## Review Round Completeness

- outcome: complete

- round: 1

- dispatched: 6

- reported: 6

- missing: (none)

- cause: complete

- head: 566fc13c639fe5f0c6923e700a182299cfef07f2

- run: fanout-3676-2026-08-27T22-59-33-072Z

- review: 5046405579

<!-- drones:round-completeness head=566fc13c639fe5f0c6923e700a182299cfef07f2 run=fanout-3676-2026-08-27T22-59-33-072Z -->

GitHub review #5046405579 was published and all dispatched review dimensions reported against the stamped head. Thread-count signals (unreplied=0) are meaningful for this head only — a later push invalidates the stamp. This section is a harness-shaped, head-bound self-report (not an authenticated out-of-band attestation).

<!-- CURSOR_AGENT_PR_BODY_BEGIN -->

## Summary

- Home now routes an opened session by phase: review/finalized open DocumentEditorPage directly; brainlift/welcome/bu_selection (and any other pre-editor phase) resume inside BoardDocModal, so a brainlift session can never skip BrainliftStep.

- Home's single CTA is relabeled Start Q{n} planning with the pinned "Continue from a finalized Q{n-1} document or start with a blank report." helper copy — no per-session clone button or second clone entry point is added.

- WelcomeStep's prior-doc picker heading reads Start from Q{n}, and a genuinely-empty search now shows the pinned prerequisite copy, kept distinct from the existing search-failed banner (which retains its own Retry affordance).

- A session cloned from a prior quarter lands on BrainliftStep with the pinned "Review and update the prior-quarter BrainLift before continuing." instruction, driven by a new bounded is_cloned_from_prior flag on the session response.

## Why It's Needed

The home screen hid the intended roll-forward model behind a generic "New Report" CTA, and opening a brainlift-phase session from Home bypassed BrainliftStep entirely (index.tsx routed every session straight into the full-page editor regardless of phase). Users could therefore carry stale prior-quarter BrainLift context into the editor without ever seeing it, let alone reviewing it.

## Changes

- Backend (routers/board_doc_router.py): added is_cloned_from_prior: bool to WizardSessionResponse, computed as session.source_doc_id is not None — a bounded, typed signal derived from existing session provenance (set once by create_from_prior_quarter, never re-written), not inferred from title text or doc_url.

- Frontend hook (useBoardDocWizard.ts, boardDocApi.ts): added isClonedFromPrior to wizard state, hydrated from the session response on every resumeSession (and reset on session switch, so it can't leak across sessions).

- Home routing (index.tsx, BoardDocHome.tsx): onOpenSession now forwards (sessionId, phase); index.tsx owns the phase → editor-vs-modal decision (no duplicated phase state).

- Pinned copy (BoardDocHome.tsx, WelcomeStep.tsx, BrainliftStep.tsx, constants.ts): exact CTA/helper text, prior-doc heading, no-candidate prerequisite copy, and clone-origin BrainLift instruction, per the pinned product decisions. Added shared nextQuarter/priorQuarter helpers in constants.ts so Home and WelcomeStep describe the same rolling quarter pairing.

- Existing clone-forward flow (WelcomeStep's prior-doc picker → createFromPrior), paste-URL, blank-start, search-failure Retry, and KLAIR-2875 service-account sharing guidance are all unchanged.

## Breaking Changes

None. is_cloned_from_prior is a new, additive field (frontend types treat it as optional for back-compat), and onOpenSession's new second argument is only consumed internally by BoardDoc/index.tsx.

## Test Plan

- [x] klair-api: uv run pytest tests/board_doc/ — 3832 passed, 2 deselected (unrelated, pre-existing).

- [x] klair-api: uv run ruff format + uv run ruff check + uv run pyright on routers/board_doc_router.py — clean.

- [x] klair-client: pnpm exec vitest run src/screens/BoardDoc — 69 test files, 730 tests passed (includes 4 new spec files and 2 updated ones).

- [x] klair-client: pnpm exec tsc -p tsconfig.app.json --noEmit — clean.

- [x] klair-client: pnpm exec eslint --max-warnings 0 --no-warn-ignored on all changed/new files — clean.

- [x] Manual boot check: started the local backend (uvicorn fast_endpoint:app) and frontend (pnpm dev) and confirmed /board-doc renders without a JS crash.

- [ ] Full authenticated browser walkthrough (prior-doc available / empty / brainlift-resume flows, desktop + narrow width, per the issue's Browser Verification section) — not captured. This sandboxed cloud-agent run did not receive the sanctioned Clerk test-user browser state (AERIE_E2E_STORAGE_STATE_B64) or the Google service-account credentials (credentials.json / SERVICE_ACCOUNT_FILE, GOOGLE_API_KEY) needed to sign in and exercise the real clone/gdoc path — those secrets are configured for this repo but weren't injected into this run (public-repo secret-injection restriction). The app was confirmed reachable up to Klair's sign-in gate; screenshots of the pinned authenticated states could not be produced honestly without real credentials.

## Verification Artifact

- Backend: tests/board_doc/ → 3832 passed, 2 deselected.

- Frontend: src/screens/BoardDoc → 69 test files, 730 tests passed.

- Typecheck (tsc -p tsconfig.app.json --noEmit) and lint (eslint --max-warnings 0) on all changed/new files: clean.

- Screenshots board-doc-planning-home.png / board-doc-prior-brainlift.png / board-doc-no-prior.png: pending — blocked on the sanctioned Clerk browser state / Google service-account credentials not being available in this run (see Test Plan).

## Impact Estimate

Business value: Makes the intended Q4 roll-forward path discoverable and prevents stale prior-quarter BrainLift context from being silently bypassed.

Pre-AI estimate: 2 points — phase-aware routing, bounded home/WelcomeStep copy changes, clone-origin plumbing, component coverage, and browser evidence.

Closes KLAIR-2876

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-7277fcf7-b154-4ff6-a930-45fb90c61654?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-7277fcf7-b154-4ff6-a930-45fb90c61654&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

Expose source-derived target-year and confirmed-enrollment year/as-of metadata on each public Admissions forecast program.

## Why It's Needed

The forecast response currently combines target-year projections with a confirmed value sourced from current/reference-year enrollment without identifying either year. Consumers can therefore interpret current enrollment as a target-year commitment.

## Changes

- Carried three new provenance fields through the internal forecast backend row (ForecastBackendSchoolRow in chat/convex/admissions/dashboards/admissions.ts): targetSchoolYear (from comingYearProjections.projectionYear), confirmedSchoolYear (the selected published enrollment school year used by the query), and confirmedAsOf (the snapshot date of whichever branch — enrollmentProjections.currentEnrollment or the enrollmentSnapshots.onCampus fallback — supplied onCampus/confirmed).

- Added targetSchoolYear to ForecastProgram and confirmedSchoolYear/confirmedAsOf to ForecastSummary in the public /v1/admissions/forecast projection (chat/convex/publicApi/http.ts). A program missing any of the three is omitted from programs rather than served with fabricated metadata — the same degrade-rather-than-fail convention already used for parentInterestSignals.

- Updated the /v1/admissions/forecast OpenAPI schemas and descriptions (chat/lib/public-api/openapi.ts) to document the new required fields and state that confirmed is current/reference-year enrollment, not a commitment for targetSchoolYear.

- Added focused tests: HTTP tests covering the projection-backed and snapshot-backed confirmed branches with distinct confirmedSchoolYear/targetSchoolYear values, the provenance-unavailable omission path, and usageMode=physical; OpenAPI tests pinning the new required fields and descriptions.

- The physical-location overlay row (buildAlphaAustinPhysicalForecastRows) sets the three new fields to null since it has no snapshotDate of its own — the merged physical-mode response continues to carry provenance from the matching base program row, which applyPhysicalForecastOverlay never overrides.

## Breaking Changes

None. The response change is additive and existing forecast values retain their meaning.

## Test Plan

- npx vitest run convex/publicApi/http.test.ts — 17 passed (includes 4 new provenance tests: dual-branch confirmed/target divergence, omission on missing provenance, usageMode=physical pinning).

- npx vitest run lib/public-api/__tests__/openapi.test.ts — 25 passed (includes 1 new test pinning required fields/descriptions).

- npx vitest run convex/dashboards.test.ts — 53 passed (existing internal forecast-query tests unaffected).

- npx vitest run convex/publicApi lib/public-api convex/admissions convex/dashboards.test.ts convex/finance — 1306 passed, 6 pre-existing failures unrelated to this change (sandbox env-var URL redaction, reproduced identically on main).

- pnpm typecheck — passes with no errors.

- npx biome check on the 5 touched files — no errors.

## Verification Artifact

Program-mode fixture (programCode: "alpha_fixture", projection-backed confirmed):

{
"programCode": "alpha_fixture",
"displayName": "Alpha Fixture School",
"status": "open",
"targetSchoolYear": 2027,
"summary": {
"confirmed": 42,
"confirmedSchoolYear": "2025-2026",
"confirmedAsOf": "2025-10-15",
"financeExpected": 42,
"isMaterialVariance": false
}
}

Physical-mode fixture (usageMode=physical, programCode: "Alpha Austin", provenance preserved from the base row through the overlay):

{
"programCode": "Alpha Austin",
"displayName": "Alpha Austin",
"status": "open",
"targetSchoolYear": 2027,
"summary": {
"confirmed": 55,
"confirmedSchoolYear": "2025-2026",
"confirmedAsOf": "2025-10-01",
"financeExpected": 55,
"isMaterialVariance": false
}
}

Both fixtures were captured from real Convex query/HTTP execution against seeded test data (not hand-written), then trimmed to the relevant fields.

## Impact Estimate

Business value: Prevents API consumers from reading current/reference-year confirmed enrollment as a commitment for the forecast target year.

Pre-AI estimate: 2 points — propagate source provenance through the forecast query and public contract, update both usage modes, and add branch-complete query, HTTP, and OpenAPI coverage.

Closes AERIE-824

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-0278820b-b9ae-48b2-ae90-41f3d6eeb49d?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-0278820b-b9ae-48b2-ae90-41f3d6eeb49d&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 an isolated seven-day operation journal and crash-safe prepare/acknowledge service for future Budget Bot add-on mutations, starting with rename_section. This PR builds the durable storage/service primitives only — no existing route, Apps Script/Sidebar file, or user-facing mutation is wired to it yet (that's KLAIR-3231).

## Why It's Needed

Add-on mutations currently cross the backend session store and Google DocumentApp with no shared durable operation identity. A failure between the two systems (a browser tab closing, an Apps Script exception, a dropped connection) can make a client retry duplicate the backend mutation, or leave the client and the session disagreeing about whether the mutation actually landed.

## Changes

- budget_bot/board_doc/addon_operations/models.py — lifecycle vocabulary (prepared -> applied_unacked -> completed, with failed/repair_required off-ramps), bounded StagedRenameCommand/StagedRenameResult, the AddonOperationRecord, a canonical SHA-256 request-fingerprint envelope (UTF-8, sorted keys, compact separators), and a stable error-code taxonomy.

- budget_bot/board_doc/addon_operations/store.py — DynamoDBAddonOperationStore against a new dedicated table, Klair-BudgetBotAddonOperations (PAY_PER_REQUEST, TTL on ttl), keyed directly by the caller-supplied UUIDv4 operation_id. Every transition is one conditional UpdateItem/PutItem gated on status + ttl > now; a by_session_created_at GSI backs a bounded, Query-only recovery listing.

- budget_bot/board_doc/addon_operations/service.py — prepare_operation (idempotent create with server-computed fingerprint, stale-session-version rejection before creation, non-enumerating conflict/access errors) and acknowledge_operation (crash-safe: conditionally moves to applied_unacked, runs one save_with_merge_retry closure that checks the session marker, applies the staged rename exactly once, and appends the marker in the same save, then only marks the ledger completed after that save lands).

- budget_bot/board_doc/models.py — WizardSession.applied_addon_mutations (bounded marker list) plus has_applied_addon_mutation/record_applied_addon_mutation (age-pruned against the same seven-day window, capped at 500, backward-compatible for pre-existing sessions).

- tests/board_doc/addon_operations/ — condition-aware fake DynamoDB table + injected clock + in-memory/CAS-aware wizard-storage fakes, plus model/store/service test suites (130 tests).

## Breaking Changes

None. No existing HTTP route, response shape, Sidebar.html/Code.gs/DocumentPlanning.gs behavior, or user-facing mutation changes. WizardSession.applied_addon_mutations is a new, optional, backward-compatible field.

## Test Plan

Ran, in order: the focused operation model/store/service/session-serialization suite, the full hermetic Board Doc backend suite, Ruff (format + check, pinned 0.15.22), and Pyright scoped to the touched modules only.

uv run pytest tests/board_doc/addon_operations/ -q      # 130 passed
uv run pytest tests/board_doc/ -q                        # 3961 passed, 2 deselected
ruff format --check budget_bot/board_doc/models.py budget_bot/board_doc/addon_operations/ tests/board_doc/addon_operations/
ruff check budget_bot/board_doc/models.py budget_bot/board_doc/addon_operations/ tests/board_doc/addon_operations/
uv run pyright budget_bot/board_doc/models.py budget_bot/board_doc/addon_operations/   # 0 errors

## Verification Artifact

Exact counts: test_models.py 74, test_store.py 33, test_service_prepare.py 8, test_service_acknowledge.py 15 → 130 passed. Full tests/board_doc/ suite: 3961 passed, 2 deselected (pre-existing integration-marked tests), 0 failed.

Failure-injection trace proving a crash after the session save is recovered without double-applying the rename (TestCrashRecovery::test_crash_after_session_save_before_journal_completion_is_recovered):

1. prepare_operation + first acknowledge_operation call run normally through the applied_unacked transition and the session-mutation closure — the rename lands, the marker is appended, and the session save succeeds.

2. store.mark_completed is monkeypatched to raise a bare RuntimeError("simulated process crash") on this first call only — a fault that is *not* one of the package's typed/caught infra errors, so it propagates straight out of acknowledge_operation uncaught, modeling a worker that dies right at the journal-completion step.

3. Assertions after the crash: the session already shows the new title and exactly one applied_addon_mutations entry (assert len(session.applied_addon_mutations) == 1); the ledger row is confirmed still applied_unacked, not repair_required (assert mid_flight.status == AddonOperationStatus.APPLIED_UNACKED).

4. A second acknowledge_operation call (the retry) is made with mark_completed restored to normal. It observes the marker already present, skips _apply_and_mark entirely, and the ledger transitions straight to completed.

5. Final assertions: recovered.status == COMPLETED; the session's marker count is still exactly 1 (assert len(session_after_retry.applied_addon_mutations) == 1 # not duplicated); and session_after_retry.version == version_after_first_attempt — proving the retry made zero additional session mutations.

A sibling test (test_compensation_exhaustion_escalates_to_repair_required) covers the distinct case where the completion write is attempted and genuinely, persistently fails (an AddonOperationInfrastructureError the store itself detects) — that case is escalated to repair_required rather than left silently applied_unacked forever, while still confirming the rename was applied exactly once.

## Impact Estimate

Business value: Establishes the durable idempotency boundary needed to stop add-on retries from duplicating backend mutations or falsely claiming success after a browser/Apps Script failure.

Pre-AI estimate: 3 points — dedicated conditional store, canonical fingerprinting, crash-safe session marker, merge-retry integration, and adversarial concurrency/failure tests.

Closes KLAIR-3230

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-4bf6d568-4ae1-48ba-b386-3ea70f647b0c?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-4bf6d568-4ae1-48ba-b386-3ea70f647b0c&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

- Publish refreshed eduCRM mart rows into the existing Redshift relation inside a rollback-safe transaction

- Fail closed on empty candidates, schema/type drift, row-count mismatch, and unconfirmed statement outcomes

- Bound submit permissions to the target cluster and document stable-OID schema evolution and recovery

## Why

The prior rename-and-drop publication replaced each live table relation. Aerie reads planned against the retired OID could fail immediately after commit, and schema-bound dependencies could prevent the old table from being dropped, leaving the recurring sync PARTIAL. Keeping the target relation stable removes both failure modes while preserving all-or-nothing visibility.

## Business Value

Forecast and other Aerie consumers retain reliable reads while the half-hourly eduCRM marts refresh, and dependent warehouse views no longer make otherwise successful publications report PARTIAL.

## Test plan

- [x] Runner unit suite: 29 passed

- [x] CDK pipeline config suites: 601 passed

- [x] CDK TypeScript build

- [x] Ruff focused correctness checks and formatting

- [x] Read-only live compatibility checks: all current targets are non-empty; exact type-metadata query succeeds

- [x] Dev Redshift canary: stable target and view OIDs across 21 publications; 91 concurrent reads with zero errors; forced count mismatch rolled back; schema drift failed before mutation; canary objects removed

- [x] Hosted CI

Local full-CDK note: 796 tests passed; six Docker-dependent bundling tests could not execute because the local Docker daemon was unavailable.

<!-- CURSOR_AGENT_PR_BODY_BEGIN -->

## Summary

Documents every field served by the Aerie document resource in the documents.document semantic catalog, with explicit handling for uploader identity, third-party document URLs, and mutable satisfaction-evidence titles. This is a documentation/contract-validation-only change; no wire response shapes, authorization, or behavior change.

## Why It's Needed

The source-owned dictionary previously described only 4 of the 13 fields required by the served Document schema (documentRef, documentType, topic, provenance), omitting person-bearing (uploader) and third-party locator (openUrl) data that callers already receive on the wire. A caller relying on the dictionary could not apply appropriate handling to fields it was never told existed.

## Changes

- chat/lib/public-api/v2/domains/documents.ts:

- Added documents.document dictionary fields for every remaining property in DOCUMENTS_V2_SCHEMAS.Document.required: site, title, associations, openUrl, mimeType, notes, uploader, timestamps, version, revision.

- Classified uploader as confidential, documented uploader.displayName as person-bearing identity, and added traps against copying/logging/publishing it or inferring identity/authorization outside the authorized response.

- Gave openUrl explicit confidential sensitivity and traps stating it is an authorized third-party document locator: it can disclose the provider and document identity, and possessing it does not expand access or make it safe to redistribute.

- Added accurate nullMeaning for every nullable field (openUrl, mimeType, notes, uploader) and honest invariants/traps noting that timestamps.sourceCreatedAt/sourceModifiedAt (and the equivalent provenance fields) are currently always null in the served projection.

- Strengthened provenance's meaning/traps to keep it explicit as authorized detail-read-only data (not part of the list-response parity set), still sourced from DocumentDetail.

- Documented documents.requirement.satisfactionEvidence, stating its {title, registeredAt} shape is evidence metadata (not canonical document identity) and that its mutable title must never replace documentRef in joins.

- Left AERIE-1866's documentType enum meanings and phasing-plan semantics untouched.

- chat/lib/public-api/v2/domains/documents.test.ts: Added a schema-derived parity test that reads DOCUMENTS_V2_SCHEMAS.Document.required directly (no hand-maintained second field inventory) and fails if any required field is missing from the documents.document dictionary, plus focused tests pinning uploader/openUrl sensitivity+handling and the satisfactionEvidence mutable-title boundary.

## Breaking Changes

None. Documentation and contract-validation only; served wire shapes and authorization are unchanged.

## Test Plan

Ran, from chat/:

- npx vitest run lib/public-api/v2/domains/documents.test.ts — 9/9 passed (includes the new schema-derived parity test and the new uploader/openUrl/satisfactionEvidence tests).

- npx vitest run convex/publicApi/v2/documentsHttp.test.ts — 30/32 passed; the 2 failures (Content-Location header value prefixed with [REDACTED]) reproduce identically on main before this change (verified via git stash) and are an unrelated sandbox URL-redaction artifact, not caused by this diff.

- npx vitest run convex/publicApi/dss/http.test.ts — 2/2 passed (dictionary/enablement SHA-256 hashes are computed live from served bytes in the test, so no hardcoded hash needed updating).

- npx vitest run lib/public-api/agent-context/projection.test.ts — 14/14 passed.

- npx vitest run src/public-api-agent-context.test.ts (packages/contracts) — 5/5 passed (shared catalog/schema cross-validation, including nullable-vs-schema and enum-vs-schema checks).

- pnpm typecheck — passed with no errors.

- npx biome check on both touched files — no errors (ran --write once to apply formatting, then re-verified clean).

## Verification Artifact

Schema-derived required set from DOCUMENTS_V2_SCHEMAS.Document.required (13 fields): documentRef, site, title, documentType, topic, associations, openUrl, mimeType, notes, uploader, timestamps, version, revision.

Actual documents.document dictionary field set after this change (14 fields — the 13 above plus detail-only provenance, which the new test asserts is present but *not* claimed as part of the Document.required list-response parity set): documentRef, site, title, documentType, topic, associations, openUrl, mimeType, notes, uploader, timestamps, version, revision, provenance.

The new documents.document dictionary field set is derived from the served Document schema and stays in parity test computes missingFromDictionary from these two sets directly (asserting it is empty) and additionally runs assertValidAgentContextCatalogs against the live Document/DocumentRequirement/DocumentDetail schemas, so a future served field silently added to Document.required without a matching dictionary entry — or a nullable/enum mismatch — fails this test immediately.

The served DSS dictionary/enablement SHA-256 hashes in chat/convex/publicApi/dss/http.test.ts are computed live from the actual response bytes on each run (not hardcoded), so DSS tier-a HTTP surfaces > serves the five-clause front and exact keyless document pointers passing confirms the expanded dictionary content round-trips correctly through the served /api/dss/dictionary endpoint without any hash needing manual regeneration.

## Impact Estimate

Business value: Prevents DSS and API consumers from overlooking a person-bearing uploader field or treating a live document URL as harmless metadata, while making the source-owned dictionary match the response it claims to describe.

Pre-AI estimate: 1.5 points — one semantic catalog expansion, schema-derived parity coverage, DSS contract/hash verification, focused tests, and review.

Closes AERIE-1886

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-a6474d57-49b4-4a3c-aec5-be85c47ae82c?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-a6474d57-49b4-4a3c-aec5-be85c47ae82c&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

Classifies the real OS-integration cases in src/dispatch-tick-signal.test.ts, src/interrupted-fire-orphan.test.ts, and src/read-capped-file.test.ts as explicit, reason-bearing Linux-only Vitest selections, and replaces the mkfifo --version command-discovery check with a real create-and-open capability probe. No production code changed.

## Why it's needed

AI-573 reproduced three failure families on clean Windows main at 26ab3fa:

- dispatch-tick-signal.test.ts — three real-SIGTERM integration cases time out waiting for the child .ready signal (no POSIX signal delivery on Windows).

- interrupted-fire-orphan.test.ts — bash/setsid/SIGKILL/heartbeat-shell cases can't execute with Linux semantics on Windows.

- read-capped-file.test.ts — mkfifo --version can classify as "support" in a full Windows run even though the host can't create/exercise a real FIFO, and the same case skips in isolation (nondeterministic full-suite vs. isolated selection).

These tests protect deliberately Linux-only production primitives (PID/boot identity, signal delivery, orphan detection, heartbeat, capped-file reads), which must keep failing closed off-Linux per repo policy. The fix makes the *test selection* explicit and deterministic without touching that production behavior.

## Changes

- src/dispatch-tick-signal.test.ts: wrapped the describe block containing the three real-bash + real-SIGTERM cases in describe.skipIf(process.platform !== "linux") with a reason-bearing title. The second describe (static text-pin assertions against scripts/dispatch-poll-wrapper.sh, no process spawn) is untouched and still runs everywhere.

- src/interrupted-fire-orphan.test.ts: wrapped the four cases that spawn a real bash (optionally under setsid, with real SIGKILL/SIGTERM delivery, or invoking real pnpm drones heartbeat) in it.skipIf(process.platform !== "linux") with reason-bearing titles:

- surviving parent writes abnormal-exit after SIGKILL of child

- AI-231 address round 2: the timeout validator actually rejects all-zero durations...

- AI-253: tick_terminal_recorded() correctly distinguishes a landed write from a killed one...

- AI-253: no double terminal record and no silent hole across the real rc==0 race boundary...

All other cases in this file (pure function assertions, mocked gh calls, and static text-pin reads of dispatch-poll-wrapper.sh) are unchanged and still run on Windows.

- src/read-capped-file.test.ts: replaced the mkfifo --version command-discovery check (HAS_MKFIFO) with detectFifoCapability(), which fails closed off-Linux and, on Linux, actually creates a FIFO in a throwaway temp dir and opens it non-blocking (not just checking the binary responds to --version) before reporting support — this is what makes full-suite and isolated selection agree. The probe cleans up its temp dir in a finally. The FIFO test's own title now embeds the capability reason when skipped.

## Breaking changes

None. No production code (src/*.ts outside *.test.ts) was touched.

## Test plan

Ran on this Linux (Cursor Cloud) VM:

pnpm exec vitest run src/dispatch-tick-signal.test.ts
→ 11 tests passed (no skips; real SIGTERM cases execute)
pnpm exec vitest run src/interrupted-fire-orphan.test.ts
→ 33 tests passed (no skips; real bash/setsid/SIGKILL/heartbeat cases execute)
pnpm exec vitest run src/read-capped-file.test.ts
→ 5 tests passed (no skips; real FIFO case executes via the new capability probe)
pnpm exec vitest run src/dispatch-tick-signal.test.ts src/interrupted-fire-orphan.test.ts src/read-capped-file.test.ts
→ 3 files, 49 tests passed (11 + 33 + 5 = 49 — full-suite selection matches isolated selection exactly, resolving the AI-573 nondeterminism)
pnpm typecheck
→ clean, no errors
pnpm test
→ 172 vitest files / 5866 tests passed; Python suite: 717 tests OK (skipped=19, pre-existing/unrelated)

Verified no stray temp dirs, FIFOs, or child processes were left behind by the new/modified cases (checked /tmp and ps aux after each run). Confirmed via git stash that a handful of unrelated pre-existing temp-dir leaks in interrupted-fire-orphan.test.ts (e.g. drones-ai227-parent-*) exist identically on unmodified main — out of scope per this ticket (general spawn-load/cleanup issues are AI-582/other AI-573 families, not touched here).

Windows was not available in this sandbox to execute directly; the change is a pure test-selection change guarded by process.platform !== "linux" (the same pattern already proven on this platform check elsewhere in the repo, e.g. src/dispatch-lock.test.ts:416 and src/box-bootstrap.test.ts:204), so on Windows these it/describe blocks would report as skipped with the embedded reason text (e.g. "Linux-only — POSIX SIGTERM/process-group semantics are unavailable off-Linux") visible in Vitest's own output — never a silent early return — while every platform-neutral case in the same three files continues to execute normally.

## Verification artifact

Full Linux run output (representative excerpt):

✓ src/read-capped-file.test.ts (5 tests) 14ms
✓ src/dispatch-tick-signal.test.ts (11 tests) 183ms
✓ src/interrupted-fire-orphan.test.ts (33 tests) 4328ms
✓ AI-253: no double terminal record and no silent hole across the real rc==0 race
boundary (end-to-end, real pnpm heartbeat; real bash + setsid + SIGTERM;
Linux-only — a real bash/setsid and POSIX signal semantics are unavailable
off-Linux)  4175ms
Test Files  3 passed (3)
Tests  49 passed (49)

pnpm test full-suite tail:

Test Files  172 passed (172)
Tests  5866 passed (5866)
...
Ran 717 tests in 61.415s
OK (skipped=19)

## Impact estimate

Business value: Removes unstable/nondeterministic Windows failures in these three test files while preserving the real Linux signal, orphan-recovery, and FIFO regressions that protect unattended dispatch operation. Clears one bounded blocker toward making Windows CI strict (AI-408, out of scope here).

Pre-AI estimate: 1 point — classify and isolate three families of real OS integration probes with reason-bearing platform selection, replace a command-discovery FIFO check with a real capability probe, and verify selection/cleanup determinism on Linux (both isolated and full-suite).

## Review Round Completeness

- outcome: complete

- round: 1

- dispatched: 5

- reported: 5

- missing: (none)

- cause: complete

- head: cd3d00de1b09c81eff4831b543ae887083f39bea

- run: fanout-256-2026-08-27T18-49-15-926Z

- review: 5044547739

<!-- drones:round-completeness head=cd3d00de1b09c81eff4831b543ae887083f39bea run=fanout-256-2026-08-27T18-49-15-926Z -->

GitHub review #5044547739 was published and all dispatched review dimensions reported against the stamped head. Thread-count signals (unreplied=0) are meaningful for this head only — a later push invalidates the stamp. This section is a harness-shaped, head-bound self-report (not an authenticated out-of-band attestation).

Closes AI-580

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-188b9a50-067a-4064-9da1-cd9cd77c8680?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-188b9a50-067a-4064-9da1-cd9cd77c8680&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

- Accept nullable QuickBooks category metadata for unmapped School Performance budget-mart accounts.

- Preserve unmapped account rows and their actual/budget values so report generation does not fail on valid publisher output.

- Add regression coverage for the Alpha New York 69120 Abandoned Projects Write-off contract shape.

## Business Value

Prevents valid School Performance QTD reports from failing when a QuickBooks account has not yet received a governed category assignment. Alpha New York’s report can now generate while preserving the unmapped account and its financial amount for downstream review.

## Implementation Effort

An average engineer would likely need about 1–2 hours to trace the mart contract, confirm the live unmapped-account case, update the consumer types/parser, add regression coverage, and run focused backend validation.

## Test Plan

- [x] uv run ruff format services/schools_performance_report/models.py services/schools_performance_report/data.py tests/schools_performance_report/test_data.py

- [x] uv run ruff check services/schools_performance_report/models.py services/schools_performance_report/data.py tests/schools_performance_report/test_data.py

- [x] uv run pyright services/schools_performance_report/models.py services/schools_performance_report/data.py tests/schools_performance_report/test_data.py

- [x] ADMIN_TOKEN_SECRET=test-only-secret uv run pytest tests/schools_performance_report/ — 112 passed.

- The repository default pytest configuration excludes integration, eval, and allow-network tests; RedshiftHandler is globally mocked, so SQL correctness against the live schema is not covered by pytest.

## Linear

- KLAIR-3467: https://linear.app/builder-team/issue/KLAIR-3467/fix-school-performance-qtd-reports-with-unmapped-quickbooks-accounts

## Stack

- Stacked on PR #3671: https://github.com/AI-Builder-Team/Klair/pull/3671

## Summary

- Retry once when Claude returns a malformed render_executive_narrative payload, including non-list bullets, missing tool blocks, and duplicate driver references.

- Fall back to a deterministic narrative built only from computed QTD metrics after a second validation failure.

- Continue propagating model API, data-access, rendering, upload, and document-service errors.

## Business Value

Prevents otherwise valid Education QTD reports from failing solely because the LLM returned a schema-invalid narrative. Report generation now completes with grounded financial commentary while preserving the existing error visibility for infrastructure and data failures.

## Implementation Effort

An average engineer would likely need about 3–5 hours to trace the structured-commentary failures, implement the validation retry and metrics-only fallback, update the contract documentation, add regression coverage, and run the feature validation.

## Test Plan

- [x] uv run ruff format services/monthly_qtd_report/commentary.py tests/monthly_qtd_report/test_commentary.py

- [x] uv run ruff check services/monthly_qtd_report/commentary.py tests/monthly_qtd_report/test_commentary.py

- [x] uv run pyright services/monthly_qtd_report/commentary.py tests/monthly_qtd_report/test_commentary.py

- [x] uv run pytest --import-mode=importlib tests/monthly_qtd_report/ --ignore=tests/monthly_qtd_report/test_qtd_reports_router.py — 944 passed, 1 warning.

- The repository default pytest configuration excludes integration, eval, and allow-network tests; RedshiftHandler is globally mocked. The unfiltered feature invocation remains blocked during collection by the existing router test's unset Zendesk credentials.

## Linear

- KLAIR-3466: https://linear.app/builder-team/issue/KLAIR-3466/prevent-qtd-report-failures-from-malformed-llm-commentary

## Summary

- Mark the retired QuickBooks runners as retired in the pipeline migration and finance documentation.

- Replace obsolete onboarding, token-manager, and sibling-pipeline references with the current quickbooks-raw-sync and mart-education-quickbooks-refresh path.

- Remove the retired NetSuite pipeline from current on-demand precedent lists.

- Preserve dated retirement packets, regression guards, and detailed historical implementation sections as audit history.

## Linear

- [SURTR-958](https://linear.app/builder-team/issue/SURTR-958/clean-up-stale-references-to-retired-surtr-pipelines)

## Business Value

Prevents operators and maintainers from following deleted pipelines, stale schedules, or obsolete state-machine instructions, while making the supported QuickBooks ingestion path clear.

## Implementation Effort

Approximately 1–2 hours for an engineer to inventory the references, update the current documentation and explanatory comments, verify successor links, and run targeted checks.

## Test Plan

- git diff --check

- Targeted reference audit with rg

- Verified the linked quickbooks-raw-sync README exists

No pipeline behavior or infrastructure was changed.

<!-- CURSOR_AGENT_PR_BODY_BEGIN -->

## Summary

Fixes two stable Windows-only test false failures identified by AI-573, both isolated to test expectations rather than production behavior:

- src/discovery.test.ts hard-coded a POSIX-only literal (/repo/eligibility-cache) as the expected eligibilityCacheDirFor() result, instead of comparing against host-platform path semantics.

- src/task-file.test.ts's corpus frontmatter test enumerated task files by absolute checkout path and fed that same absolute path to the parser as the task identity, so the intentionally title-less tasks/klair/c3-clone.md could exceed the 100-character cloud-agent-name cap purely because of a long checkout prefix.

## Why it's needed

Strict Windows CI cannot distinguish real regressions from these two checkout-path-dependent false failures. Both failures reproduce from clean main at 26ab3fa922ca1f17b51675de013900a1ffb7673b on the supported Windows/PowerShell 5.1 host per AI-573. The underlying production contracts (eligibilityCacheDirFor(), parseTaskFile()/parseTaskString(), buildAgentName(), the 100-char cap) are already correct — only the tests express the wrong path semantics.

## Changes

- src/discovery.test.ts: the eligibilityCacheDirFor sibling-of-runs/ test now computes its expectation via join(dirname(runsDir), "eligibility-cache") — the same node:path calls the production function uses — instead of a hard-coded POSIX string. Added assertions that the result is still outside runsDir (not merely "some normalized string"), keeping the regression meaningful.

- src/task-file.test.ts: the corpus frontmatter test still uses the production enumerateMarkdownSpecs() to get absolute file paths and reads real bytes from each one, but now parses each file via parseTaskString(raw, repoRelativeId) with a deterministic tasks/... identity (computed via relative(REPO_ROOT, p), forward-slash-normalized) instead of handing the parser the long absolute path. Added an explicit assertion that tasks/klair/c3-clone.md (the title-less file) is present in the enumerated corpus, so the test can't silently stop covering it.

## Breaking changes

None. No production source, task corpus content, snapshots, or CI workflow files were touched — only the two test files.

## Test plan

Ran the following from a clean checkout (Linux cloud VM; CURSOR_API_KEY is unavailable and unnecessary here, so no agent was fired — see Verification artifact for the Windows-execution caveat):

pnpm exec vitest run src/discovery.test.ts
# ✓ 31 tests passed
pnpm exec vitest run src/task-file.test.ts
# ✓ 55 tests passed
pnpm exec vitest run src/discovery.test.ts src/task-file.test.ts
# ✓ 86 tests passed (2 files)
pnpm typecheck
# tsc --noEmit — clean, no errors
pnpm test
# vitest: 172 test files passed, 5866 tests passed
# Python (scripts/run-python-tests.mjs / unittest): Ran 717 tests, OK (skipped=19)

git status --porcelain after the full run showed only the two intended test files modified — no production code, task corpus, or report artifacts were left dirty.

## Verification artifact

All verification above was run on the Linux cloud agent VM, not on the Windows/PowerShell 5.1 host — Windows execution was not actually performed for this PR. The fixes are written using host-platform node:path operations (dirname/join/relative/sep, no hard-coded / or \ literals or path-length assumptions), so the same regression should run unchanged on Windows; this was manually verified by comparing path.posix vs path.win32 behavior for the exact dirname/join calls involved (e.g. path.win32.join(path.win32.dirname("/repo/runs"), "eligibility-cache") yields a backslash-joined sibling distinct from the old POSIX-only literal, confirming the old assertion would have failed on Windows and the new one does not depend on separator style).

## Impact estimate

Business value: Removes two stable Windows false failures so strict Windows CI can detect real regressions, while preserving cache placement and the cloud agent-name safety cap.

Pre-AI estimate: 0.5 points — two narrow test corrections, cross-platform path review, and full-suite verification.

## Review Round Completeness

- outcome: complete

- round: 1

- dispatched: 5

- reported: 5

- missing: (none)

- cause: complete

- head: 27a27fbc50dd6ffcb16456b18b31a7778ee5e435

- run: run-4c0a1a4a-eb07-4a88-be3a-476aa167c8cd

- review: 5044605438

<!-- drones:round-completeness head=27a27fbc50dd6ffcb16456b18b31a7778ee5e435 run=run-4c0a1a4a-eb07-4a88-be3a-476aa167c8cd -->

GitHub review #5044605438 was published and all dispatched review dimensions reported against the stamped head. Thread-count signals (unreplied=0) are meaningful for this head only — a later push invalidates the stamp. This section is a harness-shaped, head-bound self-report (not an authenticated out-of-band attestation).

Closes AI-581

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-654ab509-f47e-41fa-b049-963e1c5b54bf?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-654ab509-f47e-41fa-b049-963e1c5b54bf&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>

## Demo

https://docs.google.com/document/d/1ckOpckg510sMt3P1MqqquSbPPqDq8IPRbtQBS8fFFAc/edit?tab=t.0

## Summary

- Align Table 2 and Table 3 to the approved shared P&L comparison order, preserving governed model-category values and using the published current-student denominator for per-student values.

- Add a Students row before the staffing or spend sections in Table 4 (Guide Spend), Table 5 (Other Headcount), and Table 6 (Facilities).

- Preserve the non-bold treatment for Add Back: D&A and Less: CapEx, and keep local worktrees pointed at the personal Ash QTD worker.

## Business Value

Makes generated school performance reports match the approved review format across the comparison, staffing, and facilities tables. Reviewers can compare actuals and modeled budgets on a consistent row spine, see student context where staffing and spend are shown, and distinguish adjustment rows without changing the underlying financial values.

## Implementation Effort

An average engineer would likely need about 3–5 hours to trace the published mart contracts, implement the shared Table 2/Table 3 layout, add the Table 4–6 context rows, update regression coverage, and run the scoped validation.

## Test Plan

- [x] uv run pytest tests/schools_performance_report/ — 109 passed; the repository default excludes integration, eval, and allow-network tests.

- [x] uv run ruff format services/schools_performance_report/document.py tests/schools_performance_report/test_document.py — files unchanged.

- [x] uv run ruff check services/schools_performance_report/document.py tests/schools_performance_report/test_document.py

- [x] uv run pyright services/schools_performance_report/document.py tests/schools_performance_report/test_document.py

- [x] bash -n start-services.sh

## Linear

- KLAIR-3465: https://linear.app/builder-team/issue/KLAIR-3465/preserve-governed-variance-percentages-in-qtd-school-reports

<!-- CURSOR_AGENT_PR_BODY_BEGIN -->

## Summary

Fixes the four stable Windows failures AI-573 isolated in three CLI test fixtures:

- src/cli/help-parity.test.ts's three generated ESM probes (scrubbed defaults, deliberately-unscrubbed sentinel, npm-style bin-symlink entrypoint resolution) embedded a raw Windows absolute path as an import specifier, which Node/tsx rejects with ERR_UNSUPPORTED_ESM_URL_SCHEME.

- src/cli/ai246-move-verify.test.ts's dotenv --skill-root regression did a raw substring check against Commander's rendered default, which never matches Commander's win32 backslash-escaped (default: "...") rendering.

## Why it's needed

These are the last blockers (per AI-573's clean-Windows-checkout reproduction) before a strict Windows CI signal can be trusted for the cli.ts split's help-parity harness (AI-408). Leaving them red either hides real regressions behind "known-flaky on Windows" or forces operators to skip the harness on their real dev platform.

## Changes

- src/cli/spawn-tsx.fixtures.ts: added filePathToImportUrl(path, opts?), a thin node:url pathToFileURL wrapper that converts an absolute filesystem path into a standards-compliant file: URL string for use as (or embedding inside) a generated ESM import specifier. opts.windows threads the same explicit-seam pattern pathDefaultToken's caseInsensitive option already uses, so Windows drive-letter/UNC conversion is testable deterministically on Linux CI.

- src/cli/help-parity.test.ts: routed the three generated-probe import specifiers through filePathToImportUrl instead of embedding a raw filesystem path. The npm-symlink probe's helper import (already a file: URL via new URL(...)) is now embedded directly instead of being round-tripped through fileURLToPath first (which is exactly how the raw-path bug got there). Added a describe block with a real tsx-subprocess dynamic-import round-trip through a path with URL-significant characters (space, #, %, unicode).

- src/cli/spawn-tsx.test.ts: added deterministic Windows drive-letter, UNC, and POSIX shape coverage for filePathToImportUrl via the opts.windows seam (runs — and would have failed pre-fix — on Linux CI, which has no windows-latest leg).

- src/cli/ai246-move-verify.test.ts: added decodeOptionDefault(helpText, flag), which locates the named option's (default: "...") capture and JSON.parses it to recover the exact value Commander rendered, then compares that decoded value to the configured skillSentinel path — instead of a substring check that assumes no escaping. --base's non-path sentinel keeps its independent plain substring check (untouched). Added unit coverage for decodeOptionDefault itself: win32 backslash-escaped decoding, option-scoping (doesn't grab a different option's default), and the not-found/no-default cases.

Contract surface affected: none — no production CLI/help/entrypoint code changed, only test fixtures and test-only helpers (.fixtures.ts is excluded from the tsc build).

## Breaking changes

None. No CLI option, help text, snapshot, or isProcessEntrypoint/symlink production semantics changed.

## Test plan

- [x] pnpm exec vitest run src/cli/help-parity.test.ts → 27 passed (Linux)

- [x] pnpm exec vitest run src/cli/ai246-move-verify.test.ts → 9 passed (Linux)

- [x] pnpm exec vitest run src/cli/ai247-move-verify.test.ts → 8 passed, unchanged, isolated run (Linux)

- [x] pnpm exec vitest run src/cli/help-parity.test.ts src/cli/ai246-move-verify.test.ts src/cli/ai247-move-verify.test.ts → 44 passed together (Linux)

- [x] pnpm typecheck → clean

- [x] pnpm test → 172 vitest files / 5874 tests passed + Python 717 tests ... OK (skipped=19) (scripts/run-python-tests.mjs)

- [ ] Reviewer-side / Windows: this cloud implementation VM is Linux-only (per AGENTS.md, it "cannot substitute for the real supported Windows validation recorded by AI-573"). Please re-run the same four commands above on the supported Windows host before merge and confirm all four (previously-red) tests now pass there too.

- No symlink-probe skip occurred on this Linux host (SYMLINK_SUPPORTED was true); the it.skipIf(!SYMLINK_SUPPORTED) guard and its reason-bearing title are unchanged, so an unprivileged Windows account without Developer Mode would still see a named, documented skip rather than a failure — never silently treated as passing.

## Verification artifact

Repro of the exact bug class before the fix (raw Windows path as an import specifier is invalid ESM syntax on any platform, not just Windows — it corrupts the string the same way, just doesn't hit Node's URL-scheme check the same way on POSIX):

$ node -e "console.log('import { x } from \"C:\\\\\\\\Users\\\\\\\\foo\\\\\\\\bar.ts\";')"
import { x } from "C:\\Users\\foo\\bar.ts";

After the fix, the same path round-trips through filePathToImportUrl:

$ node -e "console.log(require('node:url').pathToFileURL('C:\\\\Users\\\\foo\\\\bar.ts', {windows:true}).href)"
file:///C:/Users/foo/bar.ts

New/updated test run (Linux):

$ pnpm exec vitest run src/cli/help-parity.test.ts src/cli/ai246-move-verify.test.ts src/cli/ai247-move-verify.test.ts
✓ src/cli/ai246-move-verify.test.ts (9 tests)
✓ src/cli/help-parity.test.ts (27 tests)
✓ src/cli/ai247-move-verify.test.ts (8 tests)
Test Files  3 passed (3)
Tests  44 passed (44)

Help snapshots under src/cli/help-parity/snapshots/ are unchanged — this PR touches no committed snapshot.

## Impact estimate

Business value: Removes four stable Windows failures while preserving the hermetic help/entrypoint regressions a strict Windows CI signal needs (unblocks part of AI-408) — without hiding CLI path leaks or weakening the scrub/no-scrub/symlink probes.

Pre-AI estimate: 1 point — three focused fixture corrections, cross-platform path/URL regression coverage, and Windows/Linux verification, as scoped in the task.

## Review Round Completeness

- outcome: complete

- round: 2

- dispatched: 5

- reported: 5

- missing: (none)

- cause: complete

- head: 38db1fd7366015035b7d9dbfef334cdeeb0fe103

- run: run-b7e57a85-0914-487c-9589-b9cabc64ab11

- review: 5044331252

<!-- drones:round-completeness head=38db1fd7366015035b7d9dbfef334cdeeb0fe103 run=run-b7e57a85-0914-487c-9589-b9cabc64ab11 -->

GitHub review #5044331252 was published and all dispatched review dimensions reported against the stamped head. Thread-count signals (unreplied=0) are meaningful for this head only — a later push invalidates the stamp. This section is a harness-shaped, head-bound self-report (not an authenticated out-of-band attestation).

Closes AI-579

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-5c806a88-701d-489b-8743-be515783ac2d?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-5c806a88-701d-489b-8743-be515783ac2d&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

Restores Aerie's already-decided AERIE-1017 normalized-status open-campus-membership contract after PR #1077 replaced it with a stale unresolved-membership narrative. AERIE-1017 (decided 2026-07-29): a campus is a current open-campus member if and only if its normalized site status is open; lifecycle stage (including operating), opening dates, and health never establish or override that membership, and legacy stored completed continues to normalize to open.

## Why It's Needed

PR #1077 introduced OPEN_CAMPUS_MEMBERSHIP_BOUNDARY/OPEN_CAMPUS_MEMBERSHIP_HANDLING, which told DSS consumers that canonical open-campus membership "remains unresolved" and that Aerie's normalized status is merely "an operational signal, not that membership answer." This directly contradicted the already-decided and already-implemented AERIE-1017 contract (normalizeSiteStatus() / isOpenSiteStatus()), and routed agents/users away from the authoritative answer Aerie already exposes.

## Changes

- chat/lib/public-api/open-campus-membership.ts: replaced OPEN_CAMPUS_MEMBERSHIP_BOUNDARY/HANDLING with OPEN_CAMPUS_MEMBERSHIP_CONTRACT/ROUTING, stating the decided positive contract instead of an unresolved-membership narrative.

- chat/lib/public-api/dss.ts: /dss and /dss/skill now route open-campus-membership questions to Aerie and identify normalized status=open as authoritative, while keeping lifecycle stage/opening dates as separate observations.

- chat/lib/public-api/v2/domains/portfolio.ts: corrected the site-status operation description, portfolio.site lifecycle text, the status/lifecycleStage enum meanings and traps, the school-calendar field traps, and the find-site/update-site-status workflow routeAway/interpretation/handling text so every mention agrees with AERIE-1017.

- chat/lib/public-api/v2/domains/insights.ts: the portfolioHealth lifecycle text reused the same stale boundary constant (added after #1077 in #1139); reworded it to distinguish its own active/paused/open health-list scope decision from the canonical open-campus-membership predicate.

- packages/contracts/src/site-status.ts: restored isOpenSiteStatus()'s doc comment to name it the canonical open-campus predicate (AERIE-1017) without implying stage or dates override it.

- Rewrote chat/convex/publicApi/dss/http.test.ts, chat/lib/public-api/v2/domains/portfolio.test.ts, and chat/lib/public-api/v2/domains/insights.test.ts to assert the decided positive contract (and fail if the stale unresolved-membership wording reappears) instead of pinning the stale premise as a regression. Existing DSS routing and HTTP/document cross-consistency coverage from #1077 is preserved with the corrected premise.

## Breaking Changes

None. This restores the previously decided and implemented contract; normalizeSiteStatus("completed") compatibility is unchanged.

## Test Plan

Ran the focused DSS/portfolio/insights/contract tests, repository typechecking, and Biome on touched files; also ran a repository-wide search for the prohibited stale-wording variants.

## Verification Artifact

$ cd chat && npx vitest run lib/public-api/v2/domains/portfolio.test.ts lib/public-api/v2/domains/insights.test.ts convex/publicApi/dss/http.test.ts
✓ convex/publicApi/dss/http.test.ts (2 tests)
✓ lib/public-api/v2/domains/portfolio.test.ts (5 tests)
✓ lib/public-api/v2/domains/insights.test.ts (4 tests)
Test Files  3 passed (3)
Tests  11 passed (11)
$ cd packages/contracts && npx vitest run src/site-status.test.ts
✓ src/site-status.test.ts (3 tests)
Test Files  1 passed (1)
Tests  3 passed (3)
$ cd chat && pnpm typecheck
> tsc --noEmit && tsc -p convex/tsconfig.json --noEmit
(exit 0, no errors)
$ cd packages/contracts && pnpm typecheck
> tsc --noEmit
(exit 0, no errors)
$ pnpm biome check chat/convex/publicApi/dss/http.test.ts chat/lib/public-api/dss.ts \
chat/lib/public-api/open-campus-membership.ts chat/lib/public-api/v2/domains/insights.test.ts \
chat/lib/public-api/v2/domains/insights.ts chat/lib/public-api/v2/domains/portfolio.test.ts \
chat/lib/public-api/v2/domains/portfolio.ts packages/contracts/src/site-status.ts
Checked 8 files in 19ms. No fixes applied. (exit 0)
$ grep -rn "OPEN_CAMPUS_MEMBERSHIP_BOUNDARY\|OPEN_CAMPUS_MEMBERSHIP_HANDLING" --include="*.ts" --include="*.tsx" .
(no output — zero matches)
$ grep -rn "no Aerie field is the canonical open-campus predicate today\|Canonical open-campus membership remains unresolved" chat/
(no output — zero matches)

Note: npx vitest run lib/public-api/ convex/publicApi/ shows 6 unrelated pre-existing failures (all [REDACTED]-vs-plain-URL assertion mismatches from an environment secret-redaction interaction) in files this PR does not touch; confirmed identical failures reproduce on a clean main checkout before this branch's changes.

## Impact Estimate

Business value: Restores the authoritative open-campus-membership contract served to DSS consumers and prevents stale issue text from overriding decided source semantics.

Pre-AI estimate: 1.5 points — bounded multi-document semantic correction, repository-wide wording audit, focused regression tests, and review.

Closes AERIE-1891

## Review Round Completeness

- outcome: complete

- round: 2

- dispatched: 5

- reported: 5

- missing: (none)

- cause: complete

- head: f80bde377d425258b658e5fb30319be14736bef2

- run: run-ab1f0632-4906-4537-be12-58573c7c6aa4

- review: 5044017761

<!-- drones:round-completeness head=f80bde377d425258b658e5fb30319be14736bef2 run=run-ab1f0632-4906-4537-be12-58573c7c6aa4 -->

GitHub review #5044017761 was published and all dispatched review dimensions reported against the stamped head. Thread-count signals (unreplied=0) are meaningful for this head only — a later push invalidates the stamp. This section is a harness-shaped, head-bound self-report (not an authenticated out-of-band attestation).

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-2a80a3db-0505-4767-b54f-85fc07054943?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-2a80a3db-0505-4767-b54f-85fc07054943&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

Makes src/receipt-s3.test.ts's hydrateReceiptsFromS3 content-match stamp-write-failure regression deterministic on both Windows and Linux by replacing its chmod-based read-only simulation with a call-scoped, injected filesystem-error seam.

## Why It's Needed

AI-573 reproduced the test (counts stampFailed on content-match when the stamp write cannot land) failing on clean Windows main: chmod-ing the runs directory read-only does not reliably block a write there, so the stamp landed and the test observed stampFailed=0 instead of the expected 1. AI-578 is a bounded child of AI-573 and a blocker for the strict Windows CI parity work tracked as AI-408.

## Changes

- src/receipt-s3.ts:

- Added an exported AtomicFileWriter type (the (finalPath, contents) => Promise<void> shape already implemented by writeAtomicFile).

- stampLocalS3Upload now takes an optional 4th parameter, writeFile: AtomicFileWriter = writeAtomicFile — production behavior (the atomic tmp-file-plus-rename writer) is the unconditional default; nothing changes unless a caller explicitly passes an override.

- Added a new HydrateReceiptsDeps extends ReceiptMirrorDeps interface with an optional stampWriteFile?: AtomicFileWriter field, mirroring the existing MirrorReceiptBytesDeps / SyncReceiptsDeps narrow-deps precedent so the seam is reachable only through hydrateReceiptsFromS3's deps — syncReceiptsToS3 and mirrorReceiptBytes cannot read it (they don't accept HydrateReceiptsDeps).

- hydrateReceiptsFromS3's signature now accepts HydrateReceiptsDeps (a strict superset of ReceiptMirrorDeps, so every existing caller — pnpm drones sync-receipts --hydrate, etc. — is unaffected) and threads deps.stampWriteFile into the single content-match stampLocalS3Upload call site only. The download/refresh write path (writeHydratedReceiptWithStamp) is untouched.

- src/receipt-s3.test.ts:

- Removed the chmod-based simulation (and the now-unused chmod import).

- Rewrote the regression to inject a call-scoped rejecting writer via stampWriteFile that throws a genuine coded EPERM NodeJS.ErrnoException (operation not permitted, rename) — no host permissions, no directory mode bits, no retry loop, no platform skip.

- Added assertions for: stampFailed=1 / failed=0 / skippedExisting=1 / downloaded=0 / refreshed=0 / fetched=1; the existing errors diagnostic (stamp ok after content match failed) and the existing WARN ... could not stamp log line; the receipt body remaining readable and unchanged after the failed stamp attempt.

- Added a recovery assertion: a second, later hydrateReceiptsFromS3 call using the production default writer (no stampWriteFile override) successfully stamps the same retained receipt, asserting s3Upload.status === "ok" on disk and stampFailed=0 / failed=0 on that second call.

- docs/decisions/: added a new entry recording why the seam is a per-call optional parameter with a real production default, not an env switch / VITEST branch / module-global mock.

## Breaking Changes

None. stampLocalS3Upload's new 4th parameter is optional and defaults to the existing production writer. hydrateReceiptsFromS3's deps type is widened (a superset of the previous ReceiptMirrorDeps), so every existing call site — CLI wiring, heartbeat, other tests — compiles and behaves unchanged. No S3 listing/get/download, divergence, host-authority, owner-pin, mirror, or retry-policy behavior changed.

## Test Plan

Ran from the repository root on Linux (Cursor Cloud VM), bucket unset, no live AWS calls:

pnpm exec vitest run src/receipt-s3.test.ts
# Test Files  1 passed (1)
#      Tests  89 passed (89)
pnpm typecheck
# tsc --noEmit — clean, no errors
pnpm test
# vitest: Test Files 172 passed (172); Tests 5866 passed (5866)
# python (scripts/test_*.py via scripts/run-python-tests.mjs): Ran 717 tests — OK (skipped=19)

Tested platform: Linux (Cursor Cloud VM — this is the only platform available in this environment; per AGENTS.md, Windows is the operator's local pnpm test signal and should be re-verified there before merge, since a Linux-only green result does not by itself satisfy this ticket's cross-platform requirement). The fix removes the only platform-dependent piece of the test (the chmod call) and replaces it with an in-memory injected error that is identical on both platforms, so the same 89/89 pass is expected on Windows.

## Verification Artifact

$ pnpm exec vitest run src/receipt-s3.test.ts
✓ src/receipt-s3.test.ts (89 tests) 97ms
✓ hydrateReceiptsFromS3 > counts stampFailed on content-match when an injected write/rename rejection lands (AI-578, deterministic on Windows and Linux)
Test Files  1 passed (1)
Tests  89 passed (89)
$ pnpm typecheck
> tsc --noEmit
(clean)
$ pnpm test
Test Files  172 passed (172)
Tests  5866 passed (5866)
...
Ran 717 tests in 61.455s
OK (skipped=19)

## Impact Estimate

Business value: Removes a false Windows failure while preserving evidence that receipt hydration can distinguish a best-effort metadata-stamp failure from a failed receipt download. Clears one bounded blocker to the strict Windows CI signal tracked in AI-408.

Pre-AI estimate: 1 point — one narrow injected filesystem boundary, one focused failure-and-recovery regression, cross-platform verification, and review.

## Review Round Completeness

- outcome: complete

- round: 1

- dispatched: 5

- reported: 5

- missing: (none)

- cause: complete

- head: bd5afd5520ff7168b4339b262a65786da8a3eb0a

- run: run-9d2646a0-fcf4-4380-ab2d-4f562684641c

- review: 5043729085

<!-- drones:round-completeness head=bd5afd5520ff7168b4339b262a65786da8a3eb0a run=run-9d2646a0-fcf4-4380-ab2d-4f562684641c -->

GitHub review #5043729085 was published and all dispatched review dimensions reported against the stamped head. Thread-count signals (unreplied=0) are meaningful for this head only — a later push invalidates the stamp. This section is a harness-shaped, head-bound self-report (not an authenticated out-of-band attestation).

Closes AI-578

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-b51f9f05-2d4f-4b24-8d09-3e0fcaed9efe?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-b51f9f05-2d4f-4b24-8d09-3e0fcaed9efe&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

- Publish the canonical Q3 Cursor-only threat model and end-to-end data-flow inventory for AI-403.

- Make verified repository controls, documented policies, and external/deployment assumptions visibly distinct.

- Record explicit, time-bounded residual-risk decisions and follow-up ownership through AI-404/405/406/407.

## Why it's needed

The harness had strong security decisions spread across source, tests, operator guidance, and the append-only ledger, but no single current-system model. That made it easy to overstate prompt fences as authority controls, infer live AWS/GitHub/Cursor posture from checked-in configuration, or expand the system without revisiting known credential, isolation, telemetry, and supply-chain gaps.

## Changes

- Add docs/security/threat-model.md with:

- trust zones and a Mermaid data-flow diagram;

- 18 detailed external/storage/control flows;

- storage, retention, credential, capability, and deployment-precondition inventories;

- a 20-row STRIDE register with residual severity/likelihood and named follow-up work;

- explicit Q3 dispositions mapped to every threat ID, stop events, review deadline, and change triggers.

- Add a discoverability link from README.md.

- Mark the AI-403 planning row delivered in BACKLOG.md and point to AI-404/405/406/407.

- Append the structural baseline decision under docs/decisions/.

## Breaking changes

None. This is documentation only. It does not change dispatch, agent, credential, MCP, telemetry, provider, GitHub, Linear, AWS, or queue behavior. No drone was queued or fired.

## Test plan

- [x] pnpm typecheck

- [x] node scripts/render-decisions-log.mjs

- [x] node scripts/arch-drift.mjs

- [x] pnpm vitest run src/decisions-lib.test.ts src/decisions-log.test.ts src/decisions-scripts.test.ts src/arch-drift.test.ts — 68 passed

- [x] node scripts/run-python-tests.mjs — 717 passed, 19 skipped

- [x] git diff --check

- [x] Full pnpm test exercised 5,865 passing/skipped Vitest cases; one unrelated Node 24 TAP-format assertion in materialize-secondary-runtime-fixture.test.ts failed because the expected # tests 6 line was rendered as colored ℹ tests 6. The fixture itself still produced the expected 4 passing and 2 failing tests. The isolated rerun reproduced only this formatting mismatch. Required CI uses Node 22.

## Verification artifact

- Assessed baseline: 57918bdb69b9711d344b3ab14dbd70baf8ef1670.

- Two independent read-only reviews checked factual source alignment and adversarial architecture consistency. Their P0 corrections are incorporated: browser cross-repository Release writes, the separate unpinned manual S3 sync path, conditional human-merge enforcement, explicit provider/deployment unknowns, and credential-versus-confidential-data wording.

- The document contains no credential values and treats .env.example only as supported-interface evidence.

Closes AI-403

## Summary

Teach the SURTR-783 read-only production verifier to validate EventBridge InputTransformer targets as well as constant Input targets.

## Why It’s Needed

The released verifier correctly failed closed after production began forwarding the upstream Step Functions execution ARN into core-education-enrollment. CDK represents that valid target as an InputTransformer, but the verifier only parsed target.Input, so it reported target_input=None even though the deployed transformer carries the exact protected EVENT intent.

This blocks the released-verifier gate before the SURTR-781 preflight. The production guard itself is unchanged.

## Changes

- Carry configured upstream-event params and forward_upstream_execution_context into the expected rule contract.

- Require exactly one EventBridge input mode: Input, InputPath, or InputTransformer.

- Validate constant inputs by exact decoded-object equality, including scheduled run_options.

- Validate forwarded execution context structurally:

- exact detail-executionArn -> $.detail.executionArn map;

- exactly one unquoted placeholder;

- exact pipeline, trigger, upstream provenance, params, and dynamic ARN placement after safe sentinel substitution.

- Add positive coverage for the current core-enrollment production contract and fail-closed coverage for malformed, spoofed, extra, missing, or conflicting input forms.

## Breaking Changes

None. This changes only the read-only verifier and its tests. It does not alter pipeline configuration, state machines, EventBridge rules, registry state, schedules, activation, or warehouse objects.

## Test Plan

- python -m pytest pipelines/cdk/lambdas/tests -q — 475 passed.

- ruff==0.15.22 check pipelines — passed.

- ruff==0.15.22 format --check pipelines — 1,703 files already formatted.

- Independent focused re-review — 75 verifier tests passed; no blocking finding.

## Verification Artifact

Released production verifier evidence before this fix:

- 44 PASS / 1 FAIL / 8 INFO / 6 SKIP

- SHA-256 bdd46ffbe625e68d50e5466762f791936dad19f6cad0179533e28faf94076208

- Sole failure: the valid core-enrollment EventBridge InputTransformer was treated as missing constant input.

The corrected branch was then run with the same closed read-only AWS-action allowlist against current production:

- 45 PASS / 0 FAIL / 8 INFO / 6 SKIP

- SHA-256 5d411c28405bdaada58d669ed7e4ae4c5d2f5b2faa2884893dd5f2f42ed8bbcc

- The exact live transformer passed with trigger_type=EVENT, triggered_by=pipeline:sis-raw-sync, and upstream_execution_arn sourced only from $.detail.executionArn.

- Q48 remained disabled with zero post-guard runs, Lambda log activity, or Step Functions executions.

A final released-verifier rerun is still required after normal production promotion. No SURTR-781 preflight or Q48 DDL was performed.

<!-- 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>

## Summary

- add the canonical corrective spec for AERIE-1891

- pin current-state verification and the decided AERIE-1017 status-open contract

- require repository-wide removal of PR #1077's stale unresolved-policy wording

## Test plan

- [x] pnpm drones doctor --task tasks/aerie/aerie-1891-restore-status-open-contract.md

- [x] spec parses with recognized frontmatter and three review loops

<!-- 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>

<!-- CURSOR_AGENT_PR_BODY_BEGIN -->

## Summary

Adds a bounded same-agent retry for the case where a warm addresser round is terminal from the harness's point of view while the very next Agent.send on that same agent is briefly refused with agent_busy. Previously this refusal immediately ended the round as send_failed, relying entirely on AI-476's next-tick stranded-review sweep to recover the PR. Now the harness retries the exact same refused Agent.send call, on the exact same agent, a small bounded number of times before giving up — recovering the common short lifecycle-propagation-race window in-process, while leaving every AI-258 / AI-476 invariant untouched when the retry does exhaust.

## Why It's Needed

AI-258 measured that agent_busy most likely means the warm agent's previous run is terminal from the harness's side (run.wait() resolved) but not yet reaped agent-side — never evidence the agent is actually gone. AI-258 correctly forbids ever creating a competing agent on that signal, but the pre-AI-584 behavior treated the very first refusal as permanent, discarding a short recoverable window and pushing every occurrence onto AI-476's slower, tick-scoped sweep. This closes that gap without touching either of those pinned invariants.

## Changes

- New src/agent-busy-retry.ts — a small, pure extracted helper (no knowledge of reviews/findings/locks) owning the retry policy + clock/sleep plumbing:

- retryAgentSendOnBusy retries a caller-supplied attempt() closure while it fails with agent_busy, bounded by both an attempt cap and a wall-clock budget (whichever is hit first stops retrying).

- DEFAULT_AGENT_BUSY_RETRY_POLICY — named, logged defaults: maxAttempts: 4, maxElapsedMs: 90_000, backoffMs: 20_000.

- Never calls Agent.create / Agent.resume — it has no such capability at all; every attempt re-invokes the exact same closure the caller supplied.

- signal (AbortSignal) cancels an in-progress wait without ever issuing another attempt().

- Telemetry projection helpers (toAgentBusyRetryRoundOutcome, agentBusyRetryEventFields) mirror the existing PrBodyClobberTelemetryFields convention in pr-body.ts.

- src/addresser.ts — wraps *only* the sendToAgent(input.agent, prompt) call inside addressFindings with retryAgentSendOnBusy. Review fetch / finding extraction / prompt build all happen once, before this call, regardless of how many send attempts follow. On exhaustion (or an immediate non-agent_busy error, or cancellation), the same error is rethrown into the pre-existing catch block, so the send_failed outcome shape — and therefore isAddresserAgentBusyError / shouldRetryAddresserWithFreshAgent (AI-258) and the unadjudicatedPostedReview stamping path (AI-476) — is byte-identical to before. AddressOutcome's send_failed / completed variants gain an optional agentBusyRetry field, populated only when a retry sequence actually happened (refusal count > 0). Also adds stampAgentBusyRetryOnReceipt / stampAgentBusyRetryOnImplementerReceipt, mirroring the existing stampBodyClobberOn* helpers.

- src/events.ts / src/telemetry.ts — additive agentBusyPriorRunId / agentBusyPriorRunStatus / agentBusyPriorRunEndedAt / agentBusyFirstRefusalAt / agentBusyRefusalCount / agentBusyAcceptedAt / agentBusyDisposition fields on AddressCompletedEvent and DroneRunRecord, always omitted when no retry happened.

- src/runner.ts — threads best-effort priorRunStatus / priorRunEndedAt diagnostic context (the implementer's run for round 1, refreshed to the previous round's own address run for round 2+) into each addressFindings call; otherwise unchanged (fireAddressOnce/the round loop/the lock acquire-release boundary are untouched, so the lock invariant holds structurally — the retry happens fully inside the already-awaited addressFindings call).

- ARCHITECTURE.md + a docs/decisions/ entry documenting the new module and why the retry boundary is drawn where it is.

- Because src/address-turn.ts (standalone drones address, AI-476's own recovery sweep) and src/mercy-watcher.ts also call addressFindings, they get the same bounded busy-retry protection with zero extra wiring.

## Breaking Changes

None. Every new field is optional and additive; the default retry policy activates automatically, but the observable outcome on a round with zero agent_busy refusals is byte-identical to before (verified by the full existing suite staying green, including the AI-258 fresh-agent-refusal tests in runner.test.ts).

## Test Plan

- npx vitest run src/agent-busy-retry.test.ts — 18/18 passed. Pure-helper coverage: exact marker matching (positive/negative/non-Error), immediate accept, 2-refusals-then-accept, attempt-bound exhaustion, elapsed-bound exhaustion (independently of the attempt cap), unknown-error no-retry, busy-then-unrelated-error no-further-retry, cancellation before/during a wait, backoff clamped to the remaining elapsed budget, default-policy pin, and the telemetry→receipt/event projection helpers.

- npx vitest run src/addresser.test.ts -t "AI-584" — 4/4 passed. Addresser-level integration: (1) two agent_busy refusals + acceptance → exactly one accepted send on the original agent, fetchPostedReview called exactly once, agentBusyDisposition: "accepted-same-agent" on the event; (2) permanent refusal exhausts both bounds → send_failed with isAddresserAgentBusyError() === true preserved, agentBusyDisposition: "deferred-to-stranded-review-recovery", no acceptedAt; (3) an unknown/non-agent_busy error gets zero retries; (4) cancellation mid-wait prevents every later attempt.

- npx vitest run src/addresser.test.ts src/runner.test.ts src/runner-lifecycle.test.ts src/agent-busy-retry.test.ts — 375/375 passed (confirms the pre-existing AI-258 fresh-agent-refusal tests in runner.test.ts are unaffected).

- pnpm typecheck — clean (tsc --noEmit, exactOptionalPropertyTypes: true).

- pnpm test — full suite: vitest 172 files / 5855 tests passed, plus the Python unittest suite (scripts/test_*.py) green.

- pnpm build — clean (tsc).

## Verification Artifact

Terminal output from the commands above (this is a backend/CLI-only change — no GUI to screenshot):

$ npx vitest run src/agent-busy-retry.test.ts
Test Files  1 passed (1)
Tests  18 passed (18)
$ npx vitest run src/addresser.test.ts -t "AI-584"
Test Files  1 passed (1)
Tests  4 passed | 197 skipped (201)
$ npx vitest run src/addresser.test.ts src/runner.test.ts src/runner-lifecycle.test.ts src/agent-busy-retry.test.ts
Test Files  4 passed (4)
Tests  375 passed (375)
$ pnpm typecheck
> tsc --noEmit
(clean)
$ pnpm test
Test Files  172 passed (172)
Tests  5855 passed (5855)
(Python unittest suite: all green)
$ pnpm build
> tsc
(clean)

## Impact Estimate

Business value: Recovers short provider-side busy windows inside the original guarded lifecycle, reducing stranded-PR latency without weakening the single-writer safety boundary AI-258 established.

Pre-AI estimate: 2 points — extracted retry policy module, lifecycle/addresser integration at the exact send boundary, receipt/event telemetry, deterministic failure/cancellation test matrix, and review.

Closes AI-584.

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-2e5b0b8b-2822-4821-adb7-027c65d3469c?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-2e5b0b8b-2822-4821-adb7-027c65d3469c&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

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 -->

<!-- CURSOR_AGENT_PR_BODY_BEGIN -->

## Summary

Pin the Amplify deploy workflow to the repository's declared pnpm version.

## Why It's Needed

An unpinned global install drifted to a newer pnpm and made every frontend deployment from main fail before build (Deploy Frontend to AWS Amplify run 33018059424, ERR_PNPM_IGNORED_BUILDS for @clerk/shared@2.22.0 and esbuild@0.25.11).

## Changes

Update only the pnpm setup step and add version evidence:

       - name: Install pnpm
-        run: npm install -g pnpm
+        run: |
+          corepack enable
+          corepack prepare pnpm@9.15.9 --activate
+          pnpm --version

The unpinned npm install -g pnpm (which resolved to the latest pnpm, using the new store v11) is replaced with a deterministic activation of pnpm 9.15.9 via Corepack — the first-party toolchain manager bundled with Node.js 20, matching the repository root's "packageManager": "pnpm@9.15.9". pnpm --version logs the resolved version before dependency installation.

Node 20 setup, registry authentication, AWS/environment configuration, pnpm install --no-frozen-lockfile, the frontend build, and Amplify deployment steps are all unchanged.

## Breaking Changes

None.

## Test Plan

Validated the workflow YAML locally:

$ python3 -c "import yaml; d = yaml.safe_load(open('.github/workflows/ci_cd-frontend.yml')); print('YAML valid')"
YAML valid

The post-merge main run of Deploy Frontend to AWS Amplify is the end-to-end deployment verification.

## Verification Artifact

Workflow diff (only change in this PR):

diff --git a/.github/workflows/ci_cd-frontend.yml b/.github/workflows/ci_cd-frontend.yml
index 7ab06e018..4166e0ee3 100644
--- a/.github/workflows/ci_cd-frontend.yml
+++ b/.github/workflows/ci_cd-frontend.yml
@@ -35,7 +35,10 @@ jobs:
registry-url: 'https://registry.npmjs.org'
- name: Install pnpm
-        run: npm install -g pnpm
+        run: |
+          corepack enable
+          corepack prepare pnpm@9.15.9 --activate
+          pnpm --version
- name: Configure AWS Credentials
uses: aws-actions/configure-aws-credentials@v2

Local YAML validation command and result:

$ python3 -c "import yaml; d = yaml.safe_load(open('.github/workflows/ci_cd-frontend.yml')); print('YAML valid')"
YAML valid

## Impact Estimate

Business value: Restores Klair frontend deployments and removes the red default-branch gate blocking scheduled Klair drone work.

Pre-AI estimate: 0.5 points — diagnose toolchain drift, patch and validate one workflow, and observe the post-merge deployment.

<!-- drones:impact-actual:begin -->

Agent time: 4 m (implementer 1 m · reviewer 3 m · addresser 0 m)

Summed across phases. The 4 reviewer dimensions ran concurrently, so this exceeds elapsed wall-clock.

Efficiency vs. estimate: ~56.2× (0.5 points = 4 h of pre-AI effort)

<!-- drones:impact-actual:end -->

## Out of scope

- Product code or dependency upgrades.

- Broad build-script approvals.

- Changes to other workflows or deployment environments.

Closes KLAIR-3388

## Review Round Completeness

- outcome: complete

- round: 1

- dispatched: 4

- reported: 4

- missing: (none)

- cause: complete

- head: 92b6f637a0bde6fa61e9c99c8524e2dc7fd1ecdf

- run: fanout-3664-2026-08-26T22-33-24-715Z

- review: 5035619337

<!-- drones:round-completeness head=92b6f637a0bde6fa61e9c99c8524e2dc7fd1ecdf run=fanout-3664-2026-08-26T22-33-24-715Z -->

GitHub review #5035619337 was published and all dispatched review dimensions reported against the stamped head. Thread-count signals (unreplied=0) are meaningful for this head only — a later push invalidates the stamp. This section is a harness-shaped, head-bound self-report (not an authenticated out-of-band attestation).

<!-- drones:linear-id KLAIR-3388 -->

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-a51e6234-70b6-4bd4-a73e-01ce70558ac1?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-a51e6234-70b6-4bd4-a73e-01ce70558ac1&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

- 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

## 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

- Pin anthropic==0.117.1 in both src/requirements.txt and pyproject.toml for netsuite-unrealized-gains and netsuite-gl-detail (uv.lock regenerated to match).

- No application code changes.

## Why

Both pipelines' AI enrichment step has been failing 100% of rows since 2026-08-25/26 (issue #1564). The exception is caught and treated as non-fatal, so the run reports SUCCESS while the enriched table is never actually updated — a silent failure.

The real error from CloudWatch:

TypeError: Messages.create() got an unexpected keyword argument 'temperature'

Root cause: src/requirements.txt pinned only anthropic>=0.42.0 — an unbounded lower bound. CDK's Lambda bundling re-resolves this on every build, independent of the pyproject.toml/uv.lock versions used for local dev and tests, and it drifted to a version whose Messages.create() rejects the temperature kwarg both pipelines' enrichment code has always passed.

Fix: pin to anthropic==0.117.1 — not a guess. It's the exact version two currently-healthy sibling pipelines (aws-spend-insights, quickbooks-expense-ai-generation) already run successfully in production today with the identical temperature kwarg call pattern.

This PR does not address the underlying catch-and-continue-as-non-fatal pattern that let this ship silently for two days with no alert — that's tracked separately in issue #1564 for a follow-up.

## Business Value

Restores AI-enriched NetSuite unrealized-gains and GL-detail data that's been silently missing for 2 days, and closes the specific mechanism (unbounded dependency drift in Lambda-bundled requirements.txt) that caused it — the same class of pitfall this repo has hit before (documented in CLAUDE.md).

## Manual Effort Estimate

~1.5 hours (root-cause the actual CloudWatch exception vs the tracker's paraphrase, trace it to a dependency-pin drift rather than a code bug, find a proven-working reference version from healthy sibling pipelines, verify and regenerate locks/tests for both).

## Test plan

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

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

- [x] uv run ruff check .

Automated fix for openai-cost-pipeline — fix_class code_fix, scope tier draft.

Resolves https://github.com/AI-Builder-Team/Surtr/issues/1519

## What's broken

In run fbae58da-3b4a-41a4-a53c-4cb98ec4fdc6 the openai-cost-pipeline processed 27 of 28 BUs and inserted 1,407 rows, but Trilogy-CNU-University's cost data was dropped entirely after every retry hit a 429 ("BU Trilogy-CNU-University FAILED: all 1 API key(s) errored, 0 records fetched", and the terminal "HTTP error fetching cost report: 429 - ...You've exceeded the 30 request(s) every 1 minute(s) rate limit"). The run only downgraded to outcome=partial and did not page, so this billing BU's OpenAI spend is silently absent from staging_finance_ai_spend.raw_openai_cost_reports. The root cause is that pipelines/runners/openai-cost-pipeline/src/openai_client.py has no cross-request throttle: each BU fires an org-users call plus a cost call (each paginated) back-to-back across 28 BUs, so the aggregate outbound rate overruns OpenAI's 30 req/min org quota and a BU whose whole retry budget lands inside a saturated window is starved out with zero cost rows.

Root cause. The cost pipeline's only rate control is a per-page REQUEST_DELAY_SECONDS (0.5s) sleep inside each fetch loop and a per-BU OPENAI_BU_DELAY_SECONDS (2s) sleep in handler.py; neither caps the aggregate per-request rate across BUs. Because each BU makes at least two OpenAI Admin API calls (fetch_org_users + fetch_cost_report, each of which can paginate), 28 BUs processed sequentially sustain roughly one request per second — about double the observed "30 request(s) every 1 minute(s)" org quota — so the org sits at or over its rolling-window limit for long stretches. The existing exponential backoff plus the final-retry window floor in _retry_wait_seconds rescues most BUs, but Trilogy-CNU-University's five retries (2s, 4s, 8s, 16s, 65s) all landed back inside a still-saturated window and exhausted the budget, so _request_with_retry re-raised and the BU was recorded as failed with zero cost rows.

## What this PR changes

Port the already-reviewed-and-merged throttle from the sibling openai-usage-pipeline (PR #1301): add a process-wide _TokenBucket to pipelines/runners/openai-cost-pipeline/src/openai_client.py and call _rate_limiter.acquire() before every request inside _request_with_retry, governed by an env-overridable OPENAI_MAX_REQUESTS_PER_MINUTE (default 30) so the sustained request rate — org-users calls, cost calls, and retries alike — stays under the org quota. Declare OPENAI_MAX_REQUESTS_PER_MINUTE in pipeline.json's environment block and add a unit test asserting the limiter blocks once burst capacity is spent, mirroring the usage pipeline's implementation. This keeps the change confined to the pipeline's own directory (Tier A) and reuses a pattern a human already reviewed, rather than inventing a new compensating-re-fetch Lambda as the observer suggested.

Why this fixes it. This is a code-level gap confined to Tier A (pipelines/runners/openai-cost-pipeline/): the client fires more requests per minute than the org quota allows because it lacks the shared token bucket its sibling openai-usage-pipeline already carries, and the visible 429 hides a silent cost-data completeness failure (Trilogy-CNU-University's spend is entirely missing while the run reports only partial). Capping the aggregate outbound rate at the source prevents any single BU from being starved into all-retries-exhausted, which is the correct blast radius — smaller than a new retry Lambda and larger than a mere backoff tweak, since the prior backoff-only fix (PR #1299) demonstrably did not stop this recurrence. The change ports proven code (the _TokenBucket in openai-usage-pipeline/src/openai_client.py), adds one env var to the pipeline's own pipeline.json, and ships with a test, so it is a complete code_fix rather than a config nudge.

Follow-up fix 1 (commit 06caccf6). The throttle change above initially broke its own test suite: the new process-wide _rate_limiter singleton leaked real time.sleep calls into two pre-existing tests (test_honors_retry_after_header, test_final_retry_wait_outlasts_rate_limit_window) that mock time.sleep to assert on retry-backoff timing, and its token balance persisted across the whole test session, adding real wall-clock delay to unrelated tests. Added an autouse _disable_rate_limiter fixture in tests/conftest.py that resets the limiter to a disabled bucket (rate_per_minute=0) before every test — mirroring the existing _stub_secondary_side_effects autouse pattern in the same file. TestTokenBucket's own tests are unaffected since they construct their own _TokenBucket instances directly.

Follow-up fix 2 (commit 72967f5e). Per mercy's review: the bucket's default capacity = max(rate_per_minute, 1.0) (i.e. 30) permitted an instant startup burst of 30 requests, then let more through every 2s while OpenAI's *rolling* 60-second window still contained that initial burst — so the limiter itself could still trip 429s. Since this pipeline cold-starts fresh every run, that warm-up overlap spans the whole run, not just a one-time blip. Defaulted capacity to 1 instead, forcing strictly even spacing (one request every 60/rate seconds), which never lets more than rate requests land in any trailing 60-second window. Updated TestTokenBucket.test_paces_burst_to_sustained_rate (renamed test_paces_evenly_with_no_burst) to assert the new even-spacing behavior instead of codifying the burst.

### Files changed

 .../runners/openai-cost-pipeline/pipeline.json     |  3 +-
.../openai-cost-pipeline/src/openai_client.py      | 66 +++++++++++++++++++
.../tests/conftest.py                              | 15 +++++
.../tests/test_openai_client.py                    | 77 ++++++++++++++++++++++
4 files changed, 160 insertions(+), 1 deletion(-)

(plus the two follow-up commits above, touching openai_client.py and test_openai_client.py again)

## Verification

### pytest (pipelines/runners/openai-cost-pipeline/tests) — exit 0, re-run at 72967f5e

tests/test_handler.py .......................                            [ 14%]
tests/test_openai_client.py ............................................ [ 42%]
..                                                                       [ 43%]
tests/test_redshift_handler.py ......................................... [ 70%]
............                                                             [ 77%]
tests/test_secrets.py ...........                                        [ 84%]
tests/test_write_modes.py ........................                       [100%]
============================= 157 passed in 13.56s =============================

ruff check also clean on the changed files. All CI checks green on this PR.

<details>

<summary>Run metadata</summary>

| Field | Value |

| --- | --- |

| Pipeline | openai-cost-pipeline |

| Failing run (original incident) | fbae58da-3b4a-41a4-a53c-4cb98ec4fdc6 |

| Occurrence | 1 (times this exact failure signature has been seen) |

| Signature | 8e5d290a62d88977f249cbd990ecda02b4964584be2a2047aa3ae00f6343f24c |

| Verify | passing (as of 72967f5e) |

</details>

---

🤖 Opened by heimdall. mercy reviews this PR automatically; heimdall revises on REQUEST_CHANGES (bounded rounds). Tier-auto PRs may auto-merge on mercy approval when the consumer enables it; everything else waits for a human. Mention heimdall in a comment to direct it, or add the manual-dev label to take the PR over and stop it entirely.

## 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

- Render REBL3 projected opening dates as timezone-stable calendar days

- Add regression coverage for Phase 1 and Phase 2 dates

## Why

The Real Estate detail page parsed date-only REBL3 values as UTC instants. Users west of UTC therefore saw projected opening dates one day early, while the Agent and Diligence surfaces showed the canonical dates.

## Business Value

Operations users see the correct projected opening day consistently across Real Estate, Diligence, and Agent workflows.

## Test plan

- [x] Targeted WorkflowStatusPanel tests

- [x] Chat typecheck

- [x] Biome check for changed files

- [x] Full Chat suite: 9,612 passed; two unrelated existing timing/date flakes failed

## Summary

- Follow-up to #3665, found during post-deploy live verification (a blind agent probe re-answering the original Q22 question against the deployed guidance).

- The 62700 note identified account 62700 Other Expenses:CAPEX partly via account_category_code = 'new_campus_capex'. That category code turns out to be shared with a second, unrelated, still-active account: 62101 Other Expenses:Depreciation/Amortization-Renovation/Furnishings (268 postings, $4.86M net, running 2021-03-01 through 2026-07-31 — nothing to do with Finance's 62700 decision).

- The verification probe filtered by category code instead of account name, pulled in 62101's ongoing activity, and incorrectly flagged $4.86M of normal 62101 postings as a "new posting into a closed account" anomaly requiring Finance review. It also explains a small ~7-line/$1,250 drift the probe separately noted as "immaterial" — those were stray 62101 postings from 2021 leaking into what should have been a pure 62700 count.

- Fix: identify 62700 by account_name = '62700 Other Expenses:CAPEX' alone, which has no such collision, and drop the category-code reference from the note.

## Verification

Confirmed live before and after this fix:

- account_name ILIKE '62700%', excluding Allocation legs, transaction_date > 2024-05-31 → 0 rows (62700 genuinely closed, as the guidance states).

- account_category_code = 'new_campus_capex' resolves to two distinct account_name values (62700 and 62101) — confirming the collision this PR removes.

## 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)

## 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)

## Summary

- Add canonical pipeline and run identities to QuickBooks ECS result envelopes.

- Publish structured failure context before re-raising application failures.

- Preserve the original application exception when diagnostic publication itself fails.

## Why

Release PR #1561 combines the QuickBooks ECS migration with a hardened failure finalizer that rejects side-channel envelopes without matching pipeline_id and run_id. The QuickBooks producer omitted those fields and did not publish any result when the handler raised, so its structured failure diagnostics could not reach the finalizer.

## Business Value

QuickBooks ECS failures retain their actionable error type and message in Surtr run records and alerts while orchestration remains visibly failed and the original exception remains authoritative.

## Test plan

- [x] QuickBooks runner suite: 72 passed

- [x] Failure-finalizer suite: 45 passed

- [x] Ruff check and format verification

- [x] git diff --check

Addresses the blocking Mercy finding on #1561.

## Summary

- Hide both Summer Experience columns from the Admissions Pipeline dashboard

- Exclude the unreliable measures from Leads totals, summary details, sorting, search results, and CSV exports

- Preserve the underlying HubSpot ingestion and contract for easy restoration

## Why

The HubSpot data backing the Summer Experience measures is currently inaccurate and is causing confusion for dashboard users. Keeping those figures visible also contaminates the displayed Leads total and exported data.

## Business Value

Admissions users see a smaller, trustworthy Leads view while the upstream data is corrected, without requiring a destructive data or contract change.

## Test plan

- [x] Pipeline derivation tests (8/8)

- [x] Biome on all four changed files

- [x] Chat TypeScript pre-commit validation

- [x] git diff --check

## Summary

- Trigger the Core enrollment publisher after successful SIS raw-sync executions

- Resolve and verify the exact upstream execution run ID before warehouse publication

- Keep manual execution held while preserving existing freshness and reconciliation gates

## Why

The SIS source continued publishing successfully, but core_education.fct_enrollment had no recurring trigger after its one-time cutover. Its refreshed_at watermark therefore remained on August 11 even as newer accepted SIS publications became available.

## Business Value

Enrollment consumers receive current SIS-backed state after each successful source publication without introducing a latest-run race or weakening the existing fail-closed publication contract.

## Test plan

- [x] 42 focused Python tests

- [x] Ruff check and format verification

- [x] 622 CDK schema, construct, and real-pipeline configuration tests

- [x] CDK TypeScript build

- [ ] Deploy pipelines and verify the production EventBridge rule is enabled

- [ ] Allow the next successful SIS execution or perform an explicitly approved catch-up execution, then verify the pipeline run and fct_enrollment watermark

## Summary

- Accept 25 reviewed GuidePlatform fields across audio_recordings, behavioral_events, daily_notes, and shout_outs

- Persist bounded, run-bound schema-drift diagnostics in failed pipeline runs

- Synchronize the Guide roster consumer contract and add fail-closed ACL preflight for clean-view recreation

## Why

GuidePlatform added columns outside the checked raw-sync contract, so the pipeline correctly failed before extraction or publication. Six more fields landed after the original PR head, leaving the first repair stale before deployment. The scheduled sync has failed since August 21 while retaining the August 20 publication.

The existing Step Functions failure path also hid the actionable drift inside ECS logs. This change preserves structured diagnostics without trusting mismatched or oversized side-channel objects, and it prevents the required view recreation from silently discarding non-writer grants.

## Business Value

Restores the raw-sync contract to the current reviewed source shape while preserving atomic publication and the last known-good snapshot on future drift. Operators receive an actionable failure diagnosis and a safer, repeatable rollout path instead of another opaque schema incident.

## Test plan

- [x] Live generate_contract.py --check at head fb4217f6

- [x] GuidePlatform raw sync: 77 tests, Ruff, format

- [x] Guide roster consumer: 66 tests passed, 5 environment-gated integration tests skipped; changed files pass Ruff/format

- [x] Failed-run finalizer: 45 tests, Ruff, format

- [x] CDK TypeScript build

- [x] Generated DDL dry run: 355 statements with four atomic recreation markers

- [x] Live read-only ACL preflight: only the configured writer has grants on the four affected views

- [ ] Docker-dependent CDK Jest locally blocked because Docker Desktop is unavailable; hosted CI must run it

Production recovery remains a separate gate after merge: transactionally recreate the four affected clean views, deploy the runner/finalizer, then start a fresh extraction and verify source, immutable manifest, raw, clean, ledger, and downstream evidence. This PR does not apply warehouse DDL, deploy production, or start a pipeline run.

## 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

- 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

- Read Google Sheets strikethrough metadata for school-calendar rows

- Select a struck-through duplicate only when exactly one complete, unstruck replacement exists

- Fail closed and degrade the audit for mixed, incomplete, multi-active, or all-deprecated duplicate groups

## Why

The Nashville calendar sheet contains both an active Calendar A row and a struck-through deprecated Calendar B row. The sync could not see formatting, so both rows claimed the same site and the existing Calendar B value remained visible in Aerie.

## Business Value

School calendar assignments follow the source sheet's human deprecation signal while retaining fail-closed behavior when formatting does not unambiguously identify an active row.

## Test plan

- [x] 80 focused parser, sync, Sheets client, contracts, worker, and Convex audit tests

- [x] Full Sync suite: 74 files / 1,147 tests

- [x] Sync, contracts, and Chat TypeScript checks

- [x] Architecture boundary, Biome, and diff checks

- [x] Read-only live-sheet validation using the worker configuration: Nashville row 16 emitted as complete Calendar A; fully struck row 36 skipped as deprecatedFormatting

- [x] Seven-lane adversarial review plus focused follow-up review

## 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.

<!-- CURSOR_AGENT_PR_BODY_BEGIN -->

## Summary

Replaces the stringly Board Doc chat SSE contract ({ event: string, data: unknown } on the frontend, Callable[[str, dict[str, Any]], None] on the backend) with a typed discriminated union / TypedDict contract on both sides, for the same four wire-compatible events: delta, status, done, error.

## Why it's needed

Frontend/backend chat-stream drift (a renamed key, a new required field, a typo) previously surfaced only at runtime as a silently dropped event. This makes that class of drift fail at pnpm tsc / pyright / focused tests instead.

## Changes

Backend (klair-api/budget_bot/board_doc/chat_stream_events.py, new file):

- ChatDeltaPayload / ChatStatusPayload / ChatDonePayload / ChatErrorPayload TypedDicts pin exactly the keys each event has always carried.

- ChatStreamEmitter is an overloaded Protocol typing handle_chat's emit callable to the two events it actually produces (delta / status).

- wizard_orchestrator.handle_chat's emit param: Callable[[str, dict[str, Any]], None] | None → ChatStreamEmitter | None.

- board_doc_router.wizard_chat_stream builds done/error as ChatDonePayload/ChatErrorPayload literals (fields copied from WizardStepResponse, not .model_dump()) instead of hand-rolled dicts; its internal queue/emit closure is typed against the union instead of a bare dict.

- _sse_event now takes Mapping[str, Any] (read-only) so a TypedDict payload passes through without a cast.

Frontend (klair-client/src/services/boardDocApi.ts):

- New ChatStreamEvent discriminated union (ChatDeltaEvent / ChatStatusEvent / ChatDoneEvent / ChatErrorEvent) mirroring the backend union one-to-one.

- parseSseFrame now validates a frame into ChatStreamEvent and returns a discriminated ParsedSseFrame result ({ ok: true, event } | { ok: false, error }) instead of the old { event, data, parseError } tuple. Every failure mode — missing event: line, malformed data: JSON, an event name outside the four variants, or a well-formed-JSON payload that fails its event's shape check — is now an explicit ChatStreamParseFailureReason.

- streamChatMessage's dispatch is an exhaustive switch over ChatStreamEvent with an assertNeverChatStreamEvent compile-time guard, and routes every parse failure through the existing onError callback (previously several of these were silently dropped).

- parseDoneResponse now delegates to the same non-throwing validator the union's done branch uses — one source of truth for what makes a done payload valid.

## Breaking changes

None on the wire — event names and serialized payload keys are byte-identical to before this refactor. ChatStreamCallbacks (the public callback shape consumed by useBoardDocWizard) is unchanged except onStatus's phase field is now typed as required string instead of optional (the backend has always sent it).

parseSseFrame's *return shape* changes ({ event, data, parseError } → { ok, event | error }) — it has exactly one internal consumer (streamChatMessage) plus its own spec file, both updated in this PR.

## Test plan

Backend (from klair-api/):

- uv run ruff format budget_bot/board_doc/chat_stream_events.py budget_bot/board_doc/wizard_orchestrator.py routers/board_doc_router.py — no changes needed.

- uv run ruff check budget_bot/board_doc/chat_stream_events.py budget_bot/board_doc/wizard_orchestrator.py routers/board_doc_router.py — all checks passed.

- uv run pyright budget_bot/board_doc/chat_stream_events.py budget_bot/board_doc/wizard_orchestrator.py routers/board_doc_router.py — 0 errors, 1 warning (pre-existing, unrelated to this change — confirmed via git stash).

- uv run pytest tests/board_doc/test_chat_streaming.py -v — 10 passed (7 pre-existing + 3 new TestChatStreamEventPayloadShapes tests pinning TypedDict keys against both the type definitions and live wire responses).

- uv run pytest tests/board_doc/ (full feature suite) — 3567 passed, 2 deselected (integration/eval, excluded by default addopts per repo convention).

Frontend (from klair-client/):

- pnpm vitest run src/services/__tests__/boardDocApi.streamChat.spec.ts — 24 passed (11 pre-existing behaviors preserved + new coverage for each ChatStreamEvent variant and all four parse-failure dispositions: missing_event, malformed_json, unknown_event, malformed_payload, including their propagation through streamChatMessage's onError).

- pnpm vitest run src/screens/BoardDoc/ src/services/__tests__/boardDocApi — 73 files, 819 passed.

- pnpm test:run (full suite) — 648 files, 6689 passed, 16 skipped (pre-existing, unrelated).

- pnpm tsc -p tsconfig.app.json --noEmit — clean.

- pnpm eslint src/services/boardDocApi.ts src/services/__tests__/boardDocApi.streamChat.spec.ts --max-warnings 0 — clean.

- pnpm lint:pr — clean (matches CI).

- pnpm prettier --check → --write on both changed files (now formatted).

- pnpm build — succeeds.

Closes KLAIR-2849

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-742a8ffa-8438-462f-a8d5-06aa3ffd7780?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-742a8ffa-8438-462f-a8d5-06aa3ffd7780&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

Fix chat responses that render Markdown tables so document links such as

"View PDF" and "Open in Drive" remain clickable instead of being flattened to

plain text. This restores direct access to referenced permit documents while

preserving the existing searchable, sortable, exportable table interface.

### Changes

- chat/components/markdown-components.tsx — preserve inline table-link

metadata while extracting Markdown table cells, accepting only http and

https URLs.

- chat/components/data-table.tsx — render structured cell links in both

desktop tables and mobile cards, while continuing to use plain cell text for

sorting, filtering, totals, row keys, and CSV export.

- chat/components/__tests__/data-table.test.tsx — cover external-link

rendering, surrounding text, and the mobile card layout.

- chat/components/__tests__/markdown-components.test.tsx — verify safe

URLs are retained and unsafe URL schemes are not rendered as links.

### Design Decisions

The Markdown renderer passes structured text/link parts to DataTable rather

than injecting arbitrary HTML. Links open in a new tab with noopener noreferrer,

and the parser rejects non-HTTP(S) schemes.

## Business value

Users can open permit PDFs and other source documents directly from AI chat

results, avoiding broken document workflows and manual link copying.

## Estimated manual effort

1–2 focused engineering hours.

## Test Plan

- [x] Focused Vitest suite for data-table, Markdown components, and message

Markdown rendering (38 tests).

- [x] Biome check for all changed component and test files.

- [x] pnpm --dir chat typecheck.

- [x] Pre-commit Biome and chat typecheck hooks.

- [ ] Open a Markdown-table document link in the deployed chat UI.

<!-- CURSOR_AGENT_PR_BODY_BEGIN -->

### 1. Summary

- scripts/box-bootstrap.sh is now the sole checkout-synchronization authority for the hosted orchestrator, and is the systemd unit's only ExecStart (no more separate ExecStartPre).

- It acquires a host-level flock (held open across exec) before touching git, verifies user/checkout ownership, requires branch main + a clean worktree, fetches main via an explicit main:refs/remotes/origin/main refspec, refuses divergence, verifies HEAD == refs/remotes/origin/main byte-for-byte, conditionally runs pnpm install --frozen-lockfile, then execs scripts/dispatch-poll-wrapper.sh straight out of the freshly-verified checkout.

- Every refusal writes a typed terminal preflight-failed/lock-contended dispatch-tick-outcome and exits non-zero — it never silently hands off on failure the way the old best-effort updater did.

- scripts/dispatch-poll-wrapper.sh no longer performs its own fetch/merge/install; it trusts the checkout it was exec'd into.

- scripts/box-install-bootstrap.sh now stages → bash -n → sha256 → atomic-renames only the bootstrap (never the wrapper, which is no longer installed anywhere else), writes a checksum manifest, and fails loudly on systemd-unit topology drift.

- scripts/box-update-wrapper.sh is retired outright (refuses to run) — its entire job no longer exists.

### 2. Why it's needed

The 2026-08-24/25 scheduled turns failed live because the pre-tick updater and the wrapper each independently synced the checkout with different failure semantics: the updater always exited 0 (even after a failed fetch/merge/install), and the wrapper's git fetch origin main only updates FETCH_HEAD — not refs/remotes/origin/main — when the remote's own fetch refspec doesn't cover it, so a subsequent git merge --ff-only origin/main can merge a stale ref. Recovering required an operator to manually replace the wrapper, force a main:refs/remotes/origin/main fetch, fast-forward, reinstall dependencies, and hotfix the source before the noon tick. A healthy scheduled turn must never depend on that race.

### 3. Changes

- New: scripts/record-preflight-failed-tick.mjs, scripts/record-lock-contended-tick.mjs — Node-stdlib-only tick-outcome writers extending the existing AI-218/227/236 fallback family (record-started-tick.mjs, record-guard-skipped-tick.mjs, record-abnormal-exit-tick.mjs), pinned against the same TS builders in src/dispatch-tick-outcome.ts / src/heartbeat.ts.

- Rewrite: scripts/box-bootstrap.sh — lock → ownership → branch/clean → explicit-refspec fetch → divergence refusal/ff-only → byte-for-byte HEAD verification → conditional install → self-update staging → exec the canonical wrapper.

- Rewrite: scripts/box-install-bootstrap.sh — installs only the bootstrap (stage/syntax-check/hash/atomic-rename + sha256 manifest) and asserts/fails-loud on the systemd unit's ExecStart/User topology.

- Retired: scripts/box-update-wrapper.sh — now a hard-refusing stub (exit 1) rather than a no-op, so it cannot become a silent second activation path.

- Trimmed: scripts/dispatch-poll-wrapper.sh — removed its own branch check / git fetch / git merge --ff-only / pnpm install block; everything else (pgrep concurrency guard, AI-210/229/230/231 supply phases, AI-533 batch-profile fire, AI-211/218/226/227/232/236 heartbeat/turn-report emission) is unchanged.

- Tests: new src/box-bootstrap.test.ts (Linux-only fixture-repo + real flock/git integration coverage, explicitly skipIf'd elsewhere with a stated reason); new deep-equal + redaction-fixture coverage for the two new .mjs writers in src/dispatch-tick-outcome.test.ts; updated wrapper-ordering pin in src/heartbeat.test.ts and docstrings in src/dispatch-poll-wrapper-content.test.ts.

- Docs: rewrote the "Hosted orchestrator" section of guidelines/dispatch-scheduled-runner.md — the new topology, fail-closed dispositions, checksum/drift inspection commands, and a non-destructive repair runbook per refusal kind; fixed every other now-stale "installed copy" reference in the file.

- Decisions log: docs/decisions/20260826T173809.724Z-ai-574-*.md records the concrete implementation mechanism (flock-across-exec, checksum-verified install, retiring box-update-wrapper.sh) — a prior, higher-level AI-574 decision entry already existed from queue-framing and is left standing per the append-only convention.

Contract surface affected:

- scripts/dispatch-poll-wrapper.sh: no longer performs any git sync — callers that invoke it standalone (not via box-bootstrap.sh) now inherit whatever the checkout already looks like, same as any other manual pnpm drones <verb> call. All production callers (the systemd unit, via box-bootstrap.sh's exec) already sync first.

- scripts/box-update-wrapper.sh: now always exits 1. No production caller invokes it (it was an operator-run manual tool); this PR's own test (src/box-bootstrap.test.ts) pins the refusal.

### 4. Breaking changes

- The systemd unit's topology changes: ExecStartPre=.../box-bootstrap.sh + ExecStart=<installed wrapper> becomes a single ExecStart=/bin/bash -lc '/home/ubuntu/box-bootstrap.sh'. Migration: re-run scripts/box-install-bootstrap.sh on the box, which rewrites the unit (with a timestamped backup) and asserts the new topology.

- /home/ubuntu/dispatch-poll-wrapper.sh (the old installed wrapper copy) is no longer read or updated by anything; it can be left in place harmlessly or removed by the operator.

- scripts/box-update-wrapper.sh now always exits 1 instead of performing its old copy — any external tooling/runbook that still shells out to it needs to stop; this PR updates the one runbook in this repo (guidelines/dispatch-scheduled-runner.md) that referenced it.

### 5. Test plan

- [x] bash -n scripts/box-bootstrap.sh scripts/box-install-bootstrap.sh scripts/box-update-wrapper.sh scripts/dispatch-poll-wrapper.sh → all four clean

- [x] pnpm typecheck → clean (tsc --noEmit, no errors)

- [x] npx vitest run src/box-bootstrap.test.ts src/dispatch-tick-outcome.test.ts src/dispatch-tick-signal.test.ts src/interrupted-fire-orphan.test.ts → 4 files, 184 tests passed

- [x] npx vitest run src/heartbeat.test.ts src/dispatch-poll-wrapper-content.test.ts → 2 files, 108 tests passed (includes the updated wrapper-ordering pin)

- [x] pnpm test (full suite: vitest + Python unittest) → 171 test files / 5790 vitest tests passed, 717 Python tests passed (19 skipped), exit 0

- [x] Manually reproduced the exact 2026-08-24/25 regression shape in a disposable fixture (remote.origin.fetch unset) and confirmed a bare git fetch origin main leaves refs/remotes/origin/main stale while box-bootstrap.sh's explicit-refspec fetch correctly repairs it (src/box-bootstrap.test.ts's REGRESSION test)

### 6. Verification artifact

src/box-bootstrap.test.ts exercises the real scripts/box-bootstrap.sh against disposable local git fixtures (no network) — 17 passing cases covering: fast-forward to the exact fetched SHA + exec-handoff, conditional pnpm install (no-op / unrelated-change / lockfile-change), dirty worktree, wrong branch, divergence, running-user mismatch, checkout-ownership mismatch (via a shimmed stat), fetch failure, missing/non-executable/exec-failing wrapper, concurrent-invocation lock contention, the FETCH_HEAD-staleness regression, and non-destructive self-update staging. Representative excerpt (full run in the Test plan above):

✓ fast-forwards a behind-main checkout to the exact fetched remote SHA, then execs the canonical wrapper from the updated checkout
✓ refuses local divergence (fast-forward impossible) rather than reset/force, and records a typed preflight-failed outcome
✓ two concurrent invocations cannot both synchronize or fire -- the contended one refuses without touching the checkout
✓ REGRESSION: a bare git fetch origin main (no explicit refspec) leaves refs/remotes/origin/main stale when the remote's fetch refspec is unset -- box-bootstrap.sh's explicit refspec fetch is unaffected by, and repairs, that staleness

Backend-only orchestration change — no frontend surface, so no browser-verify section.

### 7. Impact estimate

Business value: Prevents stale code, stale task specs, and stale batch profiles from silently governing unattended dispatch. It removes a recurring source of empty/failed ticks and the high-risk need for last-minute manual box repair.

Pre-AI estimate: 3 points — existing-shell refactor, atomic installer and heartbeat integration, local Git-fixture failure matrix, systemd/runbook updates, and review.

Closes AI-574

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-193a1dbe-e4f5-49a9-a76e-c14a68a2fd00?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-193a1dbe-e4f5-49a9-a76e-c14a68a2fd00&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 -->

### 1. Summary

- Three tests provoked a durable-write failure via a chmod permission trick (src/explore.test.ts, src/harvest-followups.test.ts, src/pr-number-checkpoint.test.ts), which is non-deterministic: it's a no-op for the directory-owning process when running as root (the common case in CI containers) and behaves differently on Windows.

- Each of the three persistence boundaries now takes a narrow, optional injected writer — defaulting to the existing real filesystem operation — so a test can reject an exact write instead of chmod'ing a directory read-only.

- Rewrote the three affected tests to inject the exact failure and assert each caller's existing warning, accounting, and return disposition; added one supporting regression test in pr-number-checkpoint.test.ts and strengthened the harvest checkpoint test to assert the prior durable checkpoint survives untouched.

### 2. Why it's needed

AI-573 recorded this exact chmod-based failure family as a blocker for Windows CI: the permission trick used to simulate a write failure doesn't reliably fail on Windows, and (separately) is a no-op for a root-owned process on Linux CI runners. Without a deterministic seam, these three tests either silently stop exercising the failure path or flake, hiding real lost-write behaviour that the harness's degradation accounting exists to catch.

### 3. Changes

- src/pr-number-checkpoint.ts — appendPrNumberCheckpoint gains an optional opts.writeFile (new exported CheckpointWriteFn type), defaulting to a new defaultCheckpointWriter (writeFile(path, contents, "utf8"), the pre-existing behaviour unchanged).

- src/harvest-followups.ts — appendHarvestCheckpoint threads an optional opts.writeFile through to the checkpoint helper above; RunHarvestFollowupsInput gains an optional checkpointWriteFile that runHarvestFollowups's recordCheckpoint passes through. Production omits it, so the real writer is always used unattended.

- src/explore.ts — RunExplorationTickInput gains an optional persistProposal (same signature as explore-ledger.ts's real persistProposal, imported here as persistProposalToLedger to avoid a name collision); the emit loop calls input.persistProposal ?? persistProposalToLedger.

- Tests: replaced the three chmod-based setups with direct injection of a rejecting writer/persist function; removed the now-unused chmod/mkdir imports in the two test files that no longer need them.

- docs/decisions/ — new entry recording the pattern (mirrors the existing src/receipt-outbox.ts scanBacklog injection seam from a prior AI-270 address round, rather than inventing a new convention).

Contract surface affected:

* appendPrNumberCheckpoint(checkpointPath, prNumber, opts?): opts gains an optional writeFile field. Backward compatible — existing callers (src/retro.ts) pass no opts.writeFile and get the unchanged default.

* appendHarvestCheckpoint(checkpointPath, prNumber, opts?): new optional third parameter (previously took no opts). Backward compatible — no existing caller outside this PR passes a third argument.

* RunHarvestFollowupsInput / RunExplorationTickInput: each gains one new optional field. Backward compatible — every production call site (CLI, dispatcher, farm) omits the new field and gets the real filesystem behaviour.

### 4. Breaking changes

None. Every new parameter is optional and defaults to the pre-existing real filesystem operation; no production call site was changed.

### 5. Test plan

- [x] npx vitest run src/explore.test.ts → 81 passed

- [x] npx vitest run src/harvest-followups.test.ts src/pr-number-checkpoint.test.ts → 88 passed (12 + 76)

- [x] npx vitest run src/explore.test.ts src/harvest-followups.test.ts src/pr-number-checkpoint.test.ts (together) → 169 passed

- [x] pnpm typecheck → clean (tsc --noEmit, 0 errors)

- [x] pnpm test (full vitest + Python suite) → 170 vitest files / 5750 tests passed; Python unittest suite (scripts/test_*.py) → 717 tests, OK (skipped=19)

### 6. Verification artifact

Each rewritten test now injects the exact rejected write and asserts on the resulting WARN text / accounting, deterministically, with no filesystem permission state:

stderr | src/explore.test.ts > ... > degrades a persist failure (counts it, continues) rather than crashing mid-emit-loop
[drones:explore] WARN failed to persist proposal for ai-builder-team/trilogy-drones (contentKey=... title="Bug one"): EACCES: permission denied (injected)
[drones:explore] WARN failed to persist proposal for ai-builder-team/trilogy-drones (contentKey=... title="Bug two"): EACCES: permission denied (injected)
✓ src/explore.test.ts (81 tests)
stderr | src/harvest-followups.test.ts > accounting + no mutation > surfaces a checkpoint write failure on the outcome/summary and preserves the last durable checkpoint
[drones:harvest-followups] WARN could not update checkpoint /tmp/.../cp.txt: EACCES: permission denied (injected)
✓ src/harvest-followups.test.ts (76 tests)
✓ src/pr-number-checkpoint.test.ts (12 tests)
Test Files  3 passed (3)
Tests  169 passed (169)

Acceptance criteria checked against the diff:

- Explore proposal persistence failure increments skippedPersistFailed and the proposal never lands in the ledger (loadProposalLedger(dir) returns [] after the injected failure).

- Harvest checkpoint write failure is visible on the outcome/summary (checkpoint write failed, CHECKPOINT WRITE FAILED) and the new test asserts the prior sweep's durable checkpoint ("90\n") is unchanged — PR #100 is never acknowledged as harvested.

- PR-number checkpoint append failure returns { ok: false, error }, WARNs once, and the checkpoint file is never created (ENOENT on read) — added a companion test confirming the injected writer is never even called when the append is a no-op (PR already present).

### 7. Impact estimate

Business value: Makes advisory supply and checkpoint durability failures trustworthy on both supported platforms, enabling Windows CI without hiding real lost-write behavior.

Pre-AI estimate: 1.5 points — three bounded injection integrations, cross-platform regression tests, and review.

Closes AI-576

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-45e8a51b-a7b6-4c4c-868b-265782ccff1d?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-45e8a51b-a7b6-4c4c-868b-265782ccff1d&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

Clarifies the Admissions v2 dictionary and enablement documents so onCampus, startingFuture, yearStartTotal, and fillRatePct are unambiguously described as Aerie's own computed operational admissions measures at Program/school-year grain — not the authoritative enrolled-seat roster or student identity membership.

## Context

The AdmissionsProgramEnrollmentAggregate field catalog described onCampus as a live attendance count and fill-rate numerator without distinguishing it from school-year enrollment seats/roster authority, or routing roster questions to the registered SIS source. This is a served-contract wording fix only; no admissions formula, source, or algorithm changes.

## Changes

- chat/lib/public-api/v2/domains/admissions.ts: added shared SIS_ROSTER_AUTHORITY_BOUNDARY/SIS_ROSTER_ROUTE_AWAY constants; added traps on onCampus, startingFuture, yearStartTotal, and fillRatePct stating they are computed operational measures, not the authoritative SIS roster; updated the AdmissionsProgramEnrollmentAggregate object's aggregate field meaning; and added extraRouteAway/extraInterpretation on the read-program-enrollment-aggregates workflow that routes roster membership, "who is seated", and authoritative school-year enrollment census questions to the registered SIS source (by identity, not a hardcoded host), with an explicit "do not substitute this aggregate" instruction when that source is unavailable.

- chat/lib/public-api/v2/domains/admissions.test.ts: added tests pinning the field-level SIS-roster traps and pinning both directions on the workflow — an admissions aggregate question (fill rate, onCampus, capacity) stays on read-program-enrollment-aggregates, while a roster/"who is seated" question routes away to the registered SIS source, including the no-fallback-on-unavailable instruction.

## Test plan

- pnpm vitest run lib/public-api/v2/domains/admissions.test.ts lib/public-api/agent-context/projection.test.ts → 2 files, 33 tests passed.

- pnpm vitest run lib/public-api/v2/domains convex/publicApi/dss → 13 files, 63 tests passed (full domain-catalog + DSS surface regression).

- pnpm typecheck → passed (tsc --noEmit && tsc -p convex/tsconfig.json --noEmit).

- pnpm biome check lib/public-api/v2/domains/admissions.ts lib/public-api/v2/domains/admissions.test.ts → clean.

## Risk

Low: purely additive documentation/dictionary text and enablement routing guidance. No metric formula, endpoint payload, authorization, student-level data, or external DSS/SIS registry mutation changes.

## Out of scope

- Changing admissions formulas or backfilling source values.

- Adding student-level roster data to Aerie.

- Modifying the external DSS registry or SIS implementation.

- Resolving the unrelated campus-opening membership semantics tracked under AERIE-1017.

## Rollback

Revert this commit; it touches only dictionary/enablement text and its tests, so rollback carries no data or runtime risk.

Closes AERIE-1753

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-fab1ba6a-57f3-464a-a17a-d7d679930f42?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-fab1ba6a-57f3-464a-a17a-d7d679930f42&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

Documents schoolChain as a nullable, registry-backed assignment in the Portfolio v2 OpenAPI schema and the served agent-context dictionary, so readers can no longer treat a null value as a confirmed "no chain" classification.

## Context

AERIE-1133 removed the obsolete brand/schoolType fields and aligned maintained school-profile fields. schoolSizeClass is now always populated, but schoolChain remains nullable when no registry-backed assignment exists (chat/convex/migrations/schoolChainRegistry.ts). Without an explicit completeness contract, a reader filtering or grouping Portfolio sites by chain could silently drop sites whose registry assignment is simply missing, undercounting the portfolio.

## Changes

- chat/lib/public-api/v2/domains/portfolio.ts:

- OpenAPI PortfolioSiteProfile.schoolChain description now states the field is a registry-backed assignment, that null means "no current Aerie assignment" (not a confirmed no-chain classification), and that excluding null rows when filtering/grouping can undercount the portfolio.

- The served agent-context dictionary entry for portfolio.site.schoolChain mirrors the same semantics (meaning, nullMeaning, and three traps), and adds a code comment pointing operators at the existing schoolChainRegistry.verifySites gap-detection query for finding sites missing a registry assignment — without exposing that internal query to public readers.

- chat/lib/public-api/v2/domains/portfolio.test.ts: adds a focused contract test (pins schoolChain completeness semantics: nullable, registry-backed, undercount-safe) that pins the null semantics, the undercount warning, and the prohibition on name/slug/sibling-record inference across both the OpenAPI description and the dictionary field, and asserts they stay in parity.

## Testing

Ran from chat/:

- npx vitest run lib/public-api/v2/domains/portfolio.test.ts — 5 passed

- npx vitest run lib/public-api/v2/openapi.test.ts lib/public-api/agent-context/projection.test.ts convex/migrations/schoolChainRegistry.test.ts — 33 passed

- npx tsc --noEmit -p tsconfig.json — clean, no errors

- npx biome check lib/public-api/v2/domains/portfolio.ts lib/public-api/v2/domains/portfolio.test.ts — clean

Two unrelated pre-existing failures were observed and confirmed present on main without this change (a [REDACTED] string-redaction artifact of this sandbox unrelated to schoolChain): lib/public-api/compatibility/adapter.test.ts and convex/publicApi/v2/portfolioDomain.test.ts.

## Acceptance criteria

- [x] Served dictionary identifies schoolChain as nullable and registry-backed.

- [x] Field traps state null means no current Aerie assignment, not a confirmed "no chain" classification.

- [x] Traps warn that filtering/grouping by non-null chain values can undercount sites.

- [x] OpenAPI description and served dictionary use compatible semantics (asserted by the new test).

- [x] Operator guidance (code comment) points to the existing schoolChainRegistry.verifySites gap-detection path without exposing an internal mutation/query to public readers.

- [x] Contract test pins null semantics, undercount guidance, and the prohibition on name/slug/sibling-record inference.

## Out of scope

- No production rows, migration mappings, chain assignments, API payload shapes, or filter behavior were changed.

- No inference of chain membership from names, slugs, or sibling records was added.

- brand/schoolType were not reintroduced.

- Registry write behavior is untouched; verifySites remains internal-only.

## Risk

Low — this is a documentation-only change to description strings and dictionary metadata consumed by API docs and the agent-context feed. No runtime behavior, schema shape, or payload changed, confirmed by typecheck and the full focused test suite passing.

Closes AERIE-1164

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-a7fe6af7-b45a-414d-9c0e-a4012a2d67b9?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-a7fe6af7-b45a-414d-9c0e-a4012a2d67b9&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

- BenchmarkAggregateSupport (in _helpers.py) now carries three explicit, separately-documented list fields — missing_bu_rows, skipped_products, and partial_pass_labels — instead of forcing every consumer to reverse-engineer three different meanings out of one flat missing_categories list.

- missing_categories is retained as a validated compatibility mirror, always exactly [*missing_bu_rows, *skipped_products, *partial_pass_labels]; a single model_validator(mode="before") on the model is the one place that flattening rule lives, and it rejects any explicitly-passed missing_categories that disagrees with the typed fields.

- C3.7 (Sales & Marketing) — the only multi-category producer — now populates all three typed fields from its existing bu_missing / skipped_products / partial_pass_labels local state, on both the aggregate-pass and mixed-failing-plus-info paths.

- Every other C3.x producer (single-category) now passes skipped_products= explicitly instead of hand-rolling missing_categories=list(skipped_products); their missing_bu_rows / partial_pass_labels stay empty by default.

## Why It's Needed

Klair PR #3621 made C3.7 expose partial benchmark coverage, but BenchmarkAggregateSupport.missing_categories ended up mixing three unrelated concepts into one untyped string list: a missing business-unit category row (e.g. "Marketing"), a fully-skipped product column (e.g. "ProductA"), and a partial-pass display label (e.g. "ProductB (Sales missing)"). The only place this distinction lived was a comment describing a positional ordering convention — nothing in the Pydantic contract enforced it, and any future API/UI consumer would have had to pattern-match formatted strings to tell "a whole BU row is missing" apart from "a single product cell is missing" apart from "a product passed but only partially." This PR adds the typed separation before any frontend starts consuming the payload, while keeping the flattened field around so existing consumers don't break.

## Changes

- klair-api/budget_bot/board_doc/review_checks/_helpers.py

- BenchmarkAggregateSupport gains missing_bu_rows: list[str], skipped_products: list[str], and partial_pass_labels: list[str] (all Field(default_factory=list)), each documented with its exact structural meaning in the class docstring.

- Added _sync_missing_categories_mirror, a model_validator(mode="before") that derives missing_categories from the three typed fields when it's omitted, and raises ValidationError if an explicitly-passed missing_categories disagrees with the flattened typed-field order — the single shared mechanism that prevents the typed fields and the compatibility mirror from drifting apart.

- append_mixed_coverage_finding (shared by every C3.x check) now constructs BenchmarkAggregateSupport from missing_bu_rows=bu_missing, skipped_products=skipped_products, partial_pass_labels=partial_pass_labels instead of manually flattening them into missing_categories=[...].

- Contract surface — BenchmarkAggregateSupport and every producer's disposition:

- sales_marketing_benchmark.py (C3.7) — the only multi-category producer. Its aggregate all-pass branch now passes missing_bu_rows=bu_missing, skipped_products=skipped_products, partial_pass_labels=partial_pass_labels (previously hand-flattened into missing_categories=[...]); its mixed-failing branch already routed through the now-updated append_mixed_coverage_finding. Verdict/severity math is untouched.

- engineering_product_benchmark.py (C3.3), saas_it_ops_benchmark.py (C3.4), edge_benchmark.py (C3.5), support_benchmark.py (C3.6), hard_cogs_benchmark.py (C3.8), g_and_a_benchmark.py (C3.9) — single-category producers. Each aggregate-pass call site changed from missing_categories=list(skipped_products) (or, for edge_benchmark.py, list(not_evaluated_products)) to skipped_products=list(...); missing_bu_rows and partial_pass_labels stay at their empty defaults. No verdict/severity/behavior change.

- margin_per_product_benchmark.py (C3.1, per-product-target check with benchmark_pct=None) — same disposition as the single-category siblings above; the benchmark_pct=None contract is untouched.

- klair-api/tests/board_doc/test_sales_marketing_benchmark.py

- New TestBenchmarkAggregateSupportTypedCoverageFields class pinning the typed fields, the mirror-derivation behavior, the drift-rejection validator (including wrong-order rejection), frozen=True, extra="forbid", and independent default_factory=list defaults across instances.

- New combined all-pass regression (test_aggregate_pass_combines_bu_missing_skipped_and_partial_pass_typed_fields) exercising a single payload with a missing BU row (Marketing absent), a fully skipped product, and partial-pass products in one aggregate pass finding — asserts each typed bucket individually plus the flattened missing_categories mirror in the pinned BU-row → skipped-product → partial-pass order.

## Breaking Changes

None. missing_categories (both the field and its pinned flattening order) is unchanged for existing consumers. The new fields are additive; no producer relies on undeclared extra keys, and no shared mutable defaults were introduced (Field(default_factory=list) throughout, verified independent-instance in the new tests).

## Test Plan

Executed from klair-api/:

- uv run pytest tests/board_doc/test_sales_marketing_benchmark.py -q → 52 passed (42 pre-existing + 10 new).

- uv run pytest tests/board_doc/ -q -k "benchmark" → 290 passed, 3286 deselected (covers every touched C3.x sibling check's own test file; 280 pre-existing + 10 new).

- uv run pytest tests/board_doc/ -q (full board_doc suite, default marker exclusions per repo convention — no integration/eval/allow_network markers touched by this change) → 3574 passed, 2 deselected.

- uvx ruff@0.15.22 format --check <9 touched files> → all already formatted.

- uvx ruff@0.15.22 check <9 touched files> → all checks passed.

- uv run pyright <8 touched review_checks files> → 0 errors, 0 warnings, 0 informations.

## Verification Artifact

No UI/visual surface changed (backend Pydantic contract + producer call sites only; no frontend migration is in scope). Verification is the test/lint/type-check command output above — reproduced verbatim in this PR body rather than as a screenshot/video artifact, since there is nothing GUI-visible to capture.

## Impact Estimate

Business value: Prevents API and UI consumers from silently conflating a missing business-unit source row with a missing product cell, preserving accurate explanations of partial C3.x benchmark coverage once a frontend starts reading the typed fields.

Actual effort: Contained to one shared Pydantic model (BenchmarkAggregateSupport in _helpers.py) plus mechanical call-site updates across 8 producer files (7 single-category constructors switched from missing_categories= to skipped_products=; 1 multi-category producer — C3.7 — switched to passing all three typed fields) and one expanded test file. No verdict, severity, or benchmark math changed anywhere.

Closes KLAIR-3343

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-6ee017da-cef7-4f8e-9350-17d96c9cc61d?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-6ee017da-cef7-4f8e-9350-17d96c9cc61d&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 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