claudeos-core 2.4.3 → 2.5.0

package/lib/memory-scaffold.js

@@ -10,6 +10,7 @@
 
 const path = require("path");
 const fs = require("fs");
+const crypto = require("crypto");
 const { ensureDir, existsSafe, writeFileSafe, readFileSafe } = require("./safe-fs");
 
 // ─── Language labels — single source of truth: lib/language-config.js ──
@@ -58,6 +59,18 @@ function writeCache(cacheFile, cache) {
   } catch (_e) { /* best-effort */ }
 }
 
+// v2.5.0 — Cache entries are keyed by content name AND a hash of the English
+// source. Pre-v2.5.0 the key was the bare name (`MEMORY_FILES.compaction.md`),
+// so whenever a static-fallback text changed between releases, a project that
+// already had `fallback-cache-<lang>.json` kept serving the translation of the
+// OLD English text forever. Hashing the source makes a text change a cache
+// miss automatically; stale entries under the old key shape are simply never
+// read again.
+function cacheKeyFor(contentKey, englishContent) {
+  const h = crypto.createHash("sha1").update(String(englishContent), "utf8").digest("hex").slice(0, 12);
+  return `${contentKey}@${h}`;
+}
+
 // Translate English static content to the requested language via Claude CLI.
 //
 // Behavior contract:
@@ -81,6 +94,15 @@ function translateIfNeeded(englishContent, lang, contentKey, cacheFile) {
     );
   }
 
+  // Cache hit → return immediately. Checked BEFORE the env-skip below: a hit
+  // never shells out, so the skip has nothing to prevent, and this keeps the
+  // cache path unit-testable under CLAUDEOS_SKIP_TRANSLATION=1.
+  const cache = readCache(cacheFile);
+  const key = cacheKeyFor(contentKey, englishContent);
+  if (cache[key] && typeof cache[key] === "string" && cache[key].trim().length > 0) {
+    return cache[key];
+  }
+
   // M2: CI / deterministic-test escape hatch. When
   // CLAUDEOS_SKIP_TRANSLATION=1 is set, throw instead of shelling out to
   // `claude -p`. This makes the "translation fails without real Claude CLI"
@@ -95,12 +117,6 @@ function translateIfNeeded(englishContent, lang, contentKey, cacheFile) {
     );
   }
 
