universal-dev-standards 6.8.0 → 6.10.0

package/src/utils/integration-generator.js

@@ -3,7 +3,7 @@ import { dirname, join, basename } from 'path';
 import { getLanguageRules } from '../prompts/integrations.js';
 import { computeIntegrationBlockHash } from './hasher.js';
 import { UDS_MARKERS, SUPPORTED_AI_TOOLS, LEGACY_TOOL_MAPPINGS } from '../core/constants.js';
-import { resolveSelectedOptionSources, resolveStandardFilename } from './registry.js';
+import { resolveSelectedOptionSources, resolveStandardFilename, getAllStandards } from './registry.js';
 import { getAgentConfig, getAgentTier } from '../config/ai-agent-paths.js';
 
 /**
@@ -32,7 +32,10 @@ export function resolveContentModeForTool(tool, userContentMode) {
         ? { contentMode: 'minimal', level: 3 }
         : { contentMode: 'index', level: 2 };
     case 'partial':
-      return { contentMode: 'full', level: 1 };
+      // Was 'full'. Every partial-tier tool was being auto-assigned a mode
+      // that generated exactly the same bytes as 'index', so this is a rename
+      // of what these tools already got, not a change to it. (XSPEC-357 R7)
+      return { contentMode: 'index', level: 1 };
     case 'preview':
       return { contentMode: 'index', level: 2 };
     case 'minimal':
@@ -70,6 +73,31 @@ function getToolFileName(tool) {
   if (KNOWN_TOOL_FILES.has(tool) || /\.(md|yaml|yml|json)$/i.test(tool)) {
     return tool;
   }
+
+  // 🔴 A tool THIS system already knows, missing from THIS table, is an internal
+  // inconsistency — never a future tool. It must fail rather than get a generated
+  // filename.
+  //
+  // Measured 2026-09-08: `roo-code` is the key used by `ai-agent-paths.js`,
+  // `REGISTRY.json`, `agent-adapter.js` and `agents-installer.js`, while
+  // `SUPPORTED_AI_TOOLS` said `roo`. Every lookup here missed and fell through, so a
+  // real `uds init` in a Roo Code repo wrote its instructions to `roo-code.md` — a
+  // filename Roo Code's docs never mention. Nothing failed. Nothing warned. Same
+  // class as `.codex/skills/`, which this repo's own comments call "a directory UDS
+  // invented"; the line below was a *rule* for inventing them.
+  //
+  // ⚠️ The fallback itself is KEPT, because it is a deliberate design decision, not
+  // an accident: three tests assert it as "forward compatibility with future tools".
+  // Narrowing beats reversing — a genuinely unknown name still gets `<name>.md`; only
+  // the self-contradiction fails.
+  if (getAgentConfig(normalizedName)) {
+    throw new Error(
+      `getToolFileName: "${tool}" is a known agent in ai-agent-paths.js but is missing ` +
+      'from SUPPORTED_AI_TOOLS in cli/src/core/constants.js. Add it with the file that ' +
+      `tool actually reads. Refusing to invent "${tool}.md" — that is how a Roo Code ` +
+      'repo got its instructions written to a file Roo Code never reads.'
+    );
+  }
   return `${tool}.md`;
 }
 
@@ -1975,6 +2003,16 @@ src/
 /**
  * Tool-specific file headers
  */
