claudeos-core 2.3.1 → 2.4.0

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

@@ -56,20 +56,20 @@ Generation targets:
    - 00.core/01.project-overview.md — Stack, app list, server info
    - 00.core/02.architecture.md — MTV structure, request flow, app structure
    - 00.core/03.naming-conventions.md — App/model/view/serializer naming conventions
-   - 10.backend-api/01.view-patterns.md — FBV/CBV/ViewSet patterns + examples
-   - 10.backend-api/02.serializer-patterns.md — Serializer writing rules + validation
-   - 10.backend-api/03.model-patterns.md — Model structure, Manager, Signal, QuerySet
-   - 10.backend-api/04.response-exception.md — Response/error handling patterns
-   - 10.backend-api/05.business-logic.md — Service Layer, transactions, Celery
-   - 10.backend-api/06.admin-patterns.md — Admin customization, Inline, actions
+   - 10.backend/01.view-patterns.md — FBV/CBV/ViewSet patterns + examples
+   - 10.backend/02.serializer-patterns.md — Serializer writing rules + validation
+   - 10.backend/03.model-patterns.md — Model structure, Manager, Signal, QuerySet
+   - 10.backend/04.response-exception.md — Response/error handling patterns
+   - 10.backend/05.business-logic.md — Service Layer, transactions, Celery
+   - 10.backend/06.admin-patterns.md — Admin customization, Inline, actions
    - 30.security-db/01.security-auth.md — JWT, Permission, CORS, CSRF
    - 30.security-db/02.database-schema.md — Migrations, fixtures, schema conventions
    - 30.security-db/03.common-utilities.md — Common utils, custom Manager, constants
    - 40.infra/01.environment-config.md — Settings separation, environment variables
    - 40.infra/02.logging-monitoring.md — Logging standards, monitoring
    - 40.infra/03.cicd-deployment.md — CI/CD, Docker, deployment strategy
-   - 50.verification/01.development-verification.md — Testing, startup, API testing
-   - 50.verification/02.testing-strategy.md — pytest, Factory, mocking, coverage
+   - 80.verification/01.development-verification.md — Testing, startup, API testing
+   - 80.verification/02.testing-strategy.md — pytest, Factory, mocking, coverage
 
    Each file MUST include:
    - Correct examples (✅ code blocks)
@@ -83,7 +83,7 @@ Generation targets:
    - 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.view-patterns.md
+     > For detailed patterns and examples, Read: claudeos-core/standard/10.backend/01.view-patterns.md
      ```
    - `paths:` frontmatter per rule category:
      - `00.core/*` rules: `paths: ["**/*"]` — always loaded (architecture, naming are universally needed)
@@ -94,6 +94,7 @@ Generation targets:
      - `40.infra/03.cicd-deployment-rules.md` paths: `["**/*.yml", "**/*.yaml", "**/Dockerfile*", "**/*.py"]` — CI / deploy config + source
      - `50.sync/*` rules: `paths: ["**/claudeos-core/**", "**/.claude/**"]` — loaded only when editing claudeos-core files
      - `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` — 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:
      ```
      ---
@@ -110,12 +111,12 @@ Generation targets:
      - claudeos-core/standard/00.core/03.naming-conventions.md
      - claudeos-core/standard/00.core/04.doc-writing-guide.md
      ## Backend API
-     - claudeos-core/standard/10.backend-api/01.view-patterns.md
-     - claudeos-core/standard/10.backend-api/02.serializer-patterns.md
-     - claudeos-core/standard/10.backend-api/03.model-patterns.md
-     - claudeos-core/standard/10.backend-api/04.response-exception.md
-     - claudeos-core/standard/10.backend-api/05.business-logic.md
-     - claudeos-core/standard/10.backend-api/06.admin-patterns.md
+     - claudeos-core/standard/10.backend/01.view-patterns.md
+     - claudeos-core/standard/10.backend/02.serializer-patterns.md
+     - claudeos-core/standard/10.backend/03.model-patterns.md
+     - claudeos-core/standard/10.backend/04.response-exception.md
+     - claudeos-core/standard/10.backend/05.business-logic.md
+     - claudeos-core/standard/10.backend/06.admin-patterns.md
      ## Security & DB
      - claudeos-core/standard/30.security-db/01.security-auth.md
      - claudeos-core/standard/30.security-db/02.database-schema.md
@@ -124,8 +125,8 @@ Generation targets:
      - claudeos-core/standard/40.infra/01.environment-config.md
      - claudeos-core/standard/40.infra/02.logging-monitoring.md
      - claudeos-core/standard/40.infra/03.cicd-deployment.md
-     - claudeos-core/standard/50.verification/01.development-verification.md
-     - claudeos-core/standard/50.verification/02.testing-strategy.md
+     - claudeos-core/standard/80.verification/01.development-verification.md
+     - claudeos-core/standard/80.verification/02.testing-strategy.md
      ```
      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).
 

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

