fsi-agentic-wealth-transfer

# Copilot Repository Instructions

Read `.github/github-instructions.md`, `AGENTS.md`, and `Software-Requirements-Document.md` before changing this repository. The detailed rules in those files are binding.

Non-negotiable Milestone 1 constraints:

- The platform is always the receiving firm.
- Run deterministic FINRA validation before any model call.
- Account-type mismatch blocks with code `03`.
- Never fabricate an ACATS control number or unresolved `[Qn]` value.
- Hosted invocations must write to legal-hold-protected WORM Blob or fail.
- SQL, Fabric, Cosmos DB, and live ACATS submission are deferred.
- Humans own authorization changes and exception decisions.
- Portal/API workforce authentication is intentionally deferred for core-flow development. Keep
	routes public, use only server-selected synthetic workforce contexts with
	`identity_provider=development`, and never present this posture as production-ready. IAM-001/S32
	must restore Entra/SWA claims-bound authorization before real data or production use. Preserve
	Entra/managed-identity-only Azure resource access, least-privilege RBAC, Prompt Shields, and
	OpenTelemetry.
- Do not delete immutable audit containers or run destructive Azure teardown without explicit approval.

The active replacement deployment is `ai-transfer-agent` version 8 in East US 2 under azd environment `fsi-wt-dev`; the prior North Central US version 6 is retained as historical deployment evidence. Use Python 3.13 and the dependency versions pinned in `pyproject.toml`. Before committing, run the repository tests, local golden evaluation, Ruff, and Bicep validation relevant to the change.

Track C deployment completion means one successful full deployment through
`pwsh -NoProfile -File .\scripts\deploy.ps1`, which performs preflight, preview, and `azd up`.
Run `29794555499` is the accepted completion evidence. GitHub Actions must not provision Azure
resources; S35 is optional diagnostic tooling and S36/DEPLOY-004 is withdrawn. Preserve the retained
legal-hold estate, and after any Global Administrator resource-access elevation, set Entra
**Access management for Azure resources** back to **No**.

The greenfield `rg-fsi-wt-dev-eus2` replacement is deployed and validated with one East US 2 Foundry resource/project supporting both Hosted Agents and Content Understanding. Old nonimmutable North Central US resources have not been retired. Keep the old legal-hold storage as an archive until Q4 is resolved; teardown approval does not authorize inventing retention or clearing legal hold.

Phase 1 portal constraints:

- The current portal and intake API are intentionally unauthenticated development surfaces. Do not
	require SWA cookies, `x-ms-client-principal`, or browser identity. Ignore browser actor assertions
	as authority and stamp route-selected synthetic workforce identities into audit records. Keep
	IAM-001/S32 and D4 as explicit production blockers.

- Preserve the implemented Clean Architecture/CQRS boundary. New API behavior belongs in a
	contracts message, one Application handler behind typed ports, Domain invariants/exceptions,
	Infrastructure adapters, and a thin Presentation router. Do not put routes or use-case logic
	back into `services/intake_api/app.py` or legacy compatibility modules.
- Preserve the implemented React layering. Network access belongs in `portal/src/api/` and
	focused hooks; feature and reusable components render from props; `App.jsx` remains composition
	only. Only `portal/src/api/client.js` calls `fetch`.
- Preserve post-migration dead-code hygiene. Import portal resource APIs directly; do not recreate
	`portal/src/api.js` or add compatibility barrels. Remove obsolete CSS with its component and keep
	selector/variable/keyframe reachability clean. Python compatibility re-exports are intentional
	public migration boundaries: do not add new consumers, and remove them only in an explicitly
	approved contract-breaking cleanup. Framework-discovered routes, triggers, Pydantic validators,
	Prompt Shields, deferred fail-closed adapters, deployment evidence, analyzers, and demo PDFs are
	not dead code.

- The portal is a desktop-only firm-wide transfer operations workspace, not a single-transfer form. Minimum supported viewport width is 1180px.
- A queue case exists only after an idempotent upstream `TransferCaseCandidate` handoff. The authoritative intent source remains SRD Q1a; synthetic data and a future Fabric adapter must not be presented as that source of truth.
- Use `request_id` before ACATS submission and `intake_id` for ingestion attempts. A real ACATS-assigned `control_number` is required for post-submission ACATS states.
- Use the full role name `ClientRelationshipManager` / `client_relationship_manager`; do not use `CRM`, which is ambiguous with customer relationship management software.
- "Case owner" means the named person accountable for advancing a transfer. Work-item assignees may differ by governed role.
- Keep queue projections, operational state, immutable evidence/audit, and Fabric analytics as separate ownership boundaries.
- The S16 cockpit is a read-only projection of events already published through
	`AnalyticsProjectionPort`; never backfill it from mutable workflow state or fabricate progress when
	the projection is empty.
