@prestyj/cli 5.28.0 → 5.29.0

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

package/assets/skills/shared-language/SKILL.md

@@ -1,30 +1,32 @@
 ---
 name: shared-language
-description: Use when a project's domain vocabulary is fuzzy or drifting, naming decisions keep recurring, or a hard-to-reverse architectural decision needs recording so it is not re-litigated or re-suggested later. Do NOT use for throwaway scripts or projects too small to have recurring vocabulary.
+description: Use when a project's domain vocabulary is fuzzy or drifting (two names for one thing, one name for two), naming decisions keep recurring, or a hard-to-reverse architectural decision needs recording so it is not re-litigated or re-suggested — including mid-build when a term settles or a change contradicts an ADR. Do NOT use for throwaway scripts, projects too small to have recurring vocabulary, interviewing for requirements (clarify), or renames with no vocabulary decision (refactoring).
 ---
 
 # Shared Language
 
-A repo's terms are its compression. When you and the user mean the same thing by "reservation", every prompt, name, and doc gets shorter and sharper — and the agent stops spending thinking tokens re-deriving what a single word encodes. This skill builds and maintains that vocabulary.
+Two artifacts: the glossary (`CONTEXT.md`) and decision records (`docs/adr/`). On entry, read both if they exist, then act on the trigger: term settled → glossary; hard call made → offer ADR; change contradicts an ADR → surface it.
 
 ## The glossary — CONTEXT.md
 
-At the repo root. **A glossary and nothing else**: term — a one-to-three-line definition, no implementation details, no history. If a definition names a file path, it has become documentation; move that out.
+At the repo root. **A glossary and nothing else**: `term — 1–3 line definition`, plus `Avoid: <synonyms>` where drift exists. No file paths, implementation, or history.
 
-- Challenge fuzzy terms against it: "the glossary defines *cancellation* as pre-charge; this change reads as post-charge — which is meant?"
-- Stress-test a new term with an invented edge case before recording it ("is a no-show a cancellation?").
-- Update **inline, the moment a term settles** — never batch glossary edits for "later"; later never comes.
-- Name files, functions, variables, and tests with glossary terms verbatim. When code and glossary disagree, one of them is wrong — find out which.
-- Create the file lazily on the first settled term, never as an empty template.
-- On first creation, add one line to the repo's instruction file (AGENTS.md, or CLAUDE.md if that is what the repo uses): `Read CONTEXT.md before naming anything.` CONTEXT.md is not auto-loaded — the pointer is what makes the glossary ambient in every session.
+- Challenge fuzzy usage against it: "glossary says *cancellation* is pre-charge; this reads post-charge — which?"
+- Test a candidate term with an invented edge case before recording it ("is a no-show a cancellation?").
+- Update the moment a term settles; create the file lazily on the first settled term, never as an empty template.
+- Code, tests, and UI use glossary terms verbatim. Code and glossary disagree → one is wrong; ask which.
+- On creation, add to the repo's instruction file (AGENTS.md, or CLAUDE.md if that is what it uses): `Read CONTEXT.md before naming anything.` CONTEXT.md is not auto-loaded — that pointer is what makes it count in later sessions.
 
 ## Decision records — docs/adr/
 
-An ADR earns its file only when a decision is **hard to reverse**, **surprising without context**, and **a real tradeoff** — all three. One file per decision: title, 1–3 sentences of context, the decision, the main rejected alternative and why. Numbered; immutable once accepted — supersede, never edit.
+Only when a decision is **hard to reverse**, **surprising without context**, and **a real tradeoff** — all three. Offer it; don't write unasked.
 
-Read the ADRs before proposing a change that contradicts one: honor it, or surface the conflict to the user. Never silently relitigate a recorded decision, and never re-suggest a rejected alternative without new facts.
+- Follow the repo's existing ADR format. None? Use the MADR 4 minimal shape: `NNNN-title-with-dashes.md` with Context and Problem Statement, Considered Options, Decision Outcome (chosen option + why), Consequences; `status: accepted` in front matter.
+- Immutable once accepted — supersede, never edit: new ADR notes `Supersedes NNNN`; the old one's status becomes `superseded by NNNN` (the only allowed change).
+- Before proposing a change that contradicts an ADR: honour it or raise the conflict. Never re-suggest a rejected option without new facts.
 
-## Integration
+## Scaling: one agent or several
 
-- During a clarify session: settled terms go to the glossary; qualifying hard calls get an ADR offer.
-- Before naming anything: read the glossary if it exists.
+Main thread only. On a large repo, one `owl` may inventory competing terms across packages (occurrences with file:line); the main thread decides and edits.
+
+Sources (accessed 3 October 2026): MADR 4.0.0, latest release (2024-09-17) — https://adr.github.io/madr/; ubiquitous language — https://martinfowler.com/bliki/UbiquitousLanguage.html