@@ -57,20 +57,20 @@ Generation targets:
    - 00.core/01.project-overview.md — Stack, modules, server info
    - 00.core/02.architecture.md — Layer structure, request flow, directory structure
    - 00.core/03.naming-conventions.md — Module/schema/model/router naming conventions
-   - 10.backend-api/01.router-endpoint-patterns.md — Router patterns + decorators
-   - 10.backend-api/02.schema-pydantic-patterns.md — Pydantic conventions, validation
-   - 10.backend-api/03.data-access-patterns.md — ORM, Repository, query optimization
-   - 10.backend-api/04.response-exception.md — Response/error handling patterns
-   - 10.backend-api/05.dependency-injection.md — Depends chain, lifecycle
-   - 10.backend-api/06.middleware-patterns.md — CORS, custom middleware, order
+   - 10.backend/01.router-endpoint-patterns.md — Router patterns + decorators
+   - 10.backend/02.schema-pydantic-patterns.md — Pydantic conventions, validation
+   - 10.backend/03.data-access-patterns.md — ORM, Repository, query optimization
+   - 10.backend/04.response-exception.md — Response/error handling patterns
+   - 10.backend/05.dependency-injection.md — Depends chain, lifecycle
+   - 10.backend/06.middleware-patterns.md — CORS, custom middleware, order
    - 30.security-db/01.security-auth.md — JWT, OAuth2, CORS, Rate Limit
    - 30.security-db/02.database-schema.md — Alembic, schema conventions
    - 30.security-db/03.common-utilities.md — Common utils, dependency functions, constants
    - 40.infra/01.environment-config.md — pydantic-settings, environment variables
    - 40.infra/02.logging-monitoring.md — Logging standards, monitoring
    - 40.infra/03.cicd-deployment.md — CI/CD, Docker, uvicorn deployment
-   - 50.verification/01.development-verification.md — pytest, startup, API testing
-   - 50.verification/02.testing-strategy.md — Async testing, dependency overrides, mocking
+   - 80.verification/01.development-verification.md — pytest, startup, API testing
+   - 80.verification/02.testing-strategy.md — Async testing, dependency overrides, mocking
 
    Each file MUST include:
    - Correct examples (✅ code blocks)
@@ -84,7 +84,7 @@ Generation targets:
    - 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-endpoint-patterns.md
+     > For detailed patterns and examples, Read: claudeos-core/standard/10.backend/01.router-endpoint-patterns.md
      ```
    - `paths:` frontmatter per rule category:
      - `00.core/*` rules: `paths: ["**/*"]` — always loaded (architecture, naming are universally needed)
