@harness-engineering/cli 1.6.2 → 1.8.0

package/dist/agents/personas/documentation-maintainer.yaml

@@ -1,11 +1,13 @@
 version: 1
 name: Documentation Maintainer
 description: Keeps documentation in sync with source code
-role: Detect documentation drift, validate doc coverage, align docs with code changes
+role: Detect documentation drift, validate doc coverage, align docs with code changes, run full documentation health pipeline
 skills:
   - detect-doc-drift
   - align-documentation
   - harness-knowledge-mapper
+  - validate-context-engineering
+  - harness-docs-pipeline
 commands:
   - check-docs
   - validate

package/dist/agents/personas/performance-guardian.yaml

@@ -5,6 +5,7 @@ role: Run structural complexity checks, coupling analysis, benchmark regression
 skills:
   - harness-perf
   - harness-tdd
+  - harness-perf-tdd
 commands:
   - check-perf
   - perf
@@ -20,6 +21,28 @@ config:
   severity: error
   autoFix: false
   timeout: 300000
+steps:
+  - command: validate
+    when: always
+  - command: check-deps
+    when: always
+  - command: check-perf --structural
+    when: always
+  - command: check-perf --coupling
+    when: always
+  - skill: harness-perf
+    phases: [BENCHMARK, REPORT, ENFORCE]
+    when: on_pr
+  - check: missing-benchmarks
+    when: on_pr
+missing_benchmark_detection:
+  description: Detect new/modified source files without co-located benchmarks
+  logic:
+    - step: Identify new/modified source files in the PR diff
+    - step: For each file, check if a co-located .bench.ts file exists
+    - step: "If file is on a @perf-critical path (via get_critical_paths) and has no benchmark: flag Tier 2 warning"
+    - step: "If file is not critical but is new: flag Tier 3 info suggesting harness-perf-tdd"
+    - step: 'Output example: "New file src/core/parser.ts is on a critical path but has no benchmark. Consider using harness-perf-tdd to add one."'
 outputs:
   agents-md: true
   ci-workflow: true

package/dist/agents/personas/planner.yaml

@@ -0,0 +1,27 @@
+version: 2
+name: Planner
+description: Creates executable phase plans with task breakdown and dependency analysis
+role: >
+  Create detailed implementation plans from approved specs using harness methodology.
+  Breaks work into atomic tasks with explicit file paths, dependency ordering,
+  and checkpoint placement. Writes plans and handoff context for execution.
+skills:
+  - harness-planning
+steps:
+  - command: validate
+    when: always
+  - command: check-deps
+    when: always
+  - skill: harness-planning
+    when: manual
+    output: auto
+triggers:
+  - event: manual
+config:
+  severity: error
+  autoFix: false
+  timeout: 600000
+outputs:
+  agents-md: true
+  ci-workflow: false
+  runtime-config: true

package/dist/agents/personas/verifier.yaml

@@ -0,0 +1,30 @@
+version: 2
+name: Verifier
+description: Comprehensive verification of implementation against spec and plan
+role: >
+  Verify that implementation matches the approved spec and plan using harness methodology.
+  Checks at three tiers — EXISTS (files present), SUBSTANTIVE (real implementation,
+  not stubs), and WIRED (connected to the rest of the system). Reports pass/fail
+  with evidence-based findings.
+skills:
+  - harness-verification
+steps:
+  - command: validate
+    when: always
+  - command: check-deps
+    when: always
+  - command: check-phase-gate
+    when: always
+  - skill: harness-verification
+    when: manual
+    output: auto
+triggers:
+  - event: manual
+config:
+  severity: error
+  autoFix: false
+  timeout: 600000
+outputs:
+  agents-md: true
+  ci-workflow: false
+  runtime-config: true

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

@@ -40,6 +40,19 @@ When a knowledge graph exists at `.harness/graph/`, use graph queries for faster
 
 Replaces manual doc-to-code correlation. Fall back to file-based commands if no graph is available.
 
