universal-dev-standards 6.7.4 → 6.8.0

package/bundled/skills/docs-generator/SKILL.md

@@ -8,7 +8,30 @@ description: |
   Keywords: docgen, usage docs, cheatsheet, feature reference, generated documentation, 使用文件, 速查表, 文件產生.
 allowed-tools: Read, Write, Grep, Glob, Bash(*)
 argument-hint: "[config file | 設定檔]"
-disable-model-invocation: true
+status: stable
+# 2026-08-18: `disable-model-invocation: true` removed, and a status recorded.
+#
+# The flag was applied by d415937e alongside the description rewrite and, like
+# the two lifted on 2026-08-17, followed no stateable rule. These eight were
+# left alone that day for a reason that was correct at the time: the rule
+# settled on was "a reference is model-invocable", and none of them carried a
+# `status` at all, so lifting them would have replaced one unruled state with
+# one unruled action.
+#
+# Measured 2026-08-18, which is what closed it: all eight carry a full
+# `Use when:` trigger and a `Not for:` exclusion, all eight describe an action
+# rather than reference material, and all eight already have a slash command —
+# which is exactly the shape of `code-review-assistant`, whose paired `/code-review`
+# was ruled not to justify the flag. `journey-test-assistant` is the standing
+# precedent: same "Generate X" shape, `status: stable`, never disabled.
+#
+# `stable` rather than a new value: `skills/` uses reference, stable and
+# experimental, and inventing a fourth would be the same unruled-action mistake
+# in different clothing.
+#
+# The cost of being wrong is asymmetric and observable in only one direction.
+# Over-triggering shows up and is undone by deleting a line; a skill that is
+# structurally unable to fire produces no signal at all. (XSPEC-378 R5)
 ---
 
 # Documentation Generator | 文件產生器

package/bundled/skills/project-discovery/SKILL.md

@@ -8,7 +8,30 @@ description: |
   Keywords: discovery, project assessment, legacy onboarding, risk register, technical debt, 現況評估, 專案盤點, 風險登記簿.
 allowed-tools: Read, Grep, Glob, Bash(npm test:*), Bash(npm audit:*), Bash(npm outdated:*)
 argument-hint: "[feature area | 功能範圍]"
-disable-model-invocation: true
+status: stable
+# 2026-08-18: `disable-model-invocation: true` removed, and a status recorded.
+#
+# The flag was applied by d415937e alongside the description rewrite and, like
+# the two lifted on 2026-08-17, followed no stateable rule. These eight were
+# left alone that day for a reason that was correct at the time: the rule
+# settled on was "a reference is model-invocable", and none of them carried a
+# `status` at all, so lifting them would have replaced one unruled state with
+# one unruled action.
+#
+# Measured 2026-08-18, which is what closed it: all eight carry a full
+# `Use when:` trigger and a `Not for:` exclusion, all eight describe an action
+# rather than reference material, and all eight already have a slash command —
+# which is exactly the shape of `code-review-assistant`, whose paired `/code-review`
+# was ruled not to justify the flag. `journey-test-assistant` is the standing
+# precedent: same "Generate X" shape, `status: stable`, never disabled.
+#
+# `stable` rather than a new value: `skills/` uses reference, stable and
+# experimental, and inventing a fourth would be the same unruled-action mistake
+# in different clothing.
+#
+# The cost of being wrong is asymmetric and observable in only one direction.
+# Over-triggering shows up and is undone by deleting a line; a skill that is
+# structurally unable to fire produces no signal at all. (XSPEC-378 R5)
 ---
 
 # Project Discovery | 專案現況評估

package/bundled/skills/release-standards/SKILL.md

@@ -9,7 +9,30 @@ description: |
 allowed-tools: Read, Write, Grep, Bash(git:*), Bash(npm version:*)
 argument-hint: "[version]"
 prerequisites: ["release-check"]
