universal-dev-standards 6.3.6 → 6.3.8

package/bundled/locales/zh-TW/CHANGELOG.md

@@ -1,8 +1,8 @@
 ---
 source: ../../CHANGELOG.md
-source_version: 6.3.6
-translation_version: 6.3.6
-last_synced: 2026-08-07
+source_version: 6.3.8
+translation_version: 6.3.8
+last_synced: 2026-08-08
 status: current
 ---
 
@@ -17,6 +17,22 @@ status: current
 
 ## [Unreleased]
 
+## [6.3.8] - 2026-08-08
+
+### 修正
+
+- **`uds deps` 對一個它沒有檢查過的集合打了綠勾。** 對一個沒有執行期相依、且使用 pnpm lockfile 的專案執行時，它印出 `0 runtime dependencies checked`，接著 `no package-lock.json — nothing to compare the registry against`，接著 `✓ every dependency resolves to the version you test against`，然後 exit 0。兩項事實都為真；合起來卻宣稱一個這個指令讀不了的 repo 已被檢查而且沒問題，而任何接在這個 exit code 上的閘門都會同意。`clean` 的定義是三個空清單的合取，在空集合上恆真——而涵蓋它的測試正是以「分母會跟著結論一起走」為由斷言了這件事。分母確實跟著走了，卻什麼也沒改變：打勾緊接其後，而 exit code 完全沒有帶上那個計數。**印出分母不足以阻止空集合被讀成安心；拒絕給出結論才可以。** 同時修正該訊息的後半：該專案有一份完全正常的 `pnpm-lock.yaml`，而被告知「你沒有 lockfile」正是讀者判定工具搞錯、從此不再讀它的方式。指令現在會說出找到的是什麼、以及自己讀的是哪一種格式。
+- **registry ID 不是檔名，而有八個地方把它當成檔名用。** manifest 的 `standards` 陣列是刻意混合的：core 標準自 v3.4.0 起改為 registry ID，option 條目維持其上游來源路徑，因為 option 沒有 ID。而每個消費端都對兩者一律套 `basename()`——對路徑正確，對 ID 是 no-op。`error-code-standards` 安裝為 `error-codes.ai.yaml`、`logging-standards` 為 `logging.ai.yaml`、`ai-agreement` 為 `ai-agreement-standards.ai.yaml`；多數 ID 確實等於它的 basename，這正是它能存活的原因。同一個錯誤導出三種失效：minimal 模式印出 `.standards/<id>`，使**某採用者 AGENTS.md 的七十個路徑中有七個指不到東西**，而它們正下方那一行寫著「你必須讀取並遵循 `.standards/` 裡的標準」；索引區塊用 `.ai.yaml` 後綴過濾，而沒有任何 ID 帶這個後綴，於是**所有核心標準都被丟掉**，同一個採用者先前的區塊列了七個 option、六十三項核心標準一個也沒有；任務對應表以檔名為鍵，ID 一個也對不上，該標準就安靜地沒有對應。解析現在是一個匯出的函式，八個呼叫點共用，而解析不出的條目會列在清單下方回報，不會被印成路徑。
+- **那個專門用來抓這種漂移的檢查，帶著同一個缺陷。** `AGENTS.md Standards Sync` 對一份七十項的 manifest 回報 `7/7`：`.ai.yaml` 過濾只留下七個 option 條目，七個都在，於是打勾——升級前六十三項標準不在區塊裡時打勾，升級後區塊裡有七個死路徑時也打勾。對它所量測對象的九成視而不見，而且全程綠燈。在同一個專案上現在是 67/67，而手動弄壞一個路徑會回報 66/67 並指名該檔。它需要的那份對照，早就建在它上方一百七十行處，註解甚至指名了那個案例。
+- **產生器仍把 6.0.0 移除的路徑寫進採用者的指令檔。** `MIGRATION-v6` §2 移除了八個機器可讀標準，它們的執行期已移往採用層；三行 `Reference:` 與一筆 MUST 等級的任務對應仍指向 `.standards/workflow-enforcement.ai.yaml`。人類可讀的 `core/workflow-enforcement.md` 是刻意保留在上游的，但採用者收到的是 `.standards/` 而非 `core/`，所以它不是替代路徑——這幾行是刪除而非改指。控制該段落的判斷式比對的檔名，自 3.4.0 起沒有任何 manifest 持有，於是那段落對兩個仍宣告該標準的專案早已悄悄不再產生；現在兩種形式都比對。
+
+## [6.3.7] - 2026-08-07
+
+### Fixed
+
+- **`uds deps` 只讀 root 的 manifest，於是 monorepo 得到一個關於自己一部分的乾淨答案。** npm workspaces 會把宣告放在不只一份 `package.json`，而這個指令只看了其中一份。實測於一個真實專案：回報 34 個相依，實際宣告 47 個——**在 workspace 裡的那 13 個是隱形的，而其中一個帶著 high 等級的公告**。**一個沒有帶著自己範圍的計數，與一個完整的計數無從分辨**，而那正是這個指令存在要回報的失效。現在會從 `workspaces` 欄位展開、檢查每一份 manifest，並在報告中印出納入了哪些 workspace，讓分母自己帶著範圍。每一列漂移都標明它來自哪個 workspace——否則讀者知道某個套件漂移了，卻不知道該去改哪一份 `package.json`。
+- 三個細節決定了「有涵蓋 workspaces」與「看起來有涵蓋」的差別。lockfile 的條目可能被 hoist 到 root，**也可能**巢狀在 workspace 底下，所以兩處都查；只查一處會把另一處回報成「not present in package-lock.json」，而**一個被捏造出來的未知讀起來像一個發現**。workspace 相依於另一個 workspace 時是檔案連結而非已發布套件，因此跳過而不查詢——問 npm 會得到 404 並被記成 unverifiable。以及，比「最後一段結尾一個 `*`」更複雜的 `workspaces` 模式現在會**大聲失敗**而非匹配一個子集：**靜靜地涵蓋得比作者本意少，是同一個缺陷換個地方發生**。
+
 ## [6.3.6] - 2026-08-07
 
 ### Fixed

