bara-lang/TASKS.md

Task Board for AI Agents

Pick a task, implement it, test it, commit it. Each task is self-contained.

Legend

• 🔴 Large — 1+ week
• 🟡 Medium — 2-5 days
• 🟢 Small — few hours
• ⬜ Not started / 🔄 In progress / ✅ Done

---

Phase 4: AI-Native Tooling (Complete)

ID	Task	Status	Complexity	Files	Acceptance Criteria
T4.1	JSON REPL mode	✅	🟡	src/repl.nim	./cljnim repl --json works, structured I/O
T4.2	Batch evaluation	✅	🟢	src/repl.nim	{"op":"eval-batch","forms":["(defn f[x]x)","(f 42)"]} works
T4.3	File operations	✅	🟡	lib/cljnim_runtime.nim, src/emitter.nim	(file/read), (file/write), (file/ls) work
T4.4	Git operations	✅	🟡	lib/cljnim_runtime.nim, src/emitter.nim	(git/status), (git/commit), (git/push) work
T4.5	nREPL protocol	✅	🟡	src/repl.nim	REPL speaks JSON over TCP with --tcp PORT.
T4.6	Tool-call format	✅	🟢	src/repl.nim	Accept {"tool":"cljnim/eval","args":{"form":"..."}}.

---

Phase 5: Persistent Data Structures

ID	Task	Status	Complexity	Files	Acceptance Criteria
T5.1	HAMT Vector — core structure	✅	🔴	New: lib/cljnim_pvec.nim, lib/cljnim_runtime.nim	PersistentVector with 32-way trie, structural sharing. nth in O(log₃₂ n). 14 tests.
T5.2	HAMT Vector — integration	✅	🔴	lib/cljnim_runtime.nim, src/emitter.nim	ckVector uses HAMT. All 51 vecData usages migrated.
T5.3	HAMT Map	✅	🔴	New: lib/cljnim_pmap.nim, lib/cljnim_runtime.nim	Persistent Hash Map with HAMT. assoc, dissoc, get in O(log₃₂ n). 16 tests.
T5.4	Persistent Set	✅	🟡	lib/cljnim_runtime.nim	Set backed by Persistent Hash Map. conj, disj, contains?, get, count. Reader emits (set [items]).
T5.5	Transients	✅	🟡	lib/cljnim_runtime.nim	transient, persistent!, conj!, assoc! for batch mutations. Use with let.

Why HAMT matters: Current Vector is a Nim seq — every conj copies the entire array (O(n)). Real Clojure uses Hash Array Mapped Trie for O(log₃₂ n) updates with structural sharing.

Starting point for T5.1: Read lib/cljnim_vector.nim (if exists) or research Clojure's PersistentVector.java. Key concepts: 32-way branching, path copying, tail optimization.

---

Phase 6: Clojure Core Library

ID	Task	Status	Complexity	Files	Acceptance Criteria
T6.1	str — string concatenation	✅	🟢	lib/cljnim_runtime.nim, src/emitter.nim	(str "a" 1 true) → "a1true". cljStrConcat in runtime.
T6.2	pr-str — readable representation	✅	🟢	lib/cljnim_runtime.nim	(pr-str [1 2 3]) → "[1 2 3]". cljPrStrConcat in runtime.
T6.3	slurp — read file to string	✅	🟢	lib/cljnim_runtime.nim, src/emitter.nim	(slurp "file.txt") returns content. Maps to cljFileRead.
T6.4	spit — write string to file	✅	🟢	lib/cljnim_runtime.nim, src/emitter.nim	(spit "file.txt" "content") writes file. Maps to cljFileWrite.
T6.5	read-line — read from stdin	✅	🟢	lib/cljnim_runtime.nim	(read-line) reads one line from stdin.
T6.6	range — lazy number sequence	✅	🟡	lib/cljnim_runtime.nim	(range 10), (range 1 10), (range 1 10 2). Eager with 3-arg.
T6.7	repeat, cycle, iterate	✅	🟡	lib/cljnim_runtime.nim	(repeat n x), (cycle n coll), (iterate n f x). Eager.
T6.8	take, drop — seq slicing	✅	🟢	lib/cljnim_runtime.nim	(take 5 (range 100)), (drop 5 [1 2 3 4 5]).
T6.9	partition, interleave	✅	🟢	lib/cljnim_runtime.nim	(partition 2 [1 2 3 4]), (interleave [1 2] [3 4]).
T6.10	meta, with-meta, vary-meta	✅	🟡	lib/cljnim_runtime.nim, src/emitter.nim	Metadata support on vars, functions, collections.
T6.11	type, instance?	✅	🟢	lib/cljnim_runtime.nim	(type 42) → :integer. (instance? :integer 42) → true.

---

Phase 7: Project Compilation

ID	Task	Status	Complexity	Files	Acceptance Criteria
T7.1	ns declaration parsing	✅	🟡	src/emitter.nim	(ns my.app (:require [other.lib :as lib])) parses, extracts aliases, resolves.
T7.2	Multi-file compilation	✅	🔴	src/cljnim.nim, src/emitter.nim	./cljnim run app.clj finds required files (hyphen→underscore), inlines defs.
T7.3	Module caching	✅	🟡	src/cljnim.nim	Compiled .nim files cached in nimcache/. Rebuild only if source changed.
T7.4	Dependency resolution	✅	🔴	New: src/deps.nim, tests/test_deps.nim	Read deps.edn format. Download Git deps to .deps/. cljnim deps command. 12 tests.

---

Phase 8: Self-Hosted REPL

