ai-developer-skill-os 8.1.10 → 8.2.1

package/.agents/skills/qk-project-bootstrap/SKILL.md

@@ -1,9 +1,9 @@
 ---
 # ── Identity ───────────────────────────────────────────────
 name: qk-project-bootstrap
-version: 8.0.0
+version: 8.2.0
 status: stable
-description: "Khởi tạo dự án mới với cấu trúc chuẩn, linters, DESIGN.md — không bao giờ thiếu foundation."
+description: "Khởi tạo dự án mới theo chuẩn V8.2 Blueprint Plugin Generator (project.yaml, 4-folder AI RAG hoặc Coding) với cấu trúc kiên cường."
 platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
 
 # ── V8: Classification ─────────────────────────────────────
@@ -77,7 +77,7 @@ token_budget:
   max_files_read: 1
   max_lines_per_read: 50
   max_shell_commands: 2
-  stop_early: false
+  stop_early: true
 
 exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
 ---
@@ -100,77 +100,81 @@ On missing precondition:
 
 ---
 
-## Scope
-- ✅ Initialize project with standard tooling
-- ✅ Generate `DESIGN.md` (mandatory for any UI project)
-- ✅ Configure: ESLint, Prettier, TypeScript strict mode
-- ✅ Create standard directory structure
+## Scope & V8.2 Blueprint Generator
+- ✅ **One-Click Blueprint Selection:** Choose from Blueprint Plugins (`coding`, `rag`, `workflow`, `enterprise`).
+- ✅ **Generate `project.yaml`:** Copy appropriate manifest from `.agents/blueprints/<type>/project.yaml.tpl` to workspace root.
+- ✅ **Initialize Project Scaffolding:** Create standard directory structure (including the **4-Folder RAG Architecture** for AI projects).
+- ✅ **Configure Tooling:** Linter, Prettier, TypeScript strict mode, or Python environment depending on stack.
+- ✅ **Generate `DESIGN.md`:** Mandatory brand & token contract for any UI project.
 
 ## Non-Goals
+- ❌ Skip `project.yaml` workspace manifest initialization
 - ❌ Skip DESIGN.md for UI projects
 - ❌ Hardcode outdated dependency versions
-- ❌ Skip README
+- ❌ Skip README or documentation
 
 ---
 
-## Standard Directory Structures
-
-### Next.js / React
-```
-src/
-├── app/              # Pages (App Router) or pages/
-├── components/       # Shared UI components
-│   ├── ui/           # Design system primitives
-│   └── [feature]/    # Feature-specific components
-├── hooks/            # Custom React hooks
-├── lib/              # Utilities, helpers
-├── services/         # API service functions
-├── types/            # TypeScript type definitions
-└── styles/           # Global CSS + DESIGN.md tokens
-DESIGN.md             # Brand & Design Contract
+## V8.2 Blueprint Plugins & Directory Structures
+
+### 1. RAG & AI Agents (The 4-Folder Architecture Blueprint)
+*Activated when building AI agents, RAG engines, or domain automation.*
+```text
+project.yaml              # ⭐ V8.2 Workspace Manifest (Profiles & Capabilities)
+prompts/                  # Prompt instructions managed as code
+├── system/
+├── tasks/
+└── tools/
+data/                     # Strict data discipline
+├── raw/                  # IMMUTABLE original files (PDFs, Excel, Revit/CAD)
+└── processed/            # Cleaned, standardized chunks for AI ingestion
+agents/                   # Agent configurations and domain micro-skills
+├── skills/
+└── tools/
+evals/                    # Quantitative validation evidence
+├── tests/
+├── traces/               # Audit execution traces
+└── scorecards/           # scorecard.yaml eval rubrics
 ```
 
-### NestJS / Express API
-```
+### 2. Standard Coding Workspaces (Next.js / React / Node)
+*Activated when developing software applications or UI components.*
+```text
+project.yaml              # ⭐ V8.2 Workspace Manifest
 src/
-├── modules/
-│   └── [feature]/
-│       ├── [feature].controller.ts
-│       ├── [feature].service.ts
-│       ├── [feature].repository.ts
-│       └── dto/
-├── common/           # Shared utilities, guards, interceptors
-├── config/           # Environment configuration
-└── main.ts
+├── app/                  # Pages or App Router
+├── components/           # Shared UI components & Design system primitives
+├── hooks/
+├── lib/
+├── services/             # API integration & State stores
+├── types/
+└── styles/
+DESIGN.md                 # Brand & Design Contract
 ```
 
