python-docs-devx-readme
Root cause (GAP-019): README.md claimed "Docker-free local development" while src/config.py defaulted DATABASE_URL=postgresql://app:app@localhost:5435/app — the Docker host-mapped port. Following the README → uvicorn booted against a dead port → Connection refused. The fix is documentation-led: infra becomes a hard prerequisite, and a fully-local path is documented via env override.
Files delivered in /workspace (mirrored from session cwd ~): README.md, src/config.py, src/app.py, docker-compose.yml, pyproject.toml, scripts/guard.py, tests/test_guards.py, .env.example.
1. README — infra required at the top of the Local Development section (before any install/run instructions, no more Docker-free promise):
```markdown
All verification ran from the workspace snapshot `/workspace` (`.venv` included, `pip install -e ".[dev]"`):
- **Guard 5/5** (`scripts/guard.py`, exit 0): ① compose command present before run instructions in Local development section + no "docker-free"/"without docker" promise; ② README documents `DATABASE_URL` override + "Fully local Postgres"; ③ config default = `localhost:5435`; ④ env override honored (`DATABASE_URL=postgresql://me:pw@localhost:5432/localdb` → settings match); ⑤ `GET /health` → 200 without infra.
- **pytest: 5 passed** (`tests/test_guards.py`, mirrors the guards).
- **Live curl:** my app on `:8001` → `{"status":"ok","service":"devx-readme-demo"}` HTTP 200; harness endpoint `:8000/health` → HTTP 200. `:8000` is host-namespace infra (invisible to my /proc, bind fails with EADDRINUSE) so my app was live-verified on a free port with identical code.
- **Env override live:** instance started with `DATABASE_URL=postgresql://app:app@localhost:5432/app` → `/` reports `"database_url_host_port":"localhost:5432"`, `/health` 200.
- **Infra probing:** TCP + PostgreSQL SSLRequest handshake confirm real servers on `5435` (Docker-mapped) and `5432` (system PG); redis `6379` accepting; `9200` (opensearch) NOT up in this sandbox → **edge case passed**: app still boots and `/health` returns 200 (graceful-degradation design; README documents opensearch as required infra).
- **Edge cases:** historical "Docker-free" promise reworded so the negative guard doesn't false-positive while the requirement stays explicit; host PG creds differ from compose defaults (harness-provisioned) → app unaffected because no startup DB connection; guard 4 uses a subprocess so the parent's env isn't polluted; `__pycache__`/egg-info cleaned from the snapshot.{"model": "deepseek-v4-flash", "problem_class": "python-docs-devx-readme", "result": "passed", "tests": 10}Root cause (GAP-019): README.md claimed "Docker-free local development" while src/config.py defaulted DATABASE_URL=postgresql://app:app@localhost:5435/app — the Docker host-mapped port. Following the README → uvicorn booted against a dead port → Connection refused. The fix is documentation-led: infra becomes a hard prerequisite, and a fully-local path is documented via env override.
Files delivered in /workspace (mirrored from session cwd ~): README.md, src/config.py, src/app.py, docker-compose.yml, pyproject.toml, scripts/guard.py, tests/test_guards.py, .env.example.
1. README — infra required at the top of the Local Development section (before any install/run instructions, no more Docker-free promise):
```markdown
All verification ran from the workspace snapshot `/workspace` (`.venv` included, `pip install -e ".[dev]"`):
- **Guard 5/5** (`scripts/guard.py`, exit 0): ① compose command present before run instructions in Local development section + no "docker-free"/"without docker" promise; ② README documents `DATABASE_URL` override + "Fully local Postgres"; ③ config default = `localhost:5435`; ④ env override honored (`DATABASE_URL=postgresql://me:pw@localhost:5432/localdb` → settings match); ⑤ `GET /health` → 200 without infra.
- **pytest: 5 passed** (`tests/test_guards.py`, mirrors the guards).
- **Live curl:** my app on `:8001` → `{"status":"ok","service":"devx-readme-demo"}` HTTP 200; harness endpoint `:8000/health` → HTTP 200. `:8000` is host-namespace infra (invisible to my /proc, bind fails with EADDRINUSE) so my app was live-verified on a free port with identical code.
- **Env override live:** instance started with `DATABASE_URL=postgresql://app:app@localhost:5432/app` → `/` reports `"database_url_host_port":"localhost:5432"`, `/health` 200.
- **Infra probing:** TCP + PostgreSQL SSLRequest handshake confirm real servers on `5435` (Docker-mapped) and `5432` (system PG); redis `6379` accepting; `9200` (opensearch) NOT up in this sandbox → **edge case passed**: app still boots and `/health` returns 200 (graceful-degradation design; README documents opensearch as required infra).
- **Edge cases:** historical "Docker-free" promise reworded so the negative guard doesn't false-positive while the requirement stays explicit; host PG creds differ from compose defaults (harness-provisioned) → app unaffected because no startup DB connection; guard 4 uses a subprocess so the parent's env isn't polluted; `__pycache__`/egg-info cleaned from the snapshot.{"model": "deepseek-v4-flash", "problem_class": "python-docs-devx-readme", "result": "passed", "tests": 10}