@harness-engineering/cli 1.6.2 → 1.8.0

package/dist/agents/skills/claude-code/harness-soundness-review/skill.yaml

@@ -0,0 +1,48 @@
+name: harness-soundness-review
+version: "1.0.0"
+description: Deep soundness analysis of specs and plans with auto-fix and convergence loop
+cognitive_mode: meticulous-verifier
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-soundness-review
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: mode
+      description: Review mode — "spec" for spec soundness or "plan" for plan soundness
+      required: true
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-soundness-review
+    path: string
+type: rigid
+phases:
+  - name: check
+    description: Run all checks for the current mode and classify findings
+    required: true
+  - name: fix
+    description: Auto-fix inferrable issues and log changes
+    required: true
+  - name: converge
+    description: Re-run checks, compare issue counts, loop or stop
+    required: true
+  - name: surface
+    description: Present remaining issues to user for resolution
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on: []

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

@@ -13,8 +13,23 @@
 
 ## Prerequisites
 
-A knowledge graph must exist at `.harness/graph/`. Run `harness scan` if no graph is available.
-If the graph exists but code has changed since the last scan, re-run `harness scan` first — stale graph data leads to inaccurate results.
+A knowledge graph at `.harness/graph/` enables full analysis. If no graph exists,
+the skill uses static analysis fallbacks (see Graph Availability section).
+Run `harness scan` to enable graph-enhanced analysis.
+
+### Graph Availability
+
+Before starting, check if `.harness/graph/graph.json` exists.
+
+**If graph exists:** Check staleness — compare `.harness/graph/metadata.json`
+scanTimestamp against `git log -1 --format=%ct` (latest commit timestamp).
+If graph is more than 10 commits behind (`git log --oneline <scanTimestamp>..HEAD | wc -l`),
+run `harness scan` to refresh before proceeding. (Staleness sensitivity: **Medium**)
+
+**If graph exists and is fresh (or refreshed):** Use graph tools as primary strategy.
+
+**If no graph exists:** Output "Running without graph (run `harness scan` to
+enable full analysis)" and use fallback strategies for all subsequent steps.
 
 ## Process
 
@@ -43,6 +58,20 @@ For each changed file, use graph traversal to find test files:
 
 3. **Co-change tests**: Check `co_changes_with` edges for test files that historically change alongside the modified files.
 
+#### Fallback (without graph)
+
+When no graph is available, use naming conventions, import parsing, and git history:
+
+1. **Tier 1 — Filename convention matching**: For each changed file `foo.ts`, search for:
+   - `foo.test.ts`, `foo.spec.ts` (same directory)
+   - `__tests__/foo.ts`, `__tests__/foo.test.ts`
+   - Test files in a parallel `tests/` directory mirroring the source path
+2. **Tier 2 — Import-linked tests**: Parse test files' import statements (grep for `import.*from` in `*.test.*` and `*.spec.*` files). If a test file imports the changed file, it belongs in Tier 2 (if not already in Tier 1).
+3. **Tier 3 — Co-change correlated tests**: Use `git log --format="%H" --name-only` to find test files that frequently change in the same commit as the target file. Files that co-change in >2 commits are co-change correlated.
+4. **Rank**: Tier 1 = direct filename match, Tier 2 = import-linked tests, Tier 3 = co-change correlated tests. Output the same tiered format as the graph version.
+
+> Fallback completeness: ~80% — naming conventions and imports catch most mappings; misses dynamic imports and indirect coverage.
+
 ### Phase 3: PRIORITIZE — Rank and Generate Commands
 
 Organize tests into three tiers:
@@ -85,7 +114,7 @@ npx vitest run tests/services/auth.test.ts tests/types/user.test.ts tests/routes
 
 ## Harness Integration
 
-- **`harness scan`** — Must run before this skill to ensure graph is current.
+- **`harness scan`** — Recommended before this skill for full graph-enhanced analysis. If graph is missing, skill uses naming convention and import parsing fallbacks.
 - **`harness validate`** — Run after acting on findings to verify project health.
 - **Graph tools** — This skill uses `query_graph`, `get_impact`, and `get_relationships` MCP tools.
 
@@ -95,7 +124,7 @@ npx vitest run tests/services/auth.test.ts tests/types/user.test.ts tests/routes
 - Executable run commands generated for quick and full test runs
 - Coverage gaps flagged for changed files with no test coverage
 - Report follows the structured output format
-- All findings are backed by graph query evidence, not heuristics
+- All findings are backed by graph query evidence (with graph) or systematic static analysis (without graph)
 
 ## Examples
 
@@ -122,8 +151,8 @@ Output:
 
 ## Gates
 
-- **No advice without graph.** If no graph exists, fall back to: "Run all tests in the same directory as changed files."
-- **Always include Tier 1.** Direct test coverage is non-negotiable — always recommend running these.
+- **Graph preferred, fallback available.** If no graph exists, use naming conventions, import parsing, and git co-change analysis to identify relevant tests. Do not stop — produce the best test selection possible.
+- **Always include Tier 1.** Direct test coverage is non-negotiable — always recommend running these (whether found via graph or naming conventions).
 
 ## Escalation
 

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

