ai-developer-skill-os 5.0.0 → 6.0.1

package/specs/scenarios/fix-login-nullref.yaml

@@ -0,0 +1,3 @@
+scenario_id: fix-login-nullref
+description: "Một API production bị lỗi NullReferenceException sau khi merge."
+expected_behavior: qk-bug-resolution

package/tests/behavior-conformance.test.js

@@ -0,0 +1,151 @@
+import { describe, it, expect } from 'vitest';
+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 rootDir = path.resolve(__dirname, '..');
+const skillsDir = path.join(rootDir, 'skills');
+
+function getActiveSkillDirs() {
+  if (!fs.existsSync(skillsDir)) return [];
+  return fs.readdirSync(skillsDir)
+    .filter(name => !name.startsWith('_') && fs.statSync(path.join(skillsDir, name)).isDirectory())
+    .map(name => path.join(skillsDir, name));
+}
+
+function parseBSF(skillPath) {
+  const content = fs.readFileSync(skillPath, 'utf8');
+  
+  // Lấy frontmatter (v6)
+  const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
+  if (!fmMatch) return null;
+  const frontmatter = YAML.load(fmMatch[1]);
+  if (frontmatter.version !== '6.0.0') return { type: 'v5', frontmatter };
+
+  const bsf = { type: 'v6', frontmatter };
+  
+  // Parse YAML blocks
+  const yamlBlocks = [...content.matchAll(/```yaml\n([\s\S]*?)\n```/g)];
+  
+  try {
+    let parsedBlocks = {};
+    yamlBlocks.forEach(block => {
+      const parsed = YAML.load(block[1]);
+      if (parsed) Object.assign(parsedBlocks, parsed);
+    });
+    
+    bsf.constraints = {
+      must: parsedBlocks.must || [],
+      must_not: parsedBlocks.must_not || []
+    };
+    bsf.policies = {
+      prefer: parsedBlocks.prefer || []
+    };
+    bsf.escalation = {
+      stop: parsedBlocks.stop || [],
+      ask: parsedBlocks.ask || []
+    };
+
+    if (!content.includes('## Scope')) {
+      bsf.error = 'Missing Scope section';
+    }
+  } catch (e) {
+    bsf.error = 'Invalid YAML inside markdown blocks';
+  }
+  
+  return bsf;
+}
+
+describe('Behavior Validation Framework', () => {
+
+  describe('Level 1: Specification Valid', () => {
+    it('Every v6 skill must have valid Schema (Metadata, Scope, Constraints)', () => {
+      const dirs = getActiveSkillDirs();
+      const v6Skills = [];
+
+      dirs.forEach(dir => {
+        const skillPath = path.join(dir, 'SKILL.md');
+        if (!fs.existsSync(skillPath)) return;
+        const bsf = parseBSF(skillPath);
+        
+        if (bsf && bsf.type === 'v6') {
+          v6Skills.push(dir);
+          expect(bsf.error, `Parser error in ${path.basename(dir)}: ${bsf.error}`).toBeUndefined();
+          expect(bsf.frontmatter.category, `Missing category metadata in ${path.basename(dir)}`).toBeDefined();
+          expect(bsf.constraints, `Missing Constraints in ${path.basename(dir)}`).toBeDefined();
+        }
+      });
+
+      expect(v6Skills.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('Level 2: Contract Consistent', () => {
+    it('Constraints MUST NOT conflict with each other', () => {
+      const dirs = getActiveSkillDirs();
+      
+      dirs.forEach(dir => {
+        const skillPath = path.join(dir, 'SKILL.md');
+        if (!fs.existsSync(skillPath)) return;
+        const bsf = parseBSF(skillPath);
+        
+        if (bsf && bsf.type === 'v6' && !bsf.error) {
+          const must = bsf.constraints.must || [];
+          const must_not = bsf.constraints.must_not || [];
+          
+          must.forEach(rule => {
+            const conflict = must_not.some(c => c.toLowerCase() === rule.toLowerCase());
+            expect(conflict, `Conflict detected in ${path.basename(dir)}: '${rule}' is in both must and must_not`).toBe(false);
+          });
+        }
+      });
+    });
+  });
+
+  describe('Level 3: Behavior Conformance', () => {
+    const scenariosDir = path.join(rootDir, 'specs', 'scenarios');
+    const expectationsDir = path.join(rootDir, 'specs', 'expectations');
+
+    it('All scenarios must map to a valid behavior expectation', () => {
+      if (!fs.existsSync(scenariosDir)) return;
+      
+      const scenarioFiles = fs.readdirSync(scenariosDir).filter(f => f.endsWith('.yaml'));
+      if (scenarioFiles.length === 0) return;
+
+      scenarioFiles.forEach(file => {
+        const content = fs.readFileSync(path.join(scenariosDir, file), 'utf8');
+        const scenario = YAML.load(content);
+        
+        expect(scenario.scenario_id, `Missing scenario_id in ${file}`).toBeDefined();
+        expect(scenario.expected_behavior, `Missing expected_behavior in ${file}`).toBeDefined();
+
+        const expectationPath = path.join(expectationsDir, `${scenario.expected_behavior}.yaml`);
+        expect(fs.existsSync(expectationPath), `Missing expectation file for behavior: ${scenario.expected_behavior}`).toBe(true);
+      });
+    });
+
+    it('All expectations must define behavior properties (must, prefer, must_not)', () => {
+      if (!fs.existsSync(expectationsDir)) return;
+
+      const expectationFiles = fs.readdirSync(expectationsDir).filter(f => f.endsWith('.yaml'));
+      if (expectationFiles.length === 0) return;
+
+      expectationFiles.forEach(file => {
+        const content = fs.readFileSync(path.join(expectationsDir, file), 'utf8');
+        const expectation = YAML.load(content);
+        
+        expect(expectation.behavior, `Missing behavior ID in ${file}`).toBeDefined();
+        expect(Array.isArray(expectation.must), `${file} should define 'must' properties`).toBe(true);
+        expect(Array.isArray(expectation.must_not), `${file} should define 'must_not' properties`).toBe(true);
+      });
+    });
+  });
+
+  describe('Level 4: Regression Stable (Placeholder)', () => {
+    it('Golden Snapshot testing (Reserved for LLM runner)', () => {
+      expect(true).toBe(true);
+    });
+  });
+});

package/_template/SKILL.md

@@ -1,58 +0,0 @@
----
-name: qk-template
-version: 5.0.0
-updated: 2026-07-03
-description: Bản mẫu siêu gọn để tạo skill theo chuẩn Agent OS v5.0.
-category: template
-tags: [template, boilerplate]
-platforms: [claude-code, cursor, windsurf, gemini-cli]
----
-
-# 🛠️ [Tên Kỹ Năng]
-
-> **Inheritance:** Kỹ năng này tuân thủ Kiến trúc v5.0 của `framework/KERNEL.md`.
-> Các xử lý tư duy nội bộ sẽ dựa vào các thông số dưới đây và trả về Decision Summary.
-
----
-
-## 🎯 Mission (Scope)
-- ✅ Làm gì.
-- ❌ Không được làm gì.
-
----
-
-## ⚙️ Capabilities (Cognitive Pipeline)
-```yaml
-Pipeline:
-  - inference
-  - planning
-  - execution
-  - bias-review
-  - ship-check
-```
-
----
-
-## 🎛️ Dials (Hành vi)
-```yaml
-Dials:
-  - id: strictness # (Import từ dial-library/strictness.md)
-  - id: complexity-budget # (Import từ dial-library/complexity-budget.md)
-```
-
----
-
-## 🛡️ Biases (Sửa lỗi mặc định của AI)
-```yaml
-Biases:
-  - id: cosmetic-refactor # (Import từ bias-library/cosmetic-refactor.md)
-  - id: enterprise-crud # (Import từ bias-library/enterprise-crud.md)
-```
-
----
-
-## 🛫 Ship Criteria (Điều kiện xuất xưởng)
-```yaml
-Rules:
-  - id: minimal-diff # (Import từ rule-library/minimal-diff.md)
-```

package/tests/spec-compliance.test.js

@@ -1,193 +0,0 @@
-import { describe, it, expect } from 'vitest';
-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 rootDir = path.resolve(__dirname, '..');
-const skillsDir = path.join(rootDir, 'skills');
-
-function parseFrontmatter(skillPath) {
-  const content = fs.readFileSync(skillPath, 'utf8');
-  const match = content.match(/^---\s*\n([\s\S]*?)\n---/);
-  if (!match) return null;
-  try {
-    return YAML.load(match[1]);
-  } catch {
-    return null;
-  }
-}
-
-function getActiveSkillDirs() {
-  if (!fs.existsSync(skillsDir)) return [];
-  return fs.readdirSync(skillsDir)
-    .filter(name => !name.startsWith('_') && fs.statSync(path.join(skillsDir, name)).isDirectory())
-    .map(name => path.join(skillsDir, name));
-}
-
-describe('SKILL.md Spec Compliance', () => {
-  const REQUIRED_FIELDS = [
-    'name', 'version', 'updated', 'description', 'behavior', 'intent',
-    'priority', 'tags', 'platforms', 'trigger', 'inputs', 'outputs',
-    'allowed_tools', 'pipeline'
-  ];
-
-  const VALID_BEHAVIORS = ['static-analysis', 'development', 'validation', 'maintenance'];
-  const VALID_INTENTS = ['review-code', 'fix-bug', 'implement-feature', 'validate', 'maintain'];
-  const VALID_PRIORITIES = ['low', 'medium', 'high', 'critical'];
-  const VALID_PIPELINE_STEPS = new Set([
-    'analyze', 'plan', 'design', 'implement', 'review', 'validate', 'complete', 'delegate', 'evaluate', 'engineering-standard'
-  ]);
-
-  it('every active SKILL.md should have frontmatter', () => {
-    const dirs = getActiveSkillDirs();
-    dirs.forEach(dir => {
-      const skillPath = path.join(dir, 'SKILL.md');
-      expect(fs.existsSync(skillPath)).toBe(true);
-      const fm = parseFrontmatter(skillPath);
-      expect(fm).not.toBeNull();
-    });
-  });
-
-  it('every SKILL.md frontmatter should contain all required fields', () => {
-    const dirs = getActiveSkillDirs();
-    dirs.forEach(dir => {
-      const skillPath = path.join(dir, 'SKILL.md');
-      const fm = parseFrontmatter(skillPath);
-      REQUIRED_FIELDS.forEach(field => {
-        expect(fm[field], `Missing ${field} in ${path.basename(dir)}/SKILL.md`).toBeDefined();
-      });
-    });
-  });
-
-  it('behavior field should be one of the allowed values', () => {
-    const dirs = getActiveSkillDirs();
-    dirs.forEach(dir => {
-      const skillPath = path.join(dir, 'SKILL.md');
-      const fm = parseFrontmatter(skillPath);
-      expect(VALID_BEHAVIORS).toContain(fm.behavior);
-    });
-  });
-
-  it('intent field should be one of the allowed values', () => {
-    const dirs = getActiveSkillDirs();
-    dirs.forEach(dir => {
-      const skillPath = path.join(dir, 'SKILL.md');
-      const fm = parseFrontmatter(skillPath);
-      expect(VALID_INTENTS).toContain(fm.intent);
-    });
-  });
-
-  it('priority field should be one of the allowed values', () => {
-    const dirs = getActiveSkillDirs();
-    dirs.forEach(dir => {
-      const skillPath = path.join(dir, 'SKILL.md');
-      const fm = parseFrontmatter(skillPath);
-      expect(VALID_PRIORITIES).toContain(fm.priority);
-    });
-  });
-
-  it('pipeline steps should use only allowed verbs', () => {
-    const dirs = getActiveSkillDirs();
-    dirs.forEach(dir => {
-      const skillPath = path.join(dir, 'SKILL.md');
-      const fm = parseFrontmatter(skillPath);
-      const steps = Array.isArray(fm.pipeline) ? fm.pipeline : [fm.pipeline];
-      steps.forEach(step => {
-        expect(VALID_PIPELINE_STEPS.has(step), `Invalid pipeline step "${step}" in ${path.basename(dir)}`).toBe(true);
-      });
-    });
-  });
-
-  it('name field should match directory name and use qk- prefix', () => {
-    const dirs = getActiveSkillDirs();
-    dirs.forEach(dir => {
-      const skillName = path.basename(dir);
-      const skillPath = path.join(dir, 'SKILL.md');
-      const fm = parseFrontmatter(skillPath);
-      expect(fm.name).toBe(skillName);
-      expect(fm.name.startsWith('qk-')).toBe(true);
-    });
-  });
-
-  it('version should be semver string', () => {
-    const dirs = getActiveSkillDirs();
-    dirs.forEach(dir => {
-      const skillPath = path.join(dir, 'SKILL.md');
-      const fm = parseFrontmatter(skillPath);
-      expect(fm.version).toMatch(/^\d+\.\d+\.\d+$/);
-    });
-  });
-
-  it('updated should be YYYY-MM-DD', () => {
-    const dirs = getActiveSkillDirs();
-    dirs.forEach(dir => {
-      const skillPath = path.join(dir, 'SKILL.md');
-      const fm = parseFrontmatter(skillPath);
-      const val = typeof fm.updated === 'string' ? fm.updated : new Date(fm.updated).toISOString().split('T')[0];
-      expect(val).toMatch(/^\d{4}-\d{2}-\d{2}$/);
-    });
-  });
-
-  it('platforms should be an array of valid IDE strings', () => {
-    const valid = ['claude-code', 'cursor', 'windsurf', 'gemini-cli'];
-    const dirs = getActiveSkillDirs();
-    dirs.forEach(dir => {
-      const skillPath = path.join(dir, 'SKILL.md');
-      const fm = parseFrontmatter(skillPath);
-      expect(Array.isArray(fm.platforms)).toBe(true);
-      fm.platforms.forEach(p => expect(valid).toContain(p));
-    });
-  });
-
-  it('tags should be an array of strings', () => {
-    const dirs = getActiveSkillDirs();
-    dirs.forEach(dir => {
-      const skillPath = path.join(dir, 'SKILL.md');
-      const fm = parseFrontmatter(skillPath);
-      expect(Array.isArray(fm.tags)).toBe(true);
-      fm.tags.forEach(t => expect(typeof t).toBe('string'));
-    });
-  });
-
-  it('trigger should be a non-empty string', () => {
-    const dirs = getActiveSkillDirs();
-    dirs.forEach(dir => {
-      const skillPath = path.join(dir, 'SKILL.md');
-      const fm = parseFrontmatter(skillPath);
-      expect(typeof fm.trigger).toBe('string');
-      expect(fm.trigger.length).toBeGreaterThan(0);
-    });
-  });
-
-  it('allowed_tools should be an array of strings', () => {
-    const dirs = getActiveSkillDirs();
-    dirs.forEach(dir => {
-      const skillPath = path.join(dir, 'SKILL.md');
-      const fm = parseFrontmatter(skillPath);
-      expect(Array.isArray(fm.allowed_tools)).toBe(true);
-      fm.allowed_tools.forEach(t => expect(typeof t).toBe('string'));
-    });
-  });
-
-  it('body should contain required sections', () => {
-    const dirs = getActiveSkillDirs();
-    dirs.forEach(dir => {
-      const skillPath = path.join(dir, 'SKILL.md');
-      const content = fs.readFileSync(skillPath, 'utf8');
-      expect(content).toContain('Goal');
-      expect(content).toContain('Chain of Thought');
-      expect(content).toContain('Constraints');
-      expect(content).toContain('Output Format');
-    });
-  });
-
-  it('no skill should reference archived version of itself', () => {
-    const registryPath = path.join(rootDir, 'skills.json');
-    const registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
-    registry.skills.forEach(skill => {
-      expect(skill.path).not.toContain('_archive_old_skills');
-    });
-  });
-});