universal-dev-standards 5.14.0 → 5.16.0

package/bin/uds.js

@@ -175,6 +175,7 @@ program
   .option('--migrate', 'Migrate legacy manifest to hash-based tracking')
   .option('--offline', 'Skip npm registry check for CLI updates')
   .option('--force', 'Bypass UDS source-repo self-adoption guard (DEC-044 / XSPEC-071)')
+  .option('--i18n', 'Run i18n lint rules (XSPEC-239) across canonical + locale variants')
   .action(checkCommand);
 
 program
@@ -207,6 +208,7 @@ program
   .option('--plan', 'Show reconciliation plan without executing (like terraform plan)')
   .option('--force', 'Force update all files, ignoring hash comparison')
   .option('--rollback', 'Rollback to the most recent backup')
+  .option('--locale <locale>', 'Override locale for skills install (zh-tw, zh-cn, en); also reads .uds/install.yaml + UDS_LOCALE env')
   .action(updateCommand);
 
 program

package/bundled/ai/standards/acceptance-criteria-traceability.ai.yaml

@@ -108,6 +108,27 @@ standard:
         AC Coverage: <pct>% (<covered>/<implemented_total> implemented ACs)
         Status: BLOCKED by <not_impl_count> not_implemented AC(s)
 
+  user_doc_coverage:
+    description: "Second dimension: are user-facing AC also documented in the user guide? Extends the traceability spine past tests to the user guide (Forward Derivation Standards -> Terminal Projection: User Guide)"
+    user_facing_filter:
+      rule: "Apply only to user-facing AC — those an end user can directly observe or operate (UI flow, CLI command, user-facing API semantics)"
+      excluded: "Internal refactor/module contracts, performance thresholds, security/internal guardrails"
+      conservative_default: "When in doubt treat AC as user-facing; excluding requires explicit 'user_facing: false', never silent omission"
+    status:
+      - status: documented
+        symbol: "✅"
+        definition: "A user-guide step covers this AC, tagged with the AC's shared T-NNN"
+      - status: partial
+        symbol: "⚠️"
+        definition: "A user-guide step exists but is incomplete or ambiguously tagged"
+      - status: undocumented
+        symbol: "❌"
+        definition: "No user-guide step references this user-facing AC"
+    calculation: |
+      user_doc_coverage = (documented + partial × 0.5) / (user_facing_ac_count - not_implemented_count) × 100
+      non-user-facing AC counted in neither numerator nor denominator; partial = 0.5; not_implemented excluded from denominator
+    shared_ruler: "A user-guide step's T-NNN MUST equal a real journey/E2E test id (single spine: test + journey + user guide). A parallel id with no matching test is reported undocumented, never covered"
+
   quality_thresholds:
     defaults:
       - name: Minimum AC Coverage
@@ -222,6 +243,16 @@ standard:
       instruction: Validate generated AC against SMART criteria and testability
       priority: required
 
+    - id: user-doc-user-facing-only
+      trigger: computing the user-doc coverage dimension
+      instruction: "Apply user-doc coverage only to user-facing AC; when in doubt treat as user-facing, exclude only with an explicit 'user_facing: false' marking"
+      priority: recommended
+
+    - id: user-doc-shared-tnnn
+      trigger: linking a user-guide step to an AC
+      instruction: "A user-guide step's T-NNN must equal a real journey/E2E test id; a parallel id with no matching test is reported undocumented, never covered"
+      priority: required
+
 related_standards:
   - forward-derivation-standards.md
   - spec-driven-development.md

package/bundled/ai/standards/ai-instruction-standards.ai.yaml

@@ -3,10 +3,10 @@
 
 id: ai-instruction-standards
 meta:
-  version: "1.0.0"
-  updated: "2026-01-14"
+  version: "1.1.0"
+  updated: "2026-05-28"
   source: core/ai-instruction-standards.md
-  description: Best practices for creating AI instruction files with universal vs project-specific separation
+  description: Best practices for creating AI instruction files (root and skill level) with universal/project-specific separation and i18n strategy
 
 supported_tools:
   - tool: Claude Code
