@forwardimpact/schema 0.3.0 → 0.6.0

package/schema/rdf/skill-questions.ttl

@@ -7,7 +7,8 @@
 # =============================================================================
 # Skill Questions Schema
 # =============================================================================
-# Interview questions for assessing skills.
+# Interview questions for assessing skills, organized by role type
+# (professional/management) and level.
 # =============================================================================
 
 # -----------------------------------------------------------------------------
@@ -18,6 +19,18 @@ fit:Question a rdfs:Class ;
     rdfs:label "Question"@en ;
     rdfs:comment "Interview question for assessing skills or behaviours"@en .
 
+fit:RoleType a rdfs:Class ;
+    rdfs:label "RoleType"@en ;
+    rdfs:comment "Type of role: professional (IC) or management"@en .
+
+fit:professional a fit:RoleType ;
+    rdfs:label "professional"@en ;
+    rdfs:comment "Professional/individual contributor roles"@en .
+
+fit:management a fit:RoleType ;
+    rdfs:label "management"@en ;
+    rdfs:comment "Management roles"@en .
+
 # -----------------------------------------------------------------------------
 # Properties
 # -----------------------------------------------------------------------------
@@ -58,6 +71,12 @@ fit:atLevel a rdf:Property ;
     rdfs:domain fit:Question ;
     rdfs:range fit:SkillLevel .
 
+fit:forRoleType a rdf:Property ;
+    rdfs:label "forRoleType"@en ;
+    rdfs:comment "The role type this question is intended for (professional or management)"@en ;
+    rdfs:domain fit:Question ;
+    rdfs:range fit:RoleType .
+
 # =============================================================================
 # SHACL SHAPES
 # =============================================================================
@@ -125,4 +144,12 @@ fit:SkillQuestionShape a sh:NodeShape ;
         sh:maxCount 1 ;
         sh:name "atLevel" ;
         sh:description "The skill level this question is for" ;
+    ] ;
+    sh:property [
+        sh:path fit:forRoleType ;
+        sh:in ( fit:professional fit:management ) ;
+        sh:minCount 1 ;
+        sh:maxCount 1 ;
+        sh:name "forRoleType" ;
+        sh:description "The role type this question is for" ;
     ] .

package/schema/rdf/stages.ttl

@@ -33,6 +33,17 @@ fit:entryCriteria a rdf:Property ;
     rdfs:comment "Conditions that must be met before entering this stage"@en ;
     rdfs:range xsd:string .
 
+fit:exitCriteria a rdf:Property ;
+    rdfs:label "exitCriteria"@en ;
+    rdfs:comment "Conditions that must be met before leaving this stage"@en ;
+    rdfs:range xsd:string .
+
+fit:summary a rdf:Property ;
+    rdfs:label "summary"@en ;
+    rdfs:comment "Third-person summary for metadata, listings, and sub-agent descriptions"@en ;
+    rdfs:domain fit:Stage ;
+    rdfs:range xsd:string .
+
 fit:targetStage a rdf:Property ;
     rdfs:label "targetStage"@en ;
     rdfs:comment "The stage to transition to"@en ;
@@ -63,7 +74,7 @@ fit:StageShape a sh:NodeShape ;
     sh:targetClass fit:Stage ;
     sh:property [
         sh:path fit:id ;
-        sh:in ( "plan" "code" "review" ) ;
+        sh:in ( "specify" "plan" "code" "review" "deploy" ) ;
         sh:minCount 1 ;
         sh:maxCount 1 ;
         sh:name "id" ;
@@ -89,7 +100,14 @@ fit:StageShape a sh:NodeShape ;
         sh:datatype xsd:string ;
         sh:maxCount 1 ;
         sh:name "description" ;
-        sh:description "Description of the stage's purpose" ;
+        sh:description "Description of the stage's purpose (second-person, for agent body)" ;
+    ] ;
+    sh:property [
+        sh:path fit:summary ;
+        sh:datatype xsd:string ;
+        sh:maxCount 1 ;
+        sh:name "summary" ;
+        sh:description "Third-person summary for metadata, listings, and sub-agent descriptions" ;
     ] ;
     sh:property [
         sh:path fit:handoffs ;
@@ -108,6 +126,12 @@ fit:StageShape a sh:NodeShape ;
         sh:datatype xsd:string ;
         sh:name "entryCriteria" ;
         sh:description "Conditions that must be met before entering this stage" ;
+    ] ;
+    sh:property [
+        sh:path fit:exitCriteria ;
+        sh:datatype xsd:string ;
+        sh:name "exitCriteria" ;
+        sh:description "Conditions that must be met before leaving this stage" ;
     ] .
 
 # -----------------------------------------------------------------------------
