The Trilogy Times

Linear: [AI-672](https://linear.app/builder-team/issue/AI-672/mercy-fan-out-large-pr-reviews-across-lenses-carry-findings-between)

## What went wrong

[Surtr #1680](https://github.com/AI-Builder-Team/Surtr/pull/1680) (3,430 changed lines) took ten mercy reviews in two hours and never reached an approve. Each review surfaced 1–4 findings. All 22 findings across all ten rounds were already present in the first commit — verified by diffing every finding's anchor against the base SHA.

Two causes, both confirmed from the run logs:

1. The fan-out never happened. Every review was a ~50 second single pass (resolved model=gpt-5.6-luna runtime=codex; run 1: 14:44:12 → 14:45:01). AGENTS.review.md *asks* the reviewer to delegate deep dives above ~800 changed lines — but codex exec has no sub-agent tool, so the instruction was silently ignored, on a diff 4× past that floor and 2× past the ~1,500 lines where the miss analysis measured single-pass review failing.

2. Nothing was remembered between rounds. build_review_prompt took no prior-review input and the workflow always diffs BASE...HEAD. GIT_SHA undeclared was raised in round 2, went unmentioned in rounds 3–9 while remaining unfixed, and reappeared in round 10.

## What changed

        ┌─ silent-failure ─┐
├─ deployment ─────┤
diff ───┼─ correctness ────┼──→ merge + dedupe ──→ arbiter ──→ verdict (code)
├─ data-sql ───────┤         │                │
└─ security-tests ─┘         │                │
└── open items from earlier rounds ──┘

- Fan-out moves into the harness. Above multipass_lines (default 800), one pass per lens, then merge, then arbitrate. An instruction a runtime can't honour isn't a policy; a loop the harness controls is. Both runtimes now get identical depth.

- The arbiter is the precision half. Five lenses with nothing cross-examining them is just a reviewer that blocks five times as often — that would trade one failure mode for a worse one. The arbiter reads the code, drops what doesn't survive, merges duplicates, and re-rates in both directions.

- Open-items ledger. Each review body carries a compact ledger of its own findings; the next round reads it back and must reconcile every item — fixed, still present, or withdrawn.

- Not-converging guard. Past max_review_rounds (default 4), auto-approve is withheld and the PR goes to a human.

## How this stays safe

The worry with more passes is a reviewer that blocks everything; the worry with any change here is one that waves things through. Both are held explicitly:

| Property | How it's enforced |

|---|---|

| Small PRs judged exactly as before | At or under multipass_lines it's the same single pass, same prompt, same everything. Most PRs never touch the new path. |

| No verdict threshold moves | decide_event, confidence cutoffs, blocking categories, block severities: all untouched. |

| A fan-out can't over-report | merge_passes.py reconcile drops any arbiter finding matching no lens candidate and no open item. It may drop or re-rate; it cannot invent. The ceiling is what the lenses independently found. |

| Duplicates don't become N comments | Cross-lens dedupe on (path, normalized category, line proximity), with corroboration recorded as found_by for the arbiter to weigh. |

| Failure never becomes approval | An empty findings list *is* how the agent approves — so a dead lens, failed merge, failed arbiter, or failed reconciliation all report no review (notice posted, no verdict), never an empty one. |

| The round guard can't block | compute_guards only produces downgrade reasons. It sends a stalled PR to a human; it never blocks one and never approves one. |

| Arbitration loss is legible | If the arbiter dies, the review falls back to the deduplicated union and says so in the summary, so a heavier round reads as a degraded run rather than a change of standards. |

Two bugs had to be fixed for the fan-out to be honest rather than merely working:

- decide_review no longer re-extracts review_output.json from agent-raw.out. Harmless when the raw output *was* the review — but on a fan-out it would have reinstated exactly the findings reconciliation dropped, bypassing the guard entirely.

- Telemetry now sums tokens and cost across passes. Each CLI invocation reports only its own cumulative total, so reading one would have booked roughly a sixth of what a review cost.

Also extracted the duplicated Claude/Codex retry loops into one runner so the runtimes can't drift apart, and pointed run-local.sh at the same path so local iteration exercises the real shape.

## Verification

- ruff check / ruff format --check, actionlint, 188 harness tests (27 new) and 1114 heimdall tests green.

- End-to-end exercised against a stub CLI for all shapes: single-pass, fan-out, arbiter-failure fallback, and total-agent-failure. Confirmed an invented arbiter finding is dropped, a re-categorised open item survives, and every failure path yields produced=false with no review_output.json.

- Telemetry aggregation checked numerically across 6 synthetic passes (both runtimes).

## Cost and latency

Large PRs go from 1 model call to 6. At Luna's ~$0.008/review that's ~$0.05 for a PR that burned two hours of author and agent time. Job timeout raised 40 → 60 min to fit the fan-out. Small PRs are unchanged.

## Rollout

Surtr rides @main as the canary and will exercise this first. multipass_lines can be raised per-repo to keep single-pass behaviour, or set to 0 to fan out everywhere.

## Business Value

mercy's job is to be the quality gate that lets PRs merge without a human reading every diff. On large PRs it was measurably not doing that: #1680 shows it finding roughly one defect per review of a change that had eight, then charging the author ten round-trips and two hours to learn things all knowable in round one. That is worse than no review, because the author waits for it. This change makes a large-PR review converge — deep enough in one round to be worth waiting for, and cumulative across rounds so an unfixed issue can't disappear and come back. It directly serves the auto-merge/auto-deploy direction: a reviewer that needs ten rounds can never gate an automated merge, and one whose finding list is unstable trains people to ignore it. The guardrails matter as much as the depth — a reviewer that blocks everything gets switched off just as fast as one that approves everything.

## Manual Effort Estimate

~2 days of focused work (~14–16 hours): reading the ten reviews and diffing every finding against the base SHA to prove they were all knowable in round one; digging out the run logs to find the 50-second single pass and the missing sub-agent tool on codex; designing the lens/arbiter split with the no-invention guard; the harness plumbing across two runtimes; the two latent bugs (re-extraction bypassing reconciliation, telemetry undercounting by 6×); and the test suite. Keval — please confirm or adjust this number.

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

## Summary

- Give public Agent runs the API key owner’s eligible, immutable Skill catalog

- Enable read-only Skill activation and advertised resource reads without adding a Skill capability

- Keep attachments, writes, and every tool/data authorization outside the Skill boundary

## Why

PR #1193 establishes explicit Skill audiences. The public Agent API still forced an empty Skill catalog even when its owning user could use those Skills in Chat. That made API/UI trust diverge and prevented the API agent from following the same approved operating guidance.

This is stacked on #1193 so catalog visibility and runtime invocation share one audience contract.

## Business Value

API consumers can use the same approved Skill guidance available to their Aerie user without managing another capability mapping. API-key scopes continue to govern Agent invocation and every data/tool operation, while Skills remain instructions rather than authority.

## Breaking changes

The public Agent worker tool-policy version advances from 2 to 3. Stale queued claims using the previous version fail closed and must be retried.

## Test plan

- [x] Chat typecheck

- [x] Contracts typecheck

- [x] Flue conversation Worker typecheck

- [x] Chat suite: 9,978 passed, 18 skipped

- [x] Contracts suite: 902 passed

- [x] Flue conversation Worker suite: 16 passed

- [x] Public API test proves an ordinary user receives all_users Skills without a Skill API-key scope and cannot discover or activate edu_ops_only Skills

## Summary

- Adds perplexity_costs / perplexity_raw CTEs to 022_fct_ai_spend.sql, reading the new staging_finance_ai_spend.raw_perplexity_usage table (created by a companion Surtr PR, being built in parallel) and unioning it into all_providers alongside Anthropic/Cursor/GCP/Bedrock/OpenAI.

- BU is resolved directory-first by user_email (mirrors openai_raw), NOT hardcoded to a single org like cursor_raw/gcp_raw's 'Trilogy' — Perplexity spans both Trilogy and Alpha orgs, so there's no single-org precedent to hardcode. Falls back to 'Unmapped' when neither an override nor the directory resolves a BU (same literal openai_raw uses).

- total_cost_dollars is a pass-through SUM() from the raw table's own value (already a proportional Paid-credit estimate at the user-day grain, computed upstream by Surtr) — not re-derived here.

- Token columns are NULL (Perplexity's API reports credits, not tokens — same precedent as Cursor's missing input/output/cache cost breakdown).

- Double-count guard (the core safety property of this PR): perplexity is NOT added to AICostsService._BU_PROVIDER_KEYS or AICostsMartService._COMPLETENESS_GATED — both are fixed, hardcoded provider enumerations, not derived from fct_ai_spend's distinct provider values, so this new branch cannot leak into the BU-aggregate qtd_actual/budget total computed via the completely separate AIProviderKeywordsService GL-keyword path. That path is untouched by this PR.

- get_people_leaderboard/get_entity_stack_rank (Top Spenders / Top API Keys) need zero code changes: their providers filter already defaults to unfiltered, so Perplexity rows surface automatically once the mart carries them.

- New tests in tests/mart_saas_metrics/test_fct_ai_spend.py: TestPerplexityIntegration (static SQL-text assertions on the new CTEs), TestPerplexityDoubleCountGuard (imports the two fixed constants live from the service modules and pins them), TestLeaderboardStackRankUnfilteredByDefault (confirms the providers param default + _provider_filter behavior in code, not SQL text).

- Adds docs/superpowers/plans/2026-09-02-perplexity-mart-wiring-REDSHIFT-RUNBOOK.md, the out-of-band apply runbook (same pattern as this week's other 022_fct_ai_spend.sql runbooks), with the double-count non-regression gate as its most important verification step.

## Business Value

Unblocks Sandeep's original per-person Perplexity spend ask (previously stalled for weeks on the mistaken belief that Perplexity had no usable usage API). Once the companion Surtr pipeline lands and this mart wiring is applied, Perplexity spend becomes visible in the Top Spenders / Top API Keys explorer tables — the same per-person drill-down every other provider (Anthropic, OpenAI, Cursor, GCP, Bedrock) already has — closing a real blind spot for a provider that previously had zero per-person attribution anywhere in Klair. The BU-level budget total is unaffected (and explicitly guarded against ever double-counting), so this is pure additive visibility with no risk to existing budget-tracking numbers.

## Manual Effort Estimate

Proposed by Claude — Keval to confirm/adjust: ~3-4 hours focused time (reading the existing 022 script's CTE conventions closely enough to match style exactly, designing the directory-vs-hardcoded-BU decision, writing the airtight double-count guard tests including the mutation-test proof, and building the runbook).

## Deploy note

This PR alone changes nothing in prod. Mart SQL is applied out-of-band via the standard sp_refresh_fct_ai_spend() runbook process, same as every other 022_fct_ai_spend.sql change shipped this cadence (Anthropic billed-reconcile, OpenAI entity-key). Applying this PR's proc requires, in order:

1. Companion Surtr pipeline PR merged and staging_finance_ai_spend.raw_perplexity_usage created + backfilled (separate repo, being built in parallel — do not apply this proc before that table exists and has rows).

2. The out-of-band runbook: docs/superpowers/plans/2026-09-02-perplexity-mart-wiring-REDSHIFT-RUNBOOK.md. Its verification gates include:

- D1 — Perplexity mart total ties to SUM(raw_perplexity_usage.total_cost_dollars) to the cent (exact pass-through, not approximate).

- D3 (the most important gate) — the existing GL-keyword-based BU-aggregate total (AIProviderKeywordsService → core_budgets.consolidated_budgets_and_actuals joined to core_finance.ai_spend_provider_keywords) is byte-unchanged before vs. after the apply — proving the double-count guard held in live data, not just in the fixed-list assertions.

## Test plan

- [x] pytest tests/mart_saas_metrics/ tests/test_ai_costs_service.py tests/test_ai_costs_mart_service.py — 366 passed

- [x] ruff format + ruff check on the changed test file — clean

- [x] pyright on the changed test file — 0 errors

- [x] Mutation-test proof: temporarily added "perplexity" to AICostsService._BU_PROVIDER_KEYS (and separately to AICostsMartService._COMPLETENESS_GATED) — confirmed TestPerplexityDoubleCountGuard fails loudly in both cases — then reverted (git diff confirmed clean before moving on)

- [ ] Cannot run against live Redshift — raw_perplexity_usage doesn't exist yet (companion Surtr PR). All verification here is static-SQL-text / live-constant assertions, matching this file's established test style; live-data verification happens via the runbook once the companion PR + backfill land.

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

## Summary

- send Apps Script Drive OAuth only as X-Klair-Drive-Token

- treat the new header as canonical in the API

- accept the old exact header only as a bounded rollout alias when canonical is absent

- preserve fail-closed missing/invalid/mismatched-token behavior and token non-disclosure

## Production evidence

- Apps Script OIDC and OAuth tokens both identify marcus.day@trilogy.com

- Drive metadata for the affected Doc returns 200, canEdit=true, trashed=false

- the identical /board-doc/addon/review request returns 401

- identity-only /addon/service-account returns 200

- production Nginx forwards normal incoming headers

This isolates the failure to the reserved X-Google-* transport name before FastAPI receives the session-bound Drive token.

## Validation

- corepack pnpm test — 208 passed

- uv run pytest tests/board_doc/test_addon_*.py -q — 373 passed

- uv run pytest tests/board_doc/test_addon_access.py -q — 20 passed

- Ruff check/format and git diff --check passed

## Rollout

Backend first, then push merged add-on source, create Apps Script v3, and publish Marketplace version 3. No scope, ACL, session, or document behavior change.

## Summary

- Add broker-confirmed SpaceX share sales through 28-Aug-2026.

- Reconcile the 20-August Day-70 distribution, FIFO allocations, residual holdings, and waterfall inputs against the current reconciliation tabs.

- Settle the 31-August put hedge at the confirmed SPCX close of $143.69.

- Update regression coverage and explanatory page copy.

## Validation

- SpaceX feature suite: 15 files, 228 tests passed.

- Full frontend suite: 660 files, 6,792 tests passed, 16 skipped.

- Changed-file ESLint passed.

- Prettier passed.

- TypeScript check passed.

## Screenshot

<img width="1450" height="704" alt="image" src="https://github.com/user-attachments/assets/0ba639f1-367a-4e1d-920f-ced317f1e794" />

<img width="1656" height="322" alt="image" src="https://github.com/user-attachments/assets/b9fcbea4-c450-4c08-8419-9e1ae2b80152" />

mercy is finding real things — but it has no way to say "real, and it shouldn't hold up the merge." That's the actual problem, not strictness.

## The measurement

47 findings across the post-fan-out rounds on [Surtr #1680](https://github.com/AI-Builder-Team/Surtr/pull/1680) and [#1674](https://github.com/AI-Builder-Team/Surtr/pull/1674):

| severity | share | | category | count |

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

| warning | 79% | | silent_bug | 22 |

| critical | 17% | | critical_bug | 12 |

| info | 4% | | security | 9 |

| | | | missing_tests | 2 |

With warning in block_severities, 96% of everything reported was an automatic hard block. A scale whose middle value means the same as its top value has no middle value.

## Change 1: warning out of block_severities

This is the re-evaluation the 2026-07-13 decision asked for on two weeks of live data — seven weeks late. critical stays, so a critical finding still never rides along on an approval. What stops blocking is a warning in a *non-blocking* category.

Honest result: replayed against those 47 findings, this changes the verdict on exactly zero of them — every one is also in a blocking category, so the severity gate was redundant with the category gate on this data. It's still right (it retires a path that would block on a cosmetic nit — literally the example our own e2e test used, "sticky header goes translucent" at warning/other), but it is not the loosening.

## Change 2: the rubric — this is the loosening

silent_bug is 47% of all findings and blocks at confidence ≥ 85. And there was nowhere honest to put *"the code mishandles an input nothing has been observed to produce"* — style and doc_inconsistency are plainly wrong for it, so it went to silent_bug and blocked.

So:

- hardening is now a recognised non-blocking category, for exactly that class.

- A blocking finding must name the realistic input or state that triggers it, in the message. If the reviewer can't name a plausible way the bad input arises *in this system*, it's hardening — reported, not blocking.

The bar is deliberately "name the trigger", not "assume it won't happen":

| finding | verdict |

|---|---|

| Vendor documents an integer; parser truncates a float; its error responses return strings | block — trigger named |

| Join can match nothing, caller then republishes the window as empty | block — empty is a value real systems produce |

| Timestamp would misbehave if it arrived as a boolean; nothing suggests it ever does | hardening — report, don't block |

Simulating that reclassification over the measured set takes blocking from 96% → ~70%.

## What did not change

- critical still hard-blocks regardless of category or confidence.

- Genuine silent_bug / security / critical_bug findings still block at ≥ 85 confidence.

- Nothing stops being *reported* — this changes the verdict, not the review.

- A repo that wants the old behaviour sets block_severities: [critical, warning].

## Verification

200 harness tests (5 new), ruff, actionlint green. The three tests that pinned the old rule were rewritten rather than deleted, and now pin both directions — including that a repo can restore the strict rule.

## Business Value

A reviewer that blocks on 96% of its own findings is not a strict gate, it's an unusable one: the author can't tell the four findings that matter from the six that don't, so the rational response is to stop reading and start clicking through. That's how a quality gate quietly becomes a tax — and it's the direct obstacle to auto-merge, since nothing can ever reach an approve. This restores a working middle: real defects still block, defensive gaps get reported and merged past.

## Manual Effort Estimate

~3 hours — most of it measuring the severity distribution across two PRs' review history and replaying findings through both rule sets to find out that the config knob everyone would reach for first changes nothing. The code is small; knowing which knob was the wrong one took the data. Keval — please confirm or adjust.

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

<!-- CURSOR_AGENT_PR_BODY_BEGIN -->

### 1. Summary

Adds docs/security/trace-data-inventory.md (version literal

trace-data-inventory/v1): a field-level classification inventory of every

TraceSpan envelope leaf and discriminator-permitted payload leaf, for both

the raw local trace file (traces/<runId>.jsonl, unredacted) and the

mirrored S3 copy (redacted at egress per AI-630). Adds one append-only

AI-666 decision entry and a single link under the trace-related bullet in

docs/security/threat-model.md's Source index. No writer, mirror, retention,

infrastructure, or policy change.

### 2. Why it's needed

AI-630 (closed mirrored egress schema) and AI-633 (POSIX private-artifact

modes) closed the current source boundary for the trace family, which is the

threat model's T13 finding (docs/security/threat-model.md) and the first

P0 bullet of the AI-406 remediation item ("publish a field-level inventory

... mark secrets, source/IP, personal data, billing data, destinations,

readers, and TTL"). This makes traces the first data family where that

inventory can be written from source evidence rather than guesswork. It is

deliberately scoped to this one family so it lands as a reviewable, bounded

change rather than a multi-family rewrite, and it makes no claim about

receipts, events, heartbeats, screenshots, or usage data, and does not close

AI-406.

### 3. Changes

- New: docs/security/trace-data-inventory.md — envelope leaves

(schemaVersion, runId, parentRunId, spanId, parentSpanId, host,

ts, type) as 16 shared-variant rows (one raw + one mirrored per leaf,

each stating it expands across all six discriminators), then every

discriminator-permitted payload leaf for text_delta, tool_use,

tool_result, thinking_delta, turn_complete (reserved/unemitted —

never described as observed), and run_complete (citing the three actual

emit sites — runner.ts, reviewer.ts, addresser.ts — and noting which

fields each one currently populates). toolInput and toolResult.output

are each represented by exactly one open-descendant row (toolInput.*,

toolResult.output.*) rather than a false enumeration of their

arbitrary-depth contents. Every current-state claim cites a source symbol;

live/provider facts (bucket policy application, access logging, provider

retention) are marked external/unknown.

- New: docs/decisions/20260902T204630.608Z-ai-666-adopt-docs-security-trace-data-inventory-md-t.md

— the append-only AI-666 decision entry (never edits an existing decision

file, per the ledger's convention).

- Changed: docs/security/threat-model.md — one link added to the

Source index, next to the existing traces.ts/trace-egress-redact.ts

bullet. No other line in that file changed.

Contract surface affected: none — this PR touches no code, type, or

runtime behavior.

### 4. Breaking changes

None.

### 5. Test plan

- [x] pnpm exec vitest run src/traces.test.ts src/trace-egress-redact.test.ts src/trace-mirror.test.ts → 3 files, 126 tests passed

- [x] node scripts/render-decisions-log.mjs >/tmp/ai666-decisions.txt → exit 0, no stderr warnings; new AI-666 entry renders correctly at the top (newest-first) with no parse warnings

- [x] pnpm typecheck → clean, no errors

- [x] git diff --stat against main → exactly three files changed (the new inventory doc, the new decision file, and a 5-line addition to threat-model.md)

### 6. Verification artifact

Confirmed the two required eval-check substrings are present in the new file:

$ grep -c "trace-data-inventory/v1" docs/security/trace-data-inventory.md
1
$ grep -c "toolResult.output" docs/security/trace-data-inventory.md
9

threat-model.md diff (the only change to that file):

+- [docs/security/trace-data-inventory.md](trace-data-inventory.md) —
+  AI-666 field-level classification inventory (trace-data-inventory/v1)
+  for raw local and mirrored S3 trace spans; narrows the traces/ row above
+  into content-axis detail. Descriptive only — does not change this
+  document's ratings/dispositions and does not close AI-406.

### 7. Impact estimate

Business value: Makes the highest-risk raw/egress trace distinction

reviewable before later redaction, retention, KMS, and deletion policy work.

Pre-AI estimate: 3 points — a bounded inventory, one decision, one link,

source/transport/reader audit, focused regressions, and review.

## Review Round Completeness

- outcome: indeterminate

- round: 1

- dispatched: 4

- reported: 4

- missing: (none)

- cause: publication_missing

- head: beea86d7e19866b356a16c4104d829c34c1858b5

- run: fanout-275-2026-09-02T22-42-07-852Z

<!-- drones:round-completeness head=beea86d7e19866b356a16c4104d829c34c1858b5 run=fanout-275-2026-09-02T22-42-07-852Z -->

An incomplete review round is not a clean round. Do not merge without re-firing review (drones review --pr <N> --post), which re-stamps this section, or an explicit operator override.

Closes AI-666

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-c4f744ae-6608-4cb9-8c51-648e21f7b866?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-c4f744ae-6608-4cb9-8c51-648e21f7b866&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

- Resolve Forecast programs through the canonical source-ID-to-ontology-ID bridge, preserving bounded historical code reads

- Keep the dashboard on the last coherent Enrollment, Funnel, and Forecast publication while Sync Status reports partial refreshes

- Replace the blocking cross-source School Year error with neutral first-publication and unavailable-year states

## Why

An upstream Finance program rename caused Forecast source labels to diverge even though the underlying program identity was unchanged. The dashboard also combined independently advancing publication pointers and replaced the entire experience with an error whenever one refresh domain lagged.

This work builds on #1190 rather than replacing it: schoolStatus remains authoritative for operating lifecycle, the retired mart is_open value is not restored, and the legacy isOpen compatibility contract remains owned by Vlad's widen-and-migrate cutover. This PR adds stable identity resolution and coherent Forecast publication on top.

## Business Value

Forecast remains usable during partial refreshes, preserves the last known-good data, and resolves program renames through canonical identity without requiring changes to upstream EduCRM marts.

## Test plan

- [x] pnpm check

- [x] Sync test suite: 74 files, 1,155 tests passed

- [x] Chat test suite: 689 files, 10,039 passed, 18 skipped

- [x] Latest-head focused validation: 85 tests passed

- [x] Seven-lane adversarial review

- [x] Hosted CI on ad363f13d

- [x] Mercy review on ad363f13d

## Summary

- Restore Alpha Austin and Alpha High School rows in physical-mode forecast responses

- Label redistributed counts from their authoritative published enrollment generation

- Fail closed when enrollment, funnel, and forecast reads do not share one publication generation

## Why

Physical mode redistributes Austin students between Spyglass and Colorado St. Provenance hardening correctly stopped reusing the replaced program rows' year/date, but the physical cohort's own published generation was not propagated. That caused both Austin programs to be omitted even though their physical enrollment data was complete.

The public API also assembles its base and physical projections in separate reads. Admissions refreshes publish enrollment and funnel before forecast, so this patch verifies both reads came from the same complete generation before exposing Austin physical rows.

## Business Value

Physical-building forecast consumers regain the Austin soft forecast without accepting mislabeled or mixed-generation enrollment provenance.

## Test plan

- [x] 83 focused tests across forecast API, application service, and dashboard suites

- [x] pnpm --dir chat typecheck

- [x] Biome on all six changed files

- [x] pnpm lint:test-architecture

- [x] pnpm lint:read-bounds

- [x] Hosted CI, including the full repository test suite

- [x] Mercy review on b939dc3ce

Every jotform-survey-sync run has failed for 13 runs straight because the pipeline's Redshift IAM permissions were never updated when the load step was changed to use one atomic batch call — the fix is a one-line permission grant restoring the atomic write path that has been writing zero rows since it merged.

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

> Ready for review. Its tests pass. A person still merges.

## For The Agent

_Everything below is detail for review. The summary above is the change._

Presented as ready — verification green, scope tier draft, fix_class code_fix, HEIMDALL_READY_PRS=true.

### What's broken

Run 88326857-8fd2-4108-9725-e6a176707d4b failed at the Redshift load step with AccessDeniedException ... is not authorized to perform: redshift-data:BatchExecuteStatement on resource: arn:aws:redshift:us-east-1:479395885256:cluster:redshift-cluster-1 because no identity-based policy allows the redshift-data:BatchExecuteStatement action, raised from redshift_client.py:135 inside execute_batch(), called by replace_forms() at redshift_client.py:439. The pipeline's IAM policy in pipelines/runners/jotform-survey-sync/pipeline.json's iam_statements only grants redshift-data:ExecuteStatement, DescribeStatement, and GetStatementResult — it was never updated when PR #1626 (commit dccbd5c2) switched replace_forms/delete_by_form_ids from individual execute_statement calls to a single atomic batch_execute_statement call for transactional delete+insert/COPY. The run successfully extracted 393 forms and 1099 questions and staged them to S3, then failed outright writing zero rows to staging_education_jotform.jotform_forms/jotform_questions — a full data-completeness loss on every 6-hour run, 13 consecutive failures per the run record.

Root cause. The Lambda execution role pipeline-jotform-survey-sync-prod only has the three IAM actions listed in pipeline.json's redshift-data statement (ExecuteStatement, DescribeStatement, GetStatementResult), but the code path PR #1626 introduced (RedshiftClient.execute_batch at redshift_client.py:114-135, used by replace_forms at line 439 and delete_by_form_ids at lines 281/427) exclusively calls batch_execute_statement, a distinct IAM action that was never added to the policy. This is a declarative-config gap of the same shape as the repo's known src/requirements.txt and environment-block issues: the code's runtime capability requirement changed (individual statements → one atomic batch call, made atomic specifically to fix a delete-without-replace data-loss bug) but the IAM statement in pipeline.json was never updated to match, so every load has failed identically since that change merged.

### What this PR changes

Add redshift-data:BatchExecuteStatement to the actions array of the existing redshift-data entry in pipelines/runners/jotform-survey-sync/pipeline.json's iam_statements (alongside ExecuteStatement, DescribeStatement, GetStatementResult), the same shape of fix as the s3:ListBucket gap resolved in PR #1653 (commit 9fa5b558), which added a missing action to this same iam_statements block. Add a matching assertion in tests/test_handler.py, mirroring the existing test_pipeline_config_scopes_retry_queue_lookup pattern that reads pipeline.json directly, so a future action-name drift between the code and the declared IAM policy is caught in CI rather than after another string of failed prod runs.

Why this fixes it. This is a one-line addition to a declarative IAM statement already present in pipeline.json — it touches no application logic and grants exactly the one action the AccessDeniedException names, so it carries none of the risk of a behavioral change. The blast radius is confined to this pipeline's own execution role, follows the identical, already-reviewed precedent of PR #1653/commit 9fa5b558 for a prior IAM gap on this same pipeline, and restores the atomic delete+insert/COPY transaction that PR #1626 was specifically written to guarantee (its stated purpose was preventing partial-write data loss, which is currently failing 100% of the time instead).

#### Files changed

 pipelines/runners/jotform-survey-sync/pipeline.json        |  1 +
.../runners/jotform-survey-sync/tests/test_handler.py      | 14 ++++++++++++++
2 files changed, 15 insertions(+)

### Verification

### pytest (pipelines/runners/jotform-survey-sync/tests) — exit 0

============================= test session starts ==============================
platform linux -- Python 3.11.14, pytest-9.1.1, pluggy-1.6.0
rootdir: /home/runner/_work/Surtr/Surtr/publish/pipelines/runners/jotform-survey-sync
configfile: pyproject.toml
plugins: mock-3.15.1
collected 74 items
tests/test_handler.py .................................................. [ 67%]
........................                                                 [100%]
============================== 74 passed in 0.29s ==============================

### verify: ruff check — exit 0

[notice] A new release of pip is available: 25.3 -> 26.2.1
[notice] To update, run: pip install --upgrade pip
All checks passed!

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

1729 files already formatted

### verify: pytest (pipeline lambdas) — exit 0

``

6.0

rootdir: /home/runner/_work/Surtr/Surtr/publish/pipelines/cdk/lambdas

configfile: pyproject.toml

testpaths: tests

plugins: cov-7.0.0

collected 486 items

tests/test_ai_spend_raw_api.py .............................. [ 6%]

tests/test_coordinate_fanout_run.py .................................... [ 13%]

.... [ 14%]

tests/test_create_run_record.py ........................ [ 19%]

tests/test_gchat_notifier.py ........................... [ 24%]

tests/test_generate_chunks.py ..... [ 25%]

tests/test_gsheet_tracker.py .................. [ 29%]

tests/test_load_fanout_plan.py .............. [ 32%]

tests/test_redshift_cluster_iam_role_association.py ........ [ 34%]

tests/test_registry_sync.py ......................... [ 39%]

tests/test_triage_dispatcher_handler.py ................................ [ 45%]

................... [ 49%]

tests/test_triage_dispatcher_signature.py .............................. [ 55%]

...... [ 57%]

tests/test_triage_reconciler.py ............ [ 59%]

tests/test_triage_reconciler_tracker.py ............ [ 62%]

tests/test_update_run_failed.py ........................................ [ 70%]

..... …_(truncated)_

<details>

<summary>Run metadata</summary>

| Field | Value |

| --- | --- |

| Pipeline | jotform-survey-sync |

| Failing run | 88326857-8fd2-4108-9725-e6a176707d4b |

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

| Signature | 3e18a62129854a0a957c7a9c3b9483cf81c930c5e27d0f8d198f17978606a79f |

| 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.

Slice 1 of 4, split out of [PR #1689](https://github.com/AI-Builder-Team/Surtr/pull/1689) (5,385 lines, ~20 mercy rounds without converging). Same code, reviewed in reviewable pieces.

## What's here

The storage contract and the runner package — no fetch or load logic.

- pipelines/cdk/sql/staging_finance_ai_spend/raw_perplexity_usage.sql — the target table, grain (event_date, org_name, user_email, model).

- pipelines/cdk/sql/staging_finance_ai_spend/perplexity_usage_pipeline_writer_mutex.sql — an empty relation the writer LOCK TABLEs as the first statement of its DELETE+COPY transaction, so an overlapping cron run, manual backfill, or Lambda retry serializes instead of interleaving. Pattern borrowed from mart-aerie-hubspot-refresh's writer mutex rather than invented here.

- pipeline.json — Lambda definition, IAM scope (Secrets Manager, S3, Redshift), environment. schedule.enabled is false; nothing fires in production from this PR or any later one in this stack.

- pyproject.toml, uv.lock, src/requirements.txt — bundling: true, so src/requirements.txt is the file CDK's PythonFunction actually installs at deploy time (per CLAUDE.md); pyproject.toml/uv.lock cover local dev and CI.

- src/__init__.py, tests/__init__.py, tests/conftest.py.

Both DDL files are OWNER TO "CQL_download_OM" so the Lambda's own role can write them even when the DDL is applied under an admin role.

## Note on conftest.py

On the original branch conftest.py carries an autouse fixture that stubs the S3 archive and ledger writes, and it does import handler at fixture setup. Since it is autouse, it runs for every test in the directory — so shipping it before handler.py exists would break collection for slices 2 and 3. The fixture is held back and lands with handler.py in slice 4; the final state of the file is byte-identical to the original branch.

## Deploy behaviour of this PR alone

Merging this to main creates the Lambda with handler.handler before src/handler.py exists. The schedule is disabled and nothing invokes it, so this is inert rather than broken, and slices 2–4 follow immediately. Flagging it explicitly rather than leaving it to be discovered. The DDL and the Perplexity-Analytics-Keys secret are applied out of band as usual, not by CDK.

## Business Value

Lands the reviewable half of the Perplexity ingestion — the warehouse contract — as a standalone unit. The grain, the cost semantics baked into the table comment, and the concurrency story are the decisions that are expensive to get wrong and cheap to change now; they were the parts getting lost in a 5,385-line diff. Splitting the stack is also what unblocks the underlying feature: real per-person Perplexity usage for Klair's AI budget Top Spenders view, for a provider that currently has no per-user visibility at all.

## Manual Effort Estimate

Proposed by Claude — ~3 hours for this slice by hand with no AI (DDL for two tables including the grain/encoding/ownership decisions, pipeline.json with the IAM statements, dependency compile). The parent PR's whole-feature estimate was ~1.5–2 days.

Keval — please confirm or adjust.

## Stack

Base main. This is the bottom of the stack:

1. this PR — scaffold + DDL

2. [PR #1699](https://github.com/AI-Builder-Team/Surtr/pull/1699) — secrets + API client

3. [PR #1700](https://github.com/AI-Builder-Team/Surtr/pull/1700) — Redshift writer, payload archive, ledger

4. [PR #1701](https://github.com/AI-Builder-Team/Surtr/pull/1701) — orchestration + cost allocation

Each child PR is targeted at its parent branch and should be retargeted to main as the stack merges up.

There is no separate "enable the schedule" PR: the schedule is disabled on the original branch too, so enabling it was never part of this work.

## Test plan

- [x] ruff check pipelines + ruff format --check pipelines clean

- [x] No test_*.py in this slice, so CI's runner-test loop skips the directory (compgen -G guard) — nothing to run yet

- [ ] Apply both .sql files to Redshift (out of band, as usual)

- [ ] Create the Perplexity-Analytics-Keys secret in Secrets Manager

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

<!-- CURSOR_AGENT_PR_BODY_BEGIN -->

## Summary

- addon_chat, addon_review_run, addon_propose, and addon_refresh now continue only when _reconcile_addon_session_from_doc(...).outcome is unchanged or doc_applied. Every other typed outcome (blocked_read, blocked_parse, blocked_persist — including a permission-only drive_forbidden read) now returns the existing typed safe-block HTTPException before any LLM call, review run, or data-refresh job starts.

- Added a new gate, _require_fresh_addon_reconcile, and extracted the shared safe-block raiser _raise_addon_reconcile_blocked so it and the pre-existing KLAIR-3336 CRUD-mutation gate (_require_canonical_addon_mutation_projection) return byte-identical status/detail for the same reason_code.

- KLAIR-3336 CRUD routes (add/remove/rename-section) and addon_conformance are unchanged — they keep the existing best-effort drive_forbidden carve-out.

## Why It's Needed

Before this change, addon_chat / addon_review_run / addon_propose / addon_refresh called _reconcile_addon_session_from_doc but then gated on _require_canonical_addon_mutation_projection — the KLAIR-3336 CRUD gate. That gate's best_effort_unavailable carve-out (added so a session-backed structural mutation still works when the backend service account isn't shared on the doc) let a permission-only blocked read (blocked_read / drive_forbidden) fall through to reconcile.session unchanged, and these four actions would proceed on stale/unconfirmed session content — running Claire's review suite, chat turn, single-section proposal, or data refresh as if it reflected the *current* Google Doc when reconciliation had explicitly failed to confirm that.

This was directly provable: test_addon_chat_preserves_sidebar_when_reconcile_lacks_sa_access (pre-existing) asserted that a Drive 403 during reconcile still returned 200 "still works" from handle_chat. That carve-out is correct for a CRUD mutation (there's no "current content" claim being made), but wrong for an action whose entire output purports to reflect current Doc content.

## Changes

- routers/board_doc_router.py:

- Added _raise_addon_reconcile_blocked(reconcile) -> NoReturn — the one typed safe-block HTTPException raiser, extracted from _require_canonical_addon_mutation_projection's tail. Adds one new branch (drive_forbidden → 409, "Share the current Google Doc with the Klair service account...") that only the new fresh-action gate can reach (the CRUD gate's best_effort_unavailable check still returns before ever calling this for that reason code).

- _require_canonical_addon_mutation_projection (KLAIR-3336, unchanged behavior) now delegates its raise branch to the shared helper.

- Added _require_fresh_addon_reconcile(reconcile) -> WizardSession (KLAIR-3486) — continues only for outcome in ("unchanged", "doc_applied"), using reconcile.session; every other outcome raises via the shared helper.

- Rewired the four fresh-Doc-dependent routes — addon_review_run, addon_propose, addon_chat, addon_refresh — from _require_canonical_addon_mutation_projection to _require_fresh_addon_reconcile, and updated their inline comments (previously stated an aspirational "aborts on blocked reconciliation" that the CRUD gate didn't actually enforce for drive_forbidden).

- Updated _reconcile_addon_session_from_doc's docstring to describe both typed gates now layered on top of it (the helper itself still never raises).

- addon_conformance and the KLAIR-3336 CRUD routes (addon_add_section, addon_remove_section, addon_rename_section_prepare) are untouched — they are not named in the ticket's fresh-action inventory and their downstream work (structural CRUD, or a Redshift-backed structural report with no provider/job call) is not the review/chat/propose/refresh family this ticket targets. addon_conformance in particular was evaluated and intentionally left on the CRUD gate; extending the strict gate there is a separate follow-up policy decision, not implied by the ticket's inventory.

- tests/board_doc/test_addon_fresh_reconcile_gate.py (new): a parameterized, hermetic matrix — every fresh action (chat/review_run/propose/refresh) × every typed blocked reason (drive_forbidden, drive_not_found, drive_unavailable, unexpected_reconcile_error, empty_parse, degraded_parse, ambiguous_identity, retained_section_vanished, persist_failed) asserting the typed safe-block status/detail and zero provider/persist calls, plus unchanged/doc_applied continuation using result.session (with doc_applied proving the new revision + already-invalidated review_results are what the downstream call observes), a legacy-serialized-session compatibility case, and auth-precedence (outsider rejected before reconcile runs).

- tests/board_doc/test_addon_reconcile.py: renamed/inverted test_addon_chat_preserves_sidebar_when_reconcile_lacks_sa_access → test_addon_chat_blocks_before_handle_chat_when_reconcile_lacks_sa_access (now asserts 409 + zero handle_chat calls instead of the old 200 "still works"); updated the module docstring's stale "reconcile failure does NOT abort the action" claim.

- tests/board_doc/test_addon_section_crud.py: added test_remove_still_applies_when_reconcile_lacks_sa_read_access — a regression guard pinning that the KLAIR-3336 CRUD gate's drive_forbidden best-effort carve-out is unaffected by this change.

### Contract surface affected

Grepped every consumer of AddonReconcileResult, _reconcile_addon_session_from_doc, _require_canonical_addon_mutation_projection, and mutation_projection_outcome repo-wide. All are internal to klair-api/routers/board_doc_router.py plus its tests — no other production module imports these symbols (fast_endpoint.py imports only router).

| Symbol | Disposition |

|---|---|

| AddonReconcileResult (dataclass + .outcome/.reason_code/.remediation_code/.session_doc_revision/.live_doc_revision) | Unchanged — KLAIR-3225 contract reused verbatim, no new fields. |

| AddonReconcileResult.mutation_projection_outcome | Unchanged. |

| _reconcile_addon_session_from_doc | Unchanged behavior; docstring updated to describe the two gates now built on it. |

| _require_canonical_addon_mutation_projection (KLAIR-3336) | Unchanged behavior (still allows canonical/best_effort_unavailable/precondition_unavailable); raise branch now delegates to the new shared helper. Consumers unchanged: addon_conformance, addon_add_section, addon_remove_section, addon_rename_section_prepare. |

| _raise_addon_reconcile_blocked (new) | Shared safe-block raiser; adds the drive_forbidden branch, reachable only via the new gate. |

| _require_fresh_addon_reconcile (new) | New consumers: addon_review_run, addon_propose, addon_chat, addon_refresh — previously called _require_canonical_addon_mutation_projection. |

## Breaking Changes

None for any public response schema, status-code contract, or KLAIR-3336 CRUD route. Behavior-visible change: for addon_chat / addon_review_run / addon_propose / addon_refresh only, a request against a doc the backend service account cannot currently read (drive_forbidden) now returns 409 with the existing safe-block envelope instead of silently succeeding on stale/cached content. This is the intended fix — the add-on should call GET /addon/service-account and re-share the doc, then retry.

## Test Plan

Run from klair-api/:

uv run pytest tests/board_doc/test_addon_fresh_reconcile_gate.py -q
# 49 passed
uv run pytest tests/board_doc/test_addon_reconcile.py tests/board_doc/test_addon_review_run.py \
tests/board_doc/test_addon_chat.py tests/board_doc/test_addon_propose.py \
tests/board_doc/test_addon_refresh.py tests/board_doc/test_addon_conformance.py \
tests/board_doc/test_addon_section_crud.py tests/board_doc/test_addon_rename_operation_protocol.py \
tests/board_doc/test_addon_add_section.py tests/board_doc/test_addon_structural_reconcile.py -q
# 228 passed
uv run pytest tests/board_doc/ -q
# 4448 passed, 2 deselected (integration/eval markers excluded by default addopts — none apply here)
uv run ruff format --check routers/board_doc_router.py tests/board_doc/test_addon_reconcile.py \
tests/board_doc/test_addon_fresh_reconcile_gate.py tests/board_doc/test_addon_section_crud.py
# 4 files already formatted
uv run ruff check routers/board_doc_router.py tests/board_doc/test_addon_reconcile.py \
tests/board_doc/test_addon_fresh_reconcile_gate.py tests/board_doc/test_addon_section_crud.py
# All checks passed!
uv run pyright routers/board_doc_router.py
# 0 errors, 0 warnings, 0 informations

Not run: repository-wide Pyright (out of scope per ticket instructions), -m integration/-m eval (network/Redshift-backed, unrelated to this change), and no Browser/manual verification (backend-only change, no frontend/Apps Script touched).

Regression-proof sanity check (not part of CI, done manually during development): reverted the four gate call sites back to _require_canonical_addon_mutation_projection and re-ran test_addon_fresh_reconcile_gate.py — the 4 live_read_forbidden cases (one per route) failed as expected, confirming the new tests actually detect the vulnerability rather than passing vacuously. Change was then restored and the full suite re-verified green.

## Verification Artifact

Redacted parameterized matrix (test_addon_fresh_reconcile_gate.py) — one row per outcome, uniform across all 4 fresh routes (chat, review_run, propose, refresh); provider/persist call counts are AsyncMock await counts asserted in-test, not real Doc/LLM/job calls:

| Reconcile outcome | reason_code | HTTP status | Provider calls | Persist calls | Cached/sentinel content in response |

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

| blocked_read | drive_forbidden | 409 | 0 | 0 | none |

| blocked_read | drive_not_found | 409 | 0 | 0 | none |

| blocked_read | drive_unavailable | 503 | 0 | 0 | none |

| blocked_read | unexpected_reconcile_error | 503 | 0 | 0 | none |

| blocked_parse | empty_parse | 409 | 0 | 0 | none |

| blocked_parse | degraded_parse | 409 | 0 | 0 | none |

| blocked_parse | ambiguous_identity | 409 | 0 | 0 | none |

| blocked_parse | retained_section_vanished | 409 | 0 | 0 | none |

| blocked_persist | persist_failed | 503 | 0 | 0 | none |

| unchanged | revision_unchanged | 200 | 1 (using result.session) | n/a | — |

| doc_applied | doc_applied | 200 | 1 (using new revision + canonical projection) | n/a | — |

doc_applied detail (review_run route, representative of all four): the reconciled session fixture carries google_doc_revision="rev-doc-applied-new" and review_results=None (simulating KLAIR-3242's post-apply invalidation); the test asserts the session as observed by the downstream review call has exactly that revision and review_results is None at call time — proving the gate hands the review engine the new, canonical, already-invalidated projection rather than any stale cached findings.

44 blocked-case assertions (9 reasons × 4 routes) + 8 success-continuation assertions (2 outcomes × 4 routes) + 1 legacy-session case + 4 auth-precedence cases = 49 tests total, all passing; 0 flagged provider/persist/job/write calls in any blocked case.

## Impact Estimate

Business value: Prevents Budget Bot add-on actions from reviewing, generating, refreshing, or presenting stale content when the canonical Google Doc could not be read, mapped, or safely persisted.

Pre-AI estimate: 3 points - inventory and gate several route families, preserve typed compatibility, and prove a cross-product failure matrix with strict zero-provider/job/prepare/Doc side effects.

Closes KLAIR-3486

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-0c31c74f-6bd1-44c6-b67e-96d9a1c2ce18?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-0c31c74f-6bd1-44c6-b67e-96d9a1c2ce18&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, one-time section identity repair picker to the Budget Bot add-on. When apply_section, chat_rewrite, add_section, or remove_section cannot resolve exactly one live section heading (ambiguous or missing), only that operation's card pauses; the user sees every exact live candidate heading with a non-secret location, picks one explicitly (Editor only), and the pick is revalidated and seeded as one named range before the original operation retries exactly once.

## Why It's Needed

Before this change, an ambiguous or missing section identity surfaced only as static error text with no in-sidebar recovery path — the user had to manually edit document headings and hope a later retry happened to resolve uniquely. That risked either a stuck operation or, if someone else silently disambiguated by heading order/position, a write landing on the wrong section. This closes that gap without ever guessing: the picker requires an explicit Editor choice, revalidates it live, and leaves everything else in the sidebar (review, chat, other cards) fully usable throughout.

## Changes

- DocumentPlanning.gs (pure, credential-free testable): sectionIdentityRepairCandidates_ (exact-title matches + a heading-ordinal location label, TITLE/SUBTITLE excluded), sectionRepairRoleFromDrivePermission_ (Drive Permission enum → editor/commenter/viewer/unknown), planSectionIdentityRepairOutcome_ (the typed, serializable read-only outcome), planSectionIdentityRepairSubmission_ (fail-closed re-validation of role + selected heading against a fresh scan).

- Code.gs: currentSectionRepairRole_ (reads DriveApp.getFileById(docId).getAccess(user) — the same Drive ACL the backend's own can_edit check is backed by, no new backend call), getSectionIdentityRepairState (read-only fetch for the picker), submitSectionIdentityRepair (Editor-only seed via the existing rebuildSectionNamedRange_ primitive; never mints or touches a ledger operation id).

- Sidebar.html: withSectionIdentityRepair_ wraps a card's existing apply runner so an eligible failure opens the picker in-card (releasing the write-queue lock so other cards keep working) instead of the plain error text; every other failure and every success is unchanged. Candidate rows render every exact heading + location with no default/preselected choice; submit is disabled until an explicit selection; a successful seed retries the *same* original runner exactly once through the existing single-writer apply queue. Viewer/commenter see concise guidance and no selection control. Zero candidates offer Restore-heading guidance + explicit Retry (never an auto-seed). Cancel is side-effect-free. One-shot guards block duplicate seed/retry from repeat clicks or rerenders. Wired into approveChat (chat_rewrite) and approveRemoveSection (remove_section) — see Out of scope below for why add_section/rename_section are not wired.

- Tests: tests/section-identity-repair-planning.test.js (pure candidate/role/submission shaping), tests/section-identity-repair.test.js (Code.gs host adapter over a DocumentApp/DriveApp fixture), tests/section-identity-repair-sidebar.test.js (full DOM interaction via happy-dom, new test-only devDependency). tests/production-vm.js gained loadSidebarSectionIdentityRepair, mirroring the existing loadSidebarRenameRecovery bounded-span pattern.

### Contract surface affected

- New Apps Script server functions callable from the sidebar: getSectionIdentityRepairState(sectionId, title, operation) (read-only) and submitSectionIdentityRepair(sectionId, title, operation, selectedIndex, selectedText) (the only new write path, gated fail-closed on a live role check + live candidate re-match). Both are purely additive; no existing function signature changed.

- renderChatProposal's remove_section card template gained one additive data-title attribute so approveRemoveSection can build a repair state; applyRemoveSection's own signature is unchanged.

- Section ID format (BBOT_SEC::<section_id>), the rename operation protocol, and the backend permission source (Drive can_edit, read here via Apps Script's own DriveApp.getAccess) are unchanged — no backend/API changes at all.

### Out of scope

- add_section's own ambiguous/not_found case targets an *anchor* section, whose title the sidebar never receives from the backend (only before_section_id/after_section_id) — there is no title to build exact-match candidates from, so it is not wired to the picker.

- rename_section's ambiguous/not_found path already compensates into the existing KLAIR-3231 ledger repair_required state, remediated by the existing renameRecoveryCardHtml_ / approveRenameRepair recovery cards. Layering this new picker over that would duplicate an existing (if less flexible) repair flow and touch operation-ledger semantics, both explicitly out of scope for this ticket; it is untouched.

- No backend/Board Doc API changes, new section schema, new role model, OAuth scope changes, automatic section creation, heading rename, fuzzy/prefix/position matching, candidate ranking/default choice, or redesign of the rename ledger, named-range format, or add-on renderer.

## Breaking Changes

None.

## Test Plan

All commands run from budget-bot-addon/:

- pnpm install — installed deps (added happy-dom as a devDependency, test-only).

- pnpm test (vitest run) — 258/258 tests passed, 0 skipped, 11 test files, including the 3 new files (14 + 14 + 22 = 50 new tests) and every pre-existing file unchanged and still green:

- tests/section-identity-repair-planning.test.js — 14 passed

- tests/section-identity-repair.test.js — 14 passed

- tests/section-identity-repair-sidebar.test.js — 22 passed

- tests/rename-operation-protocol.test.js — 71 passed (unchanged)

- tests/addon-response-validation.test.js — 64 passed (unchanged)

- tests/sidebar-diff.test.js — 11 passed (unchanged)

- tests/addon-response-consumption.test.js — 21 passed (unchanged)

- tests/section-targeting.test.js — 20 passed (unchanged)

- tests/renderer-planning-goldens.test.js — 10 passed (unchanged)

- tests/server-planning.test.js — 10 passed (unchanged)

- tests/oauth-transport.test.js — 1 passed (unchanged)

- Tests explicitly cover: duplicate exact titles → distinct unselected candidates with distinct locations; prefix/near-collision titles never auto-matched; one explicit Editor selection → exactly one BBOT_SEC::<id> range seeded + exactly one retry; duplicate clicks/rerenders → at most one seed/retry; stale selected-heading and stale/partial-cleanup range failures → actionable state, no wrong-range write; zero headings → Restore-heading/Retry with no automatic seed; viewer/commenter → guidance only, no selection control, no RPC call even if attempted; permission downgrade between display and submit → rejected fail-closed; cancel → no RPC call, no retry; retry-after-seed failure → bounded message, never a silent second retry; unrelated ineligible failures and successful unique-resolution operations → byte-for-byte unchanged behavior.

- Static/credential-free checks (repo has no lint/tsc for this JS/Apps-Script package): node --check on each .gs file and the extracted Sidebar.html <script> body — all pass. pnpm exec clasp --project .clasp.json.example status --json — reports exactly the expected deployed file set (appsscript.json, Code.gs, DocumentPlanning.gs, MarkdownPlanning.gs, Sidebar.html), confirming the deployed source shape is unchanged and clasp can still parse it. clasp push was never run (per README, it's an approved-deployment-only action).

- No klair-client/klair-api files changed, so their lint/tsc/pytest suites are not applicable to this diff.

## Verification Artifact

No documented browser-preview command exists for this add-on's Sidebar.html — it depends on Apps Script's injected google.script.run runtime and normally only boots inside an authenticated Google Doc with a real OAuth/Drive flow, which cannot be provisioned in this credential-free cloud VM. Per the task's fallback allowance, I built a local, uncommitted static HTML harness that serves the *real, unmodified* Sidebar.html production code with a mocked google.script.run bridge (fixture review/chat/repair responses, a role toggle for Editor/Viewer) and drove it end-to-end with a real browser:

- 

- 

- 

This is a real interactive walkthrough of the exact shipped code (not a toy/contrived duplicate), not an authenticated Google Docs add-on boot — the automated tests above are the primary evidence for the fail-closed/permission/idempotency contracts, since the harness's fixture backend can't exercise real Drive ACLs or the actual backend ledger.

## Impact Estimate

Business value: Lets users recover a single ambiguous or missing section identity without risking a write to the wrong section or losing access to the rest of Budget Bot.

Pre-AI estimate: 3 points -- a human would need roughly three days to trace the Apps Script identity and permission seams, build a bounded accessible repair flow, preserve operation idempotency, and verify adversarial role and document-drift cases.

Closes KLAIR-3233

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-2134ba22-98cd-44c4-af27-8e14e384f7b9?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-2134ba22-98cd-44c4-af27-8e14e384f7b9&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>

<!-- drones:impact-actual:begin -->

Agent time: 10 m (implementer 0 m · reviewer 10 m · addresser 0 m)

Summed across phases. The 7 reviewer dimensions ran concurrently, so this exceeds elapsed wall-clock.

Efficiency vs. estimate: ~139.5× (3 points = 24 h of pre-AI effort)

<!-- drones:impact-actual:end -->

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-2134ba22-98cd-44c4-af27-8e14e384f7b9?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-2134ba22-98cd-44c4-af27-8e14e384f7b9&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>

<!-- drones:impact-actual:begin -->

Agent time: 0 m (excludes reviewer) (implementer 0 m · reviewer not measured · addresser 0 m)

<!-- drones:impact-actual:end -->

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-2134ba22-98cd-44c4-af27-8e14e384f7b9?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-2134ba22-98cd-44c4-af27-8e14e384f7b9&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>

<!-- drones:impact-actual:begin -->

Agent time: 7 m (implementer 0 m · reviewer 7 m · addresser 0 m)

Summed across phases. The 4 reviewer dimensions ran concurrently, so this exceeds elapsed wall-clock.

Efficiency vs. estimate: ~205.6× (3 points = 24 h of pre-AI effort)

<!-- drones:impact-actual:end -->

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-2134ba22-98cd-44c4-af27-8e14e384f7b9?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-2134ba22-98cd-44c4-af27-8e14e384f7b9&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>

<!-- drones:impact-actual:begin -->

Agent time: 0 m (excludes reviewer) (implementer 0 m · reviewer not measured · addresser 0 m)

<!-- drones:impact-actual:end -->

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-2134ba22-98cd-44c4-af27-8e14e384f7b9?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-2134ba22-98cd-44c4-af27-8e14e384f7b9&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>

<!-- drones:impact-actual:begin -->

Agent time: 10 m (implementer 0 m · reviewer 10 m · addresser 0 m)

Summed across phases. The 7 reviewer dimensions ran concurrently, so this exceeds elapsed wall-clock.

Efficiency vs. estimate: ~139.5× (3 points = 24 h of pre-AI effort)

<!-- drones:impact-actual:end -->

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-2134ba22-98cd-44c4-af27-8e14e384f7b9?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-2134ba22-98cd-44c4-af27-8e14e384f7b9&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>

<!-- drones:impact-actual:begin -->

Agent time: 0 m (excludes reviewer) (implementer 0 m · reviewer not measured · addresser 0 m)

<!-- drones:impact-actual:end -->

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-2134ba22-98cd-44c4-af27-8e14e384f7b9?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-2134ba22-98cd-44c4-af27-8e14e384f7b9&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>

<!-- drones:impact-actual:begin -->

Agent time: 7 m (implementer 0 m · reviewer 7 m · addresser 0 m)

Summed across phases. The 4 reviewer dimensions ran concurrently, so this exceeds elapsed wall-clock.

Efficiency vs. estimate: ~205.6× (3 points = 24 h of pre-AI effort)

<!-- drones:impact-actual:end -->

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-2134ba22-98cd-44c4-af27-8e14e384f7b9?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-2134ba22-98cd-44c4-af27-8e14e384f7b9&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>

<!-- drones:impact-actual:begin -->

Agent time: 0 m (excludes reviewer) (implementer 0 m · reviewer not measured · addresser 0 m)

<!-- drones:impact-actual:end -->

## Review Round Completeness

- outcome: indeterminate

- round: 1

- dispatched: 4

- reported: 3

- missing: security-review

- cause: dimension_shortfall

- head: b431ece2e100f5e54e94a9cef2a9de23cc7e24ec

- run: fanout-3701-2026-09-02T22-16-00-252Z

<!-- drones:round-completeness head=b431ece2e100f5e54e94a9cef2a9de23cc7e24ec run=fanout-3701-2026-09-02T22-16-00-252Z -->

An incomplete review round is not a clean round. Do not merge without re-firing review (drones review --pr <N> --post), which re-stamps this section, or an explicit operator override.

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-2134ba22-98cd-44c4-af27-8e14e384f7b9?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-2134ba22-98cd-44c4-af27-8e14e384f7b9&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>