@forwardimpact/schema 0.4.0 → 0.7.0

package/schema/json/stages.schema.json

@@ -14,7 +14,7 @@
       "properties": {
         "id": {
           "type": "string",
-          "enum": ["specify", "plan", "code", "review", "deploy"],
+          "enum": ["specify", "plan", "onboard", "code", "review", "deploy"],
           "description": "Stage identifier"
         },
         "name": {
@@ -47,16 +47,16 @@
             "type": "string"
           }
         },
-        "entryCriteria": {
+        "readChecklist": {
           "type": "array",
-          "description": "Conditions that must be met before entering this stage",
+          "description": "Read-Then-Do Checklist: steps to follow in order during this stage",
           "items": {
             "type": "string"
           }
         },
-        "exitCriteria": {
+        "confirmChecklist": {
           "type": "array",
-          "description": "Conditions that must be met before leaving this stage",
+          "description": "Do-Then-Confirm Checklist: items to verify before handing off to next stage",
           "items": {
             "type": "string"
           }
@@ -70,7 +70,7 @@
       "properties": {
         "targetStage": {
           "type": "string",
-          "enum": ["specify", "plan", "code", "review", "deploy"],
+          "enum": ["specify", "plan", "onboard", "code", "review", "deploy"],
           "description": "The stage to transition to"
         },
         "label": {

package/schema/rdf/behaviour-questions.ttl

@@ -7,7 +7,10 @@
 # =============================================================================
 # Behaviour Questions Schema
 # =============================================================================
-# Interview questions for assessing behaviours.
+# Stakeholder simulation interview questions for assessing behaviours,
+# organized by role type (professional/management) and maturity level.
+# Each question presents a realistic stakeholder scenario with simulation
+# prompts to guide the interview panel.
 # =============================================================================
 
 # -----------------------------------------------------------------------------
@@ -26,6 +29,12 @@ fit:atMaturity a rdf:Property ;
     rdfs:domain fit:Question ;
     rdfs:range fit:BehaviourMaturity .
 
+fit:simulationPrompts a rdf:Property ;
+    rdfs:label "simulationPrompts"@en ;
+    rdfs:comment "Guiding prompts to steer the stakeholder simulation and probe the candidate's behaviour"@en ;
+    rdfs:domain fit:Question ;
+    rdfs:range xsd:string .
+
 # =============================================================================
 # SHACL SHAPES
 # =============================================================================
@@ -48,27 +57,42 @@ fit:BehaviourQuestionShape a sh:NodeShape ;
     sh:property [
         sh:path fit:text ;
         sh:datatype xsd:string ;
-        sh:maxLength 150 ;
+        sh:maxLength 300 ;
         sh:minCount 1 ;
         sh:maxCount 1 ;
         sh:name "text" ;
-        sh:description "The question text (under 150 characters)" ;
+        sh:description "The stakeholder scenario (under 300 characters)" ;
+    ] ;
+    sh:property [
+        sh:path fit:context ;
+        sh:datatype xsd:string ;
+        sh:maxCount 1 ;
+        sh:name "context" ;
+        sh:description "Additional context to set up the simulation scenario" ;
+    ] ;
+    sh:property [
+        sh:path fit:simulationPrompts ;
+        sh:datatype xsd:string ;
+        sh:minCount 2 ;
+        sh:maxCount 5 ;
+        sh:name "simulationPrompts" ;
+        sh:description "3-5 guiding prompts to steer the simulation" ;
     ] ;
     sh:property [
         sh:path fit:lookingFor ;
         sh:datatype xsd:string ;
-        sh:minCount 1 ;
+        sh:minCount 2 ;
         sh:maxCount 4 ;
         sh:name "lookingFor" ;
-        sh:description "2-4 bullet points of good answer indicators" ;
+        sh:description "2-4 indicators of strong behavioural response" ;
     ] ;
     sh:property [
         sh:path fit:expectedDurationMinutes ;
         sh:datatype xsd:integer ;
-        sh:minInclusive 1 ;
+        sh:minInclusive 10 ;
         sh:maxCount 1 ;
         sh:name "expectedDurationMinutes" ;
-        sh:description "Expected duration in minutes" ;
+        sh:description "Expected duration in minutes (default: 20)" ;
     ] ;
     sh:property [
         sh:path fit:followUps ;
@@ -93,4 +117,12 @@ fit:BehaviourQuestionShape a sh:NodeShape ;
         sh:maxCount 1 ;
         sh:name "atMaturity" ;
         sh:description "The behaviour maturity 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/capability.ttl

@@ -153,14 +153,14 @@ fit:focus a rdf:Property ;
     rdfs:comment "Primary focus for this stage"@en ;
     rdfs:range xsd:string .
 
-fit:activities a rdf:Property ;
-    rdfs:label "activities"@en ;
-    rdfs:comment "Key activities to perform in this stage"@en ;
+fit:readChecklist a rdf:Property ;
+    rdfs:label "readChecklist"@en ;
+    rdfs:comment "Read-Then-Do Checklist: steps to follow in order during this stage"@en ;
     rdfs:range xsd:string .
 
-fit:ready a rdf:Property ;
-    rdfs:label "ready"@en ;
-    rdfs:comment "Criteria that indicate readiness to move to next stage"@en ;
+fit:confirmChecklist a rdf:Property ;
+    rdfs:label "confirmChecklist"@en ;
+    rdfs:comment "Do-Then-Confirm Checklist: items to verify before moving to next stage"@en ;
     rdfs:range xsd:string .
 
 # =============================================================================
@@ -197,12 +197,12 @@ fit:CapabilityShape a sh:NodeShape ;
         sh:description "Emoji for visual representation" ;
     ] ;
     sh:property [
-        sh:path fit:displayOrder ;
+        sh:path fit:ordinalRank ;
         sh:datatype xsd:integer ;
         sh:minInclusive 1 ;
         sh:maxCount 1 ;
-        sh:name "displayOrder" ;
-        sh:description "Order for display in UI" ;
+        sh:name "ordinalRank" ;
+        sh:description "Numeric rank for ordering capabilities (1 = first)" ;
     ] ;
     sh:property [
         sh:path fit:description ;
@@ -425,16 +425,16 @@ fit:SkillStageShape a sh:NodeShape ;
         sh:description "Primary focus for this stage" ;
     ] ;
     sh:property [
-        sh:path fit:activities ;
+        sh:path fit:readChecklist ;
         sh:datatype xsd:string ;
         sh:minCount 1 ;
-        sh:name "activities" ;
-        sh:description "Key activities to perform in this stage" ;
+        sh:name "readChecklist" ;
+        sh:description "Read-Then-Do Checklist: steps to follow in order during this stage" ;
     ] ;
     sh:property [
-        sh:path fit:ready ;
+        sh:path fit:confirmChecklist ;
         sh:datatype xsd:string ;
         sh:minCount 1 ;
-        sh:name "ready" ;
-        sh:description "Criteria that indicate readiness to move to next stage" ;
+        sh:name "confirmChecklist" ;
+        sh:description "Do-Then-Confirm Checklist: items to verify before moving to next stage" ;
     ] .

package/schema/rdf/defs.ttl

@@ -134,9 +134,9 @@ fit:emojiIcon a rdf:Property ;
     rdfs:comment "Emoji for visual representation"@en ;
     rdfs:range xsd:string .
 
-fit:displayOrder a rdf:Property ;
-    rdfs:label "displayOrder"@en ;
-    rdfs:comment "Order for display in UI"@en ;
+fit:ordinalRank a rdf:Property ;
+    rdfs:label "ordinalRank"@en ;
+    rdfs:comment "Numeric rank for ordering (1 = first)"@en ;
     rdfs:range xsd:integer .
 
 fit:ordinal a rdf:Property ;

package/schema/rdf/framework.ttl

@@ -22,6 +22,10 @@ fit:EntityDefinition a rdfs:Class ;
     rdfs:label "Entity Definition"@en ;
     rdfs:comment "Definition for an entity type used in pages and chapters"@en .
 
+fit:Distribution a rdfs:Class ;
+    rdfs:label "Distribution"@en ;
+    rdfs:comment "Distribution configuration for publishing and installing the framework"@en .
+
 # -----------------------------------------------------------------------------
 # Properties
 # -----------------------------------------------------------------------------
@@ -38,6 +42,18 @@ fit:entityDefinitions a rdf:Property ;
     rdfs:domain fit:Framework ;
     rdfs:range fit:EntityDefinition .
 
+fit:distribution a rdf:Property ;
+    rdfs:label "distribution"@en ;
+    rdfs:comment "Distribution configuration for the framework"@en ;
+    rdfs:domain fit:Framework ;
+    rdfs:range fit:Distribution .
+
+fit:siteUrl a rdf:Property ;
+    rdfs:label "siteUrl"@en ;
+    rdfs:comment "Base URL for the published static site"@en ;
+    rdfs:domain fit:Distribution ;
+    rdfs:range xsd:anyURI .
+
 fit:entityType a rdf:Property ;
     rdfs:label "entityType"@en ;
     rdfs:comment "The type of entity this definition describes"@en ;
@@ -88,6 +104,28 @@ fit:FrameworkShape a sh:NodeShape ;
         sh:node fit:EntityDefinitionShape ;
         sh:name "entityDefinitions" ;
         sh:description "Definitions for each entity type" ;
+    ] ;
+    sh:property [
+        sh:path fit:distribution ;
+        sh:node fit:DistributionShape ;
+        sh:maxCount 1 ;
+        sh:name "distribution" ;
+        sh:description "Distribution configuration for the framework" ;
+    ] .
+
+# -----------------------------------------------------------------------------
+# Distribution Shape
+# -----------------------------------------------------------------------------
+
+fit:DistributionShape a sh:NodeShape ;
+    sh:targetClass fit:Distribution ;
+    sh:property [
+        sh:path fit:siteUrl ;
+        sh:datatype xsd:anyURI ;
+        sh:minCount 1 ;
+        sh:maxCount 1 ;
+        sh:name "siteUrl" ;
+        sh:description "Base URL for the published static site" ;
     ] .
 
 # -----------------------------------------------------------------------------

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

@@ -28,14 +28,14 @@ fit:handoffs a rdf:Property ;
     rdfs:domain fit:Stage ;
     rdfs:range fit:Handoff .
 
-fit:entryCriteria a rdf:Property ;
-    rdfs:label "entryCriteria"@en ;
-    rdfs:comment "Conditions that must be met before entering this stage"@en ;
+fit:readChecklist a rdf:Property ;
+    rdfs:label "readChecklist"@en ;
+    rdfs:comment "Read-Then-Do Checklist: steps to follow in order during 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 ;
+fit:confirmChecklist a rdf:Property ;
+    rdfs:label "confirmChecklist"@en ;
+    rdfs:comment "Do-Then-Confirm Checklist: items to verify before handing off to next stage"@en ;
     rdfs:range xsd:string .
 
 fit:summary a rdf:Property ;
@@ -74,7 +74,7 @@ fit:StageShape a sh:NodeShape ;
     sh:targetClass fit:Stage ;
     sh:property [
         sh:path fit:id ;
-        sh:in ( "specify" "plan" "code" "review" "deploy" ) ;
+        sh:in ( "specify" "plan" "onboard" "code" "review" "deploy" ) ;
         sh:minCount 1 ;
         sh:maxCount 1 ;
         sh:name "id" ;
@@ -122,16 +122,16 @@ fit:StageShape a sh:NodeShape ;
         sh:description "Restrictions on behaviour in this stage" ;
     ] ;
     sh:property [
-        sh:path fit:entryCriteria ;
+        sh:path fit:readChecklist ;
         sh:datatype xsd:string ;
-        sh:name "entryCriteria" ;
-        sh:description "Conditions that must be met before entering this stage" ;
+        sh:name "readChecklist" ;
+        sh:description "Read-Then-Do Checklist: steps to follow in order during this stage" ;
     ] ;
     sh:property [
-        sh:path fit:exitCriteria ;
+        sh:path fit:confirmChecklist ;
         sh:datatype xsd:string ;
-        sh:name "exitCriteria" ;
-        sh:description "Conditions that must be met before leaving this stage" ;
+        sh:name "confirmChecklist" ;
+        sh:description "Do-Then-Confirm Checklist: items to verify before handing off to next stage" ;
     ] .
 
 # -----------------------------------------------------------------------------
@@ -142,7 +142,7 @@ fit:HandoffShape a sh:NodeShape ;
     sh:targetClass fit:Handoff ;
     sh:property [
         sh:path fit:targetStage ;
-        sh:in ( "specify" "plan" "code" "review" "deploy" ) ;
+        sh:in ( "specify" "plan" "onboard" "code" "review" "deploy" ) ;
         sh:minCount 1 ;
         sh:maxCount 1 ;
         sh:name "targetStage" ;

package/{lib → src}/levels.js

@@ -54,30 +54,25 @@ export const BEHAVIOUR_MATURITY_ORDER = [
   BehaviourMaturity.EXEMPLIFYING,
 ];
 
-/**
- * Lifecycle stages for development workflow
- * @readonly
- * @enum {string}
- */
-export const Stage = {
-  SPECIFY: "specify",
-  PLAN: "plan",
-  CODE: "code",
-  REVIEW: "review",
-  DEPLOY: "deploy",
-};
+// ============================================================================
+// Data-driven Stage Functions
+// ============================================================================
+// Stage ordering is derived from loaded stage data, not hardcoded.
+// Use getStageOrder(stages) to get stage IDs in lifecycle order.
 
 /**
- * Ordered array of stages for lifecycle progression
- * @type {string[]}
+ * Get ordered stage IDs from loaded stage data
+ *
+ * Stages are defined in stages.yaml and their array order IS the
+ * canonical lifecycle order. This function extracts IDs preserving
+ * that order, similar to getCapabilityOrder for capabilities.
+ *
+ * @param {Object[]} stages - Loaded stages array from stages.yaml
+ * @returns {string[]} Stage IDs in lifecycle order
  */
-export const STAGE_ORDER = [
-  Stage.SPECIFY,
-  Stage.PLAN,
-  Stage.CODE,
-  Stage.REVIEW,
-  Stage.DEPLOY,
-];
+export function getStageOrder(stages) {
+  return stages.map((s) => s.id);
+}
 
 /**
  * Skill capabilities (what capability area)
@@ -98,72 +93,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 +153,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 +341,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