cfsa-antigravity 2.15.0 → 2.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cfsa-antigravity",
-  "version": "2.15.0",
+  "version": "2.18.0",
   "description": "CFSA Pipeline — Constraint-First Specification Architecture for AI agents. Production-grade from line one.",
   "scripts": {
     "changeset": "changeset",

package/template/.agent/kit-sync.md

@@ -1,6 +1,6 @@
 # Kit Sync State
 
 upstream: https://github.com/RepairYourTech/cfsa-antigravity
-last_synced_commit: 7c5b0504d422958d0c36cf83768a7b12d3a6ab2a
-last_synced_at: 2026-03-20T18:30:16Z
-kit_version: 2.15.0
+last_synced_commit: a42ee2fd17830430d03da6a4a543039c37bb9213
+last_synced_at: 2026-03-25T02:08:41Z
+kit_version: 2.18.0

package/template/.agent/rules/source-before-ask.md

@@ -0,0 +1,93 @@
+---
+description: Before any question or decision, reason about what source documents are relevant, read them, then speak — never ask from summaries alone
+trigger: always_on
+---
+
+# Source Before Ask
+
+> Never present a question, decision, or recommendation to the user without first reading the source documents that inform it. Feature names are not features. Summaries are not specs.
+
+## The Rule
+
+**Before presenting ANY question, decision, option table, or recommendation to the user:**
+
+1. **Reason about relevance.** Ask yourself: "What domains, features, deep dives, CX files, or specs contain detail that affects THIS specific decision?" Think about second-order connections — a database decision doesn't just touch the "data" domain; it touches every domain that has complex query patterns, real-time sync, or graph relationships.
+
+2. **Read those documents.** Not the summary. Not the index line. The actual source files that contain the architectural detail. If a domain has deep dives (`[DEEP]` or `[EXHAUSTED]` status), read the deep dive files — they contain the information that changes the answer.
+
+3. **Cite what you found.** When presenting the question or decision, reference what you learned: "Based on the diagnostics deep dive, your multi-agent repair flow requires X, which means option A fits better than B because..."
+
+4. **Only then ask.** Now you're asking an informed question that the user can answer without doing your research for you.
+
+## The Per-Decision Research Loop
+
+This loop fires for EVERY decision point, not once per workflow:
+
+```
+For each question/decision/recommendation:
+  1. STOP — do not type anything to the user yet
+  2. THINK — what ideation/spec/CX content is relevant to THIS decision?
+     - Which domains does this decision affect?
+     - Which features have architectural constraints that change the answer?
+     - Which cross-cuts create dependencies?
+     - Which deep dives contain the detail I need?
+  3. READ — open and read those specific files now
+  4. SYNTHESIZE — what did I learn that affects this decision?
+  5. PRESENT — now ask the question, citing what you found
+```
+
+## Common Relevance Patterns
+
+| Decision Type | What to Read Before Asking |
+|--------------|---------------------------|
+| Frontend framework | Every domain with UI complexity, responsive requirements, offline-first features, real-time updates |
+| Database / persistence | Every domain with complex data relationships, sync requirements, search patterns, graph traversals |
+| AI/ML framework | Every domain that mentions AI, ML, diagnostics, recommendations, automation, agents |
+| Auth / security | Every domain's role matrix, CX files for cross-domain permission boundaries |
+| API design | Every domain's CX files for cross-domain data flow, every deep dive with integration points |
+| Deployment / hosting | Constraints file, every surface's performance requirements, offline capabilities |
+| State management | Every domain with real-time features, collaborative editing, optimistic updates |
+| Caching strategy | Every domain's query patterns, hot paths, data freshness requirements |
+
+## Why
+
+| Without this rule | With this rule |
+|---|---|
+| Agent asks "which database?" based on a MoSCoW bullet | Agent reads the graph traversal deep dive and knows you need a graph-capable store |
+| User has to say "go read the docs" 15 times per session | Agent arrives at each question already informed |
+| Decisions feel generic — could apply to any project | Decisions are grounded in YOUR project's specific architecture |
+| Context evaporates after Step 0.5's bulk loading | Context is refreshed per-decision, exactly when it matters |
+| Agent asks questions the ideation already answered | Agent knows what's been decided and asks only what's open |
+
+## Applies To
+
+**Every pipeline stage.** This is not limited to `/create-prd`:
+
+| Stage | What This Means |
+|-------|----------------|
+| `/create-prd-stack` | Before each axis question, read the domains that axis touches |
+| `/create-prd-architecture` | Before each component design, read the domains that component serves |
+| `/create-prd-security` | Before each security item, read the role matrices and CX trust boundaries |
+| `/write-architecture-spec` | Before each interaction design, read the relevant domain deep dives |
+| `/write-be-spec` | Before each endpoint design, read the IA shard interactions that endpoint serves |
+| `/write-fe-spec` | Before each component spec, read the BE endpoints and IA interactions it consumes |
+| `/implement-slice` | Before each implementation decision, read the relevant specs |
+
+## What Gets Flagged
+
+| Pattern | Verdict |
+|---------|---------|
+| "Which database do you prefer?" without reading any domain files | ❌ Rejected. Read the domains first — the answer might be obvious. |
+| Presenting 3 framework options with generic pros/cons | ❌ Rejected. Pros/cons must reference THIS project's specific needs. |
+| Asking a question the ideation deep dives already answered | ❌ Rejected. Read before asking. |
+| "Based on your diagnostics domain's multi-agent flow, you need X" | ✅ Correct. Informed by source material. |
+| Citing specific CX dependencies when recommending architecture | ✅ Correct. Research before recommendation. |
+| Re-reading a deep dive mid-workflow because THIS question needs it | ✅ Correct. Per-decision freshness. |
+
+## The Litmus Test
+
+Before sending any question to the user, ask yourself:
+
+> **"Could a user reasonably respond: 'Did you even read my ideation docs?'"**
+
+If the answer is yes — you didn't do this rule. Stop. Read. Then ask.

package/template/.agent/rules/vertical-slices.md

@@ -1,5 +1,5 @@
 ---
-description: Features ship across all four surfaces or they don't ship — no half-built slices
+description: Features ship across all declared surfaces or they don't ship — no half-built slices
 trigger: always_on
 ---
 
@@ -9,6 +9,36 @@ trigger: always_on
 
 **A feature is not "done" until it works across all required surfaces.** No "backend done, frontend pending." No "user-facing works, admin can't manage it."
 
+## Surface Scope
+
+Every slice **must declare its surface scope** during `/plan-phase`. The surface scope defines which project surfaces (web, mobile, desktop, CLI, etc.) the slice targets. The 4-layer checklist applies **within each declared surface**, not globally across all surfaces.
+
+### Why Surface Scope Exists
+
+Multi-surface projects have features that are inherently single-surface:
+- A board-level component viewer is **desktop only** — forcing a web and mobile implementation violates the architecture
+- Push notifications are **mobile only** — there's no web surface for this feature
+- Some features launch **web-first** and port to desktop/mobile in later phases
+
+Surface scope prevents both failure modes:
+- ❌ **Under-scoping** — "backend done, frontend pending" within a declared surface
+- ❌ **Over-scoping** — forcing all surfaces when the architecture says otherwise
+
+### Surface Scope Rules
+
+1. **Every slice must declare its surface scope** during `/plan-phase`. No implicit scope — undeclared scope is rejected.
+2. **The 4-layer checklist applies within each declared surface.** A web-only slice must have all 4 layers complete for web. A desktop+mobile slice must have all 4 layers complete for both desktop and mobile.
+3. **Surface scope comes from the architecture**, not from convenience. If the architecture says a feature spans web and mobile, the slice must cover both (or be split into "web" and "mobile" slices with an explicit dependency).
+4. **Scope is locked at planning time.** Changing surface scope mid-implementation requires updating the phase plan — no silent scope reduction.
+
+### Web-First (or Surface-First) Strategy
+
+When a multi-surface feature launches on one surface first:
+- The first-surface slice is "done" when its 4 layers are complete within its declared scope
+- Ports to other surfaces are tracked as **separate dependent slices** in the phase plan
+- Each port slice has its own 4-layer checklist and its own surface scope declaration
+- Example: "User Profile — Web" (Phase 1) → "User Profile — Mobile" (Phase 2, depends on Web slice)
+
 ## The Four Implementation Layers
 
 > **Note on terminology**: The layers below describe implementation completeness criteria — what every feature slice requires regardless of surface type. These are not the same as surface types (web/mobile/cli/etc.). For the mapping between surface types and how each implementation layer manifests on that surface, see `.agent/skills/prd-templates/references/surface-model.md`.
@@ -24,22 +54,30 @@ trigger: always_on
 
 A feature slice is complete when:
 
-- [ ] Data layer: schema defined, permissions set, seed data exists
-- [ ] API layer: endpoints exist, validated with {{CONTRACT_LIBRARY}}, tested
-- [ ] User-facing: component renders, handles loading/error/empty states
-- [ ] Admin: can create/read/update/delete the resource
+- [ ] Surface scope declared in the phase plan (explicit list of target surfaces)
+- [ ] **For each declared surface:**
+  - [ ] Data layer: schema defined, permissions set, seed data exists
+  - [ ] API layer: endpoints exist, validated with {{CONTRACT_LIBRARY}}, tested
+  - [ ] User-facing: component renders, handles loading/error/empty states
+  - [ ] Admin: can create/read/update/delete the resource (if the feature has admin management)
 - [ ] Tests pass at all levels (contract, unit, integration, E2E)
 - [ ] Navigation: every new route is reachable from at least one navigation element
 - [ ] Auth gates: every route that requires auth has the auth gate implemented (not stubbed)
 - [ ] The feature is reachable from the app's entry point via normal user navigation
+- [ ] All declared surfaces complete — no partial surface delivery
 
 ## What Gets Flagged
 
 | Pattern | Verdict |
 |---------|---------|
-| "I'll add the admin panel later" | ❌ Rejected. Include admin CRUD in the slice. |
-| "The API works, frontend next sprint" | ❌ Rejected. Ship them together or not at all. |
+| Slice with no declared surface scope | ❌ Rejected. Every slice must declare its surfaces during `/plan-phase`. |
+| "I'll add the admin panel later" | ❌ Rejected. Include admin CRUD in the slice (for features with admin management). |
+| "The API works, frontend next sprint" (within same surface) | ❌ Rejected. Ship them together or not at all. |
 | "Database is set up, just need endpoints" | ❌ Rejected. That's a layer, not a slice. |
 | Route without navigation link from existing UI | ❌ Rejected. Must be reachable. |
 | Auth-required route without auth gate | ❌ Rejected. Implement the gate. |
-| All 4 layers + tests + navigation + auth gates | ✅ Correct. |
+| Desktop-only feature forced to have a web implementation | ❌ Rejected. Surface scope should match the architecture. |
+| Silently dropping a declared surface mid-implementation | ❌ Rejected. Update the phase plan or complete the surface. |
+| Web-first slice with all 4 layers complete for web, mobile tracked as separate slice | ✅ Correct. Surface-first strategy. |
+| Slice with declared scope and all layers complete within scope | ✅ Correct. |
+| All declared surfaces + tests + navigation + auth gates | ✅ Correct. |

package/template/.agent/skill-library/surface/web/i18n-localization/SKILL.md

@@ -1,39 +1,148 @@
 ---
 name: i18n-localization
-description: Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support.
-allowed-tools: Read, Glob, Grep
+description: "Internationalization and localization — structured workflow for extracting hardcoded strings, managing translations, ICU MessageFormat, Intl API, RTL support, and audit capabilities."
+version: 2.0.0
+source: self
+date_added: "2026-02-27"
+date_rewritten: "2026-03-21"
 ---
 
 # i18n & Localization
 
-> Internationalization (i18n) and Localization (L10n) best practices.
+Production-grade internationalization skill. Covers string extraction, translation management, ICU MessageFormat, all Intl APIs, RTL support, and i18n codebase auditing.
+
+## When to Use
+
+- Extracting hardcoded strings from an existing codebase
+- Setting up i18n infrastructure for a new project
+- Auditing i18n coverage and completeness
+- Adding RTL language support
+- Formatting dates, numbers, currencies, or relative times for multiple locales
+- Writing or reviewing translation strings with plural/gender/select patterns
+
+## When NOT to Use
+
+- Framework-specific i18n routing (e.g., Astro, Next.js locale routing — use the framework skill)
+- Content management / CMS translation workflows — that's a product concern
+- Machine translation quality review — out of scope
 
 ---
 
-## 1. Core Concepts
+## Core Concepts
 
 | Term | Meaning |
 |------|---------|
-| **i18n** | Internationalization - making app translatable |
-| **L10n** | Localization - actual translations |
-| **Locale** | Language + Region (en-US, tr-TR) |
-| **RTL** | Right-to-left languages (Arabic, Hebrew) |
+| **i18n** | Internationalization — making the app translatable |
+| **L10n** | Localization — actual translations for a target locale |
+| **Locale** | Language + Region code (en-US, tr-TR, ar-SA) |
+| **RTL** | Right-to-left scripts (Arabic, Hebrew, Persian, Urdu) |
+| **ICU** | International Components for Unicode — standard message format |
 
 ---
 
-## 2. When to Use i18n
+## Structured Workflow: SCAN → EXTRACT → VERIFY → PRESENT
+
+### Phase 1: SCAN
+
+Assess current state before touching any code.
+
+1. **Detect i18n library in use** — search for `react-i18next`, `next-intl`, `vue-i18n`, `@angular/localize`, `gettext`, or native `Intl` usage
+2. **Identify hardcoded user-facing strings** — grep for string literals in UI components and templates:
+   - JSX text content: `<h1>Welcome</h1>`, `<p>Loading...</p>`
+   - Attribute strings: `placeholder="Search"`, `aria-label="Close"`
+   - Alert/confirm/error messages: `alert('Error occurred')`
+   - Template literals with user-facing text in renderables
+3. **Assess current coverage** — count: already-translated strings vs hardcoded strings, namespaces in use, supported locales
+4. **Check for string concatenation** — find patterns like `"Hello, " + name` or `` `Order #${id}` `` in UI layer — these break translation
+
+**Output**: Coverage report with string counts, namespaces, and problem patterns.
+
+### Phase 2: EXTRACT
+
+Wrap strings and generate translation files.
+
+1. **Choose key convention** — use `feature.element.action` (see [ICU reference](references/icu-message-format.md) for full naming rules):
+   ```
+   auth.login.title          → "Sign In"
+   common.buttons.save       → "Save"
+   dashboard.stats.revenue   → "Total Revenue"
+   ```
+2. **Wrap strings** — replace hardcoded text with `t()` calls:
+   ```tsx
+   // Before
+   <h1>Welcome back</h1>
+   
+   // After
+   <h1>{t('dashboard.welcome.title')}</h1>
+   ```
+3. **Generate/update locale JSON** — create namespace files per feature:
+   ```
+   locales/en/auth.json
+   locales/en/common.json
+   locales/en/dashboard.json
+   ```
+4. **Handle interpolation** — convert concatenation to ICU interpolation:
+   ```json
+   { "greeting": "Welcome back, {name}" }
+   ```
+5. **Handle plurals** — use ICU MessageFormat (see [ICU reference](references/icu-message-format.md)):
+   ```json
+   { "cart.count": "{count, plural, =0 {Cart empty} one {# item} other {# items}}" }
+   ```
+
+### Phase 3: VERIFY
+
+Validate correctness before presenting results.
+
+1. **Intl API audit** — verify all locale-sensitive formatting uses `Intl` (see [Intl reference](references/intl-api-patterns.md)):
+   - Dates → `Intl.DateTimeFormat` (not `toLocaleDateString` without options)
+   - Numbers/currency → `Intl.NumberFormat`
+   - Relative time → `Intl.RelativeTimeFormat` (not manual "X days ago")
+   - Lists → `Intl.ListFormat` (not `.join(', ')`)
+2. **String concatenation check** — confirm zero string concatenation for translated content
+3. **RTL compatibility** — if RTL locales are in scope, run the [RTL checklist](references/rtl-support.md)
+4. **Missing translations** — verify every key in the default locale exists in all target locales
+5. **Unused keys** — check for translation keys that no longer appear in code
+
+### Phase 4: PRESENT
+
+Deliver structured output.
+
+Every i18n task must produce these deliverables:
+
+| Deliverable | Content |
+|-------------|---------|
+| **Extraction count** | Strings extracted or modified (e.g., "42 strings extracted") |
+| **Namespace map** | Key structure and file organization |
+| **Translation file changes** | JSON diffs or new files created |
+| **Scope summary** | Component / feature / app-wide scope declaration |
+| **Problem patterns** | Concatenation, missing Intl usage, RTL issues found |
+| **Next steps** | Remaining work — new locales, RTL testing, translator handoff |
+
+---
+
+## Scope Management
+
+| Scope | String Count | Approach |
+|-------|-------------|----------|
+| **Component** | < 50 strings | Single PR, one namespace |
+| **Feature** | < 200 strings | Plan first, single PR, 2-3 namespaces |
+| **App-wide** | 200+ strings | Phased plan with progress tracking per namespace |
 
-| Project Type | i18n Needed? |
-|--------------|--------------|
-| Public web app | ✅ Yes |
-| SaaS product | ✅ Yes |
-| Internal tool | ⚠️ Maybe |
-| Single-region app | ⚠️ Consider future |
-| Personal project | ❌ Optional |
+For app-wide extraction, create a tracking document:
+
+```markdown
+## i18n Extraction Progress
+- [x] common (32/32 strings)
+- [x] auth (18/18 strings)
+- [/] dashboard (24/41 strings)
+- [ ] settings (0/36 strings)
+- [ ] billing (0/28 strings)
+```
 
 ---
 
-## 3. Implementation Patterns
+## Implementation Patterns
 
 ### React (react-i18next)
 
@@ -41,8 +150,14 @@ allowed-tools: Read, Glob, Grep
 import { useTranslation } from 'react-i18next';
 
 function Welcome() {
-  const { t } = useTranslation();
-  return <h1>{t('welcome.title')}</h1>;
+  const { t } = useTranslation('dashboard');
+  return (
+    <div>
+      <h1>{t('welcome.title')}</h1>
+      <p>{t('welcome.subtitle', { name: user.name })}</p>
+      <p>{t('stats.itemCount', { count: items.length })}</p>
+    </div>
+  );
 }
 ```
 
@@ -53,7 +168,12 @@ import { useTranslations } from 'next-intl';
 
 export default function Page() {
   const t = useTranslations('Home');
-  return <h1>{t('title')}</h1>;
+  return (
+    <div>
+      <h1>{t('title')}</h1>
+      <p>{t('description', { count: 5 })}</p>
+    </div>
+  );
 }
 ```
 
@@ -61,94 +181,152 @@ export default function Page() {
 
 ```python
 from gettext import gettext as _
+from gettext import ngettext
 
 print(_("Welcome to our app"))
+print(ngettext("%(count)d item", "%(count)d items", count) % {"count": count})
+```
+
+### Vue (vue-i18n)
+
+```vue
+<template>
+  <h1>{{ $t('dashboard.title') }}</h1>
+  <p>{{ $t('dashboard.greeting', { name: user.name }) }}</p>
+</template>
 ```
 
 ---
 
-## 4. File Structure
+## File Structure
 
 ```
 locales/
-├── en/
-│   ├── common.json
-│   ├── auth.json
-│   └── errors.json
-├── tr/
-│   ├── common.json
-│   ├── auth.json
-│   └── errors.json
-└── ar/          # RTL
+├── en/                    # Default / source locale
+│   ├── common.json        # Shared: buttons, labels, status
+│   ├── auth.json          # Auth feature strings
+│   ├── dashboard.json     # Dashboard feature strings
+│   ├── errors.json        # Error messages
+│   └── validation.json    # Form validation messages
+├── de/                    # German (30% longer text — test wrapping)
+│   └── ...
+├── ar/                    # Arabic (RTL)
+│   └── ...
+└── ja/                    # Japanese (CJK — test Segmenter)
     └── ...
 ```
 
+Namespace rules:
+- One JSON file per feature domain
+- `common.json` for cross-feature strings (buttons, labels, status words)
+- Never exceed 200 keys per file — split by sub-feature if needed
+
 ---
 
-## 5. Best Practices
+## Translator Context
 
-### DO ✅
+### When to Add Context Comments
 
-- Use translation keys, not raw text
-- Namespace translations by feature
-- Support pluralization
-- Handle date/number formats per locale
-- Plan for RTL from the start
-- Use ICU message format for complex strings
+Add context when a string is **ambiguous without seeing the UI**:
 
-### DON'T ❌
+| Situation | Example |
+|-----------|---------|
+| **Homonyms** | "Save" — button label? saving to disk? sports save? |
+| **Character limits** | Button has 15-char max width |
+| **Placeholder context** | What `{name}` refers to (user name? product name?) |
+| **Tone** | Formal vs casual for same meaning |
+| **UI position** | Same word used as heading vs inline text |
 
-- Hardcode strings in components
-- Concatenate translated strings
-- Assume text length (German is 30% longer)
-- Forget about RTL layout
-- Mix languages in same file
+### Context Format
 
----
+In JSON locale files, use a parallel `_context` key:
 
-## 6. Common Issues
+```json
+{
+  "common.save": "Save",
+  "common.save_context": "Button label for saving form data. Max 10 characters.",
 
-| Issue | Solution |
-|-------|----------|
-| Missing translation | Fallback to default language |
-| Hardcoded strings | Use linter/checker script |
-| Date format | Use Intl.DateTimeFormat |
-| Number format | Use Intl.NumberFormat |
-| Pluralization | Use ICU message format |
+  "billing.charge": "Charge",
+  "billing.charge_context": "Verb — action button to charge customer's payment method.",
 
----
+  "dashboard.lead": "Lead",
+  "dashboard.lead_context": "Noun — a sales lead / prospective customer, not the verb."
+}
+```
 
-## 7. RTL Support
+Or in ARB format (Flutter/Dart convention, also used by some JS tools):
 
-```css
-/* CSS Logical Properties */
-.container {
-  margin-inline-start: 1rem;  /* Not margin-left */
-  padding-inline-end: 1rem;   /* Not padding-right */
+```json
+{
+  "save": "Save",
+  "@save": {
+    "description": "Button label for saving form data",
+    "context": "Appears on all edit forms",
+    "maxLength": 10
+  }
 }
+```
 
-[dir="rtl"] .icon {
-  transform: scaleX(-1);
+### Glossary Management
+
+For domain-specific terminology, maintain a glossary file:
+
+```
+locales/glossary.json
+```
+
+```json
+{
+  "terms": {
+    "lead": "A prospective customer in the sales pipeline",
+    "sprint": "A 2-week development iteration",
+    "tenant": "An organization account in the multi-tenant system"
+  }
 }
 ```
 
+Share this glossary with translators to ensure consistent terminology across locales.
+
 ---
 
-## 8. Checklist
+## Reference Material
 
-Before shipping:
+Detailed reference docs are in the `references/` directory:
 
-- [ ] All user-facing strings use translation keys
+| Reference | Content |
+|-----------|---------|
+| [ICU MessageFormat](references/icu-message-format.md) | Plural, select, ordinal, nested patterns. Key naming conventions. Common mistakes. |
+| [Intl API Patterns](references/intl-api-patterns.md) | All 7 `Intl` formatters with usage examples: DateTimeFormat, NumberFormat, RelativeTimeFormat, ListFormat, PluralRules, DisplayNames, Segmenter. |
+| [RTL Support](references/rtl-support.md) | CSS logical properties table, component-level patterns, `dir` attribute usage, bidirectional text, testing checklist. |
+
+---
+
+## Pre-Ship Checklist
+
+- [ ] All user-facing strings use translation keys (`t()` / `$t()` / `_()`)
+- [ ] Zero string concatenation for translated content
 - [ ] Locale files exist for all supported languages
-- [ ] Date/number formatting uses Intl API
-- [ ] RTL layout tested (if applicable)
+- [ ] All keys in default locale exist in every target locale
+- [ ] ICU MessageFormat used for plurals, gender, select (no ternary hacks)
+- [ ] Dates use `Intl.DateTimeFormat` — not `.toLocaleDateString()` without options
+- [ ] Numbers/currency use `Intl.NumberFormat`
+- [ ] Relative times use `Intl.RelativeTimeFormat`
+- [ ] Lists use `Intl.ListFormat` — not `.join(', ')`
+- [ ] RTL tested (if RTL locales in scope) — run [RTL checklist](references/rtl-support.md)
+- [ ] Translator context provided for ambiguous strings
 - [ ] Fallback language configured
-- [ ] No hardcoded strings in components
+- [ ] Text doesn't overflow containers (test with German — 30% expansion)
 
 ---
 
-## Script
-
-| Script | Purpose | Command |
-|--------|---------|---------|
-| `scripts/i18n_checker.py` | Detect hardcoded strings & missing translations | `python scripts/i18n_checker.py <project_path>` |
+## Anti-Patterns
+
+| Pattern | Why It's Wrong | Fix |
+|---------|---------------|-----|
+| `"Hello, " + name` | Breaks translation word order | `t('greeting', { name })` |
+| `count === 1 ? 'item' : 'items'` | Fails for Polish, Arabic, etc. | ICU `{count, plural, ...}` |
+| `new Date().toLocaleDateString()` | Inconsistent without explicit options | `Intl.DateTimeFormat(locale, opts)` |
+| `list.join(', ')` | Wrong separator for Japanese, Arabic | `Intl.ListFormat(locale)` |
+| `margin-left: 1rem` in CSS | Breaks RTL layout | `margin-inline-start: 1rem` |
+| `t('btn1')`, `t('btn2')` | Non-semantic keys are unmaintainable | `t('common.buttons.save')` |
+| Splitting sentences across keys | Translators can't reorder words | One full sentence per key |