claudeos-core 2.1.1 → 2.2.0

package/README.md

@@ -85,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 |
@@ -364,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.
 
@@ -474,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.
 
 ---
@@ -483,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
@@ -833,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
@@ -850,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
@@ -936,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
@@ -945,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.
 

package/README.ru.md

@@ -85,10 +85,20 @@ ClaudeOS-Core создаёт документацию, которая знает
 | **Vite / React SPA** | `package.json`, `vite.config.*` | 9 категорий, 55 подпунктов |
 | **Angular** | `package.json`, `angular.json` | 12 категорий, 78 подпунктов |
 
-Автоматически определяется: язык и версия, фреймворк и версия (включая Vite как SPA-фреймворк), 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).
+Автоматически определяется: язык и версия, фреймворк и версия (включая Vite как SPA-фреймворк), 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), **конфигурация runtime из `.env.example`** (v2.2.0 — извлечение port/host/API-target из 16+ соглашений имён переменных во фреймворках Vite · Next.js · Nuxt · Angular · Node · Python).
 
 **Вам не нужно ничего указывать. Всё определяется автоматически.**
 
+### Конфигурация runtime на основе `.env` (v2.2.0)
+
+v2.2.0 добавляет `lib/env-parser.js`, чтобы генерируемый `CLAUDE.md` отражал то, что проект действительно декларирует, а не дефолты фреймворка.
+
+- **Порядок поиска**: `.env.example` (канонический, закоммиченный) → `.env.local.example` → `.env.sample` → `.env.template` → `.env` → `.env.local` → `.env.development`. Вариант `.example` побеждает, потому что он является developer-neutral shape-of-truth, а не локальными переопределениями одного контрибьютора.
+- **Распознаваемые соглашения имён port-переменных**: `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-специфичные имена побеждают 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 default (Vite 5173, Next.js 3000, Django 8000 и т.д.) в качестве последнего средства.
+- **Редактирование чувствительных переменных**: значения переменных, соответствующих паттернам `PASSWORD` / `SECRET` / `TOKEN` / `API_KEY` / `ACCESS_KEY` / `PRIVATE_KEY` / `CREDENTIAL` / `JWT_SECRET` / `CLIENT_SECRET` / `SESSION_SECRET` / `BEARER` / `SALT`, заменяются на `***REDACTED***` до того, как достигнут любого downstream-генератора. Defense-in-depth против случайно закоммиченных секретов в `.env.example`. `DATABASE_URL` явно внесён в whitelist для back-compat идентификации БД в stack-detector.
+
 ### Обнаружение Java-доменов (5 паттернов с фолбэком)
 
 | Приоритет | Паттерн | Структура | Пример |
@@ -364,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`.
 
