universal-dev-standards 6.8.0 → 6.9.0

package/src/core/manifest.js

@@ -55,6 +55,62 @@ export const DEFAULT_MANIFEST = {
   integrationBlockHashes: {}
 };
 
+/**
+ * Content modes an adopter may choose.
+ *
+ * `full` was retired in favour of `index` (XSPEC-357 R7). It was never a third
+ * behaviour: the only place the mode is read is a single `=== 'minimal'` test
+ * in `generateComplianceInstructions`, so `full` and `index` took the same
+ * branch and produced byte-identical files — 24 of 24 tool × language
+ * combinations, against a control confirming the comparison does detect a real
+ * difference (`full` vs `minimal` differed in all 24). Meanwhile the manifest
+ * schema accepted it, `--content-mode` offered it, the init prompt listed it as
+ * a distinct trade-off ("highest compliance, uses more context"), and every
+ * `partial`-tier tool was assigned it automatically. Adopters were choosing
+ * between two labels for one behaviour, and the label promised a difference
+ * that did not exist.
+ */
+export const SUPPORTED_CONTENT_MODES = ['minimal', 'index'];
+
+/**
+ * Retired content modes and what they now resolve to.
+ *
+ * The rewrite changes no adopter's output, because the two modes already
+ * generated the same bytes — which is what makes this breaking change cheap
+ * enough to do at all. Kept as a map rather than special-cased at each call
+ * site so the next retirement has somewhere to go.
+ */
+export const RETIRED_CONTENT_MODES = { full: 'index' };
+
+/**
+ * Resolve a content mode, migrating retired ones and flagging unknown ones.
+ *
+ * An unknown value resolves to `fallback` and is reported in `unrecognized`, so
+ * the caller can warn. The original intent was to throw — a *silent* fallback
+ * turns `--content-mode indx` into a normal run with nothing saying so — and
+ * that remains the goal for 7.0.0. It does not throw in 6.x because 6.8.0
+ * accepted unknown values and generated the `index` output, and
+ * `core/versioning.md` requires a deprecation warning in a MINOR release before
+ * behaviour that used to work starts failing. The warning is what removes the
+ * silence; the error is the MAJOR-version step.
+ *
+ * @param {string|undefined} mode - Requested mode
+ * @param {string} fallback - Mode to use when nothing was requested, or when the value is unknown
+ * @returns {{mode: string, migratedFrom: string|null, unrecognized: string|null}}
+ */
+export function normalizeContentMode(mode, fallback = 'index') {
+  if (mode === undefined || mode === null || mode === '') {
+    return { mode: fallback, migratedFrom: null, unrecognized: null };
+  }
+  if (SUPPORTED_CONTENT_MODES.includes(mode)) {
+    return { mode, migratedFrom: null, unrecognized: null };
+  }
+  if (Object.prototype.hasOwnProperty.call(RETIRED_CONTENT_MODES, mode)) {
+    return { mode: RETIRED_CONTENT_MODES[mode], migratedFrom: mode, unrecognized: null };
+  }
+  return { mode: fallback, migratedFrom: null, unrecognized: mode };
+}
+
 /**
  * Validation schema for manifest
  */
@@ -63,10 +119,125 @@ const MANIFEST_SCHEMA = {
   properties: {
     version: { type: 'string', pattern: '^\\d+\\.\\d+\\.\\d+$' },
     format: { type: 'string', enum: ['ai', 'human', 'both'] },
-    contentMode: { type: 'string', enum: ['minimal', 'index', 'full'] }
+    contentMode: { type: 'string', enum: SUPPORTED_CONTENT_MODES }
   }
 };
 