-### Vite + React
-```
-src/
-├── assets/
-├── components/
-├── pages/
-├── router/
-├── services/
-├── stores/           # State management
-└── types/
+### 3. Automation Workflows (n8n & Data ETL)
+```text
+project.yaml              # ⭐ V8.2 Workspace Manifest
+workflows/                # Automation graphs & JSON blueprints
+connectors/               # API & Database integrations
+pipelines/                # Transformation scripts
+evals/                    # Traceability logs
 ```
 
 ---
 
 ## Required Files Checklist
 ```
-[ ] package.json — with lint + test + build scripts
-[ ] tsconfig.json — strict: true enabled
-[ ] .eslintrc / eslint.config.js — project standard
-[ ] .prettierrc — formatting config
+[ ] project.yaml — V8.2 Machine-readable Workspace Manifest
+[ ] package.json / pyproject.toml — dependencies and scripts
+[ ] tsconfig.json — strict mode enabled (if TypeScript)
+[ ] .eslintrc / .prettierrc — project standard linting and formatting
 [ ] .gitignore — standard entries
 [ ] README.md — project description + setup instructions
 [ ] DESIGN.md — (UI projects) brand contract with color/font/spacing tokens
-[ ] .env.example — all env vars listed (no actual values)
+[ ] evals/scorecard.yaml — (AI/RAG/Workflow projects) eval standard
 ```
-
----
+-----
 
 ## DESIGN.md Minimum Template
 ```markdown

package/.agents/skills/qk-security-audit/SKILL.md

@@ -114,7 +114,7 @@ token_budget:
   max_files_read: 10
   max_lines_per_read: 150
   max_shell_commands: 2
-  stop_early: false
+  stop_early: true
 
 exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
 ---

package/.agents/skills/qk-system-evolution/SKILL.md

@@ -76,7 +76,7 @@ token_budget:
   max_files_read: 4
   max_lines_per_read: 100
   max_shell_commands: 2
-  stop_early: false
+  stop_early: true
 
 exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
 ---

package/.agents/skills/qk-test-engineering/SKILL.md

@@ -119,7 +119,7 @@ token_budget:
   max_files_read: 5
   max_lines_per_read: 150
   max_shell_commands: 0
-  stop_early: false
+  stop_early: true
 
 exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
 ---

package/.agents/skills/qk-ui-builder/SKILL.md

@@ -83,7 +83,7 @@ token_budget:
   max_files_read: 5
   max_lines_per_read: 150
   max_shell_commands: 0
-  stop_early: false
+  stop_early: true
 
 exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
 ---

package/.agents/skills/qk-validation-gate/SKILL.md

@@ -1,9 +1,9 @@
 ---
 # ── Identity ───────────────────────────────────────────────
 name: qk-validation-gate
-version: 8.0.0
+version: 8.2.0
 status: stable
-description: "Cổng kiểm tra chất lượng bắt buộc với ngưỡng pass/fail cụ thể — chặn đứng mọi mã nguồn lỗi."
+description: "Cổng kiểm tra chất lượng & Eval Pipeline bắt buộc — chạy linters, tests, và đánh giá scorecard.yaml định lượng cho AI Agent."
 platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
 
 # ── V8: Classification ─────────────────────────────────────
@@ -101,15 +101,17 @@ runtime_version: 1
 schema_version: 2
 ---
 
