clud-bug 0.7.0-rc.2 → 0.7.0-rc.21

package/src/core/review-writeback.ts

@@ -46,6 +46,34 @@ export const SEVERITY_EMOJI = {
   preexisting: '\u{1F7E3}', // U+1F7E3 PURPLE CIRCLE
 } as const;
 
+/**
+ * One parsed finding suitable for the SPEC §1.8.1 Resolved / Still-open
+ * blocks. Mirrors `ParsedFinding` from `./diff-findings.ts`; declared
+ * here as a structural interface (not re-imported) so callers without
+ * `diff-findings` in scope can still construct the input.
+ */
+export interface RenderedFindingRef {
+  file: string;
+  line: number;
+  severity: 'critical' | 'minor' | 'preexisting';
+  skillName: string;
+  summary: string;
+}
+
+/**
+ * SPEC §6.7.3 cache telemetry — per-invocation token counts from the
+ * Anthropic-family `usage` block. When present, the renderer emits a
+ * `<!-- cache: ... -->` HTML comment immediately below the
+ * `<!-- review-sha: ... -->` metadata line so downstream cost analysis
+ * tooling can audit cache behaviour from the committed doc-file.
+ */
+export interface CacheStats {
+  /** `cache_read_input_tokens` from the Anthropic usage block. */
+  cachedInputTokens: number;
+  /** `cache_creation_input_tokens` from the Anthropic usage block. */
+  cacheCreationInputTokens: number;
+}
+
 export interface RenderReviewFileInput {
   review: Review;
   prNumber: number;
@@ -53,6 +81,34 @@ export interface RenderReviewFileInput {
   headSha: string;
   /** GitHub PR URL — appended verbatim to the trailing rule. */
   prUrl: string;
+  /**
+   * Findings present in the prior `docs/reviews/PR-<n>.md` that are NOT
+   * present in this round's `review`. When non-empty, emits the SPEC
+   * §1.8.1 `**Resolved this round:**` block AFTER the severity buckets
+   * and BEFORE the trailing `---` separator. Omitted entirely when
+   * empty/undefined (SPEC §1.8.1: blocks MUST be omitted when empty).
+   *
+   * Produced by `diffFindings()` from `./diff-findings.ts`.
+   */
+  resolvedFindings?: RenderedFindingRef[];
+  /**
+   * Findings present in BOTH the prior `docs/reviews/PR-<n>.md` AND
+   * this round's `review` — the persistent ones. When non-empty, emits
+   * the SPEC §1.8.1 `**Still open:**` block AFTER `**Resolved this
+   * round:**` and before the trailing `---` separator. Omitted entirely
+   * when empty/undefined.
+   *
+   * Produced by `diffFindings()` from `./diff-findings.ts`.
+   */
+  stillOpenFindings?: RenderedFindingRef[];
+  /**
+   * SPEC §6.7.3 cache telemetry. When present, emits a
+   * `<!-- cache: <read> read · <created> created -->` HTML comment
+   * immediately below the `<!-- review-sha: ... -->` metadata line.
+   * Omitted entirely when undefined (this comment is OPTIONAL per the
+   * SPEC, but SHOULD be implemented for cost-analysis tooling).
+   */
+  cacheStats?: CacheStats;
 }
 
 /**
@@ -66,7 +122,15 @@ export interface RenderReviewFileInput {
  * the underlying finding data but differ in container.
  */
 export function renderReviewFile(input: RenderReviewFileInput): string {
-  const { review, prNumber, headSha, prUrl } = input;
+  const {
+    review,
+    prNumber,
+    headSha,
+    prUrl,
+    resolvedFindings,
+    stillOpenFindings,
+    cacheStats,
+  } = input;
   // Wire-shape Review carries findings in 3 severity arrays. Flatten to
   // internal `Finding[]` so the renderer's bucketing, count-derivation,
   // and per-skill aggregation can work uniformly.
@@ -83,6 +147,15 @@ export function renderReviewFile(input: RenderReviewFileInput): string {
   lines.push(`<!-- protocol-version: ${PROTOCOL_VERSION} -->`);
   lines.push(`<!-- written-by: ${WRITTEN_BY} -->`);
   lines.push(`<!-- review-sha: ${headSha} -->`);
+  // SPEC §6.7.3: cache telemetry comment goes immediately below the
+  // review-sha so a single grep can pull review-sha + cache stats out
+  // of a doc-file without re-parsing the whole block. Omitted entirely
+  // when cacheStats is undefined.
+  if (cacheStats !== undefined) {
+    lines.push(
+      `<!-- cache: ${cacheStats.cachedInputTokens} read · ${cacheStats.cacheCreationInputTokens} created -->`,
+    );
+  }
   lines.push('');
 
   // Summary line — SPEC §1.8.1 wording.
@@ -124,9 +197,31 @@ export function renderReviewFile(input: RenderReviewFileInput): string {
     lines.push('');
   }
 
-  // D.2.0 never emits "Resolved this round" / "Still open" — both lists
-  // are empty until D.2.5 (multi-pass tracking). SPEC §1.8.1 says these
-  // blocks MUST be omitted when empty.
+  // SPEC §1.8.1 Resolved this round / Still open blocks. Omitted
+  // entirely when the corresponding input list is empty/undefined.
+  //
+  // Bullet shape (one finding per line):
+  //   - `path/file.ts:42` — `critical-issues-only`: null-deref ... (was 🔴 Critical)
+  //
+  // The `(was <emoji> <Severity>)` suffix carries the SEVERITY at the
+  // time the finding was last seen so a downgrade across rounds is
+  // visible without diffing the two doc files. Note: backticks around
+  // file and skill render in markdown viewers as inline-code, which
+  // makes the file path scannable in the GitHub UI.
+  if (resolvedFindings !== undefined && resolvedFindings.length > 0) {
+    lines.push('**Resolved this round:**');
+    for (const f of resolvedFindings) {
+      lines.push(renderDiffFinding(f));
+    }
+    lines.push('');
+  }
+  if (stillOpenFindings !== undefined && stillOpenFindings.length > 0) {
+    lines.push('**Still open:**');
+    for (const f of stillOpenFindings) {
+      lines.push(renderDiffFinding(f));
+    }
+    lines.push('');
+  }
 
   lines.push('---');
   lines.push('');
@@ -148,6 +243,30 @@ function bucketBySeverity(findings: Finding[]): Record<
   };
 }
 
+/**
+ * Renders one finding for the SPEC §1.8.1 Resolved / Still-open blocks.
+ * Output shape:
+ *
+ *   - `path/file.ts:42` — `critical-issues-only`: null-deref ... (was 🔴 Critical)
+ *
+ * Line `0` is treated as "no anchor" (cross-cutting / missing) and the
+ * `:N` suffix is omitted. The severity label uses the SPEC §1.8.1
+ * emoji + label so a reader can see at a glance whether the finding
+ * was downgraded (different severity in current round) or merely
+ * resolved.
+ */
+function renderDiffFinding(f: RenderedFindingRef): string {
+  const location = f.line > 0 ? `${f.file}:${f.line}` : f.file;
+  const label =
+    f.severity === 'critical'
+      ? 'Critical'
+      : f.severity === 'minor'
+        ? 'Minor'
+        : 'Preexisting';
+  const emoji = SEVERITY_EMOJI[f.severity];
+  return `- \`${location}\` — \`${f.skillName}\`: ${f.summary} (was ${emoji} ${label})`;
+}
+
 function renderFinding(f: Finding, includeReasoning: boolean): string {
   // findingItemSchema.file is z.string().optional() — the model is
   // instructed to always provide it, but Zod doesn't enforce. Without
@@ -199,9 +318,30 @@ export interface PassAttribution {
   note?: string;
 }
 
+/**
+ * SPEC §6.10.1 consensus marker, derived from a finding's per-pass attributions
+ * by the aggregator's `deriveConsensus`. Defined here — the canonical home of
+ * the unified-finding shape — so it rides on `MultiPassReview.findings`.
+ *
+ * - `1-of-N` — single pass produced this finding; no consensus reached.
+ *   §6.10.2 MUST NOT fire auto-fix on these.
+ * - `2-of-2` — two passes independently produced an equivalent finding.
+ *   Qualifies for auto-fix per §6.10.2.
+ * - `arbitrated` — passes disagreed; an arbiter resolved the dispute. Today's
+ *   cross-check shape treats `arbitrated` as NOT-qualifying (conservative).
+ */
+export type Consensus = '1-of-N' | '2-of-2' | 'arbitrated';
+
 export interface UnifiedFinding extends Finding {
   /** One PassAttribution per pass involved with this finding. Order: by passNumber. */
   attributions: PassAttribution[];
+  /**
+   * SPEC §6.10.1 consensus verdict. Stamped by the aggregator's `finalize()`
+   * from `deriveConsensus(attributions)`. Optional: single-pass / non-aggregated
+   * findings omit it; consumers treat absence as '1-of-N' (the auto-fix gate
+   * default — see clud-bug-app/lib/auto-fix-policy.ts).
+   */
+  consensus?: Consensus;
 }
 
 /** Effective resolution verdict the multi-pass orchestrator emits. */
@@ -381,6 +521,15 @@ function renderUnifiedFinding(
   }
   const headLabel = formatAttributionLabel(head);
   const lines: string[] = [];
+  // SPEC §6.8.1 (NORMATIVE for multi-pass): a per-finding pass-attribution HTML
+  // comment immediately preceding the bullet, naming the originating pass as a
+  // stable lowercase identifier so consumers can aggregate per-pass metrics.
+  lines.push(`<!-- pass: ${passIdentifier(head.roleName)} -->`);
+  // SPEC §6.10.1 (NORMATIVE for gated reviewers): the consensus marker alongside
+  // the pass attribution, when the finding carries a consensus verdict.
+  if (f.consensus) {
+    lines.push(`<!-- consensus: ${f.consensus} -->`);
+  }
   lines.push(`- ${headLabel} **${location}** — ${f.skill}: ${f.summary}`);
   if (includeReasoning && f.reasoning) {
     lines.push(`  Reasoning: ${f.reasoning}`);
@@ -403,6 +552,14 @@ function renderUnifiedFinding(
  * `source: 'first'` — i.e. when a later pass surfaced this finding without
  * Pass 1 raising it.
  */
+/** SPEC §6.8.1 pass identifier: a stable lowercase slug of the role name. */
+function passIdentifier(roleName: string): string {
+  return roleName
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
 function formatAttributionLabel(a: PassAttribution): string {
   const independent =
     a.source === 'independent' && a.passNumber > 1

package/src/core/skills.ts

@@ -285,6 +285,60 @@ export function appliesToPr(skillContent: unknown, prPaths: unknown): boolean {
   return false;
 }
 
+// v0.7.0-rc.6 (SPEC §1.10.1 v0.5.1+) — does this skill apply to a PR
+// opened by `prAuthor`? Reads `applies_to.author` from the raw SKILL.md
+// frontmatter. Returns:
+//   - `true` if `applies_to.author` is absent (no author filter set —
+//     skill loads regardless of author; v0.5.0 backward-compat default).
+//   - `true` if `applies_to.author === prAuthor` (case-sensitive match
+//     against the PR author's GitHub login).
+//   - `false` if `applies_to.author` is set to a different login.
+//
+// Designed to mirror `appliesToPr`'s signature (raw skill content +
+// runtime PR context) so consumers can call both filters in a single
+// loader pass. Skills with NO `applies_to` block at all also return
+// `true` (the existing v0.5.0 unconditional-load behavior).
+//
+// Strict-AND composition per SPEC §1.10.1: when a skill sets BOTH
+// `applies_to.author` AND `paths`/`extensions`, callers MUST call BOTH
+// filters and AND the results. This helper only checks the author leg;
+// the caller composes.
+export function appliesToAuthor(
+  skillContent: unknown,
+  prAuthor: unknown,
+): boolean {
+  if (typeof skillContent !== 'string') return true;
+  const fm = skillContent.match(/^---\n([\s\S]*?)\n---/);
+  if (!fm) return true;
+  const block = fm[1] as string;
+  // Look for `applies_to:` block; if absent, no author constraint.
+  const head = block.match(/^applies_to:\s*$/m);
+  if (!head) return true;
+  const startIdx = (head.index as number) + head[0].length;
+  const rest = block.slice(startIdx);
+  // The block ends at the next top-level key (line starting with a
+  // word char + `:`) OR end-of-block. Mirrors `readAppliesTo`.
+  const stop = rest.search(/^\w[\w-]*:/m);
+  const scoped = stop === -1 ? rest : rest.slice(0, stop);
+  // Match `  author: <value>` — single string scalar; strip optional
+  // quotes. `author: [a, b]` form is intentionally NOT supported
+  // (SPEC: "single GitHub login string, no list").
+  const authorMatch = scoped.match(/^\s{2}author:\s*(.+?)\s*$/m);
+  if (!authorMatch) return true;
+  const declared = (authorMatch[1] as string)
+    .trim()
+    .replace(/^["']|["']$/g, '');
+  if (!declared) return true; // empty value treated as unset
+  if (typeof prAuthor !== 'string' || !prAuthor) return false;
+  // GitHub logins are case-insensitive (GitHub rejects creating two
+  // accounts that differ only in case; `pull_request.user.login` is
+  // case-preserved but routing is not case-sensitive). Compare
+  // case-insensitively so a skill author writing `Thrillmot` still
+  // matches a webhook delivering `thrillmot` (or vice versa).
+  // Reviewer-flagged Important on PR #179.
+  return declared.toLowerCase() === prAuthor.toLowerCase();
+}
+
 // Minimal glob → regex: `**` → `.*`, `*` → `[^/]*`, `?` → `.`,
 // everything else escaped. Anchored full-string match.
 function globMatch(glob: string, path: string): boolean {
@@ -601,14 +655,39 @@ export type SkillReviewMode = 'shared' | 'dedicated';
  * `PromptSkillFrontmatter` is a narrower subset (name + description +
  * applies_to) so we keep the full shape here.
  */
+export type SkillKind = 'rule' | 'voice' | 'design';
+export type VoiceScope = 'personal' | 'team' | 'org' | 'community';
+
 export interface SkillFrontmatter {
   name: string;
   description: string;
   source: SkillSource | string; // string fallback for forward-compat
   review_mode: SkillReviewMode;
+  /**
+   * SPEC §1.10.1 v0.5.0+ skill classification. OPTIONAL — absent =
+   * `kind: rule` (the v0.4.0 default). Surfaced on the parsed
+   * frontmatter (v0.7.0-rc.6+) so consumers can route on the field;
+   * v0.7.0-rc.5 and earlier silently dropped it.
+   */
+  kind?: SkillKind;
+  /**
+   * SPEC §1.10.1 v0.5.0+ voice scope. REQUIRED when `kind: voice`,
+   * absent otherwise. Surfaced on the parsed frontmatter (v0.7.0-rc.6+).
+   */
+  voice_scope?: VoiceScope;
   applies_to?: {
     paths?: string[];
     extensions?: string[];
+    /**
+     * SPEC §1.10.1 v0.5.1+ — single GitHub login string (no `@`
+     * prefix, no list). When present, the skill MUST only load when
+     * `pull_request.user.login === author`. Filters via strict AND
+     * with the sibling `paths` + `extensions` filters when all are
+     * present. v0.7.0-rc.5 and earlier silently dropped this field
+     * (treated skills as if it were absent — load unconditionally);
+     * v0.7.0-rc.6+ enforces the filter via `appliesToAuthor`.
+     */
+    author?: string;
   };
 }
 
@@ -691,8 +770,32 @@ export function parseFrontmatter(raw: string): SkillFrontmatter {
   const reviewMode: SkillReviewMode =
     out['review_mode'] === 'dedicated' ? 'dedicated' : 'shared';
 
+  // v0.7.0-rc.6 — surface SPEC §1.10.1 v0.5.0+ kind + voice_scope on
+  // the parsed frontmatter. v0.7.0-rc.5 silently dropped these fields
+  // (the Wave 4d reviewer-flagged silent-drop). Validation is lenient:
+  // unknown values are surfaced as undefined so downstream code sees a
+  // clean type rather than a malformed value. SPEC enforcement (e.g.,
+  // "voice_scope REQUIRED when kind: voice") is the caller's job.
+  const kindRaw = out['kind'];
+  const kind: SkillKind | undefined =
+    kindRaw === 'voice'
+      ? 'voice'
+      : kindRaw === 'design'
+        ? 'design'
+        : kindRaw === 'rule'
+          ? 'rule'
+          : undefined;
+  const voiceScopeRaw = out['voice_scope'];
+  const voiceScope: VoiceScope | undefined =
+    voiceScopeRaw === 'personal' ||
+    voiceScopeRaw === 'team' ||
+    voiceScopeRaw === 'org' ||
+    voiceScopeRaw === 'community'
+      ? voiceScopeRaw
+      : undefined;
+
   const appliesToRaw = out['applies_to'] as
-    | { paths?: unknown; extensions?: unknown }
+    | { paths?: unknown; extensions?: unknown; author?: unknown }
     | undefined;
   let appliesTo: SkillFrontmatter['applies_to'] | undefined;
   if (appliesToRaw) {
@@ -702,10 +805,28 @@ export function parseFrontmatter(raw: string): SkillFrontmatter {
     const extensions = Array.isArray(appliesToRaw.extensions)
       ? appliesToRaw.extensions.map(String)
       : undefined;
-    appliesTo = {
-      ...(paths !== undefined ? { paths } : {}),
-      ...(extensions !== undefined ? { extensions } : {}),
-    };
+    // v0.7.0-rc.6 — SPEC §1.10.1 v0.5.1+ author filter. Single string
+    // only; reject lists + falsy values to keep the filter contract
+    // unambiguous (a future SPEC could broaden to lists if customer
+    // demand argues for it).
+    const authorRaw = appliesToRaw.author;
+    const author =
+      typeof authorRaw === 'string' && authorRaw.trim().length > 0
+        ? authorRaw.trim()
+        : undefined;
+    // Reviewer-flagged Important on PR #179: an empty `applies_to:`
+    // block (no sub-keys) was emitting `applies_to: {}` on the
+    // returned frontmatter, which leaked into the prompt builder as
+    // JSON noise + semantically diverged from readAppliesTo's null
+    // return for the same input. Only construct appliesTo when at
+    // least one sub-field is present.
+    if (paths !== undefined || extensions !== undefined || author !== undefined) {
+      appliesTo = {
+        ...(paths !== undefined ? { paths } : {}),
+        ...(extensions !== undefined ? { extensions } : {}),
+        ...(author !== undefined ? { author } : {}),
+      };
+    }
   }
 
   return {
@@ -713,6 +834,8 @@ export function parseFrontmatter(raw: string): SkillFrontmatter {
     description,
     source,
     review_mode: reviewMode,
+    ...(kind !== undefined ? { kind } : {}),
+    ...(voiceScope !== undefined ? { voice_scope: voiceScope } : {}),
     ...(appliesTo !== undefined ? { applies_to: appliesTo } : {}),
   };
 }

package/src/core/version.ts

@@ -0,0 +1,3 @@
+// Generated by scripts/gen-version.mjs at build time. Do not edit.
+// Regenerated automatically on every `npm run build` via "prebuild" hook.
+export const PKG_VERSION = '0.7.0-rc.21';

package/templates/clud-bug-review.md.tmpl

@@ -0,0 +1,115 @@
+---
+description: Review the current branch's open PR locally, in this Claude Code session
+argument-hint: "[pr-number]"
+---
+
+<!-- clud-bug-local-version: v1 -->
+
+You are running **clud-bug** as a local code review — inside this Claude Code
+session, using this session's own model tokens (Max or API, whatever you have).
+No hosted App, no extra auth: you already have `gh`, `git`, and file access.
+
+## 1. Find the PR
+
+PR number: `$ARGUMENTS`
+
+If `$ARGUMENTS` is empty, detect the current branch's open PR:
+
+```bash
+gh pr list --head "$(git branch --show-current)" --state open --json number --jq '.[0].number'
+```
+
+If there is no open PR, stop and tell the user to open one (or pass a PR number).
+
+## 2. Load the review skills
+
+Read the manifest and every referenced skill body from the checkout:
+
+- `.claude/skills/.clud-bug.json` — which skills are installed, plus `strictMode`.
+- For each installed skill, `.claude/skills/<name>/SKILL.md` — the discipline to apply.
+
+Load skills **before** the diff. At minimum the baseline set applies:
+**critical-issues-only** (flag only correctness / security / performance — skip
+nits), **evidence-based-review** (quote the exact line you criticize — no
+hand-waving), **respect-existing-conventions** (don't fight the codebase's
+established patterns).
+
+## 3. Fetch the diff
+
+```bash
+gh pr diff <PR_NUMBER>
+```
+
+## 4. Review
+
+Review the diff against every loaded skill. For each finding record: `file`,
+`line`, `severity` (`critical` | `minor` | `preexisting`), the `skill` that
+motivated it, and a one-line `summary`. Apply the skills strictly — especially
+critical-issues-only (no nits) and evidence-based-review (quote the code).
+
+## 5. Render the review comment
+
+Build the body in clud-bug's standard shape (omit any empty findings section):
+
+```
+## 🐛 Clud Bug review — <clean | critical findings>
+
+**This round:** N critical · N minor · N resolved from prior · N still open
+
+Found: N 🔴 / N 🟡 / N 🟣
+
+### Per-skill scan
+- [<skill>]: <one line on what it scanned + found>
+
+### Critical findings
+🔴 [<skill>]: <summary> (<file>:<line>).
+
+### Minor findings
+🟡 [<skill>]: <summary> (<file>:<line>).
+
+### Pre-existing findings
+🟣 [<skill>]: <summary> (<file>:<line>).
+
+Skills referenced: [<skill>, <skill>]
+
+<!-- written-by: @<your-gh-login> (clud-bug local-mode) -->
+<!-- review-sha: <HEAD_SHA> -->
+```
+
+Get your gh login with `gh api user --jq .login` and the head sha with
+`git rev-parse HEAD`. The `written-by` marker **MUST** end with
+`(clud-bug local-mode)` so the bot's auto-resolve never mistakes this for a
+`clud-bug[bot]` comment.
+
+## 6. Post (or update) the comment
+
+Look for an existing local-mode comment and edit it in place (one rolling review
+comment), otherwise post a fresh one. Use the **REST** issues-comments endpoint
+for the lookup — its `.id` is the **integer** comment id the PATCH endpoint needs.
+(Do NOT use `gh pr view --json comments`; that returns GraphQL node IDs, which
+404 on the REST PATCH and cause duplicate comments.) `gh` fills `{owner}/{repo}`.
+
+```bash
+# existing local-mode comment id (integer), if any:
+EXISTING_ID=$(gh api --paginate "repos/{owner}/{repo}/issues/<PR_NUMBER>/comments" \
+  --jq '[.[] | select(.body | test("written-by: @.* \\(clud-bug local-mode\\)"))] | first | .id // empty')
+```
+
+- `$EXISTING_ID` empty → `gh pr comment <PR_NUMBER> --body-file <body.md>`
+- `$EXISTING_ID` set → `gh api "repos/{owner}/{repo}/issues/comments/$EXISTING_ID" -X PATCH -F body=@<body.md>`
+
+## 7. Summarize
+
+Print one line:
+`clud-bug local-review: N critical · N minor · N preexisting — <PASS | FAIL (strictMode) | advisory>`
+
+If `.clud-bug.json` has `strictMode: true` and there are critical findings, say
+**FAIL** and tell the user to fix them before merging.
+
+---
+
+_Optional: if the `clud-bug-mcp` MCP server is connected, you may use its
+structured tools (`load_skills_from_pr_base`, `fetch_pr_diff`,
+`partition_findings_by_severity`, `emit_review_comment`) in place of the raw
+`gh`/`git` calls above — same flow, with the base-ref skill read and the exact
+review rendering done for you._

package/templates/skills/design/design-system-consistency.md

@@ -0,0 +1,41 @@
+---
+name: design-system-consistency
+description: Visual review — flag rendered UI that drifts from the design system's tokens, scale, and color discipline. Judges the screenshot, not just the code.
+kind: design
+review_mode: dedicated
+applies_to:
+  paths: ["site/**", "app/**", "**/components/**", "**/ui/**"]
+  extensions: [".tsx", ".jsx", ".css", ".scss", ".vue", ".svelte"]
+---
+
+# Design-system consistency
+
+You are reviewing the **rendered** change (screenshots, light and dark) against the
+project's design system. Cite the specific element you see in the screenshot — name it
+and where it is — not just the source line.
+
+## Flag
+
+1. **Off-token values.** A hardcoded color, spacing, radius, shadow, or font-size where a
+   design token / CSS variable already exists for that role. Quote the value and name the
+   token it should use.
+2. **Color discipline.** Fills should be cool/neutral; strokes and text are the warm/ink
+   layer; a saturated red (or the system's "danger" hue) is reserved for destructive or
+   critical states. Flag a red used for a non-critical accent, or a one-off accent hue that
+   isn't in the palette. Prefer perceptually-uniform color (OKLCH/LCH) over ad-hoc hex when
+   the system uses it.
+3. **Off-scale spacing.** Margins/padding/gaps that don't land on the spacing scale (e.g. a
+   `13px` gap in a 4-/8-pt system). Rhythm should be consistent between sibling elements.
+4. **Type ramp drift.** A font-size/weight/line-height combination outside the defined type
+   scale, or the same semantic level rendered at two different sizes across the view.
+5. **Re-implementation.** A button/card/input hand-rolled inline when a system component
+   exists — visible as subtly different padding, radius, or hover from its siblings.
+
+## How to judge
+
+- Compare the new surface against an existing, known-good surface in the same product.
+- "It renders" is not the bar — **token-correct** is the bar. Flag a value that looks fine
+  but bypasses the system; say which token restores consistency.
+- One concrete drift per finding, with the rendered element quoted and the fix named.
+
+If the rendered change is token-clean and on-scale in both themes, say so in one line.

package/templates/skills/design/frontend-a11y.md

@@ -0,0 +1,41 @@
+---
+name: frontend-a11y
+description: Visual review — accessibility on the rendered surface: contrast, focus visibility, tap targets, semantics, motion. Cite the element and the failing ratio or state.
+kind: design
+review_mode: dedicated
+applies_to:
+  paths: ["site/**", "app/**", "**/components/**", "**/ui/**"]
+  extensions: [".tsx", ".jsx", ".css", ".scss", ".vue", ".svelte"]
+---
+
+# Frontend accessibility
+
+You are reviewing the **rendered** change (screenshots, light and dark) plus the markup for
+accessibility. Cite the element and the concrete failure (the measured ratio, the missing
+state, the tag).
+
+## Flag
+
+1. **Contrast.** Body text below WCAG AA 4.5:1, or large text / UI borders below 3:1 — in
+   **either** theme (check both screenshots; dark mode is where contrast quietly fails).
+   Name the foreground/background and the approximate ratio.
+2. **Focus visibility.** Any interactive element with no visible focus indicator, or a focus
+   ring removed (`outline: none`) without a replacement. Keyboard users must see focus.
+3. **Tap / click targets.** Controls smaller than ~24x24 CSS px (44px on touch surfaces),
+   or targets packed too tightly to hit reliably.
+4. **Semantics.** Icon-only buttons without an accessible name (`aria-label`/visually-hidden
+   text); headings that skip levels; a `<div>` with a click handler where a `<button>`/`<a>`
+   belongs; images conveying meaning without alt text.
+5. **Color-only signaling.** State or meaning carried by color alone (e.g. red/green status
+   with no icon or label).
+6. **Motion.** Auto-playing or large motion that doesn't honor `prefers-reduced-motion`.
+
+## How to judge
+
+- Prefer findings you can see or measure in the screenshot/markup; estimate the contrast
+  ratio rather than hand-waving "low contrast."
+- A genuine WCAG-AA failure on interactive/text content is high severity; a borderline ratio
+  or a nice-to-have is medium/low.
+- One issue per finding: element, the failure, the fix.
+
+If the surface is clean on these checks in both themes, say so in one line.

package/templates/skills/design/visual-polish.md

@@ -0,0 +1,41 @@
+---
+name: visual-polish
+description: Visual review — hold the rendered UI to an elite bar: alignment, optical centering, spacing rhythm, glyph/pattern quality, state coverage, theme parity. Flag "fine but not elite," not only broken.
+kind: design
+review_mode: dedicated
+applies_to:
+  paths: ["site/**", "app/**", "**/components/**", "**/ui/**"]
+  extensions: [".tsx", ".jsx", ".css", ".scss", ".vue", ".svelte"]
+---
+
+# Visual polish
+
+You are judging the **rendered** change (screenshots, light and dark) against a
+Figma-grade bar. Most of what you flag will be "acceptable but not elite" — that is the
+point. Cite the element and where it sits in the screenshot.
+
+## Flag
+
+1. **Alignment & optical centering.** Elements off a shared grid/baseline; an icon
+   geometrically centered in a button but optically off (glyphs with side-bearing need a
+   nudge); label and control not on the same baseline; ragged edges between siblings.
+2. **Spacing rhythm.** Inconsistent gaps in a list/stack; cramped or floaty padding; a
+   section that breaks the vertical rhythm the rest of the page establishes.
+3. **Glyph & pattern quality.** Blurry/missized icons, mismatched stroke widths, a pattern
+   or texture that tiles visibly or clips, emoji where a real glyph is warranted.
+4. **State coverage.** Interactive elements missing a distinct hover / focus-visible /
+   active / disabled state, or states that are present but indistinguishable.
+5. **Theme parity.** Compare the light and dark screenshots: a color that loses contrast,
+   a shadow that vanishes, a border that disappears, or an asset baked for one theme only.
+6. **Clutter & duplication.** Redundant chrome, two affordances doing the same job,
+   competing focal points, or content that overflows / truncates awkwardly at the captured
+   viewport.
+
+## How to judge
+
+- Ask "would this ship in a top-tier product?" If it's *fine but not elite*, flag it with
+  the concrete upgrade (the nudge, the token, the missing state).
+- Severity: layout breakage or an unreadable state is high; polish gaps are medium/low.
+- One issue per finding; name the element, say what's off, say the fix.
+
+If the surface is genuinely polished in both themes, say so — don't manufacture nits.