@salesforce/afv-skills 1.53.0 → 1.55.0

package/skills/dx-org-analyze/tests/test_consistency.sh

@@ -0,0 +1,428 @@
+#!/usr/bin/env bash
+# Consistency tests for dx-org-analyze SKILL.md and scripts.
+# Verifies skill structure, script references, and report contract.
+#
+# Usage: bash tests/test_consistency.sh
+# Exit 0 on all-pass, 1 on any failure.
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_FILE="$SCRIPT_DIR/../SKILL.md"
+SCRIPTS_DIR="$SCRIPT_DIR/../scripts"
+
+if [[ ! -f "$SKILL_FILE" ]]; then
+  echo "FAIL: SKILL.md not found at $SKILL_FILE"
+  exit 1
+fi
+
+PASS=0
+FAIL=0
+
+pass() { echo "  PASS: $1"; PASS=$((PASS + 1)); }
+fail() { echo "  FAIL: $1"; FAIL=$((FAIL + 1)); }
+
+# ============================================================
+echo "=== Test 1: YAML frontmatter is well-formed ==="
+# ============================================================
+
+if head -1 "$SKILL_FILE" | grep -q "^---$"; then
+  CLOSE_LINE=$(awk 'NR>1 && /^---$/ {print NR; exit}' "$SKILL_FILE")
+  if [[ -n "$CLOSE_LINE" ]]; then
+    pass "YAML frontmatter opens and closes (line $CLOSE_LINE)"
+  else
+    fail "YAML frontmatter has no closing ---"
+  fi
+else
+  fail "SKILL.md does not start with ---"
+fi
+
+# ============================================================
+echo ""
+echo "=== Test 2: Required frontmatter fields ==="
+# ============================================================
+
+CLOSE_LINE=$(awk 'NR>1 && /^---$/ {print NR; exit}' "$SKILL_FILE")
+if [[ -n "$CLOSE_LINE" ]]; then
+  FRONTMATTER=$(sed -n "1,${CLOSE_LINE}p" "$SKILL_FILE")
+  for field in "name:" "description:" "metadata:"; do
+    if echo "$FRONTMATTER" | grep -q "$field"; then
+      pass "Frontmatter has '$field'"
+    else
+      fail "Frontmatter missing '$field'"
+    fi
+  done
+  SKILL_NAME=$(echo "$FRONTMATTER" | grep "^name:" | awk '{print $2}')
+  EXPECTED_NAME=$(basename "$(cd "$SCRIPT_DIR/.." && pwd)")
+  if [[ "$SKILL_NAME" == "$EXPECTED_NAME" ]]; then
+    pass "Skill name '$SKILL_NAME' matches directory name"
+  else
+    fail "Skill name '$SKILL_NAME' doesn't match directory name '$EXPECTED_NAME'"
+  fi
+  if echo "$FRONTMATTER" | grep -q "version:"; then
+    pass "Frontmatter has 'metadata.version'"
+  else
+    fail "Frontmatter missing 'metadata.version'"
+  fi
+fi
+
+# ============================================================
+echo ""
+echo "=== Test 3: SKILL.md references both scripts ==="
+# ============================================================
+
+if grep -qF "collect_org_data.py" "$SKILL_FILE"; then
+  pass "References collect_org_data.py"
+else
+  fail "Missing reference to collect_org_data.py"
+fi
+
+if grep -qF "compute_diff.py" "$SKILL_FILE"; then
+  pass "References compute_diff.py"
+else
+  fail "Missing reference to compute_diff.py"
+fi
+
+# ============================================================
+echo ""
+echo "=== Test 4: Scripts exist and are executable ==="
+# ============================================================
+
+for script in "collect_org_data.py" "compute_diff.py"; do
+  SPATH="$SCRIPTS_DIR/$script"
+  if [[ -f "$SPATH" ]]; then
+    pass "Script exists: $script"
+  else
+    fail "Script missing: $script"
+  fi
+  if [[ -x "$SPATH" ]]; then
+    pass "Script is executable: $script"
+  else
+    fail "Script not executable: $script"
+  fi
+  if head -1 "$SPATH" | grep -q "python3"; then
+    pass "Script has python3 shebang: $script"
+  else
+    fail "Script missing python3 shebang: $script"
+  fi
+done
+
+# ============================================================
+echo ""
+echo "=== Test 5: Scripts accept --help ==="
+# ============================================================
+
+for script in "collect_org_data.py" "compute_diff.py"; do
+  if python3 "$SCRIPTS_DIR/$script" --help >/dev/null 2>&1; then
+    pass "$script --help exits 0"
+  else
+    fail "$script --help failed"
+  fi
+done
+
+# ============================================================
+echo ""
+echo "=== Test 6: collect_org_data.py has required flags ==="
+# ============================================================
+
+HELP_COLLECT=$(python3 "$SCRIPTS_DIR/collect_org_data.py" --help 2>&1)
+for flag in "org-alias" "output" "skip-deep-data"; do
+  if echo "$HELP_COLLECT" | grep -qF -- "--$flag"; then
+    pass "collect_org_data.py supports --$flag"
+  else
+    fail "collect_org_data.py missing flag: --$flag"
+  fi
+done
+
+# ============================================================
+echo ""
+echo "=== Test 7: compute_diff.py has required flags ==="
+# ============================================================
+
+HELP_DIFF=$(python3 "$SCRIPTS_DIR/compute_diff.py" --help 2>&1)
+for flag in "org-a" "org-b" "output" "format" "org-a-label" "org-b-label"; do
+  if echo "$HELP_DIFF" | grep -qF -- "--$flag"; then
+    pass "compute_diff.py supports --$flag"
+  else
+    fail "compute_diff.py missing flag: --$flag"
+  fi
+done
+
+# ============================================================
+echo ""
+echo "=== Test 8: SF CLI authentication documented ==="
+# ============================================================
+
+if grep -qF "sf org list" "$SKILL_FILE"; then
+  pass "Documents 'sf org list' for listing authenticated orgs"
+else
+  fail "Missing: sf org list"
+fi
+
+if grep -qF "sf data query" "$SKILL_FILE"; then
+  pass "Documents 'sf data query' for validating connectivity"
+else
+  fail "Missing: sf data query"
+fi
+
+if grep -qF "sf org login web" "$SKILL_FILE"; then
+  pass "Documents 'sf org login web' for authentication"
+else
+  fail "Missing: sf org login web"
+fi
+
+# ============================================================
+echo ""
+echo "=== Test 9: Drift score constants in compute_diff.py ==="
+# ============================================================
+
+DIFF_SCRIPT="$SCRIPTS_DIR/compute_diff.py"
+for term in "WEIGHT_METADATA" "WEIGHT_PERMISSION" "WEIGHT_PROFILE" "DRIFT_LEVELS"; do
+  if grep -qF "$term" "$DIFF_SCRIPT"; then
+    pass "Drift constant '$term' in compute_diff.py"
+  else
+    fail "Missing drift constant: '$term'"
+  fi
+done
+
+if grep -qF "0.6" "$DIFF_SCRIPT" && grep -qF "0.3" "$DIFF_SCRIPT" && grep -qF "0.1" "$DIFF_SCRIPT"; then
+  pass "Weights are 0.6 / 0.3 / 0.1"
+else
+  fail "Drift weights don't match expected 0.6 / 0.3 / 0.1"
+fi
+
+for level in "LOW" "MODERATE" "HIGH" "CRITICAL"; do
+  if grep -qF "\"$level\"" "$DIFF_SCRIPT"; then
+    pass "Severity level '$level' defined"
+  else
+    fail "Missing severity level: '$level'"
+  fi
+done
+
+# ============================================================
+echo ""
+echo "=== Test 10: System permissions support ==="
+# ============================================================
+
+COLLECT_SCRIPT="$SCRIPTS_DIR/collect_org_data.py"
+
+if grep -qF "collect_system_permissions" "$COLLECT_SCRIPT"; then
+  pass "collect_org_data.py has collect_system_permissions function"
+else
+  fail "collect_org_data.py missing collect_system_permissions"
+fi
+
+if grep -qF "PermissionsXxx" "$COLLECT_SCRIPT" || grep -qF "Permissions" "$COLLECT_SCRIPT" && grep -qF "PermissionSet" "$COLLECT_SCRIPT"; then
+  pass "collect_org_data.py queries PermissionsXxx fields on PermissionSet"
+else
+  fail "Missing PermissionsXxx/PermissionSet query"
+fi
+
+if grep -qF "system_permissions" "$COLLECT_SCRIPT"; then
+  pass "collect_org_data.py outputs system_permissions in result"
+else
+  fail "Missing system_permissions in output"
+fi
+
+DIFF_SCRIPT="$SCRIPTS_DIR/compute_diff.py"
+
+if grep -qF "diff_system_permissions" "$DIFF_SCRIPT"; then
+  pass "compute_diff.py has diff_system_permissions function"
+else
+  fail "compute_diff.py missing diff_system_permissions"
+fi
+
+if grep -qF "System Permissions" "$DIFF_SCRIPT"; then
+  pass "compute_diff.py renders System Permissions section in report"
+else
+  fail "Missing System Permissions section in markdown report"
+fi
+
+# ============================================================
+echo ""
+echo "=== Test 11: collect_org_data.py uses SF CLI and public APIs ==="
+# ============================================================
+
+COLLECT_SCRIPT="$SCRIPTS_DIR/collect_org_data.py"
+
+if grep -qF "sf org list metadata-types" "$COLLECT_SCRIPT" || grep -qF "metadata-types" "$COLLECT_SCRIPT"; then
+  pass "Uses sf CLI metadata-types for type discovery"
+else
+  fail "Missing sf CLI metadata type discovery"
+fi
+
+if grep -qF "sf org list metadata" "$COLLECT_SCRIPT" || grep -qF "list metadata" "$COLLECT_SCRIPT"; then
+  pass "Uses sf CLI to list metadata components"
+else
+  fail "Missing sf CLI metadata listing"
+fi
+
+if grep -qF "OrganizationSettingsDetail" "$COLLECT_SCRIPT"; then
+  pass "Uses OrganizationSettingsDetail for org settings (public API)"
+else
+  fail "Missing OrganizationSettingsDetail — must use public API for settings"
+fi
+
+if grep -qF "/limits/" "$COLLECT_SCRIPT"; then
+  pass "Uses REST /limits/ endpoint for org limits"
+else
+  fail "Missing /limits/ endpoint — must use public API for org limits"
+fi
+
+if grep -q "exit(2)\|sys.exit(2)" "$COLLECT_SCRIPT"; then
+  pass "Exits 2 on session expiry"
+else
+  fail "Missing exit code 2 for session expiry"
+fi
+
+# Verify internal tools are NOT present
+if grep -qF "hoseMyOrgPlease" "$COLLECT_SCRIPT"; then
+  fail "Still references hoseMyOrgPlease (internal-only tool, must be removed)"
+else
+  pass "No references to hoseMyOrgPlease (internal tool removed)"
+fi
+
+# ============================================================
+echo ""
+echo "=== Test 12: Core rules in SKILL.md ==="
+# ============================================================
+
+RULES=("Read-only" "never deploy" "session expired")
+
+for rule in "${RULES[@]}"; do
+  if grep -qiF "$rule" "$SKILL_FILE"; then
+    pass "Core rule/concept present: '$rule'"
+  else
+    fail "Missing: '$rule'"
+  fi
+done
+
+# ============================================================
+echo ""
+echo "=== Test 13: No hardcoded metadata type tiers ==="
+# ============================================================
+
+HARDCODED_TIERS=$(grep -cE "^\*\*Tier [0-9]" "$SKILL_FILE" || true)
+if [[ "$HARDCODED_TIERS" -eq 0 ]]; then
+  pass "No hardcoded tier lists in SKILL.md"
+else
+  fail "Found $HARDCODED_TIERS hardcoded tier lists — use describeMetadata instead"
+fi
+
+# ============================================================
+echo ""
+echo "=== Test 14: No internal-only references in SKILL.md ==="
+# ============================================================
+
+if grep -qF "hoseMyOrgPlease" "$SKILL_FILE"; then
+  fail "SKILL.md still references hoseMyOrgPlease (internal-only)"
+else
+  pass "No hoseMyOrgPlease references in SKILL.md"
+fi
+
+if grep -qF "SOAP Partner API" "$SKILL_FILE" || grep -qF "SOAP Login" "$SKILL_FILE"; then
+  fail "SKILL.md still references SOAP login (removed for external use)"
+else
+  pass "No SOAP login references in SKILL.md"
+fi
+
+if grep -qF "Web Login" "$SKILL_FILE" && grep -qF "sid cookie" "$SKILL_FILE"; then
+  fail "SKILL.md still references web login with sid cookie (removed for external use)"
+else
+  pass "No web login/cookie references in SKILL.md"
+fi
+
+# ============================================================
+echo ""
+echo "=== Test 15: introspect_org.py exists and is executable ==="
+# ============================================================
+
+INTROSPECT_SCRIPT="$SCRIPTS_DIR/introspect_org.py"
+if [[ -f "$INTROSPECT_SCRIPT" ]]; then
+  pass "Script exists: introspect_org.py"
+else
+  fail "Script missing: introspect_org.py"
+fi
+if [[ -x "$INTROSPECT_SCRIPT" ]]; then
+  pass "Script is executable: introspect_org.py"
+else
+  fail "Script not executable: introspect_org.py"
+fi
+if head -1 "$INTROSPECT_SCRIPT" | grep -q "python3"; then
+  pass "Script has python3 shebang: introspect_org.py"
+else
+  fail "Script missing python3 shebang: introspect_org.py"
+fi
+
+# ============================================================
+echo ""
+echo "=== Test 16: introspect_org.py --help and flags ==="
+# ============================================================
+
+if python3 "$INTROSPECT_SCRIPT" --help >/dev/null 2>&1; then
+  pass "introspect_org.py --help exits 0"
+else
+  fail "introspect_org.py --help failed"
+fi
+
+HELP_INTROSPECT=$(python3 "$INTROSPECT_SCRIPT" --help 2>&1)
+for flag in "org" "output" "format" "label"; do
+  if echo "$HELP_INTROSPECT" | grep -qF -- "--$flag"; then
+    pass "introspect_org.py supports --$flag"
+  else
+    fail "introspect_org.py missing flag: --$flag"
+  fi
+done
+
+# ============================================================
+echo ""
+echo "=== Test 17: SKILL.md documents introspect workflow ==="
+# ============================================================
+
+if grep -qF "introspect_org.py" "$SKILL_FILE"; then
+  pass "SKILL.md references introspect_org.py"
+else
+  fail "SKILL.md missing reference to introspect_org.py"
+fi
+
+if grep -qiF "Introspect Workflow" "$SKILL_FILE"; then
+  pass "SKILL.md has Introspect Workflow section"
+else
+  fail "SKILL.md missing Introspect Workflow section"
+fi
+
+if grep -qiF "single-org" "$SKILL_FILE" || grep -qiF "single org" "$SKILL_FILE"; then
+  pass "SKILL.md mentions single-org mode"
+else
+  fail "SKILL.md missing single-org mode documentation"
+fi
+
+if grep -qiF "introspect" "$SKILL_FILE"; then
+  pass "SKILL.md mentions introspect in description"
+else
+  fail "SKILL.md description missing introspect trigger phrases"
+fi
+
+# ============================================================
+echo ""
+echo "=== Test 18: introspect_org.py report sections ==="
+# ============================================================
+
+for section in "Metadata Inventory" "Installed Packages" "Org Settings" "Org Limits" "Licenses" "System Permissions" "Deep Data"; do
+  if grep -qF "$section" "$INTROSPECT_SCRIPT"; then
+    pass "introspect_org.py renders '$section' section"
+  else
+    fail "introspect_org.py missing '$section' section"
+  fi
+done
+
+# ============================================================
+echo ""
+echo "================================================"
+echo "Results: $PASS passed, $FAIL failed"
+echo "================================================"
+
+if [[ $FAIL -gt 0 ]]; then
+  exit 1
+fi
+exit 0

