claudeos-core 2.1.0 → 2.2.0

package/README.ja.md

@@ -12,20 +12,6 @@ ClaudeOS-Core はコードベースを読み取り、見つけたすべてのパ
 
 ---
 
-## v2.1.0 の新機能
-
-v2.1.0 は Pass 3 を再設計し、中規模〜大規模プロジェクトで発生していた `Prompt is too long` 失敗を解消します。従来、単一の Pass 3 呼び出しが `CLAUDE.md`、rules、standards、skills、guides にまたがる数十ファイルを一度にすべて出力する必要があり、出力の累積が 5 ドメインを超えるあたりで確実にコンテキストウィンドウを超えていました。今回の修正はプロンプトの調整ではなく**構造的な変更**です:
-
-- **Pass 3 split モード**（常時有効） — Pass 3 は順次実行される `claude -p` 呼び出し（`3a` → `3b-core` → `3b-N` → `3c-core` → `3c-N` → `3d-aux`）に分割されます。各ステージは**新しいコンテキストウィンドウ**で開始するため、プロジェクトの規模にかかわらず出力累積によるオーバーフローは構造的に発生しません。
-- **ステージ間のファクトシート** — ステージ `3a` が Pass 2 の分析を一度だけ読み、5〜10 KB の `pass3a-facts.md` に蒸留します。以降のすべてのステージは 100〜500 KB の `pass2-merged.json` を再読み込みせず、このファクトシートを参照するため、新しいコンテキストをまたいでもファイル間の整合性が保たれます。
-- **バッチのサブ分割**（16 ドメイン以上で自動適用） — ステージ 3b/3c はさらに 15 ドメインずつのバッチに分割され、各ステージの出力を ~50 ファイル以下に抑えます。18 ドメインの React 19 + Vite 6 管理画面フロントエンドで、**102 分で 101 ファイル生成・8 ステージ・オーバーフロー 0 件**を実測で確認しました（2026-04-20 の本番実行）。
-- **Master plan の生成を廃止** — `claudeos-core/plan/*-master.md` ファイルは生成されなくなりました。Master plan は Claude Code がランタイムで読み込まない内部バックアップであり、Pass 3d でそれらを集約することがオーバーフローの主要因でした。バックアップ/復元には `git` を使用してください。
-- **Pass 4 gap-fill: `skills/00.shared/MANIFEST.md`** — Pass 3c がスキルレジストリを省略した場合（スキルが少ないプロジェクト）、Pass 4 が自動的にスタブを作成し、`.claude/rules/50.sync/03.skills-sync.md` がぶら下がった参照先を指さないようにします。
-
-細かな修正もあります: `memory --help` が memory サブコマンドのヘルプを表示するようになりました（以前はトップレベルが表示されていました）；`memory score` が `importance` 行を重複して残さなくなりました；`memory compact` のサマリーマーカーが正しい Markdown のリスト項目になりました。詳細: [CHANGELOG.md](./CHANGELOG.md)。
-
----
-
 ## なぜ ClaudeOS-Core なのか？
 
 他のすべての Claude Code ツールはこう動作します：
@@ -99,10 +85,20 @@ ClaudeOS-Core は、プロジェクトが `ApiResponse.ok()`（`ResponseEntity.s
 | **Vite / React SPA** | `package.json`、`vite.config.*` | 9 大分類、55 小項目 |
 | **Angular** | `package.json`、`angular.json` | 12 大分類、78 小項目 |
 
-自動検出対象：言語とバージョン、フレームワークとバージョン（SPA フレームワークとしての Vite を含む）、ORM（MyBatis、JPA、Exposed、Prisma、TypeORM、SQLAlchemy など）、データベース（PostgreSQL、MySQL、Oracle、MongoDB、SQLite）、パッケージマネージャ（Gradle、Maven、npm、yarn、pnpm、pip、poetry）、アーキテクチャ（CQRS、BFF — モジュール名から）、マルチモジュール構造（settings.gradle から）、モノレポ（Turborepo、pnpm-workspace、Lerna、npm/yarn workspaces）。
+自動検出対象：言語とバージョン、フレームワークとバージョン（SPA フレームワークとしての Vite を含む）、ORM（MyBatis、JPA、Exposed、Prisma、TypeORM、SQLAlchemy など）、データベース（PostgreSQL、MySQL、Oracle、MongoDB、SQLite）、パッケージマネージャ（Gradle、Maven、npm、yarn、pnpm、pip、poetry）、アーキテクチャ（CQRS、BFF — モジュール名から）、マルチモジュール構造（settings.gradle から）、モノレポ（Turborepo、pnpm-workspace、Lerna、npm/yarn workspaces）、**`.env.example` ランタイム設定**（v2.2.0 — Vite・Next.js・Nuxt・Angular・Node・Python フレームワークの 16 以上の慣習的変数名から port/host/API-target を抽出）。
 
 **何も指定する必要はありません。すべて自動的に検出されます。**
 
+### `.env`-driven ランタイム設定（v2.2.0）
+
+v2.2.0 では `lib/env-parser.js` が追加され、生成される `CLAUDE.md` がフレームワークのデフォルトではなく、プロジェクトが実際に宣言している内容を反映するようになりました。
+
+- **検索順序**：`.env.example`（canonical、コミット対象）→ `.env.local.example` → `.env.sample` → `.env.template` → `.env` → `.env.local` → `.env.development`。`.example` バリアントが優先されるのは、それが「開発者中立な shape-of-truth」であり、特定コントリビュータのローカルオーバーライドではないためです。
+- **認識されるポート変数名の慣例**：`VITE_PORT` / `VITE_DEV_PORT` / `VITE_DESKTOP_PORT` / `NEXT_PUBLIC_PORT` / `NUXT_PORT` / `NG_PORT` / `APP_PORT` / `SERVER_PORT` / `HTTP_PORT` / `DEV_PORT` / `FLASK_RUN_PORT` / `UVICORN_PORT` / `DJANGO_PORT` / 汎用 `PORT`。両方存在する場合はフレームワーク固有名が汎用 `PORT` より優先されます。
+- **ホストと API ターゲット**：`VITE_DEV_HOST` / `VITE_API_TARGET` / `NEXT_PUBLIC_API_URL` / `NUXT_PUBLIC_API_BASE` / `BACKEND_URL` / `PROXY_TARGET` など。
+- **優先順位**：Spring Boot の `application.yml` `server.port` が引き続き最優先（framework-native config）、次に `.env` 宣言のポート、最後の手段としてフレームワークのデフォルト（Vite 5173、Next.js 3000、Django 8000 など）。
+- **機密変数の redaction**：`PASSWORD` / `SECRET` / `TOKEN` / `API_KEY` / `ACCESS_KEY` / `PRIVATE_KEY` / `CREDENTIAL` / `JWT_SECRET` / `CLIENT_SECRET` / `SESSION_SECRET` / `BEARER` / `SALT` パターンにマッチする変数の値は、下流のジェネレータに到達する前に `***REDACTED***` へ置換されます。`.env.example` に誤ってコミットされた機密情報に対する defense-in-depth です。`DATABASE_URL` は stack-detector の DB 識別における後方互換性のため、明示的にホワイトリスト登録されています。
+
 ### Java ドメイン検出（5 パターン、フォールバック付き）
 
 | 優先度 | パターン | 構造 | 例 |
@@ -378,7 +374,7 @@ cat claudeos-core/generated/pass4-prompt.md \
 
 **確認：** `claudeos-core/memory/` に 4 ファイル（`decision-log.md`、`failure-patterns.md`、`compaction.md`、`auto-rule-update.md`）、`.claude/rules/60.memory/` に 4 ルールファイルが存在し、`CLAUDE.md` に `## Memory (L4)` セクションが追加されているはずです。マーカー：`claudeos-core/generated/pass4-memory.json`。
 
-> **v2.1.0 gap-fill：** Pass 4 は `claudeos-core/skills/00.shared/MANIFEST.md` の存在も保証します。Pass 3c がこれを省略した場合（スキルが少ないプロジェクトで、スタックの `pass3.md` テンプレートは `MANIFEST.md` を生成ターゲットに挙げているものの REQUIRED としてマークしていないため起こり得ます）、gap-fill が最小限のスタブを作成し、`.claude/rules/50.sync/03.skills-sync.md` の参照ターゲットが常に有効である状態を保ちます。冪等：ファイルがすでに実体のある内容（>20 文字）を持っている場合はスキップします。
+> **v2.1.0 gap-fill：** Pass 4 は `claudeos-core/skills/00.shared/MANIFEST.md` の存在も保証します。Pass 3c がこれを省略した場合（スキルが少ないプロジェクトで、スタックの `pass3.md` テンプレートは `MANIFEST.md` を生成ターゲットに挙げているものの REQUIRED としてマークしていないため起こり得ます）、gap-fill が最小限のスタブを作成し、`.claude/rules/50.sync/02.skills-sync.md`（v2.2.0 パス — sync ルール数が 3 個から 2 個に削減され、`03` が `02` になりました）の参照ターゲットが常に有効である状態を保ちます。冪等：ファイルがすでに実体のある内容（>20 文字）を持っている場合はスキップします。
 
 > **注意：** `claude -p` が失敗したり `pass4-prompt.md` が欠損している場合、自動化パイプラインは `lib/memory-scaffold.js` を経由した静的スキャフォールドにフォールバックします（`--lang` が非英語の場合は Claude 主導の翻訳付き）。静的フォールバックは `npx claudeos-core init` 内でのみ実行されます — 手動モードでは Pass 4 が成功する必要があります。
 
@@ -488,6 +484,8 @@ Pass 3 プロンプトテンプレートには、出力量をさらに抑制す
 - **Rule D** — 出力の簡潔さ：ファイル書き込みの合間は 1 行（`[WRITE]`/`[SKIP]`）のみ、ファクトテーブルの再掲やファイル内容のエコーをしない。
 - **Rule E** — バッチ冪等チェック：ターゲットごとの `Read` 呼び出しの代わりに、PHASE 2 開始時に `Glob` を 1 回だけ実行。
 
+**v2.2.0** では、Pass 3 は決定的な CLAUDE.md scaffold（`pass-prompts/templates/common/claude-md-scaffold.md`）をプロンプトにインラインで埋め込みます。これにより 8 つの最上位セクションのタイトルと順序が固定され、生成される `CLAUDE.md` がプロジェクト間で drift しなくなり、各セクションの内容はプロジェクトごとに適応できます。stack-detector の新しい `.env` パーサー（`lib/env-parser.js`）が `stack.envInfo` をプロンプトに供給し、port/host/API target 行が framework デフォルトではなくプロジェクトが実際に宣言した値と一致するようになります。
+
 **Pass 4** は L4 メモリレイヤをスキャフォールディングします：永続的なチーム知識ファイル（decision-log、failure-patterns、compaction ポリシー、auto-rule-update）に加えて、これらのファイルをいつどのように読み書きするかを将来のセッションに指示する `60.memory/` ルール。メモリレイヤこそが、Claude Code がセッションごとに学びを再発見するのではなく、セッション間で蓄積することを可能にします。`--lang` が非英語の場合、フォールバック静的コンテンツは書き込み前に Claude を経由して翻訳されます。v2.1.0 では、Pass 3c が省略した場合に備えて `skills/00.shared/MANIFEST.md` の gap-fill が追加されました。
 
 ---
