ai-developer-skill-os 9.1.2 → 9.3.1

package/README.md

@@ -1,99 +1,205 @@
-# 🚀 AI Developer Skill OS (ai-developer-skill-os) v9.1.1
+# AI Developer Skill OS v9.3.1
 
-> **v9.1.1 "EDAOS v9.1 — Governed Capability & Universal Project Knowledge V1 Architecture"**
+> **v9.3.1 "EDAOS v9.3 — SSOT Trigger Discipline, 4-Tier Execution & Visual Terminal Rendering"**
 
-Hệ sinh thái AI Developer Skill OS tiến hóa lên phiên bản **V9.1.1 (EDAOS v9.1.1)** với kiến trúc **Universal Project Knowledge V1 (Local Private & Self-Init Architecture)**, kết hợp cùng mô hình Manifest-First và Eval Pipeline, biến AI từ trợ lý bị động thành Sư phụ Lập trình (Elite AI Engineer) thấu hiểu sâu sắc codebase và tri thức dự án với chi phí tra cứu gần như bằng 0.
+Phiên bản **v9.3.0** mang đến 5 nâng cấp chuẩn mực kỹ thuật toàn diện cho hệ điều hành AI coding agent:
+1. **SSOT 2-Clause Trigger Standard (Anthropic Standard)** — Đồng bộ 100% mô tả kích hoạt theo cấu trúc 2 vế (Năng lực cốt lõi + Cụm từ/ngữ cảnh kích hoạt thực tế) trên cả Frontmatter `SKILL.md`, danh sách `triggers` và Quick Table routing trong `.agents/AGENTS.md`.
+2. **Full-Body 4 Tầng Khép Kín (Closed-loop Body Structure)** — Toàn bộ 29 active skills được trang bị đầy đủ 4 tầng nội dung: Preconditions, Scope (In/Out-of-scope), Pipeline thực thi từng bước, và Prompt Templates theo Role.
+3. **Phân định ranh giới kỹ thuật (Boundary Disambiguation)** — Loại bỏ hoàn toàn sự chồng lấn/mơ hồ giữa các cặp kỹ năng (`qk-project-audit` vs `qk-project-health`, `qk-ui-audit` vs `qk-web-quality-gate`, `qk-access-policy` vs `qk-security-audit`).
+4. **Governed Skill Restructuring (29 Active, 2 Archived, 2 Relocated)** — Quy hoạch 29 Active skills, Archive 2 skills (`qk-frontend-architecture`, `qk-agent-observability`), Relocate 2 skills (`qk-engineering-standard` sang rules, `qk-validation-gate` sang eval runner), và bảo toàn 3 legacy skills v9.1.
+5. **Direct Terminal Visual Rendering (Unicode/ASCII Box Drawing)** — Chuẩn hóa hiển thị trực quan sơ đồ kiến trúc, flowchart trực tiếp ngay trong giao diện terminal.
 
 ---
 
-## 🧭 Kiến Trúc Trí Nhớ Dự Án (Universal Project Knowledge V1 - Local Private Mode)
-- **Quản trị như Source Code:** Tri thức dự án đơn giản, minh bạch, có thể xem xét (review) và **luôn có con người phê duyệt** (AI Đề xuất -> Con người Phê duyệt via `/learn` hoặc `./qk-project-memory`).
-- **Chính sách Local Private Duy Nhất & Tự động Khởi tạo (Self-Init Protocol):** 
-  - *Bộ Nhớ Cá Nhân (`.ai-local/`):* Toàn bộ tri thức ghi nhớ của dự án được tập trung lưu tại thư mục `.ai-local/` (bao gồm `AGENTS.md` và `knowledge/index.yaml`). Đã loại bỏ hoàn toàn chế độ dùng chung (`.agents/knowledge/index.yaml` - Shared Mode) để đảm bảo quyền riêng tư và tránh xung đột khi làm việc nhóm.
-  - *Tự động Khởi tạo & Bảo mật Gitignore:* Bất cứ khi nào AI kích hoạt kỹ năng hoặc cần tra cứu/học tri thức mà thư mục `.ai-local/` chưa tồn tại trong gốc dự án, AI **BẮT BUỘC** tự động tạo cấu trúc thư mục này và tự động thêm dòng `.ai-local/` vào file `.gitignore` của dự án ngay lập tức.
-- **Tối Ưu Nhảy Sọt (Navigator):** File `.ai-local/AGENTS.md` giới hạn siêu gọn dưới 100 dòng làm bản đồ chỉ đường, kết hợp cùng `.ai-local/knowledge/index.yaml` (lưu trữ đúng 4 loại: *Architecture, Convention, Pattern, Hard Bug*), triệt tiêu 80% chi phí tìm kiếm mù lòa (zero redundant searches).
+## Bắt đầu nhanh
 
