@forwardimpact/model 0.4.0 → 0.7.0

package/{lib → src}/matching.js

@@ -16,6 +16,17 @@ import {
   isSeniorGrade,
 } from "./derivation.js";
 
+import {
+  THRESHOLD_MATCH_STRONG,
+  THRESHOLD_MATCH_GOOD,
+  THRESHOLD_MATCH_STRETCH,
+  SCORE_GAP,
+  WEIGHT_DEV_TYPE_PRIMARY,
+  WEIGHT_DEV_TYPE_SECONDARY,
+  WEIGHT_DEV_TYPE_BROAD,
+  WEIGHT_DEV_AI_BOOST,
+} from "./policies/thresholds.js";
+
 // ============================================================================
 // Match Tier Types and Constants
 // ============================================================================
@@ -34,25 +45,26 @@ export const MatchTier = {
 
 /**
  * Match tier configuration with thresholds and display properties
+ * Uses threshold constants from policies/thresholds.js
  * @type {Object<number, {label: string, color: string, minScore: number, description: string}>}
  */
-export const MATCH_TIER_CONFIG = {
+export const CONFIG_MATCH_TIER = {
   [MatchTier.STRONG]: {
     label: "Strong Match",
     color: "green",
-    minScore: 0.85,
+    minScore: THRESHOLD_MATCH_STRONG,
     description: "Ready for this role now",
   },
   [MatchTier.GOOD]: {
     label: "Good Match",
     color: "blue",
-    minScore: 0.7,
+    minScore: THRESHOLD_MATCH_GOOD,
     description: "Ready within 6-12 months of focused growth",
   },
   [MatchTier.STRETCH]: {
     label: "Stretch Role",
     color: "amber",
-    minScore: 0.55,
+    minScore: THRESHOLD_MATCH_STRETCH,
     description: "Ambitious but achievable with dedicated development",
   },
   [MatchTier.ASPIRATIONAL]: {
@@ -76,19 +88,19 @@ export const MATCH_TIER_CONFIG = {
  * @param {number} score - Match score from 0 to 1
  * @returns {MatchTierInfo} Tier classification
  */
-export function classifyMatchTier(score) {
-  if (score >= MATCH_TIER_CONFIG[MatchTier.STRONG].minScore) {
-    return { tier: MatchTier.STRONG, ...MATCH_TIER_CONFIG[MatchTier.STRONG] };
+export function classifyMatch(score) {
+  if (score >= CONFIG_MATCH_TIER[MatchTier.STRONG].minScore) {
+    return { tier: MatchTier.STRONG, ...CONFIG_MATCH_TIER[MatchTier.STRONG] };
   }
-  if (score >= MATCH_TIER_CONFIG[MatchTier.GOOD].minScore) {
-    return { tier: MatchTier.GOOD, ...MATCH_TIER_CONFIG[MatchTier.GOOD] };
+  if (score >= CONFIG_MATCH_TIER[MatchTier.GOOD].minScore) {
+    return { tier: MatchTier.GOOD, ...CONFIG_MATCH_TIER[MatchTier.GOOD] };
   }
-  if (score >= MATCH_TIER_CONFIG[MatchTier.STRETCH].minScore) {
-    return { tier: MatchTier.STRETCH, ...MATCH_TIER_CONFIG[MatchTier.STRETCH] };
+  if (score >= CONFIG_MATCH_TIER[MatchTier.STRETCH].minScore) {
+    return { tier: MatchTier.STRETCH, ...CONFIG_MATCH_TIER[MatchTier.STRETCH] };
   }
   return {
     tier: MatchTier.ASPIRATIONAL,
-    ...MATCH_TIER_CONFIG[MatchTier.ASPIRATIONAL],
+    ...CONFIG_MATCH_TIER[MatchTier.ASPIRATIONAL],
   };
 }
 
@@ -98,16 +110,10 @@ export function classifyMatchTier(score) {
 
 /**
  * Score values for different gap sizes
- * Uses a smooth decay that reflects real-world readiness
+ * Re-exported from policies/thresholds.js for backward compatibility
  * @type {Object<number, number>}
  */
-export const GAP_SCORES = {
-  0: 1.0, // Meets or exceeds
-  1: 0.7, // Minor development needed
-  2: 0.4, // Significant but achievable gap
-  3: 0.15, // Major development required
-  4: 0.05, // Aspirational only
-};
+export const GAP_SCORES = SCORE_GAP;
 
 /**
  * Calculate gap score with smooth decay
@@ -115,11 +121,11 @@ export const GAP_SCORES = {
  * @returns {number} Score from 0 to 1
  */
 export function calculateGapScore(gap) {
-  if (gap <= 0) return GAP_SCORES[0]; // Meets or exceeds
-  if (gap === 1) return GAP_SCORES[1];
-  if (gap === 2) return GAP_SCORES[2];
-  if (gap === 3) return GAP_SCORES[3];
-  return GAP_SCORES[4]; // 4+ levels below
+  if (gap <= 0) return SCORE_GAP[0]; // Meets or exceeds
+  if (gap === 1) return SCORE_GAP[1];
+  if (gap === 2) return SCORE_GAP[2];
+  if (gap === 3) return SCORE_GAP[3];
+  return SCORE_GAP[4]; // 4+ levels below
 }
 
 /**
@@ -316,7 +322,7 @@ export function calculateJobMatch(selfAssessment, job) {
   allGaps.sort((a, b) => b.gap - a.gap);
 
   // Classify match into tier
-  const tier = classifyMatchTier(overallScore);
+  const tier = classifyMatch(overallScore);
 
   // Identify top priority gaps (top 3 by gap size)
   const priorityGaps = allGaps.slice(0, 3);
@@ -667,8 +673,12 @@ export function deriveDevelopmentPath({ selfAssessment, targetJob }) {
       // - AI skills get a boost for "AI-era focus"
       const gapSize = targetIndex - selfIndex;
       const typeMultiplier =
-        jobSkill.type === "primary" ? 3 : jobSkill.type === "secondary" ? 2 : 1;
-      const aiBoost = jobSkill.capability === "ai" ? 1.5 : 1;
+        jobSkill.type === "primary"
+          ? WEIGHT_DEV_TYPE_PRIMARY
+          : jobSkill.type === "secondary"
+            ? WEIGHT_DEV_TYPE_SECONDARY
+            : WEIGHT_DEV_TYPE_BROAD;
+      const aiBoost = jobSkill.capability === "ai" ? WEIGHT_DEV_AI_BOOST : 1;
       const priority = gapSize * typeMultiplier * aiBoost;
 
       items.push({

package/{lib → src}/modifiers.js

@@ -6,13 +6,13 @@
  * (e.g., "delivery: 1", "scale: -1") - individual skill modifiers are not allowed.
  */
 
-import { CAPABILITY_ORDER } from "@forwardimpact/schema/levels";
+import { Capability } from "@forwardimpact/schema/levels";
 
 /**
  * Valid skill capability names for modifier expansion
  * @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
@@ -66,7 +66,7 @@ export function buildCapabilityToSkillsMap(skills) {
  * @param {import('./levels.js').Skill[]} skills - Array of all skills (for capability lookup)
  * @returns {Object<string, number>} Expanded skill modifiers with individual skill IDs
  */
-export function expandSkillModifiers(skillModifiers, skills) {
+export function expandModifiersToSkills(skillModifiers, skills) {
   if (!skillModifiers) {
     return {};
   }
@@ -113,7 +113,7 @@ export function extractCapabilityModifiers(skillModifiers) {
  * @param {Object<string, number>} skillModifiers - The skill modifiers
  * @returns {Object<string, number>} Only the individual skill modifiers
  */
-export function extractIndividualModifiers(skillModifiers) {
+export function extractSkillModifiers(skillModifiers) {
   if (!skillModifiers) {
     return {};
   }

package/src/policies/composed.js

@@ -0,0 +1,111 @@
+/**
+ * Composed Policy Definitions
+ *
+ * Named policy compositions for specific use cases.
+ * Each POLICY_* export defines a complete filtering/sorting strategy.
+ *
+ * These are the high-level policies used by consuming code.
+ */
+
+import { isAgentEligible } from "./predicates.js";
+import { filterHighestLevel, composeFilters } from "./filters.js";
+import {
+  compareByLevelDesc,
+  compareByMaturityDesc,
+  compareByTypeAndName,
+} from "./orderings.js";
+
+// =============================================================================
+// Agent Skill Policies
+// =============================================================================
+
+/**
+ * Filter for agent-eligible skills at highest derived level
+ *
+ * Agents receive skills after:
+ * 1. Excluding human-only skills (isAgentEligible)
+ * 2. Keeping only skills at the highest derived level
+ *
+ * This ensures agents focus on their peak competencies and
+ * respects track modifiers (a broad skill boosted to the same
+ * level as primary skills will be included).
+ */
+export const filterAgentSkills = composeFilters(
+  isAgentEligible,
+  filterHighestLevel,
+);
+
+// =============================================================================
+// Toolkit Extraction Policy
+// =============================================================================
+
+/**
+ * Filter for toolkit extraction
+ *
+ * Tools are extracted only from highest-level skills,
+ * keeping the toolkit focused on core competencies.
+ */
+export const filterToolkitSkills = composeFilters(filterHighestLevel);
+
+// =============================================================================
+// Sorting Policies
+// =============================================================================
+
+/**
+ * Sort skills for agent profiles (level descending)
+ * @param {Array} skills - Skill matrix entries
+ * @returns {Array} Sorted skills (new array)
+ */
+export function sortAgentSkills(skills) {
+  return [...skills].sort(compareByLevelDesc);
+}
+
+/**
+ * Sort behaviours for agent profiles (maturity descending)
+ * @param {Array} behaviours - Behaviour profile entries
+ * @returns {Array} Sorted behaviours (new array)
+ */
+export function sortAgentBehaviours(behaviours) {
+  return [...behaviours].sort(compareByMaturityDesc);
+}
+
+/**
+ * Sort skills for job display (type ascending, then name)
+ * @param {Array} skills - Skill matrix entries
+ * @returns {Array} Sorted skills (new array)
+ */
+export function sortJobSkills(skills) {
+  return [...skills].sort(compareByTypeAndName);
+}
+
+// =============================================================================
+// Combined Filter + Sort Policies
+// =============================================================================
+
+/**
+ * Prepare skills for agent profile generation
+ *
+ * Complete pipeline:
+ * 1. Filter to agent-eligible skills
+ * 2. Keep only highest-level skills
+ * 3. Sort by level descending
+ *
+ * @param {Array} skillMatrix - Full skill matrix
+ * @returns {Array} Filtered and sorted skills
+ */
+export function prepareAgentSkillMatrix(skillMatrix) {
+  const filtered = filterAgentSkills(skillMatrix);
+  return sortAgentSkills(filtered);
+}
+
+/**
+ * Prepare behaviours for agent profile generation
+ *
+ * Sorts by maturity descending (highest first).
+ *
+ * @param {Array} behaviourProfile - Full behaviour profile
+ * @returns {Array} Sorted behaviours
+ */
+export function prepareAgentBehaviourProfile(behaviourProfile) {
+  return sortAgentBehaviours(behaviourProfile);
+}

package/src/policies/filters.js

@@ -0,0 +1,104 @@
+/**
+ * Matrix-Level Filter Functions
+ *
+ * Filters that operate on entire arrays of skill/behaviour entries.
+ * Unlike predicates (single entry → boolean), these transform arrays.
+ *
+ * Naming convention: filter* for functions that reduce/transform arrays.
+ */
+
+import { getSkillLevelIndex } from "@forwardimpact/schema/levels";
+
+// =============================================================================
+// Level-Based Filters
+// =============================================================================
+
+/**
+ * Filter matrix to keep only skills at the highest derived level
+ *
+ * After track modifiers are applied, some skills will be at higher levels
+ * than others. This filter keeps only the skills at the maximum level.
+ *
+ * @param {Array} matrix - Skill matrix entries with derived levels
+ * @returns {Array} Filtered matrix with only max-level skills
+ */
+export function filterHighestLevel(matrix) {
+  if (matrix.length === 0) return [];
+
+  const maxIndex = Math.max(
+    ...matrix.map((entry) => getSkillLevelIndex(entry.level)),
+  );
+
+  return matrix.filter((entry) => getSkillLevelIndex(entry.level) === maxIndex);
+}
+
+/**
+ * Filter matrix to exclude skills at awareness level
+ *
+ * Skills at awareness level are typically too basic for certain outputs
+ * like responsibilities derivation.
+ *
+ * @param {Array} matrix - Skill matrix entries
+ * @returns {Array} Filtered matrix excluding awareness skills
+ */
+export function filterAboveAwareness(matrix) {
+  return matrix.filter((entry) => entry.level !== "awareness");
+}
+
+// =============================================================================
+// Predicate Application
+// =============================================================================
+
+/**
+ * Apply a predicate to filter a matrix
+ *
+ * Convenience wrapper around Array.filter() for consistency with
+ * the policy API.
+ *
+ * @param {Function} predicate - Predicate function (entry → boolean)
+ * @returns {(matrix: Array) => Array} Curried filter function
+ */
+export function filterBy(predicate) {
+  return (matrix) => matrix.filter(predicate);
+}
+
+// =============================================================================
+// Pipeline Application
+// =============================================================================
+
+/**
+ * Apply multiple filter operations in sequence
+ *
+ * Each operation can be either:
+ * - A predicate function (entry → boolean): used with Array.filter()
+ * - A matrix filter (array → array): applied directly
+ *
+ * Detection: if the function returns an array when given [{}], it's a matrix filter.
+ *
+ * @param {Array} matrix - Initial items
+ * @param {...Function} operations - Predicates or matrix filters
+ * @returns {Array} Transformed items
+ */
+export function applyFilters(matrix, ...operations) {
+  return operations.reduce((acc, op) => {
+    // Detect matrix filter by checking return type
+    // Matrix filters always return arrays; predicates return booleans
+    const testResult = op([{}]);
+    if (Array.isArray(testResult)) {
+      return op(acc);
+    }
+    return acc.filter(op);
+  }, matrix);
+}
+
+/**
+ * Compose filter operations into a single filter function
+ *
+ * Useful for creating reusable composed policies.
+ *
+ * @param {...Function} operations - Predicates or matrix filters
+ * @returns {(matrix: Array) => Array} Composed filter function
+ */
+export function composeFilters(...operations) {
+  return (matrix) => applyFilters(matrix, ...operations);
+}

package/src/policies/index.js

@@ -0,0 +1,128 @@
+/**
+ * Policy Module Index
+ *
+ * Re-exports all policy constants, predicates, filters, and orderings.
+ *
+ * Usage:
+ *   import { THRESHOLD_MATCH_STRONG, isAgentEligible, filterHighestLevel }
+ *     from "@forwardimpact/model/policies";
+ */
+
+// Thresholds, scores, and weights
+export {
+  // Match tier thresholds
+  THRESHOLD_MATCH_STRONG,
+  THRESHOLD_MATCH_GOOD,
+  THRESHOLD_MATCH_STRETCH,
+  THRESHOLD_MATCH_ASPIRATIONAL,
+  // Gap scores
+  SCORE_GAP_MEETS,
+  SCORE_GAP_MINOR,
+  SCORE_GAP_SIGNIFICANT,
+  SCORE_GAP_MAJOR,
+  SCORE_GAP_ASPIRATIONAL,
+  SCORE_GAP,
+  // Skill type weights
+  WEIGHT_SKILL_TYPE_PRIMARY,
+  WEIGHT_SKILL_TYPE_SECONDARY,
+  WEIGHT_SKILL_TYPE_BROAD,
+  WEIGHT_SKILL_TYPE_TRACK,
+  WEIGHT_SKILL_TYPE,
+  // Capability boosts
+  WEIGHT_CAPABILITY_AI,
+  WEIGHT_CAPABILITY_DELIVERY,
+  WEIGHT_CAPABILITY_BOOST,
+  // Behaviour weights
+  WEIGHT_BEHAVIOUR_BASE,
+  WEIGHT_BEHAVIOUR_MATURITY,
+  // Interview ratios
+  RATIO_SKILL_BEHAVIOUR,
+  // Level multipliers
+  WEIGHT_SKILL_LEVEL,
+  WEIGHT_BELOW_LEVEL_PENALTY,
+  // Development path weights
+  WEIGHT_DEV_TYPE_PRIMARY,
+  WEIGHT_DEV_TYPE_SECONDARY,
+  WEIGHT_DEV_TYPE_BROAD,
+  WEIGHT_DEV_AI_BOOST,
+} from "./thresholds.js";
+
+// Predicates
+export {
+  // Identity
+  isAny,
+  isNone,
+  // Human-only
+  isHumanOnly,
+  isAgentEligible,
+  // Skill types
+  isPrimary,
+  isSecondary,
+  isBroad,
+  isTrack,
+  isCore,
+  isSupporting,
+  // Skill levels
+  hasMinLevel,
+  hasLevel,
+  hasBelowLevel,
+  // Capabilities
+  isInCapability,
+  isInAnyCapability,
+  // Combinators
+  allOf,
+  anyOf,
+  not,
+} from "./predicates.js";
+
+// Filters
+export {
+  filterHighestLevel,
+  filterAboveAwareness,
+  filterBy,
+  applyFilters,
+  composeFilters,
+} from "./filters.js";
+
+// Orderings
+export {
+  // Canonical orders
+  ORDER_SKILL_TYPE,
+  ORDER_STAGE,
+  ORDER_AGENT_STAGE,
+  // Skill comparators
+  compareByLevelDesc,
+  compareByLevelAsc,
+  compareByType,
+  compareByName,
+  compareBySkillPriority,
+  compareByTypeAndName,
+  // Capability comparators
+  compareByCapability,
+  sortSkillsByCapability,
+  // Behaviour comparators
+  compareByMaturityDesc,
+  compareByMaturityAsc,
+  compareByBehaviourName,
+  compareByBehaviourPriority,
+  // Generic comparators
+  compareByOrder,
+  chainComparators,
+  // Change comparators
+  compareBySkillChange,
+  compareByBehaviourChange,
+} from "./orderings.js";
+
+// Composed policies
+export {
+  // Agent skill filtering
+  filterAgentSkills,
+  filterToolkitSkills,
+  // Sorting
+  sortAgentSkills,
+  sortAgentBehaviours,
+  sortJobSkills,
+  // Combined filter + sort
+  prepareAgentSkillMatrix,
+  prepareAgentBehaviourProfile,
+} from "./composed.js";