@@ -118,7 +142,7 @@ fit:HandoffShape a sh:NodeShape ;
     sh:targetClass fit:Handoff ;
     sh:property [
         sh:path fit:targetStage ;
-        sh:in ( "plan" "code" "review" ) ;
+        sh:in ( "specify" "plan" "code" "review" "deploy" ) ;
         sh:minCount 1 ;
         sh:maxCount 1 ;
         sh:name "targetStage" ;

package/{lib → src}/levels.js

@@ -98,72 +98,44 @@ export const Capability = {
   PRODUCT: "product",
 };
 
-/**
- * Ordered array of capabilities for consistent display
- * Groups related capabilities logically:
- * 1. Core delivery
- * 2. Data & AI capabilities
- * 3. Scale & reliability
- * 4. People & process
- * 5. Business, documentation & product
- * @type {string[]}
- */
-export const CAPABILITY_ORDER = [
-  Capability.DELIVERY,
-  Capability.DATA,
-  Capability.AI,
-  Capability.ML,
-  Capability.SCALE,
-  Capability.RELIABILITY,
-  Capability.PEOPLE,
-  Capability.PROCESS,
-  Capability.BUSINESS,
-  Capability.DOCUMENTATION,
-  Capability.PRODUCT,
-];
-
-/**
- * Get the index of a capability in the ordered list
- * @param {string} capability - The capability to look up
- * @returns {number} The index (0-based), or -1 if not found
- */
-export function getCapabilityIndex(capability) {
-  return CAPABILITY_ORDER.indexOf(capability);
-}
+// ============================================================================
+// Data-driven Capability Functions
+// ============================================================================
+// These functions work with loaded capability data for responsibility derivation
 
 /**
- * Compare two capabilities for sorting
- * @param {string} a - First capability
- * @param {string} b - Second capability
- * @returns {number} Comparison result for sorting
+ * Get capability metadata from loaded capability data
+ * @param {Object[]} capabilities - Loaded capabilities array
+ * @param {string} capabilityId - The capability ID to look up
+ * @returns {Object|undefined} The capability object or undefined
  */
-export function compareCapabilities(a, b) {
-  return getCapabilityIndex(a) - getCapabilityIndex(b);
+export function getCapabilityById(capabilities, capabilityId) {
+  return capabilities.find((c) => c.id === capabilityId);
 }
 
 /**
- * Sort an array of skills by capability order, then by name
- * @param {import('./levels.js').Skill[]} skills - Array of skills to sort
- * @returns {import('./levels.js').Skill[]} Sorted array (new array, does not mutate input)
+ * Get ordered capability IDs from loaded capability data
+ * @param {Object[]} capabilities - Loaded capabilities array
+ * @returns {string[]} Capability IDs in display order
  */
-export function sortSkillsByCapability(skills) {
-  return [...skills].sort((a, b) => {
-    const capabilityCompare = compareCapabilities(a.capability, b.capability);
-    if (capabilityCompare !== 0) return capabilityCompare;
-    return a.name.localeCompare(b.name);
-  });
+export function getCapabilityOrder(capabilities) {
+  return [...capabilities]
+    .sort((a, b) => (a.ordinalRank || 0) - (b.ordinalRank || 0))
+    .map((c) => c.id);
 }
 
 /**
- * Group skills by capability in the defined order
+ * Group skills by capability in display order
  * @param {import('./levels.js').Skill[]} skills - Array of skills to group
- * @returns {Object<string, import('./levels.js').Skill[]>} Object with capabilities as keys (in order)
+ * @param {Object[]} capabilities - Loaded capabilities array for ordering
+ * @returns {Object<string, import('./levels.js').Skill[]>} Object with capabilities as keys (in display order)
  */
-export function groupSkillsByCapability(skills) {
+export function groupSkillsByCapability(skills, capabilities) {
+  const capabilityOrder = getCapabilityOrder(capabilities);
   const result = {};
 
-  // Initialize all capabilities in order (ensures consistent key order)
-  for (const capability of CAPABILITY_ORDER) {
+  // Initialize all capabilities in display order (ensures consistent key order)
+  for (const capability of capabilityOrder) {
     result[capability] = [];
   }
 
@@ -186,32 +158,6 @@ export function groupSkillsByCapability(skills) {
   return result;
 }
 
-// ============================================================================
-// Data-driven Capability Functions
-// ============================================================================
-// These functions work with loaded capability data for responsibility derivation
-
-/**
- * Get capability metadata from loaded capability data
- * @param {Object[]} capabilities - Loaded capabilities array
- * @param {string} capabilityId - The capability ID to look up
- * @returns {Object|undefined} The capability object or undefined
- */
-export function getCapabilityById(capabilities, capabilityId) {
-  return capabilities.find((c) => c.id === capabilityId);
-}
-
-/**
- * Get ordered capability IDs from loaded capability data
- * @param {Object[]} capabilities - Loaded capabilities array
- * @returns {string[]} Capability IDs in display order
- */
-export function getCapabilityOrder(capabilities) {
-  return [...capabilities]
-    .sort((a, b) => (a.displayOrder || 0) - (b.displayOrder || 0))
-    .map((c) => c.id);
-}
-
 /**
  * Get emoji for a capability from loaded capability data
  * @param {Object[]} capabilities - Loaded capabilities array
@@ -400,10 +346,21 @@ export const SkillType = {
  * @property {number} [expectedDurationMinutes] - Estimated time to ask and answer
  */
 
+/**
+ * @typedef {Object<string, Question[]>} LevelQuestions - Questions organized by level
+ */
+
+/**
+ * @typedef {Object} RoleTypeQuestions
+ * @property {LevelQuestions} [professionalQuestions] - Questions for professional/IC roles
+ * @property {LevelQuestions} [managementQuestions] - Questions for management roles
+ */
+
 /**
  * @typedef {Object} QuestionBank
- * @property {Object<string, Object<string, Question[]>>} skillLevels - Questions by skill ID, then by level
- * @property {Object<string, Object<string, Question[]>>} behaviourMaturities - Questions by behaviour ID, then by maturity
+ * @property {Object<string, RoleTypeQuestions>} skillLevels - Questions by skill ID, then by role type (professional/management), then by level
+ * @property {Object<string, RoleTypeQuestions>} behaviourMaturities - Questions by behaviour ID, then by role type, then by maturity
+ * @property {Object<string, RoleTypeQuestions>} [capabilityLevels] - Questions by capability ID, then by role type, then by level
  */
 
 /**

package/{lib → src}/loader.js

@@ -281,12 +281,16 @@ async function loadCapabilitiesFromDir(capabilitiesDir) {
  * @returns {Promise<import('./levels.js').QuestionBank>}
  */
 export async function loadQuestionFolder(questionsDir) {
-  const [skillLevels, behaviourMaturities] = await Promise.all([
-    loadQuestionsFromDir(join(questionsDir, "skills")),
-    loadQuestionsFromDir(join(questionsDir, "behaviours")),
-  ]);
+  const [skillLevels, behaviourMaturities, capabilityLevels] =
+    await Promise.all([
+      loadQuestionsFromDir(join(questionsDir, "skills")),
+      loadQuestionsFromDir(join(questionsDir, "behaviours")),
+      loadQuestionsFromDir(join(questionsDir, "capabilities")).catch(
+        () => ({}),
+      ),
+    ]);
 
-  return { skillLevels, behaviourMaturities };
+  return { skillLevels, behaviourMaturities, capabilityLevels };
 }
 
 /**

package/{lib → src}/modifiers.js

@@ -5,13 +5,13 @@
  * Full modifier logic is in @forwardimpact/model.
  */
 
-import { CAPABILITY_ORDER } from "./levels.js";
+import { Capability } from "./levels.js";
 
 /**
- * Valid skill capability names
+ * Valid skill capability names (derived from Capability enum)
  * @type {Set<string>}
  */
-const VALID_CAPABILITIES = new Set(CAPABILITY_ORDER);
+const VALID_CAPABILITIES = new Set(Object.values(Capability));
 
 /**
  * Check if a key is a skill capability

package/{lib → src}/validation.js

@@ -1774,6 +1774,7 @@ export function validateQuestionBank(questionBank, skills, behaviours) {
   const warnings = [];
   const skillIds = new Set(skills.map((s) => s.id));
   const behaviourIds = new Set(behaviours.map((b) => b.id));
+  const validRoleTypes = ["professionalQuestions", "managementQuestions"];
 
   if (!questionBank) {
     return createValidationResult(false, [
@@ -1784,7 +1785,7 @@ export function validateQuestionBank(questionBank, skills, behaviours) {
   // Validate skill questions
   if (questionBank.skillLevels) {
     Object.entries(questionBank.skillLevels).forEach(
-      ([skillId, levelQuestions]) => {
+      ([skillId, roleTypeQuestions]) => {
         if (!skillIds.has(skillId)) {
           errors.push(
             createError(
@@ -1795,27 +1796,46 @@ export function validateQuestionBank(questionBank, skills, behaviours) {
             ),
           );
         }
-        Object.entries(levelQuestions || {}).forEach(([level, questions]) => {
-          if (getSkillLevelIndex(level) === -1) {
-            errors.push(
-              createError(
-                "INVALID_VALUE",
-                `Question bank has invalid skill level: ${level}`,
-                `questionBank.skillLevels.${skillId}.${level}`,
-                level,
-              ),
-            );
-          }
-          if (!Array.isArray(questions) || questions.length === 0) {
-            warnings.push(
-              createWarning(
-                "EMPTY_QUESTIONS",
-                `No questions for skill ${skillId} at level ${level}`,
-                `questionBank.skillLevels.${skillId}.${level}`,
-              ),
+        // Validate each role type (professional/management)
+        Object.entries(roleTypeQuestions || {}).forEach(
+          ([roleType, levelQuestions]) => {
+            if (!validRoleTypes.includes(roleType)) {
+              errors.push(
+                createError(
+                  "INVALID_VALUE",
+                  `Question bank has invalid role type: ${roleType}`,
+                  `questionBank.skillLevels.${skillId}.${roleType}`,
+                  roleType,
+                ),
+              );
+              return;
+            }
+            // Validate each level within the role type
+            Object.entries(levelQuestions || {}).forEach(
+              ([level, questions]) => {
+                if (getSkillLevelIndex(level) === -1) {
+                  errors.push(
+                    createError(
+                      "INVALID_VALUE",
+                      `Question bank has invalid skill level: ${level}`,
+                      `questionBank.skillLevels.${skillId}.${roleType}.${level}`,
+                      level,
+                    ),
+                  );
+                }
+                if (!Array.isArray(questions) || questions.length === 0) {
+                  warnings.push(
+                    createWarning(
+                      "EMPTY_QUESTIONS",
+                      `No questions for skill ${skillId} (${roleType}) at level ${level}`,
+                      `questionBank.skillLevels.${skillId}.${roleType}.${level}`,
+                    ),
+                  );
+                }
+              },
             );
-          }
-        });
+          },
+        );
       },
     );
   }
@@ -1823,7 +1843,7 @@ export function validateQuestionBank(questionBank, skills, behaviours) {
   // Validate behaviour questions
   if (questionBank.behaviourMaturities) {
     Object.entries(questionBank.behaviourMaturities).forEach(
-      ([behaviourId, maturityQuestions]) => {
+      ([behaviourId, roleTypeQuestions]) => {
         if (!behaviourIds.has(behaviourId)) {
           errors.push(
             createError(
@@ -1834,27 +1854,44 @@ export function validateQuestionBank(questionBank, skills, behaviours) {
             ),
           );
         }
-        Object.entries(maturityQuestions || {}).forEach(
-          ([maturity, questions]) => {
-            if (getBehaviourMaturityIndex(maturity) === -1) {
+        // Validate each role type (professional/management)
+        Object.entries(roleTypeQuestions || {}).forEach(
+          ([roleType, maturityQuestions]) => {
+            if (!validRoleTypes.includes(roleType)) {
               errors.push(
                 createError(
                   "INVALID_VALUE",
-                  `Question bank has invalid behaviour maturity: ${maturity}`,
-                  `questionBank.behaviourMaturities.${behaviourId}.${maturity}`,
-                  maturity,
-                ),
-              );
-            }
-            if (!Array.isArray(questions) || questions.length === 0) {
-              warnings.push(
-                createWarning(
-                  "EMPTY_QUESTIONS",
-                  `No questions for behaviour ${behaviourId} at maturity ${maturity}`,
-                  `questionBank.behaviourMaturities.${behaviourId}.${maturity}`,
+                  `Question bank has invalid role type: ${roleType}`,
+                  `questionBank.behaviourMaturities.${behaviourId}.${roleType}`,
+                  roleType,
                 ),
               );
+              return;
             }
+            // Validate each maturity level within the role type
+            Object.entries(maturityQuestions || {}).forEach(
+              ([maturity, questions]) => {
+                if (getBehaviourMaturityIndex(maturity) === -1) {
+                  errors.push(
+                    createError(
+                      "INVALID_VALUE",
+                      `Question bank has invalid behaviour maturity: ${maturity}`,
+                      `questionBank.behaviourMaturities.${behaviourId}.${roleType}.${maturity}`,
+                      maturity,
+                    ),
+                  );
+                }
+                if (!Array.isArray(questions) || questions.length === 0) {
+                  warnings.push(
+                    createWarning(
+                      "EMPTY_QUESTIONS",
+                      `No questions for behaviour ${behaviourId} (${roleType}) at maturity ${maturity}`,
+                      `questionBank.behaviourMaturities.${behaviourId}.${roleType}.${maturity}`,
+                    ),
+                  );
+                }
+              },
+            );
           },
         );
       },