geointel/docs/M6_QUALITY_GATES.md

M6 Quality Gates

Gate 0 — Repository health

Before implementing, Codex must verify:

• expected root folders exist;
• docs are present;
• .env.example exists;
• Docker compose exists;
• scripts are executable or documented;
• no obvious merge conflict markers exist;
• no generated secrets are committed.

Gate 1 — Contract compliance

Every implemented endpoint must have:

• request schema;
• response schema;
• status codes;
• validation behavior;
• error shape following the error contract;
• at least one unit or smoke test.

Gate 2 — Database safety

Every migration must:

• be additive unless explicitly planned;
• include indexes for geometry and foreign keys where relevant;
• avoid destructive operations;
• preserve future PostGIS use;
• be documented in migration notes.

Gate 3 — Geospatial correctness

Every geometry operation must:

• validate geometry;
• preserve CRS metadata;
• use projected CRS for area/length where required;
• return units explicitly;
• handle empty geometries;
• handle invalid polygons safely;
• never silently mix coordinate systems.

Gate 4 — Job safety

Long-running tasks must:

• run through the job layer;
• record status transitions;
• record parameters;
• record errors;
• be restart-safe where feasible;
• not block the API process.

Gate 5 — Frontend state correctness

Every frontend module must:

• handle loading, empty, success, error, and processing states;
• not assume demo data exists;
• use typed API clients;
• show job progress if job-backed;
• avoid hidden state that cannot be refreshed.

Gate 6 — AI pipeline safety

Every AI pipeline must:

• support CPU fallback;
• write deterministic metadata;
• record model id/version;
• record thresholds;
• preserve georeferencing for outputs;
• expose confidence values;
• never overwrite raw input data.

Gate 7 — Export integrity

Every export must include:

• source dataset reference;
• analysis run id;
• generated timestamp;
• CRS;
• units;
• limitations where relevant.

Gate 8 — Handoff completeness

Every Codex pass must update:

• docs/CODEX_EXECUTION_LOG.md or a pass log;
• relevant module docs if behavior changed;
• tests or test notes;
• TODO/backlog if work remains.

Gate 9 — No fake completion

A feature may not be marked done when it only has:

• placeholder UI;
• stub endpoint without real service behavior;
• mock data not clearly marked as fixture/demo;
• no persistence despite requiring persistence;
• no error handling;
• no acceptance criteria coverage.