@@ -160,6 +160,70 @@ After running all three levels, produce a structured gap report:
 ### Verdict: INCOMPLETE — 2 gaps must be resolved
 ```
 
+The verification report uses conventional markdown patterns for structured output:
+
+```
+**[CRITICAL]** path/to/file.ts:22 — TODO: implement validation (anti-pattern)
+**[IMPORTANT]** path/to/file.ts — exported but not imported by any other file
+```
+
+### Verification Sign-Off
+
+After producing the verification report, request acceptance:
+
+```json
+emit_interaction({
+  path: "<project-root>",
+  type: "confirmation",
+  confirmation: {
+    text: "Verification report: <VERDICT>. Accept and proceed?",
+    context: "<summary: N artifacts checked, N gaps found>"
+  }
+})
+```
+
+### Handoff and Transition
+
+After producing the verification report, write the handoff and conditionally transition:
+
+Write `.harness/handoff.json`:
+
+```json
+{
+  "fromSkill": "harness-verification",
+  "phase": "COMPLETE",
+  "summary": "<verdict summary>",
+  "artifacts": ["<verified file paths>"],
+  "verdict": "pass | fail",
+  "gaps": ["<gap descriptions if any>"]
+}
+```
+
+**If verdict is PASS (all levels passed, no gaps):**
+
+Call `emit_interaction`:
+
+```json
+{
+  "type": "transition",
+  "transition": {
+    "completedPhase": "verification",
+    "suggestedNext": "review",
+    "reason": "Verification passed at all 3 levels",
+    "artifacts": ["<verified file paths>"],
+    "requiresConfirmation": false,
+    "summary": "Verification passed: <N> artifacts checked. EXISTS, SUBSTANTIVE, WIRED all passed."
+  }
+}
+```
+
+The response will include `nextAction: "Invoke harness-code-review skill now"`.
+Immediately invoke harness-code-review without waiting for user input.
+
+**If verdict is FAIL or INCOMPLETE:**
+
+Do NOT emit a transition. Surface gaps to the user for resolution. The handoff is written with the gaps recorded for future reference.
+
 ---
 
 ### Regression Test Verification
@@ -184,6 +248,8 @@ If step 4 passes (test does not fail without the fix), the test is not a valid r
 
 All commands must be run fresh in the current session. Do not rely on results from a previous session or a previous run in the same session if code has changed since.
 
+- **`emit_interaction`** -- Call after verification passes to auto-transition to harness-code-review. Only emitted on PASS verdict. Uses auto-transition (proceeds immediately).
+
 ## Success Criteria
 
 - Every claimed deliverable has been verified at all 3 levels

package/dist/agents/skills/claude-code/harness-verification/skill.yaml

@@ -13,6 +13,7 @@ tools:
   - Bash
   - Read
   - Glob
+  - emit_interaction
 cli:
   command: harness skill run harness-verification
   args:

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

@@ -48,6 +48,20 @@ Rules:
 - Run each command from the project root directory.
 - Do not modify any files. Do not install dependencies. Do not fix errors.
 
+### Design Constraint Check (conditional)
+
+When `harness.config.json` contains a `design` block:
+
+1. **Run design constraint checks** by invoking `harness-accessibility` in scan+evaluate mode against the project.
+2. Apply the `design.strictness` setting to determine severity:
+   - `strict`: accessibility violations are FAIL; anti-pattern violations are WARN
+   - `standard`: accessibility and anti-pattern violations are WARN; nothing blocks
+   - `permissive`: all design violations are INFO
+3. Capture the result as `Design: [PASS/WARN/FAIL/SKIPPED]`.
+4. If no `design` block exists in config, mark Design as `SKIPPED`.
+
+The design check runs AFTER test/lint/typecheck. It does not short-circuit on earlier failures.
+
 ### Phase 3: REPORT
 
 Output a structured result in this exact format:
@@ -59,12 +73,32 @@ Verification: [PASS/FAIL]
 - Test:      [PASS/FAIL/SKIPPED]
 ```
 
+When design config is present, include the design line:
+
+```
+Verification: [PASS/FAIL]
+- Typecheck: [PASS/FAIL/SKIPPED]
+- Lint:      [PASS/FAIL/SKIPPED]
+- Test:      [PASS/FAIL/SKIPPED]
+- Design:    [PASS/WARN/FAIL/SKIPPED]
+```
+
 Rules:
 
 - Overall `Verification: PASS` only if all non-skipped checks passed.
 - If all checks are SKIPPED, overall result is `PASS` (nothing to fail).
 - On FAIL, include a brief summary of what failed (e.g., "3 type errors", "2 lint errors", "5 tests failed") below the structured block.
 
