@oneie/claude 0.1.0

package/commands/do-autonomous.md

@@ -0,0 +1,80 @@
+# /do autonomous loop
+
+Loaded by `do.md` for empty invocation or `--once` flag.
+
+---
+
+## Loop
+
+```bash
+W0: bun run verify (once per session, skip if already passed)
+
+ORIENT: Read docs/TODO.md
+        → note the active front (Atomicity / Vocabulary / New Surfaces)
+        → note the Top 15 priority list
+        → let this shape which task you pick
+```
+
+```
+loop:
+  SENSE:    GET http://localhost:4321/api/tasks
+            Sort by priority (effective = score + strength − resistance)
+            Skip blocked tasks (blockedBy non-empty)
+
+  SELECT:   Pick highest unblocked (P0 > P1, attractive > ready > exploratory)
+            If all blocked: GET /api/state → follow pheromone highways (deadlock escape)
+
+  EXECUTE:
+    BRIEF (before touching any file):
+      source = task.source
+      If source missing: grep -l "{task.name}" docs/*-todo.md
+      Read docs/{source}-todo.md:
+        • frontmatter source_of_truth → spec docs to pre-load
+        • find checkbox matching task.name → note exit criteria + "See also"
+        Read each source_of_truth entry (first 80 lines each)
+    WORK: run W1-W4 against the briefing above
+      W1 targets files named in task description + source_of_truth
+      W4 exit gate: composite ≥ 0.65 AND exit criteria from TODO section
+
+  VERIFY:   bun tsc --noEmit on touched files
+
+  MARK:     POST http://localhost:4321/api/tasks/{id}/complete
+
+  CLOSE:    POST http://localhost:4321/api/loop/cycle-close {
+              slug,
+              kind: "code",
+              scores: { security, stability, simplicity, speed }
+            }
+            composite = 0.35·security + 0.30·stability + 0.25·simplicity + 0.10·speed
+            composite ≥ 0.65 → mark(loop:cycle:{slug}, composite × 5)
+            composite < 0.65 → warn equivalents (route back to W3, max 3 W4 loops)
+            Response: { ok, slug, kind, composite, gate: "pass"|"fail", marks: { cycle, namespaced } }
+
+            Note: /api/loop/close (without "cycle-") is a different endpoint —
+            it manages WorkLoop session/stage tracking. Don't confuse them.
+
+  FEEDBACK: POST http://localhost:4321/api/signal {
+              receiver: 'loop:feedback',
+              data: {
+                tags: task.tags,
+                strength: rubricAvg,
+                content: { task_id, rubric, outcome: 'result' }
+              }
+            }
+            strength >= 0.65 → mark each tag path
+            strength < 0.65 → warn(0.5) each tag path
+            Always emit — even timeout, even dissolved. Every loop closes.
+
+  GROW:     GET http://localhost:4321/api/highways → report learned paths
+
+  → repeat
+```
+
+After each task: report name, strength, priority, tests passed, unlocked tasks.
+
+---
+
+## `--once`
+
+Single iteration: pick one task → execute → mark → stop.
+Report: name, strength, priority, tests, deterministic outcome (result/timeout/dissolved/failure).

package/commands/do-improve.md

@@ -0,0 +1,51 @@
+# /do --improve
+
+Loaded by `do.md` for `--improve` flag. Runs meta-improvement on do.md itself
+when drift signals accumulate.
+
+---
+
+## Signal source (checks in order, first hit wins)
+
+1. `signals.jsonl` — read `loop:drift:*` entries if file exists
+2. `learnings.md` — read all `drift:` entries (polling fallback)
+
+Group by wave+dim+tag_combo. For each group with count ≥ 2, run a one-cycle
+meta-improvement plan on `do.md`:
+
+---
+
+## The improvement cycle
+
+**W1:** recon the drifting wave section (Haiku — what does the current instruction say?)
+
+**W2:** decide a targeted edit to the agent prompt for that wave.
+  W2 edit scope (hard limit): may only propose edits to agent instruction text
+  (what agents are told to do, how to format output, what to read).
+  **Never propose changes to:**
+  - Gate thresholds (composite ≥ 0.65, severity > 0.5, relevance < 0.4 — these are numeric gate controls)
+  - Escape conditions (zero-findings guard, max W4 loops = 3, double-anchor-miss halt)
+  - The invariant list itself
+  If in doubt: if the proposed change alters a number that controls when the loop stops or passes, it is forbidden. Escalate to user.
+
+**Snapshot:** Before W3 spawns, record current do.md content in session dict `improve_snapshot`.
+
+**W3:** edit do.md (anchor pre-validated first, within W2 scope constraints).
+
+**W4:** adversarial verify — check these invariants are preserved:
+  - never skip W2
+  - always spawn W1+W3 in a single message
+  - gate thresholds unchanged (0.65 / 0.5 / 0.4 values must appear verbatim)
+  - relevance threshold unchanged (< 0.4 must appear verbatim)
+  - escape conditions unchanged
+  - W2 scope constraint present and unmodified
+  **Threshold disguise check:** scan diff for protected values (0.65, 0.5, 0.4, 3) in control-flow or gate logic. Values in informational prose are fine; flag only if inside a conditional or gate definition.
+
+---
+
+## Outcomes
+
+- **W4 pass:** mark drift entries `resolved` in learnings.md.
+- **W4 fail:** restore `improve_snapshot`, log `improve: rollback`. Retry once — W2 re-reads W4 failure report, produces revised proposal; W3 applies; W4 re-verifies.
+- **W4 fails on retry:** restore snapshot, escalate to user. Do not retry again.
+- **W4 fails twice total:** escalate. Loop cannot self-fix this pattern.