ID	Task	Status	Complexity	Files	Acceptance Criteria
T8.1	In-memory compilation	✅	🔴	src/eval.nim, src/repl.nim	Tree-walking interpreter evaluates common forms in <1ms, no temp files. Falls back to compilation for complex cases. 66 tests.
T8.2	Fast REPL startup	✅	🟡	src/eval.nim, src/repl.nim	REPL eval in ~0.02ms (vs 1133ms compiled). Sub-millisecond for arithmetic, collections, higher-order fns.
T8.3	Hot code reloading	✅	🟡	src/eval.nim	def/defn update environment immediately. Redefined functions used by all callers at call time.

---

Phase 9: Concurrency

ID	Task	Status	Complexity	Files	Acceptance Criteria
T9.1	Atoms (CAS)	✅	🟡	lib/cljnim_runtime.nim	(def a (atom 0)), (swap! a inc), (reset! a 42), (deref a). Already implemented.
T9.2	Agents	✅	🟡	lib/cljnim_runtime.nim, src/eval.nim	(def a (agent 0)), (send a inc), (deref a). Sync dispatch in interpreter, async-ready in runtime.
T9.3	core.async channels	✅	🔴	New: lib/cljnim_async.nim, src/eval.nim	(chan), (chan n), (>! ch val), (<! ch), (close! ch), (go ...). Interpreter-first.

---

Quick Wins (do these first!)

These tasks are small, well-defined, and high impact:

1. T6.1 str ✅ — Done. cljStrConcat in runtime, str mapping in emitter.
2. T6.3 slurp ✅ — Done. (slurp "file.txt") works.
3. T6.4 spit ✅ — Done. (spit "file.txt" "content") works.
4. T6.8 take, drop ✅ — Done. cljTake, cljDrop in runtime, emitter mappings.
5. T6.11 type, instance? ✅ — Done. cljType, cljInstanceP in runtime.
6. T4.6 Tool-call format ✅ — Done. REPL accepts {"tool":"cljnim/eval","args":{"form":"..."}}.

---

Phase 10: AI Integration + Core Polish (9 May 2026)

ID	Task	Status	Complexity	Files	Acceptance Criteria
T10.1	AI error messages — cache + full coverage	✅	🟡	src/ai_assist.nim, src/cljnim.nim	Error cache (50 entries, TTL 1h). ReaderError/EmitterError get AI explanations.
T10.2	AI code generation — eval builtin + REPL	✅	🟡	src/eval.nim, src/repl.nim	(ai/generate "...") in interpreter. :ai, ai-generate in all REPL modes.
T10.3	AI optimization hints	✅	🟢	src/eval.nim, src/repl.nim	(ai/optimize "...") in interpreter. :optimize, ai-optimize in all REPL modes.
T10.4	AI debugging — special form	✅	🟡	src/eval.nim, src/repl.nim	(ai/debug expr) as special form. :debug, ai-debug in all REPL modes.
T10.5	try/catch/finally — full implementation	✅	🟡	src/emitter.nim, tests/test_emitter.nim	Exception type respected. Binding is cljMap with :type/:message. 4 tests.
T10.6	Reader edge cases	✅	🟢	src/reader.nim, tests/test_reader.nim	-.5, +.25, 1e5, 1.5e-3, -.5e-3, .25. Scientific notation. 13 tests.
T10.7	CljVal type unification	✅	🔴	src/types.nim, lib/cljnim_runtime.nim, src/runtime.nim, lib/cljnim_runtime_js.nim	Identical CljKind enum (15 values) across all 4 files. All case statements cover new variants.

Phase 11: BRing Compiler Fixes (12 May 2026)

Real-world fixes discovered during BRing web framework development.

ID	Task	Status	Complexity	Files	Acceptance Criteria
T11.1	Docstrings in defn/defn-	✅	🟢	src/emitter.nim	(defn f "doc" [x] ...) compiles correctly.
T11.2	Multi-arity defn	✅	🟡	src/emitter.nim	(defn f ([x] ...) ([x y] ...)) dispatches by args.len.
T11.3	Keyword-as-function (:key map)	✅	🟢	src/emitter.nim	(:name person) emits cljGet(person, keyword) instead of cljApply.
T11.4	& rest parameters	✅	🟡	src/emitter.nim	(defn f [x & rest] ...) accepts variadic args as seq[CljVal].
T11.5	Nim interop name mangling	✅	🟢	src/emitter.nim	nim/foo-bar emits foo_bar in Nim. sanitizeNimIdent for interop chains.
T11.6	getLibPath() + --lib-path flag	✅	🟢	src/cljnim.nim, src/repl.nim	--lib-path <dir> CLI flag. Checks CLI → env → cwd → appDir.
T11.7	:paths in deps.edn	✅	🟢	src/deps.nim	Parses :paths and includes in searchPaths.
T11.8	loop + if/else discard fix	✅	🟡	src/emitter.nim	loopResult variable. loop returns value correctly in all branches.
T11.9	clj_ prefix for identifiers	✅	🟢	src/emitter.nim	All generated procs get clj_ prefix. Nim interop excluded.
T11.10	when isMainModule skip for libs	✅	🟢	src/emitter.nim	emitProgramLib skips when isMainModule guard.
T11.11	try/catch/finally fixes	✅	🟢	src/emitter.nim	finally discards expression results. catch uses original name for scope.
T11.12	First-class defn functions	✅	🟡	src/emitter.nim	defn symbols used as values emit cljFn(...) wrapper. Direct calls unchanged.
T11.13	loop in expression context (IIFE)	✅	🟡	src/emitter.nim	loop wraps in (proc(): CljVal = ...)() when needsValue=true.

---

How to claim a task

1. Read this file
2. Pick an unclaimed task (marked ⬜)
3. Implement it
4. Run make test && make check
5. Update this file: change ⬜ to ✅
6. Commit: (git/commit "T6.1: Add str function")
7. Push: (git/push)