claudeos-core 2.4.4 → 2.5.1

package/README.vi.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/claudeos-core.svg?logo=npm&label=npm)](https://www.npmjs.com/package/claudeos-core)
 [![CI](https://img.shields.io/github/actions/workflow/status/claudeos-core/claudeos-core/test.yml?branch=master&logo=github&label=CI)](https://github.com/claudeos-core/claudeos-core/actions/workflows/test.yml)
-[![tests](https://img.shields.io/badge/tests-736%20passing-brightgreen?logo=node.js&logoColor=white)](https://github.com/claudeos-core/claudeos-core/actions/workflows/test.yml)
+[![tests](https://img.shields.io/badge/tests-974%20passing-brightgreen?logo=node.js&logoColor=white)](https://github.com/claudeos-core/claudeos-core/actions/workflows/test.yml)
 [![node](https://img.shields.io/node/v/claudeos-core.svg?logo=node.js&logoColor=white&label=node)](https://nodejs.org/)
 [![license](https://img.shields.io/npm/l/claudeos-core.svg?color=blue)](LICENSE)
 [![downloads](https://img.shields.io/npm/dm/claudeos-core.svg?logo=npm&color=blue&label=downloads)](https://www.npmjs.com/package/claudeos-core)
@@ -25,7 +25,7 @@ Mỗi khi mở phiên mới, Claude Code lại rơi về mặc định của fra
 
 **ClaudeOS-Core sinh lại toàn bộ tài liệu này một cách nhất quán, đọc thẳng từ source code thật.** Đầu tiên, một Node.js scanner duyệt dự án để chốt stack, ORM, cấu trúc package và đường dẫn file. Tiếp đó pipeline 4-pass của Claude viết toàn bộ tài liệu: `CLAUDE.md`, `.claude/rules/` auto-load, standards và skills. Mọi pass đều bị khoá trong một allowlist đường dẫn tường minh, LLM không thoát ra được. Cuối cùng, năm validator soi lại kết quả trước khi xuất.
 
-Nhờ vậy, cùng input thì luôn ra cùng output, byte-identical ở cả 10 ngôn ngữ, và không bịa ra đường dẫn không có trong code. (Xem chi tiết ở phần [Điểm khác biệt](#điểm-khác-biệt) bên dưới.)
+Nhờ vậy, cùng input thì luôn ra cùng một `CLAUDE.md` với cấu trúc 8 section cố định, được kiểm bởi cùng 25 structural check ở cả 10 ngôn ngữ, và mọi đường dẫn source được trích dẫn đều được đối chiếu với đĩa. (Xem chi tiết ở phần [Điểm khác biệt](#điểm-khác-biệt) bên dưới.)
 
 Với các dự án chạy lâu dài, công cụ còn seed thêm một [Memory Layer](#memory-layer-tùy-chọn-cho-dự-án-dài-hạn) riêng.
 
@@ -115,7 +115,7 @@ Chạy thử trên [`spring-boot-realworld-example-app`](https://github.com/goth
 </details>
 
 <details>
-<summary><strong>Phần thực sự đi vào <code>CLAUDE.md</code> của bạn (trích đoạn thật — Section 1 + 2)</strong></summary>
+<summary><strong>Phần thực sự đi vào <code>CLAUDE.md</code> của bạn (trích đoạn thật — Section 1 + 2; heading được hạ xuống <code>####</code> để hiển thị trong README, file thật dùng <code>## N.</code>)</strong></summary>
 
 ```markdown
 # CLAUDE.md — spring-boot-realworld-example-app
@@ -148,7 +148,7 @@ an XML-driven MyBatis persistence layer and JWT-based authentication.
 | Test Stack | JUnit Jupiter 5, Mockito, AssertJ, rest-assured, spring-mock-mvc |
 ```
 
-Mọi giá trị trong bảng trên đều do scanner đọc thẳng từ `build.gradle`, `application.properties` và cây source trước khi Claude viết file. Toạ độ dependency, tên file `dev.db`, tên migration `V1__create_tables.sql`, ghi chú "no JPA" — tất cả đều là sự thật trích xuất, không chỗ nào là phỏng đoán.
+Các dòng stack (Java 11, Spring Boot 2.6.3, Gradle, MyBatis, SQLite, port 8080) đến từ scanner deterministic. Những chi tiết nhỏ hơn — toạ độ dependency chính xác, tên file `dev.db`, tên migration `V1__create_tables.sql`, ghi chú "no JPA" — do Pass 1 đọc từ `build.gradle`, `application.properties` và cây source, với các sự thật của scanner làm ràng buộc, rồi được validator đối chiếu lại. Không giá trị nào lấy từ default của framework.
 
 </details>
 
@@ -309,7 +309,7 @@ Các category cùng số prefix ở `rules/` và `standard/` cùng chỉ về m
 | Bạn là... | Vấn đề được giải quyết |
 |---|---|
 | **Solo dev** đang khởi động dự án mới với Claude Code | Khỏi phải dạy lại quy ước cho Claude mỗi phiên. `CLAUDE.md` cùng 8 category trong `.claude/rules/` được sinh ra chỉ trong một lần chạy. |
-| **Team lead** quản lý standards dùng chung giữa nhiều repo | `.claude/rules/` rất hay drift mỗi khi đổi tên package, đổi ORM hay đổi response wrapper. ClaudeOS-Core đồng bộ lại một cách nhất quán: cùng input thì ra output byte-identical, không có diff thừa. |
+| **Team lead** quản lý standards dùng chung giữa nhiều repo | `.claude/rules/` rất hay drift mỗi khi đổi tên package, đổi ORM hay đổi response wrapper. ClaudeOS-Core sinh lại theo một scaffold 8 section cố định: repo nào cũng cùng cấu trúc, cùng verdict của validator, nên diff chỉ cho thấy thay đổi về convention chứ không phải nhiễu layout. |
 | **Đã quen Claude Code** nhưng chán cảnh phải sửa lại code mỗi lần | Sai response wrapper, sai cấu trúc package, viết JPA trong khi dự án dùng MyBatis, rải `try/catch` trong khi đã có middleware tập trung. Scanner trích quy ước thật của dự án, mỗi pass của Claude đều chạy trong allowlist tường minh. |
 | **Onboard vào repo mới** (dự án có sẵn, vào team mới) | Chạy `init` xong là có ngay tấm bản đồ kiến trúc sống. Bảng stack trong CLAUDE.md, rules theo từng layer kèm ví dụ ✅/❌, decision log seed sẵn lý do đằng sau những lựa chọn lớn (JPA hay MyBatis, REST hay GraphQL...). Đọc 5 file vẫn nhanh hơn lội qua 5.000 file source. |
 | **Làm việc bằng tiếng Hàn, Nhật, Trung và 7 ngôn ngữ khác** | Phần lớn rule generator cho Claude Code chỉ có tiếng Anh. ClaudeOS-Core viết toàn bộ ở **10 ngôn ngữ** (`en/ko/ja/zh-CN/es/vi/hi/ru/fr/de`) và áp **kiểm tra cấu trúc byte-identical**. Verdict của `claude-md-validator` không đổi dù chọn ngôn ngữ output nào. |
@@ -331,7 +331,7 @@ Cách này:     Code đọc stack của bạn → Code đưa fact đã xác nh
 
 Pipeline gồm **ba giai đoạn**, code có mặt ở cả hai phía của lời gọi LLM.
 
-**1. Step A — Scanner (nhất quán, không gọi LLM).** Một Node.js scanner đi qua thư mục gốc, đọc `package.json`, `build.gradle`, `pom.xml`, `pyproject.toml`, parse các file `.env*` (đồng thời redact các biến nhạy cảm như `PASSWORD/SECRET/TOKEN/JWT_SECRET/...`), phân loại pattern kiến trúc (5 pattern A/B/C/D/E của Java; Kotlin CQRS hoặc multi-module; Next.js App Router so với Pages Router; FSD; components-pattern), tìm ra các domain, rồi dựng allowlist tường minh chứa mọi đường dẫn source thật. Output là `project-analysis.json`, đóng vai trò single source of truth cho mọi bước về sau.
+**1. Step A — Scanner (nhất quán, không gọi LLM).** Một Node.js scanner đi qua thư mục gốc, đọc `package.json`, `build.gradle`, `build.gradle.kts`, `pom.xml`, `pyproject.toml`, parse các file `.env*` (đồng thời redact các biến nhạy cảm như `PASSWORD/SECRET/TOKEN/JWT_SECRET/...`), phân loại pattern kiến trúc (5 pattern A/B/C/D/E của Java; Kotlin CQRS hoặc multi-module; Next.js App Router so với Pages Router; FSD; components-pattern), tìm ra các domain, rồi dựng allowlist tường minh chứa mọi đường dẫn source thật. Output là `project-analysis.json`, đóng vai trò single source of truth cho mọi bước về sau.
 
 **2. Step B — Pipeline Claude 4-pass (ràng buộc bởi fact của Step A).**
 - **Pass 1** đọc các file đại diện theo từng domain group rồi trích ra khoảng 50–100 quy ước cho mỗi domain: response wrapper, thư viện logging, cách xử lý lỗi, quy ước naming, pattern test. Mỗi domain group chỉ chạy một lần (`max 4 domains, 40 files per group`) nên context không bao giờ tràn.
@@ -358,12 +358,14 @@ Cốt lõi gắn kết tất cả lại là một bất biến: **Claude chỉ
 
 12 stack, tự động phát hiện từ chính các file dự án.
 
-**Backend:** Java/Spring Boot · Kotlin/Spring Boot · Node/Express · Node/Fastify · Node/NestJS · Python/Django · Python/FastAPI · Python/Flask
+**Backend:** Java/Spring Boot (và Spring Framework không dùng Boot, xem bên dưới) · Kotlin/Spring Boot · Node/Express · Node/Fastify · Node/NestJS · Python/Django · Python/FastAPI · Python/Flask
 
 **Frontend:** Node/Next.js · Node/Vite · Angular · Vue/Nuxt
 
 Dự án multi-stack (chẳng hạn Spring Boot backend cộng Next.js frontend) chạy được luôn mà không cần điều chỉnh.
 
+**Java cũ là mục tiêu hạng nhất (v2.5.1).** Spring 1.x–6.x không dùng Boot được nhận diện: Gradle (thời `apply plugin:`, cách viết `group:/name:/version:` theo thứ tự bất kỳ, phân giải biến qua `gradle.properties` / `apply from:` / buildSrc, version catalog, root chỉ có `settings.gradle`), Maven (POM thời Maven 2, property `${spring.version}`, `spring-framework-bom`, root multi-module, các project anh em không có POM gốc), **Ant + Ivy**, **metadata của Eclipse / IntelliJ / NetBeans** (`.classpath` kể cả tham chiếu tới JAR không commit, mức compliance trong `.settings`, `.idea/misc.xml`, `nbproject`), `WebContent/WEB-INF/lib/**/*.jar`, `WEB-INF/web.xml`, version schema XSD của Spring và **eGovFrame** — kèm framework, version Spring Framework, mức Java, packaging `war`/`ear`, driver JDBC và ORM. Cây source lấy `src/` làm gốc cũng được quét bằng đúng các domain pattern như `src/main/java`. Mọi version báo ra đều đọc từ file build, tên JAR hoặc property định nghĩa trong chính project; không suy ra từ giá trị mặc định của framework. Project JVM hoàn toàn không có Spring (`java-library`, `application`, `war` chỉ dùng servlet) được báo là Java với `framework: null`, không bao giờ là Spring.
+
 Quy tắc phát hiện và những gì mỗi scanner trích xuất được mô tả trong [docs/vi/stacks.md](docs/vi/stacks.md).
 
 ---
@@ -393,7 +395,7 @@ Phần lớn công cụ tài liệu cho Claude Code sinh ra từ một bản mô
 
 Cách làm này dẫn tới ba điểm khác biệt cụ thể.
 
-1. **Stack detection nhất quán.** Cùng dự án, cùng code thì luôn ra cùng output. Hết cảnh "lần này Claude lại đoán khác".
+1. **Stack detection và cấu trúc nhất quán.** Cùng dự án, cùng code thì luôn ra cùng kết quả scan và cùng layout `CLAUDE.md` 8 section. Câu chữ bên trong từng section vẫn do LLM viết; thứ cố định là các sự thật nó được cung cấp và khuôn nó phải điền vào.
 2. **Không tạo path bịa.** Prompt của Pass 3 liệt kê tường minh mọi source path được phép, vì thế Claude không thể trích ra path không tồn tại.
 3. **Hiểu được multi-stack.** Trong cùng một lần chạy, domain backend và frontend dùng prompt phân tích riêng.
 
@@ -429,7 +431,7 @@ Ngoài pipeline scaffolding kể trên, ClaudeOS-Core còn seed thêm thư mục
 
 Bốn file, tất cả đều do Pass 4 viết.
 
-- `decision-log.md` — sổ append-only ghi "vì sao chọn X thay vì Y", seed từ `pass2-merged.json`
+- `decision-log.md` — sổ append-only ghi "vì sao chọn X thay vì Y", seed từ `pass2-merged.json` (không bao giờ bị compact)
 - `failure-patterns.md` — danh sách lỗi lặp lại kèm điểm frequency và importance
 - `compaction.md` — cách memory được tự động compact theo thời gian
 - `auto-rule-update.md` — các pattern nên được nâng thành rule mới
@@ -437,7 +439,7 @@ Bốn file, tất cả đều do Pass 4 viết.
 Hai lệnh để duy trì layer này lâu dài.
 
 ```bash
-# Compact log failure-patterns (chạy định kỳ)
+# Compact log failure-patterns (chạy định kỳ; decision-log.md được giữ nguyên)
 npx claudeos-core memory compact
 
 # Đề xuất rule mới từ các failure pattern xuất hiện thường xuyên

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/claudeos-core.svg?logo=npm&label=npm)](https://www.npmjs.com/package/claudeos-core)
 [![CI](https://img.shields.io/github/actions/workflow/status/claudeos-core/claudeos-core/test.yml?branch=master&logo=github&label=CI)](https://github.com/claudeos-core/claudeos-core/actions/workflows/test.yml)
-[![tests](https://img.shields.io/badge/tests-736%20passing-brightgreen?logo=node.js&logoColor=white)](https://github.com/claudeos-core/claudeos-core/actions/workflows/test.yml)
+[![tests](https://img.shields.io/badge/tests-974%20passing-brightgreen?logo=node.js&logoColor=white)](https://github.com/claudeos-core/claudeos-core/actions/workflows/test.yml)
 [![node](https://img.shields.io/node/v/claudeos-core.svg?logo=node.js&logoColor=white&label=node)](https://nodejs.org/)
 [![license](https://img.shields.io/npm/l/claudeos-core.svg?color=blue)](LICENSE)
 [![downloads](https://img.shields.io/npm/dm/claudeos-core.svg?logo=npm&color=blue&label=downloads)](https://www.npmjs.com/package/claudeos-core)
@@ -25,7 +25,7 @@ npx claudeos-core init
 
 **ClaudeOS-Core 的做法是直接读源码,稳定地把这些文件重新生成出来。** 第一步,Node.js scanner 扫一遍项目,把技术栈、ORM、包结构、文件路径都摸清楚。第二步,4-pass Claude 流水线产出完整的内容:`CLAUDE.md`、自动加载的 `.claude/rules/`、standards、skills,全部限定在一份明确的路径白名单里,LLM 越不出这个范围。最后,5 个 validator 在交付前再把结果过一遍。
 
-这样一来,同样的输入永远得到同样的输出。10 种语言里随便选一种,产物在字节层面也完全一致,代码里没有的路径绝不会出现。(细节看下面[有什么不同](#有什么不同)。)
+这样一来,同样的输入永远得到同样的 8 段式 `CLAUDE.md` 结构。10 种语言里随便选一种,都要通过同样的 25 项结构检查,引用的每一条源码路径都会核对磁盘上是否真实存在。(细节看下面[有什么不同](#有什么不同)。)
 
 长期维护的项目,还会顺带生成一份 [Memory Layer](#memory-layer-可选用于长期项目)。
 
@@ -115,7 +115,7 @@ npx claudeos-core init
 </details>
 
 <details>
-<summary><strong>实际写进 <code>CLAUDE.md</code> 的内容 (真实片段 — Section 1 + 2)</strong></summary>
+<summary><strong>实际写进 <code>CLAUDE.md</code> 的内容 (真实片段 — Section 1 + 2;为了 README 渲染把标题降为 <code>####</code>,真实文件用的是 <code>## N.</code>)</strong></summary>
 
 ```markdown
 # CLAUDE.md — spring-boot-realworld-example-app
@@ -148,7 +148,7 @@ an XML-driven MyBatis persistence layer and JWT-based authentication.
 | Test Stack | JUnit Jupiter 5, Mockito, AssertJ, rest-assured, spring-mock-mvc |
 ```
 
-表里的每一项 —— 精确的依赖坐标、`dev.db` 文件名、`V1__create_tables.sql` 迁移名,乃至 "no JPA" 这种判断 —— 都是 Claude 动笔前,scanner 从 `build.gradle`、`application.properties` 和源码目录里实打实读出来的,没有一处靠猜。
+技术栈那几行 (Java 11、Spring Boot 2.6.3、Gradle、MyBatis、SQLite、端口 8080) 来自确定性的 scanner。更细的信息 —— 精确的依赖坐标、`dev.db` 文件名、`V1__create_tables.sql` 迁移名,乃至 "no JPA" 这种判断 —— 由 Pass 1 以 scanner 确认的事实为约束,从 `build.gradle`、`application.properties` 和源码目录里读出来,再由 validator 交叉核验。没有一处取自框架默认值。
 
 </details>
 
@@ -309,7 +309,7 @@ your-project/
 | 你是... | 它能帮你解决什么 |
 |---|---|
 | **打算用 Claude Code 启动新项目的独立开发者** | 不用每个会话都把规范从头讲一遍。`CLAUDE.md` 加上 8 大类的 `.claude/rules/`,一次跑完就有了。 |
-| **要在多个仓库之间维护共享标准的技术负责人** | 重命名包、换 ORM、改响应包装器之后,`.claude/rules/` 总是慢半拍跟不上。ClaudeOS-Core 用一致的方式重新对齐:同样的输入产出字节级一致的结果,diff 里不会有多余噪音。 |
+| **要在多个仓库之间维护共享标准的技术负责人** | 重命名包、换 ORM、改响应包装器之后,`.claude/rules/` 总是慢半拍跟不上。ClaudeOS-Core 按固定的 8 段式 scaffold 重新生成:每个仓库结构相同、validator 判定相同,diff 里看到的是约定的变化,而不是版式噪音。 |
 | **已经在用 Claude Code,却被生成代码搞得头大的人** | 包装器写错、包结构不对、明明用 MyBatis 却生成 JPA、明明有统一中间件却到处 `try/catch`。Scanner 把项目真实的规范抽出来,每一次 Claude pass 都在明确的路径白名单内运行。 |
 | **刚加入一个新仓库的人** (老项目、新团队) | 在仓库里跑一下 `init`,就能拿到一张活的架构地图:CLAUDE.md 里的栈表格、按层划分的规则配 ✅/❌ 示例,加上预先写好"为什么"的 decision log (JPA vs MyBatis、REST vs GraphQL 等)。读 5 份文件,胜过翻 5,000 个源文件。 |
 | **要用中文 / 韩语 / 日语等英语以外的语言工作的人** | 大多数 Claude Code 规则生成器只支持英语。ClaudeOS-Core 把整套产物以 **10 种语言** (`en/ko/ja/zh-CN/es/vi/hi/ru/fr/de`) 输出,而结构校验在所有语言下完全一致 —— `claude-md-validator` 的判定不受输出语言影响。 |
@@ -331,7 +331,7 @@ ClaudeOS-Core 把常见的 Claude Code 流程倒过来跑:
 
 整条流水线分**三个阶段**,LLM 调用的两端都有代码把关。
 
-**1. Step A — Scanner (确定性,不调用 LLM)。** Node.js scanner 遍历项目根目录,读取 `package.json` / `build.gradle` / `pom.xml` / `pyproject.toml`,解析 `.env*` 文件 (`PASSWORD/SECRET/TOKEN/JWT_SECRET/...` 这类敏感变量自动脱敏)。接着归类架构模式 (Java 的 5 种 A/B/C/D/E、Kotlin 的 CQRS / 多模块、Next.js 的 App vs Pages Router、FSD、components-pattern),识别业务域,再为每一个真实存在的源文件路径生成一份明确的白名单。结果汇总到 `project-analysis.json`,后续所有步骤都以它为唯一事实来源。
+**1. Step A — Scanner (确定性,不调用 LLM)。** Node.js scanner 遍历项目根目录,读取 `package.json` / `build.gradle` / `build.gradle.kts` / `pom.xml` / `pyproject.toml`,解析 `.env*` 文件 (`PASSWORD/SECRET/TOKEN/JWT_SECRET/...` 这类敏感变量自动脱敏)。接着归类架构模式 (Java 的 5 种 A/B/C/D/E、Kotlin 的 CQRS / 多模块、Next.js 的 App vs Pages Router、FSD、components-pattern),识别业务域,再为每一个真实存在的源文件路径生成一份明确的白名单。结果汇总到 `project-analysis.json`,后续所有步骤都以它为唯一事实来源。
 
 **2. Step B — 4-Pass Claude 流水线 (受 Step A 的事实约束)。**
 - **Pass 1** 按域分组读取代表性文件,从每个域里提炼大约 50–100 条规范:响应包装器、日志库、错误处理、命名约定、测试模式等。每个域分组只跑一次 (`max 4 domains, 40 files per group`),所以 context 不会爆。
@@ -358,12 +358,14 @@ severity 分三档 (`fail` / `warn` / `advisory`),这样用户能手动修掉的
 
 12 种技术栈,从项目文件里自动识别:
 
-**Backend:** Java/Spring Boot · Kotlin/Spring Boot · Node/Express · Node/Fastify · Node/NestJS · Python/Django · Python/FastAPI · Python/Flask
+**Backend:** Java/Spring Boot (以及不用 Boot 的 Spring Framework，见下文) · Kotlin/Spring Boot · Node/Express · Node/Fastify · Node/NestJS · Python/Django · Python/FastAPI · Python/Flask
 
 **Frontend:** Node/Next.js · Node/Vite · Angular · Vue/Nuxt
 
 多栈项目 (例如 Spring Boot 后端 + Next.js 前端) 也能直接跑。
 
+**遗留 Java 是一等目标 (v2.5.1)。** 可识别不使用 Boot 的 Spring 1.x–6.x：Gradle (`apply plugin:` 时代、顺序任意的 `group:/name:/version:` 写法、通过 `gradle.properties` / `apply from:` / buildSrc 解析变量、版本目录、只有 `settings.gradle` 的根目录)、Maven (Maven 2 时代的 POM、`${spring.version}` 属性、`spring-framework-bom`、多模块根、没有根 POM 的同级项目)、**Ant + Ivy**、**Eclipse / IntelliJ / NetBeans 元数据** (`.classpath`，包括指向未提交 JAR 的引用、`.settings` 中的 compliance 级别、`.idea/misc.xml`、`nbproject`)、`WebContent/WEB-INF/lib/**/*.jar`、`WEB-INF/web.xml`、Spring XSD 架构版本，以及 **eGovFrame** — 连同框架、Spring Framework 版本、Java 级别、`war`/`ear` 打包方式、JDBC 驱动和 ORM 一并给出。以 `src/` 为根的源码树也会用与 `src/main/java` 相同的 domain 模式扫描。报告的每个版本都来自构建文件、JAR 文件名或项目内定义的属性；不会依据框架默认值推测。完全不用 Spring 的 JVM 项目 (`java-library`、`application`、仅有 servlet 的 `war`) 会被报告为 `framework: null` 的 Java，绝不会当成 Spring。
+
 具体的识别规则、每个 scanner 抽取了什么内容,详见 [docs/zh-CN/stacks.md](docs/zh-CN/stacks.md)。
 
 ---
@@ -393,7 +395,7 @@ npx claudeos-core health
 
 具体落到三件事上:
 
-1. **栈识别可复现。** 同样的项目 + 同样的代码 = 同样的输出,不会出现"这次 Claude 又写得不一样"的情况。
+1. **栈识别和结构可复现。** 同样的项目 + 同样的代码 = 同样的扫描结果,同样的 8 段式 `CLAUDE.md` 版式。各段里的措辞仍由 LLM 撰写,固定下来的是交给它的事实和它必须填满的框架。
 2. **不编造路径。** Pass 3 prompt 里写明了所有允许的源码路径,Claude 没法引用不存在的路径。
 3. **多栈感知。** 同一次执行里,后端域和前端域走不同的分析 prompt。
 
@@ -429,7 +431,7 @@ npx claudeos-core health
 
 一共 4 个文件,全部由 Pass 4 写入:
 
-- `decision-log.md` —— append-only 的"为什么选 X 不选 Y",从 `pass2-merged.json` 取种子。
+- `decision-log.md` —— append-only 的"为什么选 X 不选 Y",从 `pass2-merged.json` 取种子。(从不压缩)
 - `failure-patterns.md` —— 反复出现的错误,带 frequency / importance 分数。
 - `compaction.md` —— 记忆随时间自动压缩的方式。
 - `auto-rule-update.md` —— 应当晋升为新规则的模式。
@@ -437,7 +439,7 @@ npx claudeos-core health
 项目持续推进时,这两条命令负责维护这一层:
 
 ```bash
-# 压缩 failure-patterns 日志 (定期执行)
+# 压缩 failure-patterns 日志 (定期执行;不会动 decision-log.md)
 npx claudeos-core memory compact
 
 # 把高频 failure pattern 提为候选规则

package/bin/commands/init.js

@@ -615,6 +615,42 @@ async function runPass3Split(ctx) {
     },
   });
 
+  // v2.5.0 — Deterministic allowlist injection ("LLMs guess, code confirms").
+  // The `## Allowed Source Paths` section is the single most important
+  // anti-hallucination input for 3b/3c/3d, yet until now it reached
+  // pass3a-facts.md only if the LLM faithfully hand-copied up to 500 paths
+  // out of pass3-context.json — and the 3a validator only checked file
+  // length. Node now writes that section itself from project-analysis.json
+  // (replacing any LLM-written version), so the allowlist is byte-exact
+  // every run, including resumed runs where 3a was skipped.
+  {
+    const { injectAllowedPathsSection } = require("../../plan-installer/source-paths");
+    let collected = null;
+    try {
+      const pa = JSON.parse(readFile(path.join(GENERATED_DIR, "project-analysis.json")));
+      collected = pa && pa.allowedSourcePaths;
+    } catch (_e) { /* tolerated — fallback line is written instead */ }
+    const before = readFileSafe(factsFile, "");
+    if (before.replace(/^\uFEFF/, "").trim().length === 0) {
+      // 3a is marked complete in the marker but the facts file is missing/empty
+      // (deleted by hand, or a crash between validate and marker write). Do not
+      // fabricate a facts file that contains only the allowlist — 3b would run
+      // against an empty fact sheet. Surface it and let the user resume/--force.
+      throw new InitError(
+        "pass3a-facts.md is missing or empty although Pass 3a is marked complete.\n" +
+        "    Delete claudeos-core/generated/pass3-complete.json to re-run Pass 3a, or use `init --force`."
+      );
+    }
+    const after = injectAllowedPathsSection(before, collected);
+    if (after !== before) {
+      if (!writeFileSafe(factsFile, after)) {
+        throw new InitError("Failed to write the Allowed Source Paths section into pass3a-facts.md.");
+      }
+      const n = collected && Array.isArray(collected.paths) ? collected.paths.length : 0;
+      log(`    📎 Allowed Source Paths section written by orchestrator (${n} ${collected && collected.mode === "rollup" ? "dirs" : "paths"})`);
+    }
+  }
+
   // ═══ Stage 3b: CLAUDE.md + standard/ + .claude/rules/ ═══════════
   //
   // Single batch (domains ≤ 15): keep legacy "3b" marker (backward-compatible).
@@ -699,8 +735,16 @@ async function runPass3Split(ctx) {
           }
         }
         // For every batch, confirm rules/ was generated (at least one staged-rules move must succeed).
+        // Count ONLY claudeos-core-managed categories (`NN.` prefix). Since v2.5.0
+        // --force/fresh preserve user-authored entries under .claude/rules/, so a
+        // plain recursive count could be >0 even when Pass 3 produced nothing.
         const rulesDir = path.join(PROJECT_ROOT, ".claude/rules");
-        const rulesCount = countFilesRecursive(rulesDir);
+        let rulesCount = 0;
+        try {
+          for (const e of fs.readdirSync(rulesDir, { withFileTypes: true })) {
+            if (e.isDirectory() && /^\d{2}\./.test(e.name)) rulesCount += countFilesRecursive(path.join(rulesDir, e.name));
+          }
+        } catch (_e) { rulesCount = 0; }
         if (rulesCount === 0) {
           problems.push(".claude/rules/ has 0 files (staging-override may have been ignored)");
         }
@@ -855,7 +899,7 @@ function checkPrerequisites() {
   );
   if (!hasProjectMarker) {
     log(`\n  ⚠️  Warning: ${PROJECT_ROOT} does not look like a project root.`);
-    log("  No .git, package.json, build.gradle, or pom.xml found.");
+    log("  No .git, package.json, build.gradle(.kts), pom.xml, or pyproject.toml found.");
     log("  Run this command from your project directory.\n");
   }
 
@@ -910,6 +954,28 @@ async function resolveLanguage(parsedArgs) {
   return lang;
 }
 
+// Remove only the rule categories claudeos-core generates (`NN.` prefixed:
+// 00.core, 10.backend, …, 90.optional). Files/dirs the user authored under
+// .claude/rules/ without that prefix are left untouched. Returns the number
+// of entries removed.
+function wipeManagedRuleCategories(rulesDir) {
+  if (!fileExists(rulesDir)) return 0;
+  let removed = 0;
+  let entries;
+  try { entries = fs.readdirSync(rulesDir, { withFileTypes: true }); }
+  catch (_e) { return 0; }
+  for (const e of entries) {
+    // Managed entries are category DIRECTORIES (00.core/, 10.backend/, …).
+    // claudeos-core never writes a `NN.`-prefixed FILE at the rules root, so
+    // such a file (`.claude/rules/01.team-style.md`) is user-authored — keep it.
+    // Guard 2 (zero-rules detection) counts with the same predicate.
+    if (!e.isDirectory() || !/^\d{2}\./.test(e.name)) continue;
+    fs.rmSync(path.join(rulesDir, e.name), { recursive: true, force: true });
+    removed++;
+  }
+  return removed;
+}
+
 // ─── Stage 3: Resume/Fresh selection ──────────────────────────────
 // Returns { wasFreshClean: boolean } — the caller uses this to gate the
 // v1.7.x migration backfill in dispatchPass3.
@@ -930,14 +996,15 @@ async function applyResumeMode(parsedArgs, lang) {
     // (only .json/.md are unlinked above; directories aren't touched).
     const stagedDir = path.join(GENERATED_DIR, ".staged-rules");
     if (fileExists(stagedDir)) fs.rmSync(stagedDir, { recursive: true, force: true });
-    // Also wipe .claude/rules/ so Guard 2 (zero-rules detection) can't
-    // false-negative on stale rules from a previous run when the fresh
-    // Pass 3 run fails silently (e.g. Claude ignores staging-override).
-    // Step [2] recreates the subdirs from scratch. Any manual edits the
-    // user made to rule files are lost — acceptable under --force
-    // ("truly fresh start").
-    const rulesDir = path.join(PROJECT_ROOT, ".claude/rules");
-    if (fileExists(rulesDir)) fs.rmSync(rulesDir, { recursive: true, force: true });
+    // Also wipe the claudeos-core-managed categories under .claude/rules/
+    // so Guard 2 (zero-rules detection) can't false-negative on stale rules
+    // from a previous run when the fresh Pass 3 run fails silently (e.g.
+    // Claude ignores staging-override). Step [2] recreates the subdirs.
+    // Manual edits to GENERATED rule files are lost — acceptable under
+    // --force ("truly fresh start"). Anything the user placed under
+    // .claude/rules/ that is NOT a claudeos-core category (no `NN.` prefix)
+    // is preserved — it was never ours to delete.
+    wipeManagedRuleCategories(path.join(PROJECT_ROOT, ".claude/rules"));
     wasFreshClean = true;
     log("  🔄 Previous results deleted (--force)\n");
     return { wasFreshClean };
@@ -993,11 +1060,9 @@ async function applyResumeMode(parsedArgs, lang) {
     // Clean .staged-rules/ leftover from a prior crashed run (same reason as --force branch).
     const stagedDir = path.join(GENERATED_DIR, ".staged-rules");
     if (fileExists(stagedDir)) fs.rmSync(stagedDir, { recursive: true, force: true });
-    // Wipe .claude/rules/ for the same Guard 2 false-negative reason as
-    // the --force branch. Step [2] recreates the subdirs; any manual
-    // edits are lost — acceptable under an explicit "fresh" choice.
-    const rulesDir = path.join(PROJECT_ROOT, ".claude/rules");
-    if (fileExists(rulesDir)) fs.rmSync(rulesDir, { recursive: true, force: true });
+    // Wipe managed rule categories for the same Guard 2 false-negative
+    // reason as the --force branch (user-owned, non-`NN.` entries survive).
+    wipeManagedRuleCategories(path.join(PROJECT_ROOT, ".claude/rules"));
     wasFreshClean = true;
   } else if (mode === "continue" && existingPass1.length === 0 && pass2Exists) {
     // pass2 exists but no pass1 → pass2 is stale, force re-run
@@ -1078,7 +1143,7 @@ function ensureDirectories() {
 }
 
 // ─── Stage 5: Load & validate domain-groups.json ──────────────────
-function loadDomainGroups() {
+function loadDomainGroups({ wasFreshClean = false } = {}) {
   let domainGroups;
   try {
     domainGroups = JSON.parse(
@@ -1089,6 +1154,34 @@ function loadDomainGroups() {
   }
   const totalGroups = domainGroups.totalGroups;
   if (!totalGroups || typeof totalGroups !== "number" || totalGroups < 1) {
+    if (totalGroups === 0) {
+      let stackLine = "";
+      try {
+        const pa = JSON.parse(readFile(path.join(GENERATED_DIR, "project-analysis.json")));
+        const st = pa.stack || {};
+        stackLine = `    Detected stack: language=${st.language || "none"} framework=${st.framework || "none"} frontend=${st.frontend || "none"}\n`;
+      } catch (_e) { /* best effort */ }
+      throw new InitError(
+        "No domains were found in this project, so there is nothing for Pass 1-3 to analyze.\n" +
+        stackLine +
+        "    The scanner recognizes layouts such as:\n" +
+        "      Java/Kotlin  src/main/java/<pkg>/<domain>/controller/*.java, <pkg>/controller/<domain>/*.java,\n" +
+        "                   <pkg>/controller/*Controller.java, <pkg>/<domain>/adapter/in/web/*.java,\n" +
+        "                   <pkg>/<feature>/*Controller.kt, <module>/src/main/java/... (Gradle/Maven multi-module)\n" +
+        "      Node         src/<domain>/*.ts, src/modules/<domain>/, src/{controllers,routes,services}/<domain>.*\n" +
+        "      Python       app/<domain>/, app/{routers,routes}/<domain>.py, Django apps with models.py\n" +
+        "      Frontend     app/<route>/page.tsx (incl. (group)/), pages/<route>/, src/components/<name>/, src/features/<name>/\n" +
+        "    If your layout differs, open an issue with your directory tree, or check claudeos-core/generated/project-analysis.json\n" +
+        "    to see what was detected. " +
+        (wasFreshClean
+          // --force / "fresh" already wiped the managed rule categories and
+          // generated/*.json|*.md before the scanner ran — say so, do not
+          // claim nothing was touched.
+          ? "CLAUDE.md was not modified, but --force / fresh had already removed the previously generated\n" +
+            "    .claude/rules/NN.* categories and claudeos-core/generated/ pass files before this check. Restore them from version control if needed."
+          : "Nothing was written to CLAUDE.md or .claude/rules/.")
+      );
+    }
     throw new InitError(`domain-groups.json has invalid totalGroups: ${totalGroups}\n    Re-run plan-installer or check claudeos-core/generated/`);
   }
   if (!domainGroups.groups || totalGroups !== domainGroups.groups.length) {
@@ -1564,7 +1657,8 @@ async function runPass4(opts) {
       // Note: master plan files are no longer generated (previously this
       // included "claudeos-core/plan/50.memory-master.md"). The marker schema
       // still accepts an optional planFiles field for backward compatibility.
-      claudeMdAppended: true,
+      // v2.3.0+: CLAUDE.md is never touched by Pass 4 (Pass 3 §8 is authoritative).
+      claudeMdAppended: false,
     }, null, 2);
     return writeFileSafe(pass4Marker, markerBody);
   }
@@ -1625,7 +1719,7 @@ async function runPass4(opts) {
     pass4Label = "Pass 4 already present";
   } else if (!fileExists(pass4PromptFile)) {
     log("    ⚠️  pass4-prompt.md not found — falling back to static scaffold");
-    if (applyStaticFallback()) { log("    ✅ Memory/Rules/Plans scaffolded + CLAUDE.md appended (static fallback)"); pass4Label = "Pass 4 (static fallback)"; }
+    if (applyStaticFallback()) { log("    ✅ Memory/Rules/Standard scaffolded (static fallback)"); pass4Label = "Pass 4 (static fallback)"; }
     else { log("    ❌ Static fallback failed to write marker"); pass4Label = "Pass 4 fallback failed"; }
   } else {
     let prompt4 = injectProjectRoot(readFile(pass4PromptFile));
@@ -1675,7 +1769,7 @@ async function runPass4(opts) {
 
     if (!ok4 || !isValidPass4Marker(pass4Marker)) {
       log("    ⚠️  Pass 4 did not produce a valid pass4-memory.json — using static fallback");
-      if (applyStaticFallback()) { log("    ✅ Memory/Rules/Plans scaffolded + CLAUDE.md appended (static fallback)"); pass4Label = `Pass 4 (static fallback, ${formatElapsed(elapsed4)})`; }
+      if (applyStaticFallback()) { log("    ✅ Memory/Rules/Standard scaffolded (static fallback)"); pass4Label = `Pass 4 (static fallback, ${formatElapsed(elapsed4)})`; }
       else { log("    ❌ Static fallback failed to write marker"); pass4Label = "Pass 4 fallback failed"; }
     } else {
       // Claude-driven Pass 4 succeeded. Ensure memory + rules + plans + standard + CLAUDE.md append exist
@@ -1744,8 +1838,11 @@ async function runPass4(opts) {
 // ─── Stage 11: Run external verification tools ────────────────────
 function runVerificationTools() {
   const verifyTools = [
-    { name: "manifest-generator", script: path.join(TOOLS_DIR, "manifest-generator/index.js") },
-    { name: "health-checker",     script: path.join(TOOLS_DIR, "health-checker/index.js") },
+    // --sync-skills: only `init` is allowed to let manifest-generator patch
+    // CLAUDE.md §6 / MANIFEST.md (post-generation reconciliation). `health`
+    // runs the same tool without the flag and stays read-only.
+    { name: "manifest-generator", script: path.join(TOOLS_DIR, "manifest-generator/index.js"), args: " --sync-skills" },
+    { name: "health-checker",     script: path.join(TOOLS_DIR, "health-checker/index.js"),     args: "" },
   ];
 
   for (const t of verifyTools) {
@@ -1753,7 +1850,7 @@ function runVerificationTools() {
       log(`    ⏭️  ${t.name} — not found, skipping`);
       continue;
     }
-    const ok = run(`node "${t.script}"`, { ignoreError: true });
+    const ok = run(`node "${t.script}"${t.args}`, { ignoreError: true });
     if (!ok) {
       log(`    ⚠️  ${t.name} reported issues (non-fatal)`);
     }
@@ -1914,7 +2011,7 @@ async function cmdInit(parsedArgs) {
 
   // ─── [4] Pass 1: Deep analysis per domain group ────────────
   header("[4] Pass 1 — Deep analysis per domain group...");
-  const { domainGroups, totalGroups } = loadDomainGroups();
+  const { domainGroups, totalGroups } = loadDomainGroups({ wasFreshClean });
   const pass1Prompts = loadPass1Prompts();
 
   // Progress tracking: Pass 1 (N groups) + Pass 2 + Pass 3 + Pass 4 = totalSteps
@@ -1976,4 +2073,4 @@ async function cmdInit(parsedArgs) {
   printCompletionBanner({ lang, totalGroups, totalStart });
 }
 
-module.exports = { cmdInit, InitError };
+module.exports = { cmdInit, InitError, wipeManagedRuleCategories };

package/bin/commands/lint.js

@@ -32,6 +32,8 @@ Checks:
   - Section 6 has exactly 3 ### sub-sections
   - Section 8 has exactly 2 ### sub-sections + 2 #### headings
   - Each L4 memory file appears in exactly 1 table row (inside Section 8)
+  - Each \`## N.\` heading contains its English canonical token (T1)
+  - Each section has non-trivial body content (S2, warning)
 
 Exit codes:
   0 — structure valid

package/bin/commands/memory.js

@@ -2,7 +2,7 @@
  * ClaudeOS-Core — Memory command (L4 memory)
  *
  * Subcommands:
- *   memory compact         — apply 4-stage compaction to decision-log.md / failure-patterns.md
+ *   memory compact         — apply 4-stage compaction to failure-patterns.md (decision-log.md is append-only)
  *   memory score           — recompute importance of failure-patterns.md entries
  *   memory propose-rules   — analyze failure patterns, append suggestions to auto-rule-update.md
  */
@@ -247,7 +247,13 @@ function cmdCompact() {
   ensureDir(MEMORY_DIR);
   const activeRulePaths = loadActiveRulePaths();
 
-  const files = ["decision-log.md", "failure-patterns.md"];
+  // decision-log.md is EXCLUDED from compaction. Its contract (rules/60.memory/
+  // 01.decision-log.md, CLAUDE.md §8) is "permanent, append-only". Stage 1
+  // summarization dropped the Context/Options/Decision/Consequences body of
+  // every entry older than 30 days — i.e. exactly the "why" the file exists
+  // to preserve. Only failure-patterns.md carries the frequency/importance
+  // metadata the 4-stage policy is designed around.
+  const files = ["failure-patterns.md"];
   const summaries = [];
   for (const f of files) {
     const r = compactFile(path.join(MEMORY_DIR, f), activeRulePaths);
@@ -255,6 +261,7 @@ function cmdCompact() {
     if (r.changed) log(`  ✅ ${f}: ${r.before} → ${r.after} entries`);
     else log(`  ⏭️  ${f}: ${r.reason}`);
   }
+  log("  ⏭️  decision-log.md: append-only, never compacted");
 
   // Update compaction.md "Last Compaction" section.
   // Replace ONLY the "## Last Compaction" section (up to next `##` heading or EOF).
@@ -411,7 +418,7 @@ function showHelp() {
 Usage: npx claudeos-core memory <subcommand>
 
 Subcommands:
-  compact            Apply 4-stage compaction to decision-log.md and failure-patterns.md
+  compact            Apply 4-stage compaction to failure-patterns.md (decision-log.md is append-only, never compacted)
   score              Recompute importance of failure-patterns.md entries (frequency × recency)
   propose-rules      Analyze failure patterns, append rule update suggestions to auto-rule-update.md
 `);

package/content-validator/index.js

@@ -423,10 +423,35 @@ async function main() {
   // check covers both. No natural-language matching involved.
   console.log("  [10/10] path-claim verification (hallucination + MANIFEST drift)...");
 
-  // Regex: matches `src/...` paths to TS/TSX/JS/JSX files, not inside
-  // inline code already fenced. We still strip fenced blocks first so
-  // example blocks inside ```...``` don't produce false positives.
-  const SRC_PATH_RE = /\bsrc\/[\w\-./]+\.(?:ts|tsx|js|jsx)\b/g;
+  // Regex: matches `src/...` paths to source files, not inside inline code
+  // already fenced. We still strip fenced blocks first so example blocks
+  // inside ```...``` don't produce false positives.
+  //
+  // v2.5.0 — extension list widened. Pre-v2.5.0 only ts/tsx/js/jsx were
+  // checked, so Java/Kotlin/Python projects (and MyBatis mapper XML, the
+  // single most-hallucinated path class on Spring projects) got zero
+  // path-claim coverage despite "no invented paths" being the headline
+  // guarantee. Config extensions (yml/properties/json) are deliberately
+  // NOT included: those are cited as illustrative profile names
+  // (`application-{profile}.yml`) far more often than as path claims.
+  //
+  // An optional module prefix (`api/src/…`, `apps/web/src/…`,
+  // `servers/query/x/src/…`) is captured as part of the claim. A prefixed
+  // claim is checked at that exact location only — citing `core/src/…` for a
+  // file that lives under `api/` is a wrong-module claim and must be flagged,
+  // which the bare-`src/` module search below would otherwise hide.
+  //
+  // Two alternatives, each with its own left boundary:
+  //   (1) `<module>/…/src/…` — the prefix may not start right after a word
+  //       char, `.`, `/` or `@`, so `@acme/ui/src/Button.tsx` (a package
+  //       import, not a repo path) is NOT captured as module `acme/ui`;
+  //   (2) bare `src/…` — may be preceded by `/` (so the `src/Button.tsx`
+  //       tail of that import is still checked via the module search) but
+  //       not by a word char, so `libsrc/x.ts` never yields `src/x.ts`.
+  // Dependency paths (`node_modules/<pkg>/src/…`) are skipped below.
+  // `:` is excluded before a prefix so a dev-server URL (`localhost:5173/src/main.tsx`)
+  // does not yield the module `5173`; its `src/main.tsx` tail is still checked.
+  const SRC_PATH_RE = /(?:(?<![\w\-./@:])[\w\-][\w\-.]*\/(?:[\w\-][\w\-.]*\/)*src\/|(?<![\w\-.@])src\/)[\w\-./]+\.(?:ts|tsx|js|jsx|mjs|cjs|vue|svelte|java|kt|kts|py|xml|sql)\b/g;
 
   // Placeholder paths are scaffold templates / teaching examples, not
   // real path claims. We skip them. Three patterns qualify:
@@ -541,18 +566,59 @@ async function main() {
   // The monorepo fallback only fires for paths starting with `src/`,
   // which is the conventional workspace-relative form. Non-`src/` paths
   // (e.g., `claudeos-core/skills/...`) are checked direct-only.
+  // Directories that are never application modules even when they contain a
+  // `src/` child: virtualenvs (pip editable installs default to `<venv>/src`),
+  // vendored code, docs, tooling, test fixtures.
+  //
+  // Two tiers: HARD names are never modules at any depth (build output,
+  // dependencies, virtualenvs). SOFT names (`docs`, `tools`, `scripts`,
+  // `test(s)`, `fixtures`) are skipped only at the project root — inside a
+  // workspace container (`apps/docs`, `packages/tools`) they are legitimate
+  // packages, and skipping them there produced false STALE_PATH advisories on
+  // the default Turborepo layout.
+  const MODULE_SCAN_SKIP = new Set(["node_modules", ".git", ".claude", "claudeos-core", "build", "target", "dist", "out", ".gradle", ".idea", "coverage", ".next",
+    "venv", ".venv", "env", "virtualenv", "site-packages", "__pycache__", "vendor", "tmp", "temp"]);
+  const MODULE_SCAN_SKIP_ROOT_ONLY = new Set(["docs", "doc", "tools", "scripts", "test", "tests", "__tests__", "fixtures"]);
+  const WORKSPACE_CONTAINERS = new Set(["apps", "packages", "libs", "services", "servers", "modules"]);
+  function listModuleDirs(dir, { root = false, parentName = "" } = {}) {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+    catch (_e) { return []; }
+    const inWorkspace = WORKSPACE_CONTAINERS.has(parentName);
+    return entries
+      .filter(e => e.isDirectory() && !MODULE_SCAN_SKIP.has(e.name) && !e.name.startsWith(".")
+        && !((root || !inWorkspace) && MODULE_SCAN_SKIP_ROOT_ONLY.has(e.name)))
+      .map(e => path.join(dir, e.name));
+  }
+  // Memoized once per run: every directory up to three levels deep that
+  // contains a `src/` folder (JS workspaces `apps/x`, Gradle modules `api`,
+  // and the nested Kotlin CQRS layout `servers/query/x` the scanner itself
+  // supports). Computed lazily on the first `src/...` miss so projects with
+  // zero misses pay nothing.
+  let moduleSrcRoots = null;
+  function getModuleSrcRoots(ROOT) {
+    if (moduleSrcRoots) return moduleSrcRoots;
+    moduleSrcRoots = [];
+    const walk = (dir, depth) => {
+      for (const child of listModuleDirs(dir, { root: depth === 1, parentName: path.basename(dir) })) {
+        if (fs.existsSync(path.join(child, "src"))) moduleSrcRoots.push(child);
+        if (depth < 3) walk(child, depth + 1);
+      }
+    };
+    walk(ROOT, 1);
+    return moduleSrcRoots;
+  }
   function resolvePathClaim(ROOT, claimed) {
     if (fs.existsSync(path.join(ROOT, claimed))) return true;
     if (!claimed.startsWith("src/")) return false;
-    for (const workspace of ["apps", "packages"]) {
-      const wsDir = path.join(ROOT, workspace);
-      let entries;
-      try { entries = fs.readdirSync(wsDir, { withFileTypes: true }); }
-      catch (_e) { continue; }
-      for (const entry of entries) {
-        if (!entry.isDirectory()) continue;
-        if (fs.existsSync(path.join(wsDir, entry.name, claimed))) return true;
-      }
+    // v2.4.0: JS monorepo workspaces (apps/*, packages/*).
+    // v2.5.0: any first- or second-level module directory — Gradle/Maven
+    // multi-module (`api/src/main/java/...`, `servers/query/x/src/main/kotlin/...`)
+    // cite `src/...` relative to the module, exactly like JS workspaces do.
+    // Without this, widening SRC_PATH_RE to .java/.kt/.py would have turned
+    // every valid multi-module citation into a STALE_PATH false positive.
+    for (const moduleRoot of getModuleSrcRoots(ROOT)) {
+      if (fs.existsSync(path.join(moduleRoot, claimed))) return true;
     }
     return false;
   }
@@ -608,6 +674,9 @@ async function main() {
         if (seen.has(claimed)) continue;
         seen.add(claimed);
         if (hasPlaceholder(claimed)) continue;
+        // A dependency path is a reference to a library, not a claim about
+        // this repository's source tree.
+        if (/(^|\/)node_modules\//.test(claimed)) continue;
         pathClaimsChecked++;
         if (!resolvePathClaim(ROOT, claimed)) {
           pathClaimErrors++;