universal-dev-standards 6.8.0 → 6.9.0

package/src/utils/hasher.js

@@ -3,6 +3,7 @@ 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
@@ -240,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
@@ -271,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) {
@@ -284,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

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(

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/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.9.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.9.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.9.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",
@@ -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.9.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.9.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.9.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.9.0",
       "source": {
         "human": "core/resource-cost-boundary.md",
         "ai": "ai/standards/resource-cost-boundary.ai.yaml"