diff --git a/backlog/tasks/task-18 - Doc-drift-detected-2026-08-03.md b/backlog/tasks/task-18 - Doc-drift-detected-2026-08-03.md new file mode 100644 index 0000000..f9650f3 --- /dev/null +++ b/backlog/tasks/task-18 - Doc-drift-detected-2026-08-03.md @@ -0,0 +1,87 @@ +--- +id: TASK-18 +title: 'Docs: fix doc-claim drift detected on 2026-08-03' +status: To Do +assignee: [] +created_date: '2026-08-03 00:00' +updated_date: '2026-08-03 00:00' +labels: + - docs +dependencies: [] +priority: Low +--- + +## Description + + +Automated doc-drift scan run on 2026-08-03 against the 12-file audit set. Twelve concrete claim discrepancies found across 9 files. Findings are grouped by severity and then by file. Note: TASK-17 (referenced in `docs/vulnerability-inventory.md`) is a separate ongoing vulnerability-reconciliation task and is NOT this task. + +### P1 — Dev-doc errors (affects correctness, likely to mislead developers) + +#### docs/architecture.md + +- `docs/architecture.md:165` — `| DEMO_MODE | true | ...` — Default value `true` is not a valid DEMO_MODE option (valid: `full`, `strict`). Actual code default: `'full'` (see `app/config.py:32`: `os.environ.get('DEMO_MODE', 'full')`). Proposed fix: change default column from `true` to `full`. + +- `docs/architecture.md` (directory listing lines 88–116) — `education/` blueprint is missing from the `app/blueprints/` directory listing. The blueprint directory `apps/vuln-api/app/blueprints/education/` exists and is imported at `apps/vuln-api/app/asgi.py:185` (`from app.blueprints.education import education_router`). Proposed fix: add `├── education/ # Education (N routes)` to the listing. + +#### docs/developer-guide.md + +- `docs/developer-guide.md:148` — `"hatchling, with \`force-include\` ensuring \`web_dist/\` makes it into the wheel despite being gitignored"` — `apps/vuln-api/pyproject.toml` `[tool.hatch.build.targets.wheel]` block contains only `packages = ["app"]`; there is no `force-include` directive. Proposed fix: either add the `force-include` directive to pyproject.toml or remove the claim from the doc. + +- `docs/developer-guide.md:333` — `# Output: apps/vuln-api/dist/chimera_api-0.1.0-py3-none-any.whl` — Version `0.1.0` is stale; `apps/vuln-api/pyproject.toml:8` shows `version = "0.1.5"`. Proposed fix: update to `0.1.5` (or use a glob pattern to avoid re-drifting). + +#### docs/endpoints-catalog.md + +- `docs/endpoints-catalog.md:14` and `:599` — Same document claims **469 unique endpoints** (lines 4, 14, 590) and **243 Total Routes** (line 599: "✅ 243 Total Routes: Comprehensive coverage…"). These two counts are internally inconsistent by 226 routes. Proposed fix: reconcile both numbers or remove the "243 Total Routes" implementation-status callout. + +#### README.md + +- `README.md:47` — `| DEMO_MODE | strict | ... |` — The general "Environment Variables" table (not Docker-specific) claims the default is `strict`. The application code default (`app/config.py:32`) is `full`. The production Docker image (`Dockerfile.prod:39`) sets `DEMO_MODE=strict` as an env override, but that is a Docker-layer default, not the application default for pip installs. Proposed fix: change Default column to `full` (matching config.py) and add a note that `Dockerfile.prod` overrides to `strict`. + +#### AGENTS.md (root) + +- `AGENTS.md:116` — `"In production (Docker), nginx handles the proxy."` — No nginx is present in any of the three Dockerfiles (`Dockerfile`, `Dockerfile.prod`, `Dockerfile.fargate`). All use uvicorn directly. `Dockerfile.prod` runs `uvicorn app.asgi:app --workers 4` and the Starlette app serves both the API and SPA from a single process. Proposed fix: replace the nginx claim with "In production (Docker), uvicorn serves both the API and bundled SPA from a single process." + +#### apps/vuln-api/README.md + +- `apps/vuln-api/README.md:7` — `**[docs/API-DOCUMENTATION.md](docs/API-DOCUMENTATION.md)**` — Broken link: `apps/vuln-api/docs/` contains only `archive/` and `openapi.yaml`; there is no `API-DOCUMENTATION.md` at that path. The actual file is `apps/vuln-api/API-DOCUMENTATION.md` (root of vuln-api). Proposed fix: change link target to `API-DOCUMENTATION.md` (remove `docs/` prefix). + +#### apps/vuln-api/API-DOCUMENTATION.md + +- `apps/vuln-api/API-DOCUMENTATION.md:102` — `| **GenAI** | ~1 | ... |` — The Router Organization table claims ~1 GenAI endpoint, but the GenAI section of the same document (lines 347–352) lists 4 endpoints (`/api/v1/genai/chat`, `/api/v1/genai/knowledge/upload`, `/api/v1/genai/agent/browse`, `GET /api/v1/genai/models/config`), matching `docs/api-reference.md` which also states "GenAI (4 routes)". Proposed fix: change `~1` to `~4`. + +#### apps/vuln-api/tests/README.md + +- `apps/vuln-api/tests/README.md:212` — `"Coverage Requirements: Minimum overall: 90%"` — The enforced gate is 80%. See `apps/vuln-api/justfile:48`: `--cov-fail-under=80`. `apps/vuln-api/AGENTS.md:29` and `apps/vuln-api/API-DOCUMENTATION.md` both state 80%. Proposed fix: change to 80%. + +--- + +### P2 — Minor staleness (low risk, cosmetic or confusing but not incorrect at runtime) + +#### apps/vuln-api/AGENTS.md + +- `apps/vuln-api/AGENTS.md:29` — `"Coverage target: 80% minimum (\`make test-coverage\`)"` — There is no `Makefile` in `apps/vuln-api/`; the task runner is `justfile`. The correct command is `just test-coverage`. Proposed fix: replace `make test-coverage` with `just test-coverage`. + +#### apps/vuln-api/API-DOCUMENTATION.md + +- `apps/vuln-api/API-DOCUMENTATION.md:1014` — `"Total Endpoints: 450+"` at document footer contradicts the opening section claim of "469 Vulnerable Endpoints" (line 20) within the same document. Proposed fix: align both to 469 (or whichever reflects the current live route count from `scripts/check_openapi_drift.py`). + + + +## Acceptance Criteria + + +- [ ] #1 `docs/architecture.md` DEMO_MODE default column changed from `true` to `full` +- [ ] #2 `docs/architecture.md` `education/` blueprint added to `app/blueprints/` directory listing +- [ ] #3 `docs/developer-guide.md` `force-include` claim reconciled against pyproject.toml (add directive or remove claim) +- [ ] #4 `docs/developer-guide.md` wheel filename version updated from `0.1.0` to `0.1.5` +- [ ] #5 `docs/endpoints-catalog.md` endpoint count inconsistency resolved (469 vs 243 in same doc) +- [ ] #6 `README.md` DEMO_MODE default updated to `full` with note about Dockerfile.prod override +- [ ] #7 `AGENTS.md` nginx claim replaced with accurate uvicorn description +- [ ] #8 `apps/vuln-api/README.md` broken `docs/API-DOCUMENTATION.md` link fixed +- [ ] #9 `apps/vuln-api/API-DOCUMENTATION.md` GenAI row changed from `~1` to `~4` +- [ ] #10 `apps/vuln-api/tests/README.md` coverage requirement changed from 90% to 80% +- [ ] #11 `apps/vuln-api/AGENTS.md` `make test-coverage` replaced with `just test-coverage` +- [ ] #12 `apps/vuln-api/API-DOCUMENTATION.md` footer endpoint count aligned with header (450+ vs 469) +- [ ] #13 All linked claims verified against current code after fixes are applied +