universal-dev-standards 6.7.5 → 6.9.0

package/src/commands/check.js

@@ -29,7 +29,8 @@ import {
   parseReferences,
   compareStandardsWithReferences
 } from '../utils/reference-sync.js';
-import { extractMarkedContent, getToolFilePath, parseStandardsIndexCount } from '../utils/integration-generator.js';
+import { extractMarkedContent, getToolFilePath, parseStandardsIndexCount, writeIntegrationFile } from '../utils/integration-generator.js';
+import { INTEGRATION_MAPPINGS } from '../installers/integration-installer.js';
 import { getToolFormat } from '../core/constants.js';
 import { checkForUpdates } from '../utils/npm-registry.js';
 import { writeUpdateCache } from '../utils/update-checker.js';
@@ -415,6 +416,9 @@ export async function checkCommand(options = {}) {
   // XSPEC-178: Full coverage compliance check
   checkFullCoverageCompliance(manifest, projectPath);
 
+  // 錯誤訊息單一出口閘門是否已安裝（只報告，不寫入）
+  checkErrorExitGate(projectPath);
+
   // Workflow status
   displayWorkflowStatus(projectPath);
 
@@ -664,6 +668,27 @@ export async function restoreSingleFile(projectPath, manifest, relativePath, msg
     msg = t().commands.check;
   }
 
+  // 🔴 Integration files are GENERATED, not copied. Restoring one by downloading a
+  // repo template overwrites the adopter's file with a document they never had —
+  // `integrations/claude-code/CLAUDE.md` is 140 lines last touched 2026-03-25, and no
+  // code path writes it at install time. The installer already records how each file
+  // was generated (`manifest.integrationConfigs`), so a correct restore regenerates
+  // from that, exactly as `uds update --sync-refs` does.
+  const genConfig = manifest.integrationConfigs?.[relativePath];
+  if (genConfig?.tool) {
+    const result = writeIntegrationFile(genConfig.tool, {
+      ...genConfig,
+      installedStandards: genConfig.installedStandards || manifest.standards || []
+    }, projectPath);
+    if (result.success) {
+      updateFileHash(projectPath, manifest, relativePath);
+      console.log(chalk.green(`  ✓ ${relativePath}: ${msg.restored}`));
+      return true;
+    }
+    console.log(chalk.red(`  ✗ ${relativePath}: ${result.error}`));
+    return false;
+  }
+
   const sourcePath = getSourcePathFromRelative(manifest, relativePath);
   if (!sourcePath) {
     console.log(chalk.red(`  ✗ ${relativePath}: ${msg.couldNotDetermineSource}`));
@@ -775,15 +800,18 @@ export function getSourcePathFromRelative(manifest, relativePath) {
 
   // Check integrations - these might need special handling
   if (manifest.integrations.some(i => (resolveIntegrationFile(i) || i) === relativePath)) {
-    // Integration files have different source paths
-    const integrationMappings = {
-      '.cursorrules': 'integrations/cursor/.cursorrules',
-      '.windsurfrules': 'integrations/windsurf/.windsurfrules',
-      '.clinerules': 'integrations/cline/.clinerules',
-      '.github/copilot-instructions.md': 'integrations/github-copilot/copilot-instructions.md',
-      'CLAUDE.md': 'integrations/claude-code/CLAUDE.md'
-    };
-    return integrationMappings[relativePath] || null;
+    // 🔴 This was a hand-copied list of five targets. The installer's own
+    // INTEGRATION_MAPPINGS covers eight and is the map actually used when a
+    // generation falls back to a static copy, so a second copy here could only
+    // drift — and had: it named `CLAUDE.md`, which INTEGRATION_MAPPINGS does not
+    // contain because no code path ever writes that template.
+    //
+    // Reached only for legacy manifests with no `integrationConfigs`; a current
+    // install regenerates instead (see restoreSingleFile).
+    for (const { source, target } of Object.values(INTEGRATION_MAPPINGS)) {
+      if (target === relativePath) return source;
+    }
+    return null;
   }
 
   return null;
@@ -1003,6 +1031,34 @@ function displaySkillsStatus(manifest, projectPath, msg) {
   return { missingSkills, missingCommands };
 }
 
+/**
+ * 錯誤訊息單一出口閘門：**偵測並報告，絕不寫入。**
+ *
+ * 🔴 為什麼只報告：`uds update` 之外沒有任何時刻是採用者同意我們動他的 repo 的。
+ *    未經同意往別人的專案寫可執行腳本，比它要修的那個問題更糟。
+ *    所以這裡只說「你沒有這道閘門」與「怎麼拿」，寫入留給 `uds update`，
+ *    而那裡會顯示內容並要人點頭。
+ *
+ * 起因（VibeOps 2026-09-03）：使用者照著建議打上名字，畫面回他一句 `Bad Request`。
+ * 真正的原因寫在回應的 `details` 裡，而呼叫端只讀了 `error`。當天的修法改了一個
+ * 呼叫端；走訪之後發現同型的有二十四個——其中三個在同一個檔案裡。
+ */
+function checkErrorExitGate(projectPath) {
+  const gatePath = join(projectPath, 'scripts', 'check-error-exit.mjs');
+  if (existsSync(gatePath)) {
+    return; // 裝了就不出聲。這裡的沉默代表「有」，不代表「跑過了」——那是它自己的事。
+  }
+  // 沒有 src/ 的專案（純文件、純設定）本來就沒有這個問題，不要對他們嘮叨。
+  if (!existsSync(join(projectPath, 'src'))) {
+    return;
+  }
+  console.log(chalk.yellow('  ⚠ [error-exit] 沒有錯誤訊息單一出口檢查（scripts/check-error-exit.mjs）。'));
+  console.log(chalk.gray('    這道閘門防的是「每個呼叫端各自把錯誤回應拼成給人看的字串」——'));
+  console.log(chalk.gray('    第一處是實作，第二處開始就會各寫各的，而畫面上只剩一句 Bad Request。'));
+  console.log(chalk.gray('    要裝的話：`uds update` 會顯示內容並徵求同意後寫入。'));
+  console.log();
+}
+
 /**
  * XSPEC-178: Check full-coverage-testing standard presence and STUB markers
  */

package/src/commands/init.js

@@ -4,7 +4,9 @@ import { execSync } from 'child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { basename, join } from 'path';
 import {
-  manifestExists as isInitialized
+  manifestExists as isInitialized,
+  normalizeContentMode,
+  SUPPORTED_CONTENT_MODES
 } from '../core/manifest.js';
 import { t, detectLanguage } from '../i18n/messages.js';
 import { detectAll } from '../utils/detector.js';
@@ -156,9 +158,29 @@ export async function initCommand(options) {
             skillHashes: {},
             commandHashes: {}
           };
+          // A detected tool that can take skills and has no verified path gets
+          // nothing — and must be told so. Silence was the actual defect measured
+          // on 2026-09-08: `--mode skills` installed nothing, printed no skills
+          // line, and exited 0. An adopter cannot know to go looking.
+          for (const tool of config.skillsConfig.skillsPathUnknownTools || []) {
+            console.log(chalk.yellow(
+              `⚠ ${getAgentDisplayName(tool) || tool}: ` +
+              `${msg.skillsPathUnknown || 'no verified skills path — nothing was installed for this tool'}`
+            ));
+          }
           await installSkills(config.skillsConfig, projectPath, msg, skillsResults);
           await installCommands(config.skillsConfig, projectPath, msg, skillsResults);
 
+          // A tool may need something from the adopter before it will read what
+          // we just wrote. Driven by an `installNote` on the path table, so a new
+          // precondition is a field and not a branch here.
+          for (const { agent } of config.skillsConfig.skillsInstallations || []) {
+            const note = getAgentConfig(agent)?.installNote;
+            if (note) {
+              console.log(chalk.yellow(`  ⚠ ${getAgentDisplayName(agent) || agent}: ${note}`));
+            }
+          }
+
           // Combine results
           installErrors = [
             ...standardsResults.errors,
@@ -225,7 +247,25 @@ export async function initCommand(options) {
     const { installHooks } = await import('../installers/hooks-installer.js');
     const hookResult = installHooks(projectPath);
     if (hookResult.installed) {
-      console.log(chalk.green(`  ✓ Enforcement hooks installed (${hookResult.scriptsCount} scripts)`));
+      console.log(chalk.green(
+        `  ✓ Enforcement hooks installed (${hookResult.scriptsCount} scripts, `
+        + `${hookResult.events.join(', ')})`));
+    } else {
+      // Silence here is how three broken installs reported success.
+      console.log(chalk.yellow('  ⚠ No enforcement hooks installed — no standard produced a usable hook.'));
+    }
+    for (const s of hookResult.skipped ?? []) {
+      console.log(chalk.yellow(`    · skipped ${s.id}: ${s.why}`));
+    }
+    // turn-completion-integrity R8: a prose-reading hook in a language it does
+    // not ship is installed, running, and unable to fire — and that looks
+    // exactly like a turn with nothing wrong. Say so at install time; there is
+    // no later moment where the adopter could find out.
+    for (const l of hookResult.languageLimits ?? []) {
+      console.log(chalk.yellow(`    · ${l.script} reads prose, and ships:`));
+      for (const line of l.languages.split('\n')) {
+        console.log(chalk.gray(`        ${line}`));
+      }
     }
   }
 
@@ -433,16 +473,95 @@ function buildNonInteractiveConfig(options, detected, projectPath) {
   });
 
   // Skills Configuration Logic
-  const hasSkillsCompatibleTool = aiToolsNormalized.some(t => t === 'claude-code' || t === 'opencode');
-  const onlySkillsCompatibleTools = aiToolsNormalized.every(t => t === 'claude-code' || t === 'opencode');
-  
+  //
+  // 🔴 Which tools can take skills is asked of the path table, never listed here.
+  // This used to read `t === 'claude-code' || t === 'opencode'`, and the two
+  // consequences were both measured on 2026-09-08 (XSPEC-408 §18.3):
+  //
+  //   - A repo detected as codex ran `uds init --mode skills -y` and got **zero
+  //     skills, in any directory, with no message saying so.**
+  //   - When a location was passed explicitly, the install went to `.claude/skills/`
+  //     for every tool, because the branch below never built `skillsInstallations`
+  //     and `installSkills()` then fell through to the legacy path, whose target is
+  //     the hardcoded `getProjectSkillsDir()`. Codex does not read that directory:
+  //     two arms differing only in path gave 15,235 vs 18,096 input tokens, and only
+  //     the `.agents/skills` arm made Codex say it could see the skills at all.
+  //
+  // 🔴 This is the second time in the same shape. `ai-agent-paths.js` records the
+  // first: `.codex/skills/` was "a directory UDS invented", skills there were
+  // invisible, and a behavioural probe failed while Codex behaved correctly. That
+  // fix corrected the path table. This one broke in the code that never asked it.
+  // The predicate below is the same one `promptSkillsInstallLocation` already used —
+  // the interactive flow was never wrong.
+  const skillsCapableTools = aiToolsNormalized.filter(tool => {
+    const config = getAgentConfig(tool);
+    return Boolean(config?.supportsSkills && config?.skills);
+  });
+  const hasSkillsCompatibleTool = skillsCapableTools.length > 0;
+  // Marketplace is Claude Code's. A tool reaches it either by having one
+  // (`supportsMarketplace`) or by reading Claude's directory (`fallbackSkillsPath`).
+  // ⚠️ Those fallback claims are NOT all verified — `opencode`'s carries the bare
+  // comment "Can read Claude skills" and no evidence. It is preserved here rather
+  // than flipped, because changing behaviour on an unverified field in either
+  // direction is a guess. Codex's identical claim WAS measured, and falsified, so
+  // its field is now null (see `ai-agent-paths.js`) and it drops out here by data.
+  // 🔴 The marketplace is all-or-nothing for a repo: it installs into Claude's
+  // directory, so it serves a tool only if that tool has a marketplace of its own or
+  // declares Claude's directory as its fallback. If ANY detected tool is not served
+  // by it, file installs are used instead — every tool then gets its own path, and
+  // nobody is left with a successful init and an empty directory.
+  const reachesMarketplace = t => {
+    const c = getAgentConfig(t);
+    return Boolean(c?.supportsMarketplace || c?.fallbackSkillsPath);
+  };
+  const onlySkillsCompatibleTools =
+    hasSkillsCompatibleTool && aiToolsNormalized.every(reachesMarketplace);
+
   let skillsLocationFlag = options.skillsLocation;
   if (!skillsLocationFlag) {
-    skillsLocationFlag = (hasSkillsCompatibleTool && onlySkillsCompatibleTools) ? 'marketplace' : 'none';
+    skillsLocationFlag = hasSkillsCompatibleTool
+      ? (onlySkillsCompatibleTools ? 'marketplace' : 'project')
+      : 'none';
   }
 
-  const contentModeFlag = options.contentMode || 'auto';
+  // A detected tool that can take skills and is getting none must SAY SO. The worst
+  // property of the old default was not the wrong directory, it was the silence:
+  // `--mode skills` printed no skills line at all and exited 0.
+  const skippedSkillsTools = aiToolsNormalized.filter(tool => {
+    const config = getAgentConfig(tool);
+    return Boolean(config?.supportsSkills) && !config?.skills;
+  });
+  // Carried on the config and printed by the caller — this function builds config
+  // and has no message bundle in scope. (First version called `msg` here and every
+  // init that detected a pathless tool crashed with `ReferenceError: msg is not
+  // defined`; the gate's own control arm missed it, because the string it looked for
+  // appeared in the stack trace.)
+
+  // `auto` is resolved later per tool by resolveContentModeForTool, so it is
+  // not a content mode and must not go through the normalizer.
+  let contentModeFlag = options.contentMode || 'auto';
+  if (contentModeFlag !== 'auto') {
+    // An unrecognised value is never substituted quietly: a typo that still
+    // produces a normal-looking run is how `--content-mode` would lie about
+    // what it generated. (XSPEC-357 R7) In 6.x it warns and keeps 6.8.0's
+    // result (`index`); it becomes an error in 7.0.0 — see normalizeContentMode.
+    const normalized = normalizeContentMode(contentModeFlag);
+    if (normalized.unrecognized) {
+      console.log(chalk.yellow(
+        `⚠ Unknown content mode '${normalized.unrecognized}'; using '${normalized.mode}'. ` +
+        `Supported: ${SUPPORTED_CONTENT_MODES.join(', ')}. This will be an error in 7.0.0.`
+      ));
+    }
+    if (normalized.migratedFrom) {
+      console.log(chalk.yellow(
+        `⚠ --content-mode ${normalized.migratedFrom} is retired; using '${normalized.mode}'. ` +
+        'The two produced identical files, so nothing about your output changes.'
+      ));
+    }
+    contentModeFlag = normalized.mode;
+  }
   let skillsConfig = {};
+  let skillsInstallationsForYes = [];
 
   if (skillsLocationFlag === 'marketplace') {
     skillsConfig = {
@@ -472,14 +591,39 @@ function buildNonInteractiveConfig(options, detected, projectPath) {
       location = 'project';
     }
 
-    skillsConfig = {
-      installed: true,
-      location,
-      needsInstall: skillsLocationFlag === 'project' || skillsLocationFlag === 'user' || (!userSkillsInfo?.installed && !projectSkillsInfo?.installed),
-      updateTargets: [location],
-      standardsScope: 'minimal',
-      contentMode: contentModeFlag
-    };
+    // 🔴 One installation per skills-capable detected tool, each at that tool's own
+    // path from the table. Without this the config carries only `updateTargets`,
+    // `installSkills()` takes its legacy branch, and every tool's skills land in
+    // `.claude/skills/` — see the block above for what that measured.
+    skillsInstallationsForYes = skillsCapableTools.map(agent => ({ agent, level: location }));
+
+    // 🔴 Detected tools, none of which can take skills, is NOT the same as "no tools
+    // detected". The first is knowledge — install nothing and say why. The second is
+    // ignorance, and there the historical `.claude/skills/` fallback is the least-bad
+    // guess and is kept. Without this split, `--skills-location project` in an
+    // Antigravity-only repo wrote 55 skills into `.claude/skills/`, a directory
+    // nothing in that repo reads. Caught by `check:install-paths`, not by me.
+    const knowinglyUnsupported = skillsCapableTools.length === 0 && aiToolsNormalized.length > 0;
+
+    skillsConfig = knowinglyUnsupported
+      ? {
+          installed: false,
+          location: null,
+          needsInstall: false,
+          updateTargets: [],
+          skillsInstallations: [],
+          standardsScope: 'full',
+          contentMode: contentModeFlag
+        }
+      : {
+          installed: true,
+          location,
+          skillsInstallations: skillsInstallationsForYes,
+          needsInstall: skillsLocationFlag === 'project' || skillsLocationFlag === 'user' || (!userSkillsInfo?.installed && !projectSkillsInfo?.installed),
+          updateTargets: [location],
+          standardsScope: 'minimal',
+          contentMode: contentModeFlag
+        };
   }
 
   // Auto-install commands
@@ -496,6 +640,7 @@ function buildNonInteractiveConfig(options, detected, projectPath) {
   }
 
   skillsConfig.locale = displayLanguageToLocale(displayLanguage);
+  skillsConfig.skillsPathUnknownTools = skippedSkillsTools;
 
   // AGENTS.md: default to true in --yes mode unless codex/opencode selected or --no-agents-md
   // When codex/opencode is selected, they already generate AGENTS.md — no need for universal output
@@ -639,7 +784,7 @@ function displaySummary(config, msg, common) {
   }
 
   // 9. Content Mode (STEP 11)
-  const contentModeLabels = t().contentMode?.labels || { index: 'Standard', full: 'Full', minimal: 'Minimal' };
+  const contentModeLabels = t().contentMode?.labels || { index: 'Standard', minimal: 'Minimal' };
   console.log(chalk.gray(`  ${msg.contentModeLabel}: ${contentModeLabels[config.contentMode] || config.contentMode}`));
 
   // 10. Methodology (STEP 12, experimental)

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' },
-    ],
-  },
 ];
 
 /**