+// 🔴 These headers used to open by telling the agent to "PRIORITIZE reading the
+// concise rules in `core/`". `uds init` installs standards into `.standards/`
+// and has never created a `core/` directory in an adopter's project — `core/`
+// is where the standards live in the UDS repo, not in the repos that adopt it.
+// So the first instruction in every generated file, for every tool, in every
+// language, pointed at nothing. An adopter reported the symptom on 2026-09-16
+// and read it as residue from an old install; it was not residue, a clean
+// `uds init` wrote it. 36 copies of the same two sentences, all wrong the same
+// way. `tests/unit/utils/tool-headers-no-core.test.js` walks the generated
+// output so a tenth tool cannot reintroduce it.
 const TOOL_HEADERS = {
   cursor: {
     en: `# Cursor Rules
@@ -1987,8 +2025,8 @@ You are an expert software engineer assistant. Follow these project standards.
 All responses should be in **English**.
 
 ## Core Standards Usage Rule
-> When verifying standards, checking code, or performing tasks, **PRIORITIZE** reading the concise rules in \`core/\` (e.g., \`core/testing-standards.md\`).
-> **ONLY** read \`core/guides/\` or \`methodologies/guides/\` when explicitly asked for educational content, detailed explanations, or tutorials.
+> When verifying standards, checking code, or performing tasks, read the rules in \`.standards/\` — that is where this project's standards are installed.
+> Each file states its own requirements; read the one the task is about rather than all of them.
 > This ensures token efficiency and focused context.`,
     'zh-tw': `# Cursor 規則
 # 由 Universal Dev Standards CLI 生成
@@ -2000,8 +2038,8 @@ All responses should be in **English**.
 所有回覆必須使用**繁體中文 (Traditional Chinese)**。
 
 ## 核心標準使用規則 / Core Standards Usage Rule
-> 當驗證標準、檢查程式碼或執行任務時，**優先**讀取 \`core/\` 中的精簡規則（例如 \`core/testing-standards.md\`）。
-> 只有在被明確要求提供教育內容、詳細解釋或教學時，才讀取 \`core/guides/\` 或 \`methodologies/guides/\`。
+> 當驗證標準、檢查程式碼或執行任務時，讀取 \`.standards/\` 裡的規則——那是本專案標準實際安裝的位置。
+> 每個檔案各自寫明它要求什麼；讀與當下任務相關的那一份，不必全部讀完。
 > 這確保了 Token 效率和上下文聚焦。`,
     bilingual: `# Cursor Rules | Cursor 規則
 # Generated by Universal Dev Standards CLI
@@ -2016,10 +2054,10 @@ All responses should be in **Traditional Chinese (繁體中文)**, with technica
 所有回覆必須使用**繁體中文**，技術術語可保留英文。
 
 ## Core Standards Usage Rule / 核心標準使用規則
-> When verifying standards, checking code, or performing tasks, **PRIORITIZE** reading the concise rules in \`core/\` (e.g., \`core/testing-standards.md\`).
-> 當驗證標準、檢查程式碼或執行任務時，**優先**讀取 \`core/\` 中的精簡規則（例如 \`core/testing-standards.md\`）。
-> **ONLY** read \`core/guides/\` or \`methodologies/guides/\` when explicitly asked for educational content, detailed explanations, or tutorials.
-> 只有在被明確要求提供教育內容、詳細解釋或教學時，才讀取 \`core/guides/\` 或 \`methodologies/guides/\`。
+> When verifying standards, checking code, or performing tasks, read the rules in \`.standards/\` — that is where this project's standards are installed.
+> 當驗證標準、檢查程式碼或執行任務時，讀取 \`.standards/\` 裡的規則——那是本專案標準實際安裝的位置。
+> Each file states its own requirements; read the one the task is about rather than all of them.
+> 每個檔案各自寫明它要求什麼；讀與當下任務相關的那一份，不必全部讀完。
 > This ensures token efficiency and focused context.
 > 這確保了 Token 效率和上下文聚焦。`
   },
@@ -2034,8 +2072,8 @@ You are an expert software engineer assistant. Follow these project standards.
 All responses should be in **English**.
 
 ## Core Standards Usage Rule
-> When verifying standards, checking code, or performing tasks, **PRIORITIZE** reading the concise rules in \`core/\` (e.g., \`core/testing-standards.md\`).
-> **ONLY** read \`core/guides/\` or \`methodologies/guides/\` when explicitly asked for educational content, detailed explanations, or tutorials.
+> When verifying standards, checking code, or performing tasks, read the rules in \`.standards/\` — that is where this project's standards are installed.
+> Each file states its own requirements; read the one the task is about rather than all of them.
 > This ensures token efficiency and focused context.`,
     'zh-tw': `# Windsurf 規則
 # 由 Universal Dev Standards CLI 生成
@@ -2047,8 +2085,8 @@ All responses should be in **English**.
 所有回覆必須使用**繁體中文 (Traditional Chinese)**。
 
 ## 核心標準使用規則 / Core Standards Usage Rule
-> 當驗證標準、檢查程式碼或執行任務時，**優先**讀取 \`core/\` 中的精簡規則（例如 \`core/testing-standards.md\`）。
-> 只有在被明確要求提供教育內容、詳細解釋或教學時，才讀取 \`core/guides/\` 或 \`methodologies/guides/\`。
+> 當驗證標準、檢查程式碼或執行任務時，讀取 \`.standards/\` 裡的規則——那是本專案標準實際安裝的位置。
+> 每個檔案各自寫明它要求什麼；讀與當下任務相關的那一份，不必全部讀完。
 > 這確保了 Token 效率和上下文聚焦。`,
     bilingual: `# Windsurf Rules | Windsurf 規則
 # Generated by Universal Dev Standards CLI
@@ -2063,10 +2101,10 @@ All responses should be in **Traditional Chinese (繁體中文)**, with technica
 所有回覆必須使用**繁體中文**，技術術語可保留英文。
 
 ## Core Standards Usage Rule / 核心標準使用規則
-> When verifying standards, checking code, or performing tasks, **PRIORITIZE** reading the concise rules in \`core/\` (e.g., \`core/testing-standards.md\`).
-> 當驗證標準、檢查程式碼或執行任務時，**優先**讀取 \`core/\` 中的精簡規則（例如 \`core/testing-standards.md\`）。
-> **ONLY** read \`core/guides/\` or \`methodologies/guides/\` when explicitly asked for educational content, detailed explanations, or tutorials.
-> 只有在被明確要求提供教育內容、詳細解釋或教學時，才讀取 \`core/guides/\` 或 \`methodologies/guides/\`。
+> When verifying standards, checking code, or performing tasks, read the rules in \`.standards/\` — that is where this project's standards are installed.
+> 當驗證標準、檢查程式碼或執行任務時，讀取 \`.standards/\` 裡的規則——那是本專案標準實際安裝的位置。
+> Each file states its own requirements; read the one the task is about rather than all of them.
+> 每個檔案各自寫明它要求什麼；讀與當下任務相關的那一份，不必全部讀完。
 > This ensures token efficiency and focused context.
 > 這確保了 Token 效率和上下文聚焦。`
   },
@@ -2081,8 +2119,8 @@ You are an expert software engineer assistant. Follow these project standards.
 All responses should be in **English**.
 
 ## Core Standards Usage Rule
