claudeos-core 2.1.1 → 2.3.0

package/CONTRIBUTING.md

@@ -1,92 +1,92 @@
-# Contributing to ClaudeOS-Core
-
-Thank you for your interest in contributing! Here's how you can help.
-
-## Areas Where Help Is 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`)
-- **Custom template authoring** — User-defined pass1/pass2/pass3 templates for niche stacks
-- **Verification coverage** — Additional content-validator checks, stack-specific lint rules
-
-## What's Already Done (no longer needed)
-
-- ~~Monorepo support~~ — Turborepo, pnpm workspaces, Lerna, npm/yarn workspaces
-- ~~Localization~~ — 10 languages (EN, KO, ZH-CN, JA, ES, VI, HI, RU, FR, DE)
-- ~~Kotlin / Spring Boot~~ — CQRS, BFF, multi-module support
-- ~~Flask / FastAPI / Django dedicated templates~~ — each uses its own `pass1/2/3.md`
-- ~~NestJS / Fastify / Vite dedicated templates~~ — no longer sharing `node-express`
-- ~~L4 Memory layer (v2.0.0)~~ — Pass 4 + `60.memory/` rules + `memory/` files
-- ~~GitHub Actions CI~~ — `.github/workflows/test.yml` (ubuntu × windows × macOS, Node 18/20)
-
-## Getting Started
-
-```bash
-git clone https://github.com/claudeos-core/claudeos-core.git
-cd claudeos-core
-npm install
-npm test   # 489 tests, ~2s
-```
-
-## How to Contribute
-
-1. Fork the repository
-2. Create a feature branch: `git checkout -b feature/your-feature`
-3. Make your changes
-4. Run the full test suite: `npm test`
-5. Sanity-check on a sample project (optional): `npx . init --lang en` in a test directory
-6. Commit: `git commit -m "feat: your feature description"`
-7. Push: `git push origin feature/your-feature`
-8. Open a Pull Request
-
-## Testing
-
-- **Runner:** built-in Node test runner (`node --test`), no Jest/Mocha dependency.
-- **Current:** 489 tests across 24 files. CI runs the full matrix (ubuntu × windows × macOS × Node 18/20).
-- **Offline / no `claude` CLI:** the 5 tests in `tests/lang-aware-fallback.test.js` assert that translation throws when Claude is unavailable. The test file sets `process.env.CLAUDEOS_SKIP_TRANSLATION = "1"` at module top to make this deterministic regardless of CLI availability. CI also sets it at the job level in `.github/workflows/test.yml`.
-- **Adding new tests:** prefer a dedicated file (`tests/your-feature.test.js`). Use `os.tmpdir()` + `fs.rmSync(dir, {recursive: true, force: true})` cleanup, consistent with existing suites (see `tests/pass3-guards.test.js` for the canonical pattern).
-- **Integration tests:** `tests/verification-tools.test.js` spawns the CLI tools against temp project fixtures — follow that pattern for any new verification tool.
-
-## Adding a New Stack Template
-
-Reference implementations:
-- Simple single-stack backend: `pass-prompts/templates/python-flask/`
-- Complex backend with architecture variants: `pass-prompts/templates/kotlin-spring/` (CQRS, multi-module)
-- Frontend-only SPA: `pass-prompts/templates/node-vite/` (no backend, client-side routing)
-
-**Steps:**
-
-1. **Create template prompts** — `pass-prompts/templates/your-stack/{pass1.md, pass2.md, pass3.md}`. Follow sibling stacks for structure. Pass 4 uses shared `common/pass4.md` so you don't need a stack-specific memory prompt.
-2. **Add a domain scanner** — `plan-installer/scanners/scan-{language}.js` exporting a function that returns `{domains, rootPackage?}`. See `scan-java.js` (5 patterns + fallback) or `scan-python.js` (framework-aware) for patterns.
-3. **Wire scanner into dispatcher** — `plan-installer/structure-scanner.js` — add a case in `scanStructure()` for your language.
-4. **Update stack detection** — `plan-installer/stack-detector.js` — extend `detectStack()` to identify the framework from manifest files (`package.json`, `Gemfile`, `go.mod`, etc.).
-5. **Route to template** — `plan-installer/domain-grouper.js` — extend `selectTemplates()` to map `framework: "your-framework"` to the template directory name.
-6. **Set active-domain categories** — `plan-installer/domain-grouper.js` — extend `determineActiveDomains()` so the right standard categories apply (backend / frontend / security-db / infra / verification).
-7. **Add tests** — extend `tests/stack-detector.test.js`, add `tests/scan-YOUR-LANGUAGE.test.js`, extend `tests/domain-grouper.test.js`.
-8. **Update docs** — `README.md` "Supported Stacks" table + FAQ / Troubleshooting entries + `CHANGELOG.md` entry.
-
-## Code Style
-
-- Node.js CommonJS (`require`/`module.exports`), no TypeScript
-- 2-space indentation, semicolons required
-- `const` over `let` where possible
-- Custom `InitError` class for user-facing failures; named catch variable (`catch (_e)`) when the error is intentionally ignored
-- Windows compatibility: normalize paths with `path.join` + `.replace(/\\/g, "/")` before passing to `glob` (backslashes break glob patterns on Windows)
-- BOM-aware text checks: `String.prototype.trim` does NOT remove U+FEFF — use `.replace(/^\uFEFF/, "").trim()` when checking for empty content
-
-## Commit Message Convention
-
-```
-feat: add Ruby/Rails template
-fix: correct Vue domain scanning on Windows
-docs: update README for new stack
-refactor: simplify splitDomainGroups
-test: add coverage for scan-rust.js
-```
-
-CHANGELOG entries should be written in English regardless of the output language of generated docs.
-
-## License
-
-By contributing, you agree that your contributions will be licensed under the ISC License.
+# Contributing to ClaudeOS-Core
+
+Thank you for your interest in contributing! Here's how you can help.
+
+## Areas Where Help Is 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`)
+- **Custom template authoring** — User-defined pass1/pass2/pass3 templates for niche stacks
+- **Verification coverage** — Additional content-validator checks, stack-specific lint rules
+
+## What's Already Done (no longer needed)
+
+- ~~Monorepo support~~ — Turborepo, pnpm workspaces, Lerna, npm/yarn workspaces
+- ~~Localization~~ — 10 languages (EN, KO, ZH-CN, JA, ES, VI, HI, RU, FR, DE)
+- ~~Kotlin / Spring Boot~~ — CQRS, BFF, multi-module support
+- ~~Flask / FastAPI / Django dedicated templates~~ — each uses its own `pass1/2/3.md`
+- ~~NestJS / Fastify / Vite dedicated templates~~ — no longer sharing `node-express`
+- ~~L4 Memory layer (v2.0.0)~~ — Pass 4 + `60.memory/` rules + `memory/` files
+- ~~GitHub Actions CI~~ — `.github/workflows/test.yml` (ubuntu × windows × macOS, Node 18/20)
+
+## Getting Started
+
+```bash
+git clone https://github.com/claudeos-core/claudeos-core.git
+cd claudeos-core
+npm install
+npm test   # 489 tests, ~2s
+```
+
+## How to Contribute
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/your-feature`
+3. Make your changes
+4. Run the full test suite: `npm test`
+5. Sanity-check on a sample project (optional): `npx . init --lang en` in a test directory
+6. Commit: `git commit -m "feat: your feature description"`
+7. Push: `git push origin feature/your-feature`
+8. Open a Pull Request
+
+## Testing
+
+- **Runner:** built-in Node test runner (`node --test`), no Jest/Mocha dependency.
+- **Current:** 489 tests across 24 files. CI runs the full matrix (ubuntu × windows × macOS × Node 18/20).
+- **Offline / no `claude` CLI:** the 5 tests in `tests/lang-aware-fallback.test.js` assert that translation throws when Claude is unavailable. The test file sets `process.env.CLAUDEOS_SKIP_TRANSLATION = "1"` at module top to make this deterministic regardless of CLI availability. CI also sets it at the job level in `.github/workflows/test.yml`.
+- **Adding new tests:** prefer a dedicated file (`tests/your-feature.test.js`). Use `os.tmpdir()` + `fs.rmSync(dir, {recursive: true, force: true})` cleanup, consistent with existing suites (see `tests/pass3-guards.test.js` for the canonical pattern).
+- **Integration tests:** `tests/verification-tools.test.js` spawns the CLI tools against temp project fixtures — follow that pattern for any new verification tool.
+
+## Adding a New Stack Template
+
+Reference implementations:
+- Simple single-stack backend: `pass-prompts/templates/python-flask/`
+- Complex backend with architecture variants: `pass-prompts/templates/kotlin-spring/` (CQRS, multi-module)
+- Frontend-only SPA: `pass-prompts/templates/node-vite/` (no backend, client-side routing)
+
+**Steps:**
+
+1. **Create template prompts** — `pass-prompts/templates/your-stack/{pass1.md, pass2.md, pass3.md}`. Follow sibling stacks for structure. Pass 4 uses shared `common/pass4.md` so you don't need a stack-specific memory prompt.
+2. **Add a domain scanner** — `plan-installer/scanners/scan-{language}.js` exporting a function that returns `{domains, rootPackage?}`. See `scan-java.js` (5 patterns + fallback) or `scan-python.js` (framework-aware) for patterns.
+3. **Wire scanner into dispatcher** — `plan-installer/structure-scanner.js` — add a case in `scanStructure()` for your language.
+4. **Update stack detection** — `plan-installer/stack-detector.js` — extend `detectStack()` to identify the framework from manifest files (`package.json`, `Gemfile`, `go.mod`, etc.).
+5. **Route to template** — `plan-installer/domain-grouper.js` — extend `selectTemplates()` to map `framework: "your-framework"` to the template directory name.
+6. **Set active-domain categories** — `plan-installer/domain-grouper.js` — extend `determineActiveDomains()` so the right standard categories apply (backend / frontend / security-db / infra / verification).
+7. **Add tests** — extend `tests/stack-detector.test.js`, add `tests/scan-YOUR-LANGUAGE.test.js`, extend `tests/domain-grouper.test.js`.
+8. **Update docs** — `README.md` "Supported Stacks" table + FAQ / Troubleshooting entries + `CHANGELOG.md` entry.
+
+## Code Style
+
+- Node.js CommonJS (`require`/`module.exports`), no TypeScript
+- 2-space indentation, semicolons required
+- `const` over `let` where possible
+- Custom `InitError` class for user-facing failures; named catch variable (`catch (_e)`) when the error is intentionally ignored
+- Windows compatibility: normalize paths with `path.join` + `.replace(/\\/g, "/")` before passing to `glob` (backslashes break glob patterns on Windows)
+- BOM-aware text checks: `String.prototype.trim` does NOT remove U+FEFF — use `.replace(/^\uFEFF/, "").trim()` when checking for empty content
+
+## Commit Message Convention
+
+```
+feat: add Ruby/Rails template
+fix: correct Vue domain scanning on Windows
+docs: update README for new stack
+refactor: simplify splitDomainGroups
+test: add coverage for scan-rust.js
+```
+
+CHANGELOG entries should be written in English regardless of the output language of generated docs.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the ISC License.

package/README.de.md

@@ -69,6 +69,38 @@ Dieser Unterschied summiert sich. 10 Aufgaben/Tag × 20 Minuten gespart = **übe
 
 ---
 
+## Qualitätssicherung nach der Generierung (v2.3.0)
+
+Die Generierung ist nur die halbe Miete. Die andere Hälfte besteht darin, **zu wissen, dass die Ausgabe korrekt ist** — über 10 Ausgabesprachen, 11 Stack-Templates und Projekte jeder Größe hinweg. v2.3.0 fügt zwei deterministische Validatoren hinzu, die nach der Generierung laufen und nicht auf LLM-Selbstprüfungen angewiesen sind.
+
+### `claude-md-validator` — strukturelle Invarianten
+
+Jede generierte `CLAUDE.md` wird gegen 25 strukturelle Invarianten geprüft, die nur sprachinvariante Signale verwenden: Markdown-Syntax (`^## `, `^### `), literale Dateinamen (`decision-log.md`, `failure-patterns.md` — werden nie übersetzt), Anzahl der Abschnitte, Anzahl der Unterabschnitte pro Abschnitt und Anzahl der Tabellenzeilen. Derselbe Validator liefert Byte für Byte identische Urteile für eine `CLAUDE.md`, die in Englisch, Koreanisch, Japanisch, Vietnamesisch, Hindi, Russisch, Spanisch, Chinesisch, Französisch oder Deutsch generiert wurde.
+
+Die sprachübergreifende Garantie wird durch Test-Fixtures in allen 10 Sprachen verifiziert, einschließlich Bad-Case-Fixtures in 6 dieser Sprachen, die identische Fehlersignaturen erzeugen. Wenn eine Invariante bei einem vietnamesischen Projekt fehlschlägt, ist die Lösung dieselbe wie bei einem deutschen Projekt.
+
+### `content-validator [10/10]` — Prüfung von Pfadangaben und MANIFEST-Konsistenz
+
+Liest jede in Backticks eingefasste Pfadreferenz (`src/...`, `.claude/rules/...`, `claudeos-core/skills/...`) aus allen generierten `.md`-Dateien und verifiziert sie gegen das tatsächliche Dateisystem. Fängt zwei Klassen von LLM-Fehlern ab, die bisher kein Tool erkannt hat:
+
+- **`STALE_PATH`** — wenn Pass 3 oder Pass 4 einen plausiblen, aber nicht existierenden Pfad erfindet. Typische Fälle: Ableitung von `featureRoutePath.ts` aus einer TypeScript-Konstante namens `FEATURE_ROUTE_PATH`, obwohl die tatsächliche Datei `routePath.ts` heißt; Annahme von `src/main.tsx` nach Vite-Konvention in einem Multi-Entry-Projekt; Annahme von `src/__mocks__/handlers.ts` aus der MSW-Dokumentation, obwohl das Projekt keine Tests hat.
+- **`MANIFEST_DRIFT`** — wenn `claudeos-core/skills/00.shared/MANIFEST.md` einen Skill registriert, den `CLAUDE.md §6` nicht erwähnt (oder umgekehrt). Erkennt das häufige Orchestrator-plus-Sub-Skills-Layout, bei dem `CLAUDE.md §6` ein Einstiegspunkt und `MANIFEST.md` das vollständige Register ist — Sub-Skills werden als über ihren übergeordneten Orchestrator abgedeckt betrachtet.
+
+Der Validator ist gepaart mit Prompt-Time-Prävention in `pass3-footer.md` und `pass4.md`: Anti-Pattern-Blöcke dokumentieren die spezifischen Halluzinationsklassen (Parent-Directory-Präfix, Vite/MSW/Vitest/Jest/RTL-Bibliothekskonventionen), und explizite positive Guidance weist an, Regeln nach Verzeichnis zu scopen, wenn ein konkreter Dateiname nicht in `pass3a-facts.md` steht.
+
+### Validierung auf beliebigem Projekt ausführen
+
+```bash
+npx claudeos-core health     # alle Validatoren — einzelnes Go/No-Go-Urteil
+npx claudeos-core lint       # nur strukturelle Invarianten von CLAUDE.md (beliebige Sprache)
+```
+
+### Verifizierung in der realen Welt
+
+v2.3.0 wurde vor dem Release end-to-end auf zwei realen koreanischen Schwesterprojekten validiert: einem Single-SPA-Vite-+-React-19-Frontend mit 14 Domänen und einem 8-Sub-Skill-`scaffold-page-feature`-Orchestrator sowie einem Spring-Boot-+-MyBatis-Backend mit 8 Domänen und einem 8-Sub-Skill-`scaffold-crud-feature`-Orchestrator, das sich mitten in einer PostgreSQL-→-MariaDB-Migration befindet. Beide landeten bei **0 Fehlern, 0 Warnungen** im kompletten Health-Check — `STALE_PATH` 0, `MANIFEST_DRIFT` 0, 25/25 strukturelle Invarianten bestanden — ohne eine einzige manuelle Bearbeitung der generierten Ausgabe.
+
+---
+
 ## Unterstützte Stacks
 
 | Stack | Erkennung | Analysetiefe |
