ai-developer-skill-os 10.1.0 → 10.2.0

package/tooling/validate-graph.js

@@ -1,87 +1,100 @@
-import fs from 'fs';
-import path from 'path';
-import yaml from 'js-yaml';
-
-const GRAPH_FILE = path.resolve('.agents/registry/capability-graph.yml');
-
-function validateGraph() {
-  if (!fs.existsSync(GRAPH_FILE)) {
-    console.error('Không tìm thấy capability-graph.yml');
-    process.exit(1);
-  }
-
-  const content = fs.readFileSync(GRAPH_FILE, 'utf8');
-  const graph = yaml.load(content);
-
-  const nodes = Object.keys(graph.nodes || {});
-  const edges = graph.edges || [];
-
-  let errors = [];
-  
-  // 1. Kiểm tra edge references (tồn tại node đích)
-  let conflictsCount = 0;
-  edges.forEach(e => {
-    if (!nodes.includes(e.to)) {
-       // Cảnh báo nhưng không luôn lỗi vì to có thể là tên workflow
-       if (e.relation !== 'depends_on') {
-         errors.push(`Edge error: '${e.from}' trỏ đến '${e.to}' không tồn tại trong nodes (${e.relation})`);
-       }
-    }
-    if (e.relation === 'conflicts_with') conflictsCount++;
-  });
-
-  // 2. Kiểm tra reverse delegation (implementation -> architecture)
-  // Logic giả định dựa trên keyword
-  edges.forEach(e => {
-    if (e.relation === 'delegates_to') {
-       if (e.from.includes('ui-builder') && e.to.includes('architecture')) {
-           errors.push(`Policy violation: Implementation skill '${e.from}' không được delegate cho Architecture skill '${e.to}'`);
-       }
-    }
-  });
-
-  // 3. Isolated nodes (Ngoại trừ qk-orchestrator, qk-product-specification)
-  let orphanCount = 0;
-  const allowedIsolated = ['qk-orchestrator', 'qk-product-specification'];
-  
-  const connectedNodes = new Set();
-  edges.forEach(e => {
-    connectedNodes.add(e.from);
-    if (nodes.includes(e.to)) connectedNodes.add(e.to);
-  });
-
-  nodes.forEach(n => {
-    if (!connectedNodes.has(n)) {
-       if (!allowedIsolated.includes(n)) {
-          errors.push(`Orphan node: '${n}' bị cô lập (không nối đi đâu, không ai nối tới).`);
-          orphanCount++;
-       }
-    }
-  });
-
-  // Mock Cycles check
-  let cyclesCount = 0; // Để đơn giản, giả lập 0 cycles. Trong thực tế dùng thuật toán DFS.
-
-  const score = Math.max(0, 100 - (errors.length * 5));
-
-  console.log('─────────────────────────────────────────────────');
-  console.log('📊 Capability Graph Health');
-  console.log('─────────────────────────────────────────────────');
-  console.log(`Nodes:       ${nodes.length}`);
-  console.log(`Edges:       ${edges.length}`);
-  console.log(`Coverage:    100%`);
-  console.log(`Conflicts:   ${conflictsCount}`);
-  console.log(`Orphan:      ${orphanCount}`);
-  console.log(`Cycles:      ${cyclesCount}`);
-  console.log(`\nScore:       ${score}/100`);
-  
-  if (errors.length > 0) {
-    console.log('\n⚠️ Cảnh báo & Lỗi:');
-    errors.forEach(err => console.log(`- ${err}`));
-    process.exit(1);
-  } else {
-    console.log('\n✅ Capability Graph hợp lệ.');
-  }
-}
-
-validateGraph();
+import fs from 'fs';
+import path from 'path';
+
+const GRAPH_FILE = path.resolve('.agents/registry/graph.json');
+
+function validateGraph() {
+  if (!fs.existsSync(GRAPH_FILE)) {
+    console.error('Không tìm thấy graph.json');
+    process.exit(1);
+  }
+
+  const content = fs.readFileSync(GRAPH_FILE, 'utf8');
+  const graph = JSON.parse(content);
+
+  const nodes = Object.keys(graph.nodes || {});
+  const edges = graph.edges || [];
+  const adjacency = graph.adjacency || {};
+
+  let errors = [];
+  
+  // 1. Kiểm tra edge references (tồn tại node đích)
+  let conflictsCount = 0;
+  edges.forEach(e => {
+    if (!nodes.includes(e.to)) {
+       // Cảnh báo nhưng không luôn lỗi vì to có thể là tên workflow
+       if (e.relation !== 'depends_on') {
+         errors.push(`Edge error: '${e.from}' trỏ đến '${e.to}' không tồn tại trong nodes (${e.relation})`);
+       }
+    }
+    if (e.relation === 'conflicts_with') conflictsCount++;
+  });
+  // 2. Isolated nodes (Ngoại trừ qk-orchestrator)
+  let orphanCount = 0;
+  const allowedIsolated = ['qk-orchestrator'];
+  
+  const connectedNodes = new Set();
+  edges.forEach(e => {
+    connectedNodes.add(e.from);
+    connectedNodes.add(e.to);
+  });
+
+  nodes.forEach(n => {
+    if (!connectedNodes.has(n)) {
+       if (!allowedIsolated.includes(n)) {
+          errors.push(`Orphan node: '${n}' bị cô lập.`);
+          orphanCount++;
+       }
+    }
+  });
+
+  // Cycle detection using DFS
+  let cyclesCount = 0;
+  const visited = {};
+  const recursionStack = {};
+
+  function detectCycle(node) {
+    visited[node] = true;
+    recursionStack[node] = true;
+    const neighbors = adjacency[node] || [];
+    for (const neighbor of neighbors) {
+      if (!visited[neighbor]) {
+        if (detectCycle(neighbor)) return true;
+      } else if (recursionStack[neighbor]) {
+        cyclesCount++;
+        return true;
+      }
+    }
+    recursionStack[node] = false;
+    return false;
+  }
+
+  for (const node of nodes) {
+    if (!visited[node]) {
+      detectCycle(node);
+    }
+  }
+
+  const score = Math.max(0, 100 - (errors.length * 5) - (cyclesCount * 2));
+
+  console.log('─────────────────────────────────────────────────');
+  console.log('📊 Capability Graph Health');
+  console.log('─────────────────────────────────────────────────');
+  console.log(`Nodes:       ${nodes.length}`);
+  console.log(`Edges:       ${edges.length}`);
+  console.log(`Coverage:    100%`);
+  console.log(`Conflicts:   ${conflictsCount}`);
+  console.log(`Orphan:      ${orphanCount}`);
+  console.log(`Cycles:      ${cyclesCount}`);
+  console.log(`\nScore:       ${score}/100`);
+  
+  if (errors.length > 0) {
+    console.log('\n⚠️ Cảnh báo & Lỗi:');
+    errors.forEach(err => console.log(`- ${err}`));
+    process.exit(1);
+  } else {
+    console.log('\n✅ Capability Graph hợp lệ.');
+  }
+}
+
+validateGraph();

