claudeos-core 1.2.1 → 1.2.2

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [1.2.1] — 2026-04-02
+
+### Added
+- **Sync Hook** (`sync-hook/index.js`) — Automatic disk → Master Plan sync via Claude Code PostToolUse hooks
+  - Triggers on Edit/Write operations, updates the matching plan `<file>` block in-place
+  - Supports both `<file>` block format and ` ```markdown ` code block format
+  - `npx claudeos-core init` now auto-installs hooks into `.claude/settings.json`
+  - Silent no-op for non-tracked files, deleted files, and missing plan directories
+
+### Changed
+- **Standard reference rule** (`00.core/00.standard-reference.md`) — auto-generated rule file that instructs Claude Code to Read standard documents before coding; ensures standard/ files are actually used
+- **Rules now use `paths: ["**/*"]` frontmatter** — ensures Claude Code always loads all rules regardless of which file is being edited
+- **@import removed** — `@import` was never a real Claude Code feature; rules are now self-contained with full content inline
+- **50.sync/ rules role clarified** — these are now AI fallback reminders; actual sync is handled by hooks
+- All 6 pass3 templates updated to generate rules with `paths: ["**/*"]` and no `@import`
+- `content-validator` no longer checks for `@import` presence
+- `manifest-generator` generates empty deprecated `import-graph.json` stub for backward compatibility
+
+### Deprecated
+- **`import-linter`** — removed from health-checker pipeline; `@import` is not a Claude Code feature
+- **`import-graph.json`** — kept as empty stub for backward compatibility
+
+### Removed
+- `import-linter` removed from `health-checker` verification pipeline (6 tools → 5 tools)
+- `extractImports()` function removed from `manifest-generator`
+
 ## [1.2.0] — 2026-04-01
 
 ### Added

package/README.de.md

@@ -23,7 +23,7 @@ ClaudeOS-Core automatisiert den gesamten Prozess:
 1. **Scannt** Ihr Projekt — erkennt automatisch Stack, Domänen, ORM, Datenbank, Paketmanager
 2. **Analysiert** Ihren Quellcode tiefgehend — Controller-Muster, Service-Schichten, Namenskonventionen, Fehlerbehandlung, Sicherheit, Tests und 50+ Kategorien
 3. **Generiert** ein vollständiges Dokumentationsökosystem — `CLAUDE.md`, Standards (15–19 Dateien), Rules, Skills, Guides (9 Dateien), Master Plans, DB-Dokumentation und MCP-Leitfaden
-4. **Validiert** alles — 6 integrierte Verifizierungstools gewährleisten Konsistenz
+4. **Validiert** alles — 5 integrierte Verifizierungstools gewährleisten Konsistenz
 
 Gesamtzeit: **5–18 Minuten**, abhängig von der Projektgröße. Null manuelle Konfiguration.
 
@@ -209,7 +209,6 @@ node claudeos-core-tools/manifest-generator/index.js
 node claudeos-core-tools/health-checker/index.js
 
 # Oder einzelne Prüfungen ausführen:
-node claudeos-core-tools/import-linter/index.js        # @import validation
 node claudeos-core-tools/plan-validator/index.js --check # Plan ↔ disk
 node claudeos-core-tools/sync-checker/index.js          # Sync status
 node claudeos-core-tools/content-validator/index.js     # Content quality
@@ -322,7 +321,7 @@ Bei Multi-Stack-Projekten (z.B. Java + React) werden Backend- und Frontend-Domä
 
 ## Verifizierungstools
 
-ClaudeOS-Core enthält 6 integrierte Verifizierungstools, die nach der Generierung automatisch ausgeführt werden:
+ClaudeOS-Core enthält 5 integrierte Verifizierungstools, die nach der Generierung automatisch ausgeführt werden:
 
 ```bash
 # Alle Prüfungen auf einmal ausführen (empfohlen)
@@ -336,8 +335,7 @@ npx claudeos-core restore      # Plan → Festplatte Wiederherstellung
 
 | Tool | Funktion |
 |---|---|
-| **manifest-generator** | Erstellt Metadaten-JSON (rule-manifest, import-graph, sync-map, plan-manifest) |
-| **import-linter** | Validiert `@import`-Pfade — erkennt defekte, doppelte und zirkuläre Imports (DFS) |
+| **manifest-generator** | Erstellt Metadaten-JSON (rule-manifest, sync-map, plan-manifest) |
 | **plan-validator** | Vergleicht `<file>`-Blöcke des Master Plans mit der Festplatte — 3 Modi: check, refresh, restore |
 | **sync-checker** | Erkennt nicht registrierte Dateien (auf Festplatte, aber nicht im Plan) und verwaiste Einträge |
 | **content-validator** | Validiert Dateiqualität — leere Dateien, fehlende ✅/❌ Beispiele, erforderliche Abschnitte |
@@ -345,6 +343,49 @@ npx claudeos-core restore      # Plan → Festplatte Wiederherstellung
 
 ---
 
