Skip to content

Commit 30a5e03

Browse files
committed
Overhaul roadmap system for continuous autonomous iteration
- Replace roadmap.md with Phase 77-96 (Tier 0-5) structure - Phase Tracker table at top for context-efficient reading - Each phase has sub-tasks, exit criteria, dependencies - Update CLAUDE.md autonomous workflow: - Orient: check Next Phase Queue before reading roadmap - Phase Completion: read only Phase Tracker + target section - Commit Gate #4: add deps_e2e (14 tests) to gate - Binary size threshold: 4.2 -> 4.3 MB (matches 4.07 MB actual) - Update memo.md: add Known Issues (F140/F139), Next Phase Queue (Phase 78) - Update checklist.md: add Target Phase column to F## items - Update baselines.md: binary size baseline 4.00 -> 4.07 MB
1 parent 8ec798b commit 30a5e03

5 files changed

Lines changed: 411 additions & 269 deletions

File tree

.claude/CLAUDE.md

Lines changed: 15 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,9 @@ git log --oneline -3 && git status --short
3939

4040
Read: `.dev/memo.md` (current state, next task pointer)
4141

42-
If memo.md has no active task: read `.dev/roadmap.md` → pick first pending phase sub-task.
42+
If memo.md has no active task:
43+
1. Check `## Next Phase Queue` in memo.md — if populated, promote it
44+
2. Otherwise: read `.dev/roadmap.md` **Phase Tracker** → find first PENDING → read that phase section only
4345

4446
If implementing functions, check coverage:
4547
```bash
@@ -56,7 +58,7 @@ yq '.vars.clojure_core | to_entries | map(select(.value.status == "done")) | len
5658

5759
- TDD cycle: Red → Green → Refactor
5860
- Run tests: `zig build test`
59-
- Run e2e tests: `bash test/e2e/run_e2e.sh`
61+
- Run e2e tests: `bash test/e2e/run_e2e.sh` + `bash test/e2e/deps/run_deps_e2e.sh`
6062
- **Upstream test porting** (Phase 42+): Follow `.dev/test-porting-plan.md`
6163
- Port relevant upstream tests for each sub-task
6264
- Run full upstream regression suite before committing
@@ -108,7 +110,9 @@ Run before every commit:
108110
1. **decisions.md**: D## entry only for architectural decisions (new Value variant, new subsystem, etc.)
109111
2. **checklist.md**: Remove resolved F##, add new F##
110112
3. **vars.yaml**: Mark implemented vars `done` (when implementing vars)
111-
4. **e2e tests**: `bash test/e2e/run_e2e.sh` passes (when changing execution code)
113+
4. **e2e tests** (when changing execution code):
114+
- `bash test/e2e/run_e2e.sh` — core e2e (6 tests)
115+
- `bash test/e2e/deps/run_deps_e2e.sh` — deps.edn e2e (14 tests)
112116
5. **memo.md**: Advance to next task
113117
- Update `## Current Task` with next task details
114118
- Remove completed task from Task Queue
@@ -124,7 +128,7 @@ Run before every commit:
124128
- `bash bench/wasm_bench.sh --quick` — verify wasm benchmarks still work
125129
8. **Non-functional regression** (when changing execution code: src/vm/, src/evaluator/,
126130
src/compiler/, src/runtime/, src/builtins/, src/wasm/, bootstrap):
127-
- **Binary size**: `zig build -Doptimize=ReleaseSafe && stat -f%z zig-out/bin/cljw` — ≤ 4.2MB
131+
- **Binary size**: `zig build -Doptimize=ReleaseSafe && stat -f%z zig-out/bin/cljw` — ≤ 4.3MB
128132
- **Startup**: `hyperfine -N --warmup 3 --runs 5 './zig-out/bin/cljw -e nil'` — ≤ 5ms
129133
- **RSS**: `/usr/bin/time -l ./zig-out/bin/cljw -e nil 2>&1 | grep 'maximum resident'` — ≤ 12MB
130134
- **Benchmarks**: `bash bench/run_bench.sh --quick` — no CW benchmark > 1.2x baseline
@@ -136,11 +140,12 @@ Run before every commit:
136140

