docs: document storage layout and migration risks

[Bahagophilemon]

Description

Documents the Aegis contract storage layout and establishes compatibility, migration, and review requirements for future storage-changing pull requests.

The existing storage audit was incomplete and contained outdated assumptions. This update aligns the documentation with the current contract implementation and covers all 20 DataKey variants.

Key changes:

• Reworked docs/storage-audit-map.md with:
  • Complete instance and persistent storage inventories
  • Stored value types, defaults, writers, and removal paths
  • Key data models and cross-key invariants
  • Storage lifetime and archival considerations
  • In-place upgrade versus new-deployment behavior
  • Migration strategies and migration-plan requirements
  • Storage-changing PR risk guidance
  • Mandatory author and reviewer checklist
• Linked the storage guide from README.md.
• Added storage compatibility requirements to both PR templates.
• Corrected an existing broken self-assessment link.

This is a documentation-only change. It does not modify contract storage, public functions, events, error codes, roles, or runtime behavior.

Related Issues

Fixes #168

Completion Table

Acceptance Criterion	Status	Implementation Evidence	Test Evidence	Documentation Impact
AC 1: Storage layout documentation is added	Complete	docs/storage-audit-map.md contains a complete instance and persistent storage inventory	Static comparison confirmed all 20 DataKey variants are documented	Reworked docs/storage-audit-map.md
AC 2: Key data models are documented	Complete	Documents Role, ComplianceStatus, AssetStatus, ProtocolConfig, and IssuerSeparationPolicy	Models were compared against their current #[contracttype] source definitions	Added stored data-model documentation
AC 3: Storage-changing PR risks are explained	Complete	Added a risk matrix covering key, value-type, default, storage-class, authorization, and redeployment changes	Documentation consistency and diff-hygiene checks passed	Added storage-changing PR risk guide
AC 4: Migration assumptions are documented	Complete	Documents upgrades, redeployments, TTL/archival considerations, address discovery, batching, migration strategies, and rollback requirements	Documentation was reviewed against the current storage access patterns and public interface	Added upgrade and migration guidance
AC 5: Review checklist is included	Complete	Added a mandatory storage-change reviewer checklist and linked it from both PR templates	All modified local Markdown links resolve	Updated storage guide and PR templates
AC 6: README links to storage docs	Complete	Added the storage guide under README Security & Compliance	README link resolves to the documentation file	Updated README.md

No acceptance criteria are incomplete.

Detailed Traceability Mapping

Acceptance Criteria	Implementation	Storage & State Changes	Events Emitted	Test Coverage	Security/Safety Controls
AC 1: Storage layout documentation	Added all 20 keys with storage classes, value types, defaults, writers, and lifecycle details	None; documentation-only	None	Source-to-document inventory comparison	Documents decoding, lifetime, and address-enumeration risks
AC 2: Key data models	Documented compatibility-sensitive stored enums and structs	None	None	Compared with current #[contracttype] definitions	Warns against incompatible field, type, and variant changes
AC 3: Storage-changing risks	Added a change/risk/response matrix	None	None	Manual source-alignment review and git diff --check	Covers token conservation, governance, compliance, decoding, and contract-ID risks
AC 4: Migration assumptions	Added upgrade, redeployment, versioning, batching, idempotency, and rollback guidance	None	None	Reviewed against current storage APIs and absence of migration entrypoints	Requires authorization, atomicity, invariant checks, and recovery planning
AC 5: Review checklist	Added mandatory checklist and PR-template enforcement	None	None	Verified checklist links in both templates	Requires additional review for balances, supply, admin, roles, and compliance
AC 6: README link	Added a discoverable link under Security & Compliance	None	None	Local-link validation passed	Makes storage safety guidance visible to contributors and reviewers

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Chore (refactoring, build tools, etc.)

PR Evidence Checklist

Before opening this PR, complete every applicable item in the evidence
checklist below. See PR Evidence Checklist
for detailed guidance.

1. Issue Reference

• The PR description links to the issue being addressed (e.g. Fixes #123).

2. Implementation Summary

• A concise summary of what was implemented, changed, or fixed is provided
  above in the Description section.
• Key files modified are listed with brief descriptions of each change.
• No new public functions, events, error codes, or roles were introduced.

3. Tests Added or Justification

• New or updated tests cover the change (happy path + failure paths).
• Test names and locations are listed (e.g. test_mint_ok in
  src/test.rs:L45-60).
• OR a no-test justification is provided below because this is a
  documentation-only change with no contract behavior changes.

No-test justification: This PR changes only Markdown documentation and PR
templates. It does not modify Rust code, contract behavior, storage, events, or
public interfaces. Static validation was used to compare the documented
inventory with DataKey and to validate local links.

4. Commands Run

• make verify passes locally.
• Relevant command output is included in Additional Context.

5. CI Status

• All GitHub Actions checks pass (green) on the PR branch.
• Local verification limitations are documented below; CI should run the
  complete Rust verification gate.

6. Acceptance Criteria Coverage

• Every acceptance criterion from the issue is addressed in the Completion
  Table above.
• Documentation impact is recorded for every criterion.
• No acceptance criteria are incomplete.

Policy & Standards

• I have read the Contributor Evaluation Policy and understand that merge does not guarantee payment.
• I have read the CONTRIBUTING.md guidelines.
• My code follows the Rust and Soroban formatting standards (ran cargo fmt).
• My changes generate no new warnings (ran cargo clippy).
• I have added/updated tests for the new logic, and all tests pass (ran cargo test).
• Traceability Mapping: I have filled out the detailed mapping table for this storage-documentation change.
• Reviewer Guidance: I have reviewed my own changes against the Reviewer Checklist.
• Compliance & Legal Check: The documentation does not imply regulatory completeness beyond smart contract enforcement.

Additional Context

Validation performed

git diff --check
Passed with no output.

Storage inventory validation:
Key inventory: 20/20 documented
Missing keys: []
Unknown keys: []

Local Markdown link validation:
Missing local links: []

Local verification limitation

make verify was attempted, but the provided development environment does not
contain the cargo executable:

cargo fmt --all -- --check
make: cargo: No such file or directory
make: *** [Makefile:109: fmt-check] Error 127

No Rust source files were changed. CI should run the complete formatting,
Clippy, test, and build gate.