+## Wie Claude Code Ihre Dokumentation Nutzt
+
+So liest Claude Code die von ClaudeOS-Core generierte Dokumentation tatsächlich:
+
+### Automatisch gelesene Dateien
+
+| Datei | Wann | Garantiert |
+|---|---|---|
+| `CLAUDE.md` | Bei jedem Gesprächsstart | Immer |
+| `.claude/rules/*.md` | Beim Bearbeiten von Dateien (via `paths: ["**/*"]`) | Immer |
+| `.claude/rules/00.core/00.standard-reference.md` | ↑ Oben enthalten | Immer |
+
+### Dateien, die über die standard-reference Regel gelesen werden
+
+Die Regel `00.standard-reference.md` weist Claude Code an, die Standard-Dokumente vor dem Schreiben von Code zu Read:
+
+- `claudeos-core/standard/**` — Coding-Patterns, ✅/❌ Beispiele, Namenskonventionen
+- `claudeos-core/database/**` — DB-Schema (für Queries, Mapper, Migrationen)
+
+### Dateien, die NICHT gelesen werden (Kontexteinsparung)
+
+Explizit durch den `DO NOT Read`-Abschnitt der standard-reference Regel ausgeschlossen:
+
+| Ordner | Ausschlussgrund |
+|---|---|
+| `claudeos-core/plan/` | Master Plan Backups (~340KB). Automatisch durch Hooks synchronisiert. |
+| `claudeos-core/generated/` | Build-Metadaten JSON. Keine Coding-Referenz. |
+| `claudeos-core/guide/` | Onboarding-Guides für Menschen. |
+| `claudeos-core/mcp-guide/` | MCP Server Dokumentation. Keine Coding-Referenz. |
+
+### Automatische Plan-Synchronisation (Hooks)
+
+Wenn Claude Code eine Standard- oder Rules-Datei bearbeitet, synchronisiert ein PostToolUse Hook automatisch den Master Plan:
+
+```
+AI bearbeitet claudeos-core/standard/10.backend-api/01.controller-patterns.md
+  → sync-hook aktualisiert automatisch plan/10.standard-master.md
+```
+
+Keine manuelle Synchronisation nötig. Der Hook wird automatisch bei `npx claudeos-core init` installiert.
+
+---
+
 ## Täglicher Arbeitsablauf
 
 ### Nach der Installation
@@ -359,7 +400,7 @@ npx claudeos-core restore      # Plan → Festplatte Wiederherstellung
 ### Nach manueller Bearbeitung der Standards
 
 ```bash
-# Änderungen zum Master Plan synchronisieren
+# Wenn Dateien außerhalb von Claude Code bearbeitet wurden (Hooks funktionieren nur innerhalb):
 npx claudeos-core refresh
 
 # Konsistenz überprüfen
@@ -391,7 +432,7 @@ npx claudeos-core restore
 | **Projektspezifische Ausgabe** | ✅ Jede Datei spiegelt Ihre Muster wider | ❌ Generische Befehle | Teilweise | ❌ Einheitsgröße |
 | **Multi-Stack** | ✅ Auto-Erkennung + separate Analyse | ❌ Stack-agnostisch | Manuell | Variiert |
 | **Kotlin + CQRS/BFF** | ✅ Multi-Modul, Command/Query-Trennung | ❌ | ❌ | ❌ |
-| **Selbstverifizierung** | ✅ 6 Validierungstools | ❌ | ❌ | ❌ |
+| **Selbstverifizierung** | ✅ 5 Validierungstools | ❌ | ❌ | ❌ |
 | **Backup / Wiederherstellung** | ✅ Master Plan System | ❌ | ❌ | ❌ |
 | **Einrichtungszeit** | ~5–18 Min (automatisch) | ~5 Min (manuelle Konfig) | Stunden–Tage | ~5 Min |
 

package/README.es.md

@@ -23,7 +23,7 @@ ClaudeOS-Core automatiza todo el proceso:
 1. **Escanea** tu proyecto — detecta automáticamente stack, dominios, ORM, base de datos y gestor de paquetes
 2. **Analiza** tu código fuente en profundidad — patrones de controladores, capas de servicio, convenciones de nombrado, manejo de errores, seguridad, testing y más de 50 categorías
 3. **Genera** un ecosistema documental completo — `CLAUDE.md`, Standards (15–19 archivos), Rules, Skills, Guides (9 archivos), Master Plans, documentación de BD y guía MCP
-4. **Valida** todo — 6 herramientas de verificación integradas garantizan la consistencia
+4. **Valida** todo — 5 herramientas de verificación integradas garantizan la consistencia
 
 Tiempo total: **5–18 minutos**, según el tamaño del proyecto. Cero configuración manual.
 
@@ -209,7 +209,6 @@ node claudeos-core-tools/manifest-generator/index.js
 node claudeos-core-tools/health-checker/index.js
 
 # O ejecutar verificaciones individuales:
-node claudeos-core-tools/import-linter/index.js        # @import validation
 node claudeos-core-tools/plan-validator/index.js --check # Plan ↔ disk
 node claudeos-core-tools/sync-checker/index.js          # Sync status
 node claudeos-core-tools/content-validator/index.js     # Content quality
@@ -322,7 +321,7 @@ Para proyectos multi-stack (ej: Java + React), los dominios de backend y fronten
 
 ## Herramientas de Verificación
 
-ClaudeOS-Core incluye 6 herramientas de verificación integradas que se ejecutan automáticamente después de la generación:
+ClaudeOS-Core incluye 5 herramientas de verificación integradas que se ejecutan automáticamente después de la generación:
 
 ```bash
 # Ejecutar todas las verificaciones a la vez (recomendado)