+### Roadmap Sync (conditional)
+
+When all non-skipped checks pass (overall `Verification: PASS`) and `docs/roadmap.md` exists:
+
+1. Trigger a roadmap sync to update feature statuses based on the verified state.
+2. Use the `manage_roadmap` MCP tool with `sync` action if available, or note to the caller that a roadmap sync is recommended.
+3. Features linked to plans whose tasks are all complete and verified may be marked as `done`.
+
+If `docs/roadmap.md` does not exist, skip this step silently. If verification failed, do not sync — the roadmap should only reflect verified completions.
+
 ## Deterministic Checks
 
 This skill is entirely deterministic. There are no LLM judgment calls anywhere in the process.
@@ -80,6 +114,9 @@ This skill is entirely deterministic. There are no LLM judgment calls anywhere i
 - Invoked as the final step by code-producing skills (harness-execution, harness-tdd)
 - Complements harness-verification (deep audit) — use verify for quick checks, verification for milestones
 - Output format is consumed by harness-integrity for the unified pipeline
+- Invokes `harness-accessibility` for design constraint checking when `design` config exists
+- Design violations respect `design.strictness` from `harness.config.json`
+- **Roadmap sync** — When verification passes and `docs/roadmap.md` exists, triggers `manage_roadmap sync` to mark verified features as `done`. Only fires on overall PASS.
 
 ## Success Criteria
 

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

@@ -59,6 +59,11 @@
 
 4. **For advanced:** Configure state management (`.harness/state.json` schema), learnings capture (`.harness/learnings.md` conventions), and CI integration hooks.
 
+5. **Configure i18n (all levels).** Ask: "Will this project support multiple languages?" Based on the answer:
+   - **Yes:** Invoke `harness-i18n-workflow` configure phase to set up i18n config in `harness.config.json` (source locale, target locales, framework, strictness). Then invoke `harness-i18n-workflow` scaffold phase to create translation file structure and extraction config. Set `i18n.enabled: true`.
+   - **No:** Set `i18n.enabled: false` in `harness.config.json`. The `harness-i18n-process` skill will still fire gentle prompts for unconfigured projects when features touch user-facing strings.
+   - **Not sure yet:** Skip i18n configuration entirely. Do not set `i18n.enabled`. The project can enable i18n later by running `harness-i18n-workflow` directly.
+
 ### Phase 4: VALIDATE — Confirm Everything Works
 
 1. **Run `harness validate`** to verify the full configuration. This checks:
@@ -82,7 +87,9 @@ harness scan [path]
 
 This creates the `.harness/graph/` directory and populates it with the project's dependency and relationship data. Subsequent graph queries (impact analysis, dependency health, test advisor) depend on this initial scan.
 
-4. **Commit the initialization.** All generated and configured files in a single commit.
+4. **Mention roadmap.** After validation passes, inform the user: "When you are ready to set up a project roadmap, run `/harness:roadmap --create`. This creates a unified `docs/roadmap.md` that tracks features, milestones, and status across your specs and plans." This is informational only — do not create the roadmap automatically.
+
+5. **Commit the initialization.** All generated and configured files in a single commit.
 
 ## Harness Integration
 
@@ -91,6 +98,8 @@ This creates the `.harness/graph/` directory and populates it with the project's
 - **`harness persona generate`** — Generate persona definitions based on project stack and team structure.
 - **`harness validate`** — Verify the full project configuration is valid and complete.
 - **`harness check-deps`** — Verify dependency constraints match the actual codebase (intermediate and above).
+- **`harness-i18n-workflow configure` + `harness-i18n-workflow scaffold`** — Invoked during Phase 3 if the project will support multiple languages. Sets up i18n configuration and translation file structure.
+- **Roadmap nudge** — After successful initialization, inform the user about `/harness:roadmap --create` for setting up project-level feature tracking. Informational only; does not create the roadmap.
 
 ## Success Criteria
 
@@ -102,6 +111,7 @@ This creates the `.harness/graph/` directory and populates it with the project's
 - Personas are configured if the project uses them
 - The adoption level matches what was agreed upon with the human
 - All generated files are committed in a single atomic commit
+- i18n configuration is set if the human chose to enable it during init
 
 ## Examples
 
@@ -131,6 +141,10 @@ Edit AGENTS.md:
   - Add stack: TypeScript, Express, Vitest, PostgreSQL
   - Add conventions: "Use zod for validation, repository pattern for data access"
   - Add constraints: "No direct SQL queries outside repository layer"
+  - Ask: "Will this project support multiple languages?"
+  - Human: "Yes, Spanish and French."
+  - Run harness-i18n-workflow configure (source: en, targets: es, fr)
+  - Run harness-i18n-workflow scaffold (creates locales/ directory structure)
 ```
 
 **VALIDATE:**

package/dist/agents/skills/claude-code/validate-context-engineering/SKILL.md

@@ -32,6 +32,18 @@ When a knowledge graph exists at `.harness/graph/`, use graph queries for faster
 
 When a graph is available, it IS the source of truth for documentation coverage. Drift = stale or missing edges between code and doc nodes. 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 the FIX phase
+  - Write `GapFinding[]` results back to `pipeline.gapFindings` in handoff.json
+  - This enables dedup across FIX and AUDIT phases
+- 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: Detect Gaps
 
 Categorize findings into four types:

package/dist/agents/skills/gemini-cli/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."