## Summary
Phase 5 of 5 of the Security standard delivery tracked in [AERIE-3012](https://linear.app/builder-team/issue/AERIE-3012). [AERIE-3048](https://linear.app/builder-team/issue/AERIE-3048) adds the administrator migration preview and privileged backend apply/activation functions, completing the approved feature after the four prerequisite slices.
Production effect: controlled rollout or migration. Merging exposes the preview and authorized backend operations; it does not migrate a site or activate the model. Apply and activation require separate explicit calls. The admin panel offers site listing, preview and CSV download only.
## Why
Existing sites need a reviewable transition from sixteen Security assessments to ten without losing their history or linked work. A revision-bound plan lets an operator inspect the proposed results and rejects application if the captured records change. Keeping migration and activation explicit allows the completed assessment and work paths from the preceding slices to be available before an operator initiates the transition.
## Business Value
- Administrators can compare current and proposed Security colors, points and work destinations before changing a site.
- Existing sites retain assessment identities, retired history and linked work instead of receiving replacement operational work.
- Operators can export the same preview as CSV, including attributed corrections and exclusion reasons.
- Explicit backend operations provide controlled migration and activation with actor-attributed receipts and audit records.
## How does it work
1. SecurityMigrationPanel is mounted at /admin/p2-scoring. securityAssessmentMigration.listSites requires admin.rhodesSchema.manage and returns pages of at most 50 sites. Already migrated sites have disabled preview entries.
2. previewSite loads a bounded site snapshot and builds the proposed assessment and preservation plan. The response includes current/proposed colors and points, source results, work/task/note move counts and a sourceRevision. Preview changes no records and creates no work. Optional corrections must identify the source, match its captured before-state and include human attribution. Preview exclusions affect the owner-preview designation, while technical preservation and apply eligibility still include the site.
3. The panel renders that response and downloads the same matrix through securityMigrationRows and securityMigrationCsv. Input changes invalidate the displayed preview; caught errors use the clean inline error pathway.
4. A separately invoked applySite requires the privileged capability and matching revision. It reuses ten assessment IDs, preserves six retired records as history, moves linked work/tasks/notes, updates the site marker and writes a receipt/audit entry transactionally. Existing sites receive no new operational work. A stale revision rejects before writes; repeated apply validates the migrated structure and returns the existing receipt.
5. A separately invoked activateNewModel requires the privileged capability and literal confirmation ACTIVATE_SECURITY_TEN_ITEM_MODEL. It rejects queued/running catalog publication, publishes the ten Security definitions while retaining other Quality Bar definitions and enables the rollout marker. Repeated activation returns alreadyActive. The producers and consumers needed after activation are already present in the preceding four slices.
## Scope
### Included in this phase
- Read-only admin preview UI with correction/exclusion inputs and CSV download.
- Authorized backend site listing, preview, revision-checked application, receipt validation and explicit model activation.
- Existing isolated journey test and the existing admin page test's panel mock, unchanged from the approved final snapshot.
- Incremental diff against merged main a298d18ac10a306a3df5c2c94ad2acd704d4b156: seven files, 1,527 additions and no removals. Candidate 420f4de60c4a0af813a1f7fc4d74afac57e89412 preserves the original final migration patch unchanged; both range-diff comparisons and independent review passed. All intervening main changes are retained.
- Exact final diff paths:
chat/app/(main)/admin/p2-scoring/__tests__/page.test.tsxchat/components/admin/p2-scoring/p2-scoring-page.tsx
chat/components/admin/p2-scoring/security-migration-panel.tsx
chat/convex/_generated/api.d.ts
chat/convex/rhodes/securityAssessmentMigration.ts
chat/convex/rhodes/securityMigrationSchema.ts
chat/convex/securityRepairJourney.test.ts
### Deliberately excluded for later phases
- No further implementation phase is required by this split. Cleanup, shared contracts, assessment behavior and work production/consumption are supplied by AERIE-3044 through AERIE-3047.
- Deployment, real-data migration and rollout activation remain separate operator actions; none is executed by this PR or its merge.
- Apply/activation UI buttons, completed-migration undo/recovery controls and new ownership/creation/deletion controls are outside the approved scope.
- No documentation, scripts, new test fixture files or upstream writeback are included.
## Test plan
### Automated validation
- Current candidate after synchronization onto main: existing migration journey and admin page tests 14/14 passed; full Chat app and Convex typechecks passed (exit 0); independent review confirmed the identical seven-file patch and preserved main changes.
- Earlier full-suite validation below applies to the approved cumulative source before subsequent main updates.
- Existing final-snapshot journey and admin page tests — 14/14 passed across two files: pnpm --dir chat exec vitest run convex/securityRepairJourney.test.ts 'app/(main)/admin/p2-scoring/__tests__/page.test.tsx' --maxWorkers=1. This run used the final source worktree at ee2b1fdaa72ac3de61a54af51daa08ff5bb69a29, not a preceding partial branch. Local evidence: tmp/security-pr-local/split/final-journey.log.
- The isolated journey exercises provisioning, assessment/API readback, migration preservation, retired-item handling and ordinary work edits afterward; it asserts that no external fetch occurs. The admin page suite supplies existing catalog-editor regression coverage.
- Full Chat suite: pnpm --dir chat test — passed, 851 files, 12,728 tests passed and one existing skipped test; all seven Sindri asset tests also passed. Parent resumed run exited 0 in 677 seconds. Local evidence: tmp/security-pr-local/split/final-full-chat-resume.log.
- Independent review of the extracted cumulative boundary — passed.
- Full workspace typecheck: NODE_OPTIONS=--max-old-space-size=8192 pnpm typecheck — passed (exit 0), including Chat app and Convex plus every other workspace typecheck. Only incremental TypeScript caches were copied from the checked layer 4 candidate before this run. Local evidence: tmp/security-pr-local/split/final-typecheck-resume.log.
- Normal commit hooks passed: Convex path checks, Biome and Chat typecheck. Local evidence: tmp/security-pr-local/split/final-commit-resume.log.
- Exact incremental diff scope — seven paths listed above; existing approved code and tests extracted unchanged. The original cumulative extraction matched ee2b1fdaa72ac3de61a54af51daa08ff5bb69a29; the current candidate also retains subsequent main changes. Worktree is clean.
### Time for Implementation
Estimated 3–5 engineer-days without AI assistance, assuming the four prerequisite slices are complete: plan the migration and preservation rules, implement bounded snapshot/revision checks and transactional apply/activation, build the preview/CSV panel, exercise the integrated journey, review and rebase the final slice, and prepare it for deployment. Actual deployment, migration and activation require separate operational authorization.
## Review repairs and contract clarifications
Review [5704979619](https://github.com/AI-Builder-Team/Aerie/pull/2196#pullrequestreview-5704979619), reviewed/current head 420f4de60c4a0af813a1f7fc4d74afac57e89412, tracked in [AERIE-3048](https://linear.app/builder-team/issue/AERIE-3048). Parent and independent GPT-6.1 Sol diagnosis found no valid blocker. No code or tests changed.
1. Original history versus corrected ratings — false calculation premise; historical contract clarified. The approved migration preserves original ratings and separately records attributed corrections. In securityAssessmentMigration.ts:231–235, securitySourceAssessments retains those original inputs. Lines 238–254 apply the correction before combining ratings and assign the corrected result to the new group's status. effectiveSecurityStatus in packages/contracts/src/security-assessment.ts:42–50 reads only the current status, exception, key/title; it never reads source history. scoreQualityBars calculates from that current group. Thus a Guard correction Green→Red produces Red and zero guard points, while the source history correctly remains Green. Preview explanation lines 375–377 states who changed the rating and its before/after values; lines 413 and 625 preserve corrections in the preview and receipt. The panel displays the attributed before→after correction separately from source results, and CSV has distinct Source results and Attributed input corrections columns (security-migration.ts:102–105,123,133). Rewriting original source values would change the agreed history semantics, not fix an incorrect calculation.
2. Support links to retired sources — alleged legacy state has no supported writer. securityWorkSupport.ts:74 is the only production insertion into securityWorkSupports. Its create/update and generic-work-record callers all first call resolveSecurityWork, which requires site.securityAssessmentVersion === 2 (25–26), resolves only current, nonretired v2 groups (32–34), and rejects selected IDs outside that set (49–51). Generic CRUD's table union (crud.ts:42–62) does not expose securityWorkSupports. In contrast, this migration rejects already-v2 sites (176–177) and requires sixteen current legacy groups (178–180). Therefore these support rows are created only after the site has left the migration's accepted input state. Repeat-apply validation checks links that may legitimately be added after migration; it is not evidence that legacy sites can already contain them. Remapping manually injected unsupported links is speculative repair, not a current migration defect.
3. Task carrying both a work-unit ID and a group anchor — already rejected before writes. securityAssessmentMigration.ts:307–312 calls taskRecordWithCanonicalAnchor(task) before constructing its task patch. In workManagementPublicId.ts:99–106, the exact alleged combination, anchorType === "workUnitGroup" with workUnitId !== undefined, throws. Legacy tasks with both work-unit and group IDs are also rejected at lines 122–123. Migration converts this into an explicit conflicting-anchor error and never reaches its apply writes. Valid group-anchored tasks have no work-unit ID, so lines 318–321 update their group anchor; valid work-unit tasks keep the work-unit anchor and follow their parent's move. The reported successful apply with a stale group anchor cannot pass this existing validation.
4. Empty descriptions — nonblocking metadata concern, as the review already defers. Activation may publish an empty description for new keys. The approved ten-item catalog does not supply mandatory descriptions; current catalog readers also accept/default empty descriptions. Names, identities, weights and relationships are present. No wrong score or lost work is shown. Requiring new description content is not an approved migration blocker.
5. Missing denial/failure tests — coverage gap, not a demonstrated defect, also deferred by the review. Capability checks are at migration lines 553,575,588,646; stale revisions reject at 598, pending/running catalog publication rejects at 698–701, and apply changes commit in one Convex mutation. No failing authorized or unauthorized behavior was demonstrated. We retain the user-approved reduced essential test scope.
Validation remains: 14 existing journey/admin tests passed, full Chat app and Convex typechecks passed, independent extraction/rebase review passed, and all hosted non-Mercy CI checks passed on this exact head. No production migration, activation, deployment or data write occurred. These remain separately authorized operator actions; merge does not execute them.
### Follow-up review 5705062510: type-only response import
[Review](https://github.com/AI-Builder-Team/Aerie/pull/2196#pullrequestreview-5705062510) at unchanged head 420f4de60c4a0af813a1f7fc4d74afac57e89412, tracked in AERIE-3048. Mercy withdrew every prior migration/history/link/coverage concern. Parent and independent GPT-6.1 Sol checked the remaining claim.
The claimed enforced client/server boundary failure is a false premise:
1. security-migration-panel.tsx:14 explicitly uses import type { SecurityMigrationPreview }. It imports only the response shape, not a validator, implementation, business rule or runtime value. Its query references are constructed through makeFunctionReference; no server implementation is called/imported by the client bundle.
2. CLAUDE.md:23–26 places shared business rules in @bran/contracts and keeps contracts runtime-free. It does not ban UI type-only references to server-owned response types. Shared migration formatting/CSV business logic already resides in @bran/contracts/security-migration.
3. The actual boundary checker, scripts/check-architecture-boundaries-lib.mjs:62–81, prohibits Convex importing UI, not UI type references to Convex. Its walked roots at 142–148 do not include chat/components. There is no enforced rule matching the finding. This is an explanation of the actual rule, not a proposed suppression or exemption.
4. Reran node scripts/check-architecture-boundaries.mjs at the reviewed head: Architecture boundaries OK. A local TypeScript transpileModule check using ESNext modules and verbatimModuleSyntax: true confirms both the implementation-module import and SecurityMigrationPreview reference are absent from emitted JavaScript. No source files were changed or generated.
5. Hosted CI run40953750685 at this exact head already passed Lint + Boundaries, both app/Convex typechecks, Build, and every other non-Mercy check. Thus the alleged check failure is contradicted by both the actual rule and execution.
Moving the response type could be an optional ownership refactor, but no reachable runtime failure, forbidden dependency or failed check has been demonstrated. No code/tests/commit/push is warranted for this claim. Existing migration/deployment/activation boundaries are unchanged.