@skilly-hand/skilly-hand 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -16,6 +16,36 @@ All notable changes to this project are documented in this file.
 ### Removed
 - _None._
 
+## [0.7.0] - 2026-04-04
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.7.0)
+
+### Added
+- _None._
+
+### Changed
+- _None._
+
+### Fixed
+- _None._
+
+### Removed
+- _None._
+
+## [0.6.1] - 2026-04-04
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.6.1)
+
+### Added
+- _None._
+
+### Changed
+- _None._
+
+### Fixed
+- _None._
+
+### Removed
+- _None._
+
 ## [0.6.0] - 2026-04-03
 [View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.6.0)
 

package/README.md

@@ -65,6 +65,7 @@ npx skilly-hand
 
 The catalog currently includes:
 
+- `accessibility-audit`
 - `agents-root-orchestrator`
 - `angular-guidelines`
 - `figma-mcp-0to1`

package/catalog/README.md

@@ -4,6 +4,7 @@ Published portable skills consumed by the `skilly-hand` CLI.
 
 | Skill | Description | Tags | Installs For |
 | ----- | ----------- | ---- | ------------ |
+| `accessibility-audit` | Audit web accessibility against W3C WCAG 2.2 Level AA using framework-agnostic checks, remediation patterns, and portable command-line scanning. | frontend, accessibility, workflow, quality | all |
 | `agents-root-orchestrator` | Author root AGENTS.md as a Where/What/When orchestrator that routes tasks and skill invocation clearly. | core, workflow, orchestration | all |
 | `angular-guidelines` | Guide Angular code generation and review using latest stable Angular verification and modern framework best practices. | angular, frontend, workflow, best-practices | all |
 | `figma-mcp-0to1` | Guide users from Figma MCP installation and authentication through first canvas creation, with function-level tool coverage and operational recovery patterns. | figma, mcp, workflow, design | all |

package/catalog/catalog-index.json

