claudeos-core 2.1.1 → 2.3.0

package/README.fr.md

@@ -69,6 +69,38 @@ Cette différence se cumule. 10 tâches/jour × 20 minutes économisées = **plu
 
 ---
 
+## Assurance qualité post-génération (v2.3.0)
+
+La génération n'est que la moitié du problème. L'autre moitié est **savoir que la sortie est correcte** — à travers 10 langues de sortie, 11 templates de stack et des projets de toute taille. v2.3.0 ajoute deux validateurs déterministes qui s'exécutent après la génération et qui ne dépendent pas d'auto-vérifications du LLM.
+
+### `claude-md-validator` — invariants structurels
+
+Chaque `CLAUDE.md` généré est vérifié par rapport à 25 invariants structurels qui n'utilisent que des signaux indépendants de la langue : syntaxe markdown (`^## `, `^### `), noms de fichiers littéraux (`decision-log.md`, `failure-patterns.md` — jamais traduits), nombre de sections, nombre de sous-sections par section, nombre de lignes de table. Le même validateur, octet pour octet, produit des verdicts identiques sur un `CLAUDE.md` généré en anglais, coréen, japonais, vietnamien, hindi, russe, espagnol, chinois, français ou allemand.
+
+La garantie cross-langue est vérifiée par des fixtures de test dans les 10 langues, y compris des fixtures bad-case dans 6 de ces langues qui produisent des signatures d'erreur identiques. Lorsqu'un invariant échoue sur un projet en vietnamien, la correction est la même que lorsqu'il échoue sur un projet en allemand.
+
+### `content-validator [10/10]` — vérification des revendications de chemin et cohérence MANIFEST
+
+Lit chaque référence de chemin entre backticks (`src/...`, `.claude/rules/...`, `claudeos-core/skills/...`) dans tous les fichiers `.md` générés et les vérifie contre le vrai système de fichiers. Attrape deux classes d'échecs LLM que aucun outil ne détectait auparavant :
+
+- **`STALE_PATH`** — quand Pass 3 ou Pass 4 fabrique un chemin plausible mais inexistant. Cas typiques : déduire `featureRoutePath.ts` d'une constante TypeScript nommée `FEATURE_ROUTE_PATH` alors que le fichier réel est `routePath.ts` ; supposer `src/main.tsx` par convention Vite dans un projet multi-entry ; supposer `src/__mocks__/handlers.ts` d'après la documentation MSW même quand le projet n'a aucun test.
+- **`MANIFEST_DRIFT`** — quand `claudeos-core/skills/00.shared/MANIFEST.md` enregistre un skill que `CLAUDE.md §6` ne mentionne pas (ou inversement). Reconnaît le layout courant orchestrator + sub-skills où `CLAUDE.md §6` est un point d'entrée et `MANIFEST.md` est le registre complet — les sub-skills sont considérés couverts via leur orchestrator parent.
+
+Le validateur est couplé à une prévention au moment du prompt dans `pass3-footer.md` et `pass4.md` : des blocs anti-pattern documentant les classes spécifiques d'hallucination (préfixe de répertoire parent, conventions de bibliothèques Vite/MSW/Vitest/Jest/RTL) et une guidance positive explicite pour scope les règles par répertoire quand un nom de fichier concret n'est pas dans `pass3a-facts.md`.
+
+### Exécuter la validation sur n'importe quel projet
+
+```bash
+npx claudeos-core health     # tous les validateurs — verdict go/no-go unique
+npx claudeos-core lint       # uniquement les invariants structurels de CLAUDE.md (n'importe quelle langue)
+```
+
+### Vérification en conditions réelles
+
+v2.3.0 a été validé end-to-end avant la release sur deux projets frères coréens réels : un frontend single-SPA Vite + React 19 avec 14 domaines et un orchestrator `scaffold-page-feature` à 8 sub-skills, et un backend Spring Boot + MyBatis avec 8 domaines et un orchestrator `scaffold-crud-feature` à 8 sub-skills en pleine migration PostgreSQL → MariaDB. Les deux se sont stabilisés à **0 erreurs, 0 avertissements** sur le health check complet — `STALE_PATH` 0, `MANIFEST_DRIFT` 0, 25/25 invariants structurels passent — sans aucune édition manuelle de la sortie générée.
+
+---
+
 ## Stacks Supportés
 
 | Stack | Détection | Profondeur d'analyse |
@@ -85,10 +117,20 @@ Cette différence se cumule. 10 tâches/jour × 20 minutes économisées = **plu
 | **Vite / React SPA** | `package.json`, `vite.config.*` | 9 catégories, 55 sous-éléments |
 | **Angular** | `package.json`, `angular.json` | 12 catégories, 78 sous-éléments |
 
-Auto-détecté : langage et version, framework et version (y compris Vite en tant que framework SPA), ORM (MyBatis, JPA, Exposed, Prisma, TypeORM, SQLAlchemy, etc.), base de données (PostgreSQL, MySQL, Oracle, MongoDB, SQLite), gestionnaire de paquets (Gradle, Maven, npm, yarn, pnpm, pip, poetry), architecture (CQRS, BFF — à partir des noms de modules), structure multi-module (depuis settings.gradle), monorepo (Turborepo, pnpm-workspace, Lerna, npm/yarn workspaces).
+Auto-détecté : langage et version, framework et version (y compris Vite en tant que framework SPA), ORM (MyBatis, JPA, Exposed, Prisma, TypeORM, SQLAlchemy, etc.), base de données (PostgreSQL, MySQL, Oracle, MongoDB, SQLite), gestionnaire de paquets (Gradle, Maven, npm, yarn, pnpm, pip, poetry), architecture (CQRS, BFF — à partir des noms de modules), structure multi-module (depuis settings.gradle), monorepo (Turborepo, pnpm-workspace, Lerna, npm/yarn workspaces), **configuration runtime depuis `.env.example`** (v2.2.0 — extraction de port/host/API-target à partir de plus de 16 noms de variables conventionnelles parmi les frameworks Vite · Next.js · Nuxt · Angular · Node · Python).
 
 **Vous n'avez rien à spécifier. Tout est détecté automatiquement.**
 
+### Configuration runtime pilotée par `.env` (v2.2.0)
+
+v2.2.0 ajoute `lib/env-parser.js` pour que le `CLAUDE.md` généré reflète ce que le projet déclare réellement plutôt que les defaults framework.
+
+- **Ordre de recherche** : `.env.example` (canonique, commité) → `.env.local.example` → `.env.sample` → `.env.template` → `.env` → `.env.local` → `.env.development`. La variante `.example` l'emporte parce qu'elle est la shape-of-truth neutre côté développeur, et non les overrides locaux d'un contributeur particulier.
+- **Conventions de variables de port reconnues** : `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` générique. Les noms spécifiques au framework l'emportent sur le `PORT` générique quand les deux sont présents.
+- **Host & API target** : `VITE_DEV_HOST` / `VITE_API_TARGET` / `NEXT_PUBLIC_API_URL` / `NUXT_PUBLIC_API_BASE` / `BACKEND_URL` / `PROXY_TARGET`, etc.
+- **Priorité** : le `server.port` de `application.yml` Spring Boot gagne toujours (config framework-native), puis le port déclaré dans `.env`, puis le default framework (Vite 5173, Next.js 3000, Django 8000, etc.) en dernier recours.
+- **Redaction des variables sensibles** : les valeurs des variables correspondant aux patterns `PASSWORD` / `SECRET` / `TOKEN` / `API_KEY` / `ACCESS_KEY` / `PRIVATE_KEY` / `CREDENTIAL` / `JWT_SECRET` / `CLIENT_SECRET` / `SESSION_SECRET` / `BEARER` / `SALT` sont remplacées par `***REDACTED***` avant d'atteindre n'importe quel générateur en aval. Defense-in-depth contre les secrets accidentellement commités dans `.env.example`. `DATABASE_URL` est explicitement whitelisté pour la back-compat d'identification BD du stack-detector.
+
 ### Détection des Domaines Java (5 patterns avec fallback)
 
 | Priorité | Pattern | Structure | Exemple |