----
+### Bước 1 — Khai báo role và stack một lần
 
-## 🏗️ 4 Trụ Cột Kiến Trúc Cốt Lõi (EDAOS v9.0 Architecture)
+Tạo file `.agents/DEV_PROFILE.md` trong dự án:
 
-### 1. Manifest-First & O(1) Registry Engine
-Không còn phụ thuộc vào việc đọc/scan toàn bộ markdown mệt mỏi. AI Agent tra cứu siêu dữ liệu từ `.agents/registry/index.yaml` và kiểm duyệt chu trình không lặp (acyclic validation) thông qua O(1) graph JSON (`.agents/registry/graph.json`). Tốc độ hiểu và phân công năng lực đạt ngưỡng sub-second!
+```yaml
+role: fullstack          # fe | be | fullstack | data | ai-engineer | devops
+stack:
+  frontend:  Next.js 14 + TypeScript
+  backend:   tRPC + Prisma
+  database:  PostgreSQL
+  css:       Tailwind CSS
+ai_style: concise        # concise | detailed | teaching
+```
 
-### 2. V8.2 Blueprint Plugins & Universal 4-Folder Architecture
-Khởi tạo dự án (chỉ đạo qua `qk-project-bootstrap`) hỗ trợ sinh file `project.yaml` gốc từ thư viện Blueprint Plugins:
-- **RAG / AI Agents:** Cấu trúc 4 thư mục chuẩn thực chiến: `prompts/`, `data/` (bảo vệ `data/raw` bất biến), `agents/`, và `evals/`.
-- **Standard Software Coding:** Kiến trúc module sạch vững chắc với `DESIGN.md` và rào cản kiểm duyệt tự động.
-- **Automation Workflows:** Các luồng tích hợp n8n và dữ liệu lớn.
+AI sẽ đọc file này trước mọi yêu cầu — không cần nhắc lại stack mỗi lần.
 
-### 3. Eval Pipeline Platform (Khép Kín Kiểm Định)
-Chấm dứt việc tin tưởng AI blindly. Mọi Capability đều có thẻ điểm định lượng (`scorecard.yaml`), kết nối log thực thi thực tế từ thư mục `evals/traces/` qua cổng thẩm định sắt đá `qk-validation-gate`. Trách nhiệm định lượng 0–100 với sai số 0% (zero tolerance for fabrication).
+### Bước 2 — Gọi skill
 
-### 4. Domain Patterns Separation (Bảo Vệ Kernel)
-Các hệ thống AI chuyên sâu (như **Xây dựng DDC 192 skills**, bóc tách BIM/IFC, ERP) được tải lập trình viên cấu hình dạng Module dưới `knowledge/domain-patterns/` thay vì phơi bày trực tiếp vào 30 Core Developer Skills, giữ cho đồ thị cốt lõi luôn nhanh bén mượt mà!
+```bash
+# Cú pháp command
+./qk-feature-delivery
+./qk-bug-resolution
+./qk-api-lifecycle --fw=fastapi
+
+# Hoặc ngôn ngữ tự nhiên — AI tự route đúng skill
+"fix bug login crash"
+"viết api tạo đơn hàng"
+"refactor file UserService.ts quá dài"
+```
 
----
+### Cài đặt
 