-  // Cache hit → return immediately
-  const cache = readCache(cacheFile);
-  if (cache[contentKey] && typeof cache[contentKey] === "string" && cache[contentKey].trim().length > 0) {
-    return cache[contentKey];
-  }
-
   // Lazy-load CLI utils to avoid a circular dependency at module-load time.
   let runClaudeCapture;
   try {
@@ -256,8 +272,9 @@ Translate now. Output only the translated document.`;
     );
   }
 
-  // Success — save to cache for future init runs
-  cache[contentKey] = cleaned;
+  // Success — save to cache for future init runs (content-hashed key; must
+  // be recomputed here — this function does not share translateIfNeeded's scope).
+  cache[cacheKeyFor(contentKey, englishContent)] = cleaned;
   writeCache(cacheFile, cache);
 
   const elapsed = ((Date.now() - t0) / 1000).toFixed(1);
@@ -282,7 +299,7 @@ _Format: \`## <pattern-id>\` with Frequency / Last Seen / Importance / Fix._
 
   "compaction.md": `# Compaction Strategy
 
-_4-stage compaction rules for \`decision-log.md\` and \`failure-patterns.md\`._
+_4-stage compaction rules for \`failure-patterns.md\`. \`decision-log.md\` is append-only and never compacted._
 _Run via \`npx claudeos-core memory compact\`._
 
 ## Preservation Priority
@@ -431,8 +448,8 @@ Before analysis or evaluation, review this table and do not repeat these pattern
 | 8 | Making quantitative judgments based on unverified numbers, then reversing when challenged | No speculation-based quantitative claims |
 | 9 | Judging a standard document as "low practical value" without reading it | No judgment before verification |
 | 10 | Proposing to merge/reduce same-layer intentional duplication | Different perspectives on the same topic in different files is intentional. Rule accessibility > token saving |
-| 11 | Suggesting an import or package name without verifying it exists in the dependency manifest | Hallucinated module/named export. Verify by reading \`package.json\` / \`pom.xml\` / \`build.gradle\` / \`pyproject.toml\` / \`requirements.txt\` before recommending an import |
-| 12 | Mixing API signatures from different major versions of the same library | Verify by checking the manifest AND lockfile for the exact installed version (lockfile pins the truth): \`package-lock.json\`/\`pnpm-lock.yaml\`/\`yarn.lock\`, \`gradle.lockfile\`/\`gradle/libs.versions.toml\`, \`poetry.lock\`/\`Pipfile.lock\`/\`uv.lock\`, or fall back to the manifest (\`pom.xml\`/\`build.gradle\`/\`package.json\`/\`pyproject.toml\`) |
+| 11 | Suggesting an import or package name without verifying it exists in the dependency manifest | Hallucinated module/named export. Verify by reading \`package.json\` / \`pom.xml\` / \`build.gradle\` / \`build.gradle.kts\` / \`pyproject.toml\` / \`requirements.txt\` before recommending an import |
+| 12 | Mixing API signatures from different major versions of the same library | Verify by checking the manifest AND lockfile for the exact installed version (lockfile pins the truth): \`package-lock.json\`/\`pnpm-lock.yaml\`/\`yarn.lock\`, \`gradle.lockfile\`/\`gradle/libs.versions.toml\`, \`poetry.lock\`/\`Pipfile.lock\`/\`uv.lock\`, or fall back to the manifest (\`pom.xml\`/\`build.gradle\`/\`build.gradle.kts\`/\`package.json\`/\`pyproject.toml\`) |
 | 13 | Editing one environment config file without checking sibling parity | Verify by \`Glob\` for the config family before a partial edit. Backend: \`.env*\`, \`application-*.yml/.properties\`, \`*settings.py\`. Frontend: \`environment*.ts\` (Angular), \`next.config.*\`, \`vite.config.*\`, \`nuxt.config.*\`, \`.env.local\`/\`.env.production\` |
 | 14 | Mixing server/client component boundaries (SSR frameworks) — using client-only APIs (\`useState\`, \`useEffect\`, \`window\`, \`localStorage\`) in a server component, or server-only operations (DB access, secret reads, filesystem) in a client component | Read the file's boundary directive before adding code: Next.js App Router (\`"use client"\` opt-in), Nuxt (server vs client composables), Remix (\`loader\`/\`action\` exports). N/A for pure SPA or pure backend projects |
 | 15 | Inventing component prop names or function arguments without reading the target's interface | Read the target's prop type definition (\`interface Props\`, \`defineProps<>\`, function signature) or method signature before invoking. Hallucinated props may compile in loose-TS code and crash at runtime |
@@ -450,9 +467,8 @@ Before analysis or evaluation, review this table and do not repeat these pattern
 - **Do not modify onboarding/guide documents (\`claudeos-core/guide/\`) unless specifically requested.**
 - Do not clean up surrounding code during bug fixes, or add unnecessary refactoring during feature additions.
 - **Empty directories may be intentional placeholders — verify markers before flagging or removing.** Markers of intent: a \`.gitkeep\` / \`KEEP_EMPTY.md\` file inside, the directory listed in CLAUDE.md as planned, or referenced by an active plan/standard/skills document. If none of these exist, an empty directory may be neglect — ask the user before deleting.
-- **\`plan/\` master documents are internal sync management tools.** Do not suggest removing them. "DO NOT Read" means "AI should not read directly", not "the file is unnecessary".
 - **Do not duplicate into memory what is already directly verifiable in code, config files, or rule documents.** Configuration values, paths, and names already recorded in CLAUDE.md, rules, or standard must not be redundantly stored in memory. Examples — backend: port numbers, pool sizes, handler names, transaction propagation modes; frontend: dev server port, build output dir, env var prefix (\`VITE_\`/\`NEXT_PUBLIC_\`/\`REACT_APP_\`), route definitions, bundle size budgets.
-- **Do not directly read internal document directories (\`guide/\`, \`plan/\`, \`generated/\`, \`mcp-guide/\`) for routine context loading.** \`.claude/rules/\` and \`claudeos-core/standard/\` already contain the essential content. *Exception: read directly when the user explicitly asks about these contents, or when debugging an issue requires inspecting them.*
+- **Do not directly read internal document directories (\`guide/\`, \`generated/\`, \`mcp-guide/\`) for routine context loading.** \`.claude/rules/\` and \`claudeos-core/standard/\` already contain the essential content. *Exception: read directly when the user explicitly asks about these contents, or when debugging an issue requires inspecting them.*
 - **Established codebase conventions take precedence over textbook-ideal patterns.** Propose modernization, refactoring, or "current best practices" migration ONLY when the user explicitly requests it (e.g., "modernize", "migrate to v3", "refactor to current best practices"). Otherwise, follow the existing pattern even if you would write it differently in a greenfield project.
 
 ## Project Architecture — Hands Off
@@ -464,7 +480,7 @@ This project uses the CLAUDE.md → rules → standard 3-layer architecture, plu
 - **Memory (\`claudeos-core/memory/\`, on-demand) and Rules (\`.claude/rules/\`, auto-loaded by path match) are never simultaneously loaded by default.** Similar content between them is NOT duplication. Do not propose "memory cleanup", "dedupe memory vs rules", or "consolidate memory into rules" — they have different roles (on-demand history/context vs auto-loaded enforcement).
 - **Multi-rule load provides reinforcement.** Do not label co-loaded defensive rules as "redundant" — the reinforcement effect is intentional and the context cost is negligible.
 - **Rules \`paths: ["**/*"]\` — do not propose conditional path conversion for core rules.** When developing new features (no matching files exist yet), conditional paths would prevent rules from loading, risking non-standard code generation.
-- **\`00.standard-reference.md\` index additions — avoid unless specifically requested.** Each rules file already links to its corresponding standard via the \`## Reference\` section. Adding paths to the index only consumes additional tokens per conversation.
+- **\`00.standard-reference.md\` is a paths-only index of \`claudeos-core/standard/\`.** When a standard file is added, add its path there (one line, no description). Do not add rule files, skill files, memory files, or "DO NOT Read" lists to it — those belong elsewhere, and every extra line is reloaded on every edit.
 - **Minor wording or item count differences across layers are NOT "inconsistency risks".** If no information is missing, trivial expression differences are not a problem.
 
 ## Planned References — No "Missing" Judgment
@@ -577,8 +593,8 @@ paths:
 
 # Compaction Strategy (\`memory/compaction.md\`)
 
-Reference document defining the 4-stage compaction policy.
-Executed by \`npx claudeos-core memory compact\`.
+Reference document defining the 4-stage compaction policy for \`failure-patterns.md\`.
+Executed by \`npx claudeos-core memory compact\`. \`decision-log.md\` is never compacted (append-only).
 
 ## Rules
 
@@ -1055,4 +1071,7 @@ module.exports = {
   scaffoldMasterPlans,
   scaffoldDocWritingGuide,
   scaffoldSkillsManifest,
+  // Exported for test visibility (v2.5.0: content-hashed translation cache).
+  translateIfNeeded,
+  _cacheKeyFor: cacheKeyFor,
 };

package/manifest-generator/index.js

@@ -166,10 +166,21 @@ async function main() {
   // Deterministically reconcile MANIFEST.md ↔ CLAUDE.md §6 cross-references
   // that LLM stages routinely drift on. Failure here is logged but not
   // fatal — manifest-generator's primary outputs above are already on disk.
-  try {
-    syncSkillsCatalog(ROOT);
-  } catch (e) {
-    console.log(`  ⚠️  skills-sync: unexpected error (${e.message || e})`);
+  //
+  // OPT-IN ONLY. This step WRITES to CLAUDE.md and MANIFEST.md. It must not
+  // run from `npx claudeos-core health` (documented as a read-only gate that
+  // users wire into CI / pre-commit) — a health check that dirties the
+  // working tree is a trap. `init` passes `--sync-skills` after Pass 3/4;
+  // everything else gets a pure metadata generation run. The flag is the ONLY
+  // switch — an environment variable would be inherited by `health`'s child
+  // process and silently re-enable writes from a shell that exported it.
+  const syncRequested = process.argv.includes("--sync-skills");
+  if (syncRequested) {
+    try {
+      syncSkillsCatalog(ROOT);
+    } catch (e) {
+      console.log(`  ⚠️  skills-sync: unexpected error (${e.message || e})`);
+    }
   }
 
   // ─── Initialize stale-report.json (preserve existing sub-tool results) ──

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudeos-core",
-  "version": "2.4.3",
+  "version": "2.5.0",
   "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": {

package/pass-prompts/templates/angular/pass3.md

@@ -85,6 +85,7 @@ Generation targets:
      - `60.memory/*` rules: forward reference — Pass 4 will generate 4 files (01.decision-log, 02.failure-patterns, 03.compaction, 04.auto-rule-update), each with file-specific `paths`. Pass 3 must STILL list ```.claude/rules/60.memory/*``` as a row in CLAUDE.md Section 6 Rules table so developers/Claude see the category exists.
      - `70.domains/*` rules (multi-domain projects only): per-domain rules at `.claude/rules/70.domains/{type}/{domain}-rules.md` (where `{type}` is `backend` or `frontend`, ALWAYS present even in single-stack projects for uniform layout + zero-migration future-proofing), each with a `paths:` glob scoped to that domain's source directories so the rule auto-loads only when editing files within the relevant domain. Folder name is PLURAL (`domains/`) — collection of N per-domain files — and each file inside uses the SINGULAR domain name (`{domain}-rules.md`). DO NOT use `60.domains/` (collides with `60.memory/`) and DO NOT skip the `{type}/` sub-folder. See pass3-footer.md "Per-domain folder convention" for the full rationale.
    - MUST generate `.claude/rules/00.core/00.standard-reference.md` as a directory of all standard files
+     (paths only, grouped by category). Include the FORWARD REFERENCE `claudeos-core/standard/00.core/04.doc-writing-guide.md` under `## Core` — Pass 4 generates it; omitting it leaves an index gap the moment Pass 4 runs. Do NOT add a "DO NOT Read" section here — CLAUDE.md Section 7 is the single source of truth.
 
 4. .claude/rules/50.sync/ (2 sync rules)
    - 01.doc-sync.md — Bidirectional standard ↔ rules sync reminder (both directions in ONE rule).
@@ -94,7 +95,7 @@ Generation targets:
    - 02.skills-sync.md — Remind AI to update MANIFEST.md when skills are modified
 
 5. claudeos-core/skills/ (active domains only)
-   - 20.frontend-page/01.scaffold-feature-module.md (orchestrator — Angular feature module scaffolding)
+   - 20.frontend-page/01.scaffold-page-feature.md (orchestrator — Angular feature module scaffolding; stem MUST match the `scaffold-page-feature/` sub-folder so content-validator pairs them)
    - 20.frontend-page/scaffold-page-feature/01~08 (sub-skills: module, component, service, routing, template, test, style, index)
    - 00.shared/MANIFEST.md (skill registry)
 

package/pass-prompts/templates/common/claude-md-scaffold.md

@@ -277,7 +277,7 @@ Unlike rules that auto-load via `paths` glob, this layer is referenced **on-dema
 2. **Skim recent decisions**: Skim recent entries in `decision-log.md` to avoid overwriting architectural decisions that have already been agreed upon.
 3. **Record new decisions**: When making a significant design decision (choosing between competing patterns, adopting or rejecting a library, fixing a convention, etc.), append to `decision-log.md`.
 4. **Record repeated errors**: If the same error occurs ≥2 times and the root cause is non-obvious, register it in `failure-patterns.md` with a new pattern-id.
-5. **Periodic compaction**: When a memory file approaches 400 lines or has not been tidied up for over a month, run `npx claudeos-core memory compact`.
+5. **Periodic compaction**: When `failure-patterns.md` approaches 400 lines or has not been tidied up for over a month, run `npx claudeos-core memory compact` (`decision-log.md` is append-only and is never compacted).
 6. **Review rule-update proposals**: Review proposals in `auto-rule-update.md` with confidence ≥ 0.70. When accepting, edit the corresponding rule file and log the decision in `decision-log.md`.
 
 **Session Resume (after auto-compact or restart)**: Claude Code's auto-compact feature may truncate session context mid-work, and a restarted session starts with a fresh context window. When resuming work:

package/pass-prompts/templates/common/pass3a-facts.md

@@ -125,11 +125,15 @@ IMPORT, not redefine.
 - ...
 - ...
 
-## Allowed Source Paths (v2.3.x+ — MANDATORY)
+## Allowed Source Paths (v2.5.0+ — WRITTEN BY THE ORCHESTRATOR)
 
-Copy the **entire** `allowedSourcePaths` section from `pass3-context.json`
-verbatim into this pass3a-facts.md. Do NOT summarize it, do NOT truncate
-it, do NOT reword it. The shape to copy:
+**Do NOT write this section yourself.** After you finish, the Node.js
+orchestrator appends `## Allowed Source Paths` to this file directly from
+`project-analysis.json` — byte-exact, every run. Anything you write under
+that heading will be replaced. Skip it and save the tokens.
+
+The remainder of this section documents the shape the orchestrator emits,
+so Pass 3b/3c/3d know what to expect:
 
 - Header: whether the list is in `full` mode (individual file paths) or
   `rollup` mode (parent directories, used when the project exceeds the
@@ -175,11 +179,9 @@ fall back to pass2-merged.json verification per file)` instead.
 3. **Exact values only.** Every class name, method name, package path, and
    file path must be verbatim from the analysis data. If a value is not
    captured in the analysis, write `(not in analysis)` — do NOT guess.
-4. **Allowed Source Paths section is COPIED, not extracted.** Do not apply
-   judgment, ranking, or "relevance filtering" to the allowlist. The
-   whole point is that Pass 3b/3c/3d get the complete enumeration; any
-   path you drop here becomes a path they can fabricate later without
-   the downstream validator catching it until after Pass 3 completes.
+4. **Do not write the `## Allowed Source Paths` section.** The orchestrator
+   injects it verbatim from `project-analysis.json` once this step ends
+   (v2.5.0+). It is deterministic by design — no LLM copying involved.
 5. **Do NOT write any other files.** CLAUDE.md, standard/, rules/, etc.
    come in later Pass 3 steps. Writing them here is a bug.
 6. **Do NOT read source code.** All information comes from the three JSON

package/pass-prompts/templates/common/pass4.md

@@ -191,7 +191,7 @@ Baseline template (translate per above, then append the project-specific section
 ```markdown
 # Compaction Strategy
 
-_4-stage compaction rules for `decision-log.md` and `failure-patterns.md`._
+_4-stage compaction rules for `failure-patterns.md`. `decision-log.md` is append-only and never compacted._
 _Run via `npx claudeos-core memory compact`._
 
 ## Preservation Priority
@@ -266,7 +266,7 @@ Body (write in **{{LANG_NAME}}**) must cover:
 Frontmatter: `name: AI Work Rules`, `paths: ["**/*"]`
 Body (write in **{{LANG_NAME}}**) must cover:
 - Accuracy over token saving; verify before claiming
-- 13 hallucination prevention patterns (see memory-scaffold static fallback for reference list)
+- 17 hallucination prevention patterns (see memory-scaffold static fallback `RULE_FILES_00["52.ai-work-rules.md"]` for the reference table)
 - No unsolicited suggestions; ask when unsure
 - Memory vs Rules — no duplication judgment (Memory is on-demand, Rules are auto-loaded)
 - Planned references — no "missing" judgment
@@ -374,7 +374,7 @@ After all files are written, create:
   "standardFiles": [
     "claudeos-core/standard/00.core/XX.doc-writing-guide.md"
   ],
-  "claudeMdAppended": true,
+  "claudeMdAppended": false,
   "seededDecisions": <integer count of seed entries written to decision-log.md>
 }
 ```

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

@@ -89,7 +89,7 @@ Generation targets:
    - 30.security-db/01.security-auth.md — Authentication, authorization, CORS
    - 30.security-db/02.database-schema.md — DDL, migrations, audit columns
    - 30.security-db/03.common-utilities.md — Common utilities, constants, Base classes
-   - 40.infra/01.environment-config.md — Profiles, environment variables, configuration management
+   - 40.infra/01.environment-config.md — Profiles, environment variables, configuration management, build scripts (`build.gradle` / `build.gradle.kts` / `pom.xml`) and the Gradle version catalog
    - 40.infra/02.logging-monitoring.md — Logging standards, monitoring, alerts
    - 40.infra/03.cicd-deployment.md — CI/CD pipeline, deployment strategy
    - 80.verification/01.development-verification.md — Build, startup, API testing
@@ -113,7 +113,7 @@ Generation targets:
      - `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/01.environment-config-rules.md` paths: `["**/*.properties", "**/*.yml", "**/*.yaml", "**/.env*", "**/config/**", "**/application*.properties"]` — Spring config files
+     - `40.infra/01.environment-config-rules.md` paths: `["**/*.properties", "**/*.yml", "**/*.yaml", "**/.env*", "**/config/**", "**/application*.properties", "**/*.gradle", "**/*.gradle.kts", "**/gradle/libs.versions.toml", "**/pom.xml"]` — Spring config files + build scripts (Groovy and Kotlin DSL) + version catalog
      - `40.infra/02.logging-monitoring-rules.md` paths: `["**/*.java", "**/logback*.xml", "**/logback*.groovy", "**/log4j*.xml", "**/log4j*.properties", "**/log4jdbc*.properties"]` — source code where logs live + log config (covers Logback XML/Groovy DSL, Log4j/Log4j2 XML/properties, and log4jdbc JDBC-logging adapter properties)
      - `40.infra/03.cicd-deployment-rules.md` paths: `["**/*.yml", "**/*.yaml", "**/Dockerfile*", "**/*.gradle*", "**/pom.xml", "**/*.java"]` — CI / build config + source
      - `50.sync/*` rules: `paths: ["**/claudeos-core/**", "**/.claude/**"]` — loaded only when editing claudeos-core files
@@ -155,7 +155,7 @@ Generation targets:
      List only the standard files that were actually generated above. Include frontend standards only if frontend was detected. NOTE: `00.core/04.doc-writing-guide.md` is a FORWARD REFERENCE — Pass 4 will generate it; include it anyway. Do NOT add a "DO NOT Read" section here — that information lives in CLAUDE.md Section 7 (the single source of truth).
 
 4. .claude/rules/50.sync/ (2 sync rules — AI fallback reminders)
-   - NOTE: These rules remind AI to run `npx claudeos-core refresh` after modifying standard/rules/skills files.
+   - NOTE: These rules remind AI to keep standard ↔ rules ↔ MANIFEST in sync when it edits any of them (`npx claudeos-core health` reports drift). Do NOT reference `npx claudeos-core refresh` — it is a no-op since v2.1.0.
    - 01.doc-sync.md — Bidirectional standard ↔ rules sync reminder (both directions in ONE rule).
      Do NOT generate a separate 02.rules-sync.md mirror file — redundant.
      Express the mapping as a naming convention (standard/<N>.<dir>/<M>.<n>.md ↔

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

@@ -118,7 +118,7 @@ Generation targets:
      - `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/01.environment-config-rules.md` paths: `["**/*.properties", "**/*.yml", "**/*.yaml", "**/.env*", "**/config/**", "**/application*.properties"]` — Spring config files
