# LLD Dojo — Completion Tracker

> **Resuming? Read `docs/RESUME.md` first.** It carries the current state, the gotchas that cost real
> time to find, the conventions to copy rather than reinvent, and the judgements that are easy to
> erode by accident. Last updated 2026-08-18 at a deliberate stopping point: **390 tests green**,
> backend complete, 8 of 20 problems, 3 of 46 lessons.

**Created:** 2026-08-18
**Why this file exists:** the user decided *"prep will only begin when FE + BE is 100% done."* That
replaces the milestone-ladder sequencing with a single question — **is every component finished?** —
so "done" needs to be enumerable rather than a feeling.

Status values: `todo` · `wip` · `done` (implemented, tested, reviewed)

---

## Consequence of the decision, recorded once

The original M1–M6 ladder existed so he could climb Phases 0–2 within a day or two while later
milestones landed around him. He has chosen instead to wait for completion. Therefore:

- Build time is now **pure delay** before his first rep, not overlapped with it
- Sequencing optimises for **shortest path to 100%**, which means maximum parallelism across disjoint
  file trees rather than milestone order
- The **corpus is the critical path**, not the code — ~140 authored artifacts across 20 problems
- Nothing ships partially usable, so there is no longer any reason to keep Phases 3–7 behind a lock

## Standing convention: snapshot as you go

Added 2026-08-18 after three agents died to `ECONNRESET` mid-task. The user's point:
*"network issues are common, so always tell your agents to regularly commit, so that minimal work gets
lost."*

There is no git, so **snapshot is the commit.** Two changes were made in response:

1. **`tools/snapshot.mjs` now covers code**, not just content — `corpus`, `data`, `server`, `ui-src`,
   `tools`, `harness`, `lessons`, `docs`, excluding `node_modules`, `.toolchain` and build output. About
   1 MB, effectively instant. Previously it copied only `corpus/` and `data/`, which meant a lost agent
   took its source with it — exactly what happened.
2. **Every agent brief now requires incremental snapshots** after each meaningful step, and before any
   risky edit, so a crash costs at most one step. Long-running verification agents additionally write
   findings to `docs/verify/<name>.md` **as they go**, so a replacement agent resumes instead of
   restarting.

**Parallelism boundaries** — what may safely run concurrently:

| Lane | Owns | Never touches |
|---|---|---|
| BE-core | `server/lib/**`, `server/test/**` | `ui-src/**`, `corpus/**` |
| FE-shell | `ui-src/src/components/**`, `tokens.css`, `motion.ts` | `server/**`, `corpus/**` |
| FE-views | `ui-src/src/views/**` | `server/**`, `corpus/**` |
| Content-N | `corpus/<slug>/**` — one lane per problem | everything else |
| Tooling | `tools/**` | `server/lib/**` |

One agent per lane at a time. Content lanes are independent per problem, so many can run at once.

---

## Backend

| Component | Status | Notes |
|---|---|---|
| `tools/snapshot.mjs` — git stand-in | **done** | Copies `corpus/` + `data/` only. Code is *not* snapshotted — reproducible from plans |
| `server/lib/paths.mjs` — platform + toolchain paths | **done** | 5 tests |
| `tools/bootstrap.mjs` — JDK 21 + JUnit jar | **done** | Verified `javac 21.0.12` by real compile-and-run |
| JBR fallback + `idea64.exe` glob discovery | todo | Offline resilience; IntelliJ 2026.2.1 bundles `javac 25.0.3` |
| `server/lib/db.mjs` — schema, all SQL | **done** | Only file permitted to touch `node:sqlite`. 4 tests |
| `server/lib/corpus.mjs` — loader + sealed gate | **done** | `forDrill()` is the single gate, no bypass. 6 tests |
| `harness/DojoConcurrency.java` — coordination primitives | wip | Makes races *likely*, not merely possible |
| `server/lib/java.mjs` — compile + diagnostic parsing | wip | Line/column parsing is load-bearing for the editor |
| `server/lib/junit.mjs` — run a suite, parse per-test results | wip | Standalone console jar, no Maven. Empty suite is never green |
| `server/lib/diff.mjs` — curveball diff measurement | wip | **The most valuable measurement in the app** |
| `server/lib/stress.mjs` — concurrency harness | wip | Must provably catch a known lost update |
| `server/lib/grader-llm.mjs` — T1/T2/T3 tiers | wip | `claude -p` primary, Ollama fallback |
| `server/lib/grade-phase0.mjs` — vocabulary | wip | Structural checks now; **reflection probes still todo** |
| `server/lib/grade-phase1.mjs` — requirement extraction | wip | LLM + deterministic fallback, never fails closed |
| `server/lib/grade-phase2.mjs` — skeleton sprint | todo | Compile + required types/seams + clock |
| `server/lib/grade-phase3.mjs` — core build | todo | Base suite + mandatory `main` |
| `server/lib/grade-phase4.mjs` — extension under fire | todo | Curveball suite + diff budget |
| `server/lib/grade-phase5.mjs` — written defence | todo | Four question archetypes, graded vs decision log |
| `server/lib/grade-phase6.mjs` — concurrency | todo | 100-thread stress, no lost updates |
| `server/lib/grade-phase7.mjs` — full round, 5-dim rubric | todo | Hire/no-hire verdict + rubric breakdown |
| `server/lib/modes.mjs` — company mode config | todo | Clock, must-run, curveball timing, concurrency flag |
| `server/lib/ledger.mjs` — evidence claims + failure tags | todo | Claims computed from attempts, never asserted |
| `server/lib/readiness.mjs` — per-mode readiness table | todo | Honest about gaps |
| `server/index.mjs` + `lib/http.mjs` | **done** | Zero-dependency `node:http`, bound to 127.0.0.1, path traversal checked. 10 tests |
| `server/lib/validate-corpus.mjs` + CLI | wip | The gate that makes the naming guarantee true rather than aspirational |
| `server/lib/lessons.mjs` — Learn layer serving | todo | Faded-stage checks, predict gates, routing from failure tags |
| Routes for phases 3–7 | todo | Core build, extension, defence, concurrency, full round |

