@forwardimpact/pathway 0.1.0 → 0.3.0

package/app/model/validation.js

@@ -56,9 +56,10 @@ function createWarning(type, message, path) {
  * Validate that a skill has required properties
  * @param {import('./levels.js').Skill} skill - Skill to validate
  * @param {number} index - Index in the skills array
+ * @param {string[]} [requiredStageIds] - Stage IDs that must be present in agent skills
  * @returns {{errors: Array, warnings: Array}}
  */
-function validateSkill(skill, index) {
+function validateSkill(skill, index, requiredStageIds = []) {
   const errors = [];
   const warnings = [];
   const path = `skills[${index}]`;
@@ -108,6 +109,192 @@ function validateSkill(skill, index) {
     );
   }
 
+  // Validate agent section if present
+  if (skill.agent) {
+    const agentPath = `${path}.agent`;
+    if (!skill.agent.name) {
+      errors.push(
+        createError(
+          "MISSING_REQUIRED",
+          "Skill agent section missing name",
+          `${agentPath}.name`,
+        ),
+      );
+    }
+    if (!skill.agent.description) {
+      errors.push(
+        createError(
+          "MISSING_REQUIRED",
+          "Skill agent section missing description",
+          `${agentPath}.description`,
+        ),
+      );
+    }
+
+    // Validate stages (required for agent skills)
+    if (!skill.agent.stages) {
+      errors.push(
+        createError(
+          "MISSING_REQUIRED",
+          "Skill agent section missing stages",
+          `${agentPath}.stages`,
+        ),
+      );
+    } else if (typeof skill.agent.stages !== "object") {
+      errors.push(
+        createError(
+          "INVALID_VALUE",
+          "Skill agent stages must be an object",
+          `${agentPath}.stages`,
+          skill.agent.stages,
+        ),
+      );
+    } else {
+      // Validate each stage
+      const validStageIds = Object.values(Stage);
+      for (const [stageId, stageData] of Object.entries(skill.agent.stages)) {
+        if (!validStageIds.includes(stageId)) {
+          errors.push(
+            createError(
+              "INVALID_VALUE",
+              `Invalid stage ID: ${stageId}. Must be one of: ${validStageIds.join(", ")}`,
+              `${agentPath}.stages.${stageId}`,
+              stageId,
+            ),
+          );
+          continue;
+        }
+        const stagePath = `${agentPath}.stages.${stageId}`;
+        // focus is required
+        if (!stageData.focus) {
+          errors.push(
+            createError(
+              "MISSING_REQUIRED",
+              `Stage ${stageId} missing focus`,
+              `${stagePath}.focus`,
+            ),
+          );
+        } else if (typeof stageData.focus !== "string") {
+          errors.push(
+            createError(
+              "INVALID_VALUE",
+              `Stage ${stageId} focus must be a string`,
+              `${stagePath}.focus`,
+              stageData.focus,
+            ),
+          );
+        }
+        // activities is required and must be an array
+        if (!stageData.activities) {
+          errors.push(
+            createError(
+              "MISSING_REQUIRED",
+              `Stage ${stageId} missing activities`,
+              `${stagePath}.activities`,
+            ),
+          );
+        } else if (!Array.isArray(stageData.activities)) {
+          errors.push(
+            createError(
+              "INVALID_VALUE",
+              `Stage ${stageId} activities must be an array`,
+              `${stagePath}.activities`,
+              stageData.activities,
+            ),
+          );
+        }
+        // ready is required and must be an array (these become checklist items)
+        if (!stageData.ready) {
+          errors.push(
+            createError(
+              "MISSING_REQUIRED",
+              `Stage ${stageId} missing ready criteria`,
+              `${stagePath}.ready`,
+            ),
+          );
+        } else if (!Array.isArray(stageData.ready)) {
+          errors.push(
+            createError(
+              "INVALID_VALUE",
+              `Stage ${stageId} ready must be an array`,
+              `${stagePath}.ready`,
+              stageData.ready,
+            ),
+          );
+        }
+      }
+
+      // Check that all required stages are present
+      if (requiredStageIds.length > 0) {
+        const presentStageIds = Object.keys(skill.agent.stages);
+        for (const requiredStageId of requiredStageIds) {
+          if (!presentStageIds.includes(requiredStageId)) {
+            errors.push(
+              createError(
+                "MISSING_REQUIRED",
+                `Skill agent missing required stage: ${requiredStageId}`,
+                `${agentPath}.stages.${requiredStageId}`,
+              ),
+            );
+          }
+        }
+      }
+    }
+
+    // reference is optional but should be a string if present
+    if (
+      skill.agent.reference !== undefined &&
+      typeof skill.agent.reference !== "string"
+    ) {
+      errors.push(
+        createError(
+          "INVALID_VALUE",
+          "Skill agent reference must be a string",
+          `${agentPath}.reference`,
+          skill.agent.reference,
+        ),
+      );
+    }
+
+    // Error if old fields are still present
+    if (skill.agent.body !== undefined) {
+      errors.push(
+        createError(
+          "INVALID_FIELD",
+          "Skill agent 'body' field is not supported. Use stages instead.",
+          `${agentPath}.body`,
+        ),
+      );
+    }
+    if (skill.agent.applicability !== undefined) {
+      errors.push(
+        createError(
+          "INVALID_FIELD",
+          "Skill agent 'applicability' field is not supported. Use stages instead.",
+          `${agentPath}.applicability`,
+        ),
+      );
+    }
+    if (skill.agent.guidance !== undefined) {
+      errors.push(
+        createError(
+          "INVALID_FIELD",
+          "Skill agent 'guidance' field is not supported. Use stages instead.",
+          `${agentPath}.guidance`,
+        ),
+      );
+    }
+    if (skill.agent.verificationCriteria !== undefined) {
+      errors.push(
+        createError(
+          "INVALID_FIELD",
+          "Skill agent 'verificationCriteria' field is not supported. Use stages.{stage}.ready instead.",
+          `${agentPath}.verificationCriteria`,
+        ),
+      );
+    }
+  }
+
   return { errors, warnings };
 }
 
@@ -147,6 +334,51 @@ function validateBehaviour(behaviour, index) {
     );
   }
 
