# v0.4.0 — Entry Track (sprint plan)

> Status: open — entered 2026-05-25 directly after v0.3.3 stabilization release.
> Created: 2026-05-25
> Companion documents:
>   - `ROADMAP.md` §v0.4.0 — Layer 4 Lifecycle Semantics (original scope T1-T7 across 3 tracks)
>   - `docs/handovers/v0.3.x-direction5-auto-routing-track.md` — D5 closure (input to D1 stage expansion plumbing)
>   - `reports/promo-assets/v3prime-direction5-router-result.md` — D5 result doc (operator STEP 7 sweep procedure)
>   - Memory: `direction_5_auto_routing_closure` / `feedback_d1_d5_retry_doubled_wiring_gap`

## Purpose

v0.3.x closed on 2026-05-25 with three Zenodo-archived releases (v0.3.1 D1 / v0.3.2 D5 / v0.3.3 D6 retry wiring). Cycle stable. v0.4 entry triggered.

The original `ROADMAP.md` v0.4.0 scope is **Layer 4 Lifecycle Semantics** (T1 Lifecycle states + T2 Event-driven transitions + T7 Cross-workspace federation primitives — see PR #403 first-bundle design). That theme remains intact and lands in Sprint 5 below.

Before Sprint 5 (architectural shift), v0.4 runs **5 stabilization+UX sprints** to land user-facing improvements, plumbing carryovers, and retrieval quality lift. This handover sequences them by efficiency: ROI per PR + dependency direction.

## Sprint sequence

### Sprint 0 — v0.4 entry (this PR)

- `ROADMAP.md` — v0.3.0 header marked closed + v0.3.3 stabilization summary + v0.4.0 active
- This handover doc
- Memory update (`project_state.md`, `MEMORY.md` index)

Out: any code changes. Sprint 0 is pure docs/governance.

### Sprint 1 — Data correctness + RAG quality (C)

Two user-surfaced issues (2026-05-25):

- **#1 graph entity-event relation diagnostic + fix** — operator observed that the "비트코인 스팟 ETF 일괄 승인" event entity is not linked to the existing "비트코인" entity in the inference graph. Diagnostic first (read-only data check on `wiki/entity/prod/{org,event,concept}` + graph_engine snapshot) — fix path decided once root cause is clear (relation extraction gap / wiki ingestion gap / entity-type mismatch).
- **#2 query language detection + answer matching** — verify the existing detection branches (`_is_korean` etc.) correctly classify mixed Korean/English queries and the answer generator emits the same language as the question. Bug fix or contract test addition depending on findings.

Acceptance: bug-fix PRs land with regression tests pinning the corrected behavior. Production observable: same-language answers + no orphan event entities for high-traffic event topics.

Phase split: 1 PR per issue (~2 PRs total). Ships v0.4.0-alpha.1.

### Sprint 2 — UI consistency bundle (B)

Four user-surfaced issues (2026-05-25) + one carryover (admin.html 3-page split, deferred from v0.3 follow-ups):

- **#6 i18n character profile page** (smallest, ships first) — Korean-only labels not translating on the English toggle
- **#5 chat sidebar hover auto-expand + per-page toggle consistency** — UX polish
- **#3 LLM model authority chain + UI live indicator + change panel** — env var / chat page / admin page precedence clarified + always-visible model name + change widget surface
- **#4 sticky top navigation bar** — "Secure Enterprise Knowledge Operating System" + language toggle + login + page nav, persists across scroll on every page
- **admin.html 3-page split (Option-A Phase 3)** — fits this sprint if architectural touch is bundled with the nav bar redesign; otherwise defer to Sprint 6

Acceptance: every page presents the same nav + footer scaffolding; model selector reachable from chat without admin redirect; sidebar/nav toggles obey one consistent pattern.

Phase split: 4-5 PRs sequential. Smallest fix lands first (#6 → #5 → #3 → #4 ± admin.html). Ships v0.4.0-alpha.2.

### Sprint 3 — Plumbing (D part 1)

Carryover items from v0.3.x that fit before retrieval-rework:

- **BL-1** — `emit_trace_step` stdout mirror (operator UX). Memory: `feedback_stdout_vs_audit_log_trace_split`
- **BL-2** — `attributes.summary` legacy field cleanup (v0.4 docs ingestion path)
- **D1 stage expansion** — wire `planner / reflect / verify` through `complete_with_retry` (currently they hold `self._max_tokens = 4096` so retry is no-op; add D1 budget signal first so `complete_with_retry` actually retries on truncation)

Acceptance: each of the 3 wired stages emits `reason:retry` rows under truncation; STEP 7 bench verifies no regression at flag-OFF default.

Phase split: 3-4 PRs sequential. Ships v0.4.0-beta.1.

### Sprint 4 — Retrieval quality (D part 2)

- **BL-9** — embedding model swap from `paraphrase-multilingual-MiniLM-L12-v2` to **bge-m3** or **multilingual-e5-large**. Re-embeds all chroma chunks. Memory: `feedback_rag_cross_lingual_diagnostic`.
- The 2026-05-25 cross-lingual diagnostic (`feedback_rag_cross_lingual_diagnostic`) is the test bed — "팔란티어가 뭐야?" should resolve to `palantir_technologies__pltr_` even without the alias pack augmentation (BL-8, already merged at D5.D).
- STEP 7 bench under flag-OFF default + flag-ON router measures retrieval quality lift.

Acceptance: cross-lingual grounded=true rate ↑ on the diagnostic prompts; no regression on existing Korean-only queries. Tier rationale (which model wins) documented in `reports/promo-assets/v0.4-embedding-swap-result.md`.

Phase split: 1 prep PR + 1 swap+measurement PR. Ships v0.4.0-beta.2.

### Sprint 5 — Layer 4 main theme (A)

Original v0.4.0 architectural shift (preserved from the `ROADMAP.md` §v0.4.0 scope below):

- **T1** Lifecycle states (active/archived/deleted/superseded)
- **T2** Event-driven state transitions
- **T7** Cross-workspace federation primitives

PR #403 designed the T1+T2+T7 first bundle. Sprint 5 implements it as a 5-8-PR sequence.

Acceptance: every wiki entity / relation / proposal / Change Request row carries a lifecycle state; state transitions emit audit events; `JAMES_WORKSPACE=` env (already seeded in v0.3.0 PR-C6 + PR-C6.b) gains the read-only federation primitive.

Phase split: design memo first (PR #403-equivalent for this cycle) + per-track sub-PRs. Ships **v0.4.0 final**.

### Sprint 6 — Long-term backlog (D + E)

Trigger-gated or scope-deferred items:

- **D2 measured** — task-weight metric formalization. Trigger: D1.B heuristic plateau on production STEP 7 bench.
- **Cost-based scoring v2** — current 4-rule D5 policy → token price × latency × quality weighted score
- **Per-stage explicit override under D5 ON** — operator wants `JAMES_BACKEND_VERIFY=ollama_local` to beat router policy
- **Claude provider native done_reason** — 3-condition gated (`JAMES_ENABLE_CLAUDE_BACKEND=1` + `JAMES_AUTO_ROUTER=1` + observed `reason:retry` rows with claude backend > 0). Memory: `feedback_d1_d5_retry_doubled_wiring_gap`
- **Per-domain-pack policy** — v0.5 Domain Pilot scope (out of v0.4)
- **D3 cross-family generalization** — mid-June Robin trigger
- **D6(I) joint paper consolidation** — mid-June Ali Gemini + Robin (3-author byline)

These ship as separate cycles whenever their trigger fires; no fixed sequence.

## Dependency direction

```
Sprint 0 (entry)
   ↓
Sprint 1 (C — data correctness)         ← independent
   ↓
Sprint 2 (B — UI consistency)            ← independent of Sprint 1
   ↓
Sprint 3 (D plumbing, part 1)            ← depends on D6 retry helpers (already in v0.3.3)
   ↓
Sprint 4 (D plumbing, part 2 — BL-9)     ← depends on chroma re-embedding compute window
   ↓
Sprint 5 (A — Layer 4 main theme)        ← depends on stabilization complete (Sprints 1-4)
   ↓
Sprint 6 (D nameplates + E)              ← trigger-gated
```

Sprint 1 + Sprint 2 are independent and can interleave if convenient. Sprint 3 depends on D6 (already in v0.3.3 main). Sprint 4 is a single architectural bet on the embedding model; defer or skip if Sprint 3 reveals the heuristic is enough. Sprint 5 is the original `ROADMAP.md` v0.4.0 theme.

## Release cadence (proposed)

| Sprint | Release tag | Rough timing |
|---|---|---|
| 1 (Data + RAG) | v0.4.0-alpha.1 | 2026-05-26~28 |
| 2 (UI) | v0.4.0-alpha.2 | 2026-05-29 ~ 06-02 |
| 3 (Plumbing 1) | v0.4.0-beta.1 | 2026-06-03~07 |
| 4 (Plumbing 2 — embedding swap) | v0.4.0-beta.2 | 2026-06-08~12 |
| 5 (Layer 4) | **v0.4.0** | 2026-06-13~30 (~3 weeks) |
| 6 (Long-term) | post-v0.4.0 | as triggers fire |

Each release gets its own Zenodo archival following the v0.3.1 / v0.3.2 / v0.3.3 pattern (`.zenodo.json` + CHANGELOG `[X.Y.Z]` entry + GitHub release publish + DOI mint + README badge bump).

## CLAUDE.md rules applied throughout v0.4

- **rule #1** (no domain features): all sprints are generic infra / UX / RAG quality / Layer 4 architectural. Domain-coupled work remains banned until v1.0.
- **rule #2** (bench numbers on `core/{retrieval,graph,reasoning}`): Sprint 1 #1 + Sprint 3 D1 expansion + Sprint 4 embedding swap all touch bench-required paths. Numbers required in PR bodies.
- **rule #3** (self-evolution opt-in only): N/A — no self-evolution surface in v0.4 sprints.
- **rule #4** (architecture changes): Sprint 2 (admin.html if bundled) + Sprint 5 (T1/T2/T7) both carry the `architecture` label. `docs/ARCHITECTURE.md` amendments land with the corresponding sprint closure.
- **rule #5** (module size ≤ 20 KB): re-checked at each sprint's PR review.

## Build-don't-broadcast principle ([[feedback_build_dont_broadcast]])

v0.4 is product work, not research. No public broadcast on individual sprints. Public artifacts come from:
- Sprint 5 closure release notes (v0.4.0 final) — citable on Zenodo, summarized in CHANGELOG
- Sprint 4 embedding-swap result doc (`reports/promo-assets/v0.4-embedding-swap-result.md`) — citable methodology, single-author paper trajectory

Robin / Ali collaboration trajectories remain mid-June Gemini-triggered and unchanged.

## Sprint 0 deliverables (this PR)

- This handover doc (`docs/handovers/v0.4.0-entry-track.md`)
- `ROADMAP.md` v0.3.0 closed + v0.3.3 stabilization summary + v0.4.0 active
- Memory: `project_state.md` v0.4 entry update + `MEMORY.md` index entry

Sprint 1 begins on the next PR.
