claudeos-core 1.2.4 → 1.3.1

package/lib/safe-fs.js

@@ -0,0 +1,110 @@
+/**
+ * ClaudeOS-Core — Safe filesystem utilities
+ *
+ * Wraps fs operations with consistent error handling.
+ * All read functions return a fallback value on failure instead of throwing.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+/**
+ * Safely read a file as UTF-8 string.
+ * @param {string} filePath
+ * @param {string} [fallback=""] - returned on error
+ * @returns {string}
+ */
+function readFileSafe(filePath, fallback = "") {
+  try {
+    return fs.readFileSync(filePath, "utf-8");
+  } catch (e) {
+    if (e.code !== "ENOENT") {
+      console.warn(`    ⚠️  Cannot read ${path.basename(filePath)}: ${e.code || e.message}`);
+    }
+    return fallback;
+  }
+}
+
+/**
+ * Safely parse a JSON file.
+ * @param {string} filePath
+ * @param {*} [fallback=null] - returned on error
+ * @returns {*}
+ */
+function readJsonSafe(filePath, fallback = null) {
+  const raw = readFileSafe(filePath, null);
+  if (raw === null) return fallback;
+  try {
+    return JSON.parse(raw);
+  } catch (e) {
+    console.warn(`    ⚠️  JSON parse error in ${path.basename(filePath)}: ${e.message}`);
+    return fallback;
+  }
+}
+
+/**
+ * Check if a file exists (swallows permission errors).
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+function existsSafe(filePath) {
+  try {
+    return fs.existsSync(filePath);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Ensure a directory exists (recursive).
+ * @param {string} dir
+ */
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * Write a file with error reporting.
+ * @param {string} filePath
+ * @param {string} content
+ * @returns {boolean} success
+ */
+function writeFileSafe(filePath, content) {
+  try {
+    fs.writeFileSync(filePath, content);
+    return true;
+  } catch (e) {
+    console.error(`    ❌ Cannot write ${path.basename(filePath)}: ${e.code || e.message}`);
+    return false;
+  }
+}
+
+/**
+ * Get file stat safely.
+ * @param {string} filePath
+ * @returns {{ lines: number, bytes: number, modified: string } | null}
+ */
+function statSafe(filePath) {
+  try {
+    const c = fs.readFileSync(filePath, "utf-8");
+    const s = fs.statSync(filePath);
+    return {
+      lines: c.split("\n").length,
+      bytes: s.size,
+      modified: s.mtime.toISOString().split("T")[0],
+    };
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  readFileSafe,
+  readJsonSafe,
+  existsSafe,
+  ensureDir,
+  writeFileSafe,
+  statSafe,
+};

package/manifest-generator/index.js

@@ -67,9 +67,9 @@ function extractFileBlocks(f) {
 }
 
 async function main() {
-  console.log("\n╔══════════════════════════════════════╗");
+  console.log("\n╔═══════════════════════════════════════╗");
   console.log("║  ClaudeOS-Core — Manifest Generator   ║");
-  console.log("╚══════════════════════════════════════╝\n");
+  console.log("╚═══════════════════════════════════════╝\n");
 
   if (!fs.existsSync(GEN)) fs.mkdirSync(GEN, { recursive: true });
 
@@ -142,11 +142,17 @@ async function main() {
   fs.writeFileSync(path.join(GEN, "plan-manifest.json"), JSON.stringify(pm, null, 2));
   console.log(`  ✅ plan-manifest.json — ${pm.plans.length} plans`);
 
-  // ─── Initialize stale-report.json ──────────────────────────
-  fs.writeFileSync(
-    path.join(GEN, "stale-report.json"),
-    JSON.stringify({ generatedAt: new Date().toISOString(), summary: { totalIssues: 0, status: "initial" } }, null, 2)
-  );
+  // ─── Initialize stale-report.json (preserve existing sub-tool results) ──
+  const srPath = path.join(GEN, "stale-report.json");
+  let sr = {};
+  if (fs.existsSync(srPath)) {
+    try { sr = JSON.parse(fs.readFileSync(srPath, "utf-8")); } catch { sr = {}; }
+  }
+  sr.generatedAt = new Date().toISOString();
+  if (!sr.summary) sr.summary = {};
+  sr.summary.totalIssues = 0;
+  sr.summary.status = "initial";
+  fs.writeFileSync(srPath, JSON.stringify(sr, null, 2));
   console.log("  ✅ stale-report.json — initialized");
   console.log("\n  📁 Output: claudeos-core/generated/ (4 files)\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudeos-core",
-  "version": "1.2.4",
+  "version": "1.3.1",
   "description": "Auto-generate Claude Code documentation from your actual source code — Standards, Rules, Skills, and Guides tailored to your project",
   "main": "bin/cli.js",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "bin/",
+    "lib/",
     "content-validator/",
     "health-checker/",
     "manifest-generator/",
@@ -37,7 +38,8 @@
     "validate": "node bin/cli.js validate",
     "refresh": "node bin/cli.js refresh",
     "restore": "node bin/cli.js restore",
-    "test": "node health-checker/index.js"
+    "test": "node --test tests/*.test.js",
+    "test:health": "node health-checker/index.js"
   },
   "keywords": [
     "claude-code",

package/pass-json-validator/index.js

@@ -24,9 +24,9 @@ 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("\n╔═══════════════════════════════════════╗");
   console.log("║  ClaudeOS-Core — Pass JSON Validator  ║");
-  console.log("╚══════════════════════════════════════╝\n");
+  console.log("╚═══════════════════════════════════════╝\n");
 
   if (!fs.existsSync(GEN_DIR)) {
     console.log("  ❌ claudeos-core/generated/ directory not found\n");
@@ -111,9 +111,7 @@ async function main() {
 
   // ─── 3. pass1-*.json ──────────────────────────────────
   console.log("  [3/4] pass1-*.json...");
-  const pass1Files = await glob("pass1-*.json", { cwd: GEN_DIR, absolute: true });
-  // Exclude pass1-prompt.md
-  const pass1JsonFiles = pass1Files.filter(f => f.endsWith(".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?)" });
   }

package/pass-prompts/templates/java-spring/pass1.md

@@ -12,6 +12,7 @@ Analysis items (per domain):
    - URL patterns (RESTful conventions, naming conventions, versioning)
    - Parameter binding (@RequestBody, @PathVariable, @RequestParam, @ModelAttribute, @RequestHeader)
    - Response format (ResponseEntity, custom response wrappers, direct return)
+   - If a custom response wrapper class exists, record its EXACT class name, EXACT method signatures (e.g., `success()`, `error()`), and EXACT import path. Do NOT guess or invent method names — read the actual source.
    - Error handling (try-catch patterns, @ExceptionHandler, @ControllerAdvice)
    - Authentication/authorization (@AuthenticationPrincipal, @PreAuthorize, SecurityContext)
    - API documentation (Swagger/SpringDoc annotations)
@@ -47,6 +48,8 @@ Analysis items (per domain):
    - Field type conventions (Boolean handling, date types, Enum management)
    - Validation annotations (@NotNull, @NotBlank, @Size, @Pattern, custom)
    - Conversion approach (MapStruct, ModelMapper, manual conversion)
+   - Import paths: record EXACT package paths for shared/utility classes
+   - Utility class locations: record EXACT package where shared utilities live
 
 5. Interceptor/Filter/AOP Patterns
    - HandlerInterceptor usage
@@ -93,7 +96,7 @@ Analysis items (per domain):
     - Performance issues (N+1, unnecessary queries, memory waste)
     - Security issues (SQL Injection potential, missing authorization)
 
-Do not create files. Analysis only.
+Do not create or modify source files. Analysis only.
 Save results to claudeos-core/generated/pass1-{{PASS_NUM}}.json in the following format:
 
 {

package/pass-prompts/templates/java-spring/pass2.md

@@ -35,9 +35,9 @@ Merge items:
    - DB table/column naming
 
 6. Common Classes/Utilities List
-   - Base class fields (must not be redeclared)
-   - Shared utility classes
-   - Constants/Enum management approach
+   - Base class fields (must not be redeclared) with EXACT fully-qualified class names
+   - Shared utility classes with EXACT package paths (e.g., `com.company.common.util.DateUtils`)
+   - Constants/Enum management approach with EXACT locations
 
 7. Security/Authentication Patterns
    - Authentication method (JWT, Session, OAuth2)

package/pass-prompts/templates/java-spring/pass3.md

@@ -4,6 +4,31 @@ generate all ClaudeOS-Core files based on the analysis results.
 
 Do not read the original source code again. Reference only the analysis results.
 
+CRITICAL — Build Tool Consistency:
+Check `stack.buildTool` and `stack.packageManager` in project-analysis.json.
+ALL generated files MUST use the detected build tool's commands (e.g., Gradle or Maven).
+NEVER mix Gradle/Maven commands. Also verify actual task names from build files.
+
+CRITICAL — Cross-file Consistency:
+Rules (.claude/rules/) and Standards (claudeos-core/standard/) MUST NOT contradict each other.
+If a standard defines a specific pattern (e.g., import path, file naming, API usage),
+the corresponding rule MUST use the same pattern. Before generating each rule file,
+verify it is consistent with the related standard file.
+
+CRITICAL — Code Example Accuracy:
+ALL code examples in rules and standards MUST use EXACT method names, class names,
+and signatures from pass2-merged.json analysis data.
+Do NOT paraphrase, rename, or infer API names. If pass2-merged.json records
+`MzcpResponseUtils.success()`, use `success()` — NOT `ok()`, NOT `respond()`.
+If a method signature is not captured in the analysis data,
+write "See corresponding standard for exact API" instead of guessing.
+
+CRITICAL — CLAUDE.md Reference Table Completeness:
+The reference table in CLAUDE.md MUST list ALL generated standard files, not just core.
+Include all backend-api, security-db, infra, and verification standards.
+Alternatively, add a note directing readers to .claude/rules/00.core/00.standard-reference.md
+for the complete list.
+
 Generation targets:
 
 1. CLAUDE.md (project root)
@@ -39,19 +64,31 @@ Generation targets:
    - Key rules summary table
 
 3. .claude/rules/ (active domains only)
-   - Every rule file MUST include `paths: ["**/*"]` in YAML frontmatter — this ensures Claude Code always loads the rule regardless of which file is being edited
    - Write the full rule content directly in each file (self-contained, no external references)
    - Include 5-15 lines of key rules with concrete examples
    - Do NOT use @import — it is not a Claude Code feature and does not work
-   - MUST generate `.claude/rules/00.core/00.standard-reference.md` — a mandatory rule file that instructs Claude Code to Read the standard documents before coding. Structure it as:
+   - Each rule file MUST end with a `## Reference` section linking to the corresponding standard file(s):
+     ```
+     ## Reference
+     > For detailed patterns and examples, Read: claudeos-core/standard/10.backend-api/01.controller-patterns.md
+     ```
+   - `paths:` frontmatter per rule category:
+     - `00.core/*` rules: `paths: ["**/*"]` — always loaded (architecture, naming are universally needed)
+     - `10.backend/*` rules: `paths: ["**/*"]` — always loaded (backend rules needed for any source editing)
+     - `30.security-db/*` rules: `paths: ["**/*"]` — always loaded (cross-cutting concerns)
+     - `40.infra/*` rules: `paths: ["**/*.yml", "**/*.yaml", "**/*.properties", "**/config/**", "**/*.gradle*", "**/Dockerfile*", "**/.env*"]` — loaded only for config/infra files
+     - `50.sync/*` rules: `paths: ["**/claudeos-core/**", "**/.claude/**"]` — loaded only when editing claudeos-core files
+   - MUST generate `.claude/rules/00.core/00.standard-reference.md` — a directory of all standard files. This is NOT a "read all" instruction. Claude should Read ONLY the standards relevant to the current task. Structure it as:
      ```
      ---
      paths:
        - "**/*"
      ---
-     # Required Standard Documents
-     Before writing or modifying code, you MUST Read the relevant standard files below using the Read tool.
-     ## Core (always read)
+     # Standard Documents Directory
+     Below is the complete list of standard files. Read ONLY the ones relevant to your current task — do NOT read all files.
+     Each rule file in .claude/rules/ links to its corresponding standard in the ## Reference section. Follow those links first.
+     This directory is for discovering standards that have no corresponding rule file.
+     ## Core
      - claudeos-core/standard/00.core/01.project-overview.md
      - claudeos-core/standard/00.core/02.architecture.md
      - claudeos-core/standard/00.core/03.naming-conventions.md

package/pass-prompts/templates/kotlin-spring/pass1.md

@@ -14,6 +14,7 @@ Analysis items (per domain):
    - URL patterns (RESTful conventions, naming, versioning)
    - Parameter binding (@RequestBody, @PathVariable, @RequestParam, @ModelAttribute)
    - Response format (ResponseEntity, custom response wrappers, sealed class responses)
+   - If a custom response wrapper class exists, record its EXACT class name, EXACT method signatures (e.g., `success()`, `error()`), and EXACT import path. Do NOT guess or invent method names — read the actual source.
    - Error handling (try-catch, @ExceptionHandler, @ControllerAdvice, Result/Either pattern)
    - Authentication/authorization (@AuthenticationPrincipal, @PreAuthorize, SecurityContext)
    - API documentation (Swagger/SpringDoc annotations)
@@ -61,6 +62,8 @@ Analysis items (per domain):
    - Validation annotations (@field:NotNull, @field:NotBlank, @field:Size, custom)
    - Conversion approach (mapstruct-kotlin, manual extension functions, toEntity/toDto)
    - Serialization (Jackson Kotlin module, kotlinx.serialization)
+   - Import paths: record EXACT package paths for shared classes (e.g., `com.company.shared.util.DateUtils`, not an invented path)
+   - Utility class locations: record EXACT module and package where shared utilities live
 
 6. Aggregate/Aggregate Root Patterns
    - Aggregate boundary definition (which entities belong together)
@@ -126,7 +129,7 @@ Analysis items (per domain):
     - Aggregate boundary violations (cross-aggregate direct references, oversized aggregates)
     - VO misuse (mutable VOs, VOs with identity, DTO used where VO should be)
 
-Do not create files. Analysis only.
+Do not create or modify source files. Analysis only.
 Save results to claudeos-core/generated/pass1-{{PASS_NUM}}.json in the following format:
 
 {

package/pass-prompts/templates/kotlin-spring/pass2.md

@@ -43,11 +43,11 @@ Merge items:
    - Module naming conventions (what suffix: -server, -lib, -adapter)
 
 6. Common Classes/Utilities List
-   - Shared library (shared-lib) key classes and utilities
-   - Integration library (integration-lib) contracts and adapters
-   - Base classes (must not be redeclared)
-   - Shared constants/Enum management
-   - Common extension functions
+   - Shared library (shared-lib) key classes and utilities with EXACT package paths (e.g., `com.company.shared.util.DateUtils`)
+   - Integration library (integration-lib) contracts and adapters with EXACT package paths
+   - Base classes (must not be redeclared) with EXACT fully-qualified class names
+   - Shared constants/Enum management with EXACT locations
+   - Common extension functions with EXACT file locations
 
 7. BFF Patterns Summary
    - Feign Client declaration conventions

package/pass-prompts/templates/kotlin-spring/pass3.md

@@ -4,6 +4,31 @@ generate all ClaudeOS-Core files based on the analysis results.
 
 Do not read the original source code again. Reference only the analysis results.
 
+CRITICAL — Build Tool Consistency:
+Check `stack.buildTool` and `stack.packageManager` in project-analysis.json.
+ALL generated files MUST use the detected build tool's commands (e.g., Gradle tasks).
+NEVER mix Gradle/Maven commands. Also verify actual task names from build.gradle(.kts).
+
+CRITICAL — Cross-file Consistency:
+Rules (.claude/rules/) and Standards (claudeos-core/standard/) MUST NOT contradict each other.
+If a standard defines a specific pattern (e.g., import path, file naming, API usage),
+the corresponding rule MUST use the same pattern. Before generating each rule file,
+verify it is consistent with the related standard file.
+
+CRITICAL — Code Example Accuracy:
+ALL code examples in rules and standards MUST use EXACT method names, class names,
+and signatures from pass2-merged.json analysis data.
+Do NOT paraphrase, rename, or infer API names. If pass2-merged.json records
+`MzcpResponseUtils.success()`, use `success()` — NOT `ok()`, NOT `respond()`.
+If a method signature is not captured in the analysis data,
+write "See corresponding standard for exact API" instead of guessing.
+
+CRITICAL — CLAUDE.md Reference Table Completeness:
+The reference table in CLAUDE.md MUST list ALL generated standard files, not just core.
+Include all backend-api, security-db, infra, and verification standards.
+Alternatively, add a note directing readers to .claude/rules/00.core/00.standard-reference.md
+for the complete list.
+
 Generation targets:
 
 1. CLAUDE.md (project root)
@@ -42,20 +67,32 @@ Generation targets:
    - Key rules summary table
 
 3. .claude/rules/ (active domains only)
-   - Every rule file MUST include `paths: ["**/*"]` in YAML frontmatter — this ensures Claude Code always loads the rule regardless of which file is being edited
    - Write the full rule content directly in each file (self-contained, no external references)
    - Include 5-15 lines of key rules with concrete examples
    - Do NOT use @import — it is not a Claude Code feature and does not work
    - CQRS-specific rules: include command/query separation rules directly in the rule file content
-   - MUST generate `.claude/rules/00.core/00.standard-reference.md` — a mandatory rule file that instructs Claude Code to Read the standard documents before coding. Structure it as:
+   - Each rule file MUST end with a `## Reference` section linking to the corresponding standard file(s):
+     ```
+     ## Reference
+     > For detailed patterns and examples, Read: claudeos-core/standard/10.backend-api/01.controller-patterns.md
+     ```
+   - `paths:` frontmatter per rule category:
+     - `00.core/*` rules: `paths: ["**/*"]` — always loaded (architecture, naming are universally needed)
+     - `10.backend/*` rules: `paths: ["**/*"]` — always loaded (backend rules needed for any source editing)
+     - `30.security-db/*` rules: `paths: ["**/*"]` — always loaded (cross-cutting concerns)
+     - `40.infra/*` rules: `paths: ["**/*.yml", "**/*.yaml", "**/*.properties", "**/config/**", "**/*.gradle*", "**/Dockerfile*", "**/.env*"]` — loaded only for config/infra files
+     - `50.sync/*` rules: `paths: ["**/claudeos-core/**", "**/.claude/**"]` — loaded only when editing claudeos-core files
+   - MUST generate `.claude/rules/00.core/00.standard-reference.md` — a directory of all standard files. This is NOT a "read all" instruction. Claude should Read ONLY the standards relevant to the current task. Structure it as:
      ```
      ---
      paths:
        - "**/*"
      ---
-     # Required Standard Documents
-     Before writing or modifying code, you MUST Read the relevant standard files below using the Read tool.
-     ## Core (always read)
+     # Standard Documents Directory
+     Below is the complete list of standard files. Read ONLY the ones relevant to your current task — do NOT read all files.
+     Each rule file in .claude/rules/ links to its corresponding standard in the ## Reference section. Follow those links first.
+     This directory is for discovering standards that have no corresponding rule file.
+     ## Core
      - claudeos-core/standard/00.core/01.project-overview.md
      - claudeos-core/standard/00.core/02.architecture.md
      - claudeos-core/standard/00.core/03.naming-conventions.md

package/pass-prompts/templates/node-express/pass1.md

@@ -12,6 +12,7 @@ Analysis items (per domain):
    - URL patterns (RESTful conventions, naming, versioning)
    - Parameter handling (req.body, req.params, req.query, @Body(), @Param(), @Query())
    - Response format (res.json, interceptor, class-transformer, custom wrapper)
+   - If a custom response wrapper/helper exists, record its EXACT function/class name, EXACT method signatures, and EXACT import path. Do NOT guess — read the actual source.
    - Error handling (try-catch, HttpException, ExceptionFilter, error middleware)
    - Authentication (Passport, JWT Guard, custom middleware)
    - API documentation (Swagger @ApiTags, @ApiOperation, JSDoc)
@@ -40,6 +41,8 @@ Analysis items (per domain):
    - TypeScript usage level (interface vs type vs class, Generic usage)
    - Serialization/deserialization (class-transformer, custom serializer)
    - Enum/constants management
+   - File entry pattern: is the main file `index.ts` or named by module (e.g., `users.controller.ts`)? Record the exact convention.
+   - Import paths: record EXACT path aliases and import patterns used (e.g., `@/modules/`, `@app/`, relative paths)
 
 5. Configuration/Environment Patterns
    - Environment variable management (@nestjs/config, dotenv, envalid)
@@ -81,7 +84,7 @@ Analysis items (per domain):
    - Performance issues (memory leaks, blocking I/O)
    - Security issues (injection, missing authorization)
 
-Do not create files. Analysis only.
+Do not create or modify source files. Analysis only.
 Save results to claudeos-core/generated/pass1-{{PASS_NUM}}.json in the following format:
 
 {

package/pass-prompts/templates/node-express/pass2.md

@@ -29,12 +29,15 @@ Merge items:
 
 5. Naming Conventions Summary
    - File/directory naming (kebab-case, camelCase, PascalCase)
+   - File entry pattern (index.ts vs module-named files — pick ONE that the project actually uses)
    - DTO/type naming conventions
    - Route URL patterns
    - Module/package structure conventions
 
 6. Common Types/Interfaces List
-   - Shared type definition files
+   - Shared type definition files with EXACT import paths
+   - Utility functions with EXACT import paths
+   - Path aliases used in the project (e.g., `@/` → `src/`)
    - Utility types
    - Environment variable types
    - Constants/Enum management

package/pass-prompts/templates/node-express/pass3.md

@@ -4,11 +4,37 @@ generate all ClaudeOS-Core files based on the analysis results.
 
 Do not read the original source code again. Reference only the analysis results.
 
+CRITICAL — Package Manager Consistency:
+Check `stack.packageManager` in project-analysis.json (e.g., "pnpm", "yarn", "npm").
+ALL generated files MUST use ONLY that detected package manager's commands.
+For example, if packageManager is "pnpm": use `pnpm run build`, `pnpm run dev`, `pnpm install`, etc.
+NEVER mix npm/yarn/pnpm commands. Also check `scripts` field in the project's package.json
+for actual script names (e.g., "eslint" not "lint", "typecheck" not "tsc --noEmit").
+
+CRITICAL — Cross-file Consistency:
+Rules (.claude/rules/) and Standards (claudeos-core/standard/) MUST NOT contradict each other.
+If a standard defines a specific pattern (e.g., import path, file naming, API usage),
+the corresponding rule MUST use the same pattern. Before generating each rule file,
+verify it is consistent with the related standard file.
+
+CRITICAL — Code Example Accuracy:
+ALL code examples in rules and standards MUST use EXACT method names, class names,
+and signatures from pass2-merged.json analysis data.
+Do NOT paraphrase, rename, or infer API names.
+If a method signature is not captured in the analysis data,
+write "See corresponding standard for exact API" instead of guessing.
+
+CRITICAL — CLAUDE.md Reference Table Completeness:
+The reference table in CLAUDE.md MUST list ALL generated standard files, not just core.
+Include all frontend-ui, backend-api, security-db, infra, and verification standards.
+Alternatively, add a note directing readers to .claude/rules/00.core/00.standard-reference.md
+for the complete list.
+
 Generation targets:
 
 1. CLAUDE.md (project root)
    - Role definition (based on detected stack)
-   - Build & Run Commands (npm/yarn/pnpm)
+   - Build & Run Commands (use ONLY the detected packageManager — never hardcode npm/yarn/pnpm)
    - Core architecture diagram
    - DB table/collection naming
    - Standard/Skills/Guide reference table
@@ -38,19 +64,31 @@ Generation targets:
    - Key rules summary table
 
 3. .claude/rules/ (active domains only)
-   - Every rule file MUST include `paths: ["**/*"]` in YAML frontmatter — this ensures Claude Code always loads the rule regardless of which file is being edited
    - Write the full rule content directly in each file (self-contained, no external references)
    - Include 5-15 lines of key rules with concrete examples
    - Do NOT use @import — it is not a Claude Code feature and does not work
-   - MUST generate `.claude/rules/00.core/00.standard-reference.md` — a mandatory rule file that instructs Claude Code to Read the standard documents before coding. Structure it as:
+   - Each rule file MUST end with a `## Reference` section linking to the corresponding standard file(s):
+     ```
+     ## Reference
+     > For detailed patterns and examples, Read: claudeos-core/standard/10.backend-api/01.router-controller-patterns.md
+     ```
+   - `paths:` frontmatter per rule category:
+     - `00.core/*` rules: `paths: ["**/*"]` — always loaded (architecture, naming are universally needed)
+     - `10.backend/*` rules: `paths: ["**/*"]` — always loaded (backend rules needed for any source editing)
+     - `30.security-db/*` rules: `paths: ["**/*"]` — always loaded (cross-cutting concerns)
+     - `40.infra/*` rules: `paths: ["**/*.json", "**/*.env*", "**/config/**", "**/Dockerfile*", "**/*.yml", "**/*.yaml"]` — loaded only for config/infra files
+     - `50.sync/*` rules: `paths: ["**/claudeos-core/**", "**/.claude/**"]` — loaded only when editing claudeos-core files
+   - MUST generate `.claude/rules/00.core/00.standard-reference.md` — a directory of all standard files. This is NOT a "read all" instruction. Claude should Read ONLY the standards relevant to the current task. Structure it as:
      ```
      ---
      paths:
        - "**/*"
      ---
-     # Required Standard Documents
-     Before writing or modifying code, you MUST Read the relevant standard files below using the Read tool.
-     ## Core (always read)
+     # Standard Documents Directory
+     Below is the complete list of standard files. Read ONLY the ones relevant to your current task — do NOT read all files.
+     Each rule file in .claude/rules/ links to its corresponding standard in the ## Reference section. Follow those links first.
+     This directory is for discovering standards that have no corresponding rule file.
+     ## Core
      - claudeos-core/standard/00.core/01.project-overview.md
      - claudeos-core/standard/00.core/02.architecture.md
      - claudeos-core/standard/00.core/03.naming-conventions.md

package/pass-prompts/templates/node-nextjs/pass1.md

@@ -19,9 +19,13 @@ Analysis items (per domain):
    - Component structure (functional, forwardRef, memo)
    - Props type definition (interface vs type, Generic usage)
    - State management (useState, useReducer, external libraries)
-   - Styling (CSS Modules, Tailwind, styled-components, Emotion)
-   - UI library (shadcn/ui, MUI, Ant Design, Radix)
+   - Styling approach and exact import paths (e.g., `import styles from './index.module.scss'`, `import { cn } from '@/lib/utils'`)
+   - Styling utility functions: record the EXACT import path used in source code (e.g., `from '@lfos-poc-ui/utils'` NOT `from '@app/shared/lib/classNames'`)
+   - UI library and exact package names (e.g., `@lfos-poc-ui/ui`, `@shadcn/ui`, `@mui/material`)
    - Component classification (UI, Feature, Layout, Page)
+   - Component entry file pattern: is the main file `index.tsx` or `ComponentName.tsx`? Record exactly which pattern the project uses.
+   - Directory structure pattern: record exact convention (e.g., `ComponentName/index.tsx` vs `ComponentName/ComponentName.tsx`)
+   - export pattern: default export vs named export in component files
    - Reuse patterns (composition, compound components, render props)
    - Accessibility (ARIA, semantic HTML, keyboard navigation)
 
@@ -79,7 +83,7 @@ Analysis items (per domain):
    - Accessibility issues
    - Security issues (XSS, CSRF)
 
-Do not create files. Analysis only.
+Do not create or modify source files. Analysis only.
 Save results to claudeos-core/generated/pass1-{{PASS_NUM}}.json in the following format:
 
 {
@@ -97,7 +101,13 @@ Save results to claudeos-core/generated/pass1-{{PASS_NUM}}.json in the following
       },
       "patterns": {
         "page": { ... },
-        "component": { ... },
+        "component": {
+          "entryFilePattern": "index.tsx or ComponentName.tsx",
+          "exportPattern": "default export or named export",
+          "stylingImport": "exact import statement used for styling utility",
+          "uiLibraryImport": "exact import statement for UI components",
+          ...
+        },
         "dataFetching": { ... },
         "stateManagement": { ... },
         "config": { ... },

package/pass-prompts/templates/node-nextjs/pass2.md

@@ -27,14 +27,16 @@ Merge items:
 
 5. Naming Conventions Summary
    - File/directory naming (kebab-case, PascalCase)
-   - Component naming conventions
+   - Component entry file pattern (index.tsx vs ComponentName.tsx — pick ONE that the project actually uses)
+   - Component export pattern (default export vs named export)
    - Hook naming (use* prefix)
    - API route patterns
 
 6. Shared Types/Components List
-   - Common UI components
-   - Shared hooks
-   - Utility functions
+   - Common UI components with EXACT import paths (e.g., `from '@lfos-poc-ui/ui'`, NOT invented paths)
+   - Shared hooks with exact import paths
+   - Utility functions with EXACT import paths (e.g., `from '@lfos-poc-ui/utils'` for classNamesWithRoot)
+   - Path aliases used in the project (e.g., `@app/` → `src/`, `@/` → `src/`)
    - Environment variable types
    - Constants/Enum management