@@ -364,7 +406,7 @@ cat claudeos-core/generated/pass4-prompt.md \
 
 **Vérifier :** `claudeos-core/memory/` doit contenir 4 fichiers (`decision-log.md`, `failure-patterns.md`, `compaction.md`, `auto-rule-update.md`), `.claude/rules/60.memory/` doit contenir 4 fichiers de règles, et `CLAUDE.md` doit désormais avoir une section `## Memory (L4)` ajoutée. Marqueur : `claudeos-core/generated/pass4-memory.json`.
 
-> **Gap-fill v2.1.0 :** Pass 4 garantit aussi que `claudeos-core/skills/00.shared/MANIFEST.md` existe. Si Pass 3c l'a omis (possible sur les projets skill-sparse car les templates `pass3.md` par stack listent `MANIFEST.md` parmi les cibles de génération sans le marquer REQUIRED), le gap-fill crée un stub minimal pour que `.claude/rules/50.sync/03.skills-sync.md` ait toujours une cible de référence valide. Idempotent : saute si le fichier a déjà du contenu réel (>20 caractères).
+> **Gap-fill v2.1.0 :** Pass 4 garantit aussi que `claudeos-core/skills/00.shared/MANIFEST.md` existe. Si Pass 3c l'a omis (possible sur les projets skill-sparse car les templates `pass3.md` par stack listent `MANIFEST.md` parmi les cibles de génération sans le marquer REQUIRED), le gap-fill crée un stub minimal pour que `.claude/rules/50.sync/02.skills-sync.md` (chemin v2.2.0 — le nombre de règles sync est passé de 3 à 2, ce qui était `03` est devenu `02`) ait toujours une cible de référence valide. Idempotent : saute si le fichier a déjà du contenu réel (>20 caractères).
 
 > **Remarque :** Si `claude -p` échoue ou si `pass4-prompt.md` est absent, le pipeline automatisé retombe sur un scaffold statique via `lib/memory-scaffold.js` (avec traduction pilotée par Claude quand `--lang` n'est pas l'anglais). Le fallback statique ne tourne qu'à l'intérieur de `npx claudeos-core init` — le mode manuel exige que Pass 4 réussisse.
 
@@ -474,6 +516,8 @@ Le template de prompt Pass 3 inclut également un **bloc Phase 1 « Read Once, E
 - **Règle D** — Concision de sortie : une seule ligne (`[WRITE]`/`[SKIP]`) entre chaque écriture de fichier, pas de recopie de la table de faits, pas d'écho du contenu des fichiers.
 - **Règle E** — Vérification idempotente par batch : un seul `Glob` au début de PHASE 2 plutôt que des appels `Read` par cible.
 
+En **v2.2.0**, Pass 3 intègre également en ligne un scaffold CLAUDE.md déterministe (`pass-prompts/templates/common/claude-md-scaffold.md`) dans le prompt. Cela fixe les titres et l'ordre des 8 sections de premier niveau afin que le `CLAUDE.md` généré ne dérive plus entre projets, tandis que le contenu de chaque section continue de s'adapter à chaque projet. Le nouveau parser `.env` du stack-detector (`lib/env-parser.js`) fournit `stack.envInfo` au prompt pour que les lignes port/host/API target correspondent à ce que le projet déclare réellement plutôt qu'aux defaults du framework.
+
 **Pass 4** scaffolde la couche Memory L4 : fichiers persistants de connaissance d'équipe (decision-log, failure-patterns, politique de compaction, auto-rule-update) plus les règles `60.memory/` qui indiquent aux futures sessions quand et comment lire/écrire ces fichiers. La couche memory est ce qui permet à Claude Code d'accumuler des leçons entre les sessions au lieu de les redécouvrir à chaque fois. Quand `--lang` n'est pas l'anglais, le contenu statique de fallback est traduit via Claude avant d'être écrit. v2.1.0 ajoute un gap-fill pour `skills/00.shared/MANIFEST.md` au cas où Pass 3c l'aurait omis.
 
 ---
@@ -483,7 +527,7 @@ Le template de prompt Pass 3 inclut également un **bloc Phase 1 « Read Once, E
 ```
 your-project/
 │
-├── CLAUDE.md                          ← Point d'entrée Claude Code
+├── CLAUDE.md                          ← Point d'entrée Claude Code (structure déterministe à 8 sections, v2.2.0)
 │
 ├── .claude/
 │   └── rules/                         ← Règles déclenchées par glob
@@ -833,7 +877,14 @@ Rien de requis — les outils v2.1.0 ignorent `plan/` quand il est absent ou vid
 
 ```
 pass-prompts/templates/
-├── common/                  # Header/footer partagés + pass4 + staging-override
+├── common/                  # header/footer partagés + pass4 + staging-override + CLAUDE.md scaffold (v2.2.0)
+│   ├── header.md             # Rôle + directive de format de sortie (toutes les passes)
+│   ├── pass3-footer.md       # Instruction health-check post-Pass-3 + 5 blocs CRITICAL de guardrails (v2.2.0)
+│   ├── pass3-phase1.md       # Bloc « Read Once, Extract Facts » avec Rules A-E (v2.1.0)
+│   ├── pass4.md              # Prompt de scaffolding mémoire (v2.0.0)
+│   ├── staging-override.md   # Redirige les écritures .claude/rules/** vers .staged-rules/** (v2.0.0)
+│   ├── claude-md-scaffold.md # Template CLAUDE.md déterministe à 8 sections (v2.2.0)
+│   └── lang-instructions.json # Directives de sortie par langue (10 langues)
 ├── java-spring/             # Java / Spring Boot
 ├── kotlin-spring/           # Kotlin / Spring Boot (CQRS, BFF, multi-module)
 ├── node-express/            # Node.js / Express
@@ -850,6 +901,8 @@ pass-prompts/templates/
 
 `plan-installer` auto-détecte votre(vos) stack(s), puis assemble des prompts spécifiques au type. NestJS, Vue/Nuxt, Vite SPA et Flask utilisent chacun des templates dédiés avec des catégories d'analyse spécifiques au framework (ex : `@Module`/`@Injectable`/Guards pour NestJS ; `<script setup>`/Pinia/useFetch pour Vue ; client-side routing/`VITE_` env pour Vite ; Blueprint/`app.factory`/Flask-SQLAlchemy pour Flask). Pour les projets multi-stack, des `pass1-backend-prompt.md` et `pass1-frontend-prompt.md` séparés sont générés, tandis que `pass3-prompt.md` combine les cibles de génération des deux stacks. En v2.1.0, le template Pass 3 est préfixé par `common/pass3-phase1.md` (le bloc « Read Once, Extract Facts » avec les Règles A–E) avant d'être tranché par stage en mode split. Pass 4 utilise le template partagé `common/pass4.md` (memory scaffolding) quel que soit le stack.
 
+**Dans v2.2.0**, le prompt Pass 3 intègre également en ligne `common/claude-md-scaffold.md` (le template CLAUDE.md déterministe à 8 sections) entre le bloc phase1 et le corps spécifique au stack — cela fixe la structure des sections afin que les CLAUDE.md générés ne dérivent pas entre projets, tout en laissant le contenu s'adapter à chaque projet. Les templates sont écrits **English-first** ; l'injection de langue depuis `lang-instructions.json` demande au LLM de traduire les titres de section et la prose dans la langue de sortie cible au moment de l'émission.
+
 ---
 
 ## Support Monorepo
@@ -936,6 +989,12 @@ my-monorepo/                    ← Lancez ici : npx claudeos-core init
 
 **« CLAUDEOS_SKIP_TRANSLATION=1 is set but --lang='ko' requires translation » InitError (v2.0.0)** — Vous avez la variable d'environnement réservée aux tests `CLAUDEOS_SKIP_TRANSLATION=1` définie dans votre shell (probablement un reste de setup CI/test) ET vous avez choisi un `--lang` non-anglais. Cette variable d'environnement court-circuite le chemin de traduction dont dépendent le fallback statique et le gap-fill de Pass 4 pour la sortie non-anglaise. `init` détecte le conflit au moment de la sélection de langue et s'avorte immédiatement (plutôt que de crasher en plein Pass 4 avec une erreur imbriquée confuse). Fix : soit `unset CLAUDEOS_SKIP_TRANSLATION` avant de lancer, soit utilisez `npx claudeos-core init --lang en`.
 
