Initial public release

docs/30-codex-optimization/CODEX_OPTIMIZATION_OVERVIEW.md

@@ -0,0 +1,43 @@
+# M13 Codex Optimization Overview
+
+M13 adds an optimization layer on top of the M12 run-ready repository. The goal is to improve Codex output quality by making the implementation process more constrained where correctness matters, while still allowing local improvements inside documented boundaries.
+
+## M13 purpose
+
+Codex should be able to:
+
+1. choose the correct entry document without ambiguity;
+2. work pass-by-pass without re-planning the whole product;
+3. use reusable skills for repeated implementation patterns;
+4. respect token and context budgets;
+5. avoid secrets leakage;
+6. split work safely across parallel agents or worktrees;
+7. self-review every implementation pass against explicit gates;
+8. escalate only real blockers.
+
+## New canonical Codex flow
+
+1. Read `CODEX_START.md`.
+2. Read `docs/30-codex-optimization/CODEX_RUN_CHECKLIST.md`.
+3. Read `docs/30-codex-optimization/PROMPT_DISCIPLINE.md`.
+4. Select the active pass from `docs/20-run-readiness/PASS_SEQUENCE_FINAL.md`.
+5. Select only the relevant skill from `skills/`.
+6. Implement the smallest coherent pass.
+7. Run `make readiness` plus module-specific checks.
+8. Fill in `docs/CODEX_EXECUTION_LOG.md`.
+9. Produce a pass summary using `prompts/codex/m13/PASS_COMPLETION_REPORT_PROMPT.md`.
+
+## M13 rule hierarchy
+
+If instructions conflict, follow this order:
+
+1. `docs/governance/GEOINTEL_CONSTITUTION.md`
+2. `docs/governance/ARCHITECTURE_INVARIANTS.md`
+3. `docs/governance/FORBIDDEN_DECISIONS.md`
+4. `CODEX_START.md`
+5. `docs/30-codex-optimization/*`
+6. active pass prompt
+7. module documentation
+8. historical milestone documents
+
+Historical M0-M12 documents remain useful, but they must not override governance, invariants, M12 final readiness, or M13 optimization rules.

docs/30-codex-optimization/CODEX_RUN_CHECKLIST.md

@@ -0,0 +1,48 @@
+# Codex Run Checklist
+
+Use this checklist at the start and end of every Codex session.
+
+## Before starting
+
+- [ ] Confirm the current branch/worktree.
+- [ ] Read `CODEX_START.md`.
+- [ ] Read `docs/00-start/START_HERE.md`.
+- [ ] Read `docs/30-codex-optimization/CODEX_OPTIMIZATION_OVERVIEW.md`.
+- [ ] Read `docs/30-codex-optimization/PROMPT_DISCIPLINE.md`.
+- [ ] Read only the active pass prompt.
+- [ ] Read the relevant skill from `skills/`.
+- [ ] Run `make readiness` if the repository has shell/python available.
+- [ ] Identify the exact files expected to change.
+
+## During implementation
+
+- [ ] Keep changes scoped to the active pass.
+- [ ] Do not introduce new frameworks without ADR.
+- [ ] Do not change API contracts unless the active pass explicitly requires it.
+- [ ] Do not create permanent mock-only implementations.
+- [ ] Prefer small, verifiable service boundaries.
+- [ ] Keep GIS units and CRS assumptions explicit.
+- [ ] Record real limitations as limitations, not hidden TODOs.
+
+## Before finishing
+
+- [ ] Run relevant tests/smoke checks.
+- [ ] Run `make readiness` when possible.
+- [ ] Update `docs/CODEX_EXECUTION_LOG.md`.
+- [ ] Update `CHANGELOG.md`.
+- [ ] List changed files.
+- [ ] List what works.
+- [ ] List what remains incomplete.
+- [ ] List any deliberate deviations from docs.
+- [ ] Produce a self-review scorecard.
+
+## Stop conditions
+
+Stop and report instead of guessing when:
+
+- a governance invariant would be violated;
+- a required external credential is missing;
+- a data source license or endpoint is unclear;
+- a destructive migration would be needed;
+- tests indicate a core regression;
+- implementation requires a new major dependency not already approved.

docs/30-codex-optimization/CODEX_SKILLS_INDEX.md

