# AGENTS.md

## Repo Purpose
This repository contains an operator-first Microsoft 365 tenant-to-tenant migration runbook and automation toolkit. It is built for low-cost execution, native Microsoft tooling first, and strict safety controls that block destructive actions until objective validation evidence is recorded.
The repository now includes a stateful autonomous-assist orchestrator for phase execution, evidence assertions, gate checks, and operator summaries.

## Migration Philosophy
- Native-first: use Exchange Online cross-tenant mailbox migration and Microsoft-native SharePoint/OneDrive migration capabilities where practical.
- Lowest-cost reasonable path: use PowerShell automation, exports, and checklists before considering paid tooling.
- Validate before destroy: no source teardown actions are allowed before migration usability is proven.

## Non-Negotiable Safety Rule
The source domain must not be removed and the source tenant must not be decommissioned until per-user validation, dependency scans, mail-flow validation, admin sign-in validation, rollback readiness, and required evidence artifacts have all passed and been recorded.

## Forbidden Actions
- Removing the source custom domain before dependency scans and validation gates pass.
- Deleting or disabling source admin access before decommission gates pass.
- Cancelling source licensing early if it impairs validation, rollback, or coexistence access.
- Deleting migration batches before migration verification is complete and recorded.
- Performing destructive actions without required evidence files under `evidence/`.
- Releasing source-domain objects before shared mailbox/resource mailbox/group/contact/address checks pass.

## Required Technical Safeguards
- Preserve and validate aliases/proxy addresses and `x500`/`LegacyExchangeDN` handling.
- Validate target object population before migration starts.
- Validate migrated users can sign in, send/receive mail, access historical mailbox content, and access calendars.
- Validate OneDrive/SharePoint access if workload is in scope.
- Scan and remediate shared mailboxes, resource mailboxes, distribution lists, M365 groups, contacts, and admin sign-ins tied to source domain.
- Enforce hold period before final decommission unless explicitly waived with recorded sign-off.
- Keep migration batches until verification is complete.

## Execution Model
- Multi-task work is allowed across phases, but destructive tasks are blocked behind validation gates.
- Checklist status alone is insufficient. Required CSV/JSON evidence files must exist, be populated, and be referenced in `IMPLEMENTATION_PROGRESS.md`.
- If evidence is missing, empty, stale, or inconsistent, gate state is `FAIL/HOLD`.
- Operator performs final cutover and decommission steps manually using checklist and sign-off blocks.
- State-driven execution is mandatory:
  - `agent/runbook-state.json` and `state/current-phase.json` are the source of truth.
  - Agent phases run via `scripts/agent-entry.ps1` and `scripts/invoke-agent-phase.ps1`.
  - Every phase run writes `logs/operator-summary.md`.
- Approval-gated phases:
  - `CutoverAssist` requires populated `state/approvals.json` (`cutoverAssist`).
  - `DecommissionAssist` requires populated `state/approvals.json` (`decommissionAssist`).
  - Required approval fields: `approvedBy`, `approvedAtUtc`, and `changeTicket` or `justification`.
- Prior-gate enforcement:
  - Later phases must satisfy task prerequisite gates before running.
  - Gate assertions also verify prerequisite gate status from `agent/runbook-state.json`.
- Evidence quality enforcement:
  - Missing, empty, stale, malformed, or schema-invalid evidence causes `HOLD`.
  - Freshness windows are enforced by evidence scope (24h discovery/prereqs, 12h pilot/bulk, 2h cutover/decommission).
- DryRun enforcement:
  - Orchestrator DryRun is non-mutating for tenant objects.
  - Manual/destructive boundaries remain blocked regardless of DryRun state.

## Manual-Only Boundaries
- DNS cutover execution is manual-only.
- Source custom domain removal is manual-only.
- Final source tenant decommission is manual-only.
- Agent may prepare, validate, and summarize these steps but must not execute them automatically.

## Operator Expectations
- Validate exact tenant prerequisites and permissions in Microsoft documentation before execution.
- Review script placeholders marked `VERIFY IN TENANT / DOC` and set environment-specific values in config files.
- Record all gate decisions and reviewer notes in `IMPLEMENTATION_PROGRESS.md`.