+/**
+ * Provenance — the record of which files UDS itself wrote. (XSPEC-384 R1)
+ *
+ * Ownership is a question about *origin*, and origin is something you record at
+ * the moment you write, not something you infer afterwards from another table.
+ * `fileHashes` was doing the inferring: absence from it was read as "not ours",
+ * although a manifest loses entries through version migrations, hand edits,
+ * merge conflicts, and older CLI bugs. The tool then picked the destructive
+ * branch for the case it could not actually distinguish.
+ *
+ * Two properties matter and neither is shared with `fileHashes`:
+ *
+ *  - It is append-only. `fileHashes` is current state and gets rewritten every
+ *    run; provenance is history. If both were written and pruned together,
+ *    provenance would add nothing — it would just be a second copy that fails
+ *    the same way at the same moment.
+ *  - It is keyed by the path actually written, taken from the copy result,
+ *    not by re-deriving the path from the source name. The re-derivation is
+ *    wrong for nested option files (`options/<category>/<name>.ai.yaml` is
+ *    flattened to `options/<name>.ai.yaml`), so a path-math-based record would
+ *    claim ownership of files that do not exist while disowning ones that do.
+ *
+ * An entry is removed only when UDS deliberately deletes the file — deleting it
+ * is how we relinquish the claim, so that a file a user later creates under the
+ * same name is not silently inherited.
+ */
+export const PROVENANCE_SCHEMA_VERSION = 1;
+
+/**
+ * Valid writers, used so a typo becomes an error rather than an unrecognised
+ * provenance record that reads as "not ours".
+ */
+export const PROVENANCE_WRITERS = ['init', 'update', 'config', 'sync'];
+
+/**
+ * Record that UDS wrote a file.
+ * @param {Object} manifest - Manifest (not mutated)
+ * @param {string} relPath - Path relative to project root
+ * @param {string} writer - One of PROVENANCE_WRITERS
+ * @returns {Object} Updated manifest
+ */
+export function recordFileProvenance(manifest, relPath, writer) {
+  if (!relPath) return manifest;
+  const normalized = relPath.replace(/\\/g, '/');
+  const at = new Date().toISOString();
+  const existing = manifest?.provenance?.files?.[normalized];
+  return {
+    ...manifest,
+    provenance: {
+      schema: PROVENANCE_SCHEMA_VERSION,
+      ...(manifest?.provenance || {}),
+      files: {
+        ...(manifest?.provenance?.files || {}),
+        [normalized]: {
+          firstWrittenBy: existing?.firstWrittenBy || writer,
+          firstWrittenAt: existing?.firstWrittenAt || at,
+          lastWrittenBy: writer,
+          lastWrittenAt: at
+        }
+      }
+    }
+  };
+}
+
+/**
+ * Drop a provenance record, relinquishing UDS's claim on a path.
+ * @param {Object} manifest - Manifest (not mutated)
+ * @param {string} relPath - Path relative to project root
+ * @returns {Object} Updated manifest
+ */
+export function forgetFileProvenance(manifest, relPath) {
+  const normalized = (relPath || '').replace(/\\/g, '/');
+  const files = { ...(manifest?.provenance?.files || {}) };
+  delete files[normalized];
+  return {
+    ...manifest,
+    provenance: {
+      schema: PROVENANCE_SCHEMA_VERSION,
+      ...(manifest?.provenance || {}),
+      files
+    }
+  };
+}
+
+/**
+ * Mark provenance as a complete account of what UDS owns.
+ *
+ * Called at the end of a run that wrote the full installed set. Until this has
+ * happened at least once, a file with no provenance record is `unknown` rather
+ * than `foreign`, because the absence of a record proves nothing yet.
+ *
+ * @param {Object} manifest - Manifest (not mutated)
+ * @returns {Object} Updated manifest
+ */
+export function establishProvenance(manifest) {
+  return {
+    ...manifest,
+    provenance: {
+      schema: PROVENANCE_SCHEMA_VERSION,
+      files: {},
+      ...(manifest?.provenance || {}),
+      establishedAt: manifest?.provenance?.establishedAt || new Date().toISOString()
+    }
+  };
+}
+
+/**
+ * Whether provenance can be trusted as a complete list of UDS-owned files.
+ * @param {Object} manifest - Manifest
+ * @returns {boolean}
+ */
+export function isProvenanceEstablished(manifest) {
+  return !!manifest?.provenance?.establishedAt;
+}
+
 /**
  * Get manifest file path for a project
  * @param {string} projectPath - Project root path
@@ -354,10 +525,25 @@ function migrateToV320(manifest) {
   return {
     ...manifest,
     version: '3.2.0',
-    contentMode: manifest.contentMode || 'index'
+    contentMode: migrateRetiredContentMode(manifest.contentMode)
   };
 }
 
+/**
+ * Rewrite a retired content mode to its replacement, leaving anything else
+ * alone. Unlike `normalizeContentMode` this never throws: it runs while reading
+ * a manifest, and refusing to load a project because of one stale string would
+ * be a worse outcome than loading it and letting `validateManifest` report.
+ * @param {string|undefined} mode
+ * @returns {string}
+ */
+function migrateRetiredContentMode(mode) {
+  if (mode && Object.prototype.hasOwnProperty.call(RETIRED_CONTENT_MODES, mode)) {
+    return RETIRED_CONTENT_MODES[mode];
+  }
+  return mode || 'index';
+}
+
 /**
  * Migration to version 3.3.0
  * @param {Object} manifest - V3.2.x manifest
@@ -502,11 +688,23 @@ function ensureRequiredFields(manifest) {
     ...manifest,
     options,
     standards,
-    contentMode: manifest.contentMode || 'index',
+    // Rewrites a stored `full` to `index`. This is the migration path for
+    // existing adopters and it runs on every read, so a manifest written by an
+    // older CLI is corrected the first time a newer one touches it — without
+    // changing a single byte of what that project's AI tool files receive.
+    contentMode: migrateRetiredContentMode(manifest.contentMode),
     fileHashes: normalizedHashes,
     skillHashes: manifest.skillHashes || {},
     commandHashes: manifest.commandHashes || {},
     integrationBlockHashes: manifest.integrationBlockHashes || {},
+    // Present but deliberately NOT established. Filling in `establishedAt`
+    // here would declare "these records are complete" about a manifest that
+    // has never had a provenance-aware run, which is the one claim that turns
+    // every pre-existing file into `foreign` — and `foreign` is the state the
+    // deletion path acts on. Only a completed run may establish it.
+    // A fresh object per call: a shared default would be one mutable record
+    // handed to every manifest in the process. (XSPEC-384 R1)
+    provenance: manifest.provenance || { schema: PROVENANCE_SCHEMA_VERSION, files: {} },
   };
 }
 

package/src/core/paths.js

@@ -149,8 +149,8 @@ export class PathResolver {
       'copilot': 'copilot-instructions.md',
       'aider': '.aider.conf.yml',
       'opencode': 'AGENTS.md',
-      'roo': 'ROO.md',
-      'antigravity': 'INSTRUCTIONS.md'
+      'roo-code': '.roo/rules/uds-standards.md',
+      'antigravity': '.agents/AGENTS.md'
     };
 
     const targetFile = toolTargets[tool] || fileName;

package/src/i18n/messages.js

@@ -100,12 +100,10 @@ export const messages = {
       question: 'Select content mode:',
       labels: {
         index: 'Standard',
-        full: 'Full Embed',
         minimal: 'Minimal'
       },
       choices: {
         index: 'Summary + task mapping, AI knows when to read which standard',
-        full: 'Embed all rules, AI can use immediately but larger file',
         minimal: 'File references only, best with Skills'
       },
       explanations: {
@@ -114,11 +112,6 @@ export const messages = {
           '  → AI can determine "which standard to read for which task"',
           '  → Balance between context usage and compliance'
         ],
-        full: [
-          '  → All rules embedded in config file (~10-15 KB)',
-          '  → AI needs no extra file reads, highest compliance',
-          '  → Best for short tasks or strict compliance projects'
-        ],
         minimal: [
           '  → Only contains .standards/ file list',
           '  → AI needs to actively read standard files',
@@ -328,7 +321,6 @@ export const messages = {
       warning: 'Changing Content Mode will regenerate all AI tool config files',
       explanations: {
         index: '  → AI will determine when to read standards based on task mapping',
-        full: '  → All rules embedded directly, highest AI compliance',
         minimal: '  → AI must actively read standards, recommend using with Skills'
       }
     },
@@ -934,7 +926,6 @@ export const messages = {
         standardsScopeLean: 'Lean (Skills handle the rest)',
         standardsScopeComplete: 'Complete',
         contentModeLabel: 'Content Mode',
-        contentModeFull: 'Full Embed',
         contentModeIndex: 'Standard (recommended)',
         contentModeMinimal: 'Minimal (core only)',
         displayLanguageLabel: 'Display Language',
@@ -969,7 +960,10 @@ export const messages = {
         generatingAgentsMd: 'Generating AGENTS.md (universal summary)...',
         generatedAgentsMd: 'Generated AGENTS.md (universal summary)',
         couldNotGenerateAgentsMd: 'Could not generate AGENTS.md',
-        installingSkills: 'Installing Claude Code Skills...',
+        installingSkills: 'Installing Skills...',
+        // Named per detected tool, never per one tool: the install now goes to each
+        // tool's own path (XSPEC-408 §18.3), so a Claude-only label would be a lie.
+        skillsPathUnknown: 'no verified skills path for this tool — nothing was installed for it',
         installedSkills: 'Installed {count} Skills to {locations}',
         installedSkillsWithErrors: 'Installed {count} Skills with {errors} errors',
         // P1-CLI-1: locale fallback summary (printed after install when some
@@ -1334,12 +1328,10 @@ export const messages = {
       question: '選擇內容模式：',
       labels: {
         index: '標準',
-        full: '完整嵌入',
         minimal: '最小化'
       },
       choices: {
         index: '摘要 + 任務對照表，AI 知道何時讀哪個規範',
-        full: '完整嵌入所有規則，AI 立即可用但檔案較大',
         minimal: '僅檔案參考，適合搭配 Skills 使用'
       },
       explanations: {
@@ -1348,11 +1340,6 @@ export const messages = {
           '  → AI 能判斷「做什麼任務時要讀哪個規範」',
           '  → 平衡 Context 使用量和合規程度'
         ],
-        full: [
-          '  → 所有規則直接嵌入設定檔（檔案約 10-15 KB）',
-          '  → AI 無需額外讀檔，合規率最高',
-          '  → 適合短期任務或需要嚴格遵循的專案'
-        ],
         minimal: [
           '  → 僅包含 .standards/ 檔案清單',
           '  → AI 需要主動讀取規範檔案',
@@ -1562,7 +1549,6 @@ export const messages = {
       warning: '變更 Content Mode 將重新生成所有 AI 工具設定檔',
       explanations: {
         index: '  → AI 會根據任務對照表判斷何時讀取規範',
-        full: '  → 所有規則直接嵌入，AI 合規率最高',
         minimal: '  → AI 需主動讀取規範，建議搭配 Skills'
       }
     },
@@ -2168,7 +2154,6 @@ export const messages = {
         standardsScopeLean: '精簡（Skills 處理其餘）',
         standardsScopeComplete: '完整',
         contentModeLabel: '內容模式',
-        contentModeFull: '完整嵌入',
         contentModeIndex: '標準（推薦）',
         contentModeMinimal: '最小（僅核心）',
         displayLanguageLabel: '顯示語言',
@@ -2203,7 +2188,8 @@ export const messages = {
         generatingAgentsMd: '產生 AGENTS.md（通用摘要）中...',
         generatedAgentsMd: '已產生 AGENTS.md（通用摘要）',
         couldNotGenerateAgentsMd: '無法產生 AGENTS.md',
-        installingSkills: '安裝 Claude Code Skills 中...',
+        installingSkills: '安裝 Skills 中...',
+        skillsPathUnknown: '沒有查證過的 skills 路徑，這個工具沒有安裝任何東西',
         installedSkills: '已安裝 {count} 個 Skills 到 {locations}',
         installedSkillsWithErrors: '已安裝 {count} 個 Skills，有 {errors} 個錯誤',
         // P1-CLI-1：locale fallback 摘要（安裝結束後顯示，列出沒有對應語系變體而退回英文來源的 skill）
@@ -2567,12 +2553,10 @@ export const messages = {
       question: '选择内容模式：',
       labels: {
         index: '标准',
-        full: '完整嵌入',
         minimal: '最小化'
       },
       choices: {
         index: '摘要 + 任务对照表，AI 知道何时读哪个规范',
-        full: '完整嵌入所有规则，AI 立即可用但文件较大',
         minimal: '仅文件参考，适合搭配 Skills 使用'
       },
       explanations: {
@@ -2581,11 +2565,6 @@ export const messages = {
           '  → AI 能判断"做什么任务时要读哪个规范"',
           '  → 平衡 Context 使用量和合规程度'
         ],
-        full: [
-          '  → 所有规则直接嵌入配置文件（文件约 10-15 KB）',
-          '  → AI 无需额外读档，合规率最高',
-          '  → 适合短期任务或需要严格遵循的项目'
-        ],
         minimal: [
           '  → 仅包含 .standards/ 文件清单',
           '  → AI 需要主动读取规范文件',
@@ -2795,7 +2774,6 @@ export const messages = {
       warning: '变更 Content Mode 将重新生成所有 AI 工具配置文件',
       explanations: {
         index: '  → AI 会根据任务对照表判断何时读取规范',
-        full: '  → 所有规则直接嵌入，AI 合规率最高',
         minimal: '  → AI 需主动读取规范，建议搭配 Skills'
       }
     },
@@ -3144,7 +3122,6 @@ export const messages = {
         standardsScopeLean: '精简（Skills 处理其余）',
         standardsScopeComplete: '完整',
         contentModeLabel: '内容模式',
-        contentModeFull: '完整嵌入',
         contentModeIndex: '标准（推荐）',
         contentModeMinimal: '最小（仅核心）',
         displayLanguageLabel: '显示语言',