+     - `40.infra/01.environment-config-rules.md` paths: `["**/*.properties", "**/*.yml", "**/*.yaml", "**/.env*", "**/config/**", "**/application*.properties", "**/*.gradle", "**/*.gradle.kts", "**/gradle/libs.versions.toml", "**/pom.xml"]` — Spring config files + build scripts (Groovy and Kotlin DSL) + version catalog
      - `40.infra/02.logging-monitoring-rules.md` paths: `["**/*.kt", "**/*.kts", "**/logback*.xml", "**/logback*.groovy", "**/log4j*.xml", "**/log4j*.properties", "**/log4jdbc*.properties"]` — source code where logs live + log config (covers Logback XML/Groovy DSL, Log4j/Log4j2 XML/properties, and log4jdbc JDBC-logging adapter properties)
      - `40.infra/03.cicd-deployment-rules.md` paths: `["**/*.yml", "**/*.yaml", "**/Dockerfile*", "**/*.gradle*", "**/*.kt", "**/*.kts"]` — CI / build config + source
      - `50.sync/*` rules: `paths: ["**/claudeos-core/**", "**/.claude/**"]` — loaded only when editing claudeos-core files
@@ -162,7 +162,7 @@ Generation targets:
      List only the standard files that were actually generated above. Include frontend standards only if frontend was detected. NOTE: `00.core/04.doc-writing-guide.md` is a FORWARD REFERENCE — Pass 4 will generate it; include it anyway. Do NOT add a "DO NOT Read" section here — that information lives in CLAUDE.md Section 7 (the single source of truth).
 
 4. .claude/rules/50.sync/ (2 sync rules — AI fallback reminders)