@@ -1,4 +1,5 @@
 [
+  "accessibility-audit",
   "agents-root-orchestrator",
   "angular-guidelines",
   "figma-mcp-0to1",

package/catalog/skills/accessibility-audit/SKILL.md

@@ -0,0 +1,154 @@
+# Accessibility Audit Guide
+
+## When to Use
+
+Use this skill when:
+
+- Auditing components or pages for WCAG conformance.
+- Reviewing pull requests that change templates, interactive UI, forms, or styles.
+- Defining accessibility acceptance criteria for frontend delivery.
+- Converting automated scanner findings into prioritized remediations.
+
+Do not use this skill for:
+
+- Product-specific visual token compliance.
+- Framework-only code style reviews unrelated to accessibility behavior.
+- Non-web formats that need a dedicated standard beyond WCAG web content checks.
+
+---
+
+## Baseline and Sources
+
+Default baseline:
+
+- **WCAG 2.2 Level AA**.
+
+W3C status notes (verified from W3C WCAG overview):
+
+- WCAG 2.2 was published on **5 October 2023** and updated on **12 December 2024**.
+- W3C encourages using the latest WCAG version.
+
+Use only W3C sources for decisions and remediation rationale.
+
+---
+
+## Critical Patterns
+
+### Pattern 1: Audit in POUR Order
+
+Audit checks in this order to reduce misses:
+
+1. **Perceivable**: text alternatives, structure, contrast.
+2. **Operable**: keyboard, focus, target size, predictable interaction.
+3. **Understandable**: labels, errors, language, clear behavior.
+4. **Robust**: semantic roles/states and assistive-technology compatibility.
+
+### Pattern 2: Prefer Native Semantics First
+
+- Use native controls (`button`, `a`, `input`, `select`, `textarea`) before ARIA-heavy custom widgets.
+- If custom widgets are necessary, define role, keyboard behavior, name, state, and relationship.
+- Never remove focus indicators without a visible replacement.
+
+### Pattern 3: Prioritize by User Impact
+
+Fix in this order:
+
+1. Keyboard and focus blockers.
+2. Missing names/labels for controls and media.
+3. Form errors and status announcements.
+4. Contrast and non-text contrast issues.
+
+### Pattern 4: Validate with W3C Tooling
+
+Use W3C validators as baseline technical checks, then complete manual WCAG behavior review:
+
+- Nu HTML Checker
+- CSS Validator
+
+---
+
+## Decision Tree
+
+```text
+Is this an interactive control?                       -> Verify keyboard access + visible focus + accessible name
+Is this non-text content (image/icon/media)?         -> Verify text alternative strategy
+Is this a form input or validation message?          -> Verify labels, instructions, errors, and status messaging
+Is this a custom widget pattern?                     -> Verify role/state/property model and keyboard model
+Does styling reduce legibility or discernibility?    -> Verify text + non-text contrast and target size
+Otherwise                                            -> Run checklist sweep and document residual risk
+```
+
+---
+
+## Code Examples
+
+### Example 1: Icon Button with Accessible Name and Focus Indicator
+
+```html
+<button type="button" aria-label="Close dialog" class="icon-button">
+  <svg aria-hidden="true" focusable="false" viewBox="0 0 24 24">
+    <path d="M6 6l12 12M18 6L6 18" />
+  </svg>
+</button>
+```
+
+```css
+.icon-button:focus-visible {
+  outline: 2px solid #005a9c;
+  outline-offset: 2px;
+}
+```
+
+### Example 2: Labeled Input with Error Association
+
+```html
+<label for="email">Email address</label>
+<input
+  id="email"
+  type="email"
+  aria-invalid="true"
+  aria-describedby="email-error"
+/>
+<p id="email-error" role="alert">Enter a valid email address.</p>
+```
+
+### Example 3: Semantic Click Target Instead of Generic Container
+
+```html
+<button type="button" class="card-action">Open details</button>
+```
+
+```html
+<div role="button" tabindex="0" aria-label="Open details"></div>
+```
+
+---
+
+## Commands
+
+```bash
+# Run default scan on current directory
+bash catalog/skills/accessibility-audit/scripts/audit-a11y.sh
+
+# Scan a specific path
+bash catalog/skills/accessibility-audit/scripts/audit-a11y.sh src
+
+# Generate markdown report
+bash catalog/skills/accessibility-audit/scripts/audit-a11y.sh --report src
+
+# Generate JSON output for CI pipelines
+bash catalog/skills/accessibility-audit/scripts/audit-a11y.sh --json src
+```
+
+---
+
+## Resources
+
+- Full checklist: [references/w3c-wcag22-checklist.md](references/w3c-wcag22-checklist.md)
+- WCAG overview (WAI): https://www.w3.org/WAI/standards-guidelines/wcag/
+- WCAG 2.2 Recommendation: https://www.w3.org/TR/WCAG22/
+- How to Meet WCAG 2 (Quick Reference): https://www.w3.org/WAI/WCAG22/quickref/
+- Understanding WCAG 2: https://www.w3.org/WAI/WCAG22/Understanding/
+- W3C standards context: https://www.w3.org/standards/
+- W3C validators and tools: https://www.w3.org/developers/tools/
+- W3C homepage: https://www.w3.org/

package/catalog/skills/accessibility-audit/manifest.json

@@ -0,0 +1,37 @@
+{
+  "id": "accessibility-audit",
+  "title": "Accessibility Audit",
+  "description": "Audit web accessibility against W3C WCAG 2.2 Level AA using framework-agnostic checks, remediation patterns, and portable command-line scanning.",
+  "portable": true,
+  "tags": ["frontend", "accessibility", "workflow", "quality"],
+  "detectors": ["always"],
+  "detectionTriggers": ["manual"],
+  "installsFor": ["all"],
+  "agentSupport": ["codex", "claude", "cursor", "gemini", "copilot"],
+  "skillMetadata": {
+    "author": "skilly-hand",
+    "last-edit": "2026-04-04",
+    "license": "Apache-2.0",
+    "version": "1.0.0",
+    "changelog": "Added portable WCAG 2.2 Level AA accessibility auditing skill with W3C-only references and scanner script; enables consistent web accessibility review across frameworks; affects catalog skill coverage and install plans for stacks recommending accessibility-audit",
+    "auto-invoke": "Auditing, reviewing, or implementing web accessibility against WCAG 2.2 Level AA",
+    "allowed-tools": [
+      "Read",
+      "Edit",
+      "Write",
+      "Glob",
+      "Grep",
+      "Bash",
+      "WebFetch",
+      "WebSearch",
+      "Task",
+      "SubAgent"
+    ]
+  },
+  "files": [
+    { "path": "SKILL.md", "kind": "instruction" },
+    { "path": "references/w3c-wcag22-checklist.md", "kind": "reference" },
+    { "path": "scripts/audit-a11y.sh", "kind": "asset" }
+  ],
+  "dependencies": []
+}

package/catalog/skills/accessibility-audit/references/w3c-wcag22-checklist.md

@@ -0,0 +1,80 @@
+# W3C WCAG 2.2 Level AA Checklist (Web)
+
+Source basis:
+
+- WCAG 2 Overview: https://www.w3.org/WAI/standards-guidelines/wcag/
+- WCAG 2.2 Recommendation: https://www.w3.org/TR/WCAG22/
+- Quick Reference: https://www.w3.org/WAI/WCAG22/quickref/
+- Understanding WCAG 2: https://www.w3.org/WAI/WCAG22/Understanding/
+
+Default conformance target in this skill: **WCAG 2.2 Level AA**.
+
+## Principle 1: Perceivable
+
+| SC | Level | Audit Focus |
+| --- | --- | --- |
+| 1.1.1 Non-text Content | A | Images/icons/media alternatives (`alt`, labels, text alternatives) |
+| 1.3.1 Info and Relationships | A | Semantic headings, labels, table/form relationships |
+| 1.3.2 Meaningful Sequence | A | DOM reading order matches meaning |
+| 1.3.3 Sensory Characteristics | A | Instructions are not only shape/color/position |
+| 1.3.4 Orientation | AA | Content works in portrait and landscape unless essential |
+| 1.3.5 Identify Input Purpose | AA | Appropriate `autocomplete` tokens for user-data fields |
+| 1.4.1 Use of Color | A | Color is not the only information channel |
+| 1.4.3 Contrast (Minimum) | AA | Text contrast thresholds are met |
+| 1.4.4 Resize Text | AA | Content remains usable at 200% text resize |
+| 1.4.10 Reflow | AA | Reflow at narrow viewport without two-dimensional scroll |
+| 1.4.11 Non-text Contrast | AA | Component boundaries/icons/focus indicators are distinguishable |
+| 1.4.12 Text Spacing | AA | Increased spacing does not break content/function |
+| 1.4.13 Content on Hover or Focus | AA | Hover/focus content is dismissible, hoverable, persistent |
+
+## Principle 2: Operable
+
+| SC | Level | Audit Focus |
+| --- | --- | --- |
+| 2.1.1 Keyboard | A | All functionality operable via keyboard |
+| 2.1.2 No Keyboard Trap | A | Focus can enter and leave all components |
+| 2.1.4 Character Key Shortcuts | A | Single-character shortcuts are safe/controllable |
+| 2.4.1 Bypass Blocks | A | Mechanism exists to bypass repeated blocks |
+| 2.4.2 Page Titled | A | Document/page has descriptive title |
+| 2.4.3 Focus Order | A | Focus sequence follows meaningful operation |
+| 2.4.4 Link Purpose (In Context) | A | Link purpose is clear from text/context |
+| 2.4.6 Headings and Labels | AA | Headings/labels clearly describe purpose |
+| 2.4.7 Focus Visible | AA | Visible focus indicator for keyboard users |
+| 2.4.11 Focus Not Obscured (Minimum) | AA | Focused element is not fully hidden |
+| 2.5.3 Label in Name | A | Accessible name includes visible label text |
+| 2.5.7 Dragging Movements | AA | Drag interactions have non-drag alternatives |
+| 2.5.8 Target Size (Minimum) | AA | Pointer targets meet minimum size/spacing |
+
+## Principle 3: Understandable
+
+| SC | Level | Audit Focus |
+| --- | --- | --- |
+| 3.1.1 Language of Page | A | Correct `lang` on root document |
+| 3.1.2 Language of Parts | AA | Language changes are marked in content |
+| 3.2.1 On Focus | A | Focus alone does not trigger unexpected context change |
+| 3.2.2 On Input | A | Input alone does not trigger unexpected context change |
+| 3.2.3 Consistent Navigation | AA | Repeated navigation mechanisms are consistent |
+| 3.2.4 Consistent Identification | AA | Same functions are identified consistently |
+| 3.2.6 Consistent Help | AA | Repeated help mechanisms are consistently positioned |
+| 3.3.1 Error Identification | A | Errors are identified in text |
+| 3.3.2 Labels or Instructions | A | Inputs include labels/instructions |
+| 3.3.3 Error Suggestion | AA | Suggested correction is provided when possible |
+| 3.3.4 Error Prevention (Legal, Financial, Data) | AA | Reversible/confirmable/validated submissions |
+| 3.3.7 Redundant Entry | A | Re-entry burden reduced where possible |
+| 3.3.8 Accessible Authentication (Minimum) | AA | Authentication avoids inaccessible cognitive tests |
+
+## Principle 4: Robust
+
+| SC | Level | Audit Focus |
+| --- | --- | --- |
+| 4.1.2 Name, Role, Value | A | UI controls expose name, role, state/value correctly |
+| 4.1.3 Status Messages | AA | Dynamic status is conveyed programmatically |
+
+## W3C Tooling Complements
+
+Use W3C validators from https://www.w3.org/developers/tools/ as supporting checks:
+
+- Nu HTML Checker
+- CSS Validator
+
+These checks complement, but do not replace, manual WCAG behavior verification.

package/catalog/skills/accessibility-audit/scripts/audit-a11y.sh

@@ -0,0 +1,372 @@
+#!/usr/bin/env bash
+# Portable accessibility audit helper aligned to WCAG 2.2 Level AA (W3C)
+# Sources:
+# - https://www.w3.org/WAI/standards-guidelines/wcag/
+# - https://www.w3.org/TR/WCAG22/
+# - https://www.w3.org/WAI/WCAG22/quickref/
+
+set -euo pipefail
+
+RED='\033[0;31m'
+YELLOW='\033[0;33m'
+CYAN='\033[0;36m'
+GREEN='\033[0;32m'
+BOLD='\033[1m'
+DIM='\033[2m'
+RESET='\033[0m'
+
+REPORT_MODE=false
+JSON_MODE=false
+TARGET=""
+ROOT="$(pwd)"
+REPORT_FILE="$ROOT/a11y-audit-report.md"
+REPORT_CONTENT=""
+JSON_ENTRIES=""
+
+FILES_SCANNED=0
+FILES_WITH_ISSUES=0
+TOTAL_ISSUES=0
+ISSUES_CRITICAL=0
+ISSUES_SERIOUS=0
+ISSUES_MODERATE=0
+
+usage() {
+  cat <<USAGE
+Usage:
+  bash catalog/skills/accessibility-audit/scripts/audit-a11y.sh [options] [path]
+
+Options:
+  --report     Write markdown report to ./a11y-audit-report.md
+  --json       Emit JSON findings to stdout
+  --help       Show this help
+
+Default path:
+  current directory
+USAGE
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --report) REPORT_MODE=true; shift ;;
+    --json) JSON_MODE=true; shift ;;
+    --help|-h) usage; exit 0 ;;
+    *) TARGET="$1"; shift ;;
+  esac
+done
+
+TARGET="${TARGET:-.}"
+
+if [[ ! -e "$TARGET" ]]; then
+  echo "Target does not exist: $TARGET" >&2
+  exit 1
+fi
+
+json_escape() {
+  echo "$1" | sed 's/\\/\\\\/g; s/"/\\"/g; s/\t/\\t/g; s/\r/\\r/g; s/\n/\\n/g'
+}
+
+record_finding() {
+  local file="$1"
+  local relative_path="$2"
+  local category="$3"
+  local severity="$4"
+  local wcag_sc="$5"
+  local lineno="$6"
+  local raw_line="$7"
+  local message="$8"
+
+  local color_code=""
+  local label=""
+
+  case "$severity" in
+    critical) color_code="$RED"; label="CRITICAL"; ISSUES_CRITICAL=$((ISSUES_CRITICAL + 1)) ;;
+    serious) color_code="$YELLOW"; label="SERIOUS"; ISSUES_SERIOUS=$((ISSUES_SERIOUS + 1)) ;;
+    moderate) color_code="$CYAN"; label="MODERATE"; ISSUES_MODERATE=$((ISSUES_MODERATE + 1)) ;;
+  esac
+
+  if ! $JSON_MODE; then
+    printf "  ${color_code}%-14s${RESET} [${DIM}%s${RESET}] line %-4s %s\n" "$category" "$wcag_sc" "$lineno:" "$message"
+    echo -e "             ${DIM}->${RESET} $raw_line"
+  fi
+
+  if $REPORT_MODE; then
+    REPORT_CONTENT+="| \`${relative_path}\` | ${lineno} | ${label} | \`${category}\` | ${wcag_sc} | ${message} |"$'\n'
+  fi
+
+  if $JSON_MODE; then
+    [[ -n "$JSON_ENTRIES" ]] && JSON_ENTRIES+=","
+    JSON_ENTRIES+="{\"file\":\"$(json_escape "$relative_path")\",\"line\":${lineno},\"severity\":\"${severity}\",\"category\":\"$(json_escape "$category")\",\"wcag\":\"$(json_escape "$wcag_sc")\",\"message\":\"$(json_escape "$message")\",\"code\":\"$(json_escape "$raw_line")\"}"
+  fi
+}
+
+audit_markup_file() {
+  local file="$1"
+  local relative_path="${file#$ROOT/}"
+  local file_issues=0
+
+  FILES_SCANNED=$((FILES_SCANNED + 1))
+
+  while IFS=: read -r lineno line; do
+    [[ "$line" =~ ^[[:space:]]*\<\!-- ]] && continue
+    local trimmed
+    trimmed="$(echo "$line" | sed 's/^[[:space:]]*//')"
+    record_finding "$file" "$relative_path" "MISSING-ALT" "critical" "1.1.1" "$lineno" "$trimmed" "Image is missing alt attribute"
+    file_issues=$((file_issues + 1))
+  done < <(grep -n -E '<img[[:space:]]' "$file" 2>/dev/null | grep -v -E 'alt=' || true)
+
+  while IFS=: read -r lineno line; do
+    [[ "$line" =~ ^[[:space:]]*\<\!-- ]] && continue
+    echo "$line" | grep -qE 'aria-label|aria-labelledby|title=' && continue
+    local trimmed
+    trimmed="$(echo "$line" | sed 's/^[[:space:]]*//')"
+    if echo "$trimmed" | grep -qE '<button[^>]*>[[:space:]]*</button>' || echo "$trimmed" | grep -qE '<button[^>]*/>'; then
+      record_finding "$file" "$relative_path" "EMPTY-BUTTON" "critical" "4.1.2" "$lineno" "$trimmed" "Button has no text or accessible name"
+      file_issues=$((file_issues + 1))
+    fi
+  done < <(grep -n -E '<button' "$file" 2>/dev/null || true)
+
+  while IFS=: read -r lineno line; do
+    [[ "$line" =~ ^[[:space:]]*\<\!-- ]] && continue
+    echo "$line" | grep -qE 'aria-label|aria-labelledby|title=' && continue
+    local trimmed
+    trimmed="$(echo "$line" | sed 's/^[[:space:]]*//')"
+    if echo "$trimmed" | grep -qE '<a[^>]*>[[:space:]]*</a>'; then
+      record_finding "$file" "$relative_path" "EMPTY-LINK" "critical" "2.4.4" "$lineno" "$trimmed" "Link has no text or accessible name"
+      file_issues=$((file_issues + 1))
+    fi
+  done < <(grep -n -E '<a[[:space:]]' "$file" 2>/dev/null || true)
+
+  while IFS=: read -r lineno line; do
+    [[ "$line" =~ ^[[:space:]]*\<\!-- ]] && continue
+    echo "$line" | grep -qE 'aria-label|aria-labelledby' && continue
+    echo "$line" | grep -qE 'type="hidden"|type="submit"|type="button"' && continue
+
+    local has_label=false
+    if echo "$line" | grep -qE 'id="[^"]+"'; then
+      local input_id
+      input_id="$(echo "$line" | sed -n 's/.*id="\([^"]*\)".*/\1/p' | head -1)"
+      if [[ -n "$input_id" ]] && grep -qE "for=\"${input_id}\"" "$file" 2>/dev/null; then
+        has_label=true
+      fi
+    fi
+
+    if [[ "$has_label" == "false" ]]; then
+      local trimmed
+      trimmed="$(echo "$line" | sed 's/^[[:space:]]*//')"
+      record_finding "$file" "$relative_path" "MISSING-LABEL" "serious" "1.3.1/3.3.2" "$lineno" "$trimmed" "Form control missing label association or ARIA naming"
+      file_issues=$((file_issues + 1))
+    fi
+  done < <(grep -n -E '<(input|select|textarea)[[:space:]]' "$file" 2>/dev/null || true)
+
+  while IFS=: read -r lineno line; do
+    [[ "$line" =~ ^[[:space:]]*\<\!-- ]] && continue
+    echo "$line" | grep -qE 'role=|tabindex=' && continue
+    local trimmed
+    trimmed="$(echo "$line" | sed 's/^[[:space:]]*//')"
+    record_finding "$file" "$relative_path" "CLICK-NO-ROLE" "serious" "2.1.1" "$lineno" "$trimmed" "Non-semantic clickable element needs keyboard and role semantics"
+    file_issues=$((file_issues + 1))
+  done < <(grep -n -E '<(div|span|li)[^>]*((onclick=)|(\(click\)))' "$file" 2>/dev/null || true)
+
+  while IFS=: read -r lineno line; do
+    [[ "$line" =~ ^[[:space:]]*\<\!-- ]] && continue
+    local tab_val
+    tab_val="$(echo "$line" | grep -oE 'tabindex="[0-9]+"' | grep -oE '[0-9]+' | head -1)"
+    if [[ -n "$tab_val" ]] && [[ "$tab_val" -gt 0 ]]; then
+      local trimmed
+      trimmed="$(echo "$line" | sed 's/^[[:space:]]*//')"
+      record_finding "$file" "$relative_path" "TABINDEX-POS" "serious" "2.4.3" "$lineno" "$trimmed" "Positive tabindex can break logical focus order"
+      file_issues=$((file_issues + 1))
+    fi
+  done < <(grep -n -E 'tabindex="[1-9]' "$file" 2>/dev/null || true)
+
+  local prev_level=0
+  while IFS=: read -r lineno line; do
+    [[ "$line" =~ ^[[:space:]]*\<\!-- ]] && continue
+    local level
+    level="$(echo "$line" | grep -oE '<h[1-6]' | grep -oE '[1-6]' | head -1)"
+    [[ -z "$level" ]] && continue
+
+    if [[ "$prev_level" -gt 0 ]] && [[ "$level" -gt $((prev_level + 1)) ]]; then
+      local trimmed
+      trimmed="$(echo "$line" | sed 's/^[[:space:]]*//')"
+      record_finding "$file" "$relative_path" "HEADING-SKIP" "moderate" "1.3.1" "$lineno" "$trimmed" "Heading level skipped"
+      file_issues=$((file_issues + 1))
+    fi
+
+    prev_level="$level"
+  done < <(grep -n -E '<h[1-6]' "$file" 2>/dev/null || true)
+
+  if grep -qE '<html[[:space:]]' "$file" 2>/dev/null; then
+    if ! grep -qE '<html[^>]*lang=' "$file" 2>/dev/null; then
+      local lineno
+      lineno="$(grep -n -E '<html' "$file" | head -1 | cut -d: -f1)"
+      local trimmed
+      trimmed="$(grep -E '<html' "$file" | head -1 | sed 's/^[[:space:]]*//')"
+      record_finding "$file" "$relative_path" "MISSING-LANG" "serious" "3.1.1" "$lineno" "$trimmed" "Missing language declaration on html element"
+      file_issues=$((file_issues + 1))
+    fi
+  fi
+
+  if [[ "$file_issues" -gt 0 ]]; then
+    FILES_WITH_ISSUES=$((FILES_WITH_ISSUES + 1))
+    TOTAL_ISSUES=$((TOTAL_ISSUES + file_issues))
+    if ! $JSON_MODE; then
+      echo -e "\n${BOLD}${relative_path}${RESET} - ${RED}${file_issues} issue(s)${RESET}"
+    fi
+  fi
+}
+
+audit_style_file() {
+  local file="$1"
+  local relative_path="${file#$ROOT/}"
+  local file_issues=0
+
+  FILES_SCANNED=$((FILES_SCANNED + 1))
+
+  while IFS=: read -r lineno line; do
+    [[ "$line" =~ ^[[:space:]]*/\* ]] && continue
+
+    local context_start=$((lineno > 4 ? lineno - 4 : 1))
+    local context_end=$((lineno + 8))
+    if sed -n "${context_start},${context_end}p" "$file" 2>/dev/null | grep -qE 'focus-visible'; then
+      continue
+    fi
+
+    local trimmed
+    trimmed="$(echo "$line" | sed 's/^[[:space:]]*//')"
+    record_finding "$file" "$relative_path" "FOCUS-REMOVED" "critical" "2.4.7" "$lineno" "$trimmed" "Focus outline removed without visible focus-visible replacement"
+    file_issues=$((file_issues + 1))
+  done < <(
+    grep -n -E ':focus[[:space:]]*\{' "$file" 2>/dev/null | while IFS=: read -r ln _; do
+      local end=$((ln + 5))
+      if sed -n "${ln},${end}p" "$file" 2>/dev/null | grep -qE 'outline:[[:space:]]*(none|0)'; then
+        echo "${ln}:focus"
+      fi
+    done || true
+  )
+
+  if [[ "$file_issues" -gt 0 ]]; then
+    FILES_WITH_ISSUES=$((FILES_WITH_ISSUES + 1))
+    TOTAL_ISSUES=$((TOTAL_ISSUES + file_issues))
+    if ! $JSON_MODE; then
+      echo -e "\n${BOLD}${relative_path}${RESET} - ${RED}${file_issues} issue(s)${RESET}"
+    fi
+  fi
+}
+
+generate_report() {
+  local generated_at
+  generated_at="$(date '+%Y-%m-%d %H:%M:%S')"
+
+  cat > "$REPORT_FILE" <<REPORT_HEAD
+# Accessibility Audit Report (WCAG 2.2 Level AA)
+
+Generated: ${generated_at}
+Target: \`${TARGET}\`
+
+## Summary
+
+| Metric | Count |
+| --- | --- |
+| Files scanned | ${FILES_SCANNED} |
+| Files with issues | ${FILES_WITH_ISSUES} |
+| Critical | ${ISSUES_CRITICAL} |
+| Serious | ${ISSUES_SERIOUS} |
+| Moderate | ${ISSUES_MODERATE} |
+| Total issues | ${TOTAL_ISSUES} |
+
+## Findings
+
+| File | Line | Severity | Category | WCAG SC | Description |
+| --- | --- | --- | --- | --- | --- |
+REPORT_HEAD
+
+  echo "$REPORT_CONTENT" >> "$REPORT_FILE"
+
+  cat >> "$REPORT_FILE" <<REPORT_TAIL
+
+## Source References (W3C)
+
+- https://www.w3.org/WAI/standards-guidelines/wcag/
+- https://www.w3.org/TR/WCAG22/
+- https://www.w3.org/WAI/WCAG22/quickref/
+- https://www.w3.org/WAI/WCAG22/Understanding/
+- https://www.w3.org/developers/tools/
+REPORT_TAIL
+}
+
+if ! $JSON_MODE; then
+  echo -e "${BOLD}WCAG 2.2 Level AA accessibility audit${RESET}"
+  echo -e "Target: ${CYAN}${TARGET}${RESET}"
+fi
+
+MARKUP_FILES=()
+STYLE_FILES=()
+
+if [[ -f "$TARGET" ]]; then
+  case "$TARGET" in
+    *.html|*.htm|*.xhtml|*.jsx|*.tsx) MARKUP_FILES+=("$TARGET") ;;
+    *.css|*.scss|*.sass|*.less) STYLE_FILES+=("$TARGET") ;;
+  esac
+else
+  while IFS= read -r f; do MARKUP_FILES+=("$f"); done < <(
+    find "$TARGET" -type f \( -name "*.html" -o -name "*.htm" -o -name "*.xhtml" -o -name "*.jsx" -o -name "*.tsx" \) \
+      -not -path "*/node_modules/*" \
+      -not -path "*/.git/*" \
+      -not -path "*/dist/*" \
+      -not -path "*/build/*" \
+      -not -path "*/coverage/*" \
+      -not -path "*/.next/*" \
+      -not -path "*/storybook-static/*" \
+      | sort
+  )
+
+  while IFS= read -r f; do STYLE_FILES+=("$f"); done < <(
+    find "$TARGET" -type f \( -name "*.css" -o -name "*.scss" -o -name "*.sass" -o -name "*.less" \) \
+      -not -path "*/node_modules/*" \
+      -not -path "*/.git/*" \
+      -not -path "*/dist/*" \
+      -not -path "*/build/*" \
+      -not -path "*/coverage/*" \
+      -not -path "*/.next/*" \
+      -not -path "*/storybook-static/*" \
+      | sort
+  )
+fi
+
+for file in "${MARKUP_FILES[@]:-}"; do
+  [[ -n "$file" ]] && audit_markup_file "$file"
+done
+
+for file in "${STYLE_FILES[@]:-}"; do
+  [[ -n "$file" ]] && audit_style_file "$file"
+done
+
+if $REPORT_MODE; then
+  generate_report
+fi
+
+if $JSON_MODE; then
+  cat <<JSON
+{"standard":"WCAG 2.2 Level AA","target":"$(json_escape "$TARGET")","summary":{"filesScanned":${FILES_SCANNED},"filesWithIssues":${FILES_WITH_ISSUES},"critical":${ISSUES_CRITICAL},"serious":${ISSUES_SERIOUS},"moderate":${ISSUES_MODERATE},"total":${TOTAL_ISSUES}},"findings":[${JSON_ENTRIES}]}
+JSON
+else
+  echo ""
+  echo -e "${BOLD}Summary${RESET}"
+  echo "Files scanned:      $FILES_SCANNED"
+  echo "Files with issues:  $FILES_WITH_ISSUES"
+  echo "Critical:           $ISSUES_CRITICAL"
+  echo "Serious:            $ISSUES_SERIOUS"
+  echo "Moderate:           $ISSUES_MODERATE"
+  echo "Total:              $TOTAL_ISSUES"
+  if $REPORT_MODE; then
+    echo "Report:             $REPORT_FILE"
+  fi
+  if [[ "$TOTAL_ISSUES" -eq 0 ]]; then
+    echo -e "${GREEN}No issues found by this heuristic scanner.${RESET}"
+  fi
+fi
+
+if [[ "$TOTAL_ISSUES" -gt 0 ]]; then
+  exit 1
+fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/skilly-hand",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "license": "CC-BY-NC-4.0",
   "type": "module",
   "publishConfig": {

package/packages/cli/src/bin.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
+import fs from "node:fs";
 import path from "node:path";
 import { createRequire } from "node:module";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath } from "node:url";
 import { checkbox as inquirerCheckbox, confirm as inquirerConfirm, select as inquirerSelect } from "@inquirer/prompts";
 import { loadAllSkills } from "../../catalog/src/index.js";
 import {
@@ -19,7 +20,17 @@ const { version } = require("../../../package.json");
 
 function isExecutedDirectly(metaUrl, argv1) {
   if (!argv1) return false;
-  return metaUrl === pathToFileURL(argv1).href;
+  const normalizePath = (filePath) => {
+    const absolutePath = path.resolve(filePath);
+    try {
+      const realPath = fs.realpathSync.native ? fs.realpathSync.native(absolutePath) : fs.realpathSync(absolutePath);
+      return path.normalize(realPath);
+    } catch {
+      return path.normalize(absolutePath);
+    }
+  };
+
+  return normalizePath(fileURLToPath(metaUrl)) === normalizePath(argv1);
 }
 
 export function parseArgs(argv) {