package/tooling/validate-skills.js

@@ -28,11 +28,13 @@ function parseFrontmatter(content) {
   };
 
   const name = extract('name');
-  const version = extract('version') || '7.5.0';
+  const version = extract('version') || '10.2.0';
   let status = extract('status');
   
   if (!status && (version.startsWith('8.') || version.startsWith('9.'))) {
       status = 'stable';
+  } else if (!status && version.startsWith('10.')) {
+      status = 'stable';
   } else if (!status) {
       status = 'legacy';
   }
@@ -41,10 +43,16 @@ function parseFrontmatter(content) {
     name,
     version,
     status,
-    hasIntent: yamlString.includes('intent:'),
     hasWorkflow: yamlString.includes('workflow:'),
-    hasVerification: yamlString.includes('verification:'),
-    hasSelection: yamlString.includes('selection:')
+    hasTriggers: yamlString.includes('triggers:'),
+    hasRules: yamlString.includes('rules:'),
+    hasClassification: yamlString.includes('classification:'),
+    hasReferences: yamlString.includes('references:'),
+    isV10Frontmatter: yamlString.includes('classification:'),
+    isLegacyFrontmatter: yamlString.includes('workflow:') && !yamlString.includes('classification:'),
+    isV10Format: (yamlString.includes('classification:') && yamlString.includes('references:')) ||
+                 (yamlString.includes('workflow:') && !yamlString.includes('classification:')),
+    hasPlatforms: yamlString.includes('platforms:')
   };
 }
 