@@ -85,10 +117,20 @@ Dieser Unterschied summiert sich. 10 Aufgaben/Tag × 20 Minuten gespart = **übe
 | **Vite / React SPA** | `package.json`, `vite.config.*` | 9 Kategorien, 55 Unterpunkte |
 | **Angular** | `package.json`, `angular.json` | 12 Kategorien, 78 Unterpunkte |
 
-Automatisch erkannt: Sprache und Version, Framework und Version (einschließlich Vite als SPA-Framework), ORM (MyBatis, JPA, Exposed, Prisma, TypeORM, SQLAlchemy usw.), Datenbank (PostgreSQL, MySQL, Oracle, MongoDB, SQLite), Paketmanager (Gradle, Maven, npm, yarn, pnpm, pip, poetry), Architektur (CQRS, BFF — aus Modulnamen), Multi-Modul-Struktur (aus settings.gradle), Monorepo (Turborepo, pnpm-workspace, Lerna, npm/yarn workspaces).
+Automatisch erkannt: Sprache und Version, Framework und Version (einschließlich Vite als SPA-Framework), ORM (MyBatis, JPA, Exposed, Prisma, TypeORM, SQLAlchemy usw.), Datenbank (PostgreSQL, MySQL, Oracle, MongoDB, SQLite), Paketmanager (Gradle, Maven, npm, yarn, pnpm, pip, poetry), Architektur (CQRS, BFF — aus Modulnamen), Multi-Modul-Struktur (aus settings.gradle), Monorepo (Turborepo, pnpm-workspace, Lerna, npm/yarn workspaces), **Laufzeitkonfiguration aus `.env.example`** (v2.2.0 — extrahiert port/host/API-target aus über 16 Konventions-Variablennamen in den Frameworks Vite · Next.js · Nuxt · Angular · Node · Python).
 
 **Sie geben nichts an. Alles wird automatisch erkannt.**
 