@@ -336,8 +335,7 @@ npx claudeos-core restore      # Restauración Plan → Disco
 
 | Herramienta | Función |
 |---|---|
-| **manifest-generator** | Construye JSON de metadatos (rule-manifest, import-graph, sync-map, plan-manifest) |
-| **import-linter** | Valida rutas `@import` — detecta imports rotos, duplicados y circulares (DFS) |
+| **manifest-generator** | Construye JSON de metadatos (rule-manifest, sync-map, plan-manifest) |
 | **plan-validator** | Compara bloques `<file>` del Master Plan con el disco — 3 modos: check, refresh, restore |
 | **sync-checker** | Detecta archivos no registrados (en disco pero no en plan) y entradas huérfanas |
 | **content-validator** | Valida calidad de archivos — archivos vacíos, ejemplos ✅/❌ faltantes, secciones requeridas |
@@ -345,6 +343,49 @@ npx claudeos-core restore      # Restauración Plan → Disco
 
 ---
 
+## Cómo Claude Code Usa tu Documentación
+
+Así es como Claude Code lee la documentación generada por ClaudeOS-Core:
+
+### Archivos que se leen automáticamente
+
+| Archivo | Cuándo | Garantizado |
+|---|---|---|
+| `CLAUDE.md` | Al inicio de cada conversación | Siempre |
+| `.claude/rules/*.md` | Al editar archivos (vía `paths: ["**/*"]`) | Siempre |
+| `.claude/rules/00.core/00.standard-reference.md` | ↑ Incluido arriba | Siempre |
+
+### Archivos leídos vía regla standard-reference
+
+La regla `00.standard-reference.md` instruye a Claude Code a Read los documentos estándar antes de escribir código:
+
+- `claudeos-core/standard/**` — Patrones de código, ejemplos ✅/❌, convenciones de nombres
+- `claudeos-core/database/**` — Schema DB (para queries, mappers, migraciones)
+
+### Archivos que NO se leen (ahorro de contexto)
+
+Excluidos explícitamente por la sección `DO NOT Read` de la regla standard-reference:
+
+| Carpeta | Razón de exclusión |
+|---|---|
+| `claudeos-core/plan/` | Backups de Master Plan (~340KB). Auto-sincronizado por hooks. |
+| `claudeos-core/generated/` | Metadatos JSON de build. No es referencia de código. |
+| `claudeos-core/guide/` | Guías de onboarding para humanos. |
+| `claudeos-core/mcp-guide/` | Docs de servidor MCP. No es referencia de código. |
+
+### Sincronización automática de Plan (hooks)
+
+Cuando Claude Code edita un archivo standard o rules, un hook PostToolUse sincroniza automáticamente el Master Plan:
+
+```
+AI edita claudeos-core/standard/10.backend-api/01.controller-patterns.md
+  → sync-hook actualiza automáticamente plan/10.standard-master.md
+```
+
+No requiere sincronización manual. El hook se instala automáticamente durante `npx claudeos-core init`.
+
+---
+
 ## Flujo de Trabajo Diario
 
 ### Después de la Instalación
@@ -359,7 +400,7 @@ npx claudeos-core restore      # Restauración Plan → Disco
 ### Después de Editar Estándares Manualmente
 
 ```bash
-# Sincroniza tus cambios al Master Plan
+# Si editaste archivos fuera de Claude Code (los hooks solo funcionan dentro de Claude Code):
 npx claudeos-core refresh
 
 # Verifica que todo sea consistente
@@ -391,7 +432,7 @@ npx claudeos-core restore
 | **Salida específica del proyecto** | ✅ Cada archivo refleja tus patrones | ❌ Comandos genéricos | Parcial | ❌ Talla única |
 | **Multi-stack** | ✅ Auto-detección + análisis separado | ❌ Agnóstico al stack | Manual | Variable |
 | **Kotlin + CQRS/BFF** | ✅ Multi-module, Command/Query split | ❌ | ❌ | ❌ |
-| **Auto-verificación** | ✅ 6 herramientas de validación | ❌ | ❌ | ❌ |
+| **Auto-verificación** | ✅ 5 herramientas de validación | ❌ | ❌ | ❌ |
 | **Backup / Restauración** | ✅ Sistema Master Plan | ❌ | ❌ | ❌ |
 | **Tiempo de configuración** | ~5–18min (automático) | ~5min (config manual) | Horas–Días | ~5min |
 

package/README.fr.md

@@ -23,7 +23,7 @@ ClaudeOS-Core automatise l'ensemble du processus :
 1. **Scanne** votre projet — détecte automatiquement le stack, les domaines, l'ORM, la base de données et le gestionnaire de paquets
 2. **Analyse en profondeur** votre code source — patterns de contrôleurs, couches de service, conventions de nommage, gestion des erreurs, sécurité, tests et plus de 50 catégories
 3. **Génère** un écosystème documentaire complet — `CLAUDE.md`, Standards (15–19 fichiers), Rules, Skills, Guides (9 fichiers), Master Plans, documentation BD et guide MCP
-4. **Valide** tout — 6 outils de vérification intégrés garantissent la cohérence
+4. **Valide** tout — 5 outils de vérification intégrés garantissent la cohérence
 
 Temps total : **5–18 minutes**, selon la taille du projet. Zéro configuration manuelle.
 
@@ -209,7 +209,6 @@ node claudeos-core-tools/manifest-generator/index.js
 node claudeos-core-tools/health-checker/index.js
 
 # Ou exécuter les vérifications individuellement :
-node claudeos-core-tools/import-linter/index.js        # @import validation
 node claudeos-core-tools/plan-validator/index.js --check # Plan ↔ disk
 node claudeos-core-tools/sync-checker/index.js          # Sync status
 node claudeos-core-tools/content-validator/index.js     # Content quality
@@ -322,7 +321,7 @@ Pour les projets multi-stack (ex : Java + React), les domaines backend et fronte
 
 ## Outils de Vérification
 
-ClaudeOS-Core inclut 6 outils de vérification intégrés, exécutés automatiquement après la génération :
+ClaudeOS-Core inclut 5 outils de vérification intégrés, exécutés automatiquement après la génération :
 
 ```bash
 # Exécuter toutes les vérifications (recommandé)