-## Scope
-- ✅ Run lint, type-check, tests, security audit in sequence
-- ✅ Enforce pass/fail with concrete thresholds
-- ✅ Report results with structured Evidence Format
+## Scope & V8.2 Eval Pipeline
+- ✅ Run lint, type-check, tests, and security audit in sequence
+- ✅ **Execute V8.2 Eval Pipeline:** Read `scorecard.yaml` (or inherited schemas) and compute quantitative scores for AI/Agent outputs.
+- ✅ Enforce pass/fail with concrete thresholds (Code coverage >= 80%, Eval scorecard >= passing threshold, typically 80/100).
+- ✅ Validate Trace execution logs in `evals/traces/` to ensure zero hallucination and ground-truth compliance.
+- ✅ Report results with structured Evidence Format.
 
 ## Non-Goals
 - ❌ Fix failing tests or lint errors (fixes go to qk-bug-resolution)
-- ❌ Skip any gate check unless user explicitly allows
-- ❌ Override failing thresholds with "ignore" flags
+- ❌ Skip any gate check or eval scorecard unless user explicitly allows
+- ❌ Override failing thresholds with "ignore" flags or fabricated LLM scores without trace evidence
 
 skill_version: 7.5.0
 runtime_version: 1
@@ -140,6 +142,11 @@ build:
   must_succeed: true
   max_warnings: 5
   bundle_size_limit: 500KB    # Gzipped (if applicable)