-> When verifying standards, checking code, or performing tasks, **PRIORITIZE** reading the concise rules in \`core/\` (e.g., \`core/testing-standards.md\`).
-> **ONLY** read \`core/guides/\` or \`methodologies/guides/\` when explicitly asked for educational content, detailed explanations, or tutorials.
+> When verifying standards, checking code, or performing tasks, read the rules in \`.standards/\` — that is where this project's standards are installed.
+> Each file states its own requirements; read the one the task is about rather than all of them.
 > This ensures token efficiency and focused context.`,
     'zh-tw': `# Cline 規則
 # 由 Universal Dev Standards CLI 生成
@@ -2094,8 +2132,8 @@ All responses should be in **English**.
 所有回覆必須使用**繁體中文 (Traditional Chinese)**。
 
 ## 核心標準使用規則 / Core Standards Usage Rule
-> 當驗證標準、檢查程式碼或執行任務時，**優先**讀取 \`core/\` 中的精簡規則（例如 \`core/testing-standards.md\`）。
-> 只有在被明確要求提供教育內容、詳細解釋或教學時，才讀取 \`core/guides/\` 或 \`methodologies/guides/\`。
+> 當驗證標準、檢查程式碼或執行任務時，讀取 \`.standards/\` 裡的規則——那是本專案標準實際安裝的位置。
+> 每個檔案各自寫明它要求什麼；讀與當下任務相關的那一份，不必全部讀完。
 > 這確保了 Token 效率和上下文聚焦。`,
     bilingual: `# Cline Rules | Cline 規則
 # Generated by Universal Dev Standards CLI
@@ -2110,10 +2148,10 @@ All responses should be in **Traditional Chinese (繁體中文)**, with technica
 所有回覆必須使用**繁體中文**，技術術語可保留英文。
 
 ## Core Standards Usage Rule / 核心標準使用規則
-> When verifying standards, checking code, or performing tasks, **PRIORITIZE** reading the concise rules in \`core/\` (e.g., \`core/testing-standards.md\`).
-> 當驗證標準、檢查程式碼或執行任務時，**優先**讀取 \`core/\` 中的精簡規則（例如 \`core/testing-standards.md\`）。
-> **ONLY** read \`core/guides/\` or \`methodologies/guides/\` when explicitly asked for educational content, detailed explanations, or tutorials.
-> 只有在被明確要求提供教育內容、詳細解釋或教學時，才讀取 \`core/guides/\` 或 \`methodologies/guides/\`。
+> When verifying standards, checking code, or performing tasks, read the rules in \`.standards/\` — that is where this project's standards are installed.
+> 當驗證標準、檢查程式碼或執行任務時，讀取 \`.standards/\` 裡的規則——那是本專案標準實際安裝的位置。
+> Each file states its own requirements; read the one the task is about rather than all of them.
+> 每個檔案各自寫明它要求什麼；讀與當下任務相關的那一份，不必全部讀完。
 > This ensures token efficiency and focused context.
 > 這確保了 Token 效率和上下文聚焦。`
   },
@@ -2128,8 +2166,8 @@ You are an expert software engineer assistant. Follow these project standards.
 All responses should be in **English**.
 
 ## Core Standards Usage Rule
-> When verifying standards, checking code, or performing tasks, **PRIORITIZE** reading the concise rules in \`core/\` (e.g., \`core/testing-standards.md\`).
-> **ONLY** read \`core/guides/\` or \`methodologies/guides/\` when explicitly asked for educational content, detailed explanations, or tutorials.
+> When verifying standards, checking code, or performing tasks, read the rules in \`.standards/\` — that is where this project's standards are installed.
+> Each file states its own requirements; read the one the task is about rather than all of them.
 > This ensures token efficiency and focused context.`,
     'zh-tw': `# GitHub Copilot 說明
 # 由 Universal Dev Standards CLI 生成
@@ -2141,8 +2179,8 @@ All responses should be in **English**.
 所有回覆必須使用**繁體中文 (Traditional Chinese)**。
 
 ## 核心標準使用規則 / Core Standards Usage Rule
-> 當驗證標準、檢查程式碼或執行任務時，**優先**讀取 \`core/\` 中的精簡規則（例如 \`core/testing-standards.md\`）。
-> 只有在被明確要求提供教育內容、詳細解釋或教學時，才讀取 \`core/guides/\` 或 \`methodologies/guides/\`。
+> 當驗證標準、檢查程式碼或執行任務時，讀取 \`.standards/\` 裡的規則——那是本專案標準實際安裝的位置。
+> 每個檔案各自寫明它要求什麼；讀與當下任務相關的那一份，不必全部讀完。
 > 這確保了 Token 效率和上下文聚焦。`,
     bilingual: `# GitHub Copilot Instructions | GitHub Copilot 說明
 # Generated by Universal Dev Standards CLI
@@ -2157,10 +2195,10 @@ All responses should be in **Traditional Chinese (繁體中文)**, with technica
 所有回覆必須使用**繁體中文**，技術術語可保留英文。
 
 ## Core Standards Usage Rule / 核心標準使用規則
-> When verifying standards, checking code, or performing tasks, **PRIORITIZE** reading the concise rules in \`core/\` (e.g., \`core/testing-standards.md\`).
-> 當驗證標準、檢查程式碼或執行任務時，**優先**讀取 \`core/\` 中的精簡規則（例如 \`core/testing-standards.md\`）。
-> **ONLY** read \`core/guides/\` or \`methodologies/guides/\` when explicitly asked for educational content, detailed explanations, or tutorials.
-> 只有在被明確要求提供教育內容、詳細解釋或教學時，才讀取 \`core/guides/\` 或 \`methodologies/guides/\`。
+> When verifying standards, checking code, or performing tasks, read the rules in \`.standards/\` — that is where this project's standards are installed.
+> 當驗證標準、檢查程式碼或執行任務時，讀取 \`.standards/\` 裡的規則——那是本專案標準實際安裝的位置。
+> Each file states its own requirements; read the one the task is about rather than all of them.
+> 每個檔案各自寫明它要求什麼；讀與當下任務相關的那一份，不必全部讀完。
 > This ensures token efficiency and focused context.
 > 這確保了 Token 效率和上下文聚焦。`
   },
