universal-dev-standards 6.8.0 → 6.10.0

package/src/utils/reference-sync.js

@@ -1,3 +1,6 @@
+import { existsSync } from 'fs';
+import { join } from 'path';
+
 /**
  * Reference Sync Utilities
  *
@@ -109,6 +112,56 @@ export function parseReferences(content) {
   return Array.from(references);
 }
 
+/**
+ * Every `.standards/…` or `core/…` path mentioned anywhere in the file that is
+ * not on disk.
+ *
+ * `parseReferences` only reads `Reference:`/`參考:` lines, which is the right
+ * scope for reference *sync* — those lines are the ones UDS generates and owns.
+ * It is the wrong scope for "does this instruction point at anything": an older
+ * `uds init` left prose outside the marker block saying "優先讀取 core/ 中的精簡
+ * 規則（例如 core/testing-standards.md）", and on a `format: ai` project no
+ * `core/` directory is ever installed. An AI tool following that finds nothing,
+ * and nothing in the toolchain looked. Reported 2026-09-16.
+ *
+ * Existence-based, not shape-based, and deliberately so: a project that has its
+ * own `core/` directory is not doing anything wrong, and a rule about the shape
+ * of the path could not tell the two apart.
+ *
+ * @param {string} content - File content
+ * @param {string|null} projectPath - Project root; without it there is nothing
+ *   to check against and the answer is "nothing", not a guess
+ * @returns {string[]} Distinct paths that do not resolve, in first-seen order
+ */
+export function findBrokenPathMentions(content, projectPath) {
+  if (!projectPath || typeof content !== 'string') return [];
+
+  // Not preceded by `/` or a word character: that is what keeps
+  // `https://…/core/testing-standards.md` out of the results.
+  //
+  // The terminator class carries the full-width punctuation as well as the
+  // ASCII. These instructions are written in Chinese, and `（例如
+  // core/testing-standards.md）` ends in `）` — without it the path captured is
+  // `core/testing-standards.md）`, which exists nowhere and matches nothing, so
+  // the finding would be real and the path in it wrong.
+  const pattern = /(^|[^\w/\\])((?:\.standards|core)\/[^\s\n)\]`,;'"）】」』〉》，。、；：！？]+)/g;
+  const seen = new Set();
+  const broken = [];
+
+  for (const match of content.matchAll(pattern)) {
+    const cleaned = match[2].replace(/[.,;:!?、，。]+$/, '');
+    if (!cleaned || seen.has(cleaned)) continue;
+    seen.add(cleaned);
+    try {
+      if (!existsSync(join(projectPath, cleaned))) broken.push(cleaned);
+    } catch {
+      // An unreadable path is not evidence of a broken reference.
+    }
+  }
+
+  return broken;
+}
+
 /**
  * Get standard source paths for a category
  *
@@ -176,7 +229,27 @@ function categoryForStandard(pathOrName) {
  *   - missingRefs: Standards in manifest but not referenced in integration file
  *   - syncedRefs: Standards that are properly synced
  */
-export function compareStandardsWithReferences(manifestStandards, integrationReferences) {
+export function compareStandardsWithReferences(manifestStandards, integrationReferences, context = {}) {
+  const { projectPath = null, options = {} } = context;
+
+  // 🔴 Existence is a separate question from adoption, and only one of the two
+  // was ever asked. `.standards/anti-hallucination.md` passed as "synced"
+  // because the manifest adopts `anti-hallucination` — while the project holds
+  // `anti-hallucination.ai.yaml` and the `.md` file is not on disk at all
+  // (reproduced on 6.9.0, 2026-09-16). An adopter's AI tool follows that link
+  // and finds nothing. Without a projectPath there is no disk to ask, so the
+  // list stays empty rather than guessing.
+  const danglingRefs = projectPath
+    ? integrationReferences.filter(ref => !existsSync(join(projectPath, '.standards', ref)))
+    : [];
+
+  // Options are adopted in `manifest.options`, not `manifest.standards`, so
+  // every `.standards/options/...` reference was reported as "not in manifest".
+  const optionStems = new Set(
+    Object.values(options || {})
+      .filter(v => typeof v === 'string')
+      .map(v => standardStem(v))
+  );
   // The manifest is the source of truth for what this project adopted, so ask
   // it directly. The category map below is a hand-written table covering a
   // small fraction of the standards UDS ships (compare its size against
@@ -207,6 +280,10 @@ export function compareStandardsWithReferences(manifestStandards, integrationRef
   // stem (extension- and directory-insensitive) or by legacy category name.
   const orphanedRefs = integrationReferences.filter(ref => {
     if (manifestStems.has(standardStem(ref))) return false;
+    if (optionStems.has(standardStem(ref))) return false;
+    // An option file that is on disk is adopted by definition — it got there
+    // because this project selected it.
+    if (ref.startsWith('options/') && projectPath && existsSync(join(projectPath, '.standards', ref))) return false;
     const category = categoryForStandard(ref);
     return !category || !manifestCategories.has(category);
   });
@@ -221,15 +298,34 @@ export function compareStandardsWithReferences(manifestStandards, integrationRef
   }
   const missingCategories = [...manifestCategories].filter(cat => !refCategories.has(cat));
   // Convert missing categories back to representative filenames for reporting
-  const missingRefs = missingCategories.flatMap(cat => {
-    const paths = CATEGORY_TO_STANDARDS[cat] || [];
-    return paths.map(p => p.split('/').pop());
-  });
+  // 🔴 `CATEGORY_TO_STANDARDS` is a hand-written table of pre-6.0.0 filenames,
+  // so this list named files UDS has not shipped for two majors
+  // (`git-workflow.md`, `error-code-standards.md`, `project-structure.md`).
+  // Report only what this project actually holds. With no projectPath there is
+  // no disk to ask, so the legacy names stand — callers that pass one get the
+  // filtered list.
+  const missingRefs = !projectPath
+    ? missingCategories.flatMap(cat => (CATEGORY_TO_STANDARDS[cat] || []).map(p => p.split('/').pop()))
+    : missingCategories.flatMap(cat => {
+      const paths = CATEGORY_TO_STANDARDS[cat] || [];
+      return paths
+        .map(p => p.split('/').pop())
+        .map(name => {
+          const stem = standardStem(name);
+          for (const candidate of [`${stem}.ai.yaml`, `${stem}.md`]) {
+            if (existsSync(join(projectPath, '.standards', candidate))) return candidate;
+          }
+          return null;
+        })
+        .filter(Boolean);
+    });
 
   // Properly synced references
-  const syncedRefs = integrationReferences.filter(ref => !orphanedRefs.includes(ref));
+  const syncedRefs = integrationReferences.filter(
+    ref => !orphanedRefs.includes(ref) && !danglingRefs.includes(ref)
+  );
 
-  return { orphanedRefs, missingRefs, syncedRefs };
+  return { orphanedRefs, missingRefs, syncedRefs, danglingRefs };
 }
 
 /**
@@ -296,7 +392,10 @@ export function getToolFromPath(integrationPath) {
     '.windsurfrules': 'windsurf',
     '.clinerules': 'cline',
     '.github/copilot-instructions.md': 'copilot',
-    'INSTRUCTIONS.md': 'antigravity',
+    // Antigravity never read INSTRUCTIONS.md.
+    // Measured 2026-09-08 with two positive controls in the same run: tokens planted in `AGENTS.md` and `.agents/AGENTS.md` both came back with correct attribution; the one in INSTRUCTIONS.md did not.
+    // `.agents/AGENTS.md` is used rather than the repo root so it does not collide with Codex/OpenCode, which both target root AGENTS.md.
+    '.agents/AGENTS.md': 'antigravity',
     'CLAUDE.md': 'claude-code',
     '.standards/CLAUDE.md': 'claude-code',
     'AGENTS.md': 'codex'

package/src/utils/registry.js

@@ -320,3 +320,60 @@ export function resolveStandardFilename(entry, format = 'ai') {
   const parts = source.split(/[/\\]/);
   return parts[parts.length - 1] || null;
 }
+
+/**
+ * Every filename UDS can install under `.standards/`, in either format.
+ *
+ * Built by walking the registry: each standard's own source plus every option
+ * choice's source, `ai` and `human` alike. Spanning both formats is deliberate
+ * and is why this takes no format argument — a project can hold a file in a
+ * format it did not install (an upgrade that changed `format`, a hand-copied
+ * file), and calling that "no longer shipped" would be wrong in the opposite
+ * direction. The question here is only ever "is this name still ours".
+ *
+ * This exists so that question has one answer, derived from the registry rather
+ * than from the manifest. A manifest that was never cleaned and one that was
+ * must not disagree about it.
+ *
+ * @returns {Set<string>} Filenames (basenames, no directory)
+ */
+let shippableCache = null;
+export function getShippableFilenames() {
+  if (shippableCache) return shippableCache;
+
+  const out = new Set();
+  const addPath = (value) => {
+    if (typeof value !== 'string' || value.length === 0) return;
+    const parts = value.split(/[/\\]/);
+    const name = parts[parts.length - 1];
+    if (name) out.add(name);
+  };
+  const addSource = (source) => {
+    if (!source) return;
+    if (typeof source === 'string') {
+      addPath(source);
+      return;
+    }
+    for (const value of Object.values(source)) addPath(value);
+  };
+
+  for (const std of getAllStandards()) {
+    addSource(std.source);
+    for (const category of Object.values(std.options || {})) {
+      for (const choice of category.choices || []) addSource(choice.source);
+    }
+  }
+
+  shippableCache = out;
+  return out;
+}
+
+/**
+ * Does UDS still ship a file by this name, in either format?
+ * @param {string} filename - Basename, e.g. `anti-hallucination.ai.yaml`
+ * @returns {boolean}
+ */
+export function isShippedFilename(filename) {
+  if (typeof filename !== 'string' || filename.length === 0) return false;
+  return getShippableFilenames().has(filename);
+}

package/src/utils/spinner.js

@@ -0,0 +1,31 @@
+import ora from 'ora';
+
+/**
+ * A spinner that reports on stdout.
+ *
+ * ora defaults to stderr. For a spinner that redraws over itself while a pipe
+ * consumes stdout, that default is right. It is wrong for this CLI: these lines
+ * are progress reporting for a human, they sit between lines the CLI already
+ * prints on stdout, and in a non-TTY ora emits each one exactly once, so there
+ * is nothing to redraw and nothing to isolate.
+ *
+ * On Windows PowerShell 5.1 the default is worse than untidy. Any stderr output
+ * from a native command is wrapped in a `NativeCommandError`, so a successful
+ * `uds update` surfaced as an error — including the line that said it had
+ * succeeded. Measured on a clean run before this change: 9 lines on stdout, 2 on
+ * stderr, both of them the spinner, one of them `✔ 已重新產生 2 個整合檔案`.
+ *
+ * A caller that genuinely wants stderr can still ask for it; the default is the
+ * only thing that changes.
+ *
+ * @param {string|Object} options - Spinner text, or an ora options object
+ * @returns {import('ora').Ora}
+ */
+export function createSpinner(options) {
+  if (typeof options === 'string') {
+    return ora({ text: options, stream: process.stdout });
+  }
+  return ora({ stream: process.stdout, ...options });
+}
+
+export default createSpinner;

package/src/utils/yaml-generator.js

@@ -4,8 +4,44 @@
  * Generates AI-optimized YAML from parsed Markdown structure.
  */
 
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
 import { SECTION_MAPPINGS, STANDARD_ID_MAPPING } from './conversion-rules.js';
 
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// cli/src/utils/yaml-generator.js -> cli/src/utils -> cli/src -> cli -> repo root
+const REPO_ROOT = resolve(__dirname, '../../..');
+
+/**
+ * XSPEC-392 R2: `meta.updated` must reflect when the source file's content
+ * actually last changed, not a hand-typed `**Last Updated**` line (which can
+ * go stale relative to the file it lives in), and — this is the part that is
+ * not negotiable — never a `new Date()` value standing in for "the day this
+ * script happened to run".
+ *
+ * Returns an ISO date (YYYY-MM-DD) from git history for `relativeSourcePath`,
+ * or `null` when git has no record for it (untracked/new file, git missing,
+ * or any other failure). A missing `updated` field is honest; a fabricated
+ * one is not — so callers must omit the field entirely rather than fall back
+ * to any other date source.
+ */
+function getGitLastModifiedDate(relativeSourcePath) {
+  if (!relativeSourcePath) return null;
+  try {
+    const out = execFileSync(
+      'git',
+      ['log', '-1', '--format=%ad', '--date=short', '--', relativeSourcePath],
+      { cwd: REPO_ROOT, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }
+    ).trim();
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Generate AI-YAML structure from parsed Markdown
  * @param {Object} parsed - Parsed Markdown structure from md-parser
@@ -18,16 +54,22 @@ export function generateAiYaml(parsed, options = {}) {
   // Generate ID
   const id = generateStandardId(filename, parsed.metadata.title);
 
-  // Build YAML structure
-  const yaml = {
-    id,
-    meta: {
-      version: parsed.metadata.version || '1.0.0',
-      updated: parsed.metadata.updated || new Date().toISOString().split('T')[0],
-      source: inferSourcePath(filename, locale),
-      description: parsed.purpose || parsed.metadata.title || ''
-    }
+  const sourcePath = inferSourcePath(filename, locale);
+
+  // Build YAML structure. `updated` is set from git history below, and is
+  // deliberately absent (not null) when git has no record for the file —
+  // see getGitLastModifiedDate.
+  const meta = {
+    version: parsed.metadata.version || '1.0.0'
   };
+  const gitUpdated = getGitLastModifiedDate(sourcePath);
+  if (gitUpdated) {
+    meta.updated = gitUpdated;
+  }
+  meta.source = sourcePath;
+  meta.description = parsed.purpose || parsed.metadata.title || '';
+
+  const yaml = { id, meta };
 
   // Add language if locale specified
   if (locale) {

package/standards-registry.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "version": "6.8.0",
+  "version": "6.10.0",
   "lastUpdated": "2026-05-13",
   "description": "Standards registry for universal-dev-standards with integrated skills and AI-optimized formats",
   "formats": {
@@ -58,14 +58,14 @@
     "standards": {
       "name": "universal-dev-standards",
       "url": "https://github.com/AsiaOstrich/universal-dev-standards",
-      "version": "6.8.0"
+      "version": "6.10.0"
     },
     "skills": {
       "name": "universal-dev-standards",
       "url": "https://github.com/AsiaOstrich/universal-dev-standards",
       "localPath": "skills",
       "rawUrl": "https://raw.githubusercontent.com/AsiaOstrich/universal-dev-standards/main/skills",
-      "version": "6.8.0",
+      "version": "6.10.0",
       "note": "Skills are now included in the main repository under skills/"
     }
   },
@@ -736,6 +736,17 @@
       "category": "core",
       "description": "Four behavioral disciplines for AI agents: Ask (surface assumptions), Simple (minimum code), Precision (scope only what's needed), Test (loop until verified)"
     },
+    {
+      "id": "turn-completion-integrity",
+      "name": "Turn Completion Integrity",
+      "nameZh": "回合收尾完整性標準",
+      "source": {
+        "human": "core/turn-completion-integrity.md",
+        "ai": "ai/standards/turn-completion-integrity.ai.yaml"
+      },
+      "category": "core",
+      "description": "An agent must not end a turn having stated a next action it did not take; enforced at turn end by a Stop hook, with a per-language corpus that runs in CI"
+    },
     {
       "id": "ai-friendly-architecture",
       "name": "AI-Friendly Architecture",
@@ -1080,7 +1091,7 @@
       "name": "Full Coverage Testing Standards",
       "nameZh": "全覆蓋測試標準",
       "source": {
-        "human": "core/testing-standards.md",
+        "human": "core/full-coverage-testing.md",
         "ai": "ai/standards/full-coverage-testing.ai.yaml"
       },
       "category": "skill",
@@ -1569,7 +1580,7 @@
       "id": "antigravity-integration",
       "name": "Google Antigravity Instructions",
       "nameZh": "Google Antigravity 指令",
-      "source": "integrations/google-antigravity/INSTRUCTIONS.md",
+      "source": "integrations/google-antigravity/AGENTS.md",
       "category": "integration",
       "skillName": null,
       "description": "System prompt snippets for Google Antigravity agent",
@@ -1766,6 +1777,18 @@
       "skillName": null,
       "description": "Aim a fix at the set, not the member. Walk the set from the source the system reads, never from a typed list; print the denominator and what was excluded; prove the check non-vacuous per sub-set"
     },
+    {
+      "id": "deferred-item-exit",
+      "name": "Deferred Item Exit Standard",
+      "nameZh": "延後項目出口標準",
+      "source": {
+        "human": "core/deferred-item-exit.md",
+        "ai": "ai/standards/deferred-item-exit.ai.yaml"
+      },
+      "category": "reference",
+      "skillName": null,
+      "description": "A deferred item must leave the document: a traceable exit outside it, identified beside the item. The carrier is deliberately unspecified. A present link is not a working link — verified and unverified links are two states, never one green. Anchor on document structure, not wording"
+    },
     {
       "id": "verification-evidence",
       "name": "Verification Evidence Standard",
@@ -2260,7 +2283,7 @@
       "id": "license-compliance",
       "name": "License Compliance Standards",
       "nameZh": "授權合規標準",
-      "version": "6.8.0",
+      "version": "6.10.0",
       "source": {
         "human": "core/license-compliance.md",
         "ai": "ai/standards/license-compliance.ai.yaml"
@@ -2272,7 +2295,7 @@
       "id": "verification-oracle",
       "name": "Verification Oracle Standards",
       "nameZh": "驗證 Oracle 標準",
-      "version": "6.8.0",
+      "version": "6.10.0",
       "source": {
         "human": "core/verification-oracle.md",
         "ai": "ai/standards/verification-oracle.ai.yaml"
@@ -2284,7 +2307,7 @@
       "id": "model-provenance",
       "name": "Model Provenance Policy Standards",
       "nameZh": "模型來源政策標準",
-      "version": "6.8.0",
+      "version": "6.10.0",
       "source": {
         "human": "core/model-provenance.md",
         "ai": "ai/standards/model-provenance.ai.yaml"
@@ -2296,7 +2319,7 @@
       "id": "resource-cost-boundary",
       "name": "Resource / Cost Boundary Declaration Standards",
       "nameZh": "資源／成本邊界宣告標準",
-      "version": "6.8.0",
+      "version": "6.10.0",
       "source": {
         "human": "core/resource-cost-boundary.md",
         "ai": "ai/standards/resource-cost-boundary.ai.yaml"