claudeos-core 1.7.1 → 2.0.0

package/plan-installer/scanners/scan-frontend.js

@@ -7,9 +7,60 @@
  * Also provides frontend file count statistics.
  */
 
+const fs = require("fs");
 const path = require("path");
 const { glob } = require("glob");
 
+// Project-level override: `.claudeos-scan.json` at project root can extend
+// the defaults. Supported fields (all optional, all additive — never replace
+// defaults):
+//   {
+//     "frontendScan": {
+//       "platformKeywords": ["extra-platform", "custom-tier"],
+//       "skipSubappNames": ["my-shared-dir"],
+//       "minSubappFiles": 3
+//     }
+//   }
+// Invalid JSON or missing file: silently falls back to defaults.
+function loadScanOverrides(ROOT) {
+  try {
+    const content = fs.readFileSync(path.join(ROOT, ".claudeos-scan.json"), "utf-8");
+    return JSON.parse(content) || {};
+  } catch (_e) {
+    return {};
+  }
+}
+
+// Build output / cache / generated dirs that should never be scanned for
+// source code. Centralized so platform scan, Fallback E, and future scanners
+// share the same exclusion set.
+const BUILD_IGNORE_DIRS = [
+  "**/node_modules/**",
+  "**/build/**", "**/dist/**", "**/out/**",
+  "**/.next/**", "**/.nuxt/**", "**/.svelte-kit/**", "**/.angular/**",
+  "**/.turbo/**", "**/.cache/**", "**/.parcel-cache/**",
+  "**/coverage/**", "**/storybook-static/**",
+  "**/.vercel/**", "**/.netlify/**",
+];
+
+// Test / story / type-declaration file globs.
+const TEST_FILE_IGNORE = [
+  "**/*.spec.*", "**/*.test.*", "**/*.stories.*",
+  "**/*.e2e.*", "**/*.cy.*",
+  "**/__snapshots__/**", "**/__tests__/**",
+];
+
+// Build a glob prefix from a glob-returned directory path. Glob v10+ strips
+// trailing slashes from results, and on Windows returns backslash paths;
+// without normalization, the pattern `${dir}**/*.tsx` becomes something like
+// `src/foo**/*.tsx` which only matches one level deep (foo/X.tsx) — not
+// nested paths like foo/routes/X.tsx. Ensuring a trailing `/` turns it into
+// `src/foo/**/*.tsx` which matches any depth.
+function dirGlobPrefix(dir) {
+  const fwd = dir.replace(/\\/g, "/");
+  return fwd.endsWith("/") ? fwd : fwd + "/";
+}
+
 async function scanFrontendDomains(stack, ROOT) {
   const frontendDomains = [];
 
@@ -20,11 +71,16 @@ async function scanFrontendDomains(stack, ROOT) {
       ...await glob("{src/app,app}/*/", { cwd: ROOT }),
       ...await glob("{apps,packages}/*/src/app/*/", { cwd: ROOT, ignore: ["**/node_modules/**"] }),
     ];
-    const skipAngularDirs = ["shared", "core", "common", "layout", "layouts", "environments", "assets", "styles", "testing", "utils"];
+    // Skip structural containers (modules/features/pages/views) at the
+    // src/app/*/ level — the files INSIDE those containers are the real
+    // features, and the Angular deep fallback below extracts them properly.
+    const skipAngularDirs = ["shared", "core", "common", "layout", "layouts",
+      "environments", "assets", "styles", "testing", "utils",
+      "modules", "features", "pages", "views"];
     for (const dir of angularAppDirs) {
       const name = path.basename(dir.replace(/\/$/, ""));
       if (skipAngularDirs.includes(name) || name.startsWith("_") || name.startsWith(".")) continue;
-      const files = await glob(`${dir.replace(/\\/g, "/")}**/*.ts`, { cwd: ROOT, ignore: ["**/*.spec.ts", "**/*.test.ts"] });
+      const files = await glob(`${dirGlobPrefix(dir)}**/*.ts`, { cwd: ROOT, ignore: ["**/*.spec.ts", "**/*.test.ts"] });
       if (files.length > 0) {
         const components = files.filter(f => /\.component\.ts$/.test(f)).length;
         const services = files.filter(f => /\.service\.ts$/.test(f)).length;
@@ -42,7 +98,7 @@ async function scanFrontendDomains(stack, ROOT) {
       for (const dir of deepAngularDirs) {
         const name = path.basename(dir.replace(/\/$/, ""));
         if (skipAngularDirs.includes(name) || name.startsWith("_") || name.startsWith(".")) continue;
-        const files = await glob(`${dir.replace(/\\/g, "/")}**/*.ts`, { cwd: ROOT, ignore: ["**/*.spec.ts", "**/*.test.ts"] });
+        const files = await glob(`${dirGlobPrefix(dir)}**/*.ts`, { cwd: ROOT, ignore: ["**/*.spec.ts", "**/*.test.ts"] });
         if (files.length >= 2) {
           const components = files.filter(f => /\.component\.ts$/.test(f)).length;
           const services = files.filter(f => /\.service\.ts$/.test(f)).length;
@@ -67,11 +123,16 @@ async function scanFrontendDomains(stack, ROOT) {
       // Vite SPA / CRA common paths (src/views/*, src/screens/*, src/routes/*)
       ...await glob("src/{views,screens,routes}/*/", { cwd: ROOT, ignore: ["**/node_modules/**"] }),
     ];
-    const skipPages = ["api", "_app", "_document", "fonts", "not-found", "error", "loading"];
+    // Reserved Next.js/Router segments + structural containers that are never
+    // real route features. "components"/"hooks"/"widgets" under app/ or
+    // pages/ are UI containers handled by dedicated scanners — not routes.
+    const skipPages = ["api", "_app", "_document", "fonts", "not-found", "error", "loading",
+      "components", "hooks", "widgets", "entities", "features", "modules",
+      "lib", "libs", "utils", "util", "config", "types", "shared", "common", "assets"];
     for (const dir of allDirs) {
       const name = path.basename(dir);
       if (skipPages.includes(name) || name.startsWith("(") || name.startsWith("[") || name.startsWith("_") || name.startsWith(".")) continue;
-      const files = await glob(`${dir.replace(/\\/g, "/")}**/*.{tsx,jsx,ts,js,vue}`, { cwd: ROOT });
+      const files = await glob(`${dirGlobPrefix(dir)}**/*.{tsx,jsx,ts,js,vue}`, { cwd: ROOT });
       if (files.length > 0) {
         const pages = files.filter(f => /page\.|index\./.test(f)).length;
         const layouts = files.filter(f => /layout\./.test(f)).length;
@@ -95,7 +156,7 @@ async function scanFrontendDomains(stack, ROOT) {
       for (const dir of fsdDirs) {
         const name = path.basename(dir);
         if (["ui", "common", "shared", "lib", "config", "index"].includes(name)) continue;
-        const files = await glob(`${dir.replace(/\\/g, "/")}**/*.{tsx,jsx,ts,js,vue}`, { cwd: ROOT, ignore: ["**/*.spec.*", "**/*.test.*", "**/*.stories.*"] });
+        const files = await glob(`${dirGlobPrefix(dir)}**/*.{tsx,jsx,ts,js,vue}`, { cwd: ROOT, ignore: ["**/*.spec.*", "**/*.test.*", "**/*.stories.*"] });
         if (files.length > 0) {
           const uiFiles = files.filter(f => /\bui\b/.test(f)).length;
           const modelFiles = files.filter(f => /model|store|hook/.test(f)).length;
@@ -113,7 +174,7 @@ async function scanFrontendDomains(stack, ROOT) {
     for (const dir of compDirs) {
       const name = path.basename(dir);
       if (["ui", "common", "shared", "layout", "icons"].includes(name)) continue;
-      const files = await glob(`${dir.replace(/\\/g, "/")}**/*.{tsx,jsx,vue}`, { cwd: ROOT });
+      const files = await glob(`${dirGlobPrefix(dir)}**/*.{tsx,jsx,vue}`, { cwd: ROOT });
       if (files.length >= 2) {
         frontendDomains.push({ name: `comp-${name}`, type: "frontend", components: files.length, totalFiles: files.length });
       }
@@ -187,7 +248,7 @@ async function scanFrontendDomains(stack, ROOT) {
         for (const dir of deepCompDirs) {
           const name = path.basename(dir.replace(/\/$/, ""));
           if (skipDomainNames.includes(name) || name.startsWith("_") || name.startsWith(".")) continue;
-          const files = await glob(`${dir.replace(/\\/g, "/")}**/*.{tsx,jsx,ts,js,vue}`, { cwd: ROOT, ignore: ["**/*.spec.*", "**/*.test.*", "**/*.stories.*"] });
+          const files = await glob(`${dirGlobPrefix(dir)}**/*.{tsx,jsx,ts,js,vue}`, { cwd: ROOT, ignore: ["**/*.spec.*", "**/*.test.*", "**/*.stories.*"] });
           if (files.length >= 2) {
             if (!deepDomains[name]) deepDomains[name] = { components: 0, totalFiles: 0 };
             deepDomains[name].components += files.length;
@@ -212,7 +273,7 @@ async function scanFrontendDomains(stack, ROOT) {
           for (const dir of dirs) {
             const name = path.basename(dir.replace(/\/$/, ""));
             if (skipDirNames.includes(name) || name.startsWith("_") || name.startsWith(".") || name.startsWith("(") || name.startsWith("[")) continue;
-            const files = await glob(`${dir.replace(/\\/g, "/")}**/*.{tsx,jsx,ts,js,vue}`, { cwd: ROOT, ignore: ["**/*.spec.*", "**/*.test.*", "**/*.stories.*"] });
+            const files = await glob(`${dirGlobPrefix(dir)}**/*.{tsx,jsx,ts,js,vue}`, { cwd: ROOT, ignore: ["**/*.spec.*", "**/*.test.*", "**/*.stories.*"] });
             if (files.length >= 2) {
               if (!deepDirDomains[name]) deepDirDomains[name] = { components: 0, pages: 0, totalFiles: 0, sources: [] };
               const tsx = files.filter(f => /\.(tsx|jsx|vue)$/.test(f)).length;
@@ -226,6 +287,152 @@ async function scanFrontendDomains(stack, ROOT) {
           frontendDomains.push({ name, type: "frontend", components: data.components, totalFiles: data.totalFiles, sources: data.sources });
         }
       }
+
+    }
+  }
+
+  // ── Shared frontend patterns (run for ANY frontend: Angular, Next.js, React, Vue) ──
+  //
+  // These patterns don't depend on framework-specific file extensions or
+  // folder conventions — they look for top-level segmentation by platform or
+  // by routes/-file layouts, which appear across all frontend frameworks.
+  if (stack.frontend) {
+    // Read optional per-project override (.claudeos-scan.json).
+    const overrides = loadScanOverrides(ROOT).frontendScan || {};
+    // Platform-split layout: src/{platform}/{subapp}/ where platform is a
+    // device/target-environment OR access-tier keyword. Both form the same
+    // structural pattern (top-level segmentation with a common subapp layout).
+    // Subapp name comes from the filesystem at scan time via path.basename —
+    // no project-specific names are hardcoded.
+    // Produces one domain per (platform, subapp) pair, named `{platform}-{subapp}`.
+    // NOTE: 3-letter+ access-tier names only. The short `adm` abbreviation
+    // is deliberately excluded — too ambiguous in isolation and false-positive
+    // risk isn't worth the small convenience gain. If a project uses `src/adm/`
+    // as an admin tier root, rename to `admin` or add `"adm"` to
+    // `frontendScan.platformKeywords` in `.claudeos-scan.json`.
+    const DEFAULT_PLATFORM_KEYWORDS = [
+      // device / target-environment
+      "desktop", "pc", "web",
+      "mobile", "mc", "mo", "sp",
+      "tablet", "tab",
+      "pwa",
+      "tv", "ctv", "ott",
+      "watch", "wear",
+      // access-tier / audience
+      "admin", "cms", "backoffice", "back-office", "portal",
+    ];
+    const PLATFORM_KEYWORDS = [
+      ...DEFAULT_PLATFORM_KEYWORDS,
+      ...(Array.isArray(overrides.platformKeywords) ? overrides.platformKeywords : []),
+    ];
+    // Minimum source files to qualify as a subapp. A single-file directory
+    // under a platform root is almost always an accidental fixture or a
+    // placeholder, not a real subapp. Raising the floor avoids noisy
+    // 1-file "domains" in the Pass 1 group plan.
+    const MIN_SUBAPP_FILES = typeof overrides.minSubappFiles === "number" && overrides.minSubappFiles >= 1
+      ? overrides.minSubappFiles
+      : 2;
+    // Conservative skip list — never-a-feature names at the subapp level.
+    // Includes infrastructure dirs, structural dirs that other scanners
+    // already handle (components/hooks/layouts), FSD layer names, and
+    // framework router dirs. Patterns like `src/admin/pages/*/` and
+    // `src/admin/components/*/` fall through to the App/Pages Router and
+    // components scanners instead of being captured as bare subapps.
+    // `store`/`stores` are deliberately NOT skipped — e-commerce projects
+    // legitimately use them as subapp names.
+    const DEFAULT_SKIP_SUBAPP_NAMES = [
+      // infrastructure
+      "assets", "common", "shared", "utils", "util",
+      "lib", "libs", "config", "constants", "helpers", "types",
+      "test", "tests", "__mocks__", "mocks", "__tests__",
+      // structural (handled by dedicated scanners at a deeper level)
+      "components", "hooks", "layouts", "layout",
+      // FSD layers (handled by FSD scanner)
+      "widgets", "features", "entities",
+      // framework router dirs (handled by App/Pages Router scanner + fallback D)
+      "app", "pages", "routes", "views", "screens", "containers",
+      "modules", "domains",
+    ];
+    const SKIP_SUBAPP_NAMES = [
+      ...DEFAULT_SKIP_SUBAPP_NAMES,
+      ...(Array.isArray(overrides.skipSubappNames) ? overrides.skipSubappNames : []),
+    ];
+    // Match both standalone projects (src/{platform}/{subapp}/) and monorepo
+    // workspaces ({apps,packages}/*/src/{platform}/{subapp}/ and
+    // {apps,packages}/{platform}/{subapp}/ — some monorepos skip the src/ wrapper).
+    const platformGlobs = [
+      `src/{${PLATFORM_KEYWORDS.join(",")}}/*/`,
+      `{apps,packages}/*/src/{${PLATFORM_KEYWORDS.join(",")}}/*/`,
+      `{apps,packages}/{${PLATFORM_KEYWORDS.join(",")}}/*/`,
+    ];
+    const platformDirs = [];
+    for (const p of platformGlobs) {
+      const dirs = await glob(p, { cwd: ROOT, ignore: ["**/node_modules/**"] });
+      platformDirs.push(...dirs);
+    }
+    // Dedupe (the three globs can produce overlapping matches in some layouts)
+    const seenPlatformDirs = new Set();
+    for (const dir of platformDirs) {
+      const dirFwd = dir.replace(/\\/g, "/").replace(/\/$/, "");
+      if (seenPlatformDirs.has(dirFwd)) continue;
+      seenPlatformDirs.add(dirFwd);
+      const parts = dirFwd.split("/");
+      // Locate platform segment: the FIRST segment that matches a keyword.
+      // findIndex (not findLast) — if the subapp name also happens to be a
+      // keyword (e.g., `src/pc/admin/`), the subapp should stay as the
+      // second match, not be mistaken for the platform segment.
+      // Paths handled: src/<p>/<s>, apps/<workspace>/src/<p>/<s>, apps/<p>/<s>.
+      const platformIdx = parts.findIndex(seg => PLATFORM_KEYWORDS.includes(seg));
+      if (platformIdx < 0 || platformIdx + 1 >= parts.length) continue;
+      const platform = parts[platformIdx];
+      const subapp = parts[platformIdx + 1];
+      if (!subapp || SKIP_SUBAPP_NAMES.includes(subapp) || subapp.startsWith("_") || subapp.startsWith(".")) continue;
+      const files = await glob(`${dirGlobPrefix(dir)}**/*.{tsx,jsx,ts,js,vue}`, {
+        cwd: ROOT,
+        ignore: [...BUILD_IGNORE_DIRS, ...TEST_FILE_IGNORE],
+      });
+      if (files.length < MIN_SUBAPP_FILES) continue;
+      // Normalize Windows backslashes so the segment regex works cross-platform.
+      const filesFwd = files.map(f => f.replace(/\\/g, "/"));
+      const routes = filesFwd.filter(f => /\/routes\//.test(f)).length;
+      const components = filesFwd.filter(f => /\/components\//.test(f)).length;
+      const layouts = filesFwd.filter(f => /\/layouts?\//.test(f)).length;
+      const hooks = filesFwd.filter(f => /\/hooks\//.test(f)).length;
+      frontendDomains.push({
+        name: `${platform}-${subapp}`,
+        type: "frontend",
+        platform,
+        subapp,
+        routes, components, layouts, hooks,
+        totalFiles: files.length,
+      });
+    }
+
+    // Fallback E: React Router file-routing (any depth). Groups by the
+    // parent dir of `routes/`. Domain name = parent basename. Covers
+    // CRA/Vite + React Router projects that don't match Next.js page.tsx
+    // or FSD layout. Only fires when every other primary and fallback
+    // scanner returned 0 domains.
+    if (frontendDomains.length === 0) {
+      const routeFiles = await glob("**/routes/*.{tsx,jsx,ts,js,vue}", {
+        cwd: ROOT,
+        ignore: [...BUILD_IGNORE_DIRS, ...TEST_FILE_IGNORE],
+      });
+      const routeDomains = {};
+      const skipParents = ["src", "app", "pages", "", "."];
+      for (const f of routeFiles) {
+        const parts = f.replace(/\\/g, "/").split("/");
+        const routesIdx = parts.lastIndexOf("routes");
+        if (routesIdx < 1) continue;
+        const parent = parts[routesIdx - 1];
+        if (skipParents.includes(parent) || parent.startsWith("_") || parent.startsWith(".")) continue;
+        if (!routeDomains[parent]) routeDomains[parent] = { routes: 0, totalFiles: 0 };
+        routeDomains[parent].routes++;
+        routeDomains[parent].totalFiles++;
+      }
+      for (const [name, data] of Object.entries(routeDomains)) {
+        frontendDomains.push({ name, type: "frontend", routes: data.routes, totalFiles: data.totalFiles });
+      }
     }
   }
 

package/sync-checker/index.js

@@ -1,132 +1,133 @@
-#!/usr/bin/env node
-
-/**
- * ClaudeOS-Core — Sync Checker
- *
- * Role: Check disk ↔ Master Plan sync status based on sync-map.json
- * Detection items:
- *   - Unregistered: file exists on disk but not registered in any plan
- *   - Orphaned:     registered in plan but missing from disk
- *
- * Usage: npx claudeos-core <cmd> or node claudeos-core-tools/sync-checker/index.js
- * Depends: manifest-generator must run first (sync-map.json)
- */
-
-const fs = require("fs");
-const path = require("path");
-const { glob } = require("glob");
-const { updateStaleReport } = require("../lib/stale-report");
-
-const ROOT = process.env.CLAUDEOS_ROOT || path.resolve(__dirname, "../..");
-const GEN = path.join(ROOT, "claudeos-core/generated");
-const SMP = path.join(GEN, "sync-map.json");
-
-const TRACKED = [
-  { dir: ".claude/rules",           pfx: "rules"     },
-  { dir: "claudeos-core/standard",  pfx: "standard"  },
-  { dir: "claudeos-core/skills",    pfx: "skills"    },
-  { dir: "claudeos-core/guide",     pfx: "guide"     },
-  { dir: "claudeos-core/database",  pfx: "database"  },
-  { dir: "claudeos-core/mcp-guide", pfx: "mcp-guide" },
-];
-
-function rel(p) {
-  return path.relative(ROOT, p).replace(/\\/g, "/");
-}
-
-function isWithinRoot(absPath) {
-  let resolved = path.resolve(absPath);
-  let root = path.resolve(ROOT);
-  if (process.platform === "win32") {
-    resolved = resolved.toLowerCase();
-    root = root.toLowerCase();
-  }
-  return resolved === root || resolved.startsWith(root + path.sep);
-}
-
-async function main() {
-  console.log("\n╔═══════════════════════════════════════╗");
-  console.log("║  ClaudeOS-Core — Sync Checker         ║");
-  console.log("╚═══════════════════════════════════════╝\n");
-
-  if (!fs.existsSync(SMP)) {
-    console.log("  ❌ sync-map.json not found. Run manifest-generator first.\n");
-    process.exit(1);
-  }
-
-  let sm;
-  try {
-    sm = JSON.parse(fs.readFileSync(SMP, "utf-8"));
-  } catch (e) {
-    console.log(`  ❌ sync-map.json is malformed: ${e.message}\n`);
-    process.exit(1);
-  }
-  if (!Array.isArray(sm.mappings)) {
-    console.log("  ❌ sync-map.json has no mappings array.\n");
-    process.exit(1);
-  }
-  const reg = new Set(sm.mappings.map((m) => m.sourcePath).filter(Boolean));
-  const issues = { unreg: [], orphan: [] };
-
-  // ─── [1/2] Disk → Plan: detect unregistered files ───────
-  console.log("  [1/2] Disk → Plan...");
-  for (const t of TRACKED) {
-    const abs = path.join(ROOT, t.dir);
-    if (!fs.existsSync(abs)) continue;
-
-    for (const f of await glob("**/*.md", { cwd: abs, absolute: true })) {
-      const r = rel(f);
-      if (path.basename(f) === "README.md") continue;
-      if (!reg.has(r)) {
-        issues.unreg.push({ path: r, domain: t.pfx });
-      }
-    }
-  }
-
-  // Check CLAUDE.md separately
-  if (fs.existsSync(path.join(ROOT, "CLAUDE.md")) && !reg.has("CLAUDE.md")) {
-    issues.unreg.push({ path: "CLAUDE.md", domain: "root" });
-  }
-
-  // ─── [2/2] Plan → Disk: detect orphaned files ───────────────
-  console.log("  [2/2] Plan → Disk...");
-  for (const m of sm.mappings) {
-    if (!m.sourcePath) continue;
-    const abs = path.join(ROOT, m.sourcePath);
-    // Skip path traversal attempts (allow files at ROOT level and below)
-    if (!isWithinRoot(abs)) continue;
-    if (!fs.existsSync(abs)) {
-      issues.orphan.push({ path: m.sourcePath, plan: m.planFile });
-    }
-  }
-
-  // ─── Output results ─────────────────────────────────────────
-  if (issues.unreg.length) {
-    console.log(`\n  ⚠️  Unregistered (${issues.unreg.length}):`);
-    issues.unreg.forEach((i) => console.log(`     + ${i.path}`));
-  }
-  if (issues.orphan.length) {
-    console.log(`\n  ⚠️  Orphaned (${issues.orphan.length}):`);
-    issues.orphan.forEach((i) => console.log(`     - ${i.path}`));
-  }
-
-  const total = issues.unreg.length + issues.orphan.length;
-  console.log(`\n  Registered: ${reg.size} | Unregistered: ${issues.unreg.length} | Orphaned: ${issues.orphan.length}`);
-  console.log(total === 0 ? "  ✅ All in sync\n" : `  ⚠️  ${total} issues\n`);
-
-  // ─── Update stale-report.json ────────────────────────────
-  updateStaleReport(GEN, "syncMisses",
-    { checkedAt: new Date().toISOString(), unregistered: issues.unreg, orphaned: issues.orphan },
-    { syncIssues: total, status: total === 0 ? "ok" : "warning" }
-  );
-
-  // Exit 1 only for orphaned files (actual breakage), not for unregistered (informational)
-  const orphanCount = issues.orphan.length;
-  process.exit(orphanCount > 0 ? 1 : 0);
-}
-
-if (require.main === module) {
-  main().catch(e => { console.error(`\n  ❌ Unexpected error: ${e.message || e}`); process.exit(1); });
-}
-
-module.exports = { main };
+#!/usr/bin/env node
+
+/**
+ * ClaudeOS-Core — Sync Checker
+ *
+ * Role: Check disk ↔ Master Plan sync status based on sync-map.json
+ * Detection items:
+ *   - Unregistered: file exists on disk but not registered in any plan
+ *   - Orphaned:     registered in plan but missing from disk
+ *
+ * Usage: npx claudeos-core <cmd> or node claudeos-core-tools/sync-checker/index.js
+ * Depends: manifest-generator must run first (sync-map.json)
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { glob } = require("glob");
+const { updateStaleReport } = require("../lib/stale-report");
+
+const ROOT = process.env.CLAUDEOS_ROOT || path.resolve(__dirname, "../..");
+const GEN = path.join(ROOT, "claudeos-core/generated");
+const SMP = path.join(GEN, "sync-map.json");
+
+const TRACKED = [
+  { dir: ".claude/rules",           pfx: "rules"     },
+  { dir: "claudeos-core/standard",  pfx: "standard"  },
+  { dir: "claudeos-core/skills",    pfx: "skills"    },
+  { dir: "claudeos-core/guide",     pfx: "guide"     },
+  { dir: "claudeos-core/database",  pfx: "database"  },
+  { dir: "claudeos-core/mcp-guide", pfx: "mcp-guide" },
+  { dir: "claudeos-core/memory",    pfx: "memory"    },
+];
+
+function rel(p) {
+  return path.relative(ROOT, p).replace(/\\/g, "/");
+}
+
+function isWithinRoot(absPath) {
+  let resolved = path.resolve(absPath);
+  let root = path.resolve(ROOT);
+  if (process.platform === "win32") {
+    resolved = resolved.toLowerCase();
+    root = root.toLowerCase();
+  }
+  return resolved === root || resolved.startsWith(root + path.sep);
+}
+
+async function main() {
+  console.log("\n╔═══════════════════════════════════════╗");
+  console.log("║  ClaudeOS-Core — Sync Checker         ║");
+  console.log("╚═══════════════════════════════════════╝\n");
+
+  if (!fs.existsSync(SMP)) {
+    console.log("  ❌ sync-map.json not found. Run manifest-generator first.\n");
+    process.exit(1);
+  }
+
+  let sm;
+  try {
+    sm = JSON.parse(fs.readFileSync(SMP, "utf-8"));
+  } catch (e) {
+    console.log(`  ❌ sync-map.json is malformed: ${e.message}\n`);
+    process.exit(1);
+  }
+  if (!Array.isArray(sm.mappings)) {
+    console.log("  ❌ sync-map.json has no mappings array.\n");
+    process.exit(1);
+  }
+  const reg = new Set(sm.mappings.map((m) => m.sourcePath).filter(Boolean));
+  const issues = { unreg: [], orphan: [] };
+
+  // ─── [1/2] Disk → Plan: detect unregistered files ───────
+  console.log("  [1/2] Disk → Plan...");
+  for (const t of TRACKED) {
+    const abs = path.join(ROOT, t.dir);
+    if (!fs.existsSync(abs)) continue;
+
+    for (const f of await glob("**/*.md", { cwd: abs, absolute: true })) {
+      const r = rel(f);
+      if (path.basename(f) === "README.md") continue;
+      if (!reg.has(r)) {
+        issues.unreg.push({ path: r, domain: t.pfx });
+      }
+    }
+  }
+
+  // Check CLAUDE.md separately
+  if (fs.existsSync(path.join(ROOT, "CLAUDE.md")) && !reg.has("CLAUDE.md")) {
+    issues.unreg.push({ path: "CLAUDE.md", domain: "root" });
+  }
+
+  // ─── [2/2] Plan → Disk: detect orphaned files ───────────────
+  console.log("  [2/2] Plan → Disk...");
+  for (const m of sm.mappings) {
+    if (!m.sourcePath) continue;
+    const abs = path.join(ROOT, m.sourcePath);
+    // Skip path traversal attempts (allow files at ROOT level and below)
+    if (!isWithinRoot(abs)) continue;
+    if (!fs.existsSync(abs)) {
+      issues.orphan.push({ path: m.sourcePath, plan: m.planFile });
+    }
+  }
+
+  // ─── Output results ─────────────────────────────────────────
+  if (issues.unreg.length) {
+    console.log(`\n  ⚠️  Unregistered (${issues.unreg.length}):`);
+    issues.unreg.forEach((i) => console.log(`     + ${i.path}`));
+  }
+  if (issues.orphan.length) {
+    console.log(`\n  ⚠️  Orphaned (${issues.orphan.length}):`);
+    issues.orphan.forEach((i) => console.log(`     - ${i.path}`));
+  }
+
+  const total = issues.unreg.length + issues.orphan.length;
+  console.log(`\n  Registered: ${reg.size} | Unregistered: ${issues.unreg.length} | Orphaned: ${issues.orphan.length}`);
+  console.log(total === 0 ? "  ✅ All in sync\n" : `  ⚠️  ${total} issues\n`);
+
+  // ─── Update stale-report.json ────────────────────────────
+  updateStaleReport(GEN, "syncMisses",
+    { checkedAt: new Date().toISOString(), unregistered: issues.unreg, orphaned: issues.orphan },
+    { syncIssues: total, status: total === 0 ? "ok" : "warning" }
+  );
+
+  // Exit 1 only for orphaned files (actual breakage), not for unregistered (informational)
+  const orphanCount = issues.orphan.length;
+  process.exit(orphanCount > 0 ? 1 : 0);
+}
+
+if (require.main === module) {
+  main().catch(e => { console.error(`\n  ❌ Unexpected error: ${e.message || e}`); process.exit(1); });
+}
+
+module.exports = { main };