@forwardimpact/map 0.11.1 → 0.12.0

package/bin/fit-map.js

@@ -3,11 +3,12 @@
 /**
  * fit-map CLI
  *
- * Map validation and index generation for Engineering Pathway data.
+ * Map validation, index generation, and activity management for Engineering Pathway data.
  *
  * Commands:
  *   validate [--json|--shacl]   Run validation (default: --json)
  *   generate-index [--data=PATH] Generate _index.yaml files
+ *   people import <file>        Import people from CSV/YAML
  *   --help                      Show help
  */
 
@@ -22,22 +23,29 @@ const __dirname = dirname(__filename);
  * Parse CLI arguments
  */
 function parseArgs(args) {
-  const command = args[0];
   const options = {};
-
-  for (let i = 1; i < args.length; i++) {
-    const arg = args[i];
-    if (arg.startsWith("--data=")) {
-      options.dataDir = arg.slice(7);
-    } else if (arg === "--help" || arg === "-h") {
+  const positional = [];
+
+  for (const arg of args) {
+    if (arg.startsWith("--")) {
+      if (arg === "--help") {
+        options.help = true;
+      } else {
+        const [key, value] = arg.slice(2).split("=");
+        options[key] = value ?? true;
+      }
+    } else if (arg === "-h") {
       options.help = true;
-    } else if (arg.startsWith("--")) {
-      const [key, value] = arg.slice(2).split("=");
-      options[key] = value ?? true;
+    } else {
+      positional.push(arg);
     }
   }
 
-  return { command, options };
+  const command = positional[0] || null;
+  const subcommand = positional[1] || null;
+  const rest = positional.slice(2);
+
+  return { command, subcommand, options, positional: rest };
 }
 
 /**
@@ -214,31 +222,62 @@ async function runValidateShacl() {
   }
 }
 
+/**
+ * People import command
+ */
+async function runPeopleImport(filePath, dataDir) {
+  console.log(`👤 Importing people from: ${filePath}\n`);
+
+  const { loadPeopleFile, validatePeople } =
+    await import("../activity/ingestion/people.js");
+
+  const people = await loadPeopleFile(filePath);
+  console.log(`  Loaded ${people.length} people from file`);
+
+  const { valid, errors } = await validatePeople(people, dataDir);
+
+  if (errors.length > 0) {
+    console.log(`\n❌ Validation errors:`);
+    for (const err of errors) {
+      console.log(`  • Row ${err.row}: ${err.message}`);
+    }
+  }
+
+  console.log(`\n✅ ${valid.length} people validated`);
+  if (errors.length > 0) {
+    console.log(`❌ ${errors.length} rows with errors\n`);
+  }
+
+  return errors.length > 0 ? 1 : 0;
+}
+
 /**
  * Show help
  */
 function showHelp() {
   console.log(`
-fit-map - Data validation for Engineering Pathway
+fit-map - Data validation and management for Engineering Pathway
 
 Usage:
   fit-map <command> [options]
 
 Commands:
-  validate           Run validation (default: JSON schema validation)
-  generate-index     Generate _index.yaml files for directories
+  validate              Run validation (default: JSON schema validation)
+  generate-index        Generate _index.yaml files for directories
+  people import <file>  Import people from CSV/YAML (validates against framework)
 
 Options:
-  --json             JSON schema + referential validation (default)
-  --shacl            SHACL schema syntax validation
-  --data=PATH        Path to data directory (default: ./data or ./examples)
-  --help, -h         Show this help message
+  --json                JSON schema + referential validation (default)
+  --shacl               SHACL schema syntax validation
+  --data=PATH           Path to data directory (default: ./data or ./examples)
+  --help, -h            Show this help message
 
 Examples:
   fit-map validate
   fit-map validate --shacl
   fit-map validate --data=./my-data
   fit-map generate-index
+  fit-map people import ./org/people.yaml
 `);
 }
 
@@ -246,11 +285,13 @@ Examples:
  * Main entry point
  */
 async function main() {
-  const { command, options } = parseArgs(process.argv.slice(2));
+  const { command, subcommand, options, positional } = parseArgs(
+    process.argv.slice(2),
+  );
 
   if (options.help || !command) {
     showHelp();
-    process.exit(command ? 0 : 1);
+    process.exit(options.help ? 0 : 1);
   }
 
   try {
@@ -261,16 +302,32 @@ async function main() {
         if (options.shacl) {
           exitCode = await runValidateShacl();
         } else {
-          const dataDir = await findDataDir(options.dataDir);
+          const dataDir = await findDataDir(options.data);
           exitCode = await runValidate(dataDir);
         }
         break;
       }
       case "generate-index": {
-        const dataDir = await findDataDir(options.dataDir);
+        const dataDir = await findDataDir(options.data);
         exitCode = await runGenerateIndex(dataDir);
         break;
       }
+      case "people": {
+        if (subcommand === "import") {
+          const filePath = positional[0];
+          if (!filePath) {
+            console.error("Error: people import requires a file path");
+            process.exit(1);
+          }
+          const dataDir = await findDataDir(options.data);
+          exitCode = await runPeopleImport(filePath, dataDir);
+        } else {
+          console.error(`Unknown people subcommand: ${subcommand || "(none)"}`);
+          showHelp();
+          exitCode = 1;
+        }
+        break;
+      }
       default:
         console.error(`Unknown command: ${command}`);
         showHelp();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/map",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Public data model for career frameworks, consumed by AI agents and engineers",
   "license": "Apache-2.0",
   "repository": {
@@ -33,7 +33,14 @@
     "./levels": "./src/levels.js",
     "./examples/*": "./examples/*",
     "./schema/json/*": "./schema/json/*",
-    "./schema/rdf/*": "./schema/rdf/*"
+    "./schema/rdf/*": "./schema/rdf/*",
+    "./activity/queries/org": "./activity/queries/org.js",
+    "./activity/queries/snapshots": "./activity/queries/snapshots.js",
+    "./activity/queries/evidence": "./activity/queries/evidence.js",
+    "./activity/queries/artifacts": "./activity/queries/artifacts.js",
+    "./activity/ingestion/people": "./activity/ingestion/people.js",
+    "./activity/ingestion/getdx": "./activity/ingestion/getdx.js",
+    "./activity/ingestion/github": "./activity/ingestion/github.js"
   },
   "dependencies": {
     "ajv": "^8.17.1",

package/schema/json/capability.schema.json

@@ -105,10 +105,43 @@
         "implementationReference": {
           "type": "string",
           "description": "Code examples and detailed reference material, exported to references/REFERENCE.md"
+        },
+        "markers": {
+          "$ref": "#/$defs/skillMarkers",
+          "description": "Observable indicators of skill proficiency, keyed by level"
         }
       },
       "additionalProperties": false
     },
+    "skillMarkers": {
+      "type": "object",
+      "description": "Observable indicators of skill proficiency, keyed by level",
+      "propertyNames": {
+        "enum": [
+          "awareness",
+          "foundational",
+          "working",
+          "practitioner",
+          "expert"
+        ]
+      },
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "human": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Observable markers for human engineers"
+          },
+          "agent": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Observable markers for AI agents"
+          }
+        },
+        "additionalProperties": false
+      }
+    },
     "toolReference": {
       "type": "object",
       "required": ["name", "description", "useWhen"],

package/schema/rdf/capability.ttl

@@ -38,6 +38,10 @@ fit:ToolReference a rdfs:Class ;
     rdfs:label "Tool Reference"@en ;
     rdfs:comment "Reference to an external tool with usage guidance"@en .
 
+fit:SkillMarkers a rdfs:Class ;
+    rdfs:label "Skill Markers"@en ;
+    rdfs:comment "Observable indicators of skill proficiency at a level"@en .
+
 # -----------------------------------------------------------------------------
 # Properties
 # -----------------------------------------------------------------------------
@@ -95,6 +99,24 @@ fit:implementationReference a rdf:Property ;
     rdfs:domain fit:Skill ;
     rdfs:range xsd:string .
 
+fit:markers a rdf:Property ;
+    rdfs:label "markers"@en ;
+    rdfs:comment "Observable indicators keyed by proficiency level"@en ;
+    rdfs:domain fit:Skill ;
+    rdfs:range fit:SkillMarkers .
+
+fit:humanMarkers a rdf:Property ;
+    rdfs:label "humanMarkers"@en ;
+    rdfs:comment "Observable markers for human engineers"@en ;
+    rdfs:domain fit:SkillMarkers ;
+    rdfs:range xsd:string .
+
+fit:agentMarkers a rdf:Property ;
+    rdfs:label "agentMarkers"@en ;
+    rdfs:comment "Observable markers for AI agents"@en ;
+    rdfs:domain fit:SkillMarkers ;
+    rdfs:range xsd:string .
+
 fit:toolReferences a rdf:Property ;
     rdfs:label "toolReferences"@en ;
     rdfs:comment "Required tools for this skill"@en ;
@@ -315,6 +337,32 @@ fit:SkillShape a sh:NodeShape ;
         sh:maxCount 1 ;
         sh:name "implementationReference" ;
         sh:description "Code examples and detailed reference material, exported to references/REFERENCE.md" ;
+    ] ;
+    sh:property [
+        sh:path fit:markers ;
+        sh:node fit:SkillMarkersShape ;
+        sh:maxCount 1 ;
+        sh:name "markers" ;
+        sh:description "Observable indicators of skill proficiency, keyed by level" ;
+    ] .
+
+# -----------------------------------------------------------------------------
+# Skill Markers Shape
+# -----------------------------------------------------------------------------
+
+fit:SkillMarkersShape a sh:NodeShape ;
+    sh:targetClass fit:SkillMarkers ;
+    sh:property [
+        sh:path fit:humanMarkers ;
+        sh:datatype xsd:string ;
+        sh:name "human" ;
+        sh:description "Observable markers for human engineers" ;
+    ] ;
+    sh:property [
+        sh:path fit:agentMarkers ;
+        sh:datatype xsd:string ;
+        sh:name "agent" ;
+        sh:description "Observable markers for AI agents" ;
     ] .
 
 # -----------------------------------------------------------------------------