+  // Validate agent section if present
+  if (behaviour.agent) {
+    const agentPath = `${path}.agent`;
+
+    // title is required for agent behaviours
+    if (!behaviour.agent.title) {
+      errors.push(
+        createError(
+          "MISSING_REQUIRED",
+          "Behaviour agent section missing title",
+          `${agentPath}.title`,
+        ),
+      );
+    } else if (typeof behaviour.agent.title !== "string") {
+      errors.push(
+        createError(
+          "INVALID_VALUE",
+          "Behaviour agent title must be a string",
+          `${agentPath}.title`,
+          behaviour.agent.title,
+        ),
+      );
+    }
+
+    // workingStyle is required for agent behaviours
+    if (!behaviour.agent.workingStyle) {
+      errors.push(
+        createError(
+          "MISSING_REQUIRED",
+          "Behaviour agent section missing workingStyle",
+          `${agentPath}.workingStyle`,
+        ),
+      );
+    } else if (typeof behaviour.agent.workingStyle !== "string") {
+      errors.push(
+        createError(
+          "INVALID_VALUE",
+          "Behaviour agent workingStyle must be a string",
+          `${agentPath}.workingStyle`,
+          behaviour.agent.workingStyle,
+        ),
+      );
+    }
+  }
+
   return { errors, warnings };
 }
 