+### Pipeline Context (when orchestrated)
+
+When invoked by `harness-docs-pipeline`, check for a `pipeline` field in `.harness/handoff.json`:
+
+- If `pipeline` field exists: read `DocPipelineContext` from it
+  - Read `pipeline.driftFindings` to know which fixes to apply (pre-classified by safety)
+  - If `pipeline.fixBatch` is set, apply only those specific fixes rather than running full detection
+  - Write applied fixes as `DocFix[]` back to `pipeline.fixesApplied`
+  - This enables the convergence loop to track fix verification status
+- If `pipeline` field does not exist: behave exactly as today (standalone mode)
+
+No changes to the skill's interface or output format — the pipeline field is purely additive.
+
 ### Phase 2: Map — Connect Code Changes to Documentation
 
 For each changed file, identify all documentation that references it:

package/dist/agents/skills/claude-code/cleanup-dead-code/SKILL.md

@@ -43,7 +43,9 @@ Graph reachability reduces false positives compared to static analysis alone, si
 
 - Exports that are not imported anywhere AND not referenced in any config file
 - Files that are not imported anywhere AND have no side effects (no top-level execution)
-- Commented-out code blocks (dead by definition)
+- Dead exports (non-public, zero importers) -- remove `export` keyword or delete entirely if zero internal callers
+- Commented-out code blocks -- delete commented block (dead by definition, code is in git history)
+- Orphaned npm dependencies -- remove from package.json (probably safe; needs install+test verification)
 - Unused local variables and imports within a file (linter can catch these)
 
 **Needs human review before removal:**
@@ -70,6 +72,28 @@ For each item categorized as safe:
 
 5. **Commit the cleanup.** Group related removals into logical commits (e.g., "remove unused shipping utilities" not "delete dead code").
 
+**New fix types:**
+
+- **Dead exports (non-public):** Use `apply_fixes` with `fixTypes: ['dead-exports']`. The tool removes the `export` keyword. If the function/class has zero internal callers too, delete the entire declaration.
+- **Commented-out code:** Use `apply_fixes` with `fixTypes: ['commented-code']`. The tool deletes commented-out code blocks. This is cosmetic and only needs lint verification.
+- **Orphaned dependencies:** Use `apply_fixes` with `fixTypes: ['orphaned-deps']`. The tool removes the dep from package.json. **Must run `pnpm install && pnpm test` after** to verify nothing breaks.
+
+### Phase 3.5: Convergence Loop (Standalone)
+
+When running standalone (not through the orchestrator), apply a single-concern convergence loop:
+
+1. **Re-run detection.** After applying all safe fixes, run `harness cleanup --type dead-code` again.
+2. **Check if issue count decreased.** Compare the new count to the previous count.
+3. **If decreased: loop.** New dead code may have been exposed by the fixes (e.g., removing a dead export made a file fully unused). Go back to Phase 2 (Categorize) with the new report.
+4. **If unchanged: stop.** No more cascading fixes are possible. Proceed to Phase 4 (Report).
+5. **Maximum iterations: 5.** To prevent infinite loops, stop after 5 convergence cycles regardless.
+
+**Why convergence matters:** Removing dead code can create more dead code. For example:
+
+- Removing a dead export may make all remaining exports in a file dead, making the file itself dead.
+- Removing a dead file removes its imports, which may make other files' exports dead.
+- Removing an orphaned dep may cause lint warnings that reveal unused imports.
+
 ### Phase 4: Report Remaining Items
 
 ### Graph Refresh

package/dist/agents/skills/claude-code/cleanup-dead-code/skill.yaml

@@ -1,6 +1,6 @@
 name: cleanup-dead-code
-version: "1.0.0"
-description: Detect unused exports and dead code
+version: "1.1.0"
+description: Detect and auto-fix dead code including dead exports, commented-out code, and orphaned dependencies
 cognitive_mode: diagnostic-investigator
 triggers:
   - manual
@@ -18,6 +18,9 @@ cli:
     - name: path
       description: Project root path
       required: false
+    - name: fix
+      description: Enable auto-fix with convergence loop
+      required: false
 mcp:
   tool: run_skill
   input:

package/dist/agents/skills/claude-code/detect-doc-drift/SKILL.md