-> **Gap-fill в v2.1.0:** Pass 4 также гарантирует существование `claudeos-core/skills/00.shared/MANIFEST.md`. Если Pass 3c его пропустил (возможно на проектах с малым количеством skills, потому что шаблоны `pass3.md` стеков перечисляют `MANIFEST.md` среди целей генерации без отметки REQUIRED), gap-fill создаёт минимальную заглушку, чтобы `.claude/rules/50.sync/03.skills-sync.md` всегда имел валидную целевую ссылку. Идемпотентно: пропускается, если файл уже имеет реальное содержимое (>20 символов).
+> **Gap-fill в v2.1.0:** Pass 4 также гарантирует существование `claudeos-core/skills/00.shared/MANIFEST.md`. Если Pass 3c его пропустил (возможно на проектах с малым количеством skills, потому что шаблоны `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` (с переводом через Claude, когда `--lang` не английский). Статический фолбэк запускается только внутри `npx claudeos-core init` — ручной режим требует успеха Pass 4.
 
@@ -474,6 +484,10 @@ npx claudeos-core init
 - **Rule D** — Сжатость вывода: одна строка (`[WRITE]`/`[SKIP]`) между записями файлов, без повторения fact table, без эха содержимого файлов.
 - **Rule E** — Батчевая идемпотентная проверка: один `Glob` в начале PHASE 2 вместо per-target `Read` вызовов.
 
+В **v2.2.0** Pass 3 также встраивает в промпт детерминированный CLAUDE.md scaffold (`pass-prompts/templates/common/claude-md-scaffold.md`). Это фиксирует заголовки и порядок 8 секций верхнего уровня, так что сгенерированный `CLAUDE.md` больше не дрейфует между проектами, при этом содержимое каждой секции по-прежнему адаптируется к проекту. Новый `.env` parser stack-detector-а (`lib/env-parser.js`) поставляет `stack.envInfo` в промпт, чтобы строки port/host/API target соответствовали тому, что проект фактически объявляет, а не framework-дефолтам.
+
+В **v2.2.0** Pass 3 также встраивает в промпт детерминированный CLAUDE.md scaffold (`pass-prompts/templates/common/claude-md-scaffold.md`). Это фиксирует заголовки и порядок 8 секций верхнего уровня, так что сгенерированный `CLAUDE.md` больше не дрейфует между проектами, при этом содержимое каждой секции по-прежнему адаптируется к проекту. Новый `.env` parser stack-detector-а (`lib/env-parser.js`) поставляет `stack.envInfo` в промпт, чтобы строки port/host/API target соответствовали тому, что проект фактически объявляет, а не framework-дефолтам.
+
 **Pass 4** создаёт каркас слоя L4 Memory: файлы персистентного командного знания (decision-log, failure-patterns, политика компакции, auto-rule-update) плюс правила `60.memory/`, которые указывают будущим сессиям, когда и как читать/записывать эти файлы. Слой памяти — это то, что позволяет Claude Code накапливать уроки между сессиями, а не открывать их заново каждый раз. Когда `--lang` не английский, статический контент фолбэка переводится через Claude перед записью. v2.1.0 добавляет gap-fill для `skills/00.shared/MANIFEST.md` на случай, если Pass 3c его пропустил.
 
 ---
@@ -483,7 +497,7 @@ npx claudeos-core init
 ```
 your-project/
 │
-├── CLAUDE.md                          ← Точка входа Claude Code
+├── CLAUDE.md                          ← Точка входа Claude Code (детерминированная 8-секционная структура, v2.2.0)
 │
 ├── .claude/
 │   └── rules/                         ← Правила, срабатывающие по glob
@@ -833,7 +847,14 @@ v2.0.0 добавил три Guard'а Pass 3 против silent-failure (Guard
 
 ```
 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       # Инструкция health-check после Pass 3 + 5 CRITICAL блоков guardrail (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 # Детерминированный шаблон CLAUDE.md из 8 секций (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
@@ -850,6 +871,8 @@ pass-prompts/templates/
 
 `plan-installer` автоматически определяет ваш стек/стеки, затем собирает специфичные по типу промпты. NestJS, Vue/Nuxt, Vite SPA и Flask каждый используют выделенные шаблоны с категориями анализа, специфичными для фреймворка (например, `@Module`/`@Injectable`/Guards для NestJS; `<script setup>`/Pinia/useFetch для Vue; client-side routing/`VITE_` env для Vite; Blueprint/`app.factory`/Flask-SQLAlchemy для Flask). Для мульти-стек проектов генерируются отдельные `pass1-backend-prompt.md` и `pass1-frontend-prompt.md`, а `pass3-prompt.md` комбинирует цели генерации обоих стеков. В v2.1.0 шаблон Pass 3 дополняется `common/pass3-phase1.md` (блок «Read Once, Extract Facts» с Rules A–E) перед тем, как нарезаться по стадиям split-режима. Pass 4 использует общий шаблон `common/pass4.md` (memory scaffolding) независимо от стека.
 
+**В v2.2.0**, промпт Pass 3 также встраивает inline `common/claude-md-scaffold.md` (детерминированный шаблон CLAUDE.md из 8 секций) между блоком phase1 и stack-specific телом — это фиксирует структуру секций, так что генерируемые CLAUDE.md не дрейфуют между проектами, а содержимое всё ещё адаптируется к каждому проекту. Шаблоны написаны **English-first**; инъекция языка из `lang-instructions.json` указывает LLM переводить заголовки секций и прозу на целевой выходной язык во время emit.
+
 ---
 
 ## Поддержка монорепо
@@ -936,6 +959,12 @@ my-monorepo/                    ← Запускайте здесь: npx claudeo
 
 **«CLAUDEOS_SKIP_TRANSLATION=1 is set but --lang='ko' requires translation» InitError (v2.0.0)** — У вас установлена test-only env-переменная `CLAUDEOS_SKIP_TRANSLATION=1` в shell (вероятно, остаток от CI/test-настройки) И выбран неанглийский `--lang`. Эта env-переменная блокирует путь перевода, от которого зависят статический фолбэк 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` был сгенерирован pre-v2.2.0 версией. Regeneration в default resume mode пропустит existing файлы согласно Rule B idempotency, поэтому структурные улучшения v2.2.0 (8-секционный CLAUDE.md scaffold, per-file paths в `40.infra/*`, точность порта на основе `.env.example`, редизайн Section 8 `Common Rules & Memory (L4)` (редизайн с двумя под-секциями: Common Rules · L4 Memory), строка правил `60.memory/*`, forward-referenced `04.doc-writing-guide.md`) НЕ будут применены. Fix: перезапустите с `npx claudeos-core init --force`. Это перезапишет generated файлы (`CLAUDE.md`, `.claude/rules/`, `claudeos-core/standard/`, `claudeos-core/skills/`, `claudeos-core/guide/`), сохраняя при этом `claudeos-core/memory/` (накопленные decision-log, failure-patterns — append-only). Сделайте commit проекта перед `--force`, если хотите сделать diff перезаписей.
+
+**Port в CLAUDE.md отличается от `.env.example` (v2.2.0)** — Новый `.env` parser stack-detector-а (`lib/env-parser.js`) сначала читает `.env.example` (canonical, committed), затем варианты `.env` как fallback. Распознаваемые port-переменные: `PORT`, `VITE_PORT`, `VITE_DESKTOP_PORT`, `NEXT_PUBLIC_PORT`, `NUXT_PORT`, `DJANGO_PORT` и т.д. Для Spring Boot `server.port` из `application.yml` по-прежнему имеет приоритет над `.env` (framework-native config выигрывает). Если проект использует нестандартное имя env-переменной, переименуйте её в распознаваемое соглашение или создайте issue для расширения `PORT_VAR_KEYS`. Framework-дефолты (Vite 5173, Next.js 3000, Django 8000) используются только когда и direct detection, и `.env` молчат.
+
+**Secret-значения redacted как `***REDACTED***` в generated docs (v2.2.0)** — Ожидаемое поведение. `.env` parser v2.2.0 автоматически redact-ит значения переменных, соответствующих паттернам `PASSWORD`/`SECRET`/`TOKEN`/`API_KEY`/`CREDENTIAL`/`PRIVATE_KEY`, до того как они достигнут любого генератора. Это defense-in-depth против случайно закоммиченных секретов в `.env.example`. `DATABASE_URL` сохраняется as-is для back-compat идентификации DB в stack-detector. Если вы видите `***REDACTED***` где-либо в generated `CLAUDE.md`, это баг — redacted-значения не должны попадать в таблицу; пожалуйста, создайте issue. Non-sensitive runtime config (port, host, API target, NODE_ENV и т.д.) проходит без изменений.
+
 ---
 
 ## Контрибьюции
@@ -945,7 +974,7 @@ my-monorepo/                    ← Запускайте здесь: npx claudeo
 - **Новые шаблоны стеков** — 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 memory scaffold, валидацию resume Pass 2, Pass 3 Guards 1/2/3 (H1 sentinel + H2 BOM-aware empty-file + строгий stale-marker unlink), Pass 3 split-mode разбиение на батчи, Pass 3 partial-marker resume (v2.1.0), валидацию содержимого маркера Pass 4 + строгость stale-marker unlink + scaffoldSkillsManifest gap-fill (v2.1.0), translation env-skip guard + early fail-fast + CI workflow, перемещение staged-rules, lang-aware translation fallback, regression-сюиту удаления master plan (v2.1.0), регрессию форматирования memory score/compact (v2.1.0) и структуру шаблона AI Work Rules)
+- **Покрытие тестами** — расширение тестового пакета (в настоящее время 602 теста в 30 тестовых файлах, покрывающих сканеры, определение стека, группировку доменов, парсинг планов, генерацию промптов, CLI-селекторы, определение монорепо, определение Vite SPA, инструменты верификации, L4 memory scaffold, валидацию resume Pass 2, Pass 3 Guards 1/2/3 (H1 sentinel + H2 BOM-aware empty-file + строгий stale-marker unlink), Pass 3 split-mode разбиение на батчи, Pass 3 partial-marker resume (v2.1.0), валидацию содержимого маркера Pass 4 + строгость stale-marker unlink + scaffoldSkillsManifest gap-fill (v2.1.0), translation env-skip guard + early fail-fast + CI workflow, перемещение staged-rules, lang-aware translation fallback, regression-сюиту удаления master plan (v2.1.0), регрессию форматирования memory score/compact (v2.1.0) структуру шаблона AI Work Rules и извлечение port/host/API-target парсером `.env` + redaction чувствительных переменных (v2.2.0))
 
 См. [`CONTRIBUTING.md`](./CONTRIBUTING.md) для полного списка областей, стиля кода, конвенции коммитов и пошагового руководства по добавлению нового шаблона стека.
 

package/README.vi.md

@@ -85,10 +85,20 @@ Sự khác biệt này được tích lũy. 10 task/ngày × 20 phút tiết ki
 | **Vite / React SPA** | `package.json`, `vite.config.*` | 9 danh mục, 55 mục con |
 | **Angular** | `package.json`, `angular.json` | 12 danh mục, 78 mục con |
 
-Tự động phát hiện: ngôn ngữ & phiên bản, framework & phiên bản (bao gồm Vite như SPA framework), ORM (MyBatis, JPA, Exposed, Prisma, TypeORM, SQLAlchemy, v.v.), database (PostgreSQL, MySQL, Oracle, MongoDB, SQLite), package manager (Gradle, Maven, npm, yarn, pnpm, pip, poetry), kiến trúc (CQRS, BFF — phát hiện từ tên module), cấu trúc multi-module (từ settings.gradle), monorepo (Turborepo, pnpm-workspace, Lerna, npm/yarn workspaces).
+Tự động phát hiện: ngôn ngữ & phiên bản, framework & phiên bản (bao gồm Vite như SPA framework), ORM (MyBatis, JPA, Exposed, Prisma, TypeORM, SQLAlchemy, v.v.), database (PostgreSQL, MySQL, Oracle, MongoDB, SQLite), package manager (Gradle, Maven, npm, yarn, pnpm, pip, poetry), kiến trúc (CQRS, BFF — phát hiện từ tên module), cấu trúc multi-module (từ settings.gradle), monorepo (Turborepo, pnpm-workspace, Lerna, npm/yarn workspaces), **cấu hình runtime từ `.env.example`** (v2.2.0 — trích xuất port/host/API-target từ 16+ tên biến quy ước trên các framework Vite · Next.js · Nuxt · Angular · Node · Python).
 
 **Bạn không cần chỉ định gì cả. Tất cả được phát hiện tự động.**
 
+### Cấu hình runtime từ `.env` (v2.2.0)
+
+v2.2.0 bổ sung `lib/env-parser.js` để `CLAUDE.md` được sinh ra phản ánh những gì project thực sự khai báo, thay vì giá trị mặc định của framework.
+
+- **Thứ tự tìm kiếm**: `.env.example` (canonical, đã commit) → `.env.local.example` → `.env.sample` → `.env.template` → `.env` → `.env.local` → `.env.development`. Biến thể `.example` thắng vì đó là shape-of-truth trung lập của developer, không phải override local của một contributor cụ thể.
+- **Các quy ước biến port được nhận diện**: `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` tổng quát. Tên đặc thù framework thắng `PORT` tổng quát khi cả hai cùng hiện diện.
+- **Host & API target**: `VITE_DEV_HOST` / `VITE_API_TARGET` / `NEXT_PUBLIC_API_URL` / `NUXT_PUBLIC_API_BASE` / `BACKEND_URL` / `PROXY_TARGET` v.v.
+- **Độ ưu tiên**: Spring Boot `application.yml` `server.port` vẫn thắng (config framework-native), rồi đến port khai báo trong `.env`, cuối cùng mới fallback về default của framework (Vite 5173, Next.js 3000, Django 8000, v.v.).
+- **Redact biến nhạy cảm**: giá trị của các biến khớp pattern `PASSWORD` / `SECRET` / `TOKEN` / `API_KEY` / `ACCESS_KEY` / `PRIVATE_KEY` / `CREDENTIAL` / `JWT_SECRET` / `CLIENT_SECRET` / `SESSION_SECRET` / `BEARER` / `SALT` được thay bằng `***REDACTED***` trước khi tới bất kỳ generator downstream nào. Defense-in-depth chống secret bị commit nhầm vào `.env.example`. `DATABASE_URL` được whitelist tường minh để giữ back-compat cho việc nhận diện DB của stack-detector.
+
 ### Phát Hiện Domain Java (5 pattern với fallback)
 
 | Ưu tiên | Pattern | Cấu trúc | Ví dụ |
@@ -364,7 +374,7 @@ cat claudeos-core/generated/pass4-prompt.md \
 
 **Xác minh:** `claudeos-core/memory/` phải chứa 4 file (`decision-log.md`, `failure-patterns.md`, `compaction.md`, `auto-rule-update.md`), `.claude/rules/60.memory/` phải chứa 4 file rule, và `CLAUDE.md` giờ phải có mục `## Memory (L4)` được append. Marker: `claudeos-core/generated/pass4-memory.json`.
 
-> **Gap-fill v2.1.0:** Pass 4 cũng đảm bảo `claudeos-core/skills/00.shared/MANIFEST.md` tồn tại. Nếu Pass 3c bỏ sót (có thể xảy ra ở các dự án ít skill vì template stack `pass3.md` liệt kê `MANIFEST.md` là mục tiêu tạo mà không đánh dấu REQUIRED), gap-fill tạo stub tối thiểu để `.claude/rules/50.sync/03.skills-sync.md` luôn có tham chiếu hợp lệ. Idempotent: bỏ qua nếu file đã có nội dung thực (>20 ký tự).
+> **Gap-fill v2.1.0:** Pass 4 cũng đảm bảo `claudeos-core/skills/00.shared/MANIFEST.md` tồn tại. Nếu Pass 3c bỏ sót (có thể xảy ra ở các dự án ít skill vì template stack `pass3.md` liệt kê `MANIFEST.md` là mục tiêu tạo mà không đánh dấu REQUIRED), gap-fill tạo stub tối thiểu để `.claude/rules/50.sync/02.skills-sync.md` (đường dẫn v2.2.0 — số lượng rule sync giảm từ 3 xuống 2, `03` trở thành `02`) luôn có tham chiếu hợp lệ. Idempotent: bỏ qua nếu file đã có nội dung thực (>20 ký tự).
 
 > **Lưu ý:** Nếu `claude -p` lỗi hoặc thiếu `pass4-prompt.md`, pipeline tự động sẽ fallback về scaffold tĩnh qua `lib/memory-scaffold.js` (có dịch qua Claude khi `--lang` khác tiếng Anh). Fallback tĩnh chỉ chạy bên trong `npx claudeos-core init` — chế độ thủ công yêu cầu Pass 4 thành công.
 
@@ -474,6 +484,8 @@ Template prompt Pass 3 cũng bao gồm **block Phase 1 "Read Once, Extract Facts
 - **Rule D** — Output cô đọng: một dòng (`[WRITE]`/`[SKIP]`) giữa các lần ghi file, không nhắc lại bảng fact, không echo nội dung file.
 - **Rule E** — Kiểm tra idempotent theo batch: một `Glob` lúc bắt đầu PHASE 2 thay vì gọi `Read` từng target.
 
+Trong **v2.2.0**, Pass 3 cũng inline một CLAUDE.md scaffold deterministic (`pass-prompts/templates/common/claude-md-scaffold.md`) vào prompt. Điều này cố định tiêu đề và thứ tự của 8 section cấp cao nhất nên `CLAUDE.md` được sinh ra không còn drift giữa các project, trong khi nội dung mỗi section vẫn thích ứng với từng project. Parser `.env` mới của stack-detector (`lib/env-parser.js`) cung cấp `stack.envInfo` cho prompt để các hàng port/host/API target khớp với giá trị project thực sự khai báo thay vì framework default.
+
 **Pass 4** scaffold L4 Memory layer: các file kiến thức team bền vững (decision-log, failure-patterns, compaction policy, auto-rule-update) cộng với rules `60.memory/` chỉ dẫn các session tương lai khi nào và cách đọc/ghi các file đó. Memory layer là thứ giúp Claude Code tích lũy bài học qua các session thay vì phải khám phá lại mỗi lần. Khi `--lang` khác tiếng Anh, nội dung fallback tĩnh được dịch qua Claude trước khi ghi. v2.1.0 thêm gap-fill cho `skills/00.shared/MANIFEST.md` phòng trường hợp Pass 3c bỏ sót.
 
 ---
@@ -483,7 +495,7 @@ Template prompt Pass 3 cũng bao gồm **block Phase 1 "Read Once, Extract Facts
 ```
 your-project/
 │
-├── CLAUDE.md                          ← Entry point của Claude Code
+├── CLAUDE.md                          ← Entry point của Claude Code (cấu trúc 8-phần deterministic, v2.2.0)
 │
 ├── .claude/
 │   └── rules/                         ← Rules kích hoạt theo glob
@@ -833,7 +845,14 @@ Không cần gì cả — công cụ v2.1.0 bỏ qua `plan/` khi nó vắng mặ
 
 ```
 pass-prompts/templates/
-├── common/                  # header/footer dùng chung + pass4 + staging-override
+├── common/                  # header/footer dùng chung + pass4 + staging-override + CLAUDE.md scaffold (v2.2.0)
+│   ├── header.md             # Vai trò + chỉ thị định dạng output (tất cả pass)
+│   ├── pass3-footer.md       # Chỉ thị health-check sau Pass 3 + 5 khối guardrail CRITICAL (v2.2.0)
+│   ├── pass3-phase1.md       # Khối "Read Once, Extract Facts" với Rule A-E (v2.1.0)
+│   ├── pass4.md              # Prompt scaffolding memory (v2.0.0)
+│   ├── staging-override.md   # Chuyển hướng write .claude/rules/** sang .staged-rules/** (v2.0.0)
+│   ├── claude-md-scaffold.md # Template CLAUDE.md 8 section tất định (v2.2.0)
+│   └── lang-instructions.json # Chỉ thị output theo ngôn ngữ (10 ngôn ngữ)
 ├── java-spring/             # Java / Spring Boot
 ├── kotlin-spring/           # Kotlin / Spring Boot (CQRS, BFF, multi-module)
 ├── node-express/            # Node.js / Express
@@ -850,6 +869,8 @@ pass-prompts/templates/
 
 `plan-installer` tự phát hiện các stack của bạn, rồi lắp ráp prompt theo kiểu. NestJS, Vue/Nuxt, Vite SPA và Flask mỗi cái dùng template chuyên dụng với danh mục phân tích đặc thù framework (ví dụ: `@Module`/`@Injectable`/Guards cho NestJS; `<script setup>`/Pinia/useFetch cho Vue; client-side routing/`VITE_` env cho Vite; Blueprint/`app.factory`/Flask-SQLAlchemy cho Flask). Cho dự án multi-stack, `pass1-backend-prompt.md` và `pass1-frontend-prompt.md` riêng biệt được tạo, trong khi `pass3-prompt.md` kết hợp mục tiêu tạo của cả hai stack. Ở v2.1.0, template Pass 3 được thêm `common/pass3-phase1.md` (block "Read Once, Extract Facts" với Rules A–E) vào đầu trước khi được cắt theo từng stage split-mode. Pass 4 dùng template chung `common/pass4.md` (memory scaffolding) bất kể stack.
 
+**Trong v2.2.0**, prompt Pass 3 cũng chèn inline `common/claude-md-scaffold.md` (template CLAUDE.md 8 section tất định) vào giữa khối phase1 và thân stack-specific — điều này cố định cấu trúc section để CLAUDE.md được tạo ra không bị drift giữa các project, trong khi nội dung vẫn thích ứng theo project. Template được viết **English-first**; việc inject ngôn ngữ từ `lang-instructions.json` chỉ thị LLM dịch tiêu đề section và văn xuôi sang ngôn ngữ output đích tại thời điểm emit.
+
 ---
 
 ## Hỗ Trợ Monorepo
@@ -936,6 +957,12 @@ my-monorepo/                    ← Chạy ở đây: npx claudeos-core init
 
 **"CLAUDEOS_SKIP_TRANSLATION=1 is set but --lang='ko' requires translation" InitError (v2.0.0)** — Bạn đang set env var chỉ dành cho test `CLAUDEOS_SKIP_TRANSLATION=1` trong shell (có thể là sót từ setup CI/test) VÀ chọn `--lang` khác tiếng Anh. Env var này short-circuit đường dịch mà static-fallback và gap-fill của Pass 4 phụ thuộc để output không phải tiếng Anh. `init` phát hiện xung đột lúc chọn ngôn ngữ và abort ngay lập tức (thay vì crash giữa Pass-4 với lỗi lồng khó hiểu). Sửa: hoặc `unset CLAUDEOS_SKIP_TRANSLATION` trước khi chạy, hoặc dùng `npx claudeos-core init --lang en`.
 
+**Cảnh báo "⚠️ v2.2.0 upgrade detected" (v2.2.0)** — `CLAUDE.md` hiện tại được sinh bởi phiên bản trước v2.2.0. Regeneration mặc định ở resume mode sẽ skip các file existing dưới Rule B idempotency, nên các cải tiến cấu trúc v2.2.0 (CLAUDE.md scaffold 8-section, per-file paths trong `40.infra/*`, port accuracy dựa trên `.env.example`, redesign Section 8 `Common Rules & Memory (L4)` (thiết kế lại với hai sub-section: Common Rules · L4 Memory), hàng rule `60.memory/*`, forward-reference `04.doc-writing-guide.md`) sẽ KHÔNG được áp dụng. Fix: chạy lại với `npx claudeos-core init --force`. Nó overwrite file generated (`CLAUDE.md`, `.claude/rules/`, `claudeos-core/standard/`, `claudeos-core/skills/`, `claudeos-core/guide/`) đồng thời giữ nguyên `claudeos-core/memory/` (decision-log, failure-patterns bạn đã tích luỹ — append-only). Commit project trước nếu muốn diff các overwrite.
+
+**Port trong CLAUDE.md khác với `.env.example` (v2.2.0)** — Parser `.env` mới của stack-detector (`lib/env-parser.js`) đọc `.env.example` trước (canonical, committed), rồi các variant `.env` làm fallback. Biến port được nhận diện: `PORT`, `VITE_PORT`, `VITE_DESKTOP_PORT`, `NEXT_PUBLIC_PORT`, `NUXT_PORT`, `DJANGO_PORT`, v.v. Với Spring Boot, `server.port` trong `application.yml` vẫn ưu tiên hơn `.env` (config framework-native thắng). Nếu project dùng tên biến env bất thường, đổi thành convention hoặc mở issue để mở rộng `PORT_VAR_KEYS`. Framework default (Vite 5173, Next.js 3000, Django 8000) chỉ dùng khi cả direct detection lẫn `.env` đều im lặng.
+
+**Giá trị secret bị redact thành `***REDACTED***` trong docs generated (v2.2.0)** — Hành vi mong đợi. Parser `.env` v2.2.0 tự động redact giá trị của biến khớp các pattern `PASSWORD`/`SECRET`/`TOKEN`/`API_KEY`/`CREDENTIAL`/`PRIVATE_KEY` trước khi tới bất kỳ generator nào. Đây là defense-in-depth chống secret bị commit nhầm vào `.env.example`. `DATABASE_URL` giữ nguyên vì back-compat nhận diện DB của stack-detector. Nếu thấy `***REDACTED***` trong `CLAUDE.md` generated thì là bug — giá trị redacted không nên tới bảng; vui lòng báo issue. Config runtime không nhạy cảm (port, host, API target, NODE_ENV, v.v.) vẫn pass qua nguyên vẹn.
+
 ---
 
 ## Đóng Góp
@@ -945,7 +972,7 @@ my-monorepo/                    ← Chạy ở đây: npx claudeos-core init
 - **Template stack mới** — Ruby/Rails, Go (Gin/Fiber/Echo), PHP (Laravel/Symfony), Rust (Axum/Actix), Svelte/SvelteKit, Remix
 - **Tích hợp IDE** — VS Code extension, IntelliJ plugin
 - **Template CI/CD** — ví dụ GitLab CI, CircleCI, Jenkins (GitHub Actions đã có — xem `.github/workflows/test.yml`)
-- **Độ phủ test** — Mở rộng test suite (hiện tại 563 test trên 29 file test bao phủ scanner, phát hiện stack, domain grouping, plan parsing, tạo prompt, CLI selector, phát hiện monorepo, phát hiện Vite SPA, công cụ xác minh, L4 memory scaffold, xác thực resume Pass 2, Pass 3 Guards 1/2/3 (sentinel H1 + empty-file nhận biết BOM H2 + unlink marker cũ nghiêm ngặt), chia batch split-mode Pass 3, resume partial-marker Pass 3 (v2.1.0), xác thực nội dung marker Pass 4 + độ nghiêm ngặt unlink marker cũ + gap-fill scaffoldSkillsManifest (v2.1.0), guard env-skip dịch + fail-fast sớm + CI workflow, di chuyển staged-rules, fallback dịch lang-aware, suite regression loại bỏ master plan (v2.1.0), regression định dạng memory score/compact (v2.1.0), và cấu trúc template AI Work Rules)
+- **Độ phủ test** — Mở rộng test suite (hiện tại 602 test trên 30 file test bao phủ scanner, phát hiện stack, domain grouping, plan parsing, tạo prompt, CLI selector, phát hiện monorepo, phát hiện Vite SPA, công cụ xác minh, L4 memory scaffold, xác thực resume Pass 2, Pass 3 Guards 1/2/3 (sentinel H1 + empty-file nhận biết BOM H2 + unlink marker cũ nghiêm ngặt), chia batch split-mode Pass 3, resume partial-marker Pass 3 (v2.1.0), xác thực nội dung marker Pass 4 + độ nghiêm ngặt unlink marker cũ + gap-fill scaffoldSkillsManifest (v2.1.0), guard env-skip dịch + fail-fast sớm + CI workflow, di chuyển staged-rules, fallback dịch lang-aware, suite regression loại bỏ master plan (v2.1.0), regression định dạng memory score/compact (v2.1.0), và cấu trúc template AI Work Rules, và trích xuất port/host/API-target từ parser `.env` + redact biến nhạy cảm (v2.2.0))
 
 Xem [`CONTRIBUTING.md`](./CONTRIBUTING.md) để có danh sách đầy đủ các khu vực, code style, commit convention, và hướng dẫn từng bước để thêm template stack mới.
 

package/README.zh-CN.md

@@ -85,10 +85,20 @@ ClaudeOS-Core 生成的文档知道你的项目使用 `ApiResponse.ok()`（而
 | **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` 变体优先，因为它是 developer-neutral 的 shape-of-truth，而非某个贡献者的本地覆盖。
+- **识别的 port 变量约定**：`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`。当两者同时存在时，framework-specific 名称优先于通用的 `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` 中声明的 port，最后才是 framework 默认值（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` 的 secrets 的 defense-in-depth 保护。`DATABASE_URL` 因 stack-detector DB 识别 back-compat 而被显式白名单保留。
+
 ### Java 领域检测（5 种模式，带回退）
 
 | 优先级 | 模式 | 结构 | 示例 |
@@ -364,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 项目上可能发生，因为各 stack 的 `pass3.md` 模板将 `MANIFEST.md` 列为生成目标但未标记为 REQUIRED），gap-fill 会创建一个最小 stub，使 `.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 省略了它（在 skill-sparse 项目上可能发生，因为各 stack 的 `pass3.md` 模板将 `MANIFEST.md` 列为生成目标但未标记为 REQUIRED），gap-fill 会创建一个最小 stub，使 `.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 成功。
 
@@ -474,6 +484,8 @@ Pass 3 提示模板还包括一个 **Phase 1 "Read Once, Extract Facts" 块**，
 - **Rule D** — 输出简洁：文件写入之间仅一行（`[WRITE]`/`[SKIP]`），不复述事实表，不回显文件内容。
 - **Rule E** — 批量幂等检查：在 PHASE 2 开始时进行一次 `Glob`，而不是每个目标调用 `Read`。
 
+在 **v2.2.0** 中，Pass 3 会将一个确定性的 CLAUDE.md scaffold（`pass-prompts/templates/common/claude-md-scaffold.md`）内联到提示中。这固定了 8 个顶层章节的标题和顺序，使生成的 `CLAUDE.md` 不会在项目之间漂移，同时仍允许每个章节的内容适应各个项目。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 为 `skills/00.shared/MANIFEST.md` 添加了一个 gap-fill，以防 Pass 3c 省略它。
 
 ---
@@ -483,7 +495,7 @@ Pass 3 提示模板还包括一个 **Phase 1 "Read Once, Extract Facts" 块**，
 ```
 your-project/
 │
-├── CLAUDE.md                          ← Claude Code 入口点
+├── CLAUDE.md                          ← Claude Code 入口点（8 部分确定性结构，v2.2.0）
 │
 ├── .claude/
 │   └── rules/                         ← Glob 触发规则
@@ -832,7 +844,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
@@ -849,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 模板在被按 split-mode 阶段切片前，会被前置 `common/pass3-phase1.md`（包含 Rules A–E 的 "Read Once, Extract Facts" 块）。Pass 4 使用共享的 `common/pass4.md` 模板（内存脚手架），与技术栈无关。
 
+**在 v2.2.0 中**，Pass 3 提示词还在 phase1 块和栈特定主体之间内联嵌入 `common/claude-md-scaffold.md`（确定性 8 节 CLAUDE.md 模板）——这固定了 8 节的结构以避免生成的 CLAUDE.md 在项目间漂移，同时内容仍按项目自适应。`claude-md-scaffold.md` 采用 **English-first** 编写；来自 `lang-instructions.json` 的语言注入指示 LLM 在输出时将节标题和散文翻译为目标输出语言。
+
 ---
 
 ## 单体仓库支持
@@ -935,6 +956,12 @@ my-monorepo/                    ← 在此运行：npx claudeos-core init
 
 **"CLAUDEOS_SKIP_TRANSLATION=1 is set but --lang='ko' requires translation" InitError（v2.0.0）** — 你在 shell 中设置了仅用于测试的环境变量 `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 内存两个子节结构）、`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 变量名，请改用惯例名称或提 issue 请求扩展 `PORT_VAR_KEYS`。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***`，这是 bug，请提交 issue——redacted 值不应到达表格。非敏感运行时配置（port、host、API target、NODE_ENV 等）照常通过。
+
 ---
 
 ## 贡献
@@ -944,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`）
-- **测试覆盖率** — 扩展测试套件（当前 29 个测试文件中的 563 个测试，涵盖扫描器、技术栈检测、领域分组、计划解析、提示生成、CLI 选择器、单体仓库检测、Vite SPA 检测、验证工具、L4 内存脚手架、Pass 2 恢复验证、Pass 3 Guards 1/2/3（H1 哨兵 + H2 BOM-aware 空文件 + 严格陈旧标记 unlink）、Pass 3 split-mode 批次子分割、Pass 3 部分标记 resume（v2.1.0）、Pass 4 标记内容验证 + 陈旧标记 unlink 严格性 + 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 空文件 + 严格陈旧标记 unlink）、Pass 3 split-mode 批次子分割、Pass 3 部分标记 resume（v2.1.0）、Pass 4 标记内容验证 + 陈旧标记 unlink 严格性 + 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) 以获取完整的领域列表、代码风格、提交约定和添加新技术栈模板的分步指南。