package/skills/experience-design-validate/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: experience-design-validate
+description: "Use this skill to run a visual-craft audit of a rendered UI and produce an evidence-grounded Craft Report across Useful, Usable, Reliable, Coherent, and Well-Crafted. Invoke it for craft audits, visual critiques, design comparisons, felt-quality reviews, or visual-craft readiness checks on screenshots (.png, .jpg, .jpeg, .webp, .gif), Figma frames, rendered prototypes, and live URLs. Do not use it for source-code review, SLDS compliance (use design-systems-slds-validate), or accessibility compliance (use experience-accessibility-validate)."
+metadata:
+  version: "1.0"
+  domains: ["Experience"]
+  relatedSkills:
+    - "design-systems-slds-validate"
+    - "experience-accessibility-validate"
+    - "experience-lwc-generate"
+    - "experience-lwc-security-validate"
+---
+
+# Experience Design Validate
+
+Evaluate the visual craft of rendered software: what the eye sees and the felt quality those visible decisions create. Judge relationships, hierarchy, restraint, consistency, and care rather than CSS, tokens, or implementation technique.
+
+This is a **visual-craft-only** audit. It does not establish WCAG conformance, keyboard or screen-reader support, behavioral usability, implementation quality, or production release readiness. Route accessibility compliance to `experience-accessibility-validate` and SLDS compliance to `design-systems-slds-validate`.
+
+## Use and boundaries
+
+Use this skill to:
+
+- Critique visual craft at a design checkpoint.
+- Explain why a rendered design feels considered, cramped, calm, fragmented, or delightful.
+- Compare the craft of two or more designs solving the same brief.
+- Identify design moves that would lift a visible experience from good to great.
+
+Do not use this skill for:
+
+- Implementation or code review. For LWC generation or security review, use `experience-lwc-generate` or `experience-lwc-security-validate` as appropriate.
+- Accessibility compliance, including WCAG, screen-reader, keyboard, or focus-order validation. Use `experience-accessibility-validate`.
+- SLDS design-token compliance. Use `design-systems-slds-validate`.
+- Claims about real-user behavior. Recommend a usability study when impact depends on behavior rather than visible evidence.
+
+## Visual evidence contract
+
+Rendered pixels are mandatory. Prefer screenshots because they preserve the exact evidence reviewed.
+
+1. **Screenshots:** use supplied full-page or region captures directly.
+2. **Live URL:** if browser capability is available, open the URL, exercise only the relevant paths, capture screenshots, and retain the URL and viewport as evidence. Otherwise ask for screenshots.
+3. **Figma:** if Figma capability is available, fetch or export the named rendered frames. Treat a frame as static unless prototype behavior is actually exercised. Otherwise ask for frame exports or screenshots.
+4. **Screen recording or interactive prototype:** inspect observable transitions and capture representative frames when tooling supports it.
+5. **Source code, design descriptions, or inaccessible links:** do not infer the rendered result. Render with available capability; otherwise request screenshots.
+
+If no rendered pixels are available:
+
+- **Interactive run:** ask the user for screenshots or another rendered artifact and pause the audit.
+- **Non-interactive run:** return status `INSUFFICIENT_VISUAL_EVIDENCE` with a short statement of the missing artifact. Do not score, assign a verdict, create findings, or imply readiness.
+
+### Evidence modes
+
+Declare one mode before analysis:
+
+| Mode | What it can support | What it cannot support |
+|---|---|---|
+| `STATIC_VISUAL` | Visible hierarchy, spacing, typography, color, density, composition, consistency, and the visible treatment of the captured moment | Interaction behavior, transitions between states, responsive adaptation beyond captured viewports, latency, runtime performance, or unseen states |
+| `MULTI_VIEW_STATIC` | Static visual evidence across supplied screens, states, or viewport captures, including cross-screen coherence | The behavior connecting captures, timing, input response, runtime performance, or states not shown |
+| `DYNAMIC_VISUAL` | Static qualities plus behavior directly exercised or recorded: interaction feedback, transitions, state changes, and perceived performance | Unexercised paths, unrecorded states, accessibility compliance, or measured performance beyond what was observed |
+
+A static screenshot of a loading, error, or empty state supports critique of that state's **visible treatment only**. It does not substantiate state coverage, transition behavior, or performance. Never lower a score because an unobserved state or behavior was not supplied; mark that coverage `INSUFFICIENT_EVIDENCE` instead.
+
+## Five dimensions
+
+| Dimension | Felt question |
+|---|---|
+| **Useful** | Does the visible content earn the space and attention it occupies? |
+| **Usable** | Does the visible hierarchy and affordance make the intended path feel obvious? |
+| **Reliable** | Do the observed states and feedback make the experience feel predictable? |
+| **Coherent** | Does the visible experience feel made by one team with one taste? |
+| **Well-Crafted** | Does the visible design feel precise, considered, and delightful? |
+
+Use a 1-10 score only when the available evidence adequately covers a dimension. Use `INSUFFICIENT_EVIDENCE` when an applicable dimension cannot be supported. Use `N/A` only when the dimension or topic genuinely does not apply, never merely because evidence is missing.
+
+Read `references/scoring-rubric.md` for scoring anchors, verdict rules, severity definitions, and the complete report contract.
+
+## Craft lens
+
+Ask whether the rendered experience feels:
+
+- **Breathable:** space structures the composition and gives the eye room.
+- **Approachable:** the intended path is visually obvious without explanation.
+- **Inviting:** visible states encourage exploration rather than present dead ends.
+- **Considered:** repeated decisions form a system rather than an accumulation.
+- **Quiet:** hierarchy is calm; few elements compete to be primary.
+- **Delightful:** detail and personality are purposeful, not ornamental noise.
+- **Confident:** the design has a point of view and avoids unnecessary hedging.
+
+## Audit workflow
+
+Follow this order:
+
+1. Establish the evidence mode and inventory every supplied or captured artifact.
+2. If no rendered pixels exist, follow the insufficient-visual-evidence behavior and stop.
+3. Look before consulting rules. Record up to three honest first impressions for each design.
+4. Build the coverage and relevance ledger. For every dimension and reference topic, record `SCORED`, `N/A`, or `INSUFFICIENT_EVIDENCE`, the evidence mode, and a concise reason.
+5. Load `references/craft.md`, `references/scoring-rubric.md`, and `references/visual-system.md`. Load only conditional references whose topic is both relevant and observable in the evidence mode.
+6. Score only supported dimensions. Select the **highest anchor whose applicable, observable criteria are fully supported**; use an odd score only when evidence clearly exceeds that anchor without fully supporting the next.
+7. Write findings. Cap findings at five per dimension and deduplicate cross-dimensional root causes.
+8. Write the Craft Report, including the ledger and evidence limitations.
+
+## Progressive disclosure
+
+Always load:
+
+- `references/scoring-rubric.md`: scoring, coverage, severity, verdict, and report schema.
+- `references/craft.md`: felt qualities of considered work.
+- `references/visual-system.md`: visible layout, typography, color, and surfaces.
+
+Load only when relevant **and observable**:
+
+| Reference | Evidence needed |
+|---|---|
+| `references/components.md` | Visible buttons, inputs, modals, lists, tables, or feedback components |
+| `references/navigation.md` | Visible navigation, tabs, breadcrumbs, search, or wayfinding |
+| `references/responsive.md` | Captures from multiple viewports or directly exercised resizing |
+| `references/forms-flows.md` | Multiple visible steps or directly exercised form behavior |
+| `references/data.md` | Visible charts, dashboards, metrics, filters, results, or tables |
+| `references/records.md` | Visible records, detail pages, status, metadata, or collaboration |
+| `references/ai.md` | Visible AI, agent, chat, citations, or model output |
+| `references/trust.md` | Visible auth, privacy, consent, permissions, or destructive settings |
+| `references/usability.md` | Visible task structure; do not infer behavioral usability |
+| `references/interaction.md` | `DYNAMIC_VISUAL` evidence of interaction or motion |
+| `references/state.md` | `DYNAMIC_VISUAL` state transitions; static state captures support appearance only |
+| `references/performance.md` | `DYNAMIC_VISUAL` evidence of timing, latency, or layout stability |
+
+## Finding voice
+
+Speak at the felt level and anchor claims to visible evidence.
+
+Good: "The toolbar feels overworked; too many controls compete for attention, so the eye cannot find the primary action."
+
+Wrong scope: "Three button classes use inconsistent spacing tokens." That belongs in implementation or SLDS review.
+
+Each finding must include `severity`, `primary_dimension`, optional `related_dimensions`, `location`, `problem`, `why_it_weakens_craft`, `what_better_looks_like`, and `fix`. When one problem appears in three or more places, create one finding with a count and representative location.
+
+## Comparative audits
+
+Audit each design independently with the same evidence requirements and rubric. The report must include:
+
+- Per-design evidence mode, coverage ledger, first impressions, dimension scores, evidence, and gap to the next supported level.
+- A side-by-side comparison table that preserves `N/A` and `INSUFFICIENT_EVIDENCE` rather than forcing numeric comparisons.
+- A result of `A_HIGHER_CRAFT`, `B_HIGHER_CRAFT`, `TIE`, or `MIXED`. Use `MIXED` when leadership varies by dimension or evidence coverage prevents an overall ranking.
+- Differentiating dimensions, concrete craft moves each design makes better, and improvements each could borrow without copying.
+
+Do not crown a winner when the evidence supports a tie or mixed outcome.
+
+## Output
+
+If the user explicitly supplies an output path, write there exactly; that path overrides the naming convention. Otherwise use `YYYY-MM-DD-<target-slug>-craft-audit-<VERDICT>.md`, with uppercase `PASS`, `WARN`, `FAIL`, or `LIMITED`.
+
+The report must make its scope explicit: verdicts and readiness implications cover **visual craft only**, not accessibility, functional correctness, measured performance, or production release approval.
+
+Recommendations and cross-cutting patterns each contain **zero to five** items. Include only evidence-backed, useful entries; never add filler to reach a quota. End with the fix prompt defined in `references/scoring-rubric.md` only when at least one actionable recommendation exists.
+
+## Core principles
+
+1. **Pixels first.** No rendered evidence means no visual-craft audit.
+2. **Eye first, rules second.** Record first impressions before rubric analysis.
+3. **Evidence bounds claims.** Unobserved behavior is unknown, not defective.
+4. **Felt level, not implementation level.** Describe visual experience, not code.
+5. **Teach while auditing.** Explain why each finding matters and what better feels like.
+6. **Severity over volume.** A few sharp findings beat a padded checklist.