@@ -497,7 +495,7 @@ Pass 3 プロンプトテンプレートには、出力量をさらに抑制す
 ```
 your-project/
 │
-├── CLAUDE.md                          ← Claude Code エントリーポイント
+├── CLAUDE.md                          ← Claude Code エントリーポイント（8セクション決定的構造、v2.2.0）
 │
 ├── .claude/
 │   └── rules/                         ← Glob トリガールール
@@ -591,24 +589,6 @@ Pass 3 の split モードはステージ数をドメイン数に応じてスケ
 
 Pass 4（メモリスキャフォールディング）は、Claude 主導の生成または静的フォールバックのいずれが走るかによって、上に ~30 秒〜5 分を追加します。マルチスタックプロジェクト（例：Java + React）では、backend と frontend のドメインが合算されます。backend 6 + frontend 4 ドメイン = 合計 10 で中規模ティアになります。
 
-### 実本番ケース：18 ドメインの管理画面フロントエンド（2026-04-20）
-
-18 ドメイン・6 ドメイングループの React 19 + Vite 6 + TypeScript 管理画面フロントエンドは、エンドツーエンドで **102 分・101 ファイル生成**で完走しました。ステージ別内訳：
-
-| ステージ | ファイル | 時間 | Files/min |
-|---|---|---|---|
-| `3a`（ファクト抽出） | 1（`pass3a-facts.md`） | 8m 44s | — |
-| `3b-core`（CLAUDE.md + 共通） | 24 | 22m 10s | 1.1 |
-| `3b-1`（15 ドメイン） | 30 | 10m 6s | **3.0** |
-| `3b-2`（3 ドメイン） | 6 | 4m 34s | 1.3 |
-| `3c-core`（guides + 共有） | 11 | 8m 31s | 1.3 |
-| `3c-1`（15 ドメイン） | 8 | 5m 11s | **1.5** |
-| `3c-2`（3 ドメイン） | 3 | 3m 50s | 0.8 |
-| `3d-aux`（database + mcp） | 3 | 2m 52s | 1.0 |
-| Pass 4 | 12 | 5m 36s | 2.1 |
-
-バッチ化されたドメインステージではスループットが顕著に高くなります（3b-1：3.0 files/min 対 3b-core：1.1 files/min） — これは、フレッシュなコンテキストのステージが、タイトで反復的なドメインごとのパターンから恩恵を受けるためです。検証はすべてパス：`plan-validator`、`sync-checker`、`content-validator`、`pass-json-validator` — オーバーフロー失敗 0 件、切り詰め 0 件。
-
 ---
 
 ## 検証ツール
@@ -810,8 +790,7 @@ ClaudeOS-Core を使ってプロジェクトのルールを生成し、その上
 4 つの Pass をまたいで `claude -p` を複数回呼び出します。v2.1.0 の split モードでは、Pass 3 だけでもプロジェクトサイズに応じて 4〜14+ ステージに展開されます（[自動スケーリング](#プロジェクトサイズによる自動スケーリング) を参照）。典型的な小規模プロジェクト（1〜15 ドメイン）で合計 8〜9 回の `claude -p` 呼び出し；18 ドメインのプロジェクトで 11 回；60 ドメインのプロジェクトで 15〜17 回。各ステージはフレッシュなコンテキストウィンドウで実行されます — 呼び出しあたりのトークンコストは、どのステージも全体のファイルツリーを 1 つのコンテキストに保持する必要がないため、単一呼び出しの Pass 3 時代より実際は低くなっています。`--lang` が非英語の場合、静的フォールバックパスは翻訳のために追加の `claude -p` 呼び出しを数回行うことがあります；結果は `claudeos-core/generated/.i18n-cache-<lang>.json` にキャッシュされ、その後の実行で再利用されます。これは通常の Claude Code 使用量の範囲内です。
 
 **Q：Pass 3 split モードとは何ですか？なぜ v2.1.0 で追加されたのですか？**
-v2.1.0 より前の Pass 3 は、生成されたファイルツリー全体（`CLAUDE.md`、standards、rules、skills、guides — 通常 30〜60 ファイル）を 1 回のレスポンスで出力しなければならない単一の `claude -p` 呼び出しでした。小規模プロジェクトでは機能しましたが、~5 ドメインで確実に `Prompt is too long` の出力累積失敗にぶつかっていました。失敗は入力サイズから予測できず、生成される各ファイルの冗長度合いに依存し、同じプロジェクトでも断続的に発生しました。Split モードはこの問題を構造的に回避します：Pass 3 は順次ステージ（`3a` → `3b-core` → `3b-N` → `3c-core` → `3c-N` → `3d-aux`）に分割され、それぞれがフレッシュなコンテキストウィンドウを持つ独立した `claude -p` 呼び出しです。ステージをまたいだ整合性は `pass3a-facts.md` — 以降のすべてのステージが `pass2-merged.json` を再読み込みせずに参照する 5〜10 KB の蒸留されたファクトシート — によって保持されます。`pass3-complete.json` マーカーは `groupsCompleted` 配列を持ち、`3c-2` 実行中のクラッシュは `3a` からではなく `3c-2` から再開するため、トークンコストの倍増を避けられます。最大 18 ドメイン × 101 ファイル × 102 分で実証済み、オーバーフロー 0 件 — 実本番内訳は [自動スケーリング](#プロジェクトサイズによる自動スケーリング) を参照してください。
-
+v2.1.0 より前の Pass 3 は、生成されたファイルツリー全体（`CLAUDE.md`、standards、rules、skills、guides — 通常 30〜60 ファイル）を 1 回のレスポンスで出力しなければならない単一の `claude -p` 呼び出しでした。小規模プロジェクトでは機能しましたが、~5 ドメインで確実に `Prompt is too long` の出力累積失敗にぶつかっていました。失敗は入力サイズから予測できず、生成される各ファイルの冗長度合いに依存し、同じプロジェクトでも断続的に発生しました。Split モードはこの問題を構造的に回避します：Pass 3 は順次ステージ（`3a` → `3b-core` → `3b-N` → `3c-core` → `3c-N` → `3d-aux`）に分割され、それぞれがフレッシュなコンテキストウィンドウを持つ独立した `claude -p` 呼び出しです。ステージをまたいだ整合性は `pass3a-facts.md` — 以降のすべてのステージが `pass2-merged.json` を再読み込みせずに参照する 5〜10 KB の蒸留されたファクトシート — によって保持されます。`pass3-complete.json` マーカーは `groupsCompleted` 配列を持ち、`3c-2` 実行中のクラッシュは `3a` からではなく `3c-2` から再開するため、トークンコストの倍増を避けられます。
 **Q：生成されたファイルを Git にコミットすべきですか？**
 はい、推奨します。チームが同じ Claude Code スタンダードを共有できます。`claudeos-core/generated/` を `.gitignore` に追加することを検討してください（分析 JSON は再生成可能）。
 
@@ -866,7 +845,14 @@ Claude Code の sensitive-path ポリシーは `claude -p` サブプロセスか
 
 ```
 pass-prompts/templates/
-├── common/                  # 共有 header/footer + pass4 + staging-override
+├── common/                  # 共有 header/footer + pass4 + staging-override + CLAUDE.md scaffold (v2.2.0)
+│   ├── header.md             # 役割 + 出力フォーマット指示（全 pass 共通）
+│   ├── pass3-footer.md       # Pass 3 完了後の health-check 指示 + 5 つの CRITICAL ガードレールブロック (v2.2.0)
+│   ├── pass3-phase1.md       # 「Read Once, Extract Facts」ブロック（Rule A-E）(v2.1.0)
+│   ├── pass4.md              # メモリスキャフォールディングプロンプト (v2.0.0)
+│   ├── staging-override.md   # .claude/rules/** の書き込みを .staged-rules/** にリダイレクト (v2.0.0)
+│   ├── claude-md-scaffold.md # 決定論的 8 セクション CLAUDE.md テンプレート (v2.2.0)
+│   └── lang-instructions.json # 言語別出力指示（10 言語）
 ├── java-spring/             # Java / Spring Boot
 ├── kotlin-spring/           # Kotlin / Spring Boot (CQRS, BFF, multi-module)
 ├── node-express/            # Node.js / Express
@@ -883,6 +869,8 @@ pass-prompts/templates/
 
 `plan-installer` がスタックを自動検出し、タイプ固有のプロンプトを組み立てます。NestJS、Vue/Nuxt、Vite SPA、Flask はそれぞれフレームワーク固有の分析カテゴリを備えた専用テンプレートを使用します（例：NestJS の `@Module`/`@Injectable`/Guards；Vue の `<script setup>`/Pinia/useFetch；Vite の client-side routing/`VITE_` env；Flask の Blueprint/`app.factory`/Flask-SQLAlchemy）。マルチスタックプロジェクトでは、`pass1-backend-prompt.md` と `pass1-frontend-prompt.md` が別々に生成され、`pass3-prompt.md` は両方のスタックの生成ターゲットを結合します。v2.1.0 では、Pass 3 テンプレートの先頭に `common/pass3-phase1.md`（Rule A–E を含む「Read Once, Extract Facts」ブロック）が追加された後、split モードのステージごとにスライスされます。Pass 4 はスタックに関係なく共有の `common/pass4.md` テンプレート（メモリスキャフォールディング）を使用します。
 
+**v2.2.0 では**、Pass 3 プロンプトは phase1 ブロックとスタック固有本体の間に `common/claude-md-scaffold.md`（決定論的 8 セクション CLAUDE.md テンプレート）もインラインで埋め込みます — これによりセクション構造がプロジェクト間でずれることなく、内容はプロジェクトごとに適応します。テンプレートは **English-first** で記述され、`lang-instructions.json` からの言語注入が LLM に対して出力時にセクションタイトルと散文を対象出力言語に翻訳するよう指示します。
+
 ---
 
 ## モノレポサポート
@@ -969,6 +957,12 @@ my-monorepo/                    ← ここで実行：npx claudeos-core init
 
 **"CLAUDEOS_SKIP_TRANSLATION=1 is set but --lang='ko' requires translation" InitError（v2.0.0）** — シェルでテスト専用の環境変数 `CLAUDEOS_SKIP_TRANSLATION=1` が設定されており（おそらく CI/テスト設定の残り物）、かつ非英語 `--lang` を選択しました。この環境変数は、Pass 4 の静的フォールバックと gap-fill が非英語出力のために依存する翻訳パスをショートサーキットします。`init` は言語選択時に競合を検出し、即座に中止します（Pass 4 の途中で紛らわしいネストされたエラーでクラッシュするのではなく）。修正：実行前に `unset CLAUDEOS_SKIP_TRANSLATION` するか、`npx claudeos-core init --lang en` を使用してください。
 