package/assets/skills/tdd/SKILL.md

@@ -1,30 +1,42 @@
 ---
 name: tdd
-description: Use when the user asks for test-driven development, red-green-refactor, or "write the test first", or wants a feature built test-first. Do NOT use when tests are a verification step after the build, the project has no suite and the user has not asked for one, or the change is throwaway probe code.
+description: Use when the user asks for test-driven development, red-green-refactor, "write the test first", or wants a feature or bug fix built test-first — including mid-build when they ask to switch to test-first. Do NOT use when tests are a verification step after the build, the project has no suite and the user has not asked for one, the change is throwaway probe code, or the goal is restructuring without behaviour change (refactoring) or finding an unknown cause (root-cause).
 ---
 
 # TDD
 
-Red → green, one slice at a time. This skill is the reference that makes the loop produce tests worth keeping — most of it applies on every cycle, so consult it before and during the loop, not after.
+Red → green, one vertical slice at a time. Before the first test: agree seams (below). Then loop.
 
 ## Seams — agree before writing
 
-A **seam** is the public boundary where behavior is observable: an exported function, an HTTP route, a CLI invocation. Tests live at seams; they never reach into internals.
-
-Before the first test, write down the seams under test and confirm them with the user — which boundaries get tests and which stay untested is a decision, and settling it up front is what keeps effort on critical paths instead of every edge case. No test at an unagreed seam.
+A **seam** is a public boundary where behaviour is observable: exported function, HTTP route, CLI invocation. Tests live at seams, never in internals. List the seams under test and confirm them with the user (one `ask_user` call, recommended set marked). No test at an unagreed seam.
 
 ## The loop
 
-1. **Red.** One failing test at an agreed seam, for the next smallest real behavior. Run it; watch it fail for the right reason.
-2. **Green.** The least code that passes — nothing speculative. Run it.
-3. **Repeat.** The next test responds to what the last cycle taught. Work in vertical slices, never layers: writing all tests then all implementation verifies *imagined* behavior and locks in structure before understanding.
-4. **Refactor outside the loop.** Cleanup happens at a checkpoint after a green cycle or in a review pass — not interleaved guesswork inside red-green.
+1. **Red.** One failing test at an agreed seam for the next smallest real behaviour. Run it; confirm it fails for the right reason (assertion, not import/syntax error).
+2. **Green.** Least code that passes. Run the test and the touched suite.
+3. **Repeat.** The next test follows from what the last cycle taught. Never write all tests first, then all code.
+4. **Refactor** only on green, as a separate step; rerun tests after.
+
+## Test integrity (agent guard)
+
+- **Tests are frozen during green.** Never edit, delete, skip, loosen, or `.only` a test to make it pass. If a test is wrong, stop, say why, and get agreement before changing it.
+- Never special-case test inputs in production code (hard-coded returns for the test's literal).
+- Before claiming done, `git diff` the test files; explain any change made during a green step.
+
+## Test quality
+
+- **Expected values from an outside source of truth** — a known literal, worked example, or the spec. Never recompute the expected value the way the code does.
+- **Behaviour, not structure.** A test that breaks under a behaviour-preserving refactor is coupled to internals; rewrite it at the seam.
+- **Mock only external boundaries** (network, clock, filesystem), and only when slow or stateful.
+- **Name like a spec**: "user can check out with an empty cart".
+- **Property tests for rules over many inputs** (parsers, round-trips, invariants) when the project already has a property library (fast-check, Hypothesis, proptest); otherwise a table of examples.
+- **Optional strength check:** if a mutation tool is already installed (Stryker, mutmut, cargo-mutants), run it on the changed module; surviving mutants point to missing assertions. Do not install one unasked. Manual alternative: break one line of the new code, confirm a test goes red, revert.
+
+Never claim a cycle green that you did not run.
 
-## Test quality rules
+## Scaling: one agent or several
 
-- **Expected values from an outside source of truth** — a known literal, a worked example, the spec. Never recompute the expected value the same way the code does; that test can only agree with itself and can never catch the bug.
-- **Behavior, not structure.** Assert on what the interface does. A test that breaks under a refactor with unchanged behavior is coupled to implementation — rewrite it at the seam, never patch it with mocks of internals.
-- **Real paths over mocks.** Exercise real code; mock only external boundaries (network, clock, filesystem) and only when they are slow or stateful.
-- **Named like a spec.** "user can check out with an empty cart" — the name alone states the capability.
+Main thread only — the loop is sequential by design. Never parallelise red/green steps or let a child edit tests.
 
-The loop inherits the verification gate: never claim a cycle green that you did not run.
+Sources (accessed 3 October 2026): https://code.claude.com/docs/en/best-practices (failing test before the fix); https://stryker-mutator.io/docs/ (killed vs surviving mutants); https://hypothesis.readthedocs.io/