@forwardimpact/model 0.5.0 → 0.7.1

package/src/policies/thresholds.js

@@ -0,0 +1,317 @@
+/**
+ * Policy Thresholds, Scores, and Weights
+ *
+ * Named constants for filter thresholds, scoring, and priority weights.
+ * Grep for THRESHOLD_, SCORE_, WEIGHT_ to find all policy values.
+ */
+
+// =============================================================================
+// Match Tier Thresholds
+// =============================================================================
+
+/**
+ * Match tier score thresholds
+ *
+ * These thresholds determine how candidate match scores are classified.
+ * Adjust these to change how lenient/strict match tiers are.
+ *
+ * @see matching.js:classifyMatch
+ */
+export const THRESHOLD_MATCH_STRONG = 0.85;
+export const THRESHOLD_MATCH_GOOD = 0.7;
+export const THRESHOLD_MATCH_STRETCH = 0.55;
+export const THRESHOLD_MATCH_ASPIRATIONAL = 0;
+
+// =============================================================================
+// Gap Score Decay
+// =============================================================================
+
+/**
+ * Gap score decay values
+ *
+ * When a candidate has a gap between their level and the job requirement,
+ * these scores penalize larger gaps more heavily.
+ *
+ * @see matching.js:calculateGapScore
+ */
+export const SCORE_GAP_MEETS = 1.0;
+export const SCORE_GAP_MINOR = 0.7;
+export const SCORE_GAP_SIGNIFICANT = 0.4;
+export const SCORE_GAP_MAJOR = 0.15;
+export const SCORE_GAP_ASPIRATIONAL = 0.05;
+
+/** Gap scores indexed by gap size (0-4+) */
+export const SCORE_GAP = {
+  0: SCORE_GAP_MEETS,
+  1: SCORE_GAP_MINOR,
+  2: SCORE_GAP_SIGNIFICANT,
+  3: SCORE_GAP_MAJOR,
+  4: SCORE_GAP_ASPIRATIONAL,
+};
+
+// =============================================================================
+// Skill Priority Weights
+// =============================================================================
+
+/**
+ * Skill priority weights by type
+ *
+ * Primary skills are core competencies and get highest priority.
+ * Used for interview question selection and development prioritization.
+ *
+ * @see interview.js:calculateSkillPriority
+ */
+export const WEIGHT_SKILL_TYPE_PRIMARY = 30;
+export const WEIGHT_SKILL_TYPE_SECONDARY = 20;
+export const WEIGHT_SKILL_TYPE_BROAD = 10;
+export const WEIGHT_SKILL_TYPE_TRACK = 5;
+
+/** Skill type weights as object for lookup */
+export const WEIGHT_SKILL_TYPE = {
+  primary: WEIGHT_SKILL_TYPE_PRIMARY,
+  secondary: WEIGHT_SKILL_TYPE_SECONDARY,
+  broad: WEIGHT_SKILL_TYPE_BROAD,
+  track: WEIGHT_SKILL_TYPE_TRACK,
+};
+
+// =============================================================================
+// Capability Priority Boosts
+// =============================================================================
+
+/**
+ * Capability priority boosts
+ *
+ * Certain capabilities get additional priority in the AI-era engineering model.
+ *
+ * @see interview.js:calculateSkillPriority
+ */
+export const WEIGHT_CAPABILITY_AI = 15;
+export const WEIGHT_CAPABILITY_DELIVERY = 5;
+
+/** Capability boosts as object for lookup */
+export const WEIGHT_CAPABILITY_BOOST = {
+  ai: WEIGHT_CAPABILITY_AI,
+  delivery: WEIGHT_CAPABILITY_DELIVERY,
+};
+
+// =============================================================================
+// Behaviour Priority Weights
+// =============================================================================
+
+/**
+ * Base behaviour priority weight
+ *
+ * @see interview.js:calculateBehaviourPriority
+ */
+export const WEIGHT_BEHAVIOUR_BASE = 15;
+
+/**
+ * Behaviour maturity multiplier
+ *
+ * Each maturity level adds this amount to the priority.
+ */
+export const WEIGHT_BEHAVIOUR_MATURITY = 3;
+
+// =============================================================================
+// Interview Ratios
+// =============================================================================
+
+/**
+ * Default ratio of interview time allocated to skills vs behaviours
+ *
+ * 0.6 = 60% skills, 40% behaviours
+ */
+export const RATIO_SKILL_BEHAVIOUR = 0.6;
+
+// =============================================================================
+// Skill Level Multipliers
+// =============================================================================
+
+/**
+ * Skill level multiplier for priority calculation
+ *
+ * Higher skill levels get proportionally more priority.
+ */
+export const WEIGHT_SKILL_LEVEL = 2;
+
+/**
+ * Priority penalty for below-level questions
+ */
+export const WEIGHT_BELOW_LEVEL_PENALTY = -5;
+
+// =============================================================================
+// Development Path Weights
+// =============================================================================
+
+/**
+ * Type multipliers for development path prioritization
+ *
+ * Primary skills are more critical to develop first.
+ */
+export const WEIGHT_DEV_TYPE_PRIMARY = 3;
+export const WEIGHT_DEV_TYPE_SECONDARY = 2;
+export const WEIGHT_DEV_TYPE_BROAD = 1;
+
+/**
+ * AI capability boost for development paths
+ *
+ * AI skills get extra emphasis in development planning.
+ */
+export const WEIGHT_DEV_AI_BOOST = 1.5;
+
+// =============================================================================
+// Agent Profile Limits
+// =============================================================================
+
+/**
+ * Maximum number of skills shown in agent profile body
+ *
+ * Limits the skill index table and before-handoff checklist to keep
+ * agent context focused. All skills are still exported as SKILL.md files
+ * and listed via --skills.
+ *
+ * @see agent.js:buildStageProfileBodyData
+ */
+export const LIMIT_AGENT_PROFILE_SKILLS = 5;
+
+/**
+ * Maximum number of working style entries from top behaviours
+ * in agent profiles.
+ *
+ * @see agent.js:buildWorkingStyleFromBehaviours
+ */
+export const LIMIT_AGENT_WORKING_STYLES = 3;
+
+// =============================================================================
+// Interview Time Defaults
+// =============================================================================
+
+/**
+ * Default expected duration for a standard interview question (minutes)
+ */
+export const DEFAULT_INTERVIEW_QUESTION_MINUTES = 5;
+
+/**
+ * Default expected duration for a decomposition question (minutes)
+ */
+export const DEFAULT_DECOMPOSITION_QUESTION_MINUTES = 15;
+
+/**
+ * Default expected duration for a stakeholder simulation question (minutes)
+ */
+export const DEFAULT_SIMULATION_QUESTION_MINUTES = 20;
+
+/**
+ * Tolerance above target interview budget before stopping selection (minutes)
+ *
+ * Interview question selection allows exceeding the time budget by this amount
+ * to avoid under-filling interviews.
+ */
+export const TOLERANCE_INTERVIEW_BUDGET_MINUTES = 5;
+
+// =============================================================================
+// Decomposition Capability Weights
+// =============================================================================
+
+/**
+ * Capability priority weights for decomposition interviews
+ *
+ * Delivery and scale capabilities are typically more important for
+ * system decomposition questions.
+ *
+ * @see interview.js:calculateCapabilityPriority
+ */
+export const WEIGHT_CAPABILITY_DECOMP_DELIVERY = 10;
+export const WEIGHT_CAPABILITY_DECOMP_SCALE = 8;
+export const WEIGHT_CAPABILITY_DECOMP_RELIABILITY = 6;
+
+/**
+ * Priority boost applied to focus-area questions in focused interviews
+ *
+ * @see interview.js:deriveFocusedInterview
+ */
+export const WEIGHT_FOCUS_BOOST = 10;
+
+// =============================================================================
+// Senior Grade Threshold
+// =============================================================================
+
+/**
+ * Minimum ordinalRank for a grade to be considered "senior" (Staff+)
+ *
+ * Used to determine when additional expectations scoring applies
+ * in job matching.
+ *
+ * @see derivation.js:isSeniorGrade
+ */
+export const THRESHOLD_SENIOR_GRADE = 5;
+
+// =============================================================================
+// Assessment Weights
+// =============================================================================
+
+/**
+ * Default skill weight when track does not specify assessment weights
+ */
+export const WEIGHT_ASSESSMENT_SKILL_DEFAULT = 0.5;
+
+/**
+ * Default behaviour weight when track does not specify assessment weights
+ */
+export const WEIGHT_ASSESSMENT_BEHAVIOUR_DEFAULT = 0.5;
+
+/**
+ * Base weight for overall score in senior role matching (non-expectations portion)
+ */
+export const WEIGHT_SENIOR_BASE = 0.9;
+
+/**
+ * Weight for expectations score bonus in senior role matching
+ */
+export const WEIGHT_SENIOR_EXPECTATIONS = 0.1;
+
+// =============================================================================
+// Match Result Limits
+// =============================================================================
+
+/**
+ * Number of top-priority gaps to surface in match analysis
+ */
+export const LIMIT_PRIORITY_GAPS = 3;
+
+/**
+ * Score bonus for same-track candidates in next-step job matching
+ */
+export const WEIGHT_SAME_TRACK_BONUS = 0.1;
+
+// =============================================================================
+// Realistic Match Filtering
+// =============================================================================
+
+/**
+ * Grade offset (±) from best-fit grade for realistic match filtering
+ */
+export const RANGE_GRADE_OFFSET = 1;
+
+/**
+ * Grade offset below highest strong/good match for ready-tier filtering
+ *
+ * Strong and Good matches are shown up to this many levels below the
+ * highest matched grade. Stretch and Aspirational matches are only shown
+ * at or above the highest matched grade.
+ */
+export const RANGE_READY_GRADE_OFFSET = 2;
+
+// =============================================================================
+// Driver Coverage Thresholds
+// =============================================================================
+
+/**
+ * Minimum skill level for a skill to count as "covered" in driver analysis
+ */
+export const THRESHOLD_DRIVER_SKILL_LEVEL = "working";
+
+/**
+ * Minimum behaviour maturity for a behaviour to count as "covered" in driver analysis
+ */
+export const THRESHOLD_DRIVER_BEHAVIOUR_MATURITY = "practicing";

