@forwardimpact/libcoaligned 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Dick Olsson
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,27 @@
+# libcoaligned
+
+<!-- BEGIN:description — Do not edit. Generated from package.json. -->
+
+Co-Aligned architecture checks — enforce instruction-layer length caps and JTBD
+invariants across the repo.
+
+<!-- END:description -->
+
+## Getting Started
+
+```sh
+npx coaligned                   # run every check (instructions + jtbd)
+npx coaligned instructions      # enforce L1–L6 length and checklist caps
+npx coaligned jtbd              # validate JTBD entries against package.json
+npx coaligned jtbd --fix        # regenerate catalog and job blocks in place
+```
+
+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.
+- `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

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs";
+import { createCli } from "@forwardimpact/libcli";
+import { checkInstructions, checkJtbd } from "../src/index.js";
+
+const { version: VERSION } = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+);
+
+const definition = {
+  name: "coaligned",
+  version: VERSION,
+  description:
+    "Enforce the layered instruction architecture defined in COALIGNED.md (no subcommand: run every check)",
+  commands: [
+    {
+      name: "instructions",
+      args: [],
+      description: "Check L1–L6 length and checklist caps across the repo",
+      handler: instructionsHandler,
+      examples: ["coaligned instructions"],
+    },
+    {
+      name: "jtbd",
+      args: [],
+      description: "Validate package.json .jobs entries and generated blocks",
+      options: {
+        fix: {
+          type: "boolean",
+          description: "Regenerate stale catalog and jobs blocks in place",
+        },
+      },
+      handler: jtbdHandler,
+      examples: ["coaligned jtbd", "coaligned jtbd --fix"],
+    },
+  ],
+  globalOptions: {
+    help: { type: "boolean", short: "h", description: "Show this help" },
+    version: { type: "boolean", description: "Show version" },
+    json: { type: "boolean", description: "Output help 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;
+}
+
+async function runJtbd(root, fix) {
+  const { errors, stale, fixed } = await checkJtbd({ root, fix });
+  for (const e of errors) process.stderr.write(`${e}\n`);
+  for (const f of fixed) process.stdout.write(`Regenerated ${f}.\n`);
+  for (const s of stale) {
+    process.stderr.write(
+      `${s} out of date. Run \`coaligned jtbd --fix\` to regenerate.\n`,
+    );
+  }
+  return errors.length > 0 || stale.length > 0 ? 1 : 0;
+}
+
+async function instructionsHandler(ctx) {
+  return runInstructions(ctx.data.root);
+}
+
+async function jtbdHandler(ctx) {
+  return runJtbd(ctx.data.root, !!ctx.options.fix);
+}
+
+async function main() {
+  const parsed = cli.parse(process.argv.slice(2));
+  if (!parsed) return 0;
+
+  const root = process.cwd();
+
+  // 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);
+    return a || b;
+  }
+
+  const known = definition.commands.map((c) => c.name);
+  if (!known.includes(parsed.positionals[0])) {
+    cli.usageError(`unknown command "${parsed.positionals[0]}"`);
+    return 2;
+  }
+
+  return await cli.dispatch(parsed, { data: { root } });
+}
+
+main()
+  .then((code) => process.exit(code ?? 0))
+  .catch((err) => {
+    cli.error(err.message);
+    process.exit(1);
+  });

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@forwardimpact/libcoaligned",
+  "version": "0.1.0",
+  "description": "Co-Aligned architecture checks — enforce instruction-layer length caps and JTBD invariants across the repo.",
+  "keywords": [
+    "coaligned",
+    "instructions",
+    "jtbd",
+    "checklist",
+    "agent"
+  ],
+  "homepage": "https://www.forwardimpact.team",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/forwardimpact/monorepo.git",
+    "directory": "libraries/libcoaligned"
+  },
+  "license": "Apache-2.0",
+  "author": "D. Olsson <hi@senzilla.io>",
+  "jobs": [
+    {
+      "user": "Platform Builders",
+      "goal": "Keep Instruction Layers Honest",
+      "trigger": "Editing a CLAUDE.md or skill procedure and realizing the layer has quietly grown past its budget.",
+      "bigHire": "enforce instruction-layer length caps and JTBD invariants without hand-rolling repo checks.",
+      "littleHire": "verify a docs change before commit and trust the layered architecture has not drifted.",
+      "competesWith": "ad-hoc shell scripts; eyeballing word counts; tolerating slow drift in the instruction architecture"
+    }
+  ],
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./bin/coaligned.js": "./bin/coaligned.js"
+  },
+  "bin": {
+    "coaligned": "./bin/coaligned.js"
+  },
+  "files": [
+    "src/**/*.js",
+    "bin/**/*.js",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "bun test test/*.test.js"
+  },
+  "dependencies": {
+    "@forwardimpact/libcli": "^0.1.9",
+    "prettier": "^3.0.0"
+  },
+  "engines": {
+    "bun": ">=1.2.0",
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.js

@@ -0,0 +1,2 @@
+export { checkInstructions } from "./instructions.js";
+export { checkJtbd } from "./jtbd.js";

package/src/instructions.js

@@ -0,0 +1,220 @@
+import { readFile, readdir } from "node:fs/promises";
+import { resolve } from "node:path";
+
+const SKIP_DIRS = new Set([
+  ".cache",
+  ".git",
+  "build",
+  "dist",
+  "generated",
+  "node_modules",
+  "tmp",
+  "wiki",
+  "worktrees",
+]);
+
+const L6_MAX_ITEMS = 9;
+const L6_MAX_WORDS_PER_ITEM = 32;
+
+const CHECKLIST_RE =
+  /<(read_do_checklist|do_confirm_checklist)\b[^>]*>([\s\S]*?)<\/\1>/g;
+const ITEM_SPLIT_RE = /^\s*-\s*\[[ xX]\]\s*/m;
+
+const lineCount = (text) => (text.match(/\n/g) || []).length;
+const wordCount = (text) => (text.match(/\S+/g) || []).length;
+
+async function walk(root, dir, visit) {
+  let entries;
+  try {
+    entries = await readdir(resolve(root, dir), { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    if (SKIP_DIRS.has(e.name)) continue;
+    const path = dir === "." ? e.name : `${dir}/${e.name}`;
+    await visit(e, path);
+    if (e.isDirectory()) await walk(root, path, visit);
+  }
+}
+
+async function listFiles(root, dir, match) {
+  try {
+    const entries = await readdir(resolve(root, dir), { withFileTypes: true });
+    return entries.filter(match).map((e) => `${dir}/${e.name}`);
+  } catch {
+    return [];
+  }
+}
+
+async function readText(root, path) {
+  try {
+    return await readFile(resolve(root, path), "utf8");
+  } catch {
+    return null;
+  }
+}
+
+async function findByName(root, name, kind) {
+  const out = [];
+  await walk(root, ".", (e, path) => {
+    const isMatch = kind === "file" ? e.isFile() : e.isDirectory();
+    if (isMatch && e.name === name) out.push(path);
+  });
+  return out;
+}
+
+async function findAgentProfiles(root, claudeDirs) {
+  const out = [];
+  for (const d of claudeDirs) {
+    const files = await listFiles(
+      root,
+      `${d}/agents`,
+      (e) => e.isFile() && e.name.endsWith(".md"),
+    );
+    out.push(...files);
+  }
+  return out;
+}
+
+async function findSkillDirs(root, claudeDirs) {
+  const out = [];
+  for (const d of claudeDirs) {
+    const dirs = await listFiles(root, `${d}/skills`, (e) => e.isDirectory());
+    out.push(...dirs);
+  }
+  return out;
+}
+
+async function findSkillReferences(root, skillDirs) {
+  const out = [];
+  for (const d of skillDirs) {
+    const files = await listFiles(
+      root,
+      `${d}/references`,
+      (e) => e.isFile() && e.name.endsWith(".md"),
+    );
+    out.push(...files);
+  }
+  return out;
+}
+
+async function buildLayers(root) {
+  const claudeDirs = await findByName(root, ".claude", "dir");
+  const skillDirs = await findSkillDirs(root, claudeDirs);
+  return {
+    skillDirs,
+    layers: [
+      {
+        id: "L1",
+        name: "CLAUDE.md",
+        maxLines: 192,
+        maxWords: 896,
+        files: await findByName(root, "CLAUDE.md", "file"),
+      },
+      {
+        id: "L2",
+        name: "CONTRIBUTING.md",
+        maxLines: 320,
+        maxWords: 1408,
+        files: ["CONTRIBUTING.md"],
+      },
+      {
+        id: "L2",
+        name: "JTBD.md",
+        maxLines: 320,
+        maxWords: 1408,
+        files: ["JTBD.md"],
+      },
+      {
+        id: "L3",
+        name: "agent profile",
+        maxLines: 64,
+        maxWords: 384,
+        files: await findAgentProfiles(root, claudeDirs),
+      },
+      {
+        id: "L4",
+        name: "skill procedure",
+        maxLines: 192,
+        maxWords: 1280,
+        files: skillDirs.map((d) => `${d}/SKILL.md`),
+      },
+      {
+        id: "L5",
+        name: "skill reference",
+        maxLines: 128,
+        maxWords: 768,
+        files: await findSkillReferences(root, skillDirs),
+      },
+    ],
+  };
+}
+
+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})`,
+      );
+    }
+  }
+}
+
+async function checkChecklists(root, sources, errors) {
+  for (const path of sources) {
+    const text = await readText(root, path);
+    if (text == null) continue;
+    let m;
+    let index = 0;
+    while ((m = CHECKLIST_RE.exec(text))) {
+      index += 1;
+      const type = m[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)`,
+          );
+        }
+      });
+    }
+  }
+}
+
+/**
+ * Walk the repo rooted at `root`, applying the L1–L6 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.
+ */
+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 = [
+    "CONTRIBUTING.md",
+    ...skillDirs.map((d) => `${d}/SKILL.md`),
+  ];
+  await checkChecklists(root, checklistSources, errors);
+
+  return errors;
+}

