@harness-engineering/cli 2.6.1 → 2.7.1

package/dist/agents/skills/codex/copy-craft/skill.yaml

@@ -0,0 +1,52 @@
+name: copy-craft
+version: "0.1.0"
+description: LLM-judgment critique of prose-in-code across six surfaces (error messages, log lines, CLI output, commit subjects, PR descriptions, code comments). Third craft-pipeline ceiling skill; primary domain is error messages (universally bad). Graceful degradation when git/gh prerequisites are absent.
+stability: draft
+cognitive_mode: constructive-architect
+triggers:
+  - manual
+  - on_pr
+  - on_new_feature
+platforms:
+  - claude-code
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+cli:
+  command: harness copy-craft
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: files
+      description: Optional source file/glob scope
+      required: false
+    - name: surfaces
+      description: Restrict to error/log/cli-output/commit/pr-description/comment
+      required: false
+    - name: commits-since
+      description: Commit window (default 1 month ago)
+      required: false
+mcp:
+  tool: copy_craft
+  input:
+    path: string
+type: rigid
+tier: 2
+phases:
+  - name: extract
+    description: TS Compiler API for source surfaces; git/gh shell-out for commits + PRs
+    required: true
+  - name: critique
+    description: LLM-rubric loop per (item, rubric) where rubric applies to that surface
+    required: true
+  - name: report
+    description: Aggregate findings + per-surface counts + cost telemetry + skipped surfaces
+    required: true
+state:
+  persistent: false
+depends_on:
+  - harness-design-craft
+  - naming-craft

package/dist/agents/skills/codex/detect-design-drift/SKILL.md