package/bundled/locales/zh-TW/README.md

@@ -15,7 +15,7 @@ status: current
 
 > **語言**: [English](../../README.md) | 繁體中文 | [简体中文](../zh-CN/README.md)
 
-**版本**: 6.3.6 | **發布日期**: 2026-07-31 | **授權**: [雙重授權](../../LICENSE) (CC BY 4.0 + MIT)
+**版本**: 6.3.8 | **發布日期**: 2026-07-31 | **授權**: [雙重授權](../../LICENSE) (CC BY 4.0 + MIT)
 
 語言無關、框架無關的軟體專案文件標準。透過 AI 原生工作流，確保不同技術堆疊之間的一致性、品質和可維護性。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-dev-standards",
-  "version": "6.3.6",
+  "version": "6.3.8",
   "description": "CLI tool for adopting Universal Development Standards",
   "keywords": [
     "documentation",
@@ -69,10 +69,7 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@vitest/coverage-v8": "^4.1.5",
-    "ajv": "^8.20.0",
-    "ajv-formats": "^3.0.1",
     "eslint": "10.7.0",
-    "glob": "^13.0.1",
     "globals": "17.7.0",
     "husky": "^9.1.7",
     "lint-staged": "^17.0.3",

package/src/commands/check.js

@@ -7,8 +7,7 @@ import { execSync } from 'child_process';
 import { readManifest, writeManifest, isInitialized, copyStandard, copyIntegration } from '../utils/copier.js';
 import {
   getAllStandards,
-  getRepositoryInfo
-} from '../utils/registry.js';
+  getRepositoryInfo, resolveStandardFilename } from '../utils/registry.js';
 import {
   computeFileHash,
   compareFileHash,
@@ -1244,7 +1243,23 @@ function checkAgentsMdSync(manifest, projectPath, msg) {
   }
 
   const content = readFileSync(agentsMdPath, 'utf-8');
-  const installedStandards = (manifest.standards || []).map(s => basename(s));
+  // Resolved through the registry, not basename()d.
+  //
+  // This check reported "standards synced (7/7)" for a project with seventy
+  // standards in its manifest. basename() leaves a registry ID unchanged, the
+  // `.ai.yaml` filter below then drops every ID, and only the seven option
+  // entries — which are stored as paths — survived to become the denominator.
+  // Seven of seven were present, so it ticked, both before the AGENTS.md block
+  // listed the other sixty-three and after, when seven of its paths pointed at
+  // nothing. A drift check blind to ninety percent of the content.
+  //
+  // The AI-tool integration check ~170 lines above already builds this exact
+  // mapping and its comment names the exact case (`error-code-standards` ->
+  // `error-codes.ai.yaml`). The knowledge was in the file; it had not reached
+  // its sibling.
+  const installedStandards = (manifest.standards || [])
+    .map(entry => resolveStandardFilename(entry, manifest.format || 'ai'))
+    .filter(Boolean);
 
   // Same as the AI-tool integration check above: an index-mode block declares a
   // count instead of listing names, so the name grep below cannot apply to it.

package/src/commands/config.js

@@ -917,7 +917,10 @@ export async function runProjectConfiguration(options) {
     const intSpinner = ora(msgObj.regeneratingIntegrations).start();
 
     // Build installed standards list
-    const installedStandardsList = manifest.standards?.map(s => basename(s)) || [];
+    // Raw, not basename()d. Resolution needs the registry (an ID is not a
+    // filename) and the `/options/` segment (it is what classifies an entry).
+    // basename() removes both. See resolveStandardFilename.
+    const installedStandardsList = manifest.standards || [];
 
     // Determine language setting
     let commonLanguage = 'en';
@@ -941,6 +944,7 @@ export async function runProjectConfiguration(options) {
         categories: ['anti-hallucination', 'commit-standards', 'code-review'],
         language: commonLanguage,
         installedStandards: installedStandardsList,
+        standardsFormat: manifest.format || 'ai',
         contentMode: newContentMode,
         // Pass output_language for dynamic commit standards generation
         outputLanguage: newOptions.output_language || 'english'

package/src/commands/deps.js

@@ -37,8 +37,47 @@ export function render(result) {
   lines.push('');
   lines.push(`${label} — ${result.examined} runtime dependenc${result.examined === 1 ? 'y' : 'ies'} checked`);
 
+  // The scope of the count, printed whenever it is more than the root. A
+  // denominator without its scope is what let this command report "34
+  // dependencies checked" for a repository that declared 47 across two
+  // manifests — the reader has no way to tell a complete answer from a subset.
+  const wsCount = result.workspaces?.length ?? 0;
+  if (wsCount > 0) {
+    lines.push(chalk.dim(`  across the root and ${wsCount} workspace${wsCount === 1 ? '' : 's'}: ${result.workspaces.join(', ')}`));
+  }
+
   if (!result.hasLockfile) {
-    lines.push(chalk.yellow('  no package-lock.json — nothing to compare the registry against'));
+    lines.push(
+      result.foreignLockfile
+        ? chalk.yellow(
+            `  found ${result.foreignLockfile}, and this command reads package-lock.json — the` +
+              ' tested column cannot be filled in',
+          )
+        : chalk.yellow('  no package-lock.json — nothing to compare the registry against'),
+    );
+  }
+
+  // Zero examined is reported before anything else can be said about the
+  // result, because everything else would be said about nothing. The three
+  // problem lists are empty here for the same reason an empty room has no
+  // untidy corners, and the tick below used to fire on exactly that.
+  if (result.examined === 0) {
+    lines.push('');
+    lines.push(chalk.yellow('  Nothing was examined, so nothing is being asserted.'));
+    lines.push(
+      chalk.dim(
+        result.hasLockfile
+          ? '  This package declares no runtime dependencies. If you expected some,'
+          : '  Without a readable lockfile there is no tested column. If you expected',
+      ),
+    );
+    lines.push(
+      chalk.dim(
+        result.hasLockfile
+          ? '  check that they are in "dependencies" rather than "devDependencies".'
+          : '  dependencies here, check the manifest and the lockfile format.',
+      ),
+    );
   }
 
   if (result.drifted.length > 0) {
@@ -52,9 +91,12 @@ export function render(result) {
     // underneath it" shape that R4 rewrote the supply-chain standard to stop.
     lines.push(chalk.yellow(`  ${result.drifted.length} tested ≠ resolves:`));
     for (const d of result.drifted) {
+      // The workspace is part of the finding, not decoration: without it the
+      // reader knows a package drifted but not which package.json to edit.
+      const where = d.workspaceDir ? chalk.dim(`  [${d.workspaceDir}]`) : '';
       lines.push(
         `    ${chalk.bold(d.name)}  ${chalk.dim(d.range)}` +
-          `  tested=${chalk.cyan(d.locked)}  resolves=${chalk.yellow(d.resolved)}`
+          `  tested=${chalk.cyan(d.locked)}  resolves=${chalk.yellow(d.resolved)}${where}`
       );
     }
     lines.push('');

package/src/commands/update.js

@@ -589,7 +589,10 @@ export async function updateCommand(options) {
     const intSpinner = ora(msg.syncingIntegrations).start();
 
     // Build installed standards list
-    const installedStandardsList = manifest.standards?.map(s => basename(s)) || [];
+    // Raw, not basename()d. Resolution needs the registry (an ID is not a
+    // filename) and the `/options/` segment (it is what classifies an entry).
+    // basename() removes both. See resolveStandardFilename.
+    const installedStandardsList = manifest.standards || [];
 
     // Determine language setting
     let commonLanguage = 'en';
@@ -617,6 +620,7 @@ export async function updateCommand(options) {
         categories: ['anti-hallucination', 'commit-standards', 'code-review'],
         language: commonLanguage,
         installedStandards: installedStandardsList,
+        standardsFormat: manifest.format || 'ai',
         contentMode: resolved.contentMode,
         level: resolved.level,
         // Pass output_language for dynamic commit standards generation
@@ -645,6 +649,7 @@ export async function updateCommand(options) {
     if (manifest.generateAgentsMd && !generatedFiles.has('AGENTS.md')) {
       const summaryConfig = {
         installedStandards: installedStandardsList,
+        standardsFormat: manifest.format || 'ai',
         language: manifest.options?.display_language || 'en',
         outputLanguage: manifest.options?.output_language || manifest.options?.commit_language || 'english',
         standardOptions: manifest.options || {}
@@ -1404,7 +1409,8 @@ export function regenerateIntegrations(projectPath, manifest) {
   // Regenerate universal AGENTS.md if enabled and not already covered
   if (manifest.generateAgentsMd && !generatedFiles.has('AGENTS.md')) {
     const summaryConfig = {
-      installedStandards: (manifest.standards || []).map(s => basename(s)),
+      // Raw — writeAgentsMdSummary resolves via the registry now.
+      installedStandards: manifest.standards || [],
       language: manifest.options?.display_language || 'en',
       outputLanguage: manifest.options?.output_language || manifest.options?.commit_language || 'english',
       standardOptions: manifest.options || {}
@@ -1469,7 +1475,14 @@ async function updateIntegrationsOnly(projectPath, manifest, options = {}) {
           ? 'bilingual'
           : (manifest.options?.output_language || manifest.options?.commit_language) === 'traditional-chinese'
             ? 'zh-tw' : 'en',
-        installedStandards: manifest.standards?.map((x) => basename(x)) || [],
+        // Passed raw. `basename()` here destroyed the two things the
+        // generator needs: a registry ID cannot be turned back into a
+        // filename once it has been through basename() (it comes out
+        // unchanged, and an ID is not a filename), and an option entry loses
+        // the `/options/` segment that classifies it. Resolution belongs
+        // where the registry is consulted, not at the call site.
+        installedStandards: manifest.standards || [],
+        standardsFormat: manifest.format || 'ai',
         contentMode: resolvedMode.contentMode,
         level: resolvedMode.level,
         outputLanguage: manifest.options?.output_language || manifest.options?.commit_language || 'english'

package/src/utils/dependency-resolution.js

@@ -66,7 +66,7 @@
  */
 
 import { spawn } from 'node:child_process';
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import semver from 'semver';
 
@@ -200,6 +200,66 @@ function spawnNpm(cwd) {
     });
 }
 
+/**
+ * Expand npm's `workspaces` field into directories that contain a
+ * package.json. // implements XSPEC-366 R1 (workspaces)
+ *
+ * Accepts both spellings — an array, or `{ packages: [...] }` — and supports a
+ * trailing `*` in the last segment, which is what `packages/*` needs and is the
+ * shape npm's own docs use. A pattern that matches nothing is returned as
+ * nothing rather than as an error: an empty `packages/*` is a normal state for
+ * a repository that has not added one yet.
+ */
+function expandWorkspaces(root, field) {
+  const patterns = Array.isArray(field) ? field : Array.isArray(field?.packages) ? field.packages : [];
+  const dirs = [];
+  for (const pattern of patterns) {
+    if (typeof pattern !== 'string' || pattern.length === 0) continue;
+    const star = pattern.indexOf('*');
+    if (star === -1) {
+      if (existsSync(join(root, pattern, 'package.json'))) dirs.push(pattern);
+      continue;
+    }
+    // Only a trailing `*` in the final segment is supported. Anything more
+    // exotic is rejected loudly rather than silently matching less than the
+    // author meant — a workspace quietly outside the denominator is the defect
+    // this module exists to report.
+    const prefix = pattern.slice(0, star);
+    if (!pattern.endsWith('*') || prefix.includes('*') || (prefix.length > 0 && !prefix.endsWith('/'))) {
+      throw new Error(
+        `unsupported workspaces pattern ${JSON.stringify(pattern)} — only a trailing "*" in the last segment is understood`
+      );
+    }
+    const parent = join(root, prefix);
+    if (!existsSync(parent)) continue;
+    for (const entry of readdirSync(parent, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const rel = `${prefix}${entry.name}`;
+      if (existsSync(join(root, rel, 'package.json'))) dirs.push(rel);
+    }
+  }
+  return dirs;
+}
+
+/**
+ * Where the lockfile records this dependency.
+ *
+ * npm hoists what it can to the root `node_modules` and nests the rest under
+ * the workspace, so both have to be tried; checking only one under-reports and
+ * calls the miss "unverifiable", which is noise that trains people to ignore
+ * the report.
+ */
+function lockedVersionFor(lock, workspaceDir, name) {
+  const candidates = workspaceDir
+    ? [`${workspaceDir}/node_modules/${name}`, `node_modules/${name}`]
+    : [`node_modules/${name}`];
+  for (const key of candidates) {
+    const entry = lock?.packages?.[key];
+    if (entry?.version) return entry.version;
+  }
+  return null;
+}
+
 /** Map over `items` with a bounded number of concurrent workers. */
 async function mapWithConcurrency(items, limit, worker) {
   const results = new Array(items.length);
@@ -238,16 +298,46 @@ export async function measureResolutionDrift(root, options = {}) {
   const lockPath = join(root, 'package-lock.json');
   const lock = existsSync(lockPath) ? JSON.parse(readFileSync(lockPath, 'utf8')) : null;
 
-  const declared = [
-    ...Object.entries(pkg.dependencies ?? {}).map(([name, range]) => ({ name, range, kind: 'dependencies' })),
-    ...Object.entries(pkg.optionalDependencies ?? {}).map(([name, range]) => ({ name, range, kind: 'optionalDependencies' })),
-  ];
+  // Which lockfile is present, when it is not npm's. Only package-lock.json is
+  // understood, and "not understood" has to be reported as a different thing
+  // from "not there" — a pnpm project told it had no lockfile will reasonably
+  // conclude the command is confused, and stop reading.
+  const foreignLockfile =
+    lock === null
+      ? ['pnpm-lock.yaml', 'yarn.lock', 'bun.lockb', 'bun.lock'].find((f) => existsSync(join(root, f))) ?? null
+      : null;
+
+  // Workspaces are examined too. A monorepo that declares its shipped
+  // front-end in a workspace and its server at the root has two manifests, and
+  // reading only the root reports a clean subset as if it were the whole — the
+  // failure this module exists to catch, performed by the tool itself.
+  const workspaceDirs = expandWorkspaces(root, pkg.workspaces);
+  const manifests = [{ dir: null, name: pkg.name ?? null, pkg }];
+  for (const dir of workspaceDirs) {
+    const wsPkg = JSON.parse(readFileSync(join(root, dir, 'package.json'), 'utf8'));
+    manifests.push({ dir, name: wsPkg.name ?? dir, pkg: wsPkg });
+  }
+  // A workspace depending on a sibling workspace is a file link, not a
+  // registry package. Querying npm for it returns 404, which would be recorded
+  // as unverifiable — a fabricated unknown, which is worse than a missing one
+  // because it looks like a finding.
+  const localNames = new Set(manifests.map((m) => m.pkg.name).filter(Boolean));
+
+  const declared = [];
+  for (const { dir, name: workspace, pkg: manifest } of manifests) {
+    for (const kind of ['dependencies', 'optionalDependencies']) {
+      for (const [name, range] of Object.entries(manifest[kind] ?? {})) {
+        if (localNames.has(name)) continue;
+        declared.push({ name, range, kind, workspace, workspaceDir: dir });
+      }
+    }
+  }
 
   const run = options.run ?? spawnNpm(root);
   const concurrency = options.concurrency ?? DEFAULT_CONCURRENCY;
 
   const rows = await mapWithConcurrency(declared, concurrency, async (dep) => {
-    const locked = lock?.packages?.[`node_modules/${dep.name}`]?.version ?? null;
+    const locked = lockedVersionFor(lock, dep.workspaceDir, dep.name);
     let resolved;
     try {
       resolved = await resolveViaNpm(dep.name, dep.range, run);
@@ -282,12 +372,42 @@ export async function measureResolutionDrift(root, options = {}) {
     root,
     packageName: pkg.name ?? null,
     hasLockfile: lock !== null,
+    /**
+     * Workspace directories examined alongside the root, so a reader can tell
+     * "no workspaces here" from "workspaces were not looked at". The count
+     * printed by the report is the denominator, and a denominator without its
+     * scope is the shape this module was written to refuse.
+     */
+    workspaces: workspaceDirs,
     examined: rows.length,
     consistent,
     drifted,
     unverifiable,
     unpinnedNative,
-    /** True when every dependency was checked, agreed, and needs no pinning. */
-    clean: drifted.length === 0 && unverifiable.length === 0 && unpinnedNative.length === 0,
+    /**
+     * A lockfile in a format this command cannot read, when there is no
+     * package-lock.json. `hasLockfile: false` alone reads as "this project has
+     * no lockfile", which for a pnpm or yarn project is simply untrue, and the
+     * report said so out loud: "no package-lock.json — nothing to compare"
+     * printed against a repo holding a perfectly good pnpm-lock.yaml.
+     */
+    foreignLockfile,
+    /**
+     * True when every dependency was checked, agreed, and needs no pinning.
+     *
+     * `examined === 0` is excluded, and that exclusion is the point. Run
+     * against asiaostrich-telemetry-client — zero runtime dependencies, a
+     * pnpm lockfile this command cannot read — the three problem lists came
+     * back empty and the report printed "✓ every dependency resolves to the
+     * version you test against". Nothing had been examined. The tick was
+     * true and it was also the exact shape this command exists to refuse:
+     * "nothing to check" and "everything checked out" arriving as the same
+     * green line.
+     */
+    clean:
+      rows.length > 0 &&
+      drifted.length === 0 &&
+      unverifiable.length === 0 &&
+      unpinnedNative.length === 0,
   };
 }