-disable-model-invocation: true
+status: stable
+# 2026-08-18: `disable-model-invocation: true` removed, and a status recorded.
+#
+# The flag was applied by d415937e alongside the description rewrite and, like
+# the two lifted on 2026-08-17, followed no stateable rule. These eight were
+# left alone that day for a reason that was correct at the time: the rule
+# settled on was "a reference is model-invocable", and none of them carried a
+# `status` at all, so lifting them would have replaced one unruled state with
+# one unruled action.
+#
+# Measured 2026-08-18, which is what closed it: all eight carry a full
+# `Use when:` trigger and a `Not for:` exclusion, all eight describe an action
+# rather than reference material, and all eight already have a slash command —
+# which is exactly the shape of `code-review-assistant`, whose paired `/code-review`
+# was ruled not to justify the flag. `journey-test-assistant` is the standing
+# precedent: same "Generate X" shape, `status: stable`, never disabled.
+#
+# `stable` rather than a new value: `skills/` uses reference, stable and
+# experimental, and inventing a fourth would be the same unruled-action mistake
+# in different clothing.
+#
+# The cost of being wrong is asymmetric and observable in only one direction.
+# Over-triggering shows up and is undone by deleting a line; a skill that is
+# structurally unable to fire produces no signal at all. (XSPEC-378 R5)
 ---
 
 # Release Assistant | 發布助手

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

@@ -8,7 +8,30 @@ description: |
   Keywords: reverse engineering, system archeology, legacy code, spec extraction, data model, runtime, 反向工程, 系統考古, 規格提取.
 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
+status: stable
+# 2026-08-18: `disable-model-invocation: true` removed, and a status recorded.
+#
+# The flag was applied by d415937e alongside the description rewrite and, like
+# the two lifted on 2026-08-17, followed no stateable rule. These eight were
+# left alone that day for a reason that was correct at the time: the rule
+# settled on was "a reference is model-invocable", and none of them carried a
+# `status` at all, so lifting them would have replaced one unruled state with
+# one unruled action.
+#
+# Measured 2026-08-18, which is what closed it: all eight carry a full
+# `Use when:` trigger and a `Not for:` exclusion, all eight describe an action
+# rather than reference material, and all eight already have a slash command —
+# which is exactly the shape of `code-review-assistant`, whose paired `/code-review`
+# was ruled not to justify the flag. `journey-test-assistant` is the standing
+# precedent: same "Generate X" shape, `status: stable`, never disabled.
+#
+# `stable` rather than a new value: `skills/` uses reference, stable and
+# experimental, and inventing a fourth would be the same unruled-action mistake
+# in different clothing.
+#
+# The cost of being wrong is asymmetric and observable in only one direction.
+# Over-triggering shows up and is undone by deleting a line; a skill that is
+# structurally unable to fire produces no signal at all. (XSPEC-378 R5)
 ---
 
 # Reverse Engineering Assistant | 反向工程助手

package/bundled/skills/reverse-engineer/tdd-analysis.md

@@ -597,9 +597,22 @@ Mark both scenarios as [Inferred] with shared test reference
 
 ## CI/CD Integration
 
