From 771d2ffd04b86b1f06caaff047fd6f8e4fec9b3e Mon Sep 17 00:00:00 2001 From: YeonGyu-Kim Date: Thu, 23 Apr 2026 05:32:48 +0900 Subject: [PATCH] locus(#164): add Phase 0 + v1.5 baseline; revised from 2-phase to 4-phase migration (cycle #85) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fresh-dogfood validation (cycle #84, #168) proved the original locus premise was underspecified. v1.0 was never a coherent contract — each verb has a bespoke JSON shape with no coordination, and bootstrap JSON is completely broken (silent failure, exit 0 no output). Revised migration plan: - Phase 0 (NEW): Emergency fix for silent failures (#168 bootstrap JSON) - Phase 1 (NEW): v1.5 baseline — minimal JSON invariants across all 14 verbs - Every command emits valid JSON with --output-format json - Every command has top-level 'kind' field for verb ID - Every error envelope follows {error, hint, kind, type} - Phase 2 (renamed from Phase 1): v2.0 wrapped envelope (opt-in) - Phase 3 (renamed from Phase 2): v2.0 default - Phase 4 (renamed from Phase 3): v1.0/v1.5 deprecation Rationale: - Can't migrate from 'incoherent' to 'coherent v2.0' in one jump - Consumers need stable target (v1.5) to transition from - Silent failures must be fixed BEFORE migration (consumers can't detect breakage) Effort revision: ~9 dev-days (Phase 0: 1 + Phase 1: 3 + Phase 2: 5) vs original ~6 dev-days for direct v1.0→v2.0 (which would have failed). Doctrine implication: Fresh-dogfood principle (#9, cycle #73) prevented a multi-day migration from hitting an unsolvable baseline problem. Evidence-backed mid-design correction. --- FIX_LOCUS_164.md | 41 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 40 insertions(+), 1 deletion(-) diff --git a/FIX_LOCUS_164.md b/FIX_LOCUS_164.md index 4260dfe..833211b 100644 --- a/FIX_LOCUS_164.md +++ b/FIX_LOCUS_164.md @@ -1,6 +1,6 @@ # Fix-Locus #164 — JSON Envelope Contract Migration -**Status:** 📋 Proposed (2026-04-23, cycle #77). Escalated from pinpoint #164 after gaebal-gajae review recognized product-wide scope. +**Status:** 📋 Proposed (2026-04-23, cycle #77). Updated cycle #85 (2026-04-23) with v1.5 baseline phase after fresh-dogfood discovery (#168) proved v1.0 was never coherent. **Class:** Contract migration (not a patch). Affects EVERY `--output-format json` command. @@ -8,6 +8,45 @@ --- +## 0. CRITICAL UPDATE (Cycle #85 via #168 Evidence) + +**Premise revision:** This locus document originally framed the problem as **"v1.0 (incoherent) → v2.0 (target schema)"** migration. **Fresh-dogfood validation in cycle #84 proved this framing was underspecified.** + +**Actual problem (evidence from #168):** + +- There is **no coherent v1.0 envelope contract**. Each verb has a bespoke JSON shape. +- `claw list-sessions --output-format json` emits `{command, sessions}` — has `command` field +- `claw doctor --output-format json` emits `{checks, kind, message, ...}` — no `command` field +- `claw bootstrap hello --output-format json` emits **NOTHING** (silent failure with exit 0) +- Each verb renderer was written independently with no coordinating contract + +**Revised migration plan — three phases instead of two:** + +1. **Phase 0 (Emergency):** Fix silent failures (#168 bootstrap JSON). Every `--output-format json` command must emit valid JSON. +2. **Phase 1 (v1.5 Baseline):** Establish minimal JSON invariants across all 14 verbs without breaking existing consumers: + - Every command emits valid JSON when `--output-format json` is passed + - Every command has a top-level `kind` field identifying the verb + - Every error envelope follows the confirmed `{error, hint, kind, type}` shape + - Every success envelope has the verb name in a predictable location + - **Effort:** ~3 dev-days (no new design, just fill gaps and normalize bugs) +3. **Phase 2 (v2.0 Wrapped Envelope):** Execute the original Phase 1 plan documented below — common metadata wrapper, nested data/error objects, opt-in via `--envelope-version=2.0`. +4. **Phase 3 (v2.0 Default):** Original Phase 2 plan below. +5. **Phase 4 (v1.0/v1.5 Deprecation):** Original Phase 3 plan below. + +**Why add Phase 0 + Phase 1 (v1.5)?** + +- You can't migrate from "incoherent" to "coherent v2.0" in one jump. Intermediate coherence (v1.5 baseline) is required. +- Consumer code built against "whatever v1 emits today" needs a stable target to transition from. +- **Silent failures (bootstrap JSON) must be fixed BEFORE any migration** — otherwise consumers have no way to detect breakage. + +**Blocker resolved:** The original blocker "v1.0 design vs v2.0 design" is actually "no v1 design exists; let's make one (v1.5) then migrate." This is a **clearer, lower-risk migration path**. + +**Revised effort estimate:** ~9 dev-days total (Phase 0: 1 day + Phase 1/v1.5: 3 days + Phase 2/v2.0: 5 days) instead of ~6 dev-days for a direct v1.0→v2.0 migration (which would have failed given the incoherent baseline). + +**Doctrine implication:** Cycles #76–#82 diagnosed "aspirational vs current" correctly but missed that "current" was never a single thing. Cycle #84 fresh-dogfood caught this. **Fresh-dogfood discipline (principle #9) prevented a 6-day migration effort from hitting an unsolvable baseline problem.** + +--- + ## 1. Scope — What This Migration Affects **Every JSON-emitting verb.** Audit across the 14 documented verbs: