claudeos-core 1.2.0 → 1.2.2

package/README.md

@@ -23,7 +23,7 @@ ClaudeOS-Core automates the entire process:
 1. **Scans** your project — detects stack, domains, ORM, DB, package manager automatically
 2. **Analyzes** your source code in depth — controller patterns, service layers, naming conventions, error handling, security, testing, and 50+ categories
 3. **Generates** a complete documentation ecosystem — `CLAUDE.md`, Standards (15–19 files), Rules, Skills, Guides (9 files), Master Plans, DB docs, and MCP guide
-4. **Validates** everything — 6 built-in verification tools ensure consistency
+4. **Validates** everything — 5 built-in verification tools ensure consistency
 
 Total time: **5–18 minutes**, depending on project size. Zero manual configuration.
 
@@ -214,7 +214,6 @@ node claudeos-core-tools/manifest-generator/index.js
 node claudeos-core-tools/health-checker/index.js
 
 # Or run individual checks:
-node claudeos-core-tools/import-linter/index.js        # @import path validation
 node claudeos-core-tools/plan-validator/index.js --check # Plan ↔ disk consistency
 node claudeos-core-tools/sync-checker/index.js          # Unregistered/orphaned files
 node claudeos-core-tools/content-validator/index.js     # File quality checks
@@ -347,7 +346,7 @@ For multi-stack projects (e.g., Java + React), backend and frontend domains are
 
 ## Verification Tools
 
-ClaudeOS-Core includes 6 built-in verification tools that run automatically after generation:
+ClaudeOS-Core includes 5 built-in verification tools that run automatically after generation:
 
 ```bash
 # Run all checks at once (recommended)
@@ -361,15 +360,13 @@ npx claudeos-core restore      # Plan → Disk restore
 # Or use node directly (git clone users)
 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
 ```
 
 | Tool | What It Does |
 |---|---|
-| **manifest-generator** | Builds metadata JSON (rule-manifest, import-graph, sync-map, plan-manifest) |
-| **import-linter** | Validates `@import` paths — detects broken, duplicate, and circular imports (DFS) |
+| **manifest-generator** | Builds metadata JSON (rule-manifest, sync-map, plan-manifest) |
 | **plan-validator** | Compares Master Plan `<file>` blocks against disk — 3 modes: check, refresh, restore |
 | **sync-checker** | Detects unregistered files (on disk but not in plan) and orphaned entries |
 | **content-validator** | Validates file quality — empty files, missing ✅/❌ examples, required sections |
@@ -377,6 +374,49 @@ node claudeos-core-tools/sync-checker/index.js
 
 ---
 
+## How Claude Code Uses Your Documentation
+
+ClaudeOS-Core generates documentation that Claude Code actually reads — here's how:
+
+### What Claude Code reads automatically
+
+| File | When | Guaranteed |
+|---|---|---|
+| `CLAUDE.md` | Every conversation start | Always |
+| `.claude/rules/*.md` | When any file is edited (via `paths: ["**/*"]`) | Always |
+| `.claude/rules/00.core/00.standard-reference.md` | ↑ Included above | Always |
+
+### What Claude Code reads via standard-reference rule
+
+The `00.standard-reference.md` rule instructs Claude Code to Read the standard documents before writing code:
+
+- `claudeos-core/standard/**` — coding patterns, ✅/❌ examples, naming conventions
+- `claudeos-core/database/**` — DB schema (for queries, mappers, migrations)
+
+### What Claude Code does NOT read (saves context)
+
+These folders are explicitly excluded via the `DO NOT Read` section in the standard-reference rule:
+
+| Folder | Why excluded |
+|---|---|
+| `claudeos-core/plan/` | Master Plan backups (~340KB). Auto-synced by hooks. |
+| `claudeos-core/generated/` | Build metadata JSON. Not for coding. |
+| `claudeos-core/guide/` | Onboarding guides for humans. |
+| `claudeos-core/mcp-guide/` | MCP server docs. Not for coding. |
+
+### Automatic plan sync (hooks)
+
+When Claude Code edits a standard or rules file, a PostToolUse hook automatically syncs the change to the Master Plan:
+
+```
+AI edits claudeos-core/standard/10.backend-api/01.controller-patterns.md
+  → sync-hook automatically updates plan/10.standard-master.md
+```
+
+No manual sync needed. The hook is installed automatically during `npx claudeos-core init`.
+
+---
+
 ## Daily Workflow
 
 ### After Installation
