88 lines
6.2 KiB
Markdown
88 lines
6.2 KiB
Markdown
---
|
||
phase: 6
|
||
slug: turn-by-turn-guidance-live-driving
|
||
status: draft
|
||
nyquist_compliant: false
|
||
wave_0_complete: false
|
||
created: 2026-10-24
|
||
---
|
||
|
||
# Phase 6 — Validation Strategy
|
||
|
||
> Per-phase validation contract for feedback sampling during execution.
|
||
|
||
---
|
||
|
||
## Test Infrastructure
|
||
|
||
| Property | Value |
|
||
|----------|-------|
|
||
| **Framework** | Hand-rolled zero-dep runners (established Phases 1–5): `web/test/runner.mjs`, `bot/test/runner.mjs`, `routing/test/runner.mjs` over `harness.mjs` registries |
|
||
| **Config file** | none — auto-discovers `*.test.mjs` per workspace |
|
||
| **Quick run command** | `npm test -w web` / `npm test -w bot` / `npm run routing:test` |
|
||
| **Full suite command** | `npm run web:test && npm run bot:test && npm run routing:test` (+ `npm run web:capture` for legs, `npx wrangler dev` + `/cdn-cgi/local/scheduled` for cron integration) |
|
||
| **Estimated runtime** | ~30 seconds (unit/replay suites); cron integration adds ~60 s (wrangler dev boot) |
|
||
|
||
---
|
||
|
||
## Sampling Rate
|
||
|
||
- **After every task commit:** Run the touched workspace's quick suite (`npm test -w web` / `npm test -w bot` / `npm run routing:test`)
|
||
- **After every plan wave:** Run `npm run web:test && npm run bot:test && npm run routing:test` + typechecks (`web:typecheck` / `bot:typecheck` / `routing:typecheck`) + theme audit when CSS touched
|
||
- **Before `/gsd-verify-work`:** Full suite green + capture legs (extended with guidance legs) + the one real drive + A\* CPU measurement printed and inside budget
|
||
- **Max feedback latency:** 60 seconds
|
||
|
||
---
|
||
|
||
## Per-task Verification Map
|
||
|
||
| task ID | Plan | Wave | Requirement | Threat Ref | Secure Behavior | Test Type | Automated Command | File Exists | Status |
|
||
|---------|------|------|-------------|------------|-----------------|-----------|-------------------|-------------|--------|
|
||
| (assigned at plan time) | 01 | 0 | Engine A (D-01/D-03) | T-06-03 | graph header magic+version+size check on decode, fail-honest | unit | `npm run routing:test` | ❌ W0 (`routing/test/graph.test.mjs`, `astar.test.mjs`, `snap.test.mjs` + committed mini-graph fixture) | ⬜ pending |
|
||
| (assigned at plan time) | — | — | GUID-01 | — | N/A | unit + capture leg | `npm test -w web` (guidance-surface suite) | ❌ W0 (`web/test/guidance-surface.test.mjs`) | ⬜ pending |
|
||
| (assigned at plan time) | — | — | GUID-02 | — | N/A | replay (pure state machine, JSON drives) | `npm test -w web` (replay suite) + real-drive device gate | ❌ W0 (`web/test/guidance-replay.test.mjs`, `web/test/fixtures/drives/*.json`) | ⬜ pending |
|
||
| (assigned at plan time) | — | — | GUID-03 | — | N/A | replay | `npm test -w web` (eta suite inside replay fixtures) | ❌ W0 (`web/test/guidance-eta.test.mjs`) | ⬜ pending |
|
||
| (assigned at plan time) | — | — | GUID-04 | — | capability-guard no-op when unsupported | structural + unit | `npm test -w web` | ❌ W0 (inside guidance-surface suite) | ⬜ pending |
|
||
| (assigned at plan time) | — | — | GUID-05 | T-06-02 / T-06-04 | cron sends ONLY to envelope.chat_id from KV; no client-supplied chat ids | unit + wrangler-dev cron endpoint + KV budget pins | `npm test -w bot` + `curl "http://localhost:8787/cdn-cgi/local/scheduled"` | ❌ W0 (`bot/test/guidance-cron.test.mjs`) | ⬜ pending |
|
||
| (assigned at plan time) | 06 | 3 | GUID-06 | — | N/A | behavioral (route-surface suite) + unit (cron projection math) | `npm test -w web` + `npm test -w bot` | ❌ W0 (06-06 task 3: ?g= resume boot + envelope POST/DELETE flows in `web/test/route-surface.test.mjs`; projection in `bot/test/guidance-cron.test.mjs` — 06-07) | ⬜ pending |
|
||
| (assigned at plan time) | — | — | PX-01 | — | N/A | behavioral (fake WebApp) | `npm test -w web` (backbutton-graph suite) | ❌ W0 (extend existing backbutton coverage) | ⬜ pending |
|
||
| (assigned at plan time) | — | — | PX-03 | — | N/A | structural + unit | `npm test -w web` | ❌ W0 (inside guidance-surface suite) | ⬜ pending |
|
||
| (assigned at plan time) | — | — | Engine A perf (A1/A4) | T-06-01 | Bearer-gated `/api/route`; CPU budget per request is the natural rate limiter | integration (wrangler dev CPU + timing) | `npx wrangler dev` + scripted route calls; read invocation CPU logs | ❌ W0 (measurement script; prints its measurement) | ⬜ pending |
|
||
| (assigned at plan time) | — | — | D-14 (trip end) | T-06-04 | envelope deleted on arrival AND abandon; TTL 7200 s | unit (KV fake) + bot gates | `npm test -w bot` | ❌ W0 (guidance-envelope service suite; GE4–GE7 re-pins) | ⬜ pending |
|
||
|
||
*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
|
||
|
||
---
|
||
|
||
## Wave 0 Requirements
|
||
|
||
- [ ] `routing/test/` graph/astar/snap suites + committed mini-graph binary fixture (hand-built tiny CSR — also the replay ground truth)
|
||
- [ ] `web/test/fixtures/drives/` — four recorded streams per D-16 (corridor follow, off-route excursion, missed-turn excursion, GPS jitter)
|
||
- [ ] `web/test/guidance-{replay,eta,surface}.test.mjs` + `bot/test/guidance-cron.test.mjs`
|
||
- [ ] Gate re-pin tasks: RP1/RP2 (bot route surface lands), GE4–GE7 (envelope service lands)
|
||
- [ ] Setup tasks: `wrangler r2 bucket create` + upload script + fork docs; `triggers.crons` + glyph assets in static dir; `npm install -D -w routing sharp` for build scripts
|
||
- [ ] BA9 budget extension to cover `web/src/guidance/` (+ whatever the bundle law names)
|
||
|
||
*(Framework install: none needed — the harness family already exists.)*
|
||
|
||
---
|
||
|
||
## Manual-Only Verifications
|
||
|
||
| Behavior | Requirement | Why Manual | Test Instructions |
|
||
|----------|-------------|------------|-------------------|
|
||
| Real drive: banner legibility in sunlight, reroute self-heal on actual missed turn, resume after minimize, trip-end messaging | GUID-02 / PX-03 device gate | Physical GPS + real road geometry cannot be simulated; the phase's declared protocol (D-16, phases 3–5 precedent) | One real drive with capture checklist: start route, miss a turn deliberately, minimize mid-drive, re-open, end trip |
|
||
|
||
---
|
||
|
||
## Validation Sign-Off
|
||
|
||
- [ ] All tasks have `<automated>` verify or Wave 0 dependencies
|
||
- [ ] Sampling continuity: no 3 consecutive tasks without automated verify
|
||
- [ ] Wave 0 covers all MISSING references
|
||
- [ ] No watch-mode flags
|
||
- [ ] Feedback latency < 60 s
|
||
- [ ] `nyquist_compliant: true` set in frontmatter
|
||
|
||
**Approval:** pending
|