@forwardimpact/model 0.5.0 → 0.7.1

package/README.md

@@ -29,8 +29,8 @@ import {
   deriveSkillMatrix,
   deriveBehaviourProfile,
 } from "@forwardimpact/model/derivation";
-import { prepareAgentProfile } from "@forwardimpact/model/agent";
-import { selectInterviewQuestions } from "@forwardimpact/model/interview";
+import { prepareAgentProfile } from "@forwardimpact/model/profile";
+import { deriveInterviewQuestions } from "@forwardimpact/model/interview";
 import { analyzeProgression } from "@forwardimpact/model/progression";
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/model",
-  "version": "0.5.0",
+  "version": "0.7.1",
   "description": "Derivation engine for roles, skills, and AI agent profiles",
   "license": "Apache-2.0",
   "repository": {
@@ -10,25 +10,27 @@
   },
   "homepage": "https://www.forwardimpact.team/model",
   "type": "module",
-  "main": "lib/index.js",
+  "main": "src/index.js",
   "files": [
-    "lib/"
+    "src/"
   ],
   "exports": {
-    ".": "./lib/index.js",
-    "./derivation": "./lib/derivation.js",
-    "./modifiers": "./lib/modifiers.js",
-    "./agent": "./lib/agent.js",
-    "./interview": "./lib/interview.js",
-    "./job": "./lib/job.js",
-    "./job-cache": "./lib/job-cache.js",
-    "./checklist": "./lib/checklist.js",
-    "./matching": "./lib/matching.js",
-    "./profile": "./lib/profile.js",
-    "./progression": "./lib/progression.js"
+    ".": "./src/index.js",
+    "./derivation": "./src/derivation.js",
+    "./modifiers": "./src/modifiers.js",
+    "./agent": "./src/agent.js",
+    "./interview": "./src/interview.js",
+    "./job": "./src/job.js",
+    "./job-cache": "./src/job-cache.js",
+    "./checklist": "./src/checklist.js",
+    "./matching": "./src/matching.js",
+    "./profile": "./src/profile.js",
+    "./progression": "./src/progression.js",
+    "./policies": "./src/policies/index.js",
+    "./toolkit": "./src/toolkit.js"
   },
   "dependencies": {
-    "@forwardimpact/schema": "^0.4.0"
+    "@forwardimpact/schema": "^0.6.0"
   },
   "engines": {
     "node": ">=18.0.0"

package/{lib → src}/agent.js

@@ -21,10 +21,13 @@
 import { deriveSkillMatrix, deriveBehaviourProfile } from "./derivation.js";
 import { deriveChecklist } from "./checklist.js";
 import {
-  filterSkillsForAgent,
-  sortByLevelDescending,
-  sortByMaturityDescending,
-} from "./profile.js";
+  filterAgentSkills,
+  sortAgentSkills,
+  sortAgentBehaviours,
+  focusAgentSkills,
+} from "./policies/composed.js";
+import { ORDER_AGENT_STAGE } from "./policies/orderings.js";
+import { LIMIT_AGENT_WORKING_STYLES } from "./policies/thresholds.js";
 import { SkillLevel } from "@forwardimpact/schema/levels";
 
 /**
@@ -123,9 +126,9 @@ export function deriveAgentSkills({ discipline, track, grade, skills }) {
     skills,
   });
 
-  // Apply agent-specific filtering and sorting
-  const filtered = filterSkillsForAgent(skillMatrix);
-  return sortByLevelDescending(filtered);
+  // Apply agent-specific filtering and sorting using policies
+  const filtered = filterAgentSkills(skillMatrix);
+  return sortAgentSkills(filtered);
 }
 
 /**
@@ -151,7 +154,7 @@ export function deriveAgentBehaviours({
     behaviours,
   });
 
-  return sortByMaturityDescending(profile);
+  return sortAgentBehaviours(profile);
 }
 
 /**
@@ -193,7 +196,7 @@ function findAgentBehaviour(agentBehaviours, id) {
 function buildWorkingStyleFromBehaviours(
   derivedBehaviours,
   agentBehaviours,
-  topN = 3,
+  topN = LIMIT_AGENT_WORKING_STYLES,
 ) {
   const entries = [];
 
@@ -229,7 +232,7 @@ function buildWorkingStyleFromBehaviours(
  * @param {Array} stages - All stage entities
  * @returns {Object} Skill with frontmatter, title, stages array, reference, dirname
  */