@@ -222,9 +454,18 @@ function validateDriver(driver, index, skillIds, behaviourIds) {
  * @param {number} index - Index in the disciplines array
  * @param {Set<string>} skillIds - Set of valid skill IDs
  * @param {Set<string>} behaviourIds - Set of valid behaviour IDs
+ * @param {Set<string>} trackIds - Set of valid track IDs
+ * @param {Set<string>} gradeIds - Set of valid grade IDs
  * @returns {{errors: Array, warnings: Array}}
  */
-function validateDiscipline(discipline, index, skillIds, behaviourIds) {
+function validateDiscipline(
+  discipline,
+  index,
+  skillIds,
+  behaviourIds,
+  trackIds,
+  gradeIds,
+) {
   const errors = [];
   const warnings = [];
   const path = `disciplines[${index}]`;
@@ -249,6 +490,77 @@ function validateDiscipline(discipline, index, skillIds, behaviourIds) {
     );
   }
 
+  // Validate validTracks (REQUIRED - must be an array)
+  // - null in array = allow trackless (generalist)
+  // - string values = specific track IDs
+  // - empty array = no valid combinations (discipline cannot be used)
+  if (!Array.isArray(discipline.validTracks)) {
+    errors.push(
+      createError(
+        "MISSING_REQUIRED",
+        `Discipline "${discipline.id}" missing required validTracks array`,
+        `${path}.validTracks`,
+      ),
+    );
+  } else {
+    discipline.validTracks.forEach((trackId, i) => {
+      // null means "allow trackless" - skip validation
+      if (trackId === null) return;
+      if (!trackIds.has(trackId)) {
+        errors.push(
+          createError(
+            "INVALID_REFERENCE",
+            `Discipline "${discipline.id}" references non-existent track: ${trackId}`,
+            `${path}.validTracks[${i}]`,
+            trackId,
+          ),
+        );
+      }
+    });
+  }
+
+  // Validate minGrade if specified
+  if (discipline.minGrade) {
+    if (!gradeIds.has(discipline.minGrade)) {
+      errors.push(
+        createError(
+          "INVALID_REFERENCE",
+          `Discipline "${discipline.id}" references non-existent grade: ${discipline.minGrade}`,
+          `${path}.minGrade`,
+          discipline.minGrade,
+        ),
+      );
+    }
+  }
+
+  // Validate isManagement/isProfessional booleans (optional)
+  if (
+    discipline.isManagement !== undefined &&
+    typeof discipline.isManagement !== "boolean"
+  ) {
+    errors.push(
+      createError(
+        "INVALID_VALUE",
+        `Discipline "${discipline.id}" has invalid isManagement value: ${discipline.isManagement} (must be boolean)`,
+        `${path}.isManagement`,
+        discipline.isManagement,
+      ),
+    );
+  }
+  if (
+    discipline.isProfessional !== undefined &&
+    typeof discipline.isProfessional !== "boolean"
+  ) {
+    errors.push(
+      createError(
+        "INVALID_VALUE",
+        `Discipline "${discipline.id}" has invalid isProfessional value: ${discipline.isProfessional} (must be boolean)`,
+        `${path}.isProfessional`,
+        discipline.isProfessional,
+      ),
+    );
+  }
+
   // Validate core skills
   if (!discipline.coreSkills || discipline.coreSkills.length === 0) {
     errors.push(
@@ -333,6 +645,126 @@ function validateDiscipline(discipline, index, skillIds, behaviourIds) {
     );
   }
 
+  // Validate agent section if present
+  if (discipline.agent) {
+    const agentPath = `${path}.agent`;
+
+    // Required: identity
+    if (!discipline.agent.identity) {
+      errors.push(
+        createError(
+          "MISSING_REQUIRED",
+          "Discipline agent section missing identity",
+          `${agentPath}.identity`,
+        ),
+      );
+    } else if (typeof discipline.agent.identity !== "string") {
+      errors.push(
+        createError(
+          "INVALID_VALUE",
+          "Discipline agent identity must be a string",
+          `${agentPath}.identity`,
+          discipline.agent.identity,
+        ),
+      );
+    }
+
+    // Optional: priority (string)
+    if (
+      discipline.agent.priority !== undefined &&
+      typeof discipline.agent.priority !== "string"
+    ) {
+      errors.push(
+        createError(
+          "INVALID_VALUE",
+          "Discipline agent priority must be a string",
+          `${agentPath}.priority`,
+          discipline.agent.priority,
+        ),
+      );
+    }
+
+    // Optional: beforeMakingChanges (array of strings)
+    if (discipline.agent.beforeMakingChanges !== undefined) {
+      if (!Array.isArray(discipline.agent.beforeMakingChanges)) {
+        errors.push(
+          createError(
+            "INVALID_VALUE",
+            "Discipline agent beforeMakingChanges must be an array",
+            `${agentPath}.beforeMakingChanges`,
+            discipline.agent.beforeMakingChanges,
+          ),
+        );
+      } else {
+        discipline.agent.beforeMakingChanges.forEach((item, i) => {
+          if (typeof item !== "string") {
+            errors.push(
+              createError(
+                "INVALID_VALUE",
+                "Discipline agent beforeMakingChanges items must be strings",
+                `${agentPath}.beforeMakingChanges[${i}]`,
+                item,
+              ),
+            );
+          }
+        });
+      }
+    }
+
+    // Optional: delegation (string)
+    if (
+      discipline.agent.delegation !== undefined &&
+      typeof discipline.agent.delegation !== "string"
+    ) {
+      errors.push(
+        createError(
+          "INVALID_VALUE",
+          "Discipline agent delegation must be a string",
+          `${agentPath}.delegation`,
+          discipline.agent.delegation,
+        ),
+      );
+    }
+
+    // Optional: constraints (array of strings)
+    if (discipline.agent.constraints !== undefined) {
+      if (!Array.isArray(discipline.agent.constraints)) {
+        errors.push(
+          createError(
+            "INVALID_VALUE",
+            "Discipline agent constraints must be an array",
+            `${agentPath}.constraints`,
+            discipline.agent.constraints,
+          ),
+        );
+      } else {
+        discipline.agent.constraints.forEach((item, i) => {
+          if (typeof item !== "string") {
+            errors.push(
+              createError(
+                "INVALID_VALUE",
+                "Discipline agent constraints items must be strings",
+                `${agentPath}.constraints[${i}]`,
+                item,
+              ),
+            );
+          }
+        });
+      }
+    }
+
+    // Error if old 'coreInstructions' field is still present
+    if (discipline.agent.coreInstructions !== undefined) {
+      errors.push(
+        createError(
+          "INVALID_FIELD",
+          "Discipline agent 'coreInstructions' field is not supported. Use identity, priority, beforeMakingChanges, and delegation instead.",
+          `${agentPath}.coreInstructions`,
+        ),
+      );
+    }
+  }
+
   return { errors, warnings };
 }
 
@@ -357,7 +789,7 @@ function getAllDisciplineSkillIds(disciplines) {
  * @param {number} index - Index in the tracks array
  * @param {Set<string>} disciplineSkillIds - Set of skill IDs used in any discipline
  * @param {Set<string>} behaviourIds - Set of valid behaviour IDs
- * @param {Set<string>} disciplineIds - Set of valid discipline IDs
+ * @param {Set<string>} gradeIds - Set of valid grade IDs
  * @returns {{errors: Array, warnings: Array}}
  */
 function validateTrack(
@@ -365,7 +797,6 @@ function validateTrack(
   index,
   disciplineSkillIds,
   behaviourIds,
-  disciplineIds,
   gradeIds,
 ) {
   const errors = [];
@@ -379,34 +810,6 @@ function validateTrack(
     );
   }
 
-  // Validate isProfessional/isManagement booleans (optional, default to isProfessional: true)
-  if (
-    track.isProfessional !== undefined &&
-    typeof track.isProfessional !== "boolean"
-  ) {
-    errors.push(
-      createError(
-        "INVALID_VALUE",
-        `Track "${track.id}" has invalid isProfessional value: ${track.isProfessional} (must be boolean)`,
-        `${path}.isProfessional`,
-        track.isProfessional,
-      ),
-    );
-  }
-  if (
-    track.isManagement !== undefined &&
-    typeof track.isManagement !== "boolean"
-  ) {
-    errors.push(
-      createError(
-        "INVALID_VALUE",
-        `Track "${track.id}" has invalid isManagement value: ${track.isManagement} (must be boolean)`,
-        `${path}.isManagement`,
-        track.isManagement,
-      ),
-    );
-  }
-
   // Validate skill modifiers - must be capabilities only (not individual skill IDs)
   if (track.skillModifiers) {
     Object.entries(track.skillModifiers).forEach(([key, modifier]) => {
@@ -462,22 +865,6 @@ function validateTrack(
     );
   }
 
-  // Validate validDisciplines if specified
-  if (track.validDisciplines) {
-    track.validDisciplines.forEach((disciplineId, i) => {
-      if (!disciplineIds.has(disciplineId)) {
-        errors.push(
-          createError(
-            "INVALID_REFERENCE",
-            `Track "${track.id}" references non-existent discipline: ${disciplineId}`,
-            `${path}.validDisciplines[${i}]`,
-            disciplineId,
-          ),
-        );
-      }
-    });
-  }
-
   // Validate minGrade if specified
   if (track.minGrade) {
     if (!gradeIds.has(track.minGrade)) {
@@ -537,6 +924,106 @@ function validateTrack(
     }
   }
 
+  // Validate agent section if present
+  if (track.agent) {
+    const agentPath = `${path}.agent`;
+
+    // Optional: identity (string) - if provided, overrides discipline identity
+    if (
+      track.agent.identity !== undefined &&
+      typeof track.agent.identity !== "string"
+    ) {
+      errors.push(
+        createError(
+          "INVALID_VALUE",
+          "Track agent identity must be a string",
+          `${agentPath}.identity`,
+          track.agent.identity,
+        ),
+      );
+    }
+
+    // Optional: priority (string)
+    if (
+      track.agent.priority !== undefined &&
+      typeof track.agent.priority !== "string"
+    ) {
+      errors.push(
+        createError(
+          "INVALID_VALUE",
+          "Track agent priority must be a string",
+          `${agentPath}.priority`,
+          track.agent.priority,
+        ),
+      );
+    }
+
+    // Optional: beforeMakingChanges (array of strings)
+    if (track.agent.beforeMakingChanges !== undefined) {
+      if (!Array.isArray(track.agent.beforeMakingChanges)) {
+        errors.push(
+          createError(
+            "INVALID_VALUE",
+            "Track agent beforeMakingChanges must be an array",
+            `${agentPath}.beforeMakingChanges`,
+            track.agent.beforeMakingChanges,
+          ),
+        );
+      } else {
+        track.agent.beforeMakingChanges.forEach((item, i) => {
+          if (typeof item !== "string") {
+            errors.push(
+              createError(
+                "INVALID_VALUE",
+                "Track agent beforeMakingChanges items must be strings",
+                `${agentPath}.beforeMakingChanges[${i}]`,
+                item,
+              ),
+            );
+          }
+        });
+      }
+    }
+
+    // Optional: constraints (array of strings)
+    if (track.agent.constraints !== undefined) {
+      if (!Array.isArray(track.agent.constraints)) {
+        errors.push(
+          createError(
+            "INVALID_VALUE",
+            "Track agent constraints must be an array",
+            `${agentPath}.constraints`,
+            track.agent.constraints,
+          ),
+        );
+      } else {
+        track.agent.constraints.forEach((item, i) => {
+          if (typeof item !== "string") {
+            errors.push(
+              createError(
+                "INVALID_VALUE",
+                "Track agent constraints items must be strings",
+                `${agentPath}.constraints[${i}]`,
+                item,
+              ),
+            );
+          }
+        });
+      }
+    }
+
+    // Error if old 'coreInstructions' field is still present
+    if (track.agent.coreInstructions !== undefined) {
+      errors.push(
+        createError(
+          "INVALID_FIELD",
+          "Track agent 'coreInstructions' field is not supported. Use identity, priority, beforeMakingChanges, and constraints instead.",
+          `${agentPath}.coreInstructions`,
+        ),
+      );
+    }
+  }
+
   return { errors, warnings };
 }
 
@@ -792,18 +1279,6 @@ function validateStage(stage, index) {
     );
   }
 
-  // Mode is now inferred from availableTools - no longer required
-  // Validate availableTools array
-  if (!stage.availableTools || !Array.isArray(stage.availableTools)) {
-    errors.push(
-      createError(
-        "MISSING_REQUIRED",
-        "Stage missing availableTools array",
-        `${path}.availableTools`,
-      ),
-    );
-  }
-
   if (!stage.handoffs || !Array.isArray(stage.handoffs)) {
     warnings.push(
       createWarning(
@@ -974,6 +1449,9 @@ export function validateAllData({
   const behaviourIds = new Set((behaviours || []).map((b) => b.id));
   const capabilityIds = new Set((capabilities || []).map((c) => c.id));
 
+  // Extract stage IDs for agent skill validation
+  const requiredStageIds = (stages || []).map((s) => s.id);
+
   // Validate skills
   if (!skills || skills.length === 0) {
     allErrors.push(
@@ -981,7 +1459,11 @@ export function validateAllData({
     );
   } else {
     skills.forEach((skill, index) => {
-      const { errors, warnings } = validateSkill(skill, index);
+      const { errors, warnings } = validateSkill(
+        skill,
+        index,
+        requiredStageIds,
+      );
       allErrors.push(...errors);
       allWarnings.push(...warnings);
     });
@@ -1036,6 +1518,12 @@ export function validateAllData({
     });
   }
 
+  // Get track IDs for discipline validation
+  const trackIdSet = new Set((tracks || []).map((t) => t.id));
+
+  // Get grade IDs for discipline and track validation
+  const gradeIdSet = new Set((grades || []).map((g) => g.id));
+
   // Validate disciplines
   if (!disciplines || disciplines.length === 0) {
     allErrors.push(
@@ -1048,6 +1536,8 @@ export function validateAllData({
         index,
         skillIds,
         behaviourIds,
+        trackIdSet,
+        gradeIdSet,
       );
       allErrors.push(...errors);
       allWarnings.push(...warnings);
@@ -1075,12 +1565,6 @@ export function validateAllData({
   // Get all skill IDs from disciplines for track validation
   const disciplineSkillIds = getAllDisciplineSkillIds(disciplines || []);
 
-  // Get discipline IDs for track validation
-  const disciplineIdSet = new Set((disciplines || []).map((d) => d.id));
-
-  // Get grade IDs for track validation
-  const gradeIdSet = new Set((grades || []).map((g) => g.id));
-
   // Validate tracks
   if (!tracks || tracks.length === 0) {
     allErrors.push(
@@ -1093,7 +1577,6 @@ export function validateAllData({
         index,
         disciplineSkillIds,
         behaviourIds,
-        disciplineIdSet,
         gradeIdSet,
       );
       allErrors.push(...errors);
@@ -1383,3 +1866,199 @@ export function validateQuestionBank(questionBank, skills, behaviours) {
 
   return createValidationResult(errors.length === 0, errors, warnings);
 }
+
+/**
+ * Validate agent-specific data comprehensively
+ * This validates cross-references between human and agent definitions
+ * @param {Object} params - Validation parameters
+ * @param {Object} params.humanData - Human data (disciplines, tracks, skills, behaviours, stages)
+ * @param {Object} params.agentData - Agent-specific data (disciplines, tracks, behaviours with agent sections)
+ * @returns {import('./levels.js').ValidationResult}
+ */
+export function validateAgentData({ humanData, agentData }) {
+  const errors = [];
+  const warnings = [];
+
+  const humanDisciplineIds = new Set(
+    (humanData.disciplines || []).map((d) => d.id),
+  );
+  const humanTrackIds = new Set((humanData.tracks || []).map((t) => t.id));
+  const humanBehaviourIds = new Set(
+    (humanData.behaviours || []).map((b) => b.id),
+  );
+  const stageIds = new Set((humanData.stages || []).map((s) => s.id));
+
+  // Validate agent disciplines reference human disciplines
+  for (const agentDiscipline of agentData.disciplines || []) {
+    if (!humanDisciplineIds.has(agentDiscipline.id)) {
+      errors.push(
+        createError(
+          "ORPHANED_AGENT",
+          `Agent discipline '${agentDiscipline.id}' has no human definition`,
+          `agentData.disciplines`,
+          agentDiscipline.id,
+        ),
+      );
+    }
+
+    // Validate required identity exists (spread from agent section by loader)
+    if (!agentDiscipline.identity) {
+      errors.push(
+        createError(
+          "MISSING_REQUIRED",
+          `Agent discipline '${agentDiscipline.id}' missing identity`,
+          `agentData.disciplines.${agentDiscipline.id}.identity`,
+        ),
+      );
+    }
+  }
+
+  // Validate agent tracks reference human tracks
+  for (const agentTrack of agentData.tracks || []) {
+    if (!humanTrackIds.has(agentTrack.id)) {
+      errors.push(
+        createError(
+          "ORPHANED_AGENT",
+          `Agent track '${agentTrack.id}' has no human definition`,
+          `agentData.tracks`,
+          agentTrack.id,
+        ),
+      );
+    }
+  }
+
+  // Validate agent behaviours reference human behaviours
+  for (const agentBehaviour of agentData.behaviours || []) {
+    if (!humanBehaviourIds.has(agentBehaviour.id)) {
+      errors.push(
+        createError(
+          "ORPHANED_AGENT",
+          `Agent behaviour '${agentBehaviour.id}' has no human definition`,
+          `agentData.behaviours`,
+          agentBehaviour.id,
+        ),
+      );
+    }
+
+    // Validate required agent fields (spread from agent section by loader)
+    if (!agentBehaviour.title) {
+      errors.push(
+        createError(
+          "MISSING_REQUIRED",
+          `Agent behaviour '${agentBehaviour.id}' missing title`,
+          `agentData.behaviours.${agentBehaviour.id}.title`,
+        ),
+      );
+    }
+    if (!agentBehaviour.workingStyle) {
+      errors.push(
+        createError(
+          "MISSING_REQUIRED",
+          `Agent behaviour '${agentBehaviour.id}' missing workingStyle`,
+          `agentData.behaviours.${agentBehaviour.id}.workingStyle`,
+        ),
+      );
+    }
+  }
+
+  // Validate skills with agent sections have complete stage coverage
+  const skillsWithAgent = (humanData.skills || []).filter((s) => s.agent);
+  const requiredStages = ["plan", "code", "review"];
+
+  for (const skill of skillsWithAgent) {
+    const stages = skill.agent.stages || {};
+    const missingStages = requiredStages.filter((stage) => !stages[stage]);
+
+    if (missingStages.length > 0) {
+      warnings.push(
+        createWarning(
+          "INCOMPLETE_STAGES",
+          `Skill '${skill.id}' agent section missing stages: ${missingStages.join(", ")}`,
+          `skills.${skill.id}.agent.stages`,
+        ),
+      );
+    }
+
+    // Validate each stage has required fields
+    for (const [stageId, stageData] of Object.entries(stages)) {
+      if (!stageData.focus) {
+        errors.push(
+          createError(
+            "MISSING_REQUIRED",
+            `Skill '${skill.id}' agent stage '${stageId}' missing focus`,
+            `skills.${skill.id}.agent.stages.${stageId}.focus`,
+          ),
+        );
+      }
+      if (
+        !stageData.activities ||
+        !Array.isArray(stageData.activities) ||
+        stageData.activities.length === 0
+      ) {
+        errors.push(
+          createError(
+            "MISSING_REQUIRED",
+            `Skill '${skill.id}' agent stage '${stageId}' missing or empty activities`,
+            `skills.${skill.id}.agent.stages.${stageId}.activities`,
+          ),
+        );
+      }
+      if (
+        !stageData.ready ||
+        !Array.isArray(stageData.ready) ||
+        stageData.ready.length === 0
+      ) {
+        errors.push(
+          createError(
+            "MISSING_REQUIRED",
+            `Skill '${skill.id}' agent stage '${stageId}' missing or empty ready criteria`,
+            `skills.${skill.id}.agent.stages.${stageId}.ready`,
+          ),
+        );
+      }
+    }
+  }
+
+  // Validate stage handoff targets exist
+  for (const stage of humanData.stages || []) {
+    if (stage.handoffs) {
+      for (const handoff of stage.handoffs) {
+        const targetId = handoff.targetStage || handoff.target;
+        if (targetId && !stageIds.has(targetId)) {
+          errors.push(
+            createError(
+              "INVALID_REFERENCE",
+              `Stage '${stage.id}' handoff references unknown stage '${targetId}'`,
+              `stages.${stage.id}.handoffs`,
+              targetId,
+            ),
+          );
+        }
+      }
+    }
+  }
+
+  // Summary statistics as warnings (informational)
+  const stats = {
+    agentDisciplines: (agentData.disciplines || []).length,
+    agentTracks: (agentData.tracks || []).length,
+    agentBehaviours: (agentData.behaviours || []).length,
+    skillsWithAgent: skillsWithAgent.length,
+    skillsWithCompleteStages: skillsWithAgent.filter((s) => {
+      const stages = s.agent.stages || {};
+      return requiredStages.every((stage) => stages[stage]);
+    }).length,
+  };
+
+  if (stats.skillsWithCompleteStages < stats.skillsWithAgent) {
+    warnings.push(
+      createWarning(
+        "INCOMPLETE_COVERAGE",
+        `${stats.skillsWithCompleteStages}/${stats.skillsWithAgent} skills have complete stage coverage (plan, code, review)`,
+        "agentData",
+      ),
+    );
+  }
+
+  return createValidationResult(errors.length === 0, errors, warnings);
+}