openuispec 0.1.25 → 0.1.28

package/drift/index.ts

@@ -10,6 +10,7 @@
  *   openuispec drift --target ios           # check drift for ios
  *   openuispec drift                        # check all targets with snapshots
  *   openuispec drift --snapshot --target ios # snapshot for ios
+ *   openuispec drift --target ios --explain # explain semantic changes since baseline
  *   openuispec drift --json --target ios    # machine-readable output
  *   openuispec drift --target ios --all     # include stubs in drift count
  */
@@ -17,6 +18,7 @@
 import { readFileSync, writeFileSync, readdirSync, existsSync } from "node:fs";
 import { resolve, join, relative, basename, dirname } from "node:path";
 import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
 import YAML from "yaml";
 
 const STATE_FILE = ".openuispec-state.json";
@@ -28,20 +30,47 @@ interface FileEntry {
   status: string;
 }
 
-interface StateFile {
+export interface StateFile {
   spec_version: string;
   snapshot_at: string;
   target: string;
+  baseline?: BaselineRef;
   files: Record<string, FileEntry>;
 }
 
-interface DriftResult {
+export interface BaselineRef {
+  kind: "git_commit" | "working_tree";
+  commit: string | null;
+  branch: string | null;
+}
+
+export interface DriftResult {
   changed: string[];
   added: string[];
   removed: string[];
   unchanged: string[];
 }
 
+export interface SemanticChange {
+  kind: "added" | "removed" | "changed";
+  path: string;
+  before?: string;
+  after?: string;
+}
+
+export interface FileExplanation {
+  file: string;
+  status: "added" | "removed" | "changed";
+  changes: SemanticChange[];
+  truncated: boolean;
+}
+
+export interface ExplainResult {
+  available: boolean;
+  note?: string;
+  files: FileExplanation[];
+}
+
 // ── helpers ───────────────────────────────────────────────────────────
 
 function listFiles(dir: string, ext: string): string[] {
@@ -61,6 +90,21 @@ function hashFile(filePath: string): string {
   return `sha256:${hash}`;
 }
 
+function readFileIfExists(filePath: string): string | null {
+  try {
+    return readFileSync(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+function parseSpecDocument(relPath: string, content: string): unknown {
+  if (relPath.endsWith(".json")) {
+    return JSON.parse(content);
+  }
+  return YAML.parse(content);
+}
+
 /** Read the status field from a screen or flow YAML file. */
 function readStatus(filePath: string): string {
   try {
@@ -129,10 +173,249 @@ function categorize(relPath: string): string {
   return "Other";
 }
 
+function runGit(args: string[], cwd: string): string | null {
+  try {
+    return execFileSync("git", args, {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function gitPathForFile(projectDir: string, relPath: string): string | null {
+  const repoRoot = runGit(["rev-parse", "--show-toplevel"], projectDir);
+  if (!repoRoot) return null;
+  return relative(repoRoot, join(projectDir, relPath));
+}
+
+function readFileFromGit(projectDir: string, commit: string, relPath: string): string | null {
+  const gitPath = gitPathForFile(projectDir, relPath);
+  if (!gitPath) return null;
+  return runGit(["show", `${commit}:${gitPath}`], projectDir);
+}
+
+function captureBaseline(projectDir: string, files: string[]): BaselineRef | undefined {
+  const repoRoot = runGit(["rev-parse", "--show-toplevel"], projectDir);
+  if (!repoRoot) return undefined;
+
+  const branch = runGit(["branch", "--show-current"], projectDir);
+  const commit = runGit(["rev-parse", "HEAD"], projectDir);
+  const repoPaths = files.map((file) => relative(repoRoot, file));
+  const status = runGit(["status", "--porcelain", "--", ...repoPaths], projectDir) ?? "";
+
+  return {
+    kind: status.length > 0 ? "working_tree" : "git_commit",
+    commit,
+    branch: branch || null,
+  };
+}
+
+export function formatBaseline(baseline?: BaselineRef): string | null {
+  if (!baseline) return null;
+
+  const ref = baseline.commit ? baseline.commit.slice(0, 12) : "uncommitted";
+  const branchSuffix = baseline.branch ? ` on ${baseline.branch}` : "";
+
+  if (baseline.kind === "git_commit") {
+    return `${ref}${branchSuffix} (exact git baseline)`;
+  }
+
+  return `${ref}${branchSuffix} + working tree spec changes`;
+}
+
+const MAX_CHANGES_PER_FILE = 20;
+const MAX_VALUE_LENGTH = 120;
+
+function summarizeValue(value: unknown): string {
+  if (typeof value === "string") {
+    return value.length > MAX_VALUE_LENGTH
+      ? JSON.stringify(`${value.slice(0, MAX_VALUE_LENGTH - 1)}…`)
+      : JSON.stringify(value);
+  }
+
+  const serialized = JSON.stringify(value);
+  if (!serialized) return String(value);
+  return serialized.length > MAX_VALUE_LENGTH
+    ? `${serialized.slice(0, MAX_VALUE_LENGTH - 1)}…`
+    : serialized;
+}
+
+function compareSemanticValue(
+  path: string,
+  before: unknown,
+  after: unknown,
+  changes: SemanticChange[]
+): void {
+  if (changes.length >= MAX_CHANGES_PER_FILE) return;
+
+  if (before === undefined && after === undefined) return;
+  if (before === undefined) {
+    changes.push({ kind: "added", path, after: summarizeValue(after) });
+    return;
+  }
+  if (after === undefined) {
+    changes.push({ kind: "removed", path, before: summarizeValue(before) });
+    return;
+  }
+
+  if (Array.isArray(before) || Array.isArray(after)) {
+    if (!Array.isArray(before) || !Array.isArray(after)) {
+      changes.push({
+        kind: "changed",
+        path,
+        before: summarizeValue(before),
+        after: summarizeValue(after),
+      });
+      return;
+    }
+
+    const maxLength = Math.max(before.length, after.length);
+    for (let index = 0; index < maxLength; index += 1) {
+      compareSemanticValue(`${path}[${index}]`, before[index], after[index], changes);
+      if (changes.length >= MAX_CHANGES_PER_FILE) return;
+    }
+    return;
+  }
+
+  if (
+    before &&
+    after &&
+    typeof before === "object" &&
+    typeof after === "object"
+  ) {
+    const beforeObj = before as Record<string, unknown>;
+    const afterObj = after as Record<string, unknown>;
+    const keys = Array.from(new Set([...Object.keys(beforeObj), ...Object.keys(afterObj)])).sort();
+
+    for (const key of keys) {
+      const nextPath = path ? `${path}.${key}` : key;
+      compareSemanticValue(nextPath, beforeObj[key], afterObj[key], changes);
+      if (changes.length >= MAX_CHANGES_PER_FILE) return;
+    }
+    return;
+  }
+
+  if (before !== after) {
+    changes.push({
+      kind: "changed",
+      path,
+      before: summarizeValue(before),
+      after: summarizeValue(after),
+    });
+  }
+}
+
+function explainFileChange(
+  projectDir: string,
+  baselineCommit: string,
+  relPath: string,
+  status: "added" | "removed" | "changed"
+): FileExplanation {
+  if (status === "added") {
+    return {
+      file: relPath,
+      status,
+      changes: [{ kind: "added", path: relPath }],
+      truncated: false,
+    };
+  }
+
+  if (status === "removed") {
+    return {
+      file: relPath,
+      status,
+      changes: [{ kind: "removed", path: relPath }],
+      truncated: false,
+    };
+  }
+
+  const beforeContent = readFileFromGit(projectDir, baselineCommit, relPath);
+  const afterContent = readFileIfExists(join(projectDir, relPath));
+
+  if (!beforeContent || !afterContent) {
+    return {
+      file: relPath,
+      status,
+      changes: [
+        {
+          kind: "changed",
+          path: relPath,
+          before: beforeContent ? "available" : "missing from baseline",
+          after: afterContent ? "available" : "missing from working tree",
+        },
+      ],
+      truncated: false,
+    };
+  }
+
+  try {
+    const beforeDoc = parseSpecDocument(relPath, beforeContent);
+    const afterDoc = parseSpecDocument(relPath, afterContent);
+    const changes: SemanticChange[] = [];
+    compareSemanticValue("", beforeDoc, afterDoc, changes);
+
+    return {
+      file: relPath,
+      status,
+      changes,
+      truncated: changes.length >= MAX_CHANGES_PER_FILE,
+    };
+  } catch (error) {
+    return {
+      file: relPath,
+      status,
+      changes: [
+        {
+          kind: "changed",
+          path: relPath,
+          after: error instanceof Error ? error.message : "unable to parse file diff",
+        },
+      ],
+      truncated: false,
+    };
+  }
+}
+
+export function explainDrift(projectDir: string, result: CheckResult): ExplainResult {
+  const baseline = result.state.baseline;
+  if (!baseline?.commit) {
+    return {
+      available: false,
+      note: "No git baseline metadata found in snapshot. Re-run `openuispec drift --snapshot --target <target>` from a git checkout.",
+      files: [],
+    };
+  }
+
+  if (baseline.kind !== "git_commit") {
+    return {
+      available: false,
+      note: "Snapshot was created from a dirty working tree, so semantic diff cannot reconstruct the exact baseline. Re-snapshot from a clean commit for precise explanations.",
+      files: [],
+    };
+  }
+
+  const files: FileExplanation[] = [];
+  for (const relPath of result.drift.added) {
+    files.push(explainFileChange(projectDir, baseline.commit, relPath, "added"));
+  }
+  for (const relPath of result.drift.removed) {
+    files.push(explainFileChange(projectDir, baseline.commit, relPath, "removed"));
+  }
+  for (const relPath of result.drift.changed) {
+    files.push(explainFileChange(projectDir, baseline.commit, relPath, "changed"));
+  }
+
+  files.sort((a, b) => a.file.localeCompare(b.file));
+  return { available: true, files };
+}
+
 // ── project resolution ───────────────────────────────────────────────
 
 /** Find the spec project directory by looking for openuispec.yaml. */
-function findProjectDir(cwd: string): string {
+export function findProjectDir(cwd: string): string {
   const candidates = [
     join(cwd, "openuispec"),
     cwd,
@@ -152,7 +435,7 @@ function findProjectDir(cwd: string): string {
 }
 
 /** Read the project name from the manifest. */
-function readProjectName(projectDir: string): string {
+export function readProjectName(projectDir: string): string {
   const doc = YAML.parse(
     readFileSync(join(projectDir, "openuispec.yaml"), "utf-8")
   );
@@ -160,7 +443,7 @@ function readProjectName(projectDir: string): string {
 }
 
 /** Read per-target output_dir map from the manifest. */
-function readOutputDirs(projectDir: string): Record<string, string> {
+export function readOutputDirs(projectDir: string): Record<string, string> {
   try {
     const doc = YAML.parse(readFileSync(join(projectDir, "openuispec.yaml"), "utf-8"));
     return doc.generation?.output_dir ?? {};
@@ -170,7 +453,7 @@ function readOutputDirs(projectDir: string): Record<string, string> {
 }
 
 /** Resolve the generated output directory for a target. */
-function resolveOutputDir(projectDir: string, projectName: string, target: string): string {
+export function resolveOutputDir(projectDir: string, projectName: string, target: string): string {
   const outputDirs = readOutputDirs(projectDir);
   if (outputDirs[target]) {
     return resolve(projectDir, outputDirs[target]);
@@ -179,11 +462,31 @@ function resolveOutputDir(projectDir: string, projectName: string, target: strin
   return resolve(projectDir, "..", "generated", target, projectName);
 }
 
-function stateFilePath(projectDir: string, projectName: string, target: string): string {
+export function stateFilePath(projectDir: string, projectName: string, target: string): string {
   return join(resolveOutputDir(projectDir, projectName, target), STATE_FILE);
 }
 
-function discoverTargets(projectDir: string, projectName: string): string[] {
+function missingSnapshotMessage(
+  cwd: string,
+  projectDir: string,
+  projectName: string,
+  target: string
+): string {
+  const outDir = resolveOutputDir(projectDir, projectName, target);
+  if (!existsSync(outDir)) {
+    return (
+      `No snapshot found for target "${target}".\n` +
+      `Output directory not found: ${relative(cwd, outDir)}\n` +
+      `Run code generation for "${target}" first, then run: openuispec drift --snapshot --target ${target}`
+    );
+  }
+  return (
+    `No snapshot found for target "${target}".\n` +
+    `Run: openuispec drift --snapshot --target ${target}`
+  );
+}
+
+export function discoverTargets(projectDir: string, projectName: string): string[] {
   const outputDirs = readOutputDirs(projectDir);
   const targets: string[] = [];
 
@@ -241,6 +544,7 @@ function snapshot(cwd: string, projectDir: string, target: string): void {
 
   const files = discoverSpecFiles(projectDir);
   const doc = YAML.parse(readFileSync(join(projectDir, "openuispec.yaml"), "utf-8"));
+  const baseline = captureBaseline(projectDir, files);
 
   const entries: Record<string, FileEntry> = {};
   let stubCount = 0;
@@ -256,6 +560,7 @@ function snapshot(cwd: string, projectDir: string, target: string): void {
     spec_version: doc.spec_version ?? "0.1",
     snapshot_at: new Date().toISOString(),
     target,
+    baseline,
     files: entries,
   };
 
@@ -267,18 +572,23 @@ function snapshot(cwd: string, projectDir: string, target: string): void {
     console.log(`  ${stubCount} stubs (not tracked for drift)`);
   }
   console.log(`  target: ${target}`);
+  const baselineLabel = formatBaseline(baseline);
+  if (baselineLabel) {
+    console.log(`  baseline: ${baselineLabel}`);
+  }
 }
 
 // ── check ─────────────────────────────────────────────────────────────
 
-interface CheckResult {
+export interface CheckResult {
   state: StateFile;
   drift: DriftResult;
   stubDrift: DriftResult;
   statuses: Record<string, string>;
+  explanation?: ExplainResult;
 }
 
-function computeDrift(
+export function computeDrift(
   projectDir: string,
   state: StateFile,
   includeAll: boolean
@@ -326,25 +636,38 @@ function computeDrift(
   return { state, drift, stubDrift, statuses };
 }
 
-function check(
+export function loadTargetDrift(
   cwd: string,
-  projectDir: string,
   target: string,
-  jsonOutput: boolean,
-  includeAll: boolean
-): void {
+  includeAll: boolean,
+  explainOutput: boolean
+): { projectDir: string; projectName: string; statePath: string; result: CheckResult } {
+  const projectDir = findProjectDir(cwd);
   const projectName = readProjectName(projectDir);
   const statePath = stateFilePath(projectDir, projectName, target);
   if (!existsSync(statePath)) {
-    console.error(
-      `No snapshot found for target "${target}".\n` +
-        `Run: openuispec drift --snapshot --target ${target}`
-    );
+    console.error(missingSnapshotMessage(cwd, projectDir, projectName, target));
     process.exit(1);
   }
 
   const state: StateFile = JSON.parse(readFileSync(statePath, "utf-8"));
   const result = computeDrift(projectDir, state, includeAll);
+  if (explainOutput) {
+    result.explanation = explainDrift(projectDir, result);
+  }
+
+  return { projectDir, projectName, statePath, result };
+}
+
+function check(
+  cwd: string,
+  projectDir: string,
+  target: string,
+  jsonOutput: boolean,
+  includeAll: boolean,
+  explainOutput: boolean
+): void {
+  const { result } = loadTargetDrift(cwd, target, includeAll, explainOutput);
 
   if (jsonOutput) {
     printJson(result);
@@ -361,7 +684,8 @@ function checkAll(
   cwd: string,
   projectDir: string,
   jsonOutput: boolean,
-  includeAll: boolean
+  includeAll: boolean,
+  explainOutput: boolean
 ): void {
   const projectName = readProjectName(projectDir);
   const targets = discoverTargets(projectDir, projectName);
@@ -378,6 +702,9 @@ function checkAll(
     const statePath = stateFilePath(projectDir, projectName, target);
     const state: StateFile = JSON.parse(readFileSync(statePath, "utf-8"));
     const result = computeDrift(projectDir, state, includeAll);
+    if (explainOutput) {
+      result.explanation = explainDrift(projectDir, result);
+    }
 
     if (jsonOutput) {
       printJson(result);
@@ -411,7 +738,9 @@ function printJson(result: CheckResult): void {
       {
         snapshot_at: result.state.snapshot_at,
         target: result.state.target,
+        baseline: result.state.baseline,
         ...result.drift,
+        explanation: result.explanation,
         stubs: stubTotal > 0 ? result.stubDrift : undefined,
       },
       null,
@@ -428,6 +757,10 @@ function printReport(projectDir: string, result: CheckResult): void {
   console.log(`Project: ${projectName}`);
   console.log(`Snapshot: ${result.state.snapshot_at}`);
   console.log(`Target: ${result.state.target}`);
+  const baselineLabel = formatBaseline(result.state.baseline);
+  if (baselineLabel) {
+    console.log(`Baseline: ${baselineLabel}`);
+  }
 
   const d = result.drift;
 
@@ -500,6 +833,46 @@ function printReport(projectDir: string, result: CheckResult): void {
   console.log(
     `\nSummary: ${d.changed.length} changed, ${d.added.length} added, ${d.removed.length} removed${stubSuffix}`
   );
+
+  if (result.explanation) {
+    console.log("\nSemantic Changes");
+    console.log("----------------");
+
+    if (!result.explanation.available) {
+      console.log(result.explanation.note ?? "Semantic explanation unavailable.");
+      return;
+    }
+
+    if (result.explanation.files.length === 0) {
+      console.log("No semantic changes to explain.");
+      return;
+    }
+
+    for (const file of result.explanation.files) {
+      console.log(`\n${file.file}`);
+      if (file.changes.length === 0) {
+        console.log("  · no property-level changes detected");
+        continue;
+      }
+
+      for (const change of file.changes) {
+        const pathLabel = change.path || "(root)";
+        if (change.kind === "added") {
+          const value = change.after ? ` = ${change.after}` : "";
+          console.log(`  + ${pathLabel}${value}`);
+        } else if (change.kind === "removed") {
+          const value = change.before ? ` (was ${change.before})` : "";
+          console.log(`  - ${pathLabel}${value}`);
+        } else {
+          console.log(`  ~ ${pathLabel}: ${change.before ?? "?"} -> ${change.after ?? "?"}`);
+        }
+      }
+
+      if (file.truncated) {
+        console.log(`  … truncated after ${MAX_CHANGES_PER_FILE} changes`);
+      }
+    }
+  }
 }
 
 // ── main ──────────────────────────────────────────────────────────────
@@ -508,6 +881,7 @@ export function runDrift(argv: string[]): void {
   const isSnapshot = argv.includes("--snapshot");
   const isJson = argv.includes("--json");
   const includeAll = argv.includes("--all");
+  const explainOutput = argv.includes("--explain");
 
   const targetIdx = argv.indexOf("--target");
   const target = targetIdx !== -1 && argv[targetIdx + 1] ? argv[targetIdx + 1] : null;
@@ -523,9 +897,9 @@ export function runDrift(argv: string[]): void {
     }
     snapshot(cwd, projectDir, target);
   } else if (target) {
-    check(cwd, projectDir, target, isJson, includeAll);
+    check(cwd, projectDir, target, isJson, includeAll, explainOutput);
   } else {
-    checkAll(cwd, projectDir, isJson, includeAll);
+    checkAll(cwd, projectDir, isJson, includeAll, explainOutput);
   }
 }
 

package/examples/taskflow/AGENTS.md

@@ -0,0 +1,112 @@
+<!-- openuispec-rules-start -->
+<!-- openuispec-rules-version: 0.1.28 -->
+# OpenUISpec — AI Assistant Rules
+# ================================
+# This project uses OpenUISpec to define UI as a semantic spec.
+# Spec files are the single source of truth for all UI across platforms.
+# Targets: "ios", "android", "web"
+
+## IMPORTANT — Read the specification before working with spec files
+
+The spec format, file schemas, and generation rules are defined in the installed `openuispec` package.
+You MUST read the reference files listed below before creating, editing, or generating from any spec file.
+Do NOT guess the file format — skipping this step will produce invalid YAML that fails validation.
+
+**Find the package in this order:**
+1. `node_modules/openuispec/` (project dependency)
+2. Run `npm root -g` → `<prefix>/openuispec/` (global install)
+3. Online: `https://openuispec.rsteam.uz/llms-full.txt` (if not installed)
+
+**Reference files inside the package (read in this order):**
+1. `README.md` — schema tables, file format reference, root wrapper keys
+2. `spec/openuispec-v0.1.md` — full specification (contracts, layout, expressions, adaptive, etc.)
+3. `examples/taskflow/openuispec/` — complete working example with all file types
+4. `schema/` — JSON Schemas for every file type
+
+These files are updated with each package version. Always read from the installed package,
+not from cached or memorized content, to ensure you use the latest spec.
+
+## What is OpenUISpec
+OpenUISpec is a YAML-based spec format that describes an app's UI semantically — tokens, screens, flows, and platform overrides. AI reads the spec and generates native code (SwiftUI, Compose, React). AI reads native code and updates the spec. The spec is the sync layer between platforms.
+
+## Spec location
+- Spec root: `openuispec/`
+- Manifest: `openuispec/openuispec.yaml` — always read this first.
+- Tokens: `openuispec/tokens/`
+- Screens: `openuispec/screens/`
+- Flows: `openuispec/flows/`
+- Contracts: `openuispec/contracts/`
+- Platform: `openuispec/platform/`
+- Locales: `openuispec/locales/`
+
+**Note:** These are the default paths. Actual paths are in `includes:` in `openuispec.yaml` and may use relative paths. Always read `openuispec.yaml` to find the real directories.
+
+## If spec directories are empty (first-time setup)
+This means the project has existing UI code but hasn't been specced yet. Your job:
+
+1. **Read the spec first** — find and read `spec/openuispec-v0.1.md` from the installed package.
+2. **Find existing screens** — scan the codebase for UI screen files.
+3. **Create stubs** — for each screen, create `openuispec/screens/<name>.yaml` with:
+   ```yaml
+   screen_name:
+     semantic: "Brief description of what this screen does"
+     status: stub
+     layout:
+       type: scroll_vertical
+   ```
+4. **Extract tokens** — scan for colors, fonts, spacing and create files in `openuispec/tokens/`.
+5. **Update the manifest** — fill in `data_model` and `api.endpoints` in `openuispec/openuispec.yaml`.
+
+## OpenUISpec Source Of Truth
+
+OpenUISpec spec files are the primary source of truth for UI behavior across platforms.
+
+### Start from spec when:
+- the request changes screen structure
+- the request changes navigation
+- the request changes fields, actions, validation, or data binding
+- the request changes tokens, variants, contracts, flows, or localization
+- the request affects more than one platform
+- the request is phrased in product/UI terms rather than platform-code terms
+
+Spec-first workflow:
+1. Read `openuispec/openuispec.yaml` and the relevant spec files first.
+2. Update the spec first.
+3. Update the affected generated/native UI code to match the spec.
+4. Run `openuispec validate`.
+5. Run `openuispec validate semantic`.
+6. Run `openuispec drift --target <target> --explain` to inspect semantic changes since that target's baseline.
+7. Run `openuispec prepare --target <target>` to build the AI/developer work bundle for that target.
+8. Verify the affected UI targets build/run if possible.
+9. Only then run `openuispec drift --snapshot --target <target>` for affected targets, after that target output directory exists.
+10. Run `openuispec drift --target <target> --explain` again to confirm no spec changes remain for that target.
+11. Use `openuispec status` to see which other targets are still behind the updated spec.
+
+### Start from platform code when:
+- the change is platform-specific polish
+- the change is a local bug fix that does not alter shared semantic behavior
+- the request explicitly asks for an iOS-only, Android-only, or web-only adjustment
+
+Platform-first workflow:
+1. Update native/platform code.
+2. If the change affects shared semantics, sync the spec afterward.
+3. If the change is intentionally platform-specific, document it in `platform/*.yaml` when appropriate.
+
+### Never do this:
+- Do not snapshot drift immediately after changing spec unless the UI code has also been updated.
+- Do not treat `openuispec drift` as proof that generated UI matches the spec.
+- Do not skip `--explain` / `prepare` when another platform needs to catch up with shared spec changes.
+- Do not modify generated UI without checking whether the spec must change first.
+
+## CLI commands
+- `openuispec init` — scaffold a new spec project
+- `openuispec validate [group...]` — validate spec files against schemas
+- `openuispec validate semantic` — run semantic cross-reference linting
+- `openuispec drift --target <t>` — check for spec drift
+- `openuispec drift --target <t> --explain` — explain semantic spec drift since the target baseline
+- `openuispec drift --snapshot --target <t>` — snapshot current state after the target output exists
+- `openuispec prepare --target <t>` — build an AI-ready target update bundle
+- `openuispec status` — show cross-target baseline/drift status
+- `openuispec update-rules` — update AI rules to match installed package version
+- `openuispec drift --all` — include stubs in drift check
+<!-- openuispec-rules-end -->