@prestyj/cli 5.28.1 → 5.29.0

package/assets/skills/lean/SKILL.md

@@ -1,110 +1,129 @@
 ---
 name: lean
-description: Use when speed or resource efficiency matters — slow loading or startup, janky interaction, high CPU, memory leaks or RAM that grows over time, zombie/orphan processes, bundle bloat, dead code and dead styles, Core Web Vitals; while building anything that should stay fast and light, running a performance pass over an existing project, or pre-ship "will this run smoothly" checks. Any stack — web, backend/API/CLI, desktop (Electron, Tauri), mobile, native, game, ML pipeline. Do NOT use for copy/docs-only changes, design-direction or aesthetic work (that is evidence-led-ui; this skill's styling scope is payload and consistency), or when the user explicitly deprioritizes performance.
+description: Use when speed or resource use matters — while writing features that load, render lists, fetch, poll, spawn processes or cache (inline gate); on "slow / laggy / eating RAM / fans spinning", leaks, zombie or orphan processes, bundle bloat, dead code, Core Web Vitals; for a performance pass or pre-ship "will this run smoothly" check. Any stack — web, backend/API/CLI, desktop (Electron, Tauri), mobile, native, game, ML. Do NOT use for copy/docs-only changes, design direction or visual polish (that is evidence-led-ui; this skill's styling scope is payload and consistency), data-loss or migration safety (durable), or when the user explicitly deprioritizes performance.
 license: Performance engineering guidance, not a benchmark certification. Sources and snapshot date are recorded at the foot of each reference file.
-compatibility: Snapshot dated 17 August 2026. Thresholds, tool names, and defaults decay — re-verify with web access before asserting them as current. Claims sourced to that date carry a SNAPSHOT marker.
+compatibility: Snapshot dated 3 October 2026. Thresholds, tool names, and defaults decay — re-verify with web access before asserting them as current. Claims sourced to that date carry a SNAPSHOT marker.
 ---
 
 # Lean
 
-Make software fast, light, and smooth — loads quick, responds instantly, holds memory flat, leaves nothing running behind it. Built for the reality that users rarely ask for performance: they ask for a feature, then quietly leave when it eats RAM or takes five seconds to open.
+**Pick your mode now:**
 
-**This skill is on from the first line of code.** The default mode is the inline gate below — build the lean version while writing the feature, in the main thread. The full pass is for existing projects and pre-ship checks.
+| You are… | Mode | Do |
+|---|---|---|
+| Writing or editing a feature (any size) | **Inline gate** | Apply *Binding defaults* + *AI-code traps* while you write. One line in the reply on what you did. No benchmarks, no spawning. |
+| Asked "make it faster / why slow / eating RAM / will it run smoothly", a regression, pre-ship | **Full pass** | Run *Full-pass workflow*. Read `references/playbooks.md` sections for the stacks found; `references/memory-and-processes.md` for any memory or process finding. |
+| About to run `kill`/`pkill`/`taskkill`, or "stop that stuck process" | **Process safety** | Obey *Never kill your own host* first. |
+
+Users rarely ask for performance: they ask for a feature, then leave when it eats RAM or takes five seconds to open. This skill is on from the first line of code. Do not ship the heavy version intending to "optimize later".
 
 ## Governing rules
 
-1. **Measure, then cut.** In a pass, never optimize from vibes: baseline, find the bottleneck, fix it, re-measure. Guessing produces premature optimization — complexity without user-visible gain. In build mode the binding defaults below are pre-paid by platform evidence: apply them without benchmarking.
-2. **Fix the shared cause once.** The N+1 belongs in the query layer, not a memo at each call site. Check every caller of the slow path before patching where it hurt.
-3. **Optimize user time, not machine time.** What users wait on: startup, first paint, navigation, hot interactions, the nightly job. Micro-tuning code nobody waits for is last, always.
-4. **Memory should be flat.** After N cycles of the core loop, committed memory should look like after 1. Sustained growth is a leak until proven otherwise; a sawtooth that returns to baseline is GC, not a leak.
-5. **Nothing outlives its job.** Timers, listeners, observers, subscriptions, watchers, child processes, temp files, locks — everything with a lifetime needs an owner that ends it, on the success path *and* every failure path.
-6. **Bounded by default.** If it can grow — cache, queue, buffer, retry, log, list render — it gets a cap and an eviction policy at creation, not after the incident.
-7. **Small is fast.** Dead code, unused dependencies, and duplicate styles are parsed, shipped, and paid for. Removing is the cheapest optimization there is.
-8. **Numbers or silence.** Verify with before/after on the same machine and data, cold and warm. "Feels faster" is not a result, and never claim "optimized", "leak-free", or "fast" — say what moved, from X to Y, and what you could not measure.
-9. **No perf theater.** Complexity must pay for itself in measured user time; otherwise revert. Caching that introduces staleness bugs for an unmeasured gain is a regression wearing a costume.
-10. **Label evidence** on every claim: `RUNTIME` (you measured it), `CODE` (you read it), `DEDUCED` (inferred), `SNAPSHOT` (dated source claim). Never present what you read as what you ran.
+1. **Measure, then cut.** In a pass, never optimize from vibes: baseline → find the bottleneck → fix → re-measure. In build mode the binding defaults are pre-paid by platform evidence: apply them without benchmarking.
+2. **Fix the shared cause once.** The N+1 belongs in the query layer, not a memo at each call site. Check every caller of the slow path.
+3. **Optimize user time, not machine time.** Startup, first paint, navigation, hot interactions, the nightly job. Micro-tuning code nobody waits on is last.
+4. **Memory should be flat.** After N cycles of the core loop, committed memory ≈ after 1. A climbing staircase is a leak until proven otherwise; a sawtooth returning to baseline is GC.
+5. **Nothing outlives its job.** Timers, listeners, observers, subscriptions, watchers, child processes, temp files, locks — each has an owner that ends it on success *and* every failure path.
+6. **Bounded by default.** Cache, queue, buffer, retry, log, list render: cap and eviction policy at creation.
+7. **Small is fast.** Dead code, unused deps, duplicate styles are shipped and paid for. Deleting is the cheapest optimization.
+8. **Numbers or silence.** Before/after on the same machine and data, cold and warm. Say what moved, X → Y, and what you could not measure.
+9. **No perf theater.** Complexity must pay for itself in measured user time, or revert it. Caching that adds staleness bugs for an unmeasured gain is a regression.
+10. **Label evidence** on every claim: `RUNTIME` (measured), `CODE` (read in source), `DEDUCED` (inferred), `SNAPSHOT` (dated external source). Never present what you read as what you ran.
 
-## Two modes
+## Never kill your own host
 
-**Inline gate** — while writing any feature, apply the binding defaults below. One line in the reply about what you did and why it matters, then move on. Do not stop the build to lecture, and do not ship the heavy version intending to "optimize later" — later never comes.
+Agent sessions run *inside* a host process (EZ Coder's daemon/sidecar, an editor, a terminal multiplexer). Killing it kills this session and every sibling session mid-turn. This has happened.
 
-**Full pass** — triggered by "make it faster", "why is it slow / eating RAM / lagging", "will this run smoothly", a suspected regression, or a pre-ship check. Run the workflow below. Per-stack sweeps and measurement commands live in `references/playbooks.md`; the memory-leak catalog and process/zombie lifecycle detail live in `references/memory-and-processes.md`.
+- **Never kill by pattern.** No `pkill -f`, `killall`, `kill $(pgrep …)`, `taskkill /IM`, or loops over `ps | grep` output. Kill only an **exact PID or process group you started in this task** (you hold the PID from your own spawn or background-task handle).
+- **Before touching any PID you did not start:** walk its ancestry (`ps -o pid,ppid,command -p <pid>`, repeat up the PPID chain) and your own (`$$`, `$PPID` upward). If it is you, an ancestor, or another instance of the same host binary (e.g. another `app-sidecar`/daemon) — **do not kill. Report it.**
+- **A process using lots of CPU/RAM is a finding, not a target.** Report PID, command, RSS, age; recommend the fix. Orphan cleanup belongs to the app's startup sweep, never to a live session.
+- Unsure whether you own it? You don't. Ask the user.
 
 ## Binding defaults (build mode)
 
-Apply on every feature, every stack. These are the habits that prevent the pass from ever being needed:
+- **Teardown ships with the feature.** Whatever you start is torn down in the same module, success and error paths. One cleanup handle per owner: an `AbortController` for a component's fetches and listeners, a `dispose()`, a `finally`.
+- **Cap every accumulation.** LRU/TTL cache, bounded queue, paginated query, virtualized long list, capped retries with backoff + jitter, rotating logs.
+- **Never block the interactive thread.** Work that can exceed a frame (web long-task threshold: 50 ms) is chunked (`scheduler.yield()` where supported, else `setTimeout` chunking), deferred, or moved to a worker / utility process / background thread. No sync fs/crypto/CPU spikes in request handlers or UI code.
+- **Lazy by default, eager only for the first screen.** Rare routes, heavy editors, charts, optional SDKs: dynamic `import()` / deferred `require`. Preload only what the critical path provably needs.
+- **Right-size media.** AVIF/WebP with fallback, explicit `width`/`height`, `srcset`/`sizes`, `loading="lazy"` below the fold, `fetchpriority="high"` on the one LCP image only — never lazy-load it.
+- **Stream, don't hoard.** Stream files and large responses; cursor-paginate queries; chunk big jobs.
+- **Timeout everything external.** Network, subprocesses, locks, queues — and tear down on timeout.
+- **Price a dependency before adopting it** in anything user-facing (bundle impact client-side; `node --cpu-prof -e "require('mod')"` server/desktop).
+- **Batch I/O.** One query for N rows; DOM reads before writes; debounce/throttle expensive handlers.
+- **Events over polling.** Prefer push (WebSocket/SSE, fs watchers, DB notifications, webhooks). If you must poll: slowest interval the UX tolerates, back off when idle, pause on `visibilitychange` hidden, stop on unmount.
 
-- **Teardown ships with the feature.** Whatever you start — timer, listener, observer, subscription, child process, watcher — is torn down in the same module that started it, on success and error paths. Prefer one cleanup handle per owner (an `AbortController` for all of a component's fetches and listeners; a destructor/dispose method; a `finally` block) over scattered manual removes.
-- **Cap every accumulation.** LRU/TTL cache, bounded queue, paginated query, virtualized list, capped retries with backoff, rotating logs. Unbounded is a bug with a delay.
-- **Never block the interactive thread.** Chunk, defer, or offload work that can exceed a frame (web main thread long task threshold: 50ms) — web workers, background threads, task queues, utility processes. I/O stays async on the hot path; no sync fs/crypto/CPU spikes inside request handlers or UI code.
-- **Lazy by default, eager only for the first screen.** Below-the-fold media, rare routes, heavy editors, optional services: load on demand (dynamic `import()`, deferred `require`, on-demand plugin init). Preload/preconnect only what the critical path demonstrably needs.
-- **Right-size media.** AVIF/WebP with JPEG fallback, explicit `width`/`height` (also kills layout shift), `srcset`/`sizes` for density, decode thumbnails instead of full images.
-- **Stream, don't hoard.** Stream files and large responses, paginate/cursor DB queries, chunk large jobs. Loading a whole dataset into memory to process it item by item is the classic hog.
-- **Timeout everything external.** Network calls, subprocesses, locks, queues — no unbounded waits, and teardown on timeout.
-- **Price a dependency before adopting it** in anything user-facing: its load cost is your load cost (`node --cpu-prof --heap-prof -e "require('mod')"` for Node-side; bundle impact for client-side). The most-downloaded module is not the lightest.
-- **Batch I/O and reads-then-writes.** One query for N rows, not N queries; group DOM reads before writes; coalesce events (debounce/throttle) when handlers are expensive.
-
-## Full-pass workflow
+## AI-code traps (check every generated diff)
 
-### 1. Profile the target from the code
+The patterns agents produce most. Scan your own diff for them before replying.
 
-Before asking the user anything: shape (web app, API, CLI, desktop, mobile, library, game, ML pipeline — read manifests, lockfiles, build and CI configs), the surfaces users wait on (startup, first screen, navigation, hot interactions, batch jobs), scale (data sizes, traffic, session length), and platform constraints (low-end devices matter more than the dev machine).
-
-### 2. Baseline, or say you cannot
-
-Runtime numbers when the project runs: load time, startup time, p50/p99 latency, bundle sizes, RSS/heap at rest and after repeated cycles. Exact commands per stack are in `references/playbooks.md`. If you cannot run it (no environment, no data, no time), do a `CODE`-labeled static pass and say plainly in the report that nothing was measured — do not fabricate a baseline.
+| Trap | Detect | Fix |
+|---|---|---|
+| Whole-library imports | `import * as Icons`, `import _ from "lodash"`, root imports of big icon/UI/date kits | Per-icon/per-function imports or the library's documented tree-shakable entry; confirm in the bundle analyzer |
+| Effect refetch loops | `useEffect` fetching with object/array/function deps created during render, or no deps array | Fetch on the server / in the route loader / via a query library keyed by primitives |
+| Over-fetching | `SELECT *`, `findMany()` without `take`/`select`, API returning full rows to render two fields | Select needed columns, paginate, shape on the server |
+| N+1 | `await` on a query inside `for` / `.map` | Join/include/batch (`IN (...)`, DataLoader) |
+| Unvirtualized lists | `.map` over unbounded data into DOM or `ScrollView` | Paginate or virtualize (`FlatList`/`FlashList`, TanStack Virtual, `LazyColumn`) |
+| Polling | `setInterval(fetch…)` without cleanup or visibility check | Events; else backoff + pause + cleanup |
+| Everything client-side | `"use client"` at the top of a page tree; browser fetches data the server already had | Push the client boundary down to the interactive leaf |
+| Memo sprinkling | `useMemo`/`useCallback`/`React.memo` on everything | React Compiler on → write plain code, keep manual memo only as an escape hatch (e.g. stable effect deps). Compiler off → memo only what the Profiler implicates |
+| Unbounded module cache | `const cache = new Map()` at module scope, never evicted | LRU/TTL with a size cap |
 
-### 3. Sweep the six areas
+## Full-pass workflow
 
-Work this list in order — it reflects where user-perceived damage concentrates, not what is most interesting to engineer. Detection specifics per stack: `references/playbooks.md`; areas 3–4: `references/memory-and-processes.md`.
+1. **Profile the target from the code.** Shape (manifests, lockfiles, build/CI configs), surfaces users wait on, scale (data sizes, session length), platform constraints (low-end devices matter more than the dev machine). Build the coverage ledger (see Scaling).
+2. **Baseline, or say you cannot.** Load/startup time, p50/p99 latency, bundle sizes, RSS/heap at rest and after repeated cycles. Commands: `references/playbooks.md`. If nothing runs, do a `CODE`-labeled static pass and say plainly nothing was measured.
+3. **Sweep the six areas, in order:**
 
-| # | Area | What you are hunting |
+| # | Area | Hunting |
 |---|---|---|
-| 1 | **Loading & startup** | Slow first paint/open, render-blocking resources, giant bundles, eager imports of rarely-used code, waterfall requests, unoptimized media and fonts, cold-start work that could be deferred |
-| 2 | **Runtime responsiveness** | Long tasks blocking input, layout thrash, expensive re-renders, N+1 queries, sync work on hot paths, missing pagination, unvirtualized long lists, GC pressure from allocation churn |
-| 3 | **Memory** | Growth over time (leaks): forgotten timers/listeners/observers, detached DOM held alive, unbounded caches and maps, closures capturing large scope, cycles in non-GC runtimes, undecoded-or-full-size media, whole-file loads where streaming would do |
-| 4 | **Processes & lifecycle** | Zombie children (spawned, never reaped), orphans surviving parent exit (killed the node, not the tree), missing signal handling and graceful shutdown, leaked ports/fds/locks/temp files, no startup sweep for crash leftovers |
-| 5 | **Payload & dead weight** | Unused dependencies, dead code and dead exports, dead/duplicate CSS, two libraries doing one job (two icon sets, two date libs, two CSS systems), ship-weight of debug/symbol payloads, tree-shaking blockers |
-| 6 | **Styling consistency** | Same visual thing built three ways — repeated rule blocks, one-off spacing/color literals that duplicate tokens, framework utilities fighting handwritten CSS. Consistency here is payload: one way to do X is the only way that stays small. (Design direction itself is evidence-led-ui's call.) |
+| 1 | Loading & startup | Slow first paint/open, render-blocking resources, giant bundles, eager imports, request waterfalls, unoptimized media/fonts, deferrable cold-start work |
+| 2 | Runtime responsiveness | Long tasks / long animation frames, layout thrash, re-render storms, N+1, sync hot paths, missing pagination/virtualization, allocation churn |
+| 3 | Memory | Forgotten timers/listeners/observers, detached DOM, unbounded maps, large captured closures, non-GC cycles, full-size media, whole-file loads |
+| 4 | Processes & lifecycle | Unreaped children, orphans (killed node not tree), no signal handling, leaked ports/fds/locks/temp files, no startup sweep |
+| 5 | Payload & dead weight | Unused deps/files/exports, dead CSS, two libs for one job, debug payloads shipped, tree-shaking blockers |
+| 6 | Styling consistency | Same visual thing built three ways, literals duplicating tokens (design decisions are evidence-led-ui's call) |
 
-### 4. Rank by user impact, fix the top, not all
+4. **Rank by user impact; fix the top three to five.**
 
 | Severity | Meaning |
 |---|---|
-| **Critical** | Blocks or breaks: startup counted in tens of seconds, OOM crashes, multi-second UI freezes, a leak that kills a session in minutes |
-| **High** | User-perceivable degradation: sluggish interactions, fan-spinning idle CPU, RAM that climbs over a workday, zombie processes accumulating across runs, slowest paths 2–10× slower than they should be |
-| **Medium** | Waste with symptoms at scale: bundle bloat, N+1 under load, unbounded caches, missing pagination, duplicate dependencies |
-| **Low** | Hygiene without a measured symptom: dead code, dead styles, micro-tuning. Do these when adjacent to a real fix, never instead of one. |
-
-Fix the few that measurement actually implicates — three to five, rarely more. Each fix records its baseline number first. Prefer removing work over hiding it (delete the eager import beats code-splitting it beats deferring it), and prefer the platform primitive over a hand-rolled one.
-
-### 5. Verify the fix
+| Critical | Startup in tens of seconds, OOM, multi-second freezes, a leak that kills a session in minutes |
+| High | Sluggish interactions, busy idle CPU, RAM climbing over a workday, zombies accumulating, hot paths 2–10× slower than needed |
+| Medium | Bundle bloat, N+1 under load, unbounded caches, missing pagination, duplicate deps |
+| Low | Dead code/styles, micro-tuning — only when adjacent to a real fix |
 
-Re-measure exactly how you baselined, same machine, same data, cold and warm. A fix you did not measure is a hypothesis. For memory: cycle the changed path many times, force GC where the runtime allows (`--expose-gc`, DevTools), and compare committed memory — flat wins, sawtooth is fine, climbing is not fixed. If the number did not move, revert and say so; a change that adds complexity without moving the number is a regression.
+   Record each baseline first. Prefer removing work over hiding it (delete the eager import > code-split it > defer it); prefer the platform primitive.
+5. **Verify.** Re-measure exactly as baselined. Memory: cycle the path many times, force GC where possible, compare — flat wins. Number didn't move → revert and say so.
+6. **Leave one guard.** Bundle budget (`size-limit`, Lighthouse CI assertions), slow-query threshold, repeated-cycle memory assertion, a test that fails if the eager import returns.
+7. **Report.** Numbers first (X → Y, machine, data, date) → remaining findings ranked with file:line and fix → **not checked** list → changed vs recommended → dropped candidates (false positives). Label every claim.
 
-### 6. Leave a guard behind
+## Scaling: one agent or several
 
-One check so it cannot silently return: bundle-size budget in CI, Lighthouse CI or `size-limit` for web, a slow-query threshold, a repeated-cycle memory assertion where feasible, a test that fails if the eager import returns. One gate beats good intentions.
-
-### 7. Report
-
-- Lead with numbers: what moved, X → Y, on which machine/data/date.
-- Then remaining findings, ranked, each with file/line and the fix.
-- Then what was **not checked** — unmeasured areas, stacks skipped, environments unavailable. A report that silently skips the mobile client or the batch job reads as complete coverage.
-- Then what you changed vs. what you recommend and did not do.
-- Label every claim `RUNTIME` / `CODE` / `DEDUCED` / `SNAPSHOT`. Include your false positives — candidates you investigated and dropped — so the survivor list is not hiding its noise.
+| Situation | Do |
+|---|---|
+| Inline gate, small edit, single fix | Main thread only. Never spawn. |
+| Full pass, one deployable, you can read every relevant file | Single-threaded; build the ledger yourself. |
+| Full pass, several deployables (e.g. web + API + desktop shell + mobile), or more ledger rows than you can read fully | Fan out **static review** by surface — frontend / backend / processes & lifecycle — in ONE `spawn_agent` call (≤ 6). |
+| A dated claim needs checking (threshold, tool status) | One `researcher` child. |
+
+- **Ledger:** rows = six areas × in-scope units. Each row ends checked-with-findings / checked-clean / not-checked(reason).
+- **Child brief (self-contained):** absolute skill root and which `references/*.md` sections to read; slice paths; owned ledger rows; evidence labels; output = findings (file:line, label, severity, fix) + explicit `checked` / `not checked` lists; "read-only: do not kill, start, or benchmark anything". Use `owl`, or a general-purpose child if it must load this skill.
+- **Measurement does not fan out on one machine.** Benchmarks, load tests, and memory-cycle runs stay in the main thread, or one child per *separate environment*, so numbers stay comparable (same machine, same data, same build). Never run benchmarks in parallel on the same machine — they distort each other.
+- **Merge:** a failed, timed-out, or silent child → its rows are `not checked`, never clean. Re-open every reported file:line before reporting it.
+- **Large pre-ship pass:** one fresh-context verifier child tries to disprove the top findings.
+- **Edits stay serialized** in the main thread (or `bee` children on strictly disjoint files); re-measure once after merging.
 
 ## Honesty rules
 
 - Never state or imply the software is "fast", "optimized", or "leak-free". State what was measured, fixed, and left unchecked.
-- Never present a lint rule, bundle analyzer, or profiler as proof of the absence of problems; tools find a minority of what matters.
-- Never invent a number, threshold, or version. If the claim is date-sensitive and unverified, mark it `SNAPSHOT` or say "verify this".
-- "I could not measure this" is a legitimate and useful output. A fabricated confirmation is not.
-- If the project is a prototype with no users and no load, say that proportionality applies — five real fixes beat forty ignored ones — and stop early.
+- A lint rule, analyzer, or profiler is never proof of absence; tools find a minority of what matters.
+- Never invent a number, threshold, or version. Date-sensitive and unverified → `SNAPSHOT` or "verify this".
+- "I could not measure this" is a useful output. A fabricated confirmation is not.
+- Prototype with no users or load → say proportionality applies and stop early.
 
 ## Reference map
 
-Resolve every path from the installed skill root. Load only what the profile triggered.
+Resolve paths from the installed skill root. Load only what the profile triggered.
 
-- `references/playbooks.md` — per-stack sweeps and measurement commands: web frontend (Core Web Vitals with official thresholds), Node/backend/API, Electron, Tauri, mobile, native/compiled (Rust, C/C++, Go, JVM), Python, data & queries, and the payload/dead-weight/styling-consistency tooling. Read the sections the profile triggered.
-- `references/memory-and-processes.md` — the leak catalog by pattern, detection technique per runtime (three-snapshot, allocation timeline, heap dumps, pprof, valgrind, Instruments, LeakCanary), component-framework leak rules, and the process lifecycle playbook: zombies, orphans, signal handling, process-tree kills, container PID 1, startup sweeps, leaked fds/ports/temp files. Read for any memory or process finding.
+- `references/playbooks.md` — per-stack measurement and sweeps: web (Core Web Vitals, LoAF, React/Next/Vite), Node/backend, data & N+1, Electron, Tauri, mobile, native, Python, payload/dead-code tooling, styling consistency.
+- `references/memory-and-processes.md` — leak taxonomy and detection per runtime; process lifecycle: host-safety rule, zombies, orphans, tree kills, graceful shutdown, startup sweeps, container PID 1, leaked handles.

package/assets/skills/lean/references/memory-and-processes.md

@@ -44,7 +44,7 @@ ac.abort(); ro.disconnect(); clearInterval(id);
 
 Web-platform APIs accept `AbortSignal` directly; the rest get disconnected in the same teardown function. One owner, one path — including the error path.
 
-**Component frameworks (React and kin):** every subscription started in an effect is returned-from that effect for cleanup, no exceptions; stores and event buses get unsubscribe on unmount; beware module-level singletons accumulating per-component state (registered callbacks never removed — the leak lives on after the component dies). Long lists get virtualized. Before adding `memo`/`useMemo` anywhere, catch a real re-render in the Profiler — memoization has its own memory cost and is frequently perf theater. Watch `key` misuse: index keys on reorder-prone lists cause remount storms (CPU) and stale-capture bugs (memory).
+**Component frameworks (React and kin):** every subscription started in an effect is returned-from that effect for cleanup, no exceptions; stores and event buses get unsubscribe on unmount; beware module-level singletons accumulating per-component state (registered callbacks never removed — the leak lives on after the component dies). Long lists get virtualized. With React Compiler enabled, don't hand-add `memo`/`useMemo`; without it, catch a real re-render in the Profiler first — memoization has its own memory cost and is frequently perf theater. Watch `key` misuse: index keys on reorder-prone lists cause remount storms (CPU) and stale-capture bugs (memory).
 
 **Rust / C / C++ / Go / JVM / Python:** see the native/compiled and Python sections of `references/playbooks.md` for the per-runtime tools (valgrind/ASan/LSan, heaptrack, pprof, async-profiler/JFR, tracemalloc). The cycle shapes to hunt are listed in the taxonomy above.
 
@@ -64,6 +64,7 @@ Fix the lifetime, not the symptom: remove the registration (or disconnect the ob
 `kill(pid)` kills one process; its spawned children (MCP servers, LSPs, shells, helpers) survive as orphans. Correct patterns:
 
 - **Never kill the host you run in.** Before killing any long-lived daemon, node process, or "orphan", trace its ancestry (`ps -o pid,ppid,command` up the PPID chain) and check it is not your own host or an ancestor of it — agent sessions live *inside* a host daemon process, so a session killing that daemon kills itself mid-turn, and a child killing its parent kills the whole app's sessions. A process that is merely using lots of memory is a measurement finding, not a kill target; report it. Live-session agents do not kill host daemons at all — orphan cleanup belongs to the host's startup sweep (below), never to a session that might be running inside the thing it aims at.
+- **Never select targets by name or pattern** (`pkill -f`, `killall`, `pgrep | xargs kill`, `taskkill /IM`): another instance of your own host, or a sibling session's server, matches the same pattern. Signal only an exact PID — or the negative PID of a process group — that you spawned in this task and still hold. PIDs are reused: if your handle is stale (process already exited), do not re-resolve by name; check it is still yours (same start time/command) or leave it.
 - **Unix:** start the child in its own process group (`detached: true` in Node, `setsid`/`process_group` elsewhere), then kill the group: `process.kill(-pid, sig)` — the negative PID addresses the whole group. Escalate SIGTERM → grace period → SIGKILL.
 - **Windows:** there are no process groups; `taskkill /PID <pid> /T /F` kills the tree (`/T` = tree, `/F` = force), or use a Job Object assigned to children so closing the handle terminates them all.
 - **Both:** kill children *before* the parent exits, in order — parents can't clean up after they're dead; and children of an interactive app must die when the app does, normal exit *and* crash.
@@ -95,4 +96,4 @@ Anything that survives step 4 is the finding, and the ledger/sweep/group-kill pa
 
 ---
 
-**Provenance:** snapshot 17 August 2026. Sources: Rust std `process::Child` documentation (zombies and reaping), Node.js `child_process` documentation (detached/process-group semantics on Unix and Windows), Docker/tini PID 1 reaping guidance, Chrome DevTools memory documentation (three-snapshot technique, allocation timeline, `queryObjects`), web.dev long-task and lifecycle guidance. OS signal semantics are stable; tool flags and library APIs decay — re-verify specifics with web access before asserting.
+**Provenance:** snapshot 3 October 2026 (content otherwise from the 17 August 2026 review; OS semantics stable). Sources: Rust std `process::Child` documentation (zombies and reaping), Node.js `child_process` documentation (detached/process-group semantics on Unix and Windows), Docker/tini PID 1 reaping guidance, Chrome DevTools memory documentation (three-snapshot technique, allocation timeline, `queryObjects`), web.dev long-task and lifecycle guidance. OS signal semantics are stable; tool flags and library APIs decay — re-verify specifics with web access before asserting.

package/assets/skills/lean/references/playbooks.md

@@ -1,10 +1,12 @@
 # Lean — per-stack playbooks
 
-Load only the sections the profile triggered. Commands assume a POSIX shell unless noted. Claims sourced on the snapshot date (17 August 2026) carry `SNAPSHOT`; tool versions and thresholds decay — re-verify with web access before asserting as current.
+Load only the sections the profile triggered. Commands assume a POSIX shell unless noted. Claims sourced on the snapshot date (3 October 2026) carry `SNAPSHOT`; tool versions and thresholds decay — re-verify with web access before asserting as current.
+
+**Contents:** Web frontend · React / Next.js / Vite · Node.js / backend / API · Electron · Tauri · Mobile · Native / compiled · Python · Data & queries (N+1) · Payload & dead weight · Styling consistency
 
 ## Web frontend
 
-**Targets (official web.dev stable thresholds, measured at p75, mobile and desktop split):**
+**Targets (web.dev Core Web Vitals, field data at p75, mobile and desktop judged separately; unchanged since INP replaced FID in March 2024 — `SNAPSHOT`):**
 
 | Metric | Good | Needs improvement | Poor |
 |---|---|---|---|
@@ -12,9 +14,16 @@ Load only the sections the profile triggered. Commands assume a POSIX shell unle
 | INP (Interaction to Next Paint) | ≤ 200ms | ≤ 500ms | > 500ms |
 | CLS (Cumulative Layout Shift) | ≤ 0.1 | ≤ 0.25 | > 0.25 |
 
-SEO blogs circulate claims of a March 2026 tightening of LCP to 2.0s (`SNAPSHOT` — could not be confirmed on web.dev at snapshot time). Treat 2.0s as an aspiration, not a threshold; verify before quoting either number to a user.
+SEO blogs claim 2026 "tightenings" (LCP 2.0 s, stricter INP). None appear on web.dev as of the snapshot — quote only the table above. Lab tools (Lighthouse) cannot measure INP; it is a field metric. Lab = diagnosis, field (CrUX / RUM) = verdict.
+
+**Measure:**
+
+- Lab: Lighthouse (DevTools, or `npx lighthouse <url> --output json`), DevTools Performance panel (long tasks, long animation frames, layout shifts), Network waterfall, Coverage tab for shipped-but-unused JS/CSS.
+- Field: the `web-vitals` npm package; use its **attribution build** (`import { onINP } from "web-vitals/attribution"`) to get INP phase breakdown (input delay / processing / presentation) and the **Long Animation Frames (LoAF)** entries for the slow interaction — LoAF names the script and function that blocked the frame. LoAF is Chromium-only (shipped Chrome 123); script attribution misses cross-origin iframes, workers, and extensions.
+- SPAs: route changes after the first load are not separate page views in CrUX. Chrome's **Soft Navigations API** was in a final origin trial (Chrome 147–149) with a planned 2026 ship; how CrUX will use it is undecided (`SNAPSHOT`). Until it ships, measure SPA route transitions yourself (`performance.mark` around route change → next paint).
+- Regression gate: Lighthouse CI with assertions (budgets on LCP/CLS/TBT and resource sizes) and/or `size-limit` on bundle bytes.
 
-**Measure:** Lighthouse (DevTools or `lighthouse https://x --output json` in CI), Chrome DevTools Performance tab for long tasks, Network waterfall for request chains, Coverage tab for shipped-but-unused JS/CSS, `web-vitals` npm package for RUM field data. Lighthouse CI or `size-limit` as the regression gate.
+**Navigation speed:** the **Speculation Rules API** (`<script type="speculationrules">`) prefetches/prerenders likely-next pages. Chromium-only by default as of snapshot (Safari had it behind a flag; Firefox not shipped) — progressive enhancement, harmless elsewhere. Start with `moderate`/`conservative` eagerness; never prerender pages with side effects (logout, cart mutation, analytics that count views) or per-user sensitive content.
 
 **Symptom → usual cause:**
 
@@ -25,16 +34,24 @@ SEO blogs circulate claims of a March 2026 tightening of LCP to 2.0s (`SNAPSHOT`
 | High CLS | Images/embeds without dimensions, late banners pushing content, font swap | Width/height or `aspect-ratio` on all media, reserve ad/banner slots (`min-height`), `content-visibility` for below-fold, avoid injecting above existing content |
 | Slow nav | Waterfall fetches, client-side everything, no prefetch | Parallelize with `Promise.all`, prefetch likely-next routes, partial/staged rendering, keep-alive connections |
 
-**Sweep list:** code splitting at routes (`React.lazy`/dynamic `import()`), tree-shaking blockers (side-effectful modules, CJS in the graph), image audit (format, dimensions, `loading="lazy"` + `decoding="async"` below fold), font count and subsetting, dependency weight (bundle analyzer: `source-map-explorer`, `rollup-plugin-visualizer`, `webpack-bundle-analyzer`), virtualized long lists, memoization only where the React DevTools Profiler showed a real re-render cost — memo-by-default is perf theater, context split instead of one giant provider, `passive: true` listeners for scroll/touch, debounced resize/search handlers, service worker caching where offline or repeat visits matter.
+**Sweep list:** code splitting at routes (dynamic `import()`), tree-shaking blockers (side-effectful modules, CJS in the graph, barrel files re-exporting everything), image audit (format, dimensions, `loading="lazy"` + `decoding="async"` below fold, `fetchpriority="high"` on the LCP image only), font count and subsetting, dependency weight (analyzer: `source-map-explorer` works with any bundler's source maps; `rollup-plugin-visualizer` for Rollup/Vite; `webpack-bundle-analyzer` for webpack; Next.js's built-in analyzer for Next), virtualized long lists, context split instead of one giant provider, `passive: true` scroll/touch listeners, debounced resize/search handlers, third-party scripts (tag managers, chat widgets) — often the top INP offender in LoAF data.
+
+## React / Next.js / Vite
+
+- **React Compiler 1.0** (stable Oct 2025; works for React and React Native) auto-memoizes components and hooks. With it on, write plain code; React's guidance keeps `useMemo`/`useCallback` only as an escape hatch (e.g. a value used as an effect dependency). In existing code, don't mass-delete manual memo — removing it can change compiled output; remove only with tests. Without the compiler, memo only what the React DevTools Profiler implicates. The compiler does **not** fix effects: an effect that refetches on every render is still a bug.
+- **Next.js 16** (Oct 2025): Turbopack is the default bundler for dev and build. Caching is explicit — with `cacheComponents: true`, dynamic code runs per request and only `"use cache"` functions/components are cached (tune with `cacheLife`/`cacheTag`, invalidate with `revalidateTag`/`updateTag`). Perf checks: is expensive shared data cached? is per-user data kept out of shared cache (`"use cache: private"`)? is `"use client"` pushed down to leaves? are request waterfalls in server components parallelized? Turn on `reactCompiler: true` when the codebase passes the compiler's rules.
+- **Vite 8** (stable 12 Mar 2026): Rolldown (Rust) replaces esbuild + Rollup as the single bundler; config key `build.rollupOptions` → `build.rolldownOptions`; needs Node 20.19+/22.12+. Vite 7 projects still use Rollup. Build-time wins are not runtime wins — measure the shipped bundle, not the build clock.
 
 ## Node.js / backend / API
 
+**Runtime:** Node 26 becomes Active LTS on 28 Oct 2026; Node 24 moves to maintenance on 20 Oct 2026 (EOL 30 Apr 2028); Node 22 EOL 30 Apr 2027 (`SNAPSHOT`, nodejs/Release schedule). New projects target 24 now, 26 once it is LTS. Bun/Deno: same rules apply; benchmark your workload before switching runtimes for speed — vendor benchmarks are not your app.
+
 **Measure:** `autocannon` or `k6` for load (watch p99, not the average — the average lies), `clinic doctor` / `clinic flame` / `0x` for CPU and event-loop diagnosis, `--inspect` + Chrome DevTools for heap. DB: slow-query log, `EXPLAIN ANALYZE`.
 
 **Sweep list:**
 
 - **Event-loop blocking:** sync fs/crypto/zlib in request handlers, `JSON.parse` of huge payloads on the hot path, regex backtracking. Move to workers or streams.
-- **N+1 queries:** one join/include/dataloader instead of a loop of queries. The most common backend bottleneck, by far.
+- **N+1 queries:** one join/include/dataloader instead of a loop of queries. Detection under *Data & queries*.
 - **Missing indexes:** every frequent filter/sort column; verify with `EXPLAIN ANALYZE` that the plan uses them.
 - **Unpaginated reads:** `SELECT *` on growing tables, `findMany()` without `take`. Cursor pagination for stable ordering.
 - **Connection pools:** sized for the DB's real limit; check for pool exhaustion under load (requests queueing on a connection).
@@ -58,12 +75,12 @@ Official maintainer guidance (electronjs.org performance tutorial, `SNAPSHOT`):
 - **Startup:** `Menu.setApplicationMenu(null)` when no menu is needed; splash/deferred window show to cut time-to-visible; V8 compile cache for large renderer bundles.
 - Security config (`contextIsolation`, sandbox) is bulletproof's lane — but note sandboxing also shrinks renderer memory; do not weaken it for speed.
 
-## Tauri
+## Tauri (v2)
 
 **Sweep list:**
 
 - **Release profile:** in `Cargo.toml` `[profile.release]` — `lto = true` (or `"thin"`), `codegen-units = 1`, `strip = true`; `panic = "abort"` if acceptable. `opt-level = "s"/"z"` trades speed for size — measure which you need.
-- **IPC cost:** every `invoke` serializes with serde — don't shuttle large blobs or big JSON back and forth per keystroke; chunk, delta, or move the work to the Rust side. Watch for per-frame IPC from frontend animation/monitoring loops.
+- **IPC cost:** every `invoke` serializes (JSON by default) — for large binary payloads use Tauri 2's raw request/response bodies or channels rather than JSON arrays of bytes. Don't shuttle large blobs or big JSON back and forth per keystroke; chunk, delta, or move the work to the Rust side. Watch for per-frame IPC from frontend animation/monitoring loops.
 - **State:** `tauri::State` with `Mutex` held across `.await` serializes everything behind it; scope locks tightly.
 - **Frontend** follows the web section exactly — the webview is a browser; bundle size and long tasks hit the same.
 - **Assets:** embed vs. fetch per asset class; large binaries should not ship inside the binary if they can be fetched/unpacked on demand.
@@ -72,9 +89,13 @@ Official maintainer guidance (electronjs.org performance tutorial, `SNAPSHOT`):
 
 ## Mobile
 
-**Sweep list:** cold-start path (lazy screen registration, defer non-critical SDK init — analytics can wait), list virtualization (`FlatList`/`RecyclerView`/`LazyColumn` — never render 1000 rows), image assets per density via asset catalogs (not runtime-downscaled full images), main-thread discipline (decode/parse off the main thread), memory-warning handling that actually drops caches.
+**Sweep list:** cold-start path (lazy screen registration, defer non-critical SDK init — analytics can wait), list virtualization (`FlatList`/`FlashList`/`RecyclerView`/`LazyColumn` — never render 1000 rows), image assets per density (not runtime-downscaled full images), main-thread discipline (decode/parse off the main thread), memory-warning handling that actually drops caches. Measure on a low-end Android device in a release build — debug builds and simulators lie.
+
+**React Native:** since 0.82 (Oct 2025) the New Architecture is the only architecture; Hermes is the default engine; Hermes V1 was an experimental opt-in at that release (re-check status before recommending). Old-bridge libraries are a migration problem, not a perf knob. Avoid chatty JS↔native calls per frame; run animations on the UI thread (Reanimated worklets / native driver). React Compiler applies here too.
+
+**Android:** add **Baseline Profiles** (Jetpack Macrobenchmark + Baseline Profile Gradle plugin) so startup and hot paths are AOT-compiled; measure cold start with Macrobenchmark `StartupTimingMetric` or `adb shell am start -W`. **iOS:** measure launch with Instruments App Launch template and Xcode Organizer launch metrics; keep work out of `application(_:didFinishLaunching…)` and static initializers.
 
-**Measure/leak tools:** Android — Android Studio Profiler, `LeakCanary` for lifecycle leaks, `dumpsys meminfo`; iOS — Instruments Allocations/Leaks, Xcode memory graph debugger. Responding to memory warnings by freeing caches is table stakes on both.
+**Measure/leak tools:** Android — Android Studio Profiler, `LeakCanary`, `dumpsys meminfo`; iOS — Instruments Allocations/Leaks, Xcode memory graph debugger.
 
 ## Native / compiled
 
@@ -88,13 +109,17 @@ Official maintainer guidance (electronjs.org performance tutorial, `SNAPSHOT`):
 
 Generators/streams instead of list-building for large data; vectorize hot loops (NumPy/pandas — or Polars for large frames) instead of Python-level iteration; never block the asyncio event loop with sync I/O or CPU work (offload to processes); `functools.lru_cache` is bounded — `cached_property` and hand-rolled dict caches are not. Measure: `tracemalloc` for allocation deltas, `memory_profiler` line-level, `py-spy` for live flamegraphs without stopping the process. Watch for reference cycles keeping big objects alive when `gc` is disabled or timing-dependent.
 
+**Threads vs GIL:** Python 3.14's free-threaded build (`python3.14t`) is officially supported but optional, not the default (PEP 779). Single-threaded code runs roughly 5–10% slower on it, and importing a C extension that hasn't declared free-threading support re-enables the GIL for the whole process. Recommend it only for CPU-bound threaded work where the dependency stack supports it, and measure both builds. Otherwise: `multiprocessing`/`ProcessPoolExecutor` for CPU, asyncio for I/O.
+
 ## Data & queries (any stack)
 
+**N+1 detection:** turn on query logging in dev and count queries per request (a list page issuing 1 + N similar queries is the signature). Tools: Django `nplusone`/django-debug-toolbar, Rails Bullet or `strict_loading`, SQLAlchemy `lazy="raise"`, Prisma/Drizzle query logging, Laravel `Model::preventLazyLoading()`, GraphQL → DataLoader. Fix with eager loading / one batched query; add a test asserting the query count.
+
 `EXPLAIN (ANALYZE)` the slow ones; indexes on frequent filters/sorts — but every index taxes writes, so measure both sides. Batch writes; avoid N single-row inserts inside a transaction per row. Cursor/keyset pagination over offset for deep pages. Slow-query log threshold low enough to catch regressions in CI-like environments. Cache expensive reads with explicit invalidation, not hope.
 
 ## Payload & dead weight (all stacks)
 
-`SNAPSHOT` (17 Aug 2026): **Knip** is the standard JS/TS dead-code finder — unused files, exports, dependencies, and devDependencies across monorepo workspaces; `depcheck` is the older alternative. CSS: PurgeCSS (or the framework's built-in pruning) against real markup — beware class names built dynamically, which purgers cannot see; guard with a safelist. Shipped-code audit: DevTools Coverage for what the browser actually ran.
+`SNAPSHOT` (3 Oct 2026): **Knip** finds unused files, exports, dependencies, and devDependencies across JS/TS monorepo workspaces; `depcheck` is an older, narrower alternative (dependencies only). Bundle bytes: `size-limit` (fails CI over budget) plus a visualizer (see Web sweep list). CSS: PurgeCSS (or the framework's built-in pruning) against real markup — beware class names built dynamically, which purgers cannot see; guard with a safelist. Shipped-code audit: DevTools Coverage for what the browser actually ran.
 
 **Sweep list:** `knip` in CI; duplicate dependencies (`pnpm why <pkg>`, `npm ls <pkg>`) — two versions of one library is double weight; "two of the same job" audit (two icon sets, two date libs, two CSS systems, a utility lib plus hand-rolled copies of its functions); polyfills for browsers no longer supported; debug/symbol payloads shipped in release (strip; source maps to a symbol server, not the bundle); largest-files audit (`du`, bundle analyzer) — the top ten files are usually the whole story; unused assets in repos (images, fonts nobody references).
 
@@ -104,4 +129,4 @@ The rule: **one way to express one visual decision.** Hunt repeated rule blocks
 
 ---
 
-**Provenance:** snapshot 17 August 2026. Sources: web.dev Web Vitals (stable LCP/INP/CLS thresholds), Electron official performance tutorial (module cost, lazy loading, main-process blocking, profiling guidance), Rust std `process::Child` docs (zombie reaping), Knip documentation and 2026 ecosystem coverage (dead-code standard claim — `SNAPSHOT`), Valgrind/LeakCanary/Instruments/pprof public docs for tool usage. Version-specific flags and thresholds decay fastest; re-verify before asserting.
+**Provenance:** snapshot 3 October 2026 (all URLs accessed 3 Oct 2026). Sources: https://web.dev/articles/vitals (thresholds); https://web.dev/articles/find-slow-interactions-in-the-field and https://developer.chrome.com/docs/web-platform/long-animation-frames (attribution build, LoAF); https://developer.chrome.com/blog/final-soft-navigations-origin-trial (Chrome 147–149, CrUX use undecided); Speculation Rules support from secondary 2026 coverage (corewebvitals.io, uploadcare.com — Chromium default, Safari 26.2 flag; re-verify on caniuse); https://react.dev/blog/2025/10/07/react-compiler-1; https://nextjs.org/docs/app/api-reference/directives/use-cache; https://vite.dev/blog/announcing-vite8; https://github.com/nodejs/Release/blob/main/schedule.json (Node release dates); https://docs.python.org/3/whatsnew/3.14.html (PEP 779); React Native 0.82 release coverage (New Architecture only, Hermes V1 experimental). Carried from the 17 Aug 2026 snapshot, not re-verified: Electron official performance tutorial (module cost, lazy loading, main-process blocking, profiling guidance), Rust std `process::Child` docs (zombie reaping), Knip documentation and 2026 ecosystem coverage (dead-code standard claim — `SNAPSHOT`), Valgrind/LeakCanary/Instruments/pprof public docs for tool usage. Version-specific flags and thresholds decay fastest; re-verify before asserting.

package/assets/skills/refactoring/SKILL.md

@@ -1,11 +1,20 @@
 ---
 name: refactoring
-description: Use when restructuring existing code without changing behavior — "refactor", "clean up this module", "reduce tech debt/duplication", "split this god class/function", "improve code quality", "modernize" or migrate legacy code (strangler fig, framework/dependency upgrades, callback→async), or when planning a refactor before touching code. Two hats, test-guarded steps, revert-on-red. Do NOT use for new feature work, bug fixes with known symptoms (root-cause), styling or copy changes, the refactor step inside a user-requested TDD flow (tdd), or when the user asks to rewrite from scratch.
+description: Use when restructuring existing code without changing behavior — "refactor", "clean up", "reduce duplication", "split this god class", "modernize", migrating legacy code or APIs (strangler fig, parallel change, codemods across many files, callback→async), planning a refactor, or mid-build when a change needs preparatory restructuring first. Two hats, test-guarded steps, revert-on-red. Do NOT use for new features, bug fixes (stubborn ones: root-cause), performance tuning (lean), schema/data migrations (durable), styling or copy, the refactor step of a user-requested TDD flow (tdd), or a from-scratch rewrite.
 license: Behavior-preservation methodology synthesized from public sources (Fowler's Refactoring catalog, Tidy First?, and community agent skills by bienhoang, wondelai, mattpocock, jeffallan, vasilyu1983), audited 2026-09-12.
 ---
 
 # Refactoring
 
+**Route first:**
+
+| Situation | Mode | Next |
+|---|---|---|
+| Tidy a module/function you are already touching, suite green | **1. In-the-small** | Execute loop, inline |
+| User wants a plan, architectural change, or competing approaches | **2. Plan-first** | Modes → 2 |
+| No/red/unrunnable tests, or migration bigger than one session | **3. Legacy** | `references/legacy.md` before any edit |
+| Same mechanical change across >~10 files or >~500 lines | **Codemod** | `references/legacy.md` → Codemods |
+
 Change the structure of code without changing what it does. Every observable behavior that exists before the refactoring — including the bugs — must exist after it. This skill exists because agents drift: without hard gates, "refactoring" silently becomes rewriting, and rewriting untested code is how behavior is lost.
 
 **Without tests, you're not refactoring — you're editing.**
@@ -34,9 +43,9 @@ Change the structure of code without changing what it does. Every observable beh
 ## Execute loop
 
 1. **Baseline.** Run the suite on unmodified code; record green. If red or absent → mode 3. If the project has no VCS or the working tree is dirty with unrelated changes, say so and stop for direction — a dirty baseline destroys the revert safety.
-2. **Commit checkpoint.** Refactoring is safest with per-step commits on a dedicated branch — ask the user once, up front: "I'll commit each verified step on a branch — good?" If they decline, keep steps small and separable and report the step list for review at the end. Never commit without authorization; without any VCS, or with unrelated uncommitted changes in the tree, say so and stop for direction — a dirty baseline destroys the revert safety.
+2. **Commit checkpoint.** Refactoring is safest with per-step commits on a dedicated branch — ask the user once, up front: "I'll commit each verified step on a branch — good?" If they decline, keep steps small and separable and report the step list for review at the end. Never commit without authorization.
 3. **Pick one target.** Ranked by risk-adjusted value, not by how interesting it is: security → correctness → structure → duplication → naming. Hotspots first — files where churn (recent edit frequency) meets complexity. Smell catalog and metrics thresholds: `references/smells.md`.
-4. **Apply one named transformation.** Full mechanics per transformation live in `references/smells.md`. Prefer language-aware tooling (IDE rename, AST codemods) over regex edits; at scale (>~10 files or >~500 lines), a codemod is the safe path and regex is the wrong one.
+4. **Apply one named transformation.** Full mechanics per transformation live in `references/smells.md`. Prefer language-aware tooling (`code_nav` / IDE rename, AST codemods) over regex edits; at scale (>~10 files or >~500 lines), a codemod (ast-grep, jscodeshift, OpenRewrite) is the safe path and regex is the wrong one — workflow in `references/legacy.md`.
 5. **Verify.** Smallest relevant suite → green ⇒ commit (message = transformation name) → next target. Red ⇒ rule 4 of the governing rules: revert, take a smaller step.
 6. **Close.** Full suite + typecheck + lint, on the same commands CI runs — including every package that imports the code you touched, not just the one you edited (monorepos: respect build order). Report: transformations applied (named), before/after state, smells left and why, anything deferred. Agent-specific drift modes to check before closing: `references/agent-pitfalls.md`.
 
@@ -57,6 +66,18 @@ When unsure whether behavior could change: **do not apply — ask.**
 - You cannot run or construct any safety net and the risk is medium+. Report and stop.
 - The rewrite instinct hits ("this is all wrong, let me start fresh"). That is a different conversation with the user, not a refactor — and big-bang rewrites lose the one thing refactoring keeps: working software at every step.
 
+## Scaling: one agent or several
+
+| Situation | Do |
+|---|---|
+| In-the-small, or one package you can fully read | Main thread only. Never spawn. |
+| Large codebase: changed symbol has many callers across packages | Impact map first: ONE `spawn_agent` call, ≤ 6 read-only `owl` children, one per package/directory. Brief: the symbol(s) and their definition file:line, the slice's paths, output = every caller/import/dynamic reference as file:line + `checked`/`not checked` lists. |
+| Dated claim needed (framework migration, deprecated API) | One `researcher` child; label result SNAPSHOT with source URL. |
+| Executing transformations | **Serialized in the main thread**, one named step at a time, revert-on-red. Never parallel edits on a shared tree. |
+| Truly independent modules (no shared files, no import edges) | Optionally one `worker` per module on its own branch; each runs the full loop and its own baseline. Merge one branch at a time, full suite after each. |
+
+Merge rule: a child that fails or omits a slice → that slice is `not checked`; treat its callers as unknown and do not change the public signature. Re-open each reported caller before relying on it.
+
 ## References
 
 - `references/smells.md` — smell catalog, metrics thresholds, prioritization, transformation mechanics

package/assets/skills/refactoring/references/agent-pitfalls.md

@@ -11,6 +11,9 @@ LLM agents fail refactoring in specific, repeated ways. Human seniors watch for
 - **Null/undefined semantics drift** — old code crashed on null; new code defaults it. Or falsy-checks (`x || y`) "simplified" from explicit `!== undefined` where `0`/`""` are valid values.
 - **Scope and visibility drift** — module-level state introduced where locals were; caching added for performance that changes identity or staleness semantics.
 - **Silent feature addition** — validation, logging, or "improvements" smuggled in because the old code "looked wrong". The old behavior was the spec.
+- **Scope creep** — "while I'm here" edits in files outside the agreed target; reformatting mixed with structural change. Split or drop them.
+- **Duplicate helpers** — extracting a new function that already exists elsewhere; search (`code_search`, `grep`) before creating one.
+- **Config/lockfile drift** — a refactor diff must not touch dependency manifests, lockfiles, or lint/tsconfig rules unless that was the agreed step.
 - **Flaky green** — a test fails, passes on rerun, and gets shrugged off. During a refactor, one flaky red invalidates the whole green: rerun it, and if it flakes, quarantine and fix the flakiness before trusting any suite result.
 
 ## Test-healing anti-pattern
@@ -25,7 +28,7 @@ Before deleting code that looks pointless: `git blame`, read the commit message,
 
 Escalate only as far as the risk level demands:
 
-1. **Typecheck** — catches signature/shape drift for freer.
+1. **Typecheck** — catches signature/shape drift for free.
 2. **Lint** — catches dead code, suspicious patterns, unintended scope.
 3. **Unit + characterization suites** — the core proof; smallest relevant suite per step, full suite at close.
 4. **Contract test at the changed boundary** — input/output fixtures frozen before the refactor, diffed after.

package/assets/skills/refactoring/references/legacy.md

@@ -13,6 +13,8 @@ For codebases or areas where the baseline gate cannot be met: no tests, an unrun
 - Assert the captured behavior, including wrong-looking output. If output looks like a bug, record the bug and pin the bug.
 - Sufficient coverage: the paths your refactor will touch and their immediate callers. 80% project coverage is not the bar; coverage of the change surface is.
 
+Approval (snapshot) testing is the cheap way to do this for complex outputs: serialize the output, approve it once as the golden file, and any later diff fails the test (ApprovalTests exists for many languages; Jest/Vitest `toMatchSnapshot` works too). Scrub nondeterministic fields (timestamps, IDs) before comparing, or the net is flaky.
+
 Gate: the characterization suite is **green against the unmodified system** before any refactoring. A red baseline proves nothing later.
 
 **3. Create seams before structure.** A seam is a place where behavior can be intercepted without editing the logic:
@@ -42,8 +44,27 @@ Never skip the migration phase because tests pass — external consumers may exi
 ### Strangler Fig
 For replacing a subsystem wholesale. Put a facade in front of the legacy system → route traffic through the facade → intercept one route/slice at a time, implementing it fresh behind the facade (guarded by a feature flag when the slice is risky) → when all slices are intercepted, the legacy core is unused; delete it. Each interception must keep the characterization suite green.
 
+## Codemods (large mechanical changes)
+
+For one transformation applied across many files (rename, API migration, import moves). Tools: **ast-grep** (polyglot structural search/rewrite), **jscodeshift** (JS/TS transforms), **OpenRewrite** (recipes for large-scale refactoring, Java-first, also JS/TS). Use what is already installed; installing one needs the user's OK.
+
+1. **Search before rewrite.** Run the pattern read-only; count matches; spot-check ~5 by hand, including the weird ones (comments, strings, dynamic access, re-exports).
+2. **Dry run on one directory**, review the diff, run that package's tests.
+3. **Apply repo-wide as its own commit** — the codemod commit contains only codemod output. Hand fixes for leftovers go in a separate commit, so reviewers can trust the mechanical one.
+4. **Grep for survivors** the pattern missed (dynamic calls, string references, docs); list them, do not silently hand-edit beyond the plan.
+5. Full suite + typecheck + lint across every consuming package.
+
+An agent hand-editing 50 files is a rewrite with 50 chances of drift; a codemod is one reviewable rule.
+
 ## Per-phase discipline (all strategies)
 
 Every phase ends with a **validation checkpoint**: characterization + full suite green, and a stated **rollback trigger** — the condition under which this phase is reverted (a commit, a flag flip, never a re-merge). Keep commits bisectable: one phase-step per commit, `git bisect` must stay usable for finding which step changed behavior.
 
 Feature flags guard risky slices, but flags are debt: each one gets a removal issue at creation, and is retired as soon as the new path is proven.
+
+## Sources (SNAPSHOT, accessed 3 October 2026)
+
+- Parallel Change — https://martinfowler.com/bliki/ParallelChange.html
+- Strangler Fig — https://martinfowler.com/bliki/StranglerFigApplication.html
+- ApprovalTests — https://approvaltests.com/
+- ast-grep — https://ast-grep.github.io/ ; jscodeshift — https://jscodeshift.com/ ; OpenRewrite — https://docs.openrewrite.org/

package/assets/skills/root-cause/SKILL.md

@@ -1,36 +1,46 @@
 ---
 name: root-cause
-description: Use when a bug resists the obvious fix, behavior makes no sense, the same symptom keeps coming back, or the user asks why something happens and the answer is not on the surface. Do NOT use for bugs with a clear repro and an obvious cause — reproduce, fix, and re-run directly.
+description: Use when a bug resists the obvious fix, behaviour makes no sense, a symptom keeps coming back, a test is flaky, something "worked last week", or the user asks why something happens and the answer is not on the surface — including mid-build when a second fix attempt fails. Do NOT use for bugs with a clear repro and an obvious cause (reproduce, fix, re-run directly), security incident triage (bulletproof), or reviewing a diff (code-review).
 ---
 
 # Root-Cause
 
-The discipline: build a feedback loop before theorizing, then let evidence kill hypotheses. Everything else is mechanical. Each phase has a gate — do not pass a gate that has not been met.
+Build a feedback loop, then let evidence kill hypotheses. Each phase has a gate. Keep a hypothesis log in your replies: `H# | prediction | experiment | result | verdict`.
 
 ## Phase 1 — Build the loop
 
-Construct ONE command that reproduces the failure on demand. Cheapest construction that works, in order: failing test → request script (curl) → CLI invocation → headless browser script → recorded trace replay → minimal harness → bisect → differential run (old vs new).
+ONE command that reproduces the failure on demand. Cheapest first: failing test → curl/script → CLI run → headless browser script → trace replay → minimal harness.
 
-Exit gate — the command must be **red-capable** (fails while the bug lives), **deterministic** (same input, same result), **fast** (seconds, not minutes), and **agent-runnable** (no manual UI steps). Run it red. No red command, no Phase 2.
+Gate: **red-capable**, **deterministic**, **fast** (seconds), **agent-runnable**. Run it red. No red command, no Phase 2.
+
+- **Flaky?** Run it N times (e.g. 20–50) and record the fail rate; that rate is the signal. Vary one thing at a time (order, seed, parallelism, timing) until it is deterministic or the rate moves.
+- **Worked before?** With a known-good commit and the loop as a script: `git bisect start <bad> <good>`, then `git bisect run <script>` (exit 0 = good, 125 = skip untestable commit, any other 1–127 = bad). Always `git bisect reset` after. Ask first if the tree has uncommitted work.
 
 ## Phase 2 — Shrink it
 
-Strip the repro to the smallest input and config that still fails. Each removal teaches what is irrelevant; what survives is implicated. Already minimal? Say so and move on.
+Remove input, config, and code until removing anything more makes it pass (delta debugging: halve, test, keep the failing half). What survives is implicated. Already minimal? Say so.
 
 ## Phase 3 — Hypotheses
 
-List 3–5 hypotheses, one sentence each, each falsifiable by a specific observation ("stale cache after config reload — clearing the cache between runs makes it disappear"). Rank by likelihood × cheapness to test. Show the user the list before testing — non-blocking.
+3–5 falsifiable one-liners, each naming the observation that would kill it. Rank by likelihood × cheapness. Show the list (non-blocking).
 
 ## Phase 4 — One variable
 
-Test one hypothesis at a time, cheapest first. Tag debug output `[DBG-xxxx]` with a random suffix per investigation so removal is one grep. Never change two things between runs of the loop.
+Test one hypothesis at a time, cheapest first. Never change two things between runs. Instrument boundaries (inputs, outputs, timing), not everything; prefer existing logging/tracing or the debugger. Tag new debug output `[DBG-xxxx]` (random suffix) so removal is one grep.
 
 ## Phase 5 — Regression test before fix
 
-With the winning hypothesis, write the failing regression test FIRST, at a real seam. If no correct seam exists to test this behavior, that absence is itself the finding — the module boundary is wrong. Record it and test at the nearest honest boundary. No test suite in the project and none requested? Keep the repro script as the regression check — never introduce a suite unasked.
+Write the failing regression test FIRST at a real seam. No honest seam? Record that as a finding and test at the nearest honest boundary. No suite and none requested? Keep the repro script as the check — never introduce a suite unasked.
 
 ## Phase 6 — Close out
 
-If the ask was "why", stop at the answer: report the root cause and the fix it implies — change code only when the user asks for the fix. Otherwise: fix. Run the loop green, run the regression test, remove every `[DBG-xxxx]` line (grep the tag), and state the root cause in one sentence in the commit or report: cause → mechanism → symptom.
+If the ask was "why", stop at the answer and the fix it implies — change code only when the user asks for the fix. Otherwise fix, run the loop green (flaky: N runs, zero failures), run the regression test, grep-remove every `[DBG-xxxx]`, and state the cause in one sentence: cause → mechanism → symptom. Label claims `RUNTIME` / `CODE` / `DEDUCED`.
+
+Hard rules: three failed fixes → the hypothesis list is wrong; return to Phase 3. Redact secrets from any quoted or committed log line.
+
+## Scaling: one agent or several
+
+- Reproduction, shrinking, and experiments: main thread only — one variable at a time.
+- Wide codebase (several packages could own the bug): in Phase 3 you may send one read-only `owl` per hypothesis in a single `spawn_agent` call; brief = symptom, repro command, paths, "return file:line evidence for/against; do not run or edit". Treat replies as `CODE` leads to re-open, not verdicts.
 
-Hard rules: if the same fix attempt fails three times, stop patching — the hypothesis list is wrong, not the code; return to Phase 3. Redact secrets from any log line quoted or committed.
+Sources (accessed 3 October 2026): https://git-scm.com/docs/git-bisect; https://www.debuggingbook.org/html/DeltaDebugger.html