@harness-engineering/cli 2.6.1 → 2.7.1

package/dist/agents/skills/gemini-cli/audit-brand-compliance/SKILL.md

@@ -0,0 +1,189 @@
+# Audit Brand Compliance
+
+> Rule-based brand-semantics audit. Detects (a) tokens used in forbidden contexts per their `$extensions.harness.brand.forbidden_contexts` metadata (BRAND-T001) and (b) UI copy containing phrases listed in `DESIGN.md ## Brand Rules → voice.forbidden_phrases` (BRAND-V001). The 4th composed verifier in `harness check-design`, alongside audit-component-anatomy, design-craft critique, and detect-design-drift.
+
+## When to Use
+
+- After authoring or editing `DESIGN.md ## Brand Rules` — verify the new constraints are enforceable on the existing codebase
+- After adding `$extensions.harness.brand` metadata to a token — discover existing call sites in forbidden contexts
+- As part of `harness validate` (fast-mode hook, gated by `design.audit.brandCompliance.enabled`)
+- As the 4th composed verifier in `harness check-design` (the unified design check)
+- Before a PR with UI copy or token-usage changes lands
+- NOT for tone-by-context rules (deferred to v1.x — requires component-state inference)
+- NOT for reading-level or sentence-length rules (deferred to v1.x — ship with tone-context)
+- NOT for asset-usage rules (deferred to v1.x — requires image-tag scanning)
+- NOT for semantic-token-alias enforcement (overlaps with detect-design-drift T001 — design after both have shipped)
+- NOT for brand-rule authoring (use `harness-design` skill to draft DESIGN.md sections)
+
+## Process
+
+### Phase 1: LOAD — Parse the two input sources
+
+1. **Read project configuration.** Check `harness.config.json` for:
+   - `design.strictness` — `strict` / `standard` / `permissive` (default `standard`)
+   - `design.audit.brandCompliance.enabled` — gate (default `true`)
+   - `design.audit.brandCompliance.rules.{tokenMisuse,voice}` — per-rule toggles
+
+2. **Load `design-system/DESIGN.md` `## Brand Rules`.** The parser extracts:
+   - `voice.forbiddenPhrases: string[]` — used by BRAND-V001 in v1
+   - `voice.constant`, `voice.readingLevel`, `voice.maxSentenceWords` — parsed but unused in v1 (forward-compat)
+   - `toneByContext`, `assets`, `semanticTokenAliases` — parsed but unused (v1.x)
+   - Returns `null` when DESIGN.md absent or `## Brand Rules` section missing → BRAND-V001 silently skips.
+
+3. **Load `design-system/tokens.json` `$extensions.harness.brand`.** Walks the DTCG token tree capturing per-token `role`, `approved_contexts`, `forbidden_contexts`. Returns `null` when no token carries the extension → BRAND-T\* silently skips.
+
+### Phase 2: SCAN — Apply the two rule families
+
+1. **BRAND-T001 — token misuse (regex-based).** For each token whose `forbidden_contexts` is non-empty:
+   - Find every reference to the token's dotted path in source (recognizes three forms):
+     - `tokens.X.Y.Z` (JS accessor)
+     - `var(--X-Y-Z)` (CSS var, kebab-cased)
+     - `'X.Y.Z'` / `"X.Y.Z"` (string literal)
+   - Inspect surrounding context (same line + nearest non-blank previous and next line) for the v1 context-vocabulary keywords: `cta`, `selection`, `focus`, `data-visualization`, `decorative`, `background`, `text`, `border`, `error`, `success`, `warning`.
+   - If a forbidden context matches: emit BRAND-T001.
+
+2. **BRAND-V001 — forbidden phrases (TS Compiler API).** For each `.tsx`/`.jsx` file:
+   - Walk the JSX tree.
+   - For each `JsxText` node: case-insensitive substring scan for any forbiddenPhrase.
+   - For each `JsxAttribute` whose initializer is a string literal: same scan.
+   - Deduplicate per `(file, line, phrase)`.
+
+### Phase 3: REPORT — Aggregate and surface
+
+1. **Severity from `design.strictness`** (uses `severityFor`):
+   - `strict` — all findings `error`
+   - `standard` — BRAND-T001 `error` (declared violation), BRAND-V001 `warn` (copy nuance)
+   - `permissive` — all findings `info`
+
+2. **Aggregate `bySeverity` and `byCode`** into the standard Verifier shape: `{ findings, summary, catalog, meta }`.
+
+3. **Persist findings to the graph (when composed by check-design).** check-design routes brand findings through `DesignConstraintAdapter.recordFindings()` alongside anatomy / craft / drift. v1 uses the shared `VIOLATES_design` edge; v1.x may add a brand-specific edge.
+
+## Harness Integration
+
+- **`harness validate`** — Fast-mode hook gated by `design.audit.brandCompliance.enabled`. Degrades gracefully on failure (single warning; other checks continue).
+- **`harness check-design`** — Composes brand as the 4th verifier alongside audit-anatomy, design-craft critique, and detect-design-drift. This is the canonical invocation path.
+- **`mcp__harness__audit_brand`** — MCP tool. Input: `{ path, mode, files?, designStrictness?, rules? }`. Output: `{ findings, summary, catalog, meta }`. Consumed by check-design and the (future) #5 design-pipeline orchestrator.
+- **`DesignConstraintAdapter.recordFindings()`** — Generic graph persistence entry point shipped in PR #390. Brand findings reuse the adapter (no graph schema changes in v1).
+- **`harness-design` skill** — Authors `DESIGN.md ## Brand Rules`. audit-brand-compliance is the matching enforcer.
+- **`Verifier<F>` interface** — Extracted in this PR at the 4th-verifier threshold. Lives at `packages/cli/src/shared/verifier.ts`. Adding a 5th verifier requires only a type-alias declaration of conformance.
+
+## Success Criteria
+
+See `docs/changes/design-pipeline/audit-brand-compliance/proposal.md` for the full 34 success criteria. Highlights:
+
+- DESIGN.md parser returns `null` when section absent (silent-skip pattern)
+- Token-extensions walker returns `null` when no token carries `$extensions.harness.brand`
+- BRAND-T001 fires on `tokens.X`, `var(--x)`, and `'X'` reference forms
+- BRAND-T001 honors approved_contexts (no finding when context is allowed)
+- BRAND-V001 fires on JSX text + string-typed JSX attributes (case-insensitive)
+- BRAND-V001 deduplicates per `(file, line, phrase)`
+- Verifier interface extraction: anatomy / drift / brand all declare structural conformance
+- `harness check-design` test extended for 4-verifier composition (zero regressions)
+- MCP tool count bumps 72 → 73
+
+## Examples
+
+### Example: Token used in forbidden context
+
+**Input:**
+
+`design-system/tokens.json`:
+
+```json
+{
+  "color": {
+    "brand": {
+      "500": {
+        "$type": "color",
+        "$value": "#3b82f6",
+        "$extensions": {
+          "harness": {
+            "brand": {
+              "role": "primary",
+              "approved_contexts": ["cta", "selection", "focus"],
+              "forbidden_contexts": ["data-visualization", "decorative"]
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+`src/Chart.tsx`:
+
+```tsx
+// data-visualization color palette
+const palette = [tokens.color.brand.500, ...];
+```
+
+**Output:**
+
+```
+BRAND-T001 [error] src/Chart.tsx:2 — Token "color.brand.500" is used in forbidden context "data-visualization"
+  Fix: Token "color.brand.500" is not approved for the "data-visualization" context.
+       Use an approved token (allowed contexts: cta, selection, focus), or update
+       tokens.json $extensions.harness.brand if the policy is wrong.
+```
+
+### Example: Forbidden phrase in UI copy
+
+**Input:**
+
+`DESIGN.md`:
+
+```markdown
+## Brand Rules
+
+### Voice
+
+forbidden_phrases:
+
+- "click here"
+- "best-in-class"
+```
+
+`src/Cta.tsx`:
+
+```tsx
+export const Cta = () => <a href="/x">Click here</a>;
+```
+
+**Output:**
+
+```
+BRAND-V001 [warn] src/Cta.tsx:1 — UI copy contains forbidden phrase "click here" — declared at DESIGN.md ## Brand Rules → Voice → forbidden_phrases
+  Fix: Rewrite to avoid "click here". If the phrase is unavoidable for this context,
+       remove it from voice.forbidden_phrases (or scope the audit) — but the default
+       policy is that brand voice trumps convenience.
+```
+
+## Gates
+
+- **No findings without parsed inputs.** DESIGN.md absent → BRAND-V001 skips silently. tokens.json `$extensions.harness.brand` absent on every token → BRAND-T001 skips silently. Either resolver returning null is NOT a verifier failure.
+- **No `.ts`/`.js` file scans for BRAND-V001.** Only `.jsx`/`.tsx` (user-visible JSX). Doc copy in `.md` is a different audience.
+- **No tone-by-context inference.** v1 only matches the explicit context-vocabulary keywords against surrounding source text. v1.x adds component-state inference.
+- **No autofix.** audit-only. The matching `align-brand-compliance` fix-side skill is deferred until detect signals demand.
+- **No graph schema changes.** v1 reuses `VIOLATES_design` via `recordFindings()`. v1.x may add `VIOLATES_brand` edge for queryability.
+- **Strictness from config, not assumed.** Read `design.strictness` from `harness.config.json`; default `standard` if absent.
+
+## Escalation
+
+- **When BRAND-T001 false-positives on a far-context reference:** the v1 context inference is intentionally narrow (same line + adjacent non-blank). For a token used in a "background" context where the keyword appears 10 lines away, v1 misses it. v1.x adds richer context inference; for now, either widen the surrounding comment or accept the miss.
+- **When BRAND-V001 false-positives on a substring (e.g., "as is" in "as issued"):** v1 uses substring match. Add word-boundary regex in v1.x. For now, rephrase the copy or remove the phrase from voice.forbidden_phrases.
+- **When a project ships tokens with a different `$extensions` shape:** v1 reads only `harness.brand`. Document the actual shape your project uses and add it to the schema sketch in ADR 0028 — DTCG `$extensions` namespaces are vendor-prefixed and additions are forward-compatible.
+- **When `harness validate` runtime exceeds 3 seconds:** Set `design.audit.brandCompliance.fastMode.maxFiles` to cap the scope. The MCP tool ignores the cap (`fast`/`full` equivalent in v1).
+- **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 you want tone-by-context rules today:** Manual audit until v1.x ships. Component-state inference (empty/error/success/loading) requires JSX-context analysis that's a separate brainstorm.
+
+## Status
+
+**v1 — in implementation.** See:
+
+- Spec: `docs/changes/design-pipeline/audit-brand-compliance/proposal.md`
+- ADR (input schema source): `docs/knowledge/decisions/0028-brand-guidelines-source-of-truth.md`
+- Roadmap entry: `design-pipeline sub-project #3` in `docs/roadmap.md`
+- Sibling rule-based audits: `audit-component-anatomy` (#2), `detect-design-drift` (#1)
+- Cross-cutting: extracts `Verifier<F>` interface at `packages/cli/src/shared/verifier.ts` (deferred until 4th data point — this is it)

package/dist/agents/skills/gemini-cli/audit-brand-compliance/skill.yaml

@@ -0,0 +1,50 @@
+name: audit-brand-compliance
+version: "0.1.0"
+description: Rule-based brand-semantics audit. Detects token misuse (BRAND-T001 via $extensions.harness.brand.forbidden_contexts) and voice violations (BRAND-V001 via DESIGN.md voice.forbidden_phrases). 4th composed verifier in harness check-design. Triggers extraction of the formal verifier interface.
+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 audit-brand-compliance
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: mode
+      description: "fast or full (equivalent in v1)"
+      required: false
+    - name: files
+      description: Optional list of files to scope the scan
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: audit-brand-compliance
+    path: string
+type: rigid
+tier: 2
+phases:
+  - name: load
+    description: Parse DESIGN.md ## Brand Rules and tokens.json $extensions.harness.brand
+    required: true
+  - name: scan
+    description: Walk JSX text/attributes for forbidden phrases; scan source for token-misuse-in-context
+    required: true
+  - name: report
+    description: Aggregate findings; emit BRAND-T* / BRAND-V001 with severity per design.strictness
+    required: true
+state:
+  persistent: false
+depends_on:
+  - detect-design-drift
+  - harness-design

package/dist/agents/skills/gemini-cli/audit-component-anatomy/SKILL.md

@@ -0,0 +1,181 @@
+# Audit Component Anatomy
+
+> Detect missing required anatomy parts in component definitions and missing-anatomy-component patterns in composition. First programmatic enforcer of component-anatomy rules — finds what design-component-anatomy reference content prescribes.
+
+## When to Use
+
+- Reviewing component-library code for completeness of slots, states, sizes
+- Detecting compositional patterns where a needed anatomy component is missing (e.g., `.map()` over data with no empty branch; async actions with no loading boundary)
+- After component-library changes to verify anatomy contracts still hold
+- Before merging UI changes to catch anatomy regressions
+- When `on_new_feature` triggers fire and the feature touches a component definition or usage
+- NOT for token validation (use harness-design-system)
+- NOT for accessibility compliance (use harness-accessibility — overlap is documented; this skill defers label-association findings to a11y)
+- NOT for aesthetic critique or polish suggestions (use harness-design-craft)
+- NOT for declared-anti-pattern enforcement (use harness-design)
+
+## Process
+
+### Phase 1: SCAN — Identify component types and run audits
+
+1. **Read project configuration.** Check `harness.config.json` for:
+   - `design.strictness` — `strict`/`standard`/`permissive` (default `standard`)
+   - `design.audit.componentAnatomy.enabled` — gate for the entire audit AND the harness-accessibility deferral (default `true`)
+   - `design.audit.componentAnatomy.catalog` — `"default"` or path to project-supplied catalog
+   - `design.audit.componentAnatomy.patterns` — `"all"`, `"none"`, or explicit list of pattern codes
+   - `design.audit.componentAnatomy.fastMode.{patterns,maxFiles}` — fast-mode controls
+
+2. **Load source-of-truth catalogs (resolution order, most specific wins):**
+   - Component author's JSDoc `@component-type X` + `@anatomy-slot ...` etc. — file-level self-declaration
+   - `design-system/DESIGN.md` `## Component Registry` + `## Component Anatomy Overrides` — project-level
+   - Built-in convention library (20 component types: Button, Input, Select, Modal/Dialog, EmptyState, Card, Tabs, Menu, Toast, Form, Accordion, Tooltip, Popover, Drawer, Slider, Switch, Checkbox, Radio, Avatar, Badge) — fallback default
+   - No match for a file's component-type → silent skip (no false positives)
+
+3. **Identify component type per file** using the same resolution order:
+   - JSDoc `@component-type X` tag → file IS X
+   - DESIGN.md Component Registry mapping → use that
+   - Top-level export name matches a catalog entry → use that
+   - No match → skip silently
+
+4. **Run convention audit (definition findings, `ANAT-D*` codes).** For each catalogued component file:
+   - Parse component definition via TypeScript Compiler API (AST)
+   - Extract exported component's prop type / interface
+   - Check that each required anatomy part (slot, state, variant, size) is exposed as a prop or sub-component
+   - Emit `ANAT-D{NNN}` finding for each missing required part
+   - Emit `ANAT-D000` info finding when JSDoc declaration diverges from catalog convention
+
+5. **Run pattern audit (pattern-presence findings, `ANAT-P*` codes).** For each file matching pattern targets:
+   - Parse via tree-sitter (`tree-sitter-typescript` + `tree-sitter-tsx`)
+   - Run each enabled pattern's S-expression query
+   - Post-process captures to confirm pattern presence (e.g., `.map()` without an empty-branch guard)
+   - Emit `ANAT-P{NNN}` finding for each match
+   - Skip patterns NOT enabled in `design.audit.componentAnatomy.patterns`
+
+6. **Check for harness-accessibility overlap deferral.** When `design.audit.componentAnatomy.enabled = true`, this skill OWNS label-slot definition findings; harness-accessibility defers A11Y-010 and A11Y-050 for catalogued components. Track deferrals in `meta.deferralsToHarnessDesign` count.
+
+### Phase 2: EVALUATE — Apply severity model
+
+1. **Map finding severity using `design.strictness`:**
+   - `strict` — all findings are `error` severity (CI blocks)
+   - `standard` — required-part missing → `error`; optional-part missing → `warn`; info findings → `info`
+   - `permissive` — all findings → `info` (nothing blocks)
+
+2. **Cross-reference with graph constraints.** If a graph exists at `.harness/graph/`:
+   - Query existing `VIOLATES_CRAFT` edges via extended `DesignConstraintAdapter`
+   - Identify NEW violations (not in graph) and RESOLVED violations (in graph but not in current scan)
+
+3. **De-duplicate via deferral.** When this skill produces a finding whose root-cause is also tracked by harness-accessibility, prefer this skill's finding (anatomy-level cause) and increment deferrals counter.
+
+### Phase 3: REPORT — Format and persist findings
+
+1. **Write VIOLATES_CRAFT edges to graph.** Each finding becomes:
+   - Source: component file (`code_file` node) or component (`component` node)
+   - Target: `design_rule` node keyed by finding code (`ANAT-D023`, `ANAT-P001`)
+   - Metadata: severity, line, message, evidence snippet, runId
+   - Idempotent: re-running the audit produces no duplicate edges
+
+2. **Format the report.** Grouped by component file, with finding codes linked to `docs/changes/design-pipeline/audit-component-anatomy/finding-codes.md`. Each finding includes:
+   - Code (e.g., `ANAT-D023`)
+   - Severity per `design.strictness`
+   - File path + line number
+   - Component type (if identified)
+   - Message + evidence snippet
+   - Fix hint (concrete next-step text — not "fix this")
+
+3. **Emit summary.** Total findings, breakdown by severity, count of `meta.deferralsToHarnessDesign`, mode (`fast`/`full`), `runId`.
+
+## Harness Integration
+
+- **`harness validate`** — Fast-mode audit hook (convention catalog only; patterns are opt-in via `fastMode.patterns: true`). Findings respect `design.strictness`.
+- **`mcp__harness__audit_anatomy`** — Programmatic API (input: path, mode, files, designStrictness, catalog; output: findings, summary, catalog applied, deferrals count). Consumed by harness check-design verifier (sub-project #4) and design-pipeline orchestrator (sub-project #5).
+- **`DesignConstraintAdapter`** — Extended to register `ANAT-*` rule code namespace and write VIOLATES_CRAFT edges. Mirrors how harness-accessibility uses it for A11Y-\* codes.
+- **`harness-accessibility`** — Coordinates via i18n-style deferral pattern. When `design.audit.componentAnatomy.enabled = true`, a11y defers A11Y-010 and A11Y-050 for catalogued components.
+- **`design-component-anatomy`** (knowledge skill) — Source of convention vocabulary (slot, variant, state, size, exclusivity, required). This skill's catalog operationalizes that knowledge.
+
+## Success Criteria
+
+See `docs/changes/design-pipeline/audit-component-anatomy/proposal.md` for the full 30 success criteria. Highlights:
+
+- Convention findings produced for known component types only (silent skip for unknown — zero false positives)
+- JSDoc self-declaration overrides convention; DESIGN.md overrides convention but not JSDoc
+- Pattern false-positive rate ≤ 5% on the 50-fixture corpus
+- harness-accessibility deferral works (one finding for one root cause, not two)
+- Fast-mode runtime ≤ 3s on 500-file repo
+
+## Examples
+
+### Example: Button missing a required state
+
+**Input:** `packages/ui/src/Button.tsx` exports a `Button` component whose prop type omits any `loading` prop.
+
+**Output:**
+
+```
+ANAT-D002 [error] Button.tsx — Button convention requires state:loading (exclusive)
+  File:        packages/ui/src/Button.tsx
+  Component:   Button (identified via export-name match)
+  Convention:  APG/button + Radix Primitives Button
+  Fix:         Add a `loading?: boolean` prop, OR add `@anatomy-state loading exclusive`
+               JSDoc tag to the component if loading is intentionally omitted.
+```
+
+Severity is `error` under `design.strictness: standard` because the missing part is `required: true` in the Button convention.
+
+### Example: Empty list with no fallback (pattern-presence finding)
+
+**Input:** `src/pages/Dashboard.tsx` contains `{items.map(item => <Card item={item} />)}` with no empty-state branch.
+
+**Output:**
+
+```
+ANAT-P001 [warn] Dashboard.tsx:42 — map() over data with no empty-state branch
+  File:        src/pages/Dashboard.tsx:42
+  Pattern:     ANAT-P001 map-without-empty
+  Fix:         Wrap the map in a conditional that renders <EmptyState> when items.length === 0:
+                 items.length === 0 ? <EmptyState ... /> : items.map(...)
+               Or extract a guard component that handles both branches.
+```
+
+Severity is `warn` for pattern-presence findings under `design.strictness: standard`; `error` under `strict`.
+
+### Example: Catalogued component with JSDoc divergence
+
+**Input:** A Tabs.tsx file has `@anatomy-slot trigger` JSDoc but the convention library says Tabs requires both `trigger` AND `panel`.
+
+**Output:**
+
+```
+ANAT-D000 [info] Tabs.tsx — JSDoc declaration omits 2 conventional anatomy parts
+  File:        packages/ui/src/Tabs.tsx
+  Component:   Tabs (identified via JSDoc @component-type)
+  Divergence:  declared slots [trigger]; convention also expects [panel, list]
+  Note:        JSDoc wins (resolution order #1). This is an info finding to surface
+               the divergence — no action required if intentional.
+```
+
+The `ANAT-D000` info code surfaces JSDoc-vs-convention divergence so authors can confirm the divergence is intentional.
+
+## Gates
+
+- **No findings without a parsed catalog.** If the convention library or DESIGN.md catalog cannot be loaded, stop with an explanatory error — do not emit speculative findings.
+- **No usage-side findings in v1.** Only `ANAT-D*` (definition) and `ANAT-P*` (pattern) codes. Usage findings (`ANAT-U*`) ship in v2.
+- **No autofix.** Findings include fix-hint text only; source files are never modified by this skill.
+- **Strictness from config, not assumed.** Read `design.strictness` from `harness.config.json`; default to `standard` if absent.
+
+## Escalation
+
+- **When a project uses a non-standard component name (e.g., `PrimaryButton` instead of `Button`).** The export-name resolver won't match. Two paths: (1) the component author adds `@component-type Button` JSDoc, or (2) the project adds the file to DESIGN.md `## Component Registry`. Both unblock the audit without touching the catalog.
+- **When the convention catalog is wrong for an opinionated project.** Add a per-component override block to DESIGN.md `## Component Anatomy Overrides`. The override wins for that component type; other catalogued types behave normally.
+- **When pattern-presence findings have a false-positive rate >5% in a particular project.** Disable the specific pattern via `design.audit.componentAnatomy.patterns: ["-ANAT-P003"]` (negated form). Report the false positive — pattern catalog evolves based on real-world signal.
+- **When harness-accessibility produces a finding this skill should own.** Verify `design.audit.componentAnatomy.enabled = true` and the component IS in the catalog. If both, the a11y deferral is misfiring — file an issue; likely a `getCatalogTypes()` cache staleness.
+- **When `harness validate` runtime exceeds 3 seconds.** Set `design.audit.componentAnatomy.fastMode.maxFiles` to cap the scope, OR set `design.audit.componentAnatomy.fastMode.patterns: false` to skip pattern runs in fast mode (patterns are full-mode only by default).
+- **When a graph operation fails.** Skip graph integration for that run; emit findings to the report only. Log a warning that `VIOLATES_CRAFT` edges were not persisted. The audit's findings are still actionable; the graph is a consumer, not a gate.
+
+## Status
+
+**v1 — in implementation.** See:
+
+- Spec: `docs/changes/design-pipeline/audit-component-anatomy/proposal.md`
+- Plan: `docs/changes/design-pipeline/audit-component-anatomy/plans/2026-05-23-audit-component-anatomy-plan.md`
+- Finding codes: `docs/changes/design-pipeline/audit-component-anatomy/finding-codes.md`
+- Roadmap entry: `design-pipeline sub-project #2` in `docs/roadmap.md`

package/dist/agents/skills/gemini-cli/audit-component-anatomy/skill.yaml

@@ -0,0 +1,51 @@
+name: audit-component-anatomy
+version: "0.1.0"
+description: Audit component definitions for missing required anatomy parts (slots, states, sizes) and detect missing-anatomy-component patterns (data without empty states, async without loading boundaries). First programmatic enforcer of component-anatomy rules.
+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 audit-component-anatomy
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: mode
+      description: "fast (definition findings only) or full (definitions + patterns)"
+      required: false
+    - name: files
+      description: Optional glob/path scoping
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: audit-component-anatomy
+    path: string
+type: rigid
+tier: 2
+phases:
+  - name: scan
+    description: Identify component types and run convention/pattern audits
+    required: true
+  - name: evaluate
+    description: Apply severity model based on design.strictness
+    required: true
+  - name: report
+    description: Format findings as report + graph edges
+    required: true
+state:
+  persistent: false
+depends_on:
+  - design-component-anatomy
+  - harness-accessibility

package/dist/agents/skills/gemini-cli/copy-craft/SKILL.md

@@ -0,0 +1,192 @@
+# Copy Craft
+
+> LLM-judgment critique of prose-in-code across six surfaces: error messages, log lines, CLI output strings, commit subjects, PR descriptions, and code comments. Primary domain is error messages (universally bad in most codebases). Third member of the craft-pipeline initiative. NO rule-based floor exists — pure ceiling. Emits 3-axis findings (tier × impact × confidence per ADR 0019).
+
+## When to Use
+
+- During PR review on code that adds or changes error messages, log lines, or CLI output
+- After a feature ships, to audit error-message quality across the changed surfaces
+- Periodically (per-release) to catch accumulated noise in log lines + comment rot
+- As the user-facing-copy critic alongside design-craft (which owns UI copy)
+- NOT for UI copy in components (use design-craft)
+- NOT for prose documentation in `docs/` (use docs-craft #2 when it ships)
+- NOT for autofix / rewriting (this is judgment-only; v2 may ship `align-copy`)
+- NOT for JSDoc / TSDoc structured API docs (docs-craft territory)
+- NOT for non-TS/JS languages in v1 (v1.x)
+
+## Process
+
+### Phase 1: EXTRACT — Six surfaces, three infrastructures
+
+1. **Read project configuration.** Check `harness.config.json` for:
+   - `craft.copy.enabled` — gate (default `true`)
+   - `craft.copy.surfaces` — restrict to specific surfaces (default: all 6)
+   - `craft.copy.maxFiles` (default 100), `craft.copy.maxItemsPerFile` (default 20)
+   - `craft.copy.commitsSince` (default `'1 month ago'`), `craft.copy.prLimit` (default 20)
+
+2. **Source-side surfaces** (errors / logs / CLI output / comments): single TS Compiler API walk per source file. Amortizes parse cost across surfaces.
+   - **errors:** `throw new <X>Error("...")` where the constructor name ends in `Error`; also `Err({ message: "..." })` for Result-style returns
+   - **logs:** `console.log/info/warn/error/debug` and `logger.X` / `log.X` / `pino.X` / `winston.X` where X is a known level
+   - **cli-output:** strings inside files under `packages/*/src/commands/` (configurable via `cliOutputPaths`); takes precedence over `log` for files matching the glob
+   - **comments:** `ts.getLeadingCommentRanges()` + `getTrailingCommentRanges()`; excludes JSDoc and license banners
+
+3. **Git surface** (commits): shell-out to `git log --pretty=format:'%H%x09%s' --since=...`. Skip silently when not in a git repo.
+
+4. **GitHub surface** (PR descriptions): shell-out to `gh pr list --json number,title,body`. Skip silently when `gh` binary missing or `gh auth status` fails.
+
+5. **Skipped surfaces** recorded in `summary.skippedSurfaces` with the reason — visible in the report, not a failure.
+
+### Phase 2: CRITIQUE — Per (item, rubric) loop, surface-filtered
+
+8 seed rubrics, each declares which surfaces it applies to:
+
+| Rubric                                | Surfaces                        |
+| ------------------------------------- | ------------------------------- |
+| `COPY-R001` WHAT/WHY/HOW-TO-FIX       | error                           |
+| `COPY-R002` calm-not-panicky          | error, log                      |
+| `COPY-R003` specific-not-generic      | error, log, cli-output          |
+| `COPY-R004` signal-not-noise          | log                             |
+| `COPY-R005` grep-survives             | log, cli-output                 |
+| `COPY-R006` describes-change-not-work | commit, pr-description          |
+| `COPY-R007` stranger-in-6-months      | commit, pr-description, comment |
+| `COPY-R008` WHY-not-WHAT              | comment                         |
+
+For each (item, rubric) where the rubric applies to the item's surface:
+
+1. Build prompt with rubric description + surface + context (errorType / logLevel / ref) + snippet (truncated to 1500 chars).
+2. LLM returns fenced JSON: `null` (rubric doesn't apply / copy is fine) OR `{ tier, impact, confidence, message }`.
+3. On non-null: emit `CopyFinding` with `cite.rubricId` for ADR 0020 traceability.
+
+### Phase 3: REPORT — Aggregate + cost telemetry
+
+Emit `CopyCraftOutput`:
+
+```ts
+{
+  findings: CopyFinding[];
+  summary: {
+    phaseRun: ['critique'];
+    durationMs: number;
+    llmCalls: { provider, model, count, costUsd };
+    catalog: { rubricsApplied: string[]; surfacesScanned: CopySurface[] };
+    counts: Record<CopySurface, number>;
+    skippedSurfaces: Array<{ surface, reason }>;
+    runId: string;
+  }
+}
+```
+
+## Harness Integration
+
+- **`harness copy-craft`** — CLI entry. `--files` / `--surfaces` / `--max-files` / `--max-items-per-file` / `--commits-since` / `--pr-limit` / `--json` / `--verbose`.
+- **`mcp__harness__copy_craft`** — MCP tool. Same input/output. Consumed by agents.
+- **Cross-cutting API:** `critiqueCopyInFile(file, opts)` exported. Source-side surfaces only; git surfaces are project-scoped.
+- **Shared craft infrastructure:** imports `LlmProvider` + 3-axis types + `derivePriority` from `packages/cli/src/shared/craft/` (extracted by spec-craft).
+
+## Success Criteria
+
+See `docs/changes/craft-pipeline/copy-craft/proposal.md` for the full 39 success criteria. Highlights:
+
+- 8 seed rubrics ship in `catalog/rubrics/<id>.ts` (file-per-rubric, matches naming/spec-craft)
+- 3-axis output preserved (tier × impact × confidence, never collapsed)
+- `cite.rubricId` populated on every finding (ADR 0020)
+- Single TS AST walk amortizes parse cost across 4 source surfaces
+- Graceful degradation: `summary.skippedSurfaces` records when git/gh surfaces couldn't run
+- Cross-cutting `critiqueCopyInFile` exported (source surfaces only)
+
+## Examples
+
+### Example: Generic error message
+
+**Input:** `src/parse.ts`:
+
+```ts
+throw new Error('parse error');
+```
+
+**Output (mock LLM):**
+
+```
+[error]
+  COPY-R001 [foundational/large/medium] src/parse.ts:14 error
+    "parse error"
+    Doesn't tell WHAT was being parsed, WHY it failed, or HOW the user can
+    recover. Try: "Failed to parse design-system/tokens.json at line 12: ..."
+  COPY-R003 [polish/medium/high] src/parse.ts:14 error
+    "parse error"
+    Generic — no operation, no artifact. Name the file being parsed and the
+    specific failure mode.
+```
+
+### Example: Noisy log line
+
+**Input:**
+
+```ts
+console.log('entered function');
+```
+
+**Output:**
+
+```
+[log]
+  COPY-R004 [foundational/medium/high] src/handler.ts:23 log
+    "entered function"
+    Pure noise — fires on every invocation; carries no state or decision.
+    Either remove or replace with a state-transition log at the relevant
+    boundary.
+```
+
+### Example: Work-not-change commit subject
+
+**Input:** A commit with subject `"update tests"`.
+
+**Output:**
+
+```
+[commit]
+  COPY-R006 [polish/medium/medium] git:abc1234 commit
+    "update tests"
+    Describes the work, not the change. A reader six months from now needs
+    to know what behaviour changed. Try: "ratchet drift threshold to 0.5%
+    after Hermes Phase 4 baseline reset" or similar.
+```
+
+### Example: Missing prerequisites — graceful skip
+
+When not in a git repo OR `gh` is missing/unauthenticated, those surfaces silently skip and the report shows:
+
+```
+Skipped surfaces:
+  - commit: not a git repo
+  - pr-description: gh binary not found
+```
+
+## Gates
+
+- **No autofix.** v2's `align-copy` may add safe rewrites.
+- **No JSDoc / TSDoc.** docs-craft #2 territory.
+- **No PR / review comments.** v1.x.
+- **No commit BODY critique.** Subjects only in v1.
+- **No B' bootstrap.** Same posture as naming/spec-craft.
+- **No graph persistence.** Phase 1 MVP.
+- **No non-TS/JS language support.** v1.x.
+- **No author-attributed signals.** v1.x telemetry.
+
+## Escalation
+
+- **When LLM cost is too high:** drop `maxItemsPerFile` (default 20) or scope to specific surfaces with `--surfaces error`. Cost ≈ items × applicable rubrics × per-call.
+- **When intentionally-bad test fixtures get flagged:** scope via `--files` to exclude fixtures. v1.x adds `<!-- copy-craft:skip -->` annotation + JSDoc tag.
+- **When git surface skips though you ARE in a repo:** the walk goes up 10 levels looking for `.git`. If you're deeper than that, run from a closer cwd.
+- **When PR surface skips with `gh auth status` failing:** run `gh auth login` first. Or scope away with `--surfaces error,log,comment`.
+- **When `console.log` in a CLI file gets surface='log' instead of 'cli-output':** verify the file path contains `packages/cli/src/commands/` (or a similar default substring). Override with `craft.copy.cliOutputGlobs` config in v1.x.
+
+## Status
+
+**v1 — in implementation.** See:
+
+- Spec: `docs/changes/craft-pipeline/copy-craft/proposal.md`
+- Roadmap entry: `craft-pipeline sub-project #5`
+- Sibling craft skills: `naming-craft` (#1), `spec-craft` (#6)
+- Shared infrastructure: `packages/cli/src/shared/craft/` (extracted by spec-craft)
+- Future: `align-copy` (FIX side, v2), docs-craft (#2, prose docs), test-craft (#3), code-craft (#4)