claudeos-core 2.0.2 → 2.1.0

package/plan-installer/pass3-context-builder.js

@@ -0,0 +1,258 @@
+/**
+ * ClaudeOS-Core — Pass 3 Context Builder
+ *
+ * Builds a slim `pass3-context.json` that Pass 3 prompts reference INSTEAD OF
+ * re-reading the full `pass2-merged.json` repeatedly. pass2-merged.json on
+ * large multi-module projects can exceed 300 KB, and Pass 3 historically
+ * re-reads it once per file generated (30-50 times), which is the #1 cause
+ * of `Prompt is too long` Pass 3 failures.
+ *
+ * Design constraints:
+ *   - pass2-merged.json is an LLM-generated free-form JSON: field names and
+ *     nesting vary by stack and by Claude's interpretation of the pass2
+ *     template. We CANNOT reliably project specific nested fields out of it.
+ *   - project-analysis.json IS structured (we wrote it ourselves in
+ *     plan-installer). We use it as the authoritative source for stack facts.
+ *   - pass2-merged.json is still useful as a file, so we report its
+ *     existence/size/top-level key count here as signals — the Pass 3 prompt
+ *     then knows whether to fall back to reading it for specific details.
+ *
+ * Output shape (see `buildPass3Context` return) is intentionally flat and
+ * small: <5 KB even for large projects, vs. pass2-merged.json at 50-500 KB.
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+/**
+ * Safely read + parse a JSON file. Returns null on any error.
+ * Mirrors lib/safe-fs.js readJsonSafe but inlined to avoid circular-dep risk
+ * during tool-time module loading (this file is called from plan-installer
+ * after all scanners have run).
+ */
+function readJsonSafe(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, "utf-8");
+    return JSON.parse(raw);
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * Describe pass2-merged.json as signals (size, top-level key count, existence)
+ * without loading its contents into the context JSON. Pass 3 prompts use these
+ * signals to decide whether to read the full file for a specific missing detail.
+ */
+function describePass2(pass2MergedPath) {
+  let exists = false;
+  let sizeBytes = 0;
+  let topLevelKeys = [];
+  try {
+    const stat = fs.statSync(pass2MergedPath);
+    exists = true;
+    sizeBytes = stat.size;
+    try {
+      const parsed = JSON.parse(fs.readFileSync(pass2MergedPath, "utf-8"));
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        topLevelKeys = Object.keys(parsed).slice(0, 40); // cap at 40 to keep context small
+      }
+    } catch (_e) {
+      // Malformed pass2-merged.json — leave topLevelKeys empty, still report size.
+    }
+  } catch (_e) {
+    // File doesn't exist yet (e.g. Pass 2 has not run). Still return a valid descriptor.
+  }
+  return {
+    exists,
+    sizeBytes,
+    sizeKB: Math.round(sizeBytes / 1024),
+    topLevelKeys,
+    // Heuristic flag: >300 KB is the empirical threshold above which repeated
+    // re-reads reliably cause Pass 3 context overflow on 200K-context models.
+    large: sizeBytes > 300 * 1024,
+  };
+}
+
+/**
+ * Extract domain summaries from project-analysis.json's domains array.
+ * Each entry in `domains` has varying fields depending on the scanner that
+ * produced it (scan-java, scan-kotlin, scan-node, scan-python, scan-frontend).
+ * We project only the fields that are universally useful for Pass 3 consistency.
+ */
+function summarizeDomains(analysisDomains) {
+  if (!Array.isArray(analysisDomains)) return [];
+  return analysisDomains.map((d) => {
+    const summary = {
+      name: d.name,
+      type: d.type || "backend",
+      totalFiles: d.totalFiles || 0,
+    };
+    // Optional, scanner-specific fields — only include if present.
+    if (typeof d.controllers === "number") summary.controllers = d.controllers;
+    if (typeof d.services === "number") summary.services = d.services;
+    if (typeof d.repositories === "number") summary.repositories = d.repositories;
+    if (typeof d.mappers === "number") summary.mappers = d.mappers;
+    if (typeof d.dtos === "number") summary.dtos = d.dtos;
+    if (typeof d.pages === "number") summary.pages = d.pages;
+    if (typeof d.components === "number") summary.components = d.components;
+    if (d.pattern) summary.pattern = d.pattern;          // Java A-E patterns
+    if (d.modulePath) summary.modulePath = d.modulePath; // multi-module Java
+    if (d.serverType) summary.serverType = d.serverType; // Kotlin CQRS server types
+    if (d.domainName) summary.domainName = d.domainName;
+    return summary;
+  });
+}
+
+/**
+ * Extract the port default from project-analysis.stack.port (plan-installer
+ * sets this based on framework). Kept as a top-level convenience field so
+ * Pass 3 doesn't need to traverse the nested stack object.
+ */
+function extractPort(projectAnalysis) {
+  return (projectAnalysis && projectAnalysis.stack && projectAnalysis.stack.port) || null;
+}
+
+/**
+ * Build the slim Pass 3 context object.
+ *
+ * @param {string} generatedDir - absolute path to claudeos-core/generated/
+ * @returns {object|null} context object, or null if project-analysis.json is
+ *   missing/malformed (caller should then NOT write pass3-context.json — Pass 3
+ *   will fall back to the full pass2-merged.json path).
+ */
+function buildPass3Context(generatedDir) {
+  const analysisPath = path.join(generatedDir, "project-analysis.json");
+  const pass2Path = path.join(generatedDir, "pass2-merged.json");
+
+  const analysis = readJsonSafe(analysisPath);
+  if (!analysis || typeof analysis !== "object") {
+    // Without project-analysis.json we have nothing structured to summarize.
+    // Let Pass 3 fall back to reading pass2-merged.json directly.
+    return null;
+  }
+
+  const stack = analysis.stack || {};
+  const summary = analysis.summary || {};
+  const active = analysis.activeDomains || {};
+
+  const context = {
+    _schemaVersion: 1,
+    _generatedAt: new Date().toISOString(),
+    _purpose:
+      "Slim, read-once summary for Pass 3 prompts. Reference this INSTEAD OF " +
+      "re-reading pass2-merged.json during file generation. Only consult " +
+      "pass2-merged.json for specific method names / exact paths not captured " +
+      "here — and only once per detail.",
+
+    // ─── Stack facts (authoritative — from project-analysis.json) ──────
+    stack: {
+      language: stack.language || null,
+      languageVersion: stack.languageVersion || null,
+      framework: stack.framework || null,
+      frameworkVersion: stack.frameworkVersion || null,
+      buildTool: stack.buildTool || null,
+      packageManager: stack.packageManager || null,
+      database: stack.database || null,
+      orm: stack.orm || null,
+      frontend: stack.frontend || null,
+      frontendVersion: stack.frontendVersion || null,
+      port: extractPort(analysis),
+    },
+
+    // ─── Architecture flags ──────────────────────────────────────────
+    architecture: {
+      cqrs: !!(stack.architecture && String(stack.architecture).includes("cqrs")),
+      bff: Array.isArray(stack.detected) && stack.detected.includes("bff"),
+      multiModule: !!stack.multiModule,
+      monorepo: stack.monorepo || null,
+      workspaces: stack.workspaces || null,
+      modules: Array.isArray(stack.modules) ? stack.modules : [],
+      rootPackage: analysis.rootPackage || null,
+    },
+
+    // ─── Active domain groups (which 00.core / 10.backend / ... apply) ──
+    activeDomains: active,
+
+    // ─── Template routing (what pass3 templates were combined) ──────────
+    templates: analysis.templates || {},
+    isMultiStack: !!analysis.isMultiStack,
+
+    // ─── Domain summary (flat list, small per-domain footprint) ─────────
+    domainCount: {
+      total: summary.totalDomains || 0,
+      backend: summary.backendDomains || 0,
+      frontend: summary.frontendDomains || 0,
+    },
+    backendDomains: summarizeDomains(analysis.backendDomains),
+    frontendDomains: summarizeDomains(analysis.frontendDomains),
+
+    // ─── Frontend stats (if scan-frontend ran) ──────────────────────────
+    frontend: analysis.frontend || { exists: false },
+
+    // ─── pass2-merged.json descriptor (signals, not contents) ───────────
+    // Pass 3 reads this to decide whether it's safe to open the full file
+    // for a specific missing detail, and how aggressively to summarize first.
+    pass2Merged: describePass2(pass2Path),
+
+    // ─── Split-mode recommendation (informational only) ─────────────────
+    // Heuristic that predicts whether single-call Pass 3 would likely hit
+    // `Prompt is too long`. Surfaced in init logs as "estimated N files
+    // from M domains". As of the current release this does NOT drive the
+    // split/single-call decision — init.js defaults to split mode for all
+    // projects regardless of this recommendation. Kept for diagnostic
+    // visibility and future use (e.g. token budget estimation, UI hints).
+    splitRecommendation: (function computeSplit() {
+      const pass2Desc = describePass2(pass2Path);
+      const backendCount = Array.isArray(analysis.backendDomains) ? analysis.backendDomains.length : 0;
+      const frontendCount = Array.isArray(analysis.frontendDomains) ? analysis.frontendDomains.length : 0;
+      const totalDomains = backendCount + frontendCount;
+
+      // Rough estimate: each domain yields 5-8 files (standards + rules + skills),
+      // plus ~15 stack-independent files (CLAUDE.md, guides, master plans, etc.).
+      const estimatedFileCount = 15 + totalDomains * 6;
+
+      // Thresholds calibrated from empirical failures:
+      //  - pass2 > 300KB: historic input-overflow threshold (v2.1 original heuristic)
+      //  - estimated files > 35: empirical output-accumulation threshold
+      //    (observed overflow at ~40 files with pass2=35KB — output was the cause)
+      const largeInput = pass2Desc.sizeBytes > 300 * 1024;
+      const largeOutput = estimatedFileCount > 35;
+      const recommend = largeInput || largeOutput;
+
+      return {
+        recommend,
+        reasons: [
+          largeInput ? `pass2-merged.json is ${pass2Desc.sizeKB} KB (> 300 KB input threshold)` : null,
+          largeOutput ? `estimated ${estimatedFileCount} output files (> 35 file threshold) from ${totalDomains} domains` : null,
+        ].filter(Boolean),
+        estimatedFileCount,
+        totalDomains,
+      };
+    })(),
+
+    // ─── Fields that pass2-merged.json is authoritative for ─────────────
+    // These are all `null` in pass3-context.json by design — Pass 3 must
+    // read pass2-merged.json ONCE (during the Phase 1 fact-table fill)
+    // to get their actual values. Listed here so Pass 3 knows exactly
+    // what to look for instead of free-form scanning.
+    needsPass2: {
+      responseWrapperLayer: null,       // "Controller" | "Aggregator" | "Service"
+      responseWrapperMethod: null,      // e.g. "makeResponse"
+      responseUtilClass: null,          // FQN, e.g. "com.company.util.ApiResponseUtil"
+      responseUtilMethods: null,        // ["success", "fail", ...] exact names
+      mapperXmlPath: null,              // verbatim, if MyBatis
+      aggregatorExists: null,
+      aggregatorNaming: null,
+      sharedBaseClasses: null,          // array of FQNs
+      sharedUtilPackage: null,
+      authMethod: null,                 // "JWT" | "Session" | "OAuth2" | ...
+    },
+  };
+
+  return context;
+}
+
+module.exports = { buildPass3Context, describePass2, summarizeDomains };

