@forwardimpact/model 0.5.0 → 0.7.0

package/src/policies/orderings.js

@@ -0,0 +1,300 @@
+/**
+ * Orderings and Comparator Functions
+ *
+ * Canonical orderings for entity types and comparator functions for sorting.
+ *
+ * Naming conventions:
+ * - ORDER_* - canonical ordering arrays
+ * - compareBy* - comparator functions for Array.sort()
+ */
+
+import {
+  getSkillLevelIndex,
+  getBehaviourMaturityIndex,
+  getCapabilityOrder,
+} from "@forwardimpact/schema/levels";
+
+// =============================================================================
+// Canonical Orderings
+// =============================================================================
+
+/**
+ * Skill type ordering (T-shaped profile: core → broad)
+ * Primary skills first, then secondary, broad, and track-added skills.
+ */
+export const ORDER_SKILL_TYPE = ["primary", "secondary", "broad", "track"];
+
+/**
+ * Engineering lifecycle stages in execution order
+ */
+export const ORDER_STAGE = ["specify", "plan", "code", "review", "deploy"];
+
+/**
+ * Agent stage ordering (subset used for agent generation)
+ */
+export const ORDER_AGENT_STAGE = ["plan", "code", "review"];
+
+// =============================================================================
+// Skill Comparators
+// =============================================================================
+
+/**
+ * Compare skills by level descending (higher level first)
+ * @param {Object} a - First skill entry
+ * @param {Object} b - Second skill entry
+ * @returns {number} Comparison result
+ */
+export function compareByLevelDesc(a, b) {
+  return getSkillLevelIndex(b.level) - getSkillLevelIndex(a.level);
+}
+
+/**
+ * Compare skills by level ascending (lower level first)
+ * @param {Object} a - First skill entry
+ * @param {Object} b - Second skill entry
+ * @returns {number} Comparison result
+ */
+export function compareByLevelAsc(a, b) {
+  return getSkillLevelIndex(a.level) - getSkillLevelIndex(b.level);
+}
+
+/**
+ * Compare skills by type (primary first)
+ * @param {Object} a - First skill entry
+ * @param {Object} b - Second skill entry
+ * @returns {number} Comparison result
+ */
+export function compareByType(a, b) {
+  return ORDER_SKILL_TYPE.indexOf(a.type) - ORDER_SKILL_TYPE.indexOf(b.type);
+}
+
+/**
+ * Compare skills by name alphabetically
+ * @param {Object} a - First skill entry
+ * @param {Object} b - Second skill entry
+ * @returns {number} Comparison result
+ */
+export function compareByName(a, b) {
+  const nameA = a.skillName || a.name;
+  const nameB = b.skillName || b.name;
+  return nameA.localeCompare(nameB);
+}
+
+/**
+ * Compare skills by level (desc), then type (asc), then name (asc)
+ *
+ * Standard priority ordering for skill display:
+ * - Higher levels first
+ * - Within same level, primary before secondary before broad
+ * - Within same type, alphabetical by name
+ *
+ * @param {Object} a - First skill entry
+ * @param {Object} b - Second skill entry
+ * @returns {number} Comparison result
+ */
+export function compareBySkillPriority(a, b) {
+  // Level descending (higher level first)
+  const levelDiff = getSkillLevelIndex(b.level) - getSkillLevelIndex(a.level);
+  if (levelDiff !== 0) return levelDiff;
+
+  // Type ascending (primary first)
+  const typeA = ORDER_SKILL_TYPE.indexOf(a.type);
+  const typeB = ORDER_SKILL_TYPE.indexOf(b.type);
+  if (typeA !== typeB) return typeA - typeB;
+
+  // Name ascending (alphabetical)
+  const nameA = a.skillName || a.name;
+  const nameB = b.skillName || b.name;
+  return nameA.localeCompare(nameB);
+}
+
+/**
+ * Compare skills by type (asc), then name (asc)
+ *
+ * Standard ordering for job skill matrix display:
+ * - Primary skills first, then secondary, then broad, then track
+ * - Within same type, alphabetical by name
+ *
+ * @param {Object} a - First skill entry
+ * @param {Object} b - Second skill entry
+ * @returns {number} Comparison result
+ */
+export function compareByTypeAndName(a, b) {
+  const typeCompare = compareByType(a, b);
+  if (typeCompare !== 0) return typeCompare;
+  return compareByName(a, b);
+}
+
+// =============================================================================
+// Behaviour Comparators
+// =============================================================================
+
+/**
+ * Compare behaviours by maturity descending (higher maturity first)
+ * @param {Object} a - First behaviour entry
+ * @param {Object} b - Second behaviour entry
+ * @returns {number} Comparison result
+ */
+export function compareByMaturityDesc(a, b) {
+  return (
+    getBehaviourMaturityIndex(b.maturity) -
+    getBehaviourMaturityIndex(a.maturity)
+  );
+}
+
+/**
+ * Compare behaviours by maturity ascending (lower maturity first)
+ * @param {Object} a - First behaviour entry
+ * @param {Object} b - Second behaviour entry
+ * @returns {number} Comparison result
+ */
+export function compareByMaturityAsc(a, b) {
+  return (
+    getBehaviourMaturityIndex(a.maturity) -
+    getBehaviourMaturityIndex(b.maturity)
+  );
+}
+
+/**
+ * Compare behaviours by name alphabetically
+ * @param {Object} a - First behaviour entry
+ * @param {Object} b - Second behaviour entry
+ * @returns {number} Comparison result
+ */
+export function compareByBehaviourName(a, b) {
+  const nameA = a.behaviourName || a.name;
+  const nameB = b.behaviourName || b.name;
+  return nameA.localeCompare(nameB);
+}
+
+/**
+ * Compare behaviours by maturity (desc), then name (asc)
+ *
+ * Standard priority ordering for behaviour display:
+ * - Higher maturity first
+ * - Within same maturity, alphabetical by name
+ *
+ * @param {Object} a - First behaviour entry
+ * @param {Object} b - Second behaviour entry
+ * @returns {number} Comparison result
+ */
+export function compareByBehaviourPriority(a, b) {
+  const maturityDiff =
+    getBehaviourMaturityIndex(b.maturity) -
+    getBehaviourMaturityIndex(a.maturity);
+  if (maturityDiff !== 0) return maturityDiff;
+  return compareByBehaviourName(a, b);
+}
+
+// =============================================================================
+// Capability Comparators
+// =============================================================================
+
+/**
+ * Create a comparator for sorting by capability ordinal rank
+ *
+ * The returned comparator uses ordinalRank from loaded capability data,
+ * making the ordering data-driven rather than hardcoded.
+ *
+ * @param {Object[]} capabilities - Loaded capabilities array
+ * @returns {(a: Object, b: Object) => number} Comparator function
+ */
+export function compareByCapability(capabilities) {
+  const order = getCapabilityOrder(capabilities);
+  return (a, b) => {
+    const capA = a.capability || "";
+    const capB = b.capability || "";
+    return order.indexOf(capA) - order.indexOf(capB);
+  };
+}
+
+/**
+ * Sort skills by capability (display order), then by name
+ *
+ * @param {Object[]} skills - Array of skills to sort
+ * @param {Object[]} capabilities - Loaded capabilities array
+ * @returns {Object[]} Sorted array (new array, does not mutate input)
+ */
+export function sortSkillsByCapability(skills, capabilities) {
+  const capabilityComparator = compareByCapability(capabilities);
+  return [...skills].sort((a, b) => {
+    const capCompare = capabilityComparator(a, b);
+    if (capCompare !== 0) return capCompare;
+    const nameA = a.skillName || a.name;
+    const nameB = b.skillName || b.name;
+    return nameA.localeCompare(nameB);
+  });
+}
+
+// =============================================================================
+// Generic Comparator Factory
+// =============================================================================
+
+/**
+ * Create comparator from an ordering array
+ *
+ * @param {string[]} order - Canonical order
+ * @param {(item: Object) => string} accessor - Extract value to compare
+ * @returns {(a: Object, b: Object) => number}
+ */
+export function compareByOrder(order, accessor) {
+  return (a, b) => order.indexOf(accessor(a)) - order.indexOf(accessor(b));
+}
+
+/**
+ * Chain multiple comparators together
+ *
+ * Returns first non-zero result, or 0 if all comparators return 0.
+ *
+ * @param {...Function} comparators - Comparator functions
+ * @returns {(a: Object, b: Object) => number}
+ */
+export function chainComparators(...comparators) {
+  return (a, b) => {
+    for (const comparator of comparators) {
+      const result = comparator(a, b);
+      if (result !== 0) return result;
+    }
+    return 0;
+  };
+}
+
+// =============================================================================
+// Skill Change Comparators (for progression)
+// =============================================================================
+
+/**
+ * Compare skill changes by change magnitude (largest first), then type, then name
+ *
+ * Used for career progression analysis where biggest changes are most important.
+ *
+ * @param {Object} a - First skill change
+ * @param {Object} b - Second skill change
+ * @returns {number} Comparison result
+ */
+export function compareBySkillChange(a, b) {
+  // Change descending (largest improvement first)
+  if (b.change !== a.change) return b.change - a.change;
+
+  // Type ascending (primary first)
+  const typeA = ORDER_SKILL_TYPE.indexOf(a.type);
+  const typeB = ORDER_SKILL_TYPE.indexOf(b.type);
+  if (typeA !== typeB) return typeA - typeB;
+
+  // Name ascending
+  return a.name.localeCompare(b.name);
+}
+
+/**
+ * Compare behaviour changes by change magnitude (largest first), then name
+ *
+ * Used for career progression analysis.
+ *
+ * @param {Object} a - First behaviour change
+ * @param {Object} b - Second behaviour change
+ * @returns {number} Comparison result
+ */
+export function compareByBehaviourChange(a, b) {
+  if (b.change !== a.change) return b.change - a.change;
+  return a.name.localeCompare(b.name);
+}