@@ -2176,8 +2214,8 @@ Follow these project standards.
 All responses should be in **English**.
 
 ## Core Standards Usage Rule
-> When verifying standards, checking code, or performing tasks, **PRIORITIZE** reading the concise rules in \`core/\` (e.g., \`core/testing-standards.md\`).
-> **ONLY** read \`core/guides/\` or \`methodologies/guides/\` when explicitly asked for educational content, detailed explanations, or tutorials.
+> When verifying standards, checking code, or performing tasks, read the rules in \`.standards/\` — that is where this project's standards are installed.
+> Each file states its own requirements; read the one the task is about rather than all of them.
 > This ensures token efficiency and focused context.`,
     'zh-tw': `# Antigravity 系統指令
 # 由 Universal Dev Standards CLI 生成
@@ -2190,8 +2228,8 @@ Google Antigravity (Gemini Advanced Agent) 的推薦系統指令。
 所有回覆必須使用**繁體中文 (Traditional Chinese)**。
 
 ## 核心標準使用規則 / Core Standards Usage Rule
-> 當驗證標準、檢查程式碼或執行任務時，**優先**讀取 \`core/\` 中的精簡規則（例如 \`core/testing-standards.md\`）。
-> 只有在被明確要求提供教育內容、詳細解釋或教學時，才讀取 \`core/guides/\` 或 \`methodologies/guides/\`。
+> 當驗證標準、檢查程式碼或執行任務時，讀取 \`.standards/\` 裡的規則——那是本專案標準實際安裝的位置。
+> 每個檔案各自寫明它要求什麼；讀與當下任務相關的那一份，不必全部讀完。
 > 這確保了 Token 效率和上下文聚焦。`,
     bilingual: `# Antigravity System Instructions | Antigravity 系統指令
 # Generated by Universal Dev Standards CLI
@@ -2206,10 +2244,10 @@ All responses should be in **Traditional Chinese (繁體中文)**, with technica
 所有回覆必須使用**繁體中文**，技術術語可保留英文。
 
 ## Core Standards Usage Rule / 核心標準使用規則
-> When verifying standards, checking code, or performing tasks, **PRIORITIZE** reading the concise rules in \`core/\` (e.g., \`core/testing-standards.md\`).
-> 當驗證標準、檢查程式碼或執行任務時，**優先**讀取 \`core/\` 中的精簡規則（例如 \`core/testing-standards.md\`）。
-> **ONLY** read \`core/guides/\` or \`methodologies/guides/\` when explicitly asked for educational content, detailed explanations, or tutorials.
-> 只有在被明確要求提供教育內容、詳細解釋或教學時，才讀取 \`core/guides/\` 或 \`methodologies/guides/\`。
+> When verifying standards, checking code, or performing tasks, read the rules in \`.standards/\` — that is where this project's standards are installed.
+> 當驗證標準、檢查程式碼或執行任務時，讀取 \`.standards/\` 裡的規則——那是本專案標準實際安裝的位置。
+> Each file states its own requirements; read the one the task is about rather than all of them.
+> 每個檔案各自寫明它要求什麼；讀與當下任務相關的那一份，不必全部讀完。
 > This ensures token efficiency and focused context.
 > 這確保了 Token 效率和上下文聚焦。`
   },
@@ -2222,8 +2260,8 @@ All responses should be in **Traditional Chinese (繁體中文)**, with technica
 All responses should be in **English**.
 
 ## Core Standards Usage Rule
-> When verifying standards, checking code, or performing tasks, **PRIORITIZE** reading the concise rules in \`core/\` (e.g., \`core/testing-standards.md\`).
-> **ONLY** read \`core/guides/\` or \`methodologies/guides/\` when explicitly asked for educational content, detailed explanations, or tutorials.
+> When verifying standards, checking code, or performing tasks, read the rules in \`.standards/\` — that is where this project's standards are installed.
+> Each file states its own requirements; read the one the task is about rather than all of them.
 > This ensures token efficiency and focused context.`,
     'zh-tw': `# Claude Code 專案指南
 # 由 Universal Dev Standards CLI 生成
@@ -2234,8 +2272,8 @@ All responses should be in **English**.
 AI 助手應以繁體中文回覆使用者的問題與請求。
 
 ## 核心標準使用規則 / Core Standards Usage Rule
-> 當驗證標準、檢查程式碼或執行任務時，**優先**讀取 \`core/\` 中的精簡規則（例如 \`core/testing-standards.md\`）。
-> 只有在被明確要求提供教育內容、詳細解釋或教學時，才讀取 \`core/guides/\` 或 \`methodologies/guides/\`。
+> 當驗證標準、檢查程式碼或執行任務時，讀取 \`.standards/\` 裡的規則——那是本專案標準實際安裝的位置。
+> 每個檔案各自寫明它要求什麼；讀與當下任務相關的那一份，不必全部讀完。
 > 這確保了 Token 效率和上下文聚焦。`,
     bilingual: `# Project Guidelines for Claude Code | Claude Code 專案指南
 # Generated by Universal Dev Standards CLI
@@ -2248,10 +2286,10 @@ All responses should be in **Traditional Chinese (繁體中文)**, with technica
 AI 助手應以繁體中文回覆使用者的問題與請求。
 
 ## Core Standards Usage Rule / 核心標準使用規則
-> When verifying standards, checking code, or performing tasks, **PRIORITIZE** reading the concise rules in \`core/\` (e.g., \`core/testing-standards.md\`).
-> 當驗證標準、檢查程式碼或執行任務時，**優先**讀取 \`core/\` 中的精簡規則（例如 \`core/testing-standards.md\`）。
-> **ONLY** read \`core/guides/\` or \`methodologies/guides/\` when explicitly asked for educational content, detailed explanations, or tutorials.
-> 只有在被明確要求提供教育內容、詳細解釋或教學時，才讀取 \`core/guides/\` 或 \`methodologies/guides/\`。
+> When verifying standards, checking code, or performing tasks, read the rules in \`.standards/\` — that is where this project's standards are installed.
+> 當驗證標準、檢查程式碼或執行任務時，讀取 \`.standards/\` 裡的規則——那是本專案標準實際安裝的位置。
+> Each file states its own requirements; read the one the task is about rather than all of them.
+> 每個檔案各自寫明它要求什麼；讀與當下任務相關的那一份，不必全部讀完。
 > This ensures token efficiency and focused context.
 > 這確保了 Token 效率和上下文聚焦。`
   },