137141
When Task Queue empty:
138142

139-
1. If next phase exists in `roadmap.md`: create Task Queue in memo.md
140-
2. If not: plan new phase:
141-
- Read `roadmap.md` Phase Notes, `.dev/future.md`, `checklist.md`
142-
- Priority: bugs > blockers > deferred items > features
143-
- Update memo.md with new Task Queue
143+
1. Check memo.md `## Next Phase Queue` — if populated, promote to Task Queue
144+
2. If Next Phase Queue empty: read `roadmap.md` **Phase Tracker table only** (top of file)
145+
- Find first PENDING phase
146+
- Read **only that phase's section** (not the whole file — save context)
147+
- Copy sub-tasks to memo.md Task Queue
148+
- Update Phase Tracker: mark current phase DONE, next phase IN-PROGRESS
144149
- Commit: `Plan Phase X: [name]`
145150
3. Continue to first task
146151

@@ -232,7 +237,7 @@ Check `.claude/references/zig-tips.md` first, then Zig stdlib at
232237
| Impl tiers | `.claude/references/impl-tiers.md` | When implementing a new function |
233238
| Java interop | `.claude/rules/java-interop.md` | Auto-loads on .clj/analyzer/builtin edits |
234239
| Test porting | `.claude/rules/test-porting.md` | Auto-loads on test file edits |
235-
| Roadmap | `.dev/roadmap.md` | Phase planning — always read for next task |
240+
| Roadmap | `.dev/roadmap.md` | Phase Tracker (top) for next task; phase section for details |
236241
| Deferred items | `.dev/checklist.md` | F## items — blockers to resolve |
237242
| Decisions | `.dev/decisions.md` (D3-D101+) | Architectural decisions reference |
238243
| Design document | `.dev/future.md` | When planning new phases or major features |

.dev/baselines.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Non-Functional Baselines
22

3-
Measured on: 2026-02-14 (v0.2.0)
3+
Measured on: 2026-02-16 (post-Phase 77)
44
Platform: macOS ARM64 (Apple M4 Pro), Zig 0.15.2
55
Binary: ReleaseSafe
66

@@ -11,7 +11,7 @@ Fix the regression first. No exceptions without explicit user approval.
1111

1212
| Metric | Baseline | Threshold | Margin | How to measure |
1313
|---------------------|------------|------------|--------|---------------------------------------------|
14-
| Binary size | 4.00 MB | 4.2 MB | +5% | `stat -f%z zig-out/bin/cljw` (after ReleaseSafe build) |
14+
| Binary size | 4.07 MB | 4.3 MB | +5% | `stat -f%z zig-out/bin/cljw` (after ReleaseSafe build) |
1515
| Startup time | 4.2 ms | 5 ms | 1.19x | `hyperfine -N --warmup 3 --runs 5 './zig-out/bin/cljw -e nil'` |
1616
| RSS (light) | 8.0 MB | 12 MB | +50% | `/usr/bin/time -l ./zig-out/bin/cljw -e nil 2>&1 \| grep 'maximum resident'` |
1717
| Benchmark (any) | see below | 1.2x | +20% | `bash bench/run_bench.sh --quick` |

.dev/checklist.md

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -13,14 +13,16 @@ Check at session start for items that become actionable.
1313

1414
## Blocked until needed
1515

