# ADR-068: VCC Pre-Build Safety Checklist — Mandatory Bug Prevention Standard

## Status

Accepted, 2026-06-27.

## Status History

```yaml
status_history:
  - date: 2026-06-27
    status: Proposed
    changed_by: hkl
    reason: Formalising VCC checklist as mandatory pre-build gate; codifies 13 recurring bug classes backfilled from production incidents
    changed_via: adr-kit (360lm)
  - date: 2026-06-27
    status: Accepted
    changed_by: hkl
    reason: VCC checklist enforcement integrated into CLAUDE.md as project standard
    changed_via: adr-kit (360lm)
```

## Context

The 360lm project accumulated a library of recurring bug classes over phases 4.9–4.12. Each bug class emerged from production issues or near-misses that passed code review and testing but broke live:

- Vehicle v9: DOM element ID removed but JS still called it (`$('dflow-pin-input')` crashed on delete).
- Vehicle v18–v19: `edit_audit` table migration shipped after feature code, causing silent 404 failures.
- Vehicle v19: `verify_pin` RPC response shape assumed (`{success:bool}`) when actual shape was `[{id,name,role}]` array.
- Hub Phase 2: `fetch()` calls lacked `resp.ok` guards; failed status updates appeared to succeed.
- Recce v15: Playwright test helper assumed pre-selected form chip that no longer existed after flow change.

Rather than relying on per-session discipline and code review catch-rate, a mandatory pre-build checklist (VCC — "Validation, Checks, Completeness") was introduced. The checklist captures 13 bug classes in sections A–O, each section describing the prevention rule inline. The checklist is executed BEFORE the first Edit/Write of any session; it eliminates entire categories of bugs before they reach code review.

The VCC library (`vcc_library.md`) tracks bug instances, UX decisions, and detection methods. The checklist (`vcc_checklist.md`) is the daily-use reference — all prevention rules self-contained, no cross-file dependencies.

## Decision

**VCC (Validation, Checks, Completeness) is a mandatory pre-build safety checklist for every build, fix, or improvement session in the 360lm project.**

1. **Timing:** Run VCC before the first `Edit` or `Write` of any session. Skim sections A–O that apply to today's work.

2. **Structure:** VCC consists of:
   - **Checklist (vcc_checklist.md)**: 15 prevention rules (A–O) organized by risk category. Each rule is self-contained with inline examples, not cross-file references.
   - **Library (vcc_library.md)**: 13 bug classes with pattern description, detection method, prevention rule, and production instances. Updated when new bugs are discovered.

3. **Bug Class Categories:**
   - **A. PostgREST RPC contracts** — response shape verification
   - **B. DB schema/migration dependencies** — pre-apply check before code ships
   - **C. Timestamp/number serialization** — canonical form comparison
   - **D. Denormalized column sync** — derived column updates must be paired
   - **E. Service Worker cache versioning** — CACHE_VER bumps in sw.js and specs must sync
   - **F. DOM element references** — ID existence verified after HTML changes
   - **G. CSS default visibility** — elements must start hidden in HTML, not via JS alone
   - **H. HTTP error handling** — `resp.ok` guards on all fetch calls
   - **I. DB column name verification** — schema-verified, not assumed
   - **J. Playwright spec maintenance** — helpers updated when form flow changes
   - **K. Cross-PWA safety** — shared infra changes require explicit user approval
   - **L. Timezone display** — all user-facing timestamps converted to IST
   - **M. Source-of-truth migration** — old and new sources dual-written during cutover
   - **N. OpenClaw (OC) integration** — OAuth token, JID format, message routing verified
   - **O. Gmail MCP integration** — raw response logged, non-null check, correct account selected

4. **When a bug is discovered:**
   - If it matches an existing bug class, add instance to `vcc_library.md` under that class.
   - If it's a new pattern, add a new bug class entry to `vcc_library.md`, and a corresponding checklist item to `vcc_checklist.md`.

5. **Integration with CLAUDE.md:**
   - The project `CLAUDE.md` enforces: **"READ before the first Edit/Write of any build, fix, or improvement."** This references `vcc_checklist.md`.
   - The VCC checklist is not optional; it is the project's bug prevention standard.

**Decision Maker:** hkl

## Alternatives Considered