@@ -117,6 +117,26 @@ rules:
       grep -n "npm\|yarn\|pip\|cargo" CLAUDE.md | head -20
     priority: required
 
+  - id: i18n-canonical-english-only
+    trigger: editing canonical AI instruction file
+    instruction: Keep description and metadata in English; localize via locales/{lang}/ variants
+    priority: required
+
+  - id: i18n-locale-must-match-language
+    trigger: creating or editing locale variant
+    instruction: Description must be in the locale's language; include source/source_version/translation_version frontmatter
+    priority: required
+
+  - id: i18n-l3-template-language-controls-output
+    trigger: writing output templates / examples
+    instruction: L3 templates determine AI output language; localize L3 in locale variants, never in canonical
+    priority: required
+
+  - id: i18n-no-manual-canonical-edits-by-adopters
+    trigger: adopter wants to customize an installed instruction file
+    instruction: Use uds install --locale or overlays; do not modify canonical files in-place
+    priority: required
+
 maintenance_checklist:
   - item: Universal sections contain no project-specific paths, commands, or versions
     required: true
@@ -127,6 +147,173 @@ maintenance_checklist:
   - item: Format matches existing sections
     required: true
 
+i18n:
+  scope:
+    description: |
+      Defines language-handling policy for AI instruction files at two levels:
+      root-level (CLAUDE.md, .cursorrules, etc.) and skill-level
+      (Claude Code SKILL.md, OpenCode plugin instructions, etc.)
+    levels:
+      - level: root
+        files:
+          - CLAUDE.md
+          - .cursorrules
+          - .windsurfrules
+          - .clinerules
+          - .github/copilot-instructions.md
+          - .opencode/instructions.md
+        i18n_pattern: single_file_with_inline_language_sections
+      - level: skill
+        files:
+          - .claude/skills/{name}/SKILL.md
+          - .opencode/plugins/{name}/instructions.md
+        i18n_pattern: canonical_plus_locale_variants
+
+  layered_strategy:
+    description: |
+      Every AI instruction file has 4 layers. L3 (output templates) is the only
+      layer that directly affects AI output language; L1/L2 are processing
+      instructions for the AI. Enforce L3 strictly, L1 as a clear convention.
+    layers:
+      - id: L1
+        name: metadata
+        content:
+          - YAML frontmatter description
+          - argument-hint
+          - allowed-tools
+        canonical_language: english
+        locale_language: must_match_locale
+        rationale: AI-trigger signal; English has highest training-data density and token efficiency
+        impact_on_ai_output: none
+      - id: L2
+        name: instructions
+        content:
+          - imperative rules for AI
+          - steps
+          - behavior rules
+        canonical_language: english
+        locale_language: locale_optional
+        rationale: AI reads English instructions most precisely
+        impact_on_ai_output: none
+      - id: L3
+        name: output_templates
+        content:
+          - example outputs
+          - response format templates
+          - scenario examples
+        canonical_language: english
+        locale_language: must_match_locale_mandatory
+        rationale: AI mirrors the language of templates it sees — this is the only layer that controls output language
+        impact_on_ai_output: direct
+      - id: L4
+        name: human_docs
+        content:
+          - maintainer comments
+          - contributor walkthroughs
+        canonical_language: english
+        locale_language: locale_recommended
+        rationale: Read by human maintainers, not by AI
+        impact_on_ai_output: none
+
+  file_structure:
+    canonical:
+      - core/{name}.md
+      - core/{name}.ai.yaml
+      - skills/{name}/SKILL.md
+    locale:
+      - locales/{lang}/core/{name}.md
+      - locales/{lang}/ai/standards/{name}.ai.yaml
+      - locales/{lang}/skills/{name}/SKILL.md
+    locale_naming: BCP_47   # zh-TW, zh-CN, ja, ko, en-US, etc.
+
+  locale_variant_frontmatter:
+    required_fields:
+      - field: name
+        value: same as canonical
+      - field: source
+        value: relative path to canonical file
+      - field: source_version
+        value: version of canonical at time of translation
+      - field: translation_version
+        value: version of this translation
+    drift_alert:
+      condition: source_version gap > 2 minor versions behind canonical
+      severity: warn
+
+  responsibility_boundaries:
+    - role: canonical_owner
+      owns:
+        - core/{name}.md
+        - core/{name}.ai.yaml
+        - skills/{name}/SKILL.md
+      duties:
+        - Keep L1/L2/L3/L4 in English
+        - Bump source_version on every breaking change
+    - role: locale_maintainer
+      owns:
+        - locales/{lang}/...
+      duties:
+        - Keep translation_version aligned with source_version
+        - Translate L1 (required), L2 (optional), L3 (required), L4 (recommended)
+    - role: adopter
+      owns:
+        - their own .claude/skills/, CLAUDE.md
+      duties:
+        - Install via uds install --locale {lang}
+        - Never manually modify canonical files
+        - Use overlays or locale variants for customization
+
+  chimera_prevention:
+    rules:
+      - id: canonical-description-must-be-ascii
+        trigger: canonical file with CJK in description field
+        severity: error
+        instruction: Canonical files must keep description in English; move localized description to locale variant
+      - id: locale-description-must-match-language
+        trigger: locale variant with ASCII-only description
+        severity: error
+        instruction: Locale variant description must use the locale's language
+      - id: locale-must-have-source-frontmatter
+        trigger: locale variant missing source/source_version/translation_version
+        severity: error
+        instruction: Add traceability frontmatter pointing to canonical
+      - id: canonical-l3-language-consistency
+        trigger: canonical L3 output template contains non-English example
+        severity: warn
+        instruction: Localize L3 templates in locale variants, not canonical
+      - id: adopter-must-match-installed-locale
+        trigger: adopter file in .claude/skills/ differs from both canonical and any locale variant
+        severity: warn
+        instruction: Use uds install --locale or overlays instead of manual canonical edits
+      - id: translation-drift-warn
+        trigger: translation_version lag > 2 minor versions behind source_version
+        severity: warn
+        instruction: Re-sync translation from current canonical version
+
+  installation_model:
+    cli: uds install --locale {lang}
+    locale_resolution_priority:
+      - --locale CLI flag
+      - .uds/install.yaml locale field
+      - environment variable UDS_LOCALE
+      - fallback to en
+    missing_locale_behavior:
+      action: fallback_to_canonical_with_warn
+      block_install: false
+      coverage_visibility: locales/COVERAGE.md
+
+  migration:
+    name: adopter_chimera_cleanup
+    steps:
+      - id: identify
+        description: Compare adopter files against UDS canonical and locale variants
+      - id: install_proper_variants
+        description: Run uds install --locale {lang} to replace chimera
+      - id: preserve_legitimate_customization
+        description: Extract project-specific (non-translation) customization into overlay or UDS-CUSTOMIZATION.md
+      - id: discard_pure_translations
+        description: Chimera changes that were only translations are superseded by locale variants
+
 quick_reference:
   content_types:
     columns: [Type, Contains, Example]