@@ -336,8 +335,7 @@ npx claudeos-core restore      # Restauration Plan → Disque
 
 | Outil | Fonction |
 |---|---|
-| **manifest-generator** | Construit les JSON de métadonnées (rule-manifest, import-graph, sync-map, plan-manifest) |
-| **import-linter** | Valide les chemins `@import` — détecte les imports cassés, dupliqués et circulaires (DFS) |
+| **manifest-generator** | Construit les JSON de métadonnées (rule-manifest, sync-map, plan-manifest) |
 | **plan-validator** | Compare les blocs `<file>` du Master Plan avec le disque — 3 modes : check, refresh, restore |
 | **sync-checker** | Détecte les fichiers non enregistrés (sur disque mais pas dans le plan) et les entrées orphelines |
 | **content-validator** | Valide la qualité des fichiers — fichiers vides, exemples ✅/❌ manquants, sections requises |
@@ -345,6 +343,49 @@ npx claudeos-core restore      # Restauration Plan → Disque
 
 ---
 
+## Comment Claude Code Utilise Votre Documentation
+
+Voici comment Claude Code lit effectivement la documentation générée par ClaudeOS-Core :
+
+### Fichiers lus automatiquement
+
+| Fichier | Quand | Garanti |
+|---|---|---|
+| `CLAUDE.md` | Au début de chaque conversation | Toujours |
+| `.claude/rules/*.md` | Lors de l'édition de fichiers (via `paths: ["**/*"]`) | Toujours |
+| `.claude/rules/00.core/00.standard-reference.md` | ↑ Inclus ci-dessus | Toujours |
+
+### Fichiers lus via la règle standard-reference
+
+La règle `00.standard-reference.md` indique à Claude Code de Read les documents standards avant d'écrire du code :
+
+- `claudeos-core/standard/**` — Patterns de code, exemples ✅/❌, conventions de nommage
+- `claudeos-core/database/**` — Schéma DB (pour requêtes, mappers, migrations)
+
+### Fichiers NON lus (économie de contexte)
+
+Explicitement exclus par la section `DO NOT Read` de la règle standard-reference :
+
+| Dossier | Raison d'exclusion |
+|---|---|
+| `claudeos-core/plan/` | Sauvegardes Master Plan (~340Ko). Auto-synchronisé par hooks. |
+| `claudeos-core/generated/` | JSON de métadonnées build. Pas une référence de code. |
+| `claudeos-core/guide/` | Guides d'onboarding pour humains. |
+| `claudeos-core/mcp-guide/` | Docs serveur MCP. Pas une référence de code. |
+
+### Synchronisation automatique du Plan (hooks)
+
+Quand Claude Code édite un fichier standard ou rules, un hook PostToolUse synchronise automatiquement le Master Plan :
+
+```
+AI édite claudeos-core/standard/10.backend-api/01.controller-patterns.md
+  → sync-hook met à jour automatiquement plan/10.standard-master.md
+```
+
+Aucune synchronisation manuelle nécessaire. Le hook est installé automatiquement lors de `npx claudeos-core init`.
+
+---
+
 ## Flux de Travail Quotidien
 
 ### Après l'Installation