package/src/profile.js

@@ -0,0 +1,145 @@
+/**
+ * Unified Profile Derivation
+ *
+ * Shared functions for deriving skill and behaviour profiles for both
+ * human jobs and AI agents.
+ *
+ * - prepareBaseProfile() - core derivation (skills, behaviours, responsibilities)
+ * - prepareAgentProfile() - agent-specific derivation using composed policies
+ *
+ * @see policies/composed.js - Agent filtering and sorting policies
+ */
+
+import {
+  deriveSkillMatrix,
+  deriveBehaviourProfile,
+  deriveResponsibilities,
+} from "./derivation.js";
+
+import {
+  prepareAgentSkillMatrix,
+  prepareAgentBehaviourProfile,
+} from "./policies/composed.js";
+
+// =============================================================================
+// Utility Functions
+// =============================================================================
+
+/**
+ * Build set of capabilities with positive track modifiers
+ * @param {Object} track - Track definition
+ * @returns {Set<string>} Set of capability IDs with positive modifiers
+ */
+export function getPositiveTrackCapabilities(track) {
+  return new Set(
+    Object.entries(track.skillModifiers || {})
+      .filter(([_, modifier]) => modifier > 0)
+      .map(([capability]) => capability),
+  );
+}
+
+// =============================================================================
+// Profile Derivation
+// =============================================================================
+
+/**
+ * @typedef {Object} BaseProfile
+ * @property {Array} skillMatrix - Derived skill matrix
+ * @property {Array} behaviourProfile - Derived behaviour profile
+ * @property {Array} derivedResponsibilities - Derived responsibilities (if capabilities provided)
+ * @property {Object} discipline - The discipline
+ * @property {Object} track - The track
+ * @property {Object} grade - The grade
+ */
+
+/**
+ * Prepare a base profile with raw derivation
+ *
+ * Core derivation entry point shared by jobs and agents. Produces the
+ * raw skill matrix, behaviour profile, and responsibilities without
+ * any filtering or sorting. Consumers apply policies as needed:
+ *
+ * - Human jobs: use raw output directly (sorted by type in derivation)
+ * - AI agents: use prepareAgentProfile() which applies composed policies
+ *
+ * @param {Object} params
+ * @param {Object} params.discipline - The discipline
+ * @param {Object} params.track - The track
+ * @param {Object} params.grade - The grade
+ * @param {Array} params.skills - All available skills
+ * @param {Array} params.behaviours - All available behaviours
+ * @param {Array} [params.capabilities] - Optional capabilities for responsibility derivation
+ * @returns {BaseProfile} The prepared profile
+ */
+export function prepareBaseProfile({
+  discipline,
+  track,
+  grade,
+  skills,
+  behaviours,
+  capabilities,
+}) {
+  // Core derivation
+  const skillMatrix = deriveSkillMatrix({ discipline, grade, track, skills });
+  const behaviourProfile = deriveBehaviourProfile({
+    discipline,
+    grade,
+    track,
+    behaviours,
+  });
+
+  // Derive responsibilities if capabilities provided
+  let derivedResponsibilities = [];
+  if (capabilities && capabilities.length > 0) {
+    derivedResponsibilities = deriveResponsibilities({
+      skillMatrix,
+      capabilities,
+      track,
+    });
+  }
+
+  return {
+    skillMatrix,
+    behaviourProfile,
+    derivedResponsibilities,
+    discipline,
+    track,
+    grade,
+  };
+}
+
+/**
+ * Prepare a profile optimized for agent generation
+ *
+ * Applies agent-specific policies from composed.js:
+ * - Excludes human-only skills
+ * - Keeps only skills at the highest derived level
+ * - Sorts skills by level descending
+ * - Sorts behaviours by maturity descending
+ *
+ * @param {Object} params - Same as prepareBaseProfile
+ * @returns {BaseProfile} The prepared profile with agent policies applied
+ */
+export function prepareAgentProfile({
+  discipline,
+  track,
+  grade,
+  skills,
+  behaviours,
+  capabilities,
+}) {
+  const base = prepareBaseProfile({
+    discipline,
+    track,
+    grade,
+    skills,
+    behaviours,
+    capabilities,
+  });
+
+  return {
+    ...base,
+    skillMatrix: prepareAgentSkillMatrix(base.skillMatrix),
+    behaviourProfile: prepareAgentBehaviourProfile(base.behaviourProfile),
+  };
+}