-### GitHub Actions Example
+### GitHub Actions — not currently scriptable
+
+There is no `uds reverse-tdd` CLI command. Coverage-gap analysis is delivered
+as the **`reverse-tdd`** AI agent (`uds agent install reverse-tdd`) — an
+interactive, LLM-driven analysis run from your AI tool, not a deterministic
+script that emits a `coverage.json` file. A prior version of this doc showed
+a GitHub Actions step invoking a CLI command that never existed (XSPEC-383
+R4, 2026-08-19).
+
+The sketch below is **illustrative only** — it shows the shape a scriptable
+CI integration would need if one is built, not something you can paste into
+a workflow today:
 
 ```yaml
+# ASPIRATIONAL — no scriptable equivalent exists yet.
+# Today: run the reverse-tdd agent interactively from your AI tool instead.
 name: BDD Coverage Check
 
 on: [pull_request]
@@ -610,29 +623,9 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Run BDD Coverage Analysis
-        run: |
-          uds reverse-tdd features/ --output coverage.json
-
-      - name: Check Coverage Threshold
+      - name: Run BDD Coverage Analysis (not yet implemented)
         run: |
-          COVERAGE=$(jq '.summary.effectiveCoverage' coverage.json)
-          if (( $(echo "$COVERAGE < 0.80" | bc -l) )); then
-            echo "Coverage $COVERAGE below 80% threshold"
-            exit 1
-          fi
-
-      - name: Comment on PR
-        uses: actions/github-script@v6
-        with:
-          script: |
-            const coverage = require('./coverage.json');
-            github.rest.issues.createComment({
-              issue_number: context.issue.number,
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              body: `## BDD Coverage Report\n\nCoverage: ${(coverage.summary.effectiveCoverage * 100).toFixed(1)}%`
-            });
+          echo "No CLI equivalent yet — see reverse-tdd agent for interactive use"
 ```
 
 ---

package/bundled/skills/spec-derivation/SKILL.md

@@ -9,7 +9,30 @@ description: |
 allowed-tools: Read, Write, Grep, Glob
 argument-hint: "[all|bdd|tdd|it|e2e|atdd] <spec-file>"
 prerequisites: ["spec-approved"]
-disable-model-invocation: true
+status: stable
+# 2026-08-18: `disable-model-invocation: true` removed, and a status recorded.
+#
+# The flag was applied by d415937e alongside the description rewrite and, like
+# the two lifted on 2026-08-17, followed no stateable rule. These eight were
+# left alone that day for a reason that was correct at the time: the rule
+# settled on was "a reference is model-invocable", and none of them carried a
+# `status` at all, so lifting them would have replaced one unruled state with
+# one unruled action.
+#
+# Measured 2026-08-18, which is what closed it: all eight carry a full
+# `Use when:` trigger and a `Not for:` exclusion, all eight describe an action
+# rather than reference material, and all eight already have a slash command —
+# which is exactly the shape of `code-review-assistant`, whose paired `/code-review`
+# was ruled not to justify the flag. `journey-test-assistant` is the standing
+# precedent: same "Generate X" shape, `status: stable`, never disabled.
+#
+# `stable` rather than a new value: `skills/` uses reference, stable and
+# experimental, and inventing a fourth would be the same unruled-action mistake
+# in different clothing.
+#
+# The cost of being wrong is asymmetric and observable in only one direction.
+# Over-triggering shows up and is undone by deleting a line; a skill that is
+# structurally unable to fire produces no signal at all. (XSPEC-378 R5)
 ---
 
 # Forward Derivation | 正向推演

package/bundled/skills/workflows/README.md

@@ -157,18 +157,9 @@ steps:
 
 ## Usage
 
-### CLI Installation
+### Getting Workflows
 
-```bash
-# List available workflows
-uds workflow list
-
-# Install specific workflow
-uds workflow install integrated-flow
-
-# Install all workflows
-uds workflow install --all
-```
+`uds workflow` was removed in v6.0.0 (process orchestration moved to the adoption layer — DEC-049; see [MIGRATION-v6.md §3](../../docs/MIGRATION-v6.md#3-removed-4-deprecated-cli-commands)). There is no CLI install step: workflow definitions live directly under `skills/workflows/*.workflow.yaml` in this repo (see the table above), so reference them by path or copy them into your project's `.claude/workflows/`.
 
 ### Execution
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-dev-standards",
-  "version": "6.7.4",
+  "version": "6.8.0",
   "description": "CLI tool for adopting Universal Development Standards",
   "keywords": [
     "documentation",
@@ -56,7 +56,9 @@
     "prepare": "node ../scripts/setup-husky.mjs",
     "test:upgrade": "node scripts/test-upgrade-path.mjs",
     "check:bundle-parity": "node scripts/check-bundle-parity.mjs",
-    "prepack": "node scripts/prepack.mjs"
+    "prepack": "node scripts/prepack.mjs",
+    "check:reachability": "node scripts/check-module-reachability.mjs",
+    "check:command-existence": "node scripts/check-command-existence.mjs"
   },
   "dependencies": {
     "@inquirer/prompts": "^8.4.2",

package/src/commands/lint.js

@@ -0,0 +1,96 @@
+/**
+ * `uds lint` — dependency validity + size checks against installed specs
+ * (specs/*.md).
+ *
+ * XSPEC-383 R5 (Option E). `cli/src/utils/spec-linter.js` and this command's
+ * JSON shape existed since 2026-04-07, but no `uds lint` command was ever
+ * registered — VibeOps's `lint-executor.ts` has been calling
+ * `npx uds lint --json` since the same day and getting `command not found`
+ * every time, four and a half months, without anyone noticing (see
+ * `cli/scripts/check-module-reachability.mjs` for the full incident).
+ *
+ * This registers the command with exactly the two checks that survived
+ * `lintAll()`'s AC-coverage removal (see spec-linter.js for why AC coverage
+ * was dropped rather than patched). The `--json` shape is deliberately NOT a
+ * new design — it matches the shape VibeOps's `lint-executor.ts` has already
+ * been parsing (`result.summary.fail`, `result.results[].specId/.status/.message`)
+ * since it was written, so wiring this up does not also require a change on
+ * the VibeOps side.
+ *
+ * @module commands/lint
+ */
+
+import chalk from 'chalk';
+import { lintAll } from '../utils/spec-linter.js';
+
+/**
+ * Render a one-line human message for a single spec's lint result.
+ * Exported for tests; also used to build the `message` field of `--json`
+ * output.
+ */
+export function buildMessage(result) {
+  const parts = [];
+  if (result.deps.broken.length > 0) {
+    const targets = result.deps.broken.map((b) => b.target).join(', ');
+    parts.push(
+      `${result.deps.broken.length} broken dependenc${result.deps.broken.length === 1 ? 'y' : 'ies'}: ${targets}`
+    );
+  }
+  parts.push(`${result.size.effectiveLines} effective lines (${result.size.status})`);
+  return parts.join('; ');
+}
+
+export async function lintCommand(options = {}) {
+  const projectPath = process.cwd();
+  const result = lintAll(projectPath);
+
+  if (options.json) {
+    const payload = {
+      summary: result.summary,
+      results: result.results.map((r) => ({
+        specId: r.spec,
+        status: r.status,
+        message: buildMessage(r),
+      })),
+    };
+    console.log(JSON.stringify(payload, null, 2));
+    if (result.summary.fail > 0) process.exitCode = 1;
+    return;
+  }
+
+  console.log();
+  console.log(chalk.bold('Spec Lint'));
+  console.log(chalk.gray('─'.repeat(50)));
+
+  if (!result.specsDirExists) {
+    // 查無 spec 目錄 must say so explicitly — an empty { pass: 0, warn: 0,
+    // fail: 0 } summary is indistinguishable from "checked, all clean" unless
+    // the command says out loud that nothing was scanned.
+    console.log(chalk.yellow(`  查無 spec 目錄（./${result.specsDir}/ 不存在）`));
+    console.log(chalk.gray('  沒有東西被掃描——這不代表沒有問題，代表沒有檢查。'));
+    console.log();
+    return;
+  }
+
+  console.log(chalk.gray(`  掃描 ${result.results.length} 份 spec（./${result.specsDir}/）`));
+  console.log();
+
+  for (const r of result.results) {
+    const msg = buildMessage(r);
+    if (r.status === 'fail') {
+      console.log(chalk.red(`  ✗ ${r.spec}: ${msg}`));
+    } else if (r.status === 'warn') {
+      console.log(chalk.yellow(`  ⚠ ${r.spec}: ${msg}`));
+    } else {
+      console.log(chalk.green(`  ✓ ${r.spec}: ${msg}`));
+    }
+  }
+
+  console.log();
+  console.log(
+    chalk.gray(`  ${result.summary.pass} pass, ${result.summary.warn} warn, ${result.summary.fail} fail`)
+  );
+  console.log();
+
+  if (result.summary.fail > 0) process.exitCode = 1;
+}

