ai-developer-skill-os 8.1.10 → 8.2.0

package/.agents/CHANGELOG.md

@@ -5,6 +5,24 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ---
 
+## [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/.agents/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/.agents/blueprints/coding/project.yaml.tpl

@@ -0,0 +1,39 @@
+# project.yaml — Workspace Manifest for Software Coding Projects
+# Schema Version 1 — EDAOS v8.2 Governed Capability Platform
+schema_version: 1
+manifest_version: "8.2"
+
+project:
+  name: "{{PROJECT_NAME}}"
+  version: "0.1.0"
+  blueprint: "standard-software-coding"
+  description: "Clean, streamlined software engineering architecture with automated quality gating."
+
+  capabilities:
+    - qk-project-bootstrap
+    - qk-code-review
+    - qk-engineering-standard
+    - qk-bug-resolution
+    - qk-validation-gate
+  knowledge:
+    - clean-code-metrics
+    - design-intelligence
+  eval:
+    scorecard: "evals/scorecard.yaml"
+
+profiles:
+  development:
+    linter_strictness: standard
+    tools_mode: local_fs
+  production:
+    linter_strictness: maximum
+    tools_mode: ci_gated
+  testing:
+    linter_strictness: standard
+    tools_mode: unit_mock
+
+features:
+  registry: true
+  eval: true
+  planner: false
+  critic: false

package/.agents/blueprints/rag/project.yaml.tpl

@@ -0,0 +1,45 @@
+# project.yaml — Workspace Manifest for RAG & Production AI Agents
+# Schema Version 1 — EDAOS v8.2 Governed Capability Platform
+schema_version: 1
+manifest_version: "8.2"
+
+project:
+  name: "{{PROJECT_NAME}}"
+  version: "0.1.0"
+  blueprint: "rag-4-folder-architecture"
+  description: "RAG / Production AI Agent project powered by the standard 4-folder engineering blueprint."
+
+  # Recommended Folder Scaffolding:
+  # prompts/ - System prompts, tasks, tools (version-controlled as code)
+  # data/    - Immutable raw/ data and clean processed/ knowledge chunks
+  # agents/  - Customized subagents, domain micro-skills, and tool configurations
+  # evals/   - Quantitative tests/, traces/, and scorecards/
+
+  capabilities:
+    - qk-project-bootstrap
+    - qk-ai-builder
+    - qk-validation-gate
+    - qk-context-loader
+    - qk-docs
+  knowledge:
+    - architecture-standard
+    - security-guidelines
+  eval:
+    scorecard: "evals/scorecard.yaml"
+
+profiles:
+  development:
+    tools_mode: mock
+    log_level: debug
+  production:
+    tools_mode: real_mcp
+    log_level: error
+  testing:
+    tools_mode: trace_record
+    log_level: info
+
+features:
+  registry: true
+  eval: true
+  planner: false
+  critic: false

package/.agents/blueprints/workflow/project.yaml.tpl

@@ -0,0 +1,38 @@
+# project.yaml — Workspace Manifest for Automation Workflows (n8n / ETL)
+# Schema Version 1 — EDAOS v8.2 Governed Capability Platform
+schema_version: 1
+manifest_version: "8.2"
+
+project:
+  name: "{{PROJECT_NAME}}"
+  version: "0.1.0"
+  blueprint: "automation-workflow"
+  description: "Data ETL and business workflow automation pipeline driven by evidence-based evals."
+
+  capabilities:
+    - qk-project-bootstrap
+    - qk-data-lifecycle
+    - qk-api-lifecycle
+    - qk-validation-gate
+  knowledge:
+    - etl-patterns
+    - domain-patterns
+  eval:
+    scorecard: "evals/scorecard.yaml"
+
+profiles:
+  development:
+    webhook_target: staging
+    tools_mode: dry_run
+  production:
+    webhook_target: live
+    tools_mode: executed_live
+  testing:
+    webhook_target: mock_server
+    tools_mode: trace_record
+
+features:
+  registry: true
+  eval: true
+  planner: false
+  critic: false