package/src/jtbd.js

@@ -0,0 +1,430 @@
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import * as prettier from "prettier";
+
+const VALID_USERS = [
+  "Engineering Leaders",
+  "Empowered Engineers",
+  "Platform Builders",
+];
+
+const USER_ORDER = new Map(VALID_USERS.map((u, i) => [u, i]));
+
+function catalogs(root) {
+  return [
+    {
+      name: "products",
+      dir: join(root, "products"),
+      readme: join(root, "products", "README.md"),
+      filter: (name) => !name.startsWith(".") && name !== "node_modules",
+      column: "Product",
+      skipUniqueHires: true,
+    },
+    {
+      name: "services",
+      dir: join(root, "services"),
+      readme: join(root, "services", "README.md"),
+      filter: (name) => !name.startsWith(".") && name !== "node_modules",
+      column: "Service",
+    },
+    {
+      name: "libraries",
+      dir: join(root, "libraries"),
+      readme: join(root, "libraries", "README.md"),
+      filter: (name) => name.startsWith("lib"),
+      column: "Library",
+    },
+  ];
+}
+
+function loadPackages(dir, filter) {
+  if (!existsSync(dir)) return [];
+  const out = [];
+  for (const name of readdirSync(dir)) {
+    if (!filter(name)) continue;
+    const pkgPath = join(dir, name, "package.json");
+    let pkg;
+    try {
+      pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    } catch {
+      continue;
+    }
+    out.push({ dir: name, pkg });
+  }
+  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 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;
+}
+
+function validate(packages, dirName, { skipUniqueHires = false } = {}) {
+  const allHires = new Map();
+  const errors = [];
+  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}`),
+        );
+      }
+    }
+  }
+  return errors;
+}
+
+function renderTable(headers, rows) {
+  const widths = headers.map((h, i) =>
+    Math.max(h.length, ...rows.map((r) => r[i].length)),
+  );
+  const line = (cells) =>
+    `| ${cells.map((c, i) => c.padEnd(widths[i])).join(" | ")} |`;
+  return [
+    line(headers),
+    line(widths.map((w) => "-".repeat(w))),
+    ...rows.map(line),
+  ].join("\n");
+}
+
+function findMarker(content, tag) {
+  const pattern = new RegExp(`<!--\\s*${tag}[^>]*-->`);
+  const match = content.match(pattern);
+  if (!match) return null;
+  return { text: match[0], index: match.index };
+}
+
+function replaceBlock(content, beginTag, endTag, body) {
+  const begin = findMarker(content, beginTag);
+  const end = findMarker(content, endTag);
+  if (!(begin && end) || end.index < begin.index) return null;
+  return (
+    content.slice(0, begin.index) +
+    `${begin.text}\n\n${body}\n\n${end.text}` +
+    content.slice(end.index + end.text.length)
+  );
+}
+
+function mergeTriggers(triggers) {
+  const stripped = triggers.map((t) => t.replace(/\.\s*$/, "").trim());
+  const unique = [...new Set(stripped)];
+  const parts = unique.map((s, i) =>
+    i > 0 ? s.charAt(0).toLowerCase() + s.slice(1) : s,
+  );
+  return parts.join("; ") + ".";
+}
+
+function mergeCompetesWith(fragments) {
+  if (fragments.length === 0) return null;
+  const seen = new Set();
+  const unique = [];
+  for (const f of fragments) {
+    const normalized = f.replace(/\.\s*$/, "").trim();
+    const key = normalized.toLowerCase();
+    if (!seen.has(key)) {
+      seen.add(key);
+      unique.push(normalized);
+    }
+  }
+  return unique.join("; ") + ".";
+}
+
+function mergeHireField(entries, capitalize) {
+  if (entries.length === 0) return null;
+  const stripped = entries.map((e) => e.text.replace(/\.\s*$/, "").trim());
+  const unique = [...new Set(stripped)];
+  const parts = unique.map((s, i) =>
+    i > 0 ? s.charAt(0).toLowerCase() + s.slice(1) : s,
+  );
+  const pkgs = [...new Set(entries.map((e) => e.pkg))];
+  const names = pkgs.map((p) =>
+    capitalize ? p.charAt(0).toUpperCase() + p.slice(1) : p,
+  );
+  return `Help me ${parts.join("; ")}. → **${names.join(", ")}**`;
+}
+
+function addEntryToGroup(group, entry, dir) {
+  if (entry.trigger) group.triggers.push(entry.trigger);
+  if (entry.bigHire) group.bigHires.push({ text: entry.bigHire, pkg: dir });
+  if (entry.littleHire)
+    group.littleHires.push({ text: entry.littleHire, pkg: dir });
+  if (entry.competesWith) {
+    for (const fragment of entry.competesWith.split(";")) {
+      const trimmed = fragment.trim();
+      if (trimmed) group.competesWith.push(trimmed);
+    }
+  }
+  if (entry.forces && !group.forces) group.forces = entry.forces;
+  if (entry.firedWhen && !group.firedWhen) group.firedWhen = entry.firedWhen;
+}
+
+function collectJobGroups(packages) {
+  const groups = new Map();
+  for (const { dir, pkg } of packages) {
+    if (!pkg.jobs) continue;
+    for (const entry of pkg.jobs) {
+      const key = `${entry.user}\0${entry.goal}`;
+      if (!groups.has(key)) {
+        groups.set(key, {
+          user: entry.user,
+          goal: entry.goal,
+          triggers: [],
+          bigHires: [],
+          littleHires: [],
+          competesWith: [],
+          forces: null,
+          firedWhen: null,
+        });
+      }
+      addEntryToGroup(groups.get(key), entry, dir);
+    }
+  }
+  return groups;
+}
+
+function buildJobProse(group, capitalize) {
+  const trigger = mergeTriggers(group.triggers);
+  const competesWith = mergeCompetesWith(group.competesWith);
+  const bigHire = mergeHireField(group.bigHires, capitalize);
+  const littleHire = mergeHireField(group.littleHires, capitalize);
+
+  const lines = [
+    `## ${group.user}: ${group.goal}`,
+    "",
+    `**Trigger:** ${trigger}`,
+  ];
+  if (bigHire) lines.push("", `**Big Hire:** ${bigHire}`);
+  if (littleHire) lines.push("", `**Little Hire:** ${littleHire}`);
+  lines.push("", `**Competes With:** ${competesWith}`);
+
+  if (group.forces) {
+    lines.push(
+      "",
+      "**Forces:**",
+      `- **Push:** ${group.forces.push}`,
+      `- **Pull:** ${group.forces.pull}`,
+      `- **Habit:** ${group.forces.habit}`,
+      `- **Anxiety:** ${group.forces.anxiety}`,
+    );
+  }
+  if (group.firedWhen) lines.push("", `**Fired When:** ${group.firedWhen}`);
+  return lines.join("\n");
+}
+
+function makeFormatter(prettierConfig) {
+  return async function formatMarkdown(text) {
+    const formatted = await prettier.format(text, {
+      ...prettierConfig,
+      parser: "markdown",
+    });
+    // Prettier inserts a blank line between bold labels and bullet lists;
+    // remove it to match the hand-written JTBD.md style.
+    return formatted.replace(/\*\*\n\n(- )/g, "**\n$1").trimEnd();
+  };
+}
+
+async function buildCatalog(content, packages, column, formatMarkdown) {
+  const rows = packages
+    .filter(({ pkg }) => pkg.description)
+    .map(({ dir, pkg }) => [`**${dir}**`, pkg.description]);
+  if (rows.length === 0) return content;
+  const body = await formatMarkdown(renderTable([column, "Description"], rows));
+  return replaceBlock(content, "BEGIN:catalog", "END:catalog", body) ?? content;
+}
+
+async function buildJobs(
+  content,
+  packages,
+  formatMarkdown,
+  { capitalize = false } = {},
+) {
+  const groups = collectJobGroups(packages);
+  if (groups.size === 0) return content;
+
+  const sorted = [...groups.values()].sort((a, b) => {
+    const ua = USER_ORDER.get(a.user) ?? 99;
+    const ub = USER_ORDER.get(b.user) ?? 99;
+    if (ua !== ub) return ua - ub;
+    return a.goal.localeCompare(b.goal);
+  });
+
+  const blocks = await Promise.all(
+    sorted.map(async (group) => {
+      const formatted = await formatMarkdown(buildJobProse(group, capitalize));
+      return `<job user="${group.user}" goal="${group.goal}">\n\n${formatted}\n\n</job>`;
+    }),
+  );
+
+  const body = blocks.join("\n\n");
+  return replaceBlock(content, "BEGIN:jobs", "END:jobs", body) ?? content;
+}
+
+async function buildDescription(content, description, formatMarkdown) {
+  const formatted = await formatMarkdown(description);
+  const result = replaceBlock(
+    content,
+    "BEGIN:description",
+    "END:description",
+    formatted,
+  );
+  if (result !== null) return result;
+
+  const headingMatch = content.match(/^# .+\n/);
+  if (!headingMatch) return null;
+  const headingEnd = headingMatch[0].length;
+  const nextSection = content.indexOf("\n\n## ", headingEnd);
+  const descEnd = nextSection !== -1 ? nextSection : content.length;
+
+  const begin =
+    "<!-- BEGIN:description — Do not edit. Generated from package.json. -->";
+  const end = "<!-- END:description -->";
+
+  return (
+    content.slice(0, headingEnd) +
+    `\n${begin}\n\n${formatted}\n\n${end}` +
+    content.slice(descEnd)
+  );
+}
+
+function commitUpdate(filePath, label, original, updated, fix, result) {
+  if (updated === null || updated === original) return;
+  if (!fix) {
+    result.stale.push(label);
+    return;
+  }
+  writeFileSync(filePath, updated);
+  result.fixed.push(label);
+}
+
+async function processCatalog(catalog, fix, formatMarkdown, result) {
+  const packages = loadPackages(catalog.dir, catalog.filter);
+  const errors = validate(packages, catalog.name, {
+    skipUniqueHires: catalog.skipUniqueHires ?? false,
+  });
+  if (errors.length > 0) {
+    result.errors.push(...errors);
+    return;
+  }
+
+  if (existsSync(catalog.readme)) {
+    const original = readFileSync(catalog.readme, "utf8");
+    let content = original;
+    content = await buildCatalog(
+      content,
+      packages,
+      catalog.column,
+      formatMarkdown,
+    );
+    content = await buildJobs(content, packages, formatMarkdown);
+    commitUpdate(
+      catalog.readme,
+      `${catalog.name}/README.md`,
+      original,
+      content,
+      fix,
+      result,
+    );
+  }
+
+  for (const { dir, pkg } of packages) {
+    if (!pkg.description) continue;
+    const pkgReadme = join(catalog.dir, dir, "README.md");
+    if (!existsSync(pkgReadme)) continue;
+    const original = readFileSync(pkgReadme, "utf8");
+    const updated = await buildDescription(
+      original,
+      pkg.description,
+      formatMarkdown,
+    );
+    commitUpdate(
+      pkgReadme,
+      `${catalog.name}/${dir}/README.md`,
+      original,
+      updated,
+      fix,
+      result,
+    );
+  }
+}
+
+async function processJtbdMd(root, fix, formatMarkdown, result) {
+  const jtbdPath = join(root, "JTBD.md");
+  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);
+    return;
+  }
+  const original = readFileSync(jtbdPath, "utf8");
+  const updated = await buildJobs(original, packages, formatMarkdown, {
+    capitalize: true,
+  });
+  commitUpdate(jtbdPath, "JTBD.md", original, updated, fix, result);
+}
+
+/**
+ * Validate every `package.json .jobs` entry under products/, services/, and
+ * libraries/, and (when `fix` is true) regenerate the marker-delimited catalog,
+ * 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
+ *   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 prettierConfig = await prettier.resolveConfig(join(root, "JTBD.md"));
+  const formatMarkdown = makeFormatter(prettierConfig);
+
+  for (const catalog of catalogs(root)) {
+    await processCatalog(catalog, fix, formatMarkdown, result);
+  }
+  await processJtbdMd(root, fix, formatMarkdown, result);
+
+  return result;
+}