package/commands/do-show.md

@@ -0,0 +1,89 @@
+# /do --show mode
+
+Loaded by `do.md` when plan frontmatter has `show: true` or `--show` flag is passed.
+Default behavior for `/do <plan> --auto` on show-plans. The loop runs every cycle without
+intervention; pauses at each cycle close to render a cycle frame. Press Ctrl-C to stop;
+otherwise auto-continues to the next cycle.
+
+---
+
+## The cycle frame format
+
+```
+╭──────────────── C{n} / {plan-slug} / {cycle-name} ────────────────╮
+│  ✓ Cycle {n} of {N} complete                       rubric: 0.XX  │
+│                                                                   │
+│  Wave gates (W0 → W4)                                             │
+│  ───────────────                                                  │
+│    W0  bun run verify          ✓  {pass}/{total}                  │
+│    W1  recon                   ✓  {N} files ({hits} cache hits)   │
+│    W2  decide                  ✓  {decisions} decisions  ⬇ {Z} new │
+│    W3  edit (parallel)         ✓  {marked}/{dissolved-retried}    │
+│    W4  verify (scoped)         ✓  +{Δ} tests, biome+tsc clean     │
+│                                                                   │
+│  Rubric                                                           │
+│  ───────                                                          │
+│    security {0.XX}  stability {0.XX}  simplicity {0.XX}  speed {0.XX} │
+│    composite {0.XX}    ✓ above 0.65 gate                          │
+│                                                                   │
+│  Speed                                                            │
+│  ─────                                                            │
+│    {metric}  {value}  (target {budget} {✓|✗})                     │
+│                                                                   │
+│  What this unlocks                                                │
+│  ─────────────────                                                │
+│    👤 customer  {one sentence — what a human can now do}          │
+│    🤖 agent     {one sentence — what an agent can now do}         │
+│                                                                   │
+│  Lifecycle  [✓] {stage 1}  →  [✓] ...  →  [ ] {next stage}        │
+│                                                                   │
+│  Next: C{n+1} — {next cycle name + one-line preview}              │
+│                                                                   │
+│  Continuing in --auto... (Ctrl-C to stop)                         │
+╰───────────────────────────────────────────────────────────────────╯
+```
+
+After the final cycle, render a **lifecycle replay**: a short narrative walking the
+customer + agent through every stage the build now supports, in order.
+
+---
+
+## What goes in each section
+
+| Section | Source | Rule |
+|---|---|---|
+| Wave gates | telemetry from each wave's logger | one line per wave, ✓/✗ + one number; W2 also shows `⬇ Z new` (new primitives through compress check) |
+| Rubric | W4 markDims output | four numbers + composite + gate-pass |
+| Speed | `/api/speed` budgets for this cycle | only metrics this cycle changed |
+| What unlocks | plan's `lifecycle_show` frontmatter block | two sentences — customer + agent |
+| Lifecycle | plan's `lifecycle: [stages]` frontmatter | checkbox row, ✓ done / [ ] pending |
+| Next | next unchecked cycle + first task | one line; if last cycle, render lifecycle replay |
+
+---
+
+## Frontmatter required for show mode
+
+```yaml
+show: true
+lifecycle: [stage-1, stage-2, stage-3, stage-4, stage-5]
+lifecycle_show:
+  C1:
+    customer: "{one sentence — concrete user, concrete action}"
+    agent: "{one sentence — concrete agent, concrete capability}"
+    unlocks_stage: "stage-1"
+  C2:
+    customer: "..."
+    agent: "..."
+    unlocks_stage: "stage-2"
+```
+
+If `show: true` but no `lifecycle_show` block: render frame with `(no lifecycle narration)` and warn.
+
+---
+
+## Self-correcting hook
+
+Each frame emits `ui:do:show:rendered { cycle, rubric, lifecycle_stage }`.
+Ctrl-C'd frames → `warn(0.5)` on the cycle's tag — a rendered frame that's stopped is a
+signal something looked wrong. Future cycles with similar tags raise their
+security/stability bar at W2.

