universal-dev-standards 6.7.5 → 6.9.0

package/src/utils/hasher.js

@@ -1,22 +1,76 @@
 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';
+import { isProvenanceEstablished } from '../core/manifest.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.
 
 /**
- * Compute SHA-256 hash for a file
+ * 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, 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;
@@ -187,6 +241,15 @@ function scanDirectory(dirPath, basePath) {
 
 /**
  * Scan for untracked files in .standards/ and integration locations
+ *
+ * ⚠ "Untracked" here means only "absent from `manifest.fileHashes`". It is NOT
+ * an ownership predicate, and must not be used to decide what may be deleted —
+ * that is what it was used for, and it is why a user's hand-written file was
+ * removed without warning (issue #168). Use `planStandardsRemovals` /
+ * `classifyFileOwnership`, which separate "did UDS write this" from "is this
+ * still shipped". This function survives for reporting callers that genuinely
+ * want the hash-table question. (XSPEC-384 R1)
+ *
  * @param {string} projectPath - Project root path
  * @param {Object} manifest - Manifest object
  * @returns {string[]} Array of relative paths to untracked files
@@ -218,7 +281,7 @@ export function scanForUntrackedFiles(projectPath, manifest) {
     '.clinerules',
     '.github/copilot-instructions.md',
     'CLAUDE.md',
-    'INSTRUCTIONS.md'
+    '.agents/AGENTS.md'
   ];
 
   for (const intFile of knownIntegrations) {
@@ -231,6 +294,161 @@ export function scanForUntrackedFiles(projectPath, manifest) {
   return untracked;
 }
 
+/**
+ * The three states a file under `.standards/` can be in. (XSPEC-384 R1)
+ *
+ * `scanForUntrackedFiles` answers a two-state question — in `fileHashes` or
+ * not — and the caller then treated "not" as "not ours, delete it". The world
+ * has a third state: files UDS did write whose manifest record was lost. The
+ * old predicate folded that into the same branch as a user's own file, and the
+ * branch deletes.
+ */
+export const FILE_OWNERSHIP = {
+  /** UDS wrote this file; we may remove it when it stops being shipped. */
+  UDS: 'uds-owned',
+  /** Provenance is complete and does not name this file: it is not ours. */
+  FOREIGN: 'foreign',
+  /** No provenance yet — we cannot tell, so we must not act destructively. */
+  UNKNOWN: 'unknown'
+};
+
+/** Paths that are never candidates for anything, with the reason. */
+const STRUCTURAL_EXCLUSIONS = new Map([
+  ['.standards/manifest.json', 'the manifest itself']
+]);
+
+/**
+ * Decide who owns one file under `.standards/`.
+ *
+ * @param {string} relPath - Path relative to project root (forward slashes)
+ * @param {Object} manifest - Manifest object
+ * @returns {string} One of FILE_OWNERSHIP
+ */
+export function classifyFileOwnership(relPath, manifest) {
+  const normalized = (relPath || '').replace(/\\/g, '/');
+  const provenanceFiles = manifest?.provenance?.files;
+  if (provenanceFiles && Object.prototype.hasOwnProperty.call(provenanceFiles, normalized)) {
+    return FILE_OWNERSHIP.UDS;
+  }
+  // Pre-provenance evidence. A path in `fileHashes` got there because UDS put
+  // it there, so it is still proof of authorship — just weaker proof, since it
+  // is also the table that loses entries. Reading it here (rather than only
+  // reading provenance) is what keeps the first upgrade from disowning every
+  // file installed before provenance existed.
+  if (manifest?.fileHashes && Object.prototype.hasOwnProperty.call(manifest.fileHashes, normalized)) {
+    return FILE_OWNERSHIP.UDS;
+  }
+  // No record either way. Whether that means "not ours" depends entirely on
+  // whether our records are complete yet.
+  return isProvenanceEstablished(manifest) ? FILE_OWNERSHIP.FOREIGN : FILE_OWNERSHIP.UNKNOWN;
+}
+
+/**
+ * Walk `.standards/` and classify everything in it.
+ *
+ * A walk, not a list of expected names: `.standards/` is an open set — UDS's
+ * own docs invite teams to add project-specific files to it — so any
+ * enumeration of "files we know about" is stale the moment someone adds one,
+ * and being absent from that enumeration is precisely what used to get a file
+ * deleted. (XSPEC-384 R1)
+ *
+ * @param {string} projectPath - Project root path
+ * @param {Object} manifest - Manifest object
+ * @returns {{scanned:number, excluded:Array, udsOwned:string[], foreign:string[], unknown:string[]}}
+ */
+export function classifyStandardsFiles(projectPath, manifest) {
+  const result = { scanned: 0, excluded: [], udsOwned: [], foreign: [], unknown: [] };
+
+  const standardsDir = join(projectPath, '.standards');
+  if (!existsSync(standardsDir)) return result;
+
+  for (const relPath of scanDirectory(standardsDir, projectPath)) {
+    const normalized = relPath.replace(/\\/g, '/');
+    result.scanned++;
+
+    const exclusionReason = STRUCTURAL_EXCLUSIONS.get(normalized);
+    if (exclusionReason) {
+      result.excluded.push({ path: normalized, reason: exclusionReason });
+      continue;
+    }
+
+    switch (classifyFileOwnership(normalized, manifest)) {
+      case FILE_OWNERSHIP.UDS:
+        result.udsOwned.push(normalized);
+        break;
+      case FILE_OWNERSHIP.FOREIGN:
+        result.foreign.push(normalized);
+        break;
+      default:
+        result.unknown.push(normalized);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Decide which files under `.standards/` `uds update` may delete.
+ *
+ * Deletion now needs two independent facts to line up, one per axis:
+ *
+ *   1. UDS wrote the file  (ownership — provenance, or a legacy `fileHashes`
+ *      entry as weaker evidence of the same thing)
+ *   2. UDS no longer ships it  (currency — absence from `desiredFiles`, which
+ *      the caller derives from the registry it just resolved)
+ *
+ * Every other combination is kept, and says why it was kept. The old rule
+ * collapsed both axes onto `fileHashes` membership, so it deleted files it had
+ * never written (#168) while retaining files it no longer shipped (#165).
+ *
+ * Nothing is removed when `desiredFiles` is null: a caller that cannot say what
+ * should exist has not established fact 2, and "I don't know" must not resolve
+ * to the destructive branch — that was the original defect.
+ *
+ * @param {string} projectPath - Project root path
+ * @param {Object} manifest - Manifest object
+ * @param {Set<string>|null} desiredFiles - Files the current registry says should exist
+ * @returns {{scanned:number, excluded:Array, remove:Array, keep:Array, census:Object}}
+ */
+export function planStandardsRemovals(projectPath, manifest, desiredFiles = null) {
+  const census = classifyStandardsFiles(projectPath, manifest);
+  const remove = [];
+  const keep = [];
+
+  const desiredKnown = desiredFiles instanceof Set;
+
+  for (const path of census.udsOwned) {
+    if (!desiredKnown) {
+      keep.push({ path, reason: 'UDS-owned, but this run could not determine what is still shipped' });
+    } else if (desiredFiles.has(path)) {
+      keep.push({ path, reason: 'UDS-owned and still shipped' });
+    } else {
+      remove.push({ path, reason: 'UDS-owned and no longer shipped by the registry' });
+    }
+  }
+
+  for (const path of census.foreign) {
+    keep.push({ path, reason: 'not written by UDS' });
+  }
+
+  for (const path of census.unknown) {
+    keep.push({ path, reason: 'ownership unknown (manifest predates provenance)' });
+  }
+
+  return {
+    scanned: census.scanned,
+    excluded: census.excluded,
+    remove,
+    keep,
+    census: {
+      udsOwned: census.udsOwned.length,
+      foreign: census.foreign.length,
+      unknown: census.unknown.length,
+      desired: desiredKnown ? desiredFiles.size : null
+    }
+  };
+}
+
 /**
  * Detect file format based on file path
  * @param {string} filePath - File path
@@ -276,7 +494,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 +508,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/hook-stats.js

@@ -1,7 +1,7 @@
 /**
  * Hook Statistics - Context-aware loading learning loop
  *
- * Records and analyzes trigger statistics from inject-standards.js hook.
+ * Records and analyzes trigger statistics from inject-standards.mjs hook.
  * Privacy: never records full prompt content or file paths.
  *
  * @module utils/hook-stats

package/src/utils/integration-generator.js

@@ -32,7 +32,10 @@ export function resolveContentModeForTool(tool, userContentMode) {
         ? { contentMode: 'minimal', level: 3 }
         : { contentMode: 'index', level: 2 };
     case 'partial':
-      return { contentMode: 'full', level: 1 };
+      // Was 'full'. Every partial-tier tool was being auto-assigned a mode
+      // that generated exactly the same bytes as 'index', so this is a rename
+      // of what these tools already got, not a change to it. (XSPEC-357 R7)
+      return { contentMode: 'index', level: 1 };
     case 'preview':
       return { contentMode: 'index', level: 2 };
     case 'minimal':
@@ -70,6 +73,31 @@ function getToolFileName(tool) {
   if (KNOWN_TOOL_FILES.has(tool) || /\.(md|yaml|yml|json)$/i.test(tool)) {
     return tool;
   }
+
+  // 🔴 A tool THIS system already knows, missing from THIS table, is an internal
+  // inconsistency — never a future tool. It must fail rather than get a generated
+  // filename.
+  //
+  // Measured 2026-09-08: `roo-code` is the key used by `ai-agent-paths.js`,
+  // `REGISTRY.json`, `agent-adapter.js` and `agents-installer.js`, while
+  // `SUPPORTED_AI_TOOLS` said `roo`. Every lookup here missed and fell through, so a
+  // real `uds init` in a Roo Code repo wrote its instructions to `roo-code.md` — a
+  // filename Roo Code's docs never mention. Nothing failed. Nothing warned. Same
+  // class as `.codex/skills/`, which this repo's own comments call "a directory UDS
+  // invented"; the line below was a *rule* for inventing them.
+  //
+  // ⚠️ The fallback itself is KEPT, because it is a deliberate design decision, not
+  // an accident: three tests assert it as "forward compatibility with future tools".
+  // Narrowing beats reversing — a genuinely unknown name still gets `<name>.md`; only
+  // the self-contradiction fails.
+  if (getAgentConfig(normalizedName)) {
+    throw new Error(
+      `getToolFileName: "${tool}" is a known agent in ai-agent-paths.js but is missing ` +
+      'from SUPPORTED_AI_TOOLS in cli/src/core/constants.js. Add it with the file that ' +
+      `tool actually reads. Refusing to invent "${tool}.md" — that is how a Roo Code ` +
+      'repo got its instructions written to a file Roo Code never reads.'
+    );
+  }
   return `${tool}.md`;
 }
 
@@ -2398,6 +2426,52 @@ All responses should be in **Traditional Chinese (繁體中文)**, with technica
   }
 };
 
+/**
+ * Generate the index disclosure that opens every UDS-managed block.
+ *
+ * XSPEC-357 R7 — the block an adopter receives is an index. In no content mode
+ * does it carry rule bodies, and inlining them is not an option: 143 `.ai.yaml`
+ * files come to roughly 248k tokens. What can be fixed is the block pretending
+ * otherwise. A file that lists 72 standard paths under a heading reading
+ * "Standards Compliance Instructions" reads, to an agent, like the compliance
+ * instructions — and Codex was measured on 2026-07-23 doing exactly that:
+ * it enumerated the standards and opened none of them.
+ *
+ * This wording was added to the universal `AGENTS.md` summary on 2026-08-18
+ * (`generateAgentsMdSummary`). That fixed one of the two producers. The other
+ * one is this — and the split is worse than it sounds, because the two are
+ * mutually exclusive for the same filename: selecting codex or opencode turns
+ * the universal summary OFF and routes `AGENTS.md` through here instead. The
+ * disclosure written for Codex was therefore in the only file a Codex adopter
+ * never receives. Measured 2026-08-20 before this change: 8 distinct adopter
+ * files across 3 content modes, 0 carrying the disclosure.
+ *
+ * @param {string} format - Output format: 'markdown' or 'plaintext'
+ * @param {string} language - Language: 'en', 'zh-tw', 'zh-cn' or 'bilingual'
+ * @returns {string} Disclosure paragraph, already format-adjusted
+ */
+export function generateIndexDisclosure(format, language = 'en') {
+  const lines = language === 'en'
+    ? [
+      '**This block is an index, not the standards.** The rules are NOT reproduced here.',
+      'Before acting on anything below, open the relevant file under `.standards/` and',
+      'follow its contents. Working from this block alone means working without the',
+      'standards.'
+    ]
+    : [
+      '**這個區塊是索引，不是標準本文。** 規則並未複製於此。',
+      '在依照下方任何一項行動之前，請打開 `.standards/` 底下對應的檔案並遵守其內容。',
+      '只憑這個區塊工作，等同於沒有採用標準。'
+    ];
+
+  if (format === 'markdown') {
+    return lines.map((l) => `> ${l}`).join('\n');
+  }
+  // Plaintext targets (.cursorrules / .clinerules / .windsurfrules) render
+  // neither blockquotes nor backticks, so both are stripped rather than shown.
+  return lines.map((l) => l.replace(/\*\*/g, '').replace(/`/g, '')).join('\n');
+}
+
 /**
  * Generate minimal standards reference for minimal content mode
  * @param {string[]} installedStandards - List of installed standard file paths
@@ -2733,6 +2807,10 @@ export function generateIntegrationContent(config) {
     }
 
     if (installedStandards.length > 0) {
+      // XSPEC-357 R7 — every mode, every tool. Placed first because it is a
+      // precondition for reading the rest, not a footnote to it.
+      standardsContent = generateIndexDisclosure(format, language) + '\n\n' + standardsContent;
+
       if (contentMode === 'minimal') {
         // Minimal mode: simple reference list
         standardsContent += generateMinimalStandardsReference(
@@ -3181,8 +3259,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 +3440,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)

package/src/utils/reference-sync.js

@@ -296,7 +296,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/skills-installer.js

@@ -19,7 +19,7 @@ import {
   getCommandsSupportedAgents,
   getCommandFileExtension
 } from '../config/ai-agent-paths.js';
-import { computeDirectoryHashes, computeFileHash } from './hasher.js';
+import { computeDirectoryHashes, computeFileHash, normalizeLineEndings } from './hasher.js';
 import { isLocalizedLocale } from './locale.js';
 import { getSkillsSourceDir } from './skills-source.js';
 
@@ -504,6 +504,16 @@ export function resolveSkillFiles(skillName, locale = 'en') {
  * are different installs, and a hash over contents alone would call a rename
  * "unchanged".
  *
+ * Content is line-ending normalized before hashing (GitHub issue #155): the
+ * counterpart on the actual-state side, `hashInstalledSkillDir` in
+ * `reconciler/actual-state-scanner.js`, hashes files that were checked out
+ * into the adopter's own repo and so may have been rewritten to CRLF by
+ * `core.autocrlf=true` on Windows. Both sides must apply the same
+ * normalization or every skill would report as changed on Windows, same as
+ * the `.standards/*` hashes this issue was filed about — the two functions
+ * only stay comparable by construction if they agree on this too, which is
+ * why the paired tests in `skill-content-hash.test.js` exist.
+ *
  * @param {Array<{name: string, content: string}>} files
  * @returns {string|null} `sha256:<hex>`, or null for an empty resolution
  */
@@ -513,7 +523,7 @@ export function computeSkillContentHash(files) {
   for (const f of files) {
     h.update(f.name);
     h.update('\0');
-    h.update(f.content);
+    h.update(normalizeLineEndings(f.content));
     h.update('\0');
   }
   return `sha256:${h.digest('hex')}`;
@@ -779,13 +789,17 @@ export function resolveCommandContent(cmdName, agent, locale = 'en') {
  *
  * Same `sha256:` shape as `computeSkillContentHash` so the two sides of the
  * diff can be compared without caring which category an entry came from.
+ * Line-ending normalized before hashing for the same reason as
+ * `computeSkillContentHash` (GitHub issue #155) — its actual-state
+ * counterpart in `reconciler/actual-state-scanner.js` hashes an installed
+ * command file that may have been checked out as CRLF on Windows.
  *
  * @param {string|null} content
  * @returns {string|null}
  */
 export function computeCommandContentHash(content) {
   if (content === null || content === undefined) return null;
-  return `sha256:${createHash('sha256').update(content).digest('hex')}`;
+  return `sha256:${createHash('sha256').update(normalizeLineEndings(content)).digest('hex')}`;
 }
 
 function installSingleCommand(cmdName, targetDir, agent, locale = 'en') {

package/src/utils/spec-linter.js

@@ -2,6 +2,22 @@
  * Spec Linter — Stateless analysis functions for spec quality checks
  * @module utils/spec-linter
  * @see specs/superspec-borrowing-phase1-2-spec.md (AC-11, AC-12, AC-13)
+ *
+ * XSPEC-383 R5 (Option E): `checkACCoverage` / `collectTestFiles` / `scanDir`
+ * were removed here. They shipped 2026-04-07, had passing unit tests, and were
+ * never wired to any CLI command — `uds lint` did not exist. 2026-08-19,
+ * registering `uds lint` and running it against VibeOps's 93 real specs
+ * surfaced that the removed check would have reported 0/98 ACs covered on
+ * every one of them, for two independent reasons: it derived AC identifiers
+ * positionally (`AC-1`, `AC-2`, …) instead of reading the ones a spec
+ * declares, and it hardcoded the `@AC-N` tag convention from this repo's own
+ * `skills/ac-coverage`, while VibeOps's tests tag coverage as `AC-045-001`
+ * without an `@` prefix. Neither project is "wrong" — they never agreed on a
+ * convention — but a linter that always reports zero regardless of actual
+ * coverage is worse than no linter: it looks like a working gate. Redoing AC
+ * coverage requires deciding how identifiers are read and how conventions are
+ * negotiated across adopters; that is a new design, not a patch, and is out
+ * of scope for R5.
  */
 
 import { readFileSync, readdirSync, existsSync } from 'fs';
@@ -9,35 +25,6 @@ import { join, basename } from 'path';
 import { StandardValidator } from './standard-validator.js';
 import { MicroSpec } from '../vibe/micro-spec.js';
 
-/**
- * Check if a spec's ACs are referenced in test files
- * @param {string} specId - e.g. "SPEC-001"
- * @param {string[]} acIds - e.g. ["AC-1", "AC-2", "AC-3"]
- * @param {string} projectPath - Project root directory
- * @returns {{ covered: string[], orphans: string[], coverage: number }}
- */
-export function checkACCoverage(specId, acIds, projectPath) {
-  const covered = [];
-  const orphans = [];
-
-  // Collect all test file contents
-  const testContent = collectTestFiles(projectPath);
-
-  for (const acId of acIds) {
-    // Search for @AC-N pattern in test files
-    const pattern = new RegExp(`@${acId}\\b`);
-    if (testContent.some(content => pattern.test(content))) {
-      covered.push(acId);
-    } else {
-      orphans.push(acId);
-    }
-  }
-
-  const coverage = acIds.length > 0 ? covered.length / acIds.length : 0;
-
-  return { covered, orphans, coverage };
-}
-
 /**
  * Validate depends_on references exist
  * @param {Object[]} specs - Array of specs with { id, dependsOn }
@@ -75,14 +62,22 @@ export function checkSpecSize(specFilePath, options = {}) {
 }
 
 /**
- * Run all lint checks on specs in a project
+ * Run all lint checks (dependency validity + size) on specs in a project.
+ *
+ * `specsDirExists` is a three-state signal, not decoration: "no specs
+ * directory" and "specs directory with zero problems" must not collapse into
+ * the same `{ pass: 0, warn: 0, fail: 0 }` shape, or a caller cannot tell
+ * "nothing was checked" from "everything is fine" (XSPEC-383 R4/R5's own
+ * standing rule for this repo's gates — see check-module-reachability.mjs and
+ * check-command-existence.mjs).
+ *
  * @param {string} projectPath - Project root directory
- * @returns {{ results: Object[], summary: { pass: number, warn: number, fail: number } }}
+ * @returns {{ results: Object[], summary: { pass: number, warn: number, fail: number }, specsDir: string, specsDirExists: boolean }}
  */
 export function lintAll(projectPath) {
   const specsDir = join(projectPath, 'specs');
   if (!existsSync(specsDir)) {
-    return { results: [], summary: { pass: 0, warn: 0, fail: 0 } };
+    return { results: [], summary: { pass: 0, warn: 0, fail: 0 }, specsDir: 'specs', specsDirExists: false };
   }
 
   // Load all specs
@@ -102,10 +97,6 @@ export function lintAll(projectPath) {
   const summary = { pass: 0, warn: 0, fail: 0 };
 
   for (const spec of allSpecs) {
-    // AC coverage
-    const acIds = (spec.acceptance || []).map((_, i) => `AC-${i + 1}`);
-    const acCoverage = checkACCoverage(spec.id, acIds, projectPath);
-
     // Dependencies for this spec
     const specBroken = depResults.broken.filter(b => b.spec === spec.id);
     const specValid = depResults.valid.filter(v => v.spec === spec.id);
@@ -116,22 +107,18 @@ export function lintAll(projectPath) {
     const size = checkSpecSize(specPath);
 
     // Determine worst status
-    let worstStatus = 'pass';
-    if (specBroken.length > 0 || size.status === 'fail' || acCoverage.coverage === 0 && acIds.length > 0) {
-      worstStatus = 'fail';
-    } else if (size.status === 'warn' || acCoverage.coverage < 1) {
-      worstStatus = 'warn';
+    let status = 'pass';
+    if (specBroken.length > 0 || size.status === 'fail') {
+      status = 'fail';
+    } else if (size.status === 'warn') {
+      status = 'warn';
     }
 
-    summary[worstStatus]++;
+    summary[status]++;
 
     results.push({
       spec: spec.id,
-      acCoverage: {
-        covered: acCoverage.covered,
-        orphans: acCoverage.orphans,
-        coverage: acCoverage.coverage,
-      },
+      status,
       deps,
       size: {
         effectiveLines: size.effectiveLines,
@@ -140,33 +127,5 @@ export function lintAll(projectPath) {
     });
   }
 
-  return { results, summary };
-}
-
-// ─── Internal helpers ───
-
-function collectTestFiles(projectPath) {
-  const contents = [];
-  const testDirs = ['tests', 'test', '__tests__', 'cli/tests'];
-
-  for (const dir of testDirs) {
-    const fullDir = join(projectPath, dir);
-    if (existsSync(fullDir)) {
-      scanDir(fullDir, contents);
-    }
-  }
-
-  return contents;
-}
-
-function scanDir(dir, contents) {
-  const entries = readdirSync(dir, { withFileTypes: true });
-  for (const entry of entries) {
-    const fullPath = join(dir, entry.name);
-    if (entry.isDirectory()) {
-      scanDir(fullPath, contents);
-    } else if (entry.name.match(/\.(test|spec)\.(js|ts|mjs|cjs)$/)) {
-      contents.push(readFileSync(fullPath, 'utf-8'));
-    }
-  }
+  return { results, summary, specsDir: 'specs', specsDirExists: true };
 }