@@ -95,6 +95,7 @@ Generation targets:
      - `40.infra/03.cicd-deployment-rules.md` paths: `["**/*.yml", "**/*.yaml", "**/Dockerfile*", "**/*.py"]` — CI / deploy config + source
      - `50.sync/*` rules: `paths: ["**/claudeos-core/**", "**/.claude/**"]` — loaded only when editing claudeos-core files
      - `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` — 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:
      ```
      ---
@@ -111,12 +112,12 @@ Generation targets:
      - claudeos-core/standard/00.core/03.naming-conventions.md
      - claudeos-core/standard/00.core/04.doc-writing-guide.md
      ## Backend API
-     - claudeos-core/standard/10.backend-api/01.router-endpoint-patterns.md
-     - claudeos-core/standard/10.backend-api/02.schema-pydantic-patterns.md
-     - claudeos-core/standard/10.backend-api/03.data-access-patterns.md
-     - claudeos-core/standard/10.backend-api/04.response-exception.md
-     - claudeos-core/standard/10.backend-api/05.dependency-injection.md
-     - claudeos-core/standard/10.backend-api/06.middleware-patterns.md
+     - claudeos-core/standard/10.backend/01.router-endpoint-patterns.md
+     - claudeos-core/standard/10.backend/02.schema-pydantic-patterns.md
+     - claudeos-core/standard/10.backend/03.data-access-patterns.md
+     - claudeos-core/standard/10.backend/04.response-exception.md
+     - claudeos-core/standard/10.backend/05.dependency-injection.md
+     - claudeos-core/standard/10.backend/06.middleware-patterns.md
      ## Security & DB
      - claudeos-core/standard/30.security-db/01.security-auth.md
      - claudeos-core/standard/30.security-db/02.database-schema.md
@@ -125,8 +126,8 @@ Generation targets:
      - claudeos-core/standard/40.infra/01.environment-config.md
      - claudeos-core/standard/40.infra/02.logging-monitoring.md
      - claudeos-core/standard/40.infra/03.cicd-deployment.md
-     - claudeos-core/standard/50.verification/01.development-verification.md
-     - claudeos-core/standard/50.verification/02.testing-strategy.md
+     - claudeos-core/standard/80.verification/01.development-verification.md
+     - claudeos-core/standard/80.verification/02.testing-strategy.md
      ```
      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).
 

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

@@ -51,21 +51,21 @@ Generation targets:
    - 00.core/01.project-overview.md — Stack, modules, server info
    - 00.core/02.architecture.md — Application factory, Blueprint hierarchy, request flow
    - 00.core/03.naming-conventions.md — Module/model/blueprint/route naming conventions
-   - 10.backend-api/01.route-blueprint-patterns.md — Blueprint structure, route decorators, request/response handling
-   - 10.backend-api/02.model-schema-patterns.md — SQLAlchemy models, marshmallow/WTForms serialization
-   - 10.backend-api/03.service-patterns.md — Service layer, business logic separation
-   - 10.backend-api/04.response-error-patterns.md — Response formatting, error handlers, custom exceptions
+   - 10.backend/01.route-blueprint-patterns.md — Blueprint structure, route decorators, request/response handling
+   - 10.backend/02.model-schema-patterns.md — SQLAlchemy models, marshmallow/WTForms serialization
+   - 10.backend/03.service-patterns.md — Service layer, business logic separation
+   - 10.backend/04.response-error-patterns.md — Response formatting, error handlers, custom exceptions
    - 30.security-db/01.security-auth.md — Authentication, CSRF, session management, environment variables
    - 30.security-db/02.database-patterns.md — SQLAlchemy patterns, migrations, relationships
    - 40.infra/01.environment-config.md — Config classes, environment variables, extension initialization
    - 40.infra/02.logging-monitoring.md — app.logger, request logging, error tracking
    - 40.infra/03.cicd-deployment.md — CI/CD, gunicorn, Docker deployment
-   - 50.verification/01.development-verification.md — Build, startup, flask run
-   - 50.verification/02.testing-strategy.md — pytest, test_client, fixtures, DB testing
+   - 80.verification/01.development-verification.md — Build, startup, flask run
+   - 80.verification/02.testing-strategy.md — pytest, test_client, fixtures, DB testing
 
    Each file MUST include:
