From 03dfa13020ac693448da1dd388887c6b378b2dbe Mon Sep 17 00:00:00 2001 From: Chimera Bot Date: Mon, 24 Aug 2026 16:17:08 +0000 Subject: [PATCH] docs: detect drift on 2026-08-24 --- ...task-18 - Doc-drift-detected-2026-08-24.md | 90 +++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 backlog/tasks/task-18 - Doc-drift-detected-2026-08-24.md diff --git a/backlog/tasks/task-18 - Doc-drift-detected-2026-08-24.md b/backlog/tasks/task-18 - Doc-drift-detected-2026-08-24.md new file mode 100644 index 0000000..2dba00c --- /dev/null +++ b/backlog/tasks/task-18 - Doc-drift-detected-2026-08-24.md @@ -0,0 +1,90 @@ +--- +id: TASK-18 +title: 'Docs: Doc-claim drift detected on 2026-08-24' +status: To Do +assignee: [] +created_date: '2026-08-24 00:00' +updated_date: '2026-08-24 00:00' +labels: + - docs +priority: Low +dependencies: [] +--- + +## Description + +Automated doc-drift audit run on 2026-08-24 against 12 doc files. Found **13 confirmed drift findings** across 8 files. Severity breakdown: **9 P1 (dev-doc error)**, **4 P2 (minor staleness)**. + +> This task was created by the scheduled documentation drift detector. Do not "fix" source code to match docs; fix docs to match source (or update both when the code is wrong). + +--- + +### Findings by file + +#### docs/architecture.md + +- docs/architecture.md:165 — `` `DEMO_MODE` | `true` `` — The Default column lists `true`, which is not a valid `DEMO_MODE` value. Actual default in `app/config.py:31` is `'full'` (`os.environ.get('DEMO_MODE', 'full')`). — **Proposed fix**: Change default cell to `` `full` ``. — **P1** + +- docs/architecture.md (blueprint table) — `education` blueprint exists at `app/blueprints/education/` with routes and a test file (`tests/unit/test_education_routes.py`) but is not listed in the router architecture table. — **Proposed fix**: Add `education/` row to the blueprint listing. — **P2** + +#### docs/developer-guide.md + +- docs/developer-guide.md:47 — `` `DEMO_MODE` | `strict` `` — Default column says `strict`; actual default in `app/config.py:31` is `'full'`. CLI `--demo-mode` has no default (line 21-24 of `app/cli.py`). — **Proposed fix**: Change default cell to `` `full` ``. — **P1** + +- docs/developer-guide.md:243-246 — `` make -C apps/vuln-api test-unit ``, `test-quick`, `test-vulnerability`, `test-smoke` — No `Makefile` exists in the repo. The corresponding `just` recipes exist in `apps/vuln-api/justfile` (`test-unit`, `test-quick`, `test-vulnerability`, `test-smoke`). — **Proposed fix**: Replace `make -C apps/vuln-api ` with `just -f apps/vuln-api/justfile `. — **P1** + +#### README.md + +- README.md:48 — `` `DEMO_MODE` | `strict` `` — Default column says `strict`; actual default in `app/config.py:31` is `'full'`. — **Proposed fix**: Change default cell to `` `full` ``. — **P1** + +#### docs/endpoints-catalog.md + +- docs/endpoints-catalog.md:15 — `"verified against the live route table via \`just docs-drift\`"` — The recipe `docs-drift` does not exist in either the root `justfile` or `apps/vuln-api/justfile`. The closest existing recipe is `docs-check` (`apps/vuln-api/justfile:105`). — **Proposed fix**: Change `just docs-drift` to `just -f apps/vuln-api/justfile docs-check`. — **P1** + +#### apps/vuln-api/AGENTS.md + +- apps/vuln-api/AGENTS.md:116 — `"In production (Docker), nginx handles the proxy."` — No nginx appears in any Dockerfile (`Dockerfile`, `Dockerfile.prod`, `Dockerfile.fargate`); uvicorn serves directly on port 80/8880/8080 in all container variants. — **Proposed fix**: Remove or rewrite the sentence; production is single-process uvicorn, no proxy layer. — **P1** + +- apps/vuln-api/AGENTS.md:127 — `` `make test-coverage` `` — No `Makefile` exists; coverage target is `just -f apps/vuln-api/justfile test-coverage` (or bare `just test-coverage` from inside `apps/vuln-api/`). — **Proposed fix**: Replace `make test-coverage` with `just test-coverage`. — **P2** + +#### apps/vuln-api/API-DOCUMENTATION.md + +- apps/vuln-api/API-DOCUMENTATION.md:17 vs :1015 — Line 17 says "**469 Vulnerable Endpoints**"; line 1015 says "**Total Endpoints**: 450+". Internally inconsistent within the same file. — **Proposed fix**: Reconcile to a single number consistent with the live route count. — **P2** + +#### apps/vuln-api/tests/README.md + +- apps/vuln-api/tests/README.md:66-76 — References `tests/vulnerability/` directory containing `test_sql_injection.py`, `test_xss.py`, `test_command_injection.py`, `test_auth_bypass.py`. This directory does not exist. Also references `tests/pytest.ini`, `tests/run_tests.sh`, and `tests/justfile` — none of these files exist. — **Proposed fix**: Remove references to the nonexistent `tests/vulnerability/` directory and files, or create them. — **P1** + +- apps/vuln-api/tests/README.md:234-235 — Claims `conftest.py` provides fixtures `auth_headers`, `sample_data`, `mock_services`. None of these names appear in `tests/conftest.py` (actual fixtures: `client`, `set_session`, `read_session`, `mock_users`, `mock_medical_records`, etc.). — **Proposed fix**: Update the conftest fixture list to match actual fixtures. — **P1** + +- apps/vuln-api/tests/README.md:211-213 — "Coverage Requirements: Minimum overall: 90%, New code: 95%, Critical paths: 100%". The actual coverage gate in `apps/vuln-api/justfile:47-48` (`test-coverage` recipe) is `--cov-fail-under=80`. — **Proposed fix**: Update coverage requirement table to show 80% minimum. — **P1** + +#### docs/vulnerability-inventory.md + +- docs/vulnerability-inventory.md:46 — `"being reconciled under \`TASK-17\`"` — TASK-17 does not exist in `backlog/tasks/` or `backlog/completed/`. — **Proposed fix**: Either create TASK-17 or update the reference to the actual tracking task. — **P1** + +#### Cross-file internal inconsistency + +- README.md, AGENTS.md, docs/dockerhub-overview.md, apps/vuln-api/README.md — All claim "**456+**" endpoints. — endpoints-catalog.md:15,590 and apps/vuln-api/API-DOCUMENTATION.md:17 — Both claim "**469**" unique endpoints. — These numbers are internally inconsistent across the audited doc set. — **Proposed fix**: Reconcile to a single authoritative endpoint count (run `just -f apps/vuln-api/justfile docs-check` to get the live count). — **P2** + +--- + +## Acceptance Criteria + + +- [ ] #1 `docs/architecture.md` DEMO_MODE default corrected from `true` to `full`. +- [ ] #2 `docs/architecture.md` blueprint table includes the `education` domain. +- [ ] #3 `docs/developer-guide.md` DEMO_MODE default corrected from `strict` to `full`. +- [ ] #4 `docs/developer-guide.md` testing section `make -C` commands replaced with `just -f apps/vuln-api/justfile` equivalents. +- [ ] #5 `README.md` DEMO_MODE default corrected from `strict` to `full`. +- [ ] #6 `docs/endpoints-catalog.md` `just docs-drift` reference corrected to `just -f apps/vuln-api/justfile docs-check`. +- [ ] #7 `apps/vuln-api/AGENTS.md` nginx proxy claim removed or corrected. +- [ ] #8 `apps/vuln-api/AGENTS.md` `make test-coverage` corrected to `just test-coverage`. +- [ ] #9 `apps/vuln-api/API-DOCUMENTATION.md` endpoint count "469" and "450+" reconciled to a single value. +- [ ] #10 `apps/vuln-api/tests/README.md` references to nonexistent `tests/vulnerability/`, `tests/pytest.ini`, `tests/run_tests.sh`, `tests/justfile` removed or the files created. +- [ ] #11 `apps/vuln-api/tests/README.md` conftest fixture list corrected to match actual fixtures in `tests/conftest.py`. +- [ ] #12 `apps/vuln-api/tests/README.md` coverage requirement table corrected from 90%/95%/100% to match the actual 80% gate. +- [ ] #13 `docs/vulnerability-inventory.md` TASK-17 reference resolved (create the task or update the reference). +- [ ] #14 Endpoint count harmonized across all 12 audited docs to a single authoritative number. +- [ ] #15 All linked claims verified against current code after fixes are applied. +