package/src/commands/quickstart.js

@@ -3,6 +3,19 @@
  *
  * Reduces cognitive load by guiding users to common workflow paths.
  *
+ * ⚠️ Every `cmd` that starts with `uds ` MUST be a command this CLI actually
+ * registers, with flags it actually accepts. This is the one place whose entire
+ * job is "find the right commands quickly", so a wrong entry here does the exact
+ * opposite of what the command exists for.
+ *
+ * 2026-08-19: four entries pointed at things that do not exist — `uds lint`
+ * (twice), `uds sync` (twice, one of them the sole content of a whole
+ * workflow), `uds check --spec-size`, and `uds spec create --boost`. Verify with
+ * `uds <cmd> --definitely-not-a-real-flag` and look for "unknown command";
+ * `uds <cmd> --help` is NOT a valid check — commander prints the general help
+ * for an unknown command instead of erroring, so --help reports every name as
+ * valid.
+ *
  * @module commands/quickstart
  */
 
@@ -24,11 +37,10 @@ export const WORKFLOWS = [
     name: 'Full SDD Spec Flow (Boost)',
     description: 'Complete spec-driven development for complex features',
     steps: [
-      { cmd: 'uds spec create "your feature" --boost', desc: 'Create full SDD spec with design sections' },
-      { cmd: 'uds lint', desc: 'Validate spec quality and cross-references' },
+      { cmd: '# Use the /sdd skill', desc: 'Full spec lifecycle with review (see `uds spec --help`)' },
+      { cmd: 'uds spec create "your feature" --scope fullstack', desc: 'Create the spec, scoped' },
       { cmd: 'uds spec confirm SPEC-XXX', desc: 'Confirm after review' },
       { cmd: '# Implement with /derive → /tdd', desc: 'Use forward derivation and TDD' },
-      { cmd: 'uds sync', desc: 'Export context for session resume' },
     ],
   },
   {
@@ -46,19 +58,10 @@ export const WORKFLOWS = [
     description: 'Audit standards compliance and spec quality',
     steps: [
       { cmd: 'uds check', desc: 'Check standards file integrity' },
-      { cmd: 'uds check --spec-size', desc: 'Check spec sizes against limits' },
-      { cmd: 'uds lint', desc: 'Lint specs for AC coverage and dependency validity' },
+      { cmd: 'uds check --i18n', desc: 'Run i18n lint rules across canonical + locale variants' },
       { cmd: 'uds audit', desc: 'Deep health diagnosis' },
     ],
   },
-  {
-    name: 'Resume Previous Work',
-    description: 'Restore context from a previous session',
-    steps: [
-      { cmd: 'uds sync', desc: 'Generate context.md from git diff + workflow state' },
-      { cmd: 'cat .workflow-state/context.md', desc: 'Read context in new session' },
-    ],
-  },
 ];
 
 /**

package/src/i18n/messages.js

@@ -757,7 +757,7 @@ export const messages = {
         actionsAvailable: 'Actions available:',
         restoreOption: '• Run `uds check --restore` to restore all modified/missing files',
         diffOption: '• Run `uds check --diff` to view changes',
-        interactiveOption: '• Run `uds check --interactive` for file-by-file decisions',
+        interactiveOption: '• Run `uds check` for file-by-file decisions (interactive by default)',
         // Interactive mode
         interactiveMode: 'Interactive Mode:',
         filesNeedAttention: '{count} file(s) need attention.',
@@ -1991,7 +1991,7 @@ export const messages = {
         actionsAvailable: '可用操作：',
         restoreOption: '• 執行 `uds check --restore` 還原所有已修改/遺失的檔案',
         diffOption: '• 執行 `uds check --diff` 檢視變更',
-        interactiveOption: '• 執行 `uds check --interactive` 逐一處理檔案',
+        interactiveOption: '• 執行 `uds check` 逐一處理檔案（預設為互動模式）',
         // Interactive mode
         interactiveMode: '互動模式：',
         filesNeedAttention: '{count} 個檔案需要注意。',
@@ -3240,7 +3240,7 @@ export const messages = {
         actionsAvailable: '可用操作：',
         restoreOption: '• 执行 `uds check --restore` 恢复所有已修改/缺失文件',
         diffOption: '• 执行 `uds check --diff` 查看更改',
-        interactiveOption: '• 执行 `uds check --interactive` 逐文件决策',
+        interactiveOption: '• 执行 `uds check` 逐文件决策（默认为交互模式）',
         // Interactive mode
         interactiveMode: '交互模式：',
         filesNeedAttention: '{count} 个文件需要关注。',

package/src/reconciler/actual-state-scanner.js

@@ -11,7 +11,7 @@ import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
 import { createHash } from 'crypto';
 import { join, relative } from 'path';
 import { readManifest } from '../core/manifest.js';
-import { computeFileHash, computeIntegrationBlockHash } from '../utils/hasher.js';
+import { computeFileHash, computeIntegrationBlockHash, normalizeLineEndings } from '../utils/hasher.js';
 import { SUPPORTED_AI_TOOLS, UDS_MARKERS } from '../core/constants.js';
 import { getSkillsDirForAgent, getCommandsDirForAgent, getCommandFileExtension } from '../config/ai-agent-paths.js';
 import { getSkillsSourceEntryNames, getAvailableCommandNames } from '../utils/skills-installer.js';
@@ -322,6 +322,13 @@ function shippedCommandNames() {
  * materialising a second array first. The format is the contract; if it changes
  * in one place and not the other every skill reports as changed, which the
  * paired tests in `skill-content-hash.test.js` exist to catch.
+ *
+ * Content is line-ending normalized before hashing (GitHub issue #155): these
+ * are files installed into the adopter's own project, which `git checkout`
+ * may have rewritten to CRLF under `core.autocrlf=true` on Windows even
+ * though the desired side (`computeSkillContentHash`, reading UDS's own
+ * package source) never sees a `\r`. Without matching normalization here,
+ * every skill would report as changed on every Windows `uds update`.
  */
 function hashInstalledSkillDir(dirPath) {
   let entries;
@@ -346,7 +353,7 @@ function hashInstalledSkillDir(dirPath) {
     }
     h.update(name);
     h.update('\0');
-    h.update(content);
+    h.update(normalizeLineEndings(content));
     h.update('\0');
   }
   return `sha256:${h.digest('hex')}`;