@@ -2266,8 +2304,8 @@ You are an expert software engineer assistant. Follow these project standards.
 All responses should be in **English**.
 
 ## Core Standards Usage Rule
-> When verifying standards, checking code, or performing tasks, **PRIORITIZE** reading the concise rules in \`core/\` (e.g., \`core/testing-standards.md\`).
-> **ONLY** read \`core/guides/\` or \`methodologies/guides/\` when explicitly asked for educational content, detailed explanations, or tutorials.
+> When verifying standards, checking code, or performing tasks, read the rules in \`.standards/\` — that is where this project's standards are installed.
+> Each file states its own requirements; read the one the task is about rather than all of them.
 > This ensures token efficiency and focused context.`,
     'zh-tw': `# AGENTS.md - OpenAI Codex CLI 規則
 # 由 Universal Dev Standards CLI 生成
@@ -2279,8 +2317,8 @@ All responses should be in **English**.
 所有回覆必須使用**繁體中文 (Traditional Chinese)**。
 
 ## 核心標準使用規則 / Core Standards Usage Rule
-> 當驗證標準、檢查程式碼或執行任務時，**優先**讀取 \`core/\` 中的精簡規則（例如 \`core/testing-standards.md\`）。
-> 只有在被明確要求提供教育內容、詳細解釋或教學時，才讀取 \`core/guides/\` 或 \`methodologies/guides/\`。
+> 當驗證標準、檢查程式碼或執行任務時，讀取 \`.standards/\` 裡的規則——那是本專案標準實際安裝的位置。
+> 每個檔案各自寫明它要求什麼；讀與當下任務相關的那一份，不必全部讀完。
 > 這確保了 Token 效率和上下文聚焦。`,
     bilingual: `# AGENTS.md - OpenAI Codex CLI Rules | OpenAI Codex CLI 規則
 # Generated by Universal Dev Standards CLI
@@ -2295,10 +2333,10 @@ All responses should be in **Traditional Chinese (繁體中文)**, with technica
 所有回覆必須使用**繁體中文**，技術術語可保留英文。
 
 ## Core Standards Usage Rule / 核心標準使用規則
-> When verifying standards, checking code, or performing tasks, **PRIORITIZE** reading the concise rules in \`core/\` (e.g., \`core/testing-standards.md\`).
-> 當驗證標準、檢查程式碼或執行任務時，**優先**讀取 \`core/\` 中的精簡規則（例如 \`core/testing-standards.md\`）。
-> **ONLY** read \`core/guides/\` or \`methodologies/guides/\` when explicitly asked for educational content, detailed explanations, or tutorials.
-> 只有在被明確要求提供教育內容、詳細解釋或教學時，才讀取 \`core/guides/\` 或 \`methodologies/guides/\`。
+> When verifying standards, checking code, or performing tasks, read the rules in \`.standards/\` — that is where this project's standards are installed.
+> 當驗證標準、檢查程式碼或執行任務時，讀取 \`.standards/\` 裡的規則——那是本專案標準實際安裝的位置。
+> Each file states its own requirements; read the one the task is about rather than all of them.
+> 每個檔案各自寫明它要求什麼；讀與當下任務相關的那一份，不必全部讀完。
 > This ensures token efficiency and focused context.
 > 這確保了 Token 效率和上下文聚焦。`
   },
@@ -2313,8 +2351,8 @@ You are an expert software engineer assistant powered by Gemini. Follow these pr
 All responses should be in **English**.
 
 ## Core Standards Usage Rule
