claudeos-core 2.4.4 → 2.5.0

package/README.ja.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-825%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 @@ Claude Code は新しいセッションを始めるたびに、フレームワ
 
 **ClaudeOS-Core は、実際のソースコードから一貫した結果でこれを再生成します。** まず Node.js のスキャナがプロジェクトを読み、スタック・ORM・パッケージ構成・ファイルパスを把握します。次に 4-pass の Claude パイプラインがドキュメント一式を書き上げます。`CLAUDE.md`、自動ロードされる `.claude/rules/`、standards、skills のすべてが、明示的なパス allowlist の範囲内に収まります。LLM はこの範囲を超えられません。最後に 5 つの validator が、出力する前に結果を検証します。
 
-そのため、同じ入力からは常に同じ出力が返ります。10 言語のどれを選んでも byte 単位で完全に一致し、コードに存在しないパスが紛れ込むこともありません。(詳しくは下の[何が違うのか](#何が違うのか)を参照。)
+そのため、同じ入力からは常に同じ 8 セクション構造の `CLAUDE.md` が返ります。10 言語のどれを選んでも同じ 25 項目の構造チェックで検証され、引用されたソースパスはすべてディスク上に実在するか確認されます。(詳しくは下の[何が違うのか](#何が違うのか)を参照。)
 
 長く運用するプロジェクトには、[Memory Layer](#memory-layer-任意長期プロジェクト向け) も合わせて生成されます。
 
@@ -115,7 +115,7 @@ Claude Code は新しいセッションを始めるたびに、フレームワ
 </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 |
 ```
 
-上の表の値はすべて、正確な dependency の座標も、`dev.db` というファイル名も、`V1__create_tables.sql` というマイグレーション名も、「no JPA」という注記も、Claude がファイルを書く前にスキャナが `build.gradle`、`application.properties`、ソースツリーから直接読み取った内容です。推測した値は 1 つも入っていません。
+スタック表の各行 (Java 11、Spring Boot 2.6.3、Gradle、MyBatis、SQLite、ポート 8080) は決定論的なスキャナが読み取った値です。より細かい情報 (正確な dependency の座標、`dev.db` というファイル名、`V1__create_tables.sql` というマイグレーション名、「no JPA」という注記) は、スキャナが確定した事実を制約として Pass 1 が `build.gradle`、`application.properties`、ソースツリーから読み取り、その後 validator が照合します。フレームワークのデフォルト値から取った値は 1 つもありません。
 
 </details>
 
@@ -309,7 +309,7 @@ your-project/
 | こんな方に | このツールが解消する痛み |
 |---|---|
 | **Claude Code で新規プロジェクトを始める個人開発者** | セッションのたびに Claude へコンベンションを教え直す手間がなくなります。`CLAUDE.md` と 8 カテゴリの `.claude/rules/` を一発で生成します。 |
-| **複数リポジトリで共有標準を維持するチームリード** | パッケージ名の変更や ORM の差し替え、レスポンスラッパーの変更があるたびに `.claude/rules/` がついていけずズレていく問題。ClaudeOS-Core ならいつ走らせても同じ手順で再同期できます。同じ入力からは byte 単位で同じ出力が出るので、diff にノイズが乗りません。 |
+| **複数リポジトリで共有標準を維持するチームリード** | パッケージ名の変更や ORM の差し替え、レスポンスラッパーの変更があるたびに `.claude/rules/` がついていけずズレていく問題。ClaudeOS-Core は固定された 8 セクションの scaffold を基準に再生成します。どのリポジトリでも同じ構造、同じ validator の判定になるため、diff に現れるのはレイアウトのノイズではなく規約の変更だけです。 |
 | **Claude Code を使っているが生成コードの修正に疲れた方** | 違うレスポンスラッパー、違うパッケージ構成、MyBatis のプロジェクトなのに JPA、共通 middleware があるのに `try/catch` が散らばっている、といった出力。スキャナが実際のコンベンションを抽出し、Claude のすべての pass は明示的なパス allowlist の中だけで動きます。 |
 | **新しいリポジトリにジョインしたばかりの方** (既存プロジェクト、新しいチーム) | リポジトリで `init` を一度走らせれば、生きたアーキテクチャマップが手に入ります。CLAUDE.md のスタック表、レイヤーごとのルールと ✅/❌ の例、主要な決定の「なぜ」が書き込まれた decision log (JPA vs MyBatis、REST vs GraphQL など)。5,000 個のソースファイルを読むより、5 つのドキュメントを読むほうが速いです。 |
 | **韓国語、日本語、中国語など英語以外の言語で作業する方** | 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 のワークフローの順序を
 
 パイプラインは **3 段階**で動きます。LLM を呼ぶ前にも後にも、コードが間に挟まる構成です。
 
-**1. Step A — スキャナ (LLM なしの決定論的処理)。** Node.js のスキャナがプロジェクトルートを巡回し、`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 Router と Pages Router、FSD、components パターン)、ドメインを抽出し、存在するすべてのソースファイルパスを明示的な allowlist にまとめます。結果は `project-analysis.json` 1 ファイルに集約され、以降の工程はこれを single source of truth として扱います。
+**1. Step A — スキャナ (LLM なしの決定論的処理)。** Node.js のスキャナがプロジェクトルートを巡回し、`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 Router と Pages Router、FSD、components パターン)、ドメインを抽出し、存在するすべてのソースファイルパスを明示的な allowlist にまとめます。結果は `project-analysis.json` 1 ファイルに集約され、以降の工程はこれを single source of truth として扱います。
 
 **2. Step B — 4-pass の Claude パイプライン (Step A の事実を制約として動作)。**
 - **Pass 1** はドメイングループごとに代表ファイルを読み、ドメインあたり 50 〜 100 個のコンベンション (レスポンスラッパー、ロギングライブラリ、エラー処理、命名規則、テストパターンなど) を抽出します。ドメイングループごとに 1 回ずつ実行する設計 (`max 4 domains, 40 files per group`) なので、context があふれることはありません。
@@ -393,7 +393,7 @@ Claude Code 向けのドキュメント生成ツールはほとんど、ユー
 
 具体的な違いは 3 つあります。
 
-1. **決定論的なスタック検出。** 同じプロジェクト + 同じコード = 同じ出力。「今回の Claude はちょっと違う出力を出してきた」がありません。
+1. **決定論的なスタック検出と構造。** 同じプロジェクト + 同じコード = 同じスキャン結果、同じ 8 セクション構造の `CLAUDE.md`。セクション内の文章は引き続き LLM が書きますが、渡される事実と埋めるべき形は固定されています。
 2. **存在しないパスを作らない。** Pass 3 の prompt に許可済みのソースパスがすべて明示されているため、Claude はそこに無いパスを引用できません。
 3. **マルチスタックを意識した解析。** 同じ実行の中で、バックエンドとフロントエンドのドメインがそれぞれ別の解析 prompt を使います。
 
@@ -429,7 +429,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 +437,7 @@ npx claudeos-core health
 このレイヤーを長く運用するためのコマンドが 2 つあります。
 
 ```bash
-# failure-patterns ログを圧縮 (定期的に実行)
+# failure-patterns ログを圧縮 (定期的に実行。decision-log.md には触れません)
 npx claudeos-core memory compact
 
 # よく出る failure pattern を提案ルールに昇格

package/README.ko.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-825%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 @@ Claude Code는 새 세션을 시작할 때마다 일반적인 프레임워크
 
 **ClaudeOS-Core는 실제 소스 코드를 분석해서 일관된 결과로 다시 만들어 줍니다.** 먼저 Node.js scanner가 프로젝트를 읽고 스택, ORM, 패키지 구조, 파일 경로를 파악합니다. 그 다음 4-pass Claude 파이프라인이 전체 문서 세트를 작성합니다. `CLAUDE.md`, 자동 로드되는 `.claude/rules/`, standards, skills 모두 명시적인 경로 allowlist 안에서만 만들어지고, LLM은 이 범위 밖으로 나갈 수 없습니다. 마지막으로 5개 validator가 결과를 내보내기 전에 한 번 더 검증합니다.
 
-덕분에 같은 입력에는 항상 같은 출력이 나옵니다. 10개 언어 중 무엇을 골라도 결과는 byte 단위로 동일하고, 코드에 존재하지 않는 경로는 절대 등장하지 않습니다. (자세한 내용은 아래 [무엇이 다른가](#무엇이-다른가) 참고.)
+덕분에 같은 입력에는 항상 같은 8개 섹션 구조의 `CLAUDE.md`가 나옵니다. 10개 언어 중 무엇을 골라도 동일한 25개 구조 검사를 통과해야 하고, 인용된 모든 소스 경로는 디스크에 실제로 존재하는지 확인됩니다. (자세한 내용은 아래 [무엇이 다른가](#무엇이-다른가) 참고.)
 
 오래 운영되는 프로젝트라면 [Memory Layer](#memory-layer-선택-장기-프로젝트용)도 함께 만들어집니다.
 
@@ -115,7 +115,7 @@ Claude Code는 새 세션을 시작할 때마다 일반적인 프레임워크
 </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 |
 ```
 
-위 표의 모든 값(정확한 dependency 좌표, `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가 읽어 온 값입니다. 더 세부적인 값(정확한 dependency 좌표, `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로 새 프로젝트를 시작하는 1인 개발자** | 매 세션마다 Claude에게 컨벤션을 다시 가르쳐야 하는 부담이 사라집니다. `CLAUDE.md`와 8개 카테고리의 `.claude/rules/`를 한 번에 만들어 줍니다. |
-| **여러 repo의 공유 표준을 유지하는 팀 리드** | 패키지 이름이 바뀌거나 ORM이 교체되거나 response wrapper가 변경될 때마다 `.claude/rules/`가 따라가지 못해 어긋나는 문제. ClaudeOS-Core가 일관된 방식으로 다시 동기화합니다. 같은 입력에는 byte 단위로 동일한 출력이 나오기 때문에 diff 노이즈가 없습니다. |
+| **여러 repo의 공유 표준을 유지하는 팀 리드** | 패키지 이름이 바뀌거나 ORM이 교체되거나 response wrapper가 변경될 때마다 `.claude/rules/`가 따라가지 못해 어긋나는 문제. ClaudeOS-Core는 고정된 8개 섹션 scaffold를 기준으로 다시 생성합니다. 모든 repo가 같은 구조, 같은 validator 판정을 받기 때문에 diff에는 레이아웃 노이즈가 아니라 컨벤션 변경만 드러납니다. |
 | **Claude Code를 이미 쓰지만 생성된 코드를 수정하는 데 지친 사용자** | 잘못된 response wrapper, 잘못된 패키지 구조, MyBatis 프로젝트인데 JPA 코드, 중앙 middleware가 있는데도 `try/catch`가 흩뿌려진 출력. scanner가 실제 컨벤션을 추출하고, 모든 Claude pass는 명시적인 경로 allowlist 안에서만 동작합니다. |
 | **새 repo에 합류한 경우** (기존 프로젝트, 팀 합류) | repo에서 `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 워크플로를 거꾸로 뒤집습니
 
 파이프라인은 **3단계**로 동작합니다. 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 패턴), 도메인을 찾고, 존재하는 모든 소스 파일 경로의 명시적 allowlist를 만듭니다. 결과는 `project-analysis.json` 한 파일에 모이고, 이후 모든 단계는 이걸 단일 source of truth로 삼습니다.
+**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 패턴), 도메인을 찾고, 존재하는 모든 소스 파일 경로의 명시적 allowlist를 만듭니다. 결과는 `project-analysis.json` 한 파일에 모이고, 이후 모든 단계는 이걸 단일 source of truth로 삼습니다.
 
 **2. Step B — 4-Pass Claude 파이프라인 (Step A의 사실을 기반으로 동작).**
 - **Pass 1**은 도메인 그룹별로 대표 파일을 읽고 도메인당 50–100개 정도의 컨벤션을 뽑아냅니다 (response wrapper, 로깅 라이브러리, 에러 처리, 네이밍 규칙, 테스트 패턴 등). 도메인 그룹마다 한 번씩 실행하기 때문에 (`max 4 domains, 40 files per group`) context가 절대 넘치지 않습니다.
@@ -393,7 +393,7 @@ npx claudeos-core health
 
 그 결과는 구체적으로 세 가지 차이로 이어집니다:
 
-1. **결정론적 스택 감지.** 같은 프로젝트 + 같은 코드 = 같은 출력. "이번엔 Claude가 다르게 나왔네"가 없습니다.
+1. **결정론적 스택 감지와 구조.** 같은 프로젝트 + 같은 코드 = 같은 스캔 결과, 같은 8개 섹션 `CLAUDE.md` 레이아웃. 섹션 안의 문장은 여전히 LLM이 쓰지만, LLM에게 주어지는 사실과 채워야 할 형태는 고정되어 있습니다.
 2. **존재하지 않는 경로를 만들지 않음.** Pass 3 prompt에 허용된 모든 소스 경로가 명시적으로 들어가기 때문에, Claude는 없는 경로를 인용할 수 없습니다.
 3. **멀티 스택 인지.** 같은 실행 안에서 백엔드와 프론트엔드 도메인이 서로 다른 분석 prompt를 사용합니다.
 
@@ -429,7 +429,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 +437,7 @@ npx claudeos-core health
 이 레이어를 시간이 흘러도 유지하기 위한 두 가지 명령어:
 
 ```bash
-# failure-patterns 로그 압축 (주기적으로 실행)
+# failure-patterns 로그 압축 (주기적으로 실행; decision-log.md는 건드리지 않음)
 npx claudeos-core memory compact
 
 # 자주 발생하는 failure pattern을 제안 룰로 승격

package/README.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-825%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 @@ Claude Code falls back to framework defaults every session. Your team uses **MyB
 
 **ClaudeOS-Core regenerates them deterministically, from your actual source code.** A Node.js scanner reads first (stack, ORM, package layout, file paths). A 4-pass Claude pipeline then writes the full set — `CLAUDE.md` + auto-loaded `.claude/rules/` + standards + skills — constrained by an explicit path allowlist that the LLM cannot escape. Five validators verify the output before it ships.
 
-The result: same input → byte-identical output, in any of 10 languages, with no invented paths. (Detail in [What makes this different](#what-makes-this-different) below.)
+The result: same input → the same 8-section `CLAUDE.md` structure, validated by the same 25 structural checks in any of 10 languages, with every cited source path verified against disk. (Detail in [What makes this different](#what-makes-this-different) below.)
 
 A separate [Memory Layer](#memory-layer-optional-for-long-running-projects) is seeded for long-running projects.
 
@@ -115,7 +115,7 @@ Run on [`spring-boot-realworld-example-app`](https://github.com/gothinkster/spri
 </details>
 
 <details>
-<summary><strong>What ends up in your <code>CLAUDE.md</code> (real excerpt — Section 1 + 2)</strong></summary>
+<summary><strong>What ends up in your <code>CLAUDE.md</code> (real excerpt — Section 1 + 2; headings demoted to <code>####</code> for README rendering, the real file uses <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 |
 ```
 
-Every value above — exact dependency coordinates, the `dev.db` filename, the `V1__create_tables.sql` migration name, "no JPA" — is extracted by the scanner from `build.gradle` / `application.properties` / source tree before Claude writes the file. Nothing is guessed.
+The stack rows (Java 11, Spring Boot 2.6.3, Gradle, MyBatis, SQLite, port 8080) come from the deterministic scanner. The finer details — exact dependency coordinates, the `dev.db` filename, the `V1__create_tables.sql` migration name, "no JPA" — are read from `build.gradle` / `application.properties` / the source tree by Pass 1 with the scanner's facts as constraints, then cross-checked by the validators. Nothing is taken from framework defaults.
 
 </details>
 
@@ -309,7 +309,7 @@ Categories sharing the same number prefix between `rules/` and `standard/` repre
 | You are... | The pain this removes |
 |---|---|
 | **A solo dev** starting a new project with Claude Code | "Teach Claude my conventions every session" — gone. `CLAUDE.md` + 8-category `.claude/rules/` generated in one pass. |
-| **A team lead** maintaining shared standards across repos | `.claude/rules/` drift as people rename packages, switch ORMs, or change response wrappers. ClaudeOS-Core re-syncs deterministically — same input, byte-identical output, no diff noise. |
+| **A team lead** maintaining shared standards across repos | `.claude/rules/` drift as people rename packages, switch ORMs, or change response wrappers. ClaudeOS-Core regenerates against a fixed 8-section scaffold — same structure in every repo, same validator verdict, so diffs show convention changes rather than layout noise. |
 | **Already using Claude Code** but tired of fixing generated code | Wrong response wrapper, wrong package layout, JPA when you use MyBatis, `try/catch` scattered when your project uses centralized middleware. The scanner extracts your real conventions; every Claude pass runs against an explicit path allowlist. |
 | **Onboarding to a new repo** (existing project, joining a team) | Run `init` on the repo, get a living architecture map: stack table in CLAUDE.md, per-layer rules with ✅/❌ examples, decision log seeded with "why" behind major choices (JPA vs MyBatis, REST vs GraphQL, etc.). Reading 5 files beats reading 5,000 source files. |
 | **Working in Korean / Japanese / Chinese / 7 more languages** | Most Claude Code rule generators are English-only. ClaudeOS-Core writes the full set in **10 languages** (`en/ko/ja/zh-CN/es/vi/hi/ru/fr/de`) with **byte-identical structural validation** — same `claude-md-validator` verdict regardless of output language. |
@@ -331,7 +331,7 @@ This:     Code reads your stack → Code passes confirmed facts to Claude → Cl
 
 The pipeline runs in **three stages**, with code on both sides of the LLM call:
 
-**1. Step A — Scanner (deterministic, no LLM).** A Node.js scanner walks your project root, reads `package.json` / `build.gradle` / `pom.xml` / `pyproject.toml`, parses `.env*` files (with sensitive-variable redaction for `PASSWORD/SECRET/TOKEN/JWT_SECRET/...`), classifies your architecture pattern (Java's 5 patterns A/B/C/D/E, Kotlin CQRS / multi-module, Next.js App vs. Pages Router, FSD, components-pattern), discovers domains, and builds an explicit allowlist of every source file path that exists. Output: `project-analysis.json` — the single source of truth for what follows.
+**1. Step A — Scanner (deterministic, no LLM).** A Node.js scanner walks your project root, reads `package.json` / `build.gradle` / `build.gradle.kts` / `pom.xml` / `pyproject.toml`, parses `.env*` files (with sensitive-variable redaction for `PASSWORD/SECRET/TOKEN/JWT_SECRET/...`), classifies your architecture pattern (Java's 5 patterns A/B/C/D/E, Kotlin CQRS / multi-module, Next.js App vs. Pages Router, FSD, components-pattern), discovers domains, and builds an explicit allowlist of every source file path that exists. Output: `project-analysis.json` — the single source of truth for what follows.
 
 **2. Step B — 4-Pass Claude pipeline (constrained by Step A's facts).**
 - **Pass 1** reads representative files per domain group and extracts ~50–100 conventions per domain — response wrappers, logging libraries, error handling, naming conventions, test patterns. Runs once per domain group (`max 4 domains, 40 files per group`) so context never overflows.
@@ -393,7 +393,7 @@ Most Claude Code documentation tools generate from a description (you tell the t
 
 Three concrete consequences:
 
-1. **Deterministic stack detection.** Same project + same code = same output. No "Claude rolled differently this time."
+1. **Deterministic stack detection and structure.** Same project + same code = same scan result and the same 8-section `CLAUDE.md` layout. Wording inside sections is still LLM-written; what's fixed is the facts it's given and the shape it must fill.
 2. **No invented paths.** The Pass 3 prompt explicitly lists every allowed source path; Claude can't cite paths that don't exist.
 3. **Multi-stack aware.** Backend and frontend domains use different analysis prompts in the same run.
 
@@ -429,7 +429,7 @@ Beyond the scaffolding pipeline above, ClaudeOS-Core seeds a `claudeos-core/memo
 
 Four files, all written by Pass 4:
 
-- `decision-log.md` — append-only "why we chose X over Y", seeded from `pass2-merged.json`
+- `decision-log.md` — append-only "why we chose X over Y", seeded from `pass2-merged.json` (never compacted)
 - `failure-patterns.md` — recurring errors with frequency/importance scores
 - `compaction.md` — how memory is auto-compacted over time
 - `auto-rule-update.md` — patterns that should become new rules
@@ -437,7 +437,7 @@ Four files, all written by Pass 4:
 Two commands maintain this layer over time:
 
 ```bash
-# Compact the failure-patterns log (run periodically)
+# Compact the failure-patterns log (run periodically; decision-log.md is left untouched)
 npx claudeos-core memory compact
 
 # Promote frequent failure patterns into proposed rules

package/README.ru.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-825%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 разбирает проект и вытаскивает стек, ORM, раскладку пакетов, реальные пути к файлам. Затем четырёхпроходный пайплайн на Claude пишет полный комплект документации: `CLAUDE.md`, автоматически подгружаемые `.claude/rules/`, стандарты, навыки. Всё это происходит строго внутри явного allowlist путей — за его пределы LLM выйти не может. И прежде чем результат окажется у вас, его проверяют пять валидаторов.
 
-В итоге одинаковый вход даёт побайтово одинаковый выход на любом из 10 языков, а пути, которых нет в коде, в документации не появляются. Подробности — ниже, в разделе [В чём отличие](#в-чём-отличие).
+В итоге одинаковый вход даёт один и тот же `CLAUDE.md` из 8 фиксированных секций, проверенный одними и теми же 25 структурными проверками на любом из 10 языков, а каждый упомянутый путь к исходникам сверяется с диском. Подробности — ниже, в разделе [В чём отличие](#в-чём-отличие).
 
 Для долгоживущих проектов рядом разворачивается [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; заголовки понижены до <code>####</code> ради отображения в README, в настоящем файле используется <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» — сканер вычитал из `build.gradle`, `application.properties` и дерева исходников ещё до того, как Claude взялся за файл. Ничего не угадано.
+Строки о стеке (Java 11, Spring Boot 2.6.3, Gradle, MyBatis, SQLite, порт 8080) даёт детерминированный сканер. Более тонкие детали — точные координаты зависимостей, имя файла `dev.db`, название миграции `V1__create_tables.sql`, пометка «no JPA» — Pass 1 вычитывает из `build.gradle`, `application.properties` и дерева исходников, опираясь на факты сканера как на ограничения, а затем валидаторы перепроверяют их. Из умолчаний фреймворка не взято ничего.
 
 </details>
 
@@ -309,7 +309,7 @@ your-project/
 | Вы... | Какую боль это снимает |
 |---|---|
 | **Соло-разработчик**, начинающий новый проект на Claude Code | «Объяснять Claude свои соглашения каждую сессию» — больше не надо. `CLAUDE.md` и `.claude/rules/` из 8 категорий собираются за один проход. |
-| **Тимлид**, отвечающий за общие стандарты в нескольких репозиториях | Правила в `.claude/rules/` устаревают, как только переименовываются пакеты, меняются ORM или обёртки ответов. ClaudeOS-Core пересобирает их детерминированно: на одном входе всегда побайтово одинаковый выход, поэтому в diff нет шума. |
+| **Тимлид**, отвечающий за общие стандарты в нескольких репозиториях | Правила в `.claude/rules/` устаревают, как только переименовываются пакеты, меняются ORM или обёртки ответов. ClaudeOS-Core пересобирает их по фиксированному scaffold из 8 секций: одна и та же структура в каждом репозитории, один и тот же вердикт валидатора, поэтому в diff видны изменения конвенций, а не шум раскладки. |
 | **Уже использует Claude Code**, но устал чинить сгенерированный код | Не та обёртка ответа, не та раскладка пакетов, JPA вместо MyBatis, `try/catch` россыпью при том, что в проекте есть централизованный middleware. Сканер достаёт ваши настоящие соглашения, а каждый проход Claude работает только в рамках явного allowlist путей. |
 | **Подключается к новому репозиторию** (готовый проект, выход в команду) | Запустите `init` — и получите живую карту архитектуры: таблицу стека в CLAUDE.md, правила по слоям с примерами ✅/❌, decision log с ответом на вопрос «почему» по ключевым решениям (JPA vs MyBatis, REST vs GraphQL и т. д.). Прочитать пять файлов быстрее, чем пять тысяч исходников. |
 | **Пишет на корейском, японском, китайском или ещё на 7 языках** | Большинство генераторов правил для 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 переворачивает привычный сценарий
 
 Пайплайн состоит из **трёх стадий**: детерминированный код стоит и до LLM, и после неё.
 
-**1. Step A — Scanner (детерминированно, без LLM).** Сканер на Node.js обходит корень проекта, читает `package.json`, `build.gradle`, `pom.xml`, `pyproject.toml`, разбирает файлы `.env*` (чувствительные переменные `PASSWORD/SECRET/TOKEN/JWT_SECRET/...` при этом редактируются), классифицирует архитектурный паттерн (5 паттернов Java A/B/C/D/E, Kotlin CQRS / multi-module, Next.js App vs Pages Router, FSD, components-pattern), находит домены и собирает явный allowlist путей всех существующих исходных файлов. На выходе — `project-analysis.json`, единый источник истины для всех последующих шагов.
+**1. Step A — Scanner (детерминированно, без LLM).** Сканер на Node.js обходит корень проекта, читает `package.json`, `build.gradle`, `build.gradle.kts`, `pom.xml`, `pyproject.toml`, разбирает файлы `.env*` (чувствительные переменные `PASSWORD/SECRET/TOKEN/JWT_SECRET/...` при этом редактируются), классифицирует архитектурный паттерн (5 паттернов Java A/B/C/D/E, Kotlin CQRS / multi-module, Next.js App vs Pages Router, FSD, components-pattern), находит домены и собирает явный allowlist путей всех существующих исходных файлов. На выходе — `project-analysis.json`, единый источник истины для всех последующих шагов.
 
 **2. Step B — четырёхпроходный пайплайн на Claude (опирается на факты из Step A).**
 - **Pass 1** читает по группе доменов представительные файлы и достаёт по 50–100 соглашений на домен: обёртки ответов, библиотеки логирования, обработку ошибок, нейминг, паттерны тестов. Запускается по разу на каждую группу доменов (`max 4 domains, 40 files per group`), поэтому контекст не переполняется.
@@ -393,7 +393,7 @@ npx claudeos-core health
 
 На практике это даёт три конкретных эффекта:
 
-1. **Детерминированная детекция стека.** Тот же проект и тот же код всегда дают тот же результат. Никаких «в этот раз Claude как-то иначе всё интерпретировал».
+1. **Детерминированная детекция стека и структуры.** Тот же проект и тот же код всегда дают тот же результат сканирования и ту же раскладку `CLAUDE.md` из 8 секций. Формулировки внутри секций по-прежнему пишет LLM; зафиксированы факты, которые он получает, и форма, которую он обязан заполнить.
 2. **Выдуманных путей не появляется.** В промпте Pass 3 явно перечислены все разрешённые пути в исходниках, поэтому Claude не может сослаться на то, чего нет.
 3. **Учёт нескольких стеков сразу.** В рамках одного запуска бэкенд- и фронтенд-домены анализируются разными промптами.
 
@@ -429,7 +429,7 @@ npx claudeos-core health
 
 Внутри четыре файла, и все их пишет 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 +437,7 @@ npx claudeos-core health
 Поддерживать слой со временем помогают две команды:
 
 ```bash
-# Уплотнить лог failure-patterns (запускайте периодически)
+# Уплотнить лог failure-patterns (запускайте периодически; decision-log.md не трогается)
 npx claudeos-core memory compact
 
 # Превратить часто встречающиеся failure-паттерны в предложенные правила

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-825%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.
@@ -393,7 +393,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 +429,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 +437,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-825%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 不会爆。
@@ -393,7 +393,7 @@ npx claudeos-core health
 
 具体落到三件事上:
 
-1. **栈识别可复现。** 同样的项目 + 同样的代码 = 同样的输出,不会出现"这次 Claude 又写得不一样"的情况。
+1. **栈识别和结构可复现。** 同样的项目 + 同样的代码 = 同样的扫描结果,同样的 8 段式 `CLAUDE.md` 版式。各段里的措辞仍由 LLM 撰写,固定下来的是交给它的事实和它必须填满的框架。
 2. **不编造路径。** Pass 3 prompt 里写明了所有允许的源码路径,Claude 没法引用不存在的路径。
 3. **多栈感知。** 同一次执行里,后端域和前端域走不同的分析 prompt。
 
@@ -429,7 +429,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 +437,7 @@ npx claudeos-core health
 项目持续推进时,这两条命令负责维护这一层:
 
 ```bash
-# 压缩 failure-patterns 日志 (定期执行)
+# 压缩 failure-patterns 日志 (定期执行;不会动 decision-log.md)
 npx claudeos-core memory compact
 
 # 把高频 failure pattern 提为候选规则