claudeos-core 2.1.0 → 2.2.0

package/README.ru.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 — и накопленный вывод стабильно превышал context window после ~5 доменов. Исправление — структурное, а не настройка промпта:
-
-- **Pass 3 split-режим** (всегда включён) — Pass 3 разбивается на последовательные вызовы `claude -p` (`3a` → `3b-core` → `3b-N` → `3c-core` → `3c-N` → `3d-aux`). Каждая стадия стартует с **свежим context window**, поэтому переполнение из-за накопления вывода структурно невозможно независимо от размера проекта.
-- **Фактологический лист между стадиями** — Стадия `3a` один раз читает анализ Pass 2 и дистиллирует его в `pass3a-facts.md` размером 5–10 KB. Все последующие стадии ссылаются на этот fact sheet вместо повторного чтения 100–500 KB `pass2-merged.json`, что сохраняет межфайловую согласованность даже при свежих контекстах.
-- **Разбиение на батчи** (автоматически при ≥16 доменов) — Стадии 3b/3c дополнительно делятся на батчи по 15 доменов, удерживая вывод каждой стадии под ~50 файлами. 18-доменный admin-фронтенд на React 19 + Vite 6 завершается за **102 минуты со 101 сгенерированным файлом по 8 стадиям и нулевыми отказами переполнения** (реальный production-прогон, 2026-04-20).
-- **Генерация master plan удалена** — Файлы `claudeos-core/plan/*-master.md` больше не генерируются. Master plans были внутренним бэкапом, который Claude Code не читал в рантайме, и их агрегация в Pass 3d была основным триггером переполнения. Используйте `git` для бэкапа/восстановления.
-- **Pass 4 gap-fill: `skills/00.shared/MANIFEST.md`** — Если Pass 3c пропускает skill-реестр (проекты с малым количеством skills), Pass 4 теперь автоматически создаёт заглушку, чтобы `.claude/rules/50.sync/03.skills-sync.md` никогда не ссылался на несуществующий файл.
-
-Несколько более мелких фиксов: `memory --help` теперь показывает справку подкоманды memory (раньше показывался top-level); `memory score` больше не оставляет дублирующие строки `importance`; маркеры summary в `memory compact` теперь корректные markdown-элементы списка. Полные детали: [CHANGELOG.md](./CHANGELOG.md).
-
----
-
 ## Почему ClaudeOS-Core?
 
 Любой другой инструмент для Claude Code работает так:
@@ -99,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 паттернов с фолбэком)
 
 | Приоритет | Паттерн | Структура | Пример |
@@ -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`.
 
-> **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.
 
@@ -488,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 его пропустил.
 
 ---
@@ -497,7 +497,7 @@ npx claudeos-core init
 ```
 your-project/
 │
-├── CLAUDE.md                          ← Точка входа Claude Code
+├── CLAUDE.md                          ← Точка входа Claude Code (детерминированная 8-секционная структура, v2.2.0)
 │
 ├── .claude/
 │   └── rules/                         ← Правила, срабатывающие по glob
@@ -591,24 +591,6 @@ Split-режим Pass 3 масштабирует количество стади
 
 Pass 4 (memory scaffolding) добавляет от ~30 секунд до 5 минут сверху, в зависимости от того, запускается ли Claude-driven генерация или статический фолбэк. Для мульти-стек проектов (например, Java + React) backend- и frontend-домены считаются вместе. Проект с 6 backend + 4 frontend доменами = 10 суммарно = уровень «Средний».
 