package/bundled/ai/standards/forward-derivation-standards.ai.yaml

@@ -99,6 +99,20 @@ ac_level_summary:
   description: "Output AC Level Summary at end of /derive all"
   format: "| AC | Suggested Level | Rationale |"
 
+# Terminal Projection: User Guide (extends the chain past tests)
+terminal_projection:
+  description: "The user guide is the terminal projection of the derivation chain — the human-readable view of the same workflow E2E/journey tests verify by machine"
+  single_source_of_truth: "AC spine — BDD, TDD/IT/E2E, ATDD, contracts, and the user guide are all projections of the same AC"
+  user_facing_filter:
+    rule: "A user-guide step is required only for an AC an end user can directly observe or operate (UI flow, CLI command, user-facing API semantics)"
+    excluded: "Purely internal AC (refactor, internal module contracts, performance thresholds, security controls) carry no user-guide obligation"
+    default: "When in doubt, treat the AC as user-facing; explicit marking is required to exclude"
+  shared_numbering:
+    rule: "Each user-guide step is tagged T-NNN, and that T-NNN MUST be the id of a real journey/E2E test"
+    ambiguous: "Ambiguous or missing tags are reported as uncovered (prefer redundancy over omission)"
+    violation: "Minting a parallel T-NNN-style series detached from the AC spine"
+  single_spine_principle: "Test and documentation sources are layered projections of one AC spine (N×1), not independent sources cross-checking one another pairwise (N×N); TDD/IT/E2E are pyramid layers of the same spine, not rival sources"
+
 # Certainty Framework
 certainty_framework:
   tags:
@@ -171,6 +185,15 @@ rules:
   - id: ac-level-summary
     instruction: Output AC Level Summary table at end of /derive all
     priority: recommended
+  - id: single-spine-no-parallel-numbering
+    instruction: Every test/doc artifact must trace back to the AC spine; never mint a parallel T-NNN-style series detached from it
+    priority: required
+  - id: user-guide-shared-tnnn
+    instruction: A user-guide step's T-NNN must equal a real journey/E2E test id; ambiguous or missing tags are reported as uncovered
+    priority: required
+  - id: user-facing-ac-conservative-default
+    instruction: User-guide obligation applies to user-facing AC only; when in doubt treat as user-facing, explicit marking to exclude
+    priority: recommended
 
 related_standards:
   - reverse-engineering-standards.md

package/bundled/ai/standards/knowledge-graph-memory.ai.yaml

@@ -0,0 +1,83 @@
+# Knowledge Graph Memory Standards - AI Optimized
+# Source: core/knowledge-graph-memory.md
+
+standard:
+  id: knowledge-graph-memory
+  name: Knowledge Graph Memory Standards
+  description: Relationship schema for traversing specs, decisions, and code as a graph; complements vector memory with structural multi-hop queries, engine-optional with Markdown degradation
+  guidelines:
+    - "Express relationships as optional, additive YAML front-matter (related/impacts/impacted_by/supersedes/implements)"
+    - "Derive IMPACTS (Decision->Spec) and SUPERSEDES (Decision->Decision) edges from front-matter or [[ref]] links"
+    - "Support two modes: degraded (AI reads linked Markdown) and service (graph engine multi-hop query) with the same answer shape"
+    - "Keep the graph engine opt-in; always degrade gracefully to Markdown reading"
+    - "Treat vector/semantic memory as complementary (similarity) to graph traversal (structure), not replaced"
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-05-30"
+    source: core/knowledge-graph-memory.md
+    description: Relationship schema for traversing specs, decisions, and code as a graph; complements vector memory with structural multi-hop queries, engine-optional with Markdown degradation
+
+  schema:
+    format: "YAML front-matter on spec/decision Markdown documents"
+    optional_fields:
+      - field: related
+        type: list
+        direction: undirected
+        description: "Loosely associated artifact ids"
+      - field: impacts
+        type: list
+        direction: "this(Decision) -> Spec"
+        description: "Specs this decision changes"
+      - field: impacted_by
+        type: list
+        direction: "Decision -> this(Spec)"
+        description: "Decisions that change this spec"
+      - field: supersedes
+        type: list
+        direction: "this(Decision) -> Decision"
+        description: "Decisions this one replaces"
+      - field: implements
+        type: list
+        direction: "code/spec -> Spec"
+        description: "Specs this artifact realises"
+    node_kinds:
+      - prefix: "XSPEC-* / SPEC-*"
+        kind: Spec
+      - prefix: "DEC-* / ADR-*"
+        kind: Decision
+      - prefix: "function / class / module"
+        kind: Code
+
+  edges:
+    - rule: "Decision impacts:[SPEC]  => IMPACTS (Decision -> Spec)"
+    - rule: "Spec impacted_by:[DEC]   => IMPACTS (Decision -> Spec)"
+    - rule: "Decision supersedes:[DEC] => SUPERSEDES (Decision -> Decision)"
+    - rule: "[[XSPEC-NNN]] link in a Decision body => IMPACTS (Decision -> Spec)"
+    idempotent: "Declaring a relationship from both ends yields one edge, not two"
+
+  modes:
+    degraded:
+      description: "No engine: AI reads the target doc, follows front-matter/[[ref]] links by reading files, assembles the chain manually"
+      always_available: true
+    service:
+      description: "Graph engine indexed: a single multi-hop query (impact-analysis {nodeId, maxHops}) returns the full cross-domain chain"
+      example_engine: "EngramGraph (engramgraph)"
+
+  confidence:
+    optional: true
+    range: "0.1 - 1.0"
+    floor: 0.1
+    note: "Feedback signals (test pass/fail, human correction, status change) evolve confidence; floor prevents erasing important nodes (SAGE)"
+
+  rules:
+    - "Relationship fields are optional and additive; absence never breaks tooling"
+    - "Reference ids that do not exist yet become stub nodes, resolved when the target appears"
+    - "Declare each relationship from the owning side, but accept either"
+    - "Graph engine is opt-in; degrade gracefully to Markdown reading"
+    - "Vector/semantic memory is complementary, not replaced"
+
+  related_standards:
+    - project-context-memory
+    - developer-memory
+    - adr-standards