+### `.env`-basierte Laufzeitkonfiguration (v2.2.0)
+
+v2.2.0 fügt `lib/env-parser.js` hinzu, damit die generierte `CLAUDE.md` widerspiegelt, was das Projekt tatsächlich deklariert, statt Framework-Defaults.
+
+- **Suchreihenfolge**: `.env.example` (kanonisch, committet) → `.env.local.example` → `.env.sample` → `.env.template` → `.env` → `.env.local` → `.env.development`. Die `.example`-Variante gewinnt, weil sie die entwickler-neutrale Shape-of-Truth ist, nicht die lokalen Overrides eines einzelnen Contributors.
+- **Erkannte Port-Variablen-Konventionen**: `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` / generisches `PORT`. Framework-spezifische Namen gewinnen gegenüber dem generischen `PORT`, wenn beide vorhanden sind.
+- **Host & API-Target**: `VITE_DEV_HOST` / `VITE_API_TARGET` / `NEXT_PUBLIC_API_URL` / `NUXT_PUBLIC_API_BASE` / `BACKEND_URL` / `PROXY_TARGET` usw.
+- **Priorität**: Spring Boots `application.yml` `server.port` gewinnt weiterhin (framework-native Config), dann der in `.env` deklarierte Port, dann der Framework-Default (Vite 5173, Next.js 3000, Django 8000 usw.) als letzte Rückfall-Option.
+- **Redaction sensibler Variablen**: Werte von Variablen, die den Mustern `PASSWORD` / `SECRET` / `TOKEN` / `API_KEY` / `ACCESS_KEY` / `PRIVATE_KEY` / `CREDENTIAL` / `JWT_SECRET` / `CLIENT_SECRET` / `SESSION_SECRET` / `BEARER` / `SALT` entsprechen, werden durch `***REDACTED***` ersetzt, bevor sie einen nachgelagerten Generator erreichen. Defense-in-Depth gegen versehentlich committed Secrets in `.env.example`. `DATABASE_URL` ist explizit auf der Allowlist für die Stack-Detector-DB-Identifikations-Back-Compat.
+
 ### Java-Domain-Erkennung (5 Muster mit Fallback)
 
 | Priorität | Muster | Struktur | Beispiel |
@@ -364,7 +406,7 @@ cat claudeos-core/generated/pass4-prompt.md \
 
 **Verifikation:** `claudeos-core/memory/` sollte 4 Dateien enthalten (`decision-log.md`, `failure-patterns.md`, `compaction.md`, `auto-rule-update.md`), `.claude/rules/60.memory/` sollte 4 Rule-Dateien enthalten, und `CLAUDE.md` sollte einen angehängten Abschnitt `## Memory (L4)` haben. Marker: `claudeos-core/generated/pass4-memory.json`.
 