-   - Correct examples (code blocks)
-   - Incorrect examples (code blocks)
+   - Correct examples (✅ code blocks)
+   - Incorrect examples (❌ code blocks)
    - Key rules summary table
 
 3. .claude/rules/ (active domains only)
@@ -82,6 +82,7 @@ Generation targets:
      - `40.infra/03.cicd-deployment-rules.md` paths: `["**/*.yml", "**/*.yaml", "**/Dockerfile*", "**/*.py"]` — CI / deploy config + source
      - `50.sync/*` rules: `paths: ["**/claudeos-core/**", "**/.claude/**"]`
      - `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
 
 4. .claude/rules/50.sync/ (2 sync rules)

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

@@ -47,18 +47,18 @@ Generation targets:
    - 00.core/01.project-overview.md — Stack, routing approach, deployment environment
    - 00.core/02.architecture.md — Nuxt/Vue structure, component hierarchy, data flow, Nitro server
    - 00.core/03.naming-conventions.md — File/component/composable/store naming conventions
-   - 20.frontend-ui/01.component-patterns.md — SFC, <script setup>, Props/Emits, slots, provide/inject
-   - 20.frontend-ui/02.page-routing-patterns.md — Pages/layouts/dynamic routes/middleware/definePageMeta
-   - 20.frontend-ui/03.data-fetching.md — useFetch, useAsyncData, $fetch, server routes, caching
-   - 20.frontend-ui/04.state-management.md — Pinia stores, composables, useState, form state
-   - 20.frontend-ui/05.styling-patterns.md — Scoped styles, CSS Modules, Tailwind/UnoCSS, theming
-   - 10.backend-api/01.server-routes.md — Nitro server routes (server/api/), H3 event handlers
+   - 20.frontend/01.component-patterns.md — SFC, <script setup>, Props/Emits, slots, provide/inject
+   - 20.frontend/02.page-routing-patterns.md — Pages/layouts/dynamic routes/middleware/definePageMeta
+   - 20.frontend/03.data-fetching.md — useFetch, useAsyncData, $fetch, server routes, caching
+   - 20.frontend/04.state-management.md — Pinia stores, composables, useState, form state
+   - 20.frontend/05.styling-patterns.md — Scoped styles, CSS Modules, Tailwind/UnoCSS, theming
+   - 10.backend/01.server-routes.md — Nitro server routes (server/api/), H3 event handlers
    - 30.security-db/01.security-auth.md — Auth, middleware protection, environment variables
    - 40.infra/01.environment-config.md — Runtime config, nuxt.config.ts, Nitro presets
    - 40.infra/02.logging-monitoring.md — Error tracking, analytics, Web Vitals
    - 40.infra/03.cicd-deployment.md — CI/CD, deployment (Vercel/Netlify/Docker), preview
-   - 50.verification/01.development-verification.md — Build, startup, Lighthouse
-   - 50.verification/02.testing-strategy.md — Vitest, @vue/test-utils, E2E, @nuxt/test-utils
+   - 80.verification/01.development-verification.md — Build, startup, Lighthouse
+   - 80.verification/02.testing-strategy.md — Vitest, @vue/test-utils, E2E, @nuxt/test-utils
 
    Each file MUST include:
    - Correct examples (✅ code blocks)
@@ -80,6 +80,7 @@ Generation targets:
      - `40.infra/03.cicd-deployment-rules.md` paths: `["**/*.yml", "**/*.yaml", "**/Dockerfile*", "**/*.ts", "**/*.vue"]` — CI config + source
      - `50.sync/*` rules: `paths: ["**/claudeos-core/**", "**/.claude/**"]`
      - `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
 
 4. .claude/rules/50.sync/ (2 sync rules)

package/plan-installer/domain-grouper.js

@@ -5,22 +5,62 @@
  * and selects appropriate templates based on detected stack.
  */
 