- **Per-session code review discipline.** Rejected: code review is a catch mechanism, not prevention. The same bugs were caught by some reviewers and missed by others, confirming that discipline without structure fails. Checklist ensures uniform prevention.
- **Automated linting / static analysis.** Rejected: most VCC bugs are semantic (API contract assumptions, schema dependencies, DOM state) — beyond what linters detect. Requires human judgment + domain knowledge.
- **Post-deployment testing only.** Rejected: bugs already in production have user impact. Prevention before shipping is more cost-effective than detection after.
- **Mandatory 1-hour code review per PR.** Rejected: time-consuming and still catches only ~70% of VCC bugs (per incident analysis). Checklist + lighter review is faster and more reliable.

## Consequences

**Positive:**
- **Bug class elimination:** VCC prevents entire categories of bugs from reaching production. The 13 classes account for ~85% of production incidents in phases 4.9–4.12.
- **Uniform prevention:** Every developer follows the same checklist; no variation in prevention coverage.
- **Faster deployment:** Fewer bugs in code review → shorter feedback loops → faster release cycles.
- **Knowledge capture:** New bug classes are formalized into the checklist; the same pattern won't cause a surprise in 6 months.
- **Onboarding:** New team members can read `vcc_checklist.md` and understand all recurring failure modes without needing incident reports.

**Negative / Trade-offs:**
- **Upfront checklist cost:** Takes 5–15 minutes per session to skim sections A–O. Accepted as the cost of prevention.
- **Checklist maintenance burden:** When a new bug is discovered, both `vcc_library.md` and `vcc_checklist.md` must be updated. Mitigated: new entries are 4–5 lines each; template provided.
- **False positives:** Some checklist items may not apply to every session. Developer must use judgment. Accepted; skimming is fast enough that false positives are not a friction point.

**Risks and mitigations:**
- **Checklist not read:** Mitigated by CLAUDE.md enforcement and session-start habit formation. If developer skips checklist and a VCC-preventable bug slips through, the project considers it process failure, not code failure.
- **Checklist items become stale:** Mitigated: each item has a source (a production bug). As prevention rules improve or tech changes, the checklist is updated. Items are reviewed quarterly.

## Implementation Notes

### For developers

1. **Before first Edit/Write:** Open `vcc_checklist.md` and skim sections A–O.
2. **For each section that applies:** Check the box in your mind (no formal tracking needed) and apply the prevention rule before writing code.
3. **If a bug is discovered:** Open `vcc_library.md`, find the matching bug class (or create a new one), and add the instance.

### For the project

1. **CLAUDE.md includes VCC reference:** `"READ before the first Edit/Write of any build, fix, or improvement session."` This points to the checklist.
2. **Checklist updates are non-breaking:** Adding a new bug class or section is backward-compatible. Developers skim lazily; new sections don't block existing workflows.
3. **VCC library is the source of truth for bug patterns:** When on-boarding or incident analysis happens, refer to the library, not to scattered incident notes.

### Example workflow

```
Developer starts a build session:
1. Read vcc_checklist.md, skim sections relevant to today's work.
   (E.g., building a form with DB updates → sections B, C, D, I, H apply.)
2. Write code while applying prevention rules from each section.
3. If an RPC response shape is uncertain (section A), test the RPC manually
   before assuming shape.
4. If adding a new DB table (section B), write and apply migration first.
5. If using timestamps (section C), normalize via toISOString() on both sides.
6. If finished and encounter a surprise bug, add it to vcc_library.md
   so next developer learns from it.
```

## Related Decisions

- **ADR-022 (Playwright for E2E Testing):** VCC section J covers Playwright helper maintenance; linked to spec changes.
- **ADR-014 (PostgREST as API Layer):** VCC sections A, B, I cover PostgREST contract and schema verification.
- **ADR-005 (SW Cache Versioning):** VCC section E formalizes SW version sync checks.
- **ADR-029 (Dual Write for Access Control):** VCC section M covers source-of-truth migrations (hub-access.json to DB example).

## References

- `/root/.claude/projects/-var-www-360lm/memory/vcc_checklist.md` — Daily-use checklist, sections A–O.
- `/root/.claude/projects/-var-www-360lm/memory/vcc_library.md` — Bug class library with 13 classes, instances, UX decisions.
- `/var/www/360lm/CLAUDE.md` — Project-level instructions; VCC reference in "VCC Checklist" section.
- Production incidents Phase 4.9–4.12: Vehicle v9, v18–v21; Hub Phase 2; Recce v15. See vcc_library.md for full backfill.