@@ -391,7 +431,7 @@ node claudeos-core-tools/sync-checker/index.js
 ### After Manually Editing Standards
 
 ```bash
-# Sync your changes to the Master Plan
+# If you edited files outside of Claude Code (hooks only trigger inside Claude Code):
 npx claudeos-core refresh
 
 # Verify everything is consistent
@@ -423,7 +463,7 @@ npx claudeos-core restore
 | **Project-specific output** | ✅ Every file reflects your patterns | ❌ Generic commands | Partially | ❌ One-size-fits-all |
 | **Multi-stack** | ✅ Auto-detected + separate analysis | ❌ Stack-agnostic | Manual | Varies |
 | **Kotlin + CQRS/BFF** | ✅ Multi-module, Command/Query split | ❌ | ❌ | ❌ |
-| **Self-verifying** | ✅ 6 validation tools | ❌ | ❌ | ❌ |
+| **Self-verifying** | ✅ 5 validation tools | ❌ | ❌ | ❌ |
 | **Backup / Restore** | ✅ Master Plan system | ❌ | ❌ | ❌ |
 | **Setup time** | ~5–18min (automated) | ~5min (manual config) | Hours–Days | ~5min |
 

package/README.ru.md

@@ -23,7 +23,7 @@ ClaudeOS-Core автоматизирует весь процесс:
 1. **Сканирует** ваш проект — автоматически определяет стек, домены, ORM, базу данных, пакетный менеджер
 2. **Глубоко анализирует** исходный код — паттерны контроллеров, сервисные слои, соглашения об именовании, обработка ошибок, безопасность, тестирование и 50+ категорий
 3. **Генерирует** полную экосистему документации — `CLAUDE.md`, Standards (15–19 файлов), Rules, Skills, Guides (9 файлов), Master Plans, документацию БД и руководство 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** | Сравнивает блоки `<file>` Master Plan с диском — 3 режима: check, refresh, restore |
 | **sync-checker** | Обнаруживает незарегистрированные файлы (на диске, но не в плане) и осиротевшие записи |
 | **content-validator** | Проверяет качество файлов — пустые файлы, отсутствующие примеры ✅/❌, обязательные секции |
@@ -345,6 +343,49 @@ npx claudeos-core restore      # Восстановление Plan → Диск
 
 ---
 
+## Как Claude Code использует вашу документацию
+
+Вот как Claude Code фактически читает документацию, сгенерированную ClaudeOS-Core:
+
+### Автоматически читаемые файлы
+
+| Файл | Когда | Гарантия |
+|---|---|---|
+| `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/**` — Схема БД (для запросов, мапперов, миграций)
+
+### Файлы, которые НЕ читаются (экономия контекста)
+
+Явно исключены через секцию `DO NOT Read` правила standard-reference:
+
+| Папка | Причина исключения |
+|---|---|
+| `claudeos-core/plan/` | Резервные копии Master Plan (~340КБ). Автосинхронизация через hooks. |
+| `claudeos-core/generated/` | JSON метаданных сборки. Не для кодирования. |
+| `claudeos-core/guide/` | Руководства для людей. |
+| `claudeos-core/mcp-guide/` | Документация MCP сервера. Не для кодирования. |
+
+### Автоматическая синхронизация Plan (hooks)
+
+Когда Claude Code редактирует файл standard или rules, хук PostToolUse автоматически синхронизирует Master Plan:
+
+```
+AI редактирует claudeos-core/standard/10.backend-api/01.controller-patterns.md
+  → sync-hook автоматически обновляет plan/10.standard-master.md
+```
+
+Ручная синхронизация не требуется. Хук устанавливается автоматически при `npx claudeos-core init`.
+
+---
+
 ## Повседневный рабочий процесс
 
 ### После установки
@@ -359,7 +400,7 @@ npx claudeos-core restore      # Восстановление Plan → Диск
 ### После ручного редактирования стандартов
 
 ```bash
-# Синхронизировать изменения в Master Plan
+# Если файлы редактировались вне Claude Code (хуки работают только внутри 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.vi.md

@@ -23,7 +23,7 @@ ClaudeOS-Core tự động hóa toàn bộ quy trình:
 1. **Quét** dự án — tự động phát hiện stack, domain, ORM, database, package manager
 2. **Phân tích chuyên sâu** mã nguồn — controller patterns, service layers, quy ước đặt tên, xử lý lỗi, bảo mật, testing và hơn 50 danh mục
 3. **Tạo** hệ sinh thái tài liệu hoàn chỉnh — `CLAUDE.md`, Standards (15–19 file), Rules, Skills, Guides (9 file), Master Plans, tài liệu DB và hướng dẫn MCP
-4. **Xác thực** mọi thứ — 6 công cụ kiểm tra tích hợp đảm bảo tính nhất quán
+4. **Xác thực** mọi thứ — 5 công cụ kiểm tra tích hợp đảm bảo tính nhất quán
 
 Tổng thời gian: **5–18 phút**, tùy thuộc vào quy mô dự án. Không cần cấu hình thủ công.
 
@@ -209,7 +209,6 @@ node claudeos-core-tools/manifest-generator/index.js
 node claudeos-core-tools/health-checker/index.js
 
 # Hoặc chạy kiểm tra riêng lẻ:
-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 @@ Với dự án multi-stack (ví dụ: Java + React), domain backend và frontend
 
 ## Công Cụ Xác Thực
 
-ClaudeOS-Core bao gồm 6 công cụ xác thực tích hợp, chạy tự động sau khi tạo:
+ClaudeOS-Core bao gồm 5 công cụ xác thực tích hợp, chạy tự động sau khi tạo:
 
 ```bash
 # Chạy tất cả kiểm tra cùng lúc (khuyến nghị)
@@ -336,8 +335,7 @@ npx claudeos-core restore      # Khôi phục Plan → Đĩa
 
 | Công Cụ | Chức Năng |
 |---|---|
-| **manifest-generator** | Xây dựng JSON metadata (rule-manifest, import-graph, sync-map, plan-manifest) |
-| **import-linter** | Xác thực đường dẫn `@import` — phát hiện import bị hỏng, trùng lặp và vòng tròn (DFS) |
+| **manifest-generator** | Xây dựng JSON metadata (rule-manifest, sync-map, plan-manifest) |
 | **plan-validator** | So sánh khối `<file>` của Master Plan với đĩa — 3 chế độ: check, refresh, restore |
 | **sync-checker** | Phát hiện file chưa đăng ký (trên đĩa nhưng không trong plan) và mục mồ côi |
 | **content-validator** | Xác thực chất lượng file — file trống, thiếu ví dụ ✅/❌, phần bắt buộc |
@@ -345,6 +343,49 @@ npx claudeos-core restore      # Khôi phục Plan → Đĩa
 
 ---
 
+## Claude Code Sử Dụng Tài Liệu Như Thế Nào
+
+Đây là cách Claude Code thực sự đọc tài liệu được ClaudeOS-Core tạo ra:
+
+### File được đọc tự động
+
+| File | Thời điểm | Đảm bảo |
+|---|---|---|
+| `CLAUDE.md` | Mỗi lần bắt đầu cuộc trò chuyện | Luôn luôn |
+| `.claude/rules/*.md` | Khi chỉnh sửa file (qua `paths: ["**/*"]`) | Luôn luôn |
+| `.claude/rules/00.core/00.standard-reference.md` | ↑ Bao gồm ở trên | Luôn luôn |
+
+### File được đọc qua quy tắc standard-reference
+
+Quy tắc `00.standard-reference.md` hướng dẫn Claude Code Read tài liệu standard trước khi viết code:
+
+- `claudeos-core/standard/**` — Pattern coding, ví dụ ✅/❌, quy tắc đặt tên
+- `claudeos-core/database/**` — DB schema (cho query, mapper, migration)
+
+### File KHÔNG đọc (tiết kiệm context)
+
+Được loại trừ rõ ràng qua phần `DO NOT Read` của quy tắc standard-reference:
+
+| Thư mục | Lý do loại trừ |
+|---|---|
+| `claudeos-core/plan/` | Backup Master Plan (~340KB). Tự đồng bộ bằng hooks. |
+| `claudeos-core/generated/` | JSON metadata build. Không dùng cho coding. |
+| `claudeos-core/guide/` | Hướng dẫn onboarding cho người dùng. |
+| `claudeos-core/mcp-guide/` | Tài liệu MCP server. Không dùng cho coding. |
+
+### Đồng bộ Plan tự động (hooks)
+
+Khi Claude Code chỉnh sửa file standard hoặc rules, hook PostToolUse tự động đồng bộ Master Plan:
+
+```
+AI chỉnh sửa claudeos-core/standard/10.backend-api/01.controller-patterns.md
+  → sync-hook tự động cập nhật plan/10.standard-master.md
+```
+
+Không cần đồng bộ thủ công. Hook được cài đặt tự động khi chạy `npx claudeos-core init`.
+
+---
+
 ## Quy Trình Làm Việc Hàng Ngày
 
 ### Sau Khi Cài Đặt