package/commands/do.md

@@ -0,0 +1,226 @@
+# /do — idea to shipped (v2, lifecycle-first)
+
+**One command.** Type `/do "<an idea>"` and it walks the whole build lifecycle from wherever the idea is: it agrees a goal, then walks the artifact spine — promise → spec → todo → code → tests → proof → docs → release — **writing whatever is missing, skipping whatever exists.** Point it at a bare idea and it writes everything. Point it at code with no tests or docs and it backfills just those.
+
+The human owns one thing: the goal sentence. `/do` owns everything below it.
+
+> Narrative for humans: `text/000-do.md`. Per-stage template/skill/agent routing: `plans/templates.md`. This file is what `/do` executes.
+
+---
+
+## Two principles, underneath every phase
+
+**Progressive disclosure.** Each phase loads only what it needs. Recon reads the last few turns + the most relevant files, never the whole history. A reference doc loads only when the work touches it. Skills are invoked, not inlined. Widen context only on a miss.
+
+**Parallel agents at the right model · effort.** Reach for the cheapest tool that can answer, then run as many as the work allows in one message. Two dials:
+
+```
+bash    none              bit-equal checks, greps, schema validation, test exit codes
+Haiku   low | medium      recon (low) · binary judgment / rubric (medium)
+Sonnet  low | medium      mechanical edit (low) · genuine restructure / prose (medium)
+Opus    high | xhigh      architecture (high) · substrate / schema reconciliation (xhigh)
+```
+
+Fan-out: independent agents in ONE message, capped by the plan's `parallel_budget`. Recon + verify fan wide (Haiku × N). Edits run one-per-file (Sonnet × N). Only the design decision (Opus) stays single — understanding is not delegable.
+
+### Fast & lean — the token economy (automatic, never a flag)
+
+Comprehensive and fast are not in tension: the **tier decides which gates run**, so a typo never pays for a feature's pipeline.
+
+| Lever | Fires at | Saves by |
+|---|---|---|
+| Tier prune | Step 1 | PATCH walks `code` only; a gate never runs above the phases it guards |
+| Tool ladder | every decision | bash → Haiku → Sonnet → Opus; stop at the first that decides |
+| **TRIVIAL fast-path** | BUILD | **0 agent spawns** — read ≤3 files inline, edit, bash verify, inline rubric, 1 learnings line |
+| Recon cache | W1 | KV `recon:{sha}:{sha}` hit (<14d) → skip re-read, `mark(recon:hit)` |
+| Verify-only-changed | W3→W4 | dependency cone from `git diff`; full verify only at cycle close |
+| Cross-cycle pre-warm | W4 close | one fire-and-forget Haiku pre-reads the next cycle's W1 targets |
+| Recon cap | W1 | 400-word receipt; high-signal slices → `.w2-spec.json`, not the raw dump |
+| Write-once state | per cycle | `.w2-spec`/`.w3-receipts` read by path, never re-derived after compaction |
+| `cost:cycle` gradient | close | spend → pheromone; future SELECT routes toward cheap-and-effective paths |
+
+A cycle that runs **zero LLM calls** is a *good* cycle. The comprehensiveness lives in the gates (DoD, rubric, doc-sync, ANALYZE, PROVE); the tier decides how many of them you pay for.
+
+### Maximize parallelism — read the graph, reject imaginary blockers
+
+Every multi-cycle plan carries a **Mermaid dependency graph**. `/do` reads it to fire the **maximum safe fan-out**: cycles with no edge between them run their waves *at the same time*, and their independent edits merge into ONE spawn message. The default is parallel — serial is the exception you must justify.
+
+```mermaid
+graph TD
+  C1[C1 foundation] --> C2[C2]
+  C1 --> C3[C3]
+  C1 --> C4[C4]
+  C2 --> C5[C5 composes]
+  C3 --> C5
+  C4 --> C5
+  C5 --> C6[C6 polish]
+```
+
+C2·C3·C4 are siblings → their W1/W2 run concurrently and their W3a edits merge into one message. C5 waits *only* because it reads files C2–C4 write.
+
+**The only valid arrow.** `C_n → C_m` exists **only** when C_m reads a file C_n writes. Before drawing one, fill the blank or delete it:
+> `C_n → C_m because C_m imports/reads {exact file path} that C_n creates.`
+
+**Imaginary blockers — reject on sight** (full list in `plans/template-todo.md`): "same feature area" · "same folder" · "both touch the DB" (unless the *same* entity) · "logical/reading order" · "don't want too many agents at once" (`parallel_budget` already caps it) · "want to review C_n first" (policy, not a dependency) · "C_m depends on what we *learn* in C_n" (W2 learning ≠ a file dependency).
+
+**Cross-cycle W3 batch (the big win).** A batch of 3 cycles with 8 + 6 + 4 independent edits = **18 `w3-edit` agents in ONE message**, not 3 sequential rounds. Only a named same-file collision serializes (→ W3b). Same rule for waves: W1 recon across all cycles in a batch is one Haiku spawn; W4 rubric is 5 Haiku × N cycles in one message — all capped by `parallel_budget`.
+
+---
+
+## Step 0 — Classify the input
+
+| Input | Treat as | Entry |
+|---|---|---|
+| bare text (`"add usage billing"`) | **IDEA** (default) | walk the spine from the top |
+| `<slug>` or a `plans/*.md` path | existing work | resolve its slug, walk from the first gap |
+| `--auto` | run all cycles of a todo continuously | BUILD engine, trust-aware |
+| `--wave N` | force one wave of a todo | BUILD engine |
+
+Derive the **slug** from the idea: kebab-case, 2–4 words (`"add usage billing"` → `usage-billing`). Every artifact on the spine is keyed by this slug.
+
+---
+
+## Step 1 — Goal + tier (the one human gate)
+
+1. **Restate as a goal**, one sentence: *"a {persona} can {outcome} they couldn't before."* Not "ship X" — "user can do Y" / "system enforces Z".
+2. **Size the tier** (the token economy — automatic, never a human choice):
+   ```bash
+   .claude/scripts/do-tier.sh --intent "<idea>" $(git diff --name-only 2>/dev/null)
+   ```
+   Emits **tier** (PATCH | FIX | FEATURE | SCHEMA), the **pruned spine** (which stops run), the **inner classifier** (TRIVIAL | SIMPLE | COMPLEX for BUILD), and a **token ceiling**. Default down when unsure — an under-built FIX reopens cheaply at PROVE; an over-built PATCH is tokens you can't refund.
+3. **Confirm once** — goal sentence + tier, in a single `AskUserQuestion`. Never interrogate. A pre-agreed backlog item auto-skips this gate.
+
+The pruned spine by tier:
+
+```
+PATCH     code                                                                  (edit + W4 verify gate; 0 spawns)
+FIX       survey → [investigate if legacy] → code → tests → prove
+FEATURE   promise → survey → spec ▸clarify → todo ▸analyze → code → tests → proof → docs → release
+SCHEMA    = FEATURE + substrate reconcile at max
+```
+
+`investigate` rides any tier when the work touches code we didn't just write — it's the "understand before you change" step, not a separate tier.
+
+---
+
+## Step 2 — Walk the artifact spine (presence-check · backfill · skip)
+
+For each **enabled** stop (per the pruned spine), in order: check if its artifact exists. **Exists → skip. Missing → write it with the owner below.** A stop whose artifact is present is a phase already done; resume is free, no `--from` flag.
+
+| Stop | Presence check | Missing → write with | Owner · model · effort |
+|---|---|---|---|
+| **promise** | `test -f text/<slug>.md` | `writer` skill + `text/template-frame.md` | sonnet · medium |
+| **survey** | `do-survey.sh` (4 surfaces) | reuse verdict (expose / extend / build / drop) → the gap list, not the whole idea, feeds the spec | `w1-recon`, `Explore` · haiku · low |
+| **investigate** *(fix / legacy only)* | code we didn't just write | forensic recon → root cause (not symptom) + blast radius + the `must_not_break` line | `w1-recon` · haiku→sonnet · medium |
+| **spec** | `test -f plans/<slug>.md` | Opus + `plans/template-spec.md` (designs the gap list; pre-mortem + decisions live in the template), then `do-reconcile.sh` | opus · high |
+| ↳ *CLARIFY* | spec has `## Clarifications` (FEATURE/SCHEMA) | ≤5 `AskUserQuestion`, written back into the spec | opus · high |
+| **todo** | `test -f plans/<slug>-todo.md` | `/create todo` + `plans/template-todo.md` | sonnet · medium |
+| ↳ *ANALYZE* | — | `do-analyze.sh plans/<slug>-todo.md` — CRITICAL exit 1 blocks BUILD | bash · none |
+| **code** | survey verdict = `build` (≥70% match → `expose`/`extend` instead) | the BUILD engine (Step 3) | sonnet · low–medium |
+| **tests** | test file in the repo folder | test-first, one assertion per deliverable | sonnet · low |
+| **proof** | proof artifact captured | `do-prove.sh` (browser / curl / contract / sync) + `accessibility`; **promise-check** the shipped thing against `text/<slug>.md`; FEATURE/SCHEMA built in a worktree → **merge to trunk only on PROVE pass**, abandon on fail | sonnet · low |
+| **docs** | feature doc + runbook exist | `tutorial` + `writer` — written against the *proven* behavior | sonnet · medium |
+| **release** | changelog / README row | `/release` + adoption signal | sonnet · low |
+
+**Proof before docs.** PROVE can fail and loop back to BUILD; docs written first would describe behavior that isn't final. Document what's proven, then ship.
+
+The two `↳` rows are **gates, not artifacts**: CLARIFY edits the spec in place (FEATURE/SCHEMA only); ANALYZE is read-only and blocks only on CRITICAL. Each real stop closes by leaving **one durable artifact on disk** — that artifact is the skip-check next time.
+
+**FRAME first (for FEATURE/SCHEMA).** The promise (`text/<slug>.md`) is what PROVE later checks the shipped feature against. If you can't state what the user gets, halt — the idea isn't ready to build. PATCH/FIX have no promise to keep, so they skip it.
+
+**Before BUILD — EQUIP (skill-check).** Infer skills from the task tags → `ls .claude/skills/{name}/` → **ready** (proceed) / **stale** (warn, proceed) / **missing** (offer to add). Block only if a required skill is missing.
+
+**Checkboxes — the file is the progress bar.** Every actionable item is a `[ ]`, and `/do` flips it to `[x]` the **moment** that action finishes — never batched at the end, never "I'll tick them next time." A user reading the todo mid-run sees exactly where the fan-out is.
+
+| When | Ticked by |
+|---|---|
+| a W1 recon agent returns findings for a file | `/do` after the agent settles |
+| a W2 verdict / diff spec / doc-plan resolves | `/do` inline |
+| a W3 edit agent reports success on a file | `/do` after the agent settles |
+| a W4 check passes (verify · demo · doc-sync · rubric · ratchet) | `/do` after the bash exits 0 |
+| all of a wave's items are `[x]` | the wave header (derived) |
+| all 4 waves `[x]` | the cycle header (derived) |
+| all cycles in a batch `[x]` | the batch header (derived) |
+
+Forward-only — a `[x]` is never un-ticked except by `/do --wave N --redo`. If an action has no checkbox, it isn't tracked, and untracked work is the loudest smell. Full granularity table in `plans/template-todo.md`.
+
+After the spine: **LEARN / close** — write one `learnings.md` entry (slug, tier, composite, deliverable, proof line), emit `signal("cost:cycle", {tokens, model, composite})`, delete `.w3-receipts.json`, write `.do-trust.json {level, consecutive, composite}`, and append `.w4-improvements.json` (an open item recurring in 3+ consecutive cycles = systemic gap → emit `substrate:systemic-gap`; next W1 reads it as a mandatory recon target).
+
+**Plan-outcome kill-switch (zero LLM).** Re-run the plan's `outcome:` command every cycle close. Exit 0 → the goal is met: remaining cycles enter justify-or-drop (default drop), `--auto` halts. Over the tier ceiling → `warn` + justify. Weak rubric 3× → halt, the *plan* is wrong, not the code. Goal-drift (outcome fails 3× with green rubrics) → force a re-plan.
+
+**`--auto` continuation (trust-aware, reads `.do-trust.json`).** `trusted` (composite ≥ 0.85 × 3+) → start the next cycle immediately. `standard` (0.65–0.85) → continue. `cautious` (< 0.65 × 2) → halt, run `/do next` to resume. Absent file → `standard`.
+
+---
+
+## Step 3 — The BUILD engine (W0 → W4)
+
+Runs only when the spine reaches `code`. Folder-aware: there is **no root `package.json`** — resolve the target repo folder from the touched files.
+
+**W0 — Baseline.**
+```bash
+RESOLVED=$(printf '%s\n' $CYCLE_TARGET_PATHS | .claude/scripts/do-folder.sh)
+echo "$RESOLVED" | jq -se 'all(.doc_only)' >/dev/null \
+  && echo "doc-only — skip bun verify" \
+  || echo "$RESOLVED" | jq -r 'select(.verify).folder' | while read -r f; do ( cd "$f" && bun run verify ) || exit 1; done
+TSC=$(bunx tsc --noEmit 2>&1 | grep -c "error TS" || echo 0)   # write .w0-baseline.json {tscErrors, loc, tests}
+```
+
+**W1 — Recon.** Read `.w4-improvements.json` open items first — they're mandatory recon targets. Check the recon cache (KV `recon:{sha}:{sha}` <14d) → hit skips the re-read. ≤5 files → read inline. ≥6 → spawn `w1-recon` (Haiku · low) for ALL files in ONE message; each returns structured findings; skip `relevance_score < 0.4`; all-filtered → halt and broaden (zero-findings guard). Receipt capped at 400 words; persist high-signal slices into `.w2-spec.json`. *(The `w1-recon` agent carries the two-track existing-code + primitive-inventory contract.)*
+
+**W2 — Decide (never delegated — Opus · high).** Write the goal/deliverable/UX gate (3 sentences) first. Then: reconcile names against `dictionary.md`; run the **compress check** before any new primitive (name 3 existing primitives that compose it → `compose` removes it from the diff, `new` needs a one-line justification + same-diff doc edit). The pre-mortem + trade-offs were already captured at the `spec` stop (`template-spec.md`) — carry the failure modes forward as test cases, don't redo them. Classify each W1 finding Act / Keep / Defer. Output diff specs + write `.w2-spec.json` (+ `.w2-doc-plan.json` if a doc trigger fires). *(The `w2-decide` agent carries the compose-target table — which canonical doc to check per primitive type — plus context-triggers for surgical doc injection.)*
+
+**W3 — Edit (Sonnet × N parallel).** Soft-resume first: if `.w3-receipts.json` has fewer receipts than `.w2-spec.json` diff specs, a prior W3 was interrupted — skip W0–W2 and resume from the first unapplied spec. Pre-validate every anchor with `grep -qF` in parallel. No file overlap → spawn all `w3-edit` agents in ONE message (W3a). Overlap → W3a (independent) then W3b (same-file, sequential). Append a receipt per edit; anchor miss twice → halt, ask user. Build every UI state (empty / loading / error / edge), not just the happy path.
+
+**W4 — Verify (bash first, zero tokens).**
+```bash
+( cd $folder && bun run verify )            # biome + tsc + vitest
+$(cycle.demo.command)                       # the goal gate — exit 0 = pass
+# doc-sync gate (reads .w2-doc-plan.json): stale-name=0, links ok, contract mtime current
+DELTA_TSC=$((TSC_NOW - TSC_BASELINE))       # hard gate: ≤ 0, no new type errors ever
+```
+Rubric (inline for TRIVIAL/SIMPLE; for COMPLEX spawn 6 Haiku · medium — goal-fit, security, stability, simplicity, speed, adversarial — alongside `pr-review-toolkit` (code-reviewer, silent-failure-hunter, type-design-analyzer) + `find-bugs` + `accessibility` on UI):
+```
+composite = 0.35·goal-fit + 0.20·security + 0.20·stability + 0.15·simplicity + 0.10·speed
+gate: composite ≥ 0.65  AND  goal-fit ≥ 0.50 (hard)  AND  no adversarial > 0.5  AND  delta_tsc ≤ 0
+```
+Verify scope is the **dependency cone** of `git diff` (full verify only at cycle close — speed). Then compress sweep (ts-prune + noUnusedLocals → delete orphans/dead code), write `.w4-improvements.json`, and fire one pre-warm Haiku at the next cycle's W1 targets. Verify or demo failure on touched files → W3.5 (one Sonnet per dirty file), max 3 W4 loops then halt.
+
+**Testing policy** (full detail in `plans/template-todo.md`): Vitest-first; Playwright only when the cycle declares `requires_playwright: true`; one goal-based `expect()` per deliverable (assert the destination, not the path); ≤1 test file per cycle; a cycle needing >5 tasks splits unless `mode: lean`; N-variant split-test → winner `mark()`, losers `warn(0.5)`.
+
+---
+
+## Definition of done (tier-scaled — `/do` ticks these automatically)
+
+1. The agreed goal is met (goal-fit gate). 2. Every shippable deliverable has a test asserting it. 3. No regression — tests green, `delta_tsc ≤ 0`, `must_not_break` preserved. 4. Proven live, matches the promise. 5. Docs in sync. 6. Full coverage, no orphan tasks. 7. Rubric clears the bar. 8. Closed loop — recorded result + one learnings entry.
+
+PATCH clears {1,2,3,8}. FEATURE clears all eight.
+
+---
+
+## Non-negotiable rules
+
+- **Never skip W2.** Understanding is not delegable.
+- **Default to parallel.** Spawn W1, W3, and W4-rubric agents in a **single message** — across cycles in a batch, not just within one. An arrow exists only when you can name the file one cycle writes and the next reads; reject every imaginary blocker.
+- **Tick the moment it lands.** Flip `[ ]`→`[x]` as each agent/check settles — never batch at the end. The file is the progress bar.
+- **FRAME before code (FEATURE/SCHEMA)** — no *feature* ships without a stated promise. PATCH/FIX skip FRAME by design.
+- **Closed loop** — every cycle ends in `mark`/`warn`, never a silent return.
+- **Cheapest tool that decides wins** — a phase that needs no LLM call is the best kind.
+- **W4 max 3 loops**, then halt and report.
+
+---
+
+## Available to /do — the toolbox
+
+**Scripts** (`.claude/scripts/`): `do-tier.sh` (tier + pruned spine + classifier + ceiling) · `do-folder.sh` (folder-aware verify/build) · `do-survey.sh` (reuse verdict) · `do-reconcile.sh` (substrate dim/verb/dead-name gate) · `do-analyze.sh` (spec↔todo coverage gate) · `do-prove.sh` (surface-detect proof) · `do-smoke.sh` (deterministic outcome).
+
+**Templates**: `text/template-frame.md` (promise) · `plans/template-spec.md` (design + pre-mortem + decisions) · `plans/template-todo.md` (plan + parallel budget + testing policy) · `plans/agent-template.md` (agent definition).
+
+**Agents**: `w1-recon` · `w2-decide` · `w3-edit` · `w4-verify` · `Explore` · `Plan` · `pr-review-toolkit:*` (code-reviewer, silent-failure-hunter, type-design-analyzer, pr-test-analyzer, code-simplifier) · `find-bugs`.
+
+**Skills** (per-stage routing in `plans/templates.md`): FRAME → `writer`, `copywriting` · SPEC → `typedb`, `signal` · BUILD → `astro`, `react19`, `shadcn`, `ai-ui`, `ai-sdk`, `reactflow`, `hono`, `cloudflare`, `wrangler`, `durable-objects` · TEST → `vitest`, `playwright-best-practices`, `webapp-testing` · VERIFY → `accessibility`, `find-bugs`, `perf`, `typecheck` · TEACH → `tutorial`, `writer`.
+
+**State files** (write-once, read-by-path — compaction-proof): `.w0-baseline.json` · `.w2-spec.json` · `.w2-doc-plan.json` · `.w3-receipts.json` · `.do-trust.json` · `.w4-improvements.json`.
+
+---
+
+*`/do` is `select()` made human-readable: idea in, shipped-and-proven feature out. The path remembers every execution.*