+**"⚠️ v2.2.0 upgrade detected" 警告 (v2.2.0)** — 既存の `CLAUDE.md` が v2.2.0 以前のバージョンで生成されている状態。デフォルトの resume モード再生成は Rule B idempotency により既存ファイルをスキップするため、v2.2.0 の構造改善（8 セクション CLAUDE.md scaffold、`40.infra/*` ファイル別 paths、`.env.example` ベースのポート精度、Section 8 `Common Rules & Memory (L4)` 再設計（共通ルール・L4 メモリの 2 つのサブセクション構造）、`60.memory/*` ルール行、forward-reference された `04.doc-writing-guide.md`）が適用されません。解決: `npx claudeos-core init --force` で再実行。生成ファイル（`CLAUDE.md`、`.claude/rules/`、`claudeos-core/standard/`、`claudeos-core/skills/`、`claudeos-core/guide/`）は上書きされますが、`claudeos-core/memory/` コンテンツ（ユーザーが蓄積した decision-log、failure-patterns エントリー — append-only）は完全に保持されます。上書き前に diff を確認したい場合は、`--force` 実行前にプロジェクトを git commit してください。
+
+**CLAUDE.md の port が `.env.example` と異なる (v2.2.0)** — v2.2.0 の新しい `.env` パーサー（`lib/env-parser.js`）は `.env.example` を優先的に読み（コミットされた canonical ファイル）、fallback として `.env` バリアントを読みます。認識されるポート変数名: `PORT`、`VITE_PORT`、`VITE_DESKTOP_PORT`、`NEXT_PUBLIC_PORT`、`NUXT_PORT`、`DJANGO_PORT` など。Spring Boot の場合、`application.yml` の `server.port` が依然として `.env` より優先されます（framework-native config が優先）。プロジェクトが非標準 env 変数名を使用する場合は、慣例名に変更するか `PORT_VAR_KEYS` 拡張を issue でリクエストしてください。framework デフォルト（Vite 5173、Next.js 3000、Django 8000）は、直接検出と `.env` の両方がサイレントな場合のみ使用されます。
+
+**生成されたドキュメントで値が `***REDACTED***` と表示される (v2.2.0)** — 意図された動作です。v2.2.0 の `.env` パーサーは `PASSWORD`/`SECRET`/`TOKEN`/`API_KEY`/`CREDENTIAL`/`PRIVATE_KEY` パターンにマッチする変数値を自動的に `***REDACTED***` に置換してすべての生成器に渡します。`.env.example` に誤ってコミットされた機密情報に対する defense-in-depth 保護です。`DATABASE_URL` は stack-detector DB 識別 back-compat のため保持されます。生成された `CLAUDE.md` テーブルで `***REDACTED***` が見られる場合はバグなので issue を提出してください — redacted 値はテーブルに到達すべきではありません。非機密ランタイム設定（port、host、API target、NODE_ENV など）は変更なく通過します。
+
 ---
 
 ## 貢献
@@ -978,7 +972,7 @@ my-monorepo/                    ← ここで実行：npx claudeos-core init
 - **新しいスタックテンプレート** — Ruby/Rails、Go (Gin/Fiber/Echo)、PHP (Laravel/Symfony)、Rust (Axum/Actix)、Svelte/SvelteKit、Remix
 - **IDE 統合** — VS Code 拡張機能、IntelliJ プラグイン
 - **CI/CD テンプレート** — GitLab CI、CircleCI、Jenkins の例（GitHub Actions はすでに付属 — `.github/workflows/test.yml` 参照）
-- **テストカバレッジ** — テストスイートの拡張（現在 29 のテストファイルで 563 テスト、スキャナ、スタック検出、ドメイングループ化、プランパーシング、プロンプト生成、CLI セレクタ、モノレポ検出、Vite SPA 検出、検証ツール、L4 メモリスキャフォールド、Pass 2 再開検証、Pass 3 Guards 1/2/3（H1 センチネル + H2 BOM-aware 空ファイル + strict stale-marker unlink）、Pass 3 split モードのバッチサブ分割、Pass 3 部分マーカー再開（v2.1.0）、Pass 4 マーカーコンテンツ検証 + stale-marker unlink strictness + scaffoldSkillsManifest gap-fill（v2.1.0）、翻訳 env-skip ガード + early fail-fast + CI ワークフロー、staged-rules 移動、言語対応翻訳フォールバック、master plan 廃止のリグレッションスイート（v2.1.0）、memory score/compact フォーマッティングのリグレッション（v2.1.0）、AI Work Rules テンプレート構造をカバー）
+- **テストカバレッジ** — テストスイートの拡張（現在 30 のテストファイルで 602 テスト、スキャナ、スタック検出、ドメイングループ化、プランパーシング、プロンプト生成、CLI セレクタ、モノレポ検出、Vite SPA 検出、検証ツール、L4 メモリスキャフォールド、Pass 2 再開検証、Pass 3 Guards 1/2/3（H1 センチネル + H2 BOM-aware 空ファイル + strict stale-marker unlink）、Pass 3 split モードのバッチサブ分割、Pass 3 部分マーカー再開（v2.1.0）、Pass 4 マーカーコンテンツ検証 + stale-marker unlink strictness + scaffoldSkillsManifest gap-fill（v2.1.0）、翻訳 env-skip ガード + early fail-fast + CI ワークフロー、staged-rules 移動、言語対応翻訳フォールバック、master plan 廃止のリグレッションスイート（v2.1.0）、memory score/compact フォーマッティングのリグレッション（v2.1.0）、AI Work Rules テンプレート構造、`.env` パーサー port/host/API-target 抽出 + センシティブ変数 redaction (v2.2.0)をカバー）
 
 領域の完全なリスト、コードスタイル、コミット規約、新しいスタックテンプレートを追加するためのステップバイステップガイドについては、[`CONTRIBUTING.md`](./CONTRIBUTING.md) を参照してください。
 

package/README.ko.md

@@ -12,20 +12,6 @@ ClaudeOS-Core는 코드베이스를 읽고, 발견한 모든 패턴을 추출하
 
 ---
 
-## v2.1.0 신규 변경사항
-
-v2.1.0은 Pass 3를 재설계하여 중·대규모 프로젝트에서 발생하던 `Prompt is too long` 실패를 제거합니다. 이전에는 단일 Pass 3 호출이 전체 문서 트리(CLAUDE.md, rules, standards, skills, guides — 수십 개 파일)를 한 번에 출력해야 했고, 누적 출력이 5도메인 즈음부터 컨텍스트 윈도우를 초과했습니다. 이번 수정은 프롬프트 튜닝이 아니라 **구조적** 변경입니다:
-
-- **Pass 3 split 모드** (항상 활성) — Pass 3가 순차 `claude -p` 호출들로 분할됩니다 (`3a` → `3b-core` → `3b-N` → `3c-core` → `3c-N` → `3d-aux`). 각 스테이지는 **새 컨텍스트 윈도우**에서 시작하므로 프로젝트 크기와 무관하게 출력 누적 오버플로우가 구조적으로 불가능합니다.
-- **스테이지 간 팩트 시트** — `3a` 스테이지가 Pass 2 분석을 한 번만 읽고 5–10 KB의 `pass3a-facts.md`로 증류합니다. 이후 모든 스테이지는 100–500 KB의 `pass2-merged.json` 대신 이 팩트 시트를 참조하여, 새 컨텍스트 사이에서도 파일 간 일관성을 유지합니다.
-- **배치 하위 분할** (16도메인 이상에서 자동) — 3b/3c 스테이지가 15도메인 단위 배치로 추가 분할되어, 각 스테이지의 출력이 ~50 파일 이하로 제한됩니다. 18도메인 React 19 + Vite 6 admin 프론트엔드 실전 실행에서 **102분에 101파일 생성 / 8스테이지 / 오버플로우 0건** 완주를 확인했습니다 (실측 2026-04-20).
-- **Master plan 생성 제거** — `claudeos-core/plan/*-master.md` 파일은 더 이상 생성되지 않습니다. Master plan은 Claude Code가 런타임에 읽지 않는 내부 백업이었고, Pass 3d에서 이를 집계하는 것이 오버플로우 주요 원인이었습니다. 백업·복원은 `git`을 사용하세요.
-- **Pass 4 gap-fill: `skills/00.shared/MANIFEST.md`** — Pass 3c가 skill 레지스트리를 생성하지 못한 경우(skill-sparse 프로젝트), Pass 4가 스텁을 자동 생성하여 `.claude/rules/50.sync/03.skills-sync.md`가 존재하지 않는 파일을 가리키는 상황을 방지합니다.
-
-소소한 수정도 포함됩니다: `memory --help`가 이제 memory 서브커맨드 help를 표시합니다 (이전엔 top-level이 표시됨); `memory score`가 `importance` 라인을 중복 남기지 않습니다; `memory compact` summary 마커가 올바른 markdown 리스트 항목 형식입니다. 전체 내역: [CHANGELOG.md](./CHANGELOG.md).
-
----
-
 ## 왜 ClaudeOS-Core인가?
 
 다른 모든 Claude Code 도구는 이렇게 작동합니다:
@@ -99,10 +85,20 @@ ClaudeOS-Core는 프로젝트가 `ApiResponse.ok()`를 쓴다는 것, MyBatis XM
 | **Vite / React SPA** | `package.json`, `vite.config.*` | 9개 대분류, 55개 소분류 |
 | **Angular** | `package.json`, `angular.json` | 12개 대분류, 78개 소분류 |
 
-자동 감지 항목: 언어 & 버전, 프레임워크 & 버전(SPA 프레임워크인 Vite 포함), ORM (MyBatis, JPA, Exposed, Prisma, TypeORM, SQLAlchemy 등), 데이터베이스 (PostgreSQL, MySQL, Oracle, MongoDB, SQLite), 패키지 매니저 (Gradle, Maven, npm, yarn, pnpm, pip, poetry), 아키텍처 (CQRS, BFF — 모듈명에서 감지), 멀티모듈 구조 (settings.gradle에서 감지), 모노레포 (Turborepo, pnpm-workspace, Lerna, npm/yarn workspaces).
+자동 감지 항목: 언어 & 버전, 프레임워크 & 버전(SPA 프레임워크인 Vite 포함), ORM (MyBatis, JPA, Exposed, Prisma, TypeORM, SQLAlchemy 등), 데이터베이스 (PostgreSQL, MySQL, Oracle, MongoDB, SQLite), 패키지 매니저 (Gradle, Maven, npm, yarn, pnpm, pip, poetry), 아키텍처 (CQRS, BFF — 모듈명에서 감지), 멀티모듈 구조 (settings.gradle에서 감지), 모노레포 (Turborepo, pnpm-workspace, Lerna, npm/yarn workspaces), **`.env.example` 런타임 설정**(v2.2.0 — Vite · Next.js · Nuxt · Angular · Node · Python 프레임워크의 16+ 관례 변수명에서 port/host/API-target 추출).
 
 **직접 지정할 필요 없습니다. 전부 자동으로 감지합니다.**
 
