@forwardimpact/model 0.7.1 → 0.8.0

package/package.json

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

package/src/agent.js

@@ -26,7 +26,7 @@ import {
   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";
 
@@ -269,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: {
@@ -433,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];
@@ -445,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(
@@ -560,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,

package/src/checklist.js

@@ -1,14 +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
  */
 
-import { CHECKLIST_STAGE_MAP } from "./policies/orderings.js";
-
 /**
  * Derive checklist items for a specific stage
  * Returns skills grouped by capability with their ready criteria
@@ -26,11 +24,6 @@ export function deriveChecklist({
   skills,
   capabilities,
 }) {
-  const targetStage = CHECKLIST_STAGE_MAP[stageId];
-  if (!targetStage) {
-    return [];
-  }
-
   // Build skill lookup
   const skillById = new Map(skills.map((s) => [s.id, s]));
 
@@ -45,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;
     }
 
@@ -66,7 +63,7 @@ export function deriveChecklist({
         name: capability.name,
         emojiIcon: capability.emojiIcon,
       },
-      items: stageData.ready,
+      items: stageData.confirmChecklist,
     });
   }
 

package/src/index.js

@@ -177,9 +177,8 @@ export {
   composeFilters,
   // Orderings
   ORDER_SKILL_TYPE,
-  ORDER_STAGE,
-  ORDER_AGENT_STAGE,
-  CHECKLIST_STAGE_MAP,
+  getStageOrder,
+  compareByStageOrder,
   compareByLevelDesc,
   compareByType,
   compareBySkillPriority,

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/policies/index.js

@@ -117,9 +117,9 @@ export {
 export {
   // Canonical orders
   ORDER_SKILL_TYPE,
-  ORDER_STAGE,
-  ORDER_AGENT_STAGE,
-  CHECKLIST_STAGE_MAP,
+  // Data-driven stage ordering
+  getStageOrder,
+  compareByStageOrder,
   // Skill comparators
   compareByLevelDesc,
   compareByLevelAsc,

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,27 +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"];
-
-/**
- * Agent stage ordering (subset used for agent generation)
- */
-export const ORDER_AGENT_STAGE = ["plan", "code", "review"];
+// =============================================================================
+// Stage Comparators
+// =============================================================================
 
 /**
- * Stage-to-handoff mapping for checklist derivation
+ * 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.
  *
- * Maps stage IDs to the stage whose `.ready` criteria should be shown
- * before leaving that stage.
+ * @param {Object[]} stages - Loaded stages array from stages.yaml
+ * @returns {(a: Object, b: Object) => number} Comparator function
  */
-export const CHECKLIST_STAGE_MAP = {
-  plan: "plan",
-  code: "code",
-  review: "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