@@ -0,0 +1,28 @@
+# Codex Skills Index
+
+Skills are reusable implementation workflows. Use one skill per implementation pass unless the task clearly spans two tightly coupled areas.
+
+## Available skills
+
+| Skill | Use when |
+|---|---|
+| `geoai-backend-build` | creating FastAPI services, routers, schemas, domain logic |
+| `postgis-migration` | creating database models, Alembic migrations, geometry fields |
+| `raster-pipeline` | implementing Rasterio/GDAL-style raster metadata, clip, tile, indices |
+| `vector-processing` | implementing GeoPandas/Shapely vector operations and exports |
+| `frontend-maplibre-workbench` | building React/MapLibre pages, layers, UI states |
+| `qaqc-review` | implementing IoU, precision/recall, false positives/negatives |
+| `codex-pass-review` | final self-review, regression scan and pass completion reports |
+
+## Skill usage protocol
+
+1. Read active pass prompt.
+2. Select the closest skill.
+3. Read `skills/<skill>/SKILL.md`.
+4. Implement using the skill checklist.
+5. Run module-specific checks.
+6. End with the skill's required report fields.
+
+## Skill conflict rule
+
+If a skill conflicts with governance docs, governance wins. Update the skill later; do not violate governance.

docs/30-codex-optimization/M13_HANDOFF_SUMMARY.md

@@ -0,0 +1,29 @@
+# M13 Handoff Summary — Codex Optimization Pack
+
+M13 adds the final layer intended to improve tomorrow's Codex execution quality.
+
+## Added
+
+- Codex optimization overview.
+- Codex run checklist.
+- Prompt discipline rules.
+- Token/context budget policy.
+- Secrets and environment policy.
+- Parallel agent strategy.
+- Codex skills index.
+- Reusable skills under `skills/`.
+- M13 day-one optimized master prompt.
+- Pass completion report prompt.
+- Updated readiness checks for M13 assets.
+
+## Why this matters
+
+M12 made the repository run-ready. M13 makes the repository easier for Codex to execute correctly without wasting context, drifting from contracts, leaking secrets, or making undocumented architecture choices.
+
+## Recommended next action
+
+Use:
+
+- `prompts/codex/m13/DAY_1_OPTIMIZED_MASTER_PROMPT.md`
+
+for the first serious Codex build run.

docs/30-codex-optimization/PARALLEL_AGENT_STRATEGY.md

@@ -0,0 +1,87 @@
+# Parallel Agent Strategy
+
+GeoIntel can use multiple Codex agents only when their work areas do not conflict.
+
+## Safe parallel tracks
+
+### Track A — Backend foundation
+
+Allowed paths:
+
+- `backend/`
+- `tests/backend/`
+- database docs when needed
+
+Do not touch frontend except API contract comments.
+
+### Track B — Frontend shell
+
+Allowed paths:
+
+- `frontend/`
+- `tests/frontend/`
+- UI docs when needed
+
+Do not change API contracts without coordination.
+
+### Track C — Documentation/runbooks
+
+Allowed paths:
+
+- `docs/`
+- `prompts/`
+- `skills/`
+- `checklists/`
+
+Do not change implementation code.
+
+### Track D — Fixtures/tests
+
+Allowed paths:
+
+- `tests/fixtures/`
+- `fixtures/`
+- `scripts/`
+- test docs
+
+Do not alter production services except to expose stable test hooks.
+
+## Unsafe parallel work
+
+Do not run parallel agents on:
+
+- database schema plus API schemas unless coordinated;
+- API contracts plus frontend client generation unless coordinated;
+- storage paths plus dataset manager unless coordinated;
+- detection output schemas plus QA/QC engine unless coordinated.
+
+## Worktree naming convention
+
+```text
+worktrees/
+  geointel-backend-foundation
+  geointel-frontend-shell
+  geointel-qaqc-engine
+  geointel-docs-control
+```
+
+## Merge order
+
+1. governance/docs updates;
+2. database/domain foundation;
+3. backend APIs;
+4. frontend API client;
+5. UI pages;
+6. tests/fixtures;
+7. polish.
+
+## Parallel agent completion report
+
+Every agent must report:
+
+- branch/worktree name;
+- files changed;
+- contracts touched;
+- tests run;
+- merge risks;
+- required follow-up from other tracks.

docs/30-codex-optimization/PROMPT_DISCIPLINE.md