package/bundled/core/acceptance-criteria-traceability.md

@@ -140,6 +140,52 @@ The gate clears only when all `not_implemented` ACs are updated to `uncovered`,
 
 ---
 
+## User-Documentation Coverage | 使用者文件覆蓋
+
+The AC↔test matrix above verifies that AC are *tested*. A second dimension verifies that **user-facing AC are also documented** for the end user. This extends the traceability spine past tests to the user guide — see Forward Derivation Standards → *Terminal Projection: User Guide*. The user guide and the journey/E2E suite are two projections of one workflow, so they share one ruler: `T-NNN`.
+
+### User-Facing AC Filter
+
+Apply the user-doc dimension **only to user-facing AC** — those an end user can directly observe or operate. This prevents the dimension from degrading into a blanket documentation obligation on every internal AC.
+
+| AC kind | User-facing? |
+|---------|--------------|
+| UI flow, screen, navigation | Yes |
+| CLI command / flag a user runs | Yes |
+| User-facing API semantics (public contract a user calls) | Yes |
+| Internal refactor / module contract | No |
+| Performance threshold, capacity | No |
+| Security control, internal guardrail | No |
+
+**Conservative default**: when in doubt, treat the AC as user-facing. Excluding an AC requires **explicit marking** (e.g. `user_facing: false`), never silent omission.
+
+### User-Doc Status
+
+Reuse the same symbols, now answering "is this user-facing AC covered by a user-guide step?":
+
+| Status | Symbol | Definition |
+|--------|--------|------------|
+| **Documented** | ✅ | A user-guide step covers this AC, tagged with the AC's shared `T-NNN` |
+| **Partial** | ⚠️ | A user-guide step exists but is incomplete or ambiguously tagged |
+| **Undocumented** | ❌ | No user-guide step references this user-facing AC |
+
+`not_implemented` (🚫) AC are excluded from the user-doc denominator, exactly as in the test-coverage calculation.
+
+### User-Doc Coverage Calculation
+
+```
+User-Doc Coverage % = (documented + partial × 0.5) / (user_facing_ac_count - not_implemented_count) × 100
+
+Where:
+  user_facing_ac_count = count of AC classified user-facing (conservative default applies)
+  non-user-facing AC are counted in neither numerator nor denominator
+  partial counts as 0.5
+```
+
+> **Single ruler**: a user-guide step's `T-NNN` MUST equal a real journey/E2E test id (Forward Derivation Standards). This binds three projections of one AC — test, journey, and user guide — to a single spine. A user-guide step that mints a parallel id with no matching test is reported as **undocumented**, never as covered.
+
+---
+
 ## Quality Thresholds
 
 ### Default Thresholds

package/bundled/core/ai-instruction-standards.md

@@ -2,8 +2,8 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/ai-instruction-standards.md) | [简体中文](../locales/zh-CN/core/ai-instruction-standards.md)
 
-**Version**: 1.0.0
-**Last Updated**: 2026-01-14
+**Version**: 1.1.0
+**Last Updated**: 2026-05-28
 **Applicability**: All projects using AI coding assistants
 **Scope**: partial
 **Industry Standards**: None (Emerging AI tool practice)
