@prestyj/cli 5.28.0 → 5.29.0

package/assets/skills/evidence-led-ui/references/direction.md

@@ -0,0 +1,124 @@
+# Picking a Direction
+
+## Contents
+
+1. Content first
+2. The thesis template
+3. Type
+4. Colour (OKLCH, measured)
+5. Spacing, density, radius
+6. Imagery
+7. Motion
+8. Platform features worth using (verified Baseline status)
+9. Responsiveness and INP practice
+
+Use for net-new UI, redesigns, or when the existing product leaves an axis free. If the project already has a system, preserve it and skip to § 8–9.
+
+## 1. Content first
+
+Before any layout:
+
+1. Write the real headline, primary action label, and the copy for every section, in the user's vocabulary.
+2. Gather or write realistic data: longest names, empty values, large numbers, 0/1/many items, localized strings.
+3. Rank it: what must be seen first, second, and what is the one action.
+4. Only then pick layout. If a section has nothing true to say, delete the section, do not design a container for it.
+
+Fixtures must be labelled as fixtures. Never invent proof (`references/anti-defaults.md` § 4).
+
+## 2. The thesis template
+
+Write this before code (in `DESIGN.md` for broad work, in notes otherwise). Max ~12 lines.
+
+```
+Subject + audience + single job:
+Signature (one memorable device, from the subject's world):
+Type: display / body / utility roles, families, scale ratio
+Colour: 4–6 named OKLCH tokens + intended contrast pairs
+Space/density: base unit, scale, density mode
+Radius + material: scale by role; surface model (flat / tonal / bordered / elevated)
+Imagery: source and treatment, or "none"
+Motion: the one orchestrated moment + feedback durations/easing
+Alignment: rail width, grid, left/center rule
+Rejected defaults: which slop tells this plan avoided and what replaced them
+```
+
+Then run the neighbour test from `references/anti-defaults.md` § 7 on the plan and revise once.
+
+## 3. Type
+
+- One family or two; if two, make them clearly different (e.g. a characterful display + a quiet text face, or a serif text + a grotesque UI face). Three only when a mono is needed for code.
+- Choose from the subject: technical precision, warmth, editorial authority, playfulness. Name the reason in the thesis.
+- Avoid Inter/Geist/system-ui as the identity of a marketing or brand surface. They remain fine for dense application chrome or when the project already uses them.
+- Scale: one ratio (e.g. 1.2 for dense apps, 1.25–1.333 for marketing) mapped to named tokens; no ad-hoc sizes.
+- Measure: body text under ~75 characters; serif body gets slightly more line-height.
+- Use `text-wrap: balance` on headings and `text-wrap: pretty` on paragraphs as progressive enhancement.
+- Tabular numerals (`font-variant-numeric: tabular-nums`) for columns of figures.
+- Loading and font candidates: `references/craft-rulings.md` § 5.
+
+## 4. Colour (OKLCH, measured)
+
+- Start from one brand hue derived from the subject or existing brand. Not violet/indigo by default.
+- Define tokens in `oklch()` (Baseline widely available). Build ramps by stepping lightness (L) at fixed hue; reduce chroma (C) near the light and dark ends so colours stay in gamut.
+- Neutrals: tint toward the brand hue with very low chroma (about 0.005–0.02) instead of stock `slate`/`zinc`.
+- Roles, not hues: `bg`, `surface`, `text`, `text-muted`, `border`, `accent`, `accent-contrast`, `focus`, `danger`, `success`. Components consume roles only.
+- Accent covers a small share of the screen; status colours are reserved for status.
+- Themes: `light-dark()` (Baseline newly available) or `prefers-color-scheme` tokens; tune dark neutrals separately rather than inverting.
+- Contrast is measured, not eyeballed. WCAG 2.2 AA: 4.5:1 normal text, 3:1 large text, 3:1 for UI component boundaries, icons, and focus indicators against adjacent colours. Compute ratios from the resolved sRGB values (browser devtools, axe, or a script) for every text/background pair in both themes and record them. OKLCH lightness is a design aid, not a WCAG measurement.
+- `color-mix()` (Baseline widely available) for hover/pressed derivations from tokens instead of new hard-coded values.
+
+## 5. Spacing, density, radius
+
+- One base unit (4 or 8 px) and a named scale; no off-scale values.
+- Density by task: data-dense tools use compact rows and small gaps; marketing uses generous section spacing. Do not mix densities within one view without reason.
+- Group with proximity first, then alignment, then borders, then fills. Shadows last and with one reason.
+- Radius scale by role (e.g. inputs and buttons share one, overlays another, avatars full). Never one radius for everything by reflex.
+- One shared content rail (`references/craft-rulings.md` § Shared content rails).
+
+## 6. Imagery
+
+Priority: real product UI at readable scale → real photography of the subject → real data visualised → typography alone. Generated or stock illustration only when requested. Every image needs dimensions (no layout shift), meaningful `alt` or empty `alt` if decorative, and responsive sources.
+
+## 7. Motion
+
+- One orchestrated moment per page at most (a load sequence or one reveal). Everything else is feedback to user action.
+- Feedback: about 100–200 ms for hover/press, about 200–300 ms for panels; ease-out for entering, ease-in for leaving. Use tokens.
+- Animate `transform` and `opacity`; name transitioned properties.
+- Every motion has a `prefers-reduced-motion` path that keeps meaning.
+- Auto-playing motion longer than 5 s needs pause/stop/hide (WCAG 2.2.2).
+
+## 8. Platform features worth using (verified Baseline status)
+
+Status from the `web-features` package v3.40.1 (published 1 Oct 2026), read 3 Oct 2026 (SNAPSHOT). Re-check on https://webstatus.dev before relying on newer items.
+
+| Feature | Baseline | Use by default? |
+| --- | --- | --- |
+| Container queries (size) | Widely available | Yes, for components that live in varying containers. |
+| `:has()` | Widely available | Yes, for parent/state styling instead of JS class toggling. |
+| `oklch()` / `oklab()`, `color-mix()` | Widely available | Yes, for tokens. |
+| `<dialog>`, `inert` | Widely available | Yes, for modals and disabling background regions. |
+| Subgrid | Widely available | Yes, for aligning card internals across a row. |
+| Popover API | Newly available (Jan 2025) | Yes for menus/tooltips/popovers, with tested focus behaviour. |
+| `text-wrap: balance` | Newly available | Yes on headings (harmless fallback). |
+| `light-dark()` | Newly available | Yes when the project supports themes. |
+| `@starting-style` | Newly available | Yes for entry transitions; content must work without it. |
+| Same-document view transitions | Newly available (Oct 2025) | Yes as progressive enhancement with reduced-motion opt-out. |
+| `details name` (exclusive accordions) | Newly available | Yes for simple accordions. |
+| `field-sizing: content` | Newly available (Jun 2026) | Progressive enhancement for auto-growing textareas; keep a min/max size. |
+| `text-wrap: pretty` | Not Baseline | Progressive enhancement only. |
+| CSS anchor positioning | Not Baseline (Interop 2026 focus area) | Enhancement with a fallback position, or use the project's positioning library. |
+| Scroll-driven animations | Not Baseline (Interop 2026 focus area) | Decorative enhancement only; never required for content. |
+| Cross-document view transitions | Not Baseline (Interop 2026 focus area) | Enhancement only. |
+| `interpolate-size` | Not Baseline | Enhancement only. |
+
+"Newly available" means supported in current versions of all core browsers but not yet for 30 months; check the project's support policy before relying on it without a fallback.
+
+## 9. Responsiveness and INP practice
+
+Interaction to Next Paint (INP) is the Core Web Vital for responsiveness; "good" is 200 ms or less at the 75th percentile (web.dev, SNAPSHOT).
+
+- Paint feedback first: update the pressed/pending state synchronously, then do heavy work after yielding (`await scheduler.yield()` where supported, otherwise `setTimeout`/`requestAnimationFrame` fallback).
+- Keep event handlers small; debounce typing-driven filtering; virtualize long lists; avoid layout thrash (read then write).
+- Prefer CSS state (`:has()`, `:focus-visible`, popover, `<details>`) over JS-driven re-renders for simple UI state.
+- Use `content-visibility: auto` for long offscreen sections when it does not break find-in-page or anchors in the target browsers.
+- Reserve space for images, ads, embeds, and async content to avoid layout shift.
+- Report measurements as RUNTIME only when measured; otherwise say unmeasured.