-## 🧩 Danh sách 30 Master Skills (Core Developer Capabilities)
+```bash
+# NPX (không cần cài global)
+npx ai-developer-skill-os init
+
+# NPM global
+npm i -g ai-developer-skill-os
+
+# Với tham số IDE
+npx ai-developer-skill-os init --ide=cursor --scope=1
+npx ai-developer-skill-os init --ide=windsurf --scope=1
+npx ai-developer-skill-os init --ide=antigravity --scope=2
+```
 
-Các kỹ năng được quản lý bằng **Capability Graph** và được đánh giá liên tục thông qua Evaluation Suite. Bao gồm 7 lĩnh vực:
-1. **Core & Orchestration:** `qk-orchestrator`, `qk-context-loader`, `qk-project-memory`, `qk-help`
-2. **Product & Architecture:** `qk-product-specification`, `qk-project-bootstrap`, `qk-frontend-architecture`
-3. **Frontend & UI:** `qk-design-system-engineering`, `qk-ui-system-builder`, `qk-ui-builder`, `qk-fe-api-integration`, `qk-ui-audit`
-4. **Backend & Data:** `qk-api-lifecycle`, `qk-data-lifecycle`, `qk-data-engineer`, `qk-access-policy`
-5. **Engineering & Delivery:** `qk-feature-delivery`, `qk-bug-resolution`, `qk-engineering-standard`, `qk-system-evolution`, `qk-docs`
-6. **Quality & Testing:** `qk-test-engineering`, `qk-validation-gate`, `qk-web-quality-gate`, `qk-project-health`
-7. **Security, DevOps & Analytics:** `qk-security-audit`, `qk-db-optimizer`, `qk-devops-platform`, `qk-production-release`, `qk-agent-observability`, `qk-ai-builder`
+**IDE được hỗ trợ:** Cursor · Windsurf · Cline / Roo Code · Antigravity · Kilo Code · Codex
 
 ---
 
-## 💻 Cách Cài Đặt (Installation)
+## Kiến trúc v9.3
 
-### Cách 1: NXP (Không cần cài global) - MỚI
-```bash
-npx ai-developer-skill-os init
 ```
-
-### Cách 2: NPM Global (Khuyên dùng cho cá nhân)
-```bash
-npm i -g ai-developer-skill-os
+.agents/
+├── DEV_PROFILE.md        ← Khai báo role + stack (đọc đầu mỗi session)
+├── AGENTS.md             ← Entry point: SSOT routing table + role behavior matrix
+├── GEMINI.md             ← Quy định riêng cho Antigravity (Terminal ASCII Diagrams, etc.)
+├── skills/               ← 29 active skills (mỗi skill có SKILL.md 4 tầng chuẩn mực)
+├── workflows/            ← 10 execution pipelines
+├── rules/                ← Behavior policies (coding, safety, security, anti-patterns...)
+├── registry/             ← Generated indexes (index.yaml, graph.json — sinh tự động)
+├── knowledge/            ← Design intelligence + domain patterns
+└── blueprints/           ← Project scaffold templates
 ```
 
-### Chạy bằng tham số (Command Line Arguments)
-```bash
-# Cài Antigravity Global (toàn máy)
-npx ai-developer-skill-os init --ide=antigravity --scope=2
+### Role Behavior Matrix
 
-# Cài Antigravity Local (chỉ dự án này)
-npx ai-developer-skill-os init --ide=antigravity --scope=1
+| Role | AI tập trung vào | AI bỏ qua |
+|---|---|---|
+| `fe` | Component arch, state, a11y, bundle size | DB schema, backend arch |
+| `be` | API contract, business logic, DB perf, security | CSS, UI layout |
+| `fullstack` | FE+BE end-to-end, type-safe contract | Over-engineering, microservices không cần thiết |
+| `data` | Idempotency, data quality, lineage, SLA | Application ORM, UI |
+| `ai-engineer` | Prompt eng, RAG arch, eval pipeline, hallucination | Standard CRUD |
+| `devops` | CI/CD, IaC, observability, rollback plan | Business logic, UI |
 
-# Cài Cursor Local
-npx ai-developer-skill-os init --ide=cursor --scope=1
-```
+---
 