package/commands/improve.md

@@ -0,0 +1,99 @@
+# /improve
+
+Close the feedback loop opened by `stop-reflect.sh` and `session-start.sh`. Reads `.claude/improvements.queue.md`, presents each proposal, promotes accepted ones to the right target.
+
+The hooks open the loop. This command closes it.
+
+---
+
+## Loop
+
+1. Read `.claude/improvements.queue.md`. Empty → emit `improve:none`, exit.
+2. Parse: each `## YYYY-MM-DDTHH:MM:SSZ` header begins a session block; each `- **kind** ...` line is one proposal.
+3. For each proposal (oldest first, batched by session):
+   - Show the proposal verbatim
+   - Ask the user: **apply** / **defer** / **drop**
+4. On **apply**:
+   - Detect target file from the proposal text (table below)
+   - Apply the change via Edit (or surface the diff if it needs human anchoring)
+   - Move the proposal to `.claude/improvements.archive.md` with footer `→ applied {target}:{line} {YYYY-MM-DD}`
+5. On **defer**: skip; line stays in the queue for next pass.
+6. On **drop**: move to archive with footer `→ dropped {YYYY-MM-DD} (reason)`.
+
+---
+
+## Target resolution
+
+Proposals come in three kinds (set by `stop-reflect.sh`):
+
+| Proposal kind | Detection | Target |
+|---|---|---|
+| `**convention**` | `\.claude/(rules\|skills\|agents)/...` or `CLAUDE\.md` in path | the named file — promote the rule into its body |
+| `**new primitive**` | `\.claude/(skills\|rules\|agents\|hooks)/[^/]+\.(md\|sh)` | the index in `one-ie/.claude/CLAUDE.md` — add a one-line entry |
+| `**doc-drift**` | `<subdir>/CLAUDE.md` named | that CLAUDE.md — surface a 3-line summary of the most impactful code changes and ask the user which (if any) belong in the contract |
+
+If detection fails, the user is asked: "which file should this update?" Free-text answer accepted.
+
+---
+
+## Examples
+
+**Convention proposal:**
+```
+- **convention** `.claude/rules/api.md` — review: did this change introduce a rule the broader team should know?
+```
+→ `apply` opens `.claude/rules/api.md`, asks user for the rule text (one sentence), appends to the closest section.
+
+**New primitive proposal:**
+```
+- **new primitive** `.claude/skills/perf.md` — add a one-line entry to the index.
+```
+→ `apply` opens `one-ie/.claude/CLAUDE.md`, finds the skills index, appends `| /perf | ...` row.
+
+**Doc-drift proposal:**
+```
+- **doc-drift** `agents/CLAUDE.md` not updated despite 5 file changes under `^agents/src/`. Review.
+```
+→ `apply` runs `git log --oneline -5 -- agents/src/` (or `find agents/src -mtime -7`), summarises the 5 changes, and asks: "Does `agents/CLAUDE.md` need any of these reflected? If yes, paste the line(s) to add." User pastes; command Edits.
+
+---
+
+## Closed-loop signal
+
+```json
+{
+  "receiver": "improve:session:ok",
+  "data": {
+    "tags": ["improve"],
+    "weight": 1,
+    "content": {
+      "applied": N,
+      "deferred": M,
+      "dropped": K,
+      "archive_lines_added": APPLIED + DROPPED
+    }
+  }
+}
+```
+
+`applied > 0` → also emit one `mark` per `target_file` so the substrate learns which docs absorb improvement signal most often.
+
+---
+
+## Out of scope
+
+- Auto-applying without user review. The queue is a candidate list, not a worklist.
+- Editing user-scoped memory (`~/.claude/projects/.../memory/`). That's manual.
+- Pulling in changes from anywhere except `.claude/improvements.queue.md`.
+
+---
+
+## When to run
+
+- After 3+ proposals accumulate (the `session-start.sh` banner will say so).
+- Before any significant refactor — clearing the queue first prevents stale proposals against old code.
+- After a quarterly skill / CLAUDE.md audit — surface what's accumulated.
+
+---
+
+*Stop-reflect writes. Session-start surfaces. Improve closes. The path remembers what the system learned about itself.*