@@ -12,20 +12,20 @@
 
 ## Purpose
 
-This standard defines best practices for creating and maintaining AI instruction files (also known as "system prompt files"). These files guide AI assistants in understanding project-specific conventions, standards, and workflows.
+This standard defines best practices for creating and maintaining AI instruction files (also known as "system prompt files"). These files guide AI assistants in understanding project-specific conventions, standards, and workflows. This v1.1.0 extends scope to skill-level instruction files (SKILL.md) and adds i18n strategy.
 
 ---
 
 ## Supported AI Tools
 
-| AI Tool | Instruction File | Format |
-|---------|-----------------|--------|
-| Claude Code | `CLAUDE.md` | Markdown |
-| Cursor | `.cursorrules` | Markdown |
-| Windsurf | `.windsurfrules` | Markdown |
-| Cline | `.clinerules` | Markdown |
-| GitHub Copilot | `.github/copilot-instructions.md` | Markdown |
-| OpenCode | `.opencode/instructions.md` | Markdown |
+| AI Tool | Instruction File | Format | Skill-Level Instruction |
+|---------|-----------------|--------|------------------------|
+| Claude Code | `CLAUDE.md` | Markdown | `.claude/skills/{name}/SKILL.md` |
+| Cursor | `.cursorrules` | Markdown | n/a |
+| Windsurf | `.windsurfrules` | Markdown | n/a |
+| Cline | `.clinerules` | Markdown | n/a |
+| GitHub Copilot | `.github/copilot-instructions.md` | Markdown | n/a |
+| OpenCode | `.opencode/instructions.md` | Markdown | n/a |
 
 ---
 
@@ -145,6 +145,130 @@ Use clear markers to distinguish content types:
 
 ---
 