-## 📦 Các IDE/AI Assistant Được Hỗ Trợ
-- (1) Cursor
-- (2) Windsurf
-- (3) Cline / Roo Code
-- (4) Antigravity / Gemini
-- (5) Codex
-- (6) Kilo Code
+## Danh mục 29 Active Skills (v9.3.0)
+
+### 1. Core & Orchestration (4 skills)
+| Skill | Mô tả theo chuẩn SSOT (2-clause) |
+|---|---|
+| `qk-orchestrator` | Điều hướng yêu cầu của người dùng đến đúng skill với kỷ luật thép — phân tích intent, kiểm tra preconditions và routing table. |
+| `qk-context-loader` | Khảo sát kiến trúc codebase, phân tích import graph, lập bản đồ phụ thuộc và tải context chính xác trước khi code — ngăn hallucination kiến trúc. |
+| `qk-project-memory` | Quản trị Tri thức và Bộ nhớ dự án (Local Private Mode) — Quản lý tại `.ai-local/` như source code: tự động khởi tạo, bảo mật gitignore, có thể review. |
+| `qk-project-bootstrap` | Khởi tạo dự án mới HOẶC setup `DEV_PROFILE.md` cho dự án đang chạy — auto-detect stack từ manifest files, không hỏi lại những gì đã đọc được. |
+
+### 2. Product & Analysis (2 skills)
+| Skill | Mô tả theo chuẩn SSOT (2-clause) |
+|---|---|
+| `qk-product-specification` | Tư duy phát triển sản phẩm: biến ý tưởng sơ khai thành yêu cầu kỹ thuật chi tiết (Idea → Requirement → Acceptance Criteria → Technical Spec). |
+| `qk-project-audit` | Phân tích toàn diện dự án: Gap Analysis, Feasibility, Risk Assessment — báo cáo trước khi code. *(Không dùng cho đo lường code smell của code đang chạy)* |
+
+> *Ghi chú:* `qk-frontend-architecture` đã được lưu trữ (Archived) — quy hoạch vào `qk-design-system-engineering` và `qk-ui-builder`.
+
+### 3. Frontend & UI (5 skills)
+| Skill | Mô tả theo chuẩn SSOT (2-clause) |
+|---|---|
+| `qk-ui-builder` | Xây dựng, sửa, audit, và hoàn thiện UI component từ Figma/ảnh/mô tả layout — responsive, chuẩn token, đầy đủ hover/active/loading states. |
+| `qk-ui-system-builder` | Xây dựng Design System và token library từ `DESIGN.md` — không tự đặt ra token ngoài contract. |
+| `qk-design-system-engineering` | Quản trị hệ thống thiết kế (Định nghĩa quy tắc hệ thống, tokens, các biến thể component, governance). |
+| `qk-api-consumer` | Consume API (REST/GraphQL/tRPC), quản lý State, xử lý loading/error/empty states, bind vào UI — tuân thủ kiến trúc dự án. |
+| `qk-ui-audit` | Kiểm toán chất lượng thiết kế UI với 57-check Anti-Slop checklist: spacing nhất quán, contrast ratio, component polish, interaction states. *(Không dùng cho WCAG a11y hay SEO)* |
+
+### 4. Backend & Data (5 skills)
+| Skill | Mô tả theo chuẩn SSOT (2-clause) |
+|---|---|
+| `qk-api-lifecycle` | Thiết kế và implement API endpoint mới với Zero-Trust — contract trước, code sau. |
+| `qk-data-lifecycle` | Quản lý Schema và Migration cơ sở dữ liệu an toàn — schema freeze, backward-compatible migrations, zero-downtime deployment. |
+| `qk-data-engineer` | Thiết kế và implement data pipeline với best practices: idempotency, data quality gate, lineage, incremental processing. |
+| `qk-access-policy` | Quản lý và thiết lập chính sách phân quyền RBAC/ABAC, định nghĩa permission matrix, sinh auth middleware bảo vệ endpoint. |
+| `qk-db-optimizer` | Tối ưu hiệu năng Database dựa trên bằng chứng kỹ thuật: phân tích EXPLAIN/ANALYZE, phát hiện N+1 queries, thiết kế Index, refactor slow query. |
+
+### 5. Engineering & Delivery (5 skills)
+| Skill | Mô tả theo chuẩn SSOT (2-clause) |
+|---|---|
+| `qk-feature-delivery` | Phát triển tính năng mới end-to-end: Requirements → Context → Design → Implement → Self-audit. |
+| `qk-bug-resolution` | Sửa lỗi bằng chu trình khép kín: Observe → Hypothesize → Evidence → Fix → Verify. |
+| `qk-refactor` | Tái cấu trúc code để dễ bảo trì, dễ test hơn — không thay đổi external behavior (extract, simplify, decouple). |
+| `qk-upgrade` | Nâng cấp library/framework an toàn — incremental strategy, audit breaking changes, rollback plan bắt buộc. |
+| `qk-docs` | Khởi tạo và duy trì tài liệu kỹ thuật chuẩn xác (README, API docs, architecture guides, JSDoc) — cam kết đồng bộ 100% với code thực tế. |
+
+### 6. Quality & Testing (4 skills)
+| Skill | Mô tả theo chuẩn SSOT (2-clause) |
+|---|---|
+| `qk-test-engineering` | Thiết kế chiến lược kiểm thử toàn diện và viết bộ test tự động: Test Pyramid (Unit, Integration, E2E), Mocking, Edge cases. |
+| `qk-project-health` | Kiểm toán toàn diện sức khỏe dự án: đo lường Code Smells, Technical Debt, độ phức tạp Cyclomatic, God files, vi phạm SOLID — chấm điểm Health Score (0–100). |
+| `qk-code-review` | Review code, AI config, hoặc skin rules theo 4 phases với Architect mindset — phát hiện bug, security issue, architecture smell. |
+| `qk-web-quality-gate` | Đo lường chất lượng kỹ thuật Web: Accessibility violations (WCAG), Core Web Vitals, Lighthouse score, SEO tags, security headers. |
+
+> *Ghi chú:*
+> - `qk-engineering-standard` đã được chuyển vị trí (Relocated) thành **Behavior Policy Rule** tại `.agents/rules/coding.md`.
+> - `qk-validation-gate` đã được chuyển vị trí (Relocated) thành **Eval Pipeline Script** tại `evals/runner.js`.
+
+### 7. Security, DevOps & AI (4 skills)
+| Skill | Mô tả theo chuẩn SSOT (2-clause) |
+|---|---|
+| `qk-security-audit` | Audit bảo mật ứng dụng theo OWASP: phát hiện lỗ hổng, secret leak, dependency risk, permission model — xuất report + remediation plan. |
+| `qk-devops-platform` | Kỹ sư nền tảng: Chiến lược CI/CD, kiến trúc triển khai, quản lý môi trường và chiến lược rollback. |
+| `qk-production-release` | Chuẩn bị release production với 8-gate checklist bắt buộc — không pass gate = không deploy. |
+| `qk-ai-builder` | Thiết kế và implement AI Agent hoặc RAG pipeline với eval criteria bắt buộc. |
+
+> *Ghi chú:* `qk-agent-observability` đã được lưu trữ (Archived) — tích hợp theo dõi vào test runner & runtime telemetry.
 
 ---
 
