claudeos-core 1.2.1 → 1.2.3

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## [1.2.3] — 2026-04-03
+
+### Changed
+- **50.sync/ rules role clarified** — no longer described as "hooks fallback"; now the primary sync reminder mechanism (`npx claudeos-core refresh`)
+- All 6 pass3 templates updated to reference `npx claudeos-core refresh` instead of PostToolUse hooks
+- All 10 READMEs updated: removed "Automatic plan sync (hooks)" section, plan table now references `refresh` command
+
+### Fixed
+- **`plan-installer`**: malformed `package.json` no longer aborts entire `detectStack()` — Python, DB config, .env, and frontend config detection now continue normally
+
+### Removed
+- **Automatic hook installation removed from `init`** — `installSyncHooks()` function and `[2.5]` step removed from `cli.js`
+  - PostToolUse hooks caused instability: npx cache paths broke across environments, added latency to every Edit/Write
+  - Plan sync is now manual via `npx claudeos-core refresh` (same result, zero complexity)
+- All references to `PostToolUse`, `sync-hook`, and `.claude/settings.json` hooks removed from pass3 templates and READMEs
+
+## [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
@@ -289,7 +288,7 @@ your-project/
 │       ├── 20.frontend/
 │       ├── 30.security-db/
 │       ├── 40.infra/
-│       └── 50.sync/                   ← Auto-Sync-Regeln
+│       └── 50.sync/                   ← Sync-Erinnerungsregeln
 │
 ├── claudeos-core/                     ← Hauptausgabeverzeichnis
 │   ├── generated/                     ← Analyse-JSON + dynamische Prompts
@@ -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,38 @@ 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). Verwenden Sie `npx claudeos-core refresh` zur Synchronisation. |
+| `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. |
+
+---
+
 ## Täglicher Arbeitsablauf
 
 ### Nach der Installation
@@ -359,7 +389,7 @@ npx claudeos-core restore      # Plan → Festplatte Wiederherstellung
 ### Nach manueller Bearbeitung der Standards
 
 ```bash
-# Änderungen zum Master Plan synchronisieren
+# Nach dem Bearbeiten von Standard- oder Rules-Dateien:
 npx claudeos-core refresh
 
 # Konsistenz überprüfen
@@ -391,7 +421,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
@@ -289,7 +288,7 @@ your-project/
 │       ├── 20.frontend/
 │       ├── 30.security-db/
 │       ├── 40.infra/
-│       └── 50.sync/                   ← Reglas de sincronización automática
+│       └── 50.sync/                   ← Reglas de recordatorio de sincronización
 │
 ├── claudeos-core/                     ← Directorio principal de salida
 │   ├── generated/                     ← JSON de análisis + prompts dinámicos
@@ -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,38 @@ 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). Usa `npx claudeos-core refresh` para sincronizar. |
+| `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. |
+
+---
+
 ## Flujo de Trabajo Diario
 
 ### Después de la Instalación
@@ -359,7 +389,7 @@ npx claudeos-core restore      # Restauración Plan → Disco
 ### Después de Editar Estándares Manualmente
 
 ```bash
-# Sincroniza tus cambios al Master Plan
+# Después de editar archivos standard o rules:
 npx claudeos-core refresh
 
 # Verifica que todo sea consistente
@@ -391,7 +421,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
@@ -289,7 +288,7 @@ your-project/
 │       ├── 20.frontend/
 │       ├── 30.security-db/
 │       ├── 40.infra/
-│       └── 50.sync/                   ← Règles de synchronisation auto
+│       └── 50.sync/                   ← Règles de rappel de synchronisation
 │
 ├── claudeos-core/                     ← Répertoire principal de sortie
 │   ├── generated/                     ← JSON d'analyse + prompts dynamiques
@@ -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,38 @@ 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). Utilisez `npx claudeos-core refresh` pour synchroniser. |
+| `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. |
+
+---
+
 ## Flux de Travail Quotidien
 
 ### Après l'Installation
@@ -359,7 +389,7 @@ npx claudeos-core restore      # Restauration Plan → Disque
 ### Après Modification Manuelle des Standards
 
 ```bash