+### `.env` 기반 런타임 설정 (v2.2.0)
+
+v2.2.0에서 `lib/env-parser.js`가 추가되어 생성된 `CLAUDE.md`가 framework 기본값이 아닌 프로젝트가 실제로 선언한 값을 반영합니다.
+
+- **검색 순서**: `.env.example` (커밋되는 canonical) → `.env.local.example` → `.env.sample` → `.env.template` → `.env` → `.env.local` → `.env.development`. `.example` 변형이 우선인 이유는 개별 기여자의 로컬 오버라이드가 아닌 개발자 중립적인 "의도된 설정의 shape-of-truth"이기 때문입니다.
+- **인식되는 포트 변수 관례**: `VITE_PORT` / `VITE_DEV_PORT` / `VITE_DESKTOP_PORT` / `NEXT_PUBLIC_PORT` / `NUXT_PORT` / `NG_PORT` / `APP_PORT` / `SERVER_PORT` / `HTTP_PORT` / `DEV_PORT` / `FLASK_RUN_PORT` / `UVICORN_PORT` / `DJANGO_PORT` / 그리고 최후순위 `PORT`. 프레임워크별 이름이 generic `PORT`보다 우선.
+- **Host · API target**: `VITE_DEV_HOST` / `VITE_API_TARGET` / `NEXT_PUBLIC_API_URL` / `NUXT_PUBLIC_API_BASE` / `BACKEND_URL` / `PROXY_TARGET` 등.
+- **우선순위**: Spring Boot `application.yml`의 `server.port`가 먼저(framework-native config), 그 다음 `.env` 선언 포트, 마지막으로 framework 기본값(Vite 5173, Next.js 3000, Django 8000 등)이 fallback.
+- **민감 변수 redaction**: `PASSWORD` / `SECRET` / `TOKEN` / `API_KEY` / `ACCESS_KEY` / `PRIVATE_KEY` / `CREDENTIAL` / `JWT_SECRET` / `CLIENT_SECRET` / `SESSION_SECRET` / `BEARER` / `SALT` 패턴에 매칭되는 변수 값은 downstream 생성기로 전달되기 전 `***REDACTED***`로 치환. `.env.example`에 실수로 커밋된 민감 정보에 대한 defense-in-depth. `DATABASE_URL`은 stack-detector DB 감지 back-compat를 위해 명시적으로 whitelist.
+
 ### Java 도메인 감지 (5가지 패턴, 폴백 포함)
 
 | 우선순위 | 패턴 | 구조 | 예시 |
@@ -378,7 +374,7 @@ cat claudeos-core/generated/pass4-prompt.md \
 
 **확인:** `claudeos-core/memory/`에 4개 파일(`decision-log.md`, `failure-patterns.md`, `compaction.md`, `auto-rule-update.md`)이 있고, `.claude/rules/60.memory/`에 4개 규칙 파일이 있으며, `CLAUDE.md`에 `## Memory (L4)` 섹션이 추가되어야 합니다. 마커: `claudeos-core/generated/pass4-memory.json`.
 
-> **v2.1.0 gap-fill:** Pass 4는 `claudeos-core/skills/00.shared/MANIFEST.md`의 존재도 보장합니다. Pass 3c가 이를 생략한 경우(skill-sparse 프로젝트에서 가능 — 스택 `pass3.md` 템플릿들이 `MANIFEST.md`를 생성 대상으로 나열하지만 REQUIRED로 표시하지 않음), gap-fill이 최소 스텁을 생성하여 `.claude/rules/50.sync/03.skills-sync.md`가 항상 유효한 참조 대상을 갖도록 합니다. Idempotent: 파일이 이미 실제 내용(20자 초과)을 가지고 있으면 스킵합니다.
+> **v2.1.0 gap-fill:** Pass 4는 `claudeos-core/skills/00.shared/MANIFEST.md`의 존재도 보장합니다. Pass 3c가 이를 생략한 경우(skill-sparse 프로젝트에서 가능 — 스택 `pass3.md` 템플릿들이 `MANIFEST.md`를 생성 대상으로 나열하지만 REQUIRED로 표시하지 않음), gap-fill이 최소 스텁을 생성하여 `.claude/rules/50.sync/02.skills-sync.md`(v2.2.0 경로 — sync 규칙 수가 3개에서 2개로 축소되며 `03`이 `02`로 변경)가 항상 유효한 참조 대상을 갖도록 합니다. Idempotent: 파일이 이미 실제 내용(20자 초과)을 가지고 있으면 스킵합니다.
 
 > **참고:** `claude -p`가 실패하거나 `pass4-prompt.md`가 없으면, 자동 파이프라인은 `lib/memory-scaffold.js`를 통한 정적 스캐폴드로 폴백합니다(`--lang`이 비영어일 때 Claude-driven 번역 포함). 정적 폴백은 `npx claudeos-core init` 내부에서만 실행됩니다 — 수동 모드에서는 Pass 4가 성공해야 합니다.
 
@@ -488,6 +484,8 @@ Pass 3 프롬프트 템플릿에는 출력 볼륨을 추가로 제약하는 **Ph
 - **Rule D** — 출력 간결성: 파일 쓰기 사이에 한 줄(`[WRITE]`/`[SKIP]`)만, 팩트 테이블 반복 금지, 파일 내용 에코 금지.
 - **Rule E** — 배치 idempotent 체크: PHASE 2 시작 시 `Glob` 1회로 대상별 `Read` 호출 대체.
 
+**v2.2.0**에서 Pass 3는 결정적 CLAUDE.md scaffold(`pass-prompts/templates/common/claude-md-scaffold.md`)를 프롬프트에 인라인으로 임베드합니다. 이로써 8개 최상위 섹션 제목과 순서가 고정되어 생성된 `CLAUDE.md`가 프로젝트 간 drift 되지 않도록 하면서, 섹션별 내용은 각 프로젝트에 맞게 적응할 수 있습니다. stack-detector의 새 `.env` 파서(`lib/env-parser.js`)가 `stack.envInfo`를 프롬프트에 공급하여, port/host/API target 행이 framework 기본값이 아닌 프로젝트가 실제로 선언한 값과 일치하게 됩니다.
+
 **Pass 4**는 L4 Memory 레이어를 스캐폴딩합니다: 지속 팀 지식 파일들(decision-log, failure-patterns, compaction policy, auto-rule-update)과 향후 세션에 이 파일들을 언제 어떻게 읽고 쓸지 지시하는 `60.memory/` 규칙들. 메모리 레이어는 Claude Code가 세션마다 교훈을 재발견하는 대신 누적할 수 있게 해주는 핵심입니다. `--lang`이 비영어일 때는 폴백 정적 콘텐츠가 Claude를 통해 번역된 후 작성됩니다. v2.1.0은 Pass 3c가 `skills/00.shared/MANIFEST.md`를 생략한 경우의 gap-fill을 추가합니다.
 
 ---