+**Avertissement "⚠️ v2.2.0 upgrade detected" (v2.2.0)** — Votre `CLAUDE.md` existant a été généré avec une version antérieure à v2.2.0. La régénération par défaut en mode resume ignorera les fichiers existants sous Rule B idempotency, donc les améliorations structurelles de v2.2.0 (scaffold CLAUDE.md à 8 sections, paths par fichier dans `40.infra/*`, précision du port basée sur `.env.example`, redesign de Section 8 `Common Rules & Memory (L4)` (repensée avec deux sous-sections : Common Rules · L4 Memory), ligne de règle `60.memory/*`, `04.doc-writing-guide.md` en forward-reference) NE seront PAS appliquées. Fix : relancez avec `npx claudeos-core init --force`. Cela écrase les fichiers générés (`CLAUDE.md`, `.claude/rules/`, `claudeos-core/standard/`, `claudeos-core/skills/`, `claudeos-core/guide/`) tout en préservant `claudeos-core/memory/` (decision-log, failure-patterns accumulés — append-only). Commitez le projet avant si vous voulez diff les écrasements avant acceptation.
+
+**Le port dans CLAUDE.md diffère de `.env.example` (v2.2.0)** — Le nouveau parser `.env` du stack-detector (`lib/env-parser.js`) lit d'abord `.env.example` (canonique, commité), puis les variantes `.env` en fallback. Variables de port reconnues : `PORT`, `VITE_PORT`, `VITE_DESKTOP_PORT`, `NEXT_PUBLIC_PORT`, `NUXT_PORT`, `DJANGO_PORT`, etc. Pour Spring Boot, `server.port` de `application.yml` a toujours la priorité sur `.env` (config framework-native gagne). Si votre projet utilise un nom de var env inhabituel, renommez-la selon une convention reconnue ou ouvrez une issue pour étendre `PORT_VAR_KEYS`. Les defaults framework (Vite 5173, Next.js 3000, Django 8000) ne sont utilisés que quand la détection directe et `.env` sont tous deux silencieux.
+
+**Valeurs secrètes redactées en `***REDACTED***` dans les docs générés (v2.2.0)** — Comportement attendu. Le parser `.env` v2.2.0 redacte automatiquement les valeurs des variables correspondant aux patterns `PASSWORD`/`SECRET`/`TOKEN`/`API_KEY`/`CREDENTIAL`/`PRIVATE_KEY` avant qu'elles n'atteignent un générateur. C'est du defense-in-depth contre les secrets accidentellement commités dans `.env.example`. `DATABASE_URL` reste tel quel pour la back-compat d'identification DB du stack-detector. Si vous voyez `***REDACTED***` quelque part dans le `CLAUDE.md` généré, c'est un bug — les valeurs redactées ne devraient pas atteindre le tableau ; veuillez ouvrir une issue. La config runtime non sensible (port, host, API target, NODE_ENV, etc.) passe sans modification.
+
 ---
 
 ## Contribuer
@@ -945,7 +1004,7 @@ Les contributions sont les bienvenues ! Les domaines où l'aide est la plus néc
 - **Nouveaux templates de stack** — Ruby/Rails, Go (Gin/Fiber/Echo), PHP (Laravel/Symfony), Rust (Axum/Actix), Svelte/SvelteKit, Remix
 - **Intégration IDE** — extension VS Code, plugin IntelliJ
 - **Templates CI/CD** — GitLab CI, CircleCI, exemples Jenkins (GitHub Actions déjà livré — voir `.github/workflows/test.yml`)