+
+eval_scorecard:
+  default_passing_threshold: 80 # minimum weighted evaluation score
+  trace_verification_required: true # must log tool executions in evals/traces
+  zero_tolerance_hallucination: true
 ```
 
 skill_version: 7.5.0

package/.agents/skills/qk-web-quality-gate/SKILL.md

@@ -94,7 +94,7 @@ token_budget:
   max_files_read: 5
   max_lines_per_read: 150
   max_shell_commands: 2
-  stop_early: false
+  stop_early: true
 
 exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
 ---

package/CHANGELOG.md

@@ -5,6 +5,34 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ---
 
+## [8.2.1] — 2026-07 — Token Optimization Patch
+
+### Fixed
+- **`stop_early: false` → `true` in 13 skills**: `qk-code-review`, `qk-data-lifecycle`, `qk-design-system-engineering`, `qk-devops-platform`, `qk-feature-delivery`, `qk-frontend-architecture`, `qk-production-release`, `qk-product-specification`, `qk-project-bootstrap`, `qk-security-audit`, `qk-system-evolution`, `qk-test-engineering`, `qk-ui-builder`, `qk-web-quality-gate` — skills now self-terminate when token budget is exhausted instead of running indefinitely.
+- **Removed 20 duplicate metadata blocks**: Stripped repeated `skill_version/runtime_version/schema_version` YAML blocks from `qk-orchestrator` (11×) and `qk-context-loader` (9×) — saves ~1320 chars per context load.
+- **`qk-code-review` Dynamic Context Loading: mandatory → on-demand**: References are now only read when a specific issue is found, not before every review. Eliminates 2 forced `view_file` calls per review session.
+- **`qk-feature-delivery` FAST PATH**: Simple tasks (≤1 file, no new API, no DB migration) now bypass `qk-context-loader` and Phase 1 clarification — saves 2–3 turns per simple fix.
+
+---
+
+## [8.2.0] — 2026-07 — EDAOS v8.2: Governed Capability Metadata & Eval Platform
+
+### Added
+- **Manifest-First Architecture & Registry Engine**: Created `tooling/build-registry.js` (`npm run build:registry`) generating lightweight lookup index `.agents/registry/index.yaml` and O(1) runtime adjacency graph `.agents/registry/graph.json` with cycle/orphan detection.
+- **V8.2 Blueprint Plugins**: Introduced customizable project scaffolding templates under `.agents/blueprints/` (`rag`, `coding`, `workflow`) featuring multi-profile environments (`development`, `production`, `testing`) and feature flags.
+- **Governed Capability Manifests**: Created minimalist `.agents/skills/_template/capability.yaml` (`schema_version: 1`) to decouple execution metadata from natural language instructions.
+- **Eval Pipeline Platform**: Added quantitative verification frameworks via inheritance-ready `.agents/skills/_template/evals/scorecard.yaml` (`extends: default`), linking ground-truth execution traces with automated score rubrics.
+- **Domain Patterns Reference Architecture**: Added reference blueprint for Enterprise Domain AI at `.agents/knowledge/domain-patterns/construction/ddc-construction-ai-blueprint.md` (Construction AI, DDC 192 domain skills, QTO IFC bóc tách, n8n automation workflows) showcasing zero interference with core developer capabilities.
+
+### Changed
+- **`qk-project-bootstrap` Evolution (v8.2.0)**: Upgraded to support One-Click Blueprint selection, automated `project.yaml` generation, and the Universal 4-Folder RAG Architecture (`prompts/`, `data/`, `agents/`, `evals/`).
+- **`qk-validation-gate` Evolution (v8.2.0)**: Integrated automated Eval Pipeline validation, reading `scorecard.yaml` rubrics, verifying trace logs in `evals/traces/`, and enforcing quantitative pass thresholds.
+- **`qk-ai-builder` Evolution (v8.2.0)**: Upgraded to Manifest-first capability packaging and strict 4-folder data discipline (immutable `data/raw/` vs cleaned `data/processed/`).
+- Updated system core description in `package.json` to reflect the EDAOS v8.2 paradigm shift.
+- Synced `.agents/CHANGELOG.md` and `.agents/README.md` with root documentation.
+
+---
+
 ## [8.1.7] — 2026-07 — README Sync
 
 ### Changed

package/README.md

@@ -1,27 +1,31 @@
-# 🚀 AI Developer Skill OS (ai-developer-skill-os) v8.1.7
+# 🚀 AI Developer Skill OS (ai-developer-skill-os) v8.2.0
 
-> **v8.1.7 "Agent Engineering OS + Design Intelligence"**
+> **v8.2.0 "EDAOS v8.2 — Governed Capability Metadata & Eval Platform"**
 
-Hệ sinh thái AI Developer Skill OS đã lột xác hoàn toàn. Từ một bộ "công cụ phân tán" (Toolbox) ở V7, phiên bản V8.1.7 được thiết kế như một **Hệ điều hành khép kín (Agent Engineering OS)**, sở hữu năng lực giám sát, bảo vệ ranh giới quyết định (Decision Boundaries) và được trang bị thêm tầng **Design Intelligence**.
+Hệ sinh thái AI Developer Skill OS tiến hóa lên phiên bản **V8.2.0 (EDAOS v8.2)** với kiến trúc **Manifest-First & Eval Platform**, giúp giảm tối đa chi phí nhận thức (cognitive load) cho các AI Agent thế hệ mới (như Antigravity) nhờ chỉ định ranh giới định lượng, đồ thị phụ thuộc O(1), và các Blueprint Plugins quy chuẩn cho từng ngành nghề kỹ thuật.
 
 ---
 
-## 🏗️ Triết Lý Hoạt Động Cốt Lõi (V8 Kernel)
+## 🏗️ 4 Trụ Cột Kiến Trúc Cốt Lõi (EDAOS v8.2 Architecture)
 
-### 1. Decision Boundary (Ranh giới Thẩm quyền)
-Không còn tình trạng một Skill ôm đồm mọi việc. Mọi Skill (Kỹ năng) hiện tại bị quản lý bởi các trường `owns`, `does_not_own`, `conflicts_with`, `delegates_to`. Thợ code UI (`qk-ui-builder`) không được phép tự ra quyết định kiến trúc, và ngược lại.
+### 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!
 
-### 2. Design Intelligence Layer
-Khắc phục điểm yếu "mù thẩm mỹ" của AI. Agent giờ đây không chỉ biết code mà còn có Gu Thẩm Mỹ (Design Taste). Dựa trên yêu cầu của bạn, hệ thống tự động tra cứu **Knowledge Graph** để chọn đúng Theme (Fintech, Healthcare, SaaS...), Typography và Visual Patterns trước khi giao việc cho UI Builder.
+### 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.
 
-### 3. Khế Ước Đi Đầu (Contract-First & Zero-Trust)
-- **Frontend / UI**: Mọi sửa đổi phải tuân thủ Design System (được `qk-design-system-engineering` kiểm duyệt).
-- **Backend / API**: Phải viết OpenAPI/Swagger contract trước (`qk-api-lifecycle`).
-- **Data**: Cấm AI tự đoán cấu trúc DB, mọi truy vấn phải có Schema (`qk-data-lifecycle`).
+### 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).
+
+### 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à!
 
 ---
 
-## 🧩 Danh sách 30 Master Skills
+## 🧩 Danh sách 30 Master Skills (Core Developer Capabilities)
 
 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`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-developer-skill-os",
