docs(architecture): API design swarm output — v1.0 contract locked
Six-agent design swarm executed end-to-end on 2026-05-07 evening per
.planning/architecture/HANDOFF-2026-05-07.md. The architectural pivot
to API-first reaches lock state: v1.0 = JARVIS-API-DESIGN-v0.1.md +
JARVIS-API-DESIGN-v0.2.md (UQ-1..UQ-5 answered).
Swarm output (.planning/architecture/):
- INVENTORY.md (~190 capabilities, file:line cited; ALIVE/DEAD/
DEFERRED/RETIRED-CANDIDATE classification)
- JARVIS-API-DESIGN-v0.1.md (1036 lines; 7 surfaces — Turn / Voice /
Memory / Vision / Settings / Diagnostics / Self; CQRS framing;
TurnID universal correlation; typed Results)
- REVIEW-API-CORRECTNESS.md (21 findings: 2 BLOCKING, 5 HIGH)
- REVIEW-MIGRATION-RISK.md (19 findings: 1 BLOCKING, 7 HIGH;
M-0..M-7 cutover sequence)
- REVIEW-TEST-CONTRACT.md (16 findings: 2 BLOCKING, 5 HIGH; harness
shape recommendation)
- JARVIS-API-DESIGN-v0.2.md (synthesis delta; every critic finding
dispositioned ACCEPT/DEFER/USER-DECISION; UQ-1..UQ-5 locked in §5)
- JARVIS-API-TEST-CONTRACT.md (~70 scenarios across 7 surfaces +
cross-surface; B-02..B-08 reproduction matrix)
- JARVIS-API-MIGRATION-PLAN.md (M-0..M-7 + B-02 tactical patch;
~52 distinct gates; 19-26 engineer-day estimate)
- README.md (artifact index + reading order)
Locked decisions:
- UQ-1: runtime gate JARVIS_HARNESS=1 (single binary)
- UQ-2: B-02 tactical patch outside migration + streamTruncated
regression test; B-04 stays in M-6
- UQ-3: explicit Voice.synthesizeTurn(turnId:text:tier:) command
- UQ-4: Settings owns ALL configuration mutation; Voice retains only
runtime-control verbs (pttDown/pttUp/cancelTTS/synthesizeTurn);
bargeIn migrates to Turn surface
- UQ-5: parametric harness mandated — every scenario runs
.inProcessActor AND .jsonRoundTripWebView
Tools/jarvis-diag/ — Swift Package skeleton authored by Phase 5:
type signatures + scenario stubs only, no implementation logic.
Compiles green (swift build under Tools/jarvis-diag/). M-0 step 3
wires it against packages/JarvisAPI/ once that package exists.
Constraints honored: zero code changes outside .planning/architecture/
and Tools/jarvis-diag/. No fixes to B-02..B-08 inline. Parallel agents
wrote disjoint files (.continue-here.md anti-pattern preserved).
Next session: cross-AI peer review of v1.0 (GPT-5 Pro / Gemini 2.5 Pro
/ fresh Opus), then B-02 tactical patch on develop, then M-0 (pre-
migration gates), then M-1 (Self surface) on its own feature branch.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
james.maesandClaude Opus 4.7
46590cd9aa