@forwardimpact/model 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/model",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Derivation engine for roles, skills, and AI agent profiles",
   "license": "Apache-2.0",
   "repository": {

package/src/agent.js

@@ -24,8 +24,10 @@ import {
   filterAgentSkills,
   sortAgentSkills,
   sortAgentBehaviours,
+  focusAgentSkills,
 } from "./policies/composed.js";
-import { ORDER_AGENT_STAGE } from "./policies/orderings.js";
+import { compareByStageOrder } from "./policies/orderings.js";
+import { LIMIT_AGENT_WORKING_STYLES } from "./policies/thresholds.js";
 import { SkillLevel } from "@forwardimpact/schema/levels";
 
 /**
@@ -194,7 +196,7 @@ function findAgentBehaviour(agentBehaviours, id) {
 function buildWorkingStyleFromBehaviours(
   derivedBehaviours,
   agentBehaviours,
-  topN = 3,
+  topN = LIMIT_AGENT_WORKING_STYLES,
 ) {
   const entries = [];
 
@@ -267,18 +269,15 @@ export function generateSkillMarkdown(skillData, stages) {
         stageName,
         nextStageName,
         focus: stageData.focus,
-        activities: stageData.activities || [],
-        ready: stageData.ready || [],
+        readChecklist: stageData.readChecklist || [],
+        confirmChecklist: stageData.confirmChecklist || [],
       };
     },
   );
 
-  // Sort stages using canonical ordering from policies
-  stagesArray.sort(
-    (a, b) =>
-      ORDER_AGENT_STAGE.indexOf(a.stageId) -
-      ORDER_AGENT_STAGE.indexOf(b.stageId),
-  );
+  // Sort stages using canonical ordering from loaded stage data
+  const stageComparator = compareByStageOrder(stages);
+  stagesArray.sort(stageComparator);
 
   return {
     frontmatter: {
@@ -431,9 +430,9 @@ export function deriveHandoffs({ stage, discipline, track, stages }) {
   const baseName = `${abbrev}-${toKebabCase(track.id)}`;
 
   return stage.handoffs.map((handoff) => {
-    // Find the target stage to get its entry criteria
+    // Find the target stage to get its confirmChecklist
     const targetStage = stages.find((s) => s.id === handoff.targetStage);
-    const entryCriteria = targetStage?.entryCriteria || [];
+    const confirmChecklist = targetStage?.confirmChecklist || [];
 
     // Build rich prompt - formatted for single-line display
     const promptParts = [handoff.prompt];
@@ -443,9 +442,9 @@ export function deriveHandoffs({ stage, discipline, track, stages }) {
       `Summarize what was completed in the ${stage.name} stage.`,
     );
 
-    // Add entry criteria from target stage with inline numbered list
-    if (entryCriteria.length > 0) {
-      const formattedCriteria = entryCriteria
+    // Add confirm checklist from target stage with inline numbered list
+    if (confirmChecklist.length > 0) {
+      const formattedCriteria = confirmChecklist
         .map((item, index) => `(${index + 1}) ${item}`)
         .join(", ");
       promptParts.push(
@@ -518,7 +517,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);
@@ -538,7 +537,6 @@ function buildStageProfileBodyData({
   const workingStyles = buildWorkingStyleFromBehaviours(
     derivedBehaviours,
     agentBehaviours,
-    3,
   );
 
   // Constraints (stage + discipline + track)
@@ -559,12 +557,15 @@ function buildStageProfileBodyData({
   return {
     title: `${name} - ${stageName} Agent`,
     stageDescription: stage.description,
+    stageId: stage.id,
+    stageName,
+    isOnboard: stage.id === "onboard",
     identity: identity.trim(),
     priority: priority ? priority.trim() : null,
     skillIndex,
     roleContext,
     workingStyles,
-    beforeHandoff: checklist || [],
+    confirmChecklist: checklist || [],
     constraints,
     agentIndex: filteredAgentIndex,
     hasAgentIndex: filteredAgentIndex.length > 0,
@@ -602,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,
@@ -624,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,
     });
@@ -640,7 +644,7 @@ export function deriveStageAgent({
     stage,
     discipline,
     track,
-    derivedSkills,
+    derivedSkills: focusedSkills,
     derivedBehaviours,
     handoffs,
     constraints: [

package/src/checklist.js

@@ -1,22 +1,12 @@
 /**
  * Checklist Derivation
  *
- * Checklists are derived from skills with agent.stages.{stage}.ready criteria.
+ * Checklists are derived from skills with agent.stages.{stage}.confirmChecklist criteria.
  * Each skill defines its own readiness criteria for stage transitions.
  *
- * Checklist = Stage × Skill Matrix × Skill Ready Criteria
+ * Checklist = Stage × Skill Matrix × Skill Confirm Checklist
  */
 
-/**
- * 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)
-};
-
 /**
  * Derive checklist items for a specific stage
  * Returns skills grouped by capability with their ready criteria
@@ -34,11 +24,6 @@ export function deriveChecklist({
   skills,
   capabilities,
 }) {
-  const targetStage = STAGE_TO_HANDOFF[stageId];
-  if (!targetStage) {
-    return [];
-  }
-
   // Build skill lookup
   const skillById = new Map(skills.map((s) => [s.id, s]));
 
@@ -53,8 +38,12 @@ export function deriveChecklist({
       continue;
     }
 
-    const stageData = skill.agent.stages[targetStage];
-    if (!stageData || !stageData.ready || stageData.ready.length === 0) {
+    const stageData = skill.agent.stages[stageId];
+    if (
+      !stageData ||
+      !stageData.confirmChecklist ||
+      stageData.confirmChecklist.length === 0
+    ) {
       continue;
     }
 
@@ -74,7 +63,7 @@ export function deriveChecklist({
         name: capability.name,
         emojiIcon: capability.emojiIcon,
       },
-      items: stageData.ready,
+      items: stageData.confirmChecklist,
     });
   }
 

package/src/derivation.js

@@ -7,8 +7,6 @@
 
 import {
   SkillType,
-  SkillLevel,
-  BehaviourMaturity,
   SKILL_LEVEL_ORDER,
   getSkillLevelIndex,
   getBehaviourMaturityIndex,
@@ -19,6 +17,11 @@ import {
 
 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
@@ -595,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);
@@ -611,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) {
@@ -678,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/src/index.js

@@ -130,6 +130,33 @@ export {
   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,
@@ -150,8 +177,8 @@ export {
   composeFilters,
   // Orderings
   ORDER_SKILL_TYPE,
-  ORDER_STAGE,
-  ORDER_AGENT_STAGE,
+  getStageOrder,
+  compareByStageOrder,
   compareByLevelDesc,
   compareByType,
   compareBySkillPriority,
@@ -160,6 +187,7 @@ export {
   // Composed policies
   filterAgentSkills,
   filterToolkitSkills,
+  focusAgentSkills,
   sortAgentSkills,
   sortAgentBehaviours,
   prepareAgentSkillMatrix,

package/src/interview.js

@@ -20,22 +20,17 @@ import {
   WEIGHT_SKILL_LEVEL,
   WEIGHT_BELOW_LEVEL_PENALTY,
   RATIO_SKILL_BEHAVIOUR,
+  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,
 } from "./policies/thresholds.js";
 
-/**
- * Default question time estimate if not specified
- */
-const DEFAULT_QUESTION_MINUTES = 5;
-
-/**
- * Default decomposition question time estimate
- */
-const DEFAULT_DECOMPOSITION_MINUTES = 15;
-
-/**
- * Default stakeholder simulation question time estimate
- */
-const DEFAULT_SIMULATION_MINUTES = 20;
+import { compareByMaturityDesc } from "./policies/orderings.js";
 
 /**
  * Get questions from the question bank for a specific skill and level
@@ -136,7 +131,7 @@ function calculateSkillPriority(skill, includeBelowLevel = false) {
     priority += WEIGHT_CAPABILITY_BOOST.ai;
   }
 
-  // Delivery skills are core technical skills
+  // Delivery skills get a core technical boost
   if (skill.capability === Capability.DELIVERY) {
     priority += WEIGHT_CAPABILITY_BOOST.delivery;
   }
@@ -178,11 +173,11 @@ function calculateCapabilityPriority(capabilityId, levelIndex) {
 
   // Delivery and scale capabilities are typically more important for decomposition
   if (capabilityId === Capability.DELIVERY) {
-    priority += 10;
+    priority += WEIGHT_CAPABILITY_DECOMP_DELIVERY;
   } else if (capabilityId === Capability.SCALE) {
-    priority += 8;
+    priority += WEIGHT_CAPABILITY_DECOMP_SCALE;
   } else if (capabilityId === Capability.RELIABILITY) {
-    priority += 6;
+    priority += WEIGHT_CAPABILITY_DECOMP_RELIABILITY;
   }
 
   // Higher level = higher priority
@@ -339,8 +334,11 @@ export function deriveInterviewQuestions({ job, questionBank, options = {} }) {
   for (const q of allSkillQuestions) {
     if (selectedSkillIds.has(q.targetId)) continue; // Skip if we already have this skill
     const questionTime =
-      q.question.expectedDurationMinutes || DEFAULT_QUESTION_MINUTES;
-    if (skillMinutes + questionTime <= skillTimeBudget + 5) {
+      q.question.expectedDurationMinutes || DEFAULT_INTERVIEW_QUESTION_MINUTES;
+    if (
+      skillMinutes + questionTime <=
+      skillTimeBudget + TOLERANCE_INTERVIEW_BUDGET_MINUTES
+    ) {
       selectedQuestions.push(q);
       selectedSkillIds.add(q.targetId);
       coveredSkills.add(q.targetId);
@@ -352,8 +350,11 @@ export function deriveInterviewQuestions({ job, questionBank, options = {} }) {
   for (const q of allSkillQuestions) {
     if (selectedQuestions.includes(q)) continue; // Skip already selected
     const questionTime =
-      q.question.expectedDurationMinutes || DEFAULT_QUESTION_MINUTES;
-    if (skillMinutes + questionTime <= skillTimeBudget + 5) {
+      q.question.expectedDurationMinutes || DEFAULT_INTERVIEW_QUESTION_MINUTES;
+    if (
+      skillMinutes + questionTime <=
+      skillTimeBudget + TOLERANCE_INTERVIEW_BUDGET_MINUTES
+    ) {
       selectedQuestions.push(q);
       coveredSkills.add(q.targetId);
       skillMinutes += questionTime;
@@ -368,8 +369,11 @@ export function deriveInterviewQuestions({ job, questionBank, options = {} }) {
   for (const q of allBehaviourQuestions) {
     if (selectedBehaviourIds.has(q.targetId)) continue; // Skip if we already have this behaviour
     const questionTime =
-      q.question.expectedDurationMinutes || DEFAULT_QUESTION_MINUTES;
-    if (behaviourMinutes + questionTime <= behaviourTimeBudget + 5) {
+      q.question.expectedDurationMinutes || DEFAULT_INTERVIEW_QUESTION_MINUTES;
+    if (
+      behaviourMinutes + questionTime <=
+      behaviourTimeBudget + TOLERANCE_INTERVIEW_BUDGET_MINUTES
+    ) {
       selectedQuestions.push(q);
       selectedBehaviourIds.add(q.targetId);
       coveredBehaviours.add(q.targetId);
@@ -381,8 +385,11 @@ export function deriveInterviewQuestions({ job, questionBank, options = {} }) {
   for (const q of allBehaviourQuestions) {
     if (selectedQuestions.includes(q)) continue; // Skip already selected
     const questionTime =
-      q.question.expectedDurationMinutes || DEFAULT_QUESTION_MINUTES;
-    if (behaviourMinutes + questionTime <= behaviourTimeBudget + 5) {
+      q.question.expectedDurationMinutes || DEFAULT_INTERVIEW_QUESTION_MINUTES;
+    if (
+      behaviourMinutes + questionTime <=
+      behaviourTimeBudget + TOLERANCE_INTERVIEW_BUDGET_MINUTES
+    ) {
       selectedQuestions.push(q);
       coveredBehaviours.add(q.targetId);
       behaviourMinutes += questionTime;
@@ -395,7 +402,9 @@ export function deriveInterviewQuestions({ job, questionBank, options = {} }) {
   // Calculate total time
   const expectedDurationMinutes = selectedQuestions.reduce(
     (sum, q) =>
-      sum + (q.question.expectedDurationMinutes || DEFAULT_QUESTION_MINUTES),
+      sum +
+      (q.question.expectedDurationMinutes ||
+        DEFAULT_INTERVIEW_QUESTION_MINUTES),
     0,
   );
 
@@ -469,10 +478,14 @@ export function deriveShortInterview({
     }
 
     const questionTime =
-      nextQuestion.question.expectedDurationMinutes || DEFAULT_QUESTION_MINUTES;
+      nextQuestion.question.expectedDurationMinutes ||
+      DEFAULT_INTERVIEW_QUESTION_MINUTES;
 
     // Don't exceed budget by too much
-    if (totalMinutes + questionTime > targetMinutes + 5) {
+    if (
+      totalMinutes + questionTime >
+      targetMinutes + TOLERANCE_INTERVIEW_BUDGET_MINUTES
+    ) {
       break;
     }
 
@@ -549,7 +562,9 @@ export function deriveBehaviourQuestions({
   // Calculate total time
   const expectedDurationMinutes = interviewQuestions.reduce(
     (sum, q) =>
-      sum + (q.question.expectedDurationMinutes || DEFAULT_QUESTION_MINUTES),
+      sum +
+      (q.question.expectedDurationMinutes ||
+        DEFAULT_INTERVIEW_QUESTION_MINUTES),
     0,
   );
 
@@ -603,7 +618,7 @@ export function deriveFocusedInterview({
         targetName: skill.skillName,
         targetType: "skill",
         targetLevel: skill.level,
-        priority: calculateSkillPriority(skill) + 10, // Boost for focus
+        priority: calculateSkillPriority(skill) + WEIGHT_FOCUS_BOOST,
       });
       coveredSkills.add(skill.skillId);
     }
@@ -627,7 +642,7 @@ export function deriveFocusedInterview({
         targetName: behaviour.behaviourName,
         targetType: "behaviour",
         targetLevel: behaviour.maturity,
-        priority: calculateBehaviourPriority(behaviour) + 10, // Boost for focus
+        priority: calculateBehaviourPriority(behaviour) + WEIGHT_FOCUS_BOOST,
       });
       coveredBehaviours.add(behaviour.behaviourId);
     }
@@ -638,7 +653,9 @@ export function deriveFocusedInterview({
 
   const expectedDurationMinutes = interviewQuestions.reduce(
     (sum, q) =>
-      sum + (q.question.expectedDurationMinutes || DEFAULT_QUESTION_MINUTES),
+      sum +
+      (q.question.expectedDurationMinutes ||
+        DEFAULT_INTERVIEW_QUESTION_MINUTES),
     0,
   );
 
@@ -734,8 +751,11 @@ export function deriveMissionFitInterview({
   for (const q of allSkillQuestions) {
     if (selectedSkillIds.has(q.targetId)) continue;
     const questionTime =
-      q.question.expectedDurationMinutes || DEFAULT_QUESTION_MINUTES;
-    if (totalMinutes + questionTime <= targetMinutes + 5) {
+      q.question.expectedDurationMinutes || DEFAULT_INTERVIEW_QUESTION_MINUTES;
+    if (
+      totalMinutes + questionTime <=
+      targetMinutes + TOLERANCE_INTERVIEW_BUDGET_MINUTES
+    ) {
       selectedQuestions.push(q);
       selectedSkillIds.add(q.targetId);
       coveredSkills.add(q.targetId);
@@ -747,8 +767,11 @@ export function deriveMissionFitInterview({
   for (const q of allSkillQuestions) {
     if (selectedQuestions.includes(q)) continue;
     const questionTime =
-      q.question.expectedDurationMinutes || DEFAULT_QUESTION_MINUTES;
-    if (totalMinutes + questionTime <= targetMinutes + 5) {
+      q.question.expectedDurationMinutes || DEFAULT_INTERVIEW_QUESTION_MINUTES;
+    if (
+      totalMinutes + questionTime <=
+      targetMinutes + TOLERANCE_INTERVIEW_BUDGET_MINUTES
+    ) {
       selectedQuestions.push(q);
       coveredSkills.add(q.targetId);
       totalMinutes += questionTime;
@@ -854,8 +877,12 @@ export function deriveDecompositionInterview({
   for (const q of allCapabilityQuestions) {
     if (selectedCapabilityIds.has(q.targetId)) continue;
     const questionTime =
-      q.question.expectedDurationMinutes || DEFAULT_DECOMPOSITION_MINUTES;
-    if (totalMinutes + questionTime <= targetMinutes + 5) {
+      q.question.expectedDurationMinutes ||
+      DEFAULT_DECOMPOSITION_QUESTION_MINUTES;
+    if (
+      totalMinutes + questionTime <=
+      targetMinutes + TOLERANCE_INTERVIEW_BUDGET_MINUTES
+    ) {
       selectedQuestions.push(q);
       selectedCapabilityIds.add(q.targetId);
       coveredCapabilities.add(q.targetId);
@@ -867,8 +894,12 @@ export function deriveDecompositionInterview({
   for (const q of allCapabilityQuestions) {
     if (selectedQuestions.includes(q)) continue;
     const questionTime =
-      q.question.expectedDurationMinutes || DEFAULT_DECOMPOSITION_MINUTES;
-    if (totalMinutes + questionTime <= targetMinutes + 5) {
+      q.question.expectedDurationMinutes ||
+      DEFAULT_DECOMPOSITION_QUESTION_MINUTES;
+    if (
+      totalMinutes + questionTime <=
+      targetMinutes + TOLERANCE_INTERVIEW_BUDGET_MINUTES
+    ) {
       selectedQuestions.push(q);
       coveredCapabilities.add(q.targetId);
       totalMinutes += questionTime;
@@ -915,9 +946,7 @@ export function deriveStakeholderInterview({
 
   // Sort behaviours by maturity (highest first) to prioritize the most emphasized
   const sortedBehaviours = [...job.behaviourProfile].sort(
-    (a, b) =>
-      getBehaviourMaturityIndex(b.maturity) -
-      getBehaviourMaturityIndex(a.maturity),
+    compareByMaturityDesc,
   );
 
   // Select one question per behaviour, highest maturity first, within budget
@@ -940,8 +969,12 @@ export function deriveStakeholderInterview({
     if (!question) continue;
 
     const questionTime =
-      question.expectedDurationMinutes || DEFAULT_SIMULATION_MINUTES;
-    if (totalMinutes + questionTime > targetMinutes + 5) break;
+      question.expectedDurationMinutes || DEFAULT_SIMULATION_QUESTION_MINUTES;
+    if (
+      totalMinutes + questionTime >
+      targetMinutes + TOLERANCE_INTERVIEW_BUDGET_MINUTES
+    )
+      break;
 
     selectedQuestions.push({
       question,

package/src/job.js

@@ -14,6 +14,7 @@ import {
 import { deriveChecklist } from "./checklist.js";
 import { deriveToolkit } from "./toolkit.js";
 import { getOrCreateJob } from "./job-cache.js";
+import { getStageOrder } from "@forwardimpact/schema/levels";
 
 /**
  * @typedef {Object} JobDetailView
@@ -43,6 +44,7 @@ import { getOrCreateJob } from "./job-cache.js";
  * @param {Array} params.behaviours
  * @param {Array} params.drivers
  * @param {Array} [params.capabilities]
+ * @param {Array} [params.stages] - Loaded stages for checklist derivation
  * @returns {JobDetailView|null}
  */
 export function prepareJobDetail({
@@ -53,6 +55,7 @@ export function prepareJobDetail({
   behaviours,
   drivers,
   capabilities,
+  stages,
 }) {
   // Track is optional (null = generalist)
   if (!discipline || !grade) return null;
@@ -73,10 +76,10 @@ export function prepareJobDetail({
     drivers,
   });
 
-  // Derive checklists for each stage
+  // Derive checklists for each stage from loaded stage data
   const checklists = {};
-  if (capabilities) {
-    const stageIds = ["plan", "code"];
+  if (capabilities && stages) {
+    const stageIds = getStageOrder(stages);
     for (const stageId of stageIds) {
       checklists[stageId] = deriveChecklist({
         stageId,

package/src/matching.js

@@ -25,6 +25,14 @@ import {
   WEIGHT_DEV_TYPE_SECONDARY,
   WEIGHT_DEV_TYPE_BROAD,
   WEIGHT_DEV_AI_BOOST,
+  WEIGHT_ASSESSMENT_SKILL_DEFAULT,
+  WEIGHT_ASSESSMENT_BEHAVIOUR_DEFAULT,
+  WEIGHT_SENIOR_BASE,
+  WEIGHT_SENIOR_EXPECTATIONS,
+  LIMIT_PRIORITY_GAPS,
+  WEIGHT_SAME_TRACK_BONUS,
+  RANGE_GRADE_OFFSET,
+  RANGE_READY_GRADE_OFFSET,
 } from "./policies/thresholds.js";
 
 // ============================================================================
@@ -285,8 +293,12 @@ function calculateExpectationsScore(selfExpectations, jobExpectations) {
  */
 export function calculateJobMatch(selfAssessment, job) {
   // Get weights from track or use defaults (track may be null for trackless jobs)
-  const skillWeight = job.track?.assessmentWeights?.skillWeight ?? 0.5;
-  const behaviourWeight = job.track?.assessmentWeights?.behaviourWeight ?? 0.5;
+  const skillWeight =
+    job.track?.assessmentWeights?.skillWeight ??
+    WEIGHT_ASSESSMENT_SKILL_DEFAULT;
+  const behaviourWeight =
+    job.track?.assessmentWeights?.behaviourWeight ??
+    WEIGHT_ASSESSMENT_BEHAVIOUR_DEFAULT;
 
   // Calculate skill score
   const skillResult = calculateSkillScore(
@@ -312,7 +324,9 @@ export function calculateJobMatch(selfAssessment, job) {
       job.expectations,
     );
     // Add up to 10% bonus for expectations match
-    overallScore = overallScore * 0.9 + expectationsScore * 0.1;
+    overallScore =
+      overallScore * WEIGHT_SENIOR_BASE +
+      expectationsScore * WEIGHT_SENIOR_EXPECTATIONS;
   }
 
   // Combine all gaps
@@ -324,8 +338,8 @@ export function calculateJobMatch(selfAssessment, job) {
   // Classify match into tier
   const tier = classifyMatch(overallScore);
 
-  // Identify top priority gaps (top 3 by gap size)
-  const priorityGaps = allGaps.slice(0, 3);
+  // Identify top priority gaps
+  const priorityGaps = allGaps.slice(0, LIMIT_PRIORITY_GAPS);
 
   const result = {
     overallScore,
@@ -544,11 +558,11 @@ export function findRealisticMatches({
     skills,
   });
 
-  // Determine grade range (±1 level)
+  // Determine grade range (±RANGE_GRADE_OFFSET levels)
   const bestFitLevel = estimatedGrade.grade.ordinalRank;
   const gradeRange = {
-    min: bestFitLevel - 1,
-    max: bestFitLevel + 1,
+    min: bestFitLevel - RANGE_GRADE_OFFSET,
+    max: bestFitLevel + RANGE_GRADE_OFFSET,
   };
 
   // Find all matches
@@ -608,11 +622,11 @@ export function findRealisticMatches({
   }
 
   // Filter each tier to only show grades within reasonable range of highest match
-  // For Strong/Good matches: show up to 2 levels below highest match
+  // For Strong/Good matches: show up to RANGE_READY_GRADE_OFFSET levels below highest match
   // For Stretch/Aspirational: show only at or above highest match (growth opportunities)
   if (highestMatchedLevel > 0) {
-    const minLevelForReady = highestMatchedLevel - 2; // Show some consolidation options
-    const minLevelForStretch = highestMatchedLevel; // Stretch roles should be at or above current
+    const minLevelForReady = highestMatchedLevel - RANGE_READY_GRADE_OFFSET;
+    const minLevelForStretch = highestMatchedLevel;
 
     matchesByTier[1] = matchesByTier[1].filter(
       (m) => m.job.grade.ordinalRank >= minLevelForReady,
@@ -799,8 +813,8 @@ export function findNextStepJob({
 
       if (job) {
         const analysis = calculateJobMatch(selfAssessment, job);
-        // Boost score for same track
-        const trackBonus = track.id === currentJob.track.id ? 0.1 : 0;
+        const trackBonus =
+          track.id === currentJob.track.id ? WEIGHT_SAME_TRACK_BONUS : 0;
         candidates.push({
           job,
           analysis,

package/src/policies/composed.js

@@ -13,7 +13,9 @@ import {
   compareByLevelDesc,
   compareByMaturityDesc,
   compareByTypeAndName,
+  compareBySkillPriority,
 } from "./orderings.js";
+import { LIMIT_AGENT_PROFILE_SKILLS } from "./thresholds.js";
 
 // =============================================================================
 // Agent Skill Policies
@@ -78,6 +80,28 @@ export function sortJobSkills(skills) {
   return [...skills].sort(compareByTypeAndName);
 }
 
+// =============================================================================
+// Agent Profile Focus Policy
+// =============================================================================
+
+/**
+ * Select the focused subset of agent skills for profile body
+ *
+ * Agent profiles include a limited skill index to avoid context bloat.
+ * Skills are ranked by priority (level desc, type asc, name asc) and
+ * the top N are returned, where N = LIMIT_AGENT_PROFILE_SKILLS.
+ *
+ * All skills are still exported as SKILL.md files and listed via --skills.
+ *
+ * @param {Array} skills - Agent-eligible skills (already filtered and sorted)
+ * @returns {Array} Top N skills by priority
+ */
+export function focusAgentSkills(skills) {
+  return [...skills]
+    .sort(compareBySkillPriority)
+    .slice(0, LIMIT_AGENT_PROFILE_SKILLS);
+}
+
 // =============================================================================
 // Combined Filter + Sort Policies
 // =============================================================================

package/src/policies/index.js

@@ -45,6 +45,35 @@ export {
   WEIGHT_DEV_TYPE_SECONDARY,
   WEIGHT_DEV_TYPE_BROAD,
   WEIGHT_DEV_AI_BOOST,
+  // Agent profile limits
+  LIMIT_AGENT_PROFILE_SKILLS,
+  LIMIT_AGENT_WORKING_STYLES,
+  // Interview time defaults
+  DEFAULT_INTERVIEW_QUESTION_MINUTES,
+  DEFAULT_DECOMPOSITION_QUESTION_MINUTES,
+  DEFAULT_SIMULATION_QUESTION_MINUTES,
+  TOLERANCE_INTERVIEW_BUDGET_MINUTES,
+  // Decomposition capability weights
+  WEIGHT_CAPABILITY_DECOMP_DELIVERY,
+  WEIGHT_CAPABILITY_DECOMP_SCALE,
+  WEIGHT_CAPABILITY_DECOMP_RELIABILITY,
+  WEIGHT_FOCUS_BOOST,
+  // Senior grade threshold
+  THRESHOLD_SENIOR_GRADE,
+  // Assessment weights
+  WEIGHT_ASSESSMENT_SKILL_DEFAULT,
+  WEIGHT_ASSESSMENT_BEHAVIOUR_DEFAULT,
+  WEIGHT_SENIOR_BASE,
+  WEIGHT_SENIOR_EXPECTATIONS,
+  // Match result limits
+  LIMIT_PRIORITY_GAPS,
+  WEIGHT_SAME_TRACK_BONUS,
+  // Realistic match filtering
+  RANGE_GRADE_OFFSET,
+  RANGE_READY_GRADE_OFFSET,
+  // Driver coverage thresholds
+  THRESHOLD_DRIVER_SKILL_LEVEL,
+  THRESHOLD_DRIVER_BEHAVIOUR_MATURITY,
 } from "./thresholds.js";
 
 // Predicates
@@ -88,8 +117,9 @@ export {
 export {
   // Canonical orders
   ORDER_SKILL_TYPE,
-  ORDER_STAGE,
-  ORDER_AGENT_STAGE,
+  // Data-driven stage ordering
+  getStageOrder,
+  compareByStageOrder,
   // Skill comparators
   compareByLevelDesc,
   compareByLevelAsc,
@@ -118,6 +148,8 @@ export {
   // Agent skill filtering
   filterAgentSkills,
   filterToolkitSkills,
+  // Agent profile focus
+  focusAgentSkills,
   // Sorting
   sortAgentSkills,
   sortAgentBehaviours,

package/src/policies/orderings.js

@@ -12,8 +12,12 @@ import {
   getSkillLevelIndex,
   getBehaviourMaturityIndex,
   getCapabilityOrder,
+  getStageOrder,
 } from "@forwardimpact/schema/levels";
 
+// Re-export getStageOrder for consumers
+export { getStageOrder };
+
 // =============================================================================
 // Canonical Orderings
 // =============================================================================
@@ -24,15 +28,27 @@ import {
  */
 export const ORDER_SKILL_TYPE = ["primary", "secondary", "broad", "track"];
 
-/**
- * Engineering lifecycle stages in execution order
- */
-export const ORDER_STAGE = ["specify", "plan", "code", "review", "deploy"];
+// =============================================================================
+// Stage Comparators
+// =============================================================================
 
 /**
- * Agent stage ordering (subset used for agent generation)
+ * Create a comparator for sorting by stage lifecycle order
+ *
+ * The returned comparator uses the canonical order from loaded stage data,
+ * making the ordering data-driven rather than hardcoded.
+ *
+ * @param {Object[]} stages - Loaded stages array from stages.yaml
+ * @returns {(a: Object, b: Object) => number} Comparator function
  */
-export const ORDER_AGENT_STAGE = ["plan", "code", "review"];
+export function compareByStageOrder(stages) {
+  const order = getStageOrder(stages);
+  return (a, b) => {
+    const stageA = a.stageId || a.id || "";
+    const stageB = b.stageId || b.id || "";
+    return order.indexOf(stageA) - order.indexOf(stageB);
+  };
+}
 
 // =============================================================================
 // Skill Comparators

package/src/policies/thresholds.js

@@ -158,3 +158,160 @@ export const WEIGHT_DEV_TYPE_BROAD = 1;
  * 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

@@ -4,13 +4,10 @@
  * Shared functions for deriving skill and behaviour profiles for both
  * human jobs and AI agents.
  *
- * - prepareBaseProfile() - full derivation with configurable options
- * - prepareAgentProfile() - convenience wrapper with agent-specific filtering
+ * - prepareBaseProfile() - core derivation (skills, behaviours, responsibilities)
+ * - prepareAgentProfile() - agent-specific derivation using composed policies
  *
- * @see policies/predicates.js - Entry-level predicate functions
- * @see policies/filters.js - Matrix-level filter functions
- * @see policies/orderings.js - Comparator functions
- * @see policies/composed.js - Composed policies
+ * @see policies/composed.js - Agent filtering and sorting policies
  */
 
 import {
@@ -20,11 +17,9 @@ import {
 } from "./derivation.js";
 
 import {
-  isAgentEligible,
-  filterHighestLevel,
-  compareByLevelDesc,
-  compareByMaturityDesc,
-} from "./policies/index.js";
+  prepareAgentSkillMatrix,
+  prepareAgentBehaviourProfile,
+} from "./policies/composed.js";
 
 // =============================================================================
 // Utility Functions
@@ -47,14 +42,6 @@ export function getPositiveTrackCapabilities(track) {
 // Profile Derivation
 // =============================================================================
 
-/**
- * @typedef {Object} ProfileOptions
- * @property {boolean} [excludeHumanOnly=false] - Filter out human-only skills
- * @property {boolean} [keepHighestLevelOnly=false] - Keep only skills at the highest derived level
- * @property {boolean} [sortByLevel=false] - Sort skills by level descending
- * @property {boolean} [sortByMaturity=false] - Sort behaviours by maturity descending
- */
-
 /**
  * @typedef {Object} BaseProfile
  * @property {Array} skillMatrix - Derived skill matrix
@@ -66,13 +53,14 @@ export function getPositiveTrackCapabilities(track) {
  */
 
 /**
- * Prepare a base profile shared by jobs and agents
+ * Prepare a base profile with raw derivation
  *
- * This is the unified entry point for profile derivation. Both human jobs
- * and AI agents use this function, with different options:
+ * 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: No filtering, default sorting by type
- * - AI agents: Use prepareAgentProfile() for agent-specific filtering
+ * - 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
@@ -81,7 +69,6 @@ export function getPositiveTrackCapabilities(track) {
  * @param {Array} params.skills - All available skills
  * @param {Array} params.behaviours - All available behaviours
  * @param {Array} [params.capabilities] - Optional capabilities for responsibility derivation
- * @param {ProfileOptions} [params.options={}] - Filtering and sorting options
  * @returns {BaseProfile} The prepared profile
  */
 export function prepareBaseProfile({
@@ -91,40 +78,16 @@ export function prepareBaseProfile({
   skills,
   behaviours,
   capabilities,
-  options = {},
 }) {
-  const {
-    excludeHumanOnly = false,
-    keepHighestLevelOnly = false,
-    sortByLevel = false,
-    sortByMaturity = false,
-  } = options;
-
   // Core derivation
-  let skillMatrix = deriveSkillMatrix({ discipline, grade, track, skills });
-  let behaviourProfile = deriveBehaviourProfile({
+  const skillMatrix = deriveSkillMatrix({ discipline, grade, track, skills });
+  const behaviourProfile = deriveBehaviourProfile({
     discipline,
     grade,
     track,
     behaviours,
   });
 
-  // Apply skill filters using policy functions
-  if (excludeHumanOnly) {
-    skillMatrix = skillMatrix.filter(isAgentEligible);
-  }
-  if (keepHighestLevelOnly) {
-    skillMatrix = filterHighestLevel(skillMatrix);
-  }
-
-  // Apply sorting using policy comparators
-  if (sortByLevel) {
-    skillMatrix = [...skillMatrix].sort(compareByLevelDesc);
-  }
-  if (sortByMaturity) {
-    behaviourProfile = [...behaviourProfile].sort(compareByMaturityDesc);
-  }
-
   // Derive responsibilities if capabilities provided
   let derivedResponsibilities = [];
   if (capabilities && capabilities.length > 0) {
@@ -148,14 +111,14 @@ export function prepareBaseProfile({
 /**
  * Prepare a profile optimized for agent generation
  *
- * Applies agent-specific filtering and sorting:
+ * 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, without options
- * @returns {BaseProfile} The prepared profile
+ * @param {Object} params - Same as prepareBaseProfile
+ * @returns {BaseProfile} The prepared profile with agent policies applied
  */
 export function prepareAgentProfile({
   discipline,
@@ -165,18 +128,18 @@ export function prepareAgentProfile({
   behaviours,
   capabilities,
 }) {
-  return prepareBaseProfile({
+  const base = prepareBaseProfile({
     discipline,
     track,
     grade,
     skills,
     behaviours,
     capabilities,
-    options: {
-      excludeHumanOnly: true,
-      keepHighestLevelOnly: true,
-      sortByLevel: true,
-      sortByMaturity: true,
-    },
   });
+
+  return {
+    ...base,
+    skillMatrix: prepareAgentSkillMatrix(base.skillMatrix),
+    behaviourProfile: prepareAgentBehaviourProfile(base.behaviourProfile),
+  };
 }