-   - NOTE: These rules remind AI to run `npx claudeos-core refresh` after modifying standard/rules/skills files.
+   - NOTE: These rules remind AI to keep standard ↔ rules ↔ MANIFEST in sync when it edits any of them (`npx claudeos-core health` reports drift). Do NOT reference `npx claudeos-core refresh` — it is a no-op since v2.1.0.
    - 01.doc-sync.md — Bidirectional standard ↔ rules sync reminder (both directions in ONE rule).
      Do NOT generate a separate 02.rules-sync.md mirror file — redundant.
      Express the mapping as a naming convention (standard/<N>.<dir>/<M>.<n>.md ↔

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

@@ -130,7 +130,7 @@ Generation targets:
      List only the standard files that were actually generated above. NOTE: `00.core/04.doc-writing-guide.md` is a FORWARD REFERENCE — Pass 4 will generate it; include it anyway. Do NOT add a "DO NOT Read" section here — that information lives in CLAUDE.md Section 7 (the single source of truth).
 
 4. .claude/rules/50.sync/ (2 sync rules — AI fallback reminders)
-   - NOTE: These rules remind AI to run `npx claudeos-core refresh` after modifying standard/rules/skills files.
+   - NOTE: These rules remind AI to keep standard ↔ rules ↔ MANIFEST in sync when it edits any of them (`npx claudeos-core health` reports drift). Do NOT reference `npx claudeos-core refresh` — it is a no-op since v2.1.0.
    - 01.doc-sync.md — Bidirectional standard ↔ rules sync reminder (both directions in ONE rule).
      Do NOT generate a separate 02.rules-sync.md mirror file — redundant.
      Express the mapping as a naming convention (standard/<N>.<dir>/<M>.<n>.md ↔

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

@@ -89,6 +89,7 @@ Generation targets:
      - `60.memory/*` rules: forward reference — Pass 4 will generate 4 files (01.decision-log, 02.failure-patterns, 03.compaction, 04.auto-rule-update), each with file-specific `paths`. Pass 3 must STILL list ```.claude/rules/60.memory/*``` as a row in CLAUDE.md Section 6 Rules table so developers/Claude see the category exists.
      - `70.domains/*` rules (multi-domain projects only): per-domain rules at `.claude/rules/70.domains/{type}/{domain}-rules.md` (where `{type}` is `backend` or `frontend`, ALWAYS present even in single-stack projects for uniform layout + zero-migration future-proofing), each with a `paths:` glob scoped to that domain's source directories so the rule auto-loads only when editing files within the relevant domain. Folder name is PLURAL (`domains/`) — collection of N per-domain files — and each file inside uses the SINGULAR domain name (`{domain}-rules.md`). DO NOT use `60.domains/` (collides with `60.memory/`) and DO NOT skip the `{type}/` sub-folder. See pass3-footer.md "Per-domain folder convention" for the full rationale.
    - MUST generate `.claude/rules/00.core/00.standard-reference.md` as a directory of all standard files
+     (paths only, grouped by category). Include the FORWARD REFERENCE `claudeos-core/standard/00.core/04.doc-writing-guide.md` under `## Core` — Pass 4 generates it; omitting it leaves an index gap the moment Pass 4 runs. Do NOT add a "DO NOT Read" section here — CLAUDE.md Section 7 is the single source of truth.
 
 4. .claude/rules/50.sync/ (2 sync rules)
    - 01.doc-sync.md — Bidirectional standard ↔ rules sync reminder (both directions in ONE rule).

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

@@ -97,6 +97,7 @@ Generation targets:
      - `60.memory/*` rules: forward reference — Pass 4 will generate 4 files (01.decision-log, 02.failure-patterns, 03.compaction, 04.auto-rule-update), each with file-specific `paths`. Pass 3 must STILL list ```.claude/rules/60.memory/*``` as a row in CLAUDE.md Section 6 Rules table so developers/Claude see the category exists.
      - `70.domains/*` rules (multi-domain projects only): per-domain rules at `.claude/rules/70.domains/{type}/{domain}-rules.md` (where `{type}` is `backend` or `frontend`, ALWAYS present even in single-stack projects for uniform layout + zero-migration future-proofing), each with a `paths:` glob scoped to that domain's source directories so the rule auto-loads only when editing files within the relevant domain. Folder name is PLURAL (`domains/`) — collection of N per-domain files — and each file inside uses the SINGULAR domain name (`{domain}-rules.md`). DO NOT use `60.domains/` (collides with `60.memory/`) and DO NOT skip the `{type}/` sub-folder. See pass3-footer.md "Per-domain folder convention" for the full rationale.
    - MUST generate `.claude/rules/00.core/00.standard-reference.md` — directory of all standard files.
+     (paths only, grouped by category). Include the FORWARD REFERENCE `claudeos-core/standard/00.core/04.doc-writing-guide.md` under `## Core` — Pass 4 generates it; omitting it leaves an index gap the moment Pass 4 runs. Do NOT add a "DO NOT Read" section here — CLAUDE.md Section 7 is the single source of truth.
      List only the standard files that were actually generated above.
 
 4. .claude/rules/50.sync/ (2 sync rules)

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

@@ -132,7 +132,7 @@ Generation targets:
      List only the standard files that were actually generated above. NOTE: `00.core/04.doc-writing-guide.md` is a FORWARD REFERENCE — Pass 4 will generate it; include it anyway. Do NOT add a "DO NOT Read" section here — that information lives in CLAUDE.md Section 7 (the single source of truth).
 
 4. .claude/rules/50.sync/ (2 sync rules — AI fallback reminders)
-   - NOTE: These rules remind AI to run `npx claudeos-core refresh` after modifying standard/rules/skills files.
+   - NOTE: These rules remind AI to keep standard ↔ rules ↔ MANIFEST in sync when it edits any of them (`npx claudeos-core health` reports drift). Do NOT reference `npx claudeos-core refresh` — it is a no-op since v2.1.0.
    - 01.doc-sync.md — Bidirectional standard ↔ rules sync reminder (both directions in ONE rule).
      Do NOT generate a separate 02.rules-sync.md mirror file — redundant.
      Express the mapping as a naming convention (standard/<N>.<dir>/<M>.<n>.md ↔

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

@@ -83,6 +83,7 @@ Generation targets:
      - `60.memory/*` rules: forward reference — Pass 4 will generate 4 files (01.decision-log, 02.failure-patterns, 03.compaction, 04.auto-rule-update), each with file-specific `paths`. Pass 3 must STILL list ```.claude/rules/60.memory/*``` as a row in CLAUDE.md Section 6 Rules table so developers/Claude see the category exists.
      - `70.domains/*` rules (multi-domain projects only): per-domain rules at `.claude/rules/70.domains/{type}/{domain}-rules.md` (where `{type}` is `backend` or `frontend`, ALWAYS present even in single-stack projects for uniform layout + zero-migration future-proofing), each with a `paths:` glob scoped to that domain's source directories so the rule auto-loads only when editing files within the relevant domain. Folder name is PLURAL (`domains/`) — collection of N per-domain files — and each file inside uses the SINGULAR domain name (`{domain}-rules.md`). DO NOT use `60.domains/` (collides with `60.memory/`) and DO NOT skip the `{type}/` sub-folder. See pass3-footer.md "Per-domain folder convention" for the full rationale.
    - MUST generate `.claude/rules/00.core/00.standard-reference.md` — directory of all standard files.
+     (paths only, grouped by category). Include the FORWARD REFERENCE `claudeos-core/standard/00.core/04.doc-writing-guide.md` under `## Core` — Pass 4 generates it; omitting it leaves an index gap the moment Pass 4 runs. Do NOT add a "DO NOT Read" section here — CLAUDE.md Section 7 is the single source of truth.
 
 4. .claude/rules/50.sync/ (2 sync rules)
    - 01.doc-sync.md — Bidirectional standard ↔ rules sync reminder (both directions in ONE rule).

package/pass-prompts/templates/python-django/pass3.md

@@ -131,7 +131,7 @@ Generation targets:
      List only the standard files that were actually generated above. NOTE: `00.core/04.doc-writing-guide.md` is a FORWARD REFERENCE — Pass 4 will generate it; include it anyway. Do NOT add a "DO NOT Read" section here — that information lives in CLAUDE.md Section 7 (the single source of truth).
 
 4. .claude/rules/50.sync/ (2 sync rules — AI fallback reminders)
-   - NOTE: These rules remind AI to run `npx claudeos-core refresh` after modifying standard/rules/skills files.
+   - NOTE: These rules remind AI to keep standard ↔ rules ↔ MANIFEST in sync when it edits any of them (`npx claudeos-core health` reports drift). Do NOT reference `npx claudeos-core refresh` — it is a no-op since v2.1.0.
    - 01.doc-sync.md — Bidirectional standard ↔ rules sync reminder (both directions in ONE rule).
      Do NOT generate a separate 02.rules-sync.md mirror file — redundant.
      Express the mapping as a naming convention (standard/<N>.<dir>/<M>.<n>.md ↔

package/pass-prompts/templates/python-fastapi/pass3.md

@@ -132,7 +132,7 @@ Generation targets:
      List only the standard files that were actually generated above. NOTE: `00.core/04.doc-writing-guide.md` is a FORWARD REFERENCE — Pass 4 will generate it; include it anyway. Do NOT add a "DO NOT Read" section here — that information lives in CLAUDE.md Section 7 (the single source of truth).
 
 4. .claude/rules/50.sync/ (2 sync rules — AI fallback reminders)
-   - NOTE: These rules remind AI to run `npx claudeos-core refresh` after modifying standard/rules/skills files.
+   - NOTE: These rules remind AI to keep standard ↔ rules ↔ MANIFEST in sync when it edits any of them (`npx claudeos-core health` reports drift). Do NOT reference `npx claudeos-core refresh` — it is a no-op since v2.1.0.
    - 01.doc-sync.md — Bidirectional standard ↔ rules sync reminder (both directions in ONE rule).
      Do NOT generate a separate 02.rules-sync.md mirror file — redundant.
      Express the mapping as a naming convention (standard/<N>.<dir>/<M>.<n>.md ↔

package/pass-prompts/templates/python-flask/pass3.md

@@ -84,6 +84,7 @@ Generation targets:
      - `60.memory/*` rules: forward reference — Pass 4 will generate 4 files (01.decision-log, 02.failure-patterns, 03.compaction, 04.auto-rule-update), each with file-specific `paths`. Pass 3 must STILL list ```.claude/rules/60.memory/*``` as a row in CLAUDE.md Section 6 Rules table so developers/Claude see the category exists.
      - `70.domains/*` rules (multi-domain projects only): per-domain rules at `.claude/rules/70.domains/{type}/{domain}-rules.md` (where `{type}` is `backend` or `frontend`, ALWAYS present even in single-stack projects for uniform layout + zero-migration future-proofing), each with a `paths:` glob scoped to that domain's source directories so the rule auto-loads only when editing files within the relevant domain. Folder name is PLURAL (`domains/`) — collection of N per-domain files — and each file inside uses the SINGULAR domain name (`{domain}-rules.md`). DO NOT use `60.domains/` (collides with `60.memory/`) and DO NOT skip the `{type}/` sub-folder. See pass3-footer.md "Per-domain folder convention" for the full rationale.
    - MUST generate `.claude/rules/00.core/00.standard-reference.md` — directory of all standard files
+     (paths only, grouped by category). Include the FORWARD REFERENCE `claudeos-core/standard/00.core/04.doc-writing-guide.md` under `## Core` — Pass 4 generates it; omitting it leaves an index gap the moment Pass 4 runs. Do NOT add a "DO NOT Read" section here — CLAUDE.md Section 7 is the single source of truth.
 
 4. .claude/rules/50.sync/ (2 sync rules)
    - 01.doc-sync.md — Bidirectional standard ↔ rules sync reminder (both directions in ONE rule).

package/pass-prompts/templates/vue-nuxt/pass3.md

@@ -82,6 +82,7 @@ Generation targets:
      - `60.memory/*` rules: forward reference — Pass 4 will generate 4 files (01.decision-log, 02.failure-patterns, 03.compaction, 04.auto-rule-update), each with file-specific `paths`. Pass 3 must STILL list ```.claude/rules/60.memory/*``` as a row in CLAUDE.md Section 6 Rules table so developers/Claude see the category exists.
      - `70.domains/*` rules (multi-domain projects only): per-domain rules at `.claude/rules/70.domains/{type}/{domain}-rules.md` (where `{type}` is `backend` or `frontend`, ALWAYS present even in single-stack projects for uniform layout + zero-migration future-proofing), each with a `paths:` glob scoped to that domain's source directories so the rule auto-loads only when editing files within the relevant domain. Folder name is PLURAL (`domains/`) — collection of N per-domain files — and each file inside uses the SINGULAR domain name (`{domain}-rules.md`). DO NOT use `60.domains/` (collides with `60.memory/`) and DO NOT skip the `{type}/` sub-folder. See pass3-footer.md "Per-domain folder convention" for the full rationale.
    - MUST generate `.claude/rules/00.core/00.standard-reference.md` — directory of all standard files
+     (paths only, grouped by category). Include the FORWARD REFERENCE `claudeos-core/standard/00.core/04.doc-writing-guide.md` under `## Core` — Pass 4 generates it; omitting it leaves an index gap the moment Pass 4 runs. Do NOT add a "DO NOT Read" section here — CLAUDE.md Section 7 is the single source of truth.
 
 4. .claude/rules/50.sync/ (2 sync rules)
    - 01.doc-sync.md — Bidirectional standard ↔ rules sync reminder (both directions in ONE rule).

package/plan-installer/domain-grouper.js

@@ -103,7 +103,10 @@ function selectTemplates(stack) {
   if (stack.frontend === "nextjs") {
     templates.frontend = "node-nextjs";
   } else if (stack.frontend === "react") {
-    templates.frontend = stack.framework === "vite" ? "node-vite" : "node-nextjs";
+    // `framework === "vite"` only when no backend framework was detected;
+    // `frontendBundler === "vite"` (v2.5.0) covers Spring/Django + React/Vite
+    // repos (root or `frontend/` sub-directory) where `framework` is the backend.
+    templates.frontend = (stack.framework === "vite" || stack.frontendBundler === "vite") ? "node-vite" : "node-nextjs";
   } else if (stack.frontend === "vue") {
     templates.frontend = "vue-nuxt";
   } else if (stack.frontend === "angular") {

package/plan-installer/index.js

@@ -37,7 +37,7 @@ async function main() {
   if (!stack.language && !stack.framework) {
     console.warn("\n  ⚠️  No language or framework detected.");
     console.warn("  Supported: Java, Kotlin, TypeScript, JavaScript, Python");
-    console.warn("  Ensure you have build.gradle, package.json, pyproject.toml, or requirements.txt in the project root.\n");
+    console.warn("  Ensure you have build.gradle(.kts), pom.xml, package.json, pyproject.toml, or requirements.txt in the project root.\n");
   }
   console.log(`    Frontend:    ${stack.frontend || "none"} ${stack.frontendVersion || ""}`);
   // v2.4.0 — when a project ships more than one DB driver (e.g. Oracle +
@@ -115,7 +115,7 @@ async function main() {
   // Phase 6: Prompt generation
   const lang = process.env.CLAUDEOS_LANG || "en";
   console.log(`  [Phase 6] Generating prompts (lang: ${lang})...`);
-  generatePrompts(templates, lang, TEMPLATES_DIR, GENERATED_DIR);
+  generatePrompts(templates, lang, TEMPLATES_DIR, GENERATED_DIR, stack);
   console.log();
 
   // Save outputs
@@ -127,15 +127,34 @@ async function main() {
   //      the project declares no port of its own. This is a last-resort
   //      default; prefer that stack-detector extract it from .env.example
   //      to keep CLAUDE.md truthful to what the project actually runs.
-  const defaultPort = (stack.framework === "fastapi" || stack.framework === "django") ? 8000
+  //
+  // v2.5.0 — backend port and frontend dev-server port are resolved
+  // SEPARATELY. Pre-v2.5.0 the single chain (`stack.frontend === "angular"
+  // ? 4200 …`) handed a Spring/Django backend the Angular/Next dev-server
+  // port whenever a SPA lived beside it. Now:
+  //   stack.port         — the backend's port when a backend exists; for a
+  //                        frontend-only project it is the dev-server port.
+  //   stack.frontendPort — the SPA's dev-server port whenever a frontend
+  //                        exists: sub-directory `.env*` (stack-detector) →
+  //                        root `.env*` PORT for a root SPA → convention.
+  // Same definition as stack-detector's env-port split: a JVM/Python project
+  // is a backend even when no framework was recognized (plain Maven/Gradle
+  // project without Spring Boot coordinates).
+  const hasBackend = (!!stack.framework && stack.framework !== "vite") || ["java", "kotlin", "python"].includes(stack.language);
+  const backendDefaultPort = (stack.framework === "fastapi" || stack.framework === "django") ? 8000
     : stack.framework === "flask" ? 5000
-    : stack.framework === "vite" ? 5173
-    : stack.frontend === "angular" ? 4200
-    : stack.frontend === "nextjs" ? 3000
     : (stack.framework === "express" || stack.framework === "nestjs" || stack.framework === "fastify") ? 3000 : 8080;
+  const frontendDefaultPort = (stack.frontendBundler === "vite" || stack.framework === "vite") ? 5173
+    : stack.frontend === "angular" ? 4200
+    : 3000;
+  const frontendPort = !stack.frontend ? null
+    : stack.frontendPort ? stack.frontendPort
+    : (!hasBackend && stack.port) ? stack.port
+    : frontendDefaultPort;
+  const defaultPort = hasBackend ? backendDefaultPort : (stack.frontend ? frontendPort : backendDefaultPort);
   const analysis = {
     analyzedAt: new Date().toISOString(), lang,
-    stack: { ...stack, port: stack.port || defaultPort },
+    stack: { ...stack, port: stack.port || defaultPort, ...(frontendPort ? { frontendPort } : {}) },
     templates, isMultiStack, rootPackage,
     domains, backendDomains, frontendDomains, frontend,
     activeDomains: active,

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

@@ -159,6 +159,16 @@ function buildPass3Context(generatedDir) {
       orm: stack.orm || null,
       frontend: stack.frontend || null,
       frontendVersion: stack.frontendVersion || null,
+      // v2.5.0 — sub-directory SPA (`frontend/`, `client/`, …). Pass 3 must
+      // cite frontend paths under this prefix; null when the SPA is at root.
+      frontendRoot: stack.frontendRoot || null,
+      frontendBundler: stack.frontendBundler || null,
+      // Sub-directory SPA's own .env facts (port / API target); null when
+      // the SPA is at root or declares no env file.
+      frontendPort: stack.frontendPort || null,
+      frontendEnvInfo: stack.frontendEnvInfo
+        ? { source: stack.frontendEnvInfo.source || null, port: stack.frontendEnvInfo.port || null, apiTarget: stack.frontendEnvInfo.apiTarget || null }
+        : null,
       port: extractPort(analysis),
     },
 

package/plan-installer/prompt-generator.js

@@ -15,14 +15,30 @@ const { readFileSafe, readJsonSafe, existsSafe, writeFileSafe } = require("../li
  * @param {string} templatesDir - path to pass-prompts/templates/
  * @param {string} generatedDir - path to claudeos-core/generated/
  */
-function generatePrompts(templates, lang, templatesDir, generatedDir) {
+function generatePrompts(templates, lang, templatesDir, generatedDir, stack) {
   const commonDir  = path.join(templatesDir, "common");
   const headerPath = path.join(commonDir, "header.md");
   const footerPath = path.join(commonDir, "pass3-footer.md");
   const langPath   = path.join(commonDir, "lang-instructions.json");
   const stagingOverridePath = path.join(commonDir, "staging-override.md");
 
-  const header = existsSafe(headerPath) ? readFileSafe(headerPath) : "";
+  let header = existsSafe(headerPath) ? readFileSafe(headerPath) : "";
+  // v2.5.0 — Sub-directory SPA. When stack-detector found the frontend under
+  // `frontend/` (stack.frontendRoot), every prompt must know that the
+  // frontend examples in the stack templates (`app/dashboard/page.tsx`,
+  // `src/components/...`) live under that prefix. Without this line the
+  // model looks for `app/` at the project root, finds nothing, and either
+  // guesses or reports the frontend as absent. The scanner-side allowlist
+  // already carries the prefixed paths; this keeps Pass 1/2 consistent.
+  const frontendRoot = stack && typeof stack.frontendRoot === "string" && stack.frontendRoot.trim()
+    ? stack.frontendRoot.replace(/\\/g, "/").replace(/\/+$/, "")
+    : null;
+  if (frontendRoot) {
+    header += `Frontend source root: {{PROJECT_ROOT}}/${frontendRoot}/\n` +
+      `The frontend application lives in the \`${frontendRoot}/\` sub-directory (own package.json). ` +
+      `Every frontend path in these instructions (\`app/\`, \`pages/\`, \`src/\`, \`components/\`, config files) ` +
+      `is relative to \`${frontendRoot}/\`; cite it as \`${frontendRoot}/app/...\` when writing project-relative paths.\n\n---\n\n`;
+  }
   const footer = existsSafe(footerPath) ? readFileSafe(footerPath) : "";
   // Injected into pass3/pass4 prompts — redirects .claude/rules/* writes to
   // claudeos-core/generated/.staged-rules/* to bypass Claude Code's sensitive-