package/src/loader.js

@@ -94,6 +94,7 @@ async function loadSkillsFromCapabilities(capabilitiesDir) {
           installScript,
           implementationReference,
           toolReferences,
+          markers,
         } = skill;
         allSkills.push({
           id,
@@ -111,6 +112,8 @@ async function loadSkillsFromCapabilities(capabilitiesDir) {
           // Include implementation reference and tool references (shared by human and agent)
           ...(implementationReference && { implementationReference }),
           ...(toolReferences && { toolReferences }),
+          // Include markers for evidence evaluation
+          ...(markers && { markers }),
         });
       }
     }

package/src/validation.js

@@ -6,6 +6,7 @@
 
 import {
   Capability,
+  SKILL_PROFICIENCY_ORDER,
   getSkillProficiencyIndex,
   getBehaviourMaturityIndex,
 } from "./levels.js";
@@ -406,6 +407,59 @@ function validateSkill(skill, index, requiredStageIds = []) {
     }
   }
 
+  // Validate markers if present
+  if (skill.markers !== undefined) {
+    if (typeof skill.markers !== "object" || Array.isArray(skill.markers)) {
+      errors.push(
+        createError(
+          "INVALID_VALUE",
+          "Skill markers must be an object keyed by proficiency level",
+          `${path}.markers`,
+          skill.markers,
+        ),
+      );
+    } else {
+      for (const [level, levelMarkers] of Object.entries(skill.markers)) {
+        if (!SKILL_PROFICIENCY_ORDER.includes(level)) {
+          errors.push(
+            createError(
+              "INVALID_VALUE",
+              `Invalid marker level: ${level}. Must be one of: ${SKILL_PROFICIENCY_ORDER.join(", ")}`,
+              `${path}.markers.${level}`,
+              level,
+            ),
+          );
+          continue;
+        }
+        if (typeof levelMarkers !== "object" || Array.isArray(levelMarkers)) {
+          errors.push(
+            createError(
+              "INVALID_VALUE",
+              `Markers at level ${level} must be an object with human/agent arrays`,
+              `${path}.markers.${level}`,
+              levelMarkers,
+            ),
+          );
+          continue;
+        }
+        for (const section of ["human", "agent"]) {
+          if (levelMarkers[section] !== undefined) {
+            if (!Array.isArray(levelMarkers[section])) {
+              errors.push(
+                createError(
+                  "INVALID_VALUE",
+                  `Markers ${section} at level ${level} must be an array of strings`,
+                  `${path}.markers.${level}.${section}`,
+                  levelMarkers[section],
+                ),
+              );
+            }
+          }
+        }
+      }
+    }
+  }
+
   return { errors, warnings };
 }