16-
| ID | Item | Trigger |
17-
|------|---------------------------------------------|--------------------------------------------------------------------------|
18-
| F94 | Upstream Alignment pass | Phase 70.5.4 audit: 87 markers in src/clj/ (P=48, S=12, R=27). R items need: :inline meta (2), IDrop (2), IReduceInit/deftype (3), TransformerIterator (1), seqkvreduce (1), extend-via-metadata (2), deftype (3), ref/multimethod in test (7), spec in repl (1), assert-expr (1), run-test (1), :__reify_type (1). |
19-
| F102 | map/filter chunked processing | Chunked types exist, range is lazy. Optimization: use chunks in map/filter pipelines. |
20-
| F103 | Escape analysis (local scope skip GC) | Compiler detects local-only Values, skip GC tracking |
21-
| F104 | Profile-guided optimization (extend IC) | Extend inline caching beyond monomorphic |
22-
| F105 | JIT compilation (expand beyond ARM64 PoC) | ARM64 hot-loop JIT done (Phase 37.4, D87). Future: x86_64 port, expand beyond integer loops. |
23-
| F120 | Native SIMD optimization (CW internals) | Investigate Zig `@Vector` for CW hot paths. Profile first. |
24-
| F141 | cljw.xxx aliases for clojure.java.xxx | `(require '[cljw.io])` should map to `clojure.java.io`. Targets: cljw.io, cljw.shell, cljw.browse, cljw.process. Needs ns alias mapping in require/resolve path. |
25-
| F139 | case macro fails with mixed body types | `(case x :a 1 :b (cond-> ...))` — shift-mask error. Related to case hash computation when body exprs mix integer literals and complex forms. Workaround: use `cond`. |
26-
| F140 | GC crash in dissocFn (keyword pointer freed) | Segfault in keyword name comparison under heavy allocation pressure (tools.cli test-summarize). Pre-existing GC root tracking issue. |
16+
Target Phase references: see `.dev/roadmap.md` Phase Tracker + Open Checklist Items table.
17+
18+
| ID | Item | Target | Trigger |
19+
|------|---------------------------------------------|--------|--------------------------------------------------------------------------|
20+
| F94 | Upstream Alignment pass | 78.3 | Phase 70.5.4 audit: 87 markers in src/clj/ (P=48, S=12, R=27). R items need: :inline meta (2), IDrop (2), IReduceInit/deftype (3), TransformerIterator (1), seqkvreduce (1), extend-via-metadata (2), deftype (3), ref/multimethod in test (7), spec in repl (1), assert-expr (1), run-test (1), :__reify_type (1). |
21+
| F102 | map/filter chunked processing | 89.1 | Chunked types exist, range is lazy. Optimization: use chunks in map/filter pipelines. |
22+
| F103 | Escape analysis (local scope skip GC) | 89.3 | Compiler detects local-only Values, skip GC tracking |
23+
| F104 | Profile-guided optimization (extend IC) | 89 | Extend inline caching beyond monomorphic |
24+
| F105 | JIT compilation (expand beyond ARM64 PoC) | 90 | ARM64 hot-loop JIT done (Phase 37.4, D87). Future: x86_64 port, expand beyond integer loops. |
25+
| F120 | Native SIMD optimization (CW internals) | 89 | Investigate Zig `@Vector` for CW hot paths. Profile first. |
26+
| F139 | case macro fails with mixed body types | 78.2 | `(case x :a 1 :b (cond-> ...))` — shift-mask error. Related to case hash computation when body exprs mix integer literals and complex forms. Workaround: use `cond`. |
27+
| F140 | GC crash in dissocFn (keyword pointer freed) | 78.1 | Segfault in keyword name comparison under heavy allocation pressure (tools.cli test-summarize). Pre-existing GC root tracking issue. |
28+
| F141 | cljw.xxx aliases for clojure.java.xxx | 85.4 | `(require '[cljw.io])` should map to `clojure.java.io`. Targets: cljw.io, cljw.shell, cljw.browse, cljw.process. Needs ns alias mapping in require/resolve path. |

.dev/memo.md

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,20 @@ skip recorvery にくわえて、以下が解消されているかも確認。
6565

6666
## Known Issues
6767

68-
(none currently)
68+
- F140: GC crash in dissocFn (keyword pointer freed under heavy allocation pressure)
69+
- F139: case macro fails with mixed body types (shift-mask error)
70+
71+
## Next Phase Queue
72+
73+
After Phase 77 completes, proceed to Phase 78 (Bug Fixes & Correctness).
74+
Read `.dev/roadmap.md` Phase 78 section for sub-tasks.
75+
76+
```
77+
78.1 Fix F140: GC crash in dissocFn
78+
78.2 Fix F139: case macro with mixed body types
79+
78.3 F94 upstream alignment pass (87 markers in src/clj/)
80+
78.4 Audit unreachable in production paths
81+
```
6982

7083
## Notes
7184

0 commit comments

Comments
 (0)