The Trilogy Times

## Summary

- document the weekly application-pace fallback for End-of-Year and Next Year forecasts

- explain aligned-history precedence and program-age comparability rules

- capture seasonal weighting, conversion, and known-only departure behavior

## Validation

- git diff --check

- pre-commit hooks (no applicable code checks for markdown-only change)

This PR documents the forecast behavior introduced in #1742.

## Summary

- remove HubSpot Program Session start/end dates from the modeled staging contract

- make SIS MAIN offering dates canonical in int_program_year, independently of capacity precedence

- retain HubSpot sessions for admissions identity/association while resolving deal and session boundaries through the SIS-backed program year

- update contract coverage and unit tests to pin SIS-owned boundaries

## Validation

- dbt parse

- targeted unit tests will run after the PR schema has been built

- full current-vs-PR forecast comparison is required before this leaves Draft

## Pre-merge data gate

This PR must remain Draft until the PR-schema forecast is compared with the current published forecast. Known source audit findings include one forecast-scope HubSpot-only program-year (NextGen Academy: Austin 2027), five SIS rows with incomplete end dates, and 13 shared rows whose dates differ. The PR will not be marked ready or merged unless the output comparison establishes that current reporting is preserved or those gaps are resolved.

Closes #1772

## Summary

This PR is Phase 1 of 2 for [AERIE-2744: Launch and verify the complete Task Board](https://linear.app/builder-team/issue/AERIE-2744/launch-and-verify-the-complete-task-board), part of the [Human Task Assignment from Aerie project](https://linear.app/builder-team/project/human-task-assignment-from-aerie-b3582376ae6e).

It adds the shared Task engine and data contracts for lifecycle actions, approval and resubmission, assignments, completion history, comments, watchers, documents, permissions, and allowed actions.

Production effect: none of the existing Work Plan, public API, Site Note, or agent entry points switch to these rules in this PR. The Task Board remains unavailable. Phase 2 changes all of those entry points together.

## Why

The complete launch change is too large to review safely as one PR. This first phase establishes the internal foundation without changing existing Task workflows. That avoids a temporary compatibility layer and avoids an intermediate release where old screens call new rules they do not yet understand.

## Business Value

- Establishes one shared Task lifecycle and authorization model for the launch.

- Records assignments, completion attempts, reviews, comments, documents, and watchers consistently.

- Gives callers a calculated list of actions that are valid for each Task.

- Keeps the current production Task workflows unchanged until Phase 2 activates the complete API and agent experience.

- Reduces review and rollout risk by separating the engine from its entry points.

## How does it work

1. Shared modules define Task lifecycle actions, approval, assignment, completion, comments, documents, watchers, and allowed actions.

2. Indexed participant records support bounded My Tasks and authorization queries.

3. Existing production entry points continue using their current behavior while the Task Board launch gate is closed.

4. Phase 2 will switch the Work Plan, public API, Site Notes, and agent tools to this engine together.

## Scope

### Included in this phase

- Canonical Task lifecycle, approval, resubmission, completion history, assignment, document, watcher, and notification contracts.

- Shared Task action availability and metadata authority.

- Bounded participant and completion-history queries.

- Internal data model and migration support needed by the launch.

- Exact final diff paths:

chat/convex/lib/siteDetailAccess.ts
chat/convex/migrations/taskParticipants.ts
chat/convex/rhodes/schema.ts
chat/convex/taskBoard/actionAvailability.ts
chat/convex/taskBoard/approval.test.ts
chat/convex/taskBoard/approval.ts
chat/convex/taskBoard/assignments.test.ts
chat/convex/taskBoard/assignments.ts
chat/convex/taskBoard/auth.ts
chat/convex/taskBoard/completion.ts
chat/convex/taskBoard/completionHistory.ts
chat/convex/taskBoard/documents.ts
chat/convex/taskBoard/lifecycle.test.ts
chat/convex/taskBoard/lifecycle.ts
chat/convex/taskBoard/metadataAuthority.ts
chat/convex/taskBoard/mutations.test.ts
chat/convex/taskBoard/mutations.ts
chat/convex/taskBoard/notifications.test.ts
chat/convex/taskBoard/queries.test.ts
chat/convex/taskBoard/queries.ts
chat/convex/taskBoard/watchers.test.ts

### Deliberately excluded for Phase 2

- Work Plan and Site Note adapter changes.

- Public Task API and agent/DSS activation.

- Immediate Task notification activation.

- My Tasks and Team Tasks UI refresh.

- Task digest delivery and global navigation exposure.

- Rollback-only schema aliases, speculative stale-projection checks, caller-bound cursors, defensive fallbacks, and Mercy-only test changes.

- Automatic account creation, mobile-specific evidence capture, and the other approved V1 non-goals.

## Test plan

### Automated validation

- Legacy Work Plan, Site Note, and agent mutation compatibility: 124/124 passed.

- Focused Task engine, migration, Work Plan, and launch-gate suites: 181/181 passed.

- Full Chat typecheck: passed through the pre-commit check.

- Lint, architecture boundaries, Convex path validation, read bounds, test architecture, knowledge hygiene, and Biome: passed. The two unchanged Sindri placeholder warnings remain.

- git diff --check: passed.

- Exact diff: 21 paths, 732 insertions, 211 deletions, 67,794 raw bytes.

### Time for Implementation

An engineer working without AI assistance would likely need about one week to trace the existing Task surfaces, isolate the shared engine without changing production entry points, and validate the lifecycle and authorization contracts.

Linear: [KLAIR-3594](https://linear.app/builder-team/issue/KLAIR-3594)

First slice of crediting keyless Claude Code spend to the person who incurred it. Read-only and additive: one new view plus tests. fct_ai_spend, its stored procedure and every Klair surface are unchanged, so the People tab and BU dashboards still show this spend on Trilogy-Inc until the next slices.

## Why

Claude Code sessions signed in with an account instead of an API key reach the token feed with a NULL api_key_id. fct_ai_spend carries them as anthropic rows with entity_id NULL on the org's own BU (Trilogy-Inc), which is not a budget BU, so Finance cannot allocate them and no person is charged. Q3 had $155,388 of it, $149,948 from one person.

## What the view does

mart_saas_metrics.v_ai_spend_claude_code_keyless_by_person splits those billed dollars across the people who ran them, per (day, org, model).

- Who: Anthropic's per-user Claude Code report, landed daily by SURTR-1612 (raw_anthropic_claude_code_usage).

- Not everyone in the report is keyless. The report names a person for *all* their Claude Code usage, including sessions billed through their own personal key (Alec Ngai: 3.94B cache reads in the report, 3.96B on his key). So a person's keyless usage is their report usage minus what their own claude_code_key_<name>_<hash> keys already account for, per token type, floored at zero.

- Dollars are the billed keyless amounts already in fct_ai_spend. The report's estimated_cost_usd is never used (it overstated September by about a third); a test pins that. Token counts only decide how the known dollars are shared, using list-price ratios (input 1, output 5, cache read 0.1, cache write 1.25).

- Nothing is lost. What the report cannot explain is emitted as an unattributed row (user_email NULL), so for any date range SUM(keyless_cost_dollars) equals the keyless rows of fct_ai_spend. People never receive more than the pool.

- Pre-tax, like fct_ai_spend; the 6.6% uplift stays in the read layer. Late-binding view with GRANT SELECT TO "MCP_user", like v_ai_spend_anthropic_reconciled.

## Results against production data (query run read-only; the view is not yet created)

| Window | Keyless pool in mart | View total | Attributed | Unattributed | Cells off by > 1 cent |

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

| Q3 (Jul 1 to Sep 30) | $155,388.14 | $155,388.14 | 97.3% | $4,192 | 0 |

| Oct 1 to 8 | $63,783.32 | $63,783.32 | 99.0% | $627 | 0 |

Q3 by person (billed, pre-tax): Lucia Monteverde (Academics) $149,948; Casey Schmid $416; Rohit Kumar $413; Brandon Gee $91; then small amounts. No negative rows.

## Known limits (also in the SQL header)

- A key not named claude_code_key_<local>_<hash> does not count against its owner, so that person can take a share they did not earn. This shows up as the explained ratio drifting; the unattributed row and the verification query below make it visible. The Q3 numbers above show it is small today.

- Two report users with the same email local part on different domains both have that local part's keyed usage subtracted.

- A person's split inside one (day, model) pool ignores context-window mix.

## Testing

- 18 new tests in test_v_ai_spend_claude_code_keyless_by_person.py run the view's real query in SQLite against fixtures (Redshift-only functions shimmed): sole keyless person, fully keyed person gets nothing, shared pools, partial and over-explained reports, per-type subtraction, tie-out per (day, org, model), exclusions (keyed, non-token and non-anthropic rows, api_actor), [1m] suffix, key-name and case handling.

- Mutation-tested: dropping the pool-weight floor, dropping the keyed subtraction, and removing each of the day, org and model joins each fail a test. One join mutation initially survived; the missing test was added.

- ruff check and ruff format at 0.15.22 clean; the whole tests/mart_saas_metrics directory passes (101).

## Applying it (manual, like the other mart objects)

1. Run 024_v_ai_spend_claude_code_keyless_by_person.sql in Redshift. It only creates a view and a grant.

2. Verify with the pool tie-out: SELECT SUM(keyless_cost_dollars) FROM mart_saas_metrics.v_ai_spend_claude_code_keyless_by_person WHERE report_date BETWEEN '2026-07-01' AND '2026-09-30' should return 155,388.14 (the same sum over the keyless rows of fct_ai_spend).

3. Revert: DROP VIEW mart_saas_metrics.v_ai_spend_claude_code_keyless_by_person;

## Next slices (separate PRs, to keep these small)

2. Make fct_ai_spend emit the attributed portion as user-level rows so the People tab credits the person with no Python change.

3. Apply the same split in AICostsService._anthropic_billed_allocation_cte, which the BU dashboard, Budget tab and weekly emails compute separately; without it BU totals stay on Trilogy-Inc while people are credited.

## Business Value

Finance and the budget owners currently cannot see, or charge back, about $155K per quarter of Claude Code spend (about $64K in the first eight days of October alone), which sits on a non-budget business unit and is growing. This view names who incurred it and ties to the bill to the cent, so David Harpur and Sandeep can review and allocate it now through the MCP, ahead of the dashboard changes in the next slices.

## Manual Effort Estimate

About 1.5 days of focused work by hand (working out from live data that the report includes key-billed usage and how to net it out, the SQL, an executable test harness, and validating against the quarter). Keval to confirm or adjust.

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

- Preserve the existing Salesforce Notes_Actions__c value when a resolved pain point has no Grainne resolution reason; continue syncing status, dates, and other canonical fields.

- Keep replacing notes when Grainne supplies a reason, and keep clearing notes when the last comment is removed from an active pain point.

- Cover both current and legacy resolved statuses and the historical dirty-row reconciliation path.

This changes future writebacks only. It does not restore notes cleared during the October 12 backfill.

## Summary

- Migrate Budget Planner chat and auto-fill from retired Claude Sonnet 4 to Claude Sonnet 5.5.

- Use adaptive thinking for chat and native JSON-schema output for structured auto-fill, with Sonnet 5.5 temperature/context handling and existing model fallbacks.

- Update the dormant PR re-review verifier to Sonnet 5.5 and handle thinking/text response blocks.

## Verification

- Ruff format and lint passed for changed Python files.

- Mocked, document-safe unit tests passed: 8 Budget Planner/structured-output tests and 1 re-review test.

- No DEV calls or tests that create or update documents were run.

- Pyright remains nonzero with 20 errors and 31 warnings in the shared typing code; it reports no errors on the changed request settings.

## Summary

- Register Carrollton Sports Academy as an Education business unit in the backend enum and sets, including the Monthly Financial Reporting Education allowlist.

- Add Carrollton Sports Academy to the client Education business unit list.

## Tests

- Backend business-unit sync suite: 96 passed; Ruff and Pyright passed.

- Frontend suite: 676 files passed; 6,936 passed, 16 skipped.

- ESLint, Prettier, TypeScript check, and production build passed.

## Data sync

The Master Mapping row was synced separately to Redshift finance_dw, with a 619-row backup and exact post-sync row reconciliation. This PR contains the application-side code changes only.

## Screenshot

<img width="367" height="581" alt="image" src="https://github.com/user-attachments/assets/98bd54d4-c3cb-4fee-8c94-2780bcf608d9" />

## What changed

- Make Surtr the only Salesforce writer for Action Hub pain-point status, dates, owner, domain, and notes. Remove Klair's direct Salesforce client and fire-and-forget owner writeback instead of retaining two competing writers.

- Persist sf_sync_dirty with the same PostgreSQL mutation when the Klair API changes status, owner, or domain, including owner-only changes. Grainne-managed mode already disables owner/status controls in the Action Hub UI; the API write paths still exist.

- Mark active comment mutations dirty transactionally in both V1 and V2 routes. Resolved comments do not alter resolved Salesforce notes. The Surtr pull sends an empty note value when the last active comment is deleted.

- Keep the Action Hub lifecycle status constants with its model instead of the deleted Salesforce utility.

## Rollout

Deploy [Surtr #2153](https://github.com/AI-Builder-Team/Surtr/pull/2153) before this cutover so every dirty row has a writer. Surtr authenticates with sf-raw-sync/credentials, sends one canonical PATCH, and retains failed writes for retry. Historical resolved rows receive a manual production backfill only after deployment; no backfill write has run. The 52 PostgreSQL/Grainne status conflicts found in the read-only inventory remain excluded pending separate reconciliation.

## Review and validation

- Owner-only fire-and-forget writes lacked durable retries; fixed by removing Klair's direct Salesforce write and marking API-side owner changes dirty in their PostgreSQL transaction.

- Added focused tests for the resolved guard, V2 add/delete, delete-by-anchor, last-comment deletion, and rollback if dirty marking fails.

- 71 focused tests pass; Ruff check/format pass; Pyright reports 0 errors and 0 warnings on modified files. A broader router test needs Zendesk and Google Sheets credentials just to collect, so it is not included in this local count.

## What changed

- Persist Grainne's structured resolution_reason in action_hub.pain_points.grainne_resolution_reason on each successful detail fetch, including unchanged activity watermarks. The PostgreSQL migration is in the existing renewal-action-hub/scripts/ddl location and has already been applied in production; pipeline startup checks for it.

- Reconcile Salesforce pain-point status, dates, owner, domain, and Notes_Actions__c from a locked PostgreSQL row in one PATCH. Failed writes leave sf_sync_dirty set for retry. Reopened points clear stale close dates.

- Resolved notes replace comments and old Salesforce notes with the full stored Grainne reason, clipped only for Salesforce's rich-text limit. Missing reasons clear resolved notes. Active notes mirror comments, including an empty value when the last comment is deleted.

- Authenticate to Trilogy Salesforce with the working OAuth credentials in sf-raw-sync/credentials and grant the runner permission to read that secret. The expired password in ENV_API_PROD is no longer used for Salesforce.

- Add scripts/backfill_resolution_reasons.py: read-only by default, optional bounded --pain-point-id pilot, explicit --apply, committed reason+dirty state before any remote PATCH, and skipped-status/orphan reporting.

## Rollout and backfill

Deploy this writer before [Klair #3858](https://github.com/AI-Builder-Team/Klair/pull/3858). The hourly seven-day terminal polling cutoff stays intact; backfill older resolved rows manually *after* deployment. The read-only inventory found 318 PostgreSQL closed-resolved points: Grainne still considers 266 resolved (131 with a reason, 135 without); 52 have conflicting statuses and are excluded. No production backfill writes have run.

The backfill's row lock starts before its Grainne GET, but the hourly pull's GET starts before its row lock. Deployment alone does not guarantee that an overlapping pull cannot later apply an older fetched reason. The documented safe apply sequence stops both pull triggers, waits for running executions to drain, runs a pilot and the batch, then resumes them. A read-only inventory needs no pause. The 52 conflicting-status rows need separate lifecycle reconciliation.

## Review and validation

- The prior append-footer approach was withdrawn: resolved notes are replacement values, and later resolved-comment edits do not rewrite them.

- The migration-location review claim conflates PostgreSQL with Redshift pipelines/cdk/sql; the existing Action Hub PostgreSQL migrations reside alongside this migration. I replied in the review thread with the repository evidence.

- Grainne-pull tests: 153 passed; Ruff 0.15.22 check pipelines and format --check pipelines pass; git diff --check passes.

Linear: [SURTR-1615](https://linear.app/builder-team/issue/SURTR-1615)

Second of two stacked PRs for ai-spend-reconciliation; based on [1/2] (SURTR-1613). This one adds pipeline.json, so merging it deploys the job.

## What changed

- handler.py: for the month just closed (or params.month), runs the three checks and emails the result. Writes nothing to the warehouse.

- report.py: the HTML email. One section per check with counts compared, then anything that could not be checked.

- ses_email.py: SES send_email from noreply@klair.ai.

- pipeline.json: cron(0 8 5 * ? *) (5th of the month, 08:00 UTC), 900 s, 512 MB. IAM: the two existing vendor-key secrets, Redshift Data API (no BatchExecuteStatement; it only reads), ses:SendEmail on the klair.ai identity.

- owners.json.

## Behaviour worth checking

- Findings are not failures. A run that completes and finds problems returns success; the findings are in the email and the returned summary. The platform's red or amber card is reserved for the job itself breaking.

- An org that cannot be read is "not checked". Its warehouse spend is not then reported as a mismatch. The run returns partial_failure. If no vendor org can be read at all, the run raises and sends nothing.

- The email goes out every month, including a clean one, so silence never means "it did not run".

- Recipients are validated before any vendor call. They are keval.shah@trilogy.com only for now, to be widened once the first report has been reviewed.

- RECON_KNOWN_STOPPED is seeded with cursor:28316805. That is the Alpha AI Interns team. Cursor's own API returns zero events for it after 2026-08-25, so it stopped; without the entry it would be flagged every month it is compared.

- Alarm threshold is 1, not 2: the job runs once a month, so waiting for a second failure means waiting a month.

## September 2026 dry run (live APIs and Redshift, email off)

| | Provider | Org | Warehouse | Vendor today | Difference |

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

| Note | anthropic | DevFactory | $712,484 | $737,702 | -$25,218 (-3.4%), 21 days |

| Note | anthropic | Trilogy-Inc | $2,393,680 | $2,376,215 | +$17,465 (+0.7%), 2 days |

| Note | openai | Trilogy-Academics | $226,883 | $231,780 | -$4,897 (-2.1%), 1 day |

| Note | anthropic | Trilogy-ASM-Beta | $56,827 | $58,442 | -$1,615 (-2.8%), 21 days |

| Note | anthropic | Trilogy P2 | $161,956 | $160,614 | +$1,342 (+0.8%), 1 day |

| Note | anthropic | IgniteTech | $23,220 | $24,282 | -$1,062 (-4.4%), 21 days |

| Flag | anthropic | Trilogy-Superbuilders | $0 | $20,563 the month before | went quiet |

| Flag | cursor | 28316805 | $0 | $321,743 the month before | went quiet (now listed as known stopped) |

All four mart-vs-feed comparisons tied. 26 of 28 OpenAI orgs matched the vendor within $1.

## Testing

- uv run pytest: 64 passed.

- ruff check and ruff format --check at 0.15.22: clean.

- npx jest test/real-pipeline-configs.test.ts: 606 passed, including the new pipeline.json.

- Not tested: the SES send. The dry run rendered the report but did not send it.

## After merge

- [ ] Invoke once with {"params": {"month": "2026-09"}} and run_options.skip_failure_notification: true; review the email.

- [ ] Widen RECON_EMAIL_RECIPIENTS.

## Business Value

Gives Finance and the budget owners a standing monthly statement of where AI spend in Klair disagrees with what the vendors billed, without anyone reconciling by hand. It answers David Harpur's request of 2026-10-07 on the Q4 budget thread.

## Manual Effort Estimate

About 1 day of focused work by hand for this half (handler, report, email, config and tests). Keval to confirm or adjust.

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

Linear: [SURTR-1613](https://linear.app/builder-team/issue/SURTR-1613)

First of two stacked PRs for a monthly ai-spend-reconciliation job. No pipeline.json here, so nothing deploys; [2/2] adds the report email, handler and schedule.

## Why

David Harpur asked for an automated monthly check after Ravi's manual reconciliation caught three material errors in one cycle: a dashboard filter that dropped spend, a $2.79M org double-count, and a $144K gap in the Cursor feed.

## Why this is not "computed vs billed at 5%"

That was the literal ask. It would fire for every org every month. September, from the warehouse:

| Org | Billed | Token-price estimate | Gap |

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

| Anthropic, Trilogy-Inc | $2,393,680 | $2,992,651 | +25.0% |

| Anthropic, DevFactory | $712,484 | $914,027 | +28.3% |

| OpenAI, Central Support | $1,284,488 | $1,010,254 | -21.3% |

The estimate is list price; the bill has discounts and restatements. Klair reports the bill for that reason. None of the three errors above was an estimate-vs-bill gap either.

## What it checks instead (checks.py, pure functions)

1. vendor_vs_warehouse: the stored billed feed (raw_anthropic_cost_reports, raw_openai_cost_reports) against the vendor's billing API fetched at check time, per org. Flags a month more than 5% and $50 apart, and warehouse spend for an org with no admin key. A gap under 5% but over $1,000 is listed as a note. Names the days that differ.

2. mart_vs_feed: mart_saas_metrics.fct_ai_spend against the feed it is built from, for Anthropic, OpenAI (less TrueFoundry-routed spend), Cursor and Perplexity. These tie to the dollar today, so any gap over $1 is a flag.

3. coverage: an org or team with at least $1,000 the month before and nothing this month, unless listed as known stopped.

vendor_clients.py asks each API for daily totals only (no group_by), so a month is one or two requests per key. warehouse.py is read-only (Redshift Data API).

## Not covered

- Feed vs invoice for Cursor, Perplexity and Claude.ai seats. They have no independent billing API and there is no invoice data in the warehouse. This is the check that would have caught the Cursor gap; it needs Finance to supply monthly totals and is left for a follow-up.

- The Klair dashboard's own totals (the filter bug). That is covered by Klair's tests, not here.

## Testing

- uv run pytest: 39 tests for this PR's modules (64 with [2/2]).

- ruff check and ruff format --check at 0.15.22: clean.

- Dry run for September 2026 against the live APIs and Redshift, email off: 40 vendor orgs compared, none unreadable, 2 flags and 6 notes. See [2/2] for the findings.

## Business Value

Replaces a manual month-end reconciliation that Finance was relying on to catch six-figure errors in AI spend reporting. The first dry run already found about $28K of September Anthropic spend missing from the warehouse across three orgs because the vendor restated earlier days after they were ingested.

## Manual Effort Estimate

About 1.5 days of focused work by hand for this half (working out which comparisons are meaningful against live data, two vendor clients, queries, checks and tests). Keval to confirm or adjust.

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

Linear: [SURTR-1614](https://linear.app/builder-team/issue/SURTR-1614)

Second of two stacked PRs for claude-code-usage-pipeline; based on [1/2] (SURTR-1612). This one adds pipeline.json, so merging it deploys the pipeline.

## What changed

- redshift_handler.py: replaces the fetched (bu, usage_date) windows in one Data API transaction (delete, then insert). Zero-row windows are deleted too so a day that drops to empty converges. Every row must belong to an owned window.

- ledger.py: S3 payload objects plus a closing manifest under an attempt-unique prefix, and one ingestion_ledger row pointing at the manifest. Copied per pipeline by convention.

- handler.py: every org in Anthropic-Usage-Keys (or params.bus_to_process), trailing 7 days ending yesterday by default.

- pipeline.json: daily cron(0 6 * * ? *), 600 s, 512 MB. IAM is the existing secret, Redshift Data API and s3:PutObject on this pipeline's raw-payload prefix.

- owners.json: same two owners as the other AI-spend pipelines.

## Behaviour worth checking

- Failure handling. A (BU, day) whose fetch or validation fails is not owned, so its existing rows are left alone, and the run returns partial_failure. If nothing could be fetched, the run raises before S3, Redshift or the ledger are touched.

- Evidence first. The original responses and manifest are written to S3 before the load.

- Ledger is a separate statement from the load. If the ledger insert fails after the load commits, the run fails and the next run converges the same windows. This matches claude-ai-chat-usage-pipeline; it is not the single-transaction pattern Perplexity uses.

- No writer mutex. Two overlapping runs (cron plus a manual backfill over the same days) are each atomic, but the later one wins. Same as the other Data API pipelines.

- Several keys for one org are not double-counted. If a BU holds more than one admin key and two return the same organization_id for a day, the second is skipped.

- Transaction cap. One run is capped at 40 statements; beyond that it raises before writing. At 300 rows per insert a month of all orgs fits (about 30 statements), so backfill runs month by month.

## Testing

- uv run pytest in the runner: 75 passed.

- ruff check and ruff format --check at 0.15.22: clean.

- npx jest test/real-pipeline-configs.test.ts: 606 passed, including the new pipeline.json.

- Not run: the loader against Redshift. The table does not exist yet, so the first real write is the backfill below.

## Before merge

- [ ] DDL from [1/2] applied to Redshift. Without it the first scheduled run fails.

## After merge

- [ ] Backfill 2026-07-01 onward, one month per invocation, with run_options.skip_failure_notification: true.

- [ ] Check row counts against the dry run in [1/2] (19,097 rows through 2026-10-08).

## Business Value

Makes the per-user Claude Code feed land daily without anyone running a script. That is what turns the one-off list sent to David Harpur on 2026-10-07 into a standing attribution of keyless Claude Code spend to people and business units in Klair.

## Manual Effort Estimate

About 1.5 days of focused work by hand for this half (loader, ledger, handler, config and tests). Keval to confirm or adjust.

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

## Summary

- Add mart_education.vw_revenue_recognition_school_year_exceptions_current for unresolved postings in the latest complete Q118 publication.

- Document the current-only grain, available lineage, privacy boundary, and the fact that assignments and candidate-year records are not retained by this view.

- Record that the view DDL is deployed and Finance verified the production output. Reader grants are separate from the view DDL.

## Production verification

- Canonical DDL apply completed: 23/23 statements; existing table and procedure DDL matched production.

- Read-only query of the view returned 82 rows: 23 ambiguous and 59 unmatched, totaling $145,374.47 signed.

- SELECT granted to the existing edu_read role and team_engineers group; no PUBLIC grant.

## Validation

- git diff --check

- Tests not run.

## Summary

- Lock Due Diligence fields and scenarios when M2 Conducting Diligence is completed; reopening M2 restores editing.

- Add an explicit emergency override capability while preserving existing write and approval permissions.

- Show a compact lock indicator with an accessible tooltip and enforce the rule on submission and approval across UI, API, and MCP.

## Why

[AERIE-2808](https://linear.app/builder-team/issue/AERIE-2808) implements the DD canary for the forward-facing editing lock project. Completed diligence should remain stable, including when an older proposal reaches approval after M2 completes.

## Business Value

Users can see when diligence is locked, while explicitly authorized operators can make emergency changes without reopening the milestone.

## Test plan

- [x] Full CI green at 52da69ca8; Chat: 12,256 tests passed, 18 skips across 816 files.

- [x] 449 focused tests passed; 17 existing DD skips. Submission, approval, scenario operations, override permissions, and UI states use isolated mocks.

- [x] Workspace typecheck, changed-file Biome, architecture, Convex, testing, and knowledge checks.

- [x] Read-only localhost inspection of completed M2, lock tooltip, collapsed card, and scenario tabs. No DD save, approval, upstream writeback, milestone change, or capability grant.

CI also exposed two role-editor test fixtures using the old grant count and omitting Admin grants; corrected both and verified override remains ungranted for ordinary editors. All 18 role-editor tests pass.

Seven independent review lanes completed; fixed the approval timing gap with a fresh authority check after the metadata GET and a deferred-GET regression test asserting zero POSTs.

UI preview: compact 14px lock in a 24px container; reason appears in the Radix tooltip.

Validation limitation: the current lifecycle and actor authority are checked immediately before REBL3 dispatch. Convex milestone changes and external REBL3 writes are not atomic; this canary does not cancel an already dispatched write. Mercy raised this distributed timing limit; the response records why broader milestone serialization or a conditional upstream protocol is outside scope.

## Summary

- Promote School Ontology to top-level desktop and mobile navigation, preserving old School Identity links.

- Separate read access, School management, and editing grants for Program, Site, QuickBooks, SIS, and Finalsite mappings.

- Record mapping and School lifecycle changes and expose a paginated change history with resilient error handling.

## Why

[AERIE-2303](https://linear.app/builder-team/issue/AERIE-2303/promote-school-identity-to-a-top-level-school-ontology-page) makes School identity and source relationships directly accessible instead of hiding them under Admin. Mapping changes need explicit source permissions and a mandatory audit trail.

## Business Value

Users can inspect all School relationships from one place, while editors can maintain only the source systems they are authorized to change. Recorded changes make ownership and corrections traceable.

## Test plan

- [x] 248 focused UI/backend/access tests and 1,356 contracts tests.

- [x] Chat and Convex typechecks; formatting and architecture checks.

- [x] Local browser: desktop/mobile layout, search, source picker, create/rename/archive dialogs, and change history.

- [x] Browser smoke left real School relationships unchanged.

- [x] Seven-lane adversarial review; resolved read-only confidence, guidance, and contribution history findings.

- [x] All required CI checks on e035856c2; 17,602 tests passed and 18 skipped.

- [x] Mercy approved latest head e035856c2; all threads resolved. Optional additional coverage suggestions evaluated with evidence in the review reply.

Historical Program/Site and School lifecycle changes were not recorded before this change; the history UI states that limitation. Legacy School Identity grants expand to the equivalent new grants.


## Summary

- Supply exact signed packet identifiers so scheduled triage can retrieve its assigned evidence.

- Allow actionable internal Diagnostics evidence in tickets; retain targeted credential detection and reject diagnostic placeholders.

- Align intake and handoff instructions with the assigned class and verified receipt workflow.

## Why

Scheduled runs repeatedly failed because publication treated nearly every string in a Diagnostics packet as forbidden, including ordinary technical vocabulary needed to explain the error. Forced paraphrasing obscured useful findings and exhausted retries. This internal tool must produce actionable remediation work, while preserving correct-class, current-revision, duplicate-safe and verified-receipt boundaries.

## Business Value

Enables useful internal error triage without forcing the agent to conceal the technical facts engineers need to diagnose and fix failures.

## Breaking changes

Internal ticket content may now include relevant diagnostic messages, identifiers and contact references. Blanket packet-text, email and request/session identifier bans are removed under operator direction; credential patterns remain blocked.

## Test plan

- [x] 90 worker tests; regressions allow internal diagnostic evidence and continue rejecting credential patterns.

- [x] Typecheck, focused Biome, production build.

- [x] Bounded handoff on worker 84440f9b-f384-418e-b962-d7f0d9498dbe, source 3bedb48f9: run x58cmhtcgnfw33f2v5st8p047n8fz0kt created #1782 on first publication attempt, exact receipt recorded, class acknowledged. 121 seconds, estimated $0.658. No publication refusals.

- [ ] Fresh CI/review and successful unattended execution before operational closeout.

Scheduling was paused during the canary and restored after receipt verification; first unattended run on this revision remains monitored. Earlier canaries verified creation (#1779) and adoption (#1104), but the subsequent hourly run failed blanket publication checks; these earlier successes do not validate the revised publication policy.

## Summary

Documents that GET /v2/portfolio/sites spends limit on Sites before the status filter runs, so a page can hold fewer Sites than limit while hasMore is true. Fixes [AERIE-2693](https://linear.app/builder-team/issue/AERIE-2693).

## Why it's needed

Arthur's DSS reader asked for limit=100 and got 45 active Sites back with hasMore: true. With no parameters, it got 13 of the default 25. The served dictionary and enablement say the default status is active, but neither says the page limit is counted before that filter. A reader who treats one page as the active count undercounts, and at least one integration has already hit this.

This order is deliberate: listPortfolioSitesPage pages one stable source stream and applies the canonical status after the read, so cursors don't skip or repeat rows while stored statuses normalize. The fix documents the order and doesn't change it. lifecycleStage filters through the index before paging, so the trap only applies to status.

## Changes

- portfolio.site dictionary, status field: new trap. It says limit counts Sites before the status filter, including the implicit active default, and that callers should follow nextCursor until hasMore is false. One page's length isn't a count.

- portfolio.find-site enablement workflow: handling.emptyResult now says the same about short pages.

- Test asserting both sentences are served.

## Breaking changes

None. The change is documentation only, and response behavior is unchanged.

## Test plan

- [x] npx vitest run lib/public-api (184 pass). The one failure, skill-package.node.test.ts (827c90c9 vs 50674b22), is the known local CRLF checkout artifact and fails identically on main.

- [x] Pre-commit biome + typecheck-chat

- [ ] CI

Linear: [SURTR-1612](https://linear.app/builder-team/issue/SURTR-1612)

First of two stacked PRs for a new claude-code-usage-pipeline. No pipeline.json here, so nothing deploys from this PR; [2/2] adds the loader, handler and schedule.

## Why

Claude Code sessions signed in with an account instead of an API key reach raw_anthropic_token_usage with a NULL api_key_id. With no key there is no owner, so the spend lands on the org's own BU (Trilogy-Inc), which is not a budget BU. In Q3 that was about $151K on Trilogy-Inc, $148K of it one person.

Anthropic's Claude Code usage report (GET /v1/organizations/usage_report/claude_code) is the only source that names the user behind those sessions. Nothing in Surtr reads it today.

## What changed

- DDL pipelines/cdk/sql/staging_finance_ai_spend/raw_anthropic_claude_code_usage.sql: one row per (usage_date, bu, actor, customer_type, subscription_type, terminal_type, is_remote, model). bu is the same org key the other Anthropic tables carry.

- aws_secrets.py: reads the existing Anthropic-Usage-Keys map (no new secret). Fails loud on an empty map or a BU with no usable key.

- claude_code_client.py: pages one UTC day (the endpoint rejects ending_at) and explodes each record's model_breakdown into rows.

## Things a reviewer should know

- estimated_cost_usd is not spend. It is Anthropic's list-price estimate and overstated September on Trilogy-Inc by about a third against the cost report. It is stored so the mart can use it as a weight to split the *billed* no-key amount. The table comment says so.

- model is stored as reported, including the [1m] context suffix, to keep the raw table source-faithful. Consumers strip it before joining.

- A user_actor is not necessarily keyless. Most also bill through a personal claude_code_key_<name> key the same day. Deciding who is keyless is the mart's job (Klair), not this table's.

- The client raises, and so fails that day, on: a 200 without a data list, has_more without next_page, more than 50 pages, a record dated for another day, an unnamed actor, a non-USD amount, or two records on the same grain. Session, lines-of-code and tool-action counts are per actor-day, not per model, so they stay in the S3 payload only.

## Testing

- uv run pytest in the runner: 34 tests for this PR's modules (75 with [2/2]).

- ruff check and ruff format --check at the pinned 0.15.22: clean.

- Dry run of the client against the live API: all 12 orgs in the secret, 2026-07-01 to 2026-10-08, 1,200 org-days, 0 errors, 19,097 rows. All 12 orgs answer the endpoint; seven return data.

## Before merge

- [ ] Apply the DDL to Redshift (not applied by CDK). It is additive.

## Business Value

Finance cannot allocate keyless Claude Code spend to a budget today; it sits on a non-budget BU and is growing (about $55K in one September week). This table is the input that lets Klair charge that spend to the person and business unit that incurred it, which David Harpur and Sandeep asked for on the Q4 budget thread.

## Manual Effort Estimate

About 1 day of focused work by hand for this half (API discovery against the live endpoint, DDL, client and tests). Keval to confirm or adjust.

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

## Summary

A stored buildout or milestone date that isn't a date (e.g. the literal string "null") now projects as null instead of returning 503 for the whole site. That unblocks GET /buildout, GET /buildout/phases, GET /buildout/milestones and PATCH /buildout for affected sites. Fixes [AERIE-2333](https://linear.app/builder-team/issue/AERIE-2333).

## Why it's needed

The v2 projection threw on any unparseable stored date, and the handler turned that into 503 buildout_data_unavailable (or milestone_data_unavailable). One bad M4–M10 date therefore took down every buildout read for the site. PATCH /buildout computes its If-Match revision through the same projection, so API writes to that site stopped too, even when the write had nothing to do with the bad field. Dev has two such sites (1704-dorothy-pl-nashville-tn, 307-southgate-ct-brentwood-tn). Production has none today, so this is a latent robustness fix, not an outage.

## Changes

- packages/contracts/src/public-api-lifecycle-buildout.ts: milestone dueDate/completedDate and phase furnishingBeginDate/finalInspectionPassedDate read tolerantly. A value that doesn't parse projects as null. This matches how the file already treats legacy TCO values ("tolerant reads, strict writes"). An invalid milestone status still returns 503; only dates degrade.

- Dictionary (lifecycle-property.ts): the dueDate and completedDate null meanings now also say "or the stored value is not a valid date". No new response fields.

- Write side: no code change was needed. Every milestone date write already rejects non-date strings: buildPhaseMilestonePatch for phase-stored M4–M10 (since #1458), normalizeMilestonePatch for site-level M1–M3, the dashboard editor, and the v2 milestone endpoints. I added a test pinning the literal "null" rejection.

- Tests:

- contracts unit tests now expect null where they used to expect a throw;

- a new projection test mixes one bad date with good ones;

- a new Convex HTTP test covers all four endpoints on a site with a "null" milestone date;

- the HTTP test for an invalid furnishingBeginDate now expects 200 with null, replacing the 503.

## Not included

The ticket also lists a one-off cleanup of the existing literal "null" strings. Those only exist on dev, and this change makes them harmless, so I didn't add a data migration.

## Breaking changes

Clients that relied on a 503 to detect bad stored dates will now get 200 with null for those fields. Nothing else changes.

## Test plan

- [x] packages/contracts: npx vitest run (1356 pass)

- [x] chat: npx vitest run lib/public-api convex/publicApi (713 pass). The one failure, skill-package.node.test.ts (827c90c9 vs 50674b22), is the known local CRLF checkout artifact and fails identically on main.

- [x] Confirmed the two new or changed HTTP tests fail against main's projection

- [x] Pre-commit biome + typecheck-chat

- [ ] CI

## Summary

- aggregate admissions marketing events by source event ID instead of display name

- carry event IDs through atomic snapshot publication, resource refs, dashboard row keys, consistency checks, and attendee queries

- retain additive legacy fallbacks while replacing stale name-keyed materializations on the next refresh

## Validation

- pnpm --dir sync exec vitest run src/analytics/queries/educrm.test.ts src/analytics/queries/admissions-marketing-gateway.test.ts src/analytics/admissions/marketing-events-refresh.test.ts src/analytics/admissions/per-program-refresh.test.ts --maxWorkers=1

- pnpm --dir chat exec vitest run convex/marketingEventContactSnapshots.test.ts --maxWorkers=1

- pnpm --dir chat run typecheck

- pre-commit Sync + Chat typechecks and Biome

- pnpm lint:test-architecture

- pnpm lint:read-bounds

Closes #1764

Linear: AI-985

## What changed

Adds one worked example to the enablement guide: "Is the school operating, and from where".

In JC Fischer's boundary test (2026-10-08), three cold agents answered the Fort Worth question correctly but in words that misled the reader: "candidate operating flag false" on Fort Worth's backup record was read as "Keller is not operating". Keller is open in its own building; the flag means Fort Worth is not confirmed as running from Keller. Colin Guilfoyle's ask: a correct answer should not leave ambiguity, and should list what it can see and say why something is not visible.

The example tells a reader to:

- read the site's own state (opening is the own building, operation is anywhere, with its source);

- read each linked backup for three things: chosen or not, whether the contract covers today (available, not occupied), and whether Edu Ops has confirmed the site is running there;

- read the hosting school separately when the backup is itself a school, and report it as that school's state;

- answer in four parts: what Rhodes shows, why, separately, and what is not recorded.

It also states that only one backup can be confirmed as operating per site at a time.

Dictionary, contract, routes and behaviour are unchanged.

## Verification

- A cold agent given JC's exact question with this guide answered in 8 calls: own building not open; one backup linked at Keller with a lease covering today, available but not confirmed in use; no other backup linked; and, separately, Keller is a school in its own right and is open. That is the distinction the first run missed.

- pnpm check passes (50 tests), including the check that every cited route is published.

## Business Value

The operations lead who owns Rhodes could not tell from the answer whether a live school was operating. An answer that is right but misread costs the same as a wrong one. This makes the most-asked operating question come back in a form that cannot be misread.

## Manual Effort Estimate

About 2 hours by hand. Proposed figure; Keval to confirm or adjust.

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

## Summary

[AERIE-2337](https://linear.app/builder-team/issue/AERIE-2337): GET /v2/admissions/pipeline and GET /v2/admissions/pipeline/records now return 400 invalid_query_parameter when schoolYears contains a value that isn't one of the published school years, instead of a 200 with quietly different totals. The message names the unknown values and lists the available years.

## Why it's needed

On prod and dev, schoolYears=garbage, 2026 or 1999-2000 returned 200, and only year-less (lead) rows matched, so a typo gave a plausible but wrong answer (23,791 vs 27,820 on dev).

## Changes

- chat/convex/publicApi/v2/domains/admissions.ts: shared assertPublishedSchoolYears. getAdmissionsPipeline checks against the matrix's availableYears (all published years, independent of the filter); listAdmissionsPipelineRecords checks against the same list.

- chat/convex/admissions/dashboards/admissionsPipeline.ts: distinctSchoolYears helper; the API-only records query returns availableYears when the caller filters by year (one extra read of the published rollup, skipped otherwise).

Notes:

- I validated against the published vocabulary rather than an OpenAPI pattern: Finalsite years are 2026-2027, while other rows and fixtures use 2026, so a single pattern would be wrong for one of them.

- Uses the domain's existing invalid_query_parameter code rather than the invalid_parameter named in the ticket, to match every other Admissions 400.

- When nothing is published yet, the request still returns the existing no_published_data partial response.

## Breaking changes

Requests with unknown schoolYears values now get a 400 instead of a misleading 200.

## Test plan

- [x] garbage, 1999-2000 and the mixed list 2026,garbage each return 400 naming the unknown value and listing 2026, on both the aggregate and records endpoints.

- [x] schoolYears=2026 still returns 200 with the same body on both.

- [x] convex/publicApi/v2/admissions.test.ts: 45 passed; with the dashboards suites, 134 passed.

- [x] Biome and pnpm typecheck (pre-commit) clean.

## Summary

[AERIE-2339](https://linear.app/builder-team/issue/AERIE-2339): profile.capacity.entries[] is now always in phase order (Phase 1, Phase 2, then additional phases in stored order). It used to be sorted by startDate with nulls last, so when Phase 1 had no M5 date, Phase 2 came first (15 of 171 prod sites).

## Why it's needed

Clients and agents that read entries[0] as Phase 1, or assume phase order, misread capacity on those sites. It happens more often since #1467 removed Phase 1's fallback date.

## Changes

- packages/contracts/src/site-capacity.ts: siteCapacityEntries already builds entries in phase order; the date sort is removed.

- chat/lib/public-api/v2/domains/portfolio.ts: the PortfolioSiteCapacity.entries schema and the portfolio agent guidance (DSS) document the ordering and say to identify phases by id.

current is unaffected: deriveSiteCapacity already picks the latest completed phase by phase order, not array position. No internal caller reads entries by position; the order only reaches the v2 API (portfolio and site profile) and the Rhodes MCP output.

## Breaking changes

Entry order changes for sites where a later phase has an earlier (or the only) start date. The order now matches the documented phase order.

## Test plan

- [x] New contract test: Phase 1 without a date, Phase 2 and two additional phases with and without dates come out as phase1, phase2, gym, annex.

- [x] Contract site-capacity tests: 13 passed.

- [x] Capacity-related chat suites (v2 portfolio/site profile, Rhodes, lib/public-api): 701 passed. The one local failure is the skill-version hash test, which only fails on Windows checkouts with CRLF line endings and passes in CI.

- [x] Biome and pnpm typecheck (pre-commit) clean.

## Summary

[AERIE-2318](https://linear.app/builder-team/issue/AERIE-2318): the v2 funnel enrollment lists hand out encrypted adc1_ cursors that are often longer than 512 characters, then reject them with 400 invalid_cursor ("cursor must not exceed 512 characters"). Clients only ever saw page 1 while hasMore said true.

Both listAdmissionsEstablishedFunnelEnrollments and listAdmissionsCommunityFunnelEnrollments now accept cursors up to 6,144 characters, the same bound portfolio already uses. The OpenAPI cursor.maxLength follows automatically.

## Why it's needed

API and agent callers couldn't get past the first page of a funnel enrollment drill-down. It's a 4xx, so error monitoring never flagged it. Reproduced on prod during the release #1448 smoke.

## Changes

- chat/lib/public-api/v2/domains/admissions.ts: resourceOperation takes an optional cursorMaxLength; both funnel enrollment operations set it to ADMISSIONS_FUNNEL_ENROLLMENT_CURSOR_MAX_LENGTH (6,144). The decoder caps the wrapped Convex cursor at 4,096 characters, which encrypts to about 5,700.

Notes:

- Community uses the same encoder with a raw Convex cursor, so it had the same risk even though it happened to stay under 512 in the original smoke.

- listAdmissionsEnrollmentStudents, the other user of this encoder, wraps a short {afterContactId, generation} payload (about 300 characters), so it stays on the default 512.

## Breaking changes

None. The published cursor.maxLength grows from 512 to 6,144 on the two operations.

## Test plan

- [x] Established funnel: walks two pages with limit=1 using the returned nextCursor verbatim. Without the fix the second request returns 400 (test fails); with it, both rows come back.

- [x] A 5,600-character cursor reaches the decoder (Use a cursor returned by this Admissions operation…); one over 6,144 still gets the length error.

- [x] convex/publicApi/v2/admissions.test.ts and lib/public-api suites pass. The one local failure is the skill-version hash test, which only fails on Windows checkouts with CRLF line endings and passes in CI.

- [x] Biome and pnpm typecheck (pre-commit) clean.

## Summary

[AERIE-2756](https://linear.app/builder-team/issue/AERIE-2756): when a public API request has no Authorization header but does send x-api-key, the 401 now says: "Send the API key as Authorization: Bearer <key>. The x-api-key header isn't supported."

The error code stays missing_authorization, and requests without either header get the same message as before.

## Why it's needed

Austin Ray's team called the v2 documents endpoints with x-api-key and got "Missing Authorization bearer token", which sent them looking in the wrong place.

## Changes

- chat/convex/publicApi/apiKeyAuth.ts: new publicApiMissingAuthorizationMessage(request), used by the v2 auth path.

- chat/convex/publicApi/http.ts: the v1 auth path uses the same helper.

The internal diagnostics endpoint keeps its own message.

## Breaking changes

None. Same status and error code; only the message text changes, and only for x-api-key callers.

## Test plan

- [x] v2 (/v2/meta): no headers returns the original message in detail; x-api-key only returns the new hint.

- [x] v1 (/v1/admissions/enrollments): same two cases in error.message.

- [x] convex/publicApi/http.test.ts and convex/publicApi/v2/http.test.ts: 61 tests passed.

- [x] Biome and pnpm typecheck (pre-commit) clean.

## Summary

- Keep CF COGS, CF Expenses, and Core Allocation out of line-level commentary inputs while preserving official report rows and totals.

- Supply variable-only COGS and expense totals for pacing analysis.

- Reject allocation references/treatment and all-in cost pacing against elapsed days; retry invalid model narratives and keep the deterministic fallback aligned.

## Review documents

Generated locally with the updated code for Q4 FY2026 W1 through October 8:

- [Crossover](https://docs.google.com/document/d/1yaNaOMhgGDdVlQ2eQ-eRzQVo7f9fB6Tm3uO0flgpDp8/edit)

- [Central Support](https://docs.google.com/document/d/15knGbVx_Awv2SjEbk6sI70cIX6RRdzJgy7XvRcStw1c/edit)

- [WS Engineering](https://docs.google.com/document/d/1xonyYQFg5MD9Ye_HGXSb2qWmCdXRD8F_Gs1wytZmmEc/edit)

These have been reviewed and approved by the stakeholder.

## Verification

- PYTHONPATH=. uv run pytest --import-mode=importlib tests/monthly_qtd_report/ -q — 955 passed, 7 deselected.

- Ruff 0.15.22 check — passed.

- uv run pyright services/monthly_qtd_report/commentary.py services/monthly_qtd_report/presentation.py — 0 errors.

## Summary

- Enable platform on-demand runs for Q118 while preserving the scheduled 16:30 UTC readiness check.

- Update the pipeline contract assertion and operator documentation; the production gate changes after deployment.

## Validation

- uv sync --all-extras

- uv run pytest — 123 passed in 0.26s, including the pipeline contract tests.

- git diff --check

- Tests used local fixtures and mocks; no production AWS or Redshift calls were made.

Linear: AI-984

## What changed

Fixes for the findings the DSS registry filed on our feedback intake (2026-10-07 and 2026-10-08) that can be fixed in this service.

Contract (0.3.2 → 0.3.3)

- Refreshed from upstream. The utilities card's ninth block, fire_alarm_monitoring, is now declared.

- Errors are described as served. Every operation now declares this service's own 401 {error: unauthorized} and 502 {error: upstream_unavailable}, and no longer declares 403, which this service never returns. The preface explains the two error shapes (problem details relayed from the system of record; {error} from this service) and what 409, 422 and 503 mean here.

- The site document search now declares the 2,000 code point query bound that the relay already enforces on both searches.

- Rate limits are described as shared by all callers, not per key. X-RateLimit-Limit / X-RateLimit-Remaining are documented.

- The upstream platform's own skill-version header was declared on every response and sent on none; it is removed.

Enablement

- New section "Questions Rhodes answers": what the source is good for and not, ten business question types with the reads to use and the mistake to avoid, and two portfolio-wide worked examples (open schools and seats; overdue work). The portfolio examples use include=profile, which turns a per-site sweep into one or two calls.

- Section 11 documents the rate-limit headers and the two error shapes.

No change to routes, dispatch, keys or the dictionary.

## Not addressed here

- Bulk or changed-since reads, updatedAt on cards, and the quality-bar catalog need changes in the system of record.

- Field definitions in the dictionary and a brainlift need the data owner's decision.

## Business Value

The registry grades this source on a schedule and publishes the grades stakeholders see. These were the findings where the published contract and guide said something different from what the service does, which makes an agent mishandle errors and over-spend the shared rate budget. The business-question section is what the registry's contract requires an enablement to be.

## Manual Effort Estimate

About 5 hours by hand. Proposed figure; Keval to confirm or adjust.

## Testing

- pnpm check passes (50 tests; 1 new covering every contract change above).

- Existing test confirms every route cited in the new enablement text is published and uses only declared parameters.

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

## Summary

- Exclude the normalized flores associates vendor from Crossover NHC overspend alert rows.

- Keep the spend in NHC totals and leave other business units unchanged.

## Verification

- Ruff 0.15.22 format and check passed.

- Pyright passed for the changed file.

- Local --scope preview run completed; the ledger recorded the Crossover exclusion in the active filter snapshot.

- Tests were not run.

## Tests

- Confirmed with a new email sent to the stakeholder

## Summary

tfy-provider-secrets-sync has been PARTIAL on every run since 2026-09-22. TrueFoundry reports provider values the reconciler does not recognise, and the design deliberately holds the run at PARTIAL for any provider value outside the supported and skipped sets:

| Provider value | Secret | Since | What it is |

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

| microsoft-foundry | AZURE_API_KEY_QUARK | 09-22 | TFY's rename of azure-foundry (same account; the old value is already in the skipped set) |

| typesafe | TYPESAFE_API_KEY_RAW | 10-08 | New account, vendor with no Surtr usage feed |

| custom-endpoint | TYPESAFE_API_KEY | 10-08 | TFY's generic bring-your-own-endpoint type |

None has a Surtr direct-provider feed, so there is nothing to deduplicate gateway spend against. They are added to KNOWN_SKIPPED_PROVIDERS, the same fix as voyage (PR 1773). This is reporting only: no identifier is written, closed or stale-closed differently, and the supported providers (anthropic, openai, google-gemini) are untouched. The README now says how the skipped set and the unknown-provider rule interact.

The only other item in the latest run is OPENAI_DAYBREAK_KEY, already reported as known_unresolved under the registry-coverage rule, so after this change the run ends success.

For review / needs a human call: custom-endpoint is a generic provider type, so a future custom-endpoint secret will now be skipped without a human looking at it. I judged that right because a bring-your-own endpoint cannot have a provider-side usage feed by definition, but if you would rather keep a human gate for it, drop it from the set and skip by secret name instead.

Linear: SURTR-1608

## Business Value

The TrueFoundry provider-account registry feeds the double-count dedupe for AI spend. A pipeline stuck PARTIAL for 17 days means its alert is permanent noise, so a real unresolved Anthropic/OpenAI key (the case that can actually hide undeduplicated spend) would not stand out. Returning it to success restores the signal.

## Manual Effort Estimate

About 1 hour by hand (read the run history to find when each provider value first appeared, add the three values, a parametrized test, README). Proposed by Claude, for Keval to confirm or adjust.

## Test plan

- [x] cd pipelines/runners/tfy-provider-secrets-sync && uv run pytest: 70 passed (3 new, parametrized over the new provider values)

- [x] uvx ruff@0.15.22 check and format --check on the pipeline: clean

- [ ] After deploy: next 05:00 UTC run reports status: success with the three secrets under skipped

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

## Summary

- Add the Q118 current revenue-recognition-to-Finalsite-school-year mart, aggregate refresh manifest, and atomic Redshift writer procedure.

- Add the Surtr handler with source freshness and run pinning, bounded Data API polling/cancellation, and post-refresh verification.

- Register the pipeline under Sanket Ghia; the future native pipeline is event-triggered after Finalsite billing success with on-demand disabled.

## Verification

- Runner suite: 109 passed.

- Repository-wide Ruff check and format check passed.

- DDL dry-run lists 21 statements.

- Read-only reconciliation against current sources: 8,993 postings / $9,744,793.62; 8,927 unique matches, 16 ambiguous, 50 unmatched; 479 source-to-candidate tie groups, zero mismatches, and zero empty-input failures.

- Production DDL was applied on 2026-10-07, followed by one local handler invocation against production. Run q118-local-20261007T020542Z, input set b84bfca5a7ce64d14908b25a412528f5aa5d5e12232360cbde9ccc6091b8ec71. Independent verification found 8,993 unique posting rows, $9,744,793.62 signed total, exact source lineage, and zero published-output tie-out mismatches.

## Review follow-up

- The checked-in table DDL no longer attempts database-level schema creation. The apply script requires CREATE on the existing shared schema and preflights existing Q118 table columns/types/nullability before applying any statements.

- The reconciliation query labels its source-to-classified-candidate tie-out explicitly and reports an empty-input failure in the tie-out when any input population is empty. Published-output verification remains in the handler.

- The handler now rejects missing, boolean, negative, and fractional count values instead of coercing them into plausible counts.

- DDL apply tooling covers nested block comments, unterminated inputs, Redshift failure/timeout paths, statement position reporting, and schema mismatch rejection. README recovery guidance explains how to resume after a partial statement-level apply.

- The null-lineage finding was not changed: QBO, billing, and the student-year base fact declare the relevant lineage fields NOT NULL. The current student-year view directly projects that fact, and the handler preflight also rejects null lineage/freshness values.

- The matching fixture tests exercise a test-only reference oracle. Separate SQL-contract tests cover the production procedure's joins, statuses, fallback, conflicts, and year-coordinate rules; the production procedure was also executed and verified against the current source publication.

## Live rollout note

The production tables contain the initial publication. The Lambda, pipeline IAM role, Step Functions state machine, and EventBridge trigger remain undeployed. The event trigger is enabled in the manifest; deploying it unchanged will make the next successful Finalsite billing refresh eligible to invoke the Q118 refresh. Finance review of the unresolved statuses is recommended before recurring automation is enabled.

## Summary

- Pass the EC2-configured AWS_REGION explicitly when creating the ECS client, with AWS_DEFAULT_REGION as fallback.

- Route unexpected pre-launch exceptions through the existing failure update in both on-demand launch endpoints so jobs do not remain queued.

## Verification

- uv run ruff format services/monthly_qtd_report/ecs_launcher.py routers/qtd_ondemand_router.py — passed; no formatting changes.

- uv run ruff check services/monthly_qtd_report/ecs_launcher.py routers/qtd_ondemand_router.py — passed.

- uv run pyright services/monthly_qtd_report/ecs_launcher.py routers/qtd_ondemand_router.py — 0 errors.

- uv run pytest --import-mode=importlib tests/monthly_qtd_report/test_ecs_launcher.py tests/routers/test_qtd_ondemand_router.py -q — 48 passed.

- git diff --check — passed.

## Screenshot

- Previously failing on-demand jobs now succeed

<img width="935" height="113" alt="image" src="https://github.com/user-attachments/assets/ccb8327e-5da3-48c6-8f87-98c52726665e" />

## Summary

- add a reusable milestone weekly-provenance contract with exhaustive dbt method labels

- ingest, validate, and store current-year EOY and following-year Start-of-Year provenance

- render separate published calculation chains and rounding boundaries in the dashboard

- keep normalized and deprecated public Forecast API payloads unchanged

## Dependency / rollout

- Draft and must not merge until #1740 is merged, deployed, and the forecast mart has refreshed successfully.

- Column and method identifiers currently follow the proposed #1740 contract (weekly_pace_v2, seasonal_taper_v1, single_application_rate_v1, floor_final_headline_v1) and may need a naming-only adjustment after #1740 lands.

## Validation

- pnpm typecheck (all affected packages; pre-commit Chat and sync typechecks also passed)

- pnpm biome check on all changed files

- sync focused suites: 107 tests

- Convex + dashboard focused suites: 187 tests

- public Forecast API v2 suite: 45 tests

Closes #1741

## Summary

- persist enrollment school and status filters in validated local storage

- share the preference across the standard and SIS enrollment report variants

- keep free-text search session-only to avoid reopening on unexpectedly empty results

## Testing contract

### What this PR delivers

Enrollment report users keep their selected school and school-status filters after a reload, browser restart, or later session.

### Who uses it and where

Admissions dashboard users on both the standard Enrollment report and the SIS-based Enrollment report.

### Conditions needed

The user can access an enrollment report with at least one school or status filter option. Browser local storage must be available for cross-session persistence; when unavailable, filtering continues to work in memory for the current page session.

### Expected behavior and examples

- Selecting Alpha Austin and reloading restores Alpha Austin as an active filter.

- Selecting an Operating status restores that status in either enrollment report variant.

- Clearing a school, status, or all filters updates the stored preference so it stays cleared next session.

- Malformed or schema-incompatible stored values are ignored and the report opens unfiltered.

- Search text is intentionally not restored between sessions.

### Limits and unanswered questions

Preferences are browser-local and are not synced between devices or user accounts.

## Validation

- pnpm --dir chat exec vitest run components/dashboards/admissions/enrollments/__tests__/enrollments-view.test.tsx components/dashboards/admissions/enrollments/sis/__tests__/sis-enrollments-view.test.tsx --maxWorkers=1

- pnpm exec biome check chat/components/dashboards/admissions/enrollments/enrollment-filter-preference.ts chat/components/dashboards/admissions/enrollments/enrollments-view.tsx chat/components/dashboards/admissions/enrollments/sis/sis-enrollments-view.tsx chat/components/dashboards/admissions/enrollments/sis/__tests__/sis-enrollments-view.test.tsx

- pnpm --dir chat typecheck

## Summary

[AERIE-2755](https://linear.app/builder-team/issue/AERIE-2755): the v2 API now refuses documents the indexer can't read, and every v2 document response says whether the document is searchable.

- Unsupported types get a 422 up front. Uploads (site and Global), Global Drive registrations and site relinks reject file types the indexer can't read with document_type_unsupported (retryable: false). The message names the type and lists the supported ones. No document row or upload intent is created.

- One supported-type list. The check lives in packages/contracts and is shared by the API and the Rhodes worker, so the two can't drift.

- knowledgeStatus on v2 documents. List, get, upload, update and relink responses include the same status the Rhodes workbench shows: available, processing/refreshing, or not_searchable/failure with a reasonCode and message.

## Why it's needed

Today an API client can upload a .zip or .xls, get a 201, and only find out much later that it never became searchable. Clients also had no way to tell from the API whether indexing was done.

## Changes

- packages/contracts/src/document-knowledge.ts: MIME constants, isDocumentKnowledgeSupportedType, the CSV-mislabel helpers and a human-readable supported-types description.

- chat/rhodes-worker/lib/document-knowledge/{retrieval,docx,xlsx}.ts: use the shared constants and check instead of local copies.

- chat/convex/documentKnowledge/status.ts: siteDocumentKnowledgeStatus, moved from rhodes/portfolioWorkbench.ts so the API and workbench share it.

- chat/convex/publicApi/v2/domains/documents.ts: the 422 check on upload, Global registration and relink, plus knowledgeStatus in every document response (batched query for list pages).

- chat/lib/public-api/v2/domains/documents.ts: OpenAPI knowledgeStatus property, updated 422 descriptions, and the agent-context dictionary entry.

Notes:

- Drive registration doesn't give us the file name. The two MIME types that Drive uses for mislabelled CSVs (application/vnd.ms-excel, application/octet-stream) are therefore allowed at registration and left to the worker. Uploads always have a filename, so they get the exact check.

- External link registrations are still allowed on purpose. They report not_searchable / external_url.

## Breaking changes

- Uploads, Global Drive registrations and relinks of unsupported types now return 422 instead of succeeding.

- knowledgeStatus is a new required field on the Document schema (additive for readers).

## Test plan

- [x] Upload of zip, .xls and Google Slides returns 422 document_type_unsupported; nothing is written.

- [x] Global Drive registration: zip is rejected; an Excel-labelled file is accepted (CSV-mislabel case).

- [x] Relink to a Google Slides file returns 422 and the ETag is unchanged.

- [x] Get and list return knowledgeStatus (not_searchable / external_url for a link document).

- [x] Contract tests for the supported-type check (33 passed); worker tests (306 passed); v2 API, document knowledge, Rhodes and admin suites passed.

- [x] Biome and pnpm typecheck (pre-commit) clean.

## Summary

- Retain failed-tool error messages before large inputs in bounded triage session inspection.

## Why

The production credential-swap canary recovered from two publication refusals, but its long issue drafts consumed the 2,000-character inspection limit before the error messages. Operators could see failures without their causes. Reading the same retained session now reveals both privacy-guard refusals without another dispatch.

## Business Value

Makes autonomous triage failures diagnosable while preserving existing authentication and inspection bounds.

## Test plan

- [x] Session suite: 14 tests, including failed tool with oversized input.

- [x] Worker typecheck, focused Biome check and production build pass.

- [x] Isolated worker deployment: health ready; existing canary session exposes both refusal messages.

- [x] Production scheduler remains disabled; no new agent dispatch.

## Summary

Fixes [AERIE-2753](https://linear.app/builder-team/issue/AERIE-2753/make-google-sheets-and-excel-documents-searchable).

- Excel (.xlsx) files are now searchable. The Rhodes worker reads the cell values from every tab and indexes one record per tab, headed Sheet: <tab name>, with each row's non-empty cells joined by | .

- Google Sheets are now searchable, including every tab. The worker exports the Sheet from Drive as .xlsx and uses the same extractor. Drive's CSV export only returns the first tab, so it wasn't used.

- Size limits still apply. The combined unzipped size of the workbook parts is capped at the existing 25 MiB source limit, even when the ZIP's declared sizes are wrong. The rendered text is capped at the existing in-memory text budget, checked cell by cell, so one long shared string repeated across many cells can't blow it up. Going over either limit ends as "not searchable: too large".

- Dates and times read as dates. Cells formatted as a date, date-time or time are indexed as 2025-10-04, 2025-10-04 12:15 or 18:00, not as Excel serial numbers. This covers Excel's built-in date formats, custom format codes (including Google Sheets' own), and the 1904 date system. Elapsed durations like [h]:mm stay numeric.

- A workbook with no cell values ends as "not searchable: no readable text".

Out of scope: legacy .xls (stays unsupported), formulas (their last calculated value is indexed), and number formatting other than dates (currency and percentages are indexed as stored).

## Why it's needed

Managers register camera coverage registers and similar trackers as spreadsheets, and those were marked unsupported, so the assistant couldn't find anything in them.

## Changes

- chat/rhodes-worker/lib/document-knowledge/xlsx.ts (new): extractDocumentKnowledgeXlsx. Reads xl/workbook.xml, its relationships, xl/sharedStrings.xml, xl/styles.xml and xl/worksheets/*.xml. Handles shared, inline, boolean, numeric and date cells, skips error cells, and drops phonetic runs.

- chat/rhodes-worker/lib/document-knowledge/ooxml.ts (new): the bounded inflater, chunk join and XML entity decoding, moved out of docx.ts so both extractors share them. docx.ts has no behaviour change.

- chat/rhodes-worker/lib/document-knowledge/retrieval.ts: accepts the .xlsx and Google Sheet MIME types, exports Google Sheets as .xlsx, runs the extractor under the same memory hold as DOCX, and maps NO_READABLE_TEXT to no_readable_text.

## After deploy

Spreadsheets registered before this release are already marked "unsupported type", and the backfill doesn't retry those. Each one needs a Reindex from the Global documents admin page.

## Test plan

- [x] An .xlsx and a Google Sheet with two tabs are both indexed, and the second tab's text is in the records. The Google Sheet is exported as .xlsx and never downloaded.

- [x] An empty workbook ends as not_searchable / no_readable_text.

- [x] An oversized workbook ends as not_searchable / too_large. Extractor tests also cover forged ZIP sizes, a size limit that is only crossed across two sheets, and shared-string amplification.

- [x] Extractor tests cover shared, inline, boolean, formula and error cells, entity decoding, prefixed tags, absolute and ../ relationship targets, and corrupt or incomplete packages. A workbook with a missing declared tab, an unresolvable sheet relationship or a missing shared string is rejected as malformed, so it is never indexed partially. Chart sheets are skipped.

- [x] Every workbook part the extractor reads (workbook, relationships, styles, shared strings, worksheets) must be one well-formed XML element tree with the expected root, checked in one linear pass before any values are read. Truncated parts, unbalanced tags, stray text, bad entities, comments, CDATA and DOCTYPE are rejected as malformed. Rows, cells and shared strings must also be contiguous inside their containers. Well-formed elements the extractor doesn't read (sheetViews, cols, mergeCells, prefixed tags) are accepted. A 5 MB unterminated tag is rejected quickly.

- [x] Element patterns are bound to each part's root namespace prefix, and the workbook must have exactly one sheetData, sheets and relationship list, at most one workbookPr, numFmts and cellXfs, at most one value per cell, and no repeated relationship IDs. Repeated structures are rejected instead of reading only the first one. Extension elements such as x15:workbookPr inside extLst are ignored. A package with a repeated ZIP entry for any part the extractor reads is rejected, and so is a boolean cell whose value isn't 0 or 1. A cell with an unknown type, or a typed cell missing its required value (a shared-string, boolean, error, string or date cell with no value and no formula, or an inline-string cell with no inline string), is rejected rather than dropped. Blank numeric cells and formulas without a cached value are still accepted. Cell values must match their type's format: numbers, shared-string indexes, style indexes that exist, ISO dates, error codes such as #DIV/0!, and booleans. Anything else is rejected. A valid number in a date-formatted cell that can't be a date (Excel shows ####) is indexed as the number.

- [x] Date, date-time and time cells render as ISO text from built-in and custom formats. Plain numbers, [h]:mm durations and literal-only formats stay numeric. The 1904 date system is honoured. In the 1900 system, serials 0 and 60 render as Excel displays them (1900-01-00 and the phantom 1900-02-29), and serials 59 and 61 render as the days on either side.

- [x] .xls stays unsupported_type.

- [x] Rhodes worker: all tests pass. tsc --noEmit and Biome are clean.

## Title

feat(tasks): add guarded review actor migration (AERIE-2789)

## Summary

This PR is Phase 13 of 14 in the larger [Human Task Assignment from Aerie](https://linear.app/builder-team/project/human-task-assignment-from-aerie-b3582376ae6e) project.

It adds the guarded migration that the final Task Board launch needs to check and repair historical completion-review actor references. This phase is tracked by [AERIE-2789 — Ship the guarded Task review-actor migration before launch](https://linear.app/builder-team/issue/AERIE-2789/ship-the-guarded-task-review-actor-migration-before-launch).

Production effect: dormant/additive. The migration code becomes callable after deployment, but it does nothing until a production operator explicitly runs it. It is internal-only and is not connected to a scheduler, UI, API, MCP tool, or existing Task write path.

## Why

The final Task Board launch must confirm that historical completion-review records identify actors by their canonical public ID. Shipping the guarded migration first lets an operator preview conflicts, repair valid rows in bounded batches, and verify the result before the launch gate is removed.

## Business Value

- Gives operators a safe way to prepare historical Task review data before launch.

- Refuses to guess when an actor identity is missing, invalid, deleted, or duplicated.

- Keeps current Task behavior unchanged until an operator explicitly authorizes the migration.

## How does it work

1. An operator starts with a dry run that reads a bounded batch of completion-review records.

2. Each record resolves the canonical actor only through its stored actorUserId.

3. Missing, invalid, deleted, and duplicated identities are reported as conflicts. Historical names and email addresses are never used to infer identity.

4. A review snapshot whose embedded user ID disagrees with its stored actorUserId is also reported as a conflict, so the migration cannot create a contradictory identity reference.

5. Execution requires the exact confirmation value and updates only conflict-free batches. The returned cursor lets the operator resume safely.

6. Re-running an updated batch is harmless, and the separate verification action confirms that no changes or conflicts remain.

## Scope

### Included in this phase

- A bounded, resumable, confirmation-guarded internal migration.

- Dry-run, execute, and verification reporting.

- Focused coverage for successful repair, idempotency, pagination, confirmation, mismatched user references, and identity conflicts.

- Exact final diff paths:

chat/convex/_generated/api.d.ts
chat/convex/migrations/taskReviewActorPublicIds.test.ts
chat/convex/migrations/taskReviewActorPublicIds.ts

### Deliberately excluded for later phases

- Running the migration in any environment. An operator owns execution during the launch process.

- Removing the Task Board launch gate or exposing any new UI, API, MCP, or agent behavior.

- The final launch runbook and launch verification, which remain in AERIE-2744.

- Any Task lifecycle, schema, notification, digest, document, or authorization changes.

## Test plan

### Automated validation

- Focused migration coverage — 4/4 passed (pnpm --dir chat exec vitest run convex/migrations/taskReviewActorPublicIds.test.ts --maxWorkers=1).

- Chat typecheck — passed (pnpm --dir chat typecheck).

- Biome — passed (pnpm exec biome check chat/convex/migrations/taskReviewActorPublicIds.ts chat/convex/migrations/taskReviewActorPublicIds.test.ts).

- Convex module path validation — passed through the pre-commit hook.

- Test architecture validation — passed (pnpm lint:test-architecture).

- git diff --check — passed.

- Exact-head diff scope — only the three authorized migration paths listed above.

### Time for Implementation

An engineer working without AI assistance would likely need about 2 days to inspect the historical data contract, implement the guarded migration, add conflict and resumability tests, and complete review.

## Summary

This PR is Phase 9 of 10 in the larger [Human Task Assignment from Aerie](https://linear.app/builder-team/project/human-task-assignment-from-aerie-b3582376ae6e) project.

It adds the gated Team Tasks workspace for Portfolio users: bounded cross-site Task reads, summaries, grouping, filters, shareable URLs, and the shared Task detail and action experience. This phase is tracked by [AERIE-2743 — Ship Team Tasks behind the launch gate](https://linear.app/builder-team/issue/AERIE-2743/ship-team-tasks-behind-the-launch-gate).

Production effect: dormant/additive. Team Tasks remains unavailable while the existing server-authoritative Task Board launch gate is off. Merging this PR initiates no external traffic, migration, or background processing. The exact 15-commit branch is based on main commit a43133ceec337c780c146726af6be8458d871101.

---

## Why

Portfolio users need one bounded place to review and manage Tasks across sites without introducing management hierarchies or broad scans. This slice establishes that final gated workspace and its indexed projection before AERIE-2744 removes the launch gate.

Independent review of the complete slice drove two focused repairs: the projection scan now stays below Convex's hard DB-call ceiling in the true worst case, and every Team Tasks external-assignee label uses the approved wording. The final replay onto a43133ceec337c780c146726af6be8458d871101 preserved all 15 patches exactly, and fresh independent exact-head review passed on 271ec052aaf8c3afe009b4bb68bf7e2600ddcceb.

---

## Business Value

- Gives Portfolio users one cross-site view for operational Tasks.

- Makes work discoverable through summaries, detailed filters, grouping, and shareable URLs.

- Reuses My Tasks' canonical detail and lifecycle actions instead of creating a parallel workflow.

- Keeps cross-site reads bounded and predictably safe at production scale.

- Clearly distinguishes external assignees who do not have Aerie accounts.

### What it means for end users and consumers

| Area | Plain-language production effect |

| --- | --- |

| Availability | No user sees Team Tasks yet; the existing launch gate remains authoritative until AERIE-2744. |

| Access | After launch, only users with existing Portfolio access can open Team Tasks. My Tasks remains available to every authenticated user. |

| Site visibility | Portfolio users see Tasks across Portfolio sites; this creates no new site access or management hierarchy. |

| Finding work | Users can choose Open, Overdue, Due this week, Awaiting approval, or Closed in the last 7 days and combine the agreed Task and participant filters. |

| Grouping | Results can be grouped by stable person identity or site identity, so duplicate display names do not merge unrelated people or sites. |

| External assignees | Team headings and filter choices display email · External, no Aerie account. |

| Sharing | Filters live in URL query parameters; another authorized user sees the same filtered view subject to their own access. |

| Creating and managing | Authorized users can create a site-level Task and use the same detail, editing, participation, lifecycle, completion, and approval controls as My Tasks. |

| Closed Tasks | Completed and rejected Tasks remain visible but read-only except for the explicit existing exceptions. |

| Scale safety | A request scans at most 1,800 projection rows: 3,600 worst-case row reads plus 400 reserved calls totals 4,000, below Convex's 4,096-call limit. Exhaustion returns a clean bounded error asking the user to narrow filters. |

---

## How does it work

1. The /tasks/team route and Convex queries enforce the existing Task Board gate; the query additionally requires operations.portfolio.read.

2. Task writes reconcile a compact indexed portfolio projection with stable Task ordering and normalized external-assignee data.

3. The Team Tasks query reads that projection in deterministic batches, fills a cursor page, or stops at the 1,800-row safety cap with the shared clean user-facing error.

4. Summary and Task, site, person, date, placement, and assignment filters are applied consistently while option searches remain indexed and bounded.

5. The React workspace stores filters in the URL, groups returned rows by stable identity, and reuses the canonical Task editor and detail actions.

6. Migration helpers reconcile and verify existing projection rows without starting automatically when this dormant slice merges.

---

## Scope

### Included in this phase

- Gated Team Tasks route and Portfolio capability enforcement.

- Bounded indexed cross-site projection, deterministic pagination, reconciliation, and verification.

- The agreed summaries, filters, stable grouping, and shareable query-parameter URLs.

- Site-level Task creation and the shared Task detail/action experience.

- A 1,800-row request cap with explicit Convex DB-call headroom and clean exhaustion behavior.

- Approved external-assignee labels in Team Tasks grouping and filtering.

- 15 commits; 14 paths; 2,143 additions and 33 deletions against main at a43133ceec337c780c146726af6be8458d871101.

- Exact final diff paths:

chat/app/(main)/tasks/team/page.tsx
chat/components/task-board/my-tasks-view.tsx
chat/components/task-board/task-editor.test.tsx
chat/components/task-board/task-editor.tsx
chat/components/task-board/team-tasks-view.test.tsx
chat/components/task-board/team-tasks-view.tsx
chat/components/ui/enum-popover.tsx
chat/convex/migrations/taskParticipants.test.ts
chat/convex/migrations/taskParticipants.ts
chat/convex/rhodes/schema.ts
chat/convex/taskBoard/participants.ts
chat/convex/taskBoard/queries.test.ts
chat/convex/taskBoard/queries.ts
chat/convex/taskBoard/teamProjection.ts

### Deliberately excluded for later phases

- Removing the Task Board launch gate or exposing Team Tasks in production — AERIE-2744 owns final launch.

- New management hierarchies, inferred direct reports, or wider site access.

- Weekly digests or other post-V1 notification schedules.

- Automatic migration execution or rollout work triggered by merge.

---

## Test plan

### Automated validation

- Focused Team Tasks UI, shared editor, My Tasks navigation, query, and projection-migration suite — 5 files / 45 tests passed (pnpm --dir chat exec vitest run components/task-board/team-tasks-view.test.tsx components/task-board/task-editor.test.tsx components/task-board/my-tasks-view.test.tsx convex/migrations/taskParticipants.test.ts convex/taskBoard/queries.test.ts --maxWorkers=1)

- Scan-safety regression — 1,801 real projection rows reach the 1,800-row cap and return the clean bounded error; worst-case arithmetic is locked at 4,000 calls below the 4,096 hard limit.

- External-assignee presentation regression — approved label verified in both person grouping and filter options.

- Full workspace typecheck — passed (pnpm typecheck).

- Full workspace lint, Biome, architecture boundaries, Convex paths, read bounds, test architecture, and knowledge hygiene — passed (pnpm lint); two pre-existing chat/skill/forge-api/scripts/sindri.mjs warnings remain unchanged.

- git diff --check a43133ceec337c780c146726af6be8458d871101..271ec052aaf8c3afe009b4bb68bf7e2600ddcceb — passed.

- Final rebuild equivalence — 15/15 range-diff patches identical; aggregate patch ID 39d1c4bbff0e3fe8a71dbcabc8655d20f2984d8d unchanged.

- Independent exact-head review — PASS on 271ec052aaf8c3afe009b4bb68bf7e2600ddcceb.

- Exact-head diff scope — only the 14 authorized paths listed above.

### Time for Implementation

About 2 to 3 weeks for an engineer without AI assistance, including design, implementation, migration safety, focused scale tests, integration repair, rebasing, and review.

## Review repairs and contract clarifications

Review [37827885084](https://github.com/AI-Builder-Team/Aerie/actions/runs/37827885084) was classified under [AERIE-2743](https://linear.app/builder-team/issue/AERIE-2743/ship-team-tasks-behind-the-launch-gate) at reviewed head 271ec052aaf8c3afe009b4bb68bf7e2600ddcceb.

One reachable blocker was accepted. The migration verifier intentionally detects duplicate taskPortfolioRows, but canonical Task deletion used .unique() for that same projection and therefore aborted before deleting the Task when duplicates existed. The repair reuses the existing 100-row per-Task safety bound, reads at most 101 rows, rejects only states beyond that established bound, and deletes every bounded matching projection row before Task deletion continues. A focused regression creates the duplicate state at the real deletion seam and proves that the Task, participant rows, and all portfolio rows are removed atomically.

The three nonblocking suggestions do not require changes in this slice:

- External-assignee email matching already uses one canonical form. Every production assignment write starts in resolveAssignmentEmails, which trims and lowercases through normalizeEmail before taskAssignments and the Team Tasks projection are written; the existing filter regression also proves a mixed-case, whitespace-padded query matches the stored assignment.

- Existing assignees are edited directly through the initialized Assignee emails textarea, including internal and external addresses. availableUsers supplies requester and eligible-approver choices, so adding assignees there would not restore a missing unassign action.

- Projection reconciliation and zero-mismatch verification are already an explicit launch prerequisite in migrations/taskParticipants.ts. This PR remains dormant and does not enable the launch gate; AERIE-2744 owns running and verifying the migration before activation.

The established boundaries remain unchanged: Team Tasks stays gated and Portfolio-only, reads remain bounded and indexed, migration execution is not triggered by merge, and no site access or management hierarchy is added.

Independent exact-diff review passed with no findings. Current repair validation: the focused Team Tasks query and projection-migration suites pass 26/26 tests (pnpm --dir chat exec vitest run convex/taskBoard/queries.test.ts convex/migrations/taskParticipants.test.ts --maxWorkers=1), Chat typecheck passes (pnpm --dir chat typecheck), and git diff --check passes. The repair changes only chat/convex/taskBoard/teamProjection.ts and chat/convex/taskBoard/queries.test.ts; it initiates no migration, deployment action, external traffic, or production activation.

### Exact-head projection-integrity follow-up

Mercy review 5461749675 accepted the prior external-assignee, editor, and launch-prerequisite explanations and found one new reachable integrity gap on exact head f420b2248e0157bb58604d1d7637a2f985f412af. That finding is valid: a Team Tasks projection row whose Task or site is missing must not be treated like an ordinary filter miss, because doing so returns an apparently complete cross-site page with omitted work.

The follow-up fails the bounded listTeam query closed through the shared clean-error pathway when either source record is absent. It adds no scans, migration execution, repair-on-read behavior, or launch activity. Focused regressions cover both a deleted Task and a deleted site behind a retained projection row. The exact query suite passes 24/24, Chat typecheck passes, and git diff --check passes.

## Testing contract

### What this PR delivers

Restores the previously approved Praxis hosted-testing behavior from Aerie PR #1614: eligible @praxis-e2e runs resolve the private Praxis action from master. This reverses the accidental reintroduction of a fixed action SHA in Aerie PR #1695.

### Who uses it and where

The current Praxis hosted-testing operator uses it from Aerie pull-request comments while completing the Praxis feedback loop.

### Conditions needed

- An open Aerie pull request targeting main.

- An exact @praxis-e2e comment from a user with write, maintain, or admin permission.

- The existing Praxis GitHub App and AWS workflow configuration.

### Expected behavior and examples

- An eligible comment runs AI-Builder-Team/Praxis/.github/actions/run@master.

- Praxis changes merged to master become available without another Aerie pin-update PR.

- Existing comment authorization, live-head resolution, limited workflow permissions, and the single visible Praxis check remain unchanged.

- Example: after a Praxis runtime fix reaches master, a fresh @praxis-e2e comment uses that fix immediately.

### Limits and unanswered questions

This is the same temporary hosted-testing policy approved in Aerie PR #1614. This PR changes only the Praxis action reference and does not change Aerie product behavior, workflow permissions, or trigger authorization.

## Validation

- Final diff: one line in .github/workflows/praxis.yml.

- git diff --check: passed.

- Praxis master currently resolves to 679a06deedb64bb9f636558ea2332ca7f7518bf0, whose CI completed successfully.

- Aerie hosted CI is the final repository validation.

## Summary

This PR is Phase 11 of 13 in the larger [Human Task Assignment from Aerie](https://linear.app/builder-team/project/human-task-assignment-from-aerie-b3582376ae6e) project.

It adds Task comments, watcher controls, and the daily Task Scenario email across the UI, API, and agent tools. This phase is tracked by [AERIE-2742 - Add participant comments, watchers and the daily Task Scenario digest](https://linear.app/builder-team/issue/AERIE-2742/add-participant-comments-watchers-and-the-daily-task-scenario-digest).

Production effect: compatibility hardening plus dormant/additive. Existing Task-linked Notes become read-only when their Task is Completed or Rejected. The new Task Board comment, watcher, and digest experiences remain unavailable while AERIE_TASK_BOARD_ENABLED is off. Merging this PR does not send Task Scenario emails or expose the incomplete Task Board.

---

## Why

Task work needs one place for discussion and a simple way for interested people to follow progress without giving them management authority. The digest then gives each user one bounded daily summary instead of producing more immediate email noise. This slice also makes closed Tasks consistently read-only before Team Tasks and the final launch work land.

---

## Business Value

- Keeps Task discussion attached to the Task by reusing Aerie Notes.

- Lets users follow a Task like a CC without receiving permission to manage it.

- Sends one daily summary of relevant open work and sends nothing when there is nothing to report.

- Gives users, APIs, and agents the same watcher and comment behavior.

- Prevents comments, watcher changes, and other Note edits from changing a closed Task's history.

### What it means for end users and consumers

| User or consumer | What this PR provides | Important limit |

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

| Task participant | Can read and add comments to an open Task they can access | Closed Tasks remain readable, but their discussion cannot be changed |

| Portfolio user | Can comment on an open Task already visible through Portfolio access | This does not grant broader Task or site access |

| Any user who can see a Task | Can watch or unwatch that open Task | Watching grants visibility and digest inclusion, not management authority |

| Creator, requester, or global Task manager | Can add or remove other watchers | A Task supports at most 50 watchers |

| Watcher | Sees the Task in My Tasks and in the daily digest while it remains relevant and open | Watchers cannot start, edit, approve, reject, or otherwise manage the Task merely because they watch it |

| Digest recipient | Receives one Task Scenario email at 7:30 a.m. America/New_York with relevant open assigned, watched, created, and Awaiting approval Tasks | No email is sent when there is no relevant work; the email shows at most 100 Tasks and links to My Tasks for more |

| API client or agent | Can add Task comments and manage watchers through the same authorized workflow | Writes are idempotent where applicable and closed Tasks return the stable read-only error |

| Existing Note consumer | Cannot create, edit, or delete a Note anchored to a Completed or Rejected Task | Non-Task Notes and Notes on open Tasks keep their existing behavior |

---

## How does it work

1. Task comments reuse the existing Notes writer with a Task anchor. Task visibility is checked first, comments are limited to 5,000 characters, and reads use cursor pagination with up to 100 items per page.

2. Users can watch or unwatch a visible open Task. Creators, requesters, and users with operations.tasks.write can manage other watchers. Every change is audited and reconciles the indexed Task participant rows.

3. The participant projection records whether each relationship belongs in the digest. Creator, assignee, and watcher relationships are eligible for open Tasks; approver relationships are eligible while a Task is Awaiting approval.

4. The daily job evaluates 7:30 a.m. in America/New_York, pages through users in groups of 50, reads at most 401 eligible participant rows to prove the 100-Task email limit, and schedules its next user page immediately.

5. Delivery is idempotent per recipient and New York calendar date. No email is queued when the user has no relevant Tasks. A user with more than 100 relevant Tasks receives the first 100 plus a link to My Tasks.

6. UI, public API, and agent tools share the same authorization and write paths. Creating, updating, or deleting a Note anchored to a Completed or Rejected Task fails through the shared clean-error path.

7. The existing Task participant reconciliation migration now verifies and backfills digest eligibility. It must be run and verified before the final launch gate is removed; merging this PR does not start that migration.

---

## Scope

### Included in this phase

- Task comments backed by Notes, including bounded pagination and closed-Task immutability.

- Self-service watching and authorized management of other watchers.

- Watcher visibility in My Tasks and indexed participant relationships for fast queries.

- One daily, gated, idempotent Task Scenario digest at 7:30 a.m. America/New_York.

- Public API and agent parity for Task comments and watcher actions.

- Participant reconciliation and verification support for digest eligibility.

- Exact final diff paths:

chat/components/task-board/my-tasks-view.test.tsx
chat/components/task-board/my-tasks-view.tsx
chat/components/task-board/task-detail.test.tsx
chat/components/task-board/task-detail.tsx
chat/components/task-board/task-participation-actions.test.tsx
chat/components/task-board/task-participation-actions.tsx
chat/convex/_generated/api.d.ts
chat/convex/automations/cronRegistry.ts
chat/convex/crons.ts
chat/convex/lib/taskScenarioEmail.ts
chat/convex/migrations/taskParticipants.test.ts
chat/convex/migrations/taskParticipants.ts
chat/convex/notifications/events.ts
chat/convex/notifications/schema.ts
chat/convex/publicApi/v2/domains/siteNotes.ts
chat/convex/publicApi/v2/domains/workManagement.ts
chat/convex/publicApi/v2/domains/workManagementTaskBoardWrites.test.ts
chat/convex/publicApi/v2/http.ts
chat/convex/publicApi/v2/siteNotes.test.ts
chat/convex/publicApi/v2/workManagementData.ts
chat/convex/publicApi/v2/workManagementWrites.ts
chat/convex/rhodes/mcp.ts
chat/convex/rhodes/runtime/constants.ts
chat/convex/rhodes/runtime/mutationAuthorization.ts
chat/convex/rhodes/runtime/mutationDispatcher.ts
chat/convex/rhodes/runtime/writes/noteWrites.ts
chat/convex/rhodes/schema.ts
chat/convex/rhodesMcpMutationParity.test.ts
chat/convex/taskBoard/appendReceipts.ts
chat/convex/taskBoard/approval.test.ts
chat/convex/taskBoard/approval.ts
chat/convex/taskBoard/comments.ts
chat/convex/taskBoard/completion.test.ts
chat/convex/taskBoard/completion.ts
chat/convex/taskBoard/digest.test.ts
chat/convex/taskBoard/digest.ts
chat/convex/taskBoard/lifecycle.test.ts
chat/convex/taskBoard/lifecycle.ts
chat/convex/taskBoard/participants.ts
chat/convex/taskBoard/queries.ts
chat/convex/taskBoard/visibility.ts
chat/convex/taskBoard/watchers.test.ts
chat/convex/taskBoard/watchers.ts
chat/lib/public-api/v2/domains/work-management-schemas.ts
chat/lib/public-api/v2/domains/work-management-task-board.node.test.ts
chat/lib/public-api/v2/domains/work-management.ts
chat/lib/rhodes-mcp-contract.ts
chat/lib/rhodes-mutation-tools.ts
chat/rhodes-worker/mcp-server/tools/tasks.ts
docs/task-board/FEATURE.md
packages/contracts/src/agent-run-protocol.ts
packages/contracts/src/agent-tool-registry.ts
packages/contracts/src/rhodes-mutation-proposal.ts
scripts/check-monitoring-cron-coverage.test.mjs

### Deliberately excluded for later phases

- Team Tasks filters, grouping, and shareable URLs are owned by AERIE-2743.

- Final navigation, creation entry points, migration execution, verification, and launch-gate removal are owned by AERIE-2744.

- Weekly digests are not part of V1.

- Watching does not add Task management or lifecycle authority.

- This PR does not run the participant backfill or enable AERIE_TASK_BOARD_ENABLED.

---

## Test plan

### Automated validation

- Retained AERIE-2742 Chat evidence: 10/10 files, 147/147 tests passed (pnpm --dir chat exec vitest run components/task-board/my-tasks-view.test.tsx components/task-board/task-detail.test.tsx components/task-board/task-participation-actions.test.tsx convex/migrations/taskParticipants.test.ts convex/publicApi/v2/domains/workManagementTaskBoardWrites.test.ts convex/publicApi/v2/siteNotes.test.ts convex/rhodesMcpMutationParity.test.ts convex/taskBoard/digest.test.ts convex/taskBoard/watchers.test.ts lib/public-api/v2/domains/work-management-task-board.node.test.ts).

- Full Task Board suite: 11/11 files, 95/95 tests passed (pnpm --dir chat exec vitest run convex/taskBoard).

- Portfolio Workbench regression suite: 67/67 passed (pnpm --dir chat exec vitest run components/dashboards/portfolio/__tests__/portfolio-rhodes-workbench.test.tsx).

- OpenAPI suite: 14/14 passed (pnpm --dir chat exec vitest run --project node lib/public-api/v2/openapi.node.test.ts).

- Final focused AERIE-2742, API/MCP parity, and agent allowlist gate: 14/14 files, 295/295 tests passed.

- Monitoring cron checks: 3/3 passed (node --test scripts/check-monitoring-cron-coverage.test.mjs).

- Full workspace typecheck: passed (pnpm typecheck).

- Full static/lint suite: passed with 2 unrelated existing warnings in chat/skill/forge-api/scripts/sindri.mjs (pnpm lint).

- Architecture boundaries, Convex path checks, read-bound checks, test architecture, knowledge hygiene, Biome, and git diff --check 09e3828351d6293a3282edfa2bc0519fa382522e..HEAD: passed.

- Exact-head diff scope: 54 paths, 2,526 additions, 79 deletions, and 15 AERIE-2742 commits on current main 09e3828351d6293a3282edfa2bc0519fa382522e.

- Test reviewability: the essential test delta is net +889 lines (894 additions, 5 deletions), down from the original net +1,514 (1,519 additions, 5 deletions), a 41.3% reduction while retaining watcher bounds, digest projection transitions, UI actions/read-only behavior, authorization, pagination, schedule, API/MCP parity, and real regression coverage.

- Independent review: PASS on the final 15-patch content, including the one-line agent allowlist integration repair; the conflict-free rebase produced exact head c4509829065470557ec24869abb1cb8256ed58d7 with all patches equivalent.

The PR remains Draft, is based directly on current main at 09e3828351d6293a3282edfa2bc0519fa382522e, and contains the final approved AERIE-2742 delta after AERIE-2741 merged at 17add4b9c3b54c1c3576d56023480266ef19a587.

### Time for Implementation

About 2 weeks for an engineer without AI assistance, including implementation, tests, independent review repairs, stack reconstruction, and release preparation.

## Review repairs and contract clarifications

Review [37820195787](https://github.com/AI-Builder-Team/Aerie/actions/runs/37820195787) was classified under [AERIE-2742](https://linear.app/builder-team/issue/AERIE-2742/add-participant-comments-watchers-and-the-daily-task-scenario-digest) at reviewed head c4509829065470557ec24869abb1cb8256ed58d7. No production repair is warranted because each reported blocker is contradicted by the approved contract or the complete runtime path:

- Portfolio visibility is deliberate. docs/task-board/FEATURE.md defines Team Tasks as portfolio-wide, states that Portfolio users can view Tasks across all sites, permits those users to comment on visible Tasks, and explicitly excludes site-specific Task permissions. operations.portfolio.read is the existing Portfolio-access capability, so the final branch of canViewTask implements that locked decision.

- The public comment response already satisfies WorkManagementTaskComment. listTaskComments returns the comment-owned fields, then the shared responseFor serializer attaches the fully resolved SiteReference to every row before the HTTP response is emitted. The focused HTTP test observes { id, slug, displayName } on the comment row; the cited internal projection is not the published response boundary.

- Watcher projection does not silently erase a Task. The only production watcher writer validates an existing active Aerie user before persisting the reference. User public IDs are globally verified before directory-backed API reads, every new user path mints one, and production user administration does not hard-delete user rows. If stored reference integrity were nevertheless broken, projectTask returns integrity_error and the HTTP boundary emits explicit 503 work_management_reference_integrity_failed; it cannot return a successful page with the Task omitted.

- Public API and MCP participation writes intentionally require operations.tasks.write. The feature contract says credentials may manage Tasks when both the credential scope and owner have that capability and explicitly declines a participant-only API capability in V1. In-app participant and Portfolio self-service continues through the canonical Task authorization path and is not narrowed by that automation boundary.

The boundaries remain unchanged: Portfolio access is portfolio-wide; relationship-based access remains Task-scoped for users without Portfolio access; watcher membership grants visibility but no lifecycle authority; API credentials remain management automation rather than participant impersonation; and all new behavior remains behind the production Task Board gate.

Validation on the reviewed head remains green: hosted CI is green, and the focused public Task Board API suite passes 11/11 tests (pnpm --dir chat exec vitest run convex/publicApi/v2/domains/workManagementTaskBoardWrites.test.ts --maxWorkers=1). This clarification changes no code, data, deployment behavior, migration state, or production traffic.

## Summary

Follow-up to #1752 ([AERIE-2753](https://linear.app/builder-team/issue/AERIE-2753/make-google-sheets-and-excel-documents-searchable)).

- One-off conversion of link documents that are really managed Drive files. New internal action globalDocumentDrive:convertManagedRootLinks. It goes through every live Global document registered as an external link and pulls the file ID out of each Google Docs, Sheets, Slides or Drive link. It then asks the Worker to verify the file, the same check the Register and Replace flows use. A file that turns out to be inside the managed Global Drive folder becomes a managed Drive document, and that change queues it for indexing. Links outside the folder, non-Google links and anything the Worker can't verify are left unchanged.

- dryRun: true reports what it would convert without writing anything.

- It's safe to run again. Converted rows are no longer links, and a row that changed between the listing and the write is skipped.

- Fix: switching a link to a Drive file in the Edit dialog now drops the old link. updateVerifiedDrive patched the Drive fields onto the row but left externalUrl behind, so the document ended up with both sources.

## Why it's needed

Some Global documents were registered as links even though the file is already in the managed folder. Those rows are never indexed. Converting them by hand means opening Edit on each one.

## Changes

- chat/convex/globalDocumentDrive.ts: googleDriveFileIdFromUrl and the convertManagedRootLinks internal action.

- chat/convex/globalDocuments.ts:

- listExternalLinkPage: an internal paginated query over live Global link documents.

- convertExternalLinkToVerifiedDrive: an internal mutation that checks the row is still the same link, keeps the title, type, topic and notes, switches the source to Drive, and writes a global_document.updated audit entry with a fixed reason.

- updateVerifiedDrive now clears externalUrl.

## Running it (after deploy)

npx convex run globalDocumentDrive:convertManagedRootLinks '{"dryRun": true}' --prod
npx convex run globalDocumentDrive:convertManagedRootLinks '{"dryRun": false}' --prod

The result lists the converted documents and the links outside the managed folder, plus counts for non-Google links, verification failures and rows that changed mid-run. Converted spreadsheets only become searchable once #1752 is deployed, so run it after that release.

## Breaking changes

None.

## Test plan

- [x] Google link parsing: Sheets, Docs (/u/1/), Slides on a workspace /a/<domain>/ path, Drive /file/d/ and open?id= links. Rejects published /d/e/ links, folders, look-alike hosts, http: and malformed URLs.

- [x] Dry run reports one converted, one outside the folder, one non-Google link and one verification failure, and writes nothing.

- [x] Real run converts only the verified link: Drive fields set, externalUrl removed, metadata kept, indexing state switched to Drive with a new generation, one audit entry with the reason. Other rows unchanged. A second run converts nothing.

- [x] A row whose link changed after listing is skipped.

- [x] Edit dialog link-to-Drive switch no longer leaves externalUrl behind.

- [x] Related suites (Global documents, document knowledge, MCP mutation parity, v2 API, admin page): 19 files, 306 tests passed.

- [x] pnpm typecheck and Biome are clean.

## Summary

- accept partial End-of-Year historical observations when their required operands are complete

- keep unavailable observations on the existing weekly fallback path

- align the reconciliation assertion and deterministic dbt fixture with the selection rule

## Validation

- YAML fixture parsing passed

- git diff --check passed

- local dbt execution unavailable because the Aerie bran_dbt Redshift profile is not configured in this checkout; PR dbt CI is the execution validation

## Summary

- Move GitHub triage access to the organization-owned App while preserving historical issue recovery.

- Pace and cache repository research, distinguish access failures from throttling, and bound retries and memory.

- Add exact line-range source reads and document GitHub, Linear, and system-owned Diagnostics credentials.

## Why

AERIE-2783 removes the departing member's GitHub dependency. AERIE-2788 addresses code-search 403s and truncated source evidence that prevented a complete assessment. Searches now honor provider cooldowns, expose safe failure categories and rate metadata, and explicitly report exhausted evidence. Large files can be inspected beyond the previous response cutoff. Linear and Diagnostics replacements are already installed in GitHub production and the live Worker; Diagnostics uses a non-expiring review-only key owned by Aerie System Agent.

## Business Value

Triage retains team-managed access after the member exits and can gather source evidence without repeatedly hitting search limits or treating throttling as lost access.

## Test plan

- [x] 84 Worker tests; typecheck, build, and Wrangler deployment dry run.

- [x] Hermetic primary/secondary throttling, retry exhaustion, cancellation, cache byte bounds, permissions, and large-file range tests.

- [x] Seven-lane adversarial review; cache memory and partial-line findings fixed.

- [x] Prior live GitHub canary created #1750 with the replacement bot and matching Diagnostics receipt; Linear duplicate search verified live.

- [x] System-owned Diagnostics credential authenticated review-packet read returned 200; replaced personal key revoked.

- [x] Read-only live check with replacement App: code search returned six results; duplicate search used cache; exact production source lines 3000–3100 retrieved (6910 total lines).

- [ ] Release the research fix, run the final bounded combined canary, and verify the first hourly execution. Scheduling remains disabled pending that validation.

## Summary

This PR is Phase 10 of 13 in the larger [Human Task Assignment from Aerie](https://linear.app/builder-team/project/human-task-assignment-from-aerie-b3582376ae6e) project.

It adds the approval and review workflow for Tasks after completion submissions and Task-linked documents. This phase is tracked by [AERIE-2741: Add Task approval and review actions](https://linear.app/builder-team/issue/AERIE-2741/add-task-approval-and-review-actions).

Production effect: dormant/additive. The new Task Board remains behind AERIE_TASK_BOARD_ENABLED. Merging this PR does not expose the approval interface, API operations, agent tools, or notification delivery in production. The final launch phase owns removing that gate.

---

## Why

A Task that needs review must not close merely because an assignee submits work. This slice gives Aerie one consistent approval workflow across the UI, public API, and agent tools, while preserving the submission and review history when changes are requested or an approval is removed.

AERIE-2742 depends on these actions so comments, watchers, and digests can describe approval work correctly.

---

## Business Value

- Assignees can submit work for review without presenting it as completed.

- Eligible approvers can approve, request changes, or remove an approval from the same Task.

- Requesters can choose whether approval is required and name one or more eligible approvers.

- People and authorized agents use the same rules and receive the same Task result.

- Review history and notifications make approval decisions traceable.

### What it means for end users and consumers

| User or consumer | What this phase adds when the Task Board is launched |

| --- | --- |

| Assignee | Submitting a Task that does not require approval completes it. Submitting one that requires approval changes it to Awaiting approval. |

| Eligible approver | Can approve the current submission, request changes with an explanation, or remove an approval that was applied by mistake. Any one listed approver may approve. |

| Requester or creator | Can make approval optional or required and choose eligible approvers while the Task is still editable. If approval is required and no approver is supplied, the requester becomes the approver. |

| Task manager | Can manage the Task, but must be listed as an eligible approver before approving it. |

| API and agent clients | Receive the same requiresApproval, Awaiting approval, approval, request-changes, and remove-approval behavior through the existing Task API and tools. No second Task API is introduced. |

| Notification consumer | Receives gated in-app and email events when approval is requested, granted, or returned for changes. |

| Existing Task | Remains unchanged unless the gated Task Board workflow is used. Approval is not inferred from an old approver list. |

---

## How does it work

1. Task creation and editing accept an explicit requiresApproval choice and an eligible-approver list. Requiring approval with no supplied approver uses the requester; disabling approval clears the list.

2. A completion submission either completes the Task immediately or changes it to awaitingApproval, depending on that explicit choice.

3. Approval checks the authenticated actor against the eligible approvers, binds the decision to the current immutable submission, records the actor and time, and completes the Task.

4. Request changes requires an explanation, keeps the reviewed submission and evidence, and returns the Task to inProgress. Remove approval preserves history and returns a completed Task to awaitingApproval.

5. The UI, public API, and agent tools call the same approval rules with idempotency and concurrency protection. Gated notification events are queued for pending approval, approval, and requested changes.

6. Stale browser responses are ignored when a user moves between Tasks, so an old request cannot alter the newly opened Task's saving state, messages, or idempotency keys.

---

## Scope

### Included in this phase

- Explicit optional approval configuration with one or more eligible approvers.

- awaitingApproval submission, approval, request-changes, remove-approval, and rejection rules.

- Task-scoped approver access without broader site access.

- Approval actions in the gated Task detail experience.

- Matching public API and agent actions on the existing Task contract.

- Gated in-app and email notification events with retry-safe append receipts.

- Protection against stale approval responses after navigating between Tasks.

- Exact final diff paths:

chat/components/dashboards/portfolio/__tests__/portfolio-rhodes-workbench.test.tsx
chat/components/dashboards/portfolio/portfolio-rhodes-workbench.tsx
chat/components/rhodes-cards/rhodes-read-card.tsx
chat/components/task-board/my-tasks-view.test.tsx
chat/components/task-board/my-tasks-view.tsx
chat/components/task-board/task-approval-actions.test.tsx
chat/components/task-board/task-approval-actions.tsx
chat/components/task-board/task-editor.test.tsx
chat/components/task-board/task-editor.tsx
chat/convex/_generated/api.d.ts
chat/convex/notifications/events.ts
chat/convex/notifications/schema.ts
chat/convex/publicApi/v2/domains/workManagement.ts
chat/convex/publicApi/v2/domains/workManagementTaskBoardWrites.test.ts
chat/convex/publicApi/v2/domains/workManagementWrites.test.ts
chat/convex/publicApi/v2/http.ts
chat/convex/publicApi/v2/workManagementData.ts
chat/convex/publicApi/v2/workManagementWrites.ts
chat/convex/rhodes/portfolioWorkbench.ts
chat/convex/rhodes/runtime/constants.ts
chat/convex/rhodes/runtime/mutationAuthorization.ts
chat/convex/rhodes/runtime/mutationDispatcher.ts
chat/convex/rhodes/runtime/writes/taskWrites.ts
chat/convex/rhodes/schema.ts
chat/convex/rhodesMcpMutationParity.test.ts
chat/convex/taskBoard/appendReceipts.ts
chat/convex/taskBoard/approval.test.ts
chat/convex/taskBoard/approval.ts
chat/convex/taskBoard/assignmentModel.ts
chat/convex/taskBoard/assignments.test.ts
chat/convex/taskBoard/completion.test.ts
chat/convex/taskBoard/completion.ts
chat/convex/taskBoard/mutations.test.ts
chat/convex/taskBoard/mutations.ts
chat/convex/taskBoard/notifications.ts
chat/convex/taskBoard/peopleBound.ts
chat/convex/taskBoard/queries.test.ts
chat/convex/taskBoard/queries.ts
chat/lib/public-api/v2/domains/work-management-schemas.ts
chat/lib/public-api/v2/domains/work-management-task-board.node.test.ts
chat/lib/public-api/v2/domains/work-management.ts
chat/lib/rhodes-mutation-tools.ts
chat/rhodes-worker/mcp-server/tools/tasks.ts
docs/task-board/FEATURE.md
packages/contracts/src/agent-tool-registry.ts
packages/contracts/src/public-api-v2.ts
packages/contracts/src/rhodes-mutation-proposal.ts

### Deliberately excluded for later phases

- Participant comments, watchers, and the daily Task Scenario digest: AERIE-2742.

- Team Tasks views and filters: AERIE-2743.

- Removing the launch gate, production verification, and final Task Board launch: AERIE-2744.

- Multi-stage or unanimous approval. V1 closes after any one eligible approver approves.

- A general Reopen action. Request changes and Remove approval cover the approved V1 cases.

---

## Test plan

### Automated validation

- Focused approval and regression suites — 182/182 passed across 11 files (including legacy flag-off writes, gated Task Board writes, approval lifecycle, UI, API, MCP, and Rhodes parity)

- Flag-off assignability regression — red before repair (create returned 201, expected 422), then green 10/10 after restoring shared userIds validation for requiredApprovers; both create and update assert requiredApprovers_user_not_assignable

- Original hosted-failure reproduction after repair — 96/96 passed across 3 files (route-manifest parity, legacy work-management writes, and portfolio workbench)

- Full repository tests — all suites passed with the timing-sensitive contracts workspace constrained to one worker: contracts 1,337/1,337, Chat 12,136 passed / 18 skipped, all other workspace suites green, and root 154/154. Unconstrained pnpm test attempts hit only the unrelated existing 5-second agent-run-protocol timing limit; that file passed alone 20/20 and in the complete constrained contracts suite.

- Full repository check — passed (pnpm check), covering full lint/static validation and every workspace typecheck

- Architecture boundaries, Convex paths, bounded reads, test architecture, and knowledge hygiene — passed as part of pnpm check

- Biome — passed across 3,124 files; two pre-existing unrelated warnings remain in chat/skill/forge-api/scripts/sindri.mjs

- Pre-commit checks and git diff --check — passed

- Reviewed-slice equivalence before incremental repairs — stable patch ID 7df84e8a170e2ab8b67e788f992c9a1922ac667d was identical for prior reviewed slice de068754bc35663ef6cde6e7651d45f988e097fd..80d378569992dbf4056d5c716cc0b99f0fc395a0 and its exact 45-path rebuild c17409f3802fe73909732a3c9392b1f147e2a871..371a6ff7e5a34d379ba8dc77717f97f8ad270c4f

- Post-equivalence hosted-CI repair — five targeted compatibility/gating/test-harness edits only: gate the request-changes handler and operation ID, preserve legacy flag-off approver behavior and people-limit error translation, use valid unique-user cap fixtures, and add the three approval hooks to the portfolio workbench test mock

- Post-equivalence independent-review repair — restored assignability validation for both assignees and legacy flag-off requiredApprovers, with create and update regressions; no product behavior was newly selected

- Exact-parent ancestry — final head 0a22c45fd638b2c58cf19ffa63d84846ee1419d4 has merged main commit c17409f3802fe73909732a3c9392b1f147e2a871 as its direct parent

- Exact-head diff scope — only the 47 authorized paths listed above (+3363/-176)

- Hosted CI — passed on exact final head 0a22c45fd638b2c58cf19ffa63d84846ee1419d4: Test, Build, Cloudflare Workers build, both Docker builds, Typecheck, Lint + Boundaries, and Secret Scan are green in run [37766704117](https://github.com/AI-Builder-Team/Aerie/actions/runs/37766704117); Praxis and automatic Mercy also passed

### Time for Implementation

About 2 to 3 weeks for one engineer without AI assistance, including contract design, UI and API implementation, agent parity, notification behavior, regression coverage, and review repairs.

---

## Review repairs and contract clarifications

[Mercy exact-head review of 049384a94](https://github.com/AI-Builder-Team/Aerie/pull/1729#pullrequestreview-5456173366) reported one blocking requester-identity concern. No code change is warranted because the finding conflates the authenticated creator/audit actor with the Task's requester business role.

The approved Task contract deliberately keeps those identities distinct: creator is always derived from the authenticated Aerie user or API-credential owner, while requester may differ and defaults to creator when omitted. The agent flow preserves that boundary. requireCanMutateTool authenticates and authorizes the Aerie user before execution; the server passes that immutable user ID as actorUserId; createTask stores creator and audit actor from actorUserId; and the optional requester input is resolved only into the Task's requester participant. When approval is required and no approver is supplied, using requester as the default approver is also an explicit locked product decision. Supplying a different requester therefore neither changes the authenticated actor nor grants the caller another identity. Forcing requester to equal actor would remove an approved workflow rather than close an authorization bypass.

The remaining review items are explicitly deferred or nonblocking and do not alter the Task result, authorization boundary, or dormant production effect of this phase. Validation remains 182/182 focused tests, full repository checks green, and hosted CI green on the exact head. Production behavior remains gated by AERIE_TASK_BOARD_ENABLED; there is no deployment, migration, or external write from merging this phase.

---

## Mercy reconsideration on 049384a94

The [reconsideration review](https://github.com/AI-Builder-Team/Aerie/pull/1729#pullrequestreview-5456630835) withdrew the requester-identity concern after following the authenticated actor and requester paths separately. The same exact-code review found one reachable UI defect: removing the task query parameter through browser navigation left the old Task detail selected. The next head clears that selection and adds a focused browser regression.

The four findings marked blocking do not require production changes:

- Notification events persist actorUserId: args.actorUserId directly for every event type. The task-type conditional immediately below applies only to sourceTaskId and taskTitle; it does not control actor forwarding. Approval events therefore retain the actor used by eventToEmitArgs.

- The public Task response status enum already includes awaitingApproval at work-management-schemas.ts:333 under the same taskBoardEnabled() gate that exposes approval fields and operations. Gated approval responses validate against the gated enum.

- Completion submission clears closureReason, delayedReason, and blockedReason before a Task can enter awaitingApproval. Approval can only complete that current submission, so Remove approval cannot inherit those fields through any supported lifecycle path.

- Approval configuration resolves every approver from a current assignable person record. The production codebase has no path that hard-deletes a user row or converts a person principal into a non-person after configuration, so the proposed orphaned sole-approver state is not reachable through an owned production transition. Reconfiguration continues to revalidate every selected approver.

This branch has already incorporated review findings that did demonstrate real behavior, including request-changes launch gating, flag-off compatibility, assignability validation, and stale Task-switch response protection. The distinction here is therefore evidentiary, not a refusal to address review feedback: reachable defects have been repaired, while adding duplicate branches for states already excluded by the current code would increase complexity without changing production behavior.

---

## Mercy exact-head review on f625543cb

The [exact-head review](https://github.com/AI-Builder-Team/Aerie/pull/1729#pullrequestreview-5457313488) confirms that the earlier notification actor, gated status enum, stale metadata, orphaned approver, and deep-link concerns are resolved. The deep-link issue was the only reachable defect in that round and was repaired with a focused browser regression.

The four newly reported blockers do not identify reachable incorrect behavior:

- Gated Work Plan creation ignores the supplied status and always creates new. Gated edits require the supplied status to equal the stored status and omit status from updateTask. The broad argument validator therefore cannot create or transition a Task to awaitingApproval; only completion submission emits that state.

- The approved contract defines Awaiting approval as open review work and Completed and Rejected as the only generally immutable statuses. The immutable object under review is the completion submission and its evidence. Generic edits cannot change status, approval fields, the current submission, or review history; approval configuration remains separately guarded, including atomic eligible-approver replacement while review is pending.

- publicApiV2RequestGuardError rejects a missing or blank Idempotency-Key with 400 idempotency_key_required before dispatch. Approve, Remove approval, and Request changes all declare that guard as required when the Task Board gate is enabled, so their handlers never hash an absent public header.

- The optional idempotency hash on the two internal compatibility mutations exists because the same mutations also serve the flag-off legacy approval endpoints, which do not use append receipts. Every gated public call reaches them only after the router guard and passes the resulting non-empty hash. There is no accepted public payload that reaches the empty fallback.

No production code change is warranted for these four findings. The branch continues to accept and repair demonstrated defects while declining changes that would either duplicate an existing boundary or contradict the approved open-status lifecycle. Current main advanced only through unrelated dbt forecast files after this verdict; the next head will merge that main once without changing any reviewed Task path.

## Summary

Fixes [AERIE-2776](https://linear.app/builder-team/issue/AERIE-2776/retire-the-legacy-globaldocumentsremove-mutation). This is the cleanup that waited for #1725 to reach prod (it shipped in #1731 on 7 Oct).

- Global documents can no longer be hard-deleted. The legacy globalDocuments.remove mutation is gone. removeDocumentWithKnowledge, which every remaining delete path uses, now refuses Global rows with "Global documents are archived, not deleted." That covers the internal rhodes/documents.remove table mutation, Rhodes sync deletes, and the migration path. The MCP removeDocument tool already rejected Global documents.

- Edits require a reason. reason is now required on globalDocuments.update, globalDocuments.updateVerifiedDrive and the globalDocumentDrive.replace action. A blank reason is rejected, and every global_document.updated audit entry records it.

- A refused Reindex or Retry says why. The reindex and retry mutations now return the specific message (already queued or running, in the re-index cooldown, or held), and the admin page shows it instead of "No new indexing work was accepted". Retry now goes through the same requestGlobalDocumentReindex helper as Reindex, so both report refusals the same way; its audit entry still records reason: "retry".

## Why it's needed

remove and the optional reason were kept only so admin pages loaded before #1722 and #1725 kept working. Both releases are in prod, so archive is now the only way to take a Global document out of use, and every admin edit is explained in the audit log.

The toast fix came from prod: a manager clicked Reindex, saw no change (the document was already "Available"), clicked again, and got a generic error that hid the reason, which was that the first click had worked.

## Changes

- chat/convex/globalDocuments.ts: removed remove and its compatibility comment, and the now-unused removeDocumentWithKnowledge import. Made reason required on update and updateVerifiedDrive. reindex and retry return message. requestGlobalDocumentReindex takes an optional trigger ("reindex" or "retry") for the audit entry.

- chat/convex/globalDocumentDrive.ts: replace requires reason and always passes it through.

- chat/convex/documentKnowledge/lifecycle.ts: removeDocumentWithKnowledge rejects documentScope: "global" rows.

- chat/app/(main)/admin/global-documents/page.tsx: refused Reindex or Retry shows result.message first.

## Breaking changes

- Admin tabs left open since before the #1725 release (7 Oct, 4:48 PM CT) will get an error from Edit until they reload. The current page always sends a reason.

- Any internal script that hard-deleted Global documents now fails. Nothing in the repo does this.

## Test plan

- [x] Replaced the legacy remove parity test: api.globalDocuments.remove no longer exists, and internal.rhodes.documents.remove on a Global document is rejected with the row still present.

- [x] Drive replace without a reason is rejected. With a reason, the global_document.updated audit entry records it.

- [x] update without a reason or with a blank reason is rejected. With a reason, exactly one audit entry records it.

- [x] Page test: a refused reindex shows the server's specific message.

- [x] Related suites (Global documents, Drive, document knowledge, Rhodes document CRUD, Task Board documents, capacity automation, v2 public API, admin page): 48 files, 894 tests passed.

- [x] Full chat suite: 12,097 passed. The 15 failures (Forge API driver, Sindri contract, skill packaging, platform-error inventory, portfolio workbench) fail identically on clean main.

- [x] pnpm typecheck and Biome are clean.

## Summary

- Preserve a parent's quiet-run preference in dataset-triggered and pipeline-triggered descendants.

- Resolve the exact parent run before starting child work and persist the effective preference for further descendants.

- Accept period-containing recovery execution names and allow time for both parent lookup and child-record insertion.

## Why

The Enrollment recovery exposed a notification gap: dataset publication events identify their parent run but do not carry its manual-run notification preference. Downstream failures could therefore notify Google Chat despite an explicitly quiet recovery. Read the durable parent preference and apply it before processing starts.

## Business Value

Operators can recover enrollment data without sending failure notifications from automatic descendants; scheduled-run notifications remain enabled.

## Test plan

- [x] 32 create-run-record tests passed, including exact-parent inheritance, malformed/missing parents, and explicit child suppression.

- [x] 57 consumer CDK tests, 9 monolith stack tests, and TypeScript typecheck passed locally. All seven required CI checks passed on f762720a, including full CDK, Lambda, and runner suites, Ruff, Biome, frontend tests, and frontend typecheck.

- [x] Production recovery verified 20,861 unique Enrollment rows with exact SIS lineage; downstream run records retained suppression through student identity refresh.

- [x] A pre-existing Aerie Retention guard failed quietly (notification_sent: false), confirming real failure suppression. Its four unexplained residuals remain outside this PR.

Mercy reviewed f762720a with no blocking issues; sensitive-path policy reserves approval for a human. Seven independent adversarial review lanes completed; the two validated findings (execution-name compatibility and lookup latency) were fixed and re-reviewed. The generic CDK behavior covers dataset consumers and manifests opting into forward_upstream_execution_context.

The reviewed source captures the narrowly scoped recovery hotfix already applied to the shared helper and five consumer definitions. Deploy the updated helper before consumer definitions that select its additive run_options response.

## Summary

- Show DoA before DoP and explain both abbreviations with header tooltips.

- Add the legacy school and status filter experience to the SIS enrollment report.

- Keep filtered totals, drill-down, and CSV export aligned with visible rows.

- Size staffing columns responsively, preserving more space at full width and shrinking with the report pane.

## Validation

- Focused SIS enrollment and shared-filter suites: 72 tests passed.

- Chat TypeScript check passed.

- Test architecture check passed.

- Biome check passed on all changed files.

- Git diff check passed.

## Summary

- generate distinct End-of-Year and Start-of-Year weekly pace candidates at target-year grain

- classify opening program years and use weekly pace with known-only departures when comparable history is unavailable

- persist and publish complete weekly provenance, selected methods, raw operands, and rounding boundaries

- preserve coherent live-or-locked End-of-Year provenance and use resolved EOY returners for following-year forecasts

## Validation

- poetry run dbt parse --profiles-dir /home/ubuntu/aerie/control/dbt --no-partial-parse

- rendered changed models and parsed them as Redshift SQL with sqlglot

- git diff --check

Closes #1740

## Testing contract

### What this PR delivers

Switches Aerie to the reviewed Praxis action that publishes one Praxis check instead of separate Contract, System, Verification, and workflow checks. The single check keeps those three phases in its summary.

### Who uses it and where

Aerie maintainers trigger Praxis from a pull-request comment with @praxis-e2e. Authors and reviewers see the result in the pull request's checks.

### Conditions needed

- An open Aerie pull request targeting main.

- A comment containing the exact @praxis-e2e mention from a user with write, maintain, or admin permission.

- The normal Praxis AWS and GitHub configuration already installed for Aerie.

### Expected behavior and examples

- An accepted mention starts Praxis and creates one check named Praxis for the pull request's current head.

- The check summary always shows Contract, System, and Verification as internal phases.

- Contract rejection, system failure, or failed/unverifiable verification fails that same check; a passing investigation succeeds it.

- If the pull-request head changes during an active run, Praxis cancels that run on the old head. A new run starts from a new explicit mention.

- No separate Contract, System, or Verification checks are created.

### Limits and unanswered questions

This is an intentional direct cutover. It does not preserve compatibility with older Praxis action versions.

Linear: AI-983

## What changed

Replaces the published dictionary with Colin Guilfoyle's revised version of 2026-10-08. Published as-is, at Keval Shah's direction on 2026-10-08:

1. The revised dictionary, unchanged. Shorter (19 KB vs 39 KB), organised as purpose, identity and genesis, objects, calculations, and known traps. It corrects one claim in the current dictionary: tuition has no currency in the data, so "annual USD" was unsupported.

The publication test is updated for the new headings and wording. No route, contract or behaviour change.

## Verification

- All 44 operations are covered and the contract claims I checked hold (list filters, include=profile, Global document list bounds, insight parameters).

- Calculation rules match the upstream code as previously traced.

- A cold agent given only the skill, a key and this dictionary answered 14 of 14 prepared questions correctly, including the capacity and operating-versus-open traps.

- pnpm check passes (49 tests).

Not verified by me: the quality-bar scoring thresholds and the 1-to-3 diligence score semantics.

## Known trade-off

The DSS registry graded the current dictionary C+ against the data, mainly for served fields with no dictionary entry (eight findings, 2026-10-07). This revision defers field shapes to OpenAPI, so it does not close those findings and may score lower on that axis. Field coverage would be follow-up work.

## Business Value

The dictionary is what tells agents what Rhodes data means. This puts the Edu Ops owner's own wording in place of a version adapted from an earlier draft, which is the step needed before the definitions can be ratified.

## Manual Effort Estimate

About 3 hours by hand (verify claims against the contract and code, run a cold-agent test, adapt the publication checks). Proposed figure; Keval to confirm or adjust.

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

## Summary

- open the SIS enrollment report list-pane link at the student profile instead of the enrollment record

- keep the CSV enrollment-record URL and add a separate student-profile URL column

- update browser coverage for list navigation and both exported links

## Validation

- pnpm --dir chat exec vitest run components/dashboards/admissions/enrollments/sis/__tests__/sis-student-panel.test.tsx --maxWorkers=1 (23 passed)

- pnpm exec biome check chat/components/dashboards/admissions/enrollments/sis/sis-student-panel.tsx chat/components/dashboards/admissions/enrollments/sis/__tests__/sis-student-panel.test.tsx

- pnpm typecheck

## Summary

- Migrate Wrike summaries, Social Analysis, Action Hub, Zendesk ticket analysis, and Board Doc Brainlift/attachment summaries to Claude Sonnet 5.5.

- Set explicit medium effort through the Anthropic SDK's extra_body extension.

- Remove non-default sampling parameters and the unsupported ticket-analysis assistant prefill.

- Read Anthropic responses by text-block type and reject incomplete or empty responses.

## Validation

- uv run ruff format — passed.

- uv run ruff check — passed.

- Targeted callsite, Action Hub, and Board Doc tests — 82 passed.

- Full tests/board_doc/ suite — 5,188 passed, 2 deselected. The rerun used a short temp path after the default macOS temp path exceeded the Unix socket path limit.

- git diff --check — passed.

- Pyright reports 15 errors and 21 warnings on changed modules; comparison with origin/main found no new diagnostics.

No AWS deployment was performed.

## Summary

This PR is Phase 9 of 13 in the larger [Human Task Assignment from Aerie](https://linear.app/builder-team/project/human-task-assignment-from-aerie-b3582376ae6e) project.

It adds and gates the canonical link between a Task and an Aerie document. It reuses the existing Site document upload mechanics, lets users select an existing document from the Task's Site, and gives Task participants a supported way to open linked files without granting access to the entire Site. This phase is tracked by [AERIE-2740 — Link and upload Aerie documents for Tasks](https://linear.app/builder-team/issue/AERIE-2740/link-and-upload-aerie-documents-for-tasks).

Production effect: dormant/additive. The new Task document UI, public API, and agent tools stay behind the existing Task Board launch gate. Merging this stacked PR does not enable the Task Board, start uploads, mutate existing Tasks, or change the current Site document upload experience.

### What it means for end users/consumers

| Surface | After this PR merges while the launch gate is off | After the Task Board is launched |

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

| Existing Work Plan and Site document upload | No visible change. Existing upload behavior remains available. | Existing behavior remains available. |

| My Tasks and Task details | Still hidden by the Task Board gate. | A Task participant can upload or attach a same-Site document as completion evidence and open linked files. Task creators, requesters, and Task managers can also manage source links. |

| Public Task API | New document operations remain unavailable while the gate is off. | Authorized callers can list, link, and unlink Task documents through the same Task authorization rules. |

| Agents | New Task document tools remain unavailable while the gate is off. | Authorized agents can use the same document workflow as the UI and API. |

| Site access | No permission change. | Opening a Task-linked document does not grant access to the rest of the Site. |

---

## Why

Text and URL evidence cannot safely represent files uploaded directly to Aerie. Task participants may also need a file even when they do not have wider access to the related Site. This slice establishes one Task-scoped document relationship and a verified open path before approval, comments, digests, and Team Tasks depend on those files.

---

## Business Value

- Lets people attach photos, PDFs, and other Aerie documents to Task work without creating a second upload system.

- Lets assignees attach completion evidence and open a linked file without receiving source-management or broader Site permissions.

- Gives the UI, public API, and agents the same document behavior and authorization rules.

- Prevents Task uploads from triggering Due Diligence approval, Rhodes synchronization, or REBL3 writeback.

---

## How does it work

1. The Task details panel lists eligible documents already owned by the Task's Site and records a separate Task-to-document link when one is selected.

2. New files use the existing Site upload-session, Drive upload, upload-complete, and document-registration mechanics. A small Task-specific wrapper supplies server-controlled metadata, returns only the upload instructions the Task UI needs, and links the resulting document to the Task.

3. The Task Board service lets assignees attach completion evidence while keeping source removal restricted to Task creators, requesters, and Task managers. It checks Task visibility before listing or opening a document. The download route obtains the file through the existing worker boundary rather than returning an unverified Drive URL.

4. The public API and agent tools call the same canonical Task document operations and preserve actor and time audit data.

5. Task deletion and document lifecycle logic remove or protect related links without changing the document's Site ownership. The entire new workflow remains unavailable while the Task Board launch gate is off.

---

## Scope

### Included in this phase

- A canonical Task-document relationship with Task, document, actor, and time data.

- Linking and unlinking eligible documents from the Task's Site.

- Uploading through the existing Site document upload mechanics and attaching the result to the Task.

- Task-scoped file access for Task participants without broader Site access.

- Completion-document attachment for assignees without granting source-management authority.

- Task-scoped upload responses that omit Drive folder identifiers.

- Matching UI, public API, and agent behavior.

- Security repairs at the reused upload boundary: server-owned Task metadata, delegated actor validation, Site containment checks, bounded responses, and safe user-facing errors.

- Exact final diff paths:

chat/app/(main)/api/rhodes/drive/__tests__/routes.node.test.ts
chat/app/(main)/api/rhodes/drive/register-document/route.ts
chat/app/(main)/api/rhodes/drive/upload-complete/route.ts
chat/app/(main)/api/rhodes/drive/upload-session/route.ts
chat/app/(main)/api/task-documents/[taskDocumentId]/route.node.test.ts
chat/app/(main)/api/task-documents/[taskDocumentId]/route.ts
chat/components/dashboards/portfolio/__tests__/portfolio-rhodes-workbench.test.tsx
chat/components/dashboards/portfolio/portfolio-rhodes-workbench.tsx
chat/components/task-board/my-tasks-view.tsx
chat/components/task-board/task-completion-panel.test.tsx
chat/components/task-board/task-completion-panel.tsx
chat/components/task-board/task-documents-panel.test.tsx
chat/components/task-board/task-documents-panel.tsx
chat/convex/_generated/api.d.ts
chat/convex/agentRuns.test.ts
chat/convex/documentKnowledge/lifecycle.ts
chat/convex/publicApi/v2/domains/workManagement.ts
chat/convex/publicApi/v2/domains/workManagementTaskBoardWrites.test.ts
chat/convex/publicApi/v2/http.ts
chat/convex/publicApi/v2/workManagementData.ts
chat/convex/publicApi/v2/workManagementWrites.ts
chat/convex/rhodes/mcp.ts
chat/convex/rhodes/runtime/constants.ts
chat/convex/rhodes/runtime/mutationAuthorization.ts
chat/convex/rhodes/runtime/mutationDispatcher.ts
chat/convex/rhodes/runtime/writes/taskWrites.ts
chat/convex/rhodes/schema.ts
chat/convex/rhodesMcpMutationParity.test.ts
chat/convex/taskBoard/completion.ts
chat/convex/taskBoard/completionHistory.ts
chat/convex/taskBoard/documentCleanup.ts
chat/convex/taskBoard/documents.test.ts
chat/convex/taskBoard/documents.ts
chat/convex/taskBoard/queries.ts
chat/convex/taskBoard/sourceAuthority.ts
chat/lib/__tests__/rhodes-delegation-server.node.test.ts
chat/lib/__tests__/rhodes-route-response.node.test.ts
chat/lib/platform-error-coverage-inventory.ts
chat/lib/public-api/v2/domains/work-management-schemas.ts
chat/lib/public-api/v2/domains/work-management-task-board.node.test.ts
chat/lib/public-api/v2/domains/work-management.ts
chat/lib/rhodes-delegation-server.ts
chat/lib/rhodes-mcp-contract.ts
chat/lib/rhodes-mutation-tools.ts
chat/lib/rhodes-route-response.ts
chat/lib/task-board/document-upload.ts
chat/rhodes-worker/lib/google-drive/client.test.ts
chat/rhodes-worker/lib/google-drive/client.ts
chat/rhodes-worker/mcp-server/tools/portfolioParity.test.ts
chat/rhodes-worker/mcp-server/tools/tasks.ts
chat/rhodes-worker/src/index.ts
chat/rhodes-worker/src/portfolio-document-payload.test.ts
chat/rhodes-worker/src/portfolio-document-payload.ts
chat/rhodes-worker/src/task-document-response.test.ts
chat/rhodes-worker/src/task-document-response.ts
packages/contracts/src/agent-run-protocol.ts
packages/contracts/src/agent-tool-registry.test.ts
packages/contracts/src/agent-tool-registry.ts
packages/contracts/src/rhodes-mutation-proposal.ts

### Deliberately excluded for later phases

- Approval and request-changes actions — AERIE-2741.

- Participant comments, watchers, notification events, and the daily Task Scenario digest — AERIE-2742.

- Team Tasks and portfolio-wide grouping/filtering — AERIE-2743.

- Launch-gate removal and final production verification — AERIE-2744.

- Mobile-specific completion and evidence-upload optimization — explicit post-V1 follow-up.

- Any new upload provider or separate Task file store. This phase deliberately reuses the existing Site document flow.

---

## Review follow-up

Mercy identified ten substantive boundary defects across the review rounds, and all ten are repaired on the branch or in the next repair head. Earlier repairs made malformed present Task IDs fail closed, protected worker-only Drive projections with the shared secret, whitelisted public Task-upload responses, rejected malformed Worker payloads, enforced TLS and complete Convex-host rejection for shared-secret forwarding, preserved aggregates for legacy documents without public IDs, failed closed on dangling Task-document joins, and restricted the public document proxy to 200 content or a 303 redirect with Location.

The exact-head review of ad517b183 found two further reachable local failures. A successfully unlinked document could remain selected in an in-progress completion draft, causing the next submission to reference a relationship that no longer exists; successful unlink now removes that document ID from the pending selection, while failed unlink leaves the draft unchanged. The Task upload-session route could also return 200 for blank upload URLs or non-positive, non-integer, or non-finite chunk sizes; it now rejects those provider responses before the browser starts an unusable upload. The same explicit success signal also preserves the file input after a failed upload so the user can retry the same file.

The required-argument rolling-compatibility proposal remains outside this phase's reachable production behavior. This phase is dormant/additive behind the existing Task Board launch gate: neither an old nor a new production Chat container can invoke Task completion while the feature is disabled, so the mixed-version window cannot produce the alleged rejected completion. Adding a legacy optional branch here would broaden the canonical mutation contract without protecting an active caller; launch and gate removal remain owned by AERIE-2744.

The repeated compensating-deletion proposal also remains deliberately excluded. Upload completion proves that the supplied Drive ID is inside the authorized Site root, but it does not prove that this request created that file; deleting it after Convex registration failure could destroy a pre-existing Site document. The safe failure mode leaves the verified Site-owned file intact and permits registration retry with the same ID.

The full focused Task-document suite passes 156/156, Biome and diff checks pass, and the full Chat/Convex typecheck passes. The Rhodes Worker suite remains 282/282 from the earlier review round. Production effect remains dormant/additive: no launch gate, deployment, migration, external write, or existing Site-upload behavior changes.

---

## Test plan

### Automated validation

- Focused Chat Task document, API, route, UI, and parity suites — 155/155 passed (pnpm --dir chat exec vitest run 'app/(main)/api/rhodes/drive/__tests__/routes.node.test.ts' 'app/(main)/api/task-documents/[taskDocumentId]/route.node.test.ts' components/task-board/task-completion-panel.test.tsx components/task-board/task-documents-panel.test.tsx convex/publicApi/v2/domains/workManagementTaskBoardWrites.test.ts convex/rhodesMcpMutationParity.test.ts convex/taskBoard/documents.test.ts lib/__tests__/rhodes-delegation-server.node.test.ts lib/__tests__/rhodes-route-response.node.test.ts lib/public-api/v2/domains/work-management-task-board.node.test.ts --maxWorkers=1)

- Full-suite integration regressions — 6/6 passed (pnpm --dir chat exec vitest run components/dashboards/portfolio/__tests__/portfolio-rhodes-workbench.test.tsx -t uses.the.canonical.gated.lifecycle.actions.when.editing.a.Work.Plan.Task --maxWorkers=1 and pnpm --dir chat exec vitest run lib/__tests__/platform-error-smoke-inventory.node.test.ts --maxWorkers=1)

- Rhodes Worker suite — 282/282 passed (pnpm --dir chat/rhodes-worker test)

- Chat and Convex typecheck — passed (pnpm --dir chat typecheck)

- Test runtime architecture — passed (pnpm lint:test-architecture)

- Architecture boundaries — passed (pnpm lint:boundaries)

- Convex path validation — passed (pnpm lint:convex-paths)

- Bounded-read validation — passed (pnpm lint:read-bounds)

- git diff --check — passed

- Rebase equivalence — the rebased AERIE-2740 implementation matched the independently reviewed tree before adding the two test-integration repairs found by hosted CI

- Exact-head diff scope — only the authorized paths listed above

### Time for Implementation

An engineer without AI assistance would likely need 5 to 7 working days to trace the existing upload path, implement the Task relationship and access boundary across UI/API/agents, add tests, and complete review and rebase work.

## Summary

- persist the three shared admissions forecast boundaries that caused repeated Redshift plan expansion

- rewrite enrollment cohort membership as one classification scan while preserving exact row output

- add guarded, dry-run-first cleanup for experiment-prefixed dev relations

## Baseline

PR #1721 (37664352665) took 10m16s for models/seeds and 16m07s for 628 tests. Redshift attributed 162.40s planning vs. 23.00s execution to int_admissions_forecast_resolved. The slow forecast tests spent 74.47–110.18s planning and only 1.18–3.71s executing, with zero queue time.

## Research log

### Hypothesis => persist int_admissions_forecast

Test and result => In isolation the table took 66.99s. Two consumers fell to 1.11s and 1.80s, while forecast resolution remained 138.47s through the milestone view chain.

Confirmed or refuted => Refuted in isolation. Retained only as part of the combined three-boundary solution, where persisted milestone inputs reduce its producer cost.

### Hypothesis => persist milestone observations

Test and result => The table initially took 18.43s. A prototype decomposition built its milestone position, departure aggregate, and final contract in 5.62s, 3.63s, and 4.80s. Production and experiment each returned 423 rows with zero bidirectional deterministic-column differences.

Confirmed or refuted => Partially confirmed. The decomposition changed the model's direct-parent contract and invalidated ten unit-test fixtures, so it was reverted. The public contract remains persisted because it removes repeated planning from hundreds of tests.

### Hypothesis => persist milestone forecast and forecast inputs

Test and result => Milestone forecast built in 4.36s. The formerly slow terminal models fell to 1.12–3.41s. A prototype four-aggregate decomposition was rejected because it changed unit-test parent contracts.

Confirmed or refuted => Partially confirmed. The three public-contract tables are retained; rejected helper boundaries are not.

### Hypothesis => collapse repeated enrollment-cohort scans

Test and result => Replacing eight UNION ALL scans with one join to the 14-row cohort vocabulary reduced the model from 19.58s to 5.93s. All three owning unit tests passed. Production and experiment both contained 6,105 rows with zero full-row bidirectional differences.

Confirmed or refuted => Confirmed and retained.

### Hypothesis => collapse transfer-pair counting joins

Test and result => The deterministic unit test improved from 15.98s to 11.79s but remained over the 10-second gate.

Confirmed or refuted => Refuted and reverted.

## Representative result

- model/seed build: 10m16s → 3m29.80s

- full test phase: 16m07s → 2m45.04s

- formerly slow terminal forecast models: 64–223s → 1.12–3.41s

- 619 tests passed, 10 retained warnings, 0 errors

- Redshift reported zero queue time

The test phase beats both the 5-minute gate and 3-minute stretch target. Remaining strict gaps measured locally were two forecast producers over 10s, 93.64% of tests below 5s (target 95%), and five tests over 10s. This PR remains Draft until current-head CI, production parity, and Mercey review are complete.

## Validation

- poetry run dbt parse

- representative build: 131/131 nodes passed

- representative tests: 619 pass / 10 warn / 0 error

- enrollment-cohort unit tests passed

- cleanup dry-run and unsafe-schema refusal verified

- current-head production parity against fresh pr1738_ relations (SHA 43afc9c2f): zero bidirectional differences across all deterministic columns. Row counts matched for enrollment cohort (6,106), milestone observations (423), milestone forecast (423), forecast (122), resolved forecast (122), end-of-year resolved forecast (122), and published forecast mart (122). calculated_at was excluded only from the two milestone models and published mart because it is an invocation timestamp; all other columns were compared.

Closes #1735

## Summary

- Update both Income Statement AI summary calls from Claude Opus 4.1 (deprecated) to Opus 4.8.

- Replace fixed-budget thinking with adaptive thinking at high effort.

- Preserve the existing tool-use loop and token limits.

## Validation

- Manually exercised the local POST /income-statement/ai-summary flow and polled its status endpoint; the task completed and returned an appropriate summary.

- uv run ruff format routers/income_statement.py — passed.

- uv run ruff check routers/income_statement.py — passed.

- git diff --check — passed.

- uv run pyright routers/income_statement.py reports 30 errors and 33 warnings, matching the baseline on origin/main.

- Automated pytest was not run.

## Screenshots

<img width="1524" height="777" alt="image" src="https://github.com/user-attachments/assets/4c92219c-bbe0-4978-93de-24ef9df38960" />

## Summary

- Migrates passive-investment Claude analysis calls from deprecated model to claude-sonnet-5-5.

- Sets Sonnet 5.5 request options and adjusts token budgets.

- Adds shared response-text extraction and explicit refusal handling while preserving OpenAI fallback for other Claude errors.

- Updates the bundled legacy helper and adds focused response-handling tests.

## Validation

- python3 -m pytest tests -q — 5 passed.

- python3 -m compileall -q anthropic_response.py enhanced_ai_analysis.py lambda_handler.py social_analysis_service.py — passed.

- ruff format --check on the five changed Python files — passed.

- ruff check on anthropic_response.py, social_analysis_service.py, and tests/test_anthropic_response.py — passed.

## AWS rollout already completed

- Saved the exact pre-update Lambda ZIP locally at .scratch/lambda-backups/passive-investment-email/20261008T052557Z/deployed-lambda.zip and published Lambda version 2 as the pre-update snapshot.

- Deployed this code to passive-investment-email in us-east-1, preserving its existing dependency versions and runtime configuration; published version 3 after the update.

- Updated Secrets Manager recipient routing to the operator mailbox for the manual check. The address is omitted here.

- Verified the manual invocation in CloudWatch: seven successful Claude-analysis markers and one successful SES send, with no refusal or matching failure markers.

- The daily EventBridge rule remains enabled and targets the unqualified function ($LATEST).

## Screenshots

<img width="977" height="777" alt="image" src="https://github.com/user-attachments/assets/3e5a0a2a-d010-4578-b84e-ce8a9e1f628c" />

## Summary

- Migrate the QuickBooks opportunity and Renewals risk-assessment callers from deprecated Claude Sonnet 4.5 to Claude Sonnet 5.5.

- Use adaptive thinking at high effort for QuickBooks, remove the fixed token-budget request path, and increase its total token cap to 24,000.

- Use the stable structured-output parser for Renewals, with explicit high effort and no up-front thinking, while preserving Pydantic parsing and the existing token cap.

- Add versioned Sonnet 5.5 token and list-price rows with verification SQL. Keep Sonnet 4.5 pricing for historical records.

## Verification

- QuickBooks package suite: 73 passed.

- Renewals package suite: 314 passed.

- Real API smoke tests succeeded: QuickBooks structured output, one QuickBooks web-search request, and the Renewals risk-assessment function using a synthetic record and the production Pydantic schema.

- Python syntax checks and git diff --check passed.

- Pricing SQL applied to finance_dw on 2026-10-08 in one transaction; verification returned one token-pricing row and three list-price rows with the expected values.

The real API smoke tests used synthetic inputs and made billable Anthropic API requests. No pipeline run or warehouse data write was performed by those tests.

## Rollout

The pricing rows are present in finance_dw. The SQL did not trigger a pipeline or application deployment.

## Summary

This PR is the sources-and-completion slice of the [Human Task Assignment from Aerie](https://linear.app/builder-team/project/human-task-assignment-from-aerie-b3582376ae6e) project.

It adds bounded Task sources, immutable completion submissions, text-or-URL evidence, and gated UI/API/agent workflows for Tasks that do not require approval. This phase is tracked by [AERIE-2739 — Add sources, completion submissions and text-or-URL evidence](https://linear.app/builder-team/issue/AERIE-2739/add-sources-completion-submissions-and-text-or-url-evidence).

Production effect: compatibility hardening. The Task Board gate remains off by default. Existing Work Plan, public API, and agent behavior remain unchanged; the new source and completion surfaces are unavailable until the gate opens. The only live gate-off work is an hourly bounded maintenance query against the new append-receipt table, which is empty until gated writes occur and causes no external traffic.

| Surface or consumer | Gate off after deployment | Gate on later |

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

| Existing Work Plan | Existing Task creation, editing, status, and deletion behavior remain unchanged. | Authorized users can manage generic sources and submit non-approval Tasks from the same canonical Task editor. |

| My Tasks and Task detail | The gated Task Board remains unavailable. | Participants can inspect append-only submissions and evidence, and eligible assignees can submit completion. |

| Public API | New source, submission, evidence, and history routes stay undiscoverable and unavailable. | Gated routes use the existing Task identity, capability, revision, and actor boundaries. |

| Agent and MCP tools | New completion-history tools are neither advertised nor registered. | Agents use explicit source and completion operations rather than generic Task edits. |

| Task status | No existing Task is changed. | A valid submission for a Task that does not require approval atomically records history and closes it as Completed. |

| Maintenance | One hourly bounded query sees an empty receipt table and performs no writes or external calls. | Expired 24-hour idempotency receipts are removed in bounded, resumable pages. |

| Delete | Existing Task deletion behavior remains available. | Source, submission, evidence, and append-receipt children are included in the existing bounded recoverable deletion model. |

---

## Why

A Task cannot serve as the operational record of completed work if the underlying source material, submission note, evidence, actor, and time are lost or overwritten. This slice adds that durable history before approval and document-linking phases, while keeping the launch gate closed and reusing the existing Task lifecycle rather than creating a parallel completion system.

---

## Business Value

- Keeps the request, supporting sources, completion explanation, and evidence together on the canonical Task.

- Gives non-approval work a complete path from assigned work to an immutable Completed record.

- Makes retries safe for users and agents, preventing duplicate sources or completion submissions.

- Preserves earlier submissions and evidence for audit and later approval-history references.

- Keeps deployment safe before launch: all new user-, API-, and agent-facing behavior remains behind the existing Task Board gate.

---

## How does it work

1. taskSources, taskCompletionSubmissions, and taskCompletionEvidence store bounded source and completion children with stable opaque public identities instead of growing arrays on the Task document.

2. Shared normalization enforces 50 sources per Task, 20 evidence items per submission, optional 120-character labels, 4,000-character text-or-URL values, and 5,000-character completion notes with clean user errors.

3. Source appends and completion submissions require scoped idempotency keys. Actor/API-key-bound receipts preserve replay results for 24 hours, reject key reuse with different content, and are swept hourly in bounded 100-row pages.

4. Submission authority reuses the canonical lifecycle rules for internal and external assignment. A successful non-approval submission atomically records the immutable submission/evidence, advances status and closure timestamps, writes audit history, and moves the Task to Completed.

5. Task detail, Work Plan, public API, and MCP surfaces expose the same sources and append-only completion history only while the Task Board gate is enabled.

6. Hard deletion snapshots and removes sources, submissions, evidence, and receipts through the existing bounded continuation model, preserving recoverability without making the Task undeletable.

---

## Scope

### Included in this phase

- Generic optional-label plus text-or-URL Task sources with add, edit, and remove actions.

- Immutable non-approval completion submissions, evidence items, stable identities, actor/time attribution, and history reads.

- Bounded cardinality and string-size enforcement shared across UI, public API, Work Plan, and agent paths.

- Actor- and credential-scoped append idempotency, replay responses, and bounded receipt retention.

- Gated Task Board UI, public API routes, MCP tools, agent registry entries, and Work Plan integration.

- Recoverable, bounded Task deletion coverage for all source/completion child records.

- Exact final diff paths:

chat/components/dashboards/portfolio/__tests__/portfolio-rhodes-workbench.test.tsx
chat/components/dashboards/portfolio/portfolio-rhodes-workbench.tsx
chat/components/task-board/my-tasks-view.tsx
chat/components/task-board/task-completion-panel.test.tsx
chat/components/task-board/task-completion-panel.tsx
chat/convex/_generated/api.d.ts
chat/convex/automations/cronRegistry.ts
chat/convex/crons.ts
chat/convex/lib/siteDetailAccess.ts
chat/convex/publicApi/routeManifest.test.ts
chat/convex/publicApi/v2/domains/workManagement.ts
chat/convex/publicApi/v2/domains/workManagementTaskBoardWrites.test.ts
chat/convex/publicApi/v2/http.ts
chat/convex/publicApi/v2/workManagementData.ts
chat/convex/publicApi/v2/workManagementWrites.ts
chat/convex/rhodes/mcp.ts
chat/convex/rhodes/runtime/constants.ts
chat/convex/rhodes/runtime/mutationAuthorization.ts
chat/convex/rhodes/runtime/mutationDispatcher.ts
chat/convex/rhodes/runtime/writes/taskWrites.ts
chat/convex/rhodes/schema.ts
chat/convex/rhodesMcpMutationParity.test.ts
chat/convex/taskBoard/appendReceipts.test.ts
chat/convex/taskBoard/appendReceipts.ts
chat/convex/taskBoard/completion.test.ts
chat/convex/taskBoard/completion.ts
chat/convex/taskBoard/completionCleanup.ts
chat/convex/taskBoard/completionHistory.ts
chat/convex/taskBoard/lifecycle.ts
chat/convex/taskBoard/queries.test.ts
chat/convex/taskBoard/queries.ts
chat/convex/taskBoard/visibility.ts
chat/lib/public-api/v2/domains/work-management-schemas.ts
chat/lib/public-api/v2/domains/work-management-task-board.node.test.ts
chat/lib/public-api/v2/domains/work-management.ts
chat/lib/rhodes-mcp-contract.ts
chat/lib/rhodes-mutation-tools.ts
chat/rhodes-worker/mcp-server/tools/portfolioParity.test.ts
chat/rhodes-worker/mcp-server/tools/tasks.ts
packages/contracts/src/agent-run-protocol.ts
packages/contracts/src/agent-tool-registry.test.ts
packages/contracts/src/agent-tool-registry.ts
packages/contracts/src/rhodes-mutation-proposal.ts
scripts/check-monitoring-cron-coverage.test.mjs

### Deliberately excluded for later phases

- Enabling the Task Board gate or changing production environment configuration.

- Linking or uploading Aerie documents for Tasks — AERIE-2740 owns document integration.

- Approval, request-changes, approve, and remove-approval actions — AERIE-2741 owns review workflows.

- Watchers, comments, daily digests, Team Tasks, or additional completion notifications.

- A separate completion-criteria field; the Task description remains the place to explain what counts as done.

- A second Task lifecycle/state field, new Task status values, or general Reopen/Withdraw actions.

- Any AERIE-2740+ implementation, schema, UI, API, MCP, migration, backfill, or rollout behavior.

---

## Test plan

### Automated validation

- Append receipt, completion, Task query, route manifest, public API write, and MCP parity suites — 147/147 passed (pnpm --dir chat exec vitest run --project edge convex/taskBoard/appendReceipts.test.ts convex/taskBoard/completion.test.ts convex/taskBoard/queries.test.ts convex/publicApi/routeManifest.test.ts convex/publicApi/v2/domains/workManagementTaskBoardWrites.test.ts convex/rhodesMcpMutationParity.test.ts --maxWorkers=1)

- Completion panel and Work Plan browser suites — 71/71 passed (pnpm --dir chat exec vitest run --project browser components/task-board/task-completion-panel.test.tsx components/dashboards/portfolio/__tests__/portfolio-rhodes-workbench.test.tsx --maxWorkers=1)

- Agent/MCP read-tool allowlist parity suite — 111/111 passed (pnpm --dir chat exec vitest run --project edge convex/agentRuns.test.ts --maxWorkers=1)

- Shared agent tool registry suite — 19/19 passed (pnpm --dir packages/contracts exec vitest run src/agent-tool-registry.test.ts --maxWorkers=1)

- Rhodes Worker MCP parity suite — 4/4 passed (pnpm --dir chat/rhodes-worker exec tsx --test mcp-server/tools/portfolioParity.test.ts)

- Monitoring cron coverage contract — 3/3 passed (node --test scripts/check-monitoring-cron-coverage.test.mjs)

- Append-receipt cron and monitoring registry suites — 95/95 passed (pnpm --dir chat exec vitest run convex/taskBoard/appendReceipts.test.ts convex/automations/monitoring.test.ts)

- Full workspace typecheck — passed (pnpm typecheck)

- Lint, Biome, architecture boundaries, Convex paths, read bounds, test architecture, and knowledge hygiene — passed with two existing unrelated Sindri string-template warnings (pnpm lint)

- wrangler deploy --dry-run — passed; 10,249.86 KiB upload / 3,223.62 KiB gzip (pnpm --dir chat/rhodes-worker exec wrangler deploy --dry-run)

- git diff --check origin/main...HEAD — passed

- Reviewed-slice equivalence — runtime patch applied without conflict; the three test-only resolutions retain merged AERIE-2738 site-binding/dispatcher assertions alongside AERIE-2739's reviewed assertions. One in-scope integration repair adds the two reviewed completion-history tools to the Worker's existing in-app MCP allowlist after exhaustive CI proved the new tools were otherwise filtered out. One test-only contract update raises the intentionally pinned monitored-cron count from 43 to 44 for this slice's reviewed append-receipt cleanup cron (git range-diff f4b5ec280..fe93bdeb8 origin/main..HEAD)

- Exact-head diff scope — only the 44 authorized paths listed above

### Time for Implementation

About 4 to 5 weeks for one engineer without AI assistance, including domain and API design, bounded persistence and cleanup, UI/API/agent integration, hermetic tests, independent review, dependency rebasing, and release validation.

---

## Review repairs and contract clarifications

The final repair pass independently validated Mercy review 5445618112 against AERIE-2739 and the deployed code paths.

Accepted and repaired in this PR:

- completion evidence is optional consistently across OpenAPI, HTTP, Rhodes, and Worker MCP inputs;

- expired idempotency receipts are removed transactionally before a key is reused, preventing duplicate indexed rows;

- Task visibility uses a boolean capability check without converting capability-resolution or database failures into Task-not-found;

- completion history projects the immutable public actor identity captured with each submission/review instead of re-resolving mutable live users;

- completion form inputs are locked while a submission is pending so successful saves cannot discard newer edits;

- exact actor-scoped retries consult a valid receipt before lifecycle-state authorization, preserving replay after completion or deletion without weakening first-call authorization.

The receipt-concurrency wording in the review was narrower than the actual defect: Convex OCC serializes conflicting mutations. The validated issue was expired-row reuse during the cleanup gap, which is now covered directly. The brief initial loading flash is not a production blocker for this gated slice and was deliberately not expanded into unrelated UI state work.

Added regressions cover note-only submission, immediate and post-deletion replay, expired-key reuse, immutable historical identity after a user change, and pending-form locking. Focused suites, Rhodes parity, the complete Rhodes Worker suite, full Chat/Worker typechecks, full lint, and architecture checks pass.

Mercy review [5447623737](https://github.com/AI-Builder-Team/Aerie/pull/1718#pullrequestreview-5447623737) was independently classified at reviewed head 12e27a5a4b0012cda824acefff03d2e90a885602.

Three reachable contract gaps are repaired in the next head:

- the shared Valibot agent schema now defaults omitted completion evidence to an empty list, matching OpenAPI, HTTP, in-app Rhodes, and remote MCP;

- the public completion writer persists the normalized note and evidence used to calculate its request hash, so hashing, storage, history, and replay use one canonical representation;

- source update and removal now carry the source updatedAt revision through UI, agent registry, in-app Rhodes, and remote MCP, and the committing mutation rejects a stale approved proposal before changing the source.

The generic create-replay finding is not applicable to the published Work Management contract. Its guidance explicitly says create replays return the same stable public identity using its current representation. publicApiWriteIdempotency is used only by the three existing create operations and binds the request to that identity; re-projecting its current representation is intentional. Source and completion appends have a different contract and continue to replay their recorded response snapshots, including after later mutation or deletion.

The merge conflict with current main was resolved by retaining both the Task parity types and main's new global-document test imports. Focused validation passes 149 assertions across shared contracts, completion persistence and concurrency, public API writes, browser behavior, Rhodes parity, and remote MCP parity; Chat, Convex, contracts, and Rhodes Worker typechecks pass.

Mercy review [5448260520](https://github.com/AI-Builder-Team/Aerie/pull/1718#pullrequestreview-5448260520) was independently checked against the request pipeline and gated mutation lifecycle.

Two reachable issues are repaired in the next head:

- every newly gated Task Board mutation now fails closed during site resolution, authorization, and dispatch when the launch gate is disabled, including approval of a mutation queued before the gate changed;

- the completion panel is keyed by Task identity, so changing Tasks remounts and clears every Task-scoped source draft, completion draft, evidence item, edit target, and idempotency key.

The malformed-optional-input finding is not reachable. Public requests are validated against each operation request schema by validatePublicApiV2Schema in the shared HTTP dispatcher before a domain handler runs. The schemas require labels to be strings when present and evidence to be an array when present; malformed values such as label: 42 or evidence: null receive 422 request_body_invalid before the handler casts or defaults anything. No handler change is warranted for that claim.

Focused regressions pass 108 assertions across the completion panel and Rhodes mutation parity, and the full Chat/Convex typecheck passes. The branch also includes current main through c735d60ae; the earlier parity-test conflict remains resolved.

Mercy review [5448758193](https://github.com/AI-Builder-Team/Aerie/pull/1718#pullrequestreview-5448758193) was independently checked against the cleanup state machine, the capability-filtered semantic projection, and the approved Task permission contract.

The cleanup finding is not valid. Each phase schedules itself only when batch.length < rows.length, which means the query returned an extra row beyond the bounded batch. For an empty phase, 0 < 0 is false and the scheduler receives the next phase. The existing hard-deletion regression traverses an empty review-action phase and passes, and the full completion suite passes all 13 cases.

The claimed cross-operation authorization bypass is also not the actual behavior: agent-context filtering is per object and workflow, and executable routes enforce their own operation capability lists. However, the review exposed a real gate-on catalog-validation failure because the Task semantic object referenced Work Unit objects protected by the unrelated diligence capability. The next head repairs that contract without violating the approved Task permission model: Task routes and Task discovery remain governed only by operations.tasks.write; the Task-only semantic view no longer declares cross-capability Work Unit relationships; gate-on anchor nullability, awaitingApproval meaning, and workflow steps are internally consistent; and a regression proves the entire enabled catalog validates while a Task-only credential sees only Task semantics.

Both gate-off and gate-on Work Management contract suites pass, the completion/deletion suite passes, Biome passes, and the pre-commit Chat typecheck passes. The branch includes current main through ebc63e2c0 with no conflict.

Mercy review [5449221611](https://github.com/AI-Builder-Team/Aerie/pull/1718#pullrequestreview-5449221611) was independently checked against the complete gate-on and gate-off catalogs, every Task deletion call path, and both public append authorization boundaries.

None of its three blocking mechanisms is present:

- Gate polarity is intentional. Gate-off preserves the legacy Task operations inside work-management.inspect-site-work; gate-on moves Task discovery and management into the dedicated work-management.manage-tasks workflow, whose operation list and request sequence both include listWorkManagementTasks.

- Every enabled deletion path converges on deleteTaskForActor, which calls deleteRuntimeTask; that runtime function schedules completionCleanup.snapshotAndRemove before deleting the Task. Agent, Work Plan, lifecycle, and public API deletion therefore preserve the same completion history.

- A deleted API-key owner cannot make a valid public API retry. HTTP authorization rejects a key whose owner no longer exists, and the committing mutation revalidates the live key and owner before reaching append logic. For an authorized live owner, the receipt lookup already precedes Task and lifecycle checks and replays the immutable stored response. Moving it ahead of the actor lookup would not make a deleted-owner request valid because finalization must still pass live authorization.

These claims require no code change. The branch already repaired the real issues identified throughout review, including receipt expiry, visibility error masking, immutable actor snapshots, pending-form locking, replay ordering, optional evidence, normalized persistence, stale source revisions, gate-off mutation fail-closed behavior, task-switch resets, and the enabled semantic-catalog inconsistency, with focused regressions for each class. The exact reviewed head passed every hosted check; the branch now includes current main through 1937e793b without conflict.

Mercy review [5449502382](https://github.com/AI-Builder-Team/Aerie/pull/1718#pullrequestreview-5449502382) withdrew the prior malformed-input, cleanup-phase, deletion-path, replay-ordering, and capability-bypass objections after checking the current code and discussion.

Its remaining blocker is not present in the serialized response. The internal completion-history queries intentionally return site-independent rows. Every Work Management response then passes through the shared responseFor boundary, which adds site: args.site.reference to every collection item before serialization as well as to the outer envelope. The existing HTTP regression asserts that each completion submission contains site, and the exact reviewed head passed that test in the full hosted suite. Review-action pages use the same response boundary. The required schemas and successful wire payloads therefore already match; no code change is warranted.

Mercy review [5449874850](https://github.com/AI-Builder-Team/Aerie/pull/1718#pullrequestreview-5449874850) rechecked and withdrew the cleanup, malformed-input, deletion, replay-ordering, and response-site objections. Its remaining source-concurrency blocker assumes the public Task ETag does not change when a source changes. That premise is false.

Public source PATCH and DELETE resolve the current Task through projectedTask, which always calls projectTask(..., { includeSources: true }). The projected representation includes every active source ID, label, value, createdAt, and updatedAt, and its revision is the SHA-256 hash of that complete representation. The mutation recomputes this representation and calls requireRevision before resolving or changing the source. Therefore client A changing a source changes the Task ETag; client B presenting the earlier ETag receives 412 work_management_revision_conflict before any source write or removal. The subsequent source-level expectedUpdatedAt check remains a second transactional guard. A separate source header would duplicate the existing public concurrency boundary rather than close a lost-update path.

The exact head remains fully green in hosted CI, includes current main, and changes no production behavior in response to this false premise.

Mercy review [5450093512](https://github.com/AI-Builder-Team/Aerie/pull/1718#pullrequestreview-5450093512) accepted and withdrew the source-concurrency blocker. Its remaining pagination-error blocker assumes the public Convex hook can return status: "Error". The installed Convex 1.45.0 implementation proves otherwise: public usePaginatedQuery calls usePaginatedQueryInternal(..., true), setting throwOnError; non-cursor query errors are thrown during render, while the public return union contains only LoadingFirstPage, CanLoadMore, LoadingMore, and Exhausted. The internal-only Error result exists solely when throwOnError is false and is excluded from UsePaginatedQueryReturnType.

Therefore neither history consumer can receive an Error status and render its results as an authoritative empty history. A query failure propagates to the React/Next error boundary instead of producing None or a blank successful state. Adding an impossible status branch would conflict with the installed public type without changing runtime failure behavior. The exact head remains fully green, current with main, and has no unresolved review threads.

## Summary

- select aligned historical expected arrivals first, then a complete observed weekly-pace candidate

- keep historical source provenance historical-only while publishing the selected method/value

- advance the coherent forecast publication to aerie_milestone_v4

- preserve the existing controlled unavailable reason when neither candidate is usable

## Validation

- poetry run dbt parse --no-partial-parse --vars '{pr_number: 1707}' --profiles-dir .

- poetry run dbt test --select int_admissions_forecast_resolved_session_1_selects_history_then_weekly_pace --vars '{pr_number: 1707}' --profiles-dir . (passed before dependency rebase; current isolated CI rebuilds the cleaned PR namespace)

- affected singular tests passed against the prior isolated pr1707_ build:

- assert_forecast_v4_publication_contract

- assert_forecast_session_1_expected_arrival_group

- assert_forecast_weekly_pace_diagnostic_contract

- assert_forecast_session_1_reconciles

- comparison of 99 history-selected rows against production V3 found 0 changes to status, unavailable reason, selected arrivals, new-student subtotal, forecast, or headline

- deterministic unit coverage includes history preference, measured-zero weekly fallback, incomplete weekly rejection, and post-opening lock behavior

Current warehouse data does not reproduce the ticket's Highland Park availability example: Highland Park 2027 selects history and remains unavailable because its preceding End-of-Year forecast is missing. The deterministic fixture proves the missing-history weekly fallback itself.

## Deployment dependency

Do not merge/deploy this V4 publication until #1706 is merged and its runtime compatibility is deployed. This PR remains Draft until that gate is confirmed.

Closes #1707

## Summary

- correct the Enrollment DoP classifier from director_programs to the canonical dean_parents position

- document the canonical DoP/DoA IDs in the dbt staffing contract

- update existing dbt, Redshift, contract, and Convex fixtures to use Dean of Parents

The report layout changes are already delivered by #1732 and are intentionally excluded from this PR.

## Data migration required

Deploy this with the bootstrap migration below, then rebuild stg_staffing_position+ and republish the Enrollment snapshot:

BEGIN;
UPDATE sandbox_education.temp_positions
SET name = 'Dean of Parents'
WHERE id = 'dean_parents';
INSERT INTO sandbox_education.temp_positions (id, name)
SELECT 'dean_parents', 'Dean of Parents'
WHERE EXISTS (
SELECT 1
FROM sandbox_education.temp_positions
WHERE id = 'director_programs'
)
AND NOT EXISTS (
SELECT 1
FROM sandbox_education.temp_positions
WHERE id = 'dean_parents'
);
UPDATE sandbox_education.temp_campus_position_users
SET position_id = 'dean_parents'
WHERE position_id = 'director_programs';
DELETE FROM sandbox_education.temp_positions
WHERE id = 'director_programs';
COMMIT;

## Validation

- existing @bran/contracts, sync Redshift, and Chat Convex SIS Enrollment suites

- dbt parse and focused contract compilation

- pre-commit sync and Chat typechecks

- Biome and git diff --check

## Summary

- place School before DoP and DoA in the Enrollment report and CSV export

- keep School, DoP, and DoA widths stable when toggling Show all columns

- compact metric columns and show full truncated staffing names in a themed hover tooltip

- align the Total row and export ordering with the visible matrix

Follow-up to #1720.

## Validation

- focused Enrollment report suite: 38 tests passed

- Chat TypeScript check

- test-architecture and architecture-boundary checks

- targeted Biome check and git diff --check

## Summary

Follow-up to #1725 (AERIE-2765) with two small fixes deferred from that PR's final Mercy pass.

- Truncated management lists now say so. The admin page's "Proposed changes" list stops at 100 pending proposals and "Archived documents" at 200. Until now the page didn't say when more existed. It now shows "Showing the oldest 100 pending proposals. Review these to see the rest." or "Showing the 200 most recently archived documents. Older archived documents aren't listed here."

- docs/capabilities.md describes today's Global document actions. It listed operations.globalDocuments.manage as covering "registration, source replacement, Retry, Re-index, and removal". It now lists archive, supersede, metadata edits, reviewing agent proposals and restore. It also notes that an API key can only propose changes for documents it registered.

## Why it's needed

Mercy flagged that a capped list with no indication turns a successful read into an incomplete workflow. Pending proposals beyond the first 100 appear only after earlier ones are reviewed, and archived documents beyond the newest 200 can't be restored from the page at all.

## Changes

- globalDocumentProposals.listPendingForManagement takes an optional limit (at most 100). Both it and globalDocuments.listArchivedForManagement return one row beyond the limit, so the page can tell when more exist.

- The admin page passes those limits, shows at most that many rows, and shows the note when there are more.

- The return shape is still a plain list. #1725 hasn't reached prod yet, but if a release ships it before this PR, admin tabs already open keep working; at most they show one extra row.

## Breaking changes

None.

## Test plan

- [x] New Convex test: both queries return limit + 1 rows when more exist, and no extra row when they don't.

- [x] New page test: with exactly 100 proposals there's no note. With 101 proposals and 201 archived documents, the page shows 100 proposal cards and 200 archived rows, each list with its note.

- [x] vitest run convex/publicApi/v2/globalDocumentProposalsHttp.test.ts app/(main)/admin/global-documents convex/globalDocument: 28 passed.

- [x] pnpm typecheck and Biome are clean.

## Summary

This PR is a focused semantic-metadata follow-up for [AERIE-2765](https://linear.app/builder-team/issue/AERIE-2765) and [AERIE-2775 — Add Fire Alarm Monitoring to site Utilities](https://linear.app/builder-team/issue/AERIE-2775/add-fire-alarm-monitoring-to-site-utilities).

It adds the two API fields missing from the public DSS dictionary: Global document supersededBy and Utilities fire_alarm_monitoring. The underlying API and MCP behavior is unchanged.

Production effect: compatibility hardening. This corrects agent discoverability metadata without changing stored data, permissions, or write paths.

---

## Why

The live API exposes both fields, but the public DSS dictionary did not explicitly name them. Agents reading the dictionary could therefore miss behavior already supported by the API.

---

## Business Value

- Makes Global-document replacement lineage discoverable through DSS.

- Makes Fire Alarm Monitoring discoverable through DSS.

- Aligns semantic metadata with the live public API.

---

## How does it work

1. The Global-document dictionary object gains a nullable supersededBy field pointing to its GlobalDocument schema property.

2. The property-utilities dictionary object gains a fire_alarm_monitoring field pointing to its PropertyUtilities schema property.

3. Each entry documents the relevant null interpretation for agents.

---

## Scope

### Included in this phase

- Global document supersession semantic metadata.

- Fire Alarm Monitoring semantic metadata.

- Exact final diff paths:

chat/lib/public-api/v2/domains/documents.ts
chat/lib/public-api/v2/domains/property.ts

### Deliberately excluded for later phases

- API, MCP, UI, storage, permissions, and normalization changes — the runtime behavior already exists.

- New regression tests — excluded per explicit implementation direction.

---

## Test plan

### Automated validation

- Biome on the Fire Alarm Monitoring dictionary file — passed.

- git diff --check — passed.

- Hosted CI validates the combined exact PR head.

### Time for Implementation

An engineer working without AI assistance would likely need less than half a day to identify and correct both stale semantic entries.

## Screenshots

<img width="1407" height="919" alt="image" src="https://github.com/user-attachments/assets/61c39f3a-9d5c-45e6-9e67-00368d75aaac" />

<img width="1179" height="801" alt="image" src="https://github.com/user-attachments/assets/7c4cd585-a339-41d3-b7aa-74f94477c9c6" />

## Summary

PR 2 of AERIE-2765, stacked on #1722. It lets agents propose Global document changes over the v2 API, adds a review panel for managers, and lets managers restore archived Global documents.

- API proposals. The API key that registered a Global document can propose archiving it (with an optional replacement) or fixing its title, notes or topic. Nothing changes until someone with operations.globalDocuments.manage approves the proposal.

- Review panel. /admin/global-documents has a "Proposed changes" section showing, for each proposal, the current and proposed value of each field, the reason, and which key and owner proposed it. Approve applies the change. Reject requires a note.

- Restore. A "Show archived documents" toggle lists archived Global documents. Restore needs a reason, and is refused while the archive's knowledge cleanup is still running. After restore, the document is re-indexed.

- Edits need a reason. The admin edit form now asks for a reason. An edit that only changes metadata goes through patchMetadata, so it gets the same audit entry as the API path.

## Why it's needed

#1722 gave agents tools to propose changes, but there was no way for a proposal to be created over the API or reviewed by a person, and archiving couldn't be undone.

## Changes

- New globalDocumentProposals table (gdp_ public IDs). It stores a baseline snapshot, the status (pending, approved, rejected, stale or failed), the reviewer and note, and per-key idempotency.

- convex/globalDocumentProposals.ts: create, listPendingForManagement, approve and reject.

- Approve checks the baseline first. If the document changed since the proposal, the proposal is marked stale and nothing is written.

- The change is applied with channel: "api", the approver as actor, and proposalRef/proposedBy in the audit entry.

- New v2 endpoints, which need operations.portfolio.read and operations.globalDocuments.manage:

- POST /v2/portfolio/documents/global/{documentRef}/archive-proposals

- POST /v2/portfolio/documents/global/{documentRef}/metadata-proposals

- GET /v2/portfolio/documents/global/proposals/{proposalRef}, which only returns proposals made by the calling key.

- The POSTs require an idempotency key and return 202 with a Location header.

- Errors: 403 global_document_not_registered_by_key for a key that didn't register the document (this includes documents registered before #1722), and 422 global_document_proposal_no_change when the proposal changes nothing.

- Restore:

- restoreArchivedDocumentWithKnowledge and restoreGlobalDocument write the audit entry global_document.restored.

- New globalDocuments.restore mutation and listArchivedForManagement query.

- The full cleanup dedupe key is now scoped to a generation (cleanup:{doc}:all:{generation}), so archiving a restored document queues a fresh cleanup job.

- globalDocuments.update, updateVerifiedDrive and globalDocumentDrive.replace accept an optional reason. It is optional so already-deployed bundles keep working.

### Changes from the plan

- approve records failed and returns instead of rethrowing. In Convex, rethrowing would roll back the failed status along with everything else.

- The Mercy finding deferred from PR 1 (a clean error for an unknown proposal tool) was already fixed in #1722 (455370ee0).

- No skill version bump was needed: the hash covers the skill directory, not the contracts.

- Restoring an external-link document creates a not_searchable job record rather than a queued ingest, the same as when it was registered.

## Breaking changes

None. The new arguments are optional and the new endpoints are additive.

## Test plan

- [x] New convex/publicApi/v2/globalDocumentProposalsHttp.test.ts (6 tests):

- Only the registering key can propose. Other keys and documents with no recorded key get 403; unknown documents get 404.

- Validation: a blank reason, a document superseding itself, no change, and clearing the topic all get 422.

- Replaying the same idempotency key returns the same proposal; the same key with a different body gets 409.

- GET returns 404 for other keys.

- Approve uses channel api, the approver as actor, and proposalRef in the audit. Users without the capability are denied.

- A changed baseline gives stale with no write.

- Reject requires a note.

- Approve records failed when the replacement was archived in the meantime.

- Restore is refused while cleanup is queued. After cleanup it un-archives, the document reappears in the lists, and an ingest job is queued at the next generation. External documents get not_searchable.

- Archiving again creates a second, distinct cleanup job.

- [x] Admin page tests: an edit requires a reason and uses patchMetadata; the proposals panel approves, and rejects only with a note; archived documents restore only with a reason.

- [x] vitest run convex/documentKnowledge convex/publicApi lib/public-api convex/globalDocument convex/rhodesMcpMutationParity app/(main)/admin/global-documents: 992 passed. One failure, skill-package.node.test.ts, also fails on a clean checkout on Windows because of CRLF line endings.

- [x] pnpm typecheck and Biome are clean.

- [x] Pushed to a dev deployment. The schema and indexes deployed, and the new routes return 401 without a key.

### Dev deployment testing

These checks ran against a personal dev deployment, using real HTTP calls with test API keys and real job processing. They were run as a test manager user and a viewer user (who lacks the manage capability), on documents labelled AERIE-2765 PR2 test. Afterwards the keys were revoked and the test documents archived.

API proposals: 16 of 16 passed

- Another key gets 403 global_document_not_registered_by_key. A document created in the UI (no registering key) also gets 403.

- Unknown and archived documents get 404 document_not_found.

- A blank reason gets 422 global_document_proposal_invalid, and superseding itself gets 422 ("A document cannot supersede itself.").

- A metadata proposal identical to the current values gets 422 global_document_proposal_no_change. One with only a reason gets 422 request_body_invalid.

- An archive proposal returns 202 pending with Location: /v2/portfolio/documents/global/proposals/gdp_….

- Replaying the same idempotency key returns the same proposal; the same key with a different body gets 409 idempotency_conflict.

- The proposing key can GET the proposal; another key gets 404.

- The document is unchanged before review.

Review: 18 of 18 passed

- All four test proposals are listed for the manager with the key name and owner. The viewer is denied listing and approving.

- Approving a metadata proposal sets the new title and clears the notes.

- A hand edit before approval returns stale ("The document changed after this was proposed, so nothing was applied.") and writes nothing.

- Rejecting without a note is refused. With a note, the key sees rejected and the note, and the document is unchanged.

- Approving an archive proposal archives the document with its replacement. Approving twice is refused.

- The audit entries have channel: "api", the approver as actor, plus proposalRef, apiKeyId and proposedBy. Stale and rejected proposals write no audit entry.

Restore: 21 of 21 passed

- An archive made under PR 1, whose cleanup job used the old cleanup:{doc}:all key, restores fine. That proves old-format keys still work.

- The viewer is denied restore, and a blank reason is refused.

- An external-link document comes back with a not_searchable job record and reappears in the admin list. The global_document.restored audit entry keeps the previous archive reason.

- Restoring right after archiving is refused with "Cleanup from archiving is still running. Try again in a few minutes."

- After cleanup succeeds (about 50 seconds on dev), restore revives the knowledge state at the next generation.

- Archiving the restored document again queues a second, separate cleanup job (cleanup:{doc}:all:2 next to the finished :all:1), which also completes.

- A Drive document (an existing dev Global document) was archived, refused while cleanup ran, then restored once cleanup finished. Restore queued a fresh ingest at generation 2, and the worker claimed it twice. Both attempts failed with temporary_source_failure, the same error this document's original ingest has had on dev since registration: dev can't read these Drive files. Dev has no indexed Drive Global documents, so the search round trip after a restore can't be shown there.

Admin page in a browser

- [x] The "Proposed changes" panel shows the four seeded proposals with Now/Proposed values, the reason, and "key · owner".

- [x] Approving the metadata proposal applies it, and approving the archive proposal archives the 2025 plan.

- [x] Editing "Visitor Sign-in" by hand and then approving its rename shows a stale message.

- [x] Rejecting the Visitor Sign-in archive proposal requires a note.

- [x] "Show archived documents" lists the Retired Checklist with its reason, date and archiver, and Restore requires a reason.

- [x] Edit requires a reason. A title-only edit writes global_document.metadata_patched, and a type change writes global_document.updated with the reason.

After the browser run, the stored rows matched every step. The two approvals applied with audit entries showing channel api, the reviewer as actor and the proposal ID. The stale proposal changed nothing, the rejection kept its note, Restore wrote global_document.restored, and the two edits wrote metadata_patched and updated with their reasons. The test key was then revoked and the seeded documents archived.

Part of [AERIE-2765](https://linear.app/builder-team/issue/AERIE-2765). This is PR 1 of 2.

## Testing contract

### What this PR delivers

Global documents can now be archived, marked as replaced by a newer document, or have their title, notes, or topic corrected. Agents can propose any of these, but nothing happens until a person approves it. Every change records who made it and why. Today the only cleanup is the admin page's Remove button, which hard-deletes the row with no reason recorded. An agent that registers a document with the wrong title can only re-register it, which leaves a duplicate.

- Archive, not delete: an archived document keeps its row, gets archivedAt, archivedByUserId and archiveReason, and is removed from Global search. It drops out of the admin list, the v2 Global list, MCP listGlobalDocuments, re-index, and the capacity automation doctrine lookup.

- Supersede: supersededByPublicId points at the live Global document that replaces this one. The v2 list returns it as supersededBy (always null on upload and registration responses). Global search ranks superseded documents after current ones. Capacity doctrine lookup follows the chain (up to 5 hops) to the current document.

- Metadata patch: title, notes and topic only. The search snapshot is not rebuilt, the title can't be cleared, and generic document types still require a topic. A patch that changes nothing returns no_change and writes no audit entry.

- MCP: three new proposal tools: archiveGlobalDocument (optional supersededBy), supersedeGlobalDocument (supersededBy: null clears the mark) and updateGlobalDocumentMetadata. Each takes the documentRef and a required reason (1 to 1000 characters). Each creates a pending mutation that a person approves in the browser, and applies only after that approval. Agent instructions say to propose these instead of re-registering a document.

- Admin page: the Remove button becomes Archive. It opens a panel that requires a reason and has an optional "Replaced by" picker. Rows show "Replaced by {title}". The page uses new archive, supersede and patchMetadata mutations. The old remove mutation stays only for admin pages that were already deployed; it still hard-deletes and writes global_document.removed.

- Registering key: v2 registration and Global upload completion now record registeredByApiKeyId. PR 2 uses it so a key can only propose changes to documents it registered.

- All three paths go through the shared helpers in convex/globalDocumentChanges.ts, so validation and audit are the same everywhere.

### Who uses it and where

Agents and people managing the portfolio-wide Global document library, from the Global documents admin page and the Rhodes MCP worker. This is the cleanup POSH (Austin Ray's team) asked for, in their words: "Agents propose, a person confirms"; "Archive, not hard delete"; "Logged with a reason"; a "supersedes field"; "Patch is metadata only. Title, notes, topic".

### Conditions needed

- Admin page / MCP approval: the person acting needs operations.globalDocuments.manage. Creating an MCP proposal also requires it, so an agent acting for a user without it gets "Permission denied: operations.globalDocuments.manage required".

- MCP: a Rhodes worker running this branch.

- The replacement in supersededBy must be a current (not archived) Global document and not the document itself.

### Expected behavior and examples

- Archive with a reason: the document disappears from the lists and search. Its knowledge state gets removedAt and a cleanup job is queued. The audit entry global_document.archived stores the full document as before, and reason, archivedAt, supersededBy and (for MCP) channel: "mcp" as after.

- Archive without a reason (blank or whitespace): rejected. Archive twice: rejected.

- Re-index an archived document: v2 returns 404 document_not_found, and MCP returns "Global document not found."

- Supersede: returns updated, then no_change on an identical repeat. Pointing at itself fails with "A document cannot supersede itself."; pointing at an archived document fails with "The replacement must be a current Global document."; null clears the mark. Audit: global_document.superseded.

- Metadata patch: returns updated with the new values, and the audit entry global_document.metadata_patched records before and after for title, notes and topic, plus the reason. No new knowledge job is created.

- MCP: the approved result is {documentRef, outcome, supersededBy} for archive and supersede, or {documentRef, outcome, title, notes, topic} for metadata. Before approval, the tool returns awaiting_browser_approval with a review URL; a rejection returns rejected with the reason.

### Limits and unanswered questions

- PR 2 (not in this PR): the v2 API proposal endpoints (.../archive-proposals, .../metadata-proposals, GET .../proposals/{id}), limited to the key that registered the document. It also adds the admin page "Proposed changes" panel where a person approves or rejects, with a note required on rejection. Until it lands, API keys can't archive or patch.

- Documents registered before this PR have no registeredByApiKeyId. Following the spec ("Only the registering lane or an admin can archive"), PR 2 will leave them to a person on the admin page, not to API keys.

- The old Remove button is now Archive: the new admin page can't hard-delete Global documents. The remove mutation stays only so already-deployed admin pages keep working until they reload. Archived rows can't be restored from the UI yet.

- Admin page Edit doesn't ask for a reason: it still uses the existing update mutation and writes global_document.updated, as the plan specified ("Edit stays the same"). The agent path (updateGlobalDocumentMetadata) does require one. Making admin edits require a reason too would be a small follow-up.

- Audit from here on: this answers POSH's "who removed it and why" for future changes. Earlier hard deletes left nothing to recover.

- Tested by hand on a personal Convex dev deployment only (see Manual testing below). Not exercised on staging or prod.

## Verification

- chat: pnpm typecheck (app and Convex). New tests:

- documentsHttp.test.ts: archive, supersede and patch through the admin mutations, then checks the v2 list, re-index 404, knowledge removedAt, and the audit entries. Registration and upload record registeredByApiKeyId.

- rhodesMcpMutationParity.test.ts: proposals are denied without Global Documents authority and apply only after approval, with channel: "mcp" audits.

- globalIndex.test.ts: archived documents are dropped from search and superseded ones ranked last.

- capacityAutomation.test.ts: doctrine lookup follows supersededBy and ignores archived duplicates.

- The admin page test archives with a required reason and an optional replacement.

- Suites: 1522/1523 across convex/publicApi, convex/documentKnowledge, convex/capacityAutomation*, convex/rhodes*, lib/public-api and the admin page. The one failure, skill-package.node.test.ts, is a local hash mismatch from CRLF checkouts on Windows and unrelated to this change.

- chat/rhodes-worker: pnpm typecheck and pnpm test 271/271.

- biome check on all changed files.

- Suite counts above are from 4ce6dc98b, before the Mercy fixes. The fixes added a cycle check, and that broke the documentsHttp.test.ts archive test, which had set up a loop: two documents each marked as replaced by the other. d4a104faf reorders the test so it clears the first mark before archiving, and it now also checks that the cycle is rejected. documentsHttp.test.ts passes 45/45 on three consecutive runs.

### Manual testing (personal Convex dev deployment)

Run against marcus-day (zealous-jaguar-137), never staging or prod, using throwaway @example.test users: a manager on a test role (admin plus operations.globalDocuments.manage) and a plain user without it. Every check passed on the original commit 4ce6dc98b, and the scripted checks passed again on d80b602e1 (after the Mercy fixes).

Admin actions and v2 API (30/30 scripted checks)

- Registration: v2 registration returns 201 with supersededBy: null and records registeredByApiKeyId. A document created on the admin page has none. The v2 list includes supersededBy on every document.

- Supersede: rejects a document replacing itself, a replacement that's already archived, and the plain user. Returns updated and then no_change on a repeat. The v2 list shows the replacement.

- Metadata patch: a blank title is rejected, and so is clearing the topic on a policy document. Returns updated and then no_change on a repeat, and starts no new knowledge job. Archived documents are rejected.

- Archive: a blank reason, a second archive, and the plain user are rejected. Afterwards the document is gone from the v2 list and the admin list, and v2 re-index returns 404 document_not_found. The row keeps archivedAt, archiveReason, archivedByUserId and supersededByPublicId, and the knowledge state has removedAt.

- Audit: exactly one archived, superseded and metadata_patched entry each, with reason, replacement and the prior record. no_change calls write nothing.

MCP approval flow (11/11 scripted checks, worker-secret approval path)

- The plain user can't create a proposal ("Permission denied: operations.globalDocuments.manage required").

- A manager's archiveGlobalDocument proposal changes nothing until approved. After approval it returns {outcome: "archived", supersededBy}, and the audit entry has channel: "mcp" and the reason.

- A rejected updateGlobalDocumentMetadata proposal leaves the document unchanged and writes no audit entry. An approved one applies.

Admin page in a browser (local Next.js against the same dev deployment)

- Archive panel: the button doesn't work without a reason. Archiving with a reason and a "Replaced by" choice removes the row. The stored row and the global_document.archived audit entry match what was entered.

- Edit: changing the title and clearing the notes works.

Not covered by hand

- A real chat agent choosing the new tools and showing the approval cards. This needs the personal dev MCP worker redeployed with this branch.

- Global search excluding archived documents and ranking replaced ones last. Dev never gets a Global document to available; the automated tests cover both.

## Summary

This PR is the single approved Fire Alarm Monitoring feature slice tracked by [AERIE-2775 — Add Fire Alarm Monitoring to site Utilities](https://linear.app/builder-team/issue/AERIE-2775/add-fire-alarm-monitoring-to-site-utilities) and [AERIE-2774 — Add Fire Alarm Monitoring service-contract document type](https://linear.app/builder-team/issue/AERIE-2774/add-fire-alarm-monitoring-service-contract-document-type).

It adds Fire Alarm Monitoring to the existing Utilities, API v2, DSS, and service-contract document conventions.

Production effect: activation. The new section becomes available through existing live UI and API/DSS paths; no migration, backfill, external writeback, or new endpoint is started by merge.

---

## Why

Sites need the same operational ownership, account, inspection, and contract information for fire alarm monitoring that they already maintain for other utilities. Following the shared Utilities and document-taxonomy contracts keeps the feature consistent and ensures legacy rows remain readable without a data backfill.

---

## Business Value

- Gives operators one consistent place to maintain Fire Alarm Monitoring provider, account, DRI, cadence, and notes.

- Lets authorized API and DSS callers read and update the same fields.

- Returns a complete null-filled section for legacy sites, so agents can reliably identify missing information.

- Reuses the established Documents upload flow for Fire Alarm Monitoring service contracts.

---

## How does it work

1. The shared Utilities contract registers fire_alarm_monitoring with the standard eight utility fields.

2. Normalization materializes a complete null-filled section when an existing stored row lacks it; the Convex stored section remains optional for backward compatibility.

3. The Utilities card, API v2 projection and patch schemas, and DSS update tool consume or expose the shared section using their existing conventions.

4. Sensitive login, account-number, and billing fields continue through the existing redaction and audit behavior.

5. The shared document taxonomy adds serviceContractvFireAlarmMonitoring, filed under 05_Vendors & Contracts and classified as operational/non-capacity evidence.

---

## Scope

### Included in this phase

- Fire Alarm Monitoring Utilities UI, storage compatibility, API v2, and DSS exposure.

- Fire Alarm Monitoring service-contract document taxonomy and capacity classification.

- Exact final diff paths:

chat/components/dashboards/portfolio/cards/__tests__/utilities-card.test.tsx
chat/convex/publicApi/v2/domains/property.ts
chat/convex/publicApi/v2/propertyHttp.test.ts
chat/convex/rhodes/schema.ts
chat/rhodes-worker/mcp-server/tools/sites.test.ts
chat/rhodes-worker/mcp-server/tools/sites.ts
packages/contracts/src/capacity-trigger.test.ts
packages/contracts/src/capacity-trigger.ts
packages/contracts/src/document-types.test.ts
packages/contracts/src/document-types.ts
packages/contracts/src/public-api-v2-property.test.ts
packages/contracts/src/public-api-v2-property.ts
packages/contracts/src/utilities.test.ts
packages/contracts/src/utilities.ts

### Deliberately excluded for later phases

- Data migration or backfill — legacy rows are supported by optional stored validation plus null-filled normalization.

- A new upload surface or endpoint — the existing Documents and API upload patterns consume the shared taxonomy.

- Portfolio-wide completeness aggregation — this slice only exposes the new fields through existing API/DSS conventions.

- External REBL3 or Rhodes writeback — no such writeback was triggered.

---

## Test plan

### Automated validation

- Utilities, API contract, document taxonomy, and capacity trigger tests — 38/38 passed (pnpm --dir packages/contracts exec vitest run src/utilities.test.ts src/public-api-v2-property.test.ts src/document-types.test.ts src/capacity-trigger.test.ts --maxWorkers=1)

- API v2 property tests — 23/23 passed (pnpm --dir chat exec vitest run --project edge convex/publicApi/v2/propertyHttp.test.ts --maxWorkers=1)

- Utilities card browser tests — 8/8 passed (pnpm --dir chat exec vitest run --project browser components/dashboards/portfolio/cards/__tests__/utilities-card.test.tsx --maxWorkers=1)

- Document API/DSS metadata tests — 11/11 passed (pnpm --dir chat exec vitest run --project node lib/public-api/v2/domains/documents.node.test.ts --maxWorkers=1)

- Rhodes worker suite — 268/268 passed (pnpm --dir chat/rhodes-worker test)

- contracts typecheck — passed (pnpm --dir packages/contracts typecheck)

- chat typecheck — passed through the repository pre-commit gate

- test architecture — passed (pnpm lint:test-architecture)

- Biome on all changed files — passed

- git diff --check — passed

- exact-head diff scope — only the 14 authorized paths listed above

One deliberately parallel local validation run caused the longest API test to hit its existing 5-second harness timeout; the exact file was rerun alone immediately and passed 23/23. Hosted CI is the final full-suite gate.

### Time for Implementation

An engineer working without AI assistance would likely need 3–4 working days to trace the shared conventions, implement both surfaces, add backward-compatibility coverage, validate the DSS boundary, and prepare the PR.

## Summary

- ingest assignment-grain Enrollment staffing with the existing atomic publication

- resolve effective DoP/DoA names deterministically for Summary and By Levels

- add matching leading UI/CSV columns and source-neutral Enrollment copy

## Validation

- pnpm lint

- pnpm typecheck

- 42 contracts tests

- 99 sync/Redshift/gateway tests

- 149 Chat/Convex/UI tests

Closes #1720

## Summary

- add SIS-owned staging contracts for staffing users, positions, and campus assignments

- resolve campus, position, and SIS-user references without dropping assignments

- publish assignment-grain Enrollment staffing with optional program identity

- add deterministic unit coverage plus count reconciliation and warn-level resolution checks

## Validation

- REDSHIFT_HOST=unused REDSHIFT_PASSWORD=unused poetry run dbt parse --profiles-dir .

- REDSHIFT_HOST=unused REDSHIFT_PASSWORD=unused poetry run dbt ls --profiles-dir . --select stg_staffing_user+ --output name

- git diff --check

Closes #1719

Fixes [AERIE-2767](https://linear.app/builder-team/issue/AERIE-2767/let-agents-re-index-global-documents-through-the-api).

## Testing contract

### What this PR delivers

Agents can refresh the search snapshot of a Global document after its source file changes. Today only a human in the Global documents admin page can click Reindex, so an agent that knows a policy file was updated has no way to stop Global search returning stale content.

- v2 API: POST /v2/portfolio/documents/global/{documentRef}/reindex queues a fresh snapshot and returns 202 with the document and its current knowledgeStatus.

- v2 list: GET /v2/portfolio/documents/global now includes knowledgeStatus on every document, so callers can poll until the new snapshot is available.

- v2 upload and registration: the 201 responses from uploadGlobalDocument and registerGlobalDocument (including idempotent replays) also include knowledgeStatus, so an agent sees processing right away for a new Drive document, or not_searchable for an external URL reference, without listing again.

- MCP: a new reindexGlobalDocument tool takes the id from listGlobalDocuments and returns the same outcome. No approval step: re-indexing never changes the file or its metadata.

- The admin page's Reindex button, the MCP tool, and the API all go through one shared helper (requestGlobalDocumentReindex), so the cooldown and audit rules are identical everywhere.

### Who uses it and where

Agents (and integrations) working with the portfolio-wide Global document library, through API keys or the Rhodes MCP worker. Requested by Austin Ray's team (POSH), who ranked it above archive/patch (AERIE-2765): "Cleanup can be done by hand. Stale snapshots cannot."

### Conditions needed

- A managed Drive Global document (not an external URL reference) with document knowledge state.

- API: a key scoped to operations.portfolio.read and operations.globalDocuments.manage, owned by a user who still has both.

- MCP: a signed-in user with operations.globalDocuments.manage, and a Rhodes worker running this branch.

- Document knowledge processing enabled, so a queued job actually runs and the status reaches available.

### Expected behavior and examples

- Accepted: reindex a document whose last snapshot failed (e.g. invalid_source) returns 202, outcome: "queued", and knowledgeStatus.state of processing (or refreshing if an older snapshot stays searchable meanwhile). A new indexing generation is queued.

- Already running: a second request while the job is queued or processing returns 409, reason: "in_progress", retryable: false. Callers should poll instead.

- Cooldown: within 5 minutes of a successful manual re-index returns 409, reason: "cooldown", retryable: true, a Retry-After header in seconds, and the exact retry time in detail.

- External URL reference: returns 422, code: "global_document_not_indexable".

- No knowledge state yet / blocked by an unresolved earlier attempt: 409 with reason: "not_ready" / "blocked".

- Unknown or Site documentRef: 404 document_not_found. Key without Global document management: 403.

- Audit: an accepted request writes the existing global_document.reindex_requested entry. The actor is the key's owner (the audit log only records users), and the entry also records channel: "api", the apiKeyId, and the requestId, which matches the apiRequestLog row for that call. MCP requests record channel: "mcp"; UI entries are unchanged.

- MCP: same outcomes as accepted / outcome / message / retryAfter (ISO timestamp for cooldowns) / knowledgeStatus; unknown IDs return "Global document not found."

### Limits and unanswered questions

- Rejections roll back cleanly and write no audit entry; they're visible in the API request log.

- The ticket asked whether to restrict re-indexing to the registering key if AERIE-2765 landed first. It hasn't, so access is the existing Global document management scope.

- One small UI change: a Global document with no knowledge state now shows the "not accepted" toast instead of throwing.

- Not exercised end to end on a deployment. Local dev can't finish the loop to available because the dev worker has no Global Documents Drive root and the dev Drive account can't write. Proposed prod check after deploy, together with #1713: re-index POSH's camera coverage register through the new endpoint, watch knowledgeStatus reach available, then search for text from it.

## Verification

- chat: pnpm typecheck; convex/publicApi/v2/documentsHttp.test.ts 44/44, including new HTTP and MCP-path re-index tests and knowledgeStatus assertions on upload, registration, and replay responses (the upload test's fake Drive callback now inserts through insertDocumentWithKnowledge, like the real path); 953/954 across convex/publicApi, convex/documentKnowledge, lib/public-api, and the MCP parity test, plus the Global documents admin page. The one failure (skill-package.node.test.ts) is a local hash mismatch from CRLF checkouts on Windows, unrelated to this change.

- chat/rhodes-worker: pnpm typecheck, pnpm test 270/270 including a new tool test.

- biome check on all changed files.

## Summary

- ingest and preserve weekly-pace expected-arrival diagnostics while retaining V3 compatibility

- accept V4 publications with fail-closed, method-specific provenance validation

- show selected and diagnostic candidates in Next Year detail without double-counting

- preserve the public Forecast V2 response shape

## Validation

- pnpm --dir packages/contracts exec vitest run src/admissions-forecast-v2.test.ts --maxWorkers=1

- pnpm --dir sync exec vitest run src/redshift/admissions-forecast.test.ts src/analytics/admissions-forecast-refresh.test.ts --maxWorkers=1

- pnpm --dir chat exec vitest run convex/admissions/forecastV2.test.ts --maxWorkers=1

- pnpm --dir chat exec vitest run components/dashboards/admissions/forecast/v2/__tests__/forecast-v2-report.test.tsx --maxWorkers=1

- pnpm --dir chat exec vitest run convex/publicApi/v2/admissions.test.ts --maxWorkers=1

- pnpm typecheck

- pnpm lint (passes with two pre-existing warnings in chat/skill/forge-api/scripts/sindri.mjs)

Closes #1706

## Summary

This PR is the lifecycle-and-deletion slice of the [Human Task Assignment from Aerie](https://linear.app/builder-team/project/human-task-assignment-from-aerie-b3582376ae6e) project.

It enforces canonical Start, Delay, Block, Continue, Reject, and Delete actions across the gated Task Board UI, public API, Work Plan mutations, and agent tools. This phase is tracked by [AERIE-2738 — Enforce Task lifecycle actions and safe deletion](https://linear.app/builder-team/issue/AERIE-2738/enforce-task-lifecycle-actions-and-safe-deletion).

Production effect: compatibility hardening. The Task Board gate remains off by default. Existing Work Plan and published API status behavior remain available while the gate is off; the new lifecycle controls, agent tools, and immediate Task rejection/due-date notifications are unavailable or no-op until the same server gate opens.

| Surface or consumer | Gate off after deployment | Gate on later |

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

| Existing Work Plan | Existing Task editing and status behavior remain unchanged; no new lifecycle control is shown. | The editor uses the same canonical Start, Delay, Block, Continue, Reject, and Delete rules as every other surface. |

| My Tasks and Task detail | The gated Task Board remains unavailable. | Authorized participants see only the lifecycle actions valid for their role, assignment, and current status. |

| Public API | Existing transition meanings and compatibility approval writes remain intact. | New Tasks must begin as New; status transitions route through canonical lifecycle actions with revision checks and reasons where required. |

| Agent and MCP tools | New lifecycle tools are not advertised or callable through the gated tool catalog. | Agents receive explicit lifecycle tools instead of using generic status edits as a bypass. |

| Notifications | Rejection and due-date-change events are not enqueued. | Direct Task participants receive retry-safe immediate events; the acting user is excluded. |

| Delete | Existing deletion stays available with its current Note guard. | Authorized deletion additionally follows the same lifecycle authority and optimistic-concurrency rules, while the existing recoverable deletion audit and bounded child cleanup remain authoritative. |

---

## Why

The Task Board cannot become authoritative while existing writers can bypass its transition, assignment, explanation, concurrency, and closed-state rules. This slice establishes one lifecycle seam for humans and agents, preserves existing behavior before launch, and makes later completion and approval work depend on an audited, bounded foundation rather than another parallel Task API.

---

## Business Value

- Gives assignees clear actions for starting, delaying, blocking, and continuing shared work without changing status merely by viewing it.

- Keeps creators, requesters, Task managers, API clients, Work Plan users, and agents on one authorization and lifecycle model.

- Preserves explanations, actor attribution, timestamps, rejection closure, and recoverable deletion evidence for operational accountability.

- Prevents unassigned work and closed Tasks from moving through unsupported lifecycle paths after the Task Board launches.

- Keeps the deployment safe before launch: the new behavior remains behind the existing default-off Task Board gate.

---

## How does it work

1. chat/convex/taskBoard/lifecycle.ts owns the canonical action vocabulary, allowed transitions, assignment checks, role/participant authority, revision checks, lifecycle timestamps, explanations, audit entries, and site-freshness updates.

2. Direct Task Board mutations, gated public API transitions, Work Plan mutation dispatch, and Rhodes MCP tools all call that same lifecycle seam. Generic gated metadata writes cannot set status, approval fields, completion history, or lifecycle-owned timestamps.

3. Start records startedAt; every transition advances statusChangedAt; Delay and Block require reasons; Continue returns delayed or blocked work to In progress; Reject records closedAt and remains distinct from Delete.

4. External assignment counts as assigned. A creator, requester, or global Task manager may act on that assignee's behalf, while audit history records the authenticated actor.

5. Delete preserves the existing anchored-Note guard, concurrency check, complete Task audit snapshot, and bounded child-record cleanup rather than treating Reject as deletion.

6. Rejection and due-date-change notifications store durable rendering facts and are enqueued only when the Task Board gate is enabled. The UI, public schemas, and agent tool catalog use the same gate, so merging this PR does not activate the workflow.

---

## Scope

### Included in this phase

- Canonical Start, Delay, Block, Continue, Reject, and Delete actions with authority, assignment, revision, reason, timestamp, and audit enforcement.

- Gated Task detail and Work Plan lifecycle controls, plus public API and agent/MCP parity.

- Closed-state and generic-update protection, including compatibility-only approval writes for existing published endpoints.

- Default-off, retry-safe rejection and due-date-change notifications for direct Task participants.

- Existing recoverable deletion snapshots, Note protections, and bounded cleanup integrated with the canonical lifecycle authority.

- Exact final diff paths:

chat/components/dashboards/portfolio/__tests__/portfolio-rhodes-workbench.test.tsx
chat/components/dashboards/portfolio/portfolio-rhodes-workbench.tsx
chat/components/task-board/my-tasks-view.tsx
chat/components/task-board/task-lifecycle-actions.test.tsx
chat/components/task-board/task-lifecycle-actions.tsx
chat/convex/_generated/api.d.ts
chat/convex/agentRuns/runs.ts
chat/convex/notifications/events.ts
chat/convex/notifications/schema.ts
chat/convex/publicApi/v2/domains/workManagement.ts
chat/convex/publicApi/v2/domains/workManagementTaskBoardWrites.test.ts
chat/convex/publicApi/v2/workManagementData.ts
chat/convex/publicApi/v2/workManagementWrites.ts
chat/convex/rhodes/portfolioWorkbench.ts
chat/convex/rhodes/runtime/constants.ts
chat/convex/rhodes/runtime/mutationAuthorization.ts
chat/convex/rhodes/runtime/mutationDispatcher.ts
chat/convex/rhodes/runtime/writes/taskWrites.ts
chat/convex/rhodesMcpMutationParity.test.ts
chat/convex/rhodesPortfolioWorkbench.test.ts
chat/convex/taskBoard/lifecycle.test.ts
chat/convex/taskBoard/lifecycle.ts
chat/convex/taskBoard/notifications.test.ts
chat/convex/taskBoard/notifications.ts
chat/convex/taskBoard/queries.test.ts
chat/convex/taskBoard/queries.ts
chat/lib/public-api/v2/domains/work-management-schemas.ts
chat/lib/public-api/v2/domains/work-management-task-board.node.test.ts
chat/lib/public-api/v2/domains/work-management.ts
chat/lib/rhodes-mutation-tools.ts
chat/rhodes-worker/mcp-server/tools/portfolioParity.test.ts
chat/rhodes-worker/mcp-server/tools/tasks.ts
packages/contracts/src/agent-tool-registry.ts
packages/contracts/src/rhodes-mutation-proposal.ts

### Deliberately excluded for later phases

- Enabling the Task Board gate or changing production environment configuration.

- Completion submissions, evidence, approval review, request-changes, or remove-approval workflows — later Task Board slices own those actions.

- Sources, watchers, comments, daily digests, Team Tasks, or additional notification types.

- A general Reopen or Withdraw action, per the locked V1 product decisions.

- A second lifecycle/state field, new status values, semantic duplicate detection, or automatic overdue status mutation.

- AERIE-2739 and later Task Board work, schema, UI, API, MCP, migration, backfill, or rollout behavior.

---

## Test plan

### Automated validation

- Lifecycle, notification gate, Task query, public API write, MCP parity, and Work Plan backend suites — 186/186 passed (pnpm --dir chat exec vitest run --project edge convex/taskBoard/lifecycle.test.ts convex/taskBoard/notifications.test.ts convex/taskBoard/queries.test.ts convex/publicApi/v2/domains/workManagementTaskBoardWrites.test.ts convex/rhodesMcpMutationParity.test.ts convex/rhodesPortfolioWorkbench.test.ts --maxWorkers=1)

- Task lifecycle and Work Plan browser suites — 69/69 passed (pnpm --dir chat exec vitest run --project browser components/task-board/task-lifecycle-actions.test.tsx components/dashboards/portfolio/__tests__/portfolio-rhodes-workbench.test.tsx --maxWorkers=1)

- Gated public API contract suite — 2/2 passed (pnpm --dir chat exec vitest run --project node lib/public-api/v2/domains/work-management-task-board.node.test.ts --maxWorkers=1)

- Rhodes Worker MCP parity suite — 2/2 passed (pnpm --dir chat/rhodes-worker exec tsx --test mcp-server/tools/portfolioParity.test.ts)

- Full workspace typecheck — passed (pnpm typecheck)

- Lint, Biome, architecture boundaries, Convex paths, read bounds, test architecture, and knowledge hygiene — passed with two existing unrelated Sindri string-template warnings (pnpm lint)

- wrangler deploy --dry-run — passed; 10,243.06 KiB upload / 3,222.50 KiB gzip (pnpm --dir chat/rhodes-worker exec wrangler deploy --dry-run)

- git diff --check origin/main...HEAD — passed

- Patch equivalence — exact (git range-diff 27d6539a0..f4b5ec280 origin/main..HEAD reports the reviewed and rebased commits as =)

- Exact-head diff scope — only the 34 authorized paths listed above

### Time for Implementation

About 3 to 4 weeks for one engineer without AI assistance, including repository investigation, cross-surface lifecycle design, implementation, hermetic tests, independent review, dependency rebasing, and release validation.

## Review repairs and contract clarifications

### Review at b13dae937c8f01be4c10c07e01b8bd7abef54fbe

Review: https://github.com/AI-Builder-Team/Aerie/pull/1715#pullrequestreview-5444358736 · Repairs: [AERIE-2770](https://linear.app/builder-team/issue/AERIE-2770/bind-work-plan-task-lifecycle-reads-to-the-owning-site) and [AERIE-2771](https://linear.app/builder-team/issue/AERIE-2771/forward-authenticated-actors-through-task-update-dispatch)

- Accepted — Work Plan Task/site binding. The gated getWorkbenchLifecycleActions query accepted only a Task ID, so it could not prove that the Task belonged to the site open in the Work Plan. It now requires the already-loaded Workbench site ID and returns the same Task not found error when the Task belongs to another site. Both Task edit entry points pass that site ID.

- Accepted — authenticated actor forwarding. The established approval pipeline already injects the server-owned proposer ID into prepared updateTask arguments, and an end-to-end reproduction confirmed that path emits the due-date event. The dispatcher nevertheless accepted the authenticated actor through a separate parameter and discarded it for updateTask. It now overwrites args.actorUserId from that trusted parameter when present, so every caller of the dispatcher contract preserves attribution and notification delivery. A direct dispatcher regression failed before the repair and now verifies the event actor and recipient.

- Unchanged boundaries. My Tasks remains participant-scoped, Work Plan access remains site-detail scoped, lifecycle authority is unchanged, and the Task Board gate remains off by default. The new query is called only when that gate is enabled, so this repair does not alter gate-off traffic or writes.

- Repair validation. Task Board query suite 10/10; Work Plan browser suite 67/67; Rhodes MCP parity suite 96/96; full workspace typecheck passed; Biome, test-architecture lint, and git diff --check passed. After rebasing onto main at 88860d11f, git range-diff reports all three PR commits exactly equivalent.

- Production effect. Compatibility hardening only. No deployment, migration, activation, external traffic, or shared-data write was performed.

### Review at 497c891bcecd99e72d3a82dd746b575d25b044d7

Review: https://github.com/AI-Builder-Team/Aerie/pull/1715#pullrequestreview-5444650836 · Product authority: AERIE-2738 and docs/task-board/FEATURE.md

- Rejected — alleged missing site authorization. Portfolio/site-detail access is intentionally a global capability gate. The approved feature contract gives Portfolio users Task visibility across all sites and explicitly excludes site-specific Task permissions. getWorkbenchLifecycleActions requires that global site-detail access, receives the site ID from the open Work Plan, and rejects before deriving actions when task.siteId !== siteId. There is no narrower site-membership ACL for this query to omit, and adding one would contradict the approved access model rather than close an authorization gap.

- Rejected — alleged disabled Work Plan deletion. TaskDraftEditor intentionally passes canDelete={false} to TaskLifecycleActions because the Work Plan retains its own deletion control and confirmation flow. Later in the same editor, the existing Delete button renders when onDelete && lifecycle?.canDelete; both Work Plan edit entry points supply onDelete, which routes through onRequestTaskDelete. Passing the flag to TaskLifecycleActions would create a second delete affordance and bypass the established Work Plan confirmation path.

- Unchanged boundaries. Portfolio access remains global across sites; participant-only Task visibility does not grant site-detail access; the Task/site equality check prevents cross-site Work Plan object substitution; lifecycle authority and deletion confirmation remain unchanged.

- Validation. The exact-head hosted Build, Docker, lint/boundary, secret-scan, test, typecheck, Praxis, and Mercy workflow checks passed. No production or test change is warranted for either false premise.

- Production effect. None from this clarification. No deployment, migration, activation, external traffic, or shared-data write was performed.

### Same-head follow-up review

Review: https://github.com/AI-Builder-Team/Aerie/pull/1715#pullrequestreview-5444747462 · Product authority: AERIE-2738

- Rejected — alleged actorless due-date update. Every reachable production caller that can change a Task due date supplies a server-derived actor. Work Plan saveTask adds the authenticated user._id to patchArgs; the agent approval path persists the authenticated proposer on every newly created pending mutation, injects that identity into updateTask arguments during approval, and now also forwards it through the dispatcher’s separate actor parameter. The direct dispatcher regression verifies the resulting event actor and recipient.

- Legacy boundary. updateTask remains a shared compatibility helper, so its loose internal argument shape also supports pre-attribution legacy pending rows. The approval pipeline deliberately removes untrusted actor fields when such a row has no durable proposer rather than fabricating an identity. That compatibility state is not produced by any current writer and is not a current actorless update route.

- Caller audit. Outside tests, updateTask has only two call seams: authenticated Work Plan saveTask and mutationDispatcher. Both provide actor context. A hypothetical direct helper call that bypasses those seams is not a deployed Convex function or reachable production input.

- Production effect. No code change is warranted. Making the helper invent or trust an actor would weaken attribution; requiring one would reject intentionally supported legacy compatibility operations without improving current notification delivery.

Fixes [AERIE-2754](https://linear.app/builder-team/issue/AERIE-2754/index-csv-documents-that-arrive-labeled-as-excel-or-encoded-as-windows).

## Testing contract

### What this PR delivers

CSV global documents uploaded from Windows become searchable. Today they silently never index for two reasons:

1. Windows machines with Excel installed report .csv files as application/vnd.ms-excel (sometimes application/octet-stream). The Rhodes worker only accepted text/*, so these ended as unsupported_type.

2. Excel's default CSV export on Windows is Windows-1252. The worker decoded text as strict UTF-8, so a single curly quote, en dash, accented letter or Γé¼ made the document end as invalid_source.

The worker now treats a .csv file name with either of those declared types as text, and retries a failed strict UTF-8 decode as Windows-1252.

### Who uses it and where

Anyone (or any agent) registering global documents: the Rhodes global documents library in the UI and the v2 documents API. Reported by Austin Ray's team (POSH) after their camera coverage register CSV never became searchable.

### Conditions needed

- A Windows machine with Excel installed (its browser uploads .csv as application/vnd.ms-excel), or a CSV whose declared type is set to that explicitly.

- A CSV saved as Windows-1252 (Excel "CSV (Comma delimited)" on Windows) containing non-ASCII characters such as Café “lobby” – €5.

- Document knowledge processing enabled and a Rhodes worker running this branch.

### Expected behavior and examples

- register.csv declared text/csv, UTF-8: indexed, text unchanged (already worked).

- register.csv declared text/csv, Windows-1252 with Café “lobby” – €5: indexed, characters read correctly instead of invalid_source.

- Coverage Register.CSV declared application/vnd.ms-excel: indexed instead of unsupported_type. Name match is case-insensitive.

- register.csv declared application/octet-stream: indexed.

- register.xls declared application/vnd.ms-excel: still unsupported_type (real spreadsheets are out of scope).

- A .csv containing NUL bytes (UTF-16 or binary): still fails as invalid_source rather than indexing garbage.

### Limits and unanswered questions

- The Windows-1252 decoder is a small hand-written table rather than new TextDecoder("windows-1252"): workerd mis-decoded the 0x80ΓÇô0x9F range before cloudflare/workerd#6030, and this worker pins compatibility date 2025-03-10.

- Any non-UTF-8 text is read as Windows-1252, so other legacy encodings (Shift_JIS, etc.) index as mojibake instead of failing. Acceptable for this user base.

- UTF-16 CSVs (Excel "Unicode Text") are still not supported.

- Already-failed documents need a re-index after deploy; the camera coverage register should be re-indexed and confirmed searchable.

## Verification

- chat/rhodes-worker: pnpm test (269 pass, including two new retrieval tests), pnpm typecheck.

- biome check on both changed files.

- Real-file before/after: ran two sample camera registers (one Windows-1252, one UTF-8, containing “Main” door – north side, €450, Señor Muñoz’s office) through extractDocumentKnowledgeSource from main and from this branch, declared as both text/csv and application/vnd.ms-excel:

| File | Declared as | main | This PR |

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

| Windows-1252 CSV | text/csv | invalid_source | indexed, text intact |

| Windows-1252 CSV | application/vnd.ms-excel | unsupported_type | indexed, text intact |

| UTF-8 CSV | text/csv | indexed | indexed |

| UTF-8 CSV | application/vnd.ms-excel | unsupported_type | indexed, text intact |

- Not tested end to end through the UI upload: the dev Drive service account can't write to the sandbox folder, so uploads fail before indexing on local dev. Verify in prod by re-indexing the camera coverage register after deploy.

## Summary

This PR is the assignment slice of the [Human Task Assignment from Aerie](https://linear.app/builder-team/project/human-task-assignment-from-aerie-b3582376ae6e) project.

It adds the internal model for multiple Aerie assignees and external email assignees, assignment history, Task participants, durable assignment notifications, and the gated Task assignment UI and API. This phase is tracked by [AERIE-2737: Manage internal and external Task assignments](https://linear.app/builder-team/issue/AERIE-2737/manage-internal-and-external-task-assignments).

Production effect: compatibility hardening. Existing Work Plan assignment behavior and the existing internal-assignee response shape remain available. New Task Board assignment UI, API inputs, notifications, and agent-facing behavior remain unavailable while the server Task Board gate is off.

---

## Why

The Task Board needs one reliable assignment model before it can safely support My Tasks, external email assignees, assignment notifications, and later lifecycle actions. This slice preserves current internal assignees while adding bounded history and participant records that the later gated workflow can use without scanning Tasks or creating accounts for external people.

---

## Business Value

- Lets a Task represent zero, one, or several internal and external assignees without creating accounts for external email addresses.

- Preserves the current Work Plan flow and internal-assignee contract while preparing the shared Task Board workflow.

- Records who added or removed an assignment and when, so Task activity can explain assignment changes.

- Makes future assignment notifications retry-safe and independent of whether the Task still exists when delivery runs.

---

## How does it work

1. Assignment input is normalized and bounded to 100 unique email addresses. An email becomes an internal assignment only when it matches exactly one assignable Aerie user. Every other valid email is stored as external.

2. The assignment mutation updates the existing internal assignees shape, stores current and historical assignment records, refreshes indexed Task participants, and writes actor/time audit entries atomically.

3. Creators, requesters, and users with the global Task write capability can manage assignments through the gated Task Board entry points. Optimistic concurrency prevents a stale editor from overwriting a newer Task revision.

4. Internal assignment and removal events store immutable Task rendering facts before delivery. Notification enqueueing remains off with the Task Board gate, and delivery remains idempotent if retried or if the Task is later deleted.

5. Hard deletion immediately removes the Task from current surfaces, snapshots the Task in its deletion audit, and snapshots then removes assignment child records in bounded, resumable batches.

6. Existing compact Work Plan writes continue to use the current assignee payload. New email-assignment UI and API inputs stay protected by the default-off server gate.

---

## Scope

### Included in this phase

- Multiple current internal and external assignments, with external emails stored separately from existing internal user references.

- Assignment add/remove history, Task activity, participant reconciliation, authorization, concurrency checks, audit attribution, and bounded cardinality.

- Gated Task editor, detail, public API, and notification support.

- Durable assignment notification facts and bounded deletion snapshots for assignment child records.

- Exact final diff paths:

chat/components/dashboards/portfolio/__tests__/portfolio-rhodes-workbench.test.tsx
chat/components/dashboards/portfolio/portfolio-rhodes-workbench.tsx
chat/components/site-fields/save-confirm-dialog.tsx
chat/components/task-board/my-tasks-view.tsx
chat/components/task-board/task-detail.test.tsx
chat/components/task-board/task-detail.tsx
chat/components/task-board/task-editor.test.tsx
chat/components/task-board/task-editor.tsx
chat/convex/_generated/api.d.ts
chat/convex/notifications/events.ts
chat/convex/notifications/schema.ts
chat/convex/publicApi/v2/domains/workManagementTaskBoardWrites.test.ts
chat/convex/publicApi/v2/workManagementData.ts
chat/convex/publicApi/v2/workManagementWrites.ts
chat/convex/rhodes/runtime/writes/taskWrites.ts
chat/convex/rhodes/schema.ts
chat/convex/taskBoard/assignmentCleanup.ts
chat/convex/taskBoard/assignmentModel.ts
chat/convex/taskBoard/assignments.test.ts
chat/convex/taskBoard/assignments.ts
chat/convex/taskBoard/mutations.ts
chat/convex/taskBoard/queries.ts
chat/lib/public-api/v2/domains/work-management-schemas.ts
chat/lib/public-api/v2/domains/work-management.ts

### Deliberately excluded for later phases

- Enabling the Task Board gate or exposing new assignment controls in production.

- New Task lifecycle transitions, completion, approval, watchers, digests, or Team Tasks.

- Creating Aerie accounts for external email assignees or granting external assignees Aerie access.

- Automatically converting an external assignment if that email later receives an Aerie account.

- New DSS or agent discovery. Agents receive no new production operation while the gate is off.

- Any legacy Rhodes Task synchronization change. That synchronization was retired separately by AERIE-2735.

---

## Test plan

### Automated validation

- Task assignment, editor, detail, notification, public API, Work Plan, and existing-writer overlap suite: 137/137 passed (pnpm --dir chat exec vitest run components/task-board/task-editor.test.tsx components/task-board/task-detail.test.tsx components/dashboards/portfolio/__tests__/portfolio-rhodes-workbench.test.tsx convex/taskBoard/assignments.test.ts convex/taskBoard/mutations.test.ts convex/taskBoard/queries.test.ts convex/notifications/notifications.test.ts convex/publicApi/v2/domains/workManagementTaskBoardWrites.test.ts convex/publicApi/v2/domains/workManagementWrites.test.ts lib/public-api/v2/domains/work-management-task-board.node.test.ts --maxWorkers=1)

- Hard-deletion audit and retired Rhodes synchronization regressions: 2/2 passed, with 62 unrelated cases filtered out (pnpm --dir chat exec vitest run convex/rhodesPortfolioWorkbench.test.ts convex/rhodesMigrationRetirement.test.ts -t "deleteTask removes a task and writes audit|retir" --maxWorkers=1)

- Chat typecheck: passed (pnpm --dir chat typecheck)

- Lint, Biome, architecture boundaries, Convex paths, read bounds, test architecture, and knowledge hygiene: passed with two existing Sindri warnings (pnpm lint)

- git diff --check origin/main..HEAD: passed

- Exact-head diff scope: only the authorized paths listed above

### Time for Implementation

About 2 to 3 weeks for one engineer without AI assistance, including repository investigation, implementation, tests, review repairs, and prerequisite rebasing.

---

## What it means for end users/consumers

| Surface or consumer | What happens when this PR is deployed with the gate off | What this prepares after the gate opens |

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

| Existing Work Plan | The compact creation and editing flow stays the same. Existing internal assignees keep the same user-reference shape. | The same canonical Task can also be edited through Task Board surfaces. |

| Task Board UI | New assignment controls and external-assignee labels remain hidden. | Authorized creators, requesters, and global Task managers can manage multiple internal and external assignees. |

| Public API and agents | Existing published Task behavior remains available. New email-assignment input is rejected while the server gate is off, and no new agent operation is advertised. | The same Task API can accept bounded email assignments without creating a separate legacy API. |

| External assignees | No account is created, no Aerie access is granted, and no new production control is exposed. | Their normalized email is shown separately as External, no Aerie account. |

| Task participants | Existing creator and requester participation remains intact. Current internal-assignee changes also maintain the indexed assignee relationship needed by My Tasks. | My Tasks can query each user's relationship without scanning every Task. |

| Notifications | Assignment notifications are not enqueued while the gate is off. | Internal assignment and removal can deliver one in-app and one email notification with retry-safe, immutable rendering facts. |

| Task deletion | A deleted Task leaves current surfaces immediately. Its Task data and assignment records are preserved in bounded deletion audits before the related records are removed. | Assignment history does not make a Task undeletable and notification delivery does not depend on reloading a deleted Task. |

| Rhodes synchronization | Nothing changes. The retired synchronization is not reintroduced. | No dependency on Rhodes Task replacement remains. |

---

## Review repairs and contract clarifications

- [Mercy review](https://github.com/AI-Builder-Team/Aerie/pull/1712#discussion_r4207632095), tracked in [AERIE-2737](https://linear.app/builder-team/issue/AERIE-2737/manage-internal-and-external-task-assignments): the shared assignment resolver normalized email input but only checked for an at-sign. The accepted repair applies the existing server email validator before any assignment row is written and adds focused rejection coverage for malformed local, domain and multiple-at-sign inputs.

- [Combined-cardinality review](https://github.com/AI-Builder-Team/Aerie/pull/1712#discussion_r4207926022): a previously valid external set could later be combined with compact Work Plan internal reconciliation above the shared 100-assignee projection bound. The accepted repair enforces the cardinality invariant on the canonical identity-keyed desired set inside setTaskAssignments, so every writer and reconciliation path rolls back before creating an unprojectable Task.

- The public API concurrency finding is rejected as a false premise. updateTask requires ifMatch and calls requireRevision(args.ifMatch, current.revision, "Task") before setTaskAssignments in the same Convex mutation transaction.

- The assignment-denial findings are classified as coverage-only rather than demonstrated product defects. The mutation already rejects callers who are neither Task managers nor the creator/requester, and it rejects Completed and Rejected Tasks before assignment resolution or writes.

- The 101-row projection concern is closed by the canonical write invariant for valid data. Existing defensive read guards remain unchanged and continue to surface or suppress corrupt manually-created state according to their current surface contract.

- [Scheduled-cleanup review](https://github.com/AI-Builder-Team/Aerie/pull/1712#discussion_r4208152769) is rejected as a false premise. The delete mutation schedules an internalMutation atomically; Convex durably stores scheduled functions, guarantees scheduled mutations execute exactly once, and retries transient/internal failures. The cleanup performs only a bounded indexed read, one bounded audit snapshot, at most 100 deletes, and an atomic continuation. It does not reload or depend on the deleted Task. The 1,001-row regression proves recursive snapshot and removal after parent deletion.

- Unchanged boundaries: the Task Board gate remains off; no new assignment UI, public API input, agent operation, notification enqueueing or external-assignee write becomes reachable in production. Normal Work Plan behavior and the existing internal-assignee response shape remain unchanged.

- Validation: convex/taskBoard/assignments.test.ts passes 10/10, including malformed-email rejection, real-seam combined-cardinality rollback, immutable notification rendering after Task deletion, and 1,001-row bounded deletion cleanup; exact-head hosted CI is green.

---

## Review repairs and contract clarifications

- [Mercy review](https://github.com/AI-Builder-Team/Aerie/pull/1712#discussion_r4207632095), tracked in [AERIE-2737](https://linear.app/builder-team/issue/AERIE-2737/manage-internal-and-external-task-assignments): the shared assignment resolver normalized email input but only checked for an at-sign. The accepted repair applies the existing server email validator before any assignment row is written and adds focused rejection coverage for malformed local, domain and multiple-at-sign inputs.

- [Combined-cardinality review](https://github.com/AI-Builder-Team/Aerie/pull/1712#discussion_r4207926022): a previously valid external set could later be combined with compact Work Plan internal reconciliation above the shared 100-assignee projection bound. The accepted repair enforces the cardinality invariant on the canonical identity-keyed desired set inside setTaskAssignments, so every writer and reconciliation path rolls back before creating an unprojectable Task.

- The public API concurrency finding is rejected as a false premise. updateTask requires ifMatch and calls requireRevision(args.ifMatch, current.revision, "Task") before setTaskAssignments in the same Convex mutation transaction.

- The assignment-denial findings are classified as coverage-only rather than demonstrated product defects. The mutation already rejects callers who are neither Task managers nor the creator/requester, and it rejects Completed and Rejected Tasks before assignment resolution or writes.

- The 101-row projection concern is closed by the canonical write invariant for valid data. Existing defensive read guards remain unchanged and continue to surface or suppress corrupt manually-created state according to their current surface contract.

- [Scheduled-cleanup review](https://github.com/AI-Builder-Team/Aerie/pull/1712#discussion_r4208152769) is rejected as a false premise. The delete mutation schedules an internalMutation atomically; Convex durably stores scheduled functions, guarantees scheduled mutations execute exactly once, and retries transient/internal failures. The cleanup performs only a bounded indexed read, one bounded audit snapshot, at most 100 deletes, and an atomic continuation. It does not reload or depend on the deleted Task. The 1,001-row regression proves recursive snapshot and removal after parent deletion.

- Unchanged boundaries: the Task Board gate remains off; no new assignment UI, public API input, agent operation, notification enqueueing or external-assignee write becomes reachable in production. Normal Work Plan behavior and the existing internal-assignee response shape remain unchanged.

- Validation: convex/taskBoard/assignments.test.ts passes 10/10, including malformed-email rejection, real-seam combined-cardinality rollback, immutable notification rendering after Task deletion, and 1,001-row bounded deletion cleanup; exact-head hosted CI is green.

- Save a backup location's Portfolio Site selection, contract term, and operating confirmation in one transactional action.

- Preselect the sole contract term, require an explicit choice when several exist, and keep the current-term guard for operation today.

- Add an explicit stop-and-unlink flow with dated-need safeguards; remove the long protected-Site explanation from the editor.

- Cover location editor and shared writer behavior in tests.

## Summary

- calculate Start-of-Year weekly application pace from the authoritative conversion-rate window and canonical target-year applications

- publish tapered projected applications, expected enrollment, and historical comparison delta as additive V3 diagnostics

- preserve all existing selection, lifecycle status, headline, and model-version behavior

## Validation

- poetry run dbt parse --no-partial-parse

- deterministic dbt unit fixtures cover inclusive duration, measured zero, the February/March/April taper, comparison arithmetic, and unavailable-status non-regression

- singular assertion covers all-or-none provenance and diagnostic arithmetic

Closes #1705

Linear: AI-981

## What changed

The relay returned upstream bodies unchanged, so the upstream platform's name could reach callers. It was already visible on successful reads ("owner":"aerie" in provenance blocks, seen on the live service) and could appear in any upstream error.

- Successful JSON: provenance labels are renamed ("aerie" → "rhodes", "aerie.operations" → "rhodes.operations"). Only whole string tokens are matched and the body is not re-serialized, so notes, titles, links and numbers are exactly as stored. Binary downloads are untouched.

- JSON errors: status and detail are kept; the name is rewritten wherever it appears, and instance shows the caller's /api/v1 path instead of the upstream path.

- Upstream 401/403: these are about this service's own credential, so callers now get 502 upstream_unavailable instead of a message about a key they never held.

- Non-JSON errors (error pages, plain text): replaced with upstream_error (4xx) or 502 upstream_unavailable (5xx).

- Forwarded header values get the same rename.

- Contract: the same labels are renamed in the served OpenAPI so it still matches responses. Version 0.3.1 → 0.3.2.

- Docs that promised unchanged bodies now say record values and file bytes are returned as sent.

## Behaviour change to note

A caller that matched on the literal "aerie" / "aerie.operations" label values will now see "rhodes" / "rhodes.operations". An upstream 403 is now a 502.

## Business Value

Stakeholders set the rule that Rhodes is presented as its own dataset with no upstream platform name. The published text already followed it; the data responses did not. This closes the gap, including the failure paths where an upstream error would have exposed the name and details of the service credential.

## Manual Effort Estimate

About 3 hours by hand. Proposed figure; Keval to confirm or adjust.

## Testing

- pnpm check passes (49 tests).

- New test covers success, JSON errors, 401/403, HTML and plain-text errors, 429/500/503 and header values, and asserts recorded text containing the name is left alone.

- Contract test now asserts the name appears nowhere in the served OpenAPI.

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

## Summary

This is now the single review and merge target for the school-report stack formerly split across #2083, #2086, #2100, and #2102. Review the complete diff here against main; the three upper PRs are superseded and retained only as historical records.

- Report readiness and categories: correctly classify Transportation and Renovations/Furnishings, preserve known zero versus unknown actuals, and display approved missing budgets as unavailable without fabricated budget variances.

- Financial correctness and recovery: align Facilities/depreciation with the report cutoff through the owning warehouse procedure; preserve native-document layout/readback, source evidence, financial arithmetic, independent audits, bounded correction/recovery, and compatible saved-work resume.

- Bounded parallel processing: run 1–9 school-isolated workers with shared provider pacing and cooldowns, one fenced pipeline lease, failure isolation, and one consolidated completion email.

- HTML delivery: provide a full-width Finance digest and equivalent plain-text fallback with alphabetized native report links, reporting dates, aggregate updated/reused counts, and a conditional failure section.

- Durable source findings: retain both financial and operating Facilities values and insert an exact Finance-owned reconciliation finding rather than silently changing source values or withholding an otherwise usable report.

- Safe report reuse and pageless exports: verify immutable snapshots, combine retained and newly generated report links without regenerating unchanged schools, and validate readable/unencrypted/nonblank PDFs without imposing an artificial fixed page count.

- Controlled recipients: default to Ashwanth-only review delivery; a separate explicit, delivery-only approved_finance action reuses the proven review run for the fixed five-person Finance audience.

## Consolidation and review scope

| Former layer | Scope now reviewed in this PR |

| --- | --- |

| #2083 | Categories, missing-budget handling, Facilities cutoff, layout, audit/correction recovery |

| [#2086](https://github.com/AI-Builder-Team/Surtr/pull/2086) | Nine paced, isolated concurrent school workers |

| [#2100](https://github.com/AI-Builder-Team/Surtr/pull/2100) | HTML/plain-text completion digest |

| [#2102](https://github.com/AI-Builder-Team/Surtr/pull/2102) | Source findings, retained-report reuse, pageless PDF checks, approved Finance delivery |

GitHub automatically marked #2086, #2100, and #2102 merged into the consolidated base branch, not into main. #2083 is now unstacked and is the only open review target. The original upper branches are retained along with their PR histories.

The base branch codex/school-report-cost-categories is fast-forwarded from 6fa8d66f to the former top-layer commit 114001640a839f1ca837937f71f93c541e1384a6. All original commits are retained; no rebase, squash, cherry-pick, force push, or implementation change is needed. The consolidation baseline tree is identical to the former #2102 head (tree ddc45216dbe5a2e7db21014f85781e1a8844965b).

The PR targets main. It was draft during consolidation and was subsequently marked ready for review by ashwanth1109 while CI was running. This CI fix did not change readiness or enable auto-merge. Consolidation does not merge into main, deploy infrastructure, refresh warehouse data, generate reports, send email, or resolve review threads. Original upper PR descriptions remain available for detailed historical evidence; the original #2083 description is archived below.

## Business Value

Finance gets accurate, evidence-backed school reports despite explicitly identified source gaps, without fabricated budgets or silently reconciled values. Parallel processing and safe completed-report reuse reduce batch turnaround and unnecessary regeneration. A readable consolidated digest and review-first recipient workflow make delivery easier to inspect and deliberately approve.

## Implementation Effort

Approximately 45–67 engineer-hours for an average engineer to hand-code the combined solution without AI assistance, based on the four original layer estimates (20–30, 12–18, 4–6, and 9–13 hours). These estimates include differing amounts of deployment/live-validation work; additional validation effort may be required.

## Validation

### Fresh local checks — October 6, 2026

- School-performance report suite at the exact consolidated candidate: 300 passed.

- Education-financials upstream suite at the same candidate: 151 passed.

- git diff --check against current main: passed.

- Read-only git merge-tree against main at 3f67679a: clean, with no conflicts.

- Every former layer head is an ancestor of 11400164; the fast-forward preserves all four layers with no code change.

- No repository-wide lint/format run or production operation was performed for consolidation.

### Recorded pre-merge live validation

The former top-layer [#2102](https://github.com/AI-Builder-Team/Surtr/pull/2102) records exclusive deployment of the same commit 11400164 to Pipeline-school-performance-reports-prod, task revision 44, with CDK [1/1] and CloudFormation UPDATE_COMPLETE.

Its final review execution 6a1c4b05-9e60-4ca3-aa95-38f5ad74ce4d and explicitly approved Finance delivery execution a25e4985-9956-4adb-b6d5-71e0642addf6 each record 26 reports, zero failures, zero generated, 26 reused. The earlier batch exercised the nine-worker cap, unavailable Malibu budgets, the exact New York $391,000 Facilities source finding, and Raleigh's legitimate ten-page pageless export.

These are retained historical validation records, not new live runs or independently reverified AWS receipts in this consolidation session. Consolidation leaves the implementation commit and tree unchanged. Any subsequent implementation or repair still requires candidate live validation before merging under the user-level Surtr policy.

### CI import-order fix — October 6, 2026

Follow-up commit [9557f15a](https://github.com/AI-Builder-Team/Surtr/commit/9557f15a19396404333ba2f981f59f0a2ddfe7d4) fixes the absorbed stack's Ruff E402 failure in pipelines/runners/mart-aerie-education-financials-refresh/scripts/apply_facilities_cutoff.py. The helper must add its sibling script directory before importing apply_ddl; the import now has an explanatory comment and a narrow, line-only # noqa: E402. No global lint rule or workflow is relaxed.

- CI-pinned Ruff 0.15.22 check and format check pass for the only modified file.

- Python AST is identical to the pre-fix version: comments only, no runtime behavior change.

- The helper's default dry run succeeds without warehouse writes.

- Fresh local suites: 300 school-report tests and 151 education-financials tests passed.

- git diff --check passes.

- No production deployment, pipeline invocation, warehouse refresh, or email send was performed for this comments-only CI fix.

- [Fresh GitHub CI](https://github.com/AI-Builder-Team/Surtr/actions/runs/37482751012) completed successfully for this commit: all seven CI jobs passed, including Ruff check/format and the complete pipeline-runner suite. The automated review rerun was still in progress at the final CI verification; human review remains required before merge.

## Linear

- [SURTR-1535 — Categories and approved missing budgets](https://linear.app/builder-team/issue/SURTR-1535/fix-school-performance-report-categories-and-approved-missing-budgets)

- [SURTR-1538 — Parallel school-report workers](https://linear.app/builder-team/issue/SURTR-1538/run-school-performance-report-batches-with-three-isolated-parallel)

- [SURTR-1551 — HTML completion digest](https://linear.app/builder-team/issue/SURTR-1551/style-school-performance-report-delivery-as-an-html-digest)

- [SURTR-1553 — Unavailable budgets and source findings](https://linear.app/builder-team/issue/SURTR-1553/publish-school-reports-with-unavailable-budgets-and-source-findings)

## Historical base-layer description

<details>

<summary>Original #2083 description and detailed validation history (superseded scope statements)</summary>

The following text is preserved verbatim as historical evidence. Its earlier statements that upper-layer work was separate or excluded no longer describe the consolidated review scope above.

## Summary

Fixes discovered while validating school performance reports in batches. This remains a draft for review only; nothing has been merged. Candidate changes have been deployed for pre-merge validation.

- Expense categories: put 62500 Transportation under Program costs and 62100 Renovations/Furnishings as the second/last detail in Miscellaneous. Include both exactly once in financial totals, with the narrower operating Programs comparison explicitly labeled.

- Approved missing budgets: retain actuals, display Unavailable, and omit budget variances for Lunch Revenue, Financial Aid, Sibling Discount, Stripe Fees, Associate / Other Headcount, Landscaping, Lunch Program, Transportation, Renovations/Furnishings, Computers, Administration/Other, and the Miscellaneous subtotal. Other budget, actuals, Timeback, freshness, enrollment, model, and reconciliation safeguards remain enforced.

- Confirmed zero actuals: budget-only rows with explicitly zero actual postings produce zero management actuals. Unknown actuals with postings are not converted to zero.

- Native report layout: add two rows to each financial table in report copies only, preserving the pinned source template, inherited styles, revision guards, readback validation, and retry behavior. Use 90% financial-body line spacing to retain nine pages at the native 9pt font size.

- Scoped view migration: opt-in, dry-run-by-default migration of only mart_education.school_performance_report_lines, with definition/ACL backups, support for older views missing budget_value_status, transactional owner/grant preservation, and no cascading drops.

- Facilities cutoff repair: derive facilities/depreciation actuals from canonical atomic P&L postings through the report cutoff, instead of including the entire current month. Preserve the accepted QuickBooks generation/snapshot pins, monthly coverage guards, expense sign convention, allocations, model-budget proration, and atomic publication. Add a narrow procedure-only deployment script with backups and owner/ACL verification; no grants/revokes or table rebuilds.

- Native correction addresses: preserve report/claim structure in narrative-correction requests and list exact editable paths, compacting only source evidence. Fixes the observed Chicago correction targeting a columnar transport address instead of a real report field. Invalid paths still fail closed, and final audit remains required; saved drafts/contexts remain compatible.

- Truncated audit recovery: re-review the full original report, prominent text, accounting instructions, and all evidence in a bounded structured call; never treat opaque reasoning/signatures as user-text evidence. Preserve incomplete-coverage rejection, stage cost/deadline limits, corrections and final independent review. Saved research/drafts remain compatible.

- Correction numeric roles and resume compatibility: keep source-linked actual, model allowance and signed variance values separate in every correction request, outside prose compaction. Version correction results/context, so an unfinished old correction can be replaced from its compatible saved complete audit without repeating research/drafting; completed reports remain untouched. Final review and the one-correction limit remain enforced.

## Business Value

Enables usable school performance reports with correctly classified expenses and honest treatment of unavailable budgets. Aligns facilities and depreciation actuals with the report date, preventing future-dated entries from creating false reconciliation failures or overstating current spending. Makes audit output exhaustion recoverable without bypassing financial review or regenerating successful schools. Preserves the distinction between spending and comparison differences during narrative correction.

## Validation

- School report tests: 162 passed after the numeric-comparison correction fix (eight additional regression cases).

- Education financials upstream tests: 151 passed.

- Ruff checks on modified Python files and git diff --check: passed.

- Regression tests cover category totals, optional versus required budgets, zero versus unknown actuals, migration permissions, native row/style/retry handling, and the canonical facilities SELECT across cutoff/quarter boundaries, credits, wrong-school/publication/classification rows, and no-posting prefixes.

### Original changes: Boca Raton live validation

- Deployed only Pipeline-school-performance-reports-prod with --exclusively; CDK showed [1/1] and CloudFormation confirmed UPDATE_COMPLETE (task revision 28). No other pipeline stack was deployed.

- Applied the report-lines view migration with ownership/grants preserved and verified 37 distinct management lines.

- After correcting the added-row page spill, the resumed run completed SUCCEEDED, zero failures, at 2026-09-29 08:49:32 UTC. The nine-page PDF passed the layout guard and visual review; completion email was sent.

- Execution: boca-layout-resume-20260929-0847; run: e55c7dbe-4056-46d7-8d11-e0c2d2449ab7.

- [Boca Raton report](https://docs.google.com/document/d/1sL6T4wiuziNvuKdhX1pNypgD4af-knWO97L8E8YY_ls/edit).

### Batch two: candidate deployment and upstream validation

- Commit 1891f6f6 adds the seven separately approved budget exceptions. Deployed only Pipeline-school-performance-reports-prod using --exclusively ([1/1]), task revision 29; CloudFormation UPDATE_COMPLETE at 2026-09-29 09:06:51 UTC. No other stack or recipient configuration changed.

- Preflight identified future-dated September 30 depreciation in the facilities mart versus the September 29 report cutoff: $11,065.93 Brownsville, $7,747.62 Chicago. Report generation was not invoked against these known-invalid inputs.

- Commit d7070e9c repairs the owning facilities calculation (procedure version 2026-09-29.1). Applied only that procedure and its measure comment, verified original ownership/ACLs unchanged, and retained the original procedure backup. No upstream runner/infrastructure deployment was required.

- Authorized upstream platform run f9de7fb1-c7ed-4a09-9790-c25c922a92c6, execution facilities-cutoff-batch2-20260929-0917, completed SUCCEEDED at 09:18:54 UTC, publishing 10,208 facilities rows. Verified rent, facilities, and depreciation agree across the report and facilities tables for both schools. Correct depreciation: $24,963.43 Brownsville, $0 Chicago.

- That refresh picked up the newer 08:45:47 UTC FinalSite snapshot while the unit-economics tables still used 06:46:21 UTC. Preflight caught the mismatch; no report invocation occurred with mixed enrollment publications.

- With explicit additional authorization, unit-economics run 1c5bee2c-4e0e-47ea-87e3-e1614eb99259 succeeded at 09:26:37 UTC with 1,102 rows. Its automatic per-student run 053f1a3c-7a1f-441c-97bb-61d9d33d8bde succeeded at 09:26:53 UTC, also 1,102 rows. No model assignments or safety checks were changed.

### Batch-two report outcome

Full read-only preflight passed for both schools and the unchanged native template after enrollment publications were aligned. Run 4f390d10-edb1-4fc2-ad7b-c99b6408b426 completed at 2026-09-29 09:51:23 UTC, but its result was partial_failure, not complete report success:

- Brownsville succeeded, passed its independent evidence audit and PDF guard, and all nine pages passed visual review. [Completed report](https://docs.google.com/document/d/1zOALdJl1CU8d4MFsasUCPKs6ORDE1dpYOHNp5j8oMUc/edit). PDF SHA256: c37891c4b46804bf0fa7a76fb93fac7ecea35d234443ff11c5ecfe45210354e0.

- Chicago stopped before publication. Its audit correctly identified comparison-label/scope issues; correction generation then used the nonexistent transport path signals.rows[2][1]. The unchanged field guard rejected it. The summary email reported one ready and one failed school.

- Commit 326a5a4f fixes the correction request's native structure. Regression tests cover full, focused and previously compacted contexts, preserve evidence compaction, and continue rejecting the exact malformed path.

- Deployed only Pipeline-school-performance-reports-prod using --exclusively ([1/1]); CloudFormation confirmed UPDATE_COMPLETE at 09:57:43 UTC, task revision 30. No parallel-worker changes are included in this deployment.

- Verified immutable saved snapshots/draft/audit/context checksums, current freshness, template contract, and real editable paths before the authorized resume.

- Resume execution chicago-native-correction-20260929-0958, run 051588b7-a2b5-40f1-97cf-9544c24c3fc4, completed SUCCEEDED at 2026-09-29 10:03:40 UTC. Result: 2 reports, 0 failures, 1 reused report; summary email acknowledged by SES.

- Brownsville's document ID and PDF checksum are unchanged. Chicago resumed at correction, without repeating source capture/research, passed the final independent audit and PDF guard, and all nine pages passed visual review. [Completed Chicago report](https://docs.google.com/document/d/122G13Ecxp2om_UwsYMEODIn8h9-AuDs4NNJgzHW1PbQ/edit). PDF SHA256: 5ecba3c87d6fa53308a32b9320911d34ad1bde657fce78323b7f90a58e619276.

- The user-requested parallel-worker change is a separate stacked branch/PR, not included here.

### Kirkland: audit recovery live validation — September 29

- Commit 8b0c2d92ba7d9e8e8043937f229a643a5eb4c49e fixes the truncated-audit fallback. The old fallback had only a JSON serialization of opaque thinking and could not certify coverage. The new fallback independently reviews the same complete report/evidence with thinking disabled, a strict 6,000-token verdict allowance, counted full-context cost, and the unchanged 180,000-token stage / 900-second deadline. Missing coverage or truncated recovery output still fails closed.

- Eight regression cases cover opaque-response recovery using the saved draft, complete evidence including confidence-only receipts, incomplete coverage, truncated/missing verdicts, correction plus fresh final audit, and both reserved and recounted cost limits. Parent suite: 154 passed; restacked candidate suite: 169 passed. Targeted Ruff and diff checks passed.

- Deployed only Pipeline-school-performance-reports-prod, --exclusively, CDK [1/1]; CloudFormation UPDATE_COMPLETE at 11:21:31 UTC. Task revision 32, image digest sha256:5786dfa972a7cb7ae4982e73eca72089ac3b926dc8e71b605f39b1dac6db123d. The deployed candidate 94a2c767bf5eac6620470d3a6dccb01c8f5f3f95 includes the unchanged parallel-worker layer. No other stack, upstream refresh, model assignment, or recipient change.

- Fresh source/template preflight passed. Exact saved snapshot/research/draft versions and checksums were verified; current publication fingerprints matched the retained snapshots. Resume contract remained unchanged.

- Execution kirkland-audit-recovery-20260929-1122; run 2f69a5f4-02b1-40d2-97f6-23f6f908c872, resuming 474b28cb-5125-4c21-8175-ec01e0b0bbad.

- The deployed recovery path was actually exercised: the first audit consumed all 14,000 output tokens without a verdict; fresh full-evidence recovery returned complete coverage and a structured rejection, identifying a Programs comparison-label issue. Initial audit plus recovery consumed 66,404 tokens, within the unchanged cap. The built-in correction ran, followed by a fresh complete final audit.

- Report outcome remains partial failure, not successful Kirkland publication. The automatic correction introduced a separate material actual-versus-variance wording error. The final audit completed (38,307 tokens) and correctly rejected it; the existing one-correction limit stopped the school. No Kirkland Google Doc/PDF was created. Saved corrected draft and audit evidence are retained. The audit-recovery fix is live-verified; this separate narrative-correction issue still blocks Kirkland.

- La Jolla reused unchanged: same document ID 16Umzqz83io-lFdLzDROC4BjPXpRm1gKeKHd_-yr4b5w and PDF SHA256 eabb85d232ac6314a436e817a66da8d90908b19d890c94df5db238735e74aa80. Kirkland's original research/draft references also remained unchanged; neither was regenerated. Houston Heights and all other schools were excluded.

- One summary email was accepted by SES for ashwanth.r@trilogy.com (010001a0ececcb2e-444976e3-266e-4cc7-9b06-b54a18111791-000000). No inbox-delivery claim. The run is terminal and the pipeline lease is released. Paused pending authorization to address the new correction error; no automatic retry or next batch.

### Authorized Kirkland correction retry — successful September 29

This resolves the separate narrative blocker recorded in the preceding run. The user explicitly authorized fixing the correction and retrying final review from saved work, keeping La Jolla unchanged.

- Fix commit 3ed718e0b3fa90a8d25af70fe28c3544d624f29f. Numeric comparison entries retain exact E00 source paths, metric/breakdown identities and units, plus distinct actual/model/variance fields. They survive focused context and prose compaction. New correction rules prohibit substituting a variance or quarter-to-go for actuals and prefer omitting a secondary comparison to ambiguous shortening.

- Correction policy school-performance-correction-v2-comparison-roles is included in correction results and context signatures. A saved older correction is redone only if its prior audit completed and has identical evidence. Current-policy corrections resume at final review; approved reports return unchanged. No extra automatic correction cycle, altered financial data, or reduced audit gate.

- 162 parent / 177 combined tests passed, including numeric roles/nulls, compaction preservation, old/current/approved checkpoint handling, missing/incomplete/mismatched prior-audit handling, and continued rejection of an incorrect final correction. Targeted Ruff and diff checks passed.

- Native stack #2087 rebased bottom-up and safely pushed; combined candidate 42bb39f46ee889339b9d3df1a5d6d5ffa893e325. Only Pipeline-school-performance-reports-prod deployed with --exclusively; CDK [1/1], CloudFormation UPDATE_COMPLETE at 11:38:39 UTC, ECS revision 33, image digest sha256:567e2c8148ddbe3c0a4e060f5533c7ea22752a0c14b41f47d8a0eec8f5a4c069. No other stack, upstream refresh, school/model assignment, recipient or schedule change.

- Fresh full source/template preflight passed. Exact saved snapshot/research/draft/audit/correction versions and checksums were verified; source publication fingerprints were unchanged. The saved audit/correction evidence matched and the direct comparison ledger reconciled.

- Execution kirkland-comparison-retry-20260929-1139, run dfc18896-0389-41cc-bad7-5ae89015133c, resuming 2f69a5f4-02b1-40d2-97f6-23f6f908c872. Terminal SUCCEEDED, 11:39:24–11:44:05 UTC, ECS exit 0; report result success: 2 reports, 0 failures, 1 reused.

- Kirkland completed: original research/draft/snapshot references are unchanged. The deployed new policy rebuilt only the correction from the saved audit, then completed fresh final review with approved=true, coverage_complete=true, issues=[]. The corrected Programs card clearly distinguishes actuals, QuickBooks budget, and variance; the misleading model-variance-as-spending phrase is absent. No initial research/drafting or initial audit was repeated.

- [Completed Kirkland report](https://docs.google.com/document/d/1xWYkhsdsrt7m04VotO4M9RCGLq72zyznbITVW9D1piE/edit). Exact retained PDF SHA256 132254afd64c713d6cffd17050ee37a8a6703e3942bffabd9804c9dd6835e0f5. Runtime PDF checks passed; all 9 pages were rendered and visually checked, including comparison labels, tables, category placement, unavailable budgets and complete evidence/confidence layout.

- La Jolla reused unchanged in 0.5 seconds: same document 16Umzqz83io-lFdLzDROC4BjPXpRm1gKeKHd_-yr4b5w, same PDF SHA256 eabb85d232ac6314a436e817a66da8d90908b19d890c94df5db238735e74aa80. No other school was invoked.

- One consolidated email accepted by SES for ashwanth.r@trilogy.com: 010001a0ecfa36ee-1f658f77-7386-45d9-9e4b-019a85e90cdc-000000. The batch lease is released. Paused before the next batch. Both PRs remain draft; nothing merged.

## Scope and remaining investigation

The 18 changed files are limited to the report runner and the owning facilities procedure, its deployment script, tests, and documentation. No schedule, recipient, shared infrastructure, or model-assignment changes are included. No confidential report/evidence artifacts are committed.

East Bay remains paused: 19 students, but no assigned unit-economics model. Bethesda and Boston Suburbs retain their separate model/enrollment prerequisite blockers. No next batch is started automatically.

## Linear

[SURTR-1535 — Fix school performance report categories and approved missing budgets](https://linear.app/builder-team/issue/SURTR-1535/fix-school-performance-report-categories-and-approved-missing-budgets)

## Implementation Effort

Estimated 20–30 engineer-hours (about 2.5–4 days) for an average engineer to investigate and hand-code the SQL, validation, native Google Docs layout/retry changes, safe migrations, regression tests, cutoff repair, and pre-merge live validation without AI assistance.

## Five-school audit/correction recovery — September 29

The user authorized repairing the five failures from nine-worker run b7adcc20-8aa3-4dbd-b9b7-fe70021ec81c and resuming saved work, retaining Boston, Santa Monica, Scottsdale and The Woodlands unchanged.

Parent fix 3139d150db6224014728b3602e5e367660897ace, combined candidate 0d36afbbfe37f4a0c56df21f7db628d56a2a129c:

- Chantilly: request at most one audit verdict. An unexpected multi-verdict response is not cherry-picked; the bounded full-evidence recovery must independently produce one complete verdict.

- Charlotte: the one incomplete-audit retry now has two disjoint review scopes covering every claim and confidence paragraph. Both retain the full report and every receipt, must attest complete coverage, and share the original 180,000-token / 900-second audit ceiling. No incomplete verdict can reach publication or be mistaken for an issue to edit away.

- San Francisco: direct numeric comparison context now explicitly separates booked and management actuals, including booked-minus-budget/model calculations. Published financial variances are labeled as management-based. Unavailable benchmarks remain null.

- Dorado: a policy-upgrade resume re-audits the latest saved correction, rather than editing the old draft using only its first audit's issues. It can therefore address a headline defect discovered at final review without reverting earlier fixes. The same single-correction limit and fresh final audit remain mandatory.

- Palo Alto: correction requests carry exact field-length ceilings and conservative targets. The second bounded text-repair call gets its actual rejected text and measured length. Secondary examples may be omitted to fit, but retained amounts, comparison basis/direction and necessary qualifications cannot change. Full evidence review and PDF checks remain mandatory.

172 parent / 211 combined tests pass. Targeted Ruff and git diff --check pass. Regressions cover ambiguity recovery, complete two-part coverage, all receipts retained, combined issues, shared budget exhaustion, exact booked variance/null handling, field limits, rejected-text feedback, new-policy fresh review, and preservation of already-corrected fields. The native stack was rebased bottom-up and pushed with explicit force-with-lease checks; both PRs remain draft and nothing is merged.

Read-only resume preflight passed for all nine exact retained snapshot versions/checksums, their generation checkpoints and evidence references, the 48-hour source freshness constraints, six-table/enrollment/model contracts, deterministic rendering and the unchanged native template. The invocation contract is unchanged apart from resume_run_id. Five unfinished schools reuse research and drafts; four completed schools reuse existing document IDs and PDFs. No upstream refresh, model assignment, school mapping, recipient or schedule change.

Live validation finished with remaining blockers — not ready to merge. Only Pipeline-school-performance-reports-prod was deployed, using --exclusively; CDK reported [1/1] and its CloudFormation events reached UPDATE_COMPLETE at 12:33:05 UTC. Task definition 35 ran the combined candidate image. No other pipeline, registry or shared stack was deployed.

The authorized resume 967c955b-a8ef-41af-86c6-1b2f6b573fea ran from 12:33:56 to 12:41:50 UTC. Step Functions succeeded, but the application correctly reported partial_failure: 8 published reports, 1 failure, 4 reused. Boston, Santa Monica, Scottsdale and The Woodlands retained their exact prior document/PDF references. Chantilly, Dorado, Palo Alto and San Francisco completed from saved research/drafts; Charlotte retained its corrected draft. Checks confirmed unchanged research/draft and source snapshot references; no full generation was repeated. The usual summary email was sent to the unchanged recipient with eight published reports. The pipeline lease was released.

All 36 pages of the four newly published PDFs were rendered and visually inspected. Layout and page-count checks passed. San Francisco's corrected management-profit/variance pairing, Dorado's operating-program variance and janitorial account attribution, and Palo Alto's fitted correction are present. However, automated approval is not sufficient: manual inspection found the narrative defects below, so Chantilly and Dorado are published, not fully QA-approved. The email had already been sent before this post-run inspection; those documents have not been silently edited or regenerated.

### Remaining blockers found by live validation

- Charlotte — review budget coordination: its final audit exhausted the 14,000-output allowance, then the full-evidence recovery returned incomplete coverage. The first scoped retry completed and approved its own scope, but the second was blocked before invocation by the shared 180,000-token gate, including its full recovery reserve. The final audit had actually spent 117,507 tokens by that point; this is a reservation/planning failure, not evidence that the corrected narrative is wrong. The runner did not publish a half-reviewed report. The scoped fallback was live-exercised but did not finish; its live validation remains failed.

- Chantilly — standalone headline arithmetic missed by automated audit: facilities total spend $35.1K is labeled as the over-model amount instead of the actual ~$5.8K variance. Both a depreciation headline and finding title label $10.8K actual spend as the amount over both benchmarks; the overruns are ~$10.1K against QuickBooks and ~$9.6K against model. Tables and explanatory paragraphs retain the correct values. These three narrative fields need correction and a stronger comparison check.

- Dorado — explanation/attribution missed by automated audit: finding 7 and the Timeback transaction-reference paragraph say the allocation raises EBITDA, while the report's own basis shows booked EBITDA -$393,604.62 becoming management EBITDA -$488,332.07 after the $94,727.45 allocation. Its second opening signal also attributes the EBITDA result partly to depreciation, despite depreciation being added back. The third signal calls all six rent rows bills, whereas its detailed evidence distinguishes rent bills from two purchases. The displayed accounting totals are correct; these causal/directional and transaction-type descriptions need correction.

Work is paused after this batch, consistent with the requested investigate-and-confirm workflow. No follow-on execution or completed-document modification has been made. Recommended next step: repair the bounded audit scheduling and these saved-narrative QA gaps, then resume/review only the affected saved work after user confirmation. Other completed September 29 reports remain reusable and unchanged; combining reports from separate historical runs into one delivery is a separate operation, not part of this resume.

Evidence: /tmp/surtr-review-resume-OIfR2u (deployment events, terminal result/email checkpoints, immutable-source assertions, audit receipts, exact-version PDFs and rendered pages).

Incremental implementation effort for this recovery work: approximately 4–6 engineer-hours without AI assistance (in addition to the earlier work estimated below).

## Three-school saved-work repair — September 29

The user authorized fixing Charlotte's remaining audit-budget failure and the post-publication QA findings in Chantilly and Dorado, leaving all other reports untouched.

Parent 8bb89187, combined candidate 087a7534. Native stack #2087 was rebased bottom-up and pushed with leases. Both PRs remain draft; nothing is merged.

- The incomplete-review fallback now counts and reserves both disjoint scopes before starting either. Each gets full evidence and a 6,000-token forced verdict with thinking disabled, without recursively reserving another complete recovery per scope. Complete coverage of both remains mandatory; the original 180,000-token / 900-second safety limits remain unchanged. Truncation, ambiguity, incomplete coverage and unaffordable plans fail closed.

- Explicit repair_reports maps selected completed school IDs to retained human-QA findings. It requires matching published insights and a compatible saved approval with receipts. A new repair seed starts from the latest published text, receives one scoped correction and a full fresh final audit. Previous documents/PDFs/checkpoints remain intact, with supersedes provenance for replacements. No research/draft generation is repeated, and unselected completed reports are imported unchanged.

- Supplementary deterministic checks reject unambiguous facilities/depreciation variance labels that use spending or disagree with exact source arithmetic, and explicit EBITDA/addback or allocation-direction contradictions. They respect displayed rounding and explicit EBITDA-neutral/addback qualifications; they supplement, not replace, full evidence review.

198 parent / 239 combined tests pass. Targeted Ruff and git diff --check pass. Regression coverage includes Charlotte's observed budget scale, all-evidence scope coverage, fail-closed incomplete/truncated output, no partial-review approval, explicit repair eligibility, published-text seeding, mandatory final review, preservation of other reports/prior documents, same-run idempotency and the observed narrative defects/valid qualifications.

Read-only preflight passed against the exact retained snapshots and checkpoints from 967c955b-a8ef-41af-86c6-1b2f6b573fea, the 48-hour freshness and six-table contracts, current native template, unchanged recipients and role. Six reports will be reused, Chantilly and Dorado repaired, and Charlotte resumed at final review. Seven reports from earlier batches remain outside this run and unchanged. No warehouse writes or upstream refreshes.

Live validation finished with two narrative blockers — not ready to merge. Only Pipeline-school-performance-reports-prod was deployed with --exclusively; CDK showed [1/1], and CloudFormation reached UPDATE_COMPLETE at 12:58:07 UTC. ECS task definition 36 ran image digest sha256:354bf51b1de2b1d12430c41caf84125b5acf0cbbf95e8fc3962912e4b10e6c2c. No other pipeline/shared/registry stack or upstream refresh was deployed.

Resume 6b7d7aa3-5249-43b1-9a25-1c62b8f20328 ran from 12:58:34 to 13:04:10 UTC. Step Functions succeeded; the application result is correctly partial_failure: 8 reports, 1 failed repair, 6 reused. The completion email was sent to the unchanged recipient, and the lease was released. Boston, Palo Alto, San Francisco, Santa Monica, Scottsdale and The Woodlands retain identical prior document/PDF references. All original research/draft/snapshot references remained unchanged; repaired reports retain identical receipts. Seven earlier-batch reports were not included or modified.

- Dorado: the targeted repair completed, passed full evidence review (50,968 final-audit tokens), and all nine PDF pages were manually inspected. Five narrative fields changed only within the four authorized claim scopes, correcting EBITDA direction, depreciation/addback causality, and six rows versus six bills. [Corrected replacement document](https://docs.google.com/document/d/1DNkPYEJsQDqlxs7CsBFOVnA8zxl5zCuK1WE1m2CgxRM/edit). The prior published document/PDF remain untouched.

- Charlotte: final review completed on the first call (41,882 tokens), and publication succeeded with its saved corrected narrative byte-for-byte unchanged. The new scoped fallback was not needed in this live run; its budget behavior is regression-tested against the observed 80,740-token starting balance and complete evidence. All nine PDF pages were inspected. Manual QA then found a separate, pre-existing narrative error: several claims invent a 13-versus-25 enrollment target as the revenue-gap cause. E00's model revenue is $130,000 = 13 actual students × $50,000 annual tuition × 0.2; 25 is capex_reference_student_count in the model assumptions, not a revenue enrollment target. The financial tables are correct. Charlotte is published and emailed, but not fully QA-approved.

- Chantilly: the saved correction now contains the correct $5.8K facilities-over-model headline and separate $10.1K QB / $9.6K model depreciation overruns in its headline/finding. Final review (50,807 tokens) correctly blocked the replacement because the executive paragraph still calls $10.8K actual depreciation 'over both budget and model'. That paragraph was outside the supplied repair findings/allowed correction claims. No replacement document was published or included in this email; the corrected work and original published version are retained.

Next step, awaiting user direction after this batch: extend the explicit saved-work repair path to accept the latest unfinished corrected narrative with new QA findings (without replaying research or reverting the headline fixes), repair Chantilly's executive paragraph, and correct Charlotte's enrollment-benchmark/causal claims using the actual revenue-model basis. Keep every other report untouched. No automatic extra correction cycle or follow-on execution has been started.

Evidence directory: /tmp/surtr-three-repair-OzHvpw (preflight, deployment events, terminal result/email, immutable-reference assertions, audit receipts, narrative diffs, exact-version PDFs and all 18 rendered/reviewed pages). Deployment alone is not validation, and automated publication is not human QA approval.

Incremental implementation effort: approximately 3–5 engineer-hours without AI, beyond the earlier estimates.

## Saved-work narrative repairs — September 29, 2026, final validation

- Latest correction can now be an explicitly authorized repair source, not just a completed approval. Source stage and immutable reference are retained. An approved publication in progress cannot silently roll back to an older correction. Ordinary retry behavior is unchanged: no extra correction loop and no research/drafting regeneration.

- Correct the remaining Chantilly executive depreciation variance, preserving the three earlier headline/title fixes. The new source-backed check also caught its related 9 vs 25 enrollment inference before dispatch.

- Distinguish actual/model student counts from the CapEx reference denominator and model-name suffix. Remove Charlotte's unsupported 25-student enrollment target and enrollment/pricing causal claims throughout its affected narrative; preserve all reported amounts and require reconciliation instead of inventing a cause.

- Add narrow regression guards for directly labeled body-text expense variances (including “over both budget and model”) and misuse of CapEx reference counts as modeled enrollment. Full-source review still remains mandatory.

- Tests: 213 parent / 254 combined pass; targeted Ruff and git diff --check pass.

- Candidate deployed before merge: parent 6fa8d66f, combined 67cd5297, task definition 37, image digest sha256:68db812865cd85046ad4c7842b006c9e05ea8038f83574b0204ebe8dd385ccd7. Only Pipeline-school-performance-reports-prod deployed with --exclusively; CDK [1/1] and CloudFormation UPDATE_COMPLETE at 13:17:17 UTC verified. No upstream/warehouse change or other pipeline deployment.

- Live validation: arn:aws:states:us-east-1:479395885256:execution:pipeline-school-performance-reports-prod:repair-two-saved-reports-20260929-131743; Surtr run 667b1467-231f-4fae-96e6-2dd58706bd11. 9/9 reports complete, 0 failures, 7 exact reused reports, consolidated email sent to the unchanged configured recipient. Only Chantilly and Charlotte received bounded corrections and fresh full-source audits, using byte-identical retained evidence and original snapshot/research/draft references. Prior documents remain retained, new reports record superseded publication/source provenance. Dorado and every other report untouched; lease released.

- Both new PDFs have nine pages; full visual/narrative QA completed. No changes beyond the selected narrative claims; earlier Chantilly corrections preserved. Paused after this batch; both PRs remain draft and unmerged.

### Requested consolidated delivery: all 16 schools

After both repaired reports passed audit and manual QA, the user requested inclusion of the seven earlier completed reports (Boca Raton, Brownsville, Chicago, Fort Worth, High Austin, Kirkland and La Jolla). A separate delivery-only consolidation used the unchanged existing delivery.send helper, pipeline lease, immutable S3 manifest and idempotent/uncertain-send protection. This was not another generation run, a change to the fixed-school-list resume contract, or another deployment.

Read-only preflight verified complete source checkpoints, September 29 cutoffs, exact-version snapshot/narrative/PDF checksums, nine-page PDF contracts, native document completion and existing access for the unchanged recipient. 16 distinct report links sent, 0 generated in the consolidation, delivery ID consolidated-16-20260929-f16193e2b34c8ce3. The 14 other reports stayed unchanged; only Chantilly and Charlotte were repaired in the preceding run. Delivery manifest retained at s3://surtr-school-performance-evidence-prod-479395885256/runs/consolidated-16-20260929-f16193e2b34c8ce3/6db7048a-299b-41a1-97e5-20a0e50e70f5/delivery/consolidation-manifest/d58e1cf7309a47c68e187a0931d07f313b5bc5e12f602d84a98cb541ecabc44e. No source run/checkpoint/document was edited for consolidation.

</details>

## Summary

This PR is Phase 3 of 13 in the larger [Human Task Assignment from Aerie](https://linear.app/builder-team/project/human-task-assignment-from-aerie-b3582376ae6e) project.

It retires the Aerie receiver and migration paths that allowed Rhodes to replace or delete Aerie Tasks. This phase is tracked by [AERIE-2735 — Retire legacy Rhodes Task synchronization](https://linear.app/builder-team/issue/AERIE-2735/retire-legacy-rhodes-task-synchronization).

Production effect: cleanup or removal. Authenticated requests to the legacy Rhodes Task replacement and deletion paths receive an explicit rejection. Normal Aerie Task creation, including default Tasks created with a site, is unchanged. No production effect depends on the archived Rhodes repository.

## Why

Aerie is now the owner of Task data. Leaving the legacy replacement and import paths active would allow a legacy request to overwrite or delete newer Task fields added by the Task Board. This PR closes those Aerie-owned boundaries while preserving every non-Task behavior.

## Business Value

- Prevents legacy synchronization from overwriting or deleting Aerie Tasks.

- Keeps non-Task Rhodes synchronization working with its existing ordering and failure behavior.

- Protects the Task Board foundation without changing how people create or use Tasks today.

- Gives operators an explicit response when anything calls the retired Task path.

## How does it work

1. The internal Rhodes event handler rejects Task replacement and deletion before any Task record can change.

2. The HTTP receiver records each retired Task event as a terminal semantic rejection.

3. Mixed batches skip retired Task entries and continue with retained entries in order.

4. The first real retained-event failure still stops the batch. Later retained events are not applied and remain retryable, matching the existing fail-fast contract.

5. Manual Rhodes migration preparation and deletion no longer accept the Tasks table.

6. The archived Rhodes repository is inactive and out of scope. This Aerie cleanup is self-contained.

## Scope

### Included in this phase

- Explicit rejection of authenticated Rhodes Task upsert and delete events.

- Safe handling of old mixed batches without blocking retained events or changing their fail-fast behavior.

- Removal of Tasks from manual Rhodes migration preparation and deletion.

- Regression coverage proving normal Aerie Task creation remains available.

- Exact final diff paths:

chat/convex/publicApi/v2/workManagement.test.ts
chat/convex/rhodes/dualWrite.ts
chat/convex/rhodes/migration.ts
chat/convex/rhodesDualWrite.test.ts
chat/convex/rhodesMigrationRetirement.test.ts

### Deliberately excluded for later phases

- Changes in the archived Rhodes repository. It is inactive, out of scope, and not required for this Aerie cleanup.

- Task Board assignment, lifecycle, evidence, approval, notification, digest, and UI work.

- Changes to normal Aerie Task creation or default Tasks created when a site is created.

- Changes to any retained non-Task Rhodes synchronization contract.

## Test plan

### Automated validation

- Rhodes receiver and authentication contract — 17/17 passed (pnpm --dir chat exec vitest run convex/rhodesDualWrite.test.ts).

- Receiver, migration retirement, existing Task dates, CRUD, scoring, and document identity regression suite — 51/51 passed (pnpm --dir chat exec vitest run convex/rhodesDualWrite.test.ts convex/rhodesMigrationRetirement.test.ts convex/rhodes/workManagementDates.test.ts convex/rhodesCoreCrud.test.ts convex/rhodesP2Scoring.test.ts convex/rhodes/documentCrudIdentity.test.ts).

- Chat and Convex typecheck — passed in the final commit hook.

- Focused Biome and Convex path checks — passed in the final commit hook.

- Architecture boundaries, Convex paths, read bounds, and test architecture — passed (pnpm lint:boundaries && pnpm lint:convex-paths && pnpm lint:read-bounds && pnpm lint:test-architecture).

- git diff --check — passed.

- Exact-head diff scope — only the five authorized paths listed above.

### Time for Implementation

About 2 engineering days without AI assistance, including synchronization analysis, receiver-contract verification, failure-order regression coverage, migration-path cleanup, and validation.

## What it means for end users/consumers

| Area | What changes | What it means for end users/consumers |

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

| Normal Task creation | Nothing changes. Aerie users and existing Aerie code can still create Tasks, including default Tasks created with a site. | Current Task creation workflows keep working. |

| Existing Tasks | The legacy Rhodes receiver can no longer replace or delete them. | New Task Board fields and Aerie-owned Task data cannot be erased through the retired path. |

| Non-Task Rhodes data | Existing synchronization remains available and keeps its original event order and fail-fast behavior. | Sites, Work Units, documents, and other retained resources continue using their current synchronization path. |

| Legacy Task-only requests | Aerie returns an explicit retired-path rejection and marks the event as terminal in the response. | Operators can identify a caller using a path that no longer supports Tasks. |

| Legacy mixed requests | Retired Task entries are skipped. Retained entries before and after them are processed in order unless a real retained entry fails. | A retired Task entry cannot block unrelated synchronization work. |

| Retained-event failures | Processing stops at the first real failure. Successful and retired entries already handled are acknowledged; the failed and unprocessed entries remain retryable. | Later dependent work is not applied out of order. |

| Manual migration tooling | Tasks can no longer be prepared or deleted through the Rhodes migration surface. | Operators cannot accidentally reintroduce Task replacement through a second legacy path. |

| Archived Rhodes repository | No change or deployment is required there. | This PR's production effect is entirely contained within Aerie. |

## Testing contract

### What this PR delivers

It closes Aerie's legacy Rhodes Task receiving and migration paths while leaving normal Aerie Task creation and retained non-Task synchronization unchanged.

### Who uses it and where

The affected surfaces are Aerie's legacy Rhodes receiver and migration tooling. The archived Rhodes repository is not a production consumer or dependency. Aerie users should see no Task UI change.

### Conditions needed

- Use the configured Rhodes shared secret for receiver requests.

- Test Task-only, mixed Task/non-Task, and retained-event failure batches.

- No deployment or configuration change in the archived Rhodes repository is needed.

### Expected behavior and examples

- A Task-only event receives HTTP 410 with a semantic retirement result and does not change the Task.

- A mixed batch can acknowledge a retired Task and still apply retained events around it.

- If a retained Work Unit event fails, a later retained event is not applied and the response leaves both available for retry.

- Creating a Task through the existing Aerie API still succeeds.

### Limits and unanswered questions

The archived Rhodes repository is inactive and deliberately out of scope. This Aerie-only change has no external deployment or configuration dependency.

## Summary

- retire aerie_milestone_v2 from the shared supported-version contract

- move runtime, dashboard, sync, and public API success fixtures to V3

- reject V2 publications while preserving the last known-good V3 run

- keep Forecast V2 product and /v2 API contracts unchanged

## Validation

- pnpm --dir packages/contracts exec vitest run src/admissions-forecast-v2.test.ts src/admissions-forecast-v2-physical.test.ts --maxWorkers=1

- pnpm --dir sync exec vitest run src/analytics/admissions-forecast-refresh.test.ts --maxWorkers=1

- pnpm --dir chat exec vitest run --project edge convex/admissions/forecastV2.test.ts --maxWorkers=1

- pnpm --dir chat exec vitest run --project edge convex/publicApi/v2/admissions.test.ts --maxWorkers=1

- package typechecks, Biome, and test-architecture checks

Closes #1708

## Summary

- rank viable COMPLETED/ENROLLED/PENDING_REVIEW rows ahead of terminal duplicates

- preserve only strictly earlier muted terminal rows as audited departure outcomes

- add fixed-date dbt unit coverage for viability, chronology, transfers, deduplication, and terminal-only partitions

## Validation

- poetry run dbt parse --profiles-dir .

- current-head CI: full PR-prefixed dbt build and test suite passed

- canonical uniqueness: 2,819 rows / 2,819 student-offering grains; no duplicate grains

- warehouse sources refreshed 2026-10-07 10:10–10:11 UTC

## Before/after student membership comparison

- Axl Meyer (2025, Alpha Scottsdale): added On Campus; removed Withdrawn; First Day remains represented by the canonical completed enrollment

- Maya Gries-Yano (2025, Alpha San Francisco): removed First Day; added Mid-Term Join and On Campus; Withdrawn remains exactly once from the earlier terminal UUID with pre_reentry_terminal_outcome

- no other On Campus, arrival, withdrawal, transfer, graduation, or re-enrollment memberships changed

Closes #1703

## Summary

- Keep historical Backup Site API idempotency receipts valid by accepting their optional responseLocation field.

- Add a replay regression using that stored receipt shape.

## Why

Release PR #1701 cannot push its schema to the current dev deployment. A bounded read-only inspection also found two production backupSiteApiIdempotency receipts with this field. The release schema omitted it, so the failure is not missing dev data. The current writer no longer needs to create this field; retaining it as optional permits existing receipts until TTL cleanup.

## Validation

- pnpm --dir chat exec vitest run convex/publicApi/v2/backupSiteManagement.test.ts --maxWorkers=1 (5 passed)

- pnpm --dir chat typecheck

- pnpm exec biome check chat/convex/publicApi/schema.ts chat/convex/publicApi/v2/backupSiteManagement.test.ts

- git diff --check

- Pre-commit Convex paths, Biome, and Chat typecheck passed.

## Release note

Merge to main before approving #1701, then re-pin and rerun exact-head schema acceptance and smoke. This PR does not deploy or modify production data.

## Summary

- Prorate 42DS Q3'26 total actual revenue from its 42-day operating period to a full-quarter equivalent before annualizing.

- Limit the adjustment to 42DS in Q3'26; Revenue Growth% recalculates from the adjusted value.

- Add coverage for 42DS Q3'26, another acquisition, and a later 42DS period.

- Confirmed with Ravi (stakeholder) that this is a one-off case.

## Validation

- Focused Vitest spec: 2 passed.

- pnpm lint:pr: passed.

- pnpm prettier --check src/screens/JoeChartsV2/dataTransformation.ts src/screens/JoeChartsV2/dataTransformationComparison.spec.ts: passed.

- pnpm tsc -p tsconfig.app.json --noEmit: passed.

- pnpm test:run: 675 files passed; 6,935 passed; 16 skipped.

- pnpm build: passed with Browserslist age and large-chunk warnings.

## Screenshot

<img width="1909" height="451" alt="image" src="https://github.com/user-attachments/assets/93f56db4-fd15-4ca4-b501-0db56ae764f8" />

## Summary

- Add a run-current view that selects the latest accepted Core publication per as_of_date, ordered by refreshed_at DESC and then source_run_id DESC.

- Add a fact-current view that joins only the selected Core receipt; historical facts and accepted zero-row receipts remain available.

- Update Q118 verification SQL, consumer documentation, tests, and the Finance handoff.

## Verification

- uv run pytest -q — 236 passed

- uv run ruff check src tests — passed

- uv run ruff format --check src tests — passed

- apply_ddl.py dry run parsed four statements

## Warehouse status

DDL 015 was applied to finance_dw as sanket.ghia on 2026-10-07. Read-only checks confirmed the views and the 30-Jun/31-Jul selected run IDs and totals. No QBO pipeline was run. The DDL contains no grants or revokes; CQL_download_OM can query both views, while readonly_group access was not separately verified and remains DBA-managed.

Linear: AI-980

## What changed

Dictionary only. Three more items from Arthur Michel's review of the Rhodes DSS (Ops Automation Trilogy, 2026-10-07):

- Item 2, calculated fields. New "Calculated fields" section giving the rule, inputs, null handling and as-of date for lifecycleStage, opening.*, capacity.{entries,asOf,current}, and the due diligence CapEx totals plus the twenty per-square-foot and per-student ratios. Rules were traced from the upstream code and spot-checked against live records (ratios reproduce exactly; capacity.current matches the latest-completed-phase rule, including the null and zero cases).

- Item 1, copied fields. Market, metro and region (copied from REBL3) and the school-calendar values (copied from a spreadsheet) are now labelled as copies, with how they are copied, that no copy time is returned, and where to read instead.

- Item 7, staff contacts. The five staff roles are labelled as copies whose record is xo-people, with what each source value means. DRIs, site POC, vendor team and guard contact are stated as Rhodes's own.

Known traps surfaced along the way and now stated: a site reads operating before it opens; the milestone9 token actually refers to the tenth milestone; an entry's start date does not gate capacity.current.

These fields are labelled, not removed: the service relays responses unchanged.

## Business Value

Agents were being handed computed numbers (capacity, cost per student, stage) with no way to check or rerun them, and copied values with nothing saying Rhodes is not their record. This closes three of the remaining gaps blocking stakeholder sign-off of the Rhodes DSS, leaving only the owner's ratification.

## Manual Effort Estimate

About 5 hours by hand (trace four computations through the upstream contracts code, trace three sync paths, verify on live records, write up). Proposed figure; Keval to confirm or adjust.

## Testing

- pnpm check passes (48 tests), including the test that every cited operation and field route is published.

- Live spot-checks described above.

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

## Business Value

Restore campus financial attribution across nine dedicated QuickBooks books. The immutable 2 October migration baseline contains 539 postings; fresh accepted captures contain 541 on 5 October and 542 on 6 October (Boca Raton 143 → 146). The initial repair recovered $270,595.89 of October Facilities spend and retained the separate -$9,900 La Jolla workshop credit. Source-coverage checks prevent missing dedicated-book activity or unresolved accounts from being published as false zeroes. The dated classifier repairs historical headcount source coverage without replacing current-quarter reports.

## Change

Add nine guarded exact realm/Class policies to the existing Finance School crosswalk, preserving its 25 previous rows. An independent nine-company reference proves required physical book coverage; it never assigns transactions. Facilities and Guide recognize the governed Finance route narrowly for those exact books and Schools, including Jamaica Plain. Credits, zero-valued postings and verified empty scopes retain their reporting semantics.

Facilities rejects unknown/NULL classification and unnumbered or renamed Expense accounts with unrelated categories unless exact current realm/account policy evidence proves an unrelated numbered GL. Such proof also preserves the contract’s deliberate Transportation (62500) and Renovation (62100) exclusions despite their broad Facilities category. Reconciliation activity is pinned to the selected Core, snapshot, snapshot publication timestamp and School-mapping generations.

New-object DDL has single canonical sources in pipelines/cdk/sql/core_education (100 reference, 101 historical classifier). Legacy runner paths are compatibility symlinks. The application tool preflights dependencies, locks the common financial mutex, applies reference/seed before dependent procedures in one atomic batch, then verifies catalog bodies and existing owners/ACLs. CDK does not execute SQL; explicit application remains part of deployment. Reader grants for the reference remain DBA-managed.

The classifier DATE overload reuses the existing sole writer, effective-date role rules, source reconciliation and atomic publication. Its existing no-argument signature delegates with the current quarter. Historical calls replace only the selected current eligible School scope, preserving other quarters and outside-scope classifications unless a posting is explicitly reassigned into the candidate. NULL, mid-quarter and future dates fail before writes. Historical attribution is a current governed School restatement, not reconstructed September-30 eligibility/model/roster provenance.

## 6 October review follow-up — 1aa97b47

Addressed the valid Mercy and Sanket feedback:

- Fail closed for unsupported Facilities-category GLs such as 62305; preserve the explicit 62100/62500 exclusions.

- Share guarded Finance-only School eligibility across the classifier, Guide completeness gates, report context and historical audit.

- Preserve existing procedure ownership and ACLs by omitting owner/grant resets for existing signatures before the atomic DDL batch.

- Reject NULL resolved-role policy/allocation values; reconcile the complete accepted XO role ledger count and every current candidate/title/observation identity.

- Prevent empty source input from erasing an existing quarter; explicitly flag empty or mixed-generation historical evidence and missing Facilities context.

- Use the migration's immutable dated capture and count all natural-key Class rows before checking the reviewed name. Explain the 539/541/542 snapshot totals.

Evidence-backed pushback:

- Posting lineage, realm and mapping flags and School mapping generations are enforced NOT NULL in source-controlled DDL and the live schema; the suggested NULL states cannot occur in this contract.

- Required-company coverage is not exclusive transaction attribution. Existing approved Class overrides must remain ahead of company defaults.

- XO invoices are retained across accepted rolling-window publications; latest-run-only identity joins would discard valid historical evidence. Recreated identities stay explicitly ambiguous.

Original review validation: 460 tests pass, with Ruff check/format limited to the seven modified Python files and clean whitespace checks. Eleven private Redshift cases pass, including full Q3 reconciliation of 7,097 postings / $12,159,140.88 with zero mismatches and no outside-quarter changes, a Finance-only -$2,596.16 Guide posting, expected empty-source and new-Facilities-account rejections, missing-context reporting, and exact preservation of an extra procedure ACL. Fixtures use temporary data copies and remove their private procedures.

## Authorized live acceptance — 6 October

Latest-candidate live acceptance is complete. The initial application preflight refused Redshift's no-argument proargtypes[0] = 0 sentinel before submitting any DDL. e0bcdac0 normalizes only that known empty-vector shape; 1214a0d3 adds exact post-batch signature-set verification and executable success/failure coverage for procedure presence, bodies, owners, ACLs, unexpected signatures and duplicate signatures. Current tests pass: 462 financial-mart tests + 107 Core tests = 569. Ruff checks/formatting were limited to the two Python files changed in this follow-up.

Atomic DDL application f2d6c20d-df29-4dac-a27d-4a5c38f146c8 completed and verified all four candidate bodies and unchanged owners/ACLs. Supported Core execution pr2124-candidate-20261006-125503 succeeded at 12:58:36.538 UTC in 212.451 seconds. Its automatic financial-mart run 58299e26-2660-4df6-a650-4ffc068d2968 succeeded at 13:00:58.546 UTC in 141.419 seconds.

An independently launched San Pedro raw expansion temporarily invalidated the accepted snapshot during final reconciliation. This task did not invoke or change that onboarding workflow. After its automatic Core/mart chain also succeeded (202.818s / 137.889s), final read-only acceptance passed against:

- Accepted snapshot 427d1b37-f2aa-4e30-ad65-4ff79a9b8f5a (69 companies / 566 Classes), with its immutable manifest SHA256 verified.

- Core posting generation ffe70b25-83bd-4b8b-a0ac-46dabf78d3f5:posting; financial-mart run c5029a5b-9286-4237-8f22-8f4042baf9bd succeeded at 13:10:26.121 UTC.

- Current School mapping 1f48f9d7-6990-4db1-a0c3-1e09f31aac00, matching postings.

All 542 dedicated-book postings have the expected School attribution. Facilities, Guide and Other Headcount have the same 59 Schools, with no duplicates, shape errors, missing required Schools, GL/total/per-student mismatches or sibling-lineage errors. All 59 source-readiness rows are ready. The 812 revenue and 406 Timeback comparisons have zero mismatches; both current-quarter HC postings reconcile to $3,277.00 with no identity, School, amount, status or source-lineage mismatch.

All nine required-company rows and all 34 Finance-policy rows match the pre-run capture exactly. Existing Q3 classification count (7,097), signed value ($12,159,140.88), and identity/School/status/Core-lineage checksum are unchanged. No new historical restatement was invoked; preservation does not claim a fresh Q3 restatement against the new Core generation. Final catalog bodies/owners/ACLs verify against the candidate source, and all relevant writers are idle. This task used one manual Core invocation, zero manual mart/raw invocations, and zero CloudFormation deployments.

Responses were posted in all 10 original review threads, which were resolved at the user's earlier explicit request. Mercy's two newer grouped threads remain open: deployment-verification coverage is addressed; NULL-measure and mixed-generation claims have contract-backed pushback in the [original thread](https://github.com/AI-Builder-Team/Surtr/pull/2124#discussion_r4195625940). Other new findings are not claimed resolved. Remaining blocker: source review, not live validation. This PR has not been merged.

## Earlier candidate validation

- Earlier 5 October candidate: 389 runner tests passed; Ruff check/format checks were limited to the six Python files changed in this session; whitespace checks pass.

- Ten private Redshift account-boundary cases passed, including reviewed Transportation/Renovation exclusions under the broad Facilities category. Applied candidate bodies and preserved owners/ACLs match the catalog.

- Supported Core and automatic financial-mart validation succeeded on 5 October. The classifier's normal current-quarter wrapper passed a second Core/automatic-mart run (202.686s / 150.176s). After resolving main conflicts and preserving reviewed GL exclusions, the final candidate passed a supported mart-only invocation in 103.591s, with fresh catalog, historical and current-contract acceptance.

- Reconciliation preserves all 541 captured business postings, all 34 Finance policies and all nine required-company rows. All three current QTD contracts have 59 Schools and no duplicate/shape/required-School, Facilities GL/total/per-student/lineage, revenue or 20% Timeback errors. TSA Anywhere Q3 revenue reconciles to the current snapshot at $3,432,478.77 (the 2 October snapshot was $3,590,009.03).

- Private dated-classifier tests reject invalid/future quarters and reconcile all 7,097 eligible Q3 postings. The monitored Q3 repair then reconciled the same $12,159,140.88 source population with zero posting/School/amount/lineage mismatches, while atomically asserting Q4 classification and all three current report tables unchanged. The final candidate repeats this proof; $7,099,589.89 is allocated and $5,059,550.99 remains explicitly ambiguous/unassigned role spend.

- The first Q3 acceptance wrapper failed on a reserved SQL alias and the whole batch rolled back; its corrected retry passed. An earlier catalog preflight failed on an unsupported metadata cast before DDL submission. No failed attempt is counted as successful validation.

The preceding results are the earlier 5 October evidence. Current live acceptance is recorded separately above; outstanding source review still means this PR is not merge-ready.

## Scope and remaining work

Aerie company-link changes are excluded. Greenwich, both Early Centers and Novatio still require separate canonical identities before Finance policies can reference them; generated warehouse dimensions are not manually populated. Novatio additionally needs a genuine company fallback for its no-Class fee activity. Historical unresolved roles remain quality outcomes; September-end modeled/per-student acceptance requires real historical mapping/model/roster inputs. Historical dated restatements are explicit maintenance calls, not a new schedule.

## Implementation Effort

Approximately 2–3 engineer days to investigate the source identities, implement guarded attribution/coverage and historical publication boundaries, provision and verify candidates, exercise meaningful failure cases, diagnose validation failures and reconcile live financial outputs; pipeline waiting is additional.

## Linear

[SURTR-1496](https://linear.app/builder-team/issue/SURTR-1496) — Finance QuickBooks → campus P&L escalation.

Hourly Rhodes publication can advance School mappings after QuickBooks Core publishes. Facilities then rejects financials that combine the new mappings with earlier postings. The financial runner now detects that mismatch, verifies producer inputs, rebuilds Core once, retries the complete financial chain, and checks stable posting/mapping lineage before reporting success.

The automatic financial child triggered by a recovery Core run waits for the owning financial execution and returns its verified publication. The state machine forwards its trusted execution ARN through the opt-in triggers.forward_execution_arn contract, preventing that child from becoming a second financial writer.

Readiness validates accepted raw state and the immutable manifest, company coverage, source freshness, governed policy, the Core source audit, and an idle producer. The XO boundary admits only published-ledger rows; excluded historical-cohort diagnostics remain informational. NULL/blank source slugs and missing cutover markers now fail closed. The matching Core contractor-attribution procedure includes the same slug guard.

Recovery is bounded to one attempt, with a 420-second Core observation limit and 240 seconds reserved for financials. A second mapping change, stale inputs, an active Core producer, or an unrelated integrity error remains a failure. The marts retain separate atomic publications.

## Business Value

Keeps Aerie school financials refreshing when an hourly ontology publication overlaps a QuickBooks import, retains accepted-source correctness checks, and prevents duplicate publication by the automatic recovery child.

## Implementation Effort

Approximately 10–14 engineer hours to trace the production race, implement bounded coordination and source checks, verify the review findings, add regression cases, deploy the isolated candidate, and validate the live warehouse outputs.

## Linear

https://linear.app/builder-team/issue/SURTR-1601/coordinate-aerie-financial-refresh-with-school-mapping-publications

## Validation

- 300 financial runner tests, 43 Core contract tests, and all five affected CDK tests passed. TypeScript checking, Ruff on modified Python files, and git diff --check passed. CI passed on the original validated candidate 0b0ef6fd; checks are rerunning for the cleaned branch. The 300 financial runner, 43 Core contract, and five affected CDK tests also passed again after the history rewrite.

- Read-only Redshift probes tested the actual readiness predicate against ten virtual source rows: eight invalid cases rejected, both permitted legacy cases allowed, and all ten rejected when the cutover marker was absent. Production source rows were not changed by these probes.

- Candidate 0b0ef6fd was deployed from the latest production base to only Pipeline-mart-aerie-education-financials-refresh-prod, using --exclusively and confirming [1/1]. CloudFormation and Lambda reached UPDATE_COMPLETE; deployed files match the candidate.

- Applied only the source-controlled CREATE OR REPLACE PROCEDURE core_education.sp_refresh_expense_contractor_attribution(VARCHAR, VARCHAR) guard update. The existing deployed body matched the prior canonical source; the replacement adds only the NULL/blank-slug predicate. Owner, security mode, and signature were catalog-verified unchanged. No Core stack or other pipeline stack was deployed.

- Pre-merge live run validate-null-slug-20261006-154015 succeeded at 9:13 PM IST on 6 October 2026. Core run 097372f2-4366-40b0-b0c3-803f1cfa2702 published 353,459 postings from the accepted 75-company snapshot 90e9136f-a3b8-421f-804c-eac5dbd22718. Automatic financial run c5d04724-99c3-475a-9cf7-5dc44d0c7340 succeeded at 9:15 PM; all three School Performance refreshes succeeded.

- Financials published 17,013 P&L rows, 232,933 detail rows, 57,641 unit economics rows, 4,543 Guide rows, 4,484 All Other Headcount rows, and 10,384 Facilities rows. Independent warehouse verification confirmed fresh QTD publications, one shared Core/raw/FinalSite lineage, and zero violations across all seven integrity checks.

- Earlier live validation validate-mapping-recovery-20261006-145711 exercised the actual mapping mismatch: exactly one recovery Core rebuild, successful full-chain retry, and verified automatic-child coalescing. That orchestration is unchanged by the subsequent SQL guard repair.

## Review findings

The initial missing-environment and excluded-legacy-row findings were withdrawn after CDK/live configuration and accepted-source evidence. Regression tests now cover both contracts. The valid NULL-cohort finding was fixed in 0b0ef6fd, deployed, and live-validated; the original threads have evidence-backed replies and are resolved at the user's request.

## Branch scope

The PR now contains one commit, c48b5d83, directly on current main (3f67679a). It carries only this financial recovery change across 15 files. All 15 file blobs and the complete patch are byte-identical to the candidate 0b0ef6fd that was deployed and live-validated above. The rewrite removes unrelated production ancestry and preserves the later Ramp fix already on main.

## Summary

This PR is Phase 4 of 13 in the larger [Human Task Assignment from Aerie](https://linear.app/builder-team/project/human-task-assignment-from-aerie-b3582376ae6e) project.

It adds and gates one canonical Task create/edit flow shared by My Tasks, a top-level site action, the existing Work Plan, and the evolving public Task API. This phase is tracked by [AERIE-2736 — Create and edit canonical Tasks from every entry point](https://linear.app/builder-team/issue/AERIE-2736/create-and-edit-canonical-tasks-from-every-entry-point).

Production effect: dormant/additive. The new Task UI, anchorless writes, expanded API contract, and agent discovery are blocked by the default-off server gate. The dedicated Task capability becomes visible in capability administration, but no existing role receives it until the explicit reviewed migration is run. Current Task creation also records requester as the authenticated creator when no requester is supplied; that internal foundation field is not exposed through the current off-gate UI or API response. Existing Work Plan and public Task API behavior remain available while the gate is off.

## Why

Every entry point must create the same Task rather than introducing separate UI, API, and agent meanings. This slice establishes that shared write boundary, permits site-level Tasks without inventing Work Plan anchors, and gives Task management its own permission before assignments and lifecycle actions are added.

## Business Value

- Lets authorized people and their agents use one Task model from every entry point once launched.

- Supports site-level work that does not belong to a Quality Bar, Work Unit Group, or Work Unit.

- Keeps the familiar compact Work Plan flow while making richer fields available when needed.

- Adds a dedicated Task permission without widening diligence, DRI, Work Unit, or Work Unit Group authority.

- Preserves current production behavior until the complete Task Board is ready.

## How does it work

1. The shared Task writer accepts an optional Work Plan anchor while preserving the existing anchored payload.

2. Authenticated creation derives the creator from the current user or API credential owner; requester defaults to that creator and may be changed.

3. Gated My Tasks, site, and Work Plan forms all call the same canonical create/edit mutations.

4. The existing public Task endpoints widen in place behind the gate, retaining public IDs, idempotency, ETags, audit attribution, and current off-gate behavior.

5. operations.tasks.write is registered across capability presentation and API-key scope checks; a dry-run/confirmed migration can grant it to approved roles later.

6. Agent discovery uses that Task capability and remains hidden while the launch gate is off.

## Scope

### Included in this phase

- Site-level Tasks with optional Work Plan anchors across storage, projection, reads, writes, and verification.

- Reusable gated Task editor in My Tasks and as a top-level site action.

- Compact existing Work Plan creation with an optional expanded Task section.

- Actor-derived creator and requester defaulting.

- Dedicated operations.tasks.write capability, role migration, API metadata, and credential-owner checks.

- One gated evolving public Task API with existing ID, retry, concurrency, and audit behavior preserved.

- Separate gated agent discovery for Tasks.

- Exact final diff paths:

chat/app/(main)/admin/__tests__/role-editor.test.tsx
chat/components/dashboards/portfolio/__tests__/portfolio-rhodes-workbench.test.tsx
chat/components/dashboards/portfolio/portfolio-rhodes-workbench.tsx
chat/components/task-board/my-tasks-view.tsx
chat/components/task-board/task-editor.test.tsx
chat/components/task-board/task-editor.tsx
chat/convex/_generated/api.d.ts
chat/convex/migrations/taskWriteCapability.test.ts
chat/convex/migrations/taskWriteCapability.ts
chat/convex/migrations/workManagementPublicIds.ts
chat/convex/publicApi/v2/domains/workManagementTaskBoardWrites.test.ts
chat/convex/publicApi/v2/workManagement.test.ts
chat/convex/publicApi/v2/workManagementData.ts
chat/convex/publicApi/v2/workManagementWrites.ts
chat/convex/rhodes/portfolioWorkbench.ts
chat/convex/rhodes/runtime/writes/taskWrites.ts
chat/convex/rhodes/workManagementPublicId.ts
chat/convex/rhodesPortfolioWorkbench.test.ts
chat/convex/taskBoard/gate.ts
chat/convex/taskBoard/mutations.test.ts
chat/convex/taskBoard/mutations.ts
chat/convex/taskBoard/queries.test.ts
chat/convex/taskBoard/queries.ts
chat/convex/users/roles.test.ts
chat/convex/users/roles.ts
chat/lib/public-api/v2/domains/work-management-schemas.ts
chat/lib/public-api/v2/domains/work-management-task-board.node.test.ts
chat/lib/public-api/v2/domains/work-management.ts
chat/lib/task-board/gate.ts
packages/contracts/src/capabilities.test.ts
packages/contracts/src/capabilities.ts

### Deliberately excluded for later phases

- Enabling the Task Board or running the role-grant migration in production.

- Internal and external assignment management — AERIE-2737.

- Lifecycle actions and transition enforcement — AERIE-2738.

- Completion submissions, evidence, approvals, watchers, notifications, Team Tasks, digests, and final DSS launch.

- Any second or legacy Task API.

## Test plan

### Automated validation

- Current-head Task Board, public API, Work Plan, migration, role, and component tests — 12 files, 272/272 passed (cd chat && pnpm exec vitest run lib/public-api/v2/domains/work-management-task-board.node.test.ts convex/taskBoard/mutations.test.ts convex/taskBoard/queries.test.ts convex/publicApi/v2/domains/workManagementTaskBoardWrites.test.ts convex/publicApi/v2/workManagement.test.ts convex/rhodesPortfolioWorkbench.test.ts convex/migrations/taskWriteCapability.test.ts convex/users/roles.test.ts components/dashboards/portfolio/__tests__/portfolio-rhodes-workbench.test.tsx components/task-board/task-editor.test.tsx components/task-board/task-detail.test.tsx app/'(main)'/admin/__tests__/role-editor.test.tsx).

- Overlapping existing public write and Rhodes MCP validation — 2 files, 102/102 passed (cd chat && pnpm exec vitest run convex/publicApi/v2/domains/workManagementWrites.test.ts convex/rhodesMcpMutationParity.test.ts).

- Capability contract validation — 1 file, 49/49 passed (cd chat && pnpm --filter @bran/contracts exec vitest run src/capabilities.test.ts).

- Independent current-head review — 195/195 focused tests passed, with no findings.

- Chat and Convex typecheck — passed, then passed again in the final commit hook (pnpm --filter @bran/chat typecheck).

- Full lint, Biome, architecture boundaries, Convex paths, read bounds, test architecture, and knowledge hygiene — passed across 3,081 files with two pre-existing Sindri warnings (pnpm lint).

- git diff --check — passed.

- Exact-head diff scope — only the 31 authorized paths listed above.

No current production caller can reach the richer flow while the gate is off. /tasks returns Not Found; Work Plan renders the expanded editor only after an authenticated server availability query returns enabled; both new mutations independently enforce the server gate; the public API and agent catalog branch on the same gate; and the shared writer rejects anchorless creation while disabled.

### Time for Implementation

About 3 weeks for an engineer without AI assistance, including repository investigation, UI and API implementation, authorization work, migration design, compatibility testing, review, and validation.

## What it means for end users/consumers

| Area | What changes when this deploys | What does not change yet |

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

| Existing Work Plan users | No visible change while the Task Board gate is off. Current compact Task creation and payloads keep working. | The optional expanded Task fields stay hidden until launch. |

| My Tasks and site pages | The shared create/edit components are installed behind the server gate. | Users cannot reach or call the new creation flow yet. |

| Site-level Tasks | Storage and shared code can represent a Task attached only to a site. | No production user can create an anchorless Task while the gate is off. |

| Public Task API | The same endpoints are prepared to accept the richer canonical Task shape when enabled. | Current callers keep the existing off-gate contract; there is no second API. |

| Permissions | A dedicated Task write capability becomes visible in capability administration. | Existing roles do not receive it automatically; the migration is explicit and dormant. |

| Agents | Task-specific discovery and credential-owner authorization are prepared. | Agents do not see or use the new Task workflow before launch. |

| Existing Tasks | Their IDs, status, anchors, assignments, and current behavior remain unchanged. New Tasks created through current flows record requester as the authenticated creator internally. | This PR does not rewrite existing Tasks, expose requester through the current API response, or run a data backfill or lifecycle migration. |

## Review repairs and contract clarifications

[First Mercy review](https://github.com/AI-Builder-Team/Aerie/pull/1698#pullrequestreview-5436802465) and [second Mercy review](https://github.com/AI-Builder-Team/Aerie/pull/1698#pullrequestreview-5436936808), tracked under [AERIE-2736](https://linear.app/builder-team/issue/AERIE-2736/create-and-edit-canonical-tasks-from-every-entry-point):

- listAssignableUsers applies the same operations.tasks.write boundary as the creation-site query, so an authenticated participant without Task management authority cannot enumerate the assignable staff directory.

- Public Task projection budgets unique referenced user identities across assignees, approvers, approved-by, creator, and requester. Repeated identities share the existing cache and no longer cause valid pages to be rejected as over budget.

- Work Plan keeps its existing site-edit authorization for the unchanged compact Task payload. Supplying the new gated requester field additionally requires operations.tasks.write; server-projected availability hides the requester control and skips its directory query when that capability is absent.

- Requester updates now distinguish omission from an explicit clear across the standalone editor, Work Plan, and public API. Omission preserves the current requester; clearing resets it to the Task's stored creator; create omission continues to default requester to the authenticated creator. The UI now describes the reset accurately.

- Negative coverage now includes the disabled gate, missing Task-write capability, invalid or deleted requesters, completed Task edits, Work Plan requester authorization, hidden requester controls, stored-creator reset, and nullable public API PATCH.

- The claimed off-gate My Tasks creation flow is unreachable: MyTasksView is imported only by /tasks, and that server page returns Not Found before rendering when the gate is disabled.

- Missing creator or requester directory rows are not silently omitted: projectTask returns null, and both list and detail callers convert that result to integrity_error.

Validation: 147/147 focused repair tests, 272/272 current-head feature tests, 102/102 overlapping public-write and Rhodes MCP tests, 49/49 capability contract tests, Chat/Convex typecheck, full lint/boundary checks, and git diff --check all pass. Existing compact Work Plan authorization, the launch gate, dormant production state, public API activation boundary, role migration, and Task ownership rules remain unchanged.

### Third review repair

The latest review identified that default-role seeding still included operations.tasks.write even though this phase reserves every production grant for the explicit reviewed migration. The grant is now absent from both default seeding and the generic capability backfill; migrations/taskWriteCapability is the sole initial grant path and still requires its execute flag and confirmation token. Regression coverage proves both dormant paths remain grant-free.

The gate-off anchor validation now uses the shared clean user-error pathway. The full 12-file feature suite remains green at 272/272, and Chat/Convex typecheck, focused Biome checks, and git diff --check pass.

### Fourth review clarification

The latest requester-edit finding is rejected because it conflicts with the approved Task authority model. FEATURE.md grants creators and requesters authority to update, assign, and reassign their own Tasks without operations.tasks.write; that capability governs global Task management. The standalone mutation preserves that distinction: it requires the caller to be the stored creator or requester, rejects closed Tasks, and validates every replacement requester as an assignable Aerie user. Unrelated users still cannot edit the Task, and the operation does not grant site-wide access.

No code change is warranted for this finding. Exact head f41e51e3a remains fully green across all required CI checks.

### Fifth review repair

The claimed option-query gate bypass was already prevented by the shared boundary: both listCreationSites and listAssignableUsers begin with requireTaskBoardUser, which calls taskBoardEnabled() and fails with the clean unavailable error before capability checks or database reads. Explicit gate-off regression assertions now lock that inherited behavior for both queries.

Public API regression coverage now proves the required capability intersection in both directions: a scoped key is denied when its owner lacks operations.tasks.write, and a capable owner is denied when the key omits that scope. The full feature suite passes 272/272, with Chat/Convex typecheck, focused Biome checks, and git diff --check also green.

### Sixth review repair

The reusable editor now initializes draft state only when the dialog opens or its Task/fixed-site identity changes. Fresh object allocation by a parent rerender no longer retriggers initialization, so live query updates and unrelated parent state changes cannot erase in-progress user input. A browser regression test recreates the same Task prop after typing and proves the unsaved title remains intact.

Validation is green at 272/272 feature tests, plus Chat/Convex typecheck, focused Biome checks, and git diff --check.

### Seventh review repair

The shared Task writer now treats a missing record immediately after create or update as a clean operation failure, so its success contract is non-null. Standalone mutations return the persisted Task ID directly and can no longer translate a nullable writer result into a successful response with taskId: undefined. Public API and Work Plan callers inherit the same fail-closed shared boundary.

Validation is green at 272/272 feature tests, including 71/71 focused mutation, public API, and Rhodes tests, plus Chat/Convex typecheck, focused Biome checks, and git diff --check.

Linear: AI-979

## What changed

Four fixes from Arthur Michel's review of the Rhodes DSS against the latest BrainLift (Ops Automation Trilogy, 2026-10-07):

- Item 5, key contradiction. The docs said every key has the same access, but the served contract still carried upstream's per-key sentences (Requires ... on all 44 operations, and "Access Contact is included only when the API key has ..." on the security read). Checked on the live service: every Rhodes key receives the access contact. The contract builder now drops those sentences, and Enablement says so explicitly.

- Item 9, slug. site.slug is now defined as the site's REBL3 site ID (copied from REBL3, the key Rhodes uses to read market/metro/region), with the historical-slug trap stated, instead of "address-derived".

- Item 10, site ID. site.id now states its genesis: created by Rhodes when the site record is created, immutable, not issued by REBL3 or the staff directory.

- Item 4, corrections. Enablement now says where a wrong value gets fixed: in Rhodes, by Edu Ops, routed to the site's DRI, and filed here as a report so it is tracked.

Contract version 0.3.0 → 0.3.1. No route, auth or dispatch change.

Registration on the DSS registry (item 6) was done separately as a register call (intake 1796); it needs no code.

## Business Value

Rhodes is the site database of record that Ops agents are being pointed at. These were the places where the published meaning was wrong or self-contradictory: an agent reading the contract would conclude some keys cannot see the access contact, and one reading the dictionary would treat the REBL3 join key as a changeable label. Fixing them removes four of the ten gaps blocking stakeholder sign-off of the Rhodes DSS.

## Manual Effort Estimate

About 2 hours by hand (trace slug and site-ID origin in the upstream code, verify key access on the live service, edit and test). Proposed figure; Keval to confirm or adjust.

## Testing

- pnpm check (lint, types, 48 tests) passes.

- New assertions: the served contract contains no per-key requirement or scope sentences and no capability names, and does contain the uniform access-contact sentence.

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

## Summary

This PR is Phase 3 of 13 in the larger [Human Task Assignment from Aerie](https://linear.app/builder-team/project/human-task-assignment-from-aerie-b3582376ae6e) project.

It adds and gates the indexed participation model, My Tasks read surface, and reusable Task detail needed by later Task Board phases. This phase is tracked by [AERIE-2734 — Add the gated My Tasks foundation and reusable Task details](https://linear.app/builder-team/issue/AERIE-2734/add-the-gated-my-tasks-foundation-and-reusable-task-details).

Production effect: dormant/additive. The new Task Board route and queries are blocked by a default-off server gate. Existing Task writes begin maintaining internal participant rows, but the existing Work Plan, public Task API, and DSS keep their current behavior. Reconciliation of existing Tasks is available but does not run automatically.

## Why

My Tasks needs fast, relationship-based access without searching every Task or granting wider site access. This slice establishes that safe read model and keeps it synchronized before later phases add new creation, lifecycle, notification, and agent workflows.

## Business Value

- Gives every authenticated user a private My Tasks view once the Task Board is launched.

- Lets Task participants open a Task without receiving broader access to its site.

- Keeps creator, requester, assignee, approver, and watcher relationships fast to query.

- Preserves the current Work Plan and public Task behavior while the new experience remains hidden.

## How does it work

1. Current Task create, update, replace, and delete paths reconcile deterministic participant rows in the same mutation.

2. The gated My Tasks query reads those indexed relationships, applies bounded filters, and returns stable pagination plus independent site choices.

3. The gated detail query checks participation before returning the Task, known placement and lifecycle times, and activity.

4. Internal reconciliation and verification functions can backfill existing Tasks in bounded batches and detect missing, stale, or duplicate rows.

5. The server-authoritative gate remains off by default, so direct navigation or API calls cannot expose the new Task Board yet.

## Scope

### Included in this phase

- Default-off server gate for the Task Board.

- Indexed Task participant relationships for creator, requester, internal assignee, eligible approver, and watcher.

- Atomic projection maintenance in current runtime and Rhodes CRUD Task writers.

- Bounded, dormant reconciliation and terminal verification tooling.

- Gated My Tasks filters, pagination, relationship badges, and site choices.

- Participant-only reusable Task detail view with legacy Not recorded handling.

- Exact final diff paths:

chat/app/(main)/tasks/page.tsx
chat/components/task-board/my-tasks-view.tsx
chat/components/task-board/task-detail.test.tsx
chat/components/task-board/task-detail.tsx
chat/convex/_generated/api.d.ts
chat/convex/migrations/taskParticipants.test.ts
chat/convex/migrations/taskParticipants.ts
chat/convex/rhodes/crud.ts
chat/convex/rhodes/runtime/writes/taskWrites.ts
chat/convex/rhodes/schema.ts
chat/convex/rhodesSchema.test.ts
chat/convex/taskBoard/gate.ts
chat/convex/taskBoard/participants.ts
chat/convex/taskBoard/queries.test.ts
chat/convex/taskBoard/queries.ts

### Deliberately excluded for later phases

- Enabling the Task Board in production or removing the launch gate.

- New Task creation and editing fields.

- Lifecycle actions, completion submissions, evidence, approval actions, notifications, digests, and agent guidance.

- Running the participant reconciliation against production data.

- Changes to the current public Task API, OpenAPI contract, Work Plan UI, or DSS.

## Test plan

### Automated validation

- Current-head focused Task Board, participant migration, and detail component tests — 3 files, 11/11 passed (pnpm --dir chat exec vitest run convex/migrations/taskParticipants.test.ts convex/taskBoard/queries.test.ts components/task-board/task-detail.test.tsx).

- Current-head overlapping Task API, schema, and Rhodes suites — 5 files, 49/49 passed (pnpm --dir chat exec vitest run convex/rhodesCoreCrud.test.ts convex/rhodesDualWrite.test.ts convex/migrations/taskLifecycleContract.test.ts convex/publicApi/v2/domains/workManagementWrites.test.ts convex/rhodesSchema.test.ts).

- Independent current-head review — 19/19 focused tests passed, with no findings.

- Full Chat suite on the initial implementation commit before the three reviewed repairs — 785 files passed; 11,896 passed and 18 skipped (pnpm test). The repaired head is covered by the focused, overlapping, typecheck, and lint runs above and below.

- Workspace and Convex typecheck — passed (pnpm typecheck).

- Lint, Biome, architecture boundaries, Convex paths, read-bound checks, and test architecture — passed with two pre-existing Sindri warnings (pnpm lint).

- Repair-path Biome check — 7 files checked with no errors (pnpm exec biome check chat/components/task-board/my-tasks-view.tsx chat/components/task-board/task-detail.test.tsx chat/components/task-board/task-detail.tsx chat/convex/migrations/taskParticipants.test.ts chat/convex/migrations/taskParticipants.ts chat/convex/taskBoard/queries.test.ts chat/convex/taskBoard/queries.ts).

- git diff --check — passed.

- Exact-head diff scope — only the 15 authorized paths listed above.

Nothing links to or calls the new Task Board in the current product. MyTasksView is imported only by the new direct /tasks page, and its three queries are called only by that view and their tests. The route checks AERIE_TASK_BOARD_ENABLED === "true" on the server and returns Not Found otherwise. Each backend query also checks the same gate after authentication. No navigation item, public Task API route, DSS surface, notification, or digest caller was added.

### Time for Implementation

About 2 weeks for an engineer without AI assistance, including repository investigation, implementation, boundary tests, review repairs, and validation.

## What it means for end users/consumers

| Area | What changes when this deploys | What does not change yet |

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

| Existing Work Plan users | No visible change. Existing Task creation and editing continue to work. | The richer Task Board creation and lifecycle controls are not available. |

| My Tasks | The route and backend are installed but blocked by the default-off server gate. | Users cannot open or call My Tasks until the final launch phase. |

| Task data | New and updated Tasks also maintain internal rows describing who participates in them. | Task titles, statuses, assignments, and current public responses do not change. |

| Existing Tasks | Safe bounded tools exist to prepare and verify participant rows later. | No automatic backfill or production migration runs on deploy. |

| Site access | The new detail query is designed to show a Task to its participants without widening their site access. | Existing site and portfolio permissions remain unchanged. |

| APIs and agents | No current public API, OpenAPI, MCP, or DSS behavior changes. | Agents cannot use the new Task Board workflow until later gated phases ship. |

## Review repairs and contract clarifications

Review [4201911189](https://github.com/AI-Builder-Team/Aerie/pull/1697#discussion_r4201911189) was classified under [AERIE-2734](https://linear.app/builder-team/issue/AERIE-2734/add-the-gated-my-tasks-foundation-and-reusable-task-details) at head 60b48535e8c376c5a34043e5696baa2108c0e5e6.

- Accepted: current Task creation had an authoritative actorUserId but did not persist it as creator, so a creator who was not an assignee could be absent from My Tasks. createTask now stores the actor as the canonical creator before the same transaction reconciles participant rows. The regression proves creator participation survives reassignment and that the creator can retrieve the Task through My Tasks.

- Rejected as a blocker: orphaned participant joins remain omitted from user results. The gate stays off until bounded reconciliation and terminal verification report a complete projection, and current Task create, update, replace, and delete paths maintain rows atomically. A deleted Task has no Task result to return; making one stale row fail the complete My Tasks or site-options query would reduce availability without strengthening the canonical write boundary.

- Clean-error alignment: expected participant-limit and projection-inconsistency failures now use userError(...); raw internal details are not exposed to the client.

- Unchanged boundaries: no requester defaults, lifecycle behavior, capability expansion, public API shape, gate activation, automatic reconciliation, deployment traffic, or migration execution was added.

- Repair validation: focused red → green Task Board suite 7/7; overlapping Task Board, participant migration, public Task writes, Rhodes CRUD, and Rhodes dual-write suites 43/43; workspace and Convex typecheck passed; lint, boundaries, Convex paths, read bounds, test architecture, Biome, and git diff --check passed. Lint retains the two pre-existing Sindri warnings already recorded above.

## Summary

- Capture direct contact details for each listed campus/contact/school-year, validating response identity and separately reconciling scoped requests.

- Preserve the default detail stream and existing billing, finance, and Person reader behavior.

- Extend the daily-full window by resuming hourly deltas at 07:15 UTC.

## Why

A contact can belong to multiple school years with different balances, grades, payment plans, workflow states, contract dates, and checklist answers. Surtr currently combines year-specific listings into one contact set and fetches detail without a year parameter. Live controlled GETs confirmed that the default can return next-year details while explicitly passing the current-year ID returns the current-year position. A current-year reader consequently retains stale historical detail even when membership remains active.

## Business Value

Year-specific consumers can read fresh billing and enrollment details without borrowing another year's state. Existing default-position consumers retain their contract.

## Test plan

- [x] 480 affected tests pass: capture 165, billing 31, finance 238, Person 46.

- [x] Repository-wide Ruff check and format pass with CI-pinned 0.15.22.

- [x] Regression coverage: distinct multi-year payloads, full/delta scope, wrong-year failure, unavailable lookup bookkeeping, manifest integrity, and single appointment expansion.

- [x] Mercy approved candidate 34a9da22541283ab367a982c2a03e569dd6cc2bd with no findings; all CI checks passed.

- [x] Approved candidate validated in isolated Redshift: Plano full (55 memberships), normal delta (empty), and an explicit August-to-now delta (48 memberships); all 188 detail payloads match immutable API evidence. Scope/year checks, nine-ledger row reconciliation, conversion flags, default-reader compatibility, actual billing selection SQL and completed-run reconciliation pass.

- [ ] Estate-wide runtime and production consumer procedure rollout/execution remain acceptance gates; production backfill and merge are pending.

Production data and consumer procedures are unchanged. Candidate staging DDL and capture/publication were exercised in an isolated validation schema; production consumer procedures have not been applied or executed. The hourly delta trigger was briefly paused during validation (one slot skipped) and restored to its original enabled state and expression. The additional 4,721 membership requests in the sampled full-run scope imply roughly 63 minutes of pacing overhead; fresh-run coverage and duration remain acceptance gates. A fresh scoped full populates current observations and does not reconstruct historical point-in-time balances.

## Summary

- Track labeled additional acquisitions and lease documents within a main Site's Property Acquisition card.

- Add a privileged Site-header actions menu and conversion dialog that hides a misclassified standalone Site, moves its documents, and records the former identity and destination in audit history.

- Expose acquisitions in Site/API/MCP reads and protect converted records from source reimports and primary-lease reconciliation.

## Why

Real Estate handoffs can create standalone Sites for separately leased fields, play areas, or pickup spaces. Those properties belong to an existing school and need their own lease tracking without Site milestones, capacity, or Buildout.

Closes [AERIE-2727](https://linear.app/builder-team/issue/AERIE-2727/add-additional-acquisitions-and-convert-misclassified-sites).

## Business Value

Staff can track and renew supplemental leases from the main Site while removing confusing duplicate Sites. Conversion preserves document IDs and a private source snapshot, archives unused default work, and leaves a clear audit trail. Costs remain on the main Site.

## Breaking changes

The property-acquisition GET and PATCH endpoints now also require operations.portfolio.read in the API key scope and the owner's effective grants. Existing acquisition clients lacking that grant must update their keys/roles.

## Test plan

- [x] Local walkthrough using synthetic Sites: add/edit/reload, lease lookup, header conversion dialog, stable document identity, source hiding, audit/archive retention, and redirect.

- [x] Rebased onto main 53296a072; reconciled primary-document filtering with supplemental evidence exclusions and bounded compound-index reads.

- [x] 402 tests passed across reconciliation, document processing/discovery, acquisition CRUD/rollback, conversion, API scope/owner authorization, document loader failures, pagination, and API/agent-context contracts. Error-capture inventory also passed.

- [x] Chat/backend typechecks and repository lint passed (two existing lint warnings).

- [x] Full sync suite: 2,902 tests passed in 81 seconds. Keep one worker and yield to Node I/O between tests so CPU-heavy gateway fixtures cannot starve Vitest result acknowledgements; assertions, error handling, and timeouts remain unchanged.

- [x] 66 focused tests for conversion cleanup/rollback, source import contracts, real mirror document redirects, provider-free rendering, reconciliation, CRUD, and due-diligence scenarios.

- [x] Full CI on final head ce20222bd: all builds, typechecks, lint, and tests passed, including 11,907 Chat tests and 2,902 sync tests.

- [x] Mercy approved final head ce20222bd; prior provider, deleted-ID, ontology cleanup, scenario ownership, snapshot, and normalizer concerns are resolved or withdrawn.

- Local steps and rollout constraints: [docs/additional-acquisitions.md](https://github.com/AI-Builder-Team/Aerie/blob/ce20222bd5ba3c70c49e390837bdfb86e6fb65f4/docs/additional-acquisitions.md).

## Review disposition

- Converted Site create/upsert rejects through userError; mirror suppression explicitly acknowledges a no-op and returns no deleted Site ID. Tombstone identity lookups trim surrounding whitespace.

- Conversion blocks both active and archived due-diligence scenarios. Ontology cleanup deletes a complete bounded set or rolls the entire conversion back on overflow. Regression tests cover three identities, 201 identities, and scenario creation after preview.

- A test with real installed Convex hooks mounts both acquisition wrappers without a provider and confirms empty UI without a crash; useConvex() returns context and does not throw in this version.

- Real mirror-endpoint regressions prove existing and newly imported converted-source documents retain main-Site ownership, provenance, and supplemental classification. Generic document suppression would discard valid lease refreshes.

- Reconciliation rejects an in-flight proposal if any expected document becomes supplemental; it never silently drops source facts. publicOperationsSite has no historical snapshot argument: its local asOf is today's capacity date.

- Former slugs remain reserved by tombstones; ordinary create/upsert/import paths reject reuse. Terminal approval/audit history stays keyed to the archived former identity, while the main conversion audit records the destination. Empty document pages retain a Load more action and cursor; the remaining presentation note is nonblocking.

- GET/PATCH portfolio grants, shared lease references, clean document-loader fallback, and empty-page pagination remain covered. [Convex equality with undefined includes omitted optional fields](https://docs.convex.dev/database/types#working-with-undefined), including legacy primary documents.

Conversion refuses Sites with operational dependencies or active automation. It requires an explicit operations.siteAcquisitions.convert grant. Automated review findings on manual lease reassignment, GET/PATCH response parity, primary-only reconciliation limits, MCP portfolio permission gates, and explicit missing-Site states are covered by regression tests. Source suppression uses former slug/legacy identity only; shared addresses never suppress another Site. That import collision and rollback after an earlier document move have focused coverage. No production examples have been converted, and no REBL3/Rhodes writeback was triggered. Development Super Admin conversion capability was explicitly approved and left enabled. Walkthrough fixes distinguish canonical unused P2 templates from active work, separate deployment approval scan bounds from per-Site bounds, and keep converted-source subscriptions stable during redirect.


[Open the walkthrough screenshot in GitHub](https://github.com/AI-Builder-Team/Aerie/blob/ce20222bd5ba3c70c49e390837bdfb86e6fb65f4/docs/images/additional-acquisitions-walkthrough.jpg).

## Summary

- Reconcile merge survivors fetched by multiple CRM workers through one immutable canonical source read.

- Reuse that response on retries and replay while retaining worker evidence and exact alias accounting.

- Run heavy assembly with the existing quota-limited extraction role, preserving separate warehouse publication permissions.

## Why

Production CRM run 4f989f55-6efd-42f3-a612-276008fb4182 failed when two workers read the same merged contact before and after HubSpot recalculated its analytics. Both reads were valid, but the finalizer required identical survivor payloads, so assembly failed before any CRM resource could publish.

The shared exact-ID read resolves this race. Missing or archived survivors, changed identity, lost alias evidence, and unsuccessful reads still fail before publication. Unresolved conflicts without canonical evidence remain failures.

## Business Value

Legitimate contact merges and concurrent source updates can complete the CRM refresh without sacrificing data integrity or replayability.

## Test plan

- [x] HubSpot runner suite: 268 tests passing, including changed survivor versions, canonical-read reuse, replay, fragment ordering, missing survivors, changed identity, and lost aliases.

- [x] Ruff 0.15.22 lint and format checks for the HubSpot runner.

- [x] TypeScript build and all seven required repository CI checks.

- [x] Full pipeline CDK CI suite: 923 tests passing across all 19 suites, including Docker bundling tests.

- [ ] After merge, deploy the runner image and Step Functions task selection together, then verify a fresh CRM run and its publication ledger. No production deployment or rerun performed by this PR.

## Summary

This PR is the lifecycle-contract foundation for the larger [Human Task Assignment from Aerie](https://linear.app/builder-team/project/human-task-assignment-from-aerie-b3582376ae6e) project.

It adds the internal Task status and migration foundation needed by later Task Board slices, without turning on the Task Board or changing the current public Task API. This phase is tracked by [AERIE-2751 — Establish the canonical Task lifecycle contract](https://linear.app/builder-team/issue/AERIE-2751/establish-the-canonical-task-lifecycle-contract).

Production effect: dormant/additive. Aerie can safely store and read the future awaitingApproval status and optional requiresApproval field, but no current screen, API, agent or workflow can create them. Merging this PR does not run the migration or start a backfill.

## Why

The later Task Board work needs one agreed meaning for every Task status before new creation, completion and approval workflows are added. This slice establishes that foundation first, so later PRs do not invent competing meanings or reinterpret existing completed Tasks.

It also adds a guarded migration that can inspect legacy Tasks later without guessing about approval history. That migration remains inactive until the final launch work explicitly runs it.

## Business Value

- Gives every later Task Board slice one stable lifecycle contract to build against.

- Keeps existing Tasks and current Task-writing workflows working as they do today.

- Prevents old approver lists from silently reopening completed Tasks.

- Makes unsafe or contradictory approval data visible before any future migration proceeds.

- Avoids exposing unfinished Task Board behavior through the public API or agent tools.

## How does it work

1. @bran/contracts/task-state recognizes seven internal statuses: new, inProgress, delayed, escalatedBlocked, awaitingApproval, completed and rejected.

2. Shared readers treat only completed and rejected as closed. Approval waiting is represented only by the explicit awaitingApproval status, not inferred from an approver list.

3. Task storage accepts an optional internal requiresApproval field and the future lifecycle timestamps, while current public request, response and write validators remain on the existing contract.

4. The dormant migration scans Tasks in bounded batches, reports approval-data conflicts and can backfill only records it can interpret safely. It does not invent approval, submission or timestamp history.

5. The migration requires explicit confirmation and is not called by any current production workflow. Public OpenAPI, DSS, MCP and Work Plan creation remain unchanged.

## Scope

### Included in this phase

- The seven-value internal Task status contract.

- Optional internal lifecycle storage fields required by later slices.

- Shared read behavior where explicit awaitingApproval is open and completed is closed.

- Dormant, bounded and idempotent migration preflight, backfill and verification tools.

- Conflict detection for contradictory or incomplete approval data.

- The approved Task Board FEATURE.md decisions used by the remaining delivery tickets.

- Exact final diff paths:

chat/components/dashboards/school-ops/__tests__/site-detail-panel.test.tsx
chat/components/dashboards/school-ops/site-detail-panel.tsx
chat/components/rhodes-cards/rhodes-read-card.tsx
chat/convex/_generated/api.d.ts
chat/convex/migrations/taskLifecycleContract.test.ts
chat/convex/migrations/taskLifecycleContract.ts
chat/convex/publicApi/v2/workManagementData.ts
chat/convex/publicApi/v2/workManagementWrites.ts
chat/convex/rhodes/dashboard.ts
chat/convex/rhodes/portfolioWorkbench.ts
chat/convex/rhodes/runtime/siteReadModels.ts
chat/convex/rhodes/schema.ts
chat/convex/rhodesMcpParity.test.ts
chat/lib/__tests__/operating-sites.node.test.ts
chat/lib/__tests__/quality-bar-ai-summary.node.test.ts
chat/lib/operating-sites-contract.ts
chat/lib/operating-sites.ts
chat/lib/public-api/v2/domains/work-management.ts
chat/lib/quality-bar-ai-summary.ts
docs/task-board/FEATURE.md
packages/contracts/src/task-state.test.ts
packages/contracts/src/task-state.ts

### Deliberately excluded for later phases

- Task Board pages and reusable Task details — AERIE-2734.

- New Task creation and editing behavior, including setting requiresApproval — AERIE-2736.

- Lifecycle actions and enforcement — AERIE-2738.

- Completion submissions and evidence — AERIE-2739.

- Approval, Remove approval and Request changes actions — AERIE-2741.

- Public OpenAPI and DSS widening, migration execution and production launch — AERIE-2744.

- Any automatic migration, backfill, notification, external writeback or Rhodes synchronization change.

## Test plan

### Automated validation

- Migration contract — 7/7 passed (pnpm --dir chat exec vitest run convex/migrations/taskLifecycleContract.test.ts --maxWorkers=1)

- Final overlapping Task, API, read, UI and contract suites — 326/326 passed

- Independent review suites — migration 7/7, Task contract 27/27 and overlapping Chat suites 156/156 passed

- Full Chat suite on the immediately preceding implementation head — 11,869/11,869 passed; the final repair changed only dormant migration validation and its tests, so focused final-head suites were rerun instead of the entire Chat suite

- workspace typecheck — passed (pnpm typecheck)

- lint, architecture boundaries, Convex paths, read bounds and test architecture — passed with two unchanged Sindri warnings (pnpm lint)

- git diff --check — passed

- authoritative FEATURE.md byte comparison — passed

- exact-head diff scope — only the authorized paths listed above

### Time for Implementation

Approximately 5 engineering days without AI assistance to trace the existing lifecycle readers and writers, establish the contract, build the guarded migration, rebase onto the preceding Task slice and validate the compatibility boundary.

## What it means for end users/consumers

| Area | What this PR adds | What changes in production now |

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

| Existing Tasks | Aerie understands the future awaitingApproval status and optional lifecycle fields. | Existing Tasks keep their current status and data. Nothing is automatically converted. |

| Completed Tasks | completed has one clear meaning: the Task is closed. A dormant approver list does not reopen it. | Production currently has no Tasks using approval data, so users should not see existing Tasks change. |

| Awaiting approval | Aerie can safely read an explicitly stored awaitingApproval Task. | No current workflow can create this status, so it will not appear until the later gated workflow is launched. |

| Approval requirement | Storage can hold an explicit requiresApproval value. | Current screens, public API clients and agents cannot set or receive this field yet. |

| Migration | A guarded tool can later inspect and backfill legacy Tasks while stopping on contradictory approval data. | The tool does not run when this PR is deployed. No data is changed automatically. |

| Work Plan and existing Task API | Their existing creation, editing and response contracts remain supported. | Current user and integration workflows continue unchanged. |

| Task Board and agent tools | The internal foundation they will use is now defined. | No Task Board page, new action, notification, digest or DSS instruction becomes available in this PR. |

## Summary

- make the SIS Enrollment report the default and retain HubSpot behind an explicit legacy link and warning

- retarget v1/v2 Enrollment aggregates and student drilldowns to the atomic SIS publication at true SIS year grain

- publish the 16-metric SIS contract, remove pipelineDeposits / yearStartTotal, reject v1 physical mode, and update OpenAPI, compatibility metadata, and Enrollment DSS

- preserve #1670 capacity/fill-rate behavior and the compact Enrollment views added on main

- fix review findings around Program-scoped default years, snapshot-time fill rate, SIS public-ref rollout, bounded v1 pagination, and resolved v2 coordinate years

## Validation

- 13 focused SIS UI/publication/API/OpenAPI/compatibility/DSS files: 298 tests passed

- compact Enrollment views: 9 tests passed

- post-review backend regression suite: 4 files, 142 tests passed

- pnpm --dir chat typecheck

- pnpm --dir packages/contracts typecheck

- pnpm lint:test-architecture

- pnpm lint:read-bounds

- affected-file Biome check

## Rollout

- before activating public Admissions person references, run the bounded backfill, verify the current revision (verificationRevision = 2), and then activate

- missing or stale verification receipts intentionally fail closed; activation cannot resume until current-revision verification succeeds

Closes #1669

## Summary

This PR is the first delivery for [Human Task Assignment from Aerie](https://linear.app/builder-team/project/human-task-assignment-from-aerie-b3582376ae6e), tracked by [AERIE-2733 — Normalize existing Task state across Aerie](https://linear.app/builder-team/issue/AERIE-2733/normalize-existing-task-state-across-aerie).

It gives existing Aerie Task read surfaces one shared internal interpretation of open, closed, overdue, approval-pending, delayed and blocked work, and standardizes compact multi-assignee display.

Production effect: compatibility hardening. This changes live Task read presentation while preserving Task storage, Task writes, lifecycle operations, DSS guidance and the published public API response. It does not add a public state field.

## Why

Existing Work Plan, School Ops, agent-card, backend-count and AI-summary readers interpreted the same stored Task differently. This slice removes those read inconsistencies before later Task Board lifecycle work, without introducing the later schema or public API design.

## Business Value

- Rejected Tasks no longer appear as open, blocked or overdue work.

- Approval-pending completion remains visible and actionable instead of looking fully closed.

- Operators see overdue dates and every assignee consistently across current Task surfaces.

- AI summaries no longer describe rejected Tasks as current work or a planned start date as evidence that work started, and approval-pending completion remains explicit open approval work.

## How does it work

1. @bran/contracts/task-state defines the runtime-independent interpretation of the six existing stored Task statuses, approval state, New York calendar-date overdue state and compact assignee labels.

2. Work Plan, School Ops, Rhodes Task cards, backend counts and quality-bar AI summaries consume that shared interpretation.

3. Completed Tasks with required approval remain open as Done, awaiting approval; rejected and fully completed Tasks are closed.

4. Delayed and Blocked remain explicit stored statuses, while Overdue is derived separately from the deadline.

5. Convex Task projections receive an explicit New York calendar date. The subscribed Work Plan refreshes that query input across the date boundary instead of relying on wall-clock changes to invalidate a subscription.

6. The public Task API response is unchanged; no public derived-state representation or Task lifecycle schema is added.

## Scope

### Included in this phase

- Shared interpretation of existing Task reads.

- Consistent rejected, overdue and approval-pending presentation.

- Compact First assignee +N display with the complete assignee list retained.

- The approved Task Board FEATURE.md as authority for later deliveries.

- Exact final diff paths:

chat/components/__tests__/tool-call.test.tsx
chat/components/dashboards/portfolio/__tests__/portfolio-rhodes-workbench.test.tsx
chat/components/dashboards/portfolio/portfolio-rhodes-workbench.tsx
chat/components/dashboards/school-ops/__tests__/site-detail-panel.test.tsx
chat/components/dashboards/school-ops/site-detail-panel.tsx
chat/components/rhodes-cards/rhodes-read-card.tsx
chat/convex/rhodes/dashboard.ts
chat/convex/rhodes/portfolioWorkbench.ts
chat/convex/rhodes/runtime/siteReadModels.ts
chat/convex/rhodesDashboardParity.test.ts
chat/convex/rhodesMcpParity.test.ts
chat/convex/rhodesPortfolioWorkbench.test.ts
chat/lib/__tests__/operating-sites.node.test.ts
chat/lib/__tests__/quality-bar-ai-summary.node.test.ts
chat/lib/aerie-rhodes-dashboard-server.ts
chat/lib/operating-sites-contract.ts
chat/lib/operating-sites.ts
chat/lib/quality-bar-ai-summary.ts
docs/README.md
docs/task-board/FEATURE.md
packages/contracts/package.json
packages/contracts/src/index.ts
packages/contracts/src/task-state.test.ts
packages/contracts/src/task-state.ts

### Deliberately excluded for later phases

- Task fields, migrations, lifecycle actions, Task Board pages, notifications, digests and agent write tools.

- The rejected public status-plus-state response representation; the existing public Task response stays unchanged.

- DSS changes, because this phase ships no new public agent contract.

- Any decision to retain or retire Rhodes Task synchronization.

- Speculative compatibility for non-canonical Task statuses or a Task completedDate; the canonical Task schema requires one of six status literals and has no completedDate field.

## Test plan

### Automated validation

- Shared Task-state contract — 22/22 passed (pnpm --dir packages/contracts exec vitest run src/task-state.test.ts --maxWorkers=1)

- School Ops focused browser suite — 5/5 passed, including a red → green approval-pending due-badge regression (pnpm --dir chat exec vitest run components/dashboards/school-ops/__tests__/site-detail-panel.test.tsx --maxWorkers=1)

- Affected browser tests on the original delivery — 168 passed

- Affected Node tests on the original delivery — 102 passed

- Affected Convex edge tests on the original delivery — 98 passed

- Workbench and Operating explicit-date Convex regressions — 124/124 passed across their two exact files

- Workbench New York-midnight refresh regression — 1/1 passed

- Quality-bar AI summary derived-state regressions — 15/15 passed, including focused red → green coverage for both prompt builders (pnpm --dir chat exec vitest run lib/__tests__/quality-bar-ai-summary.node.test.ts --project node --maxWorkers=1)

- typecheck — passed (pnpm typecheck)

- lint and architecture/read-bound/test-routing checks — passed with two unchanged Sindri string warnings (pnpm lint)

- git diff --check — passed

- exact-head diff scope — only the authorized paths listed above

### Time for Implementation

Approximately 5 engineering days to trace current Task readers, define and test the shared contract, update all existing consumers, and validate the compatibility boundary without AI assistance.

## What it means for end users/consumers

| Area | Before this PR | After this PR | What it means for end users/consumers |

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

| Rejected Tasks | Some readers treated rejected Tasks as open work, and some labels made them look completed rather than rejected. | Rejected Tasks are consistently closed and labelled Rejected. | Rejected work no longer appears as something that still needs action, and users can still distinguish rejection from successful completion. |

| Completed Tasks awaiting approval | A Task stored as completed with required approvers but no approval could look fully finished in some views and AI summaries. | These Tasks remain visible as open approval work and are labelled Done, awaiting approval. | Approval work is not hidden or mistakenly described as already closed. |

| Completed and approved Tasks | Readers used different rules to decide whether completed work was actually closed. | Fully completed Tasks are consistently closed, and approved completion is labelled Approved. | Counts, Task cards and summaries agree that the work is finished. |

| Overdue Tasks | Different readers could disagree about whether a Task was overdue, and an open Work Plan could retain yesterday's result after midnight. | A Task is overdue only when it is still open and its due date is before the current New York calendar date. The Work Plan refreshes after the date changes. | Due today does not mean overdue, closed work is not shown as overdue, and an open screen does not need another data change to notice a new day. |

| Delayed and blocked Tasks | Some consumers mixed stored progress labels with deadline calculations. | Delayed and Blocked remain their own Task statuses, independent from the calculated overdue condition. | A Task can be delayed without being overdue, overdue without being delayed, or both. |

| Multiple assignees | Compact Task views could show only the first assignee, making the Task look individually owned. | Compact views show the first assignee plus a count, while retaining the complete assignee list. | Users can see that responsibility is shared without making compact views excessively wide. |

| Planned start dates | AI summaries could describe a planned start date as evidence that work had actually started. | Planned dates are described as scheduled dates. | Summaries no longer overstate Task progress. |

| Task counts and summaries | Work Plan, School Ops, backend counts, Task cards and AI summaries could interpret the same stored Task differently. | They use the same shared read rules for open, closed, rejected, delayed, blocked, overdue and approval-pending work. | Existing screens, agents and summaries are less likely to contradict one another about the same Task. |

| Task storage, writes and public API | Existing Task creation, editing and public API behavior were already in use. | They remain unchanged. This PR adds no public state field and does not change DSS guidance or lifecycle actions. | Existing integrations and Task-writing workflows do not need to change for this deployment. |

## Summary

- default SIS Summary to a compact column set beginning at On Campus

- keep Summary / By Levels left-aligned and add a right-aligned Show all columns switch

- keep By Levels and CSV exports unchanged, while reconciling hidden sort and drill-down state

- add hover guidance and use grade-level terminology

## Validation

- pnpm --dir chat exec vitest run components/dashboards/admissions/enrollments/sis/types.node.test.ts components/dashboards/admissions/enrollments/sis/__tests__/sis-enrollments-view.test.tsx --maxWorkers=1

- pnpm exec biome check chat/components/dashboards/admissions/enrollments/sis/sis-enrollments-view.tsx chat/components/dashboards/admissions/enrollments/sis/types.ts chat/components/dashboards/admissions/enrollments/sis/types.node.test.ts chat/components/dashboards/admissions/enrollments/sis/__tests__/sis-enrollments-view.test.tsx

- pnpm lint:test-architecture

- pnpm --dir chat typecheck

Follow-up to #1689.

## Summary

This PR is a corrective slice in [AERIE-2646 — Run the production observe rollout for property-acquisition reconciliation](https://linear.app/builder-team/issue/AERIE-2646/run-the-production-observe-rollout-for-property-acquisition).

It fixes property-acquisition reconciliation readiness so only letters of intent, draft acquisition agreements, and executed acquisition agreements count as sources; it also blocks and notifies on final core-source failures. This slice is tracked by [AERIE-2724 — Filter property-acquisition sources before reconciliation](https://linear.app/builder-team/issue/AERIE-2724/filter-property-acquisition-sources-before-reconciliation) and unblocks AERIE-2653.

Production effect: activation. The behavior is reachable only for active Sites admitted by the existing reconciliation rollout controls. This PR does not change an allowlist, deploy code, start a rollout, or enable writes.

---

## Why

The production observe rollout found a Site with 93 documents, of which only 2 were valid property-acquisition sources. Readiness applied the 64-source limit before filtering, so unrelated documents prevented reconciliation from reaching the existing receipt boundary. The same readiness check also needed to account for accepted core REBL3 candidates and final core-source failures without introducing a classifier or a second retry system.

---

## Business Value

- Allows property-acquisition reconciliation to proceed for Sites with many unrelated documents and no more than 64 core documents.

- Prevents reconciliation from proceeding with an incomplete core source set.

- Alerts the configured operator once when a core source version finally fails registration or content processing.

- Preserves existing reconciliation Agents, evidence policy, write controls, retries, quarantine rules, and rollout controls.

---

## How does it work

1. reconciliation/readiness.ts queries only canonical core document types and supported stored aliases before applying the existing 64-source bound; non-core promotions cannot trigger reconciliation.

2. Readiness also checks accepted, unresolved core Drive candidates. Pending candidates or pending Document Knowledge jobs wait silently; quarantined and non-core candidates are ignored.

3. rebl3Discovery/registration.ts persists only final registration failure facts, fenced to the candidate source version. Existing action-local retry attempts and delays remain authoritative.

4. reconciliation/propertyAcquisitionSources.ts emits one idempotent event per failed registration source version or Document Knowledge generation, using the exact stored failure reason and the existing in-app, email, and Google Chat delivery paths.

5. When all core sources are readable, the existing receipt and three-Agent workflow remain unchanged. With no core sources, no reconciliation execution or notification is created.

---

## Scope

### Included in this phase

- Core-only source filtering before the existing 64-source limit.

- Core-only promotion gating and accepted-candidate readiness checks.

- Final registration-failure persistence on the existing candidate row.

- Final core content/registration failure notifications through existing delivery infrastructure.

- Focused regression coverage and production-data local E2E validation.

- Exact final diff paths:

chat/convex/_generated/api.d.ts
chat/convex/documentKnowledge/lifecycle.test.ts
chat/convex/documentKnowledge/lifecycle.ts
chat/convex/documentKnowledge/processing.test.ts
chat/convex/documentKnowledge/processing.ts
chat/convex/notifications/events.ts
chat/convex/notifications/schema.ts
chat/convex/rebl3Discovery/autoRegistration.test.ts
chat/convex/rebl3Discovery/autoRegistration.ts
chat/convex/rebl3Discovery/registration.test.ts
chat/convex/rebl3Discovery/registration.ts
chat/convex/rebl3Discovery/registrationState.ts
chat/convex/rebl3Discovery/registry.test.ts
chat/convex/rebl3Discovery/registry.ts
chat/convex/rebl3Discovery/schema.ts
chat/convex/reconciliation/propertyAcquisitionSources.test.ts
chat/convex/reconciliation/propertyAcquisitionSources.ts
chat/convex/reconciliation/readiness.test.ts
chat/convex/reconciliation/readiness.ts
chat/convex/reconciliation/reads.test.ts

### Deliberately excluded for later phases

- Production deployment, allowlist changes, rollout execution, reconciliation writes, and AERIE-2653 actions.

- AI relevance classification, classifier assets, source catalogs, or an additional Sindri workflow.

- Changes to REBL3 discovery, parsing, classification, or quarantine behavior.

- New retry loops, timers, tables, blocker lifecycles, UI, public APIs, or notification subsystems.

- Changes to the existing reconciliation receipt, Agents, evidence roles, field policy, validation, or write controls.

- Support for more than 64 core documents.

---

## Test plan

### Automated validation

- Production-data local E2E — 6/6 passed (npx vitest run convex/reconciliation/prodData2724.e2e.test.ts --reporter=verbose).

- Base production-failure reproduction — 1/1 passed against base c3b178f9db2a7a1cf88c3484395a2cea1580661a.

- Production-shaped regression subset — 22/22 passed across readiness, failure notification, registration, and auto-registration tests.

- Affected implementation suite — 143/143 passed across 10 Vitest files.

- Full hosted test suite on reviewed feature commit — 11,817 tests passed.

- Root workspace typecheck and Chat/Convex TypeScript checks — passed.

- Changed-file Biome — passed.

- Architecture boundaries, Convex paths, read bounds, test architecture, and knowledge hygiene — passed.

- git diff --check — passed.

- Independent review of feature commit 10798d9e59db2b14baa2c0e9844dcf1233362184 — PASS with no findings.

- Production-data comparison proved the base failed on 93 total documents while this change captured exactly the 2 core sources and stopped at the queued receipt boundary; no Agent, workflow, notification dispatch, reconciliation write, or external writeback ran.

- Current PR head 887d9d6f0e748f141c9aff696f1da8615e581201 contains the reviewed feature commit, current main, and the two-file pre-deploy retry compatibility repair; hosted CI and Mercy re-review are exact-head gates.

### Time for Implementation

Approximately 4–6 engineer-days without AI assistance, including production-failure reproduction, implementation, regression coverage, independent review, rebase/merge-main validation, and production-data local E2E verification.

---

## Review repairs and contract clarifications

Reviews [5432810787](https://github.com/AI-Builder-Team/Aerie/pull/1673#pullrequestreview-5432810787) and [5433065726](https://github.com/AI-Builder-Team/Aerie/pull/1673#pullrequestreview-5433065726) were classified under [AERIE-2724](https://linear.app/builder-team/issue/AERIE-2724/filter-property-acquisition-sources-before-reconciliation).

- Accepted pre-deploy retry compatibility blockers: retries queued by the pre-change code have no sourceVersion. The first repair derives the current version after a successful source lookup for every attempt. The follow-up repair also makes terminal settlement derive the current version transactionally when the source query itself throws, while any supplied version remains a strict stale-work fence.

- Accepted candidate-alias blocker: registered documents already canonicalized supported aliases, but accepted-candidate readiness and registration-failure notification used the raw hint. Both now use the same canonical core-type predicate, so legacy lease or executedAgreement candidate hints block and notify consistently while accepted; quarantine behavior remains unchanged.

- Rejected terminal-lease finding: nextClaimableDocumentKnowledgeJob loads the state before returning a job and supersedes an ingest job when that state is missing or invalid. The exhausted-lease branch runs later in the same Convex transaction, so the validated state cannot disappear concurrently and the job just patched in that transaction cannot be absent. An orphaned job therefore never reaches the cited conditional; it is superseded first. No production change or artificial regression is warranted.

- Deployment configuration clarification: production configuration is deliberately outside this code PR. Before a separately authorized rollout, PROPERTY_ACQUISITION_FAILURE_RECIPIENT_EMAIL must be set in the production Convex environment to caina.barbosa@trilogy.com, and that email must resolve to an existing Aerie user. This PR does not hard-code the address, change production configuration, deploy, or start a rollout.

- Unchanged boundaries: existing action-local retry delays remain authoritative; supplied source-version fences still reject stale scheduled work; no new retry lifecycle, table, classifier, workflow, deployment action, or write path is introduced.

- Repair validation: focused regressions cover both legacy retry paths and aliased accepted candidates. 24/24 tests passed across registration, auto-registration, readiness, and source-failure notification files; Convex TypeScript, Biome, and git diff --check passed.

- Production effect: these repairs provide deployment compatibility for already queued internal retries and consistent interpretation of legacy stored aliases. They create no traffic, migration, rollout activation, external write, or production configuration change by themselves.

## Summary

- add data.operationalForecastV2 with stable, ordered Start-of-Year, January, and End-of-Year milestone DTOs

- preserve legacy response shapes with exact deprecation notes and carry End-of-Year target/lock metadata through worker and Convex publication boundaries

- update OpenAPI, DSS guidance, and the installable Aerie API skill/version to prefer the normalized contract

## Validation

- pnpm typecheck

- focused Chat API/publication/DSS/skill tests (181 tests)

- focused sync refresh tests (47 tests)

- Redshift forecast reader tests (40 tests)

- pnpm lint:test-architecture

- pnpm lint:boundaries

- pnpm lint:read-bounds

- Biome checks for all changed files

Closes #1685

## Summary

- Remove three lockfiles that nothing builds from. Together they account for 130 open Dependabot alerts.

## Why it's needed

These lockfiles describe dependencies that never run, so their alerts are noise that hides the real backlog.

- klair-misc/klair-mcp-ts/pnpm-lock.yaml (96 open alerts): the MCP server uses npm. Its Dockerfile, mcp-deploy.yml, and mcp-tests.yml all run npm ci against package-lock.json. The pnpm lockfile is a stale duplicate.

- _archive/exploration/vantage/uv.lock (18) and _archive/exploration/redshift/uv.lock (16): archived exploration code, last touched in March, not referenced by any workflow or deploy.

## Changes

- Delete the three lockfiles.

- Add pnpm-lock.yaml to klair-misc/klair-mcp-ts/.gitignore so a local pnpm install doesn't recommit it.

The _archive source files stay. Only their lockfiles go.

## Breaking changes

None. No workflow, Dockerfile, or deploy reads these files.

## Test plan

- [x] git grep for each deleted path: no references

- [x] Confirmed klair-mcp-ts Docker and CI paths use npm ci with package-lock.json

- [ ] After merge: confirm Dependabot closes the alerts on these three manifests

## Follow-ups

- 9 alerts remain open on klair-misc/apr-scripts-q3/uv.lock, which was already deleted on 2026-08-05 (#3481). Those can't be closed from code and would need dismissing in the GitHub UI.

## Summary

- POST /pdf-export/markdown-to-pdf now requires a Clerk token.

- WeasyPrint renders that route with a URL fetcher that loads nothing, so request content can no longer make the API read local files or call internal or external URLs.

## Why it's needed

The route had no auth dependency, CORS allows any origin, and it rendered request-derived HTML with WeasyPrint's default URL fetcher. Python-Markdown passes raw HTML through (the route relies on this to inline Mermaid SVG), and the default fetcher follows file:// and http(s):// URLs. A local test against WeasyPrint 66.0 confirmed that a rel="attachment" link embeds a local file in the returned PDF. Together, these meant anyone who could reach the API could likely read files the API process can read and make it fetch internal URLs. This came out of the 2026-10-05 Dependabot review of WeasyPrint alert #345.

## Changes

- klair-api/routers/pdf_export_router.py: dependencies=[Depends(verify_token_clerk)] on /markdown-to-pdf, and HTML(..., url_fetcher=block_all_url_fetcher). /pdf-export/health stays public. Same approach as the existing Claire export path (claire_bot/export_file_tool.py).

- klair-client/src/components/ClaireChat/pdfExport.ts: exportChatToPDF(messages, getToken, title) sends Authorization: Bearer <token>.

- ClaireBotAISDK.tsx and ClaireBotFullPage.tsx pass Clerk's getToken.

- New klair-api/tests/routers/test_pdf_export_router_security.py.

## Breaking changes

Unauthenticated callers of /pdf-export/markdown-to-pdf now get 401. The only in-repo caller is the Claire chat export, which this PR updates. Deploy the API and client together; until the client ships, PDF export from an old client will return 401.

Rendered PDFs no longer load external resources (images or stylesheets referenced by URL). Mermaid diagrams are unaffected because they are inlined as SVG.

## Test plan

- [x] uv run pytest tests/routers/test_pdf_export_router_security.py: 3 passed (401 without a token, health still public, fetcher returns nothing for file://, metadata IP, and https://)

- [x] uv run ruff format / ruff check on changed Python files: clean

- [x] uv run pyright routers/pdf_export_router.py: same 10 errors as main (all from the existing optional-WeasyPrint None fallback), none new

- [x] Local WeasyPrint 66.0 check: the default fetcher embeds a dummy local file in the PDF; block_all_url_fetcher does not

- [x] pnpm tsc --noEmit, ESLint (--max-warnings 0) on changed client files: clean

- [x] pnpm exec vitest run ClaireChat ClaireBot pdfExport: 23 files, 210 passed

- [ ] Manual: export a Claire answer with a table and a Mermaid diagram to PDF in staging and confirm it renders

## Summary

- add a themed Compact / Complete enrollment report view control, defaulting to Compact

- derive desktop, mobile, and sort display columns from On Campus onward while retaining seasonal applicability

- preserve full applicable CSV exports and reconcile hidden sorts and drill-downs

## Validation

- pnpm --dir chat exec vitest run components/dashboards/admissions/enrollments/__tests__/enrollments-view.test.tsx --maxWorkers=1

- pnpm exec biome check chat/components/dashboards/admissions/enrollments/enrollments-view.tsx chat/components/dashboards/admissions/enrollments/__tests__/enrollments-view.test.tsx

- pnpm --dir chat typecheck

- pnpm lint:test-architecture

Closes #1689

## Testing contract

### What this PR delivers

Follow-up to #1686 ([AERIE-2485](https://linear.app/builder-team/issue/AERIE-2485), [AERIE-2443](https://linear.app/builder-team/issue/AERIE-2443)). #1686 stopped the public REST routes from serving plaintext credentials, but the Rhodes MCP still served them, and agents could still write them:

- MCP getSite read: for callers allowed to see utility details (operations.portfolio.read or operations.siteFields.write), utility leaves holding an inline secret (PW:, pwd=, password:, Passcode:, upper-case PIN:) are now served as the same withheld placeholder the REST API uses. Every other leaf is unchanged. Callers without those capabilities still get the existing full redaction.

- MCP updateSiteUtilities write (direct and approval-queue apply, both via applyToolMutation): a patch carrying a plaintext credential now fails with <section>.<field> contains a plaintext credential; store a restricted credential reference instead. The error does not echo the value, and nothing is written.

It adds withholdSiteUtilityCredentials and findPlaintextCredentialInUtilitiesPatch to @bran/contracts/utilities, built on the detector from #1686.

### Who uses it and where

Rhodes MCP consumers (DSS, site-loop and other agents, API-key and user-session callers) using the getSite and updateSiteUtilities tools. The internal Portfolio UI is unchanged.

### Conditions needed

- An MCP caller with operations.portfolio.read (read case) or operations.siteFields.write (write case).

- A site whose utilities contain a login such as ops@example.com PW: hunter2.

### Expected behavior and examples

- getSite on a site with electrical_login = "ops@example.com PW: hunter2" Γò¼├┤Γö£├æΓö£├Ñ utilities.electrical.electrical_login is the withheld placeholder; electrical_provider and electrical_account_number are served as before; the result contains no hunter2.

- getSite on a site with gas_login = "gas@example.com" Γò¼├┤Γö£├æΓö£├Ñ served unchanged.

- updateSiteUtilities with { gas: { gas_login: "ops@example.com PW: hunter2" } } Γò¼├┤Γö£├æΓö£├Ñ status failed with gas.gas_login contains a plaintext credential...; the stored value is unchanged.

- updateSiteUtilities with ordinary values Γò¼├┤Γö£├æΓö£├Ñ unchanged behavior.

Tests: new cases in chat/convex/rhodesMcpParity.test.ts, chat/convex/rhodesMcpMutationParity.test.ts and packages/contracts/src/plaintext-credentials.test.ts. The Rhodes suites pass (436/436), along with contracts utilities tests, Biome, and the chat typecheck.

### Limits and unanswered questions

- The internal Portfolio UI is unchanged.

- Detection is pattern-based: a bare password with no marker is not caught.

Linear: [AI-974](https://linear.app/builder-team/issue/AI-974/issue-rhodes-api-keys-from-the-dss-and-call-upstream-with-one-service)

> Do not merge and deploy until the three prerequisites below are done. Once deployed, callers' existing upstream keys stop working here.

## Summary

Implements Benji's suggestion and Artie's "Rhodes API keys" ask: the DSS issues its own keys and makes every upstream call with one credential it holds, so callers never see the upstream platform, its key prefix or its key page.

- Key registry (src/auth/registry.ts): stores SHA-256 digests only, with holder identity, display name and enabled/operator flags. DynamoDB in production, a private file locally.

- Key management (pnpm keys mint|list|revoke|restore): run by an administrator with their own AWS identity. mint prints the key once (rhk_ + 64 hex). The running service can only look keys up.

- Relay: authenticates the Rhodes key, then calls upstream with AERIE_SERVICE_API_KEY. The caller's key is never forwarded. Unknown or revoked keys get 401; a registry failure gets 503 authentication_unavailable.

- Feedback and operator triage use the same registry. The upstream key-verification call and the operator digest list are gone.

- Infra: key registry table (retained, deletion-protected); the service credential is injected from an existing Secrets Manager secret (UpstreamKeySecretArn). The IAM plan gains the matching permissions and an --update mode to re-apply policies to the already-provisioned roles.

- Docs and contract: Enablement explains requesting a key; per-operation capability lists are no longer published, since callers hold no capabilities of their own.

## Trade-offs this accepts

- Uniform access. Every key reads whatever the service credential can read, within the allowlist. Per-person access control is gone.

- Shared rate budget. Upstream limits apply to the one credential: all callers share 120/min standard and 10/min sensitive (notes, documents, search). No per-key throttling is added here.

- Upstream audit shows one user. Per-caller attribution exists only on feedback in this service.

- Manual issuance. No self-serve page.

## Prerequisites before deploy

1. A read-only upstream service key, scoped to the Rhodes reads, stored as Secrets Manager secret rhodes-dss/production/upstream with JSON field AERIE_SERVICE_API_KEY.

2. node scripts/provision-deployment.mjs --update, run by the administrator, to grant the runtime boundary and deployment roles access to the new table and secret.

3. Update STACK_PARAMETERS: add UpstreamKeySecretArn, remove AerieKeyVerifyPath, and set FeedbackKeyContact to wherever people should request a key.

4. Mint keys for current users before cutover.

## Verification

- pnpm check: 48 tests pass. pnpm build and pnpm synth --no-lookups succeed.

- Local end-to-end run against a fake upstream: a minted key is served; the upstream received only the service credential, never the caller's key; no key and a wrong key return 401; a revoked key returns 401 on the next request.

- One unexplained transient: a single pnpm check run reported two relay tests receiving HTTP 501. It did not recur in eight further runs and no code path returns 501. Noting it in case it reappears in CI.

- Not verified: the DynamoDB registry against a real table (mocked client only), the injected secret in ECS, and the --update IAM path.

## Business Value

Removes the last place the upstream platform is visible to Rhodes consumers and gives Edu Ops keys that are theirs, which is the condition leadership set for this DSS. It also makes access revocable per holder without touching the upstream platform.

## Manual Effort Estimate

Proposed: about 1.5 days by hand (registry and key tooling, relay auth change, infra and IAM, rewriting the access docs, tests). Keval to confirm or adjust.

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

## Testing contract

### What this PR delivers

Stops the public API from serving plaintext passwords that operators typed into free-text fields. Fixes [AERIE-2485](https://linear.app/builder-team/issue/AERIE-2485) (Tulsa /property/utilities served electrical and gas portal passwords) and [AERIE-2443](https://linear.app/builder-team/issue/AERIE-2443) (201 Colorado /data-sheet served field 16.1 WiFi passwords).

A shared check in @bran/contracts/plaintext-credentials recognises inline secrets (PW:, pwd=, password:, Passcode:, upper-case PIN:) and credential-holding labels (passwords, passcodes, passphrases, WiFi keys/codes, PIN). It is applied in three places:

- v2 utilities read: any utility leaf holding an inline secret is served as [withheld: this value contains a plaintext credential. Store a restricted credential reference instead.]. All other values are unchanged, including the existing "Restricted credential reference" text.

- v1 and v2 data-sheet reads: rows whose label names a credential, or whose value holds an inline secret, are dropped from the public projection and counted in excludedCount (v1), like the existing security/access denylist.

- v2 utilities PATCH: a plaintext credential in any leaf is rejected with 422 property_utilities_patch_invalid. The error names the field but does not echo the value.

### Who uses it and where

API-key consumers of /v2/portfolio/sites/{siteRef}/property/utilities, the v2 data-sheet / site-profile reads, and the v1 data-sheet route. These are mainly DSS and site-loop agents holding operations.portfolio.read. The internal Portfolio UI and Rhodes MCP are unchanged.

### Conditions needed

- An API key with operations.portfolio.read (plus operations.siteFields.write for the PATCH case).

- A site whose utilities contain a login such as ops@example.com PW: hunter2.

- A Schools Data Sheet row (or defaults row via "Per Default") with label 16.1 WiFI passwords (Network name - Password), or any cell with an inline PW: value.

### Expected behavior and examples

- GET utilities where electrical_login = "ops@example.com PW: hunter2" → electrical.login is the withheld placeholder; provider and account_number are served as before; the response body contains no hunter2.

- GET utilities where the login is Restricted credential reference ... Secret values intentionally omitted. → served unchanged.

- GET data-sheet with a populated 16.1 WiFi passwords row → the row is absent; on v1 excludedCount includes it.

- A data-sheet cell Map pin: 30.26, -97.74 or a label like "Map pin" → still served (PIN only matches upper case).

- PATCH utilities { "gas": { "login": "ops@example.com PW: hunter2" } } → 422 property_utilities_patch_invalid; the stored value is unchanged.

Tests: packages/contracts/src/plaintext-credentials.test.ts, plus new cases in chat/convex/portfolio/siteSheetData.test.ts and chat/convex/publicApi/v2/writeErrorBoundary.test.ts. The convex/publicApi and lib/public-api suites pass (698/699). The one failure, skill-package.node.test.ts (hash mismatch), also fails on clean main on Windows.

### Limits and unanswered questions

- The stored secrets are still in the database. This PR only stops serving them. The Tulsa electrical/gas logins need overwriting with a credential reference, the WiFi passwords must be removed from the source Google Sheet, and the exposed credentials should be rotated.

- The internal Portfolio UI and Rhodes MCP still show raw utility values and the lossless data sheet to portfolio readers. Moving the write guard into the shared updateSiteUtilities writer would block new secrets on every surface. That is left as a follow-up.

- Detection is pattern-based: a bare password with no marker (e.g. ops@example.com hunter2) is not caught.

- Add API v2 creation for backup locations and contract terms, including actor-bound contract uploads, replacement, and archive.

- Expose Site candidate, operating, and dated-need writes through the same domain writers used by the browser, with API-key authorization, request guards, and audits.

- Enforce one protected Site per backup location and show existing usage in the admin edit modal; fail closed on ambiguous assignments.

- Add API, Convex, and UI coverage and document the Backup Sites API workflow.

## Summary

- treat COMPLETED enrollments with an effective withdrawal date as withdrawn while preserving the source status

- keep undated and future-dated completions on campus, with future dates also in Future Withdrawals

- preserve First Day and Mid-Term Join history and use the shared warehouse clock consistently

- add deterministic classification and cohort-fanout unit coverage

## Validation

- poetry run dbt parse --no-partial-parse

- poetry run dbt test --select int_enrollment_classification_completed_withdrawal_dates int_enrollment_cohort_completed_withdrawal_memberships (2 passed)

- warehouse comparison: 6 canonical rows in 2024, 12 in 2025, and 1 in 2026 move from On Campus to Withdrawn; no future-dated completed withdrawals currently exist

- confirmed Lincoln Kaplan's 2026 Alpha La Jolla completion has withdrawal date 2026-09-09

Closes #1679

Linear: [AERIE-2732](https://linear.app/builder-team/issue/AERIE-2732/catalog-the-wrike-and-hubspot-site-references-in-the-api-agent-context)

Follow-up to #1680. Mercy flagged there (high severity) that the agent-context catalog describes driveFolderId but not the other two references the integrations read returns. #1680 merged before that fix was pushed, so it is here.

## Testing contract

### What this PR delivers

Two added entries in the Portfolio Site Profile agent-context catalog, for wrikeFolderId and hubspotProgramCode, so agents reading the catalog can discover every field the integrations read returns. The driveFolderId entry's notes are tidied to match.

Catalog metadata only. No route, response, capability or data change.

### Who uses it and where

Agents and API consumers that read the agent-context catalog (/v2/meta and the agent-context routes) to learn what the site integrations resource contains.

### Conditions needed

None beyond the existing catalog tests; no data or roles are required.

### Expected behavior and examples

1. The catalog object portfolio.site.profile lists driveFolderId, wrikeFolderId and hubspotProgramCode, each sourced from the SiteIntegrations schema property of the same name.

2. Each entry states its meaning, what null means, and that the value is a read-only reference to an external system.

Example: hubspotProgramCode is described as the key joining the site to admissions data, with null meaning the site is not linked to a HubSpot program.

3. Responses from GET /v2/portfolio/sites/{siteRef}/integrations are unchanged.

### Limits and unanswered questions

None.

## Verification

- tsc --noEmit clean.

- vitest run lib/public-api convex/publicApi/v2/portfolioDomain.test.ts: 21 files, 202 tests pass (the catalog integrity tests are in lib/public-api).

## Business Value

Keeps the API's self-description complete, so agents don't miss two of the three references just added.

## Manual Effort Estimate

Proposed: about 20 minutes by hand. Keval to confirm or adjust.

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

Linear: [AERIE-2730](https://linear.app/builder-team/issue/AERIE-2730/return-the-sites-drive-wrike-and-hubspot-references-on-the)

> Reviewer note: this reverses a deliberate guard. portfolioDomain.test.ts asserted that GET …/integrations must not return the Drive or Wrike folder IDs. This PR changes that assertion. Please confirm the exposure is acceptable before approving.

## Testing contract

### What this PR delivers

GET /v2/portfolio/sites/{siteRef}/integrations now returns three external references stored on the site record, in addition to visibility:

- driveFolderId: the site's Google Drive document folder

- wrikeFolderId: the Wrike folder recorded for the site

- hubspotProgramCode: the HubSpot program code the site is linked to

These are shown in the Rhodes UI and returned by the Rhodes MCP, but no API v2 read returned them. Edu Ops asked for all Rhodes data to be reachable through the API (and so through the Rhodes DSS).

Read-only. No route, capability, schema or data change beyond the three added response fields.

### Who uses it and where

API key holders with operations.portfolio.read, calling the integrations read directly or through the Rhodes DSS. The fields appear in the OpenAPI SiteIntegrations schema and the agent-context catalog. No in-app UI changes.

### Conditions needed

- An API key with operations.portfolio.read, and a second key that also has operations.driSites.write.

- A site with a Drive folder ID and a Wrike folder ID recorded, and no HubSpot program code.

### Expected behavior and examples

1. Read. The integrations read returns the stored values, or null when none is recorded.

Example: a site with Drive folder drive-1 and Wrike folder wrike-1 and no program code returns driveFolderId: "drive-1", wrikeFolderId: "wrike-1", hubspotProgramCode: null.

2. Read-only key. A key with only operations.portfolio.read receives the same values.

3. Writes are unchanged. PATCH …/integrations with {"driveFolderId": "…"} is still rejected with 422 request_body_invalid. Only visibility is writable.

4. Other projections are unchanged. The site list and site detail still omit the Drive folder ID, and site change history still redacts these fields.

### Limits and unanswered questions

- Sensitivity. A Drive folder ID is an identifier, not a credential: it grants no Drive access by itself. If the original guard had a different reason (for example, discouraging callers from bypassing the document register), this PR should not merge as is.

- Scope of the reversal. Only the integrations card changes. I did not touch the change-history redaction list or the list/detail projections.

- Verified with the Convex test harness only, not against a deployed environment.

## Verification

- tsc --noEmit and tsc -p convex/tsconfig.json --noEmit clean.

- vitest run convex/publicApi lib/public-api app/api: 78 files, 892 tests pass.

- pnpm lint passes.

## Business Value

Closes the last gap between what Rhodes stores about a site and what the API returns, so agents can follow a site to its Drive folder, Wrike project and admissions program without needing the MCP.

## Manual Effort Estimate

Proposed: about 2 hours by hand. Keval to confirm or adjust.

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

Linear: [AERIE-2729](https://linear.app/builder-team/issue/AERIE-2729/add-public-api-read-routes-for-site-internet-profile-cleanliness)

## Testing contract

### What this PR delivers

Three new read-only public API v2 routes, so Rhodes data that only the Rhodes MCP could read is also available to API consumers:

- GET /v2/portfolio/sites/{siteRef}/internet: the site's internet operating profile.

- GET /v2/portfolio/sites/{siteRef}/cleanliness: the site's cleaning and consumables operating profile.

- GET /v2/portfolio/sites/{siteRef}/decision-log: the site's recorded decisions, newest first.

Edu Ops asked for all Rhodes data to be reachable through the Rhodes DSS, which reads through this API. These three were the Rhodes tables with no API route.

No writes, no schema or data migration, no change to existing routes.

### Who uses it and where

API key holders with operations.portfolio.read, calling the public API v2 directly or through the Rhodes DSS. The routes appear in the generated OpenAPI spec, /v2/meta and the API docs page, under "Portfolio Site Profile". No in-app UI changes.

### Conditions needed

- An API key with operations.portfolio.read.

- A site with a recorded internet profile, a recorded cleanliness profile and at least two decision-log entries.

- A site with none of the three.

- A second key without operations.portfolio.read (for the 403 case).

- For the bound: a site with more than 200 decision-log entries.

### Expected behavior and examples

1. Internet profile. Returns site, recorded, status, primary and backup provider with download/upload Mbps, backupFailoverMethod, and issueContact {name, phone, email}. Unset values are null.

Example: a site with primary provider "Fiber Co" at 1000/500 Mbps and automatic failover returns those values with backupProvider: null and recorded: true.

2. Cleanliness profile. Returns site, recorded, status, cleaningResponsibility, primaryProvider, serviceStartDate, servicePattern, cadence, consumables fields, pestControlProvider and two contacts. serviceStartDate can be an ISO date or the literal "N/A".

3. No profile recorded. Both profile routes return 200 with recorded: false and every other field null, not a 404.

4. Decision log. Returns entries newest first, each with recordedAt, body, relatedField (null when not recorded), author.displayName and decisionMaker.displayName, plus truncated.

- At most 200 entries are returned; truncated is true when older ones exist.

- Only display names are returned. User IDs and emails are never included, and a user whose stored name is an email address appears as "Aerie user" (same rule as site notes).

- A site with no decisions returns entries: [], truncated: false.

5. Access. No key returns 401; a key without operations.portfolio.read returns 403; an unknown site returns 404.

### Limits and unanswered questions

- Not included: driveFolderId, wrikeFolderId, hubspotProgramCode. Edu Ops also asked for these. portfolioDomain.test.ts asserts the integrations route must not return the Drive and Wrike IDs, so I treated that as a deliberate guardrail and left it alone. Whether to expose them needs an owner decision.

- Capability choice. I gated all three on operations.portfolio.read, like the other site-profile reads. The profiles include contact names, phones and emails; say if a narrower capability is wanted.

- Decision log is bounded, not paginated. 200 newest entries with a truncation flag. If sites routinely exceed that, cursor pagination should follow.

- Not exercised against a deployed environment; verified with the Convex test harness only.

## Verification

- chat: tsc --noEmit and tsc -p convex/tsconfig.json --noEmit clean.

- vitest run convex/publicApi lib/public-api app/api: 78 files, 894 tests pass, including two new tests in portfolioDomain.test.ts.

- pnpm lint passes (read-bounds check included; the decision-log read is index-scoped and bounded with .take).

## Business Value

Lets Edu Ops' agents read every Rhodes site record through one API instead of needing the MCP for three of them, which is what unblocks the Rhodes DSS from being "all of Rhodes".

## Manual Effort Estimate

Proposed: about 1 day by hand (learning the v2 route, schema and agent-catalog pattern, three routes, tests). Keval to confirm or adjust.

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

## Demo


## Linear

https://linear.app/builder-team/issue/AI-964/document-ticket-creation-in-feature-discovery

## Summary

- Add a Ticket Creation section after Research with project selection, artifact approval, and created-ticket steps.

- Add repository-owned ticket-flow screenshots and section-aware lightbox navigation with local numbering and focus restoration.

- Extend Feature Discovery coverage for the new section and its accessible image fallback.

## Test plan

- pnpm test:feature-discovery

- pnpm exec tsc --noEmit

- pnpm build

- pnpm theme:check

- git diff --check

Linear: [AI-972](https://linear.app/builder-team/issue/AI-972/remove-the-aerie-name-from-everything-the-rhodes-dss-publishes)

Colin's direction (Ops Automation Trilogy, 2026-10-06): the Aerie name should not be mentioned on the Rhodes DSS.

## Summary

- Front, Dictionary, Enablement: no mention of Aerie. Keys are called "Rhodes API key"; the key-creation steps link to the API Keys page by URL without naming the platform.

- OpenAPI: at serve time, prose (description, summary, title) is renamed and x-aerie-* extensions become x-rhodes-*. The pinned snapshot on disk is untouched, so pnpm sync:openapi still diffs cleanly against upstream.

- A new test fails if any published text names the platform.

## What still carries the name, deliberately

- Two schema values in the OpenAPI: source.owner: "aerie" and authority: "aerie.operations". Real responses contain these and the DSS relays responses unchanged, so the contract keeps them exact. Removing them means rewriting response bodies, which is a behaviour change and not in this PR.

- The key prefix aerie_sk_ (not shown in the docs, but visible on the key itself).

- Internal code, README and environment variable names. These are not served.

## Verification

- pnpm check: 47 tests pass. pnpm build succeeds.

- Local run of the built service: /api/skill, /api/dictionary and /api/enablement contain zero mentions; /api/v1/openapi.json contains only the eight occurrences of the two response values above.

No change to routes, dispatch or authentication.

## Business Value

Meets the owners' requirement that Rhodes is presented as its own dataset, so the DSS can be shared with Edu Ops consumers without the naming objection blocking adoption.

## Manual Effort Estimate

Proposed: about 3 hours by hand (finding every mention across two documents, the front and a 44-operation contract, and deciding what must stay exact). Keval to confirm or adjust.

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

## Summary

- add Montessorium to the authoritative SIS enrollment campus brand allowlist

- add a focused dbt unit test proving an active, physical, HubSpot-resolved Montessorium campus enters scope while online and unmapped campuses remain excluded

- update SIS model/source documentation to describe the centralized allowlist accurately

## Validation

- dbt parse

- dbt ls --resource-type unit_test --select stg_sis_campus

- git diff --check

Closes #1675

## Summary

- add an Enrolled column immediately after Grade in the SIS enrollment student list

- format enrollment dates as compact, timezone-stable calendar dates

- show an em dash when the enrollment date is unavailable

- update the list-pane browser coverage for column order and date rendering

## Validation

- CI/CD will validate this change per request

## Summary

- resolve Rhodes-backed Program capacity and contributor metadata for SIS enrollment rows

- calculate fill rate from 1st Day before the selected year starts and On Campus from 1 August onward

- add sortable Capacity and Fill Rate columns after Graduating, including contributor tooltips and CSV export

## Validation

- pnpm --dir packages/contracts exec vitest run src/sis-enrollment.test.ts --maxWorkers=1

- pnpm --dir chat exec vitest run components/dashboards/admissions/enrollments/sis/types.node.test.ts components/dashboards/admissions/enrollments/sis/__tests__/derivation.node.test.ts components/dashboards/admissions/enrollments/sis/__tests__/sis-enrollments-matrix.test.tsx components/dashboards/admissions/enrollments/sis/__tests__/sis-enrollments-export-button.test.tsx --maxWorkers=1

- pnpm --dir chat typecheck

- pnpm --dir packages/contracts typecheck

- pnpm lint:test-architecture

- affected-file biome check

Closes #1667

Linear: [AI-971](https://linear.app/builder-team/issue/AI-971/define-rhodes-as-edu-ops-own-dataset-on-the-rhodes-dss-front)

## Summary

Feedback from Artie, JC and Colin (Ops Automation Trilogy, 2026-10-06): the DSS should describe Rhodes as its own thing, not "a subset of Aerie".

- what now defines Rhodes: Edu Ops' database of record for the school site portfolio, one record per site enriched across its lifecycle, owned by Edu Ops, served read-only and unchanged.

- when describes the questions Rhodes answers and routes other systems' data away, without naming Aerie.

- OpenAPI description leads with Rhodes and states plainly that it is served through the Aerie API at the same paths.

- Aerie is still named where a caller needs it: the how clause (base, key, where to create one) and Enablement. A test now asserts both halves.

No change to routes, dispatch or behaviour.

## Verification

pnpm check: 46 tests pass. pnpm build succeeds.

## Still open

- Scope of "all of Rhodes": some Rhodes tables and site fields have no Aerie API route.

- "Rhodes API keys": the key is still an Aerie API key.

## Business Value

Aligns the DSS's public definition with how its owners describe their data, which is the definition other teams' agents read first when deciding whether and how to use it.

## Manual Effort Estimate

Proposed: about 1 hour by hand. Keval to confirm or adjust.

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

The weekly Ramp Spend run could finish researching every cost opportunity and then abort on one invalid AI ranking. Its missing final artifact also caused the Monday Superbuilders report to fail. Prioritization now gets at most three model/validation attempts, sends validation feedback back to the model, and checkpoints only a fully validated ranking. Identification and research remain reusable after failure.

## Business Value

Restore the weekly Superbuilders spend report and retain completed cost-saving research when an AI ranking needs correction.

## Implementation Effort

Approximately 3–4 hours for an average engineer to trace both failures, implement bounded retries, add regression coverage, and validate production recovery without AI assistance.

## Validation

- 238 Ramp Spend tests passed on the rebased main branch, including invalid/oversized rankings, feedback across transport failures, bounded exhaustion, checkpoint recovery, and propagation of unexpected errors.

- Modified Python files passed CI-pinned Ruff 0.15.22 lint and formatting checks.

- Isolated production CDK diff showed only the Ramp Spend ECS task-definition image changing.

- Production preflight confirmed 40 transformed weeks, an unchanged checkpoint input fingerprint, and all 24 checkpointed research results passing validation.

- The existing production runner successfully resumed all 24 completed research results, selected five opportunities, and published the week-40 cost artifact (run d36db3d0-5dba-488c-bf22-d484cb5ec5c2).

- All financial/cost/chart contracts and freshness checks passed before the Monday schedule_2 rerun. Report run 6ee3f746-5ae4-4bd2-8ef0-764f7b112a02 succeeded; its group-scoped receipt confirms an SES send to the seven approved recipients without forcing a resend.

- The six-file fix patch and all three AWS-tested runtime module checksums are unchanged after rebasing onto main as commit aa82d33a.

- Candidate commit 11728b75 passed an isolated AWS Fargate validation on the exact deployed image digest sha256:5744e501fd8a574327b9e23de5ee6bc0d09690785de3ad4b65d82c800a8e29bf. The three changed Python modules were checksum-verified and loaded from temporary storage. Task 57c02df8275e4f18811f256256f25176 exited with code 0.

- An injected empty ranking triggered validation feedback and one real Anthropic retry, selecting five valid opportunities with $51,163 estimated monthly savings while reusing all 24 research results. The downstream report contract passed. An always-invalid ranking stopped at exactly three attempts and wrote no checkpoint.

- This validation invoked no pipeline Chat notifier or email sender; log forwarding was disabled on the temporary task so its injected failures could not trigger production log alerts. All 46 protected S3 objects, including the published report, research checkpoint, chart, classifications, delivery receipt, and 40 weekly inputs, remained unchanged. Test writes were confined to s3://ramp-pipeline-data/validation/ramp-prioritization/20261005T104405Z-56c310af/; result.json contains the evidence. The temporary task definition was deregistered after completion.

- Permanent rollout remains pending: the production pipeline still references task-definition revision 15 and its CloudFormation stack was unchanged. The AWS test above ran candidate code temporarily inside the deployed image; it did not install a new production image. This draft remains unmerged pending the required candidate pipeline deployment and validation.

## Linear

[SURTR-1597](https://linear.app/builder-team/issue/SURTR-1597/retry-invalid-ramp-cost-prioritization-and-recover-week-40-report)

## Summary

- Sort Put Hedges — Mark-to-Market rows by expiration date, earliest first.

- Preserve source/API order and existing calculations.

## Verification

- Direct ESLint check on the changed file

- Prettier check on the changed file

- TypeScript check (pnpm tsc -p tsconfig.app.json --noEmit)

- Production build (passed with Browserslist and large-chunk warnings)

- git diff --check

- Vitest not run.

## Screenshots

<img width="1464" height="716" alt="image" src="https://github.com/user-attachments/assets/6e0ac7f6-d5ad-4864-9c86-e94dae497612" />

## Summary

- Add active put tranches from the exact Puts Detail workbook tab to the existing SpaceX hedge projection while retaining historical rows from Net Shares vs Hedge Dashboard.

- Carry exact source-tab and row lineage through staging and Core, and add migration 009 to preserve existing dashboard lineage.

- Preserve complete Goldman reference ranges, require positive Current Cost for active-tab puts, and reject populated rows without an expiration date. Historical dashboard handling remains compatible.

- Keep Klair's existing consumer calculations unchanged.

## Verification

- Projection-refresh runner: 137 tests passed.

- Ruff check and format checks passed.

- Read-only code review found no Critical, Important, or Minor issues.

## Redshift status

- Migration 009 and the initial projection were run locally against remote Redshift as authorized. The published projection contains 11 hedge rows: 5 from the historical dashboard and 6 from Puts Detail; staging/Core parity was confirmed.

- Thirteen sandbox_finance table backups were retained under the spacex_bak_20261006_030126_ prefix.

- This PR adds a stricter Core procedure check for positive active-tab cost. That follow-up procedure update has not been reapplied to Redshift, and no projection was rerun for this review fix.

- No Lambda/CDK deployment was performed.

## Summary

- Preserve HubSpot P&L enrollment divisors through SY25/26 and apply Dave's confirmed Alpha Finalsite rule from SY26/27.

- Pin quarter-end observations, retain exact quarter lineage and SY history ceilings, and reject unusable inputs before publication.

- Add regression fixtures, independent tie-out support, a temporary-table Redshift validator, and rollout/backfill guidance.

## Why

SURTR-1501 tracks "Enrollment Data - URGENT": the September 18 change applied the historical HubSpot rule to every school year, understating enrollment and inflating per-student amounts. Dave confirmed the school-year split on September 23; the Finalsite trigger prerequisite (SURTR-1505) has merged.

The live warehouse also contains the separate alpha-enrollment-denominator-v1 Finance sidecar from codex/alpha-enrollment-denominator (abf0e77f), which was absent from main. This PR includes that existing source change so the corrected procedure preserves its deployed contract and runner checks. Its columns already exist in production.

Test exclusions read accepted clean contacts because the Core contact fact has already removed test records. SY lineage records the latest selected publication as the history ceiling; each quarter retains its exact observation.

## Business Value

Correct Alpha per-student financials while preserving historical enrollment semantics and exposing the source behind each divisor.

## Test plan

- [x] 281 financial-runner and QuickBooks DDL tests pass, including executable SQL fixtures.

- [x] Redshift temporary-table validation: 204 historical cells unchanged, Miami Q1 divisor 108, no incomplete lineage or wrong historical source.

- [x] Independent tie-out query: 188 quarter count/lineage comparisons across 47 schools, zero mismatches.

- [x] New/updated validation scripts pass Ruff; the existing sibling lock-order test file has unrelated pre-existing lint findings.

- [x] Full private-output preflight: P&L, classification, Guide and Other HC passed; all nine applicable runner postchecks passed. Facilities correctly rejected an existing School mapping/posting generation mismatch.

- [x] User-approved self-review after Mercy runner failure; no blocking row-logic finding.

- [x] QuickBooks Core refresh and complete five-procedure private preflight passed, including all ten runner postchecks.

- [x] Applied and catalog-verified procedure, four comments, ownership/security mode, and audited version 2026-10-05.1.

- [x] Corrected financial refresh succeeded through the pipeline platform; all ten published runner postchecks passed.

- [x] Independent divisor, source, lineage and per-student checks passed on 16,937 published P&L rows across 2017–2027. Miami SY26/27 Q1 divisor is 108.

- [x] Independent Finance sidecar recomputation pinned to the recorded raw publication: 114 available period counts checked; zero count, status, source-lineage or policy mismatches.

- [ ] Verify published results against Finance's exact 36-campus cohort and notify Dave before closing SURTR-1501.

The correction has been applied to the warehouse and refreshed successfully. Initial validation used private tables before publication. The procedure signature is unchanged; no runner deployment is required. Rollout and replay steps are in ENROLLMENT_DIVISOR_CORRECTION.md beside the runner.

Mercy initially failed to acquire a hosted runner. The user approved self-review and rollout, treating nonblocking review findings as follow-ups. All normal CI checks pass on 912901ba. GitHub still requires one approving review; Mercy subsequently acquired a runner on this head. Finance's exact historical 36-campus cohort and Dave notification remain ticket closeout items.

Follow-up validation improvement: the existing Finance CLI tie-out selects the latest raw Finalsite boundary, so normal source advancement after a mart refresh can produce source-lineage false positives. Recorded-boundary recomputation passed; pin that CLI path to published Finance lineage or report source advancement as inconclusive. This does not require rollback of the correction.

## Summary

- derive compact active-application deposit rollups from the existing Pipeline mart fields at Program and exact-school-year grain

- publish and prune the rollups atomically with the Admissions Pipeline domain, including explicit zero cells

- add the metric to the v2 Pipeline DTO, OpenAPI schema/examples, and DSS semantic/workflow guidance without changing the report matrix

## Validation

- pnpm --dir sync exec vitest run src/analytics/admissions/pipeline-refresh.test.ts --maxWorkers=1

- pnpm --dir chat exec vitest run convex/admissions/admissionsPipeline.test.ts --maxWorkers=1

- pnpm --dir chat exec vitest run convex/publicApi/v2/admissions.test.ts --maxWorkers=1

- pnpm --dir chat exec vitest run lib/public-api/v2/domains/admissions.node.test.ts --maxWorkers=1

- pnpm --dir chat exec vitest run lib/public-api/v2/openapi.node.test.ts --maxWorkers=1

- pnpm typecheck

- pnpm lint:test-architecture

- pnpm lint:read-bounds

Closes #1668

## Summary

- add strong vertical dividers at school-year boundaries and after grouped metric blocks

- tint Year Start and next-year transfer columns with opaque theme-aware fills

- cover header, body, and totals styling with focused matrix tests

## Validation

- pnpm --dir chat exec vitest run components/dashboards/admissions/enrollments/sis/__tests__/sis-enrollments-matrix.test.tsx --maxWorkers=1 (20 passed)

- pnpm biome check chat/components/dashboards/admissions/enrollments/sis/sis-enrollments-matrix.tsx chat/components/dashboards/admissions/enrollments/sis/__tests__/sis-enrollments-matrix.test.tsx

- pre-commit typecheck-chat

- git diff --check

Linear: [AI-970](https://linear.app/builder-team/issue/AI-970/document-self-serve-aerie-key-creation-and-required-scopes-in-the)

Benji's follow-up: clarify how users create their own keys and which grants they need, so nobody has to email Keval.

## Summary

- Enablement gains a "Get an Aerie API key" section: the Aerie API Keys page (https://edu-ops.klair.ai/tools/api-keys), the create steps, expiry options, editing and revoking, and what to do when a scope is not offered.

- Required scopes table: which Aerie scope each route family needs. Four cover the core surface (Portfolio, Buildout, Real Estate, Diligence); Operating, Backup Site Contracts and Audit Read are each needed for one route only, with a warning that Audit Read is wider than change history when used directly against Aerie.

- Skill front: the access clause now reads "Create your own Aerie API key at <contact>", and the registration preflight matches the new wording. Deploying with FeedbackKeyContact set to the key page URL removes Keval's email from the front.

## Evidence and limits

- Steps, labels, expiry options and permission names come from the Aerie source (chat/components/profile/api-keys-profile-page.tsx, packages/contracts/src/capabilities.ts). The scope-to-route mapping comes from x-aerie-capabilities in the pinned OpenAPI snapshot.

- Not verified by clicking through the live Aerie UI.

- There is no Rhodes scope preset in Aerie; the doc lists individual scopes.

## Verification

pnpm check: 46 tests pass. pnpm build succeeds.

## Business Value

Makes access self-serve: RT and other consumers can create a correctly scoped read key themselves in a couple of minutes instead of waiting on one person, and are steered away from over-broad or write-capable keys.

## Manual Effort Estimate

Proposed: about 2 hours by hand (reading the Aerie key UI and capability registry, mapping scopes to routes, writing). Keval to confirm or adjust.

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

Linear: [AI-969](https://linear.app/builder-team/issue/AI-969/apply-benjis-rhodes-dss-review-44-operation-surface-document-searches)

Applies Benji's review of the deployed Rhodes DSS (handoff of 2026-10-05). Not deployed: rollout is a separate decision after review.

## Summary

- Allowlist is now the agreed 44 operations: 42 GET reads and two POST document searches, in src/aerie/allowlist.json. Removed all 14 directory routes, all 3 governance routes, and the site's integrations and data-sheet routes.

- Document searches: the two search POSTs are forwarded. Their body is validated against Aerie's contract (trimmed non-empty query up to 2000 code points, optional limit 1-10) and rebuilt before forwarding, so no other POST payload can reach Aerie. Every other POST, PATCH and DELETE still returns 404 route_not_published.

- OpenAPI is now Aerie's own contract for the selected operations, from a pinned snapshot generated by pnpm sync:openapi: parameters, request bodies, response schemas and media types (including the binary contract download), required capabilities and rate tiers. All $refs resolve inside the document.

- Dictionary and Enablement are Benji's JC-derived drafts, with the internal review header and handoff references removed.

- Pass-through wording: the front, OpenAPI description and README now say this is a selected subset of Aerie API v2 at the same paths, not a separate API.

## Reconciliation of the drafts against Aerie's contract

- A new test fails if the documents cite an unpublished route or a query parameter the operation does not declare. All citations pass.

- One discrepancy found and corrected: the site list limit default is 25, not 50.

- Spot-checked and consistent: the ten milestone keys, sensitive-tier operations, and the enums for documents, requirements, cost estimates, change-history resources and Insights filters.

- Not verified: the 120/min and 10/min rate budgets (not stated in the contract), and field-by-field response coverage.

## Verification

- pnpm check: 46 tests pass. pnpm build succeeds.

- Local build against production Aerie with a temporary key: list with filters, both searches, filtered change history, quality bars, cost breakdowns and backup-site return 200; a search body with an extra field returns 400; POST to notes and the excluded routes return 404.

- Binary relay is covered by a unit test only. The real contract download was not exercised (confidential, needs an extra grant).

## Still open (owner decisions, not in this PR)

- Key-acquisition steps: Enablement points to the how.native.auth clause of /api/skill, which currently says to email Keval. The Aerie UI steps, eligibility and any Rhodes read preset are unconfirmed.

- Grants for admin.audit.read (change history) and operations.backupSiteContracts.read (contract download).

- Owner ratification and keyed semantic evaluation of the definitions.

- The feedback key check should move to /portfolio/sites?limit=1 at next deploy (it currently uses a directory route that is no longer published here, though still valid upstream).

## Review note

The diff is large because of src/aerie/openapi.snapshot.json (generated, ~800 KB). The hand-written change is the allowlist, src/aerie/*.ts, the two documents, tests and README.

## Business Value

Brings the Rhodes DSS in line with what RT and JC asked for: only Rhodes data is reachable, agents get field-level definitions and worked read sequences instead of a bare route list, and document search works. This is the difference between a reachable endpoint and one an agent can use correctly.

## Manual Effort Estimate

Proposed: about 1.5 days by hand (allowlist and search forwarding, contract snapshot tooling, reconciling two long documents against the contract, tests). Keval to confirm or adjust.

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

## Summary

- require the upstream is_applied_on_or_after_event = true flag in marketing-event application aggregates

- keep pre-event application dates visible while removing their event-outcome classification from contact detail

- extend the Gateway contact contract and clarify dashboard, API, and agent-tool descriptions

## Validation

- pnpm --dir sync exec vitest run src/analytics/queries/educrm.test.ts src/analytics/queries/admissions-marketing-gateway.test.ts src/analytics/admissions/marketing-events-refresh.test.ts (245 passed)

- pnpm --dir chat exec vitest run lib/public-api/v2/openapi.node.test.ts components/dashboards/admissions/events/__tests__/derivation.node.test.ts components/dashboards/admissions/events/__tests__/events-mobile.test.tsx components/dashboards/admissions/events/__tests__/event-detail-panel.test.tsx (51 passed)

- sync, contracts, and Chat typechecks

- sync Biome check

Closes #1664

## Summary

- Capture active and historical deleted billing records through the existing pipeline using include_deleted=true.

- Expose creation/deletion timestamps, actors, amounts and account/contact identifiers in billing_deletion_history, and include confirmed events in billing_removals_observed without duplicating matching inferred transitions.

- Keep current views and the billing activity mart active-only; block historical capture until their updated warehouse definitions are installed.

## Why

Finance cannot match surviving credits to charges deleted before Surtr's first September 3 snapshot. The earlier snapshot-removal and finance-report changes do not supply those records. Finalsite's Billing > Audits screen uses the same billing endpoint with include_deleted=true, which the current runner omits.

A read-only Austin check found 4,022 ordinary items versus 4,838 with deleted records included. Byron Attridge's complete 14-item account includes a +2,355 charge deleted July 29 and its surviving -2,355 credit, demonstrating the missing historical matched-pair evidence.

## Business Value

Finance can retrieve historical deleted charges and source deletion dates for the August/September revenue workings, while existing current billing consumers continue to exclude deleted charges.

## Breaking changes

The raw source contract advances to finalsite-internal-billing-items-with-deleted-v2: raw publications and ledger totals now include retained deleted records. Direct raw readers must filter active parents when calculating current activity. The existing billing mart reader is updated here.

billing_removals_observed keeps its column shape but adds finalsite_source_deleted_at. For those rows, removed_at and first_missing_snapshot_at are the source deletion time, first_missing_run_id is the observation run, and last-seen run/snapshot fields are NULL. Readers must branch on provenance rather than assume every event is an inferred window.

## Test plan

- [x] Billing runner: 265 tests; billing mart: 31 tests.

- [x] Ruff check/format and git diff --check.

- [x] Execute canonical view SQL in local fixtures for repeated captures, failed snapshots, source/inference deduplication, active views and mart allocation counts.

- [x] Replay the real Austin first page: 500 parents, 382 active parents and 916 allocations; parent/allocation totals both 1,271,760.69.

- [x] Replay Attridge's real complete account through the extractor and actual view SQL locally: 14 parents / 26 allocations; all 35 deletion-history rows match source IDs, account/contact links, amounts, Created On/By and Deleted On/By field by field. The surviving -2,355 credit remains current. Local view tests translate SUPER scalar casts for DuckDB; separate native Redshift fixtures validate those casts and null actors.

- [x] Billing DDL dry run: 19 statements. Applied the mart procedure and canonical billing definitions to production finance_dw on October 5 for controlled validation; all 536 existing direct grants, procedure owner/OID and execute grants preserved. New history SELECT mirrors existing removal-view reader roles.

- [x] Read-only Redshift execution of the proposed combined query preserves current inferred counts (1,254 items / 2,901 allocations; statement fcfc457c-7b4e-453d-bb1d-8f7fa5bb1822). Native synthetic checks return two confirmed and two inferred rows with correct timestamps and preserve null actors.

- [x] Controlled production Austin capture using the branch runner, deployed configuration, real single-flight lease, immutable S3 landing, atomic publication and terminal run-result side channel: finalsite-audit-validation-20261005T192300Z; 10 source pages, 4,838 parents / 8,854 allocations; v2 ledgers complete and parent/allocation totals both 7,913,725.29.

- [x] Native Redshift comparison of all 2,510 source-confirmed history rows (816 parents / 1,694 allocations) against the immutable source responses: IDs, account/contact links, amounts, Created On/By and Deleted On/By match field by field. 2,362 rows predate September 3; earliest deletion November 12, 2025. Statement 8a88ac26-6474-452e-ad93-57d1f73519a0.

- [x] Active views contain 4,022 parents / 7,160 allocations and parent total 5,624,970.29, matching the active source subset; no deleted records leak into current views. Attridge has all 35 expected history rows and retains only the -2,355 credit / -50 payment as current. Other 52 current sites unchanged. Keval and Finance automation SELECT access verified.

- [ ] Release the runner and complete the estate-wide historical capture, Veiga/Bernardi checks and tenant/campus coverage reconciliation. The controlled local run did not deploy the scheduled runner or invoke delivery/mart refresh pipelines.

## Review follow-up

Mercy identified that confirmed rows populated last_seen_source_extracted_at with the deletion capture time despite the NULL last-seen contract. The correction returns a typed NULL and adds a regression covering confirmed parent/allocation rows alongside unchanged inferred timestamps. Capture time remains available in billing_deletion_history.observed_at.

- [x] Corrected projection executed read-only against production data: 2,510 confirmed rows have all last-seen fields NULL; all 4,058 inferred rows retain their extraction timestamps; total row counts unchanged.

- [x] Applied only the corrected removal-view definition to production finance_dw under the real single-flight fence: finalsite-view-patch-20261005T194306Z. All 2,510 confirmed rows have NULL last-seen fields; all 4,058 inferred rows retain timestamps. Bidirectional EXCEPT against the corrected query returns zero differences; view owner/OID and reader grants preserved.

- [x] All CI checks passed on c06e625c2dd4b8be0db156e065da062382bffd5f. Mercy verified the prior finding is fixed and found no additional defects. The owner approved the correction discussion and successful warehouse apply before merge.

## Rollout

1. Already applied for Austin validation: the updated billing mart procedure; both its activity candidate and source-count control exclude deleted parents.

2. Already applied canonical billing DDL through the grant-preserving helper; verify the filtered current views, new deletion-history view and combined removal view.

3. Already mirrored and verified Finance's access to billing_deletion_history, retaining existing removal-view access.

4. Release the billing runner through the normal production path. Runtime preflight rejects missing history views, unfiltered current views or the old mart procedure before authentication/publication.

5. Use a fresh run ID for Austin, reconcile Attridge and active controls, then capture the configured estate. Verify source-version v2 ledger rows/counts, Veiga and Bernardi, and coverage of Finance's 53 campuses against the configured 59 tenants before revenue reruns.

The daily schedule, immutable source landing and atomic per-site publication are reused. The warehouse procedure/views and reader access are already applied and validated; this PR records that logic and releases the recurring extractor change. The scheduled production runner still uses its prior source query until release. Historical coverage currently includes Austin only; do not treat this validation as an estate-wide backfill. Amount-line deletion timestamps/actors describe the parent deletion; independently removed allocations still use inference. Parent contact IDs are NULL for potentially multi-contact parents; allocation rows supply contacts. Missing actors remain NULL, and coverage is source-returned history rather than a proven inception guarantee.

Linear: [AI-968](https://linear.app/builder-team/issue/AI-968/publish-rhodes-read-routes-and-deploy-rhodes-dss-to-aws)

## Summary

- Publishes 61 read routes from Aerie API v2 (https://edu-ops.klair.ai/api/v2): directory (14), portfolio (40), insights (4), governance (3). Paths are the Aerie paths without the /v2 prefix.

- Selection follows Benji's guidance on the 2026-10-05 call: keep directory, portfolio, insights and governance; drop forge, agent, finance, admissions and ontology.

- Also excluded: every write, all of API v1, Aerie's own /meta and /openapi.json, and two portfolio sections whose values come from other sources: enrollment-summary (admissions forecast) and school-calendar (calendar sync).

- Forwards Content-Disposition so the backup-site contract download keeps its filename.

- scripts/provision-deployment.mjs now requires Keval's administrator IAM identity instead of Benji's.

- Dictionary and Enablement describe the published areas and the exclusions.

## Verification

- pnpm check: 42 tests pass, including the route-list well-formedness test over all 61 routes. pnpm build succeeds.

- The Aerie base URL was confirmed to answer 401 application/problem+json without a key.

- Not verified: any route with a real Aerie key. No route's response was inspected.

## Business Value

Makes the Rhodes DSS useful: RT's agents can read Rhodes portfolio, buildout and work-management records directly, with other sources' data kept out.

## Manual Effort Estimate

Proposed: about 3 hours by hand (triaging ~200 Aerie endpoints against the keep/remove rules, checking sources, docs). Keval to confirm or adjust.

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

Linear: [AI-967](https://linear.app/builder-team/issue/AI-967/scaffold-standalone-rhodes-dss-as-an-aerie-pass-through-service)

## Summary

Turns the Redshift-DSS template (the unmodified baseline on main) into a standalone DSS for the Rhodes dataset.

- /api/v1 is now an allowlisted, read-only pass-through to the Aerie API (src/aerie/). Only GET routes listed in src/aerie/routes.ts are forwarded; everything else returns 404 route_not_published without contacting Aerie.

- Callers use their own Aerie API key (aerie_sk_…), forwarded unchanged. Aerie stays the authority on access and rate limits. The service holds no upstream credential.

- Removed: Redshift driver and SQL layer, API-key registry and import scripts, Secrets Manager wiring, Redshift security-group ingress, and the Redshift dictionary/enablement content.

- Feedback keeps the template's behaviour but authenticates by verifying the caller's Aerie key against one configured Aerie route; operator triage is granted by configured key digests.

- Infra is reduced to ECS Fargate + HTTPS ALB + feedback table. Dependency versions are pinned exactly.

## Not in this PR

- The route list is empty. The service publishes its DSS documents and forwards nothing until the Rhodes endpoints are added.

- Nothing is deployed. No AWS resources, DNS (rhodes.dss.klair.ai), certificate or GitHub deployment variables exist.

- Dictionary has no object definitions yet.

- scripts/provision-deployment.mjs still requires the template's hardcoded administrator IAM user and VPC; both need review before it can be applied.

## Verification

- pnpm check: 42 tests pass across 11 files; lint reports 2 warnings inherited from the template.

- pnpm build and pnpm synth --no-lookups succeed.

- Local smoke test of the built service: /api/skill, /api/dictionary, /api/v1/openapi.json, /healthz return 200; an unpublished route returns 404.

- Not run: the Docker build, and any request against the real Aerie API.

## Business Value

Gives RT a direct, Rhodes-only DSS endpoint that returns Aerie's raw records without another team's reshaping in between, which is the DSS direction leadership asked for. Because callers reuse their existing Aerie keys, there is no new key issuance or access process to run.

## Manual Effort Estimate

Proposed: about 1.5 days of focused work by hand (understanding the template, writing the proxy and auth, reworking infra, tests and docs). Keval to confirm or adjust.

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

## Summary

This PR is the Aerie follow-up integration slice for [AI-867 — Praxis Hosted v0](https://linear.app/builder-team/issue/AI-867/praxis-hosted-v0-run-author-defined-pr-verification-on-demand).

It hardens Aerie’s canonical Preview setup so Praxis can prepare and verify an ordinary product PR without that product branch carrying Preview infrastructure changes. This slice is tracked by [AERIE-2720 — Make canonical Preview setup reusable by Praxis PR verification](https://linear.app/builder-team/issue/AERIE-2720/make-canonical-preview-setup-reusable-by-praxis-pr-verification).

Production effect: compatibility hardening. Existing local project-scoped Preview setup remains supported; the same entry point now also accepts and targets an already-created, deployment-scoped Praxis Preview.

---

## Why

Praxis creates an expiring Convex Preview before invoking Aerie’s canonical setup. The merged Aerie runner only accepts project-scoped keys and assumes it must create the deployment itself, so an ordinary PR fails before investigation unless it also carries the compatibility repairs. Those repairs were incorrectly accumulated on product test PR #1620; this slice gives them a dedicated, reusable home.

---

## Business Value

- Lets Praxis verify ordinary Aerie PRs without contaminating their product diffs.

- Keeps Preview creation, configuration, setup, readiness, and failure reporting on the real Aerie path.

- Preserves tightly scoped Convex access and produces useful, secret-safe setup diagnostics.

- Keeps local Preview development compatible with the existing project-scoped flow.

---

## How does it work

1. preview.ts accepts either the existing project Preview key or a deployment-scoped preview:/dev: key, and verifies that a scoped key names the expected deployment.

2. When the deployment already exists, the Convex CLI selects it through CONVEX_DEPLOY_KEY rather than asking convex deploy to create another Preview.

3. Archived PR source supplies and validates its exact source revision without requiring .git metadata inside the investigator container.

4. Each canonical setup boundary emits one closed, secret-safe phase/code diagnostic if it fails.

5. Preview readiness reports the populated enrollment-cohort count through a bounded query and validates that the canonical product dataset is usable.

---

## Scope

### Included in this phase

- Support Praxis-owned deployment-scoped Convex Preview keys.

- Target the exact existing Preview for deploy, seed, reconciliation, and readiness commands.

- Validate git-archive source identity.

- Add safe setup-failure classification.

- Bound and align Preview readiness counts.

- Add focused regression coverage.

- Exact final diff paths:

chat/convex/praxis/readiness.ts
chat/convex/praxisReadiness.test.ts
chat/convex/previewDataset.test.ts
chat/scripts/configure-convex-preview.ts
chat/scripts/preview.node.test.ts
chat/scripts/preview.ts

### Deliberately excluded for later phases

- Portfolio opening-date behavior from AERIE-2334 — remains isolated in PR #1620.

- Praxis workflow, AWS runtime, model, or release changes — this is only Aerie’s canonical Preview boundary.

- Any production or staging data migration, backfill, or automatic external execution.

- New setup commands or README-facing developer workflow changes; pnpm preview and pnpm preview -- --deploy-only remain the canonical commands.

---

## Test plan

### Automated validation

- Preview setup and readiness regression group — 46/46 passed (pnpm --dir chat exec vitest run scripts/preview.node.test.ts convex/praxisReadiness.test.ts convex/previewDataset.test.ts --maxWorkers=1)

- Chat and Convex typecheck — passed (pnpm --dir chat typecheck)

- Biome on all six changed paths — passed

- Test architecture — passed (pnpm lint:test-architecture)

- Architecture boundaries — passed (pnpm lint:boundaries)

- Convex module paths — passed (pnpm lint:convex-paths)

- git diff --check origin/main...HEAD — passed

- Exact-head diff scope — only the six paths listed above

### Time for Implementation

About two days for an engineer to isolate the provider mismatch, harden the canonical setup boundary, add safe diagnostics and regression coverage, rebase onto current main, and validate the slice.

## Summary

- extend the SIS enrollment contract and publication with the six start-of-year transfer and re-enrollment cohorts

- compose Summary year Y from current metrics at Y and Next Year metrics at true enrollment year Y + 1, while leaving By Levels unchanged

- add band-aware matrix/export behavior and true-year student drill-down details for transfers and declined outcomes

- preserve rolling compatibility with the active pre-change publication through nextYearDataAvailable

## Data and rollout

- no public Admissions API changes

- no new dbt cohort classification; this consumes the source contract merged in #1653

- the A8 rollup/member copies must be rebuilt with the expanded cohort allowlist and seven new member columns before enabling the new publisher

## Validation

- pnpm lint

- pnpm typecheck

- pnpm test (all workspace suites and root checks)

- focused SIS contract, sync legacy/Gateway, Convex, matrix, export, and student-panel tests

Closes #1660

## Summary

- publish normalized SIS enrollment-level membership and seven-cell On Campus rollups atomically with the existing SIS publication

- add capability-protected level matrix and generation-safe level-cell student reads

- add URL-backed Summary / By Levels dashboard switching, filtered totals, sorting, CSV export, and drill-downs

## Validation

- pnpm typecheck

- pnpm lint:test-architecture

- pnpm lint:read-bounds

- pnpm --filter @bran/contracts exec vitest run src/sis-enrollment.test.ts

- pnpm --filter @bran/sync exec vitest run src/redshift/sis-enrollment.test.ts src/analytics/sis-enrollment-refresh.test.ts src/analytics/sis-enrollment-gateway.test.ts --maxWorkers=1

- pnpm --dir chat exec vitest run convex/admissions/sisEnrollment.test.ts components/dashboards/admissions/enrollments/sis/sis-route.node.test.ts components/dashboards/admissions/enrollments/sis/__tests__/derivation.node.test.ts --maxWorkers=1

- pnpm --dir chat exec vitest run components/dashboards/admissions/enrollments/sis/__tests__/sis-enrollments-export-button.test.tsx components/dashboards/admissions/enrollments/sis/__tests__/sis-student-panel.test.tsx --maxWorkers=1

Closes #1657

## Summary

- remove every built-in tool from the one-turn Claude Quality Bar judge

- retain the existing permission allowlist as defense in depth

- lock the tool-free invariant into the judge configuration test

## Root cause

allowedTools: [] controls permission but does not remove tools from the Claude Agent SDK context. With bypass permissions enabled, the judge could call Bash. On a complex captured Aerie payload it spent its single allowed turn on that tool call, terminated with error_max_turns / stop_reason: tool_use, and exposed an empty result that was reported as an unparseable verdict.

tools: [] removes all built-in tools from the judge context.

## Validation

- regression test went red before the fix

- agent-runner suite: 199/199 pass

- agent-runner TypeScript build: pass

- scoped Biome: pass

- exact captured failing Aerie attempt-3 payload: previously deterministic empty verdict; after fix returned quality_bar_met: true in 4.1 seconds

## Summary

- Bump Shipyard from 0.6.11 to 0.6.12.

- Publish the approved notes for Feature Discovery and task prompt evaluation.

## Business Value

- Help users understand the Research workflow through an in-app guide.

- Let users evaluate completed task prompts with captured, independent replay evidence before publishing improvements.

## Implementation Effort

- Metadata-only change: version field and public release notes.

- Release validation passed locally; CI will build, audit, sign, and publish the Apple Silicon artifacts.

## Test plan

- pnpm test:release

- git diff --check

## Summary

- Lock Due Diligence fields and scenarios when M2 Conducting Diligence is completed; reopening M2 restores editing.

- Add an explicit emergency override capability while preserving existing write and approval permissions.

- Show a compact lock indicator with an accessible tooltip and enforce the rule on submission and approval across UI, API, and MCP.

## Why

[AERIE-2808](https://linear.app/builder-team/issue/AERIE-2808) implements the DD canary for the forward-facing editing lock project. Completed diligence should remain stable, including when an older proposal reaches approval after M2 completes.

## Business Value

Users can see when diligence is locked, while explicitly authorized operators can make emergency changes without reopening the milestone.

## Test plan

- [x] Full CI green at 52da69ca8; Chat: 12,256 tests passed, 18 skips across 816 files.

- [x] 449 focused tests passed; 17 existing DD skips. Submission, approval, scenario operations, override permissions, and UI states use isolated mocks.

- [x] Workspace typecheck, changed-file Biome, architecture, Convex, testing, and knowledge checks.

- [x] Read-only localhost inspection of completed M2, lock tooltip, collapsed card, and scenario tabs. No DD save, approval, upstream writeback, milestone change, or capability grant.

CI also exposed two role-editor test fixtures using the old grant count and omitting Admin grants; corrected both and verified override remains ungranted for ordinary editors. All 18 role-editor tests pass.

Seven independent review lanes completed; fixed the approval timing gap with a fresh authority check after the metadata GET and a deferred-GET regression test asserting zero POSTs.

UI preview: compact 14px lock in a 24px container; reason appears in the Radix tooltip.

Validation limitation: the current lifecycle and actor authority are checked immediately before REBL3 dispatch. Convex milestone changes and external REBL3 writes are not atomic; this canary does not cancel an already dispatched write. Mercy raised this distributed timing limit; the response records why broader milestone serialization or a conditional upstream protocol is outside scope.

## Summary

This PR is Phase 1 of 2 for [AERIE-2744: Launch and verify the complete Task Board](https://linear.app/builder-team/issue/AERIE-2744/launch-and-verify-the-complete-task-board), part of the [Human Task Assignment from Aerie project](https://linear.app/builder-team/project/human-task-assignment-from-aerie-b3582376ae6e).

It adds the shared Task engine and data contracts for lifecycle actions, approval and resubmission, assignments, completion history, comments, watchers, documents, permissions, and allowed actions.

Production effect: none of the existing Work Plan, public API, Site Note, or agent entry points switch to these rules in this PR. The Task Board remains unavailable. Phase 2 changes all of those entry points together.

## Why

The complete launch change is too large to review safely as one PR. This first phase establishes the internal foundation without changing existing Task workflows. That avoids a temporary compatibility layer and avoids an intermediate release where old screens call new rules they do not yet understand.

## Business Value

- Establishes one shared Task lifecycle and authorization model for the launch.

- Records assignments, completion attempts, reviews, comments, documents, and watchers consistently.

- Gives callers a calculated list of actions that are valid for each Task.

- Keeps the current production Task workflows unchanged until Phase 2 activates the complete API and agent experience.

- Reduces review and rollout risk by separating the engine from its entry points.

## How does it work

1. Shared modules define Task lifecycle actions, approval, assignment, completion, comments, documents, watchers, and allowed actions.

2. Indexed participant records support bounded My Tasks and authorization queries.

3. Existing production entry points continue using their current behavior while the Task Board launch gate is closed.

4. Phase 2 will switch the Work Plan, public API, Site Notes, and agent tools to this engine together.

## Scope

### Included in this phase

- Canonical Task lifecycle, approval, resubmission, completion history, assignment, document, watcher, and notification contracts.

- Shared Task action availability and metadata authority.

- Bounded participant and completion-history queries.

- Internal data model and migration support needed by the launch.

- Exact final diff paths:

chat/convex/lib/siteDetailAccess.ts
chat/convex/migrations/taskParticipants.ts
chat/convex/rhodes/schema.ts
chat/convex/taskBoard/actionAvailability.ts
chat/convex/taskBoard/approval.test.ts
chat/convex/taskBoard/approval.ts
chat/convex/taskBoard/assignments.test.ts
chat/convex/taskBoard/assignments.ts
chat/convex/taskBoard/auth.ts
chat/convex/taskBoard/completion.ts
chat/convex/taskBoard/completionHistory.ts
chat/convex/taskBoard/documents.ts
chat/convex/taskBoard/lifecycle.test.ts
chat/convex/taskBoard/lifecycle.ts
chat/convex/taskBoard/metadataAuthority.ts
chat/convex/taskBoard/mutations.test.ts
chat/convex/taskBoard/mutations.ts
chat/convex/taskBoard/notifications.test.ts
chat/convex/taskBoard/queries.test.ts
chat/convex/taskBoard/queries.ts
chat/convex/taskBoard/watchers.test.ts