## The Standard and the Syllabus

Spec: `docs/specs/2026-08-18-standard-and-syllabus.md`. These exist because LLD is subjective and the
user must be trained against a fixed bar — and because a closed syllabus is what makes the work feel
finite instead of infinite.

| Component | Status | Notes |
|---|---|---|
| STANDARD v1.0 — 5 dimensions × 4 anchored levels | **done** (spec) | Level 2 is the hire bar; any single 0 is a no-hire |
| `syllabus_items` seed — the closed set of **34** | todo | 7 modelling · 8 seams · 5 principles · 4 API · 5 concurrency · 5 process |
| `problem_syllabus` tagging | todo | Per problem, which items it exercises |
| Coverage test — all 34 tagged by ≥1 problem | todo | Build fails naming any unreachable item |
| Closure test — no problem needs anything off-list | todo | Proves the list is complete, rather than claiming it |
| Citation validation — file exists, line in range | todo | Invalid → one retry → `unscored`, stated plainly |
| Mandatory `counter_evidence` at levels 2–3 | todo | Forces a search for disconfirmation |
| Drift sampling — 1 in 6 rounds double-graded | todo | ±1 level tolerated; 2 levels = the anchor is ambiguous |
| `standard_version` stamped per attempt | todo | Old and new scores never silently compared |
| Demonstrated vs **held** (2×, ≥3 days apart) | todo | Held is the readiness requirement, not demonstrated |
| Standard as a readable UI surface | todo | An auditable judge is a trustable judge |

## Front end

| Component | Status | Notes |
|---|---|---|
| `tokens.css` — palette, type, depth | **done** | Gold reserved exclusively for achievement |
| `motion.ts` — spring/ease/duration/stagger | **done** | Single source of motion truth. `cardHover` transform-only |
| `MotionProvider` + reduced-motion gate | **done** | Accessibility requirement, global, once |
| `grain.ts` | **done** | Inline SVG turbulence, no network |
| Bundled fonts (5 × woff2) | **done** | Instrument Serif / Inter / JetBrains Mono, 21–24 KB each |
| `Shimmer` | **done** | The word "Loading" appears nowhere in the app |
| `ClockRing` | **done** | Recedes while typing, reasserts when you stall |
| `Lozenge`, `Expand`, `Shell` | **done** | Expand macro = the spoiler gate |
| `api.ts` — typed client | **done** | |
| `zone` context — Lobby vs Execution | todo | **Enforced boundary**, drains the world over 600 ms |
| `Editor` v2 — tabs, tree, inline diagnostics, console, autosave | todo | Keystroke autosave; a crash mid-round must cost nothing |
| `SeamLantern` | todo | **Flagship trick.** Lights live as you declare types |
| `Ladder`, `Brief` + shared-element morph | todo | Card becomes the page |
| `VocabDrill` (P0), `ExtractDrill` (P1), `SkeletonSprint` (P2) | todo | |
| `CoreBuild` (P3), `Extension` (P4) | todo | P4 shows the diff number live |
| `Defence` (P5), `Concurrency` (P6) | todo | |
| `Round` (P7) + company mode picker + curveball injection | todo | Desktop notification + `REQUIREMENT-CHANGE.md` |
| `Ledger` — evidence claims, `Numeral` count-ups | todo | Headline: time-to-first-compiling-skeleton |
| `ReadinessBoard` | todo | |
| Lookup layer (patterns/SOLID reference) | todo | Reachable only *from* a failed drill |
| Frontier tier F1–F13 | todo | Lobby only. F13 telemetry HUD built first |

