Skip to content

Phase 1 Review — Foundation

Date: 2026-07-28 · Four-review standard applied to the foundation build.

1. Engineering review

Executed and green in the build environment: ruff format / ruff check (clean), mypy strict (no issues in 7 source files), pytest (36 passed), mkdocs build --strict (after adding this file), docker compose config (valid).

Findings: - PyPI was unreachable from the build sandbox (HTTP 403 direct and via proxy). Consequences handled explicitly rather than papered over: the CLI uses click (preinstalled, and one fewer dependency) instead of Typer — ADR-006 amended; tests run via pytest pythonpath against the preinstalled toolchain (pytest 9.0.3, mypy 1.20.2, ruff 0.15.11, pydantic 2.13.3); the uv lockfile is deferred until an environment can resolve the index (noted in backlog F-01). - mypy plugin caveat: the sandbox mypy runs in an isolated tool environment, so pydantic.mypy could not load there; the strict run was executed with an equivalent configuration resolving the system interpreter's packages. CI runs the committed configuration (with plugin) as-is. - Unproven in this environment — explicitly not claimed: make bootstrap (venv + pip path), the CI matrix itself, the Docker image build, pre-commit hook execution. All are defined and will be proven by the first GitHub push / network-enabled run. Until then the DoD and README say so.

2. Data review

No data was processed in this phase. The one data-adjacent item: F-07 (AGS/NUTS verification) — six fetch attempts (Wikipedia NUTS/Landkreis tables and four infobox pages) failed to yield the code tables because the fetch converter drops infobox content. The shipped codes remain cross-checked from reference knowledge only, are pinned by a test so they cannot drift silently, and stay flagged (risk R-14, backlog F-07) for verification against official tables at first statistics integration.

3. Business review

  • US-16 (developer credibility) partially served: clean structure, typed config with named-field errors, honest CLI. The clean-install experience itself is still unproven (see engineering findings) — a stranger cannot yet be promised a green make bootstrap.
  • The config validator already delivers real utility: a broken region file fails with the file and field named, at the CLI, with exit code 1 — the first working slice of the "pipeline that explains itself" positioning.

4. Honesty review

  • ingoshift status prints "pipeline: not implemented yet (Phase 2 pending)" — the tool itself does not overclaim. ✅
  • make demo / make serve fail loudly with an explanation instead of pretending. ✅
  • README quick start marks which commands were proven where; CI is described as "defined, first run pending", not as passing. ✅
  • DoD row 2 upgraded only to "partially": 36 tests pass locally; matrix and install path are CI's to prove. ✅
  • No badge, screenshot, or claim exists for anything unbuilt. ✅

Gate decision: Phase 1 passes with the two carried-forward obligations (first CI run to prove install path and matrix; F-07 official-code verification). Proceed to Phase 2 (core data platform).