@forwardimpact/pathway 0.21.0 → 0.22.0

package/README.md

@@ -52,9 +52,9 @@ Use `--help` with any command for full options.
 
 ## Web App Features
 
-- **Job Builder** — Select discipline, track, and grade to explore roles
-- **Skill Browser** — View all skills with level descriptions
-- **Career Progression** — Compare grades and identify growth areas
+- **Job Builder** — Select discipline, track, and level to explore roles
+- **Skill Browser** — View all skills with proficiency descriptions
+- **Career Progression** — Compare levels and identify growth areas
 - **Interview Prep** — Generate role-specific question sets
 - **Agent Preview** — Preview generated agent profiles
 

package/bin/fit-pathway.js

@@ -10,16 +10,16 @@
  *
  * Commands:
  *   discipline [<id>]           Show disciplines
- *   grade [<id>]                Show grades
+ *   level [<id>]                Show levels
  *   track [<id>]                Show tracks
  *   behaviour [<id>]            Show behaviours
  *   skill [<id>]                Show skills (summary, --list, or detail)
  *   driver [<id>]               Show drivers
  *   stage [<id>]                Show stages
  *   tool [<name>]               Show tools
- *   job [<discipline> <grade>] [--track=TRACK]  Generate job definition
- *   interview <discipline> <grade> [--track=TRACK] [--type=mission|decomposition|stakeholder]  Generate interview
- *   progress <discipline> <grade> [--track=TRACK] [--compare=GRADE]  Career progression
+ *   job [<discipline> <level>] [--track=TRACK]  Generate job definition
+ *   interview <discipline> <level> [--track=TRACK] [--type=mission|decomposition|stakeholder]  Generate interview
+ *   progress <discipline> <level> [--track=TRACK] [--compare=LEVEL]  Career progression
  *   questions [options]         Browse interview questions
  *   agent [<discipline> <track>] [--output=PATH]  Generate AI agent
  *
@@ -37,7 +37,7 @@ import { formatError } from "../src/lib/cli-output.js";
 
 // Import command handlers
 import { runDisciplineCommand } from "../src/commands/discipline.js";
-import { runGradeCommand } from "../src/commands/grade.js";
+import { runLevelCommand } from "../src/commands/level.js";
 import { runTrackCommand } from "../src/commands/track.js";
 import { runBehaviourCommand } from "../src/commands/behaviour.js";
 import { runSkillCommand } from "../src/commands/skill.js";
