First PR shipping after ~/.vibe/skills/verifier/ went live. The verifier ran a Dimension-B (docs homogeneity + code↔docs confrontation) audit on already-merged PRs and flagged 3 BLOCK issues — endpoints / env vars introduced in code but never documented:
Optional: BDD_SCHEMA_ISOLATION (the new flag from PR #35 — featured prominently with 2.85x speedup note + ADR-0025 ref), FEATURE, GODOG_TAGS, BDD_ENABLE_CLEANUP_LOGS
Future PRs get verified at the verifier stage of their ICM workspace before merge → these gaps don't recur
This is also the first proof point that the Trinity-inspired explicit Verifier role (added today to vibe-workspace.sh) catches real bugs that ad-hoc review would miss. PRs #20, #29, #35 all passed code review and CI — only the systematic Dim-B audit found the doc gaps.
Verification
Both files use relative links per docs-homogeneity.md B.1 checklist
All referenced ADRs exist (0014, 0021, 0022, 0008, 0024, 0025)
All referenced cross-doc files exist (BDD_GUIDE.md)
Endpoint paths verified against router code (pkg/server/server.go, pkg/auth/handlers.go)
Env var defaults verified against pkg/config/config.go
BDD_SCHEMA_ISOLATION behavior verified against pkg/bdd/testserver/server.go
Out of scope
Updating Swagger annotations to include /api/healthz and /api/admin/cache/flush — these endpoints currently lack @router swag comments. Will be a follow-up if user wants the Swagger UI to be the single source of truth.
ADR-0026 documenting BDD_SCHEMA_ISOLATION as the recommended default — covered by ADR-0025 ("Implemented since PR #35").
## Context
First PR shipping after `~/.vibe/skills/verifier/` went live. The verifier ran a Dimension-B (docs homogeneity + code↔docs confrontation) audit on already-merged PRs and flagged 3 **BLOCK** issues — endpoints / env vars introduced in code but never documented:
| Source PR | Symbol | Verifier finding |
|---|---|---|
| #20 | `GET /api/healthz` | 0 mentions in `documentation/` |
| #29 | `POST /api/admin/cache/flush` | 0 mentions in `documentation/` |
| #35 | `BDD_SCHEMA_ISOLATION` env var | 0 mentions in `documentation/` or `adr/` |
## Changes
### `documentation/API.md` (new — 90 lines)
Reference for HTTP endpoints exposed by the Go server:
- Conventions (base URL, prefix, content type, errors)
- System endpoints (`/api/healthz`)
- Admin endpoints (`/api/admin/cache/flush`) — with admin-only-network warning
- v1 API: `/api/v1/login`, `/api/v1/register`, `/api/v1/greet/{lang}` (auth-gated)
- v2 API placeholder
- Swagger UI link
- Cross-refs: ADR-0014 (Viper config), ADR-0021 (auth), ADR-0022 (cache)
Each endpoint documents method, path, auth requirement, request body, response schema, status codes — with curl examples.
### `documentation/BDD_TEST_ENV.md` (new — 89 lines)
Companion to existing `BDD_GUIDE.md`. Documents the env-var surface:
- **Required**: `DLC_DATABASE_*` (host, port, user, password, name, ssl_mode)
- **Optional**: `BDD_SCHEMA_ISOLATION` (the new flag from PR #35 — featured prominently with **2.85x speedup** note + ADR-0025 ref), `FEATURE`, `GODOG_TAGS`, `BDD_ENABLE_CLEANUP_LOGS`
- 3 recommended commands: parallel-isolated, scoped-feature, repro-CI
- Cross-refs: BDD_GUIDE.md, ADR-0008, ADR-0024, ADR-0025
## Why ship this now
Closes the **verifier feedback loop**:
1. Skill produces actionable findings (3 documented BLOCK issues, with file paths + fix suggestions)
2. Findings get fixed in the very next PR (this one)
3. Future PRs get verified at the **verifier stage** of their ICM workspace before merge → these gaps don't recur
This is also the first proof point that the Trinity-inspired explicit Verifier role (added today to `vibe-workspace.sh`) catches real bugs that ad-hoc review would miss. PRs #20, #29, #35 all passed code review and CI — only the systematic Dim-B audit found the doc gaps.
## Verification
- [x] Both files use **relative** links per `docs-homogeneity.md` B.1 checklist
- [x] All referenced ADRs exist (0014, 0021, 0022, 0008, 0024, 0025)
- [x] All referenced cross-doc files exist (BDD_GUIDE.md)
- [x] Endpoint paths verified against router code (`pkg/server/server.go`, `pkg/auth/handlers.go`)
- [x] Env var defaults verified against `pkg/config/config.go`
- [x] BDD_SCHEMA_ISOLATION behavior verified against `pkg/bdd/testserver/server.go`
## Out of scope
- Updating Swagger annotations to include `/api/healthz` and `/api/admin/cache/flush` — these endpoints currently lack `@router` swag comments. Will be a follow-up if user wants the Swagger UI to be the single source of truth.
- ADR-0026 documenting BDD_SCHEMA_ISOLATION as the recommended default — covered by ADR-0025 ("Implemented since PR #35").
First PR shipping after the new ~/.vibe/skills/verifier/ skill went live.
Verifier ran on already-merged PRs and flagged 3 BLOCK doc gaps:
- /api/healthz (PR #20) — 0 mentions in documentation/
- /api/admin/cache/flush (PR #29) — 0 mentions
- BDD_SCHEMA_ISOLATION env var (PR #35) — 0 mentions
Adds:
- documentation/API.md — system + admin + v1 + v2 endpoint reference,
curl examples, response schemas, ADR cross-refs, Swagger UI link
- documentation/BDD_TEST_ENV.md — required + optional env vars
(BDD_SCHEMA_ISOLATION, FEATURE, GODOG_TAGS, BDD_ENABLE_CLEANUP_LOGS),
recommended local commands, 2.85x speedup note
Both files use relative links per docs-homogeneity.md checklist.
Closes the verifier feedback loop: skill produces actionable findings →
findings get fixed in next PR. Demonstrates audit→fix loop on real diffs.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Context
First PR shipping after
~/.vibe/skills/verifier/went live. The verifier ran a Dimension-B (docs homogeneity + code↔docs confrontation) audit on already-merged PRs and flagged 3 BLOCK issues — endpoints / env vars introduced in code but never documented:GET /api/healthzdocumentation/POST /api/admin/cache/flushdocumentation/BDD_SCHEMA_ISOLATIONenv vardocumentation/oradr/Changes
documentation/API.md(new — 90 lines)Reference for HTTP endpoints exposed by the Go server:
/api/healthz)/api/admin/cache/flush) — with admin-only-network warning/api/v1/login,/api/v1/register,/api/v1/greet/{lang}(auth-gated)Each endpoint documents method, path, auth requirement, request body, response schema, status codes — with curl examples.
documentation/BDD_TEST_ENV.md(new — 89 lines)Companion to existing
BDD_GUIDE.md. Documents the env-var surface:DLC_DATABASE_*(host, port, user, password, name, ssl_mode)BDD_SCHEMA_ISOLATION(the new flag from PR #35 — featured prominently with 2.85x speedup note + ADR-0025 ref),FEATURE,GODOG_TAGS,BDD_ENABLE_CLEANUP_LOGSWhy ship this now
Closes the verifier feedback loop:
This is also the first proof point that the Trinity-inspired explicit Verifier role (added today to
vibe-workspace.sh) catches real bugs that ad-hoc review would miss. PRs #20, #29, #35 all passed code review and CI — only the systematic Dim-B audit found the doc gaps.Verification
docs-homogeneity.mdB.1 checklistpkg/server/server.go,pkg/auth/handlers.go)pkg/config/config.gopkg/bdd/testserver/server.goOut of scope
/api/healthzand/api/admin/cache/flush— these endpoints currently lack@routerswag comments. Will be a follow-up if user wants the Swagger UI to be the single source of truth.