-- **Couverture de test** — Étendre la suite de tests (actuellement 563 tests à travers 29 fichiers de test couvrant scanners, stack detection, domain grouping, plan parsing, prompt generation, CLI selectors, monorepo detection, Vite SPA detection, outils de vérification, memory scaffold L4, validation de resume de Pass 2, Pass 3 Guards 1/2/3 (H1 sentinel + H2 BOM-aware empty-file + strict stale-marker unlink), sous-division en batches du mode split Pass 3, resume de marqueur partiel Pass 3 (v2.1.0), validation du contenu du marqueur Pass 4 + rigueur du stale-marker unlink + gap-fill scaffoldSkillsManifest (v2.1.0), guard d'env-skip de traduction + early fail-fast + workflow CI, déplacement de staged-rules, fallback lang-aware de traduction, suite de régression de suppression des master plans (v2.1.0), régression de formatage memory score/compact (v2.1.0), et structure du template AI Work Rules)
+- **Couverture de test** — Étendre la suite de tests (actuellement 602 tests à travers 30 fichiers de test couvrant scanners, stack detection, domain grouping, plan parsing, prompt generation, CLI selectors, monorepo detection, Vite SPA detection, outils de vérification, memory scaffold L4, validation de resume de Pass 2, Pass 3 Guards 1/2/3 (H1 sentinel + H2 BOM-aware empty-file + strict stale-marker unlink), sous-division en batches du mode split Pass 3, resume de marqueur partiel Pass 3 (v2.1.0), validation du contenu du marqueur Pass 4 + rigueur du stale-marker unlink + gap-fill scaffoldSkillsManifest (v2.1.0), guard d'env-skip de traduction + early fail-fast + workflow CI, déplacement de staged-rules, fallback lang-aware de traduction, suite de régression de suppression des master plans (v2.1.0), régression de formatage memory score/compact (v2.1.0), structure du template AI Work Rules, et extraction port/host/API-target du parser `.env` + redaction de variables sensibles (v2.2.0))
 
 Voir [`CONTRIBUTING.md`](./CONTRIBUTING.md) pour la liste complète des domaines, le style de code, la convention de commit et le guide pas à pas pour ajouter un nouveau template de stack.
 

package/README.hi.md

@@ -69,6 +69,38 @@ ClaudeOS-Core ऐसा डॉक्यूमेंटेशन बनाता
 
 ---
 
+## जेनरेशन के बाद गुणवत्ता सुनिश्चिति (v2.3.0)
+
+जेनरेशन समस्या का सिर्फ आधा हिस्सा है। दूसरा आधा है **यह जानना कि आउटपुट सही है** — 10 आउटपुट भाषाओं में, 11 स्टैक टेम्प्लेट्स में, किसी भी आकार के प्रोजेक्ट्स में। v2.3.0 दो deterministic validators जोड़ता है जो जेनरेशन के बाद चलते हैं और LLM के स्वयं-जांच पर निर्भर नहीं करते।
+
+### `claude-md-validator` — स्ट्रक्चरल इनवेरिएंट्स
+
+हर जेनरेट किया गया `CLAUDE.md` 25 स्ट्रक्चरल इनवेरिएंट्स के खिलाफ चेक किया जाता है, जो केवल भाषा-निरपेक्ष सिग्नल्स का उपयोग करते हैं: markdown syntax (`^## `, `^### `), कभी अनुवादित नहीं होने वाले literal फ़ाइल नाम (`decision-log.md`, `failure-patterns.md`), section count, प्रत्येक section के sub-section count, और table-row count। यही validator, byte-by-byte, अंग्रेज़ी, कोरियाई, जापानी, वियतनामी, हिंदी, रूसी, स्पेनिश, चीनी, फ्रेंच, या जर्मन में जेनरेट किए गए `CLAUDE.md` पर समान निर्णय देता है।
+
+Cross-language गारंटी को सभी 10 भाषाओं में test fixtures द्वारा सत्यापित किया जाता है, जिसमें उन भाषाओं में से 6 में bad-case fixtures शामिल हैं जो समान error signatures उत्पन्न करती हैं। जब एक वियतनामी प्रोजेक्ट पर invariant विफल होता है, तो fix वही है जो जर्मन प्रोजेक्ट पर विफल होने पर होता है।
+
+### `content-validator [10/10]` — path-claim सत्यापन और MANIFEST स्थिरता
+
+सभी जेनरेट की गई `.md` फ़ाइलों से हर backticked path reference (`src/...`, `.claude/rules/...`, `claudeos-core/skills/...`) पढ़ता है और उन्हें वास्तविक file system के खिलाफ सत्यापित करता है। दो क्लास की LLM failures पकड़ता है जो पहले कोई tool detect नहीं करता था:
+
+- **`STALE_PATH`** — जब Pass 3 या Pass 4 एक plausible-but-nonexistent path गढ़ देता है। विशिष्ट मामले: `FEATURE_ROUTE_PATH` नामक TypeScript constant से `featureRoutePath.ts` infer करना जब वास्तविक फ़ाइल `routePath.ts` है; multi-entry प्रोजेक्ट में Vite convention से `src/main.tsx` मान लेना; प्रोजेक्ट में कोई test नहीं होने के बावजूद MSW documentation से `src/__mocks__/handlers.ts` मान लेना।
+- **`MANIFEST_DRIFT`** — जब `claudeos-core/skills/00.shared/MANIFEST.md` एक skill रजिस्टर करता है जिसका `CLAUDE.md §6` में उल्लेख नहीं है (या इसके विपरीत)। सामान्य orchestrator + sub-skills layout को पहचानता है, जहाँ `CLAUDE.md §6` एक entry point है और `MANIFEST.md` पूर्ण registry है — sub-skills को उनके parent orchestrator के माध्यम से cover माना जाता है।
+
+Validator को `pass3-footer.md` और `pass4.md` में prompt-time prevention के साथ जोड़ा गया है: विशिष्ट hallucination classes (parent-directory prefix, Vite/MSW/Vitest/Jest/RTL library conventions) को document करने वाले anti-pattern blocks, और स्पष्ट positive guidance कि जब `pass3a-facts.md` में एक concrete filename नहीं है, तो rule को directory-scope से scope करें।
+
+### किसी भी प्रोजेक्ट पर validation चलाएँ
+
+```bash
+npx claudeos-core health     # सभी validators — एक single go/no-go verdict
+npx claudeos-core lint       # केवल CLAUDE.md structural invariants (किसी भी भाषा में)
+```
+
+### वास्तविक-दुनिया सत्यापन
+
+v2.3.0 को release से पहले दो वास्तविक कोरियाई sibling projects पर end-to-end validate किया गया था: एक 14-domain single-SPA Vite + React 19 frontend जिसमें 8 sub-skill `scaffold-page-feature` orchestrator है, और एक 8-domain Spring Boot + MyBatis backend जिसमें 8 sub-skill `scaffold-crud-feature` orchestrator है और PostgreSQL → MariaDB migration चल रहा है। दोनों पूर्ण health check पर **0 errors, 0 warnings** पर settle हुए — `STALE_PATH` 0, `MANIFEST_DRIFT` 0, 25/25 structural invariants pass — जेनरेटेड output पर कोई manual edit किए बिना।
+
+---
+
 ## सपोर्टेड स्टैक्स
 
 | स्टैक | डिटेक्शन | विश्लेषण गहराई |
@@ -85,10 +117,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), **`.env.example` runtime कॉन्फ़िगरेशन** (v2.2.0 — Vite · Next.js · Nuxt · Angular · Node · Python framework के 16+ convention variable नामों से port/host/API-target निकाला जाता है)।
 
 **आपको कुछ भी स्पेसिफाई करने की ज़रूरत नहीं। सब कुछ ऑटोमैटिकली डिटेक्ट होता है।**
 
+### `.env`-driven runtime कॉन्फ़िगरेशन (v2.2.0)
+
+v2.2.0 में `lib/env-parser.js` जोड़ा गया है ताकि जेनरेटेड `CLAUDE.md` framework defaults के बजाय वह दर्शाए जो project वास्तव में declare करता है।
+
+- **Search क्रम**: `.env.example` (canonical, committed) → `.env.local.example` → `.env.sample` → `.env.template` → `.env` → `.env.local` → `.env.development`। `.example` variant जीतता है क्योंकि यह developer-neutral shape-of-truth है, किसी एक contributor का local override नहीं।
+- **पहचाने जाने वाले port variable conventions**: `VITE_PORT` / `VITE_DEV_PORT` / `VITE_DESKTOP_PORT` / `NEXT_PUBLIC_PORT` / `NUXT_PORT` / `NG_PORT` / `APP_PORT` / `SERVER_PORT` / `HTTP_PORT` / `DEV_PORT` / `FLASK_RUN_PORT` / `UVICORN_PORT` / `DJANGO_PORT` / generic `PORT`। जब दोनों मौजूद हों, तो framework-specific नाम generic `PORT` पर जीतते हैं।
+- **Host और API target**: `VITE_DEV_HOST` / `VITE_API_TARGET` / `NEXT_PUBLIC_API_URL` / `NUXT_PUBLIC_API_BASE` / `BACKEND_URL` / `PROXY_TARGET` आदि।
+- **Precedence**: Spring Boot `application.yml` `server.port` अभी भी जीतता है (framework-native config), फिर `.env`-declared port, फिर last resort के रूप में framework default (Vite 5173, Next.js 3000, Django 8000, आदि)।
+- **Sensitive-variable redaction**: `PASSWORD` / `SECRET` / `TOKEN` / `API_KEY` / `ACCESS_KEY` / `PRIVATE_KEY` / `CREDENTIAL` / `JWT_SECRET` / `CLIENT_SECRET` / `SESSION_SECRET` / `BEARER` / `SALT` patterns से match होने वाले variables के values किसी भी downstream generator तक पहुंचने से पहले `***REDACTED***` से replace कर दिए जाते हैं। `.env.example` में accidentally committed secrets के खिलाफ defense-in-depth। `DATABASE_URL` stack-detector DB-identification back-compat के लिए explicitly whitelisted है।
+
 ### Java डोमेन डिटेक्शन (5 पैटर्न, फॉलबैक के साथ)
 
 | प्राथमिकता | पैटर्न | संरचना | उदाहरण |
@@ -364,7 +406,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 rule फ़ाइलें होनी चाहिए, और `CLAUDE.md` में एक `## Memory (L4)` section append होना चाहिए। Marker: `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` templates `MANIFEST.md` को generation targets में list करते हैं बिना REQUIRED मार्क किए), तो gap-fill एक minimal stub बनाता है ताकि `.claude/rules/50.sync/03.skills-sync.md` के पास हमेशा एक valid reference target हो। Idempotent: यदि फ़ाइल में पहले से real content (>20 chars) है तो skip करता है।
+> **v2.1.0 gap-fill:** Pass 4 यह भी सुनिश्चित करता है कि `claudeos-core/skills/00.shared/MANIFEST.md` मौजूद है। यदि Pass 3c ने इसे छोड़ दिया (skill-sparse प्रोजेक्ट्स पर संभव क्योंकि stack `pass3.md` templates `MANIFEST.md` को generation targets में list करते हैं बिना REQUIRED मार्क किए), तो gap-fill एक minimal stub बनाता है ताकि `.claude/rules/50.sync/02.skills-sync.md` (v2.2.0 पथ — sync rule की संख्या 3 से घटकर 2 हुई, `03` अब `02` है) के पास हमेशा एक valid reference target हो। Idempotent: यदि फ़ाइल में पहले से real content (>20 chars) है तो skip करता है।
 
 > **नोट:** यदि `claude -p` विफल हो जाता है या `pass4-prompt.md` गायब है, तो automated pipeline `lib/memory-scaffold.js` के माध्यम से static scaffold पर fallback करता है (जब `--lang` गैर-अंग्रेज़ी होता है तो Claude-driven translation के साथ)। Static fallback केवल `npx claudeos-core init` के अंदर चलता है — मैनुअल मोड के लिए Pass 4 का सफल होना ज़रूरी है।
 
@@ -474,6 +516,8 @@ Pass 3 prompt template में एक **Phase 1 "Read Once, Extract Facts" blo
 - **Rule D** — Output conciseness: फ़ाइल writes के बीच एक line (`[WRITE]`/`[SKIP]`), fact table को दोहराना नहीं, फ़ाइल content को echo नहीं।
 - **Rule E** — Batch idempotent check: per-target `Read` calls के बजाय PHASE 2 start पर एक `Glob`।
 