@@ -56,7 +56,7 @@ import { runUpdateCommand } from "../src/commands/update.js";
 
 const COMMANDS = {
   discipline: runDisciplineCommand,
-  grade: runGradeCommand,
+  level: runLevelCommand,
   track: runTrackCommand,
   behaviour: runBehaviourCommand,
   skill: runSkillCommand,
@@ -98,7 +98,7 @@ ENTITY COMMANDS
 All entity commands support: summary (default), --list (IDs for piping), <id> (detail)
 
   discipline [<id>]     Browse engineering disciplines
-  grade [<id>]          Browse career grades/levels
+  level [<id>]          Browse career levels
   track [<id>]          Browse track specializations
   behaviour [<id>]      Browse professional behaviours
   driver [<id>]         Browse outcome drivers
@@ -113,16 +113,16 @@ All entity commands support: summary (default), --list (IDs for piping), <id> (d
 JOB COMMAND
 ────────────────────────────────────────────────────────────────────────────────
 
-Generate job definitions from discipline × grade × track combinations.
+Generate job definitions from discipline × level × track combinations.
 
 Usage:
   npx fit-pathway job                                  Summary with stats
   npx fit-pathway job --list                           All valid combinations
-  npx fit-pathway job <discipline> <grade>             Detail view (trackless)
-  npx fit-pathway job <d> <g> --track=<track>          Detail view (with track)
-  npx fit-pathway job <d> <g> --skills                 Plain list of skill IDs
-  npx fit-pathway job <d> <g> --tools                  Plain list of tool names
-  npx fit-pathway job <d> <g> --checklist=<stage>      Show handoff checklist
+  npx fit-pathway job <discipline> <level>             Detail view (trackless)
+  npx fit-pathway job <d> <l> --track=<track>          Detail view (with track)
+  npx fit-pathway job <d> <l> --skills                 Plain list of skill IDs
+  npx fit-pathway job <d> <l> --tools                  Plain list of tool names
+  npx fit-pathway job <d> <l> --checklist=<stage>      Show handoff checklist
 
 Options:
   --track=TRACK       Track specialization (e.g., platform, forward_deployed)
@@ -170,9 +170,9 @@ INTERVIEW COMMAND
 Generate interview question sets based on job requirements.
 
 Usage:
-  npx fit-pathway interview <discipline> <grade>                     All types
-  npx fit-pathway interview <d> <g> --track=<track>                  With track
-  npx fit-pathway interview <d> <g> --track=<t> --type=<type>        Single type
+  npx fit-pathway interview <discipline> <level>                     All types
+  npx fit-pathway interview <d> <l> --track=<track>                  With track
+  npx fit-pathway interview <d> <l> --track=<t> --type=<type>        Single type
 
 Options:
   --track=TRACK       Track specialization
@@ -183,16 +183,16 @@ Options:
 PROGRESS COMMAND
 ────────────────────────────────────────────────────────────────────────────────
 
-Analyze career progression between grades.
+Analyze career progression between levels.
 
 Usage:
-  npx fit-pathway progress <discipline> <grade>
-  npx fit-pathway progress <d> <g> --track=<track>
-  npx fit-pathway progress <d> <g> --compare=<to_grade>
+  npx fit-pathway progress <discipline> <level>
+  npx fit-pathway progress <d> <l> --track=<track>
+  npx fit-pathway progress <d> <l> --compare=<to_level>
 
 Options:
   --track=TRACK        Track specialization
-  --compare=GRADE      Compare to specific grade
+  --compare=LEVEL      Compare to specific level
 
 ────────────────────────────────────────────────────────────────────────────────
 QUESTIONS COMMAND
@@ -207,7 +207,7 @@ Usage:
   npx fit-pathway questions --stats
 
 Options:
-  --level=LEVEL        Filter by skill level
+  --level=LEVEL        Filter by skill proficiency
   --maturity=MATURITY  Filter by behaviour maturity
   --skill=ID           Filter to specific skill
   --behaviour=ID       Filter to specific behaviour

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/pathway",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Career progression web app and CLI for exploring roles and generating agent teams",
   "license": "Apache-2.0",
   "repository": {
@@ -40,8 +40,8 @@
     "./commands": "./src/commands/index.js"
   },
   "dependencies": {
-    "@forwardimpact/map": "^0.10.0",
-    "@forwardimpact/libpathway": "^2.0.0",
+    "@forwardimpact/map": "^0.11.0",
+    "@forwardimpact/libpathway": "^3.0.0",
     "mustache": "^4.2.0",
     "simple-icons": "^16.7.0",
     "yaml": "^2.3.4"

package/src/commands/agent.js

@@ -35,7 +35,7 @@ import {
   generateStageAgentProfile,
   validateAgentProfile,
   validateAgentSkill,
-  deriveReferenceGrade,
+  deriveReferenceLevel,
   deriveAgentSkills,
   generateSkillMarkdown,
   deriveToolkit,
@@ -414,15 +414,15 @@ export async function runAgentCommand({ data, args, options, dataDir }) {
     process.exit(1);
   }
 
-  // Get reference grade for derivation
-  const grade = deriveReferenceGrade(data.grades);
+  // Get reference level for derivation
+  const level = deriveReferenceLevel(data.levels);
 
   // --skills: Output plain list of skill IDs (for piping)
   if (options.skills) {
     const derivedSkills = deriveAgentSkills({
       discipline: humanDiscipline,
       track: humanTrack,
-      grade,
+      level,
       skills: skillsWithAgent,
     });
     for (const skill of derivedSkills) {
@@ -436,7 +436,7 @@ export async function runAgentCommand({ data, args, options, dataDir }) {
     const derivedSkills = deriveAgentSkills({
       discipline: humanDiscipline,
       track: humanTrack,
-      grade,
+      level,
       skills: skillsWithAgent,
     });
     const toolkit = deriveToolkit({
@@ -462,7 +462,7 @@ export async function runAgentCommand({ data, args, options, dataDir }) {
   const stageParams = {
     discipline: humanDiscipline,
     track: humanTrack,
-    grade,
+    level,
     skills: skillsWithAgent,
     behaviours: data.behaviours,
     agentBehaviours: agentData.behaviours,
@@ -534,7 +534,7 @@ export async function runAgentCommand({ data, args, options, dataDir }) {
   const derivedSkills = deriveAgentSkills({
     discipline: humanDiscipline,
     track: humanTrack,
-    grade,
+    level,
     skills: skillsWithAgent,
   });
 

package/src/commands/index.js

@@ -5,7 +5,7 @@
  */
 
 export { runDisciplineCommand } from "./discipline.js";
-export { runGradeCommand } from "./grade.js";
+export { runLevelCommand } from "./level.js";
 export { runTrackCommand } from "./track.js";
 export { runBehaviourCommand } from "./behaviour.js";
 export { runSkillCommand } from "./skill.js";

package/src/commands/init.js

@@ -54,7 +54,7 @@ Next steps:
 Data structure:
   data/
   ├── framework.yaml      # Framework metadata
-  ├── grades.yaml         # Career levels
+  ├── levels.yaml         # Career levels
   ├── stages.yaml         # Lifecycle stages
   ├── drivers.yaml        # Business drivers
   ├── capabilities.yaml   # Capability areas

package/src/commands/interview.js

@@ -4,9 +4,9 @@
  * Generates and displays interview questions in the terminal.
  *
  * Usage:
- *   npx fit-pathway interview <discipline> <grade>                                  # All interview types
- *   npx fit-pathway interview <discipline> <grade> --track=<track>                  # With track
- *   npx fit-pathway interview <discipline> <grade> --track=<track> --type=mission   # Single type
+ *   npx fit-pathway interview <discipline> <level>                                  # All interview types
+ *   npx fit-pathway interview <discipline> <level> --track=<track>                  # With track
+ *   npx fit-pathway interview <discipline> <level> --track=<track> --type=mission   # Single type
  */
 
 import { createCompositeCommand } from "./command-factory.js";
@@ -45,7 +45,7 @@ function formatAllInterviews(views, options) {
 
 export const runInterviewCommand = createCompositeCommand({
   commandName: "interview",
-  requiredArgs: ["discipline_id", "grade_id"],
+  requiredArgs: ["discipline_id", "level_id"],
   findEntities: (data, args, options) => {
     const interviewType = options.type === "full" ? null : options.type;
 
@@ -57,7 +57,7 @@ export const runInterviewCommand = createCompositeCommand({
 
     return {
       discipline: data.disciplines.find((d) => d.id === args[0]),
-      grade: data.grades.find((g) => g.id === args[1]),
+      level: data.levels.find((g) => g.id === args[1]),
       track: options.track
         ? data.tracks.find((t) => t.id === options.track)
         : null,
@@ -68,8 +68,8 @@ export const runInterviewCommand = createCompositeCommand({
     if (!entities.discipline) {
       return `Discipline not found: ${entities.discipline}`;
     }
-    if (!entities.grade) {
-      return `Grade not found: ${entities.grade}`;
+    if (!entities.level) {
+      return `Level not found: ${entities.level}`;
     }
     if (options.track && !entities.track) {
       return `Track not found: ${options.track}`;
@@ -79,7 +79,7 @@ export const runInterviewCommand = createCompositeCommand({
   presenter: (entities, data, _options) => {
     const params = {
       discipline: entities.discipline,
-      grade: entities.grade,
+      level: entities.level,
       track: entities.track,
       skills: data.skills,
       behaviours: data.behaviours,

package/src/commands/job.js

@@ -6,10 +6,10 @@
  * Usage:
  *   npx pathway job                                          # Summary with stats
  *   npx pathway job --list                                   # All valid combinations (for piping)
- *   npx pathway job <discipline> <grade>                     # Detail view (trackless)
- *   npx pathway job <discipline> <grade> --track=<track>     # Detail view (with track)
- *   npx pathway job <d> <g> [--track=<t>] --skills           # Plain list of skill IDs
- *   npx pathway job <d> <g> [--track=<t>] --tools            # Plain list of tool names
+ *   npx pathway job <discipline> <level>                     # Detail view (trackless)
+ *   npx pathway job <discipline> <level> --track=<track>     # Detail view (with track)
+ *   npx pathway job <d> <l> [--track=<t>] --skills           # Plain list of skill IDs
+ *   npx pathway job <d> <l> [--track=<t>] --tools            # Plain list of tool names
  *   npx pathway job se L3 --track=platform --checklist=code  # Show checklist for handoff
  *   npx pathway job --validate                               # Validation checks
  */
@@ -47,20 +47,20 @@ function formatJob(view, _options, entities, jobTemplate) {
 export async function runJobCommand({ data, args, options, dataDir }) {
   const jobs = generateAllJobs({
     disciplines: data.disciplines,
-    grades: data.grades,
+    levels: data.levels,
     tracks: data.tracks,
     skills: data.skills,
     behaviours: data.behaviours,
     validationRules: data.framework.validationRules,
   });
 
-  // --list: Output clean lines for piping (discipline grade track format)
+  // --list: Output clean lines for piping (discipline level track format)
   if (options.list) {
     for (const job of jobs) {
       if (job.track) {
-        console.log(`${job.discipline.id} ${job.grade.id} ${job.track.id}`);
+        console.log(`${job.discipline.id} ${job.level.id} ${job.track.id}`);
       } else {
-        console.log(`${job.discipline.id} ${job.grade.id}`);
+        console.log(`${job.discipline.id} ${job.level.id}`);
       }
     }
     return;
@@ -82,15 +82,15 @@ export async function runJobCommand({ data, args, options, dataDir }) {
     console.log(`\nTotal: ${jobs.length} valid job combinations`);
     console.log(`\nRun 'npx pathway job --list' for all combinations`);
     console.log(
-      `Run 'npx pathway job <discipline> <grade> [--track=<track>]' for details\n`,
+      `Run 'npx pathway job <discipline> <level> [--track=<track>]' for details\n`,
     );
     return;
   }
 
-  // Handle job detail view - requires discipline and grade
+  // Handle job detail view - requires discipline and level
   if (args.length < 2) {
     console.error(
-      "Usage: npx pathway job <discipline> <grade> [--track=<track>]",
+      "Usage: npx pathway job <discipline> <level> [--track=<track>]",
     );
     console.error("       npx pathway job --list");
     console.error("Example: npx pathway job software_engineering L4");
@@ -101,7 +101,7 @@ export async function runJobCommand({ data, args, options, dataDir }) {
   }
 
   const discipline = data.disciplines.find((d) => d.id === args[0]);
-  const grade = data.grades.find((g) => g.id === args[1]);
+  const level = data.levels.find((g) => g.id === args[1]);
   const track = options.track
     ? data.tracks.find((t) => t.id === options.track)
     : null;
@@ -112,9 +112,9 @@ export async function runJobCommand({ data, args, options, dataDir }) {
     process.exit(1);
   }
 
-  if (!grade) {
-    console.error(`Grade not found: ${args[1]}`);
-    console.error(`Available: ${data.grades.map((g) => g.id).join(", ")}`);
+  if (!level) {
+    console.error(`Level not found: ${args[1]}`);
+    console.error(`Available: ${data.levels.map((g) => g.id).join(", ")}`);
     process.exit(1);
   }
 
@@ -126,7 +126,7 @@ export async function runJobCommand({ data, args, options, dataDir }) {
 
   const view = prepareJobDetail({
     discipline,
-    grade,
+    level,
     track,
     skills: data.skills,
     behaviours: data.behaviours,
@@ -137,8 +137,8 @@ export async function runJobCommand({ data, args, options, dataDir }) {
 
   if (!view) {
     const combo = track
-      ? `${discipline.id} × ${grade.id} × ${track.id}`
-      : `${discipline.id} × ${grade.id}`;
+      ? `${discipline.id} × ${level.id} × ${track.id}`
+      : `${discipline.id} × ${level.id}`;
     console.error(`Invalid combination: ${combo}`);
     if (track) {
       const validTracks =
@@ -212,5 +212,5 @@ export async function runJobCommand({ data, args, options, dataDir }) {
 
   // Load job template for description formatting
   const jobTemplate = await loadJobTemplate(dataDir);
-  formatJob(view, options, { discipline, grade, track }, jobTemplate);
+  formatJob(view, options, { discipline, level, track }, jobTemplate);
 }

package/src/commands/level.js

@@ -0,0 +1,60 @@
+/**
+ * Level CLI Command
+ *
+ * Handles level summary, listing, and detail display in the terminal.
+ *
+ * Usage:
+ *   npx pathway level              # Summary with stats
+ *   npx pathway level --list       # IDs only (for piping)
+ *   npx pathway level <id>         # Detail view
+ *   npx pathway level --validate   # Validation checks
+ */
+
+import { createEntityCommand } from "./command-factory.js";
+import { levelToMarkdown } from "../formatters/level/markdown.js";
+import { formatTable } from "../lib/cli-output.js";
+import { getConceptEmoji } from "@forwardimpact/map/levels";
+import { capitalize } from "../formatters/shared.js";
+
+/**
+ * Format level summary output
+ * @param {Array} levels - Raw level entities
+ * @param {Object} data - Full data context
+ */
+function formatSummary(levels, data) {
+  const { framework } = data;
+  const emoji = framework ? getConceptEmoji(framework, "level") : "📊";
+
+  console.log(`\n${emoji} Levels\n`);
+
+  const rows = levels.map((g) => [
+    g.id,
+    g.displayName || g.id,
+    g.typicalExperienceRange || "-",
+    capitalize(g.baseSkillProficiencies?.primary || "-"),
+  ]);
+
+  console.log(formatTable(["ID", "Name", "Experience", "Primary Level"], rows));
+  console.log(`\nTotal: ${levels.length} levels`);
+  console.log(`\nRun 'npx pathway level --list' for IDs`);
+  console.log(`Run 'npx pathway level <id>' for details\n`);
+}
+
+/**
+ * Format level detail output
+ * @param {Object} level - Raw level entity
+ * @param {Object} framework - Framework config
+ */
+function formatDetail(level, framework) {
+  console.log(levelToMarkdown(level, framework));
+}
+
+export const runLevelCommand = createEntityCommand({
+  entityName: "level",
+  pluralName: "levels",
+  findEntity: (data, id) => data.levels.find((g) => g.id === id),
+  presentDetail: (entity) => entity,
+  formatSummary,
+  formatDetail,
+  emojiIcon: "📊",
+});

package/src/commands/progress.js

@@ -4,15 +4,15 @@
  * Shows career progression analysis in the terminal.
  *
  * Usage:
- *   npx pathway progress <discipline> <grade>                            # Progress for trackless job
- *   npx pathway progress <discipline> <grade> --track=<track>            # Progress with track
- *   npx pathway progress <discipline> <from_grade> --compare=<to_grade>  # Compare grades
+ *   npx pathway progress <discipline> <level>                            # Progress for trackless job
+ *   npx pathway progress <discipline> <level> --track=<track>            # Progress with track
+ *   npx pathway progress <discipline> <from_level> --compare=<to_level>  # Compare levels
  */
 
 import { createCompositeCommand } from "./command-factory.js";
 import {
   prepareProgressDetail,
-  getDefaultTargetGrade,
+  getDefaultTargetLevel,
 } from "../formatters/progress/shared.js";
 import { progressToMarkdown } from "../formatters/progress/markdown.js";
 
@@ -26,53 +26,53 @@ function formatProgress(view) {
 
 export const runProgressCommand = createCompositeCommand({
   commandName: "progress",
-  requiredArgs: ["discipline_id", "grade_id"],
+  requiredArgs: ["discipline_id", "level_id"],
   findEntities: (data, args, options) => {
     const discipline = data.disciplines.find((d) => d.id === args[0]);
-    const grade = data.grades.find((g) => g.id === args[1]);
+    const level = data.levels.find((g) => g.id === args[1]);
     const track = options.track
       ? data.tracks.find((t) => t.id === options.track)
       : null;
 
-    let targetGrade;
+    let targetLevel;
     if (options.compare) {
-      targetGrade = data.grades.find((g) => g.id === options.compare);
-      if (!targetGrade) {
-        console.error(`Target grade not found: ${options.compare}`);
+      targetLevel = data.levels.find((g) => g.id === options.compare);
+      if (!targetLevel) {
+        console.error(`Target level not found: ${options.compare}`);
         process.exit(1);
       }
     } else {
-      targetGrade = getDefaultTargetGrade(grade, data.grades);
-      if (!targetGrade) {
-        console.error("No next grade available for progression.");
+      targetLevel = getDefaultTargetLevel(level, data.levels);
+      if (!targetLevel) {
+        console.error("No next level available for progression.");
         process.exit(1);
       }
     }
 
-    return { discipline, grade, track, targetGrade };
+    return { discipline, level, track, targetLevel };
   },
   validateEntities: (entities, _data, options) => {
     if (!entities.discipline) {
       return `Discipline not found`;
     }
-    if (!entities.grade) {
-      return `Grade not found`;
+    if (!entities.level) {
+      return `Level not found`;
     }
     if (options.track && !entities.track) {
       return `Track not found: ${options.track}`;
     }
-    if (!entities.targetGrade) {
-      return `Target grade not found`;
+    if (!entities.targetLevel) {
+      return `Target level not found`;
     }
     return null;
   },
   presenter: (entities, data) =>
     prepareProgressDetail({
       fromDiscipline: entities.discipline,
-      fromGrade: entities.grade,
+      fromLevel: entities.level,
       fromTrack: entities.track,
       toDiscipline: entities.discipline,
-      toGrade: entities.targetGrade,
+      toLevel: entities.targetLevel,
       toTrack: entities.track,
       skills: data.skills,
       behaviours: data.behaviours,

package/src/commands/questions.js

@@ -49,7 +49,7 @@ function showQuestionsSummary(data) {
   console.log(`\n❓ Questions\n`);
 
   // Skill questions by level
-  const skillLevels = [
+  const skillProficiencies = [
     "awareness",
     "foundational",
     "working",
@@ -57,10 +57,10 @@ function showQuestionsSummary(data) {
     "expert",
   ];
   const roleTypes = ["professionalQuestions", "managementQuestions"];
-  const skillRows = skillLevels.map((level) => {
+  const skillRows = skillProficiencies.map((level) => {
     let count = 0;
     for (const skill of skills) {
-      const sq = questions.skillLevels?.[skill.id];
+      const sq = questions.skillProficiencies?.[skill.id];
       if (sq) {
         for (const roleType of roleTypes) {
           count += (sq[roleType]?.[level] || []).length;

package/src/components/action-buttons.js

@@ -30,7 +30,7 @@ export function createNavButton({ label, href, variant = "primary" }) {
 /**
  * Create a button to navigate to job builder with a parameter
  * @param {Object} options - Configuration options
- * @param {string} options.paramName - Parameter name (discipline, grade, track)
+ * @param {string} options.paramName - Parameter name (discipline, level, track)
  * @param {string} options.paramValue - Parameter value (the ID)
  * @param {string} [options.label] - Optional custom label
  * @returns {HTMLElement}
@@ -38,7 +38,7 @@ export function createNavButton({ label, href, variant = "primary" }) {
 export function createJobBuilderButton({ paramName, paramValue, label }) {
   const defaultLabels = {
     discipline: "Build Job with this Discipline →",
-    grade: "Build Job at this Grade →",
+    level: "Build Job at this Level →",
     track: "Build Job with this Track →",
   };
 
@@ -52,7 +52,7 @@ export function createJobBuilderButton({ paramName, paramValue, label }) {
 /**
  * Create a button to navigate to interview prep with a parameter
  * @param {Object} options - Configuration options
- * @param {string} options.paramName - Parameter name (discipline, grade, track)
+ * @param {string} options.paramName - Parameter name (discipline, level, track)
  * @param {string} options.paramValue - Parameter value (the ID)
  * @param {string} [options.label] - Optional custom label
  * @returns {HTMLElement}