@@ -30,6 +30,18 @@ When a knowledge graph exists at `.harness/graph/`, use graph queries for faster
 
 When a graph is available, drift is simply stale edges: doc-to-code edges where the code side has been modified more recently than the doc side. This replaces regex pattern matching and catches semantic drift that text search misses. Fall back to file-based commands if no graph is available.
 
+### Pipeline Context (when orchestrated)
+
+When invoked by `harness-docs-pipeline`, check for a `pipeline` field in `.harness/handoff.json`:
+
+- If `pipeline` field exists: read `DocPipelineContext` from it
+  - Use `pipeline.exclusions` to skip findings that were already addressed in a previous phase
+  - Write `DriftFinding[]` results back to `pipeline.driftFindings` in handoff.json
+  - This enables the orchestrator to track findings across phases and avoid double-counting
+- If `pipeline` field does not exist: behave exactly as today (standalone mode)
+
+No changes to the skill's interface or output format — the pipeline field is purely additive.
+
 ### Phase 2: Identify — Classify Drift Types
 
 Categorize each finding into one of these drift types:

package/dist/agents/skills/claude-code/enforce-architecture/SKILL.md

@@ -22,6 +22,12 @@
    - **Forbidden imports** — specific import paths that are never allowed in certain contexts
    - **Boundary definitions** — which directories/packages belong to which layer
 
+- **Design constraints** — when `design` config exists, also load design constraint rules:
+  - Token compliance — components must reference design tokens, not hardcoded values
+  - Accessibility compliance — color pairs must meet WCAG contrast ratios
+  - Anti-pattern enforcement — project-specific anti-patterns from `design-system/DESIGN.md`
+  - Platform binding — tokens must have appropriate platform bindings for enabled platforms
+
 2. **Understand the layer model.** In a typical layered architecture:
    - Higher layers depend on lower layers (UI depends on Service, Service depends on Repository)
    - Lower layers NEVER depend on higher layers (Repository must not import from UI)
@@ -58,12 +64,64 @@ For each violation, determine:
    - **Skip-layer dependency** — a layer reaches past its immediate neighbor (e.g., UI importing directly from Repository, bypassing Service). This breaks encapsulation and makes the middle layer pointless.
    - **Circular dependency** — two modules or layers depend on each other. This creates fragile coupling where changing either module risks breaking the other.
    - **Forbidden import** — a specific import that is explicitly banned (e.g., importing a database driver outside the repository layer). This prevents implementation details from leaking.
+   - **Design constraint violation** — a component uses hardcoded values instead of design tokens, or violates a declared anti-pattern. Severity depends on `design.strictness` in config. These violations surface as DESIGN-xxx codes:
+     - `DESIGN-001` [warn] — Hardcoded color/font/spacing instead of token reference
+     - `DESIGN-002` [warn] — Value matches a project anti-pattern
+     - `DESIGN-003` [error] — WCAG contrast ratio failure (error in strict mode)
+     - `DESIGN-004` [info] — Missing platform binding for enabled platform
 
 3. **Explain the impact.** For each violation, state:
    - WHY the constraint exists (what architectural property it protects)
    - WHAT would happen if the violation were allowed to persist
    - HOW it affects testability, maintainability, and changeability
 