## The Learn layer — repositioned from afterthought to spine

Spec: `docs/specs/2026-08-18-learning-design.md`. The user's correction: *"this should be a very
effective LEARNING tool, not a test+mcq forward app with teaching content as an afterthought."* The
earlier design demoted teaching to a lookup layer; that was wrong. Assessment is retained and
**repositioned — its job is to aim the teaching.**

**Explicitly rejected:** MCQs (no LLD round asks one; they would inflate coverage without moving skill)
and video/lecture-length prose (the passive register is what failed in the first place).

| Component | Status | Notes |
|---|---|---|
| Worked → **faded** → independent progression | todo | The faded stage is the missing middle: the gap between watching a video and an empty editor |
| Adaptive fading | todo | Pass faded twice → it stops being offered. Fail independent → it returns |
| Contrast pairs with measured consequence | todo | Same `measureChange()` as the grader, so lesson and score share one instrument |
| Predict-before-reveal gates | todo | Nothing unlocks until he commits an answer. Wrong = calibration signal, never failure |
| Failure-tag → lesson routing | todo | 8 tags mapped to specific items and stages, not a generic list |
| Spaced retrieval + interleaving | todo | `held` (2×, ≥3 days) is a learning mechanism, not just a stricter bar |
| 34 lessons — 12 highest-leverage first | todo | B1 B6 C1 C2 C3 A1 A2 A5 A7 E1 E2 F2, then the other 22 |
| Per-lesson caps enforced | todo | `idea.md` ≤150 words, runnable Java mandatory, `when-not.md` mandatory, ≤8 min |
| Learn as a first-class surface | todo | Second in the sidebar, after the Ladder |
| Two-track coverage in the Ledger | todo | Studied / faded-passed / demonstrated / held — studying alone never advances readiness |

## Content — the critical path

Each problem needs 7 artifacts: prompt + must-haves + skeleton spec + base suite + curveballs
(suite + measured budget each) + review questions + reference with decision log.
Concurrency tests only where marked.

| # | Problem | Tier | Sealed | Concurrency | Status |
|---|---|---|---|---|---|
| 1 | Parking Lot | 1 | | | todo |
| 2 | Vending Machine | 1 | | | todo |
| 3 | Snake & Ladder | 1 | | | todo |
| 4 | Shopping Cart | 1 | | | todo |
| 5 | Elevator | 2 | | yes | todo |
| 6 | Movie Booking | 2 | **yes** | yes | todo |
| 7 | Food Ordering | 2 | **yes** | | todo |
| 8 | Tic-Tac-Toe | 2 | | | todo |
| 9 | Library | 2 | | | todo |
| 10 | Splitwise | 2 | | | todo |
| 11 | Rate Limiter | 3 | | yes | todo |
| 12 | Notification Service | 3 | **yes** | yes | todo |
| 13 | In-memory File System | 3 | | | todo |
| 14 | LRU custom eviction | 3 | | yes | todo |
| 15 | Logger | 3 | **yes** | yes | todo |
| 16 | Cost Explorer | 3 | | | todo |
| 17 | Rating System | 2 | | | todo |
| 18 | Middleware Router | 3 | | | todo |
| 19 | Customer Satisfaction | 2 | **yes** | | todo |
| 20 | Trip State Machine | 3 | **yes** | | todo |

## Packaging

| Component | Status |
|---|---|
| `run.ps1` / `run.sh` bootstrapping launchers | todo |
| `tools/build-ui.mjs`, `tools/fetch-fonts.mjs` | wip |
| `tools/package.mjs` → `lld-trainer.zip` | todo |
| macOS verification on the actual Mac | todo |
| `README.md` | todo |

---

## Definition of done

The app is finished when all of the following hold:

1. Every row above reads `done`
2. Bare `node --test` is fully green
3. A fresh unzip on a clean directory bootstraps and serves with no manual steps
4. **Every one of the 8 phases is completable end to end** against at least one problem
5. All 20 problems load and validate; the 6 sealed ones are unreachable from any drill endpoint
6. Every curveball's `diff_budget` was **measured** against its reference solution, never guessed
7. The app runs with the network disconnected — fonts, sounds and textures all local
8. `prefers-reduced-motion` leaves every surface usable
9. The frontier tier degrades to a declared fallback when WebGL/Houdini/View Transitions are absent
10. Verified on the Mac, not just on Windows
