@harness-engineering/cli 2.6.1 → 2.7.0

package/dist/agents/skills/claude-code/align-design-system/SKILL.md

@@ -0,0 +1,174 @@
+# Align Design System
+
+> Apply codemods for safe DRIFT-T001/T002/T003 token-bypass findings (replace hex / font-family / px-spacing literals with token references) and emit precise suggestions for DRIFT-T004 (deprecated tokens) and all DRIFT-P\* (primitive adoption). The FIX half of design-pipeline sub-project #1, paired with detect-design-drift.
+
+## When to Use
+
+- After detect-design-drift reports DRIFT-T001/T002/T003 findings — align replaces literals with token references where the fix is unambiguous
+- Before a PR that touches UI code lands — pair with detect-design-drift to surface AND fix drift in one shot
+- Inside a (future) #5 design-pipeline orchestrator's convergence loop — align is the FIX step the loop runs between DETECT and VERIFY
+- When you want to dry-run the fixes first (`--dry-run`) and review the diff before writing
+- NOT for primitive-adoption codemods — v1 emits suggestions only for DRIFT-P\*; the prop-translation work lives in v1.x
+- NOT for adding new tokens to tokens.json (no auto-add of palette entries; that's a separate intentional act)
+- NOT for non-design-system fixes (use cleanup-dead-code, align-documentation, etc. for their respective domains)
+
+## Process
+
+### Phase 1: GATHER — Load drift findings
+
+1. **Read project configuration.** Check `harness.config.json` for:
+   - `design.strictness` — passes through to detect-design-drift
+   - `design.audit.driftDetection.*` — passes through to detect
+
+2. **In standalone mode (default):** invoke `detect-design-drift` internally with the same project root + strictness; receive the full `DriftFinding[]`.
+
+3. **In pipeline mode:** read `.harness/handoff.json` and pull `pipeline.driftFindings` (pre-classified by the orchestrator). Honor `pipeline.fixBatch` if present to limit application to a specific subset of findings (the orchestrator may apply fixes in batches across iterations).
+
+### Phase 2: CLASSIFY — Pre-flight safe-codemod vs suggestion
+
+For each finding, the pre-flight classifier inspects file context and chooses:
+
+- **DRIFT-T001 (hex)** — safe-codemod iff token import already present in the file AND hex is in single string-literal context (not a template literal or concatenation) AND exactly one palette token matches by value. Otherwise → suggestion.
+- **DRIFT-T002 (font-family)** — same shape as T001 against the typography palette.
+- **DRIFT-T003 (px spacing)** — safe-codemod iff token import present AND px matches a spacing token's `$value` EXACTLY (no rounding) AND not in an arithmetic expression. Otherwise → suggestion.
+- **DRIFT-T004 (deprecated)** — always suggestion in v1. Migration target may not be in the token's `$description`.
+- **DRIFT-P\* (primitive adoption)** — always suggestion in v1. Prop translation across `<button>` ⇄ `<Button>` is genuinely ambiguous (event handlers, ref forwarding, class merging) — codemods deferred to v1.x.
+
+Token import discovery recognizes three forms:
+
+- ES named: `import { tokens } from '...'`
+- ES default: `import tokens from '...'`
+- CJS: `const tokens = require('...')`
+
+### Phase 3: APPLY — Codemod or emit suggestion
+
+For each finding classified as `safe-codemod`:
+
+1. Read the source file (cached per-run to avoid re-reads when multiple findings hit the same file).
+2. Locate the exact match position from the finding's `line` + `evidence.snippet`.
+3. Compute the replacement using file-extension-aware syntax:
+   - `.ts` / `.tsx` / `.js` / `.jsx` → `tokens.<dotted.path>`
+   - `.css` / `.scss` → `var(--<dotted-path-as-kebab>)`
+4. Replace in-place. Emit `FixOutcome.applied` with a structured diff (file / line / before / after).
+5. If `--dry-run`: compute the diff but DO NOT write to disk.
+6. If the file changed between detect-time and apply-time: skip with `kind: 'skipped-unsafe', reason: 'file changed since finding'`.
+
+For each finding classified as `suggestion`: emit a human-readable description plus a preview of the suggested change. No file mutation.
+
+### Phase 4: REPORT — Aggregate + (pipeline-mode) handoff writeback
+
+1. Aggregate `FixOutcome[]` into a summary: counts by kind (applied / suggestion / skipped / failed) plus files modified and duration.
+2. Build a `catalog` of finding codes that produced codemods and codes that produced suggestions.
+3. In pipeline mode: write `pipeline.fixesApplied: FixOutcome[]` back to `.harness/handoff.json` so the orchestrator can re-verify only the affected findings on the next loop iteration.
+
+## Harness Integration
+
+- **`harness align-design-system`** — the CLI entry point. `--dry-run` for preview; `--write` is the default. Standard `--json` / `--verbose` / `--quiet` flags.
+- **`harness align-design-system --mode pipeline`** — orchestrator-driven mode. Reads pre-classified findings from handoff.json; writes outcomes back.
+- **`mcp__harness__align_design_system`** — MCP tool for agent consumption. Same input/output shape as the function call.
+- **`detect-design-drift`** — soft dependency. Standalone mode invokes detect internally; pipeline mode trusts the orchestrator to have done it.
+- **`harness check-design`** — composes detect (as 3rd verifier) into a single-pass design check. align is the matching FIX step; together they form the DETECT → FIX cycle that the (future) #5 orchestrator will loop.
+- **`DesignConstraintAdapter`** — align does NOT write to the graph. The graph already tracks `VIOLATES_design` edges (the findings). Re-running detect after align shows the delta — no separate fix-edge needed.
+
+## Success Criteria
+
+See `docs/changes/design-pipeline/align-design-system/proposal.md` for the full 34 success criteria. Highlights:
+
+- T001/T002/T003 codemods write to disk only when pre-flight classifier returns `safe-codemod`
+- Codemods are idempotent — running twice produces zero additional changes on the second run
+- Classifier downgrades to suggestion when token import is missing, when value appears in template/concatenation, or when multiple tokens share the value
+- Classifier ALWAYS returns suggestion for T004 + all P\* findings (no source inspection)
+- Pipeline mode reads `pipeline.driftFindings` from handoff.json; standalone mode runs detect internally
+- Pipeline mode writes `pipeline.fixesApplied` back to handoff.json
+- `--dry-run` produces identical `FixOutcome` shapes but never writes files
+- Re-running detect after align produces strictly fewer T001/T002/T003 findings
+
+## Examples
+
+### Example: Apply a T001 codemod (hex → token reference)
+
+**Input:**
+
+`design-system/tokens.json` has:
+
+```json
+{ "color": { "brand": { "primary": { "$type": "color", "$value": "#0066cc" } } } }
+```
+
+`src/Card.tsx` has:
+
+```ts
+import { tokens } from '@/design-system/tokens';
+const styles = { color: '#0066cc' }; // raw literal where token exists
+```
+
+**Output:**
+
+```
+src/Card.tsx
+  ✓ DRIFT-T001:2 — Hex color "#0066cc" should use a token reference instead of a raw literal
+     before: const styles = { color: "#0066cc" };
+     after:  const styles = { color: tokens.color.brand.primary };
+
+Summary: 1 applied, 0 suggestions, 0 skipped, 0 failed (1 files modified, 5ms)
+```
+
+### Example: Downgrade to suggestion (no token import)
+
+Same finding as above, but `src/Card.tsx` does NOT import tokens. align emits a suggestion instead:
+
+```
+src/Card.tsx
+  ? DRIFT-T001:2 — Hex color "#0066cc" should use a token reference instead of a raw literal
+
+Summary: 0 applied, 1 suggestions, 0 skipped, 0 failed (0 files modified, 3ms)
+```
+
+(Run with `--verbose` to see the suggestion text and the classifier's reason for downgrading.)
+
+### Example: Suggestion-only for DRIFT-P001
+
+**Input:**
+
+`design-system/DESIGN.md` registers `Button` in `## Component Registry`. `src/SaveButton.tsx` has:
+
+```tsx
+export const S = () => <button onClick={() => save()}>Save</button>;
+```
+
+**Output:**
+
+```
+src/SaveButton.tsx
+  ? DRIFT-P001:1 — Raw <button> element where the registered component "Button" should be used
+
+(use --verbose to see prop-translation suggestion)
+```
+
+v1 never auto-applies primitive adoption — prop translation across `<button>` ⇄ `<Button>` is the kind of judgment-call that benefits from a human or LLM review.
+
+## Gates
+
+- **No autofix without classifier approval.** Every codemod application goes through `classifyFinding`. If the classifier returns `suggestion`, NO file write occurs — even for the same finding code in the same file.
+- **No autofix when token import is missing.** Adding the import line is its own ambiguity surface (alias? barrel? relative?). v1 skips with a suggestion.
+- **No autofix for non-exact px matches.** "Round 13px to the nearest 16px" is a design decision the tool shouldn't make.
+- **No autofix for primitive adoption.** v1 has no codemod for DRIFT-P\* — always suggestions.
+- **No autofix in pipeline mode unless a `pipeline.driftFindings` field is present.** Empty handoff = empty run.
+- **No graph writes.** align modifies source files; the graph is read-only from align's perspective.
+
+## Escalation
+
+- **When a T001 finding has multiple matching tokens (ambiguous):** the classifier downgrades to suggestion. To resolve, declare a primary token in DESIGN.md `## Token Primary Resolution Overrides` (v1.x), OR pick one in the source manually and re-run.
+- **When the codemod corrupts a file (rare):** every application includes a structured diff. Recover via `git checkout <file>`. If the same input repeatedly corrupts, report the case — pre-flight classifier rules are conservative by design.
+- **When pipeline-mode run finds no `pipeline.driftFindings` field:** align exits cleanly with empty outcomes. The orchestrator's contract is to write the field BEFORE invoking align.
+- **When `--dry-run` shows fixes you don't want applied:** scope with `--files <glob>` to apply only specific files, or invoke align in pipeline mode with a curated `pipeline.fixBatch` list.
+- **When you want primitive-adoption fixes today:** apply the suggestion manually. The v1.x sub-project will add prop-translation tables + import resolution + revert-on-test-fail.
+- **When align is invoked without detect having run first (standalone mode):** standalone mode runs detect internally — no manual ordering needed. Pipeline mode trusts the orchestrator to populate findings.
+
+## Status
+
+**v1 — in implementation.** See:
+
+- Spec: `docs/changes/design-pipeline/align-design-system/proposal.md`
+- Roadmap entry: `design-pipeline sub-project #1` (align half) in `docs/roadmap.md`
+- Sibling: `detect-design-drift` (detect half — shipped PR #396)

package/dist/agents/skills/claude-code/align-design-system/skill.yaml

@@ -0,0 +1,57 @@
+name: align-design-system
+version: "0.1.0"
+description: Apply codemods for safe DRIFT-T001/T002/T003 token-bypass findings; emit precise suggestions for DRIFT-T004 (deprecated tokens) and all DRIFT-P* (primitive adoption). FIX half of design-pipeline sub-project #1; pairs with detect-design-drift.
+stability: draft
+cognitive_mode: constructive-architect
+triggers:
+  - manual
+  - on_pr
+  - on_new_feature
+platforms:
+  - claude-code
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+cli:
+  command: harness align-design-system
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: dry-run
+      description: Compute diffs without writing files
+      required: false
+    - name: files
+      description: Optional file/glob scope (standalone mode only)
+      required: false
+    - name: mode
+      description: standalone (default) or pipeline (read findings from handoff.json)
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: align-design-system
+    path: string
+type: rigid
+tier: 2
+phases:
+  - name: gather
+    description: Load drift findings (run detect-design-drift in standalone mode; read pipeline.driftFindings in pipeline mode)
+    required: true
+  - name: classify
+    description: Per-finding pre-flight check decides safe-codemod vs suggestion
+    required: true
+  - name: apply
+    description: Write codemods for safe T001/T002/T003; emit suggestions for everything else
+    required: true
+  - name: report
+    description: Emit FixOutcome[] + aggregate summary; write pipeline.fixesApplied in pipeline mode
+    required: true
+state:
+  persistent: false
+depends_on:
+  - detect-design-drift

package/dist/agents/skills/claude-code/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/claude-code/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/claude-code/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`