+### Phase 3.5: Apply Safe Architecture Fixes
+
+Some architecture violations can be auto-fixed. Apply these before surfacing remaining violations.
+
+**Import ordering violations:**
+
+1. Identify files where imports are not ordered according to the project's layer convention.
+2. Reorder imports: external packages first, then by layer (lowest to highest), then relative imports.
+3. Verify with lint + typecheck. This is a safe, mechanical fix.
+
+**Forbidden import replacement (with configured alternative):**
+
+1. Check `harness.config.json` for `forbiddenImports` entries that include an `alternative` field.
+2. For each violation where an alternative exists, replace the import path with the alternative.
+3. Verify with typecheck + test. This is "probably safe" -- present as a diff for approval in interactive mode, apply silently in CI mode.
+
+**Design token substitution (unambiguous mapping):**
+
+1. When a hardcoded value has exactly one matching design token, replace the literal with the token reference.
+2. Verify with typecheck + test.
+3. If the mapping is ambiguous (multiple candidate tokens), surface to user.
+
+**Never auto-fix these (always surface to user):**
+
+- Upward dependencies
+- Skip-layer dependencies
+- Circular dependencies
+- Forbidden imports without a configured alternative
+
+### Phase 3.6: Convergence Loop (Standalone)
+
+When running standalone (not through the orchestrator), apply a single-concern convergence loop:
+
+1. **Re-run detection.** After applying all safe/probably-safe fixes, run `harness check-deps` again.
+2. **Check if violation count decreased.** Compare the new count to the previous count.
+3. **If decreased: loop.** Fixing one violation can resolve others (e.g., replacing a forbidden import may eliminate a transitive skip-layer violation). Go back to Phase 2 with the new results.
+4. **If unchanged: stop.** Proceed to Phase 4 (Guide Resolution) for remaining violations.
+5. **Maximum iterations: 5.** To prevent infinite loops.
+
+**Verification gate:** After each fix batch, run:
+
+```
+pnpm lint && pnpm tsc --noEmit && pnpm test
+```
+
+If any command fails, revert the batch and reclassify those findings as unsafe.
+
 ### Phase 4: Guide Resolution
 
 For each violation, provide a specific fix:
@@ -71,7 +129,8 @@ For each violation, provide a specific fix:
 - **Upward dependency:** Introduce an interface or abstraction in the lower layer. The higher layer implements it; the lower layer depends only on the abstraction. Alternatively, use dependency injection.
 - **Skip-layer dependency:** Route the call through the intermediate layer. Add a method to the Service layer that delegates to the Repository, then have the UI call the Service.
 - **Circular dependency:** Break the cycle by extracting shared types into a common module that both can depend on, or restructure so the dependency flows in one direction only.
-- **Forbidden import:** Replace the forbidden import with the approved alternative. If no alternative exists, the feature may need to live in a different layer.
+- **Forbidden import:** Check `harness.config.json` for an `alternative` field. If present, this should have been auto-fixed in Phase 3.5. If not present, replace the forbidden import with the approved alternative or restructure the code.
+- **Design constraint violation:** Replace hardcoded values with token references from `design-system/tokens.json`. For anti-pattern violations, consult `design-system/DESIGN.md` for the project's aesthetic intent and approved alternatives. For contrast failures, use `harness-accessibility` to find compliant color pairs.
 
 ## Common Violation Patterns
 
@@ -87,6 +146,10 @@ Two layers both need the same type definition. Fix: place shared types in the lo
 
 Test helpers import across layer boundaries for convenience. Fix: each layer's tests should only import from that layer and below. Test utilities should follow the same constraints as production code.
 
+### Pattern: "Hardcoded colors in components"
+
+A component uses `#3b82f6` directly instead of referencing `color.primary` from the design token system. Fix: import and reference the token. In Tailwind: use the token-mapped utility class. In CSS: use the custom property `var(--color-primary)`.
+
 ### Pattern: "Circular dependency through re-exports"
 
 Module A re-exports from Module B, and Module B imports from Module A. The circular dependency is hidden by the re-export. Fix: identify the true dependency direction and remove the reverse path.
@@ -96,6 +159,9 @@ Module A re-exports from Module B, and Module B imports from Module A. The circu
 - **`harness check-deps`** — Primary tool. Analyzes all imports against the layer model defined in `harness.config.json`. Returns structured violation data including file, line, source layer, target layer, and rule violated.
 - **`harness check-deps --json`** — Machine-readable output for automated pipelines. Use this when parsing results programmatically.
 - **`harness validate`** — Includes dependency checking as part of full project validation. Use when you want a complete health check, not just architecture.
+- **`harness-design-system`** — Provides the design token source of truth (`tokens.json`) that constraints validate against.
+- **`harness-accessibility`** — Provides WCAG contrast validation used by DESIGN-003 constraints.
+- **Design constraint category** — Controlled by `design.strictness` in `harness.config.json`. Design violations surface alongside architectural violations in the same report.
 
 ## Success Criteria
 

package/dist/agents/skills/claude-code/enforce-architecture/skill.yaml

@@ -1,6 +1,6 @@
 name: enforce-architecture