+// ─── Splitting thresholds ───────────────────────────────────────
+//
+// MAX_FILES_PER_GROUP and MAX_DOMAINS_PER_GROUP are the original budgets that
+// have governed Pass 1 batching since v1.x. They are sound for projects with
+// a roughly uniform file-size distribution but can produce time-outlier
+// batches when a single domain contains a very large file (e.g. a 2500-line
+// TUI Grid wrapper) — observed in field testing where a group of ~29
+// files ran ~70% longer than a group of 39 files.
+//
+// MAX_LINES_PER_GROUP is the optional second axis. It only fires when the
+// caller supplies per-domain `totalLines`; scanners that do not yet record
+// line counts leave it unset and the line-budget check is skipped, so this
+// field is strictly additive (no behavior change for existing scanners).
+//
+// The 8000-line threshold is a pragmatic starting point calibrated against
+// observed field tests: ~40 files × ~200 lines/file average. It can be
+// tuned later once more scanners populate `totalLines` and we have more
+// data on per-stack line-count distributions.
+const MAX_FILES_PER_GROUP = 40;
+const MAX_DOMAINS_PER_GROUP = 4;
+const MAX_LINES_PER_GROUP = 8000;
+
 function splitDomainGroups(domains, type, template) {
-  const MAX_FILES_PER_GROUP = 40;
-  const MAX_DOMAINS_PER_GROUP = 4;
   const groups = [];
   let current = [];
   let fileCount = 0;
+  let lineCount = 0;
 
   for (const d of domains) {
-    // Flush current group before adding if it would exceed limits
-    if (current.length > 0 && (fileCount + d.totalFiles > MAX_FILES_PER_GROUP || current.length >= MAX_DOMAINS_PER_GROUP)) {
+    // Read `totalLines` as an optional signal. Domains produced by scanners
+    // that have not yet been extended to record line counts leave this
+    // undefined, which makes the line-budget check a no-op (0 + undefined
+    // stays undefined; the `hasLines` guard below suppresses the comparison
+    // entirely in that case). This preserves exact byte-for-byte output for
+    // all existing callers.
+    const domainLines = (typeof d.totalLines === "number" && d.totalLines >= 0) ? d.totalLines : 0;
+    const hasLines = domainLines > 0;
+
+    // Flush current group before adding if it would exceed any budget.
+    // The line-budget condition (`hasLines && ...`) is only evaluated when
+    // the incoming domain actually carries line-count data — callers using
+    // the legacy `{ name, totalFiles }` shape retain the original 2-axis
+    // behavior.
+    const wouldExceedFiles = fileCount + d.totalFiles > MAX_FILES_PER_GROUP;
+    const wouldExceedDomains = current.length >= MAX_DOMAINS_PER_GROUP;
+    const wouldExceedLines = hasLines && (lineCount + domainLines > MAX_LINES_PER_GROUP);
+
+    if (current.length > 0 && (wouldExceedFiles || wouldExceedDomains || wouldExceedLines)) {
       groups.push({ type, template, domains: [...current], estimatedFiles: fileCount });
       current = [];
       fileCount = 0;
+      lineCount = 0;
     }
     current.push(d.name);
     fileCount += d.totalFiles;
+    lineCount += domainLines;
   }
   if (current.length > 0) {
     groups.push({ type, template, domains: [...current], estimatedFiles: fileCount });
@@ -38,7 +78,7 @@ function determineActiveDomains(stack) {
     "20.frontend": !!stack.frontend,
     "30.security-db": !!(stack.database || isBackend || stack.frontend),
     "40.infra": true,
-    "50.verification": true,
+    "80.verification": true,
     "90.optional": true,
   };
 }

package/plan-installer/index.js

@@ -16,6 +16,7 @@ const { detectStack } = require("./stack-detector");
 const { scanStructure } = require("./structure-scanner");
 const { splitDomainGroups, determineActiveDomains, selectTemplates } = require("./domain-grouper");
 const { generatePrompts } = require("./prompt-generator");
+const { collectSourcePaths } = require("./source-paths");
 
 const ROOT = process.env.CLAUDEOS_ROOT || path.resolve(__dirname, "../..");
 const GENERATED_DIR = path.join(ROOT, "claudeos-core/generated");
@@ -39,7 +40,17 @@ async function main() {
     console.warn("  Ensure you have build.gradle, package.json, pyproject.toml, or requirements.txt in the project root.\n");
   }
   console.log(`    Frontend:    ${stack.frontend || "none"} ${stack.frontendVersion || ""}`);
-  console.log(`    Database:    ${stack.database || "none"}`);
+  // v2.4.0 — when a project ships more than one DB driver (e.g. Oracle +
+  // MySQL master/slave), surface the full list so downstream LLMs (Pass 1)
+  // see the dual-dialect setup without having to re-derive it from source
+  // code. Singular `Database:` line preserved for byte-for-byte parity in
+  // single-DB projects (the dominant case).
+  if (Array.isArray(stack.databases) && stack.databases.length > 1) {
+    console.log(`    Database:    ${stack.database} (primary)`);
+    console.log(`    Databases:   ${stack.databases.join(", ")} (multi-dialect)`);
+  } else {
+    console.log(`    Database:    ${stack.database || "none"}`);
+  }
   console.log(`    ORM:         ${stack.orm || "none"}`);
   console.log(`    PackageMgr:  ${stack.packageManager || "none"}\n`);
 
@@ -57,6 +68,23 @@ async function main() {
   }
   console.log();
 
+  // Phase 2.5: Allowed source paths (v2.3.x+ — path-hallucination prevention)
+  //
+  // Collect the authoritative list of source files that actually exist on
+  // disk. Pass 3/4 prompts use this list (via pass3a-facts.md and the
+  // pass3-footer.md grounding rule) to refuse citations of convention-based
+  // fabricated paths like `src/app/providers.tsx` when the project does
+  // not in fact ship that file. See plan-installer/source-paths.js for
+  // the full rationale.
+  console.log("  [Phase 2.5] Collecting source-path allowlist...");
+  const sourcePaths = await collectSourcePaths(ROOT);
+  if (sourcePaths.mode === "full") {
+    console.log(`    ${sourcePaths.totalFiles} source file(s) enumerated (full mode)`);
+  } else {
+    console.log(`    ${sourcePaths.totalFiles} source files across ${sourcePaths.paths.length} dirs (rollup mode — project exceeds enumeration budget)`);
+  }
+  console.log();
+
   // Phase 3: Template selection
   console.log("  [Phase 3] Selecting templates...");
   const templates = selectTemplates(stack);
@@ -111,6 +139,11 @@ async function main() {
     templates, isMultiStack, rootPackage,
     domains, backendDomains, frontendDomains, frontend,
     activeDomains: active,
+    // v2.3.x+: authoritative on-disk source-file list. Consumed by
+    // pass3-context-builder → pass3a-facts.md → Pass 3/4 prompts to
+    // prevent convention-based path hallucination (e.g. Next.js
+    // `src/app/providers.tsx` when the project does not ship it).
+    allowedSourcePaths: sourcePaths,
     summary: {
       totalDomains: domains.length, backendDomains: backendDomains.length,
       frontendDomains: frontendDomains.length,

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

@@ -192,6 +192,20 @@ function buildPass3Context(generatedDir) {
     // ─── Frontend stats (if scan-frontend ran) ──────────────────────────
     frontend: analysis.frontend || { exists: false },
 
+    // ─── Source path allowlist (v2.3.x+ — path-hallucination prevention) ─
+    // Authoritative on-disk source-file list, copied from project-analysis.
+    // Pass 3a includes a rendered form of this in pass3a-facts.md as
+    // "## Allowed Source Paths". Pass 3b/3c/3d then cite ONLY from this
+    // list when writing `src/...` / `packages/...` / language-specific
+    // paths in rule/standard files.
+    //
+    // Shape: { mode: "full" | "rollup", paths: string[], totalFiles: number,
+    //          excludedDirs: string[] }
+    // See plan-installer/source-paths.js for the full contract.
+    allowedSourcePaths: (analysis.allowedSourcePaths && typeof analysis.allowedSourcePaths === "object")
+      ? analysis.allowedSourcePaths
+      : { mode: "full", paths: [], totalFiles: 0, excludedDirs: [] },
+
     // ─── 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.

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

@@ -383,7 +383,8 @@ async function scanFrontendDomains(stack, ROOT) {
     // Emitting those as domains fragments one logical app into 5+
     // pseudo-domains, which in turn primes Pass 3 to fabricate
     // prefixed filenames (featureRoutePath.ts, admin-api.service.ts) —
-    // the hallucination class observed in frontend-react-B dogfooding.
+    // a canonical hallucination class the single-SPA rule is designed
+    // to prevent.
     //
     // Detection of "single-SPA" mode: inspect the top-level platform
     // segment for every glob match and count distinct values. If only

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

@@ -22,9 +22,42 @@ async function scanJavaDomains(stack, ROOT) {
   let rootPackage = null;
 
   const javaFiles = (await glob("src/main/java/**/*.java", { cwd: ROOT })).map(norm);
+
+  // v2.4.0 — Pick the LONGEST package prefix (1-4 segments) that still
+  // covers ≥80% of layer-bearing files. Pre-v2.4.0 the first matched file
+  // won, which misclassified projects whose actual production code lives
+  // under one root (e.g. `<orgA>.<projectA>.*`) but where a small number
+  // of stub files happen to sit under another deeper subtree (e.g.
+  // `<orgA>.<otherModule>.core.<dir>.*`) — glob enumeration order then
+  // determined the rootPackage non-deterministically.
+  //
+  // Algorithm: count every (1-, 2-, 3-, 4-)segment prefix preceding a
+  // known layer marker. Then pick the longest prefix whose count is at
+  // least 80% of the maximum (1-segment) count. This gives:
+  //   • Mono-package project (`com.example.app.*` only): root = `com.example.app`
+  //     (all 4 prefix lengths tied, longest = most specific root).
+  //   • Multi-module project (95% under `<root>.api.*`, 5% stubs under
+  //     `<root>.misc.*`): root = `<root>.api` (the LONGEST prefix that
+  //     still covers ≥80% of files), not `<root>` (too generic) and
+  //     not the minority `<root>.misc.*` location (no longer first-match).
+  const pkgCounts = new Map();
   for (const f of javaFiles) {
     const m = f.match(/src\/main\/java\/(.+?)\/(controller|aggregator|facade|usecase|orchestrator|service|mapper|dao|dto|entity|repository|adapter)/);
-    if (m) { rootPackage = m[1].replace(/\//g, "."); break; }
+    if (!m) continue;
+    const segs = m[1].split("/");
+    for (let len = Math.min(4, segs.length); len >= 1; len--) {
+      const prefix = segs.slice(0, len).join(".");
+      pkgCounts.set(prefix, (pkgCounts.get(prefix) || 0) + 1);
+    }
+  }
+  if (pkgCounts.size > 0) {
+    const maxCount = Math.max(...pkgCounts.values());
+    const threshold = Math.ceil(maxCount * 0.8);
+    const candidates = [...pkgCounts.entries()].filter(([_, c]) => c >= threshold);
+    // Among candidates, pick the longest prefix (most specific root that
+    // still covers the majority of files). Tie-break on length DESC.
+    candidates.sort((a, b) => b[0].length - a[0].length);
+    rootPackage = candidates[0][0];
   }
   const domainMap = {};
   let detectedPattern = null;
@@ -172,7 +205,70 @@ async function scanJavaDomains(stack, ROOT) {
     domainMap[d].mappers = mpr.length;
     domainMap[d].dtos = dto.length;
     domainMap[d].xmlMappers = xml.length;
-    const totalFiles = svc.length + agg.length + mpr.length + dto.length + xml.length + domainMap[d].controllers;
+
+    // v2.4.0 — Deep-sweep fallback (Pattern B/D only).
+    //
+    // Pre-v2.4.0: standard globs assume `{domain}/{layer}/X.java`. This
+    // misses two real-world layouts:
+    //   (a) Multi-module split: `front/{domain}/{layer}/` for HTTP
+    //       layer + `core/{domain}/{layer}/` for service/dao layer.
+    //       Standard glob `**/{domain}/{layer}/` actually matches BOTH
+    //       via the leading `**`, so this case generally works.
+    //   (b) Cross-domain coupling: `core/{otherDomain}/{layer}/{domain}/`
+    //       — services for `{domain}` living under a different module's
+    //       layer directory (the layer dir comes BEFORE the domain dir).
+    //       Standard glob `**/{domain}/{layer}/*.java` does NOT match
+    //       this layout.
+    //
+    // When standard globs return zero files for a Pattern B/D domain
+    // that is registered in domainMap (so it does exist), fall back to
+    // a deep sweep: `**/${dn}/**/*.java` finds every .java file under
+    // ANY directory named ${dn}. We then classify each file by walking
+    // up its path to find the nearest layer dir, which catches both
+    // `${dn}/{layer}/` AND `{layer}/${dn}/` placements.
+    //
+    // Restricting to Pattern B/D and to the zero-files case keeps the
+    // legacy behavior identical for projects whose standard globs
+    // already cover everything, and prevents over-counting for
+    // domains with healthy direct-layout file counts.
+    const standardCount = svc.length + agg.length + mpr.length + dto.length + xml.length;
+    if (standardCount === 0 && (p === "B" || p === "D")) {
+      const deepFiles = (await glob(`src/main/java/**/${dn}/**/*.java`, { cwd: ROOT })).map(norm);
+      // v2.4.0 — extended layer recognition. Real-world enterprise codebases
+      // commonly include implementation/support layers beyond the canonical
+      // controller/service/mapper/dto trio. Files in `factory/`, `strategy/`,
+      // `impl/`, `helper/`, etc. were previously dropped by deep-sweep
+      // (no `break`), causing domains with non-standard layer names to
+      // report 0 totalFiles. The recognized list is augmented and a
+      // catch-all classifies any remaining `.java` file under the domain
+      // tree as a service (the most generic backend layer).
+      const SVC_LAYERS = ["aggregator", "facade", "usecase", "orchestrator", "service",
+                          "factory", "strategy", "impl", "helper", "support",
+                          "client", "provider", "manager", "handler", "interceptor",
+                          "filter", "listener", "task", "scheduler", "command", "query",
+                          "validator", "converter", "translator", "resolver"];
+      const DAO_LAYERS = ["mapper", "repository", "dao"];
+      const DTO_LAYERS = ["dto", "vo", "entity", "model", "request", "response", "payload"];
+      for (const f of deepFiles) {
+        const parts = f.split("/");
+        let classified = false;
+        for (let i = parts.length - 2; i >= 0; i--) {
+          const seg = parts[i];
+          if (seg === "controller") { domainMap[d].controllers++; classified = true; break; }
+          if (SVC_LAYERS.includes(seg)) { domainMap[d].services++; classified = true; break; }
+          if (DAO_LAYERS.includes(seg)) { domainMap[d].mappers++; classified = true; break; }
+          if (DTO_LAYERS.includes(seg)) { domainMap[d].dtos++; classified = true; break; }
+        }
+        // Fallback: any unclassified .java file under the domain tree is
+        // counted as a service. This catches layouts like
+        // `core/${dn}/X.java` (no layer subdir) and prevents legitimate
+        // backend domains from reporting 0 totalFiles when their files
+        // happen to live under unrecognized parent directories.
+        if (!classified) domainMap[d].services++;
+      }
+    }
+
+    const totalFiles = domainMap[d].services + domainMap[d].mappers + domainMap[d].dtos + domainMap[d].xmlMappers + domainMap[d].controllers;
     backendDomains.push({ name: d, type: "backend", ...domainMap[d], totalFiles });
   }