package/plan-installer/prompt-generator.js

@@ -28,6 +28,14 @@ function generatePrompts(templates, lang, templatesDir, generatedDir) {
   // claudeos-core/generated/.staged-rules/* to bypass Claude Code's sensitive-
   // path block. The Node.js orchestrator moves the staged files after each pass.
   const stagingOverride = existsSafe(stagingOverridePath) ? readFileSafe(stagingOverridePath) + "\n" : "";
+  // v2.1: Phase 1 "Read Once, Extract Facts" block prepended to every Pass 3
+  // prompt. Teaches Claude to read pass2-merged.json exactly once into a
+  // compact in-context fact table and reference that table for all subsequent
+  // file generation — fixes the `Prompt is too long` failure on large projects
+  // caused by 10-20× re-reads of pass2-merged.json. Also includes idempotent
+  // skip rules (Rule B) so interrupted Pass 3 runs can resume safely.
+  const phase1Path = path.join(commonDir, "pass3-phase1.md");
+  const phase1 = existsSafe(phase1Path) ? readFileSafe(phase1Path) + "\n" : "";
 
   let langInstruction = "";
   if (lang && lang !== "en" && existsSafe(langPath)) {
@@ -92,7 +100,7 @@ function generatePrompts(templates, lang, templatesDir, generatedDir) {
 
     writeFileSafe(
       path.join(generatedDir, "pass3-prompt.md"),
-      header + langInstruction + stagingOverride + combinedBody.trimEnd() + "\n" + footer
+      header + langInstruction + stagingOverride + phase1 + combinedBody.trimEnd() + "\n" + footer
     );
     console.log(`    ✅ pass3-prompt.md${templates.frontend && templates.backend ? " (multi-stack combined)" : ""}`);
   }

package/plan-validator/index.js

@@ -57,8 +57,14 @@ async function main() {
   console.log("╚═══════════════════════════════════════╝\n");
 
   if (!fs.existsSync(PLAN)) {
-    console.log("  ❌ Plan directory not found");
-    process.exit(1);
+    console.log("  ℹ️  Plan directory not present — nothing to validate.");
+    console.log("     (Master plans are no longer generated by default; this is normal.)\n");
+    // Emit empty stale-report block so health-checker summary is consistent.
+    updateStaleReport(GEN, "planValidation",
+      { checkedAt: new Date().toISOString(), mode, total: 0, synced: 0, drift: 0, missing: 0 },
+      { planDrift: 0, planMissing: 0 }
+    );
+    process.exit(0);
   }
 
   let total = 0, synced = 0, drift = 0, missing = 0;
@@ -145,13 +151,22 @@ async function main() {
   console.log(drift + missing === 0 ? "  ✅ All plans in sync\n" : `  ⚠️  ${drift + missing} issues\n`);
 
   // ─── Update plan-sync-status.json + stale-report.json ──
+  // v2.1.0: master plan generation was removed. When plan/ exists but contains
+  // no .md files (legacy directory skeleton), we skip plan-sync-status.json
+  // entirely — writing a 147 B file full of zeros is noise. stale-report still
+  // records the (passing) validation run so health-checker sees a clean result.
+  // Note: plan/ missing entirely is already handled by the early-return at
+  // the top of main() (line ~59), so by here PLAN exists — but may be empty.
+  const planHasFiles = fs.readdirSync(PLAN).some(f => f.endsWith(".md"));
   if (fs.existsSync(GEN)) {
-    fs.writeFileSync(
-      path.join(GEN, "plan-sync-status.json"),
-      JSON.stringify({ generatedAt: new Date().toISOString(), lastMode: mode, total, synced, drift, missing, issues: results }, null, 2)
-    );
-
-    // Also write to stale-report.json for consolidated health reporting
+    if (planHasFiles) {
+      fs.writeFileSync(
+        path.join(GEN, "plan-sync-status.json"),
+        JSON.stringify({ generatedAt: new Date().toISOString(), lastMode: mode, total, synced, drift, missing, issues: results }, null, 2)
+      );
+    }
+    // stale-report is always updated so health-checker sees a consistent
+    // planValidation entry regardless of plan/ contents.
     updateStaleReport(GEN, "planValidation",
       { checkedAt: new Date().toISOString(), mode, total, synced, drift, missing },
       { planDrift: drift, planMissing: missing }

package/sync-checker/index.js

@@ -50,7 +50,27 @@ async function main() {
   console.log("║  ClaudeOS-Core — Sync Checker         ║");
   console.log("╚═══════════════════════════════════════╝\n");
 
+  // Master plan directory is optional. If it doesn't exist (new default for
+  // claudeos-core, since master plans are no longer generated) AND sync-map
+  // has no mappings to validate, sync-checker has nothing to compare against
+  // and should skip cleanly. This is a PASS state, not a failure.
+  //
+  // However, if sync-map.json DOES contain mappings (either because master
+  // plans exist, or because a caller wrote mappings directly for testing),
+  // we still validate them normally.
+  const PLAN_DIR = path.join(ROOT, "claudeos-core/plan");
+  const planExists = fs.existsSync(PLAN_DIR);
+
   if (!fs.existsSync(SMP)) {
+    // No sync-map at all.
+    if (!planExists) {
+      console.log("  ℹ️  No plan/ directory and no sync-map.json — nothing to compare; skipping.\n");
+      updateStaleReport(GEN, "syncMisses",
+        { checkedAt: new Date().toISOString(), unregistered: [], orphaned: [], skipped: true },
+        { syncIssues: 0, status: "ok" }
+      );
+      process.exit(0);
+    }
     console.log("  ❌ sync-map.json not found. Run manifest-generator first.\n");
     process.exit(1);
   }
@@ -66,6 +86,30 @@ async function main() {
     console.log("  ❌ sync-map.json has no mappings array.\n");
     process.exit(1);
   }
+
+  // If sync-map has no mappings AND plan/ directory doesn't exist, skip
+  // cleanly — there's no ground truth to validate against and no master plans
+  // in use.
+  if (sm.mappings.length === 0 && !planExists) {
+    console.log("  ℹ️  No plan/ directory and sync-map has no mappings — skipping.\n");
+    updateStaleReport(GEN, "syncMisses",
+      { checkedAt: new Date().toISOString(), unregistered: [], orphaned: [], skipped: true },
+      { syncIssues: 0, status: "ok" }
+    );
+    process.exit(0);
+  }
+
+  // If sync-map has no mappings but plan/ exists (e.g., empty plan files),
+  // skip without raising a warning — there's nothing to validate.
+  if (sm.mappings.length === 0) {
+    console.log("  ℹ️  sync-map has no mappings — nothing to validate; skipping.\n");
+    updateStaleReport(GEN, "syncMisses",
+      { checkedAt: new Date().toISOString(), unregistered: [], orphaned: [], skipped: true },
+      { syncIssues: 0, status: "ok" }
+    );
+    process.exit(0);
+  }
+
   const reg = new Set(sm.mappings.map((m) => m.sourcePath).filter(Boolean));
   const issues = { unreg: [], orphan: [] };