-export function generateSkillMd(skillData, stages) {
+export function generateSkillMarkdown(skillData, stages) {
   const { agent, name } = skillData;
 
   if (!agent) {
@@ -272,10 +275,11 @@ export function generateSkillMd(skillData, stages) {
     },
   );
 
-  // Sort stages in order: plan, code, review
-  const stageOrder = ["plan", "code", "review"];
+  // Sort stages using canonical ordering from policies
   stagesArray.sort(
-    (a, b) => stageOrder.indexOf(a.stageId) - stageOrder.indexOf(b.stageId),
+    (a, b) =>
+      ORDER_AGENT_STAGE.indexOf(a.stageId) -
+      ORDER_AGENT_STAGE.indexOf(b.stageId),
   );
 
   return {
@@ -516,7 +520,7 @@ function buildStageProfileBodyData({
     ? substituteTemplateVars(rawPriority, humanDiscipline)
     : null;
 
-  // Build skill index from derived skills with agent sections
+  // Build skill index from derived skills (already focused by deriveStageAgent)
   const skillIndex = derivedSkills
     .map((derived) => {
       const skill = skills.find((s) => s.id === derived.skillId);
@@ -536,7 +540,6 @@ function buildStageProfileBodyData({
   const workingStyles = buildWorkingStyleFromBehaviours(
     derivedBehaviours,
     agentBehaviours,
-    3,
   );
 
   // Constraints (stage + discipline + track)
@@ -600,13 +603,16 @@ export function deriveStageAgent({
   stages,
 }) {
   // Derive skills and behaviours
-  const derivedSkills = deriveAgentSkills({
+  const allSkills = deriveAgentSkills({
     discipline,
     track,
     grade,
     skills,
   });
 
+  // Focus skills for profile body (limited set to reduce context bloat)
+  const focusedSkills = focusAgentSkills(allSkills);
+
   const derivedBehaviours = deriveAgentBehaviours({
     discipline,
     track,
@@ -622,13 +628,13 @@ export function deriveStageAgent({
     stages,
   });
 
-  // Derive checklist if applicable
+  // Derive checklist from focused skills only
   const checklistStage = getChecklistStage(stage.id);
   let checklist = [];
   if (checklistStage && capabilities) {
     checklist = deriveChecklist({
       stageId: checklistStage,
-      skillMatrix: derivedSkills,
+      skillMatrix: focusedSkills,
       skills,
       capabilities,
     });
@@ -638,7 +644,7 @@ export function deriveStageAgent({
     stage,
     discipline,
     track,
-    derivedSkills,
+    derivedSkills: focusedSkills,
     derivedBehaviours,
     handoffs,
     constraints: [

package/{lib → src}/checklist.js

@@ -7,15 +7,7 @@
  * Checklist = Stage × Skill Matrix × Skill Ready Criteria
  */
 
-/**
- * Map from stage ID to the stage whose ready criteria should be shown
- * (i.e., what must be ready before leaving this stage)
- */
-const STAGE_TO_HANDOFF = {
-  plan: "plan", // Show plan.ready before leaving plan
-  code: "code", // Show code.ready before leaving code
-  review: "review", // Show review.ready (completion criteria)
-};
+import { CHECKLIST_STAGE_MAP } from "./policies/orderings.js";
 
 /**
  * Derive checklist items for a specific stage
@@ -34,7 +26,7 @@ export function deriveChecklist({
   skills,
   capabilities,
 }) {
-  const targetStage = STAGE_TO_HANDOFF[stageId];
+  const targetStage = CHECKLIST_STAGE_MAP[stageId];
   if (!targetStage) {
     return [];
   }

package/{lib → src}/derivation.js

@@ -7,8 +7,6 @@
 
 import {
   SkillType,
-  SkillLevel,
-  BehaviourMaturity,
   SKILL_LEVEL_ORDER,
   getSkillLevelIndex,
   getBehaviourMaturityIndex,
@@ -18,6 +16,12 @@ import {
 } from "@forwardimpact/schema/levels";
 
 import { resolveSkillModifier } from "./modifiers.js";
+import { ORDER_SKILL_TYPE } from "./policies/orderings.js";
+import {
+  THRESHOLD_SENIOR_GRADE,
+  THRESHOLD_DRIVER_SKILL_LEVEL,
+  THRESHOLD_DRIVER_BEHAVIOUR_MATURITY,
+} from "./policies/thresholds.js";
 
 /**
  * Build a Map of skillId → skillType for a discipline
@@ -226,14 +230,10 @@ export function deriveSkillMatrix({ discipline, grade, track = null, skills }) {
   }
 
   // Sort by type (primary first, then secondary, then broad, then track) and then by name
-  const typeOrder = {
-    [SkillType.PRIMARY]: 0,
-    [SkillType.SECONDARY]: 1,
-    [SkillType.BROAD]: 2,
-    [SkillType.TRACK]: 3,
-  };
+  // Use ORDER_SKILL_TYPE from policies for canonical ordering
   matrix.sort((a, b) => {
-    const typeCompare = typeOrder[a.type] - typeOrder[b.type];
+    const typeCompare =
+      ORDER_SKILL_TYPE.indexOf(a.type) - ORDER_SKILL_TYPE.indexOf(b.type);
     if (typeCompare !== 0) return typeCompare;
     return a.skillName.localeCompare(b.skillName);
   });
@@ -485,7 +485,7 @@ export function deriveResponsibilities({
         capability: capabilityId,
         capabilityName: capability.name,
         emojiIcon: capability.emojiIcon || "💡",
-        displayOrder: capability.displayOrder ?? 999,
+        ordinalRank: capability.ordinalRank ?? 999,
         responsibility: responsibilityText,
         level,
         levelIndex: SKILL_LEVEL_ORDER.indexOf(level),
@@ -498,7 +498,7 @@ export function deriveResponsibilities({
     if (b.levelIndex !== a.levelIndex) {
       return b.levelIndex - a.levelIndex;
     }
-    return a.displayOrder - b.displayOrder;
+    return a.ordinalRank - b.ordinalRank;
   });
 
   // Remove levelIndex from output (internal use only)
@@ -598,7 +598,10 @@ export function calculateDriverCoverage({ job, drivers }) {
 
     for (const skillId of contributingSkills) {
       const level = jobSkillLevels.get(skillId);
-      if (level && skillLevelMeetsRequirement(level, SkillLevel.WORKING)) {
+      if (
+        level &&
+        skillLevelMeetsRequirement(level, THRESHOLD_DRIVER_SKILL_LEVEL)
+      ) {
         coveredSkills.push(skillId);
       } else {
         missingSkills.push(skillId);
@@ -614,7 +617,7 @@ export function calculateDriverCoverage({ job, drivers }) {
     const coveredBehaviours = [];
     const missingBehaviours = [];
     const practicingIndex = getBehaviourMaturityIndex(
-      BehaviourMaturity.PRACTICING,
+      THRESHOLD_DRIVER_BEHAVIOUR_MATURITY,
     );
 
     for (const behaviourId of contributingBehaviours) {
@@ -681,8 +684,7 @@ export function getGradeLevel(grade) {
  * @returns {boolean} True if the grade is senior level
  */
 export function isSeniorGrade(grade) {
-  // Typically Staff+ is level 5 or higher
-  return grade.ordinalRank >= 5;
+  return grade.ordinalRank >= THRESHOLD_SENIOR_GRADE;
 }
 
 /**

package/{lib → src}/index.js

@@ -33,11 +33,11 @@ export {
 
 // Job caching
 export {
-  makeJobKey,
+  buildJobKey,
   getOrCreateJob,
-  clearJobCache,
-  invalidateJob,
-  getCacheSize,
+  clearCache,
+  invalidateCachedJob,
+  getCachedJobCount,
 } from "./job-cache.js";
 
 // Modifiers
@@ -45,17 +45,17 @@ export {
   isCapability,
   getSkillsByCapability,
   buildCapabilityToSkillsMap,
-  expandSkillModifiers,
+  expandModifiersToSkills,
   extractCapabilityModifiers,
-  extractIndividualModifiers,
+  extractSkillModifiers,
   resolveSkillModifier,
 } from "./modifiers.js";
 
 // Matching
 export {
   MatchTier,
-  MATCH_TIER_CONFIG,
-  classifyMatchTier,
+  CONFIG_MATCH_TIER,
+  classifyMatch,
   GAP_SCORES,
   calculateGapScore,
   calculateJobMatch,
@@ -87,16 +87,18 @@ export {
   deriveShortInterview,
   deriveBehaviourQuestions,
   deriveFocusedInterview,
+  deriveMissionFitInterview,
+  deriveDecompositionInterview,
+  deriveStakeholderInterview,
 } from "./interview.js";
 
 // Agent generation
 export {
   deriveReferenceGrade,
   getDisciplineAbbreviation,
-  toKebabCase,
   deriveAgentSkills,
   deriveAgentBehaviours,
-  generateSkillMd,
+  generateSkillMarkdown,
   validateAgentProfile,
   validateAgentSkill,
   deriveHandoffs,
@@ -111,15 +113,84 @@ export { deriveChecklist, formatChecklistMarkdown } from "./checklist.js";
 // Toolkit
 export { deriveToolkit } from "./toolkit.js";
 
-// Profile filtering (for agents)
+// Profile derivation
 export {
   getPositiveTrackCapabilities,
-  filterHumanOnlySkills,
-  filterByHighestLevel,
-  filterSkillsForAgent,
-  sortByLevelDescending,
-  sortByMaturityDescending,
   prepareBaseProfile,
-  AGENT_PROFILE_OPTIONS,
   prepareAgentProfile,
 } from "./profile.js";
+
+// Policies - re-export key items for convenience
+export {
+  // Thresholds
+  THRESHOLD_MATCH_STRONG,
+  THRESHOLD_MATCH_GOOD,
+  THRESHOLD_MATCH_STRETCH,
+  THRESHOLD_MATCH_ASPIRATIONAL,
+  SCORE_GAP,
+  WEIGHT_SKILL_TYPE,
+  WEIGHT_CAPABILITY_BOOST,
+  // Interview thresholds
+  DEFAULT_INTERVIEW_QUESTION_MINUTES,
+  DEFAULT_DECOMPOSITION_QUESTION_MINUTES,
+  DEFAULT_SIMULATION_QUESTION_MINUTES,
+  TOLERANCE_INTERVIEW_BUDGET_MINUTES,
+  WEIGHT_CAPABILITY_DECOMP_DELIVERY,
+  WEIGHT_CAPABILITY_DECOMP_SCALE,
+  WEIGHT_CAPABILITY_DECOMP_RELIABILITY,
+  WEIGHT_FOCUS_BOOST,
+  // Senior grade
+  THRESHOLD_SENIOR_GRADE,
+  // Assessment weights
+  WEIGHT_ASSESSMENT_SKILL_DEFAULT,
+  WEIGHT_ASSESSMENT_BEHAVIOUR_DEFAULT,
+  WEIGHT_SENIOR_BASE,
+  WEIGHT_SENIOR_EXPECTATIONS,
+  // Match limits
+  LIMIT_PRIORITY_GAPS,
+  WEIGHT_SAME_TRACK_BONUS,
+  RANGE_GRADE_OFFSET,
+  RANGE_READY_GRADE_OFFSET,
+  // Driver coverage
+  THRESHOLD_DRIVER_SKILL_LEVEL,
+  THRESHOLD_DRIVER_BEHAVIOUR_MATURITY,
+  // Agent limits
+  LIMIT_AGENT_PROFILE_SKILLS,
+  LIMIT_AGENT_WORKING_STYLES,
+  // Predicates
+  isHumanOnly,
+  isAgentEligible,
+  isPrimary,
+  isSecondary,
+  isBroad,
+  isTrack,
+  isCore,
+  isSupporting,
+  hasMinLevel,
+  allOf,
+  anyOf,
+  not,
+  // Filters
+  filterHighestLevel,
+  filterAboveAwareness,
+  applyFilters,
+  composeFilters,
+  // Orderings
+  ORDER_SKILL_TYPE,
+  ORDER_STAGE,
+  ORDER_AGENT_STAGE,
+  CHECKLIST_STAGE_MAP,
+  compareByLevelDesc,
+  compareByType,
+  compareBySkillPriority,
+  compareByMaturityDesc,
+  compareByBehaviourPriority,
+  // Composed policies
+  filterAgentSkills,
+  filterToolkitSkills,
+  focusAgentSkills,
+  sortAgentSkills,
+  sortAgentBehaviours,
+  prepareAgentSkillMatrix,
+  prepareAgentBehaviourProfile,
+} from "./policies/index.js";