package/commands/kill.md

@@ -0,0 +1,45 @@
+# /kill — Reset dev environment
+
+Stop all Astro dev servers (ports 4321–4329) and wrangler (8787), clear node + astro + vite + wrangler caches, run `bun install`, then `bun run dev`.
+
+Use when HMR is broken, Vite re-optimization desyncs deps (duplicate React `useContext` is null, `createRoot` not exported with two `?v=hash` URLs), ghost ports refuse to release, or the user says "kill", "nuke", "reset dev", or "full clean rebuild".
+
+Scope is `one.ie/web/` only.
+
+## What it does (in order)
+
+1. **Kill** any process bound to ports 4321–4329 (Astro) and 8787 (wrangler), plus lingering `astro dev` / `wrangler dev` / `vite` / `workerd` processes
+2. **Clear** caches only — `.astro`, `node_modules/.vite`, `node_modules/.astro`, `dist` (preserves `node_modules` + `bun.lock` so install is fast; preserves `.wrangler/state` to keep local KV/D1/R2/DO data)
+3. **Reinstall** via `bun install`
+4. **Start** `bun run dev`
+
+## One-shot command
+
+Run this exactly:
+
+```bash
+cd /Users/toc/Server/one-ie/one.ie/web && \
+  (lsof -ti:4321,4322,4323,4324,4325,4326,4327,4328,4329,8787 2>/dev/null | xargs kill -9 2>/dev/null; \
+   pkill -f "astro dev" 2>/dev/null; \
+   pkill -f "wrangler dev" 2>/dev/null; \
+   pkill -f "vite" 2>/dev/null; \
+   pkill -f "workerd" 2>/dev/null; true) && \
+  rm -rf .astro node_modules/.vite node_modules/.astro dist && \
+  bun install && \
+  bun run dev
+```
+
+Start the final `bun run dev` in the background (`run_in_background: true`) so you can monitor logs and confirm the server is up on 4321.
+
+## When NOT to use
+
+- Cache-only fix would do → `rm -rf node_modules/.vite .astro && bun run dev` (~3s); this is ~30s
+- Production / deploy issues → use `/deploy` or `/build`
+- TypeScript errors only → use `/typecheck`; cache reset won't fix code
+- Dependency version drift suspected → manually `rm -rf node_modules bun.lock && bun install` (this command preserves both)
+
+## Diagnostic order (cheapest first)
+
+1. `rm -rf node_modules/.vite .astro && bun run dev` — clears Vite + Astro cache only (~3s)
+2. **This command** — kills servers + clears caches + reinstall (~30s)
+3. Full nuke: `rm -rf node_modules bun.lock .astro dist && bun install && bun run dev` (~90s) — only if dependency tree itself is suspect