+## Internationalization (i18n)
+
+AI instruction files often need to be available in multiple languages — both for international adopters and for projects with non-English-speaking maintainers. This section defines how to organize, validate, and install multi-language instruction files.
+
+### Scope of AI Instruction Files
+
+This standard covers instruction files at two levels:
+
+| Level | Examples | i18n Pattern |
+|-------|----------|--------------|
+| **Root-level** | `CLAUDE.md`, `.cursorrules`, `.windsurfrules`, `.opencode/instructions.md` | Single file with inline language sections (e.g., `## 中文` / `## English`) |
+| **Skill-level** | Claude Code `.claude/skills/{name}/SKILL.md`, OpenCode plugin instructions | Canonical (English) + `locales/{lang}/` variants |
+
+> Note: skill-level multi-file structure is most relevant to Claude Code. Other tools use single root files; for them, only the layered language strategy (below) and the chimera-prevention rules apply.
+
+### Layered Language Strategy
+
+Every AI instruction file conceptually has **four layers**, each with different language responsibilities:
+
+| Layer | Content | Canonical (en) | Locale ({lang}) | Why |
+|-------|---------|---------------|----------------|-----|
+| **L1 — Metadata** | YAML frontmatter `description`, `argument-hint`, `allowed-tools` | **Must be English** | **Must match locale** | AI-trigger signal; English has highest training-data density and token efficiency |
+| **L2 — Instructions** | Imperative rules for the AI (steps, behavior, allowed-tools rationale) | **Must be English** | Locale language (optional; may stay English) | AI reads English instructions most precisely; locale only useful if maintainers need to read instructions in their language |
+| **L3 — Output Templates** | Example outputs, response formats, scenario templates | English (locale-pinned to English in canonical) | **Mandatory locale match** | **Only layer that directly controls AI output language** — AI inherits the language of templates it sees |
+| **L4 — Human Docs** | Comments for maintainers, walkthroughs, contributor notes | English | Locale language (strongly recommended) | Read by human maintainers, not by AI |
+
+**Critical insight**: L1 (description) is the trigger signal AI uses to decide *whether to invoke* a skill — it does **not** affect what the AI says afterwards. L3 (output templates) is the only layer that controls AI output language, because AI mirrors the language of templates it sees. **i18n enforcement should focus on L3 — strengthening L1 enforcement is a common mistake that solves the wrong problem.**
+
+### Canonical / Locale File Structure
+
+For UDS standards and skills with locale variants:
+
+```text
+core/{name}.md                              ← canonical (English) — single source of truth
+core/{name}.ai.yaml                         ← canonical structured (English)
+locales/{lang}/core/{name}.md               ← locale variant (matches lang)
+locales/{lang}/ai/standards/{name}.ai.yaml  ← locale .ai.yaml (matches lang)
+skills/{name}/SKILL.md                      ← canonical skill (English)
+locales/{lang}/skills/{name}/SKILL.md       ← locale skill variant
+```
+
+**Naming convention**: use BCP 47 language tags — `zh-TW`, `zh-CN`, `ja`, `ko`, `en-US`, etc.
+
+### Locale Variant Frontmatter Requirements
+
+Every locale variant must include traceability frontmatter so drift can be detected:
+
+```yaml
+---
+name: {same name as canonical}
+source: {relative path back to canonical}
+source_version: {version of canonical at time of translation}
+translation_version: {version of this translation}
+---
+```
+
+When canonical is updated (bumping `source_version`), locale maintainers should re-sync and bump `translation_version`. A `source_version` gap of more than 2 minor versions triggers a drift warning (see Chimera Prevention).
+
+### Responsibility Boundaries
+
+| Role | Owns | Must do |
+|------|------|---------|
+| **Canonical owner** | `core/{name}.md`, `core/{name}.ai.yaml`, `skills/{name}/SKILL.md` | Keep L1/L2/L3/L4 in English; bump `source_version` on every breaking change |
+| **Locale maintainer** | `locales/{lang}/...` files | Keep `translation_version` aligned with `source_version`; translate L1 (required) / L2 (optional) / L3 (required) / L4 (recommended) |
+| **Adopter (downstream project)** | Their own `.claude/skills/`, `CLAUDE.md`, etc. | Install via `uds install --locale {lang}`; **never** manually modify canonical files (always edit locale variants or use overlays) |
+
+### Chimera Prevention
+
+A **chimera** is a file that mixes languages in violation of layer rules. Common chimera patterns:
+
+| Pattern | Severity | Detection |
+|---------|----------|-----------|
+| Canonical file with CJK in `description` field | ❌ Error | Lint: `canonical:description-must-be-ascii` |
+| Locale variant with ASCII-only `description` field | ❌ Error | Lint: `locale:description-must-match-language` |
+| Locale variant missing `source:` frontmatter | ❌ Error | Lint: `locale:must-have-source-frontmatter` |
+| Canonical L3 output template containing non-English example response | ⚠️ Warn | Lint: `canonical:l3-language-consistency` |
+| Adopter file in `.claude/skills/` differs from both canonical and any locale variant | ⚠️ Warn | Sync check: `adopter:must-match-installed-locale` |
+| `translation_version` lag > 2 minor versions behind `source_version` | ⚠️ Warn | Drift check |
+
+Pre-commit / CI lint should enforce error-level rules; warn-level rules surface in dashboards but don't block.
+
+### Adopter Installation Model
+
+Adopters install instruction files via the UDS CLI:
+
+```bash
+uds install --locale zh-TW   # install skills + standards in Traditional Chinese
+```
+
+**Locale resolution order**:
+1. `--locale` CLI flag (highest priority)
+2. `.uds/install.yaml` field `locale:`
+3. Environment variable `UDS_LOCALE`
+4. Fallback: `en`
+
+**Missing locale fallback**: when a requested locale variant doesn't exist for a specific skill, the CLI:
+- Installs the canonical (English) file
+- Emits a WARN listing skills that fell back
+- Does **not** block installation
+
+This keeps installation usable for adopters even when locale coverage is incomplete. Adopters can consult `locales/COVERAGE.md` for the canonical list of what is and isn't translated.
+
+### Migration: Adopters With Existing Chimera
+
+If an adopter has already manually modified canonical files in their project (e.g. translated descriptions in `.claude/skills/`):
+
+1. **Identify the chimera**: compare adopter files against UDS canonical and canonical's locale variants.
+2. **Install proper variants**: run `uds install --locale {lang}` to replace chimera files with locale variants.
+3. **Preserve project-specific customization**: if the chimera contained legitimate project-specific customization (not just translation), extract it into an overlay or document it in the adopter's customization log (e.g. `UDS-CUSTOMIZATION.md`).
+4. **Discard pure translations**: chimera changes that were only translations should be discarded — the proper locale variant supersedes them.
+
+### Quick Reference
+
+| Action | When | Tool / File |
+|--------|------|-------------|
+| Add new language | Want to support a new locale | Create `locales/{lang}/...` mirroring canonical structure |
+| Update canonical | Improving English source | Bump `source_version`; notify locale maintainers |
+| Translate / sync locale | Adding or updating locale content | Bump `translation_version`; reference current `source_version` |
+| Check coverage | Periodic review | View auto-generated `locales/COVERAGE.md` |
+| Install with locale | Adopter setup or re-sync | `uds install --locale {lang}` |
+| Lint i18n rules | Before commit / in CI | `uds lint --i18n` |
+
+---
+
 ## Maintenance Checklist
 
 Before committing changes to AI instruction files:
@@ -199,6 +323,7 @@ Review each match to ensure it's in a project-specific section.
 | Version | Date | Changes |
 |---------|------|---------|
 | 1.0.0 | 2026-01-14 | Initial release |
+| 1.1.0 | 2026-05-28 | Add i18n section; extend scope to skill-level files |
 
 ---
 

package/bundled/core/forward-derivation-standards.md

@@ -515,6 +515,25 @@ spec-review → forward-derivation → discovery
 
 ---
 
+## Terminal Projection: User Guide | 終端投影：使用者指南
+
+The derivation chain does not stop at tests. The **user guide is the terminal projection** of the same chain — the human-readable view of the very workflow that E2E/journey tests verify by machine. "What the user reads as steps" and "what E2E actually verifies as behavior" become one maintained invariant.
+
+- **Single source of truth**: the SPEC's acceptance criteria (AC). Every downstream artifact — BDD scenarios, TDD/IT/E2E skeletons, ATDD tables, contracts, **and the user guide** — is a projection of the same AC spine. The user guide is not a separate source to be cross-checked; it is one more projection.
+- **User-facing AC only**: a user-guide step is required only for an AC that an **end user can directly observe or operate** (UI flow, CLI command, user-facing API semantics). Purely internal AC (refactor, internal module contracts, performance thresholds, security controls) carry no user-guide obligation. **When in doubt, treat the AC as user-facing** — conservative default; explicit marking is required to exclude.
+- **Shared numbering (`T-NNN`)**: each user-guide step is tagged `T-NNN`, and that `T-NNN` MUST be the id of a real journey/E2E test. The user guide and the E2E suite are two projections of one workflow sharing one ruler. Ambiguous or missing tags are reported as **uncovered** (prefer redundancy over omission).
+  - ✅ user-guide step `T-012 "Create a project"` ↔ E2E test `T-012` in the journey spec.
+  - ❌ user guide invents `UG-3` with no corresponding test → drift, reported as uncovered.
+- **Drift example**: user guide says "2-click checkout" while E2E still verifies "3-step payment" — without shared numbering, no one notices. Shared `T-NNN` turns this drift into a reported coverage gap.
+
+### Single-Spine Principle (not parallel cross-check)
+
+Test and documentation sources are **multiple layered projections of one AC spine**, not independent sources of truth that cross-check one another. TDD/IT/E2E are pyramid *layers* of the same spine (see Test Level Decision Tree), not rival sources. Cross-checking N sources pairwise (N×N) breeds drift; projecting each artifact back to the single AC spine (N×1) eliminates it.
+
+> **Rule**: every test or documentation artifact MUST trace back to an AC. Minting a **parallel numbering scheme** — a second `T-NNN`-style series detached from the AC spine — is a VIOLATION. There is one ruler: the AC spine, with `T-NNN` shared between journey/E2E tests and the user guide.
+
+---
+
 ## Test Level Decision Tree
 
 根據 AC 的性質決定應生成哪種測試層級：