@forwardimpact/libcoaligned 0.1.4 → 0.1.6

package/README.md

@@ -11,7 +11,7 @@ invariants across the repo.
 
 ```sh
 npx coaligned                   # run every check (instructions + jtbd)
-npx coaligned instructions      # enforce L1–L6 length and checklist caps
+npx coaligned instructions      # enforce L1–L7 length and checklist caps
 npx coaligned jtbd              # validate JTBD entries against package.json
 npx coaligned jtbd --fix        # regenerate catalog and job blocks in place
 ```
@@ -20,8 +20,9 @@ The two subcommands implement the contract described in
 [COALIGNED.md](https://github.com/forwardimpact/monorepo/blob/main/COALIGNED.md):
 
 - `instructions` — every layer (L1 CLAUDE.md, L2 CONTRIBUTING.md / JTBD.md,
-  L3 agent profile, L4 SKILL.md, L5 reference, L6 checklist block) is gated by
-  a line cap **and** a word cap. Either breach fails.
+  L3 agent profile, L4 agent reference, L5 SKILL.md, L6 skill reference,
+  L7 checklist block) is gated by a line cap **and** a word cap. Either breach
+  fails.
 - `jtbd` — each `package.json .jobs` entry is validated against the JTBD
   schema; with `--fix`, marker-delimited blocks in `<dir>/README.md`,
   `<dir>/<pkg>/README.md`, and root `JTBD.md` are regenerated.

package/bin/coaligned.js

@@ -4,6 +4,7 @@ import "@forwardimpact/libpreflight/node22";
 
 import { readFileSync } from "node:fs";
 import { createCli } from "@forwardimpact/libcli";
