devrites 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to DevRites are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and DevRites adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Releases are generated automatically by [semantic-release](https://semantic-release.gitbook.io/) from Conventional Commits on `main`.
 
+## [2.1.0](https://github.com/ViktorsBaikers/DevRites/compare/v2.0.0...v2.1.0) (2026-06-23)
+
+### Added
+
+* **agents:** perf reviewer gets Source/Measured CWV modes ([be82b20](https://github.com/ViktorsBaikers/DevRites/commit/be82b20b37252a9f55d77e0f71659ec58a213ca6))
+
 ## [2.0.0](https://github.com/ViktorsBaikers/DevRites/compare/v1.18.0...v2.0.0) (2026-06-23)
 
 ### ⚠ BREAKING CHANGES

package/README.md

@@ -94,7 +94,7 @@ Full diagram set (lifecycle, polish orchestrator, review fan-out, debug loop,
 rules carrier, workspace state, namespace map) →
 [`docs/flow.md`](docs/flow.md).
 
-**Status:** [`v2.0.0`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v2.0.0) — see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
+**Status:** [`v2.1.0`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v2.1.0) — see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
 
 ## Contents
 

package/pack/.claude/agents/devrites-performance-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: devrites-performance-reviewer
-description: Fresh-context, measure-first performance reviewer for /rite-seal. Use to independently review a DevRites feature diff for N+1s, hot-path work, payload/bundle size, and Core Web Vitals risks. Won't claim a slowdown without a number or a measurement to take.
+description: Fresh-context, measure-first performance reviewer for /rite-seal. Use to independently review a DevRites feature diff for N+1s, hot-path work, payload/bundle size, and Core Web Vitals risks. Runs in Source mode (static scan, findings tagged potential) or Measured mode (judges real Lighthouse/PSI/CrUX/trace numbers and leads with a source-labeled CWV scorecard). Won't claim a slowdown without a number or a measurement to take, and never presents lab data as field data.
 tools: Read, Grep, Glob, Bash
 hooks:
   PreToolUse:
@@ -17,19 +17,50 @@ You are measure-first: no performance claim without a number or a specified meas
 
 ## Inputs
 Workspace `.devrites/work/<slug>/`: read `spec.md` (any perf budget), `evidence.md`,
-`touched-files.md`. Run `git diff` and read the touched files.
+`touched-files.md`. Run `git diff` and read the touched files. Also look for Core Web
+Vitals artifacts — numbers already in `evidence.md`, a Lighthouse / PageSpeed Insights /
+CrUX JSON path the builder left, or a browser-proof capture in `browser-evidence.md`.
+
+Read the baseline checklist on demand (resolve the path like the readonly hook):
+```
+C=.claude/skills/rite-review/reference/performance-checklist.md
+[ -f "$C" ] || C="$CLAUDE_PLUGIN_ROOT/pack/.claude/skills/rite-review/reference/performance-checklist.md"
+[ -f "$C" ] || C=pack/.claude/skills/rite-review/reference/performance-checklist.md
+```
+
+## Two modes (the inputs set the mode, not a flag)
+- **Source mode** — default, no perf artifacts present. Scan the diff statically for
+  structural anti-patterns. Every frontend finding is **potential impact**, never a
+  measurement; name the command that would confirm it. Emit **no scorecard**.
+- **Measured mode** — a CWV artifact or a real number exists. Judge it against the
+  `spec.md` budget or the pre-change baseline, and lead with the scorecard.
+
+Source mode is the same discipline as the old "specify the measurement" — it just names
+the contract for when the scorecard appears.
 
 ## Review (feature scope)
-- **Backend** — N+1 queries, missing indexes on new queries, unbounded result sets,
-  per-request work that should be cached/batched, blocking sync work.
-- **Frontend (Core Web Vitals)** — LCP (oversized images, render-blocking work), CLS
-  (layout shift), INP (interaction latency), bundle growth, unnecessary re-renders.
+- **Backend** (always, every feature) — N+1 queries, missing indexes on new queries,
+  unbounded result sets, per-request work that should be cached/batched, blocking sync
+  work. *AI-codegen smell:* over-fetching "just in case", sequential `await`s where
+  `Promise.all` fits, redundant calls a dedup would collapse.
+- **Frontend (Core Web Vitals)** — only when the feature is UI-facing. Identify the
+  framework and rendering model first (React / Vue / Svelte / Angular / Next / Astro /
+  vanilla) and apply only that stack's idioms — don't recommend `next/image` to a Vue app
+  or `React.memo` to Svelte. Check LCP (oversized images, render-blocking work, missing
+  `fetchpriority`), CLS (layout shift, missing image dimensions), INP (long tasks, heavy
+  event handlers), bundle growth, unnecessary re-renders. *AI-codegen smell:* `memo` /
+  `useMemo` / `useCallback` wrapping everything, over-eager effect deps, broad watchers.
 - **General** — accidental quadratic loops, repeated hot-path work, large allocations.
 
 ## Measure-first discipline
-- If a real number exists in `evidence.md`, judge it against the budget/baseline.
+- If a real number exists, judge it against the budget/baseline; state the before/after.
 - If not, **specify the measurement** (command, scenario, metric) instead of asserting a
   regression. Distinguish "measured regression" from "likely hot spot, verify with X".
+- **Source-honesty.** Label every measured CWV value with where it came from —
+  `Field (CrUX)` (real users, p75), `Lab (Lighthouse)` (one synthetic run), or
+  `Trace (DevTools)`. Field and lab are not interchangeable; presenting one as the other
+  is fabrication. Reading static source cannot measure LCP / INP / CLS — never invent a
+  number for a value you did not capture.
 
 ## Rules
 - Don't edit. Findings only, labeled Critical / Important / Suggestion / Nit / FYI with
@@ -37,9 +68,26 @@ Workspace `.devrites/work/<slug>/`: read `spec.md` (any perf budget), `evidence.
   micro-opt with no measured impact is a Suggestion at most. Feature scope only.
 
 ## Output
+
+**Measured mode** — lead with a compact scorecard, then the line findings:
+```
+Performance review (<slug>) — independent
+Scorecard (source-labeled):
+  LCP <value>  <Field(CrUX) | Lab(LH) | Trace>  <Good/Needs Work/Poor>  (target ≤2.5s)
+  INP <value>  <source>                          <status>               (target ≤200ms)
+  CLS <value>  <source>                          <status>               (target ≤0.1)
+  [Lighthouse perf <score> Lab(LH)]  Artifacts: <which>  Stack: <detected>
+[Critical]/[Important] file:line — issue. measured: <number>. direction.
+[Suggestion]/[Nit]/[FYI] ...
+Budget: <breached? | none stated>
+Verdict: <blockers? none/list>
+```
+
+**Source mode** — no artifacts; one scorecard line, findings tagged `potential`:
 ```
 Performance review (<slug>) — independent
-[Important] file:line — issue. measured: <number | "measure: <cmd/metric>">. direction.
+Scorecard: not measured (Source mode)
+[Important] file:line — issue. potential; verify: <cmd/metric>. direction.
 [Suggestion]/[Nit]/[FYI] ...
 Budget: <breached? | none stated>
 To prove any win: <measure X before/after>

package/pack/.claude/rules/performance.md

@@ -21,6 +21,15 @@ Measure first. An optimization without a measurement is a guess that adds comple
 - Don't trade correctness or readability for a micro-win that doesn't matter.
 - Prefer a better algorithm or query over micro-tuning; the big wins are structural.
 
+## Frontend — Core Web Vitals
+For UI work, measure-first means LCP / INP / CLS judged against real numbers, each labeled
+by source (`Field (CrUX)`, `Lab (Lighthouse)`, `Trace (DevTools)`) — field and lab are not
+interchangeable, and static source cannot measure a CWV. The reviewer captures these via the
+browser-proof ladder when a budget exists, then judges them in Measured mode (a
+source-labeled scorecard); with no artifact it runs in Source mode and names the command.
+Baseline checks + measurement commands:
+[`rite-review/reference/performance-checklist.md`](../skills/rite-review/reference/performance-checklist.md).
+
 ## Scope
 Optimize what the change touches or what a measurement flags. Project-wide performance
 work is its own effort — record it as a follow-up, don't smuggle it into an unrelated

package/pack/.claude/skills/devrites-browser-proof/SKILL.md

@@ -22,12 +22,32 @@ of the ladder that's available; record which one.
    the project's existing commands. Don't add a new framework.
 5. **Manual fallback** — none available: record the limitation + exact manual steps.
 
+## Core Web Vitals capture (when the spec states a perf budget)
+If `spec.md` carries a perf budget — or a frontend regression risk is visible — capture the
+CWV numbers here so the perf reviewer judges real data instead of guessing. Use the highest
+rung available; **detect, don't install**.
+
+1. **Chrome DevTools MCP** (if configured) — `lighthouse_audit` for LCP/INP/CLS + the
+   Lighthouse performance score. Source label: **Lab (Lighthouse)**. A `performance_*` trace
+   gives **Trace (DevTools)** attribution.
+2. **browser-harness** — drive the route, capture a performance trace over CDP. Source
+   label: **Trace (DevTools)**.
+3. **CrUX / PageSpeed Insights** — only if the user supplied an API key. Field data, p75.
+   Source label: **Field (CrUX)**.
+4. **None available** → mark CWV **pending (manual)** and name the exact command
+   (`npx lighthouse <url> --output json …`). Don't install anything; don't fake a number.
+
+Write each captured value **with its source label** to `evidence.md` (so the perf reviewer
+reads it in Measured mode) and note the tool + route in `browser-evidence.md`. Never present
+a lab value as a field value or vice versa.
+
 ## Evidence schema → `browser-evidence.md`
 Tooling used · route(s) · viewports (375/768/1280) · screenshot paths **opened and
 described** · console errors/warnings · network failures · interaction path tested ·
-accessibility basics · responsive checks · **design-reference match** (if the spec saved
-references in `references/`, compare the built UI to them and note match/diffs) ·
-limitations.
+accessibility basics · responsive checks · **CWV capture** (tool + route + each
+source-labeled value, or `pending (manual)` + the command) · **design-reference match** (if
+the spec saved references in `references/`, compare the built UI to them and note
+match/diffs) · limitations.
 
 ## Hard rules
 - A screenshot **path is not proof** — open it and describe what's visible.

package/pack/.claude/skills/rite-review/reference/performance-checklist.md

@@ -0,0 +1,80 @@
+# Performance checklist (baseline for the perf reviewer)
+
+The minimum baseline `devrites-performance-reviewer` checks against, in feature scope. It
+is a checklist, not a mandate: flag what the diff actually touches or what a measurement
+flags, never a project-wide sweep. The philosophy lives in
+[`rules/performance.md`](../../../rules/performance.md) (measure first) — this file is the
+concrete what-to-look-for.
+
+## Core Web Vitals targets
+
+| Metric | Good | Needs work | Poor |
+|---|---|---|---|
+| LCP — Largest Contentful Paint | ≤ 2.5s | ≤ 4.0s | > 4.0s |
+| INP — Interaction to Next Paint | ≤ 200ms | ≤ 500ms | > 500ms |
+| CLS — Cumulative Layout Shift | ≤ 0.1 | ≤ 0.25 | > 0.25 |
+
+A CWV value only counts when it carries a source — `Field (CrUX)`, `Lab (Lighthouse)`, or
+`Trace (DevTools)`. No source → it's a Source-mode hypothesis, not a measurement.
+
+## Frontend (only when the feature is UI-facing)
+
+Identify the framework first; apply only its idioms.
+
+- **Images** — modern format (WebP/AVIF); responsive `srcset`/`sizes`; explicit
+  `width`/`height` to reserve space (CLS); below-the-fold `loading="lazy"`; the LCP image
+  gets `fetchpriority="high"` and is **not** lazy-loaded.
+- **JavaScript** — initial bundle stays small (≈200KB gzipped is the usual line); code-split
+  routes and heavy features; no blocking script in `<head>` without `defer`/`async`; break
+  long tasks (>50ms) so the main thread stays free (the main INP lever); `memo`/`useMemo`/
+  `useCallback` only where profiling shows a win, not wrapped over everything.
+- **CSS** — critical CSS not render-blocking; no per-render CSS-in-JS runtime cost in prod.
+- **Fonts** — 2–3 families max; WOFF2; self-hosted where possible; preload the LCP font;
+  `font-display: swap`; subset with `unicode-range`.
+- **Rendering** — no layout thrashing (batch reads, then writes); animate `transform`/
+  `opacity` only; virtualize long lists; `content-visibility: auto` for off-screen sections;
+  don't break bfcache (no `unload` handler, no `Cache-Control: no-store` on HTML).
+
+## Backend (every feature, UI or not)
+
+- No N+1 queries; eager-load / join / batch instead.
+- New queries have the indexes they need for their filter/sort columns.
+- List endpoints paginate — never an unbounded `SELECT *`.
+- Per-request work that doesn't change per call is cached or hoisted.
+- Responses compressed (gzip/brotli); bulk operations instead of a loop of single calls.
+
+## Network
+
+- Static assets cached with a long `max-age` + content hashing.
+- Known origins `preconnect`-ed; no unnecessary redirects; HTTP/2 or HTTP/3 where available.
+
+## AI-codegen perf smells (fold into the area above, not a separate finding category)
+
+- State duplicated instead of lifted; effects with over-broad deps that re-run needlessly.
+- Sequential `await`s where `Promise.all` / parallel fetch fits.
+- Over-fetching "just in case"; redundant calls a dedup would collapse.
+- Defensive memoization wrapping cheap components — cost with no benefit.
+
+## Modern APIs to consider (one-liners — reach for these, don't gate on them)
+
+`scheduler.yield()` to keep input responsive in long loops · Speculation Rules for
+prefetch/prerender · View Transitions on SPA navigation · Long Animation Frames (LoAF) for
+production INP attribution · `fetchpriority` on critical non-image resources.
+
+## Measurement commands (name these in Source mode; don't run installs in review)
+
+```bash
+# Lighthouse (lab)
+npx lighthouse <url> --output json --output-path ./report.json
+# or via the Chrome DevTools MCP CLI, no install:
+npx -p chrome-devtools-mcp chrome-devtools lighthouse_audit --output-format=json > report.json
+
+# Bundle size
+npx vite-bundle-visualizer        # Vite
+npx webpack-bundle-analyzer stats.json   # webpack
+
+# Field data: CrUX / PageSpeed Insights (real users, p75) — needs an API key
+```
+
+Field is what real users experienced; lab is one synthetic run. Don't present one as the
+other.

package/pack/.claude/skills/rite-review/reference/performance-review.md

@@ -17,6 +17,10 @@ a hunch.
   unnecessary re-renders.
 - **General**: accidental quadratic loops, repeated work in hot paths, large allocations.
 
+The agent runs **Source mode** (static scan, findings tagged `potential` + the verify
+command) or **Measured mode** (real CWV numbers → a source-labeled scorecard). Baseline
+checks + measurement commands: [`performance-checklist.md`](performance-checklist.md).
+
 ## Optimize responsibly
 - Fix the measured bottleneck, then **re-measure** to prove the win (before/after in
   `evidence.md`). An optimization with no measured improvement is just added complexity.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devrites",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "DevRites — disciplined senior-engineer workflow skills pack for Claude Code",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://github.com/ViktorsBaikers/DevRites#readme",