@@ -359,7 +400,7 @@ npx claudeos-core restore      # Khôi phục Plan → Đĩa
 ### Sau Khi Chỉnh Sửa Thủ Công Standards
 
 ```bash
-# Đồng bộ thay đổi vào Master Plan
+# Nếu bạn chỉnh sửa file bên ngoài Claude Code (hooks chỉ hoạt động bên trong Claude Code):
 npx claudeos-core refresh
 
 # Xác minh mọi thứ nhất quán
@@ -391,7 +432,7 @@ npx claudeos-core restore
 | **Đầu ra riêng dự án** | ✅ Mọi file phản ánh pattern của bạn | ❌ Lệnh chung | Một phần | ❌ Một cỡ cho tất cả |
 | **Multi-stack** | ✅ Tự phát hiện + phân tích riêng | ❌ Không phân biệt stack | Thủ công | Không chắc |
 | **Kotlin + CQRS/BFF** | ✅ Multi-module, Command/Query split | ❌ | ❌ | ❌ |
-| **Tự xác thực** | ✅ 6 công cụ validation | ❌ | ❌ | ❌ |
+| **Tự xác thực** | ✅ 5 công cụ validation | ❌ | ❌ | ❌ |
 | **Backup / Khôi phục** | ✅ Hệ thống Master Plan | ❌ | ❌ | ❌ |
 | **Thời gian cài đặt** | ~5–18 phút (tự động) | ~5 phút (cấu hình thủ công) | Hàng giờ–ngày | ~5 phút |
 

package/README.zh-CN.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** | 检测未注册文件（磁盘有但计划中没有）和孤立条目 |
 | **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/**` — 数据库 schema（查询、mapper、迁移用）