@@ -437,12 +444,16 @@ function scanCommands(state, projectPath, manifest) {
       // Content hash of the installed file, for UDS-managed commands only —
       // same reasoning as skills: an adopter's own command has no desired
       // counterpart to compare against. (XSPEC-382 R7)
+      //
+      // Line-ending normalized before hashing (GitHub issue #155), matching
+      // `computeCommandContentHash` on the desired side — the same CRLF
+      // checkout risk `hashInstalledSkillDir` above documents applies here.
       const cmdUdsManaged = shippedCommandNames().has(cmdName);
       let cmdHash = null;
       if (cmdUdsManaged) {
         try {
           cmdHash = `sha256:${createHash('sha256')
-            .update(readFileSync(join(cmdsDir, entry.name), 'utf-8'))
+            .update(normalizeLineEndings(readFileSync(join(cmdsDir, entry.name), 'utf-8')))
             .digest('hex')}`;
         } catch {
           // Unreadable → no hash. A partial answer would claim a match that

package/src/utils/hasher.js

@@ -1,22 +1,75 @@
 import { createHash } from 'crypto';
-import { readFileSync, statSync, existsSync, readdirSync } from 'fs';
+import { readFileSync, existsSync, readdirSync } from 'fs';
 import { join, relative } from 'path';
 import { UDS_MARKERS } from '../core/constants.js';
 import { resolveIntegrationFile } from '../core/constants.js';
 
+// GitHub issue #155. `git config core.autocrlf true` (the common
+// Windows default) rewrites LF to CRLF on checkout. The manifest's stored
+// hashes are computed from the LF bytes git carries in the blob (that is what
+// every non-Windows install reads), so a Windows working tree — content
+// byte-for-byte what `git status` calls clean — hashed to something else
+// entirely. Every `.standards/*` file, every skill/command file, and every
+// CLAUDE.md/AGENTS.md UDS block came back "modified" although nothing had
+// changed. Normalizing line endings before hashing (both when the manifest is
+// written and when it is compared) makes the hash line-ending agnostic, so
+// LF and CRLF checkouts of the same content agree.
+//
+// This intentionally makes "someone converted this file's line endings, text
+// otherwise identical" invisible to `uds check`/`uds update`. That is the
+// point, not a gap: line-ending convention is a checkout artifact, not
+// content a standards library should track as a modification — it is the
+// same normalization `git diff`/`git status` already apply before deciding a
+// tracked file is dirty.
+
+/**
+ * Heuristic binary-content detector, matching the approach git itself uses:
+ * a NUL byte anywhere in the first 8000 bytes marks the buffer as binary.
+ * Binary content must never be line-ending-normalized — flipping `\r\n` bytes
+ * inside an image or font would silently corrupt the hash rather than make it
+ * platform-agnostic, and could hide (or manufacture) a real difference.
+ * Every file `uds` currently manages under `.standards/`, skills, and
+ * commands is text (`.md`/`.yaml`/`.json`), but this function is the general
+ * per-file entry point (also used for arbitrary skill directory contents),
+ * so the check stays in place for whatever gets added later.
+ * @param {Buffer} buffer
+ * @returns {boolean} True if the buffer looks binary
+ */
+export function isBinaryContent(buffer) {
+  const sampleSize = Math.min(buffer.length, 8000);
+  for (let i = 0; i < sampleSize; i++) {
+    if (buffer[i] === 0) return true;
+  }
+  return false;
+}
+
+/**
+ * Normalize CRLF and lone-CR line endings to LF.
+ * @param {string} text
+ * @returns {string} Normalized text
+ */
+export function normalizeLineEndings(text) {
+  return text.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+}
+
 /**
- * Compute SHA-256 hash for a file
+ * Compute SHA-256 hash for a file, normalizing line endings first (unless the
+ * file is binary — see `isBinaryContent`). `size` is the byte length of the
+ * normalized content, not the raw on-disk size, so the two stay consistent
+ * with each other for the quick-reject check in `compareFileHash`.
  * @param {string} filePath - Absolute file path
  * @returns {Object|null} { hash, size } or null if file doesn't exist
  */
 export function computeFileHash(filePath) {
   try {
-    const content = readFileSync(filePath);
+    const raw = readFileSync(filePath);
+    const content = isBinaryContent(raw)
+      ? raw
+      : Buffer.from(normalizeLineEndings(raw.toString('utf-8')), 'utf-8');
     const hash = createHash('sha256').update(content).digest('hex');
-    const stats = statSync(filePath);
     return {
       hash: `sha256:${hash}`,
-      size: stats.size
+      size: content.length
     };
   } catch {
     return null;
@@ -276,7 +329,10 @@ function extractBlockContent(content, format) {
  */
 export function computeIntegrationBlockHash(filePath) {
   try {
-    const content = readFileSync(filePath, 'utf-8');
+    // CLAUDE.md / AGENTS.md are always text — no binary check needed here,
+    // unlike `computeFileHash`.
+    const rawContent = readFileSync(filePath, 'utf-8');
+    const content = normalizeLineEndings(rawContent);
     const format = detectFormat(filePath);
     const { blockContent } = extractBlockContent(content, format);
 
@@ -287,13 +343,12 @@ export function computeIntegrationBlockHash(filePath) {
 
     const blockHash = createHash('sha256').update(blockContent).digest('hex');
     const fullHash = createHash('sha256').update(content).digest('hex');
-    const stats = statSync(filePath);
 
     return {
       blockHash: `sha256:${blockHash}`,
       blockSize: Buffer.byteLength(blockContent, 'utf-8'),
       fullHash: `sha256:${fullHash}`,
-      fullSize: stats.size
+      fullSize: Buffer.byteLength(content, 'utf-8')
     };
   } catch {
     return null;

package/src/utils/integration-generator.js

@@ -3181,8 +3181,8 @@ export function parseStandardsIndexCount(content) {
 export function wrapWithMarkers(content, format) {
   const markers = UDS_MARKERS[format] || UDS_MARKERS.markdown;
   const warning = format === 'plaintext'
-    ? '# WARNING: This block is managed by UDS (universal-dev-standards). DO NOT manually edit. Use \'npx uds install\' or \'npx uds update\' to modify.'
-    : '<!-- WARNING: This block is managed by UDS (universal-dev-standards). DO NOT manually edit. Use \'npx uds install\' or \'npx uds update\' to modify. -->';
+    ? '# WARNING: This block is managed by UDS (universal-dev-standards). DO NOT manually edit. Use \'npx uds init\' or \'npx uds update\' to modify.'
+    : '<!-- WARNING: This block is managed by UDS (universal-dev-standards). DO NOT manually edit. Use \'npx uds init\' or \'npx uds update\' to modify. -->';
   // 冪等：warning 位於 markers **內部**，而 extractMarkedContent 取出的內容也含它，
   // 於是重新包裝會疊出第二份（dev-platform CLAUDE.md 實測 178/179 兩行完全相同）。
   // 這裡先剝掉內容開頭既有的 warning，不論上游哪條路徑造成都能修掉。
@@ -3362,7 +3362,25 @@ export function generateAgentsMdSummary(config = {}) {
   lines.push('# AGENTS.md');
   lines.push('');
   lines.push('> Auto-generated by [Universal Dev Standards (UDS)](https://github.com/AsiaOstrich/universal-dev-standards).');
-  lines.push('> Full standards available in the `.standards/` directory.');
+  lines.push('>');
+  // Say it as an instruction, and say what this file is NOT.
+  //
+  // The previous line — "Full standards available in the `.standards/` directory" — was a
+  // description, and a description asks for nothing. Measured 2026-07-23: Codex read this
+  // file, listed the 65 standards it indexes, and opened none of them, so the rules had the
+  // same effect as not installing UDS at all. Measured again 2026-08-18 on a fresh
+  // `uds init -y`: the generated file is 5,667 bytes containing 69 filename references and
+  // **zero rule statements**. That is not a bug in the generator — 143 `.ai.yaml` files come
+  // to roughly 248k tokens, so inlining them is not possible — which is exactly why the file
+  // has to be explicit that it is an index and that the rules are elsewhere.
+  //
+  // This does not prove the rules get read; only XSPEC-357's P7 probe can measure that, and
+  // it is not built yet. It removes the one thing that was certainly wrong: a file that read
+  // as though it carried the standards when it carried their filenames. (XSPEC-357 R7)
+  lines.push('> **This file is an index, not the standards.** The rules are NOT reproduced here.');
+  lines.push('> Before acting on anything below, open the relevant file under `.standards/`');
+  lines.push('> and follow its contents. Working from this summary alone means working');
+  lines.push('> without the standards.');
   lines.push('');
 
   // Build & Test Commands (auto-detect project type)