+import { emitFindingsJson, emitFindingsText } from "@forwardimpact/libutil";
 import { checkInstructions, checkJtbd } from "../src/index.js";
 
 const { version: VERSION } = JSON.parse(
@@ -40,37 +41,48 @@ const definition = {
   globalOptions: {
     help: { type: "boolean", short: "h", description: "Show this help" },
     version: { type: "boolean", description: "Show version" },
-    json: { type: "boolean", description: "Output help as JSON" },
+    json: { type: "boolean", description: "Output findings as JSON" },
   },
   examples: ["coaligned", "coaligned instructions", "coaligned jtbd --fix"],
 };
 
 const cli = createCli(definition);
 
-async function runInstructions(root) {
-  const errors = await checkInstructions({ root });
-  for (const e of errors) process.stderr.write(`error: ${e}\n`);
-  return errors.length > 0 ? 1 : 0;
+function writeFindings(findings, passMessage, jsonOutput, cwd) {
+  if (jsonOutput) {
+    process.stdout.write(emitFindingsJson(findings));
+  } else if (findings.length > 0) {
+    process.stderr.write(emitFindingsText(findings, { cwd, passMessage }));
+  } else {
+    process.stdout.write(emitFindingsText(findings, { cwd, passMessage }));
+  }
+}
+
+async function runInstructions(root, jsonOutput) {
+  const findings = await checkInstructions({ root });
+  writeFindings(findings, "coaligned instructions passed", jsonOutput, root);
+  return findings.length > 0 ? 1 : 0;
 }
 
-async function runJtbd(root, fix) {
-  const { errors, stale, fixed } = await checkJtbd({ root, fix });
-  for (const e of errors) process.stderr.write(`${e}\n`);
+async function runJtbd(root, fix, jsonOutput) {
+  const { findings, stale, fixed } = await checkJtbd({ root, fix });
+  writeFindings(findings, "coaligned jtbd passed", jsonOutput, root);
   for (const f of fixed) process.stdout.write(`Regenerated ${f}.\n`);
-  for (const s of stale) {
+  if (stale.length > 0 && !jsonOutput) {
     process.stderr.write(
-      `${s} out of date. Run \`coaligned jtbd --fix\` to regenerate.\n`,
+      `\n${stale.length} file${stale.length === 1 ? "" : "s"} out of date — run \`coaligned jtbd --fix\` to regenerate:\n`,
     );
+    for (const s of stale) process.stderr.write(`  - ${s}\n`);
   }
-  return errors.length > 0 || stale.length > 0 ? 1 : 0;
+  return findings.length > 0 || stale.length > 0 ? 1 : 0;
 }
 
 async function instructionsHandler(ctx) {
-  return runInstructions(ctx.data.root);
+  return runInstructions(ctx.data.root, !!ctx.options.json);
 }
 
 async function jtbdHandler(ctx) {
-  return runJtbd(ctx.data.root, !!ctx.options.fix);
+  return runJtbd(ctx.data.root, !!ctx.options.fix, !!ctx.options.json);
 }
 
 async function main() {
@@ -78,12 +90,13 @@ async function main() {
   if (!parsed) return 0;
 
   const root = process.cwd();
+  const jsonOutput = !!parsed.values.json;
 
   // No subcommand → run every check; --fix stays jtbd-only and must be opted
   // into explicitly via `coaligned jtbd --fix`.
   if (parsed.positionals.length === 0) {
-    const a = await runInstructions(root);
-    const b = await runJtbd(root, false);
+    const a = await runInstructions(root, jsonOutput);
+    const b = await runJtbd(root, false, jsonOutput);
     return a || b;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libcoaligned",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Co-Aligned architecture checks — enforce instruction-layer length caps and JTBD invariants across the repo.",
   "keywords": [
     "coaligned",
@@ -47,6 +47,7 @@
   "dependencies": {
     "@forwardimpact/libcli": "^0.1.9",
     "@forwardimpact/libpreflight": "^0.1.0",
+    "@forwardimpact/libutil": "*",
     "prettier": "^3.0.0"
   },
   "engines": {

package/src/instructions.js

@@ -1,5 +1,6 @@
 import { readFile, readdir } from "node:fs/promises";
 import { resolve } from "node:path";
+import { runRules } from "@forwardimpact/libutil";
 
 const SKIP_DIRS = new Set([
   ".cache",
@@ -13,8 +14,8 @@ const SKIP_DIRS = new Set([
   "worktrees",
 ]);
 
-const L6_MAX_ITEMS = 9;
-const L6_MAX_WORDS_PER_ITEM = 32;
+const L7_MAX_ITEMS = 9;
+const L7_MAX_WORDS_PER_ITEM = 32;
 
 const CHECKLIST_RE =
   /<(read_do_checklist|do_confirm_checklist)\b[^>]*>([\s\S]*?)<\/\1>/g;
@@ -77,6 +78,19 @@ async function findAgentProfiles(root, claudeDirs) {
   return out;
 }
 
+async function findAgentReferences(root, claudeDirs) {
+  const out = [];
+  for (const d of claudeDirs) {
+    const files = await listFiles(
+      root,
+      `${d}/agents/references`,
+      (e) => e.isFile() && e.name.endsWith(".md"),
+    );
+    out.push(...files);
+  }
+  return out;
+}
+
 async function findSkillDirs(root, claudeDirs) {
   const out = [];
   for (const d of claudeDirs) {
@@ -133,7 +147,7 @@ async function buildLayers(root) {
         id: "L2",
         name: "JTBD.md",
         maxLines: 320,
-        // Bumped from 1408 in spec 1010 to absorb a fifth persona block.
+        // Larger than the L2 default to absorb a fifth persona block.
         maxWords: 1664,
         files: ["JTBD.md"],
       },
@@ -146,13 +160,20 @@ async function buildLayers(root) {
       },
       {
         id: "L4",
+        name: "agent reference",
+        maxLines: 192,
+        maxWords: 1280,
+        files: await findAgentReferences(root, claudeDirs),
+      },
+      {
+        id: "L5",
         name: "skill procedure",
         maxLines: 192,
         maxWords: 1280,
         files: skillDirs.map((d) => `${d}/SKILL.md`),
       },
       {
-        id: "L5",
+        id: "L6",
         name: "skill reference",
         maxLines: 128,
         maxWords: 768,
@@ -162,70 +183,143 @@ async function buildLayers(root) {
   };
 }
 
-async function checkLayer(root, layer, errors) {
-  for (const path of layer.files) {
-    const text = await readText(root, path);
-    if (text == null) continue;
-    const lines = lineCount(text);
-    const words = wordCount(text);
-    if (lines > layer.maxLines) {
-      errors.push(
-        `${path} has ${lines} lines (max ${layer.maxLines}, ${layer.id} ${layer.name})`,
-      );
-    }
-    if (words > layer.maxWords) {
-      errors.push(
-        `${path} has ${words} words (max ${layer.maxWords}, ${layer.id} ${layer.name})`,
-      );
+function offsetToLine(text, offset) {
+  let line = 1;
+  for (let i = 0; i < offset && i < text.length; i++) {
+    if (text.charCodeAt(i) === 10) line++;
+  }
+  return line;
+}
+
+// -- Subject builders ----------------------------------------------------
+
+async function buildFileSubjects(root, layers) {
+  const subjects = [];
+  for (const layer of layers) {
+    for (const relPath of layer.files) {
+      const text = await readText(root, relPath);
+      if (text == null) continue;
+      subjects.push({
+        path: resolve(root, relPath),
+        layer: { id: layer.id, name: layer.name },
+        lines: lineCount(text),
+        words: wordCount(text),
+        maxLines: layer.maxLines,
+        maxWords: layer.maxWords,
+      });
     }
   }
+  return subjects;
 }
 
-async function checkChecklists(root, sources, errors) {
-  for (const path of sources) {
-    const text = await readText(root, path);
+async function buildChecklistSubjects(root, sources) {
+  const subjects = [];
+  for (const relPath of sources) {
+    const text = await readText(root, relPath);
     if (text == null) continue;
+    const absPath = resolve(root, relPath);
+    CHECKLIST_RE.lastIndex = 0;
     let m;
-    let index = 0;
+    let blockIndex = 0;
     while ((m = CHECKLIST_RE.exec(text))) {
-      index += 1;
-      const type = m[1];
+      blockIndex += 1;
       const items = m[2].split(ITEM_SPLIT_RE).slice(1);
-      if (items.length > L6_MAX_ITEMS) {
-        errors.push(
-          `${path} checklist #${index} (${type}) has ${items.length} items (max ${L6_MAX_ITEMS}, L6 checklist)`,
-        );
-      }
-      items.forEach((raw, i) => {
-        const w = wordCount(raw.trim());
-        if (w > L6_MAX_WORDS_PER_ITEM) {
-          errors.push(
-            `${path} checklist #${index} (${type}) item ${i + 1} has ${w} words (max ${L6_MAX_WORDS_PER_ITEM}, L6 checklist item)`,
-          );
-        }
+      subjects.push({
+        path: absPath,
+        lineNo: offsetToLine(text, m.index),
+        type: m[1],
+        blockIndex,
+        items: items.map((raw) => ({ words: wordCount(raw.trim()) })),
       });
     }
   }
+  return subjects;
 }
 
+const HINT_LAYER_BUDGET =
+  "trim prose to fit the layer cap — see COALIGNED.md for the layered-instruction model";
+
+// -- Rule catalogue ------------------------------------------------------
+
+export const INSTRUCTION_RULES = [
+  {
+    id: "instructions.line-budget",
+    scope: "instruction-file",
+    severity: "fail",
+    check: (s) =>
+      s.lines > s.maxLines ? { value: s.lines, max: s.maxLines } : null,
+    message: (s, r) => `${r.value} lines (max ${r.max}, ${s.layer.name})`,
+    hint: HINT_LAYER_BUDGET,
+  },
+  {
+    id: "instructions.word-budget",
+    scope: "instruction-file",
+    severity: "fail",
+    check: (s) =>
+      s.words > s.maxWords ? { value: s.words, max: s.maxWords } : null,
+    message: (s, r) => `${r.value} words (max ${r.max}, ${s.layer.name})`,
+    hint: HINT_LAYER_BUDGET,
+  },
+  {
+    id: "L7.too-many-items",
+    scope: "checklist-block",
+    severity: "fail",
+    check: (s) =>
+      s.items.length > L7_MAX_ITEMS
+        ? { count: s.items.length, max: L7_MAX_ITEMS }
+        : null,
+    message: (s, r) =>
+      `checklist #${s.blockIndex} (${s.type}) has ${r.count} items (max ${r.max})`,
+    hint: "split the checklist into multiple sections, or remove items not load-bearing for the goal",
+  },
+  {
+    id: "L7.item-too-many-words",
+    scope: "checklist-block",
+    severity: "fail",
+    check: (s) => {
+      const offenders = [];
+      s.items.forEach((item, i) => {
+        if (item.words > L7_MAX_WORDS_PER_ITEM) {
+          offenders.push({
+            itemIndex: i + 1,
+            words: item.words,
+            max: L7_MAX_WORDS_PER_ITEM,
+          });
+        }
+      });
+      return offenders.length === 0 ? null : offenders;
+    },
+    message: (s, r) =>
+      `checklist #${s.blockIndex} (${s.type}) item ${r.itemIndex} has ${r.words} words (max ${r.max})`,
+    hint: "rewrite the item more concisely — checklist items are pointers, not explanations",
+  },
+];
+
+// -- Public entry --------------------------------------------------------
+
 /**
- * Walk the repo rooted at `root`, applying the L1–L6 caps from COALIGNED.md.
+ * Walk the repo rooted at `root`, applying the L1–L7 caps from COALIGNED.md.
  * Each layer is gated by a line cap AND a word cap; either breach fails.
  *
  * @param {{ root: string }} options
- * @returns {Promise<string[]>} List of human-readable error messages; empty when the repo is conformant.
+ * @returns {Promise<Finding[]>} Structured findings; empty when conformant.
+ *   Each Finding is `{ id, level, path, lineNo?, message, hint? }` for use
+ *   with `emitFindingsText` / `emitFindingsJson` from libutil.
  */
 export async function checkInstructions({ root }) {
-  const errors = [];
   const { layers, skillDirs } = await buildLayers(root);
-
-  for (const layer of layers) await checkLayer(root, layer, errors);
-
-  const checklistSources = [
+  const fileSubjects = await buildFileSubjects(root, layers);
+  const checklistSubjects = await buildChecklistSubjects(root, [
     "CONTRIBUTING.md",
     ...skillDirs.map((d) => `${d}/SKILL.md`),
-  ];
-  await checkChecklists(root, checklistSources, errors);
+  ]);
 
-  return errors;
+  const ctx = {
+    subjects: {
+      "instruction-file": fileSubjects,
+      "checklist-block": checklistSubjects,
+    },
+  };
+  const resolveScope = (scopeKey) => ctx.subjects[scopeKey] ?? [];
+  return runRules(INSTRUCTION_RULES, ctx, { resolveScope });
 }

package/src/jtbd.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import * as prettier from "prettier";
+import { runRules } from "@forwardimpact/libutil";
 
 const VALID_USERS = [
   "Engineering Leaders",
@@ -55,65 +56,140 @@ function loadPackages(dir, filter) {
   return out.sort((a, b) => a.dir.localeCompare(b.dir));
 }
 
-function validateEntry(entry, prefix) {
-  const errors = [];
-  if (!(entry.user && VALID_USERS.includes(entry.user))) {
-    errors.push(
-      `${prefix}: invalid user "${entry.user}". Must be one of: ${VALID_USERS.join(", ")}`,
-    );
-  }
-  for (const field of ["goal", "trigger", "competesWith"]) {
-    if (!entry[field] || typeof entry[field] !== "string") {
-      errors.push(`${prefix}: ${field} is required and must be a string`);
-    }
-  }
-  for (const field of ["bigHire", "littleHire"]) {
-    if (!entry[field] || typeof entry[field] !== "string") {
-      errors.push(`${prefix}: ${field} is required and must be a string`);
-    } else if (!entry[field].endsWith(".")) {
-      errors.push(`${prefix}: ${field} must end with ".": "${entry[field]}"`);
-    }
-  }
-  return errors;
+function slot(s) {
+  return `.jobs[${s.index}]`;
 }
 
-function checkHireUniqueness(entry, prefix, allHires, loc) {
-  const errors = [];
-  for (const field of ["bigHire", "littleHire"]) {
-    if (!entry[field] || typeof entry[field] !== "string") continue;
-    const key = `${field}:${entry[field].toLowerCase()}`;
-    if (allHires.has(key) && allHires.get(key).goal !== entry.goal) {
-      errors.push(
-        `${prefix}: duplicate ${field} "${entry[field]}" (also in ${allHires.get(key).loc})`,
-      );
-    }
-    allHires.set(key, { loc, goal: entry.goal });
-  }
-  return errors;
-}
+export const JTBD_RULES = [
+  {
+    id: "jtbd.jobs-must-be-array",
+    scope: "package-jobs",
+    severity: "fail",
+    check: (s) => (Array.isArray(s.jobs) ? null : {}),
+    message: () => ".jobs must be an array",
+    hint: "wrap the value in [] — even a single job is an array of one",
+  },
+  {
+    id: "jtbd.invalid-user",
+    scope: "jtbd-entry",
+    severity: "fail",
+    check: (s) =>
+      s.entry.user && VALID_USERS.includes(s.entry.user)
+        ? null
+        : { user: s.entry.user },
+    message: (s, r) => `${slot(s)}: invalid user "${r.user}"`,
+    hint: `must be one of: ${VALID_USERS.join(", ")}`,
+  },
+  {
+    id: "jtbd.missing-field",
+    scope: "jtbd-entry",
+    severity: "fail",
+    check: (s) => {
+      const offenders = [];
+      for (const field of [
+        "goal",
+        "trigger",
+        "competesWith",
+        "bigHire",
+        "littleHire",
+      ]) {
+        if (!s.entry[field] || typeof s.entry[field] !== "string") {
+          offenders.push({ field });
+        }
+      }
+      return offenders.length === 0 ? null : offenders;
+    },
+    message: (s, r) =>
+      `${slot(s)}: ${r.field} is required and must be a string`,
+    hint: "every job entry needs goal, trigger, competesWith, bigHire, and littleHire (hires end with a period)",
+  },
+  {
+    id: "jtbd.hire-missing-period",
+    scope: "jtbd-entry",
+    severity: "fail",
+    check: (s) => {
+      const offenders = [];
+      for (const field of ["bigHire", "littleHire"]) {
+        const v = s.entry[field];
+        if (typeof v === "string" && v.length > 0 && !v.endsWith(".")) {
+          offenders.push({ field, value: v });
+        }
+      }
+      return offenders.length === 0 ? null : offenders;
+    },
+    message: (s, r) =>
+      `${slot(s)}: ${r.field} must end with "." — "${r.value}"`,
+    hint: "append a period to the hire sentence",
+  },
+  {
+    // Cross-entry uniqueness — mutates ctx.allHires across iterations.
+    id: "jtbd.duplicate-hire",
+    scope: "jtbd-entry",
+    severity: "fail",
+    when: (s) => !s.skipUniqueHires,
+    check: (s, ctx) => {
+      const offenders = [];
+      for (const field of ["bigHire", "littleHire"]) {
+        const v = s.entry[field];
+        if (typeof v !== "string" || !v) continue;
+        const key = `${field}:${v.toLowerCase()}`;
+        const prior = ctx.allHires.get(key);
+        if (prior && prior.goal !== s.entry.goal) {
+          offenders.push({ field, value: v, otherLoc: prior.loc });
+        }
+        ctx.allHires.set(key, { loc: s.loc, goal: s.entry.goal });
+      }
+      return offenders.length === 0 ? null : offenders;
+    },
+    message: (s, r) =>
+      `${slot(s)}: duplicate ${r.field} "${r.value}" (also in ${r.otherLoc})`,
+    hint: "merge the duplicate job into a single entry, or differentiate the hire text",
+  },
+];
 
-function validate(packages, dirName, { skipUniqueHires = false } = {}) {
-  const allHires = new Map();
-  const errors = [];
+function buildSubjects(packages, catalogDir, catalogName, skipUniqueHires) {
+  const packageSubjects = [];
+  const entrySubjects = [];
   for (const { dir, pkg } of packages) {
-    const jobs = pkg.jobs;
-    if (!jobs) continue;
-    if (!Array.isArray(jobs)) {
-      errors.push(`${dir}/package.json: .jobs must be an array`);
-      continue;
-    }
-    for (let i = 0; i < jobs.length; i++) {
-      const entry = jobs[i];
-      const prefix = `${dirName}/${dir}/package.json .jobs[${i}]`;
-      errors.push(...validateEntry(entry, prefix));
-      if (!skipUniqueHires) {
-        errors.push(
-          ...checkHireUniqueness(entry, prefix, allHires, `${dirName}/${dir}`),
-        );
-      }
-    }
+    const pkgPath = join(catalogDir, dir, "package.json");
+    if (pkg.jobs == null) continue;
+    packageSubjects.push({ path: pkgPath, jobs: pkg.jobs });
+    if (!Array.isArray(pkg.jobs)) continue;
+    const loc = `${catalogName}/${dir}`;
+    pkg.jobs.forEach((entry, i) => {
+      entrySubjects.push({
+        path: pkgPath,
+        index: i,
+        entry,
+        loc,
+        skipUniqueHires,
+      });
+    });
   }
-  return errors;
+  return { packageSubjects, entrySubjects };
+}
+
+function validate(
+  packages,
+  catalogDir,
+  catalogName,
+  { skipUniqueHires = false } = {},
+) {
+  const { packageSubjects, entrySubjects } = buildSubjects(
+    packages,
+    catalogDir,
+    catalogName,
+    skipUniqueHires,
+  );
+  const ctx = {
+    allHires: new Map(),
+    subjects: {
+      "package-jobs": packageSubjects,
+      "jtbd-entry": entrySubjects,
+    },
+  };
+  const resolveScope = (scopeKey) => ctx.subjects[scopeKey] ?? [];
+  return runRules(JTBD_RULES, ctx, { resolveScope });
 }
 
 function renderTable(headers, rows) {
@@ -340,11 +416,11 @@ function commitUpdate(filePath, label, original, updated, fix, result) {
 
 async function processCatalog(catalog, fix, formatMarkdown, result) {
   const packages = loadPackages(catalog.dir, catalog.filter);
-  const errors = validate(packages, catalog.name, {
+  const findings = validate(packages, catalog.dir, catalog.name, {
     skipUniqueHires: catalog.skipUniqueHires ?? false,
   });
-  if (errors.length > 0) {
-    result.errors.push(...errors);
+  if (findings.length > 0) {
+    result.findings.push(...findings);
     return;
   }
 
@@ -394,9 +470,11 @@ async function processJtbdMd(root, fix, formatMarkdown, result) {
   if (!existsSync(jtbdPath)) return;
   const productsCatalog = catalogs(root).find((c) => c.name === "products");
   const packages = loadPackages(productsCatalog.dir, productsCatalog.filter);
-  const errors = validate(packages, "products", { skipUniqueHires: true });
-  if (errors.length > 0) {
-    if (result.errors.length === 0) result.errors.push(...errors);
+  const findings = validate(packages, productsCatalog.dir, "products", {
+    skipUniqueHires: true,
+  });
+  if (findings.length > 0) {
+    if (result.findings.length === 0) result.findings.push(...findings);
     return;
   }
   const original = readFileSync(jtbdPath, "utf8");
@@ -412,13 +490,14 @@ async function processJtbdMd(root, fix, formatMarkdown, result) {
  * jobs, and description blocks in the corresponding README.md and JTBD.md.
  *
  * @param {{ root: string, fix?: boolean }} options
- * @returns {Promise<{ errors: string[], stale: string[], fixed: string[] }>}
- *   `errors` are validation failures; `stale` is files whose generated blocks
+ * @returns {Promise<{ findings: Finding[], stale: string[], fixed: string[] }>}
+ *   `findings` are validation failures (structured for `emitFindingsText` /
+ *   `emitFindingsJson` from libutil); `stale` is files whose generated blocks
  *   are out of date (only populated when `fix` is false); `fixed` is files
  *   that were rewritten in place.
  */
 export async function checkJtbd({ root, fix = false }) {
-  const result = { errors: [], stale: [], fixed: [] };
+  const result = { findings: [], stale: [], fixed: [] };
   const prettierConfig = await prettier.resolveConfig(join(root, "JTBD.md"));
   const formatMarkdown = makeFormatter(prettierConfig);