Initial GeoIntel V1 foundation

docs/19-architect-audit/ARCHITECT_AUDIT_REPORT_M11.md

@@ -0,0 +1,81 @@
+# M11 Architect Audit Report
+
+## Audit summary
+
+The repo has strong breadth: product docs, architecture docs, API plans, build prompts, fixtures, smoke scripts and milestone handoffs exist. The main risk is no longer lack of documentation; it is competing documentation and missing hierarchy.
+
+## Findings
+
+### Finding 1 — Too many competing start points
+
+There are multiple handoff files and prompt files from M0 through M10. This is useful historically but dangerous for Codex.
+
+Resolution:
+
+- added `docs/00-start/START_HERE.md` as canonical entry point;
+- added decision precedence;
+- older files remain historical.
+
+### Finding 2 — Governance rules were implied, not constitutional
+
+Previous docs often said what to build, but not which principles override conflicts.
+
+Resolution:
+
+- added GeoIntel Constitution;
+- added Architecture Invariants;
+- added Forbidden Decisions.
+
+### Finding 3 — Domain language needed locking
+
+Terms like Dataset, Layer, Analysis, Detection and Segmentation could be implemented inconsistently.
+
+Resolution:
+
+- added Canonical Domain Models.
+
+### Finding 4 — State machines needed canonical names
+
+Multiple docs referenced statuses, but a single source of truth was missing.
+
+Resolution:
+
+- added `STATE_MACHINES.md`.
+
+### Finding 5 — Build order needed dependency graph, not only phase lists
+
+Codex needs to know not only tasks, but why one task must precede another.
+
+Resolution:
+
+- added Build Order Dependency Graph.
+
+### Finding 6 — Golden paths needed stronger protection
+
+The desired demo was clear, but not protected as regression-critical workflows.
+
+Resolution:
+
+- added `GOLDEN_PATHS.md`.
+
+### Finding 7 — Error handling needed stable codes
+
+The frontend and backend need a common error taxonomy.
+
+Resolution:
+
+- added `ERROR_CATALOG.md`.
+
+## Remaining recommendations for M12+
+
+1. Generate actual starter code skeleton aligned with the docs.
+2. Add OpenAPI YAML snapshot once backend exists.
+3. Add migration files once database models exist.
+4. Convert golden paths into executable tests.
+5. Add real small GeoTIFF fixture if licensing/file size allows.
+6. Add GRB WFS proof-of-concept adapter after local fixture path is stable.
+7. Add QGIS export verification later.
+
+## Architect verdict
+
+The repo is now suitable for a disciplined autonomous Codex build, provided Codex starts from `docs/00-start/START_HERE.md` and treats older handoff docs as historical.