-### Реальный production-кейс: 18-доменный admin-фронтенд (2026-04-20)
-
-Admin-фронтенд на React 19 + Vite 6 + TypeScript с 18 доменами и 6 доменными группами завершился end-to-end за **102 минуты со 101 сгенерированным файлом**. Разбивка по стадиям:
-
-| Стадия | Файлы | Время | Файлов/мин |
-|---|---|---|---|
-| `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 файлов/мин), потому что стадии со свежим контекстом выигрывают от компактных повторяющихся per-domain паттернов. Верификация вся зелёная: `plan-validator`, `sync-checker`, `content-validator`, `pass-json-validator` — ноль отказов переполнения, ноль усечений.
-
 ---
 
 ## Инструменты верификации
@@ -810,8 +792,7 @@ ClaudeOS-Core фокусируется на **проектно-специфич
 Он вызывает `claude -p` несколько раз на протяжении 4 проходов. В split-режиме v2.1.0 только Pass 3 разворачивается в 4–14+ стадий в зависимости от размера проекта (см. [Автомасштабирование](#автомасштабирование-по-размеру-проекта)). Типичный малый проект (1–15 доменов) использует в сумме 8–9 вызовов `claude -p`; 18-доменный проект использует 11; 60-доменный проект использует 15–17. Каждая стадия запускается со свежим context window — per-call стоимость токенов в действительности ниже, чем была у single-call Pass 3, потому что ни одна стадия не должна удерживать всё дерево файлов в одном контексте. Когда `--lang` не английский, путь статического фолбэка может вызвать несколько дополнительных `claude -p` для перевода; результаты кэшируются в `claudeos-core/generated/.i18n-cache-<lang>.json`, так что последующие запуски их переиспользуют. Это в пределах нормального использования Claude Code.
 
 **В: Что такое Pass 3 split-режим и зачем он был добавлен в v2.1.0?**
-До v2.1.0 Pass 3 делал один вызов `claude -p`, который должен был выдать всё сгенерированное дерево файлов (`CLAUDE.md`, стандарты, правила, skills, гайды — обычно 30–60 файлов) в одном ответе. Это работало на малых проектах, но стабильно падало с ошибкой `Prompt is too long` (переполнение из-за накопления вывода) около 5 доменов. Отказ не был предсказуем по размеру входа — он зависел от того, насколько многословным оказался каждый сгенерированный файл, и мог случаться на одном и том же проекте эпизодически. Split-режим структурно обходит проблему: Pass 3 разбивается на последовательные стадии (`3a` → `3b-core` → `3b-N` → `3c-core` → `3c-N` → `3d-aux`), каждая из которых — отдельный вызов `claude -p` со свежим context window. Кросс-стейджевая согласованность сохраняется через `pass3a-facts.md` — дистиллированный fact sheet размером 5–10 KB, на который ссылается каждая последующая стадия вместо повторного чтения `pass2-merged.json`. Маркер `pass3-complete.json` несёт массив `groupsCompleted`, так что краш во время `3c-2` возобновляется с `3c-2` (а не с `3a`), избегая двойного расхода токенов. Эмпирически проверено до 18 доменов × 101 файл × 102 минут с нулевыми переполнениями — см. [Автомасштабирование](#автомасштабирование-по-размеру-проекта) для реальной production-разбивки.
-
+До v2.1.0 Pass 3 делал один вызов `claude -p`, который должен был выдать всё сгенерированное дерево файлов (`CLAUDE.md`, стандарты, правила, skills, гайды — обычно 30–60 файлов) в одном ответе. Это работало на малых проектах, но стабильно падало с ошибкой `Prompt is too long` (переполнение из-за накопления вывода) около 5 доменов. Отказ не был предсказуем по размеру входа — он зависел от того, насколько многословным оказался каждый сгенерированный файл, и мог случаться на одном и том же проекте эпизодически. Split-режим структурно обходит проблему: Pass 3 разбивается на последовательные стадии (`3a` → `3b-core` → `3b-N` → `3c-core` → `3c-N` → `3d-aux`), каждая из которых — отдельный вызов `claude -p` со свежим context window. Кросс-стейджевая согласованность сохраняется через `pass3a-facts.md` — дистиллированный fact sheet размером 5–10 KB, на который ссылается каждая последующая стадия вместо повторного чтения `pass2-merged.json`. Маркер `pass3-complete.json` несёт массив `groupsCompleted`, так что краш во время `3c-2` возобновляется с `3c-2` (а не с `3a`), избегая двойного расхода токенов.
 **В: Стоит ли коммитить сгенерированные файлы в Git?**
 Да, рекомендуется. Ваша команда может использовать одинаковые стандарты Claude Code. Подумайте о добавлении `claudeos-core/generated/` в `.gitignore` (JSON анализа регенерируется).
 
@@ -866,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
@@ -883,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.
+
 ---
 
 ## Поддержка монорепо
@@ -969,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 и т.д.) проходит без изменений.
+
 ---
 
 ## Контрибьюции
@@ -978,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

@@ -12,20 +12,6 @@ ClaudeOS-Core đọc codebase của bạn, trích xuất mọi pattern tìm th
 
 ---
 
-## Có Gì Mới Trong v2.1.0
-
-v2.1.0 tái kiến trúc Pass 3 để loại bỏ lỗi `Prompt is too long` trên các dự án cỡ trung bình đến lớn. Trước đây, một lời gọi Pass 3 đơn lẻ phải phát ra toàn bộ cây tài liệu cùng lúc — hàng chục file trải dài qua `CLAUDE.md`, rules, standards, skills và guides — và output tích lũy luôn vượt context window khi vượt quá ~5 domain. Fix này mang tính **cấu trúc**, không phải tinh chỉnh prompt:
-
-- **Pass 3 split mode** (luôn bật) — Pass 3 được tách thành các lời gọi `claude -p` tuần tự (`3a` → `3b-core` → `3b-N` → `3c-core` → `3c-N` → `3d-aux`). Mỗi stage bắt đầu với **context window mới**, nên tràn output do tích lũy không còn khả thi bất kể kích thước dự án.
-- **Fact sheet giữa các stage** — Stage `3a` đọc kết quả phân tích Pass 2 một lần và chắt lọc thành `pass3a-facts.md` kích thước 5–10 KB. Tất cả stage sau tham chiếu fact sheet này thay vì đọc lại `pass2-merged.json` 100–500 KB, giữ tính nhất quán xuyên file qua các context mới.
-- **Chia batch tự động** (tự động ở ≥16 domain) — Stage 3b/3c được chia thêm thành các batch 15 domain mỗi cái, giữ output của mỗi stage dưới ~50 file. Admin frontend React 19 + Vite 6 với 18 domain hoàn thành trong **102 phút với 101 file được tạo qua 8 stage, 0 lỗi tràn output** (chạy thực tế production, 2026-04-20).
-- **Loại bỏ tạo master plan** — Các file `claudeos-core/plan/*-master.md` không còn được tạo nữa. Master plan là backup nội bộ mà Claude Code không đọc lúc runtime, và việc tổng hợp chúng trong Pass 3d là nguyên nhân tràn chính. Dùng `git` để backup/restore thay thế.
-- **Pass 4 gap-fill: `skills/00.shared/MANIFEST.md`** — Nếu Pass 3c bỏ sót skill registry (dự án ít skill), Pass 4 giờ tự động tạo stub để `.claude/rules/50.sync/03.skills-sync.md` không bao giờ trỏ tới file không tồn tại.
-
-Một vài fix nhỏ: `memory --help` giờ hiển thị help của subcommand memory (trước đây hiển thị top-level); `memory score` không còn để lại các dòng `importance` trùng lặp; marker summary của `memory compact` giờ là markdown list item đúng định dạng. Chi tiết đầy đủ: [CHANGELOG.md](./CHANGELOG.md).
-
----
-
 ## Tại sao chọn ClaudeOS-Core?
 
 Mọi công cụ Claude Code khác hoạt động như sau:
@@ -99,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ụ |
@@ -378,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.
 
@@ -488,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.
 
 ---
@@ -497,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
@@ -591,24 +589,6 @@ Công thức số stage (khi chia batch): `1 (3a) + 1 (3b-core) + N (3b-1..N) +
 
 Pass 4 (memory scaffolding) thêm khoảng ~30 giây đến 5 phút lên trên tùy thuộc vào việc chạy tạo qua Claude hay fallback tĩnh. Với dự án multi-stack (ví dụ Java + React), domain backend và frontend được đếm cộng lại. Dự án 6 backend + 4 frontend = 10 tổng = tier Vừa.
 
-### Thực tế production: admin frontend 18 domain (2026-04-20)
-
-Một admin frontend React 19 + Vite 6 + TypeScript với 18 domain và 6 domain group hoàn thành end-to-end trong **102 phút với 101 file được tạo**. Phân bổ stage:
-
-| Stage | File | Thời gian | File/phút |
-|---|---|---|---|
-| `3a` (trích xuất fact) | 1 (`pass3a-facts.md`) | 8m 44s | — |
-| `3b-core` (CLAUDE.md + chung) | 24 | 22m 10s | 1.1 |
-| `3b-1` (15 domain) | 30 | 10m 6s | **3.0** |
-| `3b-2` (3 domain) | 6 | 4m 34s | 1.3 |
-| `3c-core` (guide + chung) | 11 | 8m 31s | 1.3 |
-| `3c-1` (15 domain) | 8 | 5m 11s | **1.5** |
-| `3c-2` (3 domain) | 3 | 3m 50s | 0.8 |
-| `3d-aux` (database + mcp) | 3 | 2m 52s | 1.0 |
-| Pass 4 | 12 | 5m 36s | 2.1 |
-
-Throughput cao rõ rệt ở các stage domain theo batch (3b-1: 3.0 file/phút vs. 3b-core: 1.1 file/phút) vì các stage context mới được hưởng lợi từ các pattern chặt chẽ, lặp lại cho từng domain. Xác minh toàn xanh: `plan-validator`, `sync-checker`, `content-validator`, `pass-json-validator` — 0 lỗi tràn, 0 file bị cắt.
-
 ---
 
 ## Công Cụ Xác Minh
@@ -810,8 +790,7 @@ Không. Nó chỉ tạo `CLAUDE.md`, `.claude/rules/`, và `claudeos-core/`. Cod
 Nó gọi `claude -p` vài lần qua 4 pass. Ở split mode v2.1.0, chỉ riêng Pass 3 đã mở rộng thành 4–14+ stage tùy theo kích thước dự án (xem [Tự Động Mở Rộng](#tự-động-mở-rộng-theo-kích-thước-dự-án)). Một dự án nhỏ điển hình (1–15 domain) dùng tổng cộng 8–9 lời gọi `claude -p`; dự án 18 domain dùng 11; dự án 60 domain dùng 15–17. Mỗi stage chạy với context window mới — chi phí token mỗi lời gọi thực ra thấp hơn Pass 3 lời-gọi-đơn, vì không stage nào phải giữ toàn bộ cây file trong một context. Khi `--lang` khác tiếng Anh, đường fallback tĩnh có thể gọi thêm vài `claude -p` để dịch; kết quả được cache trong `claudeos-core/generated/.i18n-cache-<lang>.json` nên các lần chạy sau dùng lại. Vẫn nằm trong mức sử dụng Claude Code bình thường.
 
 **Q: Pass 3 split mode là gì và tại sao được thêm ở v2.1.0?**
-Trước v2.1.0, Pass 3 thực hiện một lời gọi `claude -p` đơn phải phát ra toàn bộ cây file được tạo (`CLAUDE.md`, standards, rules, skills, guides — thường 30–60 file) trong một response. Điều này hoạt động trên dự án nhỏ nhưng luôn gặp lỗi `Prompt is too long` do tích lũy output ở ~5 domain. Lỗi không thể dự đoán từ kích thước input — nó phụ thuộc vào mức độ dài dòng của mỗi file được tạo, và có thể ập đến cùng một dự án một cách không ổn định. Split mode né vấn đề này về cấu trúc: Pass 3 được chia thành các stage tuần tự (`3a` → `3b-core` → `3b-N` → `3c-core` → `3c-N` → `3d-aux`), mỗi cái là một lời gọi `claude -p` riêng với context window mới. Tính nhất quán xuyên stage được bảo tồn bởi `pass3a-facts.md`, fact sheet đã chắt lọc 5–10 KB mà mọi stage sau tham chiếu thay vì đọc lại `pass2-merged.json`. Marker `pass3-complete.json` mang mảng `groupsCompleted` để crash trong `3c-2` resume từ `3c-2` (không phải từ `3a`), tránh chi phí token gấp đôi. Đã xác minh thực nghiệm lên tới 18 domain × 101 file × 102 phút với 0 tràn — xem [Tự Động Mở Rộng](#tự-động-mở-rộng-theo-kích-thước-dự-án) cho phân tích production thực tế.
-
+Trước v2.1.0, Pass 3 thực hiện một lời gọi `claude -p` đơn phải phát ra toàn bộ cây file được tạo (`CLAUDE.md`, standards, rules, skills, guides — thường 30–60 file) trong một response. Điều này hoạt động trên dự án nhỏ nhưng luôn gặp lỗi `Prompt is too long` do tích lũy output ở ~5 domain. Lỗi không thể dự đoán từ kích thước input — nó phụ thuộc vào mức độ dài dòng của mỗi file được tạo, và có thể ập đến cùng một dự án một cách không ổn định. Split mode né vấn đề này về cấu trúc: Pass 3 được chia thành các stage tuần tự (`3a` → `3b-core` → `3b-N` → `3c-core` → `3c-N` → `3d-aux`), mỗi cái là một lời gọi `claude -p` riêng với context window mới. Tính nhất quán xuyên stage được bảo tồn bởi `pass3a-facts.md`, fact sheet đã chắt lọc 5–10 KB mà mọi stage sau tham chiếu thay vì đọc lại `pass2-merged.json`. Marker `pass3-complete.json` mang mảng `groupsCompleted` để crash trong `3c-2` resume từ `3c-2` (không phải từ `3a`), tránh chi phí token gấp đôi.
 **Q: Tôi có nên commit các file được tạo vào Git không?**
 Có, khuyến nghị. Team của bạn có thể chia sẻ cùng standard Claude Code. Hãy xem xét thêm `claudeos-core/generated/` vào `.gitignore` (JSON phân tích có thể tạo lại).
 
@@ -866,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
@@ -883,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
@@ -969,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
@@ -978,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

@@ -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 个阶段，零溢出失败**（实测生产运行，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 现在会自动创建一个 stub，使 `.claude/rules/50.sync/03.skills-sync.md` 永远不会指向悬空文件。
-
-一些较小的修复：`memory --help` 现在显示 memory 子命令帮助（之前显示的是顶层）；`memory score` 不再留下重复的 `importance` 行；`memory compact` 的 summary 标记现在是正确的 markdown 列表项。完整详情：[CHANGELOG.md](./CHANGELOG.md)。
-
----
-
 ## 为什么选择 ClaudeOS-Core？
 
 其他所有 Claude Code 工具都是这样工作的：
@@ -99,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 种模式，带回退）
 
 | 优先级 | 模式 | 结构 | 示例 |
@@ -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 项目上可能发生，因为各 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 成功。
 
@@ -488,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 省略它。
 
 ---
@@ -497,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 触发规则
@@ -591,24 +589,6 @@ Pass 3 的 split 模式会随领域数扩展阶段数。批次子分割在 16
 
 Pass 4（内存脚手架）根据运行 Claude 驱动的生成还是静态回退，额外增加 ~30 秒到 5 分钟。对于多技术栈项目（例如 Java + React），backend 和 frontend 领域一起计数。6 个 backend + 4 个 frontend 领域的项目 = 总共 10 个 = 中型层级。
 
-### 实际生产案例：18 领域 admin 前端（2026-04-20）
-
-一个具有 18 个领域和 6 个领域分组的 React 19 + Vite 6 + TypeScript admin 前端端到端**在 102 分钟内生成 101 个文件**完成。阶段分解：
-
-| 阶段 | 文件 | 时间 | 文件/分钟 |
-|---|---|---|---|
-| `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`（指南 + 共享） | 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 文件/分钟 vs. 3b-core：1.1 文件/分钟），因为全新上下文的阶段受益于紧凑的、可重复的每领域模式。验证全部通过：`plan-validator`、`sync-checker`、`content-validator`、`pass-json-validator` — 零溢出失败，零截断。
-
 ---
 
 ## 验证工具
@@ -809,8 +789,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 次。每个阶段都以全新的上下文窗口运行 — 每次调用的 token 成本实际上比过去的单次调用 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 -p` 调用，必须在一次响应中输出整个生成文件树（`CLAUDE.md`、standards、rules、skills、guides — 通常 30–60 个文件）。这在小型项目上有效，但在约 5 个领域时就会可靠地触发 `Prompt is too long` 输出累积失败。失败无法从输入规模预测 — 它取决于每个生成文件碰巧多么冗长，并且可能间歇性地击中同一个项目。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`），避免 token 成本翻倍。实测已在 18 领域 × 101 文件 × 102 分钟且零溢出的条件下验证 — 实际生产分解见[按项目规模自动扩展](#按项目规模自动扩展)。
-
+在 v2.1.0 之前，Pass 3 进行一次 `claude -p` 调用，必须在一次响应中输出整个生成文件树（`CLAUDE.md`、standards、rules、skills、guides — 通常 30–60 个文件）。这在小型项目上有效，但在约 5 个领域时就会可靠地触发 `Prompt is too long` 输出累积失败。失败无法从输入规模预测 — 它取决于每个生成文件碰巧多么冗长，并且可能间歇性地击中同一个项目。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`），避免 token 成本翻倍。
 **Q：我应该将生成的文件提交到 Git 吗？**
 是的，推荐。你的团队可以共享相同的 Claude Code 标准。考虑将 `claudeos-core/generated/` 添加到 `.gitignore`（分析 JSON 可以重新生成）。
 
@@ -865,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
@@ -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 模板在被按 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 在输出时将节标题和散文翻译为目标输出语言。
+
 ---
 
 ## 单体仓库支持
@@ -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）** — 你在 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 等）照常通过。
+
 ---
 
 ## 贡献
@@ -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`）
-- **测试覆盖率** — 扩展测试套件（当前 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) 以获取完整的领域列表、代码风格、提交约定和添加新技术栈模板的分步指南。