-> **v2.1.0 Gap-Fill:** Pass 4 stellt zudem sicher, dass `claudeos-core/skills/00.shared/MANIFEST.md` existiert. Wenn Pass 3c die Datei ausgelassen hat (möglich bei skill-spärlichen Projekten, weil die Stack-`pass3.md`-Templates `MANIFEST.md` unter den Generierungszielen listen, aber nicht als REQUIRED markieren), erzeugt das Gap-Fill einen minimalen Stub, damit `.claude/rules/50.sync/03.skills-sync.md` stets ein gültiges Referenzziel hat. Idempotent: wird übersprungen, wenn die Datei bereits echten Inhalt hat (>20 Zeichen).
+> **v2.1.0 Gap-Fill:** Pass 4 stellt zudem sicher, dass `claudeos-core/skills/00.shared/MANIFEST.md` existiert. Wenn Pass 3c die Datei ausgelassen hat (möglich bei skill-spärlichen Projekten, weil die Stack-`pass3.md`-Templates `MANIFEST.md` unter den Generierungszielen listen, aber nicht als REQUIRED markieren), erzeugt das Gap-Fill einen minimalen Stub, damit `.claude/rules/50.sync/02.skills-sync.md` (v2.2.0-Pfad — die Anzahl der Sync-Regeln wurde von 3 auf 2 reduziert, was `03` war, ist jetzt `02`) stets ein gültiges Referenzziel hat. Idempotent: wird übersprungen, wenn die Datei bereits echten Inhalt hat (>20 Zeichen).
 
 > **Hinweis:** Wenn `claude -p` fehlschlägt oder `pass4-prompt.md` fehlt, fällt die automatisierte Pipeline auf ein statisches Scaffold über `lib/memory-scaffold.js` zurück (mit Claude-getriebener Übersetzung, wenn `--lang` nicht-englisch ist). Der statische Fallback läuft nur innerhalb von `npx claudeos-core init` — der manuelle Modus erfordert, dass Pass 4 erfolgreich ist.
 
@@ -474,6 +516,8 @@ Das Pass-3-Prompt-Template enthält zudem einen **Phase-1-Block „Read Once, Ex
 - **Rule D** — Output-Knappheit: eine Zeile (`[WRITE]`/`[SKIP]`) zwischen Datei-Schreibvorgängen, keine Wiederholung der Fact-Tabelle, kein Echoing des Datei-Inhalts.
 - **Rule E** — Batch-Idempotenz-Prüfung: ein `Glob` zu PHASE-2-Beginn statt Per-Target-`Read`-Aufrufe.
 
+In **v2.2.0** bettet Pass 3 zusätzlich ein deterministisches CLAUDE.md-Scaffold (`pass-prompts/templates/common/claude-md-scaffold.md`) inline in den Prompt ein. Dies fixiert die Titel und die Reihenfolge der 8 obersten Abschnitte, sodass die generierte `CLAUDE.md` nicht mehr zwischen Projekten drifted, während der Inhalt jedes Abschnitts sich weiterhin an jedes Projekt anpasst. Der neue `.env`-Parser des Stack-Detectors (`lib/env-parser.js`) liefert `stack.envInfo` an den Prompt, sodass Port/Host/API-Target-Zeilen mit dem übereinstimmen, was das Projekt tatsächlich deklariert, statt mit Framework-Defaults.
+
 **Pass 4** baut die L4-Memory-Schicht auf: persistente Team-Wissensdateien (decision-log, failure-patterns, Compaction-Policy, auto-rule-update) plus die `60.memory/`-Regeln, die zukünftigen Sessions mitteilen, wann und wie diese Dateien gelesen/geschrieben werden sollen. Die Memory-Schicht ist das, was Claude Code erlaubt, Lehren über Sessions hinweg anzusammeln, anstatt sie jedes Mal neu zu entdecken. Wenn `--lang` nicht-englisch ist, wird der statische Fallback-Inhalt über Claude übersetzt, bevor er geschrieben wird. v2.1.0 fügt ein Gap-Fill für `skills/00.shared/MANIFEST.md` hinzu, falls Pass 3c es ausgelassen hat.
 
 ---
@@ -483,7 +527,7 @@ Das Pass-3-Prompt-Template enthält zudem einen **Phase-1-Block „Read Once, Ex
 ```
 your-project/
 │
-├── CLAUDE.md                          ← Claude-Code-Einstiegspunkt
+├── CLAUDE.md                          ← Claude-Code-Einstiegspunkt (deterministische 8-Abschnitt-Struktur, v2.2.0)
 │
 ├── .claude/
 │   └── rules/                         ← Glob-getriggerte Regeln
@@ -834,7 +878,14 @@ Nichts erforderlich — v2.1.0-Tools ignorieren `plan/`, wenn es fehlt oder leer
 
 ```
 pass-prompts/templates/
-├── common/                  # Gemeinsamer Header/Footer + pass4 + staging-override
+├── common/                  # gemeinsame header/footer + pass4 + staging-override + CLAUDE.md scaffold (v2.2.0)
+│   ├── header.md             # Rolle + Ausgabeformat-Direktive (alle Passes)
+│   ├── pass3-footer.md       # Post-Pass-3 health-check-Anweisung + 5 CRITICAL Guardrail-Blöcke (v2.2.0)
+│   ├── pass3-phase1.md       # „Read Once, Extract Facts"-Block mit Rules A-E (v2.1.0)
+│   ├── pass4.md              # Memory-Scaffolding-Prompt (v2.0.0)
+│   ├── staging-override.md   # Leitet .claude/rules/**-Schreibvorgänge auf .staged-rules/** um (v2.0.0)
+│   ├── claude-md-scaffold.md # Deterministische 8-Abschnitt-CLAUDE.md-Vorlage (v2.2.0)
+│   └── lang-instructions.json # Ausgabedirektiven pro Sprache (10 Sprachen)
 ├── java-spring/             # Java / Spring Boot
 ├── kotlin-spring/           # Kotlin / Spring Boot (CQRS, BFF, multi-module)
 ├── node-express/            # Node.js / Express