@@ -58,8 +66,8 @@ function validate() {
     .filter(d => !d.startsWith('_') && fs.statSync(path.join(SKILLS_DIR, d)).isDirectory());
 
   let totalScanned = 0;
-  let stableValid = 0;
-  let stableTotal = 0;
+  let v10Valid = 0;
+  let v10Total = 0;
   let legacyIgnored = 0;
   let missingRequiredCount = 0;
 
@@ -73,13 +81,23 @@ function validate() {
 
     totalScanned++;
 
-    if (meta.status === 'stable' || meta.status === 'experimental') {
-      stableTotal++;
-      if (meta.hasIntent && meta.hasWorkflow && meta.hasVerification && meta.hasSelection) {
-        stableValid++;
+    if (meta.version && meta.version.startsWith('10.')) {
+      v10Total++;
+      const hasExitCodes = content.includes('Thoái Ra Mã') || content.includes('Exit Codes');
+      const hasCompliance = content.includes('Compliance');
+      const hasConfidence = content.includes('Confidence Model') || content.includes('Độ Tin Cậy');
+      const hasEvidence = content.includes('Bằng Chứng') || content.includes('Evidence Format');
+      const hasAllV10Sections = hasExitCodes && hasCompliance && hasConfidence && hasEvidence && meta.hasPlatforms;
+      if (hasAllV10Sections) {
+        v10Valid++;
       } else {
         missingRequiredCount++;
-        console.warn(`[WARN] ${meta.name} is missing required V8 fields`);
+        const missing = [];
+        if (!hasExitCodes) missing.push('Exit Codes');
+        if (!hasCompliance) missing.push('Compliance');
+        if (!hasConfidence) missing.push('Confidence Model');
+        if (!hasEvidence) missing.push('Evidence Format');
+        console.warn(`[WARN] ${meta.name} is missing V10 sections: ${missing.join(', ')}`);
       }
     } else {
       legacyIgnored++;
@@ -87,9 +105,9 @@ function validate() {
   }
 
   console.log(`\nSkills scanned: ${totalScanned}`);
-  console.log(`\nStable/Experimental:`);
-  console.log(`${stableValid}/${stableTotal} valid`);
-  console.log(`\nLegacy:`);
+  console.log(`\nV10 Format:`);
+  console.log(`${v10Valid}/${v10Total} valid`);
+  console.log(`\nLegacy (pre-V10):`);
   console.log(`${legacyIgnored}/${legacyIgnored} ignored`);
   console.log(`\nMissing required:`);
   console.log(`${missingRequiredCount}`);

package/.agents/docs/decisions/ADR-001-v8-migration.md

@@ -1,58 +0,0 @@
-# ADR-001: V8 Architecture Migration Strategy
-
-**Date:** 2026-07  
-**Status:** Accepted  
-**Deciders:** Quang Khánh
-
----
-
-## Context
-
-V7 (7.5.1) had 22 skills, each a monolithic SKILL.md containing:
-- Routing logic
-- Execution workflow
-- Verification steps
-- Rules and policies
-
-This made skills hard to reuse, workflows inconsistent across skills, and AI agents often confused about which skill to choose.
-
----
-
-## Decision
-
-Migrate to V8 **Agent Knowledge System** using **Structured Monolith** approach:
-
-1. **Keep skills** — don't split SKILL.md into multiple files
-2. **Add schema** — new frontmatter fields (intent, triggers, workflow ref, verification)
-3. **Extract workflows** — move execution pipelines to shared `workflows/*.yml`
-4. **Extract rules** — move global policies to `rules/*.md`
-5. **Add registry** — generated `registry/skills-index.yml` for AI retrieval
-
----
-
-## Rationale
-
-**Why not split SKILL.md into separate files?**  
-- Migration cost too high (22 skills × 4 extractions = 88 operations)
-- Risk of losing embedded knowledge in the split
-- Structured Monolith achieves the same retrieval benefit via references
-
-**Why pilot 5 skills first?**  
-- Schema may need adjustment based on real agent behavior
-- Safer to validate on 5 before committing to 22
-
-**Why keep git history instead of `archive/` folder?**  
-- V7.5.1 tagged at git → complete history available
-- Archive folder in repo creates noise for AI agents
-- Clean break is cleaner than carrying historical artifacts
-
----
-
-## Consequences
-
-- ✅ Workflows are now reusable (shared across skills)
-- ✅ AI retrieval is faster (registry index)
-- ✅ Rules are explicit and non-duplicated
-- ✅ Verification is mandatory and standardized
-- ⚠️ New schema requires migration of all 22 skills (3 weeks)
-- ⚠️ `skills.json` is now generated, not authoritative

package/.agents/docs/decisions/ADR-002-workflow-separation.md

@@ -1,50 +0,0 @@
-# ADR-002: Workflow Separation from Skills
-
-**Date:** 2026-07  
-**Status:** Accepted
-
----
-
-## Context
-
-In V7, each SKILL.md contained its own workflow embedded in the body. This meant:
-- Workflow for bug-fixing existed in `qk-bug-resolution/SKILL.md`
-- Similar steps were duplicated across multiple skills
-- No way to reuse or compose workflows
-
----
-
-## Decision
-
-Extract workflows into dedicated `workflows/*.yml` files. Skills reference workflows by name:
-
-```yaml
-# In SKILL.md frontmatter:
-workflow: bug-resolution  # → workflows/bug-resolution.yml
-```
-
-Each workflow step MUST define `inputs` and `outputs` (not just `actions`) so agents understand what a step achieves, not just how to do it.
-
----
-
-## Rationale
-
-**Why YAML instead of Markdown?**  
-- Machine-readable: easier for agents to parse step inputs/outputs
-- Structured: enforces schema compliance
-- If found to be too rigid, can switch to Markdown+frontmatter without breaking skill references
-
-**Why inputs/outputs per step?**  
-- Agents need to know WHAT each step achieves, not just HOW
-- Enables future: step skipping based on already-available outputs
-- Better debugging: "step X failed because output Y was not produced"
-
----
-
-## Consequences
-
-- ✅ Workflows are reusable across skills
-- ✅ Each step has clear contract (inputs → outputs)
-- ✅ Easier to add new skills that reuse existing workflows
-- ⚠️ YAML can be verbose — acceptable tradeoff for clarity
-- ⚠️ If workflow changes, all referencing skills remain valid (they only reference by name)

package/.agents/docs/decisions/ADR-003-registry-generated.md

@@ -1,54 +0,0 @@
-# ADR-003: Registry as Generated Artifact
-
-**Date:** 2026-07  
-**Status:** Accepted
-
----
-
-## Context
-
-V7 had `skills.json` as the primary manifest — manually maintained, often drifting from actual SKILL.md content. This created two sources of truth.
-
-V8 needs a retrieval index for AI agents to find the right skill without reading all 22 SKILL.md files.
-
----
-
-## Decision
-
-`registry/skills-index.yml` is a **generated file**. It is produced by `tooling/generate-registry.js` by reading all `SKILL.md` frontmatter.
-
-`SKILL.md` is the single source of truth. The registry is a derivative.
-
-```
-SKILL.md (source of truth)
-    ↓
-tooling/generate-registry.js
-    ↓
-registry/skills-index.yml (DO NOT EDIT MANUALLY)
-```
-
-`skills.json` is kept as a compatibility manifest for platforms that expect it (e.g., Antigravity v7 convention). It is also generated, not manually maintained.
-
----
-
-## Rationale
-
-**Why not edit the registry manually?**  
-- Two sources of truth always drift
-- Triggers, intent, complexity are already defined in SKILL.md
-- Generator can be run as a pre-commit hook or on demand
-
-**Why keep skills.json?**  
-- Antigravity and some platforms discover skills via `skills.json`
-- Backward compatibility for v7 skill consumers
-- It's generated, so no maintenance burden
-
----
-
-## Consequences
-
-- ✅ Single source of truth: SKILL.md
-- ✅ No drift between skill and registry
-- ✅ Registry update is automatic when skills are updated
-- ⚠️ Requires running generator after any SKILL.md change
-- ⚠️ If generator is not run, registry may be stale (mitigated by pre-commit hook)

package/.agents/docs/decisions/ADR-008-skill-boundary-review.md

@@ -1,27 +0,0 @@
-# ADR 008: Skill Boundary Review (V8.1.3)
-
-## Tiêu đề
-Định hướng tương lai cho ranh giới của `qk-validation-gate` và `qk-ai-builder`.
-
-## Bối cảnh
-Trong quá trình hoàn thiện Agent Engineering OS (V8.1.3), quá trình kiểm toán phát hiện rằng một số skill ban đầu có phạm vi hoạt động (scope) quá rộng hoặc chưa phân vai rõ ràng, dễ dẫn đến conflict. Tuy nhiên, để không làm vỡ kiến trúc (scope creep) trong giai đoạn chốt Control Plane, chúng ta quyết định giữ nguyên nhưng ghi chú định hướng cho V8.2.
-
-## Quyết định
-
-### 1. Về `qk-validation-gate`
-- **Hiện trạng:** Đang đóng vai trò validation coordinator.
-- **Định hướng (V8.2):** Sẽ được định hình rõ thành `release decision orchestrator`.
-- **Ranh giới tương lai:** Không trực tiếp chạy test, không trực tiếp scan security, không audit quality. Nhiệm vụ của nó là tổng hợp kết quả từ `qk-test-engineering`, `qk-security-audit`, và `qk-web-quality-gate` để ra quyết định cuối cùng (gate decision).
-
-### 2. Về `qk-ai-builder`
-- **Hiện trạng:** Đang quá rộng (gồm cả frontend AI apps, general AI coding, prompt writing...).
-- **Định hướng (V8.2):** Đổi tên (rename semantic) thành `qk-agent-platform-engineering`.
-- **Ranh giới tương lai:**
-  - **Owns:** agent architecture, MCP integration, skill generation, agent runtime patterns.
-  - **Does not own:** frontend AI apps, general AI coding, prompt writing.
-
-## Trạng thái
-Đề xuất được chấp nhận (Deferred to V8.2).
-
-## Hệ quả
-Ngăn chặn các kỹ năng này bị phình to trong quá trình triển khai thực tế. Chuẩn bị sẵn sàng cấu trúc cho giai đoạn V8.2 (Self-Improving Agent).