fsi-agentic-wealth-transfer

# Agent Engineering Instructions

Read `.github/github-instructions.md` and `Software-Requirements-Document.md` before changing the agent layer. Treat the SRD open questions as unresolved until a stakeholder answer is recorded; never replace a `# TODO [Qn]` with an assumption.

The active Milestone 1 replacement is deployed as `ai-transfer-agent` version 8 in East US 2 under `fsi-wt-dev`; prior North Central US version 6 is retained as historical deployment evidence. Its immutable audit system of record is WORM Blob only. Do not add SQL, Fabric, Cosmos DB, live ACATS submission, or a fabricated control number unless a later milestone and architecture revision explicitly require it.

The greenfield East US 2 replacement in `rg-fsi-wt-dev-eus2`, managed by `fsi-wt-dev`, is deployed and validated. It uses one Foundry resource/project for Content Understanding and the hosted agent. Old nonimmutable North Central US resources have not been retired; preserve its legal-hold audit storage as an archive until Q4 is resolved.

Deployment completion uses the operator-controlled `scripts/deploy.ps1` full `azd up` path; run
`29794555499` is the accepted Track C evidence. Do not recreate the retired GitHub deployment
workflow or make the optional S35 harness a completion gate. S36/DEPLOY-004 is withdrawn, and all
legal-hold estates remain subject to Q4 disposition controls.

Before changing deployment code, preserve these verified constraints:

- Use `agent-framework-core`, not the `agent-framework` all-extras meta-package.
- Keep `TELEMETRY_CONNECTION_STRING` as the hosted alias configured before `InvocationAgentServerHost` construction.
- Keep legal hold, protected append writes, Entra-only Blob access, and fail-closed audit behavior.
- Do not delete the superseded immutable `audit-records` container or run `azd down` without explicit approval.
- Authenticate local Foundry operations through `azd` in tenant `0ee6c2d6-3cf2-4bbc-94ee-217cec207296`.

Run `python -m pytest tests -q`, `python -m evals.run_local`, and `python -m ruff check agents contracts evals services tools tests scripts` before committing agent-layer changes.

For Phase 1 portal/API work, preserve the deployed agent boundary and use the full `ClientRelationshipManager` role name plus the UI label "Case owner". Run Ruff over `services` as well, and run `npm --prefix portal test`, `npm --prefix portal run build`, and `npm --prefix portal audit --audit-level=high` before committing.

The shared `.vscode` files are intentional repository tooling. Keep normal portal review on
`scripts.run_portal_api`; use the Azure Functions attach profile only for full host/trigger debugging,
keep `.venv` as its Python environment, and never add secrets or machine-specific paths.

The intake API is fully migrated to Clean Architecture/CQRS. Add behavior through one contracts
Command/Query, one Application handler behind role-specific ports, shared Domain invariants, an
Infrastructure adapter when required, and a thin Presentation route registered in the composition
root. `services/intake_api/app.py` is factory/entry only; `repository.py`, `cloud_storage.py`, and
`views.py` are compatibility re-exports, not extension points.

The portal is split into `api/`, hooks, queue/workspace/evidence features, and reusable components.
Only `portal/src/api/client.js` may call `fetch`; keep `App.jsx` as a composition shell. The current
verified local baseline is 489 Python tests, 111 portal tests across 32 files, golden catch rate
`1.0000`, clean broad Ruff, a clean Vite build, and zero npm vulnerabilities through the Microsoft
package proxy.

The post-migration orphan audit removed the temporary hello agent, unused portal API barrel, and
legacy CSS. Do not recreate those compatibility surfaces. New portal callers import resource APIs
directly. Treat the Python root-level compatibility modules as intentional public migration
boundaries: do not add new consumers or delete them without explicit contract-breaking approval.
Before removing apparently unused code, account for FastAPI/Azure decorators, Pydantic validators,
pytest discovery, CLI/deployment hooks, Prompt Shields, and deferred fail-closed adapters.

The current portal 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`, with 40 PDFs total. Every case starts at `waiting_intake`; candidate shells omit document-derived account/profile facts. The public synthetic profile is Julia Bennett and remains unauthenticated development context. The firm queue distributes 8 cases to Julia, 2 to Omar, and 2 to Megan so My work is demonstrable without fabricating lifecycle progress. The simulator selects fixture bytes only and uses the same atomic unlabeled batch command as Add evidence. Filenames are never classification inputs. Active universal v4 is the tenth runtime analyzer; immutable v1/v2/v3 remain provenance. Async triggers disable and show spinners; successful batches auto-advance from Collect to Analyze, while bounded processing failures surface an actionable error. Raw bbox coordinates remain hidden until a correct overlay exists. Track A continues through synthetic closure/cockpit; all live ACATS/Fabric semantics remain roadmap work. Keep [the Demo Run of Show](docs/demo-run-of-show.md) synchronized.

S37-S40 define the unified evidence path: atomic `1..N` unlabeled PDFs, commit-only
universal processing, repeated artifact/section/field lineage, server-selected development occurrence review,
reviewed-union completeness, and append-only exact-source conflict resolution. Never route staging
blobs to the legacy worker, collapse repeated sources, mutate extraction truth, or present a human
resolution as firm verification. Preserve completed S40 multi-file Add evidence, unified simulator,
side-by-side protected PDF/Review, document-at-a-time quick approval, anomaly-only interruption,
collapsed exception/audit details, Resolve conflicts, explicit missing values, and mixed campaign.

The guided tour is part of that presenter contract. Keep its 15 steps synchronized with the
run-of-show from queue through all six stage surfaces and back to the cockpit. It may open Evelyn
and select tabs only; never add intake, review, freeze, submission, clock, correction,
reconciliation, restart, or analytics side effects to tour navigation. Keep the public-development,
Julia's public synthetic profile versus production authentication, unified unlabeled evidence intake, S40, and IAM-001 boundaries
in the exact tour/runbook sequence.

Use the [Evidence to Authoritative Truth Roadmap](docs/evidence-to-authority-roadmap.md) to prioritize implementation. Reviewed/internal consistency is not authoritative truth. Do not promote a value to verified without recorded authority provenance, and do not activate final-TIF receipt/submission behavior until firm written procedures and ACATS interfaces are approved.

Keep the README [External Systems, Dependencies, and Blockers](README.md#external-systems-dependencies-and-blockers) matrix synchronized as the quick dependency index. Detailed status, gates, acceptance evidence, owners, and open decisions remain authoritative in the Evidence to Authoritative Truth Roadmap.

This project was built with the microsoft-foundry skill. Before working on or answering questions about Foundry agents, read the microsoft-foundry skill first.

If you are in VS Code, read the vscode-microsoft-foundry skill first.