package/src/policies/predicates.js

@@ -0,0 +1,177 @@
+/**
+ * Entry-Level Predicate Functions
+ *
+ * Pure predicates that operate on single skill/behaviour matrix entries.
+ * Each predicate takes one entry and returns boolean.
+ *
+ * Naming conventions:
+ * - is* - checks a boolean condition
+ * - has* - checks presence of a value
+ * - allOf/anyOf/not - combinators
+ */
+
+import { getSkillLevelIndex } from "@forwardimpact/schema/levels";
+
+// =============================================================================
+// Identity Predicates
+// =============================================================================
+
+/** Always returns true (identity predicate for optional filtering) */
+export const isAny = () => true;
+
+/** Always returns false (null predicate) */
+export const isNone = () => false;
+
+// =============================================================================
+// Human-Only Predicates
+// =============================================================================
+
+/**
+ * Returns true if skill is marked as human-only
+ * @param {Object} entry - Skill matrix entry
+ * @returns {boolean}
+ */
+export const isHumanOnly = (entry) => entry.isHumanOnly === true;
+
+/**
+ * Returns true if skill is NOT human-only (agent-eligible)
+ * @param {Object} entry - Skill matrix entry
+ * @returns {boolean}
+ */
+export const isAgentEligible = (entry) => !entry.isHumanOnly;
+
+// =============================================================================
+// Skill Type Predicates
+// =============================================================================
+
+/**
+ * Returns true if skill type is primary
+ * @param {Object} entry - Skill matrix entry
+ * @returns {boolean}
+ */
+export const isPrimary = (entry) => entry.type === "primary";
+
+/**
+ * Returns true if skill type is secondary
+ * @param {Object} entry - Skill matrix entry
+ * @returns {boolean}
+ */
+export const isSecondary = (entry) => entry.type === "secondary";
+
+/**
+ * Returns true if skill type is broad
+ * @param {Object} entry - Skill matrix entry
+ * @returns {boolean}
+ */
+export const isBroad = (entry) => entry.type === "broad";
+
+/**
+ * Returns true if skill type is track
+ * @param {Object} entry - Skill matrix entry
+ * @returns {boolean}
+ */
+export const isTrack = (entry) => entry.type === "track";
+
+/**
+ * Returns true if skill is primary or secondary (core skills)
+ * @param {Object} entry - Skill matrix entry
+ * @returns {boolean}
+ */
+export const isCore = (entry) =>
+  entry.type === "primary" || entry.type === "secondary";
+
+/**
+ * Returns true if skill is broad or track (supporting skills)
+ * @param {Object} entry - Skill matrix entry
+ * @returns {boolean}
+ */
+export const isSupporting = (entry) =>
+  entry.type === "broad" || entry.type === "track";
+
+// =============================================================================
+// Skill Level Predicates
+// =============================================================================
+
+/**
+ * Create predicate for skills at or above a minimum level
+ * @param {string} minLevel - Minimum skill level
+ * @returns {(entry: Object) => boolean}
+ */
+export function hasMinLevel(minLevel) {
+  const minIndex = getSkillLevelIndex(minLevel);
+  return (entry) => getSkillLevelIndex(entry.level) >= minIndex;
+}
+
+/**
+ * Create predicate for skills at exactly a specific level
+ * @param {string} level - Exact skill level to match
+ * @returns {(entry: Object) => boolean}
+ */
+export function hasLevel(level) {
+  const targetIndex = getSkillLevelIndex(level);
+  return (entry) => getSkillLevelIndex(entry.level) === targetIndex;
+}
+
+/**
+ * Create predicate for skills below a level threshold
+ * @param {string} maxLevel - Level that must NOT be reached
+ * @returns {(entry: Object) => boolean}
+ */
+export function hasBelowLevel(maxLevel) {
+  const maxIndex = getSkillLevelIndex(maxLevel);
+  return (entry) => getSkillLevelIndex(entry.level) < maxIndex;
+}
+
+// =============================================================================
+// Capability Predicates
+// =============================================================================
+
+/**
+ * Create predicate for skills in a specific capability
+ * @param {string} capability - Capability to match
+ * @returns {(entry: Object) => boolean}
+ */
+export function isInCapability(capability) {
+  return (entry) => entry.capability === capability;
+}
+
+/**
+ * Create predicate for skills in any of the specified capabilities
+ * @param {string[]} capabilities - Capabilities to match
+ * @returns {(entry: Object) => boolean}
+ */
+export function isInAnyCapability(capabilities) {
+  const set = new Set(capabilities);
+  return (entry) => set.has(entry.capability);
+}
+
+// =============================================================================
+// Combinators
+// =============================================================================
+
+/**
+ * Compose predicates with AND logic (all must pass)
+ * @param {...Function} predicates - Predicates to combine
+ * @returns {(entry: Object) => boolean}
+ */
+export function allOf(...predicates) {
+  return (entry) => predicates.every((p) => p(entry));
+}
+
+/**
+ * Compose predicates with OR logic (any must pass)
+ * @param {...Function} predicates - Predicates to combine
+ * @returns {(entry: Object) => boolean}
+ */
+export function anyOf(...predicates) {
+  return (entry) => predicates.some((p) => p(entry));
+}
+
+/**
+ * Negate a predicate
+ * @param {Function} predicate - Predicate to negate
+ * @returns {(entry: Object) => boolean}
+ */
+export function not(predicate) {
+  return (entry) => !predicate(entry);
+}

package/src/policies/thresholds.js

@@ -0,0 +1,160 @@
+/**
+ * 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;