@kynetic-ai/spec 0.1.2 → 0.4.0

package/dist/parser/validate.js

@@ -3,13 +3,14 @@
  *
  * Provides schema validation, reference validation, and orphan detection.
  */
-import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
-import { TaskSchema, TasksFileSchema, ManifestSchema, SpecItemSchema, MetaManifestSchema, AgentSchema, WorkflowSchema, ConventionSchema, ObservationSchema, UlidSchema, } from '../schema/index.js';
-import { readYamlFile, findTaskFiles, loadSpecFile, expandIncludePattern, extractItemsFromRaw, } from './yaml.js';
-import { ReferenceIndex, validateRefs } from './refs.js';
-import { findMetaManifest, loadMetaContext } from './meta.js';
-import { TraitIndex } from './traits.js';
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { AgentSchema, ConventionSchema, isSkill, ManifestSchema, MetaManifestSchema, ObservationSchema, SkillSchema, SpecItemSchema, TaskSchema, TasksFileSchema, UlidSchema, WorkflowSchema, } from "../schema/index.js";
+import { findMetaManifest, getSkillContentPath, loadMetaContext } from "./meta.js";
+import { loadPlans } from "./plans.js";
+import { ReferenceIndex, validateRefs, } from "./refs.js";
+import { TraitIndex } from "./traits.js";
+import { expandIncludePattern, extractItemsFromRaw, findTaskFiles, loadSpecFile, readYamlFile, } from "./yaml.js";
 // ============================================================
 // SCHEMA VALIDATION
 // ============================================================
