@forwardimpact/pathway 0.1.0 → 0.2.0

package/app/model/derivation.js

@@ -85,7 +85,7 @@ export function findMaxBaseSkillLevel(grade) {
  *
  * @param {Object} params
  * @param {import('./levels.js').Discipline} params.discipline - The discipline
- * @param {import('./levels.js').Track} params.track - The track
+ * @param {import('./levels.js').Track} [params.track] - The track (optional)
  * @param {import('./levels.js').Grade} params.grade - The grade
  * @param {string} params.skillId - The skill ID
  * @param {import('./levels.js').Skill[]} params.skills - All available skills (for capability lookup)
@@ -94,7 +94,7 @@ export function findMaxBaseSkillLevel(grade) {
 export function deriveSkillLevel({
   discipline,
   grade,
-  track,
+  track = null,
   skillId,
   skills,
 }) {
@@ -107,8 +107,13 @@ export function deriveSkillLevel({
   const baseLevel = grade.baseSkillLevels[effectiveType];
   const baseIndex = getSkillLevelIndex(baseLevel);
 
-  // 3. Apply track modifier via capability lookup
-  const modifier = resolveSkillModifier(skillId, track.skillModifiers, skills);
+  // 3. Apply track modifier via capability lookup (if track provided)
+  const effectiveTrack = track || { skillModifiers: {} };
+  const modifier = resolveSkillModifier(
+    skillId,
+    effectiveTrack.skillModifiers,
+    skills,
+  );
 
   // Track-added skills require a positive modifier to be included
   if (!skillType && modifier <= 0) {
@@ -133,7 +138,7 @@ export function deriveSkillLevel({
  * Derive the behaviour maturity for a specific behaviour given discipline, track, and grade
  * @param {Object} params
  * @param {import('./levels.js').Discipline} params.discipline - The discipline
- * @param {import('./levels.js').Track} params.track - The track
+ * @param {import('./levels.js').Track} [params.track] - The track (optional)
  * @param {import('./levels.js').Grade} params.grade - The grade
  * @param {string} params.behaviourId - The behaviour ID
  * @returns {string} The derived maturity level
@@ -141,7 +146,7 @@ export function deriveSkillLevel({
 export function deriveBehaviourMaturity({
   discipline,
   grade,
-  track,
+  track = null,
   behaviourId,
 }) {
   // 1. Get base maturity from grade
@@ -150,7 +155,8 @@ export function deriveBehaviourMaturity({
 
   // 2. Calculate behaviour modifiers (additive from discipline and track)
   const disciplineModifier = discipline.behaviourModifiers?.[behaviourId] ?? 0;
-  const trackModifier = track.behaviourModifiers?.[behaviourId] ?? 0;
+  const effectiveTrack = track || { behaviourModifiers: {} };
+  const trackModifier = effectiveTrack.behaviourModifiers?.[behaviourId] ?? 0;
   const totalModifier = disciplineModifier + trackModifier;
 
   // 3. Apply modifier and clamp
@@ -163,12 +169,13 @@ export function deriveBehaviourMaturity({
  * @param {Object} params
  * @param {import('./levels.js').Discipline} params.discipline - The discipline
  * @param {import('./levels.js').Grade} params.grade - The grade
- * @param {import('./levels.js').Track} params.track - The track
+ * @param {import('./levels.js').Track} [params.track] - The track (optional)
  * @param {import('./levels.js').Skill[]} params.skills - All available skills
  * @returns {import('./levels.js').SkillMatrixEntry[]} Complete skill matrix
  */
-export function deriveSkillMatrix({ discipline, grade, track, skills }) {
+export function deriveSkillMatrix({ discipline, grade, track = null, skills }) {
   const matrix = [];
+  const effectiveTrack = track || { skillModifiers: {} };
 
   // Collect all skills for this discipline
   const allDisciplineSkills = new Set([
@@ -179,7 +186,7 @@ export function deriveSkillMatrix({ discipline, grade, track, skills }) {
 
   // Collect capabilities with positive track modifiers
   const trackCapabilities = new Set(
-    Object.entries(track.skillModifiers || {})
+    Object.entries(effectiveTrack.skillModifiers || {})
       .filter(([_, modifier]) => modifier > 0)
       .map(([capability]) => capability),
   );
@@ -239,14 +246,14 @@ export function deriveSkillMatrix({ discipline, grade, track, skills }) {
  * @param {Object} params
  * @param {import('./levels.js').Discipline} params.discipline - The discipline
  * @param {import('./levels.js').Grade} params.grade - The grade
- * @param {import('./levels.js').Track} params.track - The track
+ * @param {import('./levels.js').Track} [params.track] - The track (optional)
  * @param {import('./levels.js').Behaviour[]} params.behaviours - All available behaviours
  * @returns {import('./levels.js').BehaviourProfileEntry[]} Complete behaviour profile
  */
 export function deriveBehaviourProfile({
   discipline,
   grade,
-  track,
+  track = null,
   behaviours,
 }) {
   const profile = [];
@@ -278,7 +285,7 @@ export function deriveBehaviourProfile({
  * @param {Object} params
  * @param {import('./levels.js').Discipline} params.discipline - The discipline
  * @param {import('./levels.js').Grade} params.grade - The grade
- * @param {import('./levels.js').Track} params.track - The track
+ * @param {import('./levels.js').Track} [params.track] - The track (optional)
  * @param {import('./levels.js').JobValidationRules} [params.validationRules] - Optional validation rules
  * @param {Array<import('./levels.js').Grade>} [params.grades] - Optional array of all grades for minGrade validation
  * @returns {boolean} True if the combination is valid
@@ -286,18 +293,50 @@ export function deriveBehaviourProfile({
 export function isValidJobCombination({
   discipline,
   grade,
-  track,
+  track = null,
   validationRules,
   grades,
 }) {
-  // Check track's validDisciplines constraint (e.g., SRE only valid for Software Engineering and Data Engineering)
-  if (track.validDisciplines && track.validDisciplines.length > 0) {
-    if (!track.validDisciplines.includes(discipline.id)) {
+  // 1. Check discipline's minGrade constraint
+  if (discipline.minGrade && grades) {
+    const minGradeObj = grades.find((g) => g.id === discipline.minGrade);
+    if (minGradeObj && grade.ordinalRank < minGradeObj.ordinalRank) {
+      return false;
+    }
+  }
+
+  // 2. Handle trackless vs tracked jobs based on validTracks
+  // validTracks semantics:
+  // - null in array means "allow trackless (generalist)"
+  // - string values mean "allow this specific track"
+  // - empty array = discipline cannot have any jobs
+  if (!track) {
+    // Trackless job: only valid if null is in validTracks
+    // Note: for backwards compatibility, empty array also allows trackless
+    const validTracks = discipline.validTracks ?? [];
+    if (validTracks.length === 0) {
+      // Empty array = allow trackless (legacy behavior)
+      return true;
+    }
+    // Check if null is explicitly in the array
+    return validTracks.includes(null);
+  }
+
+  // 3. Check discipline's validTracks constraint for tracked jobs
+  // Only string entries matter here (null = trackless, not a track ID)
+  const validTracks = discipline.validTracks ?? [];
+  if (validTracks.length > 0) {
+    const trackIds = validTracks.filter((t) => t !== null);
+    if (trackIds.length > 0 && !trackIds.includes(track.id)) {
+      return false;
+    }
+    // If validTracks only contains null (no track IDs), reject all tracks
+    if (trackIds.length === 0) {
       return false;
     }
   }
 
-  // Check track's minGrade constraint (e.g., manager track only valid for senior grades)
+  // 4. Check track's minGrade constraint
   if (track.minGrade && grades) {
     const minGradeObj = grades.find((g) => g.id === track.minGrade);
     if (minGradeObj && grade.ordinalRank < minGradeObj.ordinalRank) {
@@ -305,12 +344,8 @@ export function isValidJobCombination({
     }
   }
 
-  if (!validationRules) {
-    return true;
-  }
-
-  // Check invalid combinations
-  if (validationRules.invalidCombinations) {
+  // 5. Apply framework-level validation rules
+  if (validationRules?.invalidCombinations) {
     for (const combo of validationRules.invalidCombinations) {
       const disciplineMatch =
         !combo.discipline || combo.discipline === discipline.id;
@@ -323,14 +358,6 @@ export function isValidJobCombination({
     }
   }
 
-  // Check valid tracks by discipline
-  if (validationRules.validTracksByDiscipline) {
-    const validTracks = validationRules.validTracksByDiscipline[discipline.id];
-    if (validTracks && !validTracks.includes(track.id)) {
-      return false;
-    }
-  }
-
   return true;
 }
 
@@ -338,48 +365,59 @@ export function isValidJobCombination({
  * Generate a job title from discipline, track, and grade
  *
  * Rules:
- * - If professional track and grade starts with "Level": ${discipline.roleTitle} ${grade.professionalTitle} - ${track.name}
- * - Else if professional track: ${grade.professionalTitle} ${discipline.roleTitle} - ${track.name}
- * - Else if management track: ${grade.managementTitle}, ${discipline.specialization} - ${track.name}
+ * - Management discipline without track: ${grade.managementTitle}, ${discipline.specialization}
+ * - Management discipline with track: ${grade.managementTitle}, ${track.name}
+ * - IC discipline with track: ${grade.professionalTitle} ${discipline.roleTitle} - ${track.name}
+ * - IC discipline without track: ${grade.professionalTitle} ${discipline.roleTitle}
  *
  * @param {import('./levels.js').Discipline} discipline - The discipline
- * @param {import('./levels.js').Track} track - The track
  * @param {import('./levels.js').Grade} grade - The grade
+ * @param {import('./levels.js').Track} [track] - The track (optional)
  * @returns {string} Generated job title
  */
-export function generateJobTitle(discipline, grade, track) {
-  const { roleTitle, specialization } = discipline;
+export function generateJobTitle(discipline, grade, track = null) {
+  const { roleTitle, specialization, isManagement } = discipline;
   const { professionalTitle, managementTitle } = grade;
 
-  // Determine if track is professional or management (default to professional)
-  const isProfessional = track.isProfessional !== false && !track.isManagement;
-  const isManagement = track.isManagement === true;
+  // Management discipline (no track needed)
+  if (isManagement && !track) {
+    return `${managementTitle}, ${specialization}`;
+  }
 
-  if (isManagement) {
-    // Management family track: "Director, Software Engineering"
-    if (track.id == "manager") {
-      return `${managementTitle}, ${specialization}`;
-    }
-    // Other management tracks: "Director, Developer Experience"
+  // Management discipline with track
+  if (isManagement && track) {
     return `${managementTitle}, ${track.name}`;
-  } else if (isProfessional && professionalTitle.startsWith("Level")) {
-    // Professional track with Level grade: "Software Engineer Level II - Platform"
-    return `${roleTitle} ${professionalTitle} - ${track.name}`;
-  } else {
+  }
+
+  // IC discipline with track
+  if (track) {
+    if (professionalTitle.startsWith("Level")) {
+      // Professional track with Level grade: "Software Engineer Level II - Platform"
+      return `${roleTitle} ${professionalTitle} - ${track.name}`;
+    }
     // Professional track with non-Level grade: "Staff Software Engineer - Platform"
     return `${professionalTitle} ${roleTitle} - ${track.name}`;
   }
+
+  // IC discipline without track (generalist)
+  if (professionalTitle.startsWith("Level")) {
+    return `${roleTitle} ${professionalTitle}`;
+  }
+  return `${professionalTitle} ${roleTitle}`;
 }
 
 /**
- * Generate a job ID from discipline, track, and grade
+ * Generate a job ID from discipline, grade, and track
  * @param {import('./levels.js').Discipline} discipline - The discipline
- * @param {import('./levels.js').Track} track - The track
  * @param {import('./levels.js').Grade} grade - The grade
+ * @param {import('./levels.js').Track} [track] - The track (optional)
  * @returns {string} Generated job ID
  */
-function generateJobId(discipline, track, grade) {
-  return `${discipline.id}_${track.id}_${grade.id}`;
+function generateJobId(discipline, grade, track = null) {
+  if (track) {
+    return `${discipline.id}_${grade.id}_${track.id}`;
+  }
+  return `${discipline.id}_${grade.id}`;
 }
 
 /**
@@ -392,23 +430,27 @@ function generateJobId(discipline, track, grade) {
  * Capabilities are sorted by their maximum skill level (descending),
  * so Expert-level capabilities appear before Practitioner-level, etc.
  *
- * Uses professionalResponsibilities for professional tracks (professional: true)
- * and managementResponsibilities for management tracks (management: true).
+ * Uses professionalResponsibilities for professional disciplines (isProfessional: true)
+ * and managementResponsibilities for management disciplines (isManagement: true).
  *
  * @param {Object} params
  * @param {import('./levels.js').SkillMatrixEntry[]} params.skillMatrix - Derived skill matrix for the job
  * @param {Object[]} params.capabilities - Capability definitions with responsibilities
- * @param {import('./levels.js').Track} params.track - The track (determines which responsibilities to use)
+ * @param {import('./levels.js').Discipline} params.discipline - The discipline (determines which responsibilities to use)
  * @returns {Array<{capability: string, capabilityName: string, emoji: string, responsibility: string, level: string}>}
  */
-export function deriveResponsibilities({ skillMatrix, capabilities, track }) {
+export function deriveResponsibilities({
+  skillMatrix,
+  capabilities,
+  discipline,
+}) {
   if (!capabilities || capabilities.length === 0) {
     return [];
   }
 
-  // Determine which responsibility set to use based on track type
-  // Management tracks use managementResponsibilities, professional tracks use professionalResponsibilities
-  const responsibilityKey = track?.isManagement
+  // Determine which responsibility set to use based on discipline type
+  // Management disciplines use managementResponsibilities, professional disciplines use professionalResponsibilities
+  const responsibilityKey = discipline?.isManagement
     ? "managementResponsibilities"
     : "professionalResponsibilities";
 
@@ -464,11 +506,11 @@ export function deriveResponsibilities({ skillMatrix, capabilities, track }) {
 }
 
 /**
- * Create a complete job definition from discipline, track, and grade
+ * Create a complete job definition from discipline, grade, and optional track
  * @param {Object} params
  * @param {import('./levels.js').Discipline} params.discipline - The discipline
  * @param {import('./levels.js').Grade} params.grade - The grade
- * @param {import('./levels.js').Track} params.track - The track
+ * @param {import('./levels.js').Track} [params.track] - The track (optional)
  * @param {import('./levels.js').Skill[]} params.skills - All available skills
  * @param {import('./levels.js').Behaviour[]} params.behaviours - All available behaviours
  * @param {Object[]} [params.capabilities] - Optional capabilities for responsibility derivation
@@ -478,7 +520,7 @@ export function deriveResponsibilities({ skillMatrix, capabilities, track }) {
 export function deriveJob({
   discipline,
   grade,
-  track,
+  track = null,
   skills,
   behaviours,
   capabilities,
@@ -511,7 +553,7 @@ export function deriveJob({
     derivedResponsibilities = deriveResponsibilities({
       skillMatrix,
       capabilities,
-      track,
+      discipline,
     });
   }
 
@@ -645,6 +687,7 @@ export function isSeniorGrade(grade) {
 
 /**
  * Generate all valid job definitions from the data
+ * Generates both trackless jobs and jobs with tracks based on discipline.validTracks
  * @param {Object} params
  * @param {import('./levels.js').Discipline[]} params.disciplines - All disciplines
  * @param {import('./levels.js').Grade[]} params.grades - All grades
@@ -665,8 +708,32 @@ export function generateAllJobs({
   const jobs = [];
 
   for (const discipline of disciplines) {
-    for (const track of tracks) {
-      for (const grade of grades) {
+    for (const grade of grades) {
+      // First, generate trackless job for this discipline/grade
+      if (
+        isValidJobCombination({
+          discipline,
+          grade,
+          track: null,
+          validationRules,
+          grades,
+        })
+      ) {
+        const tracklessJob = deriveJob({
+          discipline,
+          grade,
+          track: null,
+          skills,
+          behaviours,
+          validationRules,
+        });
+        if (tracklessJob) {
+          jobs.push(tracklessJob);
+        }
+      }
+
+      // Then, generate jobs with valid tracks
+      for (const track of tracks) {
         if (
           !isValidJobCombination({
             discipline,

package/app/model/index-generator.js

@@ -47,13 +47,7 @@ ${content}`;
  * @returns {Promise<Object>} Summary of generated indexes
  */
 export async function generateAllIndexes(dataDir) {
-  const directories = [
-    "skills",
-    "behaviours",
-    "disciplines",
-    "tracks",
-    "capabilities",
-  ];
+  const directories = ["behaviours", "disciplines", "tracks", "capabilities"];
 
   const results = {};
 

package/app/model/job.js

@@ -52,7 +52,8 @@ export function prepareJobDetail({
   drivers,
   capabilities,
 }) {
-  if (!discipline || !grade || !track) return null;
+  // Track is optional (null = generalist)
+  if (!discipline || !grade) return null;
 
   const job = getOrCreateJob({
     discipline,
@@ -70,14 +71,15 @@ export function prepareJobDetail({
     drivers,
   });
 
-  // Derive checklists for each handoff type
+  // Derive checklists for each stage
   const checklists = {};
   if (capabilities) {
-    const handoffTypes = ["plan_to_code", "code_to_review"];
-    for (const handoff of handoffTypes) {
-      checklists[handoff] = deriveChecklist({
-        handoff,
+    const stageIds = ["plan", "code"];
+    for (const stageId of stageIds) {
+      checklists[stageId] = deriveChecklist({
+        stageId,
         skillMatrix: job.skillMatrix,
+        skills,
         capabilities,
       });
     }
@@ -89,8 +91,8 @@ export function prepareJobDetail({
     disciplineName: discipline.specialization || discipline.name,
     gradeId: grade.id,
     gradeName: grade.professionalTitle || grade.id,
-    trackId: track.id,
-    trackName: track.name,
+    trackId: track?.id || null,
+    trackName: track?.name || null,
     expectations: job.expectations || {},
     // Raw model data for components that need the original shape
     skillMatrix: job.skillMatrix,
@@ -130,7 +132,7 @@ export function prepareJobSummary({
   skills,
   behaviours,
 }) {
-  if (!discipline || !grade || !track) return null;
+  if (!discipline || !grade) return null;
 
   const job = getOrCreateJob({
     discipline,
@@ -147,8 +149,8 @@ export function prepareJobSummary({
     disciplineId: discipline.id,
     disciplineName: discipline.specialization || discipline.name,
     gradeId: grade.id,
-    trackId: track.id,
-    trackName: track.name,
+    trackId: track?.id || null,
+    trackName: track?.name || null,
     skillCount: job.skillMatrix.length,
     behaviourCount: job.behaviourProfile.length,
     primarySkillCount: job.skillMatrix.filter((s) => s.type === "primary")
@@ -182,7 +184,8 @@ export function prepareJobBuilderPreview({
   behaviourCount,
   grades,
 }) {
-  if (!discipline || !grade || !track) {
+  // Track is optional (null = generalist)
+  if (!discipline || !grade) {
     return {
       isValid: false,
       title: null,
@@ -200,12 +203,15 @@ export function prepareJobBuilderPreview({
   });
 
   if (!validCombination) {
+    const reason = track
+      ? `The ${track.name} track is not available for ${discipline.specialization}.`
+      : `${discipline.specialization} requires a track specialization.`;
     return {
       isValid: false,
       title: null,
       totalSkills: 0,
       totalBehaviours: 0,
-      invalidReason: `The ${track.name} track is not available for ${discipline.specialization}.`,
+      invalidReason: reason,
     };
   }
 

package/app/model/levels.js

@@ -60,16 +60,24 @@ export const BEHAVIOUR_MATURITY_ORDER = [
  * @enum {string}
  */
 export const Stage = {
+  SPECIFY: "specify",
   PLAN: "plan",
   CODE: "code",
   REVIEW: "review",
+  DEPLOY: "deploy",
 };
 
 /**
  * Ordered array of stages for lifecycle progression
  * @type {string[]}
  */
-export const STAGE_ORDER = [Stage.PLAN, Stage.CODE, Stage.REVIEW];
+export const STAGE_ORDER = [
+  Stage.SPECIFY,
+  Stage.PLAN,
+  Stage.CODE,
+  Stage.REVIEW,
+  Stage.DEPLOY,
+];
 
 /**
  * Skill capabilities (what capability area)
@@ -86,6 +94,7 @@ export const Capability = {
   BUSINESS: "business",
   PEOPLE: "people",
   DOCUMENTATION: "documentation",
+  PRODUCT: "product",
 };
 
 /**
@@ -95,7 +104,7 @@ export const Capability = {
  * 2. Data & AI capabilities
  * 3. Scale & reliability
  * 4. People & process
- * 5. Business & documentation
+ * 5. Business, documentation & product
  * @type {string[]}
  */
 export const CAPABILITY_ORDER = [
@@ -108,6 +117,7 @@ export const CAPABILITY_ORDER = [
   Capability.PROCESS,
   Capability.BUSINESS,
   Capability.DOCUMENTATION,
+  Capability.PRODUCT,
 ];
 
 /**
@@ -214,24 +224,24 @@ export function getCapabilityEmoji(capabilities, capabilityId) {
 /**
  * Get responsibility statement for a capability at a specific skill level
  *
- * Uses professionalResponsibilities for professional tracks and
- * managementResponsibilities for management tracks.
+ * Uses professionalResponsibilities for professional disciplines and
+ * managementResponsibilities for management disciplines.
  *
  * @param {Object[]} capabilities - Loaded capabilities array
  * @param {string} capabilityId - The capability ID
  * @param {string} level - The skill level (awareness, foundational, working, practitioner, expert)
- * @param {Object} [track] - Optional track to determine which responsibilities to use
- * @param {boolean} [track.isManagement] - Whether this is a management track
+ * @param {Object} [discipline] - Optional discipline to determine which responsibilities to use
+ * @param {boolean} [discipline.isManagement] - Whether this is a management discipline
  * @returns {string|undefined} The responsibility statement or undefined
  */
 export function getCapabilityResponsibility(
   capabilities,
   capabilityId,
   level,
-  track,
+  discipline,
 ) {
   const capability = getCapabilityById(capabilities, capabilityId);
-  const responsibilityKey = track?.isManagement
+  const responsibilityKey = discipline?.isManagement
     ? "managementResponsibilities"
     : "professionalResponsibilities";
   return capability?.[responsibilityKey]?.[level];
@@ -288,6 +298,7 @@ export const SkillType = {
  * @property {string} roleTitle - Display name for a person in this role (e.g., "Software Engineer")
  * @property {string} [name] - Legacy display name (deprecated, use specialization/roleTitle)
  * @property {string} description - Description of the discipline
+ * @property {Array<string|null>} validTracks - Valid track configurations. null = allow trackless (generalist), string = track ID
  * @property {string[]} coreSkills - Skill IDs requiring deep expertise (Practitioner/Expert)
  * @property {string[]} supportingSkills - Skill IDs requiring solid competence (Working/Practitioner)
  * @property {string[]} broadSkills - Skill IDs requiring awareness (Awareness/Foundational)
@@ -305,12 +316,9 @@ export const SkillType = {
  * @property {string} id - Unique identifier
  * @property {string} name - Display name
  * @property {string} description - Description of the track focus
- * @property {boolean} [isProfessional=true] - Whether this is a professional/individual contributor track
- * @property {boolean} [isManagement=false] - Whether this is a management/people manager track
- * @property {Object<string, number>} skillModifiers - Map of skill ID to level modifier (positive or negative integer)
+ * @property {Object<string, number>} skillModifiers - Map of capability/skill ID to level modifier (positive or negative integer)
  * @property {Object<string, number>} behaviourModifiers - Map of behaviour ID to maturity modifier (positive or negative integer)
  * @property {AssessmentWeights} [assessmentWeights] - Optional custom weights for job matching
- * @property {string[]} [validDisciplines] - Optional array of discipline IDs this track is valid for
  * @property {string} [minGrade] - Optional minimum grade ID this track is valid for
  */