+**v2.2.0** में, Pass 3 एक deterministic CLAUDE.md scaffold (`pass-prompts/templates/common/claude-md-scaffold.md`) को prompt में inline embed करता है। यह 8 top-level section titles और order को fix करता है ताकि generated `CLAUDE.md` projects के बीच drift न हो, जबकि हर section का content per-project adapt होता रहे। stack-detector का नया `.env` parser (`lib/env-parser.js`) prompt को `stack.envInfo` supply करता है ताकि port/host/API target rows framework defaults के बजाय project द्वारा actually declare किए गए values से match करें।
+
 **Pass 4** L4 Memory layer को scaffold करता है: स्थायी टीम ज्ञान फ़ाइलें (decision-log, failure-patterns, compaction policy, auto-rule-update) साथ ही `60.memory/` rules जो भविष्य के sessions को बताते हैं कि उन फ़ाइलों को कब और कैसे पढ़ना/लिखना है। Memory layer वह है जो Claude Code को sessions में सबक संचित करने की अनुमति देता है, बजाय हर बार उन्हें फिर से खोजने के। जब `--lang` गैर-अंग्रेज़ी होता है, तो fallback static सामग्री लिखे जाने से पहले Claude के माध्यम से अनुवादित होती है। v2.1.0 यदि Pass 3c ने `skills/00.shared/MANIFEST.md` को omit किया हो तो उसके लिए एक gap-fill जोड़ता है।
 
 ---