-# Synchroniser les changements vers le Master Plan
+# Après avoir édité des fichiers standard ou rules :
 npx claudeos-core refresh
 
 # Vérifier la cohérence
@@ -391,7 +421,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
@@ -289,7 +288,7 @@ your-project/
 │       ├── 20.frontend/
 │       ├── 30.security-db/
 │       ├── 40.infra/
-│       └── 50.sync/                   ← ऑटो-सिंक rules
+│       └── 50.sync/                   ← सिंक रिमाइंडर rules
 │
 ├── claudeos-core/                     ← मुख्य आउटपुट डायरेक्टरी
 │   ├── generated/                     ← एनालिसिस JSON + डायनामिक प्रॉम्प्ट्स
@@ -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,38 @@ 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)। `npx claudeos-core refresh` से सिंक करें। |
+| `claudeos-core/generated/` | बिल्ड मेटाडेटा JSON। कोडिंग रेफरेंस नहीं। |
+| `claudeos-core/guide/` | इंसानों के लिए ऑनबोर्डिंग गाइड। |
+| `claudeos-core/mcp-guide/` | MCP सर्वर डॉक्स। कोडिंग रेफरेंस नहीं। |
+
+---
+
 ## दैनिक वर्कफ़्लो
 
 ### इंस्टॉलेशन के बाद
@@ -359,7 +389,7 @@ npx claudeos-core restore      # Plan → डिस्क रीस्टोर
 ### स्टैंडर्ड्स मैन्युअली एडिट करने के बाद
 
 ```bash
-# बदलाव Master Plan में सिंक करें
+# standard या rules फाइल एडिट करने के बाद:
 npx claudeos-core refresh
 
 # सब कुछ कंसिस्टेंट है वेरिफाई करें
@@ -391,7 +421,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
@@ -289,7 +288,7 @@ your-project/
 │       ├── 20.frontend/
 │       ├── 30.security-db/
 │       ├── 40.infra/
-│       └── 50.sync/                   ← 自動同期ルール
+│       └── 50.sync/                   ← 同期リマインダールール
 │
 ├── claudeos-core/                     ← メイン出力ディレクトリ
 │   ├── generated/                     ← 分析 JSON + 動的プロンプト
@@ -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,38 @@ 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）。`npx claudeos-core refresh` で同期。 |
+| `claudeos-core/generated/` | ビルドメタデータ JSON。コーディング参照不要。 |
+| `claudeos-core/guide/` | 人間向けオンボーディングガイド。 |
+| `claudeos-core/mcp-guide/` | MCP サーバードキュメント。コーディング参照不要。 |
+
+---
+
 ## 日常ワークフロー
 
 ### インストール後
@@ -359,7 +389,7 @@ npx claudeos-core restore      # Plan → ディスク復元
 ### 標準ファイルを手動編集した後
 
 ```bash
-# 変更を Master Plan に同期
+# standard や rules ファイルを編集した後：
 npx claudeos-core refresh
 
 # 整合性を検証
@@ -391,7 +421,7 @@ npx claudeos-core restore
 | **プロジェクト固有の出力** | ✅ すべてのファイルがあなたのパターンを反映 | ❌ 汎用コマンド | 部分的 | ❌ 画一的 |
 | **マルチスタック** | ✅ 自動検出 + 個別分析 | ❌ スタック非依存 | 手動 | 不定 |
 | **Kotlin + CQRS/BFF** | ✅ マルチモジュール、Command/Query分離 | ❌ | ❌ | ❌ |
-| **自己検証** | ✅ 6 つの検証ツール | ❌ | ❌ | ❌ |
+| **自己検証** | ✅ 5 つの検証ツール | ❌ | ❌ | ❌ |
 | **バックアップ / リストア** | ✅ Master Plan システム | ❌ | ❌ | ❌ |
 | **セットアップ時間** | ~5–18分（自動） | ~5分（手動設定） | 数時間–数日 | ~5分 |