@@ -359,7 +400,7 @@ npx claudeos-core restore      # Restauration Plan → Disque
 ### Après Modification Manuelle des Standards
 
 ```bash
-# Synchroniser les changements vers le Master Plan
+# Si vous avez édité des fichiers en dehors de Claude Code (les hooks ne fonctionnent qu'à l'intérieur) :
 npx claudeos-core refresh
 
 # Vérifier la cohérence
@@ -391,7 +432,7 @@ npx claudeos-core restore
 | **Sortie spécifique au projet** | ✅ Chaque fichier reflète vos patterns | ❌ Commandes génériques | Partiel | ❌ Taille unique |
 | **Multi-stack** | ✅ Auto-détection + analyse séparée | ❌ Agnostique au stack | Manuel | Variable |
 | **Kotlin + CQRS/BFF** | ✅ Multi-module, Command/Query split | ❌ | ❌ | ❌ |
-| **Auto-vérification** | ✅ 6 outils de validation | ❌ | ❌ | ❌ |
+| **Auto-vérification** | ✅ 5 outils de validation | ❌ | ❌ | ❌ |
 | **Sauvegarde / Restauration** | ✅ Système Master Plan | ❌ | ❌ | ❌ |
 | **Temps de configuration** | ~5–18 min (automatique) | ~5 min (config manuelle) | Heures–Jours | ~5 min |
 

package/README.hi.md

@@ -23,7 +23,7 @@ ClaudeOS-Core पूरी प्रक्रिया को ऑटोमेट
 1. **स्कैन** — स्टैक, डोमेन, ORM, डेटाबेस, पैकेज मैनेजर ऑटो-डिटेक्ट
 2. **गहन विश्लेषण** — कंट्रोलर पैटर्न, सर्विस लेयर्स, नेमिंग कन्वेंशन, एरर हैंडलिंग, सिक्योरिटी, टेस्टिंग और 50+ कैटेगरी
 3. **जेनरेट** — `CLAUDE.md`, Standards (15–19 फाइलें), Rules, Skills, Guides (9 फाइलें), Master Plans, DB डॉक्स और MCP गाइड का पूरा डॉक्यूमेंटेशन इकोसिस्टम
-4. **वैलिडेट** — 6 बिल्ट-इन वेरिफिकेशन टूल्स कंसिस्टेंसी सुनिश्चित करते हैं
+4. **वैलिडेट** — 5 बिल्ट-इन वेरिफिकेशन टूल्स कंसिस्टेंसी सुनिश्चित करते हैं
 
 कुल समय: प्रोजेक्ट साइज़ के अनुसार **5–18 मिनट**। शून्य मैन्युअल कॉन्फ़िगरेशन।
 
@@ -209,7 +209,6 @@ node claudeos-core-tools/manifest-generator/index.js
 node claudeos-core-tools/health-checker/index.js
 
 # या इंडिविजुअल चेक रन करें:
-node claudeos-core-tools/import-linter/index.js        # @import validation
 node claudeos-core-tools/plan-validator/index.js --check # Plan ↔ disk
 node claudeos-core-tools/sync-checker/index.js          # Sync status
 node claudeos-core-tools/content-validator/index.js     # Content quality
@@ -322,7 +321,7 @@ your-project/
 
 ## वेरिफिकेशन टूल्स
 
-ClaudeOS-Core में 6 बिल्ट-इन वेरिफिकेशन टूल्स हैं जो जेनरेशन के बाद ऑटोमैटिकली रन होते हैं:
+ClaudeOS-Core में 5 बिल्ट-इन वेरिफिकेशन टूल्स हैं जो जेनरेशन के बाद ऑटोमैटिकली रन होते हैं:
 
 ```bash
 # सभी चेक एक साथ रन करें (अनुशंसित)
@@ -336,8 +335,7 @@ npx claudeos-core restore      # Plan → डिस्क रीस्टोर
 
 | टूल | क्या करता है |
 |---|---|
-| **manifest-generator** | मेटाडेटा JSON बनाता है (rule-manifest, import-graph, sync-map, plan-manifest) |
-| **import-linter** | `@import` पाथ वैलिडेट करता है — टूटे, डुप्लिकेट और सर्कुलर इम्पोर्ट डिटेक्ट (DFS) |
+| **manifest-generator** | मेटाडेटा JSON बनाता है (rule-manifest, sync-map, plan-manifest) |
 | **plan-validator** | Master Plan `<file>` ब्लॉक्स की डिस्क से तुलना — 3 मोड: check, refresh, restore |
 | **sync-checker** | अनरजिस्टर्ड फाइलें (डिस्क पर हैं लेकिन plan में नहीं) और ऑर्फन एंट्रीज़ डिटेक्ट |
 | **content-validator** | फाइल क्वालिटी वैलिडेट — खाली फाइलें, मिसिंग ✅/❌ उदाहरण, आवश्यक सेक्शन |
@@ -345,6 +343,49 @@ npx claudeos-core restore      # Plan → डिस्क रीस्टोर
 
 ---
 
+## Claude Code आपके डॉक्यूमेंटेशन को कैसे उपयोग करता है
+
+ClaudeOS-Core द्वारा जेनरेट किए गए डॉक्यूमेंटेशन को Claude Code वास्तव में कैसे पढ़ता है:
+
+### ऑटोमैटिकली पढ़ी जाने वाली फाइलें
+
+| फाइल | कब | गारंटी |
+|---|---|---|
+| `CLAUDE.md` | हर कन्वर्सेशन शुरू होने पर | हमेशा |
+| `.claude/rules/*.md` | फाइल एडिट करते समय (`paths: ["**/*"]`) | हमेशा |
+| `.claude/rules/00.core/00.standard-reference.md` | ↑ ऊपर में शामिल | हमेशा |
+
+### standard-reference रूल के ज़रिए पढ़ी जाने वाली फाइलें
+
+`00.standard-reference.md` रूल Claude Code को कोड लिखने से पहले ये डॉक्यूमेंट Read करने का निर्देश देता है:
+
+- `claudeos-core/standard/**` — कोडिंग पैटर्न, ✅/❌ उदाहरण, नेमिंग कन्वेंशन
+- `claudeos-core/database/**` — DB स्कीमा (क्वेरी, मैपर, माइग्रेशन के लिए)
+
+### न पढ़ी जाने वाली फाइलें (कॉन्टेक्स्ट बचत)
+
+standard-reference रूल के `DO NOT Read` सेक्शन द्वारा स्पष्ट रूप से बाहर:
+
+| फोल्डर | बाहर करने का कारण |
+|---|---|
+| `claudeos-core/plan/` | Master Plan बैकअप (~340KB)। hooks द्वारा ऑटो-सिंक। |
+| `claudeos-core/generated/` | बिल्ड मेटाडेटा JSON। कोडिंग रेफरेंस नहीं। |
+| `claudeos-core/guide/` | इंसानों के लिए ऑनबोर्डिंग गाइड। |
+| `claudeos-core/mcp-guide/` | MCP सर्वर डॉक्स। कोडिंग रेफरेंस नहीं। |
+
+### ऑटोमैटिक Plan सिंक (hooks)
+
+जब Claude Code standard या rules फाइल एडिट करता है, PostToolUse hook ऑटोमैटिकली Master Plan सिंक करता है:
+
+```
+AI claudeos-core/standard/10.backend-api/01.controller-patterns.md एडिट करता है
+  → sync-hook ऑटोमैटिकली plan/10.standard-master.md अपडेट करता है
+```
+
+मैन्युअल सिंक ज़रूरी नहीं। hook `npx claudeos-core init` के दौरान ऑटोमैटिकली इंस्टॉल होता है।
+
+---
+
 ## दैनिक वर्कफ़्लो
 
 ### इंस्टॉलेशन के बाद