@@ -0,0 +1,139 @@
+# Detect Design Drift
+
+> Detect design-system drift — hardcoded values where tokens exist, and raw HTML primitives where registered components exist. The rule-based floor of design-pipeline #1 (detect half). Reports findings; never modifies source. Pairs with a separate align-design-system fixer skill (deferred to a sibling sub-project).
+
+## When to Use
+
+- Reviewing a PR that touches UI code, when you want to catch divergence from the design system before it ships
+- After adding a new design token, to surface places in the codebase that still use the hardcoded equivalent
+- After registering a new primitive (e.g. Button) in DESIGN.md `## Component Registry`, to find existing raw-HTML usages that should adopt it
+- As part of `harness validate` so drift surfaces continuously, not only on demand
+- As one of three verifiers composed by `harness check-design` (alongside audit-component-anatomy and harness-design-craft)
+- NOT for component-anatomy gaps (use audit-component-anatomy)
+- NOT for aesthetic critique (use harness-design-craft)
+- NOT for fixing drift — this skill detects only; the matching fixer (align-design-system) is a separate sub-project
+
+## Process
+
+### Phase 1: SCAN — Load resolvers + walk files
+
+1. **Read project configuration.** Check `harness.config.json` for:
+   - `design.strictness` — `strict` / `standard` / `permissive` (default `standard`)
+   - `design.audit.driftDetection.enabled` — gate for the verifier (default `true`)
+   - `design.audit.driftDetection.rules.{tokenBypass,primitiveAdoption}` — per-rule toggles
+   - `design.audit.driftDetection.fastMode.maxFiles` — validate-time scope cap
+
+2. **Load resolvers (soft-dependency — silent skip when absent):**
+   - `design-system/tokens.json` (W3C DTCG format) — parsed by `loadTokenSet`. Extracts colors, font families, spacing scale, and deprecated token paths. Returns `null` when the file doesn't exist; token-bypass rules then skip silently.
+   - `design-system/DESIGN.md` `## Component Registry` — parsed by `loadComponentRegistry`. Maps registered component types (Button/Input/Textarea/Link/Anchor) to their HTML primitive tag. Returns `null` when DESIGN.md or the section is absent; primitive-adoption rules then skip silently.
+
+3. **Collect candidate files.** Walk the project root (or honor an explicit `files` arg from the caller). Skip `node_modules`, `dist`, `build`, `coverage`, and any dotfile directory. Honor only these extensions: `.ts`, `.tsx`, `.js`, `.jsx`, `.css`, `.scss`.
+
+### Phase 2: APPLY RULES — Two rule families
+
+1. **Token bypass rules (DRIFT-T\*) — regex-based detection.** For each file when tokens were loaded:
+   - **DRIFT-T001** — Hex color literal (`#abc`, `#aabbcc`, etc.) NOT present in the loaded palette. Case-insensitive palette match. Deduplicated per `line:value`.
+   - **DRIFT-T002** — Font-family string literal NOT present in the typography palette. System fallbacks (`sans-serif`, `serif`, `monospace`, `system-ui`, `inherit`) are always allowed.
+   - **DRIFT-T003** — Pixel margin/padding/gap/positioning value NOT present in the spacing scale. Skipped entirely when no spacing tokens exist.
+   - **DRIFT-T004** — Reference to a token flagged `$deprecated: true` (or `$extensions.harness.deprecated: true`) in tokens.json. Matched in both `'token.path.form'` and CSS-var kebab form (`--token-path-form`).
+
+2. **Primitive adoption rules (DRIFT-P\*) — TS Compiler API JSX parsing.** For each `.jsx`/`.tsx` file when the registry was loaded:
+   - **DRIFT-P001** — `<button>` JSX where `Button` is registered
+   - **DRIFT-P002** — `<input>` JSX where `Input` is registered
+   - **DRIFT-P003** — `<a>` JSX where `Link` or `Anchor` is registered
+   - **DRIFT-P004** — `<textarea>` JSX where `Textarea` is registered
+   - Lowercase JSX = HTML primitive (JSX semantics). Uppercase identifiers are skipped — they're already components. Member expressions (`<Foo.Bar>`) are skipped.
+
+### Phase 3: REPORT — Severity, aggregate, persist
+
+1. **Severity from `design.strictness`:**
+   - `strict` — every finding `error` (CI blocks)
+   - `standard` — DRIFT-T001/T002/P001 → `error`; everything else → `warn`
+   - `permissive` — everything → `info`
+
+2. **Aggregate the run summary.** `bySeverity`, `byCode`, `totalFiles`, `durationMs`. Also report `catalog.rulesApplied` (which rule families fired) and `meta.{tokensLoaded, registryLoaded, mode}` so callers can see what was active.
+
+3. **Persist findings to the graph (when composed by check-design).** The check-design orchestrator passes drift findings to `DesignConstraintAdapter.recordFindings()` alongside anatomy and craft findings. Each finding becomes an idempotent `VIOLATES_design` edge keyed by `(file, code, line)` — re-runs do not double-write.
+
+## Harness Integration
+
+- **`harness validate`** — Fast-mode hook runs the detect-drift verifier. Findings respect `design.strictness`. Failures degrade gracefully: if the verifier throws, validate logs a warning and continues with other checks.
+- **`harness check-design`** — One of three composed verifiers. The orchestrator aggregates findings across audit-anatomy, design-craft, and detect-drift; persists all three to the graph; and surfaces a unified report.
+- **`mcp__harness__detect_drift`** — Programmatic API. Input: `{ path, mode, files?, designStrictness?, rules? }`. Output: `{ findings, summary, catalog, meta }`. Consumed by the design-pipeline orchestrator (sub-project #5).
+- **`DesignConstraintAdapter.recordFindings()`** — Generic graph persistence entry point shipped in PR #390. Drift findings reuse the adapter; no extra graph plumbing.
+- **Future align-design-system skill** — Separate sub-project. Reads the same finding codes (DRIFT-T\*, DRIFT-P\*) and applies fixes. Decoupling detect from align keeps each skill testable in isolation and lets the detect side ship first.
+
+## Success Criteria
+
+See `docs/changes/design-pipeline/detect-design-drift/proposal.md` for the full 34 success criteria. Highlights:
+
+- Zero false positives when tokens.json/DESIGN.md are absent (rules skip silently — no speculative findings)
+- Token-bypass detection runs in &lt; 1s on a 500-file repo (fast-mode budget)
+- Primitive-adoption parses JSX correctly across multi-line / fragmented opening tags (TS Compiler API, not regex)
+- Idempotent graph persistence — re-running produces zero duplicate edges
+- `harness validate` runtime budget &lt; 3s on a 500-file repo with both rule families enabled
+- Both rule families gated independently via config (a project can disable primitive-adoption without disabling token-bypass)
+
+## Examples
+
+### Example: Hardcoded brand color outside the palette
+
+**Input:** `src/Card.tsx` contains `const styles = { color: "#ff0000" };`, and `design-system/tokens.json` defines `color.brand.primary` as `#0066cc` (but no `#ff0000`).
+
+**Output:**
+
+```
+DRIFT-T001 [error] src/Card.tsx:14 — Hardcoded color "#ff0000" is not in the design token palette
+  Fix: Replace "#ff0000" with a token reference (e.g. var(--color-...) or a token-system lookup).
+       If the color is intentionally one-off, add it to tokens.json first.
+```
+
+Severity is `error` under `standard` because brand-color drift is high-impact.
+
+### Example: Raw `<button>` where Button is registered
+
+**Input:** `src/SaveButton.tsx` contains `<button onClick={...}>Save</button>`, and `design-system/DESIGN.md` `## Component Registry` lists `Button` mapped to `packages/ui/src/Button.tsx`.
+
+**Output:**
+
+```
+DRIFT-P001 [error] src/SaveButton.tsx:8 — Raw <button> element where the registered component "Button" should be used
+  Fix: Import Button from your component library and replace <button> with <Button>.
+       If this raw primitive is intentional (e.g. inside the Button component's own implementation),
+       add a JSDoc `@allow-raw-primitive` annotation on the file.
+```
+
+### Example: Reference to a deprecated token
+
+**Input:** `src/legacy.css` contains `.x { color: var(--color-brand-500); }`, and `tokens.json` flags `color.brand.500` as `$deprecated: true` with `$description: "Use color.brand.primary instead"`.
+
+**Output:**
+
+```
+DRIFT-T004 [warn] src/legacy.css:3 — Token "color.brand.500" is deprecated and should be migrated
+  Fix: Migrate references to "color.brand.500" to the replacement token noted in tokens.json $description,
+       or remove the deprecation if the token is still load-bearing.
+```
+
+## Gates
+
+- **No findings without resolved inputs.** If `tokens.json` is absent, all T\* rules silently skip. If `DESIGN.md ## Component Registry` is absent, all P\* rules silently skip. Either resolver failing is not a verifier failure — the project simply hasn't opted in.
+- **No autofix.** Findings include codemod-todo descriptions. The matching fixer (align-design-system) is a separate skill.
+- **No usage-side primitive findings beyond the four registered tags.** Other tags (`<select>`, `<details>`, etc.) are not in scope for v1 — even if the project registers a component for them. Subsumption ships in v1.x.
+- **Strictness from config, not assumed.** Read `design.strictness` from `harness.config.json`; default to `standard` if absent.
+
+## Escalation
+
+- **When token-bypass false positives appear in a third-party-shaped value.** E.g. a vendor color brought in via a CSS variable that legitimately doesn't match the palette. Either add the value to `tokens.json` (preferred — makes the palette authoritative) or scope the file via `design.audit.driftDetection.rules.tokenBypass: false` for a narrow path-overrides block (v1.x).
+- **When primitive-adoption fires inside the Button component's own implementation.** That's a true positive that the rule can't tell apart from the usage form. Two paths: (1) add `@allow-raw-primitive` JSDoc on the file (v1.x — annotation honored by the rule), or (2) extract the raw `<button>` into a private internal component until the annotation lands.
+- **When `harness validate` runtime exceeds 3 seconds.** Set `design.audit.driftDetection.fastMode.maxFiles` to cap the scope. The MCP tool ignores the cap (`fast`/`full` are equivalent in v1 — the cap is validate-side only).
+- **When the graph persistence fails.** Skip graph integration for that run; findings still appear in the report. The graph is a consumer, not a gate.
+- **When a project ships its own design-system convention (not tokens.json, not DESIGN.md registry).** v1 reads only the two declared input formats. Either (1) generate a tokens.json adapter that mirrors the existing convention (one-shot script), or (2) wait for v1.x's pluggable resolver interface.
+
+## Status
+
+**v1 — in implementation.** See:
+
+- Spec: `docs/changes/design-pipeline/detect-design-drift/proposal.md`
+- Roadmap entry: `design-pipeline sub-project #1` (detect half) in `docs/roadmap.md`
+- Sibling: `align-design-system` (fix half — deferred to a separate sub-project)

package/dist/agents/skills/codex/detect-design-drift/skill.yaml

@@ -0,0 +1,50 @@
+name: detect-design-drift
+version: "0.1.0"
+description: Detect design-system drift — hardcoded values where tokens exist and raw HTML primitives where registered components exist. Reports only; never modifies source. Floor-layer rule-based verifier composed by harness check-design.
+stability: draft
+cognitive_mode: constructive-architect
+triggers:
+  - manual
+  - on_pr
+  - on_new_feature
+platforms:
+  - claude-code
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+cli:
+  command: harness skill run detect-design-drift
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: mode
+      description: "fast or full (equivalent in v1 — reserved for future scope expansion)"
+      required: false
+    - name: files
+      description: Optional list of files to scope the run
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: detect-design-drift
+    path: string
+type: rigid
+tier: 2
+phases:
+  - name: scan
+    description: Load tokens.json and DESIGN.md registry; walk candidate files
+    required: true
+  - name: apply_rules
+    description: Run DRIFT-T* and DRIFT-P* rules per file
+    required: true
+  - name: report
+    description: Aggregate severity, format findings, persist to graph
+    required: true
+state:
+  persistent: false
+depends_on:
+  - audit-component-anatomy
+  - harness-design-craft

package/dist/agents/skills/codex/harness-accessibility/SKILL.md

@@ -31,6 +31,15 @@
 - If `i18n.enabled` is false or absent, scan for `lang`/`dir` as normal (these remain part of the accessibility audit).
 - This deduplication prevents the same finding from appearing in both the accessibility report and the i18n report.
 
+  2.6. **Check for component-anatomy audit overlap.** Read `harness.config.json` for `design.audit.componentAnatomy.enabled` (default `true` when absent):
+
+- If `enabled: true`, **defer** `A11Y-010` (interactive elements without accessible labels) and `A11Y-050` (`<input>`/`<select>`/`<textarea>` without associated `<label>`) findings for components whose identified type is in the anatomy catalog. Load the catalog component-type set via `getCatalogTypes()` from `audit-component-anatomy`'s public export so this skill has zero rule-content duplication.
+- Identify each scanned JSX element's component type using the same 3-layer resolver `audit-component-anatomy` uses: (1) JSDoc `@component-type X` tag, (2) `design-system/DESIGN.md` `## Component Registry` mapping, (3) top-level export-name catalog match.
+- For components in the catalog: `audit-component-anatomy` owns the label-slot finding as `ANAT-D*` (definition-side in v1, `ANAT-U*` in v2). Do not emit `A11Y-010` / `A11Y-050` for them.
+- For raw HTML elements (`<button>`, `<input>`, `<select>`, `<textarea>`) and unidentified components: scan for `A11Y-010` / `A11Y-050` as normal.
+- If `enabled: false` or absent: scan for `A11Y-010` / `A11Y-050` as normal (no deferral).
+- Same i18n-style deduplication pattern as step 2.5 — prevents one root cause from appearing in both the accessibility report and the anatomy report.
+
 3. **Scan component files.** Search all files matching `.tsx`, `.jsx`, `.vue`, `.svelte`, `.html` for the following violations:
 
    **Images and media:**
@@ -183,6 +192,7 @@ This phase is optional. It applies fixes only for **mechanical issues** -- viola
 - **`harness-impact-analysis`** -- When tokens change (palette update, new colors), impact analysis traces affected components. The accessibility skill uses this to determine which components need re-scanning.
 - **`harness-design-system`** -- Dependency. When contrast failures originate from token definitions (not component code), escalate to harness-design-system to fix at the source.
 - **`harness-i18n` deduplication** -- When `i18n.enabled: true` in config, `lang` and `dir` attribute checks are deferred to the i18n skill. This prevents duplicate findings across the accessibility and i18n reports. When i18n is not enabled, these checks remain part of the accessibility scan.
+- **`audit-component-anatomy` deduplication** -- When `design.audit.componentAnatomy.enabled: true` in config (default), `A11Y-010` and `A11Y-050` are deferred to `audit-component-anatomy` for components in its catalog (Button, Input, Select, Modal, Card, Tabs, etc.). The anatomy audit owns the label-slot finding for those components; this skill still scans raw HTML and unidentified components. Same i18n-style deduplication pattern.
 
 ## Success Criteria
 

package/dist/agents/skills/codex/harness-design-craft/SKILL.md

@@ -0,0 +1,212 @@
+# Harness Design Craft
+
+> LLM-judgment-based design ceiling-raiser. Three branchable phases — CRITIQUE finds what's mediocre, POLISH applies high-craft moves, BENCHMARK scores against curated exemplars. The ceiling counterpart to harness-design (declared-intent enforcement, rule-based) and the design-pipeline floor audits.
+
+## When to Use
+
+- Reviewing UI for craft elevation opportunities the rule-based skills can't surface ("hierarchy is muddy here," "loading spinner where a content-matched skeleton would fit")
+- After harness-design has captured intent and basic checks pass — go from "consistent" to "stunning"
+- Before launching customer-facing surfaces — visual judgment beyond consistency
+- During design-engineering work — POLISH phase suggests concrete craft moves with before/after sketches
+- For competitive benchmarking — BENCHMARK scores how close you are to Linear / Stripe / Raycast tier
+- When `on_new_feature` fires AND the feature touches design surface
+- NOT for declared-anti-pattern enforcement (use harness-design)
+- NOT for component anatomy completeness (use audit-component-anatomy)
+- NOT for token validation (use harness-design-system)
+- NOT for accessibility (use harness-accessibility)
+- NOT for code generation from scratch (use v0 / bolt.new / Lovable — different tool class)
+
+## Process
+
+### Argument Resolution
+
+- `mode`: `"fast"` (code-only LLM, cheap, default) or `"deep"` (rendered + vision-LLM, ceiling-raising, requires playwright + vision-capable model)
+- `phases`: subset of `critique`, `polish`, `benchmark`. Default: all three, sequenced.
+- `autoCapture`: B' upgrade behavior. `"prompt"` (default — offer to chain to harness-design if preconditions missing), `"auto"` (chain without prompting), `"skip"` (run with generic-craft rubrics, no offer).
+- `files`: optional scoping. Default: all components/pages discovered.
+
+### B' Precondition Check (every invocation)
+
+Before any phase runs, check four preconditions and offer to fulfill missing ones:
+
+| Precondition                 | Source                                          | If missing                                                           |
+| ---------------------------- | ----------------------------------------------- | -------------------------------------------------------------------- |
+| `designMdExists`             | `design-system/DESIGN.md` present               | Offer to chain to harness-design (INTENT + DIRECTION)                |
+| `aestheticIntentDeclared`    | DESIGN.md Aesthetic Direction section populated | Offer to chain to harness-design (INTENT)                            |
+| `tokensExist`                | `design-system/tokens.json` present             | Note in summary; do not auto-chain (harness-design-system territory) |
+| `componentRegistryPopulated` | DESIGN.md Component Registry section            | Note in summary; falls back to export-name resolution                |
+
+`autoCapture` controls behavior:
+
+- `prompt`: emit `upgradeOffer` interaction; pause for user choice
+- `auto`: chain to harness-design transition automatically (for autopilot)
+- `skip`: run with generic-craft rubrics (degrades quality but unblocks first-run)
+
+### Phase: CRITIQUE — Find what is craft-mediocre
+
+1. **Identify targets.** Discover components (or pages, when scoped to pages) to critique. Apply `files` scoping if provided.
+
+2. **Load critique rubrics.** Read from catalog (`catalog/rubrics/`). 10 rubrics in v1 covering: hierarchy clarity, typography craft, motion quality, color confidence, density rhythm, restraint, polish details, copy voice, interaction craft, brand coherence. Filter by `catalog.rubrics` config if set.
+
+3. **For each target × each rubric, run an LLM critique pass:**
+   - **Fast mode:** pass source code + rubric prompt + AestheticIntent (if present) to text LLM
+   - **Deep mode:** render via playwright at three viewports (1440/768/375), pass screenshots + source + rubric prompt + AestheticIntent to vision-capable LLM
+   - Parse response into 3-axis finding: `tier` (foundational/polish/aspirational), `impact` (small/medium/large), `confidence` (high/medium/low — essential for honest LLM output)
+
+4. **Apply harness-design overlap deferral.** Per `design.craft.enabled = true`, when a CRITIQUE finding matches a declared anti-pattern in DESIGN.md, defer to harness-design (suppress this finding) and increment `meta.deferralsToHarnessDesign`.
+
+5. **Compute derived `priority` field** for each finding (tier × impact × confidence-weighted score) for single-axis sorting when needed.
+
+### Phase: POLISH — Apply craft pattern library
+
+1. **Load polish patterns.** Read from catalog (`catalog/patterns/`). 15 patterns in v1 across 5 categories: motion (3), skeleton (3), typography (3), interaction (3), layout (3). Filter by `catalog.patterns` config if set.
+
+2. **For each target × each applicable pattern, evaluate fit:**
+   - Match pattern's `applicableTo` criteria (jsx-attribute, css-property, component-type, etc.)
+   - LLM judgment: would applying this pattern improve craft here?
+   - If yes: produce 3-axis finding with `before` and `after` content (codemod-TODO sketch, not actual edit)
+
+3. **No source modification.** POLISH only emits suggestions with before/after sketches. The user applies via codemod tools or by hand.
+
+### Phase: BENCHMARK — Score against curated exemplars
+
+1. **Load exemplar corpus.** Read from catalog (`catalog/exemplars/`). 50 exemplars in v1 across 5 component types (EmptyState, LoadingState, ErrorState, Modal, Button — 10 each). Filter by `catalog.exemplars` config if set.
+
+2. **For each target component, identify matching exemplars** by component-type tag (e.g., target is an EmptyState → load all 10 EmptyState exemplars).
+
+3. **For each target × matching exemplars, run an LLM benchmark pass:**
+   - **Fast mode:** structural comparison (code/markup/declared anatomy vs exemplar's reference markup) — limited but useful as a first signal
+   - **Deep mode:** visual comparison via vision-LLM (target screenshot vs exemplar screenshot/URL)
+   - Parse response into 5-dim radar: `philosophicalCoherence`, `hierarchy`, `craftExecution`, `function`, `innovation` — each with score (0-100), confidence, notes
+   - Compute weighted `overall` score
+   - Emit narrative `gaps` (where the target falls short of the best exemplars and why)
+
+4. **Cite exemplars used.** Each `BenchmarkScore` lists `exemplars` (ids) consulted. Increment per-exemplar `citationCount` for measurement.
+
+### Phase: REPORT — Format and persist outputs
+
+1. **Write to graph:** CRITIQUE/POLISH findings → `VIOLATES_CRAFT` edges via extended `DesignConstraintAdapter`. BENCHMARK scores → `CRAFT_SCORE` nodes attached to component nodes. All carry `runId` for sub-project #4 fixpoint detection. Idempotent.
+
+2. **Format markdown report.** Grouped by component, with `CRAFT-*` codes linked to `finding-codes.md` and rubric/pattern/exemplar names linked to their catalog entries. Low-confidence findings visually distinguished (italic or `(low confidence:)` prefix).
+
+3. **Emit summary.** Total findings, breakdown by phase, mode (`fast`/`deep`), LLM cost (`llmCalls.{count, costUsd}`), catalog applied, deferrals to harness-design, precondition state.
+
+4. **Signal feedback.** Append to running aggregate: when the same finding-shape recurs N≥5 times across audits (config: `design.craft.signal.proposalThreshold`), emit a candidate pattern proposal to `.harness/design-craft/proposals/`.
+
+## Harness Integration
+
+- **`harness validate`** — Fast-mode CRITIQUE hook (subset of rubrics; opt-in). Findings respect `design.strictness`.
+- **`mcp__harness__design_craft`** — Programmatic API. Consumed by harness check-design verifier (#4) and design-pipeline orchestrator (#5). Phase selector exposed.
+- **`harness-design`** — Soft dependency. B' progressive upgrade chains to it when AestheticIntent missing. Defers declared-anti-pattern findings to it.
+- **`harness-design-system`** — Soft dependency. Token-related polish patterns enriched when tokens exist.
+- **`DesignConstraintAdapter`** — Extended for `CRAFT-*` codes (CRAFT-C* critique, CRAFT-P* polish, CRAFT-B\* benchmark identifiers) + `CRAFT_SCORE` node type.
+- **`packages/intelligence/`** — Wrapped by `llm/provider.ts` for vision-capable LLM calls. May need extension if no vision support today.
+
+## Success Criteria
+
+See `docs/changes/design-pipeline/design-craft-elevator/proposal.md` for the full 38 success criteria. Highlights:
+
+- Three phases independently invocable via `phases` arg
+- 3-axis output for CRITIQUE/POLISH; 5-dim radar for BENCHMARK
+- Confidence is honest (low-confidence findings emitted, not silently dropped)
+- B' detect-and-offer works (preconditions detected, offer payload emitted, chain to harness-design honored)
+- Seed catalog complete (10 rubrics + 15 patterns + 50 exemplars)
+- Growth infrastructure operational (contribution validation, signal loop, usage measurement)
+- Fast-mode ≤ 30s / 50 files; deep-mode ≤ 3min / 10 components
+- LLM cost tracked per audit
+
+## Examples
+
+### Example: CRITIQUE finds hierarchy muddiness
+
+**Input:** A Dashboard.tsx page rendering three CTA buttons, all using the same `variant="primary"`.
+
+**Output (3-axis finding):**
+
+```
+CRAFT-C001 [foundational | medium | high] Hierarchy muddy: three buttons compete for primary
+  File:        src/pages/Dashboard.tsx:88
+  Rubric:      hierarchy-clarity (rubric-hierarchy-clarity)
+  Tier:        foundational  (this is "fix to be not-broken," not polish)
+  Impact:      medium        (users can still complete tasks, but decision fatigue is real)
+  Confidence:  high          (rule is unambiguous; LLM saw the three buttons + their identical styling)
+  Priority:    derived → 0.78
+  Message:     Three primary-variant buttons in the same view: "Save", "Export", "Share".
+               No visual signal indicates which is the recommended action. Reduce to one
+               primary; demote the others to secondary or ghost variant.
+  Cite:        rubric "hierarchy-clarity" / source: huashu-design#hierarchy
+```
+
+### Example: POLISH suggests spring physics
+
+**Input:** A Modal.tsx using `transition: transform 0.2s cubic-bezier(0.4, 0, 0.2, 1)`.
+
+**Output (3-axis finding with before/after):**
+
+```
+CRAFT-P001 [polish | medium | high] Spring physics would feel more confident here
+  File:        src/components/Modal.tsx:42
+  Pattern:     spring-physics-microinteraction
+  Tier:        polish        (Modal already works; this elevates the feel)
+  Impact:      medium        (users notice modal motion every time)
+  Before:      transition: transform 0.2s cubic-bezier(0.4, 0, 0.2, 1);
+  After:       transition: transform { duration: spring.medium };
+               // stiffness:200 damping:25 for modal entries per emil-design-eng#spring-physics
+  Fix kind:    codemod-todo (POLISH does not modify source; suggestion only)
+```
+
+### Example: BENCHMARK against Linear
+
+**Input:** A custom EmptyState component for the project's task list.
+
+**Output (5-dim radar):**
+
+```
+CRAFT-B001 EmptyState component scored against Linear empty list exemplar
+
+  philosophicalCoherence: 80 [high]   "Restraint aligns with declared minimal aesthetic."
+  hierarchy:              65 [medium] "Heading and body OK; action button competes
+                                       with secondary 'Learn more' link."
+  craftExecution:         55 [medium] "Generic illustration; Linear uses subtle line art
+                                       matching their monochromatic palette. Missing the
+                                       'breathing room' Linear gets via 64px vertical padding."
+  function:               85 [high]   "Action is clear and verb-led."
+  innovation:             50 [low]    "Standard 4-part anatomy; not differentiated."
+
+  Overall: 67  [medium confidence]
+  Gaps:
+    - "Reduce the empty-state to one CTA — the secondary link adds noise"
+    - "Replace stock illustration with a custom line art aligned to brand"
+    - "Increase top padding from 32px to 56px+ to match the breathing-room pattern"
+  Exemplars cited: exemplar-linear-empty-list
+```
+
+## Gates
+
+- **No assertion of "stunning" without LLM judgment.** This skill is LLM-judgment-based; if no LLM provider is configured, halt with explanatory error — do not degrade to rule-based output.
+- **Deep mode requires playwright + vision-capable LLM.** If either is missing, surface to user with the documented fallback path (code-only mode); do not silently degrade.
+- **No autofix.** POLISH emits suggestions only; source files are never modified.
+- **Confidence is honest.** Low-confidence outputs MUST be emitted (with the low-confidence flag) — never silently upgraded.
+- **B' deferral honored.** When `design.craft.enabled = true` and DESIGN.md declares an anti-pattern matching a CRITIQUE finding, defer to harness-design; never double-count.
+
+## Escalation
+
+- **When deep mode renders fail (component not reachable via URL).** Emit a "render-unreachable" finding for the affected component, fall back to fast mode for that component, continue the audit. Do not abort.
+- **When the vision-LLM rejects the screenshot (size, content, format).** Log the rejection; downgrade that component's run to fast mode; do not abort.
+- **When LLM cost exceeds the configured per-audit budget.** Halt the audit, emit findings collected so far, report the cost overrun. Do not retry. Config: `design.craft.llm.maxCostUsd` (default unset = no cap).
+- **When the catalog is empty or unloadable.** Halt with explanatory error pointing to `agents/skills/shared/design-knowledge/craft-{rubrics,patterns,exemplars}/`. Do not synthesize findings without the catalog.
+- **When B' detect-and-offer produces an offer the user declines.** Run in generic-craft mode (no AestheticIntent context); note the degraded quality in summary. User can re-invoke with `autoCapture: skip` to suppress future offers.
+- **When the same finding-shape recurs across many audits (signal feedback loop).** Auto-export a candidate pattern proposal to `.harness/design-craft/proposals/` after N≥`design.craft.signal.proposalThreshold` recurrences; require human review before promotion to the catalog.
+- **When a graph operation fails.** Skip graph integration for that run; emit findings to the report only. Log a warning that `VIOLATES_CRAFT` edges + `CRAFT_SCORE` nodes were not persisted.
+
+## Status
+
+**v1 — in implementation.** See:
+
+- Spec: `docs/changes/design-pipeline/design-craft-elevator/proposal.md`
+- Plan: `docs/changes/design-pipeline/design-craft-elevator/plans/2026-05-23-design-craft-elevator-plan.md`
+- Finding codes: `docs/changes/design-pipeline/design-craft-elevator/finding-codes.md`
+- Contribution guide: `docs/changes/design-pipeline/design-craft-elevator/contribution.md`
+- Growth trajectory: `docs/changes/design-pipeline/design-craft-elevator/growth-trajectory.md`
+- Roadmap entry: `design-pipeline sub-project #6` in `docs/roadmap.md`
+- Prior-art references: `docs/changes/design-pipeline/REFERENCES.md` tier-1 entries #2, #3, #4 (impeccable, emil-design-eng, huashu-design)

package/dist/agents/skills/codex/harness-design-craft/skill.yaml

@@ -0,0 +1,57 @@
+name: harness-design-craft
+version: "0.1.0"
+description: LLM-judgment-based design ceiling-raiser. CRITIQUE finds what's mediocre, POLISH applies high-craft moves, BENCHMARK scores against curated exemplars. The ceiling counterpart to rule-based audit skills.
+stability: draft
+cognitive_mode: constructive-architect
+triggers:
+  - manual
+  - on_new_feature
+platforms:
+  - claude-code
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-design-craft
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: mode
+      description: "fast (code-only LLM critique) or deep (rendered + vision-LLM)"
+      required: false
+    - name: phases
+      description: "Subset of critique,polish,benchmark (comma-separated). Default: all three."
+      required: false
+    - name: files
+      description: Optional glob/path scoping
+      required: false
+    - name: autoCapture
+      description: "B' upgrade behavior: prompt | auto | skip. Default: prompt."
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-design-craft
+    path: string
+type: flexible
+tier: 2
+phases:
+  - name: critique
+    description: LLM-judgment finding what is craft-mediocre (3-axis tier/impact/confidence output)
+    required: false
+  - name: polish
+    description: Apply polish patterns with before/after sketches (3-axis output)
+    required: false
+  - name: benchmark
+    description: Score against curated exemplars (5-dim radar output)
+    required: false
+state:
+  persistent: false
+depends_on:
+  - harness-design
+  - harness-design-system