@@ -851,6 +902,8 @@ pass-prompts/templates/
 
 `plan-installer` erkennt Ihren Stack/Ihre Stacks automatisch und setzt dann typ-spezifische Prompts zusammen. NestJS, Vue/Nuxt, Vite SPA und Flask verwenden jeweils dedizierte Templates mit framework-spezifischen Analyse-Kategorien (z. B. `@Module`/`@Injectable`/Guards für NestJS; `<script setup>`/Pinia/useFetch für Vue; Client-Side-Routing/`VITE_`-Env für Vite; Blueprint/`app.factory`/Flask-SQLAlchemy für Flask). Für Multi-Stack-Projekte werden separate `pass1-backend-prompt.md` und `pass1-frontend-prompt.md` generiert, während `pass3-prompt.md` die Generierungsziele beider Stacks kombiniert. In v2.1.0 wird dem Pass-3-Template `common/pass3-phase1.md` (der „Read Once, Extract Facts"-Block mit Rules A–E) vorangestellt, bevor es pro Split-Mode-Stage zugeschnitten wird. Pass 4 verwendet unabhängig vom Stack das gemeinsame `common/pass4.md`-Template (Memory-Scaffolding).
 
+**In v2.2.0** bettet der Pass-3-Prompt zusätzlich `common/claude-md-scaffold.md` (die deterministische 8-Abschnitt-CLAUDE.md-Vorlage) inline zwischen dem phase1-Block und dem stack-spezifischen Körper ein — dies fixiert die Abschnittsstruktur, sodass generierte CLAUDE.md nicht zwischen Projekten abweichen, während der Inhalt weiterhin projektspezifisch angepasst wird. Vorlagen werden **English-first** geschrieben; die Sprachinjektion aus `lang-instructions.json` weist das LLM an, Abschnittstitel und Fließtext zum Emit-Zeitpunkt in die Zielausgabesprache zu übersetzen.
+
 ---
 
 ## Monorepo-Unterstützung
@@ -937,6 +990,12 @@ my-monorepo/                    ← Hier ausführen: npx claudeos-core init
 
 **„CLAUDEOS_SKIP_TRANSLATION=1 is set but --lang='ko' requires translation" InitError (v2.0.0)** — Sie haben die Test-only-Env-Var `CLAUDEOS_SKIP_TRANSLATION=1` in Ihrer Shell gesetzt (wahrscheinlich ein Rest aus CI-/Test-Setup) UND eine nicht-englische `--lang` gewählt. Diese Env-Var short-circuit den Übersetzungs-Pfad, von dem Pass 4's statischer Fallback und Gap-Fill für nicht-englischen Output abhängen. `init` erkennt den Konflikt beim Sprachwahl-Zeitpunkt und bricht sofort ab (anstatt mitten in Pass 4 mit einem verwirrenden verschachtelten Fehler zu crashen). Fix: Entweder `unset CLAUDEOS_SKIP_TRANSLATION` vor dem Ausführen oder `npx claudeos-core init --lang en` verwenden.
 
+**Warnung "⚠️ v2.2.0 upgrade detected" (v2.2.0)** — Deine existierende `CLAUDE.md` wurde mit einer Pre-v2.2.0-Version generiert. Die Standard-Resume-Mode-Regeneration wird existierende Dateien unter Rule B idempotency überspringen, daher werden die strukturellen Verbesserungen von v2.2.0 (8-Abschnitt-CLAUDE.md-Scaffold, Per-File-Paths in `40.infra/*`, `.env.example`-basierte Port-Genauigkeit, Section-8-Redesign mit `Common Rules & Memory (L4)` (neu gestaltet mit zwei Unterabschnitten: Common Rules · L4 Memory), `60.memory/*`-Rule-Zeile, forward-referenced `04.doc-writing-guide.md`) NICHT angewendet. Fix: Mit `npx claudeos-core init --force` erneut ausführen. Das überschreibt generierte Dateien (`CLAUDE.md`, `.claude/rules/`, `claudeos-core/standard/`, `claudeos-core/skills/`, `claudeos-core/guide/`) und bewahrt dabei `claudeos-core/memory/` (akkumulierte decision-log-, failure-patterns-Einträge — append-only). Committe das Projekt vorher, wenn du die Überschreibungen vor dem Akzeptieren diff-en möchtest.
+
+**Port in CLAUDE.md weicht von `.env.example` ab (v2.2.0)** — Der neue `.env`-Parser des Stack-Detectors (`lib/env-parser.js`) liest zuerst `.env.example` (kanonisch, committed), dann `.env`-Varianten als Fallback. Erkannte Port-Variablen: `PORT`, `VITE_PORT`, `VITE_DESKTOP_PORT`, `NEXT_PUBLIC_PORT`, `NUXT_PORT`, `DJANGO_PORT` usw. Für Spring Boot hat `server.port` aus `application.yml` weiterhin Vorrang vor `.env` (framework-native Config gewinnt). Wenn dein Projekt einen ungewöhnlichen Env-Variablennamen verwendet, benenne ihn auf eine anerkannte Konvention um oder stelle eine Issue-Anfrage zur Erweiterung von `PORT_VAR_KEYS`. Framework-Defaults (Vite 5173, Next.js 3000, Django 8000) werden nur verwendet, wenn sowohl direkte Detection als auch `.env` still bleiben.
+
+**Secret-Werte als `***REDACTED***` in generierten Docs (v2.2.0)** — Erwartetes Verhalten. Der `.env`-Parser von v2.2.0 redact-iert automatisch Werte von Variablen, die den Mustern `PASSWORD`/`SECRET`/`TOKEN`/`API_KEY`/`CREDENTIAL`/`PRIVATE_KEY` entsprechen, bevor sie irgendeinen Generator erreichen. Das ist Defense-in-Depth gegen versehentlich in `.env.example` committed Secrets. `DATABASE_URL` bleibt unverändert für Stack-Detector-DB-Identifikations-Back-Compat. Wenn du irgendwo in der generierten `CLAUDE.md` `***REDACTED***` siehst, ist das ein Bug — redact-ierte Werte sollten nicht in der Tabelle landen; bitte erstelle eine Issue. Nicht-sensible Runtime-Config (Port, Host, API Target, NODE_ENV usw.) kommt unverändert durch.
+
 ---
 
 ## Mitwirken
@@ -946,7 +1005,7 @@ Beiträge sind willkommen! Bereiche, in denen Hilfe am meisten benötigt wird:
 - **Neue 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-Beispiele (GitHub Actions bereits ausgeliefert — siehe `.github/workflows/test.yml`)
-- **Testabdeckung** — Erweiterung der Test-Suite (derzeit 563 Tests über 29 Test-Dateien, die Scanner, Stack-Erkennung, Domain-Grouping, Plan-Parsing, Prompt-Generierung, CLI-Selectors, Monorepo-Erkennung, Vite-SPA-Erkennung, Verifikations-Tools, L4-Memory-Scaffold, Pass-2-Resume-Validierung, Pass-3-Guards 1/2/3 (H1-Sentinel + H2-BOM-aware-Empty-File + strikter Stale-Marker-Unlink), Pass-3-Split-Mode-Batch-Unterteilung, Pass-3-Partial-Marker-Resume (v2.1.0), Pass-4-Marker-Content-Validierung + Stale-Marker-Unlink-Striktheit + 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-Regressions-Suite (v2.1.0), Memory-Score/Compact-Formatting-Regression (v2.1.0) und AI-Work-Rules-Template-Struktur abdecken)
+- **Testabdeckung** — Erweiterung der Test-Suite (derzeit 602 Tests über 30 Test-Dateien, die Scanner, Stack-Erkennung, Domain-Grouping, Plan-Parsing, Prompt-Generierung, CLI-Selectors, Monorepo-Erkennung, Vite-SPA-Erkennung, Verifikations-Tools, L4-Memory-Scaffold, Pass-2-Resume-Validierung, Pass-3-Guards 1/2/3 (H1-Sentinel + H2-BOM-aware-Empty-File + strikter Stale-Marker-Unlink), Pass-3-Split-Mode-Batch-Unterteilung, Pass-3-Partial-Marker-Resume (v2.1.0), Pass-4-Marker-Content-Validierung + Stale-Marker-Unlink-Striktheit + 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-Regressions-Suite (v2.1.0), Memory-Score/Compact-Formatting-Regression (v2.1.0) und AI-Work-Rules-Template-Struktur und `.env`-Parser Port/Host/API-Target-Extraktion + Redaction sensibler Variablen (v2.2.0) abdecken)
 
 Siehe [`CONTRIBUTING.md`](./CONTRIBUTING.md) für die vollständige Liste der Bereiche, den Code-Style, die Commit-Konvention und die Schritt-für-Schritt-Anleitung zum Hinzufügen eines neuen Stack-Templates.
 

package/README.es.md

@@ -69,6 +69,38 @@ Esta diferencia se acumula. 10 tareas/día × 20 minutos ahorrados = **más de 3
 
 ---
 
+## Aseguramiento de Calidad Post-Generación (v2.3.0)
+
+La generación es solo la mitad del problema. La otra mitad es **saber que la salida es correcta** — a través de 10 idiomas de salida, 11 plantillas de stack y proyectos de cualquier tamaño. v2.3.0 añade dos validadores deterministas que se ejecutan después de la generación y no dependen de auto-verificaciones del LLM.
+
+### `claude-md-validator` — invariantes estructurales
+
+Cada `CLAUDE.md` generado se verifica contra 25 invariantes estructurales que usan solo señales independientes del idioma: sintaxis markdown (`^## `, `^### `), nombres de archivo literales (`decision-log.md`, `failure-patterns.md` — nunca traducidos), recuento de secciones, recuento de sub-secciones por sección y recuento de filas de tabla. El mismo validador, byte por byte, produce veredictos idénticos sobre un `CLAUDE.md` generado en inglés, coreano, japonés, vietnamita, hindi, ruso, español, chino, francés o alemán.
+
+La garantía cross-idioma se verifica mediante fixtures de prueba en los 10 idiomas, incluyendo fixtures de casos malos en 6 de esos idiomas que producen firmas de error idénticas. Cuando un invariante falla en un proyecto en vietnamita, la solución es la misma que cuando falla en un proyecto en alemán.
+
+### `content-validator [10/10]` — verificación de afirmaciones de ruta y consistencia de MANIFEST
+
+Lee toda referencia de ruta entre backticks (`src/...`, `.claude/rules/...`, `claudeos-core/skills/...`) de todos los archivos `.md` generados y las verifica contra el sistema de archivos real. Captura dos clases de fallo de LLM que ninguna herramienta detectaba antes:
+
+- **`STALE_PATH`** — cuando Pass 3 o Pass 4 inventa una ruta plausible pero inexistente. Casos típicos: inferir `featureRoutePath.ts` de una constante TypeScript llamada `FEATURE_ROUTE_PATH` cuando el archivo real es `routePath.ts`; asumir `src/main.tsx` por convención de Vite en un proyecto multi-entry; asumir `src/__mocks__/handlers.ts` por la documentación de MSW aunque el proyecto no tenga tests.
+- **`MANIFEST_DRIFT`** — cuando `claudeos-core/skills/00.shared/MANIFEST.md` registra un skill que `CLAUDE.md §6` no menciona (o viceversa). Reconoce el layout común orchestrator + sub-skills donde `CLAUDE.md §6` es un punto de entrada y `MANIFEST.md` es el registro completo — los sub-skills se consideran cubiertos vía su orchestrator padre.
+
+El validador se empareja con prevención en tiempo de prompt en `pass3-footer.md` y `pass4.md`: bloques de anti-patrón que documentan las clases específicas de alucinación (prefijo de directorio padre, convenciones de bibliotecas Vite/MSW/Vitest/Jest/RTL) y guía positiva explícita para definir el alcance de las reglas por directorio cuando un nombre de archivo concreto no está en `pass3a-facts.md`.
+
+### Ejecutar validación en cualquier proyecto
+
+```bash
+npx claudeos-core health     # todos los validadores — veredicto único go/no-go
+npx claudeos-core lint       # solo invariantes estructurales de CLAUDE.md (cualquier idioma)
+```
+
+### Verificación en el mundo real
+
+v2.3.0 fue validado end-to-end en dos proyectos hermanos reales en coreano antes del lanzamiento: un frontend Vite + React 19 single-SPA con 14 dominios y un orchestrator `scaffold-page-feature` de 8 sub-skills, y un backend Spring Boot + MyBatis con 8 dominios y un orchestrator `scaffold-crud-feature` de 8 sub-skills en plena migración PostgreSQL → MariaDB. Ambos se asentaron en **0 errores, 0 advertencias** en el health check completo — `STALE_PATH` 0, `MANIFEST_DRIFT` 0, 25/25 invariantes estructurales pasando — sin ninguna edición manual sobre la salida generada.
+
+---
+
 ## Stacks Soportados
 
 | Stack | Detección | Profundidad de análisis |
@@ -85,10 +117,20 @@ Esta diferencia se acumula. 10 tareas/día × 20 minutos ahorrados = **más de 3
 | **Vite / React SPA** | `package.json`, `vite.config.*` | 9 categorías, 55 sub-ítems |
 | **Angular** | `package.json`, `angular.json` | 12 categorías, 78 sub-ítems |
 
-Auto-detectado: lenguaje y versión, framework y versión (incluyendo Vite como framework SPA), ORM (MyBatis, JPA, Exposed, Prisma, TypeORM, SQLAlchemy, etc.), base de datos (PostgreSQL, MySQL, Oracle, MongoDB, SQLite), gestor de paquetes (Gradle, Maven, npm, yarn, pnpm, pip, poetry), arquitectura (CQRS, BFF — a partir de los nombres de módulos), estructura multi-módulo (desde settings.gradle), monorepo (Turborepo, pnpm-workspace, Lerna, npm/yarn workspaces).
+Auto-detectado: lenguaje y versión, framework y versión (incluyendo Vite como framework SPA), ORM (MyBatis, JPA, Exposed, Prisma, TypeORM, SQLAlchemy, etc.), base de datos (PostgreSQL, MySQL, Oracle, MongoDB, SQLite), gestor de paquetes (Gradle, Maven, npm, yarn, pnpm, pip, poetry), arquitectura (CQRS, BFF — a partir de los nombres de módulos), estructura multi-módulo (desde settings.gradle), monorepo (Turborepo, pnpm-workspace, Lerna, npm/yarn workspaces), **configuración de runtime desde `.env.example`** (v2.2.0 — extrae port/host/API-target de más de 16 nombres de variable convencionales a través de frameworks Vite · Next.js · Nuxt · Angular · Node · Python).
 
 **No tienes que especificar nada. Todo se detecta automáticamente.**
 
+### Configuración de runtime desde `.env` (v2.2.0)
+
+v2.2.0 añade `lib/env-parser.js` para que el `CLAUDE.md` generado refleje lo que el proyecto declara realmente, en vez de los valores por defecto del framework.
+
+- **Orden de búsqueda**: `.env.example` (canónico, commiteado) → `.env.local.example` → `.env.sample` → `.env.template` → `.env` → `.env.local` → `.env.development`. La variante `.example` gana porque es la forma-de-verdad neutral para desarrolladores, no los overrides locales de un contribuidor concreto.
+- **Convenciones de variable de puerto reconocidas**: `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` genérico. Los nombres específicos de framework ganan sobre `PORT` genérico cuando ambos están presentes.
+- **Host y API target**: `VITE_DEV_HOST` / `VITE_API_TARGET` / `NEXT_PUBLIC_API_URL` / `NUXT_PUBLIC_API_BASE` / `BACKEND_URL` / `PROXY_TARGET`, etc.
+- **Precedencia**: `server.port` de `application.yml` de Spring Boot sigue ganando (config framework-native), luego el puerto declarado en `.env`, y finalmente el valor por defecto del framework (Vite 5173, Next.js 3000, Django 8000, etc.) como último recurso.
+- **Redacción de variables sensibles**: los valores de variables que coinciden con patrones `PASSWORD` / `SECRET` / `TOKEN` / `API_KEY` / `ACCESS_KEY` / `PRIVATE_KEY` / `CREDENTIAL` / `JWT_SECRET` / `CLIENT_SECRET` / `SESSION_SECRET` / `BEARER` / `SALT` se sustituyen por `***REDACTED***` antes de llegar a cualquier generador downstream. Defense-in-depth contra secretos commiteados accidentalmente en `.env.example`. `DATABASE_URL` se incluye explícitamente en la lista blanca para retrocompatibilidad con la identificación de DB del stack-detector.
+
 ### Detección de Dominios Java (5 patrones con fallback)
 
 | Prioridad | Patrón | Estructura | Ejemplo |
@@ -364,7 +406,7 @@ cat claudeos-core/generated/pass4-prompt.md \
 
 **Verificar:** `claudeos-core/memory/` debe contener 4 archivos (`decision-log.md`, `failure-patterns.md`, `compaction.md`, `auto-rule-update.md`), `.claude/rules/60.memory/` debe contener 4 archivos de reglas, y `CLAUDE.md` debe tener ahora una sección `## Memory (L4)` añadida. Marcador: `claudeos-core/generated/pass4-memory.json`.
 
-> **Gap-fill v2.1.0:** Pass 4 también asegura que `claudeos-core/skills/00.shared/MANIFEST.md` exista. Si Pass 3c lo omitió (posible en proyectos skill-sparse porque las plantillas `pass3.md` de cada stack listan `MANIFEST.md` entre los targets de generación sin marcarlo como REQUIRED), el gap-fill crea un stub mínimo para que `.claude/rules/50.sync/03.skills-sync.md` siempre tenga un target de referencia válido. Idempotente: omite el paso si el archivo ya tiene contenido real (>20 caracteres).
+> **Gap-fill v2.1.0:** Pass 4 también asegura que `claudeos-core/skills/00.shared/MANIFEST.md` exista. Si Pass 3c lo omitió (posible en proyectos skill-sparse porque las plantillas `pass3.md` de cada stack listan `MANIFEST.md` entre los targets de generación sin marcarlo como REQUIRED), el gap-fill crea un stub mínimo para que `.claude/rules/50.sync/02.skills-sync.md` (ruta v2.2.0 — el número de reglas de sync se redujo de 3 a 2, por lo que lo que era `03` ahora es `02`) siempre tenga un target de referencia válido. Idempotente: omite el paso si el archivo ya tiene contenido real (>20 caracteres).
 
 > **Nota:** Si `claude -p` falla o `pass4-prompt.md` está ausente, el pipeline automatizado cae a un scaffold estático vía `lib/memory-scaffold.js` (con traducción por Claude cuando `--lang` no es inglés). El fallback estático solo se ejecuta dentro de `npx claudeos-core init` — el modo manual requiere que Pass 4 tenga éxito.
 
@@ -474,6 +516,8 @@ La plantilla de prompt de Pass 3 también incluye un **bloque Phase 1 "Read Once
 - **Rule D** — Concisión de salida: una línea (`[WRITE]`/`[SKIP]`) entre escrituras de archivo, sin restatear la tabla de hechos, sin echoar el contenido del archivo.
 - **Rule E** — Comprobación idempotente por lote: un único `Glob` al inicio de PHASE 2 en vez de llamadas `Read` por cada target.
 
+En **v2.2.0**, Pass 3 también incrusta en línea un scaffold CLAUDE.md determinista (`pass-prompts/templates/common/claude-md-scaffold.md`) en el prompt. Esto fija los títulos y el orden de las 8 secciones de nivel superior para que el `CLAUDE.md` generado no se desvíe entre proyectos, mientras que el contenido de cada sección sigue adaptándose a cada proyecto. El nuevo parser `.env` del stack-detector (`lib/env-parser.js`) suministra `stack.envInfo` al prompt para que las filas de port/host/API target coincidan con lo que el proyecto realmente declara en lugar de los valores por defecto del framework.
+
 **Pass 4** scaffoldea la capa Memory L4: archivos persistentes de conocimiento de equipo (decision-log, failure-patterns, compaction policy, auto-rule-update) más las reglas `60.memory/` que indican a sesiones futuras cuándo y cómo leer/escribir esos archivos. La capa de memory es lo que permite que Claude Code acumule lecciones entre sesiones en lugar de redescubrirlas cada vez. Cuando `--lang` no es inglés, el contenido estático de fallback se traduce vía Claude antes de ser escrito. v2.1.0 añade un gap-fill para `skills/00.shared/MANIFEST.md` por si Pass 3c lo omitió.
 
 ---
@@ -483,7 +527,7 @@ La plantilla de prompt de Pass 3 también incluye un **bloque Phase 1 "Read Once
 ```
 your-project/
 │
-├── CLAUDE.md                          ← Punto de entrada de Claude Code
+├── CLAUDE.md                          ← Punto de entrada de Claude Code (estructura determinista de 8 secciones, v2.2.0)
 │
 ├── .claude/
 │   └── rules/                         ← Reglas disparadas por glob
@@ -833,7 +877,14 @@ Nada requerido — las herramientas de v2.1.0 ignoran `plan/` cuando está ausen
 
 ```
 pass-prompts/templates/
-├── common/                  # Header/footer compartido + pass4 + staging-override
+├── common/                  # header/footer compartidos + pass4 + staging-override + CLAUDE.md scaffold (v2.2.0)
+│   ├── header.md             # Rol + directiva de formato de salida (todas las passes)
+│   ├── pass3-footer.md       # Instrucción post-Pass-3 health-check + 5 bloques CRITICAL de guardrails (v2.2.0)
+│   ├── pass3-phase1.md       # Bloque "Read Once, Extract Facts" con Rules A-E (v2.1.0)
+│   ├── pass4.md              # Prompt de scaffolding de memoria (v2.0.0)
+│   ├── staging-override.md   # Redirige escrituras .claude/rules/** a .staged-rules/** (v2.0.0)
+│   ├── claude-md-scaffold.md # Plantilla CLAUDE.md determinista de 8 secciones (v2.2.0)
+│   └── lang-instructions.json # Directivas de salida por idioma (10 idiomas)
 ├── java-spring/             # Java / Spring Boot
 ├── kotlin-spring/           # Kotlin / Spring Boot (CQRS, BFF, multi-módulo)
 ├── node-express/            # Node.js / Express
@@ -850,6 +901,8 @@ pass-prompts/templates/
 
 `plan-installer` auto-detecta tu stack(s), y luego ensambla prompts específicos del tipo. NestJS, Vue/Nuxt, Vite SPA y Flask usan cada uno plantillas dedicadas con categorías de análisis específicas del framework (ej: `@Module`/`@Injectable`/Guards para NestJS; `<script setup>`/Pinia/useFetch para Vue; client-side routing/`VITE_` env para Vite; Blueprint/`app.factory`/Flask-SQLAlchemy para Flask). Para proyectos multi-stack, se generan `pass1-backend-prompt.md` y `pass1-frontend-prompt.md` por separado, mientras que `pass3-prompt.md` combina los targets de generación de ambos stacks. En v2.1.0, la plantilla de Pass 3 se anteanteponte con `common/pass3-phase1.md` (el bloque "Read Once, Extract Facts" con Rules A–E) antes de ser troceada por etapa en modo split. Pass 4 usa la plantilla compartida `common/pass4.md` (memory scaffolding) independientemente del stack.
 
+**En v2.2.0**, el prompt de Pass 3 también incrusta en línea `common/claude-md-scaffold.md` (la plantilla CLAUDE.md determinista de 8 secciones) entre el bloque phase1 y el cuerpo específico del stack — esto fija la estructura de secciones para que los CLAUDE.md generados no se desvíen entre proyectos, mientras el contenido se adapta por proyecto. Las plantillas se escriben **English-first**; la inyección de idioma desde `lang-instructions.json` instruye al LLM a traducir títulos de sección y prosa al idioma de salida objetivo en tiempo de emisión.
+
 ---
 
 ## Soporte de Monorepo
@@ -936,6 +989,12 @@ my-monorepo/                    ← Ejecuta aquí: npx claudeos-core init
 
 **"CLAUDEOS_SKIP_TRANSLATION=1 is set but --lang='ko' requires translation" InitError (v2.0.0)** — Tienes la variable de entorno de solo-test `CLAUDEOS_SKIP_TRANSLATION=1` configurada en tu shell (probablemente un resto de setup de CI/test) Y elegiste un `--lang` no-inglés. Esta env var cortocircuita el path de traducción del que dependen el fallback estático y el gap-fill de Pass 4 para la salida no-inglesa. `init` detecta el conflicto en el momento de la selección de idioma y aborta inmediatamente (en vez de crashear a mitad de Pass 4 con un error anidado confuso). Solución: o bien `unset CLAUDEOS_SKIP_TRANSLATION` antes de ejecutar, o usa `npx claudeos-core init --lang en`.
 
+**Advertencia "⚠️ v2.2.0 upgrade detected" (v2.2.0)** — Tu `CLAUDE.md` existente fue generado con una versión anterior a v2.2.0. La regeneración en modo resume por defecto omitirá los archivos existentes bajo Rule B idempotency, por lo que las mejoras estructurales de v2.2.0 (scaffold CLAUDE.md de 8 secciones, paths por archivo en `40.infra/*`, precisión de puerto basada en `.env.example`, rediseño de Section 8 `Common Rules & Memory (L4)` (rediseñado con dos sub-secciones: Common Rules · L4 Memory), fila de regla `60.memory/*`, `04.doc-writing-guide.md` con forward-reference) NO se aplicarían. Solución: vuelve a ejecutar con `npx claudeos-core init --force`. Sobrescribe los archivos generados (`CLAUDE.md`, `.claude/rules/`, `claudeos-core/standard/`, `claudeos-core/skills/`, `claudeos-core/guide/`) preservando `claudeos-core/memory/` (decision-log, failure-patterns acumulados — append-only). Haz commit del proyecto antes si quieres revisar el diff de las sobrescrituras.
+
+**El puerto en CLAUDE.md difiere de `.env.example` (v2.2.0)** — El nuevo parser `.env` del stack-detector (`lib/env-parser.js`) lee `.env.example` primero (canónico, commiteado), luego variantes `.env` como fallback. Variables de puerto reconocidas: `PORT`, `VITE_PORT`, `VITE_DESKTOP_PORT`, `NEXT_PUBLIC_PORT`, `NUXT_PORT`, `DJANGO_PORT`, etc. Para Spring Boot, `server.port` de `application.yml` sigue teniendo prioridad sobre `.env` (config framework-native gana). Si tu proyecto usa un nombre de var env inusual, renómbralo a una convención reconocida o abre un issue para extender `PORT_VAR_KEYS`. Los valores por defecto del framework (Vite 5173, Next.js 3000, Django 8000) se usan solo cuando tanto la detección directa como `.env` están silenciosos.
+
+**Valores secretos redactados como `***REDACTED***` en docs generados (v2.2.0)** — Comportamiento esperado. El parser `.env` de v2.2.0 redacta automáticamente valores de variables que coinciden con patrones `PASSWORD`/`SECRET`/`TOKEN`/`API_KEY`/`CREDENTIAL`/`PRIVATE_KEY` antes de que lleguen a cualquier generador. Esto es defense-in-depth contra secretos commiteados accidentalmente en `.env.example`. `DATABASE_URL` se mantiene tal cual por back-compat de identificación de DB en stack-detector. Si ves `***REDACTED***` en algún lugar del `CLAUDE.md` generado, es un bug — los valores redactados no deberían llegar a la tabla; por favor reporta un issue. La config runtime no sensible (port, host, API target, NODE_ENV, etc.) pasa sin cambios.
+
 ---
 
 ## Contribuir
@@ -945,7 +1004,7 @@ my-monorepo/                    ← Ejecuta aquí: npx claudeos-core init
 - **Nuevas plantillas de stack** — Ruby/Rails, Go (Gin/Fiber/Echo), PHP (Laravel/Symfony), Rust (Axum/Actix), Svelte/SvelteKit, Remix
 - **Integración IDE** — extensión de VS Code, plugin de IntelliJ
 - **Plantillas de CI/CD** — GitLab CI, CircleCI, ejemplos de Jenkins (GitHub Actions ya incluido — ver `.github/workflows/test.yml`)
-- **Test coverage** — Ampliar la suite de tests (actualmente 563 tests en 29 archivos de test cubriendo scanners, stack detection, domain grouping, plan parsing, prompt generation, CLI selectors, monorepo detection, Vite SPA detection, verification tools, memory scaffold L4, validación de resume de Pass 2, Pass 3 Guards 1/2/3 (H1 sentinel + H2 BOM-aware empty-file + estricto stale-marker unlink), sub-división por lotes de Pass 3 en modo split, resume de Pass 3 con marcador parcial (v2.1.0), validación del contenido del marcador de Pass 4 + rigor del stale-marker unlink + gap-fill de scaffoldSkillsManifest (v2.1.0), guard env-skip de traducción + early fail-fast + workflow CI, movimiento de staged-rules, fallback lang-aware de traducción, suite de regresión por eliminación de master plan (v2.1.0), regresión de formato de memory score/compact (v2.1.0), y estructura de la plantilla AI Work Rules)
+- **Test coverage** — Ampliar la suite de tests (actualmente 602 tests en 30 archivos de test cubriendo scanners, stack detection, domain grouping, plan parsing, prompt generation, CLI selectors, monorepo detection, Vite SPA detection, verification tools, memory scaffold L4, validación de resume de Pass 2, Pass 3 Guards 1/2/3 (H1 sentinel + H2 BOM-aware empty-file + estricto stale-marker unlink), sub-división por lotes de Pass 3 en modo split, resume de Pass 3 con marcador parcial (v2.1.0), validación del contenido del marcador de Pass 4 + rigor del stale-marker unlink + gap-fill de scaffoldSkillsManifest (v2.1.0), guard env-skip de traducción + early fail-fast + workflow CI, movimiento de staged-rules, fallback lang-aware de traducción, suite de regresión por eliminación de master plan (v2.1.0), regresión de formato de memory score/compact (v2.1.0), y estructura de la plantilla AI Work Rules, y extracción de port/host/API-target del parser `.env` + redacción de variables sensibles (v2.2.0))
 
 Ver [`CONTRIBUTING.md`](./CONTRIBUTING.md) para la lista completa de áreas, estilo de código, convención de commits y la guía paso a paso para añadir una nueva plantilla de stack.