@@ -359,7 +400,7 @@ npx claudeos-core restore      # Plan → डिस्क रीस्टोर
 ### स्टैंडर्ड्स मैन्युअली एडिट करने के बाद
 
 ```bash
-# बदलाव Master Plan में सिंक करें
+# Claude Code के बाहर फाइल एडिट की है तो (hooks सिर्फ़ Claude Code के अंदर काम करते हैं):
 npx claudeos-core refresh
 
 # सब कुछ कंसिस्टेंट है वेरिफाई करें
@@ -391,7 +432,7 @@ npx claudeos-core restore
 | **प्रोजेक्ट-स्पेसिफिक आउटपुट** | ✅ हर फाइल आपके पैटर्न रिफ्लेक्ट करती है | ❌ जेनेरिक कमांड | आंशिक | ❌ वन-साइज़-फिट्स-ऑल |
 | **मल्टी-स्टैक** | ✅ ऑटो-डिटेक्ट + अलग विश्लेषण | ❌ स्टैक-एग्नॉस्टिक | मैन्युअल | अनिश्चित |
 | **Kotlin + CQRS/BFF** | ✅ मल्टी-मॉड्यूल, Command/Query विभाजन | ❌ | ❌ | ❌ |
-| **सेल्फ-वेरिफाइंग** | ✅ 6 वैलिडेशन टूल्स | ❌ | ❌ | ❌ |
+| **सेल्फ-वेरिफाइंग** | ✅ 5 वैलिडेशन टूल्स | ❌ | ❌ | ❌ |
 | **बैकअप / रीस्टोर** | ✅ Master Plan सिस्टम | ❌ | ❌ | ❌ |
 | **सेटअप समय** | ~5–18 मिनट (ऑटोमेटेड) | ~5 मिनट (मैन्युअल कॉन्फ़िग) | घंटे–दिन | ~5 मिनट |
 

package/README.ja.md

@@ -23,7 +23,7 @@ ClaudeOS-Core がプロセス全体を自動化します：
 1. **スキャン** — スタック、ドメイン、ORM、DB、パッケージマネージャーを自動検出
 2. **ディープ分析** — コントローラーパターン、サービス層、命名規則、エラーハンドリング、セキュリティ、テストなど 50+ カテゴリ
 3. **生成** — `CLAUDE.md`、Standards（15–19 ファイル）、Rules、Skills、Guides（9 ファイル）、Master Plans、DB ドキュメント、MCP ガイドの完全な文書エコシステム
-4. **検証** — 6 つの組み込み検証ツールが整合性を保証
+4. **検証** — 5 つの組み込み検証ツールが整合性を保証
 
 所要時間：プロジェクト規模に応じて **5–18 分**。手動設定ゼロ。
 
@@ -209,7 +209,6 @@ node claudeos-core-tools/manifest-generator/index.js
 node claudeos-core-tools/health-checker/index.js
 
 # または個別チェック：
-node claudeos-core-tools/import-linter/index.js        # @import validation
 node claudeos-core-tools/plan-validator/index.js --check # Plan ↔ disk
 node claudeos-core-tools/sync-checker/index.js          # Sync status
 node claudeos-core-tools/content-validator/index.js     # Content quality
@@ -322,7 +321,7 @@ your-project/
 
 ## 検証ツール
 
-ClaudeOS-Core には生成後に自動実行される 6 つの組み込み検証ツールがあります：
+ClaudeOS-Core には生成後に自動実行される 5 つの組み込み検証ツールがあります：
 
 ```bash
 # 全チェックを一括実行（推奨）
@@ -336,8 +335,7 @@ npx claudeos-core restore      # Plan → ディスク復元
 
 | ツール | 機能 |
 |---|---|
