@harness-engineering/cli 1.14.0 → 1.16.0

package/dist/agents/skills/codex/harness-test-data/SKILL.md

@@ -0,0 +1,268 @@
+# Harness Test Data
+
+> Test factories, fixtures, database seeding, and test data isolation. Establishes patterns for creating realistic, composable test data without coupling tests to specific database states.
+
+## When to Use
+
+- Setting up test data factories for a new domain model or entity
+- Migrating from shared test fixtures to isolated factory-based test data
+- Establishing database seeding for development, staging, or test environments
+- NOT when writing the tests themselves (use harness-tdd or harness-e2e instead)
+- NOT when designing the database schema (use harness-database instead)
+- NOT when testing data pipeline transformations (use harness-data-validation instead)
+
+## Process
+
+### Phase 1: DETECT -- Identify Models and Existing Patterns
+
+1. **Catalog domain models.** Scan for:
+   - ORM model definitions (Prisma schema, TypeORM entities, Django models, SQLAlchemy models)
+   - Database migration files that reveal table structures and relationships
+   - TypeScript/Python type definitions for domain objects
+
+2. **Map model relationships.** For each model, identify:
+   - Required fields and their types
+   - Foreign key relationships and cardinality (one-to-one, one-to-many, many-to-many)
+   - Unique constraints, enums, and validation rules
+   - Default values and auto-generated fields (IDs, timestamps)
+
+3. **Inventory existing test data patterns.** Search for:
+   - Factory files (fishery, factory-bot, factory_boy, rosie)
+   - Fixture files (JSON, YAML, SQL seed files)
+   - Inline test data (objects constructed directly in test files)
+   - Shared test setup files (beforeAll/beforeEach with data creation)
+
+4. **Identify test data problems.** Flag:
+   - Tests that share mutable data (one test's setup affects another)
+   - Hardcoded IDs or magic values that break when database is reset
+   - Missing cleanup leading to test pollution
+   - Overly complex setup that obscures test intent
+
+5. **Report findings.** Summarize: models found, existing patterns, and specific problems to address.
+
+### Phase 2: DESIGN -- Choose Patterns and Plan Structure
+
+1. **Select the factory pattern.** Based on the project's language and conventions:
+   - **TypeScript/JavaScript:** fishery (type-safe factories with traits), or a custom builder pattern
+   - **Python:** factory_boy (Django/SQLAlchemy integration), or Faker-based builders
+   - **Go:** custom builder functions with functional options pattern
+   - **Ruby:** factory_bot with traits and transient attributes
+
+2. **Design the factory API.** Each factory must support:
+   - Default creation: `UserFactory.build()` returns a valid object with sensible defaults
+   - Override: `UserFactory.build({ name: 'Custom' })` overrides specific fields
+   - Traits: `UserFactory.build({ trait: 'admin' })` applies a named set of overrides
+   - Associations: `ProjectFactory.build()` automatically creates a related `User` owner
+   - Batch creation: `UserFactory.buildList(5)` returns an array
+
+3. **Plan data relationships.** Define how factories handle foreign keys:
+   - Lazy association: create the related record only when needed
+   - Explicit association: pass an existing related record to avoid duplicates
+   - Transient attributes: factory parameters that control behavior but are not persisted
+
+4. **Design cleanup strategy.** Choose based on test infrastructure:
+   - **Transaction rollback:** wrap each test in a transaction (fastest, requires framework support)
+   - **Truncation:** truncate tables between tests in dependency order
+   - **Deletion:** delete records created by the test using tracked IDs
+   - **Database recreation:** drop and recreate the test database per suite (slowest, most isolated)
+
+5. **Define seed data tiers.** Separate:
+   - Reference data: enums, categories, roles -- loaded once, read-only
+   - Scenario data: realistic datasets for development and demos
+   - Test data: minimal data created per-test via factories
+
+### Phase 3: SCAFFOLD -- Generate Factories and Seed Scripts
+
+1. **Create the factory directory structure.** Follow the project's conventions:
+   - `tests/factories/` or `src/__tests__/factories/` for unit/integration test factories
+   - `seeds/` or `prisma/seed.ts` for database seeding scripts
+   - `tests/fixtures/` for static fixture data (JSON, YAML)
+
+2. **Generate a factory for each domain model.** Each factory file contains:
+   - Default attribute definitions using realistic fake data (Faker for names, emails, dates)
+   - Traits for common variations (active/inactive, admin/member, draft/published)
+   - Association handling for required relationships
+   - Type safety: factory output matches the model type definition
+
+3. **Generate a factory index.** Create a barrel file that exports all factories for easy importing:
+
+   ```
+   import { UserFactory, ProjectFactory, TaskFactory } from '../factories';
+   ```
+
+4. **Create seed scripts.** Generate:
+   - Reference data seeder: loads enums, categories, and lookup tables
+   - Development seeder: creates a realistic dataset for local development
+   - Test seeder: minimal baseline data required by most tests
+
+5. **Create cleanup utilities.** Generate:
+   - Database cleanup function that truncates or deletes in correct dependency order
+   - Test lifecycle hooks (beforeEach/afterEach) that integrate cleanup
+   - Transaction wrapper for test isolation (if supported by the ORM)
+
+6. **Verify factories produce valid data.** Write a smoke test that builds one instance of every factory and validates it against the model schema.
+
+### Phase 4: VALIDATE -- Verify Isolation, Composability, and Correctness
+
+1. **Test factory defaults.** For each factory, verify:
+   - `build()` returns a valid object that passes model validation
+   - Required fields are populated with realistic values
+   - Unique fields generate unique values across multiple builds
+   - Associations are created when needed and reused when provided
+
+2. **Test factory composition.** Verify:
+   - Traits compose correctly: `UserFactory.build({ traits: ['admin', 'verified'] })` applies both
+   - Overrides take precedence over defaults and traits
+   - Batch creation produces distinct records with unique identifiers
+
+3. **Test data isolation.** Run the test suite with factory-generated data and verify:
+   - Tests pass in any execution order (run with randomized order flag)
+   - No test reads data created by another test
+   - Cleanup runs correctly between tests (no orphaned records)
+
+4. **Test seed scripts.** Verify:
+   - Seed scripts are idempotent (running twice does not create duplicates)
+   - Reference data seeder can run against an empty database
+   - Development seeder creates a realistic, navigable dataset
+
+5. **Run `harness validate`.** Confirm the project passes all harness checks with factory infrastructure in place.
+
+### Graph Refresh
+
+If a knowledge graph exists at `.harness/graph/`, refresh it after code changes to keep graph queries accurate:
+
+```
+harness scan [path]
+```
+
+## Harness Integration
+
+- **`harness validate`** -- Run in VALIDATE phase after all factories and seed scripts are created. Confirms project health.
+- **`harness check-deps`** -- Run after SCAFFOLD phase to ensure test factory dependencies (Faker, fishery) are in devDependencies, not dependencies.
+- **`emit_interaction`** -- Used at design checkpoints to present factory pattern options and cleanup strategy choices to the human.
+- **Grep** -- Used in DETECT phase to find inline test data, hardcoded IDs, and existing factory patterns.
+- **Glob** -- Used to catalog model definitions, migration files, and existing fixture files.
+
+## Success Criteria
+
+- Every domain model has a corresponding factory with sensible defaults
+- Factories produce valid objects that pass model validation without any overrides
+- No test file contains inline object construction for domain models (all use factories)
+- Tests pass in any execution order, confirming data isolation
+- Seed scripts are idempotent and documented
+- Cleanup runs between tests with no orphaned records
+- `harness validate` passes with factory infrastructure in place
+
+## Examples
+
+### Example: Fishery Factories for a TypeScript Project
+
+**SCAFFOLD -- User factory with traits:**
+
+```typescript
+// tests/factories/user.factory.ts
+import { Factory } from 'fishery';
+import { faker } from '@faker-js/faker';
+import { User } from '../../src/types/user';
+
+export const UserFactory = Factory.define<User>(({ sequence, params, transientParams }) => ({
+  id: `user-${sequence}`,
+  email: params.email ?? faker.internet.email(),
+  name: params.name ?? faker.person.fullName(),
+  role: params.role ?? 'member',
+  status: params.status ?? 'active',
+  createdAt: params.createdAt ?? faker.date.past(),
+  updatedAt: new Date(),
+}));
+
+// Traits
+export const AdminUser = UserFactory.params({ role: 'admin' });
+export const InactiveUser = UserFactory.params({ status: 'inactive' });
+```
+
+**SCAFFOLD -- Project factory with association:**
+
+```typescript
+// tests/factories/project.factory.ts
+import { Factory } from 'fishery';
+import { faker } from '@faker-js/faker';
+import { Project } from '../../src/types/project';
+import { UserFactory } from './user.factory';
+
+export const ProjectFactory = Factory.define<Project>(({ sequence, associations }) => ({
+  id: `project-${sequence}`,
+  name: faker.commerce.productName(),
+  description: faker.lorem.sentence(),
+  owner: associations.owner ?? UserFactory.build(),
+  ownerId: associations.owner?.id ?? `user-${sequence}`,
+  status: 'active',
+  createdAt: faker.date.past(),
+}));
+```
+
+### Example: factory_boy for a Django Project
+
+**SCAFFOLD -- Django model factories:**
+
+```python
+# tests/factories.py
+import factory
+from factory.django import DjangoModelFactory
+from faker import Faker
+from myapp.models import User, Organization, Project
+
+fake = Faker()
+
+class OrganizationFactory(DjangoModelFactory):
+    class Meta:
+        model = Organization
+
+    name = factory.LazyFunction(lambda: fake.company())
+    slug = factory.LazyAttribute(lambda o: o.name.lower().replace(' ', '-'))
+
+class UserFactory(DjangoModelFactory):
+    class Meta:
+        model = User
+
+    email = factory.LazyFunction(lambda: fake.unique.email())
+    name = factory.LazyFunction(lambda: fake.name())
+    organization = factory.SubFactory(OrganizationFactory)
+
+    class Params:
+        admin = factory.Trait(is_staff=True, is_superuser=True)
+
+class ProjectFactory(DjangoModelFactory):
+    class Meta:
+        model = Project
+
+    name = factory.LazyFunction(lambda: fake.catch_phrase())
+    owner = factory.SubFactory(UserFactory)
+    organization = factory.LazyAttribute(lambda p: p.owner.organization)
+```
+
+**Usage in tests:**
+
+```python
+def test_project_belongs_to_owner_organization():
+    project = ProjectFactory.create()
+    assert project.organization == project.owner.organization
+
+def test_admin_can_delete_any_project():
+    admin = UserFactory.create(admin=True)
+    project = ProjectFactory.create()
+    assert admin.has_perm('delete_project', project)
+```
+
+## Gates
+
+- **No hardcoded IDs in factories.** Factories must generate unique IDs per instance. Hardcoded IDs cause collision failures when tests run in parallel. Use sequences or UUIDs.
+- **No production data in test fixtures.** Test data must be synthetic. If a fixture file contains real customer names, emails, or PII, it must be replaced with Faker-generated data before merging.
+- **Factories must produce valid objects.** A factory `build()` with zero overrides must return an object that passes model validation. If it requires manual overrides to be valid, the defaults are wrong.
+- **Cleanup must be explicit.** Do not rely on test framework teardown happening "eventually." Every test or test suite that creates database records must have an explicit cleanup step that runs even when tests fail.
+
+## Escalation
+
+- **When models have circular dependencies (User has Projects, Project has Owner User):** Use lazy evaluation or two-pass creation. Create the User first without Projects, create the Project with the User, then optionally update the User. Document the pattern in the factory file.
+- **When the database schema is too complex for factories (50+ models):** Prioritize factories for the models that appear most frequently in tests. Use a tiered approach: core factories first, then add factories for secondary models as tests demand them.
+- **When seed data conflicts with migration state:** Seed scripts must be updated whenever migrations change the schema. If seeds fail after a migration, fix the seeds immediately -- do not skip seeding.
+- **When test isolation requires database-level features (row-level security, multi-tenancy):** Factory cleanup may need tenant-aware truncation. Escalate to ensure the cleanup strategy respects the application's multi-tenancy model.

package/dist/agents/skills/codex/harness-test-data/skill.yaml

@@ -0,0 +1,74 @@
+name: harness-test-data
+version: "1.0.0"
+description: Test factories, fixtures, database seeding, and test data isolation
+cognitive_mode: advisory-guide
+triggers:
+  - manual
+  - on_new_feature
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - emit_interaction
+cli:
+  command: harness skill run harness-test-data
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: pattern
+      description: "Data pattern: factory, fixture, builder, or seed. Auto-detected when omitted."
+      required: false
+    - name: model
+      description: "Target model or entity name for focused factory generation."
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-test-data
+    path: string
+type: rigid
+tier: 3
+internal: false
+keywords:
+  - test data
+  - factory
+  - fixture
+  - seed
+  - faker
+  - test database
+  - isolation
+  - cleanup
+  - test container
+  - builder pattern
+  - mother object
+stack_signals:
+  - "tests/factories/"
+  - "tests/fixtures/"
+  - "src/**/factories/**"
+  - "seeds/"
+  - "test-data/"
+  - "src/**/__fixtures__/"
+phases:
+  - name: detect
+    description: Identify data models, existing test data patterns, and database schema
+    required: true
+  - name: design
+    description: Choose factory pattern, define builder interfaces, and plan data relationships
+    required: true
+  - name: scaffold
+    description: Generate factories, fixtures, seed scripts, and cleanup utilities
+    required: true
+  - name: validate
+    description: Verify data isolation, cleanup correctness, and factory composability
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/harness-ux-copy/SKILL.md

@@ -0,0 +1,271 @@
+# Harness UX Copy
+
+> Audit microcopy, error messages, and UI strings for voice/tone consistency, clarity, and actionability. Produces a structured report with specific rewrites and a project voice guide when none exists.
+
+## When to Use
+
+- When reviewing a PR that adds or changes user-facing text (labels, error messages, tooltips, onboarding flows)
+- When establishing or enforcing a voice/tone guide across a product
+- When error messages are vague, blame the user, or lack actionable next steps
+- NOT for internationalization string extraction (use harness-i18n)
+- NOT for accessibility auditing of non-text elements (use harness-accessibility)
+- NOT for marketing copy or landing page content outside the application
+
+## Process
+
+### Phase 1: DISCOVER -- Locate UI String Sources
+
+1. **Resolve project root.** Use provided path or cwd.
+
+2. **Locate voice/tone guide.** Search for `VOICE.md`, `STYLE.md`, `docs/voice-guide.md`, `docs/tone.md`, or a `voice` section in `harness.config.json`. If no guide is found, flag this as a gap and use sensible defaults (clear, concise, respectful, action-oriented).
+
+3. **Identify string sources.** Scan the project for UI text using multiple strategies:
+   - Component files: `src/**/components/**/*.{tsx,jsx,vue,svelte}` for inline text
+   - String constants: `src/**/strings*`, `src/**/messages*`, `src/**/copy*` for centralized copy
+   - i18n files: `src/**/i18n/**`, `locales/`, `translations/` for translation keys
+   - Error definitions: files containing `throw new Error`, `toast.error`, `setError`, `addNotification`
+   - Form labels: files containing `label=`, `placeholder=`, `aria-label=`, `helperText=`
+
+4. **Determine audit scope.** If `--scope` is provided, filter to the specified category. If triggered by a PR, scope to changed files only using `git diff --name-only`.
+
+5. **Build string inventory.** Extract all user-facing strings with their source location, category (error, label, help, onboarding, confirmation, empty-state), and surrounding context.
+
+6. **Report discovery summary.** Output the count of strings found by category and source type:
+   ```
+   Discovery: 142 strings found
+     Errors: 23 | Labels: 48 | Help text: 31 | Onboarding: 12 | Empty states: 8 | Other: 20
+     Sources: 18 components, 3 string files, 2 i18n bundles
+   ```
+
+---
+
+### Phase 2: AUDIT -- Evaluate Copy Quality
+
+1. **Check error messages against quality rules.** Every error message must satisfy:
+   - **What happened:** Describe the problem without technical jargon
+   - **Why it happened:** Provide context when possible (not "An error occurred")
+   - **What to do next:** Include an actionable recovery step
+   - **No blame language:** Avoid "you failed to," "invalid input," "wrong password" -- prefer "we couldn't," "please check," "that password didn't match"
+
+2. **Check labels and form text.** Evaluate:
+   - **Clarity:** Can the user understand what is expected without additional context?
+   - **Consistency:** Are similar fields labeled the same way across the app? (e.g., "Email" vs "Email address" vs "E-mail")
+   - **Brevity:** Are labels concise without sacrificing clarity?
+   - **Placeholder misuse:** Are placeholders being used as labels? (accessibility anti-pattern)
+
+3. **Check voice/tone alignment.** Compare strings against the voice guide (or defaults):
+   - **Formality level:** Is the tone consistent? (e.g., mixing "gonna" with "We regret to inform you")
+   - **Pronoun usage:** Is first/second person used consistently? ("your account" vs "the account")
+   - **Technical jargon:** Are technical terms exposed to non-technical users?
+   - **Emotional tone:** Are error states empathetic? Are success states appropriately celebratory?
+
+4. **Check empty states and onboarding.** Evaluate:
+   - Do empty states explain what will appear and how to get started?
+   - Do onboarding flows use progressive disclosure?
+   - Are CTAs clear and specific? ("Add your first project" vs "Get started")
+
+5. **Check confirmation dialogs.** Evaluate:
+   - Is the consequence of the action clearly stated?
+   - Are button labels specific? ("Delete project" vs "OK")
+   - Is the destructive action visually distinct?
+
+6. **Classify findings by severity:**
+   - **Error:** Misleading text, blame language, missing recovery steps, accessibility violations
+   - **Warning:** Inconsistent terminology, vague CTAs, jargon exposure
+   - **Info:** Style preferences, minor tone adjustments, punctuation inconsistencies
+
+---
+
+### Phase 3: GUIDE -- Produce Recommendations
+
+1. **Generate specific rewrites.** For every error and warning finding, provide:
+   - The current string (with file location)
+   - The recommended rewrite
+   - The rule that triggered the finding
+   - A brief rationale
+
+2. **Produce consistency patches.** When terminology is inconsistent (e.g., "Sign in" vs "Log in"), recommend a single canonical term and list all locations that need updating.
+
+3. **Generate voice guide draft.** If no voice guide was found in Phase 1, produce a draft `VOICE.md` covering:
+   - Brand voice attributes (3-5 adjectives with examples)
+   - Tone spectrum (how voice changes by context: error, success, onboarding, help)
+   - Word list (preferred terms and terms to avoid)
+   - Punctuation and capitalization rules
+   - Example patterns for common UI scenarios
+
+4. **Produce error message template.** Generate a reusable template for error messages:
+
+   ```
+   [What happened]. [Why / context]. [What to do next].
+   Example: "We couldn't save your changes. The file may have been modified by someone else. Try refreshing the page and saving again."
+   ```
+
+5. **Prioritize recommendations.** Order by impact: error-severity findings first, then warnings grouped by frequency (most repeated patterns first), then informational suggestions.
+
+---
+
+### Phase 4: VALIDATE -- Verify Recommendations
+
+1. **Check rewrites preserve meaning.** Verify each recommended rewrite conveys the same information as the original. Flag any rewrite that changes the semantic meaning.
+
+2. **Check i18n compatibility.** If the project uses i18n:
+   - Verify recommended strings do not break interpolation variables (`{count}`, `{{name}}`)
+   - Verify string key references remain valid
+   - Flag any rewrites that would require translator review
+
+3. **Check length constraints.** Verify rewrites fit within UI constraints:
+   - Button labels: typically under 25 characters
+   - Toast messages: typically under 100 characters
+   - Form labels: typically under 40 characters
+   - Flag any rewrite that significantly increases string length
+
+4. **Output structured report.** Present findings in a format suitable for PR review:
+
+   ```
+   UX Copy Audit: [PASS/NEEDS_ATTENTION/FAIL]
+   Strings audited: N
+   Findings: E errors, W warnings, I info
+
+   ERRORS:
+   [UXC-ERR-001] src/components/LoginForm.tsx:42
+     Current: "Invalid credentials"
+     Recommended: "That email and password combination didn't match. Please try again or reset your password."
+     Rule: error-missing-recovery-step
+
+   WARNINGS:
+   [UXC-WARN-001] Inconsistent terminology: "Sign in" (4 occurrences) vs "Log in" (2 occurrences)
+     Recommendation: Standardize on "Sign in" across all 6 locations.
+   ```
+
+5. **Verify voice guide completeness.** If a voice guide was generated, confirm it covers all required sections and includes at least 3 examples per section.
+
+---
+
+## Harness Integration
+
+- **`harness skill run harness-ux-copy`** -- Primary command for running the UX copy audit.
+- **`harness validate`** -- Run after applying recommended changes to verify project health.
+- **`Glob`** -- Used to locate string sources, component files, and voice guides.
+- **`Grep`** -- Used to extract inline strings, error patterns, and label attributes from source files.
+- **`Read`** -- Used to read voice guides, component files, and string constant files.
+- **`Write`** -- Used to generate voice guide drafts when none exists.
+- **`emit_interaction`** -- Used to present findings and request confirmation on bulk terminology changes.
+
+## Success Criteria
+
+- All user-facing strings in scope are audited
+- Every error message is evaluated for what-happened, why, and what-to-do-next
+- Terminology inconsistencies are identified with canonical term recommendations
+- Specific rewrites are provided for every error and warning finding
+- Rewrites preserve semantic meaning and i18n compatibility
+- Voice guide exists (found or generated) with actionable patterns
+- Report follows structured format with severity classification
+
+## Examples
+
+### Example: React Application with Vague Error Messages
+
+```
+Phase 1: DISCOVER
+  Scanned: 34 components, 2 string files, 1 i18n bundle
+  Found: 89 strings (18 errors, 32 labels, 14 help text, 25 other)
+  Voice guide: not found (will generate draft)
+
+Phase 2: AUDIT
+  [UXC-ERR-001] src/components/CheckoutForm.tsx:78
+    "Payment failed" -- missing context and recovery step
+  [UXC-ERR-002] src/components/SignupForm.tsx:33
+    "Invalid email" -- blame language, no guidance
+  [UXC-WARN-001] Terminology inconsistency:
+    "Shopping cart" (3 files) vs "Cart" (5 files) vs "Basket" (1 file)
+  [UXC-WARN-002] src/components/EmptyOrders.tsx:12
+    "No orders" -- empty state missing guidance on what to do
+
+Phase 3: GUIDE
+  Rewrite: "Payment failed" ->
+    "Your payment didn't go through. Please check your card details and try again, or use a different payment method."
+  Rewrite: "Invalid email" ->
+    "Please enter a valid email address, like name@example.com."
+  Terminology: Standardize on "Cart" (most frequent, shortest)
+  Generated: VOICE.md draft with friendly-professional tone
+
+Phase 4: VALIDATE
+  All rewrites preserve original meaning: YES
+  i18n interpolation variables intact: YES
+  Length constraints met: 1 warning (payment rewrite exceeds toast limit, suggest truncated variant)
+  Result: NEEDS_ATTENTION -- 2 errors, 2 warnings
+```
+
+### Example: Vue.js SaaS Dashboard with Existing Voice Guide
+
+```
+Phase 1: DISCOVER
+  Voice guide found: docs/VOICE.md (professional, empathetic, action-oriented)
+  Scanned: 52 components, 4 string files
+  Scope: PR diff (8 changed files, 14 new/modified strings)
+
+Phase 2: AUDIT
+  [UXC-ERR-001] src/views/Settings.vue:145
+    "Error: 403 Forbidden" -- exposes HTTP status, no user context
+  [UXC-WARN-001] src/views/Dashboard.vue:67
+    "Click here to learn more" -- vague CTA, accessibility concern
+  [UXC-INFO-001] src/components/Sidebar.vue:23
+    "Organisations" -- British spelling, rest of app uses American English
+
+Phase 3: GUIDE
+  Rewrite: "Error: 403 Forbidden" ->
+    "You don't have permission to change these settings. Ask your workspace admin to update your role."
+  Rewrite: "Click here to learn more" ->
+    "Learn how to configure integrations"
+  Consistency: Standardize on American English per voice guide
+
+Phase 4: VALIDATE
+  All rewrites align with VOICE.md tone: YES
+  Result: NEEDS_ATTENTION -- 1 error, 1 warning, 1 info
+```
+
+### Example: Next.js E-commerce with i18n (next-intl)
+
+```
+Phase 1: DISCOVER
+  i18n framework: next-intl (detected via next.config.js and messages/ directory)
+  Locales: en, es, fr, de
+  Scanned: messages/en.json (312 keys)
+  Scope: --scope errors
+
+Phase 2: AUDIT
+  [UXC-ERR-001] messages/en.json -> errors.generic
+    "Something went wrong" -- no context, no recovery
+  [UXC-ERR-002] messages/en.json -> errors.network
+    "Network error" -- technical, no user action
+  [UXC-ERR-003] messages/en.json -> checkout.cardDeclined
+    "Your card was declined" -- blame language
+
+Phase 3: GUIDE
+  Rewrite: errors.generic ->
+    "Something unexpected happened on our end. Please try again, or contact support if the problem continues."
+  Rewrite: errors.network ->
+    "We're having trouble connecting. Please check your internet connection and try again."
+  Rewrite: checkout.cardDeclined ->
+    "This card couldn't be processed. Please try a different card or contact your bank."
+  Note: All rewrites use {variable} interpolation compatible with next-intl
+
+Phase 4: VALIDATE
+  Interpolation variables preserved: YES (no variables in affected keys)
+  Translator review needed: YES (3 keys modified, flag for es/fr/de update)
+  Result: NEEDS_ATTENTION -- 3 errors requiring translator coordination
+```
+
+## Gates
+
+- **No rewrite may change semantic meaning.** If a recommended rewrite alters what the user understands about the situation or available actions, it is rejected. Rewrites improve clarity and tone, not content.
+- **No breaking i18n interpolation.** Rewrites must preserve all interpolation variables exactly as they appear in the original string. A rewrite that drops `{count}` or renames `{{userName}}` is invalid.
+- **No applying bulk changes without confirmation.** When a terminology standardization affects more than 5 files, present the change list and wait for human confirmation before recommending the batch edit.
+- **No generating a voice guide that contradicts an existing one.** If a voice guide exists, recommendations must align with it. If the guide itself has problems, flag them separately rather than overriding.
+
+## Escalation
+
+- **When the voice guide conflicts with accessibility best practices:** Flag the conflict. Accessibility requirements take precedence over voice guide preferences. Example: the guide says "use playful language for errors" but playful error messages can confuse screen reader users. Recommend a voice guide amendment.
+- **When terminology standardization has brand implications:** If the inconsistency involves brand-specific terms (product names, feature names), do not auto-recommend. Present the variants and escalate to the product team: "Found 3 variants of the product tier name. This needs a product decision."
+- **When rewrites significantly increase string length:** If a rewrite exceeds UI constraints and cannot be shortened without losing critical information, flag the constraint: "This error message needs more space than the current toast component allows. Consider using an inline error or expanding the toast max-width."
+- **When error messages require backend changes:** If an error message improvement requires the backend to send more specific error codes or context, document the dependency: "Improving this message requires the API to distinguish between 'card declined' and 'card expired' -- currently both return PAYMENT_FAILED."