+
+### 不读取的文件（节省上下文）
+
+通过 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/bin/cli.js

@@ -150,6 +150,64 @@ function injectProjectRoot(text) {
   return text.replace(/\{\{PROJECT_ROOT\}\}/g, PROJECT_ROOT);
 }
 
+// ─── Install sync hooks into .claude/settings.json ──────
+function installSyncHooks() {
+  const settingsPath = path.join(PROJECT_ROOT, ".claude/settings.json");
+
+  // Determine sync-hook script path (relative to project root)
+  // Works for both npx (node_modules) and git clone (direct path) usage
+  let syncHookScript;
+  const npxPath = path.join(PROJECT_ROOT, "node_modules/claudeos-core/sync-hook/index.js");
+  const localPath = path.join(TOOLS_DIR, "sync-hook/index.js");
+
+  if (fs.existsSync(npxPath)) {
+    syncHookScript = "node node_modules/claudeos-core/sync-hook/index.js";
+  } else if (fs.existsSync(localPath)) {
+    const relScript = path.relative(PROJECT_ROOT, localPath).replace(/\\/g, "/");
+    syncHookScript = `node ${relScript}`;
+  } else {
+    log("    ⏭️  sync-hook script not found, skipping");
+    return;
+  }
+
+  const hookEntry = {
+    matcher: "Edit|Write",
+    command: `${syncHookScript} "$TOOL_INPUT_FILE"`
+  };
+
+  let settings = {};
+  if (fs.existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+    } catch {
+      // Malformed JSON — start fresh but warn
+      log("    ⚠️  Existing settings.json was malformed, recreating");
+      settings = {};
+    }
+  }
+
+  // Ensure hooks.PostToolUse array exists
+  if (!settings.hooks) settings.hooks = {};
+  if (!Array.isArray(settings.hooks.PostToolUse)) settings.hooks.PostToolUse = [];
+
+  // Check if sync-hook is already installed (avoid duplicates)
+  const alreadyInstalled = settings.hooks.PostToolUse.some(
+    (h) => h.command && h.command.includes("sync-hook")
+  );
+
+  if (alreadyInstalled) {
+    log("    ✅ Sync hooks already installed");
+    return;
+  }
+
+  settings.hooks.PostToolUse.push(hookEntry);
+
+  ensureDir(path.dirname(settingsPath));
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+  log("    ✅ Sync hooks installed → .claude/settings.json");
+  log(`    Hook: PostToolUse (Edit|Write) → ${syncHookScript}`);
+}
+
 // ─── Command: init ───────────────────────────────────────
 async function cmdInit() {
   // ─── Prerequisites check ───────────────────────────────────
@@ -179,7 +237,7 @@ async function cmdInit() {
   }
 
   // Verify Claude is authenticated (quick prompt test)
-  const claudeAuth = run('claude -p "echo ok" --max-tokens 10', { silent: true, ignoreError: true });
+  const claudeAuth = run('claude -p "echo ok"', { silent: true, ignoreError: true });
   if (!claudeAuth) {
     log("\n  ⚠️  Claude Code may not be authenticated.");
     log("  Run: claude (and complete authentication)");
@@ -250,6 +308,11 @@ async function cmdInit() {
   }
   log("    ✅ Done\n");
 
+  // ─── [2.5] Install sync hooks in .claude/settings.json ────
+  header("[2.5] Installing sync hooks...");
+  installSyncHooks();
+  log("");
+
   // ─── [3] Run plan-installer ─────────────────────────
   header("[3] Analyzing project (plan-installer)...");
   run(`node "${path.join(TOOLS_DIR, "plan-installer/index.js")}"`);

package/content-validator/index.js

@@ -7,7 +7,7 @@
  * Validation items:
  *   - File is not empty
  *   - standard files contain ✅/❌ examples + rules table
- *   - rules files contain paths: frontmatter + @import
+ *   - rules files contain paths: ["all files"] frontmatter
  *   - CLAUDE.md required sections exist
  *   - All 9 guide files are generated
  *   - Skills orchestrator + sub-skills exist
@@ -102,17 +102,14 @@ async function main() {
         errors.push({ file: r, type: "EMPTY", msg: "Empty file" });
         continue;
       }
-      // sync rules don't need paths
+      // All rules (except sync) must have paths: ["**/*"] frontmatter
       if (!r.includes("50.sync")) {
         const hasFrontmatter = c.startsWith("---");
         const hasPathsKey = c.includes("paths:");
         if (!hasFrontmatter) {
           warnings.push({ file: r, type: "NO_FRONTMATTER", msg: "Missing YAML frontmatter (---)" });
         } else if (!hasPathsKey) {
-          warnings.push({ file: r, type: "NO_PATHS", msg: "Frontmatter exists but missing paths: key" });
-        }
-        if (!/^@[^\s]+/m.test(c)) {
-          warnings.push({ file: r, type: "NO_IMPORT", msg: "No @import reference found" });
+          warnings.push({ file: r, type: "NO_PATHS", msg: "Frontmatter exists but missing paths: key — use paths: [\"**/*\"] to ensure rule is always loaded" });
         }
       }
     }

package/health-checker/index.js

@@ -6,11 +6,10 @@
  * Role: Execute all verification tools sequentially and output consolidated results
  * Execution order:
  *   [0] manifest-generator  ← prerequisite: generates metadata like sync-map.json
- *   [1] import-linter        ← @import path validation
- *   [2] plan-validator       ← Plan ↔ disk consistency
- *   [3] sync-checker         ← sync verification based on sync-map.json (requires manifest)
- *   [4] content-validator    ← generated file quality validation
- *   [5] pass-json-validator  ← Pass 1-3 JSON format validation
+ *   [1] plan-validator       ← Plan ↔ disk consistency
+ *   [2] sync-checker         ← sync verification based on sync-map.json (requires manifest)
+ *   [3] content-validator    ← generated file quality validation
+ *   [4] pass-json-validator  ← Pass 1-3 JSON format validation
  *
  * Usage: npx claudeos-core <cmd> or node claudeos-core-tools/health-checker/index.js
  */
@@ -58,9 +57,8 @@ function main() {
   }
   console.log();
 
-  // ─── [1-5] Run verification tools sequentially ────────────────────
+  // ─── [1-4] Run verification tools sequentially ────────────────────
   const tools = [
-    { name: "import-linter",       script: path.join(TOOLS, "import-linter/index.js"),       desc: "@import validation"          },
     { name: "plan-validator",      script: path.join(TOOLS, "plan-validator/index.js"),      desc: "Plan consistency"           },
     { name: "sync-checker",        script: path.join(TOOLS, "sync-checker/index.js"),        desc: "Sync status"                },
     { name: "content-validator",   script: path.join(TOOLS, "content-validator/index.js"),   desc: "Content quality"            },

package/import-linter/index.js

@@ -1,15 +1,13 @@
 #!/usr/bin/env node
 
 /**
- * ClaudeOS-Core — Import Linter
+ * ClaudeOS-Core — Import Linter (DEPRECATED)
  *
- * Role: Validate @import paths in .claude/rules/, standard/, skills/, guide/
- * Validation items:
- *   - BROKEN:   @import pointing to non-existent file
- *   - DUPLICATE: Same path imported multiple times in the same file
- *   - CIRCULAR: Circular @import chain detected (DFS)
+ * @deprecated @import is not a real Claude Code feature and has been removed.
+ * Rules now use paths frontmatter with wildcard glob to ensure they are always loaded.
+ * This tool is kept for backward compatibility but is no longer run by health-checker.
  *
- * Usage: npx claudeos-core <cmd> or node claudeos-core-tools/import-linter/index.js
+ * Usage: node claudeos-core-tools/import-linter/index.js
  */
 
 const fs = require("fs");

package/manifest-generator/index.js

@@ -6,7 +6,7 @@
  * Role: Generate 4 types of metadata JSON + initialize stale-report
  * Output (claudeos-core/generated/):
  *   - rule-manifest.json   : rules/standard/skills/guide file list + frontmatter
- *   - import-graph.json    : @import dependency graph (nodes + edges)
+ *   - import-graph.json    : (deprecated — kept for backward compatibility, @import removed)
  *   - sync-map.json        : plan/ <file> block → file path mapping
  *   - plan-manifest.json   : plan/ file list + <file> block count
  *   - stale-report.json    : initialized (each verification tool appends results)
@@ -54,25 +54,6 @@ function frontmatter(f) {
   }
 }
 
-function extractImports(f) {
-  const content = fs.readFileSync(f, "utf-8");
-  const result = [];
-  let inCodeFence = false;
-  for (const line of content.split("\n")) {
-    if (/^```/.test(line)) { inCodeFence = !inCodeFence; continue; }
-    if (inCodeFence) continue;
-    const m = line.match(/^@(\.\.?\/[^\s]+)/);
-    if (m) {
-      const target = path.resolve(path.dirname(f), m[1]);
-      result.push({
-        raw: m[0],
-        resolved: rel(target),
-        exists: fs.existsSync(target),
-      });
-    }
-  }
-  return result;
-}
 
 function extractFileBlocks(f) {
   if (!fs.existsSync(f)) return [];
@@ -136,34 +117,16 @@ async function main() {
   fs.writeFileSync(path.join(GEN, "rule-manifest.json"), JSON.stringify(mf, null, 2));
   console.log(`  ✅ rule-manifest.json — ${mf.summary.total} files indexed`);
 
-  // ─── import-graph.json ─────────────────────────────────
-  const gr = { generatedAt: new Date().toISOString(), nodes: [], edges: [], errors: [] };
-  const ns = new Set();
-
-  const importScanDirs = [DIRS.rules, DIRS.standard, DIRS.skills, DIRS.guide, DIRS.database, DIRS.mcpGuide].filter(Boolean);
-  for (const scanDir of importScanDirs) {
-    if (!fs.existsSync(scanDir)) continue;
-    for (const f of await glob("**/*.md", { cwd: scanDir, absolute: true })) {
-      const r = rel(f);
-      ns.add(r);
-      for (const i of extractImports(f)) {
-        ns.add(i.resolved);
-        gr.edges.push({ from: r, to: i.resolved, exists: i.exists });
-        if (!i.exists) {
-          gr.errors.push({ type: "broken_import", file: r, target: i.resolved });
-        }
-      }
-    }
-  }
-
-  gr.nodes = Array.from(ns).sort();
-  gr.summary = {
-    totalNodes: gr.nodes.length,
-    totalEdges: gr.edges.length,
-    brokenImports: gr.errors.length,
+  // ─── import-graph.json (deprecated — @import removed) ──
+  const gr = {
+    generatedAt: new Date().toISOString(),
+    deprecated: true,
+    note: "@import is not a Claude Code feature and has been removed. Rules now use paths: [\"**/*\"] frontmatter.",
+    nodes: [], edges: [], errors: [],
+    summary: { totalNodes: 0, totalEdges: 0, brokenImports: 0 },
   };
   fs.writeFileSync(path.join(GEN, "import-graph.json"), JSON.stringify(gr, null, 2));
-  console.log(`  ✅ import-graph.json — ${gr.summary.totalEdges} edges, ${gr.summary.brokenImports} broken`);
+  console.log("  ✅ import-graph.json — deprecated (no @imports)");
 
   // ─── sync-map.json ─────────────────────────────────────
   const sm = { generatedAt: new Date().toISOString(), mappings: [] };