package/assets/skills/evidence-led-ui/references/production-contract.md

@@ -30,6 +30,13 @@ WCAG 2.2 Level AA is the default technical floor for web UI. Conformance means e
 
 ADA is a civil-rights and equal-access obligation, not a technical certification. WCAG 2.2 Level AA is the engineering baseline, but meeting it does not by itself establish full ADA compliance. When ADA applies, verify the current Title II or Title III obligations, scope, exceptions, effective-communication duties, and alternative arrangements with the responsible product or legal owner. Never claim `ADA compliant` or `WCAG conformant` without evidence for a defined scope.
 
+Dated legal and standards context (SNAPSHOT 3 Oct 2026, sources in `references/provenance.md`; re-check before citing to a user):
+
+- WCAG 2.2 is the current W3C Recommendation. WCAG 3.0 is still a Working Draft (latest 10 Sep 2026): do not target or claim it.
+- US ADA Title II web rule (state and local government): technical standard WCAG 2.1 AA. An April 2026 DOJ interim final rule moved compliance dates to 26 April 2027 (population 50,000+) and 26 April 2028 (smaller entities and special districts); substance unchanged. Private-sector (Title III) has no adopted technical standard; the equal-access duty still applies.
+- EU European Accessibility Act: applies since 28 June 2025 to covered products and services (including e-commerce and consumer banking) placed on the EU market. The harmonised technical standard is expected to be EN 301 549 (WCAG-based); confirm the version the applicable national law references.
+- Meeting WCAG 2.2 AA covers the WCAG 2.1 AA criteria these regimes reference. Applicability, exemptions, and legal claims belong to the product or legal owner; this skill never makes them.
+
 - Define the conformance scope before broad implementation: routes/screens, complete user processes, content types, components and states, supported technologies, and the browser, device, input, and assistive-technology matrix. Audit against the current official [WCAG 2.2 Quick Reference](https://www.w3.org/WAI/WCAG22/quickref/), criterion by criterion; this summary is not a substitute. Track every applicable Level A and AA criterion as pass, fail, or not applicable with a rationale and evidence.
 - Satisfy all five WCAG conformance requirements: the claimed level, full pages, every page in each complete process, only accessibility-supported uses of technology, and non-interference from any non-conforming content. One unresolved applicable failure blocks conformance.
 - Use native semantics and controls first. Supply meaningful text alternatives for informative images, controls, and graphics; mark decoration as decorative. Preserve programmatic information and relationships, headings, landmarks, lists, tables, meaningful sequence, page and passage language, reading order, and a bypass route for repeated blocks.
@@ -83,6 +90,7 @@ For web surfaces, use current Core Web Vitals as the shared target at the 75th p
 ## 6. Modern platform features and progressive enhancement
 
 - Set a browser and device support policy from project evidence. Prefer features in the project's Baseline/support range; use feature detection and a simpler fallback for newer capabilities.
+- Verified Baseline status for common modern features is in `references/direction.md` § 8. Do not state a feature's support status from memory.
 - Use native `dialog`, Popover, `inert`, constraint validation, and other platform primitives when their semantics match the job and the support policy allows them. Do not choose a new API merely because it is fashionable.
 - Treat View Transitions and similar enhancements as optional continuity layers. Navigation and state changes must still work without them and under reduced motion.
 - Preserve the essential task when scripts, media, fonts, animation, clipboard access, or a preferred input mode are unavailable whenever progressive enhancement is feasible for the product.

package/assets/skills/evidence-led-ui/references/provenance.md

@@ -9,6 +9,7 @@
 - Production-practice research
 - Design-process references
 - Skill-architecture research
+- Q4 2026 refresh (3 October 2026): slop tells, platform status, legal dates
 - Refresh policy
 
 ## Included corpus
@@ -47,7 +48,7 @@ Therefore this skill must not bulk-scrape Refero, call undocumented Refero endpo
 - **Web conformance floor:** [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/), W3C Recommendation dated 12 December 2024 in the current publication fetched 2026-07-21. The [W3C WCAG overview](https://www.w3.org/WAI/standards-guidelines/wcag/) encourages the latest version and states that WCAG 2.2 conformance is backward compatible with WCAG 2.1 and 2.0.
 - **Native application guidance:** [WCAG2ICT](https://www.w3.org/TR/wcag2ict-22/) explains how Level A and AA criteria apply to non-web software. It is informative guidance, not a normative standard, and native work still needs platform and product-specific accessibility requirements.
 - **U.S. ADA context:** The Department of Justice [ADA web accessibility guidance](https://www.ada.gov/resources/web-guidance/) explains equal access and effective communication under Titles II and III. The current [Title II web and mobile app rule fact sheet](https://www.ada.gov/resources/2024-03-08-web-rule/) names WCAG 2.1 Level AA as its technical standard and documents scope, exceptions, and compliance timing. These sources were checked 2026-07-21.
-- **Not the conformance target:** [W3C Accessibility Guidelines (WCAG) 3.0](https://www.w3.org/TR/wcag-3.0/) is a W3C Working Draft dated 3 March 2026. W3C says publication as a Working Draft does not imply endorsement and that it is inappropriate to cite as anything other than work in progress.
+- **Not the conformance target:** [W3C Accessibility Guidelines (WCAG) 3.0](https://www.w3.org/TR/wcag-3.0/) is a W3C Working Draft (dated 10 September 2026 when re-checked 3 October 2026). W3C says publication as a Working Draft does not imply endorsement and that it is inappropriate to cite as anything other than work in progress.
 
 WCAG 2.2 Level AA is the default engineering floor because it includes and extends WCAG 2.1, but technical WCAG conformance alone does not prove compliance with the ADA or another law. Project, procurement, contractual, platform, and jurisdictional requirements may exceed this floor. Use the current official standard and obtain qualified product or legal review before making a legal-compliance claim.
 
@@ -105,6 +106,28 @@ The package structure was checked against the [Agent Skills specification](https
 
 `SKILL.md` remains below the recommended 500-line limit. Reference files over 100 lines include a contents overview so an agent preview exposes the file's scope. Detailed corpus data stays out of runtime context unless a specific claim requires it. The existing external A/B artifacts are unscored and predate the current contracts, so they are benchmark inputs rather than evidence that the current skill improves quality.
 
+## Q4 2026 refresh (3 October 2026)
+
+All accessed 3 October 2026 (SNAPSHOT).
+
+### Slop-tell sources
+
+- [Anthropic `frontend-design` SKILL.md](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md) (last changed 3 Sep 2026): named default clusters (cream/serif/terracotta, near-black + single accent, broadsheet, SaaS card kit, template chrome), single-word headline accents, all-caps labels, numbered markers on non-sequences, scattered fade-up entrances, plan-then-review-against-brief process, outcome-named CTAs. Paraphrased, not bundled.
+- [Vercel Web Interface Guidelines](https://github.com/vercel-labs/web-interface-guidelines): no `transition: all`, compositor-friendly motion, reduced motion, focus-visible, hit targets, links are links, loading-state timing, ellipsis conventions.
+- The tells table in `references/anti-defaults.md` merges these with the earlier synthesis; the clusters are DEDUCED, not measured.
+
+### Platform status
+
+- Baseline statuses in `references/direction.md` § 8 read from the [`web-features`](https://www.npmjs.com/package/web-features) package v3.40.1 (published 1 Oct 2026), the data behind [webstatus.dev](https://webstatus.dev).
+- [Interop 2026 focus areas](https://github.com/web-platform-tests/interop/blob/main/2026/README.md) and [WebKit's announcement](https://webkit.org/blog/17818/announcing-interop-2026/): anchor positioning, scroll-driven animations, view transitions, dialogs and popovers, container style queries, among others.
+- [WCAG 2.2](https://www.w3.org/TR/WCAG22/) Recommendation 12 Dec 2024; [WCAG 3.0](https://www.w3.org/TR/wcag-3.0/) Working Draft 10 Sep 2026.
+- [web.dev INP](https://web.dev/articles/inp): good at 200 ms or less, 75th percentile.
+
+### Legal dates
+
+- ADA Title II: DOJ interim final rule published 20 April 2026 (91 Fed. Reg. 20902) extends compliance to 26 April 2027 / 26 April 2028; WCAG 2.1 AA unchanged. Secondary confirmations: [Reed Smith](https://www.reedsmith.com/articles/doj-extends-digital-accessibility-compliance-dates-under-title-ii-of-the-ada/), [Seyfarth](https://www.adatitleiii.com/2026/04/doj-extends-ada-title-ii-website-accessibility-deadlines-for-governmental-entities-but-litigation-and-compliance-risks-remain/). Primary: [ada.gov web rule](https://www.ada.gov/resources/2024-03-08-web-rule/).
+- European Accessibility Act (Directive (EU) 2019/882): applies from 28 June 2025; [European Commission EAA page](https://commission.europa.eu/strategy-and-policy/policies/justice-and-fundamental-rights/disability/union-equality-strategy-rights-persons-disabilities-2021-2030/european-accessibility-act_en).
+
 ## Refresh policy
 
 A corpus refresh must be explicit:

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.