-| **manifest-generator** | メタデータ JSON を構築（rule-manifest、import-graph、sync-map、plan-manifest） |
-| **import-linter** | `@import` パスを検証 — 破損、重複、循環インポートを検出（DFS） |
+| **manifest-generator** | メタデータ JSON を構築（rule-manifest、sync-map、plan-manifest） |
 | **plan-validator** | Master Plan の `<file>` ブロックとディスクを比較 — 3 モード：check、refresh、restore |
 | **sync-checker** | 未登録ファイル（ディスク上にあるがプランにない）と孤立エントリを検出 |
 | **content-validator** | ファイル品質を検証 — 空ファイル、✅/❌ 例の欠落、必須セクション |
@@ -345,6 +343,49 @@ npx claudeos-core restore      # Plan → ディスク復元
 
 ---
 
+## Claude Code がドキュメントを使用する仕組み
+
+ClaudeOS-Core が生成したドキュメントを Claude Code が実際に読み取る仕組みです：
+
+### 自動的に読み取るファイル
+
+| ファイル | タイミング | 保証 |
+|---|---|---|
+| `CLAUDE.md` | 毎回の会話開始時 | 常に |
+| `.claude/rules/*.md` | ファイル編集時（`paths: ["**/*"]`） | 常に |
+| `.claude/rules/00.core/00.standard-reference.md` | ↑ 上記に含まれる | 常に |
+
+### standard-reference ルール経由で読み取るファイル
+
+`00.standard-reference.md` ルールが、コード作成前に以下のドキュメントを Read するよう指示します：
+
+- `claudeos-core/standard/**` — コーディングパターン、✅/❌ 例、命名規則
+- `claudeos-core/database/**` — DB スキーマ（クエリ、マッパー、マイグレーション用）
+
+### 読み取らないファイル（コンテキスト節約）
+
+standard-reference ルールの `DO NOT Read` セクションで明示的に除外されます：
+
+| フォルダ | 除外理由 |
+|---|---|
+| `claudeos-core/plan/` | Master Plan バックアップ（~340KB）。hooks で自動同期。 |
+| `claudeos-core/generated/` | ビルドメタデータ JSON。コーディング参照不要。 |
+| `claudeos-core/guide/` | 人間向けオンボーディングガイド。 |
+| `claudeos-core/mcp-guide/` | MCP サーバードキュメント。コーディング参照不要。 |
+
+### 自動 Plan 同期（hooks）
+
+Claude Code が standard や rules ファイルを編集すると、PostToolUse hook が自動的に Master Plan を同期します：
+
+```
+AI が claudeos-core/standard/10.backend-api/01.controller-patterns.md を編集
+  → sync-hook が自動的に plan/10.standard-master.md を更新
+```
+
+手動同期は不要です。hook は `npx claudeos-core init` 時に自動インストールされます。
+
+---
+
 ## 日常ワークフロー
 
 ### インストール後
@@ -359,7 +400,7 @@ npx claudeos-core restore      # Plan → ディスク復元
 ### 標準ファイルを手動編集した後
 
 ```bash
-# 変更を Master Plan に同期
+# Claude Code の外部でファイルを編集した場合（hooks は Claude Code 内でのみ動作）：
 npx claudeos-core refresh
 
 # 整合性を検証
@@ -391,7 +432,7 @@ npx claudeos-core restore
 | **プロジェクト固有の出力** | ✅ すべてのファイルがあなたのパターンを反映 | ❌ 汎用コマンド | 部分的 | ❌ 画一的 |
 | **マルチスタック** | ✅ 自動検出 + 個別分析 | ❌ スタック非依存 | 手動 | 不定 |
 | **Kotlin + CQRS/BFF** | ✅ マルチモジュール、Command/Query分離 | ❌ | ❌ | ❌ |
-| **自己検証** | ✅ 6 つの検証ツール | ❌ | ❌ | ❌ |
+| **自己検証** | ✅ 5 つの検証ツール | ❌ | ❌ | ❌ |
 | **バックアップ / リストア** | ✅ Master Plan システム | ❌ | ❌ | ❌ |
 | **セットアップ時間** | ~5–18分（自動） | ~5分（手動設定） | 数時間–数日 | ~5分 |
 

package/README.ko.md

@@ -24,7 +24,7 @@ ClaudeOS-Core가 전체 프로세스를 자동화합니다:
 1. **스캔** — 스택, 도메인, ORM, DB, 패키지 매니저를 자동 감지
 2. **분석** — 컨트롤러 패턴, 서비스 레이어, 명명 규칙, 에러 처리, 보안, 테스트 등 50개+ 카테고리 심층 분석
 3. **생성** — `CLAUDE.md`, Standards (15–19개 파일), Rules, Skills, Guides (9개 파일), Master Plans, DB 문서, MCP 가이드 완전 생성
-4. **검증** — 6개 내장 검증 도구로 일관성 자동 확인
+4. **검증** — 5개 내장 검증 도구로 일관성 자동 확인
 
 총 소요 시간: 프로젝트 규모에 따라 **5–18분**. 수동 설정 불필요.
 
@@ -209,7 +209,6 @@ node claudeos-core-tools/manifest-generator/index.js
 node claudeos-core-tools/health-checker/index.js
 
 # 또는 개별 검사 실행:
-node claudeos-core-tools/import-linter/index.js        # @import validation
 node claudeos-core-tools/plan-validator/index.js --check # Plan ↔ disk
 node claudeos-core-tools/sync-checker/index.js          # Sync status
 node claudeos-core-tools/content-validator/index.js     # Content quality
@@ -334,7 +333,7 @@ your-project/
 
 ## 검증 도구
 
-ClaudeOS-Core에는 생성 후 자동으로 실행되는 6개의 내장 검증 도구가 포함되어 있습니다:
+ClaudeOS-Core에는 생성 후 자동으로 실행되는 5개의 내장 검증 도구가 포함되어 있습니다:
 
 ```bash
 # 한 번에 전체 확인 (권장)