package/skills/experience-design-validate/references/ai.md

@@ -0,0 +1,54 @@
+# AI & Agent UX
+
+> **Skip this reference if the design shows no AI, LLM, agent, chat, citation, or model-output surfaces.**
+
+Craft in AI surfaces is the difference between a model that feels considered and one that feels duct-taped. It lives in the visual rhythm of a multi-step progress timeline, the restraint of a "thinking" indicator that respects screen real estate, the elegance of an inline citation marker, and the quiet confidence of reasoning that sits subordinate to the answer. This reference judges the visual and behavioral craft of agent progress, disclosure, reasoning, confidence, citations, and review surfaces.
+
+## Why this matters
+
+AI features are where craft becomes load-bearing — users decide in seconds whether to trust output, and that decision rests almost entirely on visual signals. When craft is high, the interface feels like it understands its own limits: progress is shown with precision, citations sit close to the claim they support, confidence is conveyed without drama, and reasoning collapses politely until invited. When craft is low, AI surfaces feel either showy (every token streaming, walls of "thinking", verbose tool logs) or evasive (no provenance, no progress, no way out). The visual treatment of AI is where the product proves it has thought about how the model fits into a human's workflow.
+
+---
+
+## Agent Progress
+
+- **The work is visible as a timeline.** Each step has a status the user can read at a glance — pending, active, complete. A vague "thinking..." for thirty seconds reads as the product hiding from itself. Tool use is named, not narrated; verbose logs read as developer output left in production.
+- **Stop is always available, and the input area stays alive.** The user can interrupt and clarify mid-flight. On completion, progress collapses politely — a summary remains, the scaffolding recedes. Failure preserves what was done.
+
+## Disclosure
+
+- **AI is unmistakable in conversation.** A distinct avatar or label tells the user when they're talking to a model rather than a person. Ambiguity here is a small ethical breach.
+- **AI-generated content carries a persistent signal until reviewed.** Handoffs between AI and human agents are clear. An escape to a human is always reachable.
+
+## Reasoning
+
+- **Reasoning is subordinate to the answer.** The result leads; the explanation sits quietly below or behind a click. A wall of reasoning above the answer reads as showing off. Default is short; depth is on demand.
+- **Tool invocations are collapsible.** What was called and what came back, summarized; full output one click away. Raw model internals stay out of production.
+
+## Confidence
+
+- **Confidence is communicated without drama.** A simple visual register beats a percentage. Numeric confidence reads as false precision to most users. The source of uncertainty is named when possible. High-stakes outputs prompt review.
+
+## Citations
+
+- **Claims and their sources sit close together.** A citation marker right after the claim, not collected at the bottom. Markers are subtle but reachable. Sources are specific — page, section, timestamp — not just a document name.
+- **Quoted text and AI interpretation look different.** Source quality is visible — recency, authority, primary versus user-generated. Conflicts between sources are surfaced rather than hidden. Cited links go directly to the source.
+
+## Human Review
+
+- **High-stakes AI output goes through a human gate.** Irreversible or third-party-affecting actions pause for explicit approval. The review queue presents proposed action, context, confidence, reasoning, and approve/reject/edit in one view.
+- **Override is easy and unjudged.** No dark pattern friction punishes the human for disagreeing with the model. Batch approval exists but never defaults to "approve all."
+
+---
+
+## Scoring Guide
+
+**Contributes to dimensions: Useful, Reliable, Coherent**
+
+| Score | Criteria |
+|-------|----------|
+| 9-10 | The AI surface understands its own limits. Progress reads at a glance, citations sit near their claims, confidence is communicated without drama, and review gates handle the high-stakes work. |
+| 7-8 | AI disclosure is present. Confidence and citations are mostly consistent. |
+| 5-6 | Vague "thinking" indicators. Citations missing or batched. Confidence over-hedged or unstated. |
+| 3-4 | The AI is a black box. No disclosure. Citations absent or misleading. |
+| 1-2 | No disclosure. No guardrails. Outputs presented as fact without sources. |