# Roadmap

## Phase 2A - Read-Only Shadow Implementation

Status: implemented, validated, merged, and deployed as release `0.4.0`.

The production service is healthy in `shadow-read-only` mode and supports all 58
configured English-language markets. Scheduler approval is withheld, so the
deployment is intentionally inert until durable storage and a controlled
read-only subset are accepted. The remaining work is operational completion of
Phase 2A evidence, followed by explicit Phase 2B activation gates.

Phase 2A is reviewed as six separate subphases:

1. **2A.1 — Foundation and guardrails**: Python application foundation,
   immutable configuration, domain contracts, read-only ports, CLI, tests, and
   CI. Acceptance requires deterministic offline checks and proof that no
   production writer or external connection exists.
2. **2A.2 — Sidecar schema and migrations**: isolated PostgreSQL/PostGIS
   schema, migrations, and constraints. Acceptance requires isolated apply and
   rollback evidence; NocoDB remains untouched.
3. **2A.3 — PBF ingestion foundation**: bounded fixtures, parser boundaries,
   and validated Geofabrik extract metadata. Acceptance requires fixture and
   checksum validation.
4. **2A.4 — Profiles, normalization, and deduplication**: versioned profile
   rules, deterministic normalization, and collision candidates. Acceptance
   requires golden and rerun-stability evidence.
5. **2A.5 — Noco read adapter and adoption scanner**: schema-fingerprinted
   read access, adoption matching, duplicate analysis, and workflow-protection
   evidence. Acceptance requires read-only method-surface and isolated-read
   evidence.
6. **2A.6 — Integrated shadow reconciliation**: immutable reports and
   deterministic planned actions combining source, profile, and Noco-read
   evidence. Acceptance requires repeatable end-to-end shadow reports.

Each subphase uses its own branch, PR, handoff, review, merge, and `/clear`.
Later subphases do not begin before the preceding gate is accepted.

Allowed:

- Create application structure needed for read-only processing.
- Implement Geofabrik catalog lookup, download validation, PBF parsing, category
  profiles, normalization, Noco read access, adoption scanning, reconciliation
  reports, and tests.

Prohibited:

- No NocoDB writes.
- No direct writes to Noco PostgreSQL.
- No stale deletion.
- No deployment or scheduler unless separately approved.
- No production writer.

## Phase 2B - Insert-Only Controlled Writer

Gate: Phase 2A review accepted and explicit approval for controlled writes.

Allowed:

- Implement NocoDB API insert flow for approved region/profile scope.
- Use final duplicate checks and idempotency controls.

Prohibited:

- No updates or deletes unless explicitly included in the approved scope.
- No stale deletion.
- No concurrent writer operation with the legacy scraper.

## Phase 2C - Safe Refresh And Stale Lifecycle

Gate: controlled writer evidence accepted.

Allowed:

- Implement monthly refresh lifecycle, source presence tracking, missing counters,
  remap candidates, and stale evidence reports.

Prohibited:

- No destructive stale deletion.
- No profile-change-as-deletion behavior.

## Phase 2D - Approved Stale Deletion

Gate: explicit deletion approval after evidence review.

Allowed:

- Implement deletion only after two complete snapshots and at least 60 days of
  evidence, with workflow checks and rollback evidence.

Prohibited:

- No deletion without explicit approval.
- No deletion of rows with protected or unknown ownership/workflow state.

## Phase 2E - Authenticated MCP Integration

Gate: explicit approval after core service behavior is accepted.

Allowed:

- Add authenticated read/search tools, draft category proposals, dry-run requests,
  and approved action execution through the reconciliation engine.

Prohibited:

- No arbitrary SQL.
- No arbitrary shell.
- No unrestricted write tools.