@@ -348,15 +347,13 @@ npx claudeos-core restore      # Plan → 디스크 복원
 # node 직접 실행 (git clone 사용자)
 node claudeos-core-tools/health-checker/index.js
 node claudeos-core-tools/manifest-generator/index.js
-node claudeos-core-tools/import-linter/index.js
 node claudeos-core-tools/plan-validator/index.js --check
 node claudeos-core-tools/sync-checker/index.js
 ```
 
 | 도구 | 역할 |
 |---|---|
-| **manifest-generator** | 메타데이터 JSON 생성 (rule-manifest, import-graph, sync-map, plan-manifest) |
-| **import-linter** | `@import` 경로 검증 — 깨진 경로, 중복, 순환 참조 탐지 (DFS) |
+| **manifest-generator** | 메타데이터 JSON 생성 (rule-manifest, sync-map, plan-manifest) |
 | **plan-validator** | Master Plan `<file>` 블록과 디스크 비교 — check, refresh, restore 3가지 모드 |
 | **sync-checker** | 미등록 파일 (디스크에 있지만 Plan에 없는) 및 고아 항목 탐지 |
 | **content-validator** | 파일 품질 검증 — 빈 파일, ✅/❌ 예시 누락, 필수 섹션 확인 |
@@ -364,6 +361,49 @@ node claudeos-core-tools/sync-checker/index.js
 
 ---
 
+## Claude Code가 문서를 사용하는 방식
+
+ClaudeOS-Core가 생성한 문서를 Claude Code가 실제로 읽는 방식입니다:
+
+### 자동으로 읽는 파일
+
+| 파일 | 시점 | 보장 |
+|---|---|---|
+| `CLAUDE.md` | 매 대화 시작 시 | 항상 |
+| `.claude/rules/*.md` | 파일 편집 시 (`paths: ["**/*"]`) | 항상 |
+| `.claude/rules/00.core/00.standard-reference.md` | ↑ 위에 포함 | 항상 |
+
+### standard-reference 규칙을 통해 읽는 파일
+
+`00.standard-reference.md` 규칙이 Claude Code에게 코드 작성 전 아래 문서를 Read하도록 지시합니다:
+
+- `claudeos-core/standard/**` — 코딩 패턴, ✅/❌ 예시, 네이밍 규칙
+- `claudeos-core/database/**` — DB 스키마 (쿼리, 매퍼, 마이그레이션용)
+
+### 읽지 않는 파일 (컨텍스트 절약)
+
+standard-reference 규칙의 `DO NOT Read` 섹션으로 명시적으로 제외됩니다:
+
+| 폴더 | 제외 이유 |
+|---|---|
+| `claudeos-core/plan/` | Master Plan 백업 (~340KB). hooks로 자동 동기화. |
+| `claudeos-core/generated/` | 빌드 메타데이터 JSON. 코딩 참조 아님. |
+| `claudeos-core/guide/` | 사람을 위한 온보딩 가이드. |
+| `claudeos-core/mcp-guide/` | MCP 서버 문서. 코딩 참조 아님. |
+
+### 자동 Plan 동기화 (hooks)
+
+Claude Code가 standard나 rules 파일을 수정하면, PostToolUse hook이 자동으로 Master Plan을 동기화합니다:
+
+```
+AI가 claudeos-core/standard/10.backend-api/01.controller-patterns.md 수정
+  → sync-hook이 자동으로 plan/10.standard-master.md 업데이트
+```
+
+수동 동기화 불필요. hook은 `npx claudeos-core init` 시 자동 설치됩니다.
+
+---
+
 ## 일상 워크플로우
 
 ### 설치 후
@@ -378,7 +418,7 @@ node claudeos-core-tools/sync-checker/index.js
 ### 표준을 직접 편집한 후
 
 ```bash
-# 변경 사항을 Master Plan에 동기화
+# Claude Code 밖에서 파일을 수정한 경우 (hooks는 Claude Code 안에서만 동작):
 npx claudeos-core refresh
 
 # 전체 일관성 확인
@@ -410,7 +450,7 @@ npx claudeos-core restore
 | **프로젝트 특화 출력** | ✅ 모든 파일이 실제 패턴 반영 | ❌ 제네릭 명령어 | 부분적 | ❌ 획일적 |
 | **멀티스택** | ✅ 자동 감지 + 별도 분석 | ❌ 스택 무관 | 수동 | 다양 |
 | **Kotlin + CQRS/BFF** | ✅ 멀티모듈, Command/Query 분리 | ❌ | ❌ | ❌ |
-| **자체 검증** | ✅ 6개 검증 도구 | ❌ | ❌ | ❌ |
+| **자체 검증** | ✅ 5개 검증 도구 | ❌ | ❌ | ❌ |
 | **백업 / 복원** | ✅ Master Plan 시스템 | ❌ | ❌ | ❌ |
 | **설정 시간** | ~5–18분 (자동화) | ~5분 (수동 설정) | 수 시간–며칠 | ~5분 |