universal-dev-standards 5.14.0 → 5.15.1

package/bundled/skills/knowledge-graph/guide.md

@@ -0,0 +1,69 @@
+# Knowledge Graph — Detailed Guide | 詳細指南
+
+Companion to [SKILL.md](SKILL.md). Worked examples of both operating modes and the engine API.
+
+[SKILL.md](SKILL.md) 的配套說明。兩種運作模式的範例與引擎 API。
+
+---
+
+## 1. Service Mode (graph engine) | 服務模式
+
+When a CodeSage-compatible engine is reachable, a single query returns the full chain.
+
+### Impact analysis | 影響分析
+
+```bash
+curl -s -X POST "$CODESAGE_URL/graph/impact-analysis" \
+  -H 'content-type: application/json' \
+  -d '{"nodeId":"XSPEC-205","maxHops":3}'
+# => { "nodeId": "XSPEC-205",
+#      "decisions": [ {"id":"DEC-062","title":"...","via":"direct"},
+#                     {"id":"DEC-069","title":"...","via":"supersedes"} ] }
+```
+
+`via: "direct"` means the decision IMPACTS the spec directly; `via: "supersedes"` means it reaches the spec through a SUPERSEDES chain (≤ `maxHops`).
+
+### Confidence feedback (SAGE) | 信心回饋
+
+```bash
+curl -s -X POST "$CODESAGE_URL/graph/ingest" \
+  -H 'content-type: application/json' \
+  -d '{"type":"test_fail","functionId":"src/a.ts#execute"}'
+```
+
+Lowers the node's confidence; reads then surface higher-confidence nodes first.
+
+---
+
+## 2. Degraded Mode (Markdown only) | 降級模式
+
+No engine required. Reconstruct the chain by reading files:
+
+1. Read the target document (e.g. `XSPEC-205`).
+2. Collect ids from its front-matter (`impacts`, `impacted_by`, `supersedes`, `related`) and inline `[[ref]]` links.
+3. For each id, read that document and repeat up to the desired hop depth.
+4. Classify each id by prefix (`XSPEC-*`/`SPEC-*` → Spec; `DEC-*`/`ADR-*` → Decision) and report the edges.
+
+```bash
+# find the documents
+grep -rl "id: XSPEC-205" --include='*.md' .
+# discover outbound references
+grep -nE "(impacts|impacted_by|supersedes|related):|\[\[(XSPEC|DEC|ADR)-" path/to/XSPEC-205.md
+```
+
+Degraded mode is always correct but bounded by how many files you read; cross-domain code links (function → spec) are usually only available in service mode.
+
+---
+
+## 3. Equivalence | 等價性
+
+Both modes produce the **same answer shape** (a list of connected Specs/Decisions with edge types). Service mode is faster and more complete (it can include code→spec→decision hops); degraded mode is the universal fallback. Always tell the user which mode produced the answer.
+
+兩種模式產生**相同形狀的答案**。服務模式更快更完整；降級模式為通用後備。務必告知使用者答案來自哪種模式。
+
+---
+
+## Reference | 參考
+
+- [core/knowledge-graph-memory.md](../../core/knowledge-graph-memory.md)
+- [CodeSage](https://github.com/AsiaOstrich/CodeSage)

package/bundled/skills/logging-guide/SKILL.md

@@ -4,7 +4,7 @@ scope: universal
 description: |
   Implement structured logging with proper log levels and sensitive data handling.
   Use when: adding logging, debugging, setting up observability.
-  Keywords: logging, log level, structured logging, observability, 日誌, 記錄, 結構化日誌.
+  Keywords: logging, log level, structured logging, observability.
 ---
 
 # Logging Guide

package/bundled/skills/observability-assistant/SKILL.md

@@ -4,7 +4,7 @@ scope: universal
 description: |
   Guide observability setup, metrics design, and alerting configuration.
   Use when: new service instrumentation, SLO definition, alert design, maturity assessment.
-  Keywords: observability, metrics, traces, golden signals, alerting, SLO, 可觀測性, 告警.
+  Keywords: observability, metrics, traces, golden signals, alerting, SLO.
 allowed-tools: Read, Write, Grep, Glob
 argument-hint: "[service name or observability topic | 服務名稱或可觀測性主題]"
 ---

package/bundled/skills/orchestrate/SKILL.md

@@ -5,7 +5,7 @@ scope: universal
 description: |
   Orchestrate multi-task execution plans using Claude's native Agent tool (DAG-based, no external engine).
   Use when: executing a plan.json file with parallel/sequential task dependencies.
-  Keywords: orchestrate, plan, execute, DAG, task plan, 編排, 執行計畫, 並行.
+  Keywords: orchestrate, plan, execute, DAG, task plan.
 argument-hint: "<plan.json> [--dry-run]"
 ---
 

package/bundled/skills/plan/SKILL.md

@@ -5,7 +5,7 @@ scope: universal
 description: |
   Generate plan.json from Spec documents, OpenSpec changes, or free-text requirements.
   Use when: converting specifications into executable task plans for /orchestrate.
-  Keywords: plan, spec, task plan, 計畫, 規格, 任務, plan.json, DAG.
+  Keywords: plan, spec, task plan, plan.json, DAG.
 argument-hint: "[spec-file.md | openspec-dir/ | \"requirement text\" | (interactive)]"
 ---
 

package/bundled/skills/pr-automation-assistant/SKILL.md

@@ -4,7 +4,7 @@ scope: universal
 description: |
   Guide pull request creation, review automation, and merge strategies.
   Use when: creating PRs, automating reviews, configuring merge policies.
-  Keywords: pull request, PR, merge, review, GitHub, GitLab, 合併請求, 審查.
+  Keywords: pull request, PR, merge, review, GitHub, GitLab.
 allowed-tools: Read, Grep, Glob, Bash(git:*, gh:*)
 argument-hint: "[branch name or PR number | 分支名稱或 PR 編號]"
 ---

package/bundled/skills/project-structure-guide/SKILL.md

@@ -4,7 +4,7 @@ scope: universal
 description: |
   Guide for organizing project directories following language-specific best practices.
   Use when: creating projects, reorganizing structure, adding modules, setting up builds, deciding file placement.
-  Keywords: project, structure, directory, layout, gitignore, scaffold, 專案結構, 目錄, file placement, utils, helpers, shared, where to put, 檔案歸檔.
+  Keywords: project, structure, directory, layout, gitignore, scaffold, file placement, utils, helpers, shared, where to put.
 ---
 
 # Project Structure Guide

package/bundled/skills/push/SKILL.md

@@ -4,7 +4,7 @@ scope: universal
 description: |
   AI-assisted safety layer for git push operations with quality gates and collaboration guardrails.
   Use when: pushing commits, force pushing, pushing to protected branches, pushing feature branches.
-  Keywords: git push, force push, protected branch, quality gate, push receipt, PR automation, 推送, 保護分支, 品質閘門.
+  Keywords: git push, force push, protected branch, quality gate, push receipt, PR automation.
 allowed-tools: Read, Bash(git:*), Bash(npm:*), Bash(pnpm:*), Bash(yarn:*), Bash(bun:*)
 argument-hint: "[--force] [--target <branch>] [--skip-gates] [--no-pr]"
 ---

package/bundled/skills/retrospective-assistant/SKILL.md

@@ -4,7 +4,7 @@ scope: universal
 description: |
   [UDS] Guide structured team retrospectives for Sprint and Release cycles.
   Use when: sprint end, release post-mortem, iteration review, process improvement.
-  Keywords: retrospective, retro, sprint review, lessons learned, action items, 回顧, 檢討, 持續改善.
+  Keywords: retrospective, retro, sprint review, lessons learned, action items.
 allowed-tools: Read, Write, Glob, Grep
 argument-hint: "[sprint | release | actions | --technique starfish]"
 ---

package/bundled/skills/reverse-engineer/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: reverse
 scope: partial
-description: "[UDS] System archeology — reverse engineer code across Logic, Data, and Runtime dimensions"
+description: "[UDS] System archeology - reverse engineer code across Logic, Data, and Runtime dimensions"
 allowed-tools: Read, Grep, Glob, Bash(pg_dump:*), Bash(mysql:*), Bash(sqlite3:*), Bash(npm run:*), Bash(cat:*), Bash(docker:*)
 argument-hint: "[spec|data|runtime|bdd|tdd] <input>"
 disable-model-invocation: true

package/bundled/skills/runbook-assistant/SKILL.md

@@ -4,7 +4,7 @@ scope: universal
 description: |
   Guide runbook creation, maintenance, and drill exercises.
   Use when: writing runbooks, planning drills, auditing runbook coverage, post-incident runbook updates.
-  Keywords: runbook, operations, drill, on-call, procedure, 操作手冊, 演練.
+  Keywords: runbook, operations, drill, on-call, procedure.
 allowed-tools: Read, Write, Grep, Glob
 argument-hint: "[create|drill|coverage] [alert name or type | 告警名稱或類型]"
 ---

package/bundled/skills/security-assistant/SKILL.md

@@ -4,7 +4,7 @@ scope: universal
 description: |
   Guide security review and vulnerability assessment following OWASP standards.
   Use when: security audit, vulnerability check, secure coding review, threat modeling.
-  Keywords: security, OWASP, vulnerability, authentication, authorization, 安全, 漏洞, 認證.
+  Keywords: security, OWASP, vulnerability, authentication, authorization.
 allowed-tools: Read, Grep, Glob
 argument-hint: "[module or file to audit | 要審計的模組或檔案]"
 ---

package/bundled/skills/security-scan-assistant/SKILL.md

@@ -4,7 +4,7 @@ scope: universal
 description: |
   Guide automated security scanning, dependency auditing, and secret detection.
   Use when: dependency audit, CVE scanning, secret detection, license compliance.
-  Keywords: scan, audit, CVE, dependency, secret, SBOM, vulnerability, 掃描, 漏洞.
+  Keywords: scan, audit, CVE, dependency, secret, SBOM, vulnerability.
 allowed-tools: Read, Grep, Glob, Bash(npm:audit, npx:*)
 argument-hint: "[scan type or target | 掃描類型或目標]"
 ---

package/bundled/skills/slo-assistant/SKILL.md

@@ -4,7 +4,7 @@ scope: universal
 description: |
   Guide SLI selection, SLO setting, and Error Budget management.
   Use when: defining service quality targets, setting up SLO-based alerting, Error Budget policy.
-  Keywords: SLI, SLO, SLA, Error Budget, burn rate, service level, 服務等級.
+  Keywords: SLI, SLO, SLA, Error Budget, burn rate, service level.
 allowed-tools: Read, Write, Grep, Glob
 argument-hint: "[create|review|budget] [service name | 服務名稱]"
 ---

package/bundled/skills/sweep/SKILL.md

@@ -4,7 +4,7 @@ scope: universal
 description: |
   Scan codebase for debug artifacts and code quality issues; optionally auto-fix safe patterns.
   Use when: before committing, during PR review, or periodic codebase cleanup.
-  Keywords: sweep, debug cleanup, console.log, debugger, TODO, ts-any, code quality, 掃描, 清理.
+  Keywords: sweep, debug cleanup, console.log, debugger, TODO, ts-any, code quality.
 allowed-tools: Read, Grep, Glob, Bash(find:*), Edit, Write
 argument-hint: "[--fix] [--report] [--path <dir>] [--exclude <pattern>]"
 ---

package/bundled/skills/testing-guide/SKILL.md

@@ -5,7 +5,7 @@ description: |
   Testing pyramid and test writing standards for UT/IT/ST/E2E.
   Supports ISTQB and Industry Pyramid frameworks.
   Use when: writing tests, discussing test coverage, test strategy, or test naming.
-  Keywords: test, unit, integration, e2e, coverage, mock, ISTQB, SIT, 測試, 單元, 整合, 端對端.
+  Keywords: test, unit, integration, e2e, coverage, mock, ISTQB, SIT.
 ---
 
 # Testing Guide

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-dev-standards",
-  "version": "5.14.0",
+  "version": "5.15.1",
   "description": "CLI tool for adopting Universal Development Standards",
   "keywords": [
     "documentation",

package/src/commands/check.js

@@ -38,6 +38,7 @@ import { StandardValidator } from '../utils/standard-validator.js';
 import { WorkflowGate } from '../utils/workflow-gate.js';
 import { t, setLanguage, isLanguageExplicitlySet } from '../i18n/messages.js';
 import { guardAgainstSelfAdoption } from '../utils/detect-self-adoption.js';
+import { lintAll as lintI18nAll, partitionFindings as partitionI18nFindings } from '../lint/i18n.js';
 
 /**
  * Display the summary of file integrity status
@@ -243,6 +244,15 @@ function displayAdoptionStatus(manifest, msg, common, repoInfo) {
 export async function checkCommand(options = {}) {
   const projectPath = process.cwd();
 
+  // Handle --i18n option early — i18n lint is meant to be runnable both
+  // inside UDS source (lint canonical + locale variants) and inside
+  // adopter projects (lint installed locale variants). It does not require
+  // adoption-drift checks, so we short-circuit before guardAgainstSelfAdoption.
+  if (options.i18n) {
+    await runI18nLint(projectPath, options);
+    return;
+  }
+
   // Refuse to run inside the UDS source repo itself.
   // See DEC-044 / XSPEC-071 — adoption-drift check makes no sense for the
   // source repo. `--force` bypasses (e.g. private forks of UDS).
@@ -1837,3 +1847,64 @@ function displayWorkflowStatus(projectPath) {
     // Silently skip if workflow gate not available
   }
 }
+
+// ============================================================
+// i18n Lint (XSPEC-239 — P1-CLI-5)
+// ============================================================
+
+/**
+ * Run i18n lint across canonical + locale variants and print findings.
+ * Exits 1 if any error-level findings are detected.
+ *
+ * @param {string} projectPath
+ * @param {object} options - CLI options (currently honors options.json)
+ */
+async function runI18nLint(projectPath, options = {}) {
+  const findings = lintI18nAll({ projectPath });
+  const { errors, warnings } = partitionI18nFindings(findings);
+
+  if (options.json) {
+    console.log(JSON.stringify({
+      summary: {
+        errors: errors.length,
+        warnings: warnings.length,
+      },
+      findings,
+    }, null, 2));
+    if (errors.length > 0) process.exitCode = 1;
+    return;
+  }
+
+  console.log();
+  console.log(chalk.bold('UDS i18n Lint (XSPEC-239)'));
+  console.log(chalk.gray('─'.repeat(50)));
+  console.log();
+
+  if (findings.length === 0) {
+    console.log(chalk.green('  ✓ No i18n violations found.'));
+    console.log();
+    return;
+  }
+
+  // Display errors first
+  for (const f of errors) {
+    console.log(chalk.red(`  ✗ [${f.rule}]`));
+    console.log(chalk.red(`    ${f.file}:${f.line}`));
+    console.log(chalk.gray(`    ${f.message}`));
+    console.log();
+  }
+  for (const f of warnings) {
+    console.log(chalk.yellow(`  ⚠ [${f.rule}]`));
+    console.log(chalk.yellow(`    ${f.file}:${f.line}`));
+    console.log(chalk.gray(`    ${f.message}`));
+    console.log();
+  }
+
+  console.log(chalk.gray('─'.repeat(50)));
+  console.log(`  ${chalk.red('Errors:')} ${errors.length}    ${chalk.yellow('Warnings:')} ${warnings.length}`);
+  console.log();
+
+  if (errors.length > 0) {
+    process.exitCode = 1;
+  }
+}

package/src/commands/init.js

@@ -23,6 +23,7 @@ import {
 import { displayLanguageToLocale } from '../utils/locale.js';
 import { generateReleaseConfig, RELEASE_MODE_LABELS } from '../utils/release-config.js';
 import { guardAgainstSelfAdoption } from '../utils/detect-self-adoption.js';
+import { readInstallYaml } from '../utils/config-manager.js';
 
 /**
  * Init command - initialize standards in current project
@@ -308,7 +309,13 @@ echo "Pre-commit checks passed"
  * Build configuration for non-interactive mode
  */
 function buildNonInteractiveConfig(options, detected, projectPath) {
-  const displayLanguage = options.locale || detectLanguage(null);
+  // Locale resolution order (XSPEC-239 §Req-3):
+  //   CLI --locale > .uds/install.yaml locale: > UDS_LOCALE env > LANG > 'en'
+  // detectLanguage() handles UDS_LOCALE + LANG fallback internally (P1-CLI-3).
+  const installYaml = readInstallYaml(projectPath);
+  const displayLanguage = options.locale
+    || installYaml.locale
+    || detectLanguage(null);
   
   // Determine AI tools
   const detectedAiTools = Object.keys(detected.aiTools).filter(k => detected.aiTools[k]);

package/src/commands/update.js

@@ -30,6 +30,7 @@ import {
   cleanupLegacyCommands
 } from '../utils/skills-installer.js';
 import { displayLanguageToLocale, isLocalizedLocale, detectLocaleFromStandards } from '../utils/locale.js';
+import { readInstallYaml } from '../utils/config-manager.js';
 import {
   getAgentDisplayName,
   getAgentConfig,
@@ -237,17 +238,49 @@ function checkNewStandards(manifest) {
 }
 
 /**
- * Resolve locale from manifest with fallback detection.
- * If manifest has display_language, use it. Otherwise detect from .standards/ files.
+ * Resolve locale for skill / command installation.
+ *
+ * Resolution order (XSPEC-239 §Req-3 / P1-CLI-2 + P1-CLI-3):
+ *   1. CLI `--locale` (passed via `options.locale`)
+ *   2. `.uds/install.yaml` `locale:`
+ *   3. `UDS_LOCALE` env var
+ *   4. manifest `options.display_language` (existing behaviour)
+ *   5. `.standards/` file-based detection (existing behaviour)
+ *   6. `'en'`
+ *
  * @param {Object} manifest - Project manifest
  * @param {string} projectPath - Project root path
+ * @param {Object} [options] - CLI options object (optional, for `--locale`)
  * @returns {string} Locale directory name (e.g., 'zh-TW', 'en')
  */
-function resolveLocale(manifest, projectPath) {
+function resolveLocale(manifest, projectPath, options) {
+  // 1. CLI flag wins
+  const cliLocale = options?.locale && displayLanguageToLocale(options.locale);
+  if (cliLocale && isLocalizedLocale(cliLocale)) return cliLocale;
+  if (cliLocale === 'en') return 'en';
+
+  // 2. .uds/install.yaml
+  const installYaml = readInstallYaml(projectPath);
+  if (installYaml.locale) {
+    const fromYaml = displayLanguageToLocale(installYaml.locale);
+    if (isLocalizedLocale(fromYaml)) return fromYaml;
+    if (fromYaml === 'en') return 'en';
+  }
+
+  // 3. UDS_LOCALE env
+  if (process.env.UDS_LOCALE) {
+    const fromEnv = displayLanguageToLocale(process.env.UDS_LOCALE);
+    if (isLocalizedLocale(fromEnv)) return fromEnv;
+    if (fromEnv === 'en') return 'en';
+  }
+
+  // 4. Manifest
   const fromManifest = displayLanguageToLocale(manifest.options?.display_language);
   if (isLocalizedLocale(fromManifest)) {
     return fromManifest;
   }
+
+  // 5. .standards/ detection → 6. 'en'
   return detectLocaleFromStandards(projectPath) || 'en';
 }
 
@@ -309,13 +342,13 @@ export async function updateCommand(options) {
 
   // Handle --skills option
   if (options.skills) {
-    await updateSkillsOnly(projectPath, manifest);
+    await updateSkillsOnly(projectPath, manifest, options);
     return;
   }
 
   // Handle --commands option
   if (options.commands) {
-    await updateCommandsOnly(projectPath, manifest);
+    await updateCommandsOnly(projectPath, manifest, options);
     return;
   }
 
@@ -892,7 +925,7 @@ export async function updateCommand(options) {
         // Install Skills if user agreed
         if (installSkills.length > 0) {
           const skillSpinner = ora(msg.installingNewSkills || 'Installing Skills...').start();
-          const skillsLocale = resolveLocale(manifest, projectPath);
+          const skillsLocale = resolveLocale(manifest, projectPath, options);
           const skillResult = await installSkillsToMultipleAgents(installSkills, null, projectPath, skillsLocale);
 
           // Update manifest
@@ -933,7 +966,7 @@ export async function updateCommand(options) {
         // Update outdated Skills if user agreed
         if (updateSkills.length > 0) {
           const updateSpinner = ora(msg.updatingSkills || 'Updating Skills...').start();
-          const updateLocale = resolveLocale(manifest, projectPath);
+          const updateLocale = resolveLocale(manifest, projectPath, options);
           const updateResult = await installSkillsToMultipleAgents(updateSkills, null, projectPath, updateLocale);
 
           // Update manifest version
@@ -969,7 +1002,7 @@ export async function updateCommand(options) {
         // Install Commands if user agreed
         if (installCommands.length > 0) {
           const cmdSpinner = ora(msg.installingNewCommands || 'Installing commands...').start();
-          const cmdLocale = resolveLocale(manifest, projectPath);
+          const cmdLocale = resolveLocale(manifest, projectPath, options);
           const cmdResult = await installCommandsToMultipleAgents(installCommands, null, projectPath, cmdLocale);
 
           // Update manifest
@@ -999,7 +1032,7 @@ export async function updateCommand(options) {
         // Update outdated Commands if user agreed
         if (updateCommands.length > 0) {
           const updateCmdSpinner = ora(msg.updatingCommands || 'Updating Commands...').start();
-          const updateCmdLocale = resolveLocale(manifest, projectPath);
+          const updateCmdLocale = resolveLocale(manifest, projectPath, options);
           const updateCmdResult = await installCommandsToMultipleAgents(updateCommands, null, projectPath, updateCmdLocale);
 
           // Update manifest version
@@ -1069,7 +1102,7 @@ export async function updateCommand(options) {
         }
       } else {
         // --yes mode: auto-install/update Skills and Commands (treat -y as confirming all prompts)
-        const skillsLocale = resolveLocale(manifest, projectPath);
+        const skillsLocale = resolveLocale(manifest, projectPath, options);
         let hasChanges = false;
 
         if (missingSkills.length > 0) {
@@ -1551,8 +1584,9 @@ async function syncIntegrationReferences(projectPath, manifest) {
  * Update Skills for all AI agents (--skills option)
  * @param {string} projectPath - Project path
  * @param {Object} manifest - Manifest object
+ * @param {Object} [options] - CLI options (forwarded for locale resolution)
  */
-async function updateSkillsOnly(projectPath, manifest) {
+async function updateSkillsOnly(projectPath, manifest, options) {
   const msg = t().commands.update;
   const repoInfo = getRepositoryInfo();
   const latestVersion = repoInfo.skills.version;
@@ -1621,7 +1655,7 @@ async function updateSkillsOnly(projectPath, manifest) {
 
   const spinner = ora(msg.installingSkills || 'Installing Skills...').start();
 
-  const skillsLocaleForUpdate = resolveLocale(manifest, projectPath);
+  const skillsLocaleForUpdate = resolveLocale(manifest, projectPath, options);
   const result = await installSkillsToMultipleAgents(
     fileBasedInstallations,
     null, // Install all skills
@@ -1665,8 +1699,9 @@ async function updateSkillsOnly(projectPath, manifest) {
  * Update slash commands for all AI agents (--commands option)
  * @param {string} projectPath - Project path
  * @param {Object} manifest - Manifest object
+ * @param {Object} [options] - CLI options (forwarded for locale resolution)
  */
-async function updateCommandsOnly(projectPath, manifest) {
+async function updateCommandsOnly(projectPath, manifest, options) {
   const msg = t().commands.update;
 
   console.log(chalk.cyan(msg.updatingCommandsOnly || 'Updating slash commands for all AI Agents...'));
@@ -1715,7 +1750,7 @@ async function updateCommandsOnly(projectPath, manifest) {
 
   const spinner = ora(msg.installingCommands || 'Installing commands...').start();
 
-  const commandsLocale = resolveLocale(manifest, projectPath);
+  const commandsLocale = resolveLocale(manifest, projectPath, options);
   const result = await installCommandsToMultipleAgents(
     commandsInstallations,
     null, // Install all commands

package/src/i18n/messages.js

@@ -1003,6 +1003,10 @@ export const messages = {
         installingSkills: 'Installing Claude Code Skills...',
         installedSkills: 'Installed {count} Skills to {locations}',
         installedSkillsWithErrors: 'Installed {count} Skills with {errors} errors',
+        // P1-CLI-1: locale fallback summary (printed after install when some
+        // skills lack a localized variant and fell back to English source)
+        localeFallbackTitle: 'Locale fallback: {count} skill(s) fell back to English because no {locale} variant exists:',
+        localeFallbackHint: 'See locales/COVERAGE.md for full coverage status.',
         // Success
         initializedSuccess: '✓ Standards initialized successfully!',
         filesCopied: '{count} files copied to project',
@@ -2264,6 +2268,9 @@ export const messages = {
         installingSkills: '安裝 Claude Code Skills 中...',
         installedSkills: '已安裝 {count} 個 Skills 到 {locations}',
         installedSkillsWithErrors: '已安裝 {count} 個 Skills，有 {errors} 個錯誤',
+        // P1-CLI-1：locale fallback 摘要（安裝結束後顯示，列出沒有對應語系變體而退回英文來源的 skill）
+        localeFallbackTitle: 'Locale fallback：{count} 個 skill 因為沒有 {locale} 變體而退回英文版本：',
+        localeFallbackHint: '完整覆蓋率請參閱 locales/COVERAGE.md。',
         // Success
         initializedSuccess: '✓ 標準初始化成功！',
         filesCopied: '已複製 {count} 個檔案到專案',
@@ -3270,6 +3277,9 @@ export const messages = {
         installingSkills: '正在安装 Claude Code Skills...',
         installedSkills: '已安装 {count} 个 Skills 到 {locations}',
         installedSkillsWithErrors: '已安装 {count} 个 Skills，有 {errors} 个错误',
+        // P1-CLI-1：locale fallback 摘要（安装结束后显示，列出没有对应语种变体而退回英文来源的 skill）
+        localeFallbackTitle: 'Locale fallback：{count} 个 skill 因为没有 {locale} 变体而退回英文版本：',
+        localeFallbackHint: '完整覆盖率请参阅 locales/COVERAGE.md。',
         // Success
         initializedSuccess: '✓ 标准初始化成功！',
         filesCopied: '已复制 {count} 个文件到项目',
@@ -3792,12 +3802,19 @@ export function msg(path) {
 }
 
 /**
- * Detect language from environment or locale setting
+ * Detect language from environment or locale setting.
+ *
+ * Resolution order (XSPEC-239 §Req-3 / P1-CLI-3):
+ *   1. explicit `locale` arg (from CLI `--locale`)
+ *   2. `UDS_LOCALE` env var (UDS-specific override; takes precedence over LANG)
+ *   3. POSIX locale env vars (`LANG` / `LC_ALL` / `LC_MESSAGES`)
+ *   4. `'en'`
+ *
  * @param {string|null} locale - Locale setting from CLI options
- * @returns {string} Detected language code
+ * @returns {string} Detected language code ('zh-tw' | 'zh-cn' | 'en')
  */
 export function detectLanguage(locale) {
-  // If locale is explicitly set, use it
+  // 1. If locale is explicitly set, use it
   if (locale === 'zh-tw') {
     return 'zh-tw';
   }
@@ -3805,7 +3822,17 @@ export function detectLanguage(locale) {
     return 'zh-cn';
   }
 
-  // Check environment variables
+  // 2. UDS-specific env var (P1-CLI-3): preferred over generic POSIX LANG so
+  // adopters can opt into a specific UDS locale in CI without touching LANG.
+  if (process.env.UDS_LOCALE) {
+    const v = process.env.UDS_LOCALE.toLowerCase();
+    if (v === 'zh-tw' || v === 'zh_tw') return 'zh-tw';
+    if (v === 'zh-cn' || v === 'zh_cn') return 'zh-cn';
+    if (v === 'en') return 'en';
+    // Unknown UDS_LOCALE values fall through to LANG detection below
+  }
+
+  // 3. Check POSIX environment variables
   const envLang = process.env.LANG || process.env.LC_ALL || process.env.LC_MESSAGES || '';
   if (envLang.toLowerCase().includes('zh_tw') || envLang.toLowerCase().includes('zh-tw')) {
     return 'zh-tw';
@@ -3814,6 +3841,6 @@ export function detectLanguage(locale) {
     return 'zh-cn';
   }
 
-  // Default to English
+  // 4. Default to English
   return 'en';
 }

package/src/installers/skills-installer.js

@@ -34,6 +34,46 @@ import {
 } from '../config/ai-agent-paths.js';
 import { getRepositoryInfo } from '../utils/registry.js';
 
+/**
+ * Print a single WARN block summarizing skills that fell back to the English
+ * source because no localized variant exists for the requested locale.
+ *
+ * Adopter-facing behaviour (XSPEC-239 §Req-3 / P1-CLI-1):
+ * - One yellow block at the end of install, listing all fallen-back skills.
+ * - Hint pointer to `locales/COVERAGE.md` for the full coverage matrix.
+ *
+ * The `messages` bundle is the same flat command-scope bundle that `installSkills`
+ * receives (e.g. `t().commands.init`). Falls back to English literals if keys
+ * are absent so older translation bundles keep working.
+ *
+ * @param {string[]} fallenBack - Skill names that fell back to English
+ * @param {string} [locale] - Requested locale (e.g. 'zh-TW'); used in the message
+ * @param {Object} [messages] - Command-scope i18n bundle (optional)
+ * @returns {void}
+ */
+export function printLocaleFallbackWarning(fallenBack, locale, messages) {
+  if (!fallenBack || fallenBack.length === 0) return;
+
+  const count = fallenBack.length;
+  const localeLabel = locale || 'requested locale';
+
+  const titleTemplate = messages?.localeFallbackTitle
+    || 'Locale fallback: {count} skill(s) fell back to English because no {locale} variant exists:';
+  const hint = messages?.localeFallbackHint
+    || 'See locales/COVERAGE.md for full coverage status.';
+
+  const title = titleTemplate
+    .replace('{count}', String(count))
+    .replace('{locale}', localeLabel);
+
+  console.log();
+  console.log(chalk.yellow(`⚠ ${title}`));
+  for (const name of fallenBack) {
+    console.log(chalk.yellow(`    - ${name}`));
+  }
+  console.log(chalk.gray(`  ${hint}`));
+}
+
 /**
  * Get all skill files mapping (skill name -> file paths)
  * Used for remote download fallback
@@ -120,6 +160,15 @@ export async function installSkills(skillsConfig, projectPath, messages, results
         .replace('{count}', installResult.totalInstalled)
         .replace('{errors}', installResult.totalErrors));
     }
+
+    // P1-CLI-1: Emit a single locale-fallback WARN after the install loop when
+    // adopters requested a localized variant but some skills only ship in English.
+    // The aggregated list is built in installSkillsToMultipleAgents (deduped).
+    if (Array.isArray(installResult.localeFallbacks) && installResult.localeFallbacks.length > 0) {
+      // `messages` is a flat command-scope bundle (e.g. t().commands.init);
+      // the WARN helper looks for localeFallbackTitle/Hint keys directly on it.
+      printLocaleFallbackWarning(installResult.localeFallbacks, skillsConfig.locale, messages);
+    }
   } else if (skillsConfig.needsInstall && skillsConfig.updateTargets?.length > 0) {
     // Legacy fallback for backward compatibility (remote download)
     await installSkillsLegacy(skillsConfig, projectPath, messages, results);