dev.md — YeeYee: the whole-project arc
- #update
- #software
Purpose. A single onboarding map for a new dev: every major subsystem across the project's full history, what each one does, roughly when it landed, and whether it's shipped / gated / TODO. This is the breadth view. For the running feature timeline see [CHANGELOG.md](CHANGELOG.md); for subsystem deep-dives see [building_block/editor/README.md](building_block/editor/README.md) (editor) and [scripts/reward/phd.md](scripts/reward/phd.md) (the training pipeline / eval).
The one-sentence project: a local-first, offline LLM code editor whose thesis is the agent does the work — plus a full home-grown loop to mine real edit history, train ("forge") a small local coding model on it, and honestly evaluate whether that training actually helps.
The arc, four eras:
| Era | Roughly | What it is |
|---|---|---|
| 0 — Foundation | 2025-01 → | Monaco editor + Gateway backend + multi-app workspace + storage abstraction |
| 1 — The Forge (mine → train → eval) | 2026-01 → 2026-06 | Harvest real edits, SFT a local yee-coder, and an honest eval/scoring instrument |
| 2 — Hard mode editor | matured pre-2026-06 | The full-power editor: Ty AI pipeline, agent loop, codebase index, provider routing |
| 3 — Easy mode / YeeYee | 2026-06-28 → 2026-07-08 | Glass chat-to-code surface, live preview, chat branches, Python Space, per-language tuning |
Legend: ✅ shipped & verified · 🟡 built, gated on a paid eval run · 🧭 partial / next-phase · ❌ not started... (no client data is used in the creation of this stats, only personal projects)
Era 0 — Foundation (2025-01 →)
Documented in the [dir_agent level-up logs](dir_agent/changelog.md) (2025-01-30/31). The bedrock the rest is built on.
| Feature | What it does | When | Status |
|---|---|---|---|
| Monaco editor shell | Electron desktop editor: file tree, tabs, diff mode, Chokidar file-watching, keyboard bindings, high-contrast a11y | 2025-01 | ✅ |
| The Gateway | Node WebSocket control plane wrapping the local model: NDJSON streaming, reconnect/backoff, sessions, latency probe | 2025-01 | ✅ |
| YeeAgent chat | Chat service with persistent history + shared CODE_APPLICATION_RULES prompt | 2025-01 | ✅ |
| Multi-app workspace | App-per-directory + MainMenu router (cycleplus, lightcycle, calendar, calculator, crm, musica, kanban, whiteboard…) | 2025-01 | ✅ |
| Storage abstraction | storageService + swappable backend (localStorage / Electron / future Postgres); 25 collections | 2025-01 | ✅ |
| dir_agent intelligence | SQLite + FTS5 full-text search over the codebase's own docs (BRAIN, changelog, ux-*) | 2025-01 | ✅ |
Era 1 — The Forge: mine → train → eval (2026-01 → 2026-06)
The home-grown pipeline that harvests real edits, trains a local model, and measures it honestly. Lives under [scripts/reward/](scripts/reward/); the research log is [phd.md](scripts/reward/phd.md). The whole dashboard is served by forge-server.mjs at /forge.
GitHub harvesting / author mining (⛏ Mine)
| Feature | What it does | When | Status |
|---|---|---|---|
| Edit warehouse | ~14.3K SFT pairs mined from ~5 months of real edit history (2026-01-09→2026-06-16), 65% GitHub; segmented by repo | 2026-06 | ✅ |
| ⛏ Mine tab | Paste a GitHub profile → harvest that author's own apply-verified edits → append git-<login>.jsonl to the warehouse | 2026-06 | ✅ |
| Author roster | Avatar + public/🔒-private pill + coverage + top-segment + "race on 4-bit"; reads public repo lists from HTML (no API budget) | 2026-06 | ✅ |
| Private-repo mining | Owner's own repos mined locally from disk (gato/dev3lop/bloog…≈9.9K edits); GITHUB_TOKEN-gated, never via public API | 2026-06 | ✅ |
| Traceable rows | Every mined edit carries github_url back to the exact commit — auditable, non-redistributive | 2026-06 | ✅ |
| Topic discovery + race | /api/mine/discover-topic, /api/mine/race, combine-train — discover authors, race their data on the 4-bit base | 2026-06 | ✅ |
SFT LLM builder (the local `yee-coder`)
| Feature | What it does | When | Status |
|---|---|---|---|
| MLX SFT training | Fine-tune yee-coder locally via MLX (venv/caffeinate); 8-bit (4-bit NaNs) — train_local.py | 2026-06 | ✅ |
| Prompt-contract seal | One byte-identical prompt across prepare/eval/serve (buildSftPrompt) so train==eval==serve | 2026-06 | ✅ |
| Leak-clean dataset build | prepare_sft.js --exclude-ids, segment-build.mjs; disjoint train vs held-out enforced | 2026-06 | ✅ |
| Decoupled eval-worker | Separate eval process fixed the "climb-then-collapse" training artifact (eval_worker.py) | 2026-06 | ✅ |
| DPO from rejected edits | Contrastive negatives (negatives.jsonl) → dpo_pairs.py / dpo_train.py seed | 2026-06 | ✅ |
| Edit-reward / swe_check | Pivot to EDIT-domain real-repo reward: run a repo's real tests → "resolved"; validated on Django | 2026-06 | 🧭 next: edit-DPO from SFT trajectories |
The Forge dashboard (`/forge`)
| Feature | What it does | When | Status |
|---|---|---|---|
| Live training dashboard | /forge shows runs live, per-run dropdown, launch/stop, base-model picker | 2026-06 | ✅ |
| Split-test tournament | Segment mined edits by folder, race each on a shared frozen held-out, branch into the winner, prune noise; live tree-map (tournament.mjs) | 2026-06 | ✅ |
| Canvas engine | Event-sourced single-writer daemon + ML-judge autopilot grows a tree of repo/folder segments toward the best training data (canvas-core.mjs) | 2026-06 | 🧭 Phase 1 done; Phase 2 (interactive pan/zoom) + synthesize TODO |
| Data library (◧ Data) | Scores the data segment (not the model): standalone vs marginal value; /api/data-library.json | 2026-06 | 🧭 shipped; Composer + export-bundle next |
| Export bundle | Zip a scored data segment to hyper-train elsewhere (export-bundle.mjs) | 2026-06 | ✅ |
The honest eval instrument (the part the author is proudest of)
| Feature | What it does | When | Status |
|---|---|---|---|
| Apply-success metric | Reference-based RLVR: score 100 only if the edit applies cleanly through the real searchReplace.js engine; diff-F1 ladder, 0.3 floor | 2026-06 | ✅ |
| Leak gate | eval-leakage-check.mjs — closes all 3 train/eval leak channels (found a 100% Run-mode leak, fixed it) | 2026-06 | ✅ |
| Frozen stratified held-out | make-heldout.mjs — deterministic, group/content-excluded, hash-stamped (24→96 tasks) | 2026-06 | ✅ |
| Bootstrap CI | Greedy point estimate + bootstrap confidence interval, never a lonely number (eval_live.py) | 2026-06 | ✅ |
| pass@k | eval_live.score_passk + PASSK worker verb | 2026-06 | ✅ built |
| gen2 scoring era | Save every model response + 5 judge lenses (form audit, helpfulness, trajectory, calibration, attribution) to re-score data | 2026-06 | ✅ |
| gen3 Opus-judge | Instruction-satisfaction rubric; honest apply-success + honesty gap (judge_score − byte), trust-checked | 2026-06 | ✅ |
| Data-quality scoring | Opus-score the 330K mined corpus (data_quality.py, resumable); ~33% keep-rate; embedding-distill (κ0.48) ranks all free, Opus adjudicates the uncertain band | 2026-06 | ✅ |
| Quality-selected pool | build_quality_pool.py → leak-clean, quality-weighted SFT pool that removes the honest-correct collapse | 2026-06 | ✅ |
Headline finding (honest): SFT buys format compliance, not correctness. Lead with +22pts apply-rate and −0.122 honesty gap and the format win — never brag the ~1% (noise-level). See [phd.md §18 claims ledger](scripts/reward/phd.md).
Era 2 — Hard mode editor (matured pre-2026-06)
The full-power "awesome" editor. Deep-dive: [building_block/editor/README.md](building_block/editor/README.md). The local-model pipeline here is "paused, not gone" — the frontier/provider path took the lead for Easy mode.
Ty AI — the multi-stage edit pipeline
| Feature | What it does | Status |
|---|---|---|
| Rewriter | Turns a casual prompt into a precise instruction; gated by a specificity score (only rewrites if <45) | ✅ |
| Locator (3-stage) | Finds the exact excerpt + line range — deterministic (LanceDB index), LLM, or skip | ✅ |
| Executor | Instruction + excerpt → one SEARCH/REPLACE block | ✅ |
| 2/3-stage modes + named arrangements | Save/load rewriter→executor(→locator) combos; three built-in | ✅ |
The editing engine
| Feature | What it does | Status |
|---|---|---|
| SEARCH/REPLACE core | Shared engine (shared/lib/searchReplace.js) — single source of truth for Apply, Cmd+K, agent tools | ✅ |
| 6-strategy fuzzy match | exact → trimEnd → whitespace → case-insensitive → block-anchor → line-similarity (≥0.9); returns closest region on miss | ✅ |
| Smart retry | Feeds the closest actual file region back to the model (up to 2×) | ✅ |
| Whole-file fallback | Files <400 lines: full rewrite through diff review | ✅ |
| Diff review modal | Monaco side-by-side, Accept (⌘↵)/Cancel (Esc), 12s Undo toast | ✅ |
| Cmd+K inline edit | Select code → ⌘K → instruction → one applied block | ✅ |
Agent (Auto mode) & orchestration
| Feature | What it does | Status |
|---|---|---|
| Agentic tool-use loop | agentLoop.js: read/edit/run until done; tools emit fenced JSON | ✅ |
| Tool set | read/write/edit_existing/search_replace/single_find_and_replace/multi_edit/insert_code/list_files/run_terminal | ✅ |
| Approval gates | Edits via diff review (auto-approve toggle, off by default); terminal always prompts (once / always / deny) | ✅ |
| Self-correction | Post-edit lint self-heal (≤2), one-round project verify, terminal-error feedback | ✅ |
| Kill switch | Stop button aborts via AbortController | ✅ |
| Parallel plan execution | orchestrator.js pure DAG scheduler (bounded concurrency) + global apply-lock (single diff modal); cycle/deadlock guards | ✅ |
| Behavior modes | Edit (one change) / Plan (checkable numbered plan) / Auto (full loop) | ✅ |
Context, models, backend, security
| Feature | What it does | Status |
|---|---|---|
| Codebase vector index | LanceDB + nomic-embed-text via Ollama; incremental, code-aware chunking; status pill; ripgrep fallback | ✅ |
| @-mentions | @codebase (semantic) / @<file> (specific); autocomplete | ✅ |
| Models tab | System resources, running/installed/available, quantization picker, live pull; "Oh Snap" RAM gate | ✅ |
| The Mix | Benchmark harness for model arrangements; perfect-score requires a clean apply through the real engine | ✅ |
| Provider routing | mlx:/yee:/local: → forged local model · openai:/anthropic: → frontier · unprefixed → Gateway/Ollama; unified usage struct powers the token meter | ✅ |
| Plan & summarization (Python) | Agent 008 writes .yeeyee/plan.md; context summarizer condenses old turns | ✅ |
| Security model | Workspace sandbox (realpath + symlink refuse), approval gates, contextIsolation, CSP, DOMPurify, localhost-only | ✅ |
| Integrated terminal | xterm.js + node-pty per session, command approval allowlist | ✅ |
Era 3 — Easy mode / YeeYee (2026-06-28 → 2026-07-08)
The glass chat-to-code surface for non-experts — the current push. Full timeline in [CHANGELOG.md](CHANGELOG.md). Commit hashes below are from that log.
| Feature | What it does | When | Status |
|---|---|---|---|
| Easy-mode chat room | Full-window glassmorphism chat-to-code + WebGL shader; pi-style collapsible tool cards with inline diffs | 2026-06-28 | ✅ |
| Live preview + fix loop | ▶ runs the repo's dev server in an in-app webview; console + stderr feed back to the agent as a one-round fix loop; lifecycle-hardened (tree-kill, timeouts, EADDRINUSE) | 2026-06-28 | ✅ |
| One-window workspace | ☰ repos & chats navigator + file tree (auto-refresh) + per-session terminal; switching chats swaps the workspace | 2026-06-28 | ✅ |
| SQLite persistence | chatStore.js (sql.js, no native build); chats survive restart and re-seed context | 2026-06-28 | ✅ |
| Per-edit farming | Approved edits auto-apply + auto-write training rows; deleting a chat/repo prunes its rows | 2026-06-28 | ✅ |
| "Under the hood" split-testing | Split-test your agent's context, promote what measures leaner (CI-gated promote) | 2026-07-01 | ✅ |
| Python Space | Jupyter-quality notebook surface, zero Jupyter dependency (+ hardening pass) | 2026-07-02/03 | ✅ |
| Language-tier chips | Honest per-language capability ladder in-app + launch screen | 2026-07-03 | ✅ |
| Element picker | Click an element in the preview → agent jumps to its file:line (9 review fixes) | 2026-07-03 | ✅ |
| Screenshot → chat (vision) | Agent sees the rendered preview; white-screen crash fixed via main-process capture | 2026-07-04 | ✅ |
| Direct-first tool routing | Kills the workspace-less-gateway bug class at the source | 2026-07-04 | ✅ |
| Chat branches | Git-backed checkpoint/branch DAG for AI chats: 3-way conflict resolution, AI-suggest, undeniable merge graph, permanent panel; per-repo scoping fix | 2026-07-04/05 | ✅ 81e3ff8 |
| Repo-map tree fallback (#5) | Non-code files (config/docs/data) stop vanishing from the agent's map; own budget; binaries still skipped | 2026-07-05 | ✅ |
| Data-integrity (#6) | Split-test streams localStorage→SQLite; live prompt-cache-break guard | 2026-07-05 | ✅ |
| Per-language-group tuning (#7) | Packs/scores/eval keyed by (model, group: js-ts/css-html/python/general); live chat auto-uses its repo's group's pack; language: tab strip | 2026-07-06 | ✅ b986741→e362658 |
| Measured model save% | Retired the hardcoded per-model save% for a measured per-language average; honest "unmeasured" until a real run | 2026-07-06 | ✅ 9da86d8 |
| Variance-robust measurement | Stratified log-ratio bootstrap + hard n≥5 floor; powered-n advisory not veto — the honest token-savings instrument | 2026-07-07 | ✅ |
| Per-language prompts SHIP | Native, tier-aware wd/rm/pa prompts per (model, group); guarded against silent collapse to identical | 2026-07-08 | ✅ |
Open / gated / not started
The forward roadmap ("🗺 Priority Tracker", 2026-07-04 synthesis in [CHANGELOG.md](CHANGELOG.md)).
| Item | State | Blocker |
|---|---|---|
| #1 — Element-pick + verify-compaction bench cells | 🟡 built, adversarially reviewed, dry-tested (37/37) | Awaiting Ty's paid eval run for the CI verdict — no headline until MIN_PAIRS clears |
| #3 — Python S− eval cell | 🟡 built, reviewed, fixed (60/60 dry) | Awaiting paid run; no tier promotion until a significant CI |
| #4 — Human-anchored honesty slice | ❌ not started | ≥50–100 gold edits, ≥2 annotators + κ, non-Opus judge (week+). Retires the two biggest phd.md §18.3 caveats |
| Canvas engine Phase 2 | 🧭 partial | Interactive pan/zoom canvas + synthesize step |
| Data library Composer | 🧭 partial | Connect→race-union + export-bundle wiring |
| Edit-reward → edit-DPO | 🧭 next | swe_check validated on Django; next is edit-DPO from SFT trajectories |
Completion — where we're at
Two honest denominators, because "% done" depends on what you're counting.
A) Current roadmap (Priority Tracker: P0 + #1–#7 = 8 items). This is the active push.
- 5 fully done & verified (P0, #2, #5, #6, #7)
- 2 code-complete, gated on a paid eval run (#1, #3)
- 1 not started (#4)
- ⇒ 62.5% validated-only, ~81% crediting the two gated items at half.
B) Whole product. The four eras are each substantially built and shipping. Foundation, the Forge (mine/train/eval), and the hard-mode editor are effectively complete and in daily use; Easy mode is the maturing surface. The genuinely open work is narrow: a handful of gated eval runs (#1/#3), one unstarted research slice (#4), and two next-phase polish items (Canvas Phase 2, Data-library Composer). By breadth of shipped-and-verified subsystems, the project is ~85–90% of the way to the public launch scope, with the remaining gap concentrated in validation (spending API money to earn the honest CIs) rather than in unbuilt features.
The load-bearing caveat (house rule): no headline without a cell. Several features ship with their token-savings claims deliberately unclaimed until a paid eval run produces a significant confidence interval. Don't promote anything from #1/#3 until the CI clears. The single biggest measurement gap is #4 (human ground truth) — the only unstarted item and the most expensive.
Sources: [CHANGELOG.md](CHANGELOG.md) · [building_block/editor/README.md](building_block/editor/README.md) · [scripts/reward/phd.md](scripts/reward/phd.md) · [dir_agent/changelog.md](dir_agent/changelog.md). Keep this file's era tables in sync when a subsystem materially changes; keep CHANGELOG.md as the running log.