@@ -497,7 +495,7 @@ Pass 3 프롬프트 템플릿에는 출력 볼륨을 추가로 제약하는 **Ph
 ```
 your-project/
 │
-├── CLAUDE.md                          ← Claude Code 진입점
+├── CLAUDE.md                          ← Claude Code 진입점 (8섹션 결정적 구조, v2.2.0)
 │
 ├── .claude/
 │   └── rules/                         ← Glob 트리거 규칙
@@ -591,24 +589,6 @@ Pass 3 split 모드는 도메인 수에 비례하여 스테이지 수가 증가
 
 Pass 4(메모리 스캐폴딩)는 Claude-driven 생성 또는 정적 폴백 중 어느 것이 실행되는지에 따라 ~30초–5분을 추가합니다. 멀티스택 프로젝트(예: Java + React)에서는 백엔드와 프론트엔드 도메인이 합산됩니다. 백엔드 6개 + 프론트엔드 4개 = 총 10개로 중규모 등급입니다.
 
-### 실전 프로덕션 케이스: 18도메인 admin 프론트엔드 (2026-04-20)
-
-18개 도메인과 6개 도메인 그룹을 가진 React 19 + Vite 6 + TypeScript admin 프론트엔드가 **102분에 101개 파일 생성**으로 end-to-end 완주했습니다. 스테이지별 내역:
-
-| 스테이지 | 파일 수 | 소요 시간 | 파일/분 |
-|---|---|---|---|
-| `3a` (팩트 추출) | 1 (`pass3a-facts.md`) | 8분 44초 | — |
-| `3b-core` (CLAUDE.md + 공통) | 24 | 22분 10초 | 1.1 |
-| `3b-1` (15도메인) | 30 | 10분 6초 | **3.0** |
-| `3b-2` (3도메인) | 6 | 4분 34초 | 1.3 |
-| `3c-core` (가이드 + 공유) | 11 | 8분 31초 | 1.3 |
-| `3c-1` (15도메인) | 8 | 5분 11초 | **1.5** |
-| `3c-2` (3도메인) | 3 | 3분 50초 | 0.8 |
-| `3d-aux` (database + mcp) | 3 | 2분 52초 | 1.0 |
-| Pass 4 | 12 | 5분 36초 | 2.1 |
-
-배치된 도메인 스테이지에서 처리량이 눈에 띄게 높습니다 (3b-1: 3.0 파일/분 vs. 3b-core: 1.1 파일/분). 이는 새 컨텍스트 스테이지가 도메인별로 반복 가능한 패턴을 유지하기 때문입니다. 검증 전부 green: `plan-validator`, `sync-checker`, `content-validator`, `pass-json-validator` — 오버플로우 0건, 트렁케이션 0건.
-
 ---
 
 ## 검증 도구
@@ -809,8 +789,7 @@ ClaudeOS-Core로 프로젝트 규칙을 생성한 뒤, ECC나 Harness를 그 위
 4 Pass에 걸쳐 `claude -p`를 여러 번 호출합니다. v2.1.0 split 모드에서는 Pass 3만 해도 프로젝트 크기에 따라 4–14+ 스테이지로 확장됩니다 (자세히는 [프로젝트 규모별 자동 스케일링](#프로젝트-규모별-자동-스케일링) 참조). 일반적으로 소규모 프로젝트(1–15 도메인)는 총 8–9회, 18 도메인 프로젝트는 11회, 60 도메인 프로젝트는 15–17회의 `claude -p` 호출을 사용합니다. 각 스테이지는 새 컨텍스트 윈도우에서 실행되므로 호출당 토큰 비용은 실제로 단일 호출 Pass 3보다 낮습니다 — 어떤 스테이지도 전체 파일 트리를 한 컨텍스트에 담지 않기 때문입니다. `--lang`이 비영어이면 정적 폴백 경로가 번역을 위해 추가로 몇 번 호출할 수 있지만, 결과는 `claudeos-core/generated/.i18n-cache-<lang>.json`에 캐시되어 이후 실행에서 재사용됩니다. 일반적인 Claude Code 사용량 내에서 처리됩니다.
 
 **Q: Pass 3 split 모드가 무엇이고 왜 v2.1.0에 추가됐나요?**
-v2.1.0 이전에는 Pass 3가 전체 생성 파일 트리(`CLAUDE.md`, standards, rules, skills, guides — 보통 30–60개 파일)를 한 응답에 출력해야 하는 단일 `claude -p` 호출이었습니다. 소규모 프로젝트에서는 동작했지만 ~5도메인부터 `Prompt is too long` 출력 누적 실패가 안정적으로 발생했습니다. 이 실패는 입력 크기로부터 예측 불가능 — 각 생성 파일이 얼마나 verbose한지에 따라 달라졌고, 같은 프로젝트에서도 간헐적으로 발생할 수 있었습니다. Split 모드는 이를 구조적으로 회피합니다: Pass 3가 순차 스테이지들(`3a` → `3b-core` → `3b-N` → `3c-core` → `3c-N` → `3d-aux`)로 분할되고, 각각은 새 컨텍스트 윈도우를 가진 별개의 `claude -p` 호출입니다. 스테이지 간 일관성은 `pass3a-facts.md`(5–10 KB 증류 팩트 시트)로 보존되며, 이후 모든 스테이지가 `pass2-merged.json` 재독 대신 이를 참조합니다. `pass3-complete.json` 마커는 `groupsCompleted` 배열을 가지므로 `3c-2`에서 크래시되어도 `3c-2`부터 재개되어(`3a`가 아니라) 토큰 비용 두 배 증가를 방지합니다. 18도메인 × 101파일 × 102분 실증 — [프로젝트 규모별 자동 스케일링](#프로젝트-규모별-자동-스케일링)에서 실측 내역 참조.
-
+v2.1.0 이전에는 Pass 3가 전체 생성 파일 트리(`CLAUDE.md`, standards, rules, skills, guides — 보통 30–60개 파일)를 한 응답에 출력해야 하는 단일 `claude -p` 호출이었습니다. 소규모 프로젝트에서는 동작했지만 ~5도메인부터 `Prompt is too long` 출력 누적 실패가 안정적으로 발생했습니다. 이 실패는 입력 크기로부터 예측 불가능 — 각 생성 파일이 얼마나 verbose한지에 따라 달라졌고, 같은 프로젝트에서도 간헐적으로 발생할 수 있었습니다. Split 모드는 이를 구조적으로 회피합니다: Pass 3가 순차 스테이지들(`3a` → `3b-core` → `3b-N` → `3c-core` → `3c-N` → `3d-aux`)로 분할되고, 각각은 새 컨텍스트 윈도우를 가진 별개의 `claude -p` 호출입니다. 스테이지 간 일관성은 `pass3a-facts.md`(5–10 KB 증류 팩트 시트)로 보존되며, 이후 모든 스테이지가 `pass2-merged.json` 재독 대신 이를 참조합니다. `pass3-complete.json` 마커는 `groupsCompleted` 배열을 가지므로 `3c-2`에서 크래시되어도 `3c-2`부터 재개되어(`3a`가 아니라) 토큰 비용 두 배 증가를 방지합니다.
 **Q: 생성된 파일을 Git에 커밋해야 하나요?**
 네, 권장합니다. 팀원 전체가 동일한 Claude Code 표준을 공유할 수 있습니다. `claudeos-core/generated/`는 `.gitignore`에 추가하는 것을 권장합니다 (분석 JSON은 재생성 가능).
 
@@ -865,7 +844,14 @@ Claude Code의 sensitive-path 정책이 `claude -p` 서브프로세스에서 `.c
 
 ```
 pass-prompts/templates/
-├── common/                  # 공유 header/footer + pass4 + staging-override
+├── common/                  # 공유 header/footer + pass4 + staging-override + CLAUDE.md scaffold (v2.2.0)
+│   ├── header.md             # 역할 + 출력 포맷 지시문 (모든 pass)
+│   ├── pass3-footer.md       # Pass 3 완료 후 health-check 지시 + 5개 CRITICAL 가드레일 블록 (v2.2.0)
+│   ├── pass3-phase1.md       # "Read Once, Extract Facts" 블록 (Rule A-E) (v2.1.0)
+│   ├── pass4.md              # 메모리 스캐폴딩 프롬프트 (v2.0.0)
+│   ├── staging-override.md   # .claude/rules/** 쓰기를 .staged-rules/**로 리다이렉트 (v2.0.0)
+│   ├── claude-md-scaffold.md # 결정적 8섹션 CLAUDE.md 템플릿 (v2.2.0)
+│   └── lang-instructions.json # 언어별 출력 지시문 (10개 언어)
 ├── java-spring/             # Java / Spring Boot
 ├── kotlin-spring/           # Kotlin / Spring Boot (CQRS, BFF, multi-module)
 ├── node-express/            # Node.js / Express
@@ -882,6 +868,8 @@ pass-prompts/templates/
 
 `plan-installer`가 스택을 자동 감지한 후 타입별 프롬프트를 조합합니다. NestJS, Vue/Nuxt, Vite SPA, Flask는 각각 프레임워크별 분석 카테고리가 적용된 전용 템플릿 사용 (예: NestJS의 `@Module`/`@Injectable`/Guards; Vue의 `<script setup>`/Pinia/useFetch; Vite의 client-side routing/`VITE_` env; Flask의 Blueprint/`app.factory`/Flask-SQLAlchemy). 멀티스택 프로젝트에서는 `pass1-backend-prompt.md`와 `pass1-frontend-prompt.md`가 별도로 생성되고, `pass3-prompt.md`는 두 스택의 생성 대상을 결합합니다. v2.1.0에서는 Pass 3 템플릿 앞에 `common/pass3-phase1.md`("Read Once, Extract Facts" 블록, Rule A–E 포함)가 prepend된 후 split 모드 스테이지별로 슬라이스됩니다. Pass 4는 스택 무관 공유 `common/pass4.md` 템플릿 사용 (메모리 스캐폴딩).
 
+**v2.2.0에서는** Pass 3 프롬프트가 phase1 블록과 스택별 본문 사이에 `common/claude-md-scaffold.md`(결정적 8섹션 CLAUDE.md 템플릿)를 인라인 임베드합니다 — 이로써 생성된 CLAUDE.md의 섹션 구조가 프로젝트 간 drift되지 않으며, 내용은 프로젝트별로 적응됩니다. 템플릿은 **English-first**로 작성되며, `lang-instructions.json`의 언어 주입이 LLM에게 출력 시점에 섹션 제목과 산문을 대상 출력 언어로 번역하도록 지시합니다.
+
 ---
 
 ## 모노레포 지원
@@ -950,10 +938,10 @@ my-monorepo/                    ← 여기서 실행: npx claudeos-core init
 
 **"Pass 3 produced CLAUDE.md and rules but N/9 guide files are missing or empty" (v2.0.0)** — Guard 3 (H2) 발동: Claude가 CLAUDE.md + rules 작성 후 `claudeos-core/guide/` 섹션에 도달하기 전(또는 시작 전) 응답이 잘림 (9 파일 예상). BOM-only 또는 공백만 있는 파일에서도 발동 (헤딩은 작성됐으나 본문이 잘림). 이 가드 없으면 완료 마커가 작성되어 이후 실행에서 `guide/`가 영구히 비어 있음. 마커 미작성이므로 다음 `init` 실행이 동일 Pass 2 결과에서 Pass 3 재시도. 계속 반복되면 `npx claudeos-core init --force`로 처음부터 재생성.
 
-**"Pass 3 finished but the following required output(s) are missing or empty" (v2.0.0, v2.1.0에서 업데이트)** — Guard 3 (H1) 발동: Claude가 `claudeos-core/guide/` 이후, `claudeos-core/standard/`나 `claudeos-core/skills/` 도달 전(또는 진행 중) 응답이 잘림. 요구사항: (a) `standard/00.core/01.project-overview.md` 존재 + 비어있지 않음 (모든 스택의 Pass 3 프롬프트가 작성하는 센티넬), (b) `skills/`에 ≥1 비어있지 않은 `.md`. `database/`와 `mcp-guide/`는 의도적으로 제외 (일부 스택은 정당하게 0 파일 생성). v2.1.0부터 `plan/`은 검사하지 않음 (master plan 제거됨). Guard 3 (H2)와 동일 복구 경로: `init` 재실행, 지속되면 `--force`.
-
-**"Pass 3 split 스테이지가 중간에 크래시됨 (v2.1.0)"** — split 스테이지 중 하나(예: `3b-1`, `3c-2`)가 실행 중 실패하면 해당 스테이지 마커는 작성되지 **않지만**, 완료된 스테이지는 `pass3-complete.json.groupsCompleted`에 기록**됩니다**. 다음 `init` 실행이 이 배열을 읽고 첫 미완료 스테이지부터 재개하며, 이전 완료 작업을 스킵합니다. 수동 조치 불필요 — 그냥 `npx claudeos-core init`을 재실행하세요. 같은 스테이지에서 재개가 계속 실패하면 `claudeos-core/generated/pass3-prompt.md`를 검사하여 malformed content가 있는지 확인 후 전체 재시작을 위해 `--force`를 시도하세요. `pass3-complete.json` 형식(`mode: "split"`, `groupsCompleted: [...]`)은 안정적 — 마커가 없거나 malformed이면 전체 Pass 3가 `3a`부터 재실행됩니다.
-
+**"Pass 3 finished but the following required output(s) are missing or empty" (v2.0.0, v2.1.0에서 업데이트)** — Guard 3 (H1) 발동: Claude가 `claudeos-core/guide/` 이후, `claudeos-core/standard/`나 `claudeos-core/skills/` 도달 전(또는 진행 중) 응답이 잘림. 요구사항: (a) `standard/00.core/01.project-overview.md` 존재 + 비어있지 않음 (모든 스택의 Pass 3 프롬프트가 작성하는 센티넬), (b) `skills/`에 ≥1 비어있지 않은 `.md`. `database/`와 `mcp-guide/`는 의도적으로 제외 (일부 스택은 정당하게 0 파일 생성). v2.1.0부터 `plan/`은 검사하지 않음 (master plan 제거됨). Guard 3 (H2)와 동일 복구 경로: `init` 재실행, 지속되면 `--force`.
+
+**"Pass 3 split 스테이지가 중간에 크래시됨 (v2.1.0)"** — split 스테이지 중 하나(예: `3b-1`, `3c-2`)가 실행 중 실패하면 해당 스테이지 마커는 작성되지 **않지만**, 완료된 스테이지는 `pass3-complete.json.groupsCompleted`에 기록**됩니다**. 다음 `init` 실행이 이 배열을 읽고 첫 미완료 스테이지부터 재개하며, 이전 완료 작업을 스킵합니다. 수동 조치 불필요 — 그냥 `npx claudeos-core init`을 재실행하세요. 같은 스테이지에서 재개가 계속 실패하면 `claudeos-core/generated/pass3-prompt.md`를 검사하여 malformed content가 있는지 확인 후 전체 재시작을 위해 `--force`를 시도하세요. `pass3-complete.json` 형식(`mode: "split"`, `groupsCompleted: [...]`)은 안정적 — 마커가 없거나 malformed이면 전체 Pass 3가 `3a`부터 재실행됩니다.
+
 **"Pass 3 stale 마커 (형식 불일치) — incomplete로 처리" (v2.1.0)** — v2.1.0 이전의 단일 호출 실행에서 생성된 `pass3-complete.json`이 새 split 모드 규칙으로 해석되고 있습니다. 형식 체크가 `mode: "split"`와 `groupsCompleted` 배열을 찾으며, 둘 중 하나라도 없으면 마커를 partial로 간주하고 Pass 3가 split 모드로 재실행됩니다. v2.0.x에서 업그레이드했다면 한 번 예상되는 동작 — 다음 실행이 올바른 마커 형식을 작성합니다. 조치 불필요.
 
 **"pass2-merged.json exists but is malformed or incomplete (<5 top-level keys), re-running" (v2.0.0)** — 에러가 아닌 정보 로그. 재개 시 `init`이 이제 `pass2-merged.json`을 파싱하고 검증 (≥5 최상위 키 필요, `pass-json-validator`의 `INSUFFICIENT_KEYS` 임계값 미러링). 이전 크래시 실행에서 남은 skeleton `{}` 또는 malformed JSON은 자동 삭제되고 Pass 2 재실행. 수동 조치 불필요 — 파이프라인 자가 치유. 계속 반복되면 `claudeos-core/generated/pass2-prompt.md` 검사 후 `--force`로 재시도.
@@ -968,6 +956,12 @@ my-monorepo/                    ← 여기서 실행: npx claudeos-core init
 
 **"CLAUDEOS_SKIP_TRANSLATION=1 is set but --lang='ko' requires translation" InitError (v2.0.0)** — 셸에 테스트 전용 환경변수 `CLAUDEOS_SKIP_TRANSLATION=1`이 설정된 상태(CI/테스트 설정 leftover 가능성)에서 비영어 `--lang` 선택. 이 환경변수는 Pass 4의 정적 폴백과 gap-fill이 의존하는 번역 경로를 short-circuit. `init`이 언어 선택 시점에 충돌 감지 후 즉시 중단 (Pass 4 중간에 혼란스러운 중첩 에러로 크래시되는 대신). 해결: 실행 전 `unset CLAUDEOS_SKIP_TRANSLATION`, 또는 `npx claudeos-core init --lang en` 사용.
 
+**"⚠️ v2.2.0 upgrade detected" 경고 (v2.2.0)** — 기존 `CLAUDE.md`가 v2.2.0 이전 버전으로 생성된 상태. 기본 resume 모드 재생성은 Rule B idempotency에 따라 기존 파일을 건너뛰므로 v2.2.0의 구조적 개선(8섹션 CLAUDE.md scaffold, `40.infra/*` 파일별 paths, `.env.example` 기반 포트 정확성, Section 8 `공통 규칙 & 메모리 (L4)` 재설계 — 공통 규칙 · L4 메모리 두 하위 섹션 구조, `60.memory/*` 규칙 행, forward-reference 된 `04.doc-writing-guide.md`)이 적용되지 않습니다. 해결: `npx claudeos-core init --force`로 재실행. 생성 파일(`CLAUDE.md`, `.claude/rules/`, `claudeos-core/standard/`, `claudeos-core/skills/`, `claudeos-core/guide/`)은 덮어쓰지만 `claudeos-core/memory/` 콘텐츠(사용자가 축적한 decision-log, failure-patterns 항목 — append-only)는 온전히 보존됩니다. 덮어쓰기 전에 diff를 확인하고 싶다면 `--force` 실행 전에 프로젝트를 git commit 해두세요.
+
+**CLAUDE.md의 port가 `.env.example`과 다름 (v2.2.0)** — v2.2.0의 새 `.env` 파서(`lib/env-parser.js`)는 `.env.example`을 우선 읽고(커밋된 canonical 파일) `.env` 변형을 fallback으로 읽습니다. 인식되는 포트 변수명: `PORT`, `VITE_PORT`, `VITE_DESKTOP_PORT`, `NEXT_PUBLIC_PORT`, `NUXT_PORT`, `DJANGO_PORT` 등. Spring Boot의 경우 `application.yml`의 `server.port`가 `.env`보다 우선합니다(framework-native config 우선). 프로젝트가 비표준 env 변수명을 쓴다면 관례 이름으로 바꾸거나 `PORT_VAR_KEYS` 확장을 issue로 요청해주세요. framework 기본값(Vite 5173, Next.js 3000, Django 8000)은 직접 감지와 `.env` 모두 비어있을 때만 사용됩니다.
+
+**생성된 문서에 값이 `***REDACTED***`로 표시됨 (v2.2.0)** — 의도된 동작입니다. v2.2.0의 `.env` 파서가 `PASSWORD`/`SECRET`/`TOKEN`/`API_KEY`/`CREDENTIAL`/`PRIVATE_KEY` 패턴에 매칭되는 변수 값을 자동으로 `***REDACTED***`로 치환한 후 모든 생성기로 전달합니다. `.env.example`에 실수로 커밋된 민감 정보에 대한 defense-in-depth 보호입니다. `DATABASE_URL`은 stack-detector DB 감지 back-compat 때문에 유지됩니다. 생성된 `CLAUDE.md` 테이블에 `***REDACTED***`가 보인다면 버그이므로 issue로 제보해주세요 — redacted 값이 테이블까지 도달해서는 안 됩니다. 비민감 런타임 설정(port, host, API target, NODE_ENV 등)은 변경 없이 통과합니다.
+
 ---
 
 ## 기여
@@ -977,7 +971,7 @@ my-monorepo/                    ← 여기서 실행: npx claudeos-core init
 - **새 스택 템플릿** — Ruby/Rails, Go (Gin/Fiber/Echo), PHP (Laravel/Symfony), Rust (Axum/Actix), Svelte/SvelteKit, Remix
 - **IDE 연동** — VS Code 확장, IntelliJ 플러그인
 - **CI/CD 템플릿** — GitLab CI, CircleCI, Jenkins 예시 (GitHub Actions는 이미 포함 — `.github/workflows/test.yml` 참조)
-- **테스트 커버리지** — 테스트 스위트 확장 중 (현재 563개 테스트, 29개 테스트 파일; 스캐너, 스택 감지, 도메인 그룹핑, 플랜 파싱, 프롬프트 생성, CLI 셀렉터, 모노레포 감지, Vite SPA 감지, 검증 도구, L4 메모리 스캐폴드, Pass 2 재개 검증, Pass 3 Guards 1/2/3 (H1 센티넬 + H2 BOM-aware 빈 파일 + strict stale-marker unlink), Pass 3 split 모드 배치 하위 분할, Pass 3 partial-marker 재개 (v2.1.0), Pass 4 마커 내용 검증 + stale-marker unlink strictness + scaffoldSkillsManifest gap-fill (v2.1.0), 번역 env-skip 가드 + early fail-fast + CI 워크플로, staged-rules 이동, 언어별 번역 폴백, master plan 제거 regression 스위트 (v2.1.0), memory score/compact 포맷팅 regression (v2.1.0), AI Work Rules 템플릿 구조 커버)
+- **테스트 커버리지** — 테스트 스위트 확장 중 (현재 602개 테스트, 30개 테스트 파일; 스캐너, 스택 감지, 도메인 그룹핑, 플랜 파싱, 프롬프트 생성, CLI 셀렉터, 모노레포 감지, Vite SPA 감지, 검증 도구, L4 메모리 스캐폴드, Pass 2 재개 검증, Pass 3 Guards 1/2/3 (H1 센티넬 + H2 BOM-aware 빈 파일 + strict stale-marker unlink), Pass 3 split 모드 배치 하위 분할, Pass 3 partial-marker 재개 (v2.1.0), Pass 4 마커 내용 검증 + stale-marker unlink strictness + scaffoldSkillsManifest gap-fill (v2.1.0), 번역 env-skip 가드 + early fail-fast + CI 워크플로, staged-rules 이동, 언어별 번역 폴백, master plan 제거 regression 스위트 (v2.1.0), memory score/compact 포맷팅 regression (v2.1.0), AI Work Rules 템플릿 구조, `.env` 파서 port/host/API-target 추출 + 민감 변수 redaction (v2.2.0) 커버)
 
 전체 영역 목록, 코드 스타일, 커밋 컨벤션, 새 스택 템플릿 추가 단계별 가이드는 [`CONTRIBUTING.md`](./CONTRIBUTING.md) 참조.
 

package/README.md

@@ -12,20 +12,6 @@ ClaudeOS-Core reads your codebase, extracts every pattern it finds, and generate
 
 ---
 
-## What's New in v2.1.0
-
-v2.1.0 re-architects Pass 3 to eliminate `Prompt is too long` failures on medium-to-large projects. Previously, a single Pass 3 call had to emit the entire documentation tree at once — dozens of files across `CLAUDE.md`, rules, standards, skills, and guides — and the accumulated output reliably exceeded the context window past ~5 domains. The fix is structural, not a prompt tweak:
-
-- **Pass 3 split mode** (always on) — Pass 3 is broken into sequential `claude -p` calls (`3a` → `3b-core` → `3b-N` → `3c-core` → `3c-N` → `3d-aux`). Each stage starts with a **fresh context window**, so output-accumulation overflow is no longer possible regardless of project size.
-- **Fact sheet between stages** — Stage `3a` reads the Pass 2 analysis once and distills it into a 5–10 KB `pass3a-facts.md`. All later stages reference that fact sheet instead of re-reading the 100–500 KB `pass2-merged.json`, preserving cross-file consistency across fresh contexts.
-- **Batch sub-division** (automatic at ≥16 domains) — Stages 3b/3c are further split into batches of 15 domains each, keeping each stage under ~50 files of output. An 18-domain React 19 + Vite 6 admin frontend completes in **102 minutes with 101 files generated across 8 stages, zero overflow failures** (real production run, 2026-04-20).
-- **Master plan generation removed** — `claudeos-core/plan/*-master.md` files are no longer generated. Master plans were an internal backup not consumed by Claude Code at runtime, and aggregating them in Pass 3d was a primary overflow trigger. Use `git` for backup/restore instead.
-- **Pass 4 gap-fill: `skills/00.shared/MANIFEST.md`** — If Pass 3c omits the skill registry (skill-sparse projects), Pass 4 now auto-creates a stub so `.claude/rules/50.sync/03.skills-sync.md` never points at a dangling file.
-
-A few smaller fixes: `memory --help` now shows the memory subcommand help (previously top-level was shown); `memory score` no longer leaves duplicate `importance` lines; `memory compact` summary markers are proper markdown list items. Full details: [CHANGELOG.md](./CHANGELOG.md).
-
----
-
 ## Why ClaudeOS-Core?
 
 Every other Claude Code tool works like this:
@@ -99,10 +85,20 @@ This difference compounds. 10 tasks/day × 20 minutes saved = **3+ hours/day**.
 | **Vite / React SPA** | `package.json`, `vite.config.*` | 9 categories, 55 sub-items |
 | **Angular** | `package.json`, `angular.json` | 12 categories, 78 sub-items |
 
-Auto-detected: language & version, framework & version (including Vite as SPA framework), ORM (MyBatis, JPA, Exposed, Prisma, TypeORM, SQLAlchemy, etc.), database (PostgreSQL, MySQL, Oracle, MongoDB, SQLite), package manager (Gradle, Maven, npm, yarn, pnpm, pip, poetry), architecture (CQRS, BFF — from module names), multi-module structure (from settings.gradle), monorepo (Turborepo, pnpm-workspace, Lerna, npm/yarn workspaces).
+Auto-detected: language & version, framework & version (including Vite as SPA framework), ORM (MyBatis, JPA, Exposed, Prisma, TypeORM, SQLAlchemy, etc.), database (PostgreSQL, MySQL, Oracle, MongoDB, SQLite), package manager (Gradle, Maven, npm, yarn, pnpm, pip, poetry), architecture (CQRS, BFF — from module names), multi-module structure (from settings.gradle), monorepo (Turborepo, pnpm-workspace, Lerna, npm/yarn workspaces), **runtime configuration from `.env.example`** (v2.2.0 — port/host/API-target across 16+ convention variable names for Vite, Next.js, Nuxt, Angular, Node, Python frameworks).
 
 **You don't specify anything. It's all detected automatically.**
 
+### `.env`-driven runtime configuration (v2.2.0)
+
+v2.2.0 adds `lib/env-parser.js` so generated `CLAUDE.md` reflects what the project actually declares rather than framework defaults.
+
+- **Search order**: `.env.example` (canonical, committed) → `.env.local.example` → `.env.sample` → `.env.template` → `.env` → `.env.local` → `.env.development`. The `.example` variant wins because it is the developer-neutral shape-of-truth, not one contributor's local overrides.
+- **Port variable conventions recognised**: `VITE_PORT` / `VITE_DEV_PORT` / `VITE_DESKTOP_PORT` / `NEXT_PUBLIC_PORT` / `NUXT_PORT` / `NG_PORT` / `APP_PORT` / `SERVER_PORT` / `HTTP_PORT` / `DEV_PORT` / `FLASK_RUN_PORT` / `UVICORN_PORT` / `DJANGO_PORT` / generic `PORT`. Framework-specific names win over the generic `PORT` when both are present.
+- **Host & API target**: `VITE_DEV_HOST` / `VITE_API_TARGET` / `NEXT_PUBLIC_API_URL` / `NUXT_PUBLIC_API_BASE` / `BACKEND_URL` / `PROXY_TARGET` etc.
+- **Precedence**: Spring Boot `application.yml` `server.port` still wins (framework-native config), then `.env`-declared port, then framework default (Vite 5173, Next.js 3000, Django 8000, etc.) as last resort.
+- **Sensitive-variable redaction**: values of variables matching `PASSWORD` / `SECRET` / `TOKEN` / `API_KEY` / `ACCESS_KEY` / `PRIVATE_KEY` / `CREDENTIAL` / `JWT_SECRET` / `CLIENT_SECRET` / `SESSION_SECRET` / `BEARER` / `SALT` patterns are replaced with `***REDACTED***` before reaching any downstream generator. Defense-in-depth against accidentally committed secrets in `.env.example`. `DATABASE_URL` is explicitly whitelisted for stack-detector DB-identification back-compat.
+
 ### Java Domain Detection (5 patterns with fallback)
 
 | Priority | Pattern | Structure | Example |
@@ -378,7 +374,7 @@ cat claudeos-core/generated/pass4-prompt.md \
 
 **Verify:** `claudeos-core/memory/` should contain 4 files (`decision-log.md`, `failure-patterns.md`, `compaction.md`, `auto-rule-update.md`), `.claude/rules/60.memory/` should contain 4 rule files, and `CLAUDE.md` should have a `## Memory (L4)` section appended. Marker: `claudeos-core/generated/pass4-memory.json`.
 
-> **v2.1.0 gap-fill:** Pass 4 also ensures `claudeos-core/skills/00.shared/MANIFEST.md` exists. If Pass 3c omitted it (possible on skill-sparse projects because the stack `pass3.md` templates list `MANIFEST.md` among generation targets without marking it REQUIRED), the gap-fill creates a minimal stub so that `.claude/rules/50.sync/03.skills-sync.md` always has a valid reference target. Idempotent: skips if the file already has real content (>20 chars).
+> **v2.1.0 gap-fill:** Pass 4 also ensures `claudeos-core/skills/00.shared/MANIFEST.md` exists. If Pass 3c omitted it (possible on skill-sparse projects because the stack `pass3.md` templates list `MANIFEST.md` among generation targets without marking it REQUIRED), the gap-fill creates a minimal stub so that `.claude/rules/50.sync/02.skills-sync.md` (v2.2.0 path — the sync rule count was reduced from 3 to 2, so what was `03` is now `02`) always has a valid reference target. Idempotent: skips if the file already has real content (>20 chars).
 
 > **Note:** If `claude -p` fails or `pass4-prompt.md` is missing, the automated pipeline falls back to a static scaffold via `lib/memory-scaffold.js` (with Claude-driven translation when `--lang` is non-English). The static fallback runs only inside `npx claudeos-core init` — manual mode requires Pass 4 to succeed.
 
@@ -488,6 +484,8 @@ The Pass 3 prompt template also includes a **Phase 1 "Read Once, Extract Facts"
 - **Rule D** — Output conciseness: one line (`[WRITE]`/`[SKIP]`) between file writes, no restating the fact table, no echoing file content.
 - **Rule E** — Batch idempotent check: one `Glob` at PHASE 2 start instead of per-target `Read` calls.
 
+In **v2.2.0**, Pass 3 also inlines a deterministic CLAUDE.md scaffold (`pass-prompts/templates/common/claude-md-scaffold.md`) into the prompt. This fixes the 8 top-level section titles and order so the generated `CLAUDE.md` no longer drifts across projects, while still letting per-section content adapt to each project. The stack-detector's new `.env`-parser (`lib/env-parser.js`) supplies `stack.envInfo` to the prompt so port/host/API-target rows match what the project actually declares rather than framework defaults.
+
 **Pass 4** scaffolds the L4 Memory layer: persistent team knowledge files (decision-log, failure-patterns, compaction policy, auto-rule-update) plus the `60.memory/` rules that tell future sessions when and how to read/write those files. The memory layer is what lets Claude Code accumulate lessons across sessions instead of re-discovering them each time. When `--lang` is non-English, the fallback static content is translated via Claude before being written. v2.1.0 adds a gap-fill for `skills/00.shared/MANIFEST.md` in case Pass 3c omitted it.
 
 ---
@@ -497,7 +495,7 @@ The Pass 3 prompt template also includes a **Phase 1 "Read Once, Extract Facts"
 ```
 your-project/
 │
-├── CLAUDE.md                          ← Claude Code entry point
+├── CLAUDE.md                          ← Claude Code entry point (deterministic 8-section structure, v2.2.0)
 │
 ├── .claude/
 │   └── rules/                         ← Glob-triggered rules
@@ -591,24 +589,6 @@ Stage count formula (when batched): `1 (3a) + 1 (3b-core) + N (3b-1..N) + 1 (3c-
 
 Pass 4 (memory scaffolding) adds ~30 seconds to 5 minutes on top depending on whether Claude-driven generation or static fallback runs. For multi-stack projects (e.g., Java + React), backend and frontend domains are counted together. A project with 6 backend + 4 frontend domains = 10 total = Medium tier.
 
-### Real production case: 18-domain admin frontend (2026-04-20)
-
-A React 19 + Vite 6 + TypeScript admin frontend with 18 domains and 6 domain groups completed end-to-end in **102 minutes with 101 files generated**. Stage breakdown:
-
-| Stage | Files | Time | Files/min |
-|---|---|---|---|
-| `3a` (fact extraction) | 1 (`pass3a-facts.md`) | 8m 44s | — |
-| `3b-core` (CLAUDE.md + common) | 24 | 22m 10s | 1.1 |
-| `3b-1` (15 domains) | 30 | 10m 6s | **3.0** |
-| `3b-2` (3 domains) | 6 | 4m 34s | 1.3 |
-| `3c-core` (guides + shared) | 11 | 8m 31s | 1.3 |
-| `3c-1` (15 domains) | 8 | 5m 11s | **1.5** |
-| `3c-2` (3 domains) | 3 | 3m 50s | 0.8 |
-| `3d-aux` (database + mcp) | 3 | 2m 52s | 1.0 |
-| Pass 4 | 12 | 5m 36s | 2.1 |
-
-Throughput is noticeably higher on the batched domain stages (3b-1: 3.0 files/min vs. 3b-core: 1.1 files/min) because fresh-context stages benefit from tight, repeatable per-domain patterns. Verification all-green: `plan-validator`, `sync-checker`, `content-validator`, `pass-json-validator` — zero overflow failures, zero truncation.
-
 ---
 
 ## Verification Tools
@@ -810,8 +790,7 @@ No. It only creates `CLAUDE.md`, `.claude/rules/`, and `claudeos-core/`. Your ex
 It calls `claude -p` several times across 4 passes. In v2.1.0 split mode, Pass 3 alone expands into 4–14+ stages depending on project size (see [Auto-scaling](#auto-scaling-by-project-size)). A typical small project (1–15 domains) uses 8–9 `claude -p` calls total; an 18-domain project uses 11; a 60-domain project uses 15–17. Each stage runs with a fresh context window — the per-call token cost is actually lower than single-call Pass 3 was, because no stage has to hold the entire file tree in one context. When `--lang` is non-English, the static fallback path may invoke a few additional `claude -p` calls for translation; results are cached in `claudeos-core/generated/.i18n-cache-<lang>.json` so subsequent runs reuse them. This is within normal Claude Code usage.
 
 **Q: What is Pass 3 split mode and why was it added in v2.1.0?**
-Before v2.1.0, Pass 3 made a single `claude -p` call that had to emit the entire generated file tree (`CLAUDE.md`, standards, rules, skills, guides — typically 30–60 files) in one response. This worked on small projects but reliably hit `Prompt is too long` output-accumulation failures at ~5 domains. The failure was not predictable from input size — it depended on how verbose each generated file happened to be, and could strike the same project intermittently. Split mode sidesteps the problem structurally: Pass 3 is broken into sequential stages (`3a` → `3b-core` → `3b-N` → `3c-core` → `3c-N` → `3d-aux`), each a separate `claude -p` call with a fresh context window. Cross-stage consistency is preserved by `pass3a-facts.md`, a 5–10 KB distilled fact sheet that every later stage references instead of re-reading `pass2-merged.json`. The `pass3-complete.json` marker carries a `groupsCompleted` array so a crash during `3c-2` resumes from `3c-2` (not from `3a`), avoiding double token cost. Empirically verified up to 18 domains × 101 files × 102 minutes with zero overflow — see [Auto-scaling](#auto-scaling-by-project-size) for the real production breakdown.
-
+Before v2.1.0, Pass 3 made a single `claude -p` call that had to emit the entire generated file tree (`CLAUDE.md`, standards, rules, skills, guides — typically 30–60 files) in one response. This worked on small projects but reliably hit `Prompt is too long` output-accumulation failures at ~5 domains. The failure was not predictable from input size — it depended on how verbose each generated file happened to be, and could strike the same project intermittently. Split mode sidesteps the problem structurally: Pass 3 is broken into sequential stages (`3a` → `3b-core` → `3b-N` → `3c-core` → `3c-N` → `3d-aux`), each a separate `claude -p` call with a fresh context window. Cross-stage consistency is preserved by `pass3a-facts.md`, a 5–10 KB distilled fact sheet that every later stage references instead of re-reading `pass2-merged.json`. The `pass3-complete.json` marker carries a `groupsCompleted` array so a crash during `3c-2` resumes from `3c-2` (not from `3a`), avoiding double token cost.
 **Q: Should I commit the generated files to Git?**
 Yes, recommended. Your team can share the same Claude Code standards. Consider adding `claudeos-core/generated/` to `.gitignore` (analysis JSON is regeneratable).
 
@@ -866,7 +845,14 @@ Nothing required — v2.1.0 tools ignore `plan/` when it's absent or empty, and
 
 ```
 pass-prompts/templates/
-├── common/                  # Shared header/footer + pass4 + staging-override
+├── common/                  # Shared header/footer + pass4 + staging-override + CLAUDE.md scaffold (v2.2.0)
+│   ├── header.md             # Role + output-format directive (all passes)
+│   ├── pass3-footer.md       # Post-Pass-3 health-check instruction + 5 CRITICAL guardrail blocks (v2.2.0)
+│   ├── pass3-phase1.md       # "Read Once, Extract Facts" block with Rules A-E (v2.1.0)
+│   ├── pass4.md              # Memory scaffolding prompt (v2.0.0)
+│   ├── staging-override.md   # Redirects .claude/rules/** writes to .staged-rules/** (v2.0.0)
+│   ├── claude-md-scaffold.md # Deterministic 8-section CLAUDE.md template (v2.2.0)
+│   └── lang-instructions.json # Per-language output directives (10 languages)
 ├── java-spring/             # Java / Spring Boot
 ├── kotlin-spring/           # Kotlin / Spring Boot (CQRS, BFF, multi-module)
 ├── node-express/            # Node.js / Express
@@ -883,6 +869,8 @@ pass-prompts/templates/
 
 `plan-installer` auto-detects your stack(s), then assembles type-specific prompts. NestJS, Vue/Nuxt, Vite SPA, and Flask each use dedicated templates with framework-specific analysis categories (e.g., `@Module`/`@Injectable`/Guards for NestJS; `<script setup>`/Pinia/useFetch for Vue; client-side routing/`VITE_` env for Vite; Blueprint/`app.factory`/Flask-SQLAlchemy for Flask). For multi-stack projects, separate `pass1-backend-prompt.md` and `pass1-frontend-prompt.md` are generated, while `pass3-prompt.md` combines both stacks' generation targets. In v2.1.0, the Pass 3 template is prepended with `common/pass3-phase1.md` (the "Read Once, Extract Facts" block with Rules A–E) before being sliced per split-mode stage. Pass 4 uses the shared `common/pass4.md` template (memory scaffolding) regardless of stack.
 
+**In v2.2.0**, the Pass 3 prompt also inlines `common/claude-md-scaffold.md` (the deterministic 8-section CLAUDE.md template) between the phase1 block and the stack-specific body — this fixes the section structure so generated CLAUDE.md files don't drift across projects while letting content adapt per-project. Templates are written **English-first**; the language injection from `lang-instructions.json` tells the LLM to translate section titles and prose at emit time into the target output language.
+
 ---
 
 ## Monorepo Support
@@ -951,10 +939,10 @@ my-monorepo/                    ← Run here: npx claudeos-core init
 
 **"Pass 3 produced CLAUDE.md and rules but N/9 guide files are missing or empty" (v2.0.0)** — Guard 3 (H2) fired: Claude truncated mid-response after writing CLAUDE.md + rules but before finishing (or starting) the `claudeos-core/guide/` section (9 files expected). Also fires on a BOM-only or whitespace-only file (heading was written but the body was truncated). Without this guard the completion marker would still be written, leaving `guide/` permanently empty on subsequent runs. The marker is NOT written here, so the next `init` run retries Pass 3 from the same Pass 2 results. If it keeps repeating, re-run with `npx claudeos-core init --force` to regenerate from scratch.
 
-**"Pass 3 finished but the following required output(s) are missing or empty" (v2.0.0, updated v2.1.0)** — Guard 3 (H1) fired: Claude truncated AFTER `claudeos-core/guide/` but before (or during) `claudeos-core/standard/` or `claudeos-core/skills/`. Requirements: (a) `standard/00.core/01.project-overview.md` exists and is non-empty (sentinel written by every stack's Pass 3 prompt), (b) `skills/` has ≥1 non-empty `.md`. `database/` and `mcp-guide/` are intentionally excluded (some stacks legitimately produce zero files). `plan/` is no longer checked as of v2.1.0 (master plans were removed). Same recovery path as Guard 3 (H2): re-run `init`, or `--force` if it persists.
-
-**"Pass 3 split stage crashed partway through (v2.1.0)"** — When one of the split stages (e.g., `3b-1`, `3c-2`) fails mid-run, the stage-level marker is NOT written, but completed stages ARE recorded in `pass3-complete.json.groupsCompleted`. The next `init` run reads this array and resumes from the first uncompleted stage, skipping all earlier completed work. You don't need to do anything manually — just re-run `npx claudeos-core init`. If resume keeps failing at the same stage, inspect `claudeos-core/generated/pass3-prompt.md` for malformed content, then try `--force` for a full restart. The `pass3-complete.json` shape (`mode: "split"`, `groupsCompleted: [...]`) is stable; a missing or malformed marker causes the full Pass 3 to re-run from `3a`.
-
+**"Pass 3 finished but the following required output(s) are missing or empty" (v2.0.0, updated v2.1.0)** — Guard 3 (H1) fired: Claude truncated AFTER `claudeos-core/guide/` but before (or during) `claudeos-core/standard/` or `claudeos-core/skills/`. Requirements: (a) `standard/00.core/01.project-overview.md` exists and is non-empty (sentinel written by every stack's Pass 3 prompt), (b) `skills/` has ≥1 non-empty `.md`. `database/` and `mcp-guide/` are intentionally excluded (some stacks legitimately produce zero files). `plan/` is no longer checked as of v2.1.0 (master plans were removed). Same recovery path as Guard 3 (H2): re-run `init`, or `--force` if it persists.
+
+**"Pass 3 split stage crashed partway through (v2.1.0)"** — When one of the split stages (e.g., `3b-1`, `3c-2`) fails mid-run, the stage-level marker is NOT written, but completed stages ARE recorded in `pass3-complete.json.groupsCompleted`. The next `init` run reads this array and resumes from the first uncompleted stage, skipping all earlier completed work. You don't need to do anything manually — just re-run `npx claudeos-core init`. If resume keeps failing at the same stage, inspect `claudeos-core/generated/pass3-prompt.md` for malformed content, then try `--force` for a full restart. The `pass3-complete.json` shape (`mode: "split"`, `groupsCompleted: [...]`) is stable; a missing or malformed marker causes the full Pass 3 to re-run from `3a`.
+
 **"Pass 3 stale marker (shape mismatch) — treating as incomplete" (v2.1.0)** — A `pass3-complete.json` from a pre-v2.1.0 single-call run is being interpreted under the new split-mode rules. The shape check looks for `mode: "split"` and a `groupsCompleted` array; if either is missing, the marker is treated as partial and Pass 3 re-runs in split mode. If you upgraded from v2.0.x, this is expected once — the next run will write the correct marker shape. No action needed.
 
 **"pass2-merged.json exists but is malformed or incomplete (<5 top-level keys), re-running" (v2.0.0)** — Info log, not an error. On resume, `init` now parses and validates `pass2-merged.json` (≥5 top-level keys required, mirroring `pass-json-validator`'s `INSUFFICIENT_KEYS` threshold). Skeleton `{}` or malformed JSON from a prior crashed run is automatically deleted and Pass 2 re-runs. No manual action needed — the pipeline self-heals. If it keeps recurring, inspect `claudeos-core/generated/pass2-prompt.md` and retry with `--force`.
@@ -969,6 +957,12 @@ my-monorepo/                    ← Run here: npx claudeos-core init
 
 **"CLAUDEOS_SKIP_TRANSLATION=1 is set but --lang='ko' requires translation" InitError (v2.0.0)** — You have the test-only env var `CLAUDEOS_SKIP_TRANSLATION=1` set in your shell (likely a leftover from CI/test setup) AND picked a non-English `--lang`. This env var short-circuits the translation path that Pass 4's static-fallback and gap-fill depend on for non-English output. `init` detects the conflict at language-selection time and aborts immediately (rather than crashing mid-Pass-4 with a confusing nested error). Fix: either `unset CLAUDEOS_SKIP_TRANSLATION` before running, or use `npx claudeos-core init --lang en`.
 
+**"⚠️ v2.2.0 upgrade detected" warning (v2.2.0)** — Your existing `CLAUDE.md` was generated with a pre-v2.2.0 version. The default resume-mode regeneration will skip existing files under Rule B idempotency, so v2.2.0's structural improvements (8-section CLAUDE.md scaffold, per-file `40.infra/*` paths, `.env.example`-based port accuracy, Section 8 redesign into `Common Rules & Memory (L4)` with two sub-sections, `60.memory/*` rule row, forward-referenced `04.doc-writing-guide.md`) would NOT be applied. Fix: re-run with `npx claudeos-core init --force` — this overwrites generated files (`CLAUDE.md`, `.claude/rules/`, `claudeos-core/standard/`, `claudeos-core/skills/`, `claudeos-core/guide/`) while preserving `claudeos-core/memory/` content (decision-log, failure-patterns entries you've accumulated are append-only and kept intact). Commit your project first if you want to diff the overwrites before accepting them.
+
+**Port in CLAUDE.md differs from `.env.example` (v2.2.0)** — The stack-detector's new `.env`-parser (`lib/env-parser.js`) reads `.env.example` first (canonical, committed), then `.env` variants as fallback. Port variables it recognizes include `PORT`, `VITE_PORT`, `VITE_DESKTOP_PORT`, `NEXT_PUBLIC_PORT`, `NUXT_PORT`, `DJANGO_PORT`, etc. For Spring Boot, `application.yml`'s `server.port` still takes precedence over `.env` (framework-native config wins). If your project uses an unusual env var name, either rename it to a recognized convention or raise an issue for us to extend `PORT_VAR_KEYS`. Framework defaults (Vite 5173, Next.js 3000, Django 8000) are used only when both direct detection and `.env` are silent.
+
+**Secret values redacted as `***REDACTED***` in generated docs (v2.2.0)** — Expected behavior. The v2.2.0 `.env`-parser automatically redacts values of variables matching `PASSWORD`/`SECRET`/`TOKEN`/`API_KEY`/`CREDENTIAL`/`PRIVATE_KEY` patterns before they reach any generator. This is defense-in-depth against accidentally committed secrets in `.env.example`. `DATABASE_URL` is kept as-is for stack-detector DB identification back-compat. If you see `***REDACTED***` somewhere in the generated `CLAUDE.md`, that's a bug — redacted values should never reach the table; please file an issue. Non-sensitive runtime config (port, host, API target, NODE_ENV, etc.) pass through unchanged.
+
 ---
 
 ## Contributing
@@ -978,7 +972,7 @@ Contributions are welcome! Areas where help is most needed:
 - **New stack templates** — Ruby/Rails, Go (Gin/Fiber/Echo), PHP (Laravel/Symfony), Rust (Axum/Actix), Svelte/SvelteKit, Remix
 - **IDE integration** — VS Code extension, IntelliJ plugin
 - **CI/CD templates** — GitLab CI, CircleCI, Jenkins examples (GitHub Actions already shipped — see `.github/workflows/test.yml`)
-- **Test coverage** — Expanding test suite (currently 563 tests across 29 test files covering scanners, stack detection, domain grouping, plan parsing, prompt generation, CLI selectors, monorepo detection, Vite SPA detection, verification tools, L4 memory scaffold, Pass 2 resume validation, Pass 3 Guards 1/2/3 (H1 sentinel + H2 BOM-aware empty-file + strict stale-marker unlink), Pass 3 split-mode batch subdivision, Pass 3 partial-marker resume (v2.1.0), Pass 4 marker content validation + stale-marker unlink strictness + scaffoldSkillsManifest gap-fill (v2.1.0), translation env-skip guard + early fail-fast + CI workflow, staged-rules move, lang-aware translation fallback, master plan removal regression suite (v2.1.0), memory score/compact formatting regression (v2.1.0), and AI Work Rules template structure)
+- **Test coverage** — Expanding test suite (currently 602 tests across 30 test files covering scanners, stack detection, domain grouping, plan parsing, prompt generation, CLI selectors, monorepo detection, Vite SPA detection, verification tools, L4 memory scaffold, Pass 2 resume validation, Pass 3 Guards 1/2/3 (H1 sentinel + H2 BOM-aware empty-file + strict stale-marker unlink), Pass 3 split-mode batch subdivision, Pass 3 partial-marker resume (v2.1.0), Pass 4 marker content validation + stale-marker unlink strictness + scaffoldSkillsManifest gap-fill (v2.1.0), translation env-skip guard + early fail-fast + CI workflow, staged-rules move, lang-aware translation fallback, master plan removal regression suite (v2.1.0), memory score/compact formatting regression (v2.1.0), AI Work Rules template structure, and `.env`-parser port/host/API-target extraction + sensitive-variable redaction (v2.2.0))
 
 See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the full list of areas, code style, commit convention, and the step-by-step guide for adding a new stack template.