@@ -0,0 +1,94 @@
+# Prompt Discipline for Codex Runs
+
+Codex performs best when each run has one active objective, a clear source of truth, explicit stop conditions, and a small set of expected outputs.
+
+## Required prompt shape
+
+Every implementation prompt should contain:
+
+1. Active milestone.
+2. Active pass.
+3. Required documents to read.
+4. Forbidden documents to treat as historical only.
+5. Expected files or directories to touch.
+6. Expected tests/checks.
+7. Definition of Done.
+8. Reporting format.
+
+## Good prompt pattern
+
+```text
+You are working on GeoIntel Kempen.
+Active pass: PASS_02_DATABASE_DOMAIN.
+Read first: CODEX_START.md, docs/30-codex-optimization/CODEX_RUN_CHECKLIST.md, skills/postgis-migration/SKILL.md, docs/DATABASE_IMPLEMENTATION_PLAN.md.
+Do not modify frontend files in this pass.
+Implement only the database/domain foundation described in the active pass.
+Run make readiness and relevant backend checks.
+End with changed files, commands run, tests, risks, next pass.
+```
+
+## Bad prompt pattern
+
+```text
+Build the whole platform. Improve whatever you see. Make it production ready.
+```
+
+This is forbidden because it causes scope creep, undocumented architecture choices, and conflicting implementations.
+
+## Improvement boundary
+
+Codex may improve:
+
+- naming consistency;
+- validation details;
+- typing;
+- docstrings;
+- tests;
+- small helper functions;
+- error messages;
+- UI empty/loading/error states;
+- non-breaking internal structure.
+
+Codex may not independently change:
+
+- primary stack;
+- database choice;
+- job queue choice;
+- CRS policy;
+- API contract shape;
+- V1 scope;
+- security model;
+- storage architecture;
+- model governance rules.
+
+## Context loading rule
+
+Do not read the entire repository for every pass. Load context in this order:
+
+1. root start files;
+2. governance docs;
+3. active pass prompt;
+4. relevant skill;
+5. directly relevant module docs;
+6. code files affected by the pass;
+7. tests/fixtures for the affected area.
+
+## End-of-pass response format
+
+Codex must end each pass with:
+
+```md
+## Completed
+
+## Changed files
+
+## Commands run
+
+## Test results
+
+## Known limitations
+
+## Deviations from docs
+
+## Next recommended pass
+```

docs/30-codex-optimization/SECRETS_AND_ENV_POLICY.md

@@ -0,0 +1,50 @@
+# Secrets and Environment Policy
+
+GeoIntel must be safe to publish as a portfolio repository.
+
+## Absolute rules
+
+- Never commit real API keys.
+- Never commit credentials, tokens, cookies or private endpoints.
+- Never place secrets in docs, fixtures, tests or screenshots.
+- `.env.example` may contain placeholder values only.
+- Runtime secrets are read from environment variables.
+- If a real key is accidentally found, remove it and rotate it outside the repo.
+
+## Approved environment variables
+
+- `DATABASE_URL`
+- `POSTGRES_HOST`
+- `POSTGRES_PORT`
+- `POSTGRES_DB`
+- `POSTGRES_USER`
+- `POSTGRES_PASSWORD`
+- `REDIS_URL`
+- `STORAGE_ROOT`
+- `OPENAI_API_KEY`
+- `COPERNICUS_CLIENT_ID`
+- `COPERNICUS_CLIENT_SECRET`
+- `GRB_WFS_BASE_URL`
+- `OSM_OVERPASS_URL`
+
+## Codex behavior
+
+When credentials are missing, Codex must:
+
+1. implement a clear configuration error;
+2. document the missing variable;
+3. provide an example in `.env.example`;
+4. avoid hardcoded fallback secrets;
+5. keep external-service calls behind adapters.
+
+## Local development fallback
+
+For V1 foundation work, services should be able to run with:
+
+- local PostGIS;
+- local Redis;
+- fixture datasets;
+- disabled external fetchers;
+- deterministic demo outputs.
+
+This fallback is not fake production behavior. It is a development mode and must be labeled as such.

docs/30-codex-optimization/TOKEN_BUDGET_POLICY.md

@@ -0,0 +1,45 @@
+# Token and Context Budget Policy
+
+This repository is intentionally documentation-heavy. Codex must not load all documents for every task.
+
+## Context tiers
+
+### Tier 0 — Always read
+
+- `CODEX_START.md`
+- `docs/00-start/START_HERE.md`
+- `docs/30-codex-optimization/CODEX_RUN_CHECKLIST.md`
+- active pass prompt
+
+### Tier 1 — Read when architecture-sensitive
+
+- `docs/governance/GEOINTEL_CONSTITUTION.md`
+- `docs/governance/ARCHITECTURE_INVARIANTS.md`
+- `docs/governance/FORBIDDEN_DECISIONS.md`
+- relevant ADRs
+
+### Tier 2 — Read when module-specific
+
+- relevant module spec
+- relevant skill
+- relevant API/database contract
+- relevant tests/fixtures
+
+### Tier 3 — Historical reference only
+
+- old milestone handoff summaries
+- previous pass prompts not active for the current run
+- release notes from previous preparation milestones
+
+## Budget rules
+
+- Prefer reading indexes before detailed specs.
+- Prefer targeted `grep/find` over opening large unrelated docs.
+- Do not re-summarize old milestones unless needed.
+- Work in small coherent diffs.
+- If a task requires touching more than three major subsystems, split it into passes.
+- If the active prompt conflicts with governance, stop and report.
+
+## Large file policy
+
+Large generated files, model artifacts, tiles, rasters and exports must not be created during documentation-preparation passes unless they are tiny fixtures. Real heavy assets belong outside git or in storage paths documented by `docs/STORAGE_ARCHITECTURE.md`.