-version: "1.0.0"
-description: Validate architectural layer boundaries and detect circular dependencies
+version: "1.1.0"
+description: Validate architectural layer boundaries, detect violations, and auto-fix import ordering and forbidden import replacement
 cognitive_mode: meticulous-verifier
 triggers:
   - manual
@@ -19,6 +19,9 @@ cli:
     - name: path
       description: Project root path
       required: false
+    - name: fix
+      description: Enable auto-fix with convergence loop
+      required: false
 mcp:
   tool: run_skill
   input:

package/dist/agents/skills/claude-code/harness-accessibility/SKILL.md

@@ -0,0 +1,281 @@
+# Harness Accessibility
+
+> WCAG compliance verification and remediation. Scan components for accessibility violations, evaluate severity against design strictness, generate actionable reports, and apply automated fixes for mechanical issues.
+
+## When to Use
+
+- Auditing new or existing UI components for WCAG AA accessibility compliance
+- Before PR merge to catch accessibility regressions in UI changes
+- When `on_new_feature` triggers fire and the feature includes UI components
+- When design tokens change (color updates may break contrast compliance)
+- After running harness-design-system to validate the generated palette
+- When `on_project_init` triggers fire to establish an accessibility baseline
+- NOT for design token generation or palette selection (use harness-design-system)
+- NOT for visual design review or aesthetic direction (use harness-design, Phase 4)
+- NOT for non-UI code (backend services, CLI tools, data pipelines)
+
+## Process
+
+### Phase 1: SCAN -- Detect Accessibility Violations
+
+1. **Load design tokens.** Read `design-system/tokens.json` (if it exists) to identify declared color values and contrast pairs. Token-defined colors are the source of truth -- hardcoded colors in components are themselves a violation.
+
+2. **Read design strictness.** Check `harness.config.json` for `design.strictness`:
+   - `strict` -- all findings are errors that block (CI fails, PR cannot merge)
+   - `standard` -- warnings are visible, errors block (default behavior)
+   - `permissive` -- all findings are informational (nothing blocks, but everything is reported)
+
+2.5. **Check for i18n skill overlap.** Read `harness.config.json` for `i18n.enabled`:
+
+- If `i18n.enabled: true`, **defer** `lang` and `dir` attribute checks to `harness-i18n`. Do not scan for missing `lang` on `<html>` or missing `dir` on user-content containers -- those checks are covered by the i18n skill's scan phase with more context (locale-aware, RTL-aware).
+- 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.
+
+3. **Scan component files.** Search all files matching `.tsx`, `.jsx`, `.vue`, `.svelte`, `.html` for the following violations:
+
+   **Images and media:**
+   - `<img>` tags without `alt` attribute (`A11Y-001`)
+   - `<img>` tags with empty `alt=""` on non-decorative images (`A11Y-002`)
+   - `<video>` and `<audio>` without captions/transcripts (`A11Y-003`)
+
+   **ARIA and semantics:**
+   - Interactive elements (`<button>`, `<a>`, `<input>`) without accessible labels (`A11Y-010`)
+   - Icon-only buttons without `aria-label` or visually hidden text (`A11Y-011`)
+   - Clickable `<div>` or `<span>` without `role="button"` and keyboard handler (`A11Y-012`)
+   - Missing `role` attributes on custom interactive widgets (`A11Y-013`)
+   - `aria-hidden="true"` on focusable elements (`A11Y-014`)
+
+   **Heading structure:**
+   - Non-sequential heading levels (e.g., `<h1>` followed by `<h3>`, skipping `<h2>`) (`A11Y-020`)
+   - Multiple `<h1>` elements on a single page/component (`A11Y-021`)
+   - Empty headings (`A11Y-022`)
+
+   **Color and contrast:**
+   - Hardcoded color values not from the token set (`A11Y-030`)
+   - Inline styles with color/background-color that may fail contrast (`A11Y-031`)
+
+   **Keyboard navigation:**
+   - `onClick` handlers without corresponding `onKeyDown`/`onKeyUp` (`A11Y-040`)
+   - Missing `tabIndex` on custom interactive elements (`A11Y-041`)
+   - Positive `tabIndex` values (disrupts natural tab order) (`A11Y-042`)
+   - Missing focus indicators (`:focus` or `:focus-visible` styles) (`A11Y-043`)
+
+   **Forms:**
+   - `<input>`, `<select>`, `<textarea>` without associated `<label>` or `aria-label` (`A11Y-050`)
+   - Missing `id` attributes on form controls (needed for label association) (`A11Y-051`)
+   - Missing error messages or `aria-invalid` on validation states (`A11Y-052`)
+
+4. **Load anti-pattern catalogs.** Read additional detection rules from `agents/skills/shared/design-knowledge/` if available. These catalogs contain industry-specific accessibility patterns (e.g., healthcare forms require higher contrast, fintech requires screen reader-compatible data tables).
+
+5. **Record all findings.** Each finding includes:
+   - File path
+   - Line number (approximate, from Grep output)
+   - Violation code (e.g., `A11Y-001`)
+   - Element or pattern that triggered the finding
+   - Raw evidence (the matching line of code)
+
+### Phase 2: EVALUATE -- Assess Severity and Categorize
+
+1. **Assign severity based on `design.strictness`:**
+   - `strict` mode: all violations are `error` severity
+   - `standard` mode: missing alt, missing labels, contrast failures are `error`; heading order, tabIndex are `warn`; informational patterns are `info`
+   - `permissive` mode: contrast failures and missing labels are `warn`; everything else is `info`
+
+2. **Calculate contrast ratios.** For every color pair found in scanned code:
+   - Extract foreground and background colors (from inline styles, class mappings, or token references)
+   - Calculate relative luminance for each color using the WCAG 2.1 formula:
+     - `L = 0.2126 * R + 0.7152 * G + 0.0722 * B` (where R, G, B are linearized sRGB values)
+   - Calculate contrast ratio: `(L1 + 0.05) / (L2 + 0.05)` where L1 is the lighter color
+   - Compare against thresholds:
+     - Normal text (< 18px regular, < 14px bold): 4.5:1 minimum (WCAG AA)
+     - Large text (>= 18px regular, >= 14px bold): 3:1 minimum (WCAG AA)
+
+3. **Cross-reference with design tokens.** If `design-system/tokens.json` exists:
+   - Map hardcoded colors in code to their nearest token equivalents
+   - If a token-based color pair fails contrast, flag the **token definition** (not just the component usage) -- the fix belongs in harness-design-system, not here
+   - If a hardcoded color fails contrast, flag both the contrast issue and the non-token usage
+
+4. **Check graph constraints.** If a graph exists at `.harness/graph/`, use `DesignConstraintAdapter` from `packages/graph/src/constraints/DesignConstraintAdapter.ts` to:
+   - Query for existing `VIOLATES` edges (violations already recorded in the graph)
+   - Add new `VIOLATES` edges for findings from this scan
+   - The adapter reads `design.strictness` to control which violations produce edges
+
+5. **Categorize findings.** Group into categories:
+   - **Contrast** (A11Y-030, A11Y-031): color-related violations
+   - **ARIA** (A11Y-010 through A11Y-014): attribute and role violations
+   - **Semantics** (A11Y-020 through A11Y-022): heading and structure violations
+   - **Keyboard** (A11Y-040 through A11Y-043): navigation and focus violations
+   - **Forms** (A11Y-050 through A11Y-052): form control violations
+   - **Media** (A11Y-001 through A11Y-003): image, video, audio violations
+
+### Phase 3: REPORT -- Generate Accessibility Report
+
+1. **Generate summary header:**
+
+   ```
+   Accessibility Report
+   ====================
+   Scanned:    42 component files
+   Findings:   18 total (6 error, 8 warn, 4 info)
+   Strictness: standard
+   ```
+
+2. **List findings grouped by category.** Each finding follows this format:
+
+   ```
+   A11Y-001 [error] Missing alt attribute on <img>
+     File:      src/components/UserAvatar.tsx
+     Line:      24
+     Element:   <img src={user.avatarUrl} className="avatar" />
+     WCAG:      1.1.1 Non-text Content
+     Fix:       Add alt={user.name} or alt="" if decorative
+   ```
+
+   ```
+   A11Y-031 [error] Contrast ratio 2.8:1 fails WCAG AA (requires 4.5:1)
+     File:      src/components/Button.tsx
+     Line:      15
+     Element:   color: #999 on background: #fff
+     WCAG:      1.4.3 Contrast (Minimum)
+     Fix:       Use color token "neutral.600" (#475569, ratio 4.9:1) instead
+   ```
+
+3. **Provide category summaries** with counts and severity breakdown.
+
+4. **List actionable next steps:**
+   - Errors that can be auto-fixed (Phase 4)
+   - Errors that require human judgment
+   - Warnings to address in next iteration
+   - Token-level issues to escalate to harness-design-system
+
+### Phase 4: FIX -- Apply Automated Remediation (Optional)
+
+This phase is optional. It applies fixes only for **mechanical issues** -- violations with a single, unambiguous correct fix. Subjective issues (color choices, layout decisions, content writing) are never auto-fixed.
+
+1. **Fixable violations:**
+   - `A11Y-001`: Add `alt=""` to `<img>` tags that are decorative (inside `<button>`, `<a>`, or with `role="presentation"`)
+   - `A11Y-011`: Add `aria-label` to icon-only `<button>` elements (using the icon name as label)
+   - `A11Y-012`: Add `role="button"` and `tabIndex={0}` to clickable `<div>` elements
+   - `A11Y-041`: Add `tabIndex={0}` to custom interactive elements missing it
+   - `A11Y-051`: Generate `id` attributes for form controls and link them to labels
+
+2. **Apply each fix as a minimal, targeted edit.** Use the Edit tool. Do not refactor surrounding code. Do not change formatting. The fix should be the smallest possible change that resolves the violation.
+
+3. **Show before/after diff for each fix.** Present the exact change to the user. This is a hard gate -- no fix is applied without showing the diff first.
+
+4. **Re-scan after fixes.** Run the scan phase again on fixed files to confirm violations are resolved. Report:
+   - Fixes applied: N
+   - Violations resolved: N
+   - Remaining violations (require human judgment): M
+
+5. **Do NOT fix:**
+   - Color choices (subjective -- escalate to harness-design-system)
+   - Content for alt text on meaningful images (requires human judgment about image meaning)
+   - Layout and heading structure changes (may affect design intent)
+   - Any fix that would change the visual appearance of the component
+
+## Harness Integration
+
+- **`harness validate`** -- Accessibility findings surface as design constraint violations when `design.strictness` is `strict` or `standard`. Running validate after a scan reflects the current a11y state.
+- **`harness scan`** -- Refresh the knowledge graph after fixes to update `VIOLATES` edges. Ensures impact analysis stays current.
+- **`DesignConstraintAdapter`** (`packages/graph/src/constraints/DesignConstraintAdapter.ts`) -- Reads `design.strictness` from project config to control violation severity. Manages `VIOLATES` edges in the graph for design and accessibility constraints.
+- **`DesignIngestor`** (`packages/graph/src/ingest/DesignIngestor.ts`) -- Provides token data used for contrast checking. The ingestor parses `tokens.json` so the accessibility scanner can compare code colors against declared tokens.
+- **`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.
+
+## Success Criteria
+
+- All scanned component files have findings categorized by severity (`error`, `warn`, `info`)
+- Contrast failures detected with correct ratios and WCAG criterion references
+- Missing ARIA attributes flagged with specific file paths and line numbers
+- Non-sequential heading hierarchy violations identified
+- Keyboard navigation gaps (missing handlers, broken tab order) detected
+- Form accessibility issues (missing labels, missing error states) found
+- Report generated with violation codes, WCAG references, and actionable remediation
+- Automated fixes applied without breaking existing functionality or tests
+- `harness validate` reflects accessibility findings at the configured strictness level
+- Token-level contrast issues escalated to harness-design-system (not fixed locally)
+
+## Examples
+
+### Example: Scanning a React Dashboard Component
+
+**Context:** A React component `DashboardCard.tsx` with known accessibility issues.
+
+**Source file:**
+
+```tsx
+// src/components/DashboardCard.tsx
+export function DashboardCard({ title, value, icon, onClick }) {
+  return (
+    <div className="card" onClick={onClick}>
+      <img src={icon} />
+      <h3>{title}</h3>
+      <span style={{ color: '#999', fontSize: '14px' }}>{value}</span>
+    </div>
+  );
+}
+```
+
+**SCAN findings:**
+
+```
+A11Y-001 [error] Missing alt attribute on <img>
+  File:    src/components/DashboardCard.tsx
+  Line:    5
+  Element: <img src={icon} />
+  WCAG:    1.1.1 Non-text Content
+
+A11Y-012 [error] Clickable <div> without role="button" and keyboard handler
+  File:    src/components/DashboardCard.tsx
+  Line:    4
+  Element: <div className="card" onClick={onClick}>
+  WCAG:    2.1.1 Keyboard
+
+A11Y-031 [warn] Contrast ratio 2.8:1 for #999 on #fff fails WCAG AA
+  File:    src/components/DashboardCard.tsx
+  Line:    7
+  Element: <span style={{ color: '#999' }}>
+  WCAG:    1.4.3 Contrast (Minimum)
+  Note:    Hardcoded color -- not from token set
+
+A11Y-030 [info] Hardcoded color value not from design token set
+  File:    src/components/DashboardCard.tsx
+  Line:    7
+  Element: color: '#999'
+```
+
+**FIX phase (auto-fixable only):**
+
+```diff
+- <img src={icon} />
++ <img src={icon} alt="" />
+
+- <div className="card" onClick={onClick}>
++ <div className="card" role="button" tabIndex={0} onClick={onClick} onKeyDown={(e) => { if (e.key === 'Enter' || e.key === ' ') onClick?.(); }}>
+```
+
+**Remaining (requires human judgment):**
+
+- `A11Y-031`: Contrast failure -- fix requires choosing a darker color. Escalate to design tokens or get human input on replacement color.
+- `A11Y-001`: The `alt=""` fix assumes decorative. If the icon conveys meaning, human must write descriptive alt text.
+
+## Gates
+
+These are hard stops. Violating any gate means the process has broken down.
+
+- **No component marked "accessible" without passing WCAG AA contrast checks.** A passing scan means zero `error`-severity contrast violations, not zero findings overall.
+- **No automated fix applied without showing the before/after diff.** Every fix must be presented to the user with the exact code change before being written to disk.
+- **No severity downgrade below what `design.strictness` config specifies.** If the project is in `strict` mode, a missing alt attribute is an error. The scanner does not get to decide it is a warning.
+- **The scan phase must complete before evaluate.** No partial evaluations on incomplete scan results. All files must be scanned before severity assignment begins.
+- **No fixes that change visual appearance.** Automated fixes are structural (adding attributes, roles, handlers). If a fix would visibly change the rendered output, it requires human approval.
+
+## Escalation
+
+- **When contrast ratio is borderline (4.5:1 to 5:1):** Flag for human review rather than auto-passing. Report: "Contrast ratio 4.6:1 technically passes WCAG AA but is borderline. Consider using a higher-contrast alternative for better readability."
+- **When a component has more than 10 findings:** Suggest architectural refactoring rather than piecemeal fixes. The component likely has systemic accessibility issues that individual fixes will not adequately address. Recommend: "This component has 14 accessibility findings. Consider refactoring to use accessible base components rather than fixing each issue individually."
+- **When design tokens themselves have contrast failures:** Do not fix at the usage site. Escalate to harness-design-system: "Token pair primary-500 on neutral-50 has contrast ratio 3.2:1. This must be fixed in design-system/tokens.json, not in individual components. Run harness-design-system to update the palette."
+- **When automated fix would change visual appearance:** Require explicit human approval. Present the fix with a note: "This fix changes the rendered output. The current <div> will become keyboard-focusable with a visible focus ring. Approve this change?"
+- **When `design.strictness` is not configured:** Default to `standard` mode. Report: "No design.strictness found in harness.config.json. Using 'standard' (warnings visible, errors block). Set design.strictness in config to customize."
+- **After 3 failed attempts to resolve a contrast issue:** The color pair may be fundamentally incompatible. Suggest: "Consider using a different color combination. The current pair cannot achieve WCAG AA compliance without changing one of the colors significantly."