-> When verifying standards, checking code, or performing tasks, **PRIORITIZE** reading the concise rules in \`core/\` (e.g., \`core/testing-standards.md\`).
-> **ONLY** read \`core/guides/\` or \`methodologies/guides/\` when explicitly asked for educational content, detailed explanations, or tutorials.
+> When verifying standards, checking code, or performing tasks, read the rules in \`.standards/\` — that is where this project's standards are installed.
+> Each file states its own requirements; read the one the task is about rather than all of them.
 > This ensures token efficiency and focused context.`,
     'zh-tw': `# GEMINI.md - Gemini CLI 規則
 # 由 Universal Dev Standards CLI 生成
@@ -2326,8 +2364,8 @@ All responses should be in **English**.
 所有回覆必須使用**繁體中文 (Traditional Chinese)**。
 
 ## 核心標準使用規則 / Core Standards Usage Rule
-> 當驗證標準、檢查程式碼或執行任務時，**優先**讀取 \`core/\` 中的精簡規則（例如 \`core/testing-standards.md\`）。
-> 只有在被明確要求提供教育內容、詳細解釋或教學時，才讀取 \`core/guides/\` 或 \`methodologies/guides/\`。
+> 當驗證標準、檢查程式碼或執行任務時，讀取 \`.standards/\` 裡的規則——那是本專案標準實際安裝的位置。
+> 每個檔案各自寫明它要求什麼；讀與當下任務相關的那一份，不必全部讀完。
 > 這確保了 Token 效率和上下文聚焦。`,
     bilingual: `# GEMINI.md - Gemini CLI Rules | Gemini CLI 規則
 # Generated by Universal Dev Standards CLI
@@ -2342,10 +2380,10 @@ All responses should be in **Traditional Chinese (繁體中文)**, with technica
 所有回覆必須使用**繁體中文**，技術術語可保留英文。
 
 ## Core Standards Usage Rule / 核心標準使用規則
-> When verifying standards, checking code, or performing tasks, **PRIORITIZE** reading the concise rules in \`core/\` (e.g., \`core/testing-standards.md\`).
-> 當驗證標準、檢查程式碼或執行任務時，**優先**讀取 \`core/\` 中的精簡規則（例如 \`core/testing-standards.md\`）。
-> **ONLY** read \`core/guides/\` or \`methodologies/guides/\` when explicitly asked for educational content, detailed explanations, or tutorials.
-> 只有在被明確要求提供教育內容、詳細解釋或教學時，才讀取 \`core/guides/\` 或 \`methodologies/guides/\`。
+> When verifying standards, checking code, or performing tasks, read the rules in \`.standards/\` — that is where this project's standards are installed.
+> 當驗證標準、檢查程式碼或執行任務時，讀取 \`.standards/\` 裡的規則——那是本專案標準實際安裝的位置。
+> Each file states its own requirements; read the one the task is about rather than all of them.
+> 每個檔案各自寫明它要求什麼；讀與當下任務相關的那一份，不必全部讀完。
 > This ensures token efficiency and focused context.
 > 這確保了 Token 效率和上下文聚焦。`
   },
@@ -2360,8 +2398,8 @@ You are an expert software engineer assistant. Follow these project standards.
 All responses should be in **English**.
 
 ## Core Standards Usage Rule
-> When verifying standards, checking code, or performing tasks, **PRIORITIZE** reading the concise rules in \`core/\` (e.g., \`core/testing-standards.md\`).
-> **ONLY** read \`core/guides/\` or \`methodologies/guides/\` when explicitly asked for educational content, detailed explanations, or tutorials.
+> When verifying standards, checking code, or performing tasks, read the rules in \`.standards/\` — that is where this project's standards are installed.
+> Each file states its own requirements; read the one the task is about rather than all of them.
 > This ensures token efficiency and focused context.`,
     'zh-tw': `# AGENTS.md - OpenCode 規則
 # 由 Universal Dev Standards CLI 生成
@@ -2373,8 +2411,8 @@ All responses should be in **English**.
 所有回覆必須使用**繁體中文 (Traditional Chinese)**。
 
 ## 核心標準使用規則 / Core Standards Usage Rule
-> 當驗證標準、檢查程式碼或執行任務時，**優先**讀取 \`core/\` 中的精簡規則（例如 \`core/testing-standards.md\`）。
-> 只有在被明確要求提供教育內容、詳細解釋或教學時，才讀取 \`core/guides/\` 或 \`methodologies/guides/\`。
+> 當驗證標準、檢查程式碼或執行任務時，讀取 \`.standards/\` 裡的規則——那是本專案標準實際安裝的位置。
+> 每個檔案各自寫明它要求什麼；讀與當下任務相關的那一份，不必全部讀完。
 > 這確保了 Token 效率和上下文聚焦。`,
     bilingual: `# AGENTS.md - OpenCode Rules | OpenCode 規則
 # Generated by Universal Dev Standards CLI
@@ -2389,15 +2427,61 @@ All responses should be in **Traditional Chinese (繁體中文)**, with technica
 所有回覆必須使用**繁體中文**，技術術語可保留英文。
 
 ## Core Standards Usage Rule / 核心標準使用規則
-> When verifying standards, checking code, or performing tasks, **PRIORITIZE** reading the concise rules in \`core/\` (e.g., \`core/testing-standards.md\`).
-> 當驗證標準、檢查程式碼或執行任務時，**優先**讀取 \`core/\` 中的精簡規則（例如 \`core/testing-standards.md\`）。
-> **ONLY** read \`core/guides/\` or \`methodologies/guides/\` when explicitly asked for educational content, detailed explanations, or tutorials.
-> 只有在被明確要求提供教育內容、詳細解釋或教學時，才讀取 \`core/guides/\` 或 \`methodologies/guides/\`。
+> When verifying standards, checking code, or performing tasks, read the rules in \`.standards/\` — that is where this project's standards are installed.
+> 當驗證標準、檢查程式碼或執行任務時，讀取 \`.standards/\` 裡的規則——那是本專案標準實際安裝的位置。
+> Each file states its own requirements; read the one the task is about rather than all of them.
+> 每個檔案各自寫明它要求什麼；讀與當下任務相關的那一份，不必全部讀完。
 > This ensures token efficiency and focused context.
 > 這確保了 Token 效率和上下文聚焦。`
   }
 };
 