package/.agents/knowledge/domain-patterns/construction/ddc-construction-ai-blueprint.md

@@ -0,0 +1,103 @@
+# Reference Blueprint: Construction AI Agent System (DDC Methodology)
+**EDAOS v8.2 Domain Pattern Implementation — Governed Capability Metadata & Eval Platform**
+
+Tài liệu này đóng vai trò là **Mô hình Mẫu Thực Chiến (Reference Case Study)** cho việc áp dụng kiến trúc **EDAOS v8.2** vào các nghiệp vụ kỹ thuật chuyên sâu (Enterprise Domain AI), tiêu biểu nhất là **Ngành Xây Dựng (Construction Engineering, BIM & ERP Automation)**.
+
+---
+
+## 1. Triết Lý Tách Biệt Ranh Giới (Zero Interference Principle)
+Trong EDAOS v8.2, các nghiệp vụ cụ thể thuộc các ngành chuyên biệt như Xây dựng (Construction), Tài chính (Finance), hay Y tế (Healthcare) là **các bản thi công tham chiếu (Reference Implementations)** được nạp theo định dạng Plugin tại Thư viện Tri thức: `.agents/knowledge/domain-patterns/*`.
+
+Tuyệt đối không nhồi nhét 192 skill ngành Xây Dựng vào 30 Master Capabilities cốt lõi của Lập trình viên để giữ chi phí nhận thức (cognitive load) và O(1) Dependency Graph của Antigravity ở mức nhẹ nhàng, nhanh chóng nhất.
+
+---
+
+## 2. Bản Đồ Năng Lực DDC (192 Domain-Specific Capabilities)
+Một hệ sinh thái AI Agent thực chiến cho doanh nghiệp xây dựng được cấu trúc thành 4 nhóm nghiệp vụ:
+
+### 🛠️ Nhóm 1: Toolkit Hoạt Động Hằng Ngày (85 Skills)
+- **Bóc tách & Dự toán (QTO / CWRICR):** Bóc khối lượng tự động từ mô hình IFC/Revit; tự động khớp đơn giá và tính hao phí vật liệu.
+- **Phân tích BIM:** Phát hiện xung đột mô hình (Clash Detection), báo cáo chất lượng BIM và tính toán dấu chân Carbon ($\text{CO}_2$).
+- **Chuyển đổi Dữ liệu CAD:** Tự động chuyển đổi hàng loạt DWG, DGN, IFC, Revit sang bảng tính Excel và ngược lại.
+- **Quản trị Hiện trường:** Lập báo cáo tiến độ thi công hằng ngày, phân tích năng suất tổ đội và xử lý Lệnh Thay Đổi (Change Order).
+
+### 🧠 Nhóm 2: Nền Tảng Dữ Liệu & Quy Trình Số (67 Skills)
+- **Xử lý Silo Dữ Liệu & ETL Tự Động:** Chuẩn hóa dữ liệu thô, liên thông ERP doanh nghiệp với mô hình BIM.
+- **AI / Machine Learning:** Truy vấn bằng vector search cho hồ sơ thầu, mô hình ML dự báo trượt giá và chi phí công trình.
+- **Kiểm định Chất lượng Dữ liệu:** Tự động hóa QA/QC trước khi đẩy dữ liệu vào RAG.
+
+### ⚙️ Nhóm 3: Vận Hành & Automation Workflows (20 Skills)
+- **Luồng n8n Automation:** Xây dựng các pipeline tự động đồng bộ báo cáo từ hiện trường về Văn phòng chính.
+- **Quản trị An toàn & Minh Bạch:** Đánh giá rủi ro lao động từ ảnh hiện trường và giám sát tiến độ theo thời gian thực.
+
+### 📄 Nhóm 4: Sinh Tài Liệu & QA (20 Skills)
+- **Soạn thảo Hợp đồng & Pháp lý:** Phân tích hợp đồng FIDIC, phát hiện các điều khoản rủi ro trong hồ sơ mời thầu.
+- **Báo cáo Tài chính & Bản vẽ Hoàn công:** Lập báo cáo chênh lệch ngân sách, theo dõi vật tư và bảo hành dự án.
+
+---
+
+## 3. Ứng Dụng "4-Folder Blueprint" Vào Dự Án Xây Dựng
+Khi bootstrap một dự án Xây dựng số với `project.yaml` (sử dụng blueprint `rag`), cấu trúc 4 thư mục quy chuẩn sẽ được kích hoạt để quản trị toàn bộ nguồn tri thức:
+
+```text
+ai-construction-project/
+├── project.yaml            ← Manifest gốc nạp bộ skill DDC & profile
+├── 📁 prompts/
+│   ├── system/             ← chuyen-gia-fidic.md, tro-ly-bim.md
+│   └── tasks/              ← boc-khoi-luong-ifc.md, phan-tich-truot-gia.md
+├── 📁 data/
+│   ├── raw/                ← Dữ liệu BẤT BIẾN: PDF thầu gốc, file DWG/Revit/IFC khách gửi
+│   └── processed/          ← Dữ liệu SẠCH: Bảng Excel đã lược bỏ dòng lặp, JSON cho RAG
+├── 📁 agents/
+│   ├── skills/             ← Các micro-skills chuyên sâu được nạp theo khuôn capability.yaml
+│   └── tools/              ← MCP kết nối Revit API, Excel ODBC, Google Drive
+└── 📁 evals/
+    ├── scorecards/         ← scorecard.yaml theo tiêu chuẩn rào dốc Ngành Xây Dựng
+    └── traces/             ← Nhật ký log chứng minh Agent đã bóc đúng bản vẽ
+```
+
+---
+
+## 4. Đặc Tả Metadata & Eval Kép Cho Ngành (Domain Capability Manifest)
+
+### Mẫu `capability.yaml` Cho Kỹ Năng Bóc Khối Lượng IFC
+```yaml
+schema_version: 1
+id: ddc-qto-ifc-extractor
+version: "1.0.0"
+description: "Tự động trích xuất và tính toán khối lượng vật liệu từ mô hình IFC xuất ra Excel chốt."
+dependencies:
+  - qk-validation-gate
+tools:
+  - read_file
+  - run_command
+knowledge:
+  - ddc-construction-ai-blueprint
+eval:
+  scorecard: evals/scorecards/qto-scorecard.yaml
+```
+
+### Mẫu `scorecard.yaml` Cho Kỹ Sư Kinh Tế Xây Dựng (Inheriting Default)
+Trong ngành xây dựng, một sai sót trong đơn giá hoặc bóc tách có thể dẫn đến thất Thoát hàng tỷ đồng. Do đó, bộ Scorecard chuyên biệt định nghĩa trọng số khắt khe:
+
+```yaml
+schema_version: 1
+extends: default
+passing_threshold: 90  # Đuôi chu du ranh giới cao tuyệt đối
+
+criteria:
+  pricing_and_qty_accuracy:
+    weight: 45
+    description: "Khối lượng bóc tách từ IFC phải khớp 100% với định danh công thức chuẩn CWRICR."
+  contractual_compliance:
+    weight: 30
+    description: "Các điều khoản và tham chiếu kỹ thuật phải trích dẫn chính xác từ hồ sơ FIDIC/raw."
+  audit_traceability:
+    weight: 25
+    description: "Log toàn bộ quy trình làm sạch từ data/raw sang data/processed mà không tự phán lụi."
+```
+
+---
+
+## 5. Kết Luận Kiến Trúc
+Mô hình Xây dựng DDC chứng minh tính hiệu quả và mở rộng kiệt xuất của **EDAOS v8.2**: Khi con người tổ chức rõ ràng (Blueprints), máy móc nạp đúng Manifest tối giản (`capability.yaml`, `project.yaml`), và chất lượng được giám sát bằng Eval Pipeline (`scorecard.yaml`), bất kỳ doanh nghiệp truyền thống nào cũng có thể hiện thực hóa lộ trình chuyển đổi số thành công theo thời gian thực!