-  "version": "8.1.10",
-  "description": "Agent Engineering OS: A deterministic capability graph, governance rules, and dynamic knowledge base for AI coding agents.",
+  "version": "8.2.1",
+  "description": "EDAOS v8.2 — Governed Capability Metadata & Eval Platform: Blueprints organize, manifests govern, registries accelerate.",
   "main": "bin/install.js",
   "files": [
     "bin",
@@ -20,9 +20,10 @@
     "node": ">=18.0.0"
   },
   "scripts": {
+    "build:registry": "node tooling/build-registry.js",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:registry": "vitest run --config vitest.config.js",
+    "test:registry": "vitest run && node tooling/build-registry.js",
     "test:graph": "node tooling/validate-graph.js",
     "lint": "node bin/lint.js",
     "test:agent": "node tests/agent-evaluation/runner/evaluate-routing.js",
@@ -49,7 +50,11 @@
     "developer",
     "agent",
     "prompts",
-    "framework"
+    "framework",
+    "edaos",
+    "manifest",
+    "registry",
+    "eval"
   ],
   "author": "Quang Khánh",
   "license": "MIT",

package/tooling/build-registry.js

@@ -0,0 +1,186 @@
+/**
+ * build-registry.js
+ * V8.2 Governed Capability Metadata & Eval Platform
+ * Generates registry/index.yaml (lightweight lookup) and registry/graph.json (O(1) graph & cycle check)
+ * 
+ * Usage: node tooling/build-registry.js
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import yaml from 'js-yaml';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const SKILLS_DIR = path.join(__dirname, '../.agents/skills');
+const REGISTRY_DIR = path.join(__dirname, '../.agents/registry');
+const INDEX_YAML = path.join(REGISTRY_DIR, 'index.yaml');
+const GRAPH_JSON = path.join(REGISTRY_DIR, 'graph.json');
+
+function parseYamlFile(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (match) {
+      return yaml.load(match[1]);
+    }
+    return yaml.load(content);
+  } catch (e) {
+    console.error(`[WARN] Failed to parse YAML from ${filePath}: ${e.message}`);
+    return null;
+  }
+}
+
+function buildRegistry() {
+  console.log('🔄 Building V8.2 Governed Capability Registry & O(1) Runtime Graph...');
+
+  if (!fs.existsSync(SKILLS_DIR)) {
+    console.error('❌ Skills directory not found:', SKILLS_DIR);
+    process.exit(1);
+  }
+
+  fs.mkdirSync(REGISTRY_DIR, { recursive: true });
+
+  const dirs = fs.readdirSync(SKILLS_DIR).filter(d => 
+    !d.startsWith('_') && fs.statSync(path.join(SKILLS_DIR, d)).isDirectory()
+  );
+
+  const capabilities = {};
+  const adjacency = {};
+  const reverseAdjacency = {};
+
+  for (const dir of dirs) {
+    const capYamlPath = path.join(SKILLS_DIR, dir, 'capability.yaml');
+    const skillMdPath = path.join(SKILLS_DIR, dir, 'SKILL.md');
+    
+    let meta = null;
+    let fromCapabilityYaml = false;
+
+    if (fs.existsSync(capYamlPath)) {
+      meta = parseYamlFile(capYamlPath);
+      fromCapabilityYaml = true;
+    } else if (fs.existsSync(skillMdPath)) {
+      meta = parseYamlFile(skillMdPath);
+    }
+
+    if (!meta) continue;
+
+    const id = meta.id || meta.name || dir;
+    const version = meta.version || '8.2.0';
+    const description = meta.description || '';
+    
+    // Normalize tags
+    let tags = meta.tags || meta.keywords || [];
+    if (!Array.isArray(tags) || tags.length === 0) {
+      // Derive simple tags from dir words
+      tags = dir.replace(/^qk-/, '').split('-');
+    }
+
+    // Normalize dependencies
+    let dependencies = meta.dependencies || [];
+    if (!fromCapabilityYaml) {
+      // Derive from V8.1 skill frontmatter decision_boundary / workflow
+      const deps = new Set();
+      if (meta.workflow && typeof meta.workflow === 'string') deps.add(meta.workflow);
+      if (meta.decision_boundary?.delegates_to) {
+        meta.decision_boundary.delegates_to.forEach(d => deps.add(d));
+      }
+      dependencies = Array.from(deps);
+    }
+
+    capabilities[id] = {
+      path: `.agents/skills/${dir}`,
+      version,
+      tags,
+      dependencies
+    };
+
+    adjacency[id] = dependencies;
+    if (!reverseAdjacency[id]) reverseAdjacency[id] = [];
+  }
+
+  // Populate reverse adjacency for orphan detection
+  for (const [id, deps] of Object.entries(adjacency)) {
+    for (const dep of deps) {
+      if (!reverseAdjacency[dep]) reverseAdjacency[dep] = [];
+      reverseAdjacency[dep].push(id);
+    }
+  }
+
+  // Detect cycles using DFS
+  let hasCycles = false;
+  const visited = {};
+  const recursionStack = {};
+
+  function detectCycle(node) {
+    visited[node] = true;
+    recursionStack[node] = true;
+
+    const deps = adjacency[node] || [];
+    for (const dep of deps) {
+      if (!visited[dep]) {
+        if (detectCycle(dep)) return true;
+      } else if (recursionStack[dep]) {
+        return true;
+      }
+    }
+
+    recursionStack[node] = false;
+    return false;
+  }
+
+  for (const node of Object.keys(adjacency)) {
+    if (!visited[node]) {
+      if (detectCycle(node)) {
+        hasCycles = true;
+        break;
+      }
+    }
+  }
+
+  // Build Graph JSON (O(1) Runtime lookups)
+  const graphNodes = {};
+  for (const [id, data] of Object.entries(capabilities)) {
+    const dependents = reverseAdjacency[id] || [];
+    const isOrphan = data.dependencies.length === 0 && dependents.length === 0 && id !== 'qk-orchestrator' && id !== 'qk-help';
+
+    graphNodes[id] = {
+      path: data.path,
+      version: data.version,
+      tags: data.tags,
+      dependencies: data.dependencies,
+      dependents,
+      is_orphan: isOrphan
+    };
+  }
+
+  const graphJsonData = {
+    schema_version: 1,
+    manifest_version: '8.2',
+    generated_at: new Date().toISOString(),
+    nodes: graphNodes,
+    adjacency,
+    stats: {
+      total_capabilities: Object.keys(capabilities).length,
+      has_cycles: hasCycles
+    }
+  };
+
+  // Build Registry Index YAML (Lightweight lookup)
+  const indexYamlContent = `# AUTO-GENERATED BY registry-builder (tooling/build-registry.js)\n# DO NOT EDIT MANUALLY. THIS IS A GENERATED RUNTIME ARTIFACT.\n` +
+    yaml.dump({
+      schema_version: 1,
+      manifest_version: '8.2',
+      generated_at: new Date().toISOString(),
+      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})`);
+}
+
+buildRegistry();