-## 🧪 Đánh Giá Tự Động (Agent Evaluation)
+## Changelog
+
+### v9.3.1 (2026-09-14) — EDAOS v9.3: Documentation & Governance Release
+- **Đồng bộ toàn diện tài liệu:** Cập nhật `README.md` và `CHANGELOG.md` đầy đủ chuẩn mực v9.3.
+- **SSOT 2-Clause Trigger Standard:** Áp dụng chuẩn Anthropic 2-vế cho toàn bộ 29 active skills, đồng bộ hoàn toàn giữa frontmatter `description`, `triggers` array và Quick Table trong `.agents/AGENTS.md`.
+- **Closed-Loop 4-Tier Execution Body:** Xóa bỏ toàn bộ 22 empty stubs, hoàn thiện đủ 4 phần (Preconditions, Scope, Steps, Prompt Templates).
+- **Boundary Disambiguation:** Phân định ranh giới rõ ràng giữa các cặp skill dễ nhầm lẫn (`qk-project-audit` vs `qk-project-health`, `qk-ui-audit` vs `qk-web-quality-gate`, `qk-access-policy` vs `qk-security-audit`).
+- **Skill Restructuring & Governance:**
+  - Quy hoạch 29 Active Skills chính thức.
+  - Archive 2 skills: `qk-frontend-architecture`, `qk-agent-observability`.
+  - Relocate 2 skills: `qk-engineering-standard` (thành Policy Rule `.agents/rules/coding.md`), `qk-validation-gate` (thành Eval Script `evals/runner.js`).
+  - Bảo toàn 3 legacy skills v9.1 (`qk-fe-api-integration`, `qk-help`, `qk-system-evolution`).
+- **Terminal Visual Rendering:** Quy định trong `GEMINI.md` về việc bắt buộc render sơ đồ/kiến trúc trực tiếp bằng Unicode/ASCII box drawing trong terminal.
+- **Vitest Isolation:** Thêm `vitest.config.js`, cô lập runner khỏi IDE worktrees (`.kilo/`), đảm bảo 10/10 test suites pass trong <1s.
+
+### v9.2.0 (2026-09-11)
+- **Thêm:** `DEV_PROFILE.md` — role + stack context file, AI đọc đầu mỗi session
+- **Thêm:** Role Behavior Matrix trong `AGENTS.md` — 6 roles với focus/depth/skip
+- **Thêm:** Prompt templates theo role trong 7 key skills
+- **Đổi tên:** `qk-fe-api-integration` → `qk-api-consumer` (rõ hơn, không FE-only)
+- **Đổi tên:** `qk-system-evolution` → `qk-upgrade` (đúng mục đích thực tế)
+- **Đổi tên:** `qk-project-analyst` → `qk-project-audit` (rõ output là audit report)
+- **Đổi tên workflow:** `skill-evolution.yml` → `skin-governance.yml`
+- **Đổi tên workflow:** `research.yml` → `context-discovery.yml`
+- **Xóa:** `qk-help` (deprecated từ v8.0, superseded bởi `qk-orchestrator`)
+- **Xóa:** `.ai-local/` Self-Init Protocol khỏi tất cả SKILL.md (giảm token overhead)
+- **Fix:** Compact routing table trong `AGENTS.md` — không cần đọc `skills-index.yml`
+
+### v9.1.x (2026-08-03)
+- O(1) registry engine, Universal Project Knowledge V1
+
+### v9.0.0 (2026-07-01)
+- V9 schema migration, manifest-first architecture
 
