claudeos-core 1.7.0 → 2.0.0

package/pass-json-validator/index.js

@@ -1,299 +1,337 @@
-#!/usr/bin/env node
-
-/**
- * ClaudeOS-Core — Pass JSON Validator
- *
- * Role: Validate format and required keys of JSON files generated by Pass 1-3
- * Validation items:
- *   - JSON is parseable
- *   - pass1-*.json: analyzedAt, passNum, domains, analysisPerDomain keys exist
- *   - pass2-merged.json: fuzzy validation of common required sections (10) + backend sections (2)
- *                        empty value detection, top-level key count check (<5 ERROR, <9 WARNING)
- *   - project-analysis.json: stack, domains, frontend, summary keys exist
- *
- * Usage: npx claudeos-core <cmd> or node claudeos-core-tools/pass-json-validator/index.js
- */
-
-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_DIR = path.join(ROOT, "claudeos-core/generated");
-
-function rel(p) { return path.relative(ROOT, p).replace(/\\/g, "/"); }
-
-async function main() {
-  console.log("\n╔═══════════════════════════════════════╗");
-  console.log("║  ClaudeOS-Core — Pass JSON Validator  ║");
-  console.log("╚═══════════════════════════════════════╝\n");
-
-  if (!fs.existsSync(GEN_DIR)) {
-    console.log("  ❌ claudeos-core/generated/ directory not found\n");
-    process.exit(1);
-  }
-
-  const errors = [];
-  const warnings = [];
-  let checked = 0;
-
-  // ─── Helpers: JSON parse + key validation ────────────────────────
-  function validateJson(filePath, requiredKeys, optionalKeys) {
-    const r = rel(filePath);
-    if (!fs.existsSync(filePath)) {
-      errors.push({ file: r, type: "MISSING", msg: "File not found" });
-      return null;
-    }
-    checked++;
-    let data;
-    try {
-      const raw = fs.readFileSync(filePath, "utf-8");
-      data = JSON.parse(raw);
-    } catch (e) {
-      errors.push({ file: r, type: "PARSE_ERROR", msg: `JSON parse failed: ${e.message}` });
-      return null;
-    }
-
-    for (const key of requiredKeys) {
-      if (!(key in data)) {
-        errors.push({ file: r, type: "MISSING_KEY", msg: `Required key '${key}' missing` });
-      }
-    }
-    for (const key of (optionalKeys || [])) {
-      if (!(key in data)) {
-        warnings.push({ file: r, type: "MISSING_KEY", msg: `Recommended key '${key}' missing` });
-      }
-    }
-    return data;
-  }
-
-  // ─── 1. project-analysis.json ──────────────────────────
-  console.log("  [1/4] project-analysis.json...");
-  const pa = validateJson(
-    path.join(GEN_DIR, "project-analysis.json"),
-    ["analyzedAt", "stack", "domains", "frontend", "summary"],
-    ["lang", "template", "templates", "rootPackage", "activeDomains"]
-  );
-  if (pa) {
-    if (!pa.stack || !pa.stack.language) {
-      errors.push({ file: "project-analysis.json", type: "INVALID_STACK", msg: "stack.language is missing" });
-    }
-    if (!Array.isArray(pa.domains)) {
-      errors.push({ file: "project-analysis.json", type: "INVALID_DOMAINS", msg: "domains is not an array" });
-    } else {
-      console.log(`    stack: ${pa.stack?.language || "?"} / ${pa.stack?.framework || "?"}`);
-      console.log(`    domains: ${pa.domains.length}`);
-      console.log(`    lang: ${pa.lang || "en (default)"}`);
-      const tmpl = pa.templates || pa.template;
-      if (tmpl && typeof tmpl === "object") {
-        console.log(`    templates: backend=${tmpl.backend || "none"}, frontend=${tmpl.frontend || "none"}`);
-        if (pa.isMultiStack) console.log(`    mode: 🔀 multi-stack`);
-      } else {
-        console.log(`    template: ${tmpl || "?"}`);
-      }
-    }
-  }
-
-  // ─── 2. domain-groups.json ─────────────────────────────
-  console.log("  [2/4] domain-groups.json...");
-  const dg = validateJson(
-    path.join(GEN_DIR, "domain-groups.json"),
-    ["generatedAt", "totalDomains", "totalGroups", "groups"],
-    []
-  );
-  if (dg) {
-    if (!Array.isArray(dg.groups)) {
-      errors.push({ file: "domain-groups.json", type: "INVALID_GROUPS", msg: "groups is not an array" });
-    } else {
-      console.log(`    ${dg.totalGroups} groups, ${dg.totalDomains} domains`);
-    }
-  }
-
-  // ─── 3. pass1-*.json ──────────────────────────────────
-  console.log("  [3/4] pass1-*.json...");
-  const pass1JsonFiles = await glob("pass1-*.json", { cwd: GEN_DIR, absolute: true });
-  if (pass1JsonFiles.length === 0) {
-    warnings.push({ file: "pass1-*.json", type: "NO_FILES", msg: "No pass1 JSON found (not yet executed?)" });
-  }
-  for (const f of pass1JsonFiles) {
-    const data = validateJson(f,
-      ["analyzedAt", "passNum", "domains", "analysisPerDomain"],
-      ["crossDomainCommon"]
-    );
-    if (data) {
-      if (!Array.isArray(data.domains) || data.domains.length === 0) {
-        warnings.push({ file: rel(f), type: "EMPTY_DOMAINS", msg: "No analyzed domains found" });
-      }
-      if (typeof data.analysisPerDomain !== "object") {
-        errors.push({ file: rel(f), type: "INVALID_ANALYSIS", msg: "analysisPerDomain is not an object" });
-      } else {
-        const domainCount = Object.keys(data.analysisPerDomain).length;
-        console.log(`    ${path.basename(f)}: ${domainCount} domains analyzed`);
-      }
-    }
-  }
-
-  // ─── 4. pass2-merged.json ─────────────────────────────
-  console.log("  [4/4] pass2-merged.json...");
-  const p2path = path.join(GEN_DIR, "pass2-merged.json");
-  if (!fs.existsSync(p2path)) {
-    warnings.push({ file: "pass2-merged.json", type: "NO_FILE", msg: "Not yet generated (Pass 2 not executed?)" });
-  } else {
-    checked++;
-    let data;
-    try {
-      data = JSON.parse(fs.readFileSync(p2path, "utf-8"));
-    } catch (e) {
-      errors.push({ file: "pass2-merged.json", type: "PARSE_ERROR", msg: `JSON parse failed: ${e.message}` });
-      data = null;
-    }
-
-    if (data) {
-      const keys = Object.keys(data);
-      console.log(`    ${keys.length} top-level keys: ${keys.slice(0, 5).join(", ")}${keys.length > 5 ? " ..." : ""}`);
-
-      // Required sections common to all stacks (intersection of all 5 stack pass2 prompts)
-      const REQUIRED_SECTIONS = [
-        "commonPatterns",      // 1. Universal patterns
-        "sharedPatterns",      // 2. Majority patterns
-        "domainSpecific",      // 3. Domain-specific patterns
-        "antiPatterns",        // 4. Anti-pattern summary
-        "namingConventions",   // 5. Naming conventions summary
-        "commonUtilities",     // 6. Common classes/utilities list
-        "security",            // 7. Security/auth patterns
-        "testing",             // 9. Testing strategy summary
-        "logging",             // 10. Logging/monitoring strategy
-        "codeQuality",         // 12. Code quality tools
-      ];
-
-      // Sections only in backend stacks (java/node-express/django/fastapi/kotlin)
-      const BACKEND_SECTIONS = [
-        "database",            // 8. DB patterns
-        "performance",         // 11. Performance patterns
-      ];
-
-      // Sections only in kotlin-spring with CQRS/BFF/multi-module detected
-      const KOTLIN_CQRS_SECTIONS = [
-        "bffPatterns",              // 7. BFF patterns summary
-        "interModuleCommunication", // Inter-module communication
-      ];
-      // Sections for all kotlin-spring projects (regardless of CQRS)
-      const KOTLIN_BASE_SECTIONS = [
-        "buildModulePatterns",      // 13. Build & module patterns
-      ];
-
-      // Check stack from project-analysis.json
-      const paPath = path.join(GEN_DIR, "project-analysis.json");
-      let isBackend = true; // Default: also validate backend sections
-      let isKotlin = false;
-      let isKotlinCqrs = false;
-      if (fs.existsSync(paPath)) {
-        try {
-          const paData = JSON.parse(fs.readFileSync(paPath, "utf-8"));
-          const frontend = paData.stack?.frontend;
-          const framework = paData.stack?.framework;
-          const language = paData.stack?.language;
-          const architecture = paData.stack?.architecture;
-          isBackend = !frontend || ["express", "nestjs", "fastify", "django", "fastapi", "flask", "spring-boot"].includes(framework);
-          isKotlin = language === "kotlin";
-          isKotlinCqrs = isKotlin && (architecture === "cqrs" || paData.stack?.multiModule);
-        } catch (_e) { /* If project-analysis parsing fails, conservatively assume backend */ }
-      }
-
-      const sectionsToCheck = [
-        ...REQUIRED_SECTIONS,
-        ...(isBackend ? BACKEND_SECTIONS : []),
-        ...(isKotlin ? KOTLIN_BASE_SECTIONS : []),
-        ...(isKotlinCqrs ? KOTLIN_CQRS_SECTIONS : []),
-      ];
-
-      // Key existence validation (case-insensitive fuzzy matching)
-      // Normalize a key to a comparable form: lowercase, strip separators
-      const normalize = (s) => s.toLowerCase().replace(/[_\-\s]/g, "");
-      const normalizedKeys = keys.map(normalize);
-      for (const section of sectionsToCheck) {
-        const sectionNorm = normalize(section);
-        // Exact normalized match first, then check if any key contains the section name (one-direction only to avoid false positives)
-        const found = normalizedKeys.some(k => k === sectionNorm)
-          || (sectionNorm.length >= 6 && normalizedKeys.some(k => k.includes(sectionNorm)));
-        if (!found) {
-          warnings.push({
-            file: "pass2-merged.json",
-            type: "MISSING_SECTION",
-            msg: `'${section}' section missing (Claude may have used a different key name)`,
-          });
-        }
-      }
-
-      // Top-level key count validation
-      if (keys.length < 5) {
-        errors.push({
-          file: "pass2-merged.json",
-          type: "INSUFFICIENT_KEYS",
-          msg: `Only ${keys.length} top-level keys — merge is incomplete (minimum 5 required)`,
-        });
-      } else if (keys.length < 9) {
-        warnings.push({
-          file: "pass2-merged.json",
-          type: "FEW_KEYS",
-          msg: `${keys.length} top-level keys — some sections may be missing (recommended 9+)`,
-        });
-      }
-
-      // Value depth validation — detect empty objects/arrays
-      let emptyCount = 0;
-      for (const [k, v] of Object.entries(data)) {
-        const isEmpty =
-          v === null ||
-          v === "" ||
-          (Array.isArray(v) && v.length === 0) ||
-          (typeof v === "object" && !Array.isArray(v) && Object.keys(v).length === 0);
-        if (isEmpty) emptyCount++;
-      }
-      if (emptyCount > 0) {
-        warnings.push({
-          file: "pass2-merged.json",
-          type: "EMPTY_VALUES",
-          msg: `${emptyCount} items have empty values — analysis content may be missing`,
-        });
-      }
-
-      const missingCount = warnings.filter(w => w.file === "pass2-merged.json" && w.type === "MISSING_SECTION").length;
-      if (missingCount === 0 && keys.length >= 9) {
-        console.log(`    ✅ Structure validation passed (${keys.length} keys, ${emptyCount} empty values)`);
-      }
-    }
-  }
-
-  // ─── Output results ─────────────────────────────────────────
-  console.log(`\n  Checked ${checked} files\n`);
-  if (errors.length) {
-    console.log(`  ❌ ERRORS (${errors.length}):`);
-    errors.forEach(e => console.log(`     [${e.type}] ${e.file}: ${e.msg}`));
-    console.log();
-  }
-  if (warnings.length) {
-    console.log(`  ⚠️  WARNINGS (${warnings.length}):`);
-    warnings.forEach(w => console.log(`     [${w.type}] ${w.file}: ${w.msg}`));
-    console.log();
-  }
-  if (!errors.length && !warnings.length) {
-    console.log("  ✅ All JSON validation passed\n");
-  }
-
-  // Record in stale-report
-  updateStaleReport(GEN_DIR, "jsonValidation",
-    { checkedAt: new Date().toISOString(), checked, errors: errors.length, warnings: warnings.length },
-    { jsonErrors: errors.length, jsonWarnings: warnings.length }
-  );
-
-  console.log(`  Total: ${errors.length} errors, ${warnings.length} warnings\n`);
-  process.exit(errors.length > 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 — Pass JSON Validator
+ *
+ * Role: Validate format and required keys of JSON files generated by Pass 1-3
+ * Validation items:
+ *   - JSON is parseable
+ *   - pass1-*.json: analyzedAt, passNum, domains, analysisPerDomain keys exist
+ *   - pass2-merged.json: fuzzy validation of common required sections (10) + backend sections (2)
+ *                        empty value detection, top-level key count check (<5 ERROR, <9 WARNING)
+ *   - project-analysis.json: stack, domains, frontend, summary keys exist
+ *
+ * Usage: npx claudeos-core <cmd> or node claudeos-core-tools/pass-json-validator/index.js
+ */
+
+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_DIR = path.join(ROOT, "claudeos-core/generated");
+
+function rel(p) { return path.relative(ROOT, p).replace(/\\/g, "/"); }
+
+async function main() {
+  console.log("\n╔═══════════════════════════════════════╗");
+  console.log("║  ClaudeOS-Core — Pass JSON Validator  ║");
+  console.log("╚═══════════════════════════════════════╝\n");
+
+  if (!fs.existsSync(GEN_DIR)) {
+    console.log("  ❌ claudeos-core/generated/ directory not found\n");
+    process.exit(1);
+  }
+
+  const errors = [];
+  const warnings = [];
+  let checked = 0;
+
+  // ─── Helpers: JSON parse + key validation ────────────────────────
+  function validateJson(filePath, requiredKeys, optionalKeys) {
+    const r = rel(filePath);
+    if (!fs.existsSync(filePath)) {
+      errors.push({ file: r, type: "MISSING", msg: "File not found" });
+      return null;
+    }
+    checked++;
+    let data;
+    try {
+      const raw = fs.readFileSync(filePath, "utf-8");
+      data = JSON.parse(raw);
+    } catch (e) {
+      errors.push({ file: r, type: "PARSE_ERROR", msg: `JSON parse failed: ${e.message}` });
+      return null;
+    }
+
+    for (const key of requiredKeys) {
+      if (!(key in data)) {
+        errors.push({ file: r, type: "MISSING_KEY", msg: `Required key '${key}' missing` });
+      }
+    }
+    for (const key of (optionalKeys || [])) {
+      if (!(key in data)) {
+        warnings.push({ file: r, type: "MISSING_KEY", msg: `Recommended key '${key}' missing` });
+      }
+    }
+    return data;
+  }
+
+  // ─── 1. project-analysis.json ──────────────────────────
+  console.log("  [1/5] project-analysis.json...");
+  const pa = validateJson(
+    path.join(GEN_DIR, "project-analysis.json"),
+    ["analyzedAt", "stack", "domains", "frontend", "summary"],
+    ["lang", "template", "templates", "rootPackage", "activeDomains"]
+  );
+  if (pa) {
+    if (!pa.stack || !pa.stack.language) {
+      errors.push({ file: "project-analysis.json", type: "INVALID_STACK", msg: "stack.language is missing" });
+    }
+    if (!Array.isArray(pa.domains)) {
+      errors.push({ file: "project-analysis.json", type: "INVALID_DOMAINS", msg: "domains is not an array" });
+    } else {
+      console.log(`    stack: ${pa.stack?.language || "?"} / ${pa.stack?.framework || "?"}`);
+      console.log(`    domains: ${pa.domains.length}`);
+      console.log(`    lang: ${pa.lang || "en (default)"}`);
+      const tmpl = pa.templates || pa.template;
+      if (tmpl && typeof tmpl === "object") {
+        console.log(`    templates: backend=${tmpl.backend || "none"}, frontend=${tmpl.frontend || "none"}`);
+        if (pa.isMultiStack) console.log(`    mode: 🔀 multi-stack`);
+      } else {
+        console.log(`    template: ${tmpl || "?"}`);
+      }
+    }
+  }
+
+  // ─── 2. domain-groups.json ─────────────────────────────
+  console.log("  [2/5] domain-groups.json...");
+  const dg = validateJson(
+    path.join(GEN_DIR, "domain-groups.json"),
+    ["generatedAt", "totalDomains", "totalGroups", "groups"],
+    []
+  );
+  if (dg) {
+    if (!Array.isArray(dg.groups)) {
+      errors.push({ file: "domain-groups.json", type: "INVALID_GROUPS", msg: "groups is not an array" });
+    } else {
+      console.log(`    ${dg.totalGroups} groups, ${dg.totalDomains} domains`);
+    }
+  }
+
+  // ─── 3. pass1-*.json ──────────────────────────────────
+  console.log("  [3/5] pass1-*.json...");
+  const pass1JsonFiles = await glob("pass1-*.json", { cwd: GEN_DIR, absolute: true });
+  if (pass1JsonFiles.length === 0) {
+    warnings.push({ file: "pass1-*.json", type: "NO_FILES", msg: "No pass1 JSON found (not yet executed?)" });
+  }
+  for (const f of pass1JsonFiles) {
+    const data = validateJson(f,
+      ["analyzedAt", "passNum", "domains", "analysisPerDomain"],
+      ["crossDomainCommon"]
+    );
+    if (data) {
+      if (!Array.isArray(data.domains) || data.domains.length === 0) {
+        warnings.push({ file: rel(f), type: "EMPTY_DOMAINS", msg: "No analyzed domains found" });
+      }
+      if (typeof data.analysisPerDomain !== "object") {
+        errors.push({ file: rel(f), type: "INVALID_ANALYSIS", msg: "analysisPerDomain is not an object" });
+      } else {
+        const domainCount = Object.keys(data.analysisPerDomain).length;
+        console.log(`    ${path.basename(f)}: ${domainCount} domains analyzed`);
+      }
+    }
+  }
+
+  // ─── 4. pass2-merged.json ─────────────────────────────
+  console.log("  [4/5] pass2-merged.json...");
+  const p2path = path.join(GEN_DIR, "pass2-merged.json");
+  if (!fs.existsSync(p2path)) {
+    warnings.push({ file: "pass2-merged.json", type: "NO_FILE", msg: "Not yet generated (Pass 2 not executed?)" });
+  } else {
+    checked++;
+    let data;
+    try {
+      data = JSON.parse(fs.readFileSync(p2path, "utf-8"));
+    } catch (e) {
+      errors.push({ file: "pass2-merged.json", type: "PARSE_ERROR", msg: `JSON parse failed: ${e.message}` });
+      data = null;
+    }
+
+    if (data) {
+      const keys = Object.keys(data);
+      console.log(`    ${keys.length} top-level keys: ${keys.slice(0, 5).join(", ")}${keys.length > 5 ? " ..." : ""}`);
+
+      // Required sections common to all stacks (intersection of all 5 stack pass2 prompts)
+      const REQUIRED_SECTIONS = [
+        "commonPatterns",      // 1. Universal patterns
+        "sharedPatterns",      // 2. Majority patterns
+        "domainSpecific",      // 3. Domain-specific patterns
+        "antiPatterns",        // 4. Anti-pattern summary
+        "namingConventions",   // 5. Naming conventions summary
+        "commonUtilities",     // 6. Common classes/utilities list
+        "security",            // 7. Security/auth patterns
+        "testing",             // 9. Testing strategy summary
+        "logging",             // 10. Logging/monitoring strategy
+        "codeQuality",         // 12. Code quality tools
+      ];
+
+      // Sections only in backend stacks (java/node-express/django/fastapi/kotlin)
+      const BACKEND_SECTIONS = [
+        "database",            // 8. DB patterns
+        "performance",         // 11. Performance patterns
+      ];
+
+      // Sections only in kotlin-spring with CQRS/BFF/multi-module detected
+      const KOTLIN_CQRS_SECTIONS = [
+        "bffPatterns",              // 7. BFF patterns summary
+        "interModuleCommunication", // Inter-module communication
+      ];
+      // Sections for all kotlin-spring projects (regardless of CQRS)
+      const KOTLIN_BASE_SECTIONS = [
+        "buildModulePatterns",      // 13. Build & module patterns
+      ];
+
+      // Check stack from project-analysis.json
+      const paPath = path.join(GEN_DIR, "project-analysis.json");
+      let isBackend = true; // Default: also validate backend sections
+      let isKotlin = false;
+      let isKotlinCqrs = false;
+      if (fs.existsSync(paPath)) {
+        try {
+          const paData = JSON.parse(fs.readFileSync(paPath, "utf-8"));
+          const frontend = paData.stack?.frontend;
+          const framework = paData.stack?.framework;
+          const language = paData.stack?.language;
+          const architecture = paData.stack?.architecture;
+          isBackend = !frontend || ["express", "nestjs", "fastify", "django", "fastapi", "flask", "spring-boot"].includes(framework);
+          isKotlin = language === "kotlin";
+          isKotlinCqrs = isKotlin && (architecture === "cqrs" || paData.stack?.multiModule);
+        } catch (_e) { /* If project-analysis parsing fails, conservatively assume backend */ }
+      }
+
+      const sectionsToCheck = [
+        ...REQUIRED_SECTIONS,
+        ...(isBackend ? BACKEND_SECTIONS : []),
+        ...(isKotlin ? KOTLIN_BASE_SECTIONS : []),
+        ...(isKotlinCqrs ? KOTLIN_CQRS_SECTIONS : []),
+      ];
+
+      // Key existence validation (case-insensitive fuzzy matching)
+      // Normalize a key to a comparable form: lowercase, strip separators
+      const normalize = (s) => s.toLowerCase().replace(/[_\-\s]/g, "");
+      const normalizedKeys = keys.map(normalize);
+      for (const section of sectionsToCheck) {
+        const sectionNorm = normalize(section);
+        // Exact normalized match first, then check if any key contains the section name (one-direction only to avoid false positives)
+        const found = normalizedKeys.some(k => k === sectionNorm)
+          || (sectionNorm.length >= 6 && normalizedKeys.some(k => k.includes(sectionNorm)));
+        if (!found) {
+          warnings.push({
+            file: "pass2-merged.json",
+            type: "MISSING_SECTION",
+            msg: `'${section}' section missing (Claude may have used a different key name)`,
+          });
+        }
+      }
+
+      // Top-level key count validation
+      if (keys.length < 5) {
+        errors.push({
+          file: "pass2-merged.json",
+          type: "INSUFFICIENT_KEYS",
+          msg: `Only ${keys.length} top-level keys — merge is incomplete (minimum 5 required)`,
+        });
+      } else if (keys.length < 9) {
+        warnings.push({
+          file: "pass2-merged.json",
+          type: "FEW_KEYS",
+          msg: `${keys.length} top-level keys — some sections may be missing (recommended 9+)`,
+        });
+      }
+
+      // Value depth validation — detect empty objects/arrays
+      let emptyCount = 0;
+      for (const [k, v] of Object.entries(data)) {
+        const isEmpty =
+          v === null ||
+          v === "" ||
+          (Array.isArray(v) && v.length === 0) ||
+          (typeof v === "object" && !Array.isArray(v) && Object.keys(v).length === 0);
+        if (isEmpty) emptyCount++;
+      }
+      if (emptyCount > 0) {
+        warnings.push({
+          file: "pass2-merged.json",
+          type: "EMPTY_VALUES",
+          msg: `${emptyCount} items have empty values — analysis content may be missing`,
+        });
+      }
+
+      const missingCount = warnings.filter(w => w.file === "pass2-merged.json" && w.type === "MISSING_SECTION").length;
+      if (missingCount === 0 && keys.length >= 9) {
+        console.log(`    ✅ Structure validation passed (${keys.length} keys, ${emptyCount} empty values)`);
+      }
+    }
+  }
+
+  // ─── 5a. pass3-complete.json (optional) ──────────────────
+  console.log("  [5a/5] pass3-complete.json (optional)...");
+  const p3path = path.join(GEN_DIR, "pass3-complete.json");
+  if (fs.existsSync(p3path)) {
+    const p3 = validateJson(p3path, ["completedAt"], ["backfilled", "reason"]);
+    if (p3) {
+      if (typeof p3.completedAt !== "string" || !/^\d{4}-\d{2}-\d{2}T/.test(p3.completedAt)) {
+        warnings.push({ file: "pass3-complete.json", type: "INVALID_TIMESTAMP", msg: `completedAt should be ISO 8601 (got ${JSON.stringify(p3.completedAt)})` });
+      } else {
+        console.log(`    ✅ completedAt=${p3.completedAt}${p3.backfilled ? " (backfilled)" : ""}`);
+      }
+    }
+  } else {
+    console.log("    ⏭️  not present (Pass 3 not yet run)");
+  }
+
+  // ─── 5b. pass4-memory.json (optional) ─────────────
+  console.log("  [5b/5] pass4-memory.json (optional)...");
+  const p4path = path.join(GEN_DIR, "pass4-memory.json");
+  if (fs.existsSync(p4path)) {
+    const p4 = validateJson(p4path,
+      ["analyzedAt", "passNum", "memoryFiles"],
+      ["planFiles", "ruleFiles", "seededDecisions", "fallback"]
+    );
+    if (p4) {
+      if (typeof p4.passNum !== "number" || p4.passNum !== 4) {
+        errors.push({ file: "pass4-memory.json", type: "INVALID_PASS_NUM", msg: `passNum must be number 4 (got ${JSON.stringify(p4.passNum)})` });
+      }
+      if (!Array.isArray(p4.memoryFiles) || p4.memoryFiles.length !== 4) {
+        errors.push({ file: "pass4-memory.json", type: "INVALID_MEMORY", msg: `memoryFiles must be an array of 4 paths (got ${Array.isArray(p4.memoryFiles) ? p4.memoryFiles.length : typeof p4.memoryFiles})` });
+      } else {
+        console.log(`    ✅ passNum=${p4.passNum}, memory=${p4.memoryFiles.length}${p4.fallback ? " (fallback)" : ""}`);
+      }
+    }
+  } else {
+    warnings.push({ file: "pass4-memory.json", type: "NO_FILE", msg: "Not yet generated (Pass 4 not executed?)" });
+  }
+
+  // ─── Output results ─────────────────────────────────────────
+  console.log(`\n  Checked ${checked} files\n`);
+  if (errors.length) {
+    console.log(`  ❌ ERRORS (${errors.length}):`);
+    errors.forEach(e => console.log(`     [${e.type}] ${e.file}: ${e.msg}`));
+    console.log();
+  }
+  if (warnings.length) {
+    console.log(`  ⚠️  WARNINGS (${warnings.length}):`);
+    warnings.forEach(w => console.log(`     [${w.type}] ${w.file}: ${w.msg}`));
+    console.log();
+  }
+  if (!errors.length && !warnings.length) {
+    console.log("  ✅ All JSON validation passed\n");
+  }
+
+  // Record in stale-report
+  updateStaleReport(GEN_DIR, "jsonValidation",
+    { checkedAt: new Date().toISOString(), checked, errors: errors.length, warnings: warnings.length },
+    { jsonErrors: errors.length, jsonWarnings: warnings.length }
+  );
+
+  console.log(`  Total: ${errors.length} errors, ${warnings.length} warnings\n`);
+  process.exit(errors.length > 0 ? 1 : 0);
+}
+
+if (require.main === module) {
+  main().catch(e => { console.error(`\n  ❌ Unexpected error: ${e.message || e}`); process.exit(1); });
+}
+
+module.exports = { main };