geointel/docs/19-architect-audit/ARCHITECT_AUDIT_REPORT_M11.md

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.