-Hệ thống đi kèm một bộ Runner nội bộ để kiểm toán **Routing Intelligence**. Bất kỳ cập nhật nào vào hệ thống Kỹ năng đều phải vượt qua bài kiểm tra hóc búa (Bypass Security, Boundary Attacks, Ambiguous Prompts):
+---
 
-```bash
-npm run test:agent
-npm run test:graph
-npm run test:registry
-```
+## Đánh giá tự động
 
-## 🚀 Hướng Dẫn Sử Dụng
-Sau khi cài đặt thành công, hãy gõ lệnh:
 ```bash
-./qk-help
+npm test                # Vitest runner (10/10 suites pass isolated)
+npm run test:registry   # Registry consistency check
+npm run test:graph      # Capability graph validation
+npm run eval:all        # Toàn bộ AI capability eval scorecards
 ```
-để kích hoạt AI Orchestrator và khám phá sức mạnh của hệ điều hành!

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-developer-skill-os",
-  "version": "9.1.2",
-  "description": "EDAOS v9.1 — Governed Capability Platform & Universal Project Knowledge V1 (Candidate Memory & Golden Rule Architecture).",
+  "version": "9.3.1",
+  "description": "EDAOS v9.3 — SSOT Governed Capability Platform with 2-Clause Triggers & Full Technical Lifecycle.",
   "main": "bin/install.js",
   "files": [
     "bin",

package/tooling/build-registry.js

@@ -20,7 +20,8 @@ const GRAPH_JSON = path.join(REGISTRY_DIR, 'graph.json');
 
 function parseYamlFile(filePath) {
   try {
-    const content = fs.readFileSync(filePath, 'utf8');
+    let content = fs.readFileSync(filePath, 'utf8');
+    if (content.charCodeAt(0) === 0xFEFF) content = content.slice(1);
     const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
     if (match) {
       return yaml.load(match[1]);
@@ -57,18 +58,24 @@ function buildRegistry() {
     let meta = null;
     let fromCapabilityYaml = false;
 
+    let skillMdMeta = null;
+    if (fs.existsSync(skillMdPath)) {
+      skillMdMeta = parseYamlFile(skillMdPath);
+    }
+
     if (fs.existsSync(capYamlPath)) {
       meta = parseYamlFile(capYamlPath);
       fromCapabilityYaml = true;
-    } else if (fs.existsSync(skillMdPath)) {
-      meta = parseYamlFile(skillMdPath);
+    } else if (skillMdMeta) {
+      meta = skillMdMeta;
     }
 
     if (!meta) continue;
 
     const id = meta.id || meta.name || dir;
-    const version = meta.version || '8.2.0';
-    const description = meta.description || '';
+    const version = meta.version || skillMdMeta?.version || '8.2.0';
+    const status = meta.status || skillMdMeta?.status || 'stable';
+    const description = meta.description || skillMdMeta?.description || '';
     
     // Normalize tags
     let tags = meta.tags || meta.keywords || [];
@@ -92,6 +99,7 @@ function buildRegistry() {
     capabilities[id] = {
       path: `.agents/skills/${dir}`,
       version,
+      status,
       tags,
       dependencies
     };
@@ -155,6 +163,11 @@ function buildRegistry() {
     };
   }
 
+  const allIds = Object.keys(capabilities);
+  const activeSkills = allIds.filter(id => capabilities[id].status === 'stable' || capabilities[id].status === 'experimental');
+  const archivedSkills = allIds.filter(id => capabilities[id].status === 'archived');
+  const relocatedSkills = allIds.filter(id => capabilities[id].status === 'relocated');
+
   const graphJsonData = {
     schema_version: 1,
     manifest_version: '8.2',
@@ -162,7 +175,10 @@ function buildRegistry() {
     nodes: graphNodes,
     adjacency,
     stats: {
-      total_capabilities: Object.keys(capabilities).length,
+      total_scanned: allIds.length,
+      active: activeSkills.length,
+      archived: archivedSkills.length,
+      relocated: relocatedSkills.length,
       has_cycles: hasCycles
     }
   };
@@ -173,14 +189,20 @@ function buildRegistry() {
       schema_version: 1,
       manifest_version: '8.2',
       generated_at: new Date().toISOString(),
+      stats: {
+        total_scanned: allIds.length,
+        active: activeSkills.length,
+        archived: archivedSkills.length,
+        relocated: relocatedSkills.length
+      },
       capabilities
     }, { indent: 2 });
 
   fs.writeFileSync(INDEX_YAML, indexYamlContent, 'utf8');
   fs.writeFileSync(GRAPH_JSON, JSON.stringify(graphJsonData, null, 2), 'utf8');
 
-  console.log(`✅ Generated lightweight registry index at .agents/registry/index.yaml (${Object.keys(capabilities).length} capabilities)`);
-  console.log(`✅ Generated O(1) adjacency graph at .agents/registry/graph.json (has_cycles: ${hasCycles})`);
+  console.log(`✅ Generated lightweight registry index at .agents/registry/index.yaml (${allIds.length} scanned: ${activeSkills.length} active, ${archivedSkills.length} archived, ${relocatedSkills.length} relocated)`);
+  console.log(`✅ Generated O(1) adjacency graph at .agents/registry/graph.json (active: ${activeSkills.length}, has_cycles: ${hasCycles})`);
 }
 
 buildRegistry();