- Keep the 15-step guided tour synchronized with `docs/demo-run-of-show.md`: queue, Evelyn, all six
	stage surfaces, cockpit, and honesty boundary. Its first/final steps must state public synthetic
	development, no real data, IAM-001, and S40; its Collect/Analyze steps must demonstrate the unified
	unlabeled simulator/Add evidence boundary and completed Review/Resolve conflicts workflow. It may open the workspace and select tabs only; it
	must never invoke intake, review, freeze, submission, clock, correction, reconciliation, restart,
	or analytics writes. Update `TOUR_STEPS`, stable `data-tour` targets, `App.test.jsx`, the runbook,
	and README together whenever the demonstrated stage sequence changes.
- Local portal review uses the FastAPI synthetic queue/API on port 7071 and Vite on port 5173. The API may use deployed EUS2 Blob, Event Grid, Functions, and Content Understanding for document processing. No live ACATS side effect is permitted.
- Shared `.vscode` launch, task, settings, and extension-recommendation files are intentional
	repository tooling. Keep the normal portal task on `scripts.run_portal_api`, reserve the Functions
	attach profile for full host/trigger debugging, use `.venv`, and never add secrets or machine-
	specific paths. Keep generated `.python_packages/` content ignored.
- Track A Monitor is executable only through the governed synthetic clock, non-authoritative T+0–T+5
	lifecycle events, and deterministic Exception stand-in. S11 human correction requires the routed
	role plus evidence, immutable audit, prior-cycle archival, package re-freeze, and a new tagged
	synthetic control. Track A Complete is executable through audited T+4 settlement, three-way
	quantities, T+5 residual/cost-basis gates, discrepancy work, and synthetic client confirmation.
	Production correction, settlement, receiving-book, and closure semantics remain blocked.
- The active clean demo campaign is `WT-2026-0101` through `WT-2026-0107`, plus minimal candidate-only handwriting shells `0108`, `0109`, and `0111`, and queue-only manual-intake shells `0112` and `0113`. All begin in `waiting_intake`; candidate shells must not preseed document-derived account/profile facts. Forty PDFs live under `samples/synthetic-documents/`.
- The unified evidence API accepts one atomic `1..N` unlabeled-PDF batch; never infer document type from a filename. Only a commit marker may trigger the universal worker. Every proposed section and field occurrence remains human-reviewed, repeated sources remain independent, and a conflict resolution must reference the exact current extraction set without rewriting evidence. Simulator manifests select fixture bytes only and use the same batch command as Add evidence.
- Preserve the completed S40 contract: multi-file **Add evidence**, unified simulator, side-by-side protected PDF/Review, document-at-a-time quick approval, anomaly-only interruption, collapsed extraction/audit details, Resolve conflicts, explicit missing observations, no preselected winner, append-only conflict resolution, and the mixed-artifact campaign. New batches use universal v4; v1/v2/v3 remain immutable replay/provenance. Null/missing/malformed section collections normalize to `[]` with an auditable projection warning; never discard the raw analyzer response.
- Async commands disable their trigger and show a visible spinner. A `received` document shows analyzer progress until extraction is ready; do not fabricate percentage progress.
- Keep raw source polygons in the projection for lineage, but omit bbox coordinates from the UI until an accurate PDF overlay exists.
- Keep `docs/demo-run-of-show.md`, the README, roadmap, scenario matrix, and current test baseline aligned with portal behavior. In `legal_hold` mode, repeated Azure-connected demos use untouched request IDs or a fresh campaign and never delete immutable evidence or clear legal hold. In `development` mode, resets may delete only isolated mutable `intake-*-dev` containers through the guarded purge utility; audit, `worm`, legal-hold, immutable, and non-`-dev` targets remain forbidden. Per-case demo restart resets only mutable projection state and never deletes or overwrites retained WORM evidence/audit prefixes.
- Treat `docs/evidence-to-authority-roadmap.md` as the living priority and blocker register. Update item status, authority assumptions, gates, and acceptance evidence in the same PR that changes truth/provenance, work routing, package readiness, external adapters, or ACATS behavior.
- Keep the README `External Systems, Dependencies, and Blockers` matrix synchronized as the quick index to that register; the roadmap owns detailed status, acceptance evidence, decisions, and blockers when the two differ.
- Never equate human-reviewed or cross-document-consistent evidence with verified customer/account truth. A `verified` claim requires a typed authority assertion with source system/reference/version, checked time, result, and policy/tool provenance.
- Complete KYC, target-account readiness, preflight, and known corrections before final TIF execution where firm procedure permits. Production must record authorized-TIF receipt and immediate ACATS handling under approved written procedures; do not invent a permissible holding period.

Before committing portal/API changes, also run `npm --prefix portal test`, `npm --prefix portal run build`, and `npm --prefix portal audit --audit-level=high`.

Current local baseline: 489 Python tests, 111 portal tests across 32 files, local golden catch rate
`1.0000`, clean broad Ruff, clean portal production build, and zero npm vulnerabilities through
the Microsoft package proxy.