package/{lib → src}/progression.js

@@ -11,6 +11,10 @@ import {
   getBehaviourMaturityIndex,
 } from "@forwardimpact/schema/levels";
 import { deriveJob, isValidJobCombination } from "./derivation.js";
+import {
+  compareBySkillChange,
+  compareByBehaviourChange,
+} from "./policies/orderings.js";
 
 /**
  * @typedef {Object} SkillChange
@@ -128,14 +132,8 @@ export function calculateSkillChanges(currentMatrix, targetMatrix) {
     }
   }
 
-  // Sort by change (largest first), then by type, then by name
-  const typeOrder = { primary: 0, secondary: 1, broad: 2 };
-  changes.sort((a, b) => {
-    if (b.change !== a.change) return b.change - a.change;
-    if (typeOrder[a.type] !== typeOrder[b.type])
-      return typeOrder[a.type] - typeOrder[b.type];
-    return a.name.localeCompare(b.name);
-  });
+  // Sort using policy comparator
+  changes.sort(compareBySkillChange);
 
   return changes;
 }
@@ -172,11 +170,8 @@ export function calculateBehaviourChanges(currentProfile, targetProfile) {
     }
   }
 
-  // Sort by change (largest first), then by name
-  changes.sort((a, b) => {
-    if (b.change !== a.change) return b.change - a.change;
-    return a.name.localeCompare(b.name);
-  });
+  // Sort using policy comparator
+  changes.sort(compareByBehaviourChange);
 
   return changes;
 }

package/{lib → src}/toolkit.js

@@ -6,7 +6,7 @@
  * level contribute tools, ensuring focused toolkits for both jobs and agents.
  */
 
-import { filterByHighestLevel } from "./profile.js";
+import { filterToolkitSkills } from "./policies/composed.js";
 
 /**
  * @typedef {Object} ToolkitEntry
@@ -30,8 +30,8 @@ import { filterByHighestLevel } from "./profile.js";
  * @returns {ToolkitEntry[]} De-duplicated toolkit sorted by name
  */
 export function deriveToolkit({ skillMatrix, skills }) {
-  // Filter to highest level skills only
-  const sourceMatrix = filterByHighestLevel(skillMatrix);
+  // Filter to highest level skills only using policy
+  const sourceMatrix = filterToolkitSkills(skillMatrix);
 
   // Build skill lookup map for O(1) access
   const skillMap = new Map(skills.map((s) => [s.id, s]));