@@ -25,7 +26,7 @@ async function validateManifestFile(filePath) {
             for (const issue of result.error.issues) {
                 errors.push({
                     file: filePath,
-                    path: issue.path.join('.'),
+                    path: issue.path.join("."),
                     message: issue.message,
                     details: issue,
                 });
@@ -52,7 +53,7 @@ async function validateTasksFile(filePath) {
         if (Array.isArray(raw)) {
             taskList = raw;
         }
-        else if (raw && typeof raw === 'object' && 'tasks' in raw) {
+        else if (raw && typeof raw === "object" && "tasks" in raw) {
             // Try full TasksFile schema first
             const fileResult = TasksFileSchema.safeParse(raw);
             if (!fileResult.success) {
@@ -67,7 +68,7 @@ async function validateTasksFile(filePath) {
         else {
             errors.push({
                 file: filePath,
-                message: 'Invalid tasks file format: expected array or { tasks: [...] }',
+                message: "Invalid tasks file format: expected array or { tasks: [...] }",
             });
             return errors;
         }
@@ -79,7 +80,7 @@ async function validateTasksFile(filePath) {
                 for (const issue of result.error.issues) {
                     errors.push({
                         file: filePath,
-                        path: `tasks[${i}].${issue.path.join('.')}`,
+                        path: `tasks[${i}].${issue.path.join(".")}`,
                         message: issue.message,
                         details: issue,
                     });
@@ -103,7 +104,7 @@ async function validateSpecFile(filePath) {
     try {
         const raw = await readYamlFile(filePath);
         // Recursively validate spec items
-        validateSpecItemRecursive(raw, filePath, '', errors);
+        validateSpecItemRecursive(raw, filePath, "", errors);
     }
     catch (err) {
         errors.push({
@@ -127,7 +128,7 @@ async function validateMetaManifestFile(filePath) {
             for (const issue of manifestResult.error.issues) {
                 errors.push({
                     file: filePath,
-                    path: issue.path.join('.'),
+                    path: issue.path.join("."),
                     message: issue.message,
                     details: issue,
                 });
@@ -135,7 +136,10 @@ async function validateMetaManifestFile(filePath) {
             return errors;
         }
         // Validate each agent with strict ULID validation
-        if (raw && typeof raw === 'object' && 'agents' in raw && Array.isArray(raw.agents)) {
+        if (raw &&
+            typeof raw === "object" &&
+            "agents" in raw &&
+            Array.isArray(raw.agents)) {
             const agents = raw.agents;
             for (let i = 0; i < agents.length; i++) {
                 const agent = agents[i];
@@ -144,27 +148,30 @@ async function validateMetaManifestFile(filePath) {
                     for (const issue of agentResult.error.issues) {
                         errors.push({
                             file: filePath,
-                            path: `agents[${i}].${issue.path.join('.')}`,
+                            path: `agents[${i}].${issue.path.join(".")}`,
                             message: issue.message,
                             details: issue,
                         });
                     }
                 }
                 // Strict ULID validation
-                if (agent && typeof agent === 'object' && '_ulid' in agent) {
+                if (agent && typeof agent === "object" && "_ulid" in agent) {
                     const ulidResult = UlidSchema.safeParse(agent._ulid);
                     if (!ulidResult.success) {
                         errors.push({
                             file: filePath,
                             path: `agents[${i}]._ulid`,
-                            message: 'Invalid ULID format (expected 26 characters)',
+                            message: "Invalid ULID format (expected 26 characters)",
                         });
                     }
                 }
             }
         }
         // Validate each workflow with strict ULID validation
-        if (raw && typeof raw === 'object' && 'workflows' in raw && Array.isArray(raw.workflows)) {
+        if (raw &&
+            typeof raw === "object" &&
+            "workflows" in raw &&
+            Array.isArray(raw.workflows)) {
             const workflows = raw.workflows;
             for (let i = 0; i < workflows.length; i++) {
                 const workflow = workflows[i];
@@ -173,28 +180,32 @@ async function validateMetaManifestFile(filePath) {
                     for (const issue of workflowResult.error.issues) {
                         errors.push({
                             file: filePath,
-                            path: `workflows[${i}].${issue.path.join('.')}`,
+                            path: `workflows[${i}].${issue.path.join(".")}`,
                             message: issue.message,
                             details: issue,
                         });
                     }
                 }
                 // Strict ULID validation
-                if (workflow && typeof workflow === 'object' && '_ulid' in workflow) {
+                if (workflow && typeof workflow === "object" && "_ulid" in workflow) {
                     const ulidResult = UlidSchema.safeParse(workflow._ulid);
                     if (!ulidResult.success) {
                         errors.push({
                             file: filePath,
                             path: `workflows[${i}]._ulid`,
-                            message: 'Invalid ULID format (expected 26 characters)',
+                            message: "Invalid ULID format (expected 26 characters)",
                         });
                     }
                 }
             }
         }
         // Validate each convention with strict ULID validation
-        if (raw && typeof raw === 'object' && 'conventions' in raw && Array.isArray(raw.conventions)) {
-            const conventions = raw.conventions;
+        if (raw &&
+            typeof raw === "object" &&
+            "conventions" in raw &&
+            Array.isArray(raw.conventions)) {
+            const conventions = raw
+                .conventions;
             for (let i = 0; i < conventions.length; i++) {
                 const convention = conventions[i];
                 const conventionResult = ConventionSchema.safeParse(convention);
@@ -202,28 +213,34 @@ async function validateMetaManifestFile(filePath) {
                     for (const issue of conventionResult.error.issues) {
                         errors.push({
                             file: filePath,
-                            path: `conventions[${i}].${issue.path.join('.')}`,
+                            path: `conventions[${i}].${issue.path.join(".")}`,
                             message: issue.message,
                             details: issue,
                         });
                     }
                 }
                 // Strict ULID validation
-                if (convention && typeof convention === 'object' && '_ulid' in convention) {
+                if (convention &&
+                    typeof convention === "object" &&
+                    "_ulid" in convention) {
                     const ulidResult = UlidSchema.safeParse(convention._ulid);
                     if (!ulidResult.success) {
                         errors.push({
                             file: filePath,
                             path: `conventions[${i}]._ulid`,
-                            message: 'Invalid ULID format (expected 26 characters)',
+                            message: "Invalid ULID format (expected 26 characters)",
                         });
                     }
                 }
             }
         }
         // Validate each observation with strict ULID validation
-        if (raw && typeof raw === 'object' && 'observations' in raw && Array.isArray(raw.observations)) {
-            const observations = raw.observations;
+        if (raw &&
+            typeof raw === "object" &&
+            "observations" in raw &&
+            Array.isArray(raw.observations)) {
+            const observations = raw
+                .observations;
             for (let i = 0; i < observations.length; i++) {
                 const observation = observations[i];
                 const observationResult = ObservationSchema.safeParse(observation);
@@ -231,20 +248,54 @@ async function validateMetaManifestFile(filePath) {
                     for (const issue of observationResult.error.issues) {
                         errors.push({
                             file: filePath,
-                            path: `observations[${i}].${issue.path.join('.')}`,
+                            path: `observations[${i}].${issue.path.join(".")}`,
                             message: issue.message,
                             details: issue,
                         });
                     }
                 }
                 // Strict ULID validation
-                if (observation && typeof observation === 'object' && '_ulid' in observation) {
+                if (observation &&
+                    typeof observation === "object" &&
+                    "_ulid" in observation) {
                     const ulidResult = UlidSchema.safeParse(observation._ulid);
                     if (!ulidResult.success) {
                         errors.push({
                             file: filePath,
                             path: `observations[${i}]._ulid`,
-                            message: 'Invalid ULID format (expected 26 characters)',
+                            message: "Invalid ULID format (expected 26 characters)",
+                        });
+                    }
+                }
+            }
+        }
+        // AC: @skill-validation ac-4 - validate each skill with strict ULID validation
+        if (raw &&
+            typeof raw === "object" &&
+            "skills" in raw &&
+            Array.isArray(raw.skills)) {
+            const skills = raw.skills;
+            for (let i = 0; i < skills.length; i++) {
+                const skill = skills[i];
+                const skillResult = SkillSchema.safeParse(skill);
+                if (!skillResult.success) {
+                    for (const issue of skillResult.error.issues) {
+                        errors.push({
+                            file: filePath,
+                            path: `skills[${i}].${issue.path.join(".")}`,
+                            message: issue.message,
+                            details: issue,
+                        });
+                    }
+                }
+                // Strict ULID validation
+                if (skill && typeof skill === "object" && "_ulid" in skill) {
+                    const ulidResult = UlidSchema.safeParse(skill._ulid);
+                    if (!ulidResult.success) {
+                        errors.push({
+                            file: filePath,
+                            path: `skills[${i}]._ulid`,
+                            message: "Invalid ULID format (expected 26 characters)",
                         });
                     }
                 }
@@ -263,16 +314,18 @@ async function validateMetaManifestFile(filePath) {
  * Recursively validate spec items in a structure
  */
 function validateSpecItemRecursive(raw, file, pathPrefix, errors) {
-    if (!raw || typeof raw !== 'object')
+    if (!raw || typeof raw !== "object")
         return;
     // Check if this is a spec item (has _ulid)
-    if ('_ulid' in raw) {
+    if ("_ulid" in raw) {
         const result = SpecItemSchema.safeParse(raw);
         if (!result.success) {
             for (const issue of result.error.issues) {
                 errors.push({
                     file,
-                    path: pathPrefix ? `${pathPrefix}.${issue.path.join('.')}` : issue.path.join('.'),
+                    path: pathPrefix
+                        ? `${pathPrefix}.${issue.path.join(".")}`
+                        : issue.path.join("."),
                     message: issue.message,
                     details: issue,
                 });
@@ -280,13 +333,22 @@ function validateSpecItemRecursive(raw, file, pathPrefix, errors) {
         }
     }
     // Recurse into nested structures
-    const nestedFields = ['modules', 'features', 'requirements', 'constraints', 'decisions', 'items'];
+    const nestedFields = [
+        "modules",
+        "features",
+        "requirements",
+        "constraints",
+        "decisions",
+        "items",
+    ];
     const obj = raw;
     for (const field of nestedFields) {
         if (field in obj && Array.isArray(obj[field])) {
             const arr = obj[field];
             for (let i = 0; i < arr.length; i++) {
-                const newPath = pathPrefix ? `${pathPrefix}.${field}[${i}]` : `${field}[${i}]`;
+                const newPath = pathPrefix
+                    ? `${pathPrefix}.${field}[${i}]`
+                    : `${field}[${i}]`;
                 validateSpecItemRecursive(arr[i], file, newPath, errors);
             }
         }
@@ -305,20 +367,20 @@ function findOrphans(tasks, items, index) {
     const allItems = [...tasks, ...items];
     // Fields that contain references
     const refFields = [
-        'depends_on',
-        'blocked_by',
-        'implements',
-        'relates_to',
-        'tests',
-        'supersedes',
-        'spec_ref',
-        'context',
+        "depends_on",
+        "blocked_by",
+        "implements",
+        "relates_to",
+        "tests",
+        "supersedes",
+        "spec_ref",
+        "context",
     ];
     for (const item of allItems) {
         const obj = item;
         for (const field of refFields) {
             const value = obj[field];
-            if (typeof value === 'string' && value.startsWith('@')) {
+            if (typeof value === "string" && value.startsWith("@")) {
                 const resolved = index.resolve(value);
                 if (resolved.ok) {
                     referenced.add(resolved.ulid);
@@ -326,7 +388,7 @@ function findOrphans(tasks, items, index) {
             }
             else if (Array.isArray(value)) {
                 for (const v of value) {
-                    if (typeof v === 'string' && v.startsWith('@')) {
+                    if (typeof v === "string" && v.startsWith("@")) {
                         const resolved = index.resolve(v);
                         if (resolved.ok) {
                             referenced.add(resolved.ulid);
@@ -338,12 +400,12 @@ function findOrphans(tasks, items, index) {
     }
     // Find items not in the referenced set
     // Skip entry point types: modules are spec entry points, tasks are work items
-    const entryPointTypes = ['module', 'task', 'epic', 'bug', 'spike', 'infra'];
+    const entryPointTypes = ["module", "task", "epic", "bug", "spike", "infra"];
     for (const item of items) {
         // Only check spec items, not tasks
         if (!referenced.has(item._ulid)) {
             // Skip entry point types
-            if (entryPointTypes.includes(item.type || ''))
+            if (entryPointTypes.includes(item.type || ""))
                 continue;
             // Skip nested items - they're implicitly referenced by their parent
             // _path indicates nesting (e.g., "features[0].requirements[2]")
@@ -352,7 +414,7 @@ function findOrphans(tasks, items, index) {
             orphans.push({
                 ulid: item._ulid,
                 title: item.title,
-                type: item.type || 'unknown',
+                type: item.type || "unknown",
                 file: item._sourceFile,
             });
         }
@@ -368,12 +430,14 @@ function findOrphans(tasks, items, index) {
  */
 function detectTraitCycles(items, index) {
     const errors = [];
-    const traits = items.filter(item => item.type === 'trait');
+    const traits = items.filter((item) => item.type === "trait");
     // Build adjacency list: trait ULID → trait ULIDs it references
     const graph = new Map();
     const traitInfo = new Map();
     for (const trait of traits) {
-        const ref = trait.slugs?.[0] ? `@${trait.slugs[0]}` : `@${trait._ulid.slice(0, 8)}`;
+        const ref = trait.slugs?.[0]
+            ? `@${trait.slugs[0]}`
+            : `@${trait._ulid.slice(0, 8)}`;
         traitInfo.set(trait._ulid, { ref, title: trait.title });
         const dependencies = [];
         if (trait.traits && trait.traits.length > 0) {
@@ -419,7 +483,7 @@ function detectTraitCycles(items, index) {
             if (cycle) {
                 const info = traitInfo.get(cycle[0]);
                 if (info) {
-                    const cycleRefs = cycle.map(ulid => {
+                    const cycleRefs = cycle.map((ulid) => {
                         const cycleInfo = traitInfo.get(ulid);
                         return cycleInfo ? cycleInfo.ref : `@${ulid.slice(0, 8)}`;
                     });
@@ -427,7 +491,7 @@ function detectTraitCycles(items, index) {
                         traitRef: info.ref,
                         traitTitle: info.title,
                         cycle: cycleRefs,
-                        message: `Circular trait reference: ${cycleRefs.join(' → ')} → ${cycleRefs[0]}`,
+                        message: `Circular trait reference: ${cycleRefs.join(" → ")} → ${cycleRefs[0]}`,
                     });
                 }
                 // Mark all traits in cycle as visited to avoid duplicate errors
@@ -443,21 +507,45 @@ function detectTraitCycles(items, index) {
 // COMPLETENESS VALIDATION
 // ============================================================
 /**
- * Scan test files for AC annotations to build coverage index
+ * Recursively find all test files in a directory
+ */
+async function findTestFilesRecursive(dir) {
+    const testFiles = [];
+    try {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                // Recurse into subdirectories
+                const subFiles = await findTestFilesRecursive(fullPath);
+                testFiles.push(...subFiles);
+            }
+            else if (entry.isFile() &&
+                (entry.name.endsWith(".test.ts") || entry.name.endsWith(".test.js"))) {
+                testFiles.push(fullPath);
+            }
+        }
+    }
+    catch {
+        // Directory doesn't exist or can't be read - return empty
+    }
+    return testFiles;
+}
+/**
+ * Scan test files for AC annotations to build coverage index.
+ * Recursively scans all subdirectories under tests/.
  * Returns a Set of covered ACs in format "@spec-ref ac-N"
  */
-async function scanTestCoverage(rootDir) {
+export async function scanTestCoverage(rootDir) {
     const coveredACs = new Set();
-    const testsDir = path.join(rootDir, 'tests');
+    const testsDir = path.join(rootDir, "tests");
     try {
         // Check if tests directory exists
         await fs.access(testsDir);
-        // Read all test files
-        const files = await fs.readdir(testsDir);
-        const testFiles = files.filter(f => f.endsWith('.test.ts') || f.endsWith('.test.js'));
-        for (const file of testFiles) {
-            const filePath = path.join(testsDir, file);
-            const content = await fs.readFile(filePath, 'utf-8');
+        // Recursively find all test files
+        const testFiles = await findTestFilesRecursive(testsDir);
+        for (const filePath of testFiles) {
+            const content = await fs.readFile(filePath, "utf-8");
             // Match AC annotations: // AC: @spec-ref ac-N
             // Also handle multiple ACs on one line: // AC: @spec-ref ac-1, ac-2
             const acPattern = /\/\/\s*AC:\s*(@[\w-]+)(?:\s+(ac-\d+(?:\s*,\s*ac-\d+)*))?/g;
@@ -467,7 +555,7 @@ async function scanTestCoverage(rootDir) {
                 const acList = match[2]; // "ac-1, ac-2" or just "ac-1" or undefined
                 if (acList) {
                     // Split by comma and trim
-                    const acs = acList.split(',').map(ac => ac.trim());
+                    const acs = acList.split(",").map((ac) => ac.trim());
                     for (const ac of acs) {
                         coveredACs.add(`${specRef} ${ac}`);
                     }
@@ -480,68 +568,97 @@ async function scanTestCoverage(rootDir) {
             }
         }
     }
-    catch (err) {
+    catch (_err) {
         // Tests directory doesn't exist or can't be read - that's ok
     }
     return coveredACs;
 }
+/**
+ * Compute coverage status for acceptance criteria of a spec item.
+ * Shared utility used by both daemon API and JSON export.
+ *
+ * @param item - The spec item containing acceptance_criteria
+ * @param coveredACs - Set of covered AC references from scanTestCoverage()
+ * @returns Array of ACs with covered field populated
+ */
+export function computeACCoverage(item, coveredACs) {
+    if (!item.acceptance_criteria || item.acceptance_criteria.length === 0) {
+        return [];
+    }
+    return item.acceptance_criteria.map((ac, index) => {
+        const acId = `ac-${index + 1}`;
+        const possibleRefs = [];
+        // Try with primary slug
+        if (item.slugs && item.slugs.length > 0) {
+            possibleRefs.push(`@${item.slugs[0]} ${acId}`);
+            possibleRefs.push(`@${item.slugs[0]}`);
+        }
+        // Try with ULID (short form)
+        possibleRefs.push(`@${item._ulid.slice(0, 8)} ${acId}`);
+        possibleRefs.push(`@${item._ulid.slice(0, 8)}`);
+        const covered = possibleRefs.some((ref) => coveredACs.has(ref));
+        return { ...ac, covered };
+    });
+}
 /**
  * Check spec items for completeness
  * AC: @spec-completeness ac-1, ac-2, ac-3
  * AC: @trait-validation ac-1, ac-2, ac-3
  */
-async function checkCompleteness(items, index, rootDir, traitIndex) {
+async function checkCompleteness(items, _index, rootDir, traitIndex) {
     const warnings = [];
     // Scan test files for AC coverage
     const coveredACs = await scanTestCoverage(rootDir);
     for (const item of items) {
-        const itemRef = item.slugs?.[0] ? `@${item.slugs[0]}` : `@${item._ulid.slice(0, 8)}`;
-        const isTrait = item.type === 'trait';
+        const itemRef = item.slugs?.[0]
+            ? `@${item.slugs[0]}`
+            : `@${item._ulid.slice(0, 8)}`;
+        const isTrait = item.type === "trait";
         // AC: @spec-completeness ac-1
         // AC: @trait-type ac-2 - Traits should have acceptance criteria for completeness
         // Check for missing acceptance criteria
         if (!item.acceptance_criteria || item.acceptance_criteria.length === 0) {
             warnings.push({
-                type: 'missing_acceptance_criteria',
+                type: "missing_acceptance_criteria",
                 itemRef,
                 itemTitle: item.title,
-                message: `${isTrait ? 'Trait' : 'Item'} ${itemRef} has no acceptance criteria`,
+                message: `${isTrait ? "Trait" : "Item"} ${itemRef} has no acceptance criteria`,
             });
         }
         // AC: @spec-completeness ac-2
         // AC: @trait-type ac-3 - Traits should have description for completeness
         // Check for missing description
-        if (!item.description || item.description.trim() === '') {
+        if (!item.description || item.description.trim() === "") {
             warnings.push({
-                type: 'missing_description',
+                type: "missing_description",
                 itemRef,
                 itemTitle: item.title,
-                message: `${isTrait ? 'Trait' : 'Item'} ${itemRef} has no description`,
+                message: `${isTrait ? "Trait" : "Item"} ${itemRef} has no description`,
             });
         }
         // AC: @spec-completeness ac-3
         // Check for status inconsistency between parent and children
-        if (item.status?.implementation === 'implemented') {
+        if (item.status?.implementation === "implemented") {
             // Check if this item has children with not_started status
             const childFields = [
-                'modules',
-                'features',
-                'requirements',
-                'constraints',
-                'epics',
-                'themes',
-                'capabilities',
+                "modules",
+                "features",
+                "requirements",
+                "constraints",
+                "epics",
+                "themes",
+                "capabilities",
             ];
             for (const field of childFields) {
                 const children = item[field];
                 if (Array.isArray(children)) {
                     for (const child of children) {
-                        if (child.status?.implementation === 'not_started') {
+                        if (child.status?.implementation === "not_started") {
                             const childRef = child.slugs?.[0]
                                 ? `@${child.slugs[0]}`
-                                : `@${child._ulid?.slice(0, 8) || 'unknown'}`;
+                                : `@${child._ulid?.slice(0, 8) || "unknown"}`;
                             warnings.push({
-                                type: 'status_inconsistency',
+                                type: "status_inconsistency",
                                 itemRef,
                                 itemTitle: item.title,
                                 message: `Parent ${itemRef} is implemented but child ${childRef} is not_started`,
@@ -568,7 +685,7 @@ async function checkCompleteness(items, index, rootDir, traitIndex) {
                 possibleRefs.push(`@${item._ulid.slice(0, 8)} ${ac.id}`);
                 possibleRefs.push(`@${item._ulid.slice(0, 8)}`);
                 // Check if any of these references are covered
-                const isCovered = possibleRefs.some(ref => coveredACs.has(ref));
+                const isCovered = possibleRefs.some((ref) => coveredACs.has(ref));
                 if (!isCovered) {
                     uncoveredACs.push(ac.id);
                 }
@@ -576,11 +693,11 @@ async function checkCompleteness(items, index, rootDir, traitIndex) {
             // Only warn if there are uncovered ACs
             if (uncoveredACs.length > 0) {
                 warnings.push({
-                    type: 'missing_test_coverage',
+                    type: "missing_test_coverage",
                     itemRef,
                     itemTitle: item.title,
                     message: `Item ${itemRef} has ${uncoveredACs.length} AC(s) without test coverage`,
-                    details: `Uncovered: ${uncoveredACs.join(', ')}`,
+                    details: `Uncovered: ${uncoveredACs.join(", ")}`,
                 });
             }
         }
@@ -599,7 +716,7 @@ async function checkCompleteness(items, index, rootDir, traitIndex) {
                 possibleRefs.push(`@${trait.ulid.slice(0, 8)} ${ac.id}`);
                 possibleRefs.push(`@${trait.ulid.slice(0, 8)}`);
                 // Check if any of these references are covered
-                const isCovered = possibleRefs.some(ref => coveredACs.has(ref));
+                const isCovered = possibleRefs.some((ref) => coveredACs.has(ref));
                 if (!isCovered) {
                     uncoveredTraitACs.push({ traitSlug: trait.slug, acId: ac.id });
                 }
@@ -608,9 +725,9 @@ async function checkCompleteness(items, index, rootDir, traitIndex) {
             if (uncoveredTraitACs.length > 0) {
                 const details = uncoveredTraitACs
                     .map(({ traitSlug, acId }) => `@${traitSlug} ${acId}`)
-                    .join(', ');
+                    .join(", ");
                 warnings.push({
-                    type: 'missing_test_coverage',
+                    type: "missing_test_coverage",
                     itemRef,
                     itemTitle: item.title,
                     message: `Item ${itemRef} has ${uncoveredTraitACs.length} inherited trait AC(s) without test coverage`,
@@ -618,10 +735,270 @@ async function checkCompleteness(items, index, rootDir, traitIndex) {
                 });
             }
         }
+        // AC: @trait-retrospective ac-2, ac-3
+        // Check retrospective specs have required verification metadata
+        const isRetrospective = item.traits?.includes("@trait-retrospective");
+        if (isRetrospective) {
+            const isImplementedOrVerified = item.status?.implementation === "implemented" ||
+                item.status?.implementation === "verified";
+            // AC: @trait-retrospective ac-2
+            // Retrospective specs with implemented/verified status must have verification metadata
+            if (isImplementedOrVerified) {
+                if (!item.verified_at || !item.verified_by) {
+                    warnings.push({
+                        type: "status_inconsistency",
+                        itemRef,
+                        itemTitle: item.title,
+                        message: `Retrospective spec ${itemRef} is ${item.status?.implementation} but missing verified_at/verified_by`,
+                        details: "Specs using @trait-retrospective must have verified_at and verified_by fields when marked as implemented or verified",
+                    });
+                }
+            }
+            // Inverse validation: If verification metadata exists, status should be implemented/verified
+            if ((item.verified_at || item.verified_by) && !isImplementedOrVerified) {
+                warnings.push({
+                    type: "status_inconsistency",
+                    itemRef,
+                    itemTitle: item.title,
+                    message: `Retrospective spec ${itemRef} has verification metadata but status is not implemented/verified`,
+                    details: "Retrospective specs with verified_at/verified_by should have implementation status set to 'implemented' or 'verified'",
+                });
+            }
+        }
     }
     return warnings;
 }
 // ============================================================
+// AC SCHEMA DRIFT DETECTION
+// ============================================================
+/**
+ * Known schema fields for SpecItem
+ * These are the actual fields defined in SpecItemSchema
+ */
+const SPEC_ITEM_FIELDS = new Set([
+    "_ulid",
+    "slugs",
+    "title",
+    "type",
+    "status",
+    "maturity",
+    "implementation",
+    "priority",
+    "tags",
+    "description",
+    "acceptance_criteria",
+    "depends_on",
+    "implements",
+    "relates_to",
+    "tests",
+    "traits",
+    "supersedes",
+    "traceability",
+    "created",
+    "created_by",
+    "deprecated_in",
+    "superseded_by",
+    "verified_at",
+    "verified_by",
+    "notes",
+]);
+/**
+ * Known schema fields for Task
+ * These are the actual fields defined in TaskSchema
+ */
+const TASK_FIELDS = new Set([
+    "_ulid",
+    "slugs",
+    "title",
+    "type",
+    "description",
+    "spec_ref",
+    "derivation",
+    "meta_ref",
+    "plan_ref",
+    "origin",
+    "status",
+    "blocked_by",
+    "closed_reason",
+    "depends_on",
+    "context",
+    "priority",
+    "complexity",
+    "tags",
+    "assignee",
+    "vcs_refs",
+    "created_at",
+    "started_at",
+    "completed_at",
+    "notes",
+    "todos",
+    "automation",
+]);
+/**
+ * Known fields that are referenced but are parse-time or conceptual only
+ * These are common pseudo-fields that ACs reference but don't exist in schema
+ */
+const CONCEPTUAL_FIELDS = new Set([
+    "children", // Hierarchy is parse-time only
+    "parent", // Parent references are derived, not stored
+    "modules", // These are container structures in YAML, not item fields
+    "features",
+    "requirements",
+    "constraints",
+    "decisions",
+    "epics",
+    "themes",
+    "capabilities",
+]);
+/**
+ * Extract field reference patterns from AC text
+ * Looks for patterns like:
+ * - item.field
+ * - spec.field
+ * - task.field
+ * - status.field
+ * - spec_ref.field
+ * - the field
+ * - their field
+ * - item's field
+ */
+/**
+ * File extensions to exclude from field matching
+ * These are common file extensions that would otherwise match our patterns
+ */
+const FILE_EXTENSIONS = new Set([
+    "yaml",
+    "yml",
+    "json",
+    "js",
+    "ts",
+    "md",
+    "txt",
+    "html",
+    "css",
+    "log",
+]);
+function extractFieldReferences(text) {
+    const references = [];
+    // Pattern: context.field (e.g., item.status, spec_ref.children)
+    // This matches entity.property patterns in prose
+    const dotPattern = /\b(item|spec|task|status|spec_ref|task_ref|meta_ref|plan_ref)\.(\w+)/gi;
+    let match;
+    while ((match = dotPattern.exec(text)) !== null) {
+        const field = match[2].toLowerCase();
+        // Skip file extensions (e.g., spec.yaml, task.json)
+        if (FILE_EXTENSIONS.has(field)) {
+            continue;
+        }
+        references.push({ context: match[1].toLowerCase(), field });
+    }
+    // Pattern: "the <field>" when discussing items/tasks (common in ACs)
+    // Only match known schema-like words to avoid false positives
+    const thePattern = /\bthe\s+(status|children|parent|spec_ref|depends_on|traits|tags|notes|todos|acceptance_criteria)\b/gi;
+    while ((match = thePattern.exec(text)) !== null) {
+        references.push({ context: "item", field: match[1].toLowerCase() });
+    }
+    return references;
+}
+/**
+ * Check if a field exists in the appropriate schema
+ */
+function isValidSchemaField(context, field) {
+    // If it's a known conceptual field, it's technically invalid but we can give a specific message
+    if (CONCEPTUAL_FIELDS.has(field)) {
+        return { valid: false, reason: `'${field}' is a parse-time/conceptual field, not stored in schema` };
+    }
+    // Check based on context
+    switch (context) {
+        case "spec":
+        case "item":
+            if (SPEC_ITEM_FIELDS.has(field)) {
+                return { valid: true };
+            }
+            break;
+        case "task":
+            if (TASK_FIELDS.has(field)) {
+                return { valid: true };
+            }
+            break;
+        case "status":
+            // status.maturity, status.implementation are valid for specs
+            if (field === "maturity" || field === "implementation") {
+                return { valid: true };
+            }
+            break;
+        case "spec_ref":
+        case "task_ref":
+        case "meta_ref":
+        case "plan_ref":
+            // These are string references, not objects with fields
+            return { valid: false, reason: `'${context}' is a reference string, not an object with fields` };
+    }
+    // Check if field exists in either schema (might be ambiguous context)
+    if (SPEC_ITEM_FIELDS.has(field) || TASK_FIELDS.has(field)) {
+        return { valid: true };
+    }
+    return { valid: false, reason: `'${field}' is not a known schema field` };
+}
+/**
+ * Check acceptance criteria for field references that don't exist in schema
+ * Catches drift between spec prose and implementation reality.
+ */
+export function checkACSchemaReferences(items) {
+    const warnings = [];
+    for (const item of items) {
+        if (!item.acceptance_criteria || item.acceptance_criteria.length === 0) {
+            continue;
+        }
+        const itemRef = item.slugs?.[0]
+            ? `@${item.slugs[0]}`
+            : `@${item._ulid.slice(0, 8)}`;
+        for (const ac of item.acceptance_criteria) {
+            // Check all three parts of the AC for field references
+            const textToCheck = `${ac.given} ${ac.when} ${ac.then}`;
+            const fieldRefs = extractFieldReferences(textToCheck);
+            for (const { context, field } of fieldRefs) {
+                const result = isValidSchemaField(context, field);
+                if (!result.valid) {
+                    warnings.push({
+                        type: "ac_schema_field_mismatch",
+                        itemRef,
+                        itemTitle: item.title,
+                        message: `AC ${ac.id} references '${context}.${field}' which doesn't exist in schema`,
+                        details: result.reason,
+                    });
+                }
+            }
+        }
+    }
+    return warnings;
+}
+// ============================================================
+// SKILL CONTENT VALIDATION
+// ============================================================
+/**
+ * Validate that skill meta entries have corresponding SKILL.md files.
+ * AC: @skill-content-model ac-3 - missing content file reports validation error
+ */
+async function validateSkillContentFiles(ctx, skills) {
+    const errors = [];
+    for (const skill of skills) {
+        const contentPath = getSkillContentPath(ctx, skill.id);
+        try {
+            await fs.access(contentPath);
+        }
+        catch {
+            // File doesn't exist - report validation error
+            errors.push({
+                file: skill._sourceFile || "kynetic.meta.yaml",
+                path: `skills.${skill.id}`,
+                message: `Skill '${skill.id}' is missing content file at ${contentPath}`,
+            });
+        }
+    }
+    return errors;
+}
+// ============================================================
 // AUTOMATION VALIDATION
 // ============================================================
 /**
@@ -631,12 +1008,14 @@ async function checkCompleteness(items, index, rootDir, traitIndex) {
 function checkAutomationEligibility(tasks, index) {
     const warnings = [];
     for (const task of tasks) {
-        const taskRef = task.slugs?.[0] ? `@${task.slugs[0]}` : `@${task._ulid.slice(0, 8)}`;
+        const taskRef = task.slugs?.[0]
+            ? `@${task.slugs[0]}`
+            : `@${task._ulid.slice(0, 8)}`;
         // AC: @task-automation-eligibility ac-21
         // Warn if eligible but no spec_ref
-        if (task.automation === 'eligible' && !task.spec_ref) {
+        if (task.automation === "eligible" && !task.spec_ref) {
             warnings.push({
-                type: 'automation_eligible_no_spec',
+                type: "automation_eligible_no_spec",
                 itemRef: taskRef,
                 itemTitle: task.title,
                 message: `Task ${taskRef} is automation: eligible but has no spec_ref - eligible tasks should have linked specs`,
@@ -644,11 +1023,11 @@ function checkAutomationEligibility(tasks, index) {
         }
         // AC: @task-automation-eligibility ac-23
         // Warn if eligible but spec_ref doesn't resolve
-        if (task.automation === 'eligible' && task.spec_ref) {
+        if (task.automation === "eligible" && task.spec_ref) {
             const specResult = index.resolve(task.spec_ref);
             if (!specResult.ok) {
                 warnings.push({
-                    type: 'automation_eligible_no_spec',
+                    type: "automation_eligible_no_spec",
                     itemRef: taskRef,
                     itemTitle: task.title,
                     message: `Task ${taskRef} is automation: eligible but spec_ref ${task.spec_ref} cannot be resolved`,
@@ -659,6 +1038,81 @@ function checkAutomationEligibility(tasks, index) {
     return warnings;
 }
 // ============================================================
+// SKILL VALIDATION
+// ============================================================
+/**
+ * Validate skill depends_on references
+ * AC: @skill-validation ac-2 - broken depends_on ref reports warning
+ */
+function validateSkillDependsOn(skills, index) {
+    const warnings = [];
+    for (const skill of skills) {
+        if (!skill.depends_on || skill.depends_on.length === 0) {
+            continue;
+        }
+        for (const depRef of skill.depends_on) {
+            const result = index.resolve(depRef);
+            if (!result.ok) {
+                warnings.push({
+                    ref: depRef,
+                    sourceFile: skill._sourceFile,
+                    sourceUlid: skill._ulid,
+                    field: "depends_on",
+                    warning: "deprecated_target", // Reuse warning type for broken refs
+                    message: `Skill '${skill.id}' depends_on reference '${depRef}' cannot be resolved`,
+                });
+            }
+            else {
+                // Check that the resolved item is actually a skill (uses _type discriminant)
+                if (!isSkill(result.item)) {
+                    warnings.push({
+                        ref: depRef,
+                        sourceFile: skill._sourceFile,
+                        sourceUlid: skill._ulid,
+                        field: "depends_on",
+                        warning: "deprecated_target",
+                        message: `Skill '${skill.id}' depends_on reference '${depRef}' points to non-skill item`,
+                    });
+                }
+            }
+        }
+    }
+    return warnings;
+}
+/**
+ * Find orphaned skill directories (directories with no corresponding meta entry)
+ * AC: @skill-validation ac-3 - orphaned directory reports warning
+ */
+async function findOrphanedSkillDirectories(ctx, skills) {
+    const warnings = [];
+    const skillsDir = path.join(ctx.specDir, "skills");
+    try {
+        // Check if skills directory exists
+        await fs.access(skillsDir);
+        // Read all directories in skills/
+        const entries = await fs.readdir(skillsDir, { withFileTypes: true });
+        const directories = entries.filter(entry => entry.isDirectory());
+        // Build set of skill IDs from meta
+        const skillIds = new Set(skills.map(s => s.id));
+        // Find orphaned directories
+        for (const dir of directories) {
+            if (!skillIds.has(dir.name)) {
+                warnings.push({
+                    ref: `@${dir.name}`,
+                    sourceFile: path.join(skillsDir, dir.name),
+                    field: "directory",
+                    warning: "deprecated_target", // Reuse warning type
+                    message: `Orphaned skill directory '${dir.name}' has no corresponding meta entry`,
+                });
+            }
+        }
+    }
+    catch {
+        // Skills directory doesn't exist - that's fine
+    }
+    return warnings;
+}
+// ============================================================
 // MAIN VALIDATION
 // ============================================================
 /**
@@ -699,9 +1153,10 @@ export async function validate(ctx, options = {}) {
         result.stats.itemsChecked += manifestItems.length;
     }
     // Find and validate task files
+    // Exclude test fixtures which have their own self-contained references
     const taskFiles = await findTaskFiles(ctx.rootDir);
-    const specTaskFiles = await findTaskFiles(path.join(ctx.rootDir, 'spec'));
-    const allTaskFiles = [...new Set([...taskFiles, ...specTaskFiles])];
+    const specTaskFiles = await findTaskFiles(path.join(ctx.rootDir, "spec"));
+    const allTaskFiles = [...new Set([...taskFiles, ...specTaskFiles])].filter((f) => !f.includes("/fixtures/"));
     for (const taskFile of allTaskFiles) {
         if (runSchema) {
             const taskErrors = await validateTasksFile(taskFile);
@@ -715,7 +1170,7 @@ export async function validate(ctx, options = {}) {
             if (Array.isArray(raw)) {
                 taskList = raw;
             }
-            else if (raw && typeof raw === 'object' && 'tasks' in raw) {
+            else if (raw && typeof raw === "object" && "tasks" in raw) {
                 taskList = raw.tasks || [];
             }
             for (const t of taskList) {
@@ -762,13 +1217,46 @@ export async function validate(ctx, options = {}) {
         ...metaCtx.workflows,
         ...metaCtx.conventions,
         ...metaCtx.observations,
+        ...metaCtx.skills, // Include skills for reference indexing
     ];
+    // Load plans for reference validation
+    // AC: @plan-validation ac-10
+    const allPlans = await loadPlans(ctx);
     // Reference validation
-    if (runRefs && (allTasks.length > 0 || allItems.length > 0 || allMetaItems.length > 0)) {
-        const index = new ReferenceIndex(allTasks, allItems, allMetaItems);
+    if (runRefs &&
+        (allTasks.length > 0 ||
+            allItems.length > 0 ||
+            allMetaItems.length > 0 ||
+            allPlans.length > 0)) {
+        const index = new ReferenceIndex(allTasks, allItems, allMetaItems, allPlans);
         const refResult = validateRefs(index, allTasks, allItems);
-        result.refErrors = refResult.errors;
-        result.refWarnings = refResult.warnings;
+        // AC: @config-validation ac-2 ac-3 — strict_refs controls error vs warning
+        // When strictRefs is false, demote "not_found" ref errors to warnings
+        if (options.strictRefs === false) {
+            // Move not_found errors to warnings
+            const notFoundErrors = refResult.errors.filter((e) => e.error === "not_found");
+            const otherErrors = refResult.errors.filter((e) => e.error !== "not_found");
+            result.refErrors = otherErrors;
+            result.refWarnings = [
+                ...refResult.warnings,
+                ...notFoundErrors.map((e) => ({
+                    ref: e.ref,
+                    sourceFile: e.sourceFile,
+                    sourceUlid: e.sourceUlid,
+                    field: e.field,
+                    warning: "deprecated_target", // Reuse existing warning type
+                    message: e.message,
+                })),
+            ];
+        }
+        else {
+            // Default/strict behavior: not_found refs are errors
+            result.refErrors = refResult.errors;
+            result.refWarnings = refResult.warnings;
+        }
+        // AC: @skill-validation ac-2 - validate skill depends_on references
+        const skillDependsOnWarnings = validateSkillDependsOn(metaCtx.skills, index);
+        result.refWarnings.push(...skillDependsOnWarnings);
         // AC: @trait-edge-cases ac-2
         // Detect circular trait references
         result.traitCycleErrors = detectTraitCycles(allItems, index);
@@ -782,11 +1270,28 @@ export async function validate(ctx, options = {}) {
         if (runCompleteness) {
             // Build trait index for trait AC coverage validation
             const traitIndex = new TraitIndex(allItems, index);
-            result.completenessWarnings = await checkCompleteness(allItems, index, ctx.rootDir, traitIndex);
+            const completenessWarnings = await checkCompleteness(allItems, index, ctx.rootDir, traitIndex);
             // AC: @task-automation-eligibility ac-21, ac-23
             // Check automation eligibility warnings for tasks
             const automationWarnings = checkAutomationEligibility(allTasks, index);
-            result.completenessWarnings.push(...automationWarnings);
+            completenessWarnings.push(...automationWarnings);
+            // AC: @config-validation ac-1 — require_acceptance promotes missing AC to errors
+            if (options.requireAcceptance) {
+                const missingAC = completenessWarnings.filter((w) => w.type === "missing_acceptance_criteria");
+                const otherWarnings = completenessWarnings.filter((w) => w.type !== "missing_acceptance_criteria");
+                // Promote missing AC warnings to schema errors
+                for (const w of missingAC) {
+                    result.schemaErrors.push({
+                        file: "completeness",
+                        path: w.itemRef,
+                        message: w.message,
+                    });
+                }
+                result.completenessWarnings = otherWarnings;
+            }
+            else {
+                result.completenessWarnings = completenessWarnings;
+            }
         }
     }
     // Meta manifest validation (AC-meta-manifest-2, AC-meta-manifest-3)
@@ -798,20 +1303,32 @@ export async function validate(ctx, options = {}) {
             workflows: metaCtx.workflows.length,
             conventions: metaCtx.conventions.length,
             observations: metaCtx.observations.length,
+            skills: metaCtx.skills.length,
         };
         // Validate meta manifest schema with strict ULID validation
         if (runSchema) {
             const metaErrors = await validateMetaManifestFile(metaManifestPath);
             // Prefix all meta errors with "meta:"
             for (const err of metaErrors) {
-                err.path = err.path ? `meta:${err.path}` : 'meta:';
+                err.path = err.path ? `meta:${err.path}` : "meta:";
             }
             result.schemaErrors.push(...metaErrors);
             result.stats.filesChecked++;
+            // AC: @skill-content-model ac-3 - validate skill content files exist
+            if (metaCtx.skills.length > 0) {
+                const skillContentErrors = await validateSkillContentFiles(ctx, metaCtx.skills);
+                result.schemaErrors.push(...skillContentErrors);
+            }
+            // AC: @skill-validation ac-3 - detect orphaned skill directories
+            const orphanedSkillWarnings = await findOrphanedSkillDirectories(ctx, metaCtx.skills);
+            result.refWarnings.push(...orphanedSkillWarnings);
         }
     }
     // Set valid flag
-    result.valid = result.schemaErrors.length === 0 && result.refErrors.length === 0 && result.traitCycleErrors.length === 0;
+    result.valid =
+        result.schemaErrors.length === 0 &&
+            result.refErrors.length === 0 &&
+            result.traitCycleErrors.length === 0;
     return result;
 }
 //# sourceMappingURL=validate.js.map