+/**
+ * Generate the index disclosure that opens every UDS-managed block.
+ *
+ * XSPEC-357 R7 — the block an adopter receives is an index. In no content mode
+ * does it carry rule bodies, and inlining them is not an option: 143 `.ai.yaml`
+ * files come to roughly 248k tokens. What can be fixed is the block pretending
+ * otherwise. A file that lists 72 standard paths under a heading reading
+ * "Standards Compliance Instructions" reads, to an agent, like the compliance
+ * instructions — and Codex was measured on 2026-07-23 doing exactly that:
+ * it enumerated the standards and opened none of them.
+ *
+ * This wording was added to the universal `AGENTS.md` summary on 2026-08-18
+ * (`generateAgentsMdSummary`). That fixed one of the two producers. The other
+ * one is this — and the split is worse than it sounds, because the two are
+ * mutually exclusive for the same filename: selecting codex or opencode turns
+ * the universal summary OFF and routes `AGENTS.md` through here instead. The
+ * disclosure written for Codex was therefore in the only file a Codex adopter
+ * never receives. Measured 2026-08-20 before this change: 8 distinct adopter
+ * files across 3 content modes, 0 carrying the disclosure.
+ *
+ * @param {string} format - Output format: 'markdown' or 'plaintext'
+ * @param {string} language - Language: 'en', 'zh-tw', 'zh-cn' or 'bilingual'
+ * @returns {string} Disclosure paragraph, already format-adjusted
+ */
+export function generateIndexDisclosure(format, language = 'en') {
+  const lines = language === 'en'
+    ? [
+      '**This block is an index, not the standards.** The rules are NOT reproduced here.',
+      'Before acting on anything below, open the relevant file under `.standards/` and',
+      'follow its contents. Working from this block alone means working without the',
+      'standards.'
+    ]
+    : [
+      '**這個區塊是索引，不是標準本文。** 規則並未複製於此。',
+      '在依照下方任何一項行動之前，請打開 `.standards/` 底下對應的檔案並遵守其內容。',
+      '只憑這個區塊工作，等同於沒有採用標準。'
+    ];
+
+  if (format === 'markdown') {
+    return lines.map((l) => `> ${l}`).join('\n');
+  }
+  // Plaintext targets (.cursorrules / .clinerules / .windsurfrules) render
+  // neither blockquotes nor backticks, so both are stripped rather than shown.
+  return lines.map((l) => l.replace(/\*\*/g, '').replace(/`/g, '')).join('\n');
+}
+
 /**
  * Generate minimal standards reference for minimal content mode
  * @param {string[]} installedStandards - List of installed standard file paths
@@ -2662,6 +2746,86 @@ function generateWorkflowGateContent(language) {
  * @param {Object} config - Integration configuration
  * @returns {string} Generated content
  */
+/**
+ * Point every `.standards/<file>` reference at the file this project actually has.
+ *
+ * `RULE_TEMPLATES` spells its references as `.standards/<name>.md` because that
+ * is what UDS shipped when they were written. A project installed with
+ * `--format ai` holds `<name>.ai.yaml`, so those lines named files that are not
+ * there — reproduced on 6.9.0 (2026-09-16): a clean `--format ai` project got
+ * `.standards/anti-hallucination.md` and `.standards/checkin-standards.md`, and
+ * `uds check` called the file in sync because it compared names with the
+ * extension stripped and never asked whether the file existed.
+ *
+ * Rewrites by stem against the installed set; a reference whose standard this
+ * project did not install is dropped rather than left dangling, and if that
+ * empties the line, the line goes too.
+ *
+ * @param {string} content - Generated integration content
+ * @param {string[]} installedStandards - Manifest standards (IDs or paths)
+ * @param {string} standardsFormat - 'ai' | 'human'
+ * @returns {string}
+ */
+function resolveStandardReferences(content, installedStandards = [], standardsFormat = 'ai', projectPath = null) {
+  if (!content) return content;
+
+  const stemOf = (value) => basename(String(value)).replace(/\.(ai\.yaml|yaml|md)$/i, '');
+  // Every stem UDS itself ships — the only references this function may delete.
+  //
+  // Read defensively: this runs inside pure content generation, and callers
+  // (including this repo's own tests) may have the registry or `fs` mocked. A
+  // registry that cannot be read means "delete nothing", which degrades to
+  // rewriting matched paths only — never to removing a line.
+  const udsOwnedStems = new Set();
+  try {
+    for (const std of getAllStandards()) {
+      if (std?.id) udsOwnedStems.add(stemOf(std.id));
+      const sources = typeof std?.source === 'string'
+        ? [std.source]
+        : [std?.source?.ai, std?.source?.human].filter(Boolean);
+      for (const src of sources) udsOwnedStems.add(stemOf(src));
+    }
+  } catch {
+    // Registry unavailable — keep every reference that does not match.
+  }
+
+  const installedByStem = new Map();
+  for (const entry of installedStandards) {
+    const filename = resolveStandardFilename(entry, standardsFormat) || basename(String(entry));
+    installedByStem.set(stemOf(entry), filename);
+    installedByStem.set(stemOf(filename), filename);
+  }
+
+  const referenceLine = /^([^\n]*(?:Reference|參考|参考)[:：])([^\n]*)$/gim;
+  return content.replace(referenceLine, (line, label, rest) => {
+    let dropped = 0;
+    let kept = 0;
+    const rewritten = rest.replace(/(\.standards\/)([^\s,`)\]]+)/g, (match, prefix, path) => {
+      // Option files live in `.standards/options/…` and are named by path, not ID.
+      if (path.startsWith('options/')) { kept++; return match; }
+      const actual = installedByStem.get(stemOf(path));
+      if (actual) { kept++; return `${prefix}${actual}`; }
+
+      // 🔴 Only UDS's own standards may be dropped. The first version of this
+      // rewrite removed every unmatched reference, which deleted a project's own
+      // `.standards/our-house-rule.md` line — a file it had put there on purpose.
+      // Removing a user's line is worse than the dead link this exists to fix.
+      let onDisk = false;
+      try {
+        onDisk = Boolean(projectPath) && existsSync(join(projectPath, '.standards', path));
+      } catch {
+        onDisk = false;
+      }
+      if (onDisk || !udsOwnedStems.has(stemOf(path))) { kept++; return match; }
+      dropped++;
+      return '';
+    });
+    if (kept === 0 && dropped > 0) return '';
+    // Tidy the separators left behind by a dropped path.
+    return `${label}${rewritten.replace(/,\s*,/g, ',').replace(/[:：]?\s*,\s*$/, '').replace(/\s+,/g, ',')}`;
+  }).replace(/\n{3,}/g, '\n\n');
+}
+
 export function generateIntegrationContent(config) {
   const {
     tool,
@@ -2733,6 +2897,10 @@ export function generateIntegrationContent(config) {
     }
 
     if (installedStandards.length > 0) {
+      // XSPEC-357 R7 — every mode, every tool. Placed first because it is a
+      // precondition for reading the rest, not a footnote to it.
+      standardsContent = generateIndexDisclosure(format, language) + '\n\n' + standardsContent;
+
       if (contentMode === 'minimal') {
         // Minimal mode: simple reference list
         standardsContent += generateMinimalStandardsReference(
@@ -2812,7 +2980,8 @@ export function generateIntegrationContent(config) {
     sections.push('\n');
   }
 
-  return sections.join('\n').trim() + '\n';
+  const assembled = sections.join('\n').trim() + '\n';
+  return resolveStandardReferences(assembled, installedStandards, standardsFormat, config.projectPath || null);
 }
 
 /**
@@ -2895,6 +3064,19 @@ export function writeIntegrationFile(tool, config, projectPath) {
       }
     }
 
+    // 🔴 The rule sections live OUTSIDE the markers, so a marker-based update
+    // never refreshes them: a file first written by an older CLI kept
+    // `.standards/commit-message-guide.md` for ever, and a regenerate on the
+    // fixed generator still left it (measured 2026-09-16). Repoint stale
+    // `.standards/` paths across the whole file — it touches nothing but the
+    // paths, and a path to a file that is not there helps no reader.
+    content = resolveStandardReferences(
+      content,
+      config.installedStandards || [],
+      config.standardsFormat || 'ai',
+      projectPath
+    );
+
     writeFileSync(filePath, content);
 
     // Compute block hash for tracking UDS content separately from user content
@@ -3123,9 +3305,19 @@ function withSelectedOptions(manifest) {
 
 export function buildToolIntegrationConfig(manifest, tool) {
   const selected = manifest.options?.output_language || manifest.options?.commit_language || 'english';
-  const language = selected === 'bilingual'
+
+  // Content language comes from `display_language` — the setting whose entire
+  // job is "what language do you want to read" — and only falls back to
+  // `output_language`, which is the commit-message language, when the project
+  // has no display setting to go on. They are different questions: `uds init`
+  // has always used the first, every regeneration path used the second, and a
+  // project installed with `--locale zh-tw` therefore got Chinese instructions
+  // from `init` and English ones from the next `uds update`, silently.
+  const display = manifest.options?.display_language;
+  const fromOutput = selected === 'bilingual'
     ? 'bilingual'
     : selected === 'traditional-chinese' ? 'zh-tw' : 'en';
+  const language = ['en', 'zh-tw', 'bilingual'].includes(display) ? display : fromOutput;
   const resolved = resolveContentModeForTool(tool, manifest.contentMode || 'auto');
 
   return {
@@ -3353,6 +3545,7 @@ export function generateAgentsMdSummary(config = {}) {
     language = 'en',
     outputLanguage = 'english',
     standardOptions = {},
+    standardsFormat = 'ai',
     projectPath
   } = config;
 
@@ -3445,12 +3638,25 @@ export function generateAgentsMdSummary(config = {}) {
     // only the option files. On one adopter that meant seven lines standing in
     // for seventy, under a heading reading "Installed Standards", with nothing
     // anywhere reporting the sixty-three that had been dropped.
-    const resolved = installedStandards
-      .map((s) => resolveStandardFilename(s, 'ai'))
-      .filter((name) => name?.endsWith('.ai.yaml'));
-
-    for (const filename of resolved) {
-      lines.push(`- \`.standards/${filename}\` — ${filename.replace('.ai.yaml', '')}`);
+    // Two things this used to get wrong, both of which produced a list of paths
+    // that are not there — under a heading telling the agent to read them.
+    //
+    // Options install one directory deeper (`.standards/options/…`), and this
+    // wrote every entry at the top level. The sibling renderer in this file has
+    // always handled that; the docblock above it says a previous fix reached
+    // "one of the two producers", and this is the other one.
+    //
+    // And the format was pinned to `ai`, so a `--format human` project was
+    // handed `.ai.yaml` names for files it holds as `.md`.
+    const format = standardsFormat === 'human' ? 'human' : 'ai';
+    const suffix = format === 'human' ? '.md' : '.ai.yaml';
+
+    for (const entry of installedStandards) {
+      const filename = resolveStandardFilename(entry, format);
+      if (!filename?.endsWith(suffix)) continue;
+      const isOption = entry.includes('/options/') || entry.includes('\\options\\');
+      const dir = isOption ? '.standards/options' : '.standards';
+      lines.push(`- \`${dir}/${filename}\` — ${filename.replace(suffix, '')}`);
     }
   } else {
     lines.push('No standards installed yet. Run `npx uds init` to install.');