@@ -483,7 +527,7 @@ Pass 3 prompt template में एक **Phase 1 "Read Once, Extract Facts" blo
 ```
 your-project/
 │
-├── CLAUDE.md                          ← Claude Code entry point
+├── CLAUDE.md                          ← Claude Code entry point (deterministic 8-section structure, v2.2.0)
 │
 ├── .claude/
 │   └── rules/                         ← Glob-triggered rules
@@ -833,7 +877,14 @@ Claude Code की sensitive-path policy `claude -p` subprocess से `.claude/
 
 ```
 pass-prompts/templates/
-├── common/                  # साझा header/footer + pass4 + staging-override
+├── common/                  # साझा header/footer + pass4 + staging-override + CLAUDE.md scaffold (v2.2.0)
+│   ├── header.md             # भूमिका + output फ़ॉर्मैट निर्देश (सभी pass)
+│   ├── pass3-footer.md       # Pass 3 पूरा होने के बाद health-check निर्देश + 5 CRITICAL guardrail ब्लॉक (v2.2.0)
+│   ├── pass3-phase1.md       # "Read Once, Extract Facts" ब्लॉक (Rule A-E) (v2.1.0)
+│   ├── pass4.md              # Memory scaffolding prompt (v2.0.0)
+│   ├── staging-override.md   # .claude/rules/** लिखना .staged-rules/** पर redirect (v2.0.0)
+│   ├── claude-md-scaffold.md # Deterministic 8-section CLAUDE.md टेम्प्लेट (v2.2.0)
+│   └── lang-instructions.json # प्रति-भाषा output निर्देश (10 भाषाएँ)
 ├── java-spring/             # Java / Spring Boot
 ├── kotlin-spring/           # Kotlin / Spring Boot (CQRS, BFF, multi-module)
 ├── node-express/            # Node.js / Express
@@ -850,6 +901,8 @@ pass-prompts/templates/
 
 `plan-installer` आपके स्टैक(s) को ऑटो-डिटेक्ट करता है, फिर type-specific प्रॉम्प्ट assemble करता है। NestJS, Vue/Nuxt, Vite SPA, और Flask हर एक framework-विशिष्ट विश्लेषण श्रेणियों के साथ समर्पित templates का उपयोग करते हैं (जैसे NestJS के लिए `@Module`/`@Injectable`/Guards; Vue के लिए `<script setup>`/Pinia/useFetch; Vite के लिए client-side routing/`VITE_` env; Flask के लिए Blueprint/`app.factory`/Flask-SQLAlchemy)। Multi-stack प्रोजेक्ट्स के लिए, अलग `pass1-backend-prompt.md` और `pass1-frontend-prompt.md` जेनरेट किए जाते हैं, जबकि `pass3-prompt.md` दोनों स्टैक्स के generation targets को combine करता है। v2.1.0 में, Pass 3 template के आगे `common/pass3-phase1.md` (Rules A–E वाला "Read Once, Extract Facts" block) prepend किया जाता है, फिर इसे split-mode stage के अनुसार sliced किया जाता है। Pass 4 स्टैक की परवाह किए बिना साझा `common/pass4.md` template (memory scaffolding) का उपयोग करता है।
 
+**v2.2.0 में**, Pass 3 prompt phase1 ब्लॉक और stack-specific body के बीच `common/claude-md-scaffold.md` (deterministic 8-section CLAUDE.md टेम्प्लेट) को भी inline embed करता है — यह section संरचना को ठीक करता है ताकि जेनरेटेड CLAUDE.md projects के बीच drift न हो, जबकि content प्रति-project adapt होता है। Templates **English-first** लिखे गए हैं; `lang-instructions.json` से language injection LLM को निर्देश देता है कि emit समय पर section titles और prose को target output भाषा में अनुवाद करे।
+
 ---
 
 ## Monorepo समर्थन
@@ -936,6 +989,12 @@ my-monorepo/                    ← यहाँ चलाएँ: npx claudeos-c
 
 **"CLAUDEOS_SKIP_TRANSLATION=1 is set but --lang='ko' requires translation" InitError (v2.0.0)** — आपके shell में test-only env var `CLAUDEOS_SKIP_TRANSLATION=1` set है (संभवतः CI/test setup से leftover) AND गैर-अंग्रेज़ी `--lang` चुना है। यह env var translation path को short-circuit करता है जिस पर Pass 4 की static-fallback और gap-fill गैर-अंग्रेज़ी output के लिए निर्भर करती हैं। `init` language-selection time पर conflict डिटेक्ट करता है और तुरंत abort हो जाता है (mid-Pass-4 में confusing nested error के साथ crash होने के बजाय)। Fix: या तो चलाने से पहले `unset CLAUDEOS_SKIP_TRANSLATION`, या `npx claudeos-core init --lang en` का उपयोग करें।
 
+**"⚠️ v2.2.0 upgrade detected" warning (v2.2.0)** — आपका existing `CLAUDE.md` pre-v2.2.0 version से generated है। Default resume-mode regeneration Rule B idempotency के तहत existing files को skip करेगा, इसलिए v2.2.0 के structural improvements (8-section CLAUDE.md scaffold, per-file `40.infra/*` paths, `.env.example`-based port accuracy, Section 8 `Common Rules & Memory (L4)` (दो sub-section संरचना के साथ पुनः डिज़ाइन: Common Rules · L4 Memory), `60.memory/*` rule row, forward-referenced `04.doc-writing-guide.md`) apply नहीं होंगे। Fix: `npx claudeos-core init --force` के साथ re-run करें। यह generated files (`CLAUDE.md`, `.claude/rules/`, `claudeos-core/standard/`, `claudeos-core/skills/`, `claudeos-core/guide/`) को overwrite करता है लेकिन `claudeos-core/memory/` content (आपके accumulated decision-log, failure-patterns entries — append-only) को preserve करता है। Overwrite से पहले diff देखना हो तो `--force` से पहले project को git commit कर दें।
+
+**CLAUDE.md में port `.env.example` से अलग (v2.2.0)** — stack-detector का नया `.env` parser (`lib/env-parser.js`) पहले `.env.example` (canonical, committed) पढ़ता है, फिर `.env` variants को fallback के रूप में। Recognized port variables: `PORT`, `VITE_PORT`, `VITE_DESKTOP_PORT`, `NEXT_PUBLIC_PORT`, `NUXT_PORT`, `DJANGO_PORT`, etc. Spring Boot के लिए, `application.yml` का `server.port` अभी भी `.env` पर precedence रखता है (framework-native config wins)। अगर project unusual env var name use करता है, तो recognized convention पर rename करें या `PORT_VAR_KEYS` extend करने के लिए issue raise करें। Framework defaults (Vite 5173, Next.js 3000, Django 8000) तब use होते हैं जब direct detection और `.env` दोनों silent हों।
+
+**Generated docs में `***REDACTED***` values (v2.2.0)** — Expected behavior। v2.2.0 का `.env` parser `PASSWORD`/`SECRET`/`TOKEN`/`API_KEY`/`CREDENTIAL`/`PRIVATE_KEY` patterns से match करने वाले variables के values को automatically `***REDACTED***` से replace कर देता है before किसी भी generator तक पहुंचे। यह `.env.example` में accidentally committed secrets के खिलाफ defense-in-depth है। `DATABASE_URL` stack-detector DB identification back-compat के लिए as-is रहता है। अगर generated `CLAUDE.md` table में `***REDACTED***` दिखे तो वह bug है, please issue file करें — redacted values table तक नहीं पहुंचने चाहिए। Non-sensitive runtime config (port, host, API target, NODE_ENV, etc.) बिना बदलाव pass होता है।
+
 ---
 
 ## योगदान
@@ -945,7 +1004,7 @@ my-monorepo/                    ← यहाँ चलाएँ: npx claudeos-c
 - **नए 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 पहले से shipped — `.github/workflows/test.yml` देखें)
-- **Test coverage** — Test suite का विस्तार करना (वर्तमान में 29 test फ़ाइलों में 563 tests जो scanners, stack detection, domain grouping, plan parsing, prompt generation, CLI selectors, monorepo detection, Vite SPA detection, verification tools, L4 memory scaffold, Pass 2 resume validation, Pass 3 Guards 1/2/3 (H1 sentinel + H2 BOM-aware empty-file + strict stale-marker unlink), Pass 3 split-mode batch subdivision, Pass 3 partial-marker resume (v2.1.0), Pass 4 marker content validation + stale-marker unlink strictness + scaffoldSkillsManifest gap-fill (v2.1.0), translation env-skip guard + early fail-fast + CI workflow, staged-rules move, lang-aware translation fallback, master plan removal regression suite (v2.1.0), memory score/compact formatting regression (v2.1.0), और AI Work Rules template संरचना को कवर करते हैं)
+- **Test coverage** — Test suite का विस्तार करना (वर्तमान में 30 test फ़ाइलों में 602 tests जो scanners, stack detection, domain grouping, plan parsing, prompt generation, CLI selectors, monorepo detection, Vite SPA detection, verification tools, L4 memory scaffold, Pass 2 resume validation, Pass 3 Guards 1/2/3 (H1 sentinel + H2 BOM-aware empty-file + strict stale-marker unlink), Pass 3 split-mode batch subdivision, Pass 3 partial-marker resume (v2.1.0), Pass 4 marker content validation + stale-marker unlink strictness + scaffoldSkillsManifest gap-fill (v2.1.0), translation env-skip guard + early fail-fast + CI workflow, staged-rules move, lang-aware translation fallback, master plan removal regression suite (v2.1.0), memory score/compact formatting regression (v2.1.0), और AI Work Rules template संरचना, और `.env` parser port/host/API-target extraction + sensitive-variable redaction (v2.2.0) को कवर करते हैं)
 
 क्षेत्रों की पूरी सूची, code style, commit convention, और नया stack template जोड़ने के लिए step-by-step guide के लिए [`CONTRIBUTING.md`](./CONTRIBUTING.md) देखें।
 

package/README.ja.md

@@ -69,6 +69,38 @@ ClaudeOS-Core は、プロジェクトが `ApiResponse.ok()`（`ResponseEntity.s
 
 ---
 
+## 生成後の品質保証 (v2.3.0)
+
+生成は問題の半分にすぎません。もう半分は **出力が正しいと分かること** です — 10 の出力言語、11 のスタックテンプレート、あらゆる規模のプロジェクトにわたって。v2.3.0 は生成後に実行され、LLM の自己チェックに依存しない決定論的な validator を 2 つ追加します。
+
+### `claude-md-validator` — 構造的不変条件
+
+生成されたすべての `CLAUDE.md` は、言語不変のシグナルのみを使う 25 の構造的不変条件に対して検証されます: Markdown 構文 (`^## `, `^### `)、翻訳されないリテラルファイル名 (`decision-log.md`, `failure-patterns.md`)、セクション数、セクションごとのサブセクション数、テーブル行数。同じ validator が、英語・韓国語・日本語・ベトナム語・ヒンディー語・ロシア語・スペイン語・中国語・フランス語・ドイツ語で生成された `CLAUDE.md` に対してバイト単位で同じ判定を下します。
+
+クロス言語保証は 10 言語すべてのテスト fixture で検証されており、6 言語の不良 fixture が同一のエラーシグネチャを生成することも確認済みです。ベトナム語プロジェクトで不変条件が失敗したとき、その修正方法はドイツ語プロジェクトで失敗したときと同じです。
+
+### `content-validator [10/10]` — パス主張検証と MANIFEST 一貫性
+
+生成されたすべての `.md` ファイルからバッククォート付きのパス参照 (`src/...`, `.claude/rules/...`, `claudeos-core/skills/...`) を読み取り、実際のファイルシステムと照合します。これまでどのツールも検出できなかった 2 つの LLM 失敗クラスを捕捉します:
+
+- **`STALE_PATH`** — Pass 3 または Pass 4 がもっともらしいが実在しないパスを捏造した場合。典型例: 実際のファイルが `routePath.ts` なのに TypeScript 定数 `FEATURE_ROUTE_PATH` から `featureRoutePath.ts` を推論; multi-entry プロジェクトで Vite 慣習から `src/main.tsx` を仮定; プロジェクトにテストがないのに MSW ドキュメントから `src/__mocks__/handlers.ts` を仮定。
+- **`MANIFEST_DRIFT`** — `claudeos-core/skills/00.shared/MANIFEST.md` に登録された skill が `CLAUDE.md §6` に言及されていない (または逆)。`CLAUDE.md §6` がエントリーポイントで `MANIFEST.md` が完全なレジストリとなる orchestrator + sub-skill レイアウトを認識し、sub-skill は親 orchestrator を介して間接的にカバーされると判定します。
+
+validator は `pass3-footer.md` と `pass4.md` の prompt-time prevention とペアになります: 特定の幻覚クラス (親ディレクトリ接頭辞、Vite/MSW/Vitest/Jest/RTL ライブラリ慣習) を文書化した anti-pattern ブロックと、`pass3a-facts.md` に具体的なファイル名がない場合はルールをディレクトリ単位でスコープするという明示的な positive guidance。
+
+### 任意のプロジェクトで validation を実行
+
+```bash
+npx claudeos-core health     # すべての validator — 単一 go/no-go 判定
+npx claudeos-core lint       # CLAUDE.md 構造不変条件のみ (任意の言語)
+```
+
+### 実世界検証
+
+v2.3.0 はリリース前に、実世界の韓国語姉妹プロジェクト 2 つで end-to-end 検証されました: 14 ドメイン + 8 サブスキルの `scaffold-page-feature` orchestrator を持つ single-SPA Vite + React 19 フロントエンド 1 つと、8 ドメイン + 8 サブスキルの `scaffold-crud-feature` orchestrator を持ち PostgreSQL → MariaDB 移行中の Spring Boot + MyBatis バックエンド 1 つ。両者とも full health check で **エラー 0、警告 0** に落ち着きました — `STALE_PATH` 0、`MANIFEST_DRIFT` 0、25/25 の構造不変条件すべて通過 — 生成された出力への手動編集は一切なし。
+
+---
+
 ## 対応スタック
 
 | スタック | 検出方法 | 分析深度 |
@@ -85,10 +117,20 @@ ClaudeOS-Core は、プロジェクトが `ApiResponse.ok()`（`ResponseEntity.s
 | **Vite / React SPA** | `package.json`、`vite.config.*` | 9 大分類、55 小項目 |
 | **Angular** | `package.json`、`angular.json` | 12 大分類、78 小項目 |
 
-自動検出対象：言語とバージョン、フレームワークとバージョン（SPA フレームワークとしての Vite を含む）、ORM（MyBatis、JPA、Exposed、Prisma、TypeORM、SQLAlchemy など）、データベース（PostgreSQL、MySQL、Oracle、MongoDB、SQLite）、パッケージマネージャ（Gradle、Maven、npm、yarn、pnpm、pip、poetry）、アーキテクチャ（CQRS、BFF — モジュール名から）、マルチモジュール構造（settings.gradle から）、モノレポ（Turborepo、pnpm-workspace、Lerna、npm/yarn workspaces）。
+自動検出対象：言語とバージョン、フレームワークとバージョン（SPA フレームワークとしての Vite を含む）、ORM（MyBatis、JPA、Exposed、Prisma、TypeORM、SQLAlchemy など）、データベース（PostgreSQL、MySQL、Oracle、MongoDB、SQLite）、パッケージマネージャ（Gradle、Maven、npm、yarn、pnpm、pip、poetry）、アーキテクチャ（CQRS、BFF — モジュール名から）、マルチモジュール構造（settings.gradle から）、モノレポ（Turborepo、pnpm-workspace、Lerna、npm/yarn workspaces）、**`.env.example` ランタイム設定**（v2.2.0 — Vite・Next.js・Nuxt・Angular・Node・Python フレームワークの 16 以上の慣習的変数名から port/host/API-target を抽出）。
 
 **何も指定する必要はありません。すべて自動的に検出されます。**
 
+### `.env`-driven ランタイム設定（v2.2.0）
+
+v2.2.0 では `lib/env-parser.js` が追加され、生成される `CLAUDE.md` がフレームワークのデフォルトではなく、プロジェクトが実際に宣言している内容を反映するようになりました。
+
+- **検索順序**：`.env.example`（canonical、コミット対象）→ `.env.local.example` → `.env.sample` → `.env.template` → `.env` → `.env.local` → `.env.development`。`.example` バリアントが優先されるのは、それが「開発者中立な shape-of-truth」であり、特定コントリビュータのローカルオーバーライドではないためです。
+- **認識されるポート変数名の慣例**：`VITE_PORT` / `VITE_DEV_PORT` / `VITE_DESKTOP_PORT` / `NEXT_PUBLIC_PORT` / `NUXT_PORT` / `NG_PORT` / `APP_PORT` / `SERVER_PORT` / `HTTP_PORT` / `DEV_PORT` / `FLASK_RUN_PORT` / `UVICORN_PORT` / `DJANGO_PORT` / 汎用 `PORT`。両方存在する場合はフレームワーク固有名が汎用 `PORT` より優先されます。
+- **ホストと API ターゲット**：`VITE_DEV_HOST` / `VITE_API_TARGET` / `NEXT_PUBLIC_API_URL` / `NUXT_PUBLIC_API_BASE` / `BACKEND_URL` / `PROXY_TARGET` など。
+- **優先順位**：Spring Boot の `application.yml` `server.port` が引き続き最優先（framework-native config）、次に `.env` 宣言のポート、最後の手段としてフレームワークのデフォルト（Vite 5173、Next.js 3000、Django 8000 など）。
+- **機密変数の redaction**：`PASSWORD` / `SECRET` / `TOKEN` / `API_KEY` / `ACCESS_KEY` / `PRIVATE_KEY` / `CREDENTIAL` / `JWT_SECRET` / `CLIENT_SECRET` / `SESSION_SECRET` / `BEARER` / `SALT` パターンにマッチする変数の値は、下流のジェネレータに到達する前に `***REDACTED***` へ置換されます。`.env.example` に誤ってコミットされた機密情報に対する defense-in-depth です。`DATABASE_URL` は stack-detector の DB 識別における後方互換性のため、明示的にホワイトリスト登録されています。
+
 ### Java ドメイン検出（5 パターン、フォールバック付き）
 
 | 優先度 | パターン | 構造 | 例 |
@@ -364,7 +406,7 @@ cat claudeos-core/generated/pass4-prompt.md \
 
 **確認：** `claudeos-core/memory/` に 4 ファイル（`decision-log.md`、`failure-patterns.md`、`compaction.md`、`auto-rule-update.md`）、`.claude/rules/60.memory/` に 4 ルールファイルが存在し、`CLAUDE.md` に `## Memory (L4)` セクションが追加されているはずです。マーカー：`claudeos-core/generated/pass4-memory.json`。
 
-> **v2.1.0 gap-fill：** Pass 4 は `claudeos-core/skills/00.shared/MANIFEST.md` の存在も保証します。Pass 3c がこれを省略した場合（スキルが少ないプロジェクトで、スタックの `pass3.md` テンプレートは `MANIFEST.md` を生成ターゲットに挙げているものの REQUIRED としてマークしていないため起こり得ます）、gap-fill が最小限のスタブを作成し、`.claude/rules/50.sync/03.skills-sync.md` の参照ターゲットが常に有効である状態を保ちます。冪等：ファイルがすでに実体のある内容（>20 文字）を持っている場合はスキップします。
+> **v2.1.0 gap-fill：** Pass 4 は `claudeos-core/skills/00.shared/MANIFEST.md` の存在も保証します。Pass 3c がこれを省略した場合（スキルが少ないプロジェクトで、スタックの `pass3.md` テンプレートは `MANIFEST.md` を生成ターゲットに挙げているものの REQUIRED としてマークしていないため起こり得ます）、gap-fill が最小限のスタブを作成し、`.claude/rules/50.sync/02.skills-sync.md`（v2.2.0 パス — sync ルール数が 3 個から 2 個に削減され、`03` が `02` になりました）の参照ターゲットが常に有効である状態を保ちます。冪等：ファイルがすでに実体のある内容（>20 文字）を持っている場合はスキップします。
 
 > **注意：** `claude -p` が失敗したり `pass4-prompt.md` が欠損している場合、自動化パイプラインは `lib/memory-scaffold.js` を経由した静的スキャフォールドにフォールバックします（`--lang` が非英語の場合は Claude 主導の翻訳付き）。静的フォールバックは `npx claudeos-core init` 内でのみ実行されます — 手動モードでは Pass 4 が成功する必要があります。
 
@@ -474,6 +516,8 @@ Pass 3 プロンプトテンプレートには、出力量をさらに抑制す
 - **Rule D** — 出力の簡潔さ：ファイル書き込みの合間は 1 行（`[WRITE]`/`[SKIP]`）のみ、ファクトテーブルの再掲やファイル内容のエコーをしない。
 - **Rule E** — バッチ冪等チェック：ターゲットごとの `Read` 呼び出しの代わりに、PHASE 2 開始時に `Glob` を 1 回だけ実行。
 
+**v2.2.0** では、Pass 3 は決定的な CLAUDE.md scaffold（`pass-prompts/templates/common/claude-md-scaffold.md`）をプロンプトにインラインで埋め込みます。これにより 8 つの最上位セクションのタイトルと順序が固定され、生成される `CLAUDE.md` がプロジェクト間で drift しなくなり、各セクションの内容はプロジェクトごとに適応できます。stack-detector の新しい `.env` パーサー（`lib/env-parser.js`）が `stack.envInfo` をプロンプトに供給し、port/host/API target 行が framework デフォルトではなくプロジェクトが実際に宣言した値と一致するようになります。
+
 **Pass 4** は L4 メモリレイヤをスキャフォールディングします：永続的なチーム知識ファイル（decision-log、failure-patterns、compaction ポリシー、auto-rule-update）に加えて、これらのファイルをいつどのように読み書きするかを将来のセッションに指示する `60.memory/` ルール。メモリレイヤこそが、Claude Code がセッションごとに学びを再発見するのではなく、セッション間で蓄積することを可能にします。`--lang` が非英語の場合、フォールバック静的コンテンツは書き込み前に Claude を経由して翻訳されます。v2.1.0 では、Pass 3c が省略した場合に備えて `skills/00.shared/MANIFEST.md` の gap-fill が追加されました。
 
 ---
@@ -483,7 +527,7 @@ Pass 3 プロンプトテンプレートには、出力量をさらに抑制す
 ```
 your-project/
 │
-├── CLAUDE.md                          ← Claude Code エントリーポイント
+├── CLAUDE.md                          ← Claude Code エントリーポイント（8セクション決定的構造、v2.2.0）
 │
 ├── .claude/
 │   └── rules/                         ← Glob トリガールール
@@ -833,7 +877,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
@@ -850,6 +901,8 @@ pass-prompts/templates/
 
 `plan-installer` がスタックを自動検出し、タイプ固有のプロンプトを組み立てます。NestJS、Vue/Nuxt、Vite SPA、Flask はそれぞれフレームワーク固有の分析カテゴリを備えた専用テンプレートを使用します（例：NestJS の `@Module`/`@Injectable`/Guards；Vue の `<script setup>`/Pinia/useFetch；Vite の client-side routing/`VITE_` env；Flask の Blueprint/`app.factory`/Flask-SQLAlchemy）。マルチスタックプロジェクトでは、`pass1-backend-prompt.md` と `pass1-frontend-prompt.md` が別々に生成され、`pass3-prompt.md` は両方のスタックの生成ターゲットを結合します。v2.1.0 では、Pass 3 テンプレートの先頭に `common/pass3-phase1.md`（Rule A–E を含む「Read Once, Extract Facts」ブロック）が追加された後、split モードのステージごとにスライスされます。Pass 4 はスタックに関係なく共有の `common/pass4.md` テンプレート（メモリスキャフォールディング）を使用します。
 
+**v2.2.0 では**、Pass 3 プロンプトは phase1 ブロックとスタック固有本体の間に `common/claude-md-scaffold.md`（決定論的 8 セクション CLAUDE.md テンプレート）もインラインで埋め込みます — これによりセクション構造がプロジェクト間でずれることなく、内容はプロジェクトごとに適応します。テンプレートは **English-first** で記述され、`lang-instructions.json` からの言語注入が LLM に対して出力時にセクションタイトルと散文を対象出力言語に翻訳するよう指示します。
+
 ---
 
 ## モノレポサポート
@@ -936,6 +989,12 @@ my-monorepo/                    ← ここで実行：npx claudeos-core init
 
 **"CLAUDEOS_SKIP_TRANSLATION=1 is set but --lang='ko' requires translation" InitError（v2.0.0）** — シェルでテスト専用の環境変数 `CLAUDEOS_SKIP_TRANSLATION=1` が設定されており（おそらく CI/テスト設定の残り物）、かつ非英語 `--lang` を選択しました。この環境変数は、Pass 4 の静的フォールバックと gap-fill が非英語出力のために依存する翻訳パスをショートサーキットします。`init` は言語選択時に競合を検出し、即座に中止します（Pass 4 の途中で紛らわしいネストされたエラーでクラッシュするのではなく）。修正：実行前に `unset CLAUDEOS_SKIP_TRANSLATION` するか、`npx claudeos-core init --lang en` を使用してください。
 
+**"⚠️ v2.2.0 upgrade detected" 警告 (v2.2.0)** — 既存の `CLAUDE.md` が v2.2.0 以前のバージョンで生成されている状態。デフォルトの resume モード再生成は Rule B idempotency により既存ファイルをスキップするため、v2.2.0 の構造改善（8 セクション CLAUDE.md scaffold、`40.infra/*` ファイル別 paths、`.env.example` ベースのポート精度、Section 8 `Common Rules & Memory (L4)` 再設計（共通ルール・L4 メモリの 2 つのサブセクション構造）、`60.memory/*` ルール行、forward-reference された `04.doc-writing-guide.md`）が適用されません。解決: `npx claudeos-core init --force` で再実行。生成ファイル（`CLAUDE.md`、`.claude/rules/`、`claudeos-core/standard/`、`claudeos-core/skills/`、`claudeos-core/guide/`）は上書きされますが、`claudeos-core/memory/` コンテンツ（ユーザーが蓄積した decision-log、failure-patterns エントリー — append-only）は完全に保持されます。上書き前に diff を確認したい場合は、`--force` 実行前にプロジェクトを git commit してください。
+
+**CLAUDE.md の port が `.env.example` と異なる (v2.2.0)** — v2.2.0 の新しい `.env` パーサー（`lib/env-parser.js`）は `.env.example` を優先的に読み（コミットされた canonical ファイル）、fallback として `.env` バリアントを読みます。認識されるポート変数名: `PORT`、`VITE_PORT`、`VITE_DESKTOP_PORT`、`NEXT_PUBLIC_PORT`、`NUXT_PORT`、`DJANGO_PORT` など。Spring Boot の場合、`application.yml` の `server.port` が依然として `.env` より優先されます（framework-native config が優先）。プロジェクトが非標準 env 変数名を使用する場合は、慣例名に変更するか `PORT_VAR_KEYS` 拡張を issue でリクエストしてください。framework デフォルト（Vite 5173、Next.js 3000、Django 8000）は、直接検出と `.env` の両方がサイレントな場合のみ使用されます。
+
+**生成されたドキュメントで値が `***REDACTED***` と表示される (v2.2.0)** — 意図された動作です。v2.2.0 の `.env` パーサーは `PASSWORD`/`SECRET`/`TOKEN`/`API_KEY`/`CREDENTIAL`/`PRIVATE_KEY` パターンにマッチする変数値を自動的に `***REDACTED***` に置換してすべての生成器に渡します。`.env.example` に誤ってコミットされた機密情報に対する defense-in-depth 保護です。`DATABASE_URL` は stack-detector DB 識別 back-compat のため保持されます。生成された `CLAUDE.md` テーブルで `***REDACTED***` が見られる場合はバグなので issue を提出してください — redacted 値はテーブルに到達すべきではありません。非機密ランタイム設定（port、host、API target、NODE_ENV など）は変更なく通過します。
+
 ---
 
 ## 貢献
@@ -945,7 +1004,7 @@ my-monorepo/                    ← ここで実行：npx claudeos-core init
 - **新しいスタックテンプレート** — Ruby/Rails、Go (Gin/Fiber/Echo)、PHP (Laravel/Symfony)、Rust (Axum/Actix)、Svelte/SvelteKit、Remix
 - **IDE 統合** — VS Code 拡張機能、IntelliJ プラグイン
 - **CI/CD テンプレート** — GitLab CI、CircleCI、Jenkins の例（GitHub Actions はすでに付属 — `.github/workflows/test.yml` 参照）
-- **テストカバレッジ** — テストスイートの拡張（現在 29 のテストファイルで 563 テスト、スキャナ、スタック検出、ドメイングループ化、プランパーシング、プロンプト生成、CLI セレクタ、モノレポ検出、Vite SPA 検出、検証ツール、L4 メモリスキャフォールド、Pass 2 再開検証、Pass 3 Guards 1/2/3（H1 センチネル + H2 BOM-aware 空ファイル + strict stale-marker unlink）、Pass 3 split モードのバッチサブ分割、Pass 3 部分マーカー再開（v2.1.0）、Pass 4 マーカーコンテンツ検証 + stale-marker unlink strictness + scaffoldSkillsManifest gap-fill（v2.1.0）、翻訳 env-skip ガード + early fail-fast + CI ワークフロー、staged-rules 移動、言語対応翻訳フォールバック、master plan 廃止のリグレッションスイート（v2.1.0）、memory score/compact フォーマッティングのリグレッション（v2.1.0）、AI Work Rules テンプレート構造をカバー）
+- **テストカバレッジ** — テストスイートの拡張（現在 30 のテストファイルで 602 テスト、スキャナ、スタック検出、ドメイングループ化、プランパーシング、プロンプト生成、CLI セレクタ、モノレポ検出、Vite SPA 検出、検証ツール、L4 メモリスキャフォールド、Pass 2 再開検証、Pass 3 Guards 1/2/3（H1 センチネル + H2 BOM-aware 空ファイル + strict stale-marker unlink）、Pass 3 split モードのバッチサブ分割、Pass 3 部分マーカー再開（v2.1.0）、Pass 4 マーカーコンテンツ検証 + stale-marker unlink strictness + scaffoldSkillsManifest gap-fill（v2.1.0）、翻訳 env-skip ガード + early fail-fast + CI ワークフロー、staged-rules 移動、言語対応翻訳フォールバック、master plan 廃止のリグレッションスイート（v2.1.0）、memory score/compact フォーマッティングのリグレッション（v2.1.0）、AI Work Rules テンプレート構造、`.env` パーサー port/host/API-target 抽出 + センシティブ変数 redaction (v2.2.0)をカバー）
 
 領域の完全なリスト、コードスタイル、コミット規約、新しいスタックテンプレートを追加するためのステップバイステップガイドについては、[`CONTRIBUTING.md`](./CONTRIBUTING.md) を参照してください。