arcodange/dance-lessons-coach
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

📝 docs: homogenize API + BDD env docs (verifier skill audit) #36

Merged
arcodange merged 1 commits from docs/homogenize-api-and-bdd-env into main 2026-05-04 07:53:32 +02:00
Conversation 0 Commits 1 Files Changed 2 +179
arcodange commented 2026-05-04 07:51:53 +02:00
Owner
Copy Link

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

  • 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").
arcodange added 1 commit 2026-05-04 07:51:54 +02:00
📝 docs: homogenize API + BDD env docs (verifier skill audit) 89f2b1ed15 
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.
arcodange merged commit 75ae7e3c17 into main 2026-05-04 07:53:32 +02:00
arcodange deleted branch docs/homogenize-api-and-bdd-env 2026-05-04 07:53:32 +02:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
arcodange
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: arcodange/dance-lessons-coach#36
Delete Branch "docs/homogenize-api-and-bdd-env"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?