# WORKFLOW — Audit & Documentation Process (Magento Module)

**Last verified:** 2026-02-24 00:00 (Europe/London)  
**Scope:** Dev-only. Process for auditing and documenting what exists.

---

## 1) Purpose

This workflow standardises how we:
- Audit unknown breakage
- Document actual behaviour
- Create a minimal, safe plan to fix issues

---

## 2) Phases

### Phase 0 — Orientation (read-only)
Inputs:
- `README.md`, `SETUP_GUIDE.md`, `CHANGELOG.md`, `composer.json`
- `src/` codebase

Outputs:
- `/docs/TODO.md` initial audit checklist
- Initial `/docs/SYSTEM_MAP.md` (L0/L1 only)

### Phase 1 — Evidence Audit (read-only)
Required checks:
- Module registration and enablement
- Admin configuration visibility and config paths
- Checkout UI insertion point, RequireJS mapping, JS component load
- REST routes existence and wiring
- Auth/ACL requirements for each endpoint
- Upstream getAddress.io call logic, timeouts, error handling
- Quote write path (if implemented)
- Logging behaviour and PII exposure

Outputs:
- Audit Findings (structured)
- Update `/docs/*` with evidence-based statements

### Phase 2 — Fix Planning (no code changes)
Output:
- Minimal fix plan with:
  - suspected root cause(s)
  - scope of changes
  - risk & rollback notes
  - docs impact list

### Phase 3 — Implementation (only with explicit instruction)
Rules:
- Minimal changes only
- Update docs alongside behaviour changes
- Validate no PII logging and no secret leakage

---

## 3) Documentation Rules

- All docs live in `/docs`.
- Keep `/docs/SYSTEM_MAP.md` minimal (L0/L1 only).
- Keep contracts in `/docs/API.md`.
- Keep runtime guarantees in `/docs/OBSERVABILITY.md`.
- Do not document production.

---

## 4) Docs Impact Template (must accompany any fix plan)

## Docs Impact

**Updated:**
- docs/ARCHITECTURE.md — <what changed> (verified YYYY-MM-DD HH:MM)
- docs/API.md — <what changed> (verified YYYY-MM-DD HH:MM)
- docs/OBSERVABILITY.md — <what changed> (verified YYYY-MM-DD HH:MM)

**Reviewed (no changes needed):**
- docs/SECURITY.md — <reason>
- docs/GDPR.md — <reason>
- docs/INFRA.md — <reason>

**New Risks / Assumptions:**
- <bullets>