@harness-engineering/cli 1.7.0 → 1.8.1

package/dist/agents/skills/gemini-cli/initialize-harness-project/SKILL.md

@@ -0,0 +1,224 @@
+# Initialize Harness Project
+
+> Scaffold a new harness-compliant project or migrate an existing project to the next adoption level. Assess current state, configure personas, generate AGENTS.md, and validate the result.
+
+## When to Use
+
+- Starting a brand new project that should be harness-managed from day one
+- Migrating an existing project to harness for the first time
+- Upgrading an existing harness project from one adoption level to the next (basic to intermediate, intermediate to advanced)
+- When `on_project_init` triggers fire
+- NOT when the project is already at the desired adoption level (use harness-onboarding to orient instead)
+- NOT when adding a single component to an existing harness project (use add-harness-component)
+- NOT when the project has no clear owner or maintainer — harness setup requires someone to own the constraints
+
+## Process
+
+### Phase 1: ASSESS — Determine Current State
+
+1. **Check for existing harness configuration.** Look for `.harness/` directory, `AGENTS.md`, `harness.yaml`, and any skill definitions. Their presence determines whether this is a new project or a migration.
+
+2. **For new projects:** Gather project context — language, framework, test runner, build tool. Ask the human if any of these are undecided. Do not assume defaults.
+
+3. **For existing projects:** Run `harness validate` to see what is already configured and what is missing. Read `AGENTS.md` if it exists. Identify the current adoption level:
+   - **Basic:** Has `AGENTS.md` and `harness.yaml` with project metadata. No layers, no skills, no dependency constraints.
+   - **Intermediate:** Has layers defined, dependency constraints between layers, at least one custom skill. `harness check-deps` runs and passes.
+   - **Advanced:** Has full persona configuration, custom skills for the team's workflows, state management, learnings capture, and CI integration for `harness validate`.
+
+4. **Recommend the target adoption level.** For new projects, start with basic unless the team has harness experience. For existing projects, recommend one level up from current. Present the recommendation and wait for confirmation.
+
+### Phase 2: SCAFFOLD — Generate Project Structure
+
+1. **Run `harness init` with the appropriate flags:**
+   - New basic project: `harness init --level basic --framework <framework>`
+   - New intermediate project: `harness init --level intermediate --framework <framework>`
+   - Migration to intermediate: `harness init --level intermediate --migrate`
+   - Migration to advanced: `harness init --level advanced --migrate`
+
+2. **Review generated files.** `harness init` creates:
+   - `harness.yaml` — Project configuration (name, stack, adoption level)
+   - `.harness/` directory — State and learnings storage
+   - `AGENTS.md` — Agent instructions (template, needs customization)
+   - Layer definitions (intermediate and above)
+   - Dependency constraints (intermediate and above)
+
+3. **Do not blindly accept generated content.** Read the generated `AGENTS.md` and `harness.yaml`. Flag anything that looks wrong or incomplete. The scaffolded output is a starting point, not a finished product.
+
+### Phase 3: CONFIGURE — Customize for the Project
+
+1. **Configure personas.** Run `harness persona generate` to create persona definitions based on the project's stack and team structure. Personas define how agents should behave in this project — coding style, communication preferences, constraint strictness.
+
+2. **Customize AGENTS.md.** The generated template needs project-specific content:
+   - Project description and purpose
+   - Architecture overview (components, layers, data flow)
+   - Key conventions the team follows
+   - Known constraints and forbidden patterns
+   - Links to relevant documentation
+
+3. **For intermediate and above:** Define layer boundaries. Which modules belong to which layers? What are the allowed import directions? Document these in `harness.yaml` and ensure they match the actual codebase structure.
+
+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:
+   - `harness.yaml` schema validity
+   - `AGENTS.md` presence and required sections
+   - Layer definitions (if intermediate+)
+   - Dependency constraints (if intermediate+)
+   - Persona configuration (if configured)
+
+2. **Fix any validation errors before finishing.** Do not leave the project in a half-configured state.
+
+3. **Run `harness check-deps`** (intermediate and above) to verify dependency constraints match the actual codebase. If there are violations, decide with the human: update the constraints or fix the code.
+
+### Build the Initial Knowledge Graph
+
+If the project will use graph-based queries, build the initial knowledge graph now:
+
+```
+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. **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
+
+- **`harness init --level <level> --framework <framework>`** — Scaffold a new project at the specified adoption level.
+- **`harness init --level <level> --migrate`** — Migrate an existing project to the next adoption level, preserving existing configuration.
+- **`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
+
+- `harness.yaml` exists and passes schema validation
+- `AGENTS.md` exists with project-specific content (not just the template)
+- `.harness/` directory exists with appropriate state files
+- `harness validate` passes with zero errors
+- `harness check-deps` passes (intermediate and above)
+- 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
+
+### Example: New TypeScript Project (Basic Level)
+
+**ASSESS:**
+
+```
+Human: "I'm starting a new TypeScript API project using Express and Vitest."
+Check for .harness/ — not found. This is a new project.
+Recommend: basic level (new project, start simple).
+Human confirms: "Basic is fine for now."
+```
+
+**SCAFFOLD:**
+
+```bash
+harness init --level basic --framework express
+# Creates: harness.yaml, .harness/, AGENTS.md (template)
+```
+
+**CONFIGURE:**
+
+```
+Edit AGENTS.md:
+  - Add project description: "REST API for widget management"
+  - 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:**
+
+```bash
+harness validate  # Pass — basic level checks satisfied
+git add harness.yaml .harness/ AGENTS.md
+git commit -m "feat: initialize harness project at basic level"
+```
+
+### Example: Migrating Existing Project from Basic to Intermediate
+
+**ASSESS:**
+
+```
+Read harness.yaml — level: basic
+Read AGENTS.md — exists, has project-specific content
+Run: harness validate — passes at basic level
+Recommend: intermediate (add layers and dependency constraints)
+Human confirms: "Yes, we're ready for layers."
+```
+
+**SCAFFOLD:**
+
+```bash
+harness init --level intermediate --migrate
+# Preserves existing harness.yaml and AGENTS.md
+# Adds: layer definitions template, dependency constraints template
+```
+
+**CONFIGURE:**
+
+```
+Define layers in harness.yaml:
+  - presentation: src/routes/, src/middleware/
+  - business: src/services/, src/models/
+  - data: src/repositories/, src/db/
+
+Define constraints:
+  - presentation → business (allowed)
+  - business → data (allowed)
+  - data → presentation (forbidden)
+  - presentation → data (forbidden — must go through business)
+
+Update AGENTS.md with layer documentation.
+```
+
+**VALIDATE:**
+
+```bash
+harness validate      # Pass — intermediate level checks satisfied
+harness check-deps    # Pass — no constraint violations in existing code
+git add -A
+git commit -m "feat: migrate harness project to intermediate level with layers"
+```
+
+### Example: Adoption Level Progression
+
+**Basic (start here):**
+
+- `AGENTS.md` with project context
+- `harness.yaml` with metadata
+- `harness validate` runs in development
+
+**Intermediate (add structure):**
+
+- Layer definitions and boundaries
+- Dependency constraints enforced by `harness check-deps`
+- At least one custom skill for team workflows
+
+**Advanced (full integration):**
+
+- Persona configuration for consistent agent behavior
+- State management across sessions
+- `.harness/learnings.md` capturing institutional knowledge
+- `harness validate` runs in CI pipeline
+- Custom skills for all common team workflows

package/dist/agents/skills/gemini-cli/initialize-harness-project/skill.yaml

@@ -0,0 +1,31 @@
+name: initialize-harness-project
+version: "1.0.0"
+description: Scaffold a new harness-compliant project
+cognitive_mode: constructive-architect
+triggers:
+  - manual
+  - on_project_init
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Glob
+cli:
+  command: harness skill run initialize-harness-project
+  args:
+    - name: path
+      description: Project root path
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: initialize-harness-project
+    path: string
+type: flexible
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/validate-context-engineering/SKILL.md

@@ -0,0 +1,150 @@
+# Validate Context Engineering
+
+> Validate AGENTS.md quality and evolve it as the codebase changes. Good context engineering means AI agents always have accurate, current knowledge about the project.
+
+## When to Use
+
+- After adding new files, modules, or packages to the project
+- After renaming, moving, or deleting significant files
+- After changing public APIs, architectural patterns, or conventions
+- When onboarding a new contributor (human or AI) and want to verify context is current
+- When `on_context_check` or `on_pre_commit` triggers fire
+- Periodically (weekly or per-sprint) as a hygiene check
+- NOT when making trivial changes (typo fixes, comment updates, formatting)
+- NOT during active feature development — run this between features or at cycle boundaries
+
+## Process
+
+### Phase 1: Audit — Run Automated Checks
+
+1. **Run `harness validate`** to check overall project health. Review any context-related warnings or errors in the output.
+
+2. **Run `harness check-docs`** to detect documentation gaps, broken links, and stale references. Capture the full output for analysis.
+
+3. **Review AGENTS.md manually.** Automated tools catch structural issues but miss semantic drift. Read each section and ask: "Is this still true?"
+
+### Graph-Enhanced Context (when available)
+
+When a knowledge graph exists at `.harness/graph/`, use graph queries for faster, more accurate auditing:
+
+- `query_graph` — find all undocumented code nodes (file nodes without `documents` edges), replacing manual cross-referencing
+- `search_similar` — detect stale references in AGENTS.md by matching section text against current code entities
+
+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:
+
+1. **Undocumented files.** New source files, modules, or packages that are not mentioned in AGENTS.md or any knowledge map section. These are the highest priority — an AI agent encountering these files has no context.
+
+2. **Broken links.** References to files, functions, or URLs that no longer exist. These actively mislead agents.
+
+3. **Stale sections.** Content that was accurate when written but no longer reflects reality. Examples: renamed functions still referenced by old name, removed features still described, changed conventions not updated.
+
+4. **Missing context.** Sections that exist but lack critical information. A module is listed but its purpose, constraints, or relationships are not explained. An AI agent can find the file but does not understand why it exists or how to use it correctly.
+
+### Phase 3: Suggest Updates
+
+For each gap, generate a specific suggestion:
+
+- **Undocumented files:** Draft a new section or entry with the file path, purpose, key exports, and relationship to existing modules. Use the existing AGENTS.md style and structure.
+- **Broken links:** Identify the correct target (renamed file, moved function) or recommend removal if the target was deleted.
+- **Stale sections:** Draft replacement text that reflects current reality. Show the diff between old and new.
+- **Missing context:** Draft additional content that fills the gap. Focus on what an AI agent needs to know: purpose, constraints, relationships, and gotchas.
+
+### Phase 4: Apply with Approval
+
+1. **Present all suggestions as a grouped list.** Organize by section of AGENTS.md for easy review.
+
+2. **Apply approved changes.** Update AGENTS.md with the approved suggestions. Preserve existing formatting and style.
+
+3. **Re-run `harness check-docs`** to verify all fixes are clean. No new issues should be introduced.
+
+4. **Commit the update.** Use a descriptive commit message that summarizes what was updated and why.
+
+## What Makes Good AGENTS.md Content
+
+Good context engineering treats AGENTS.md as a **dynamic knowledge base**, not a static document.
+
+- **Accuracy over completeness.** A small, accurate AGENTS.md is better than a comprehensive but stale one. Every statement must be verifiable against the current codebase.
+- **Purpose-first descriptions.** Do not just list files. Explain WHY each module exists, what problem it solves, and what constraints apply to it.
+- **Relationship mapping.** Show how modules connect. Which modules depend on which? What are the boundaries? An agent reading one section should understand how it fits into the whole.
+- **Gotchas and constraints.** Document the non-obvious. What will break if someone does X? What patterns must be followed? What is forbidden and why?
+- **Change-friendly structure.** Organize so that adding a new module means adding one section, not updating ten places. Use consistent formatting so automated tools can parse it.
+- **Actionable guidance.** Every section should help an agent make correct decisions. "This module handles authentication" is less useful than "This module handles authentication. All auth changes must go through the AuthService class. Direct database access for auth data is forbidden — use the repository layer."
+
+## Harness Integration
+
+- **`harness validate`** — Full project health check. Reports context gaps as part of overall validation.
+- **`harness check-docs`** — Focused documentation audit. Detects broken links, missing references, stale sections, and undocumented files.
+- **`harness fix-drift`** — Auto-fix simple drift issues (broken links, renamed references). Use after manual review confirms the fixes are correct.
+
+## Success Criteria
+
+- `harness check-docs` passes with zero errors and zero warnings
+- Every source file that contains public API or architectural significance is referenced in AGENTS.md
+- All file paths and function names in AGENTS.md match the current codebase
+- All links (internal and external) resolve correctly
+- AGENTS.md sections accurately describe current module purposes, constraints, and relationships
+- A new AI agent reading AGENTS.md can navigate the codebase and make correct decisions without additional guidance
+
+## Examples
+
+### Example: New module added but not documented
+
+**Audit output from `harness check-docs`:**
+
+```
+WARNING: Undocumented file detected: src/services/notification-service.ts
+  - File contains 3 public exports: NotificationService, NotificationType, sendNotification
+  - File is imported by 4 other modules
+  - No AGENTS.md section references this file
+```
+
+**Suggested update:**
+
+```markdown
+### Notification Service (`src/services/notification-service.ts`)
+
+Handles all outbound notifications (email, Slack, webhook). All notification delivery
+must go through `NotificationService` — direct use of transport libraries (nodemailer,
+Slack SDK) outside this module is forbidden.
+
+- `NotificationType` — enum of supported notification channels
+- `sendNotification()` — primary entry point; routes to the correct transport
+- Requires `NOTIFICATION_CONFIG` environment variables to be set
+- Respects rate limits defined in `harness.config.json` under `notifications`
+```
+
+**Apply:** Add the section under the Services heading in AGENTS.md. Re-run `harness check-docs` to confirm the warning is resolved.
+
+### Example: Renamed function still referenced by old name
+
+**Audit output:**
+
+```
+ERROR: Broken reference in AGENTS.md line 47: `calculateShipping()`
+  - Function was renamed to `computeShippingCost()` in commit abc123
+  - Located in src/services/shipping.ts
+```
+
+**Fix:** Replace `calculateShipping()` with `computeShippingCost()` in AGENTS.md. Verify no other references to the old name exist.
+
+## Escalation
+
+- **When AGENTS.md is severely outdated (>20 issues):** Do not attempt to fix everything at once. Prioritize: broken links first, then undocumented public APIs, then stale descriptions. Batch the work across multiple commits.
+- **When you are unsure whether a section is stale:** Check git blame for the section and compare against recent changes to the referenced files. If the section has not been updated since the referenced files changed, it is likely stale.
+- **When the project has no AGENTS.md:** Escalate to the human. Creating an AGENTS.md from scratch is a significant decision about project structure and should be done intentionally, not automatically.

package/dist/agents/skills/gemini-cli/validate-context-engineering/skill.yaml

@@ -0,0 +1,31 @@
+name: validate-context-engineering
+version: "1.0.0"
+description: Validate repository context engineering practices (AGENTS.md, doc coverage, knowledge map)
+cognitive_mode: meticulous-verifier
+triggers:
+  - manual
+  - on_pr
+  - on_commit
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Glob
+cli:
+  command: harness skill run validate-context-engineering
+  args:
+    - name: path
+      description: Project root path
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: validate-context-engineering
+    path: string
+type: flexible
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/shared/i18n-knowledge/accessibility/intersection.yaml

@@ -0,0 +1,142 @@
+description: "Rules at the intersection of i18n and accessibility — ensuring localized content remains accessible across languages, scripts, and text directions"
+
+rules:
+  - name: "lang attribute on html element"
+    category: "lang-tags"
+    wcag_criteria: ["3.1.1"]
+    description: "The <html> element must have a valid lang attribute matching the page's primary language"
+    detect:
+      method: "Check for lang attribute on <html> element; verify it matches a valid BCP 47 tag and corresponds to the page content language"
+    reason: "Screen readers use the lang attribute to select the correct pronunciation engine. Without it, an English screen reader will mispronounce French content."
+    fix: "Set <html lang='fr'> for French content, <html lang='ar' dir='rtl'> for Arabic, etc. Update dynamically when locale changes."
+    severity: error
+    strictness:
+      permissive: warn
+      standard: error
+      strict: error
+
+  - name: "lang attribute on inline language switches"
+    category: "lang-tags"
+    wcag_criteria: ["3.1.2"]
+    description: "Inline content in a different language must be wrapped with a lang attribute"
+    detect:
+      method: "Check for foreign-language words or phrases without a lang attribute on their container"
+    reason: "Screen readers will pronounce foreign words using the page's primary language rules, making them unintelligible."
+    fix: "Wrap language switches: <span lang='fr'>bonjour</span> within English content, <span lang='en'>API</span> within Japanese content."
+    severity: warning
+    strictness:
+      permissive: info
+      standard: warn
+      strict: error
+
+  - name: "dir attribute for RTL content"
+    category: "bidi-a11y"
+    wcag_criteria: ["1.3.2"]
+    description: "RTL content must have dir='rtl' set on the appropriate container element"
+    detect:
+      method: "Check for Arabic, Hebrew, or other RTL script content without a dir attribute on its container"
+    reason: "Without dir='rtl', screen readers may read RTL text in the wrong order, and visual rendering will be incorrect."
+    fix: "Set dir='rtl' on containers with RTL content. For the full page: <html lang='ar' dir='rtl'>. For inline: <span dir='rtl'>."
+    severity: error
+    strictness:
+      permissive: warn
+      standard: error
+      strict: error
+
+  - name: "dir=auto on user-generated content"
+    category: "bidi-a11y"
+    wcag_criteria: ["1.3.2"]
+    description: "User-generated content containers should use dir='auto' to detect text direction automatically"
+    detect:
+      method: "Check for user-generated content areas (comments, messages, reviews) without dir='auto'"
+    reason: "User content may be in any language. Without dir='auto', an Arabic comment in an English page will render incorrectly."
+    fix: "Set dir='auto' on elements that display user-generated content: <p dir='auto'>{userComment}</p>"
+    severity: warning
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "Font size scaling for complex scripts"
+    category: "script-sizing"
+    wcag_criteria: ["1.4.4"]
+    description: "Complex scripts (Devanagari, Thai, Arabic, CJK) require larger minimum font sizes for legibility"
+    detect:
+      method: "Check minimum font sizes when content language uses complex scripts; flag sizes below recommended minimums"
+    reason: "Complex scripts have more visual detail per character. Arabic letters reshape by position. Thai stacks diacritics vertically. Below 12-14px, these become illegible."
+    fix: "Set minimum font sizes: 12px for CJK, 13px for Arabic, 14px for Devanagari and Thai. Increase line-height to 1.6-1.8 for scripts with stacking marks."
+    severity: warning
+    strictness:
+      permissive: info
+      standard: warn
+      strict: error
+
+  - name: "Screen reader pronunciation of numbers and dates"
+    category: "screen-readers"
+    wcag_criteria: ["1.3.1"]
+    description: "Numbers and dates must use semantic markup so screen readers pronounce them correctly per locale"
+    detect:
+      method: "Check for visually formatted numbers/dates that lack semantic markup (time element, appropriate ARIA)"
+    reason: "A screen reader seeing '03/04/2025' cannot determine if it is March 4 or April 3 without semantic context. '1.234' could be one-point-two-three-four or one-thousand-two-hundred-thirty-four."
+    fix: "Use <time datetime='2025-03-04'>March 4, 2025</time> for dates. Use aria-label for ambiguous number formats."
+    severity: warning
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "ARIA labels must be translated"
+    category: "screen-readers"
+    wcag_criteria: ["4.1.2"]
+    description: "All ARIA labels, descriptions, and live region content must go through the translation pipeline"
+    detect:
+      method: "Check for hardcoded English strings in aria-label, aria-description, aria-roledescription attributes"
+    reason: "Untranslated ARIA labels make the interface inaccessible to screen reader users in non-English locales."
+    fix: "Wrap ARIA attributes in translation functions: aria-label={t('nav.menu')} instead of aria-label='Menu'"
+    severity: error
+    strictness:
+      permissive: warn
+      standard: error
+      strict: error
+
+  - name: "hreflang attribute on alternate-language links"
+    category: "lang-tags"
+    wcag_criteria: ["3.1.1"]
+    description: "Links to alternate-language versions of a page must have hreflang attributes"
+    detect:
+      method: "Check for <link rel='alternate'> elements without hreflang, or language switcher links without hreflang"
+    reason: "hreflang helps search engines serve the correct language version and assists screen readers in announcing the target language."
+    fix: "Add hreflang to all alternate links: <link rel='alternate' hreflang='es' href='/es/page'>. Include x-default for the default version."
+    severity: warning
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "Translated alt text for images"
+    category: "screen-readers"
+    wcag_criteria: ["1.1.1"]
+    description: "Image alt text must be translated along with all other user-facing content"
+    detect:
+      method: "Check for img alt attributes containing English text when the page language is non-English"
+    reason: "Untranslated alt text is meaningless to screen reader users who do not speak the source language."
+    fix: "Include all alt attributes in the translation pipeline: <img alt={t('hero.alt')} /> instead of hardcoded text"
+    severity: error
+    strictness:
+      permissive: warn
+      standard: error
+      strict: error
+
+  - name: "Keyboard navigation in RTL layouts"
+    category: "bidi-a11y"
+    wcag_criteria: ["2.4.3"]
+    description: "Tab order must follow visual order in RTL layouts — right-to-left, top-to-bottom"
+    detect:
+      method: "Check tab order in RTL layouts; verify it matches the visual reading order (right to left)"
+    reason: "If tab order remains LTR in an RTL layout, keyboard users navigate against the visual flow, causing confusion."
+    fix: "Use CSS logical properties for layout; avoid manual tabindex that assumes LTR order; test tab navigation with RTL locale"
+    severity: error
+    strictness:
+      permissive: info
+      standard: warn
+      strict: error

package/dist/agents/skills/shared/i18n-knowledge/anti-patterns/encoding.yaml

@@ -0,0 +1,67 @@
+description: "Encoding anti-patterns — common mistakes in character encoding, Unicode handling, and text measurement that break with non-ASCII content"
+
+patterns:
+  - name: "Assuming 1 character equals 1 byte"
+    severity: error
+    scope: all
+    detect:
+      method: "Check for buffer allocation or data storage sized by string.length for strings that may contain non-ASCII"
+      context: "Buffer.alloc(str.length) or database VARCHAR columns sized by character count for UTF-8 data"
+    reason: "UTF-8 encodes characters in 1-4 bytes. 'hello' is 5 bytes but 'こんにちは' is 15 bytes. Buffer overflow or truncation results."
+    instead: "Use Buffer.byteLength(str, 'utf8') for byte calculations; size database columns for byte length not character count"
+    strictness:
+      permissive: info
+      standard: warn
+      strict: error
+
+  - name: "String length not equal to visual width"
+    severity: warning
+    scope: all
+    detect:
+      method: "Check for string.length used to estimate visual display width"
+      context: "Layout calculations or column alignment using .length instead of visual width measurement"
+    reason: "CJK characters are double-width visually but .length counts them as 1. Emoji may be multiple code points but one visual glyph."
+    instead: "Use Intl.Segmenter for grapheme counting; use canvas.measureText() or terminal wcwidth for visual width"
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "Missing UTF-8 BOM handling"
+    severity: warning
+    scope: all
+    detect:
+      method: "Check for file reading that does not strip BOM (U+FEFF) from the beginning of text files"
+      context: "Reading CSV, JSON, or translation files that may have been edited in Windows tools that add BOM"
+    reason: "BOM at the start of a file can break JSON parsing, CSV parsing, and string comparison. Windows Notepad adds BOM by default."
+    instead: "Strip BOM when reading files: content.replace(/^\\uFEFF/, '') or use a BOM-aware file reader"
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "Emoji and ZWJ sequence handling"
+    severity: warning
+    scope: all
+    detect:
+      method: "Check for string operations that split or truncate without grapheme cluster awareness"
+      context: "Array.from(str) or str.split('') used to process strings containing emoji"
+    reason: "Family emoji (👨‍👩‍👦) is 5 code points joined by ZWJ. Splitting by code point produces broken fragments."
+    instead: "Use Intl.Segmenter(locale, { granularity: 'grapheme' }) to iterate over visual characters safely"
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "Filename and URL encoding not handling non-ASCII"
+    severity: error
+    scope: all
+    detect:
+      method: "Check for file path or URL construction that does not encode non-ASCII characters"
+      context: "Path concatenation with user input or locale-specific filenames without encodeURIComponent"
+    reason: "Non-ASCII filenames and URL segments must be percent-encoded. Unencoded characters cause 404 errors and security issues."
+    instead: "Use encodeURIComponent() for URL segments; use encodeURI() for full URLs; normalize filenames to ASCII-safe slugs"
+    strictness:
+      permissive: warn
+      standard: error
+      strict: error