universal-dev-standards 6.9.0 → 6.11.0

package/src/utils/marker-locator.js

@@ -0,0 +1,140 @@
+/**
+ * Shared marker-block location logic for UDS-managed sections in integration
+ * files (CLAUDE.md, AGENTS.md, etc.).
+ *
+ * XSPEC adopter-report Q5 (v3.5.0–6.10.0): every call site that located the
+ * `<!-- UDS:STANDARDS:START -->` / `<!-- UDS:STANDARDS:END -->` pair used
+ * `content.indexOf(markers.start)` / `.indexOf(markers.end)` directly. That
+ * matches the marker text anywhere in the file — including inside a sentence
+ * that merely *mentions* it (this project's own CLAUDE.md explains the marker
+ * syntax in prose, `<!-- UDS:STANDARDS:START -->`, inline) or inside a fenced
+ * code sample quoting it. A write path built on that wrong index then treated
+ * everything between the mention and the real END marker as "the UDS block"
+ * and deleted it — including the user's own content in between.
+ *
+ * The fix: a marker only counts when, after trimming, it occupies an entire
+ * line by itself, and that line is not inside a fenced code block (``` or
+ * ~~~). Every reader of a marker pair in this codebase must go through
+ * `locateMarkerBlock`/`tryLocateMarkerBlock` instead of indexOf/includes —
+ * enforced by a static-scan guard test.
+ */
+
+/**
+ * @typedef {Object} MarkerLine
+ * @property {number} offset - Character offset of the marker text itself
+ *   within `content` (not the start of the line — leading whitespace before
+ *   the marker, if any, is excluded).
+ * @property {number} line - 1-based line number.
+ */
+
+/**
+ * Find every standalone-line, non-fenced-code occurrence of `markerText`.
+ * @param {string} content
+ * @param {string} markerText
+ * @returns {MarkerLine[]}
+ */
+function findMarkerLines(content, markerText) {
+  const lines = content.split('\n');
+  const occurrences = [];
+  let offset = 0;
+  let inFence = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const rawLine = lines[i];
+    const trimmed = rawLine.trim();
+
+    if (/^(`{3,}|~{3,})/.test(trimmed)) {
+      // Fenced code block delimiter (``` or ```lang, closing ``` too) — a
+      // marker string appearing between a pair of these is a documentation
+      // sample, not a real boundary. This intentionally does not try to
+      // distinguish open/close by matching fence characters or length; any
+      // triple-backtick-or-tilde line toggles the state, matching how
+      // Markdown renderers treat fences in practice.
+      inFence = !inFence;
+    } else if (!inFence && trimmed === markerText) {
+      const leading = rawLine.length - rawLine.trimStart().length;
+      occurrences.push({ offset: offset + leading, line: i + 1 });
+    }
+
+    offset += rawLine.length + 1; // +1 for the '\n' that split('\n') consumed
+  }
+
+  return occurrences;
+}
+
+/**
+ * Thrown when a marker's start or end text has more than one standalone,
+ * non-fenced occurrence in a file — the file is ambiguous and no caller
+ * should guess which one is the real boundary.
+ */
+export class AmbiguousMarkerError extends Error {
+  /**
+   * @param {string} markerText
+   * @param {number[]} lines - 1-based line numbers of every occurrence found.
+   */
+  constructor(markerText, lines) {
+    super(
+      `Found ${lines.length} standalone occurrences of marker "${markerText}" ` +
+      `on line(s) ${lines.join(', ')} — expected exactly one. Refusing to guess ` +
+      'which one bounds the UDS-managed block.'
+    );
+    this.name = 'AmbiguousMarkerError';
+    this.markerText = markerText;
+    this.lines = lines;
+  }
+}
+
+/**
+ * Locate the single UDS marker block in `content`.
+ *
+ * @param {string} content
+ * @param {{start: string, end: string}} markers
+ * @returns {{startIdx: number, endIdx: number, startLine: number, endLine: number} | null}
+ *   `null` means "this file has no UDS block" — the same meaning the old
+ *   `startIdx === -1` check carried. This is not an error.
+ * @throws {AmbiguousMarkerError} when more than one valid START or END line
+ *   exists — the file has two or more marker pairs, or a corrupted one.
+ */
+export function locateMarkerBlock(content, markers) {
+  const starts = findMarkerLines(content, markers.start);
+  const ends = findMarkerLines(content, markers.end);
+
+  if (starts.length > 1) {
+    throw new AmbiguousMarkerError(markers.start, starts.map((s) => s.line));
+  }
+  if (ends.length > 1) {
+    throw new AmbiguousMarkerError(markers.end, ends.map((e) => e.line));
+  }
+  if (starts.length === 0 || ends.length === 0) {
+    return null;
+  }
+
+  const startIdx = starts[0].offset;
+  const endIdx = ends[0].offset;
+  if (endIdx <= startIdx) {
+    return null;
+  }
+
+  return { startIdx, endIdx, startLine: starts[0].line, endLine: ends[0].line };
+}
+
+/**
+ * Non-throwing variant of `locateMarkerBlock` for callers that must not
+ * crash a broader scan on one ambiguous file (e.g. a full-project state
+ * scan reconciling many files at once). Ambiguity is reported through the
+ * return value instead of an exception.
+ *
+ * @param {string} content
+ * @param {{start: string, end: string}} markers
+ * @returns {{ok: true, block: ReturnType<typeof locateMarkerBlock>} | {ok: false, error: AmbiguousMarkerError}}
+ */
+export function tryLocateMarkerBlock(content, markers) {
+  try {
+    return { ok: true, block: locateMarkerBlock(content, markers) };
+  } catch (error) {
+    if (error instanceof AmbiguousMarkerError) {
+      return { ok: false, error };
+    }
+    throw error;
+  }
+}

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 };
 }
 
 /**
@@ -242,7 +338,12 @@ export function calculateCategoriesFromStandards(standards) {
   const categories = new Set();
 
   for (const std of standards) {
-    const category = getStandardCategory(std);
+    // XSPEC adopter-report Q1: getStandardCategory is keyed by filename and
+    // returns null for a bare manifest stem ('commit-message'), which is
+    // exactly what a 3.4.0 manifest stores — this emptied the whole category
+    // set on a real install. categoryForStandard (below) tries the stem
+    // against both known extensions first.
+    const category = categoryForStandard(std);
     if (category) {
       categories.add(category);
     }
@@ -251,6 +352,53 @@ export function calculateCategoriesFromStandards(standards) {
   return Array.from(categories);
 }
 
+/**
+ * Whether a stored `categories` array is broken and should not be trusted:
+ * missing/not-an-array, empty, or containing a value this build does not
+ * recognize as a category id.
+ *
+ * @param {*} categories - `manifest.integrationConfigs[file].categories`
+ * @returns {boolean}
+ */
+function categoriesLookBroken(categories) {
+  if (!Array.isArray(categories) || categories.length === 0) return true;
+  const known = new Set(Object.keys(CATEGORY_TO_STANDARDS));
+  return categories.some((c) => !known.has(c));
+}
+
+/**
+ * Repair `manifest.integrationConfigs[file].categories` wherever it is empty
+ * or contains an unrecognized value, recomputing it from `manifest.standards`
+ * the same way `calculateCategoriesFromStandards` (used by `--sync-refs`)
+ * does.
+ *
+ * XSPEC adopter-report Q1 follow-up (main-session review): the original Q1
+ * fix repaired this only inside `--sync-refs`. A manifest that picked up a
+ * broken `categories: []` from an older buggy `--sync-refs` run stayed
+ * broken forever afterward — a plain `uds update` reaches its OWN,
+ * independent integration-sync code path (update.js's general update flow)
+ * which writes `integrationBlockHashes` but never even reads
+ * `integrationConfigs`, so nothing there ever corrected it. The next `uds
+ * check --restore-missing` then rebuilt the file from that broken stored
+ * config and silently dropped sections. Deliberately conservative: an
+ * already-valid (if outdated) categories list is left alone — that is
+ * `--sync-refs`'s job, not every plain `update`'s — this only self-heals
+ * outright corruption (empty or unrecognized values).
+ *
+ * @param {Object} manifest - Manifest object (mutated in place)
+ * @returns {string[]} Paths whose `categories` were repaired
+ */
+export function repairIntegrationConfigCategories(manifest) {
+  if (!manifest?.integrationConfigs) return [];
+  const repaired = [];
+  for (const [file, config] of Object.entries(manifest.integrationConfigs)) {
+    if (!config || !categoriesLookBroken(config.categories)) continue;
+    config.categories = calculateCategoriesFromStandards(manifest.standards || []);
+    repaired.push(file);
+  }
+  return repaired;
+}
+
 /**
  * Get all standard filenames that should be referenced for given categories
  *

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/standards-registry.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "version": "6.9.0",
+  "version": "6.11.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.9.0"
+      "version": "6.11.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.9.0",
+      "version": "6.11.0",
       "note": "Skills are now included in the main repository under skills/"
     }
   },
@@ -1091,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",
@@ -2283,7 +2283,7 @@
       "id": "license-compliance",
       "name": "License Compliance Standards",
       "nameZh": "授權合規標準",
-      "version": "6.9.0",
+      "version": "6.11.0",
       "source": {
         "human": "core/license-compliance.md",
         "ai": "ai/standards/license-compliance.ai.yaml"
@@ -2295,7 +2295,7 @@
       "id": "verification-oracle",
       "name": "Verification Oracle Standards",
       "nameZh": "驗證 Oracle 標準",
-      "version": "6.9.0",
+      "version": "6.11.0",
       "source": {
         "human": "core/verification-oracle.md",
         "ai": "ai/standards/verification-oracle.ai.yaml"
@@ -2307,7 +2307,7 @@
       "id": "model-provenance",
       "name": "Model Provenance Policy Standards",
       "nameZh": "模型來源政策標準",
-      "version": "6.9.0",
+      "version": "6.11.0",
       "source": {
         "human": "core/model-provenance.md",
         "ai": "ai/standards/model-provenance.ai.yaml"
@@ -2319,7 +2319,7 @@
       "id": "resource-cost-boundary",
       "name": "Resource / Cost Boundary Declaration Standards",
       "nameZh": "資源／成本邊界宣告標準",
-      "version": "6.9.0",
+      "version": "6.11.0",
       "source": {
         "human": "core/resource-cost-boundary.md",
         "ai": "ai/standards/resource-cost-boundary.ai.yaml"