@forwardimpact/libinvariant 0.2.0 → 0.2.1

package/README.md

@@ -10,9 +10,9 @@ directory.
 
 ## Getting Started
 
-libinvariant is an import-only library: it ships no CLI. To run the checks,
-hire the Jidoka product — `npx @forwardimpact/jidoka` or the installed
-`jidoka` binary — which wires these handlers to a command surface.
+libinvariant is an import-only library. It ships no CLI. To run the checks,
+hire the Jidoka product. Use `npx @forwardimpact/jidoka` or the installed
+`jidoka` binary. The product wires these handlers to a command surface.
 
 ```js
 import {
@@ -30,26 +30,26 @@ const ruleFindings = await checkInvariants({
 });
 ```
 
-The `checkInstructions` and `checkJtbd` handlers implement the contract
-described in
-[JIDOKA.md](https://github.com/forwardimpact/monorepo/blob/main/JIDOKA.md):
+The `checkInstructions` and `checkJtbd` handlers implement the contract that
+[JIDOKA.md](https://github.com/forwardimpact/monorepo/blob/main/JIDOKA.md)
+describes:
 
-- `checkInstructions` — every layer (L1 CLAUDE.md, L2 CONTRIBUTING.md /
-  JTBD.md, 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.
-- `checkJtbd` — 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.
+- `checkInstructions` — a line cap **and** a word cap gate every layer (L1
+  CLAUDE.md, L2 CONTRIBUTING.md / JTBD.md, L3 agent profile, L4 agent
+  reference, L5 SKILL.md, L6 skill reference, L7 checklist block). Either
+  breach fails.
+- `checkJtbd` — the handler validates each `package.json .jobs` entry against
+  the JTBD schema. With `fix`, it regenerates the marker-delimited blocks in
+  `<dir>/README.md`, `<dir>/<pkg>/README.md`, and root `JTBD.md`.
 
 ## Invariants
 
 `checkInvariants` is a generic host for a repository's own invariant checks.
-It loads every `*.rules.mjs` module under the caller-supplied `rulesDir` and
+It loads every `*.rules.mjs` module under the caller-supplied `rulesDir`. It
 runs each module's declarative rule catalogue through the shared rules
-engine. The library carries no discovery default — the calling product or
-script names the directory (the Jidoka CLI supplies `.jidoka/invariants`).
-The policies stay in the repository; the library ships only the engine.
+engine. The library carries no discovery default. The product or script that
+calls it names the directory (the Jidoka CLI supplies `.jidoka/invariants`).
+The policies stay in the repository. The library ships only the engine.
 
 A rule module's default export is:
 
@@ -79,15 +79,15 @@ export default {
 ### The build kit
 
 The engine binds a kit per run to the repo `root`, the module's own `dir`
-(for co-located config), and the `runtime` bag (fs and ripgrep route through
-it, so the engine carries no ambient dependencies). The module declares only
-policy; the kit owns the mechanism:
+(for co-located config), and the `runtime` bag. fs and ripgrep route through
+the bag, so the engine carries no ambient dependencies. The module declares
+only policy. The kit owns the mechanism:
 
 - `scan({ dirs, match, skip?, under?, read? })` — collect files as
-  `{ path, rel, text? }`; `under` restricts to the per-package `src`/`test`
+  `{ path, rel, text? }`. `under` restricts to the per-package `src`/`test`
   shape.
 - `scanAst({ dirs, match, extract, locations?, … })` — read + parse each file
-  and merge `extract(ast)`; a parse failure becomes `{ path, rel, parseError }`.
+  and merge `extract(ast)`. A parse failure becomes `{ path, rel, parseError }`.
 - `parse(src, path, opts?)`, `walk(ast, visit)` — the lower-level AST seam.
 - `grep({ pattern | patterns, paths?, globs?, caseSensitive?, onlyMatching?,
   dedupe? })` — ripgrep matches as `{ path, lineNo, text, reason? }`, with
@@ -95,10 +95,10 @@ policy; the kit owns the mechanism:
 - `restatementDrift({ entries, equal })` — the shared "single source restated
   across consumers" scan + compare (service URLs, scalar values).
 - `enumDrift.build(registry)` / `enumDrift.seed(registry)` — the
-  enumeration-drift engine: assert (or seed) that every consumer's fenced
-  `<!-- enum:TOPIC:PROPERTY -->` block matches its source-of-truth set (an
-  fs-glob or md-table probe). Pass a parsed topics registry (e.g.
-  `config(topicsFile)`); pair with the rule kit's `enumDriftRules`.
+  enumeration-drift engine. It asserts (or seeds) that every consumer's
+  fenced `<!-- enum:TOPIC:PROPERTY -->` block matches its source-of-truth set
+  (an fs-glob or md-table probe). Pass a parsed topics registry (e.g.
+  `config(topicsFile)`). Pair it with the rule kit's `enumDriftRules`.
 - `readText`, `readJson`, `config(name, fallback?)` (co-located JSON/YAML),
   `listDir(path, { dirsOnly? })`.
 - `lineAt(text, offset)`, `glob(pattern)`.
@@ -107,30 +107,30 @@ policy; the kit owns the mechanism:
 
 When `rules` is a function it receives the rule helpers:
 
-- `parseError(scope, { id?, hint? })` — fails any subject carrying a
-  `parseError` (paired with `scanAst`).
+- `parseError(scope, { id?, hint? })` — fails any subject that carries a
+  `parseError` (pair it with `scanAst`).
 - `failAll(scope, { id, message, hint?, when? })` — fails every subject in
   scope (the build step already decided each is a violation).
-- `enumDriftRules` — the enumeration-drift rule set, paired with the build
-  kit's `enumDrift` (expose via `rules: (kit) => kit.enumDriftRules`).
+- `enumDriftRules` — the enumeration-drift rule set. Pair it with the build
+  kit's `enumDrift` (expose it with `rules: (kit) => kit.enumDriftRules`).
 
 Findings render in the same ESLint-style format across the handlers
-(`emitFindingsJson` for machine output); any finding fails the run.
+(`emitFindingsJson` for machine output). Any finding fails the run.
 
 ## Documentation home
 
 libinvariant shares the **Run a Predictable Platform** job goal with the
-service-lifecycle libraries (librc, libsupervise, libtelemetry, libpreflight),
-but its full guide home is the Jidoka standard at
-<https://www.jidoka.team/> and [JIDOKA.md](../../JIDOKA.md), not the
-service-lifecycle guide tree under `websites/fit/docs/libraries/`.
-
-**Decision (2026-06-27):** this is deliberate scope separation, not a gap. The
-invariant checks run at **authoring time** against a repository's instruction
-layers and JTBD blocks; the service-lifecycle libraries run at **service
-runtime** against a live process. Mixing the two into one guide would blur the
+service-lifecycle libraries (librc, libsupervise, libtelemetry, libpreflight).
+Its full guide home is the Jidoka standard at <https://www.jidoka.team/> and
+[JIDOKA.md](../../JIDOKA.md). The service-lifecycle guide tree under
+`websites/fit/docs/libraries/` is not its guide home.
+
+**Decision (2026-06-27):** this scope separation is deliberate. It is not a
+gap. The invariant checks run at **authoring time** against a repository's
+instruction layers and JTBD blocks. The service-lifecycle libraries run at
+**service runtime** against a live process. One guide for both would blur the
 audience. The service-lifecycle Big Hire carries a one-line cross-link to the
-Jidoka standard so a reader who lands there can find this check, and that is
-the only link the service-lifecycle tree should carry. Future doc audits should
+Jidoka standard, so a reader who lands there can find this check. The
+service-lifecycle tree should carry no other link. In a future doc audit,
 treat the absence of a service-lifecycle guide page for the invariant checks
 as intended.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libinvariant",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Repository invariant checks — instruction-layer length caps, JTBD block validation, and a declarative rule-module runner over a caller-supplied rules directory.",
   "keywords": [
     "invariants",
@@ -43,8 +43,8 @@
   "dependencies": {
     "@forwardimpact/libcli": "^0.1.9",
     "@forwardimpact/libutil": "*",
-    "acorn": "^8.17.0",
-    "prettier": "^3.8.4",
+    "acorn": "^8.18.0",
+    "prettier": "^3.9.6",
     "yaml": "^2.9.0"
   },
   "devDependencies": {

package/src/enum-drift-grammar.js

@@ -1,15 +1,15 @@
 // The enumeration-drift grammar: source probes (fs-glob, md-table), the
 // list/count value extractors, and the fenced-block consumer parser. These are
-// the reusable mechanics the invariant kit injects as `kit.enumDrift`; they
-// carry no policy. Filesystem access is passed in (`fsSync`) rather than
-// imported, so this module stays clean under the repo's ambient-deps invariant;
-// the orchestration that binds them lives in enum-drift.js.
+// the reusable mechanics the invariant kit injects as `kit.enumDrift`. They
+// carry no policy. The caller passes filesystem access in (`fsSync`) instead of
+// an import, so this module stays clean under the repo's ambient-deps
+// invariant. The orchestration that binds them lives in enum-drift.js.
 
 import { isAbsolute, join } from "node:path";
 
 export const VALID_PROPERTIES = new Set(["count", "list"]);
 
-/** Reject a pattern/file that escapes `root` (absolute or `..`); else null.
+/** Reject a pattern/file that escapes `root` (absolute or `..`), else null.
  *
  * @param {string} pattern - A repo-relative source pattern or file path.
  * @returns {string|null} An error message, or null when contained.
@@ -59,7 +59,7 @@ function splitGlob(pattern) {
   return { fixed: segments.slice(0, i), tail: segments.slice(i) };
 }
 
-/** Walk `tail`-deep below `dir`, matching each level, collecting ids. */
+/** Walk `tail`-deep below `dir`. Match each level and collect ids. */
 function walkGlob(dir, tail, fixed, relParts, id, excludeSet, ids, fsSync) {
   if (relParts.length === tail.length) {
     const base = relParts[relParts.length - 1];
@@ -119,8 +119,8 @@ export function probeFsGlob(source, root, fsSync) {
 // --- md-table probe --------------------------------------------------------
 
 /**
- * Reduce a composite-action cell to its bare slug. Unwraps a leading
- * `[text](url)` markdown link to its link text, then drops backticks, the
+ * Reduce a composite-action cell to its bare slug. Unwrap a leading
+ * `[text](url)` markdown link to its link text. Then drop backticks, the
  * `forwardimpact/` scope, and a trailing `@version`.
  *
  * @param {string} cell - A raw table cell.
@@ -157,8 +157,8 @@ export function parseTableRow(line) {
     .map((c) => c.trim());
 }
 
-// The table rows under a `## <section>` heading, up to the next heading,
-// skipping fenced-code regions. Returns parsed cell-arrays (header included).
+// The table rows under a `## <section>` heading, up to the next heading. This
+// skips fenced-code regions and returns parsed cell-arrays (header included).
 function sectionTableRows(lines, section) {
   const headingRe = new RegExp(`^#{1,6}\\s+${escapeRegExp(section)}\\s*$`);
   let i = lines.findIndex((l) => headingRe.test(l));
@@ -178,7 +178,7 @@ function sectionTableRows(lines, section) {
   return rows;
 }
 
-/** Probe a md-table source: filtered column cells under a section heading.
+/** Probe a md-table source for filtered column cells under a section heading.
  *
  * @param {{ file: string, section: string, column: string, filter: string }} source
  * @param {string} root - Repository root.
@@ -351,8 +351,8 @@ function bulletTokens(lines) {
   return out;
 }
 
-// First non-empty cell of each GFM data row, dropping the header (the row right
-// before the `|---|` alignment row).
+// First non-empty cell of each GFM data row. This drops the header (the row
+// right before the `|---|` alignment row).
 function tableIds(lines) {
   const rows = [];
   let alignmentAt = -1;
@@ -380,7 +380,7 @@ function tableIds(lines) {
   return ids;
 }
 
-// ASCII-tree leaf `name/  desc` — the trailing slash distinguishes a directory
+// ASCII-tree leaf `name/  desc`. The trailing slash distinguishes a directory
 // leaf from a prose sentence whose first word is capitalized.
 function treeIds(lines) {
   const ids = new Set();
@@ -396,10 +396,10 @@ function treeIds(lines) {
 
 // A bare comma/space-separated run of inline code spans and nothing else, e.g.
 // `a`, `b`, `c`. Returns the code-span tokens, or null when the span carries
-// any other text (prose, a bullet marker, an item description). That ambiguity
-// — commas inside a description versus commas between items — is exactly what
-// the bracketed shapes resolve, so this fires only when the whole span is code
-// spans plus separators, and needs at least two so a lone token is not a list.
+// any other text (prose, a bullet marker, an item description). Commas inside
+// a description look like commas between items. The bracketed shapes resolve
+// exactly that ambiguity. So this fires only when the whole span is code spans
+// plus separators. It needs at least two, so a lone token is not a list.
 function inlineCodeSpanList(span) {
   const t = span.trim();
   const spans = t.match(/`[^`]+`/g);
@@ -411,8 +411,8 @@ function inlineCodeSpanList(span) {
 /**
  * Identifier set from a list-shaped span. Precedence: brace expansion, bullets,
  * a bare comma/space-separated run of code spans, GFM table, ASCII tree, then a
- * parenthetical comma-list (last resort, since a bullet/tree leaf often carries
- * a parenthetical aside whose commas are prose).
+ * parenthetical comma-list. The parenthetical comma-list comes last, because a
+ * bullet/tree leaf often carries a parenthetical aside whose commas are prose.
  *
  * @param {string} span - The fenced body to read.
  * @returns {Set<string>} The normalized identifier set.

package/src/enum-drift.js

@@ -1,11 +1,12 @@
 // The enumeration-drift engine: assert that every registered consumer's fenced
-// enumeration block matches its source-of-truth set. This is the reusable
-// mechanism the invariant kit injects — `kit.enumDrift.build/seed` and the
-// `enumDriftRules` rule set — so a repository's rule module carries only the
+// enumeration block matches its source-of-truth set. The invariant kit injects
+// this reusable mechanism as `kit.enumDrift.build/seed` and the
+// `enumDriftRules` rule set. A repository's rule module then carries only the
 // registry (a topics file) and a one-line delegation. The grammar (probes,
-// extractors, consumer parser) lives in enum-drift-grammar.js and is re-exported
-// here so a single import reaches the whole engine. Filesystem access is passed
-// in by the kit (`fsSync`), keeping this clean under the ambient-deps invariant.
+// extractors, consumer parser) lives in enum-drift-grammar.js. This module
+// re-exports the grammar, so a single import reaches the whole engine. The kit
+// passes filesystem access in (`fsSync`), which keeps this module clean under
+// the ambient-deps invariant.
 
 import { join } from "node:path";
 
@@ -28,8 +29,8 @@ export {
   VALID_PROPERTIES,
 } from "./enum-drift-grammar.js";
 
-// A topics file is expected to name itself this way beside the rule module;
-// used only as the display path on a registry-error finding.
+// The engine expects a topics file to use this name beside the rule module.
+// This label appears only as the display path on a registry-error finding.
 const REGISTRY_LABEL = "enumeration-drift.topics.yml";
 
 function expandProperty(property) {
@@ -50,8 +51,8 @@ function indexConsumers(topic, propsByConsumer) {
   }
 }
 
-// Walk the registry topics, probing each source and indexing per-consumer
-// required properties; collects probe errors as registry subjects.
+// Walk the registry topics. Probe each source and index the per-consumer
+// required properties. Collect probe errors as registry subjects.
 function indexRegistry(topics, root, fsSync, registrySubjects) {
   const expectedByTopic = new Map();
   const propsByConsumer = new Map();
@@ -78,8 +79,8 @@ function indexRegistry(topics, root, fsSync, registrySubjects) {
   return { expectedByTopic, propsByConsumer, knownTopics };
 }
 
-// Emit assertion subjects for one consumer: the registry property is a required
-// minimum, and beyond that every well-formed fence found is asserted.
+// Emit assertion subjects for one consumer. The registry property is a
+// required minimum. Beyond that, it asserts every well-formed fence it finds.
 function consumerAssertions(cp, topicMap, records, expectedByTopic) {
   const out = [];
   for (const [topicId, props] of topicMap) {
@@ -130,8 +131,8 @@ function fenceSubjects(cp, records, knownTopics) {
 /**
  * Build subjects from a parsed registry: assertions (consumer×property),
  * fences, and registry errors. `registry` is the parsed topics object (e.g. the
- * kit's `config(topicsFile)`); a missing or malformed registry yields a single
- * registry-error subject rather than throwing.
+ * kit's `config(topicsFile)`). A missing or malformed registry yields a single
+ * registry-error subject. It does not throw.
  *
  * @param {{ registry: { topics?: object[] }|null, root: string, fsSync: object }} options
  * @returns {{ subjects: { assertion: object[], fence: object[], registry: object[] } }}
@@ -242,7 +243,7 @@ function symDiff(observed, expected) {
 }
 
 /**
- * The enumeration-drift rule set, injected into a rule module via the rule kit
+ * The enumeration-drift rule set. The rule kit injects it into a rule module
  * as `enumDriftRules`. The rules render the subjects `buildSubjects` produces.
  */
 export const ENUM_DRIFT_RULES = [
@@ -261,7 +262,7 @@ export const ENUM_DRIFT_RULES = [
     when: (s) => s.fenceAbsent,
     check: (s) => ({ topic: s.topic, property: s.property }),
     message: (s, r) => `${r.topic}:${r.property} :: required fence not found`,
-    hint: "wrap the enumeration in <!-- enum:TOPIC:PROPERTY --> … <!-- /enum -->; seed the body with `jidoka invariants --seed enumeration-drift`",
+    hint: "wrap the enumeration in <!-- enum:TOPIC:PROPERTY --> … <!-- /enum -->, and seed the body with `jidoka invariants --seed enumeration-drift`",
   },
   {
     id: "enum.unknown-topic",
@@ -270,7 +271,7 @@ export const ENUM_DRIFT_RULES = [
     when: (s) => !s.malformed && s.topic !== null,
     check: (s) => (s.known ? null : { topic: s.topic }),
     message: (s, r) =>
-      `${r.topic} :: unknown topic; remove the fence or add the topic to the registry`,
+      `${r.topic} :: unknown topic, so remove the fence or add the topic to the registry`,
     hint: "fence TOPIC must be one of the registry topic ids in the enumeration-drift topics file",
   },
   {
@@ -280,7 +281,7 @@ export const ENUM_DRIFT_RULES = [
     when: (s) => Boolean(s.malformed),
     check: (s) => ({ reason: s.malformed }),
     message: (s, r) => `malformed fence (${r.reason})`,
-    hint: "fences are <!-- enum:TOPIC:count|list --> … <!-- /enum -->; close every open fence and put a number in a count span",
+    hint: "write fences as <!-- enum:TOPIC:count|list --> … <!-- /enum -->, close every open fence, and put a number in a count span",
   },
   {
     id: "enum.list-drift",
@@ -296,7 +297,7 @@ export const ENUM_DRIFT_RULES = [
     },
     message: (s, r) =>
       `${r.topic}:list :: missing=[${r.missing.join(", ")}] extra=[${r.extra.join(", ")}]`,
-    hint: "update the fenced list to match the source set; seed with `jidoka invariants --seed enumeration-drift`",
+    hint: "update the fenced list to match the source set, and seed with `jidoka invariants --seed enumeration-drift`",
   },
   {
     id: "enum.count-drift",
@@ -310,6 +311,6 @@ export const ENUM_DRIFT_RULES = [
         : { topic: s.topic, actual: s.observed, expected: s.expected.size },
     message: (s, r) =>
       `${r.topic}:count :: actual=${r.actual} expected=${r.expected}`,
-    hint: "update the fenced count to match the source set size; seed with `jidoka invariants --seed enumeration-drift`",
+    hint: "update the fenced count to match the source set size, and seed with `jidoka invariants --seed enumeration-drift`",
   },
 ];

package/src/instructions.js

@@ -23,12 +23,12 @@ 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;
 
-// A leading YAML frontmatter block carries metadata, not instruction prose:
-// a skill's `name`/`description`, plus the `license` and `metadata` fields the
-// publish pipeline injects. Exclude it from the line/word budget so a published
-// copy of a layer counts the same as its in-repo source. Only a fenced block
-// that opens on the first line is stripped; the closing fence is the first
-// `---` line that follows.
+// A leading YAML frontmatter block carries metadata. It does not carry
+// instruction prose. It holds a skill's `name`/`description`, plus the
+// `license` and `metadata` fields the publish pipeline injects. Exclude it from
+// the line/word budget so a published copy of a layer counts the same as its
+// in-repo source. This strips only a fenced block that opens on the first line.
+// The closing fence is the first `---` line that follows.
 const FRONTMATTER_RE = /^---[ \t]*\r?\n[\s\S]*?\r?\n---[ \t]*\r?\n?/;
 const stripFrontmatter = (text) => text.replace(FRONTMATTER_RE, "");
 
@@ -81,16 +81,16 @@ async function findByName(root, name, kind, fs) {
 }
 
 // A `.claude/agents/*.md` file is a profile when it carries both `name` and
-// `description` frontmatter — the same test Claude Code's agent loader applies
-// to decide what loads as an agent — and a reference otherwise. This replaces
+// `description` frontmatter. Otherwise it is a reference. Claude Code's agent
+// loader applies the same test to decide what loads as an agent. This replaces
 // the old references-subdirectory marker, which APM flattens away.
 const isProfile = (text) =>
   /^name:[ \t]*\S/m.test(text) && /^description:[ \t]*\S/m.test(text);
 
 /**
  * Partition the flat `agents/*.md` listing into profiles (L3) and references
- * (L4) by frontmatter. Reads each file once and shares the read between the
- * two layers, replacing the former separate directory walks.
+ * (L4) by frontmatter. This reads each file once and shares the read between
+ * the two layers. It replaces the former separate directory walks.
  */
 async function partitionAgents(root, claudeDirs, fs) {
   const profiles = [];
@@ -198,14 +198,14 @@ async function buildLayers(root, fs) {
         id: "L4",
         name: "memory-protocol agent reference",
         // Larger than the L4 default to absorb the two durable surfaces this
-        // one reference is the sole home for: the boot-digest routing contract
-        // (materialized agent-experiments surface with provenance fields and a
-        // last-successful-sync freshness bound, plus the verbatim
-        // standing-carries digest field) and the canonical Carry Surface
-        // section (a durable per-Assess obligation surface kept off the summary
-        // budget, beside the On-Boot Read Set it extends). Both are load-bearing
-        // memory-protocol concepts. Sized to the current content, not
-        // open-ended.
+        // one reference is the sole home for. The first is the boot-digest
+        // routing contract. It is a materialized agent-experiments surface with
+        // provenance fields and a last-successful-sync freshness bound, plus
+        // the verbatim standing-carries digest field. The second is the
+        // canonical Carry Surface section. It is a durable per-Assess
+        // obligation surface kept off the summary budget, beside the On-Boot
+        // Read Set it extends. Both are load-bearing memory-protocol concepts.
+        // This limit fits the current content. It is not open-ended.
         maxLines: 216,
         maxWords: 1588,
         files: agentReferences.filter((p) =>
@@ -225,11 +225,11 @@ async function buildLayers(root, fs) {
         id: "L5",
         name: "kata-release-merge skill procedure",
         // Larger than the L5 default to absorb four consolidated merge-gate
-        // rule sets that govern adjacent corners of one gate: phase-PR review
+        // rule sets. They govern adjacent corners of one gate: phase-PR review
         // transfer (pin-based head coverage), post-panel coverage (folded into
-        // the pin mechanism rather than duplicated), the spec-less
-        // experiment-PR approval path, and the block-comment re-ping cadence.
-        // Sized to the consolidated content, not open-ended.
+        // the pin mechanism rather than duplicated), the approval path for a
+        // spec-less experiment PR, and the block-comment re-ping cadence.
+        // This limit fits the consolidated content. It is not open-ended.
         maxLines: 320,
         maxWords: 2304,
         files: skillDirs
@@ -263,7 +263,7 @@ async function buildFileSubjects(root, layers, fs) {
     for (const relPath of layer.files) {
       const text = await readText(root, relPath, fs);
       if (text == null) continue;
-      // Budget the instruction prose only — metadata frontmatter is exempt.
+      // Budget the instruction prose only. Metadata frontmatter is exempt.
       const body = stripFrontmatter(text);
       subjects.push({
         path: resolve(root, relPath),
@@ -303,7 +303,7 @@ async function buildChecklistSubjects(root, sources, fs) {
 }
 
 const HINT_LAYER_BUDGET =
-  "trim prose to fit the layer cap — see JIDOKA.md for the layered-instruction model";
+  "trim prose to fit the layer cap, and see JIDOKA.md for the layered-instruction model";
 
 // -- Rule catalogue ------------------------------------------------------
 
@@ -357,18 +357,18 @@ export const INSTRUCTION_RULES = [
     },
     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",
+    hint: "rewrite the item more concisely, because a checklist item is a pointer and does not explain",
   },
 ];
 
 // -- Public entry --------------------------------------------------------
 
 /**
- * Walk the repo rooted at `root`, applying the L1–L7 caps from JIDOKA.md.
- * Each layer is gated by a line cap AND a word cap; either breach fails.
+ * Walk the repo rooted at `root` and apply the L1–L7 caps from JIDOKA.md.
+ * A line cap AND a word cap gate each layer. Either breach fails.
  *
  * @param {{ root: string, runtime?: import('@forwardimpact/libutil/runtime').Runtime }} options
- * @returns {Promise<Finding[]>} Structured findings; empty when 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.
  */

package/src/invariant-kit.js

@@ -1,14 +1,16 @@
-// The invariant authoring kit: the mechanism an invariant rule module needs to
-// turn the repository into subjects and findings, so the module itself carries
-// only policy. The engine injects a *build kit* into every module's `build`
-// (and `seed`), and a *rule kit* into a module's `rules` when it is written as
-// a function. Modules never import this file — the host (invariants.js) binds a
-// kit per run and passes it in, the same way the rest of the monorepo threads
-// the `runtime` bag instead of importing ambient collaborators.
+// The invariant kit: the mechanism an invariant rule module needs to turn the
+// repository into subjects and findings, so the module itself carries only
+// policy. The engine injects a *build kit* into every module's `build` (and
+// `seed`). It injects a *rule kit* into a module's `rules` when the module
+// exports `rules` as a function. Modules never import this file. The host
+// (invariants.js) binds a kit per run and passes it in. The rest of the
+// monorepo threads the `runtime` bag the same way and does not import ambient
+// collaborators.
 //
-// Filesystem and subprocess access route through the injected `runtime`
-// (`runtime.fsSync`, `runtime.subprocess`) so this module — which lives under
-// libraries/<pkg>/src — stays clean under the repo's own ambient-deps invariant.
+// This module lives under libraries/<pkg>/src. Filesystem and subprocess
+// access route through the injected `runtime` (`runtime.fsSync`,
+// `runtime.subprocess`), so the module stays clean under the repo's own
+// ambient-deps invariant.
 
 import { isAbsolute, join, relative, resolve } from "node:path";
 
@@ -20,7 +22,7 @@ import { buildSubjects, ENUM_DRIFT_RULES, seedBodies } from "./enum-drift.js";
 // -- AST -----------------------------------------------------------------
 
 /**
- * Parse an ES module, wrapping acorn's error with the offending path.
+ * Parse an ES module. Wrap acorn's error with the offending path.
  *
  * @param {string} source - Module source text.
  * @param {string} filePath - Path used in parse-error messages.
@@ -41,10 +43,10 @@ export function parse(source, filePath, { locations = false } = {}) {
 }
 
 /**
- * Depth-first visit of every typed node in an acorn AST.
+ * Visit every typed node in an acorn AST, depth first.
  *
  * @param {object|object[]} node - AST node (or array of nodes).
- * @param {(node: object) => void} visit - Called once per typed node.
+ * @param {(node: object) => void} visit - Runs once per typed node.
  */
 export function walk(node, visit) {
   if (!node || typeof node !== "object") return;
@@ -78,7 +80,7 @@ export function lineAt(text, offset) {
 }
 
 /**
- * Compile a minimal path glob to a `RegExp`. `**` matches any path segments;
+ * Compile a minimal path glob to a `RegExp`. `**` matches any path segments.
  * `*` matches a non-slash run.
  *
  * @param {string} pattern - The glob.
@@ -94,7 +96,7 @@ export function glob(pattern) {
   );
 }
 
-// -- Filesystem walking (over runtime.fsSync) ----------------------------
+// -- Filesystem walk (over runtime.fsSync) -------------------------------
 
 function collectFiles(fsSync, dir, skip, match) {
   const out = [];
@@ -151,7 +153,7 @@ function dedupeRows(rows, dedupe) {
   });
 }
 
-// A grep row carries `rel`/`raw` for dedupe; the subject keeps only the
+// A grep row carries `rel`/`raw` for dedupe. The subject keeps only the
 // reportable fields (plus `reason` when the matching entry supplied one).
 function toGrepSubject({ path, lineNo, text, reason }) {
   const subject = { path, lineNo, text };
@@ -162,9 +164,10 @@ function toGrepSubject({ path, lineNo, text, reason }) {
 // -- The build kit -------------------------------------------------------
 
 /**
- * Build the kit injected into a rule module's `build` and `seed`. Every
- * collaborator is bound to `root` (the repository root), `dir` (the module's
- * own directory, for co-located config), and `runtime` (the ambient bag).
+ * Build the kit that the engine injects into a rule module's `build` and
+ * `seed`. This binds every collaborator to `root` (the repository root), `dir`
+ * (the module's own directory, for co-located config), and `runtime` (the
+ * ambient bag).
  *
  * @param {{ root: string, dir: string, runtime: import('@forwardimpact/libutil/runtime').Runtime }} options
  * @returns {object} The build kit.
@@ -227,7 +230,7 @@ export function createBuildKit({ root, dir, runtime }) {
 
   function assertRg() {
     if (subprocess.runSync("rg", ["--version"]).exitCode !== 0) {
-      throw new Error("ripgrep (rg) is required by the invariant rule modules");
+      throw new Error("the invariant rule modules require ripgrep (rg)");
     }
   }
 
@@ -252,15 +255,15 @@ export function createBuildKit({ root, dir, runtime }) {
   /**
    * Scan the repo with ripgrep and return matches as subjects. Accepts one
    * `pattern` or a list of `patterns` (strings, or `{ pattern, reason?, globs?,
-   * caseSensitive?, onlyMatching?, exclude? }`); per-entry options override the
-   * call defaults, and a per-entry `exclude` RegExp drops matches whose raw
-   * line it tests true (a false-positive filter). `dedupe` is `false`, `true`
-   * (key on the raw line), or a key function over `{ path, rel, lineNo, text,
-   * raw, reason }`.
+   * caseSensitive?, onlyMatching?, exclude? }`). Per-entry options override the
+   * call defaults. A per-entry `exclude` RegExp drops matches whose raw line it
+   * tests true (a false-positive filter). `dedupe` is `false`, `true` (key on
+   * the raw line), or a key function over `{ path, rel, lineNo, text, raw,
+   * reason }`.
    *
    * Each subject is `{ path, lineNo, text }`, plus `reason` when the matching
    * entry carries one. The repo-relative `rel` and full `raw` line are
-   * available to the `dedupe` key function but are not part of the subject.
+   * available to the `dedupe` key function. They are not part of the subject.
    *
    * @param {object} options
    * @returns {Array<{ path: string, lineNo: number, text: string, reason?: string }>}
@@ -303,7 +306,7 @@ export function createBuildKit({ root, dir, runtime }) {
   }
 
   /**
-   * Read and parse a repo JSON file, returning `null` when missing or invalid.
+   * Read and parse a repo JSON file. Return `null` when missing or invalid.
    *
    * @param {string} path - Relative to the repo root, or absolute.
    * @returns {object|null}
@@ -319,9 +322,9 @@ export function createBuildKit({ root, dir, runtime }) {
   }
 
   /**
-   * Read a config file co-located with the rule module (`<dir>/<name>`),
-   * parsed by extension (`.json` / `.yml` / `.yaml`). Returns `fallback` when
-   * the file is missing, empty, or unparseable.
+   * Read a config file co-located with the rule module (`<dir>/<name>`). The
+   * extension (`.json` / `.yml` / `.yaml`) selects the parser. Returns
+   * `fallback` when the file is missing, empty, or unparseable.
    *
    * @param {string} name - File name beside the module.
    * @param {*} [fallback] - Value when absent or unreadable (default `null`).
@@ -343,15 +346,16 @@ export function createBuildKit({ root, dir, runtime }) {
   /**
    * The shared "single source restated across consumers" check. For every
    * registry `entry` (`{ key, expected, consumers: [{ path, pattern }] }`),
-   * scan each consumer file line by line for `pattern` and emit one subject
-   * per match: the restated value (capture group 1, else the whole match,
-   * trimmed) paired with the entry's `expected` value and an `ok` verdict from
-   * `equal(restated, expected, key)`. The module supplies the domain pieces
-   * (how `expected` is computed, what `equal` means); the kit owns the scan.
+   * scan each consumer file line by line for `pattern`. Emit one subject per
+   * match. The subject holds the restated value (capture group 1, else the
+   * whole match, trimmed), the entry's `expected` value, and an `ok` verdict
+   * from `equal(restated, expected, key)`. The module supplies the domain
+   * pieces (how it computes `expected`, what `equal` means). The kit owns the
+   * scan.
    *
-   * Native line-by-line matching, not ripgrep: the surfaces carry URLs and
-   * other colon-bearing values that ripgrep's single-file output corrupts, and
-   * look-around is sometimes needed.
+   * This matches line by line and does not use ripgrep. The surfaces carry
+   * URLs and other colon-bearing values that ripgrep's single-file output
+   * corrupts. Look-around is sometimes necessary.
    *
    * @param {object} options
    * @param {Array<{ key: string, expected: *, consumers: Array<{ path: string, pattern: RegExp|string }> }>} options.entries
@@ -387,7 +391,7 @@ export function createBuildKit({ root, dir, runtime }) {
   }
 
   /**
-   * List the entries of a repo directory by name, returning `[]` when missing.
+   * List the entries of a repo directory by name. Return `[]` when missing.
    *
    * @param {string} path - Relative to the repo root, or absolute.
    * @param {{ dirsOnly?: boolean, filesOnly?: boolean }} [options]
@@ -409,7 +413,7 @@ export function createBuildKit({ root, dir, runtime }) {
 
   // The enumeration-drift engine, bound to this run's root and filesystem. A
   // rule module passes its parsed registry (e.g. `config(topicsFile)`) to
-  // `build`/`seed`; the matching rule set is on the rule kit as
+  // `build`/`seed`. The rule kit carries the matching rule set as
   // `enumDriftRules`.
   const enumDrift = {
     build: (registry) => buildSubjects({ registry, root, fsSync }),
@@ -440,19 +444,19 @@ export function createBuildKit({ root, dir, runtime }) {
 
 /**
  * Helpers a rule module receives when it exports `rules` as a function. They
- * build the two recurring rule shapes so the module declares only policy.
+ * build the two rule shapes that recur, so the module declares only policy.
  */
 export const RULE_KIT = {
   /**
    * The enumeration-drift rule set, paired with the build kit's `enumDrift`. A
-   * rule module that delegates to `kit.enumDrift` exposes these via
+   * rule module that delegates to `kit.enumDrift` exposes these through
    * `rules: (kit) => kit.enumDriftRules`.
    */
   enumDriftRules: ENUM_DRIFT_RULES,
 
   /**
-   * The standard parse-error rule: fails any subject carrying a `parseError`
-   * string (as produced by the build kit's `scanAst`).
+   * The standard parse-error rule. It fails any subject that carries a
+   * `parseError` string. The build kit's `scanAst` produces that string.
    *
    * @param {string} scope - The subject scope to guard.
    * @param {{ id?: string, hint?: string }} [options]
@@ -465,13 +469,13 @@ export const RULE_KIT = {
       severity: "fail",
       check: (s) => (s.parseError ? { msg: s.parseError } : null),
       message: (_s, r) => r.msg,
-      hint: hint ?? "fix the syntax error so the file can be parsed",
+      hint: hint ?? "fix the syntax error so the parser can read the file",
     };
   },
 
   /**
    * A rule that fails every subject in `scope` (optionally gated by `when`).
-   * The build step has already decided each subject is a violation; the rule
+   * The build step already decided that each subject is a violation. The rule
    * only renders it.
    *
    * @param {string} scope

package/src/invariants.js

@@ -6,17 +6,18 @@ import { LIBCLI_IS_COMPILED } from "@forwardimpact/libcli";
 import { runRules } from "@forwardimpact/libutil";
 import { createBuildKit, RULE_KIT } from "./invariant-kit.js";
 
-// Rule modules are imported dynamically at runtime, so a compiled binary cannot
-// bundle their bare imports, and the standalone executable has no node_modules
-// to resolve them from — a rule module's `import "yaml"` would fail. Expose the
-// third-party packages libinvariant already bundles as virtual modules, so a
-// compiled rule module resolves them to the embedded copies. Under node/bunx
-// this is a no-op: node_modules resolves them normally. A rule module that
-// imports a package beyond this set must run via the package, not the binary.
+// The loader imports rule modules dynamically at runtime. So a compiled binary
+// cannot bundle their bare imports. The standalone executable also has no
+// node_modules to resolve them from, so a rule module's `import "yaml"` would
+// fail. Expose the third-party packages libinvariant already bundles as virtual
+// modules. A compiled rule module then resolves them to the embedded copies.
+// Under node/bunx this is a no-op, because node_modules resolves them normally.
+// A rule module that imports a package beyond this set must run through the
+// package. It cannot run through the binary.
 let bundledRuleDepsRegistered = false;
 function registerBundledRuleDeps() {
   if (bundledRuleDepsRegistered) return;
-  // Only the standalone binary needs this; node/bunx resolve from node_modules.
+  // Only the standalone binary needs this. node/bunx resolve from node_modules.
   if (!LIBCLI_IS_COMPILED || typeof Bun === "undefined") {
     return;
   }
@@ -32,20 +33,20 @@ function registerBundledRuleDeps() {
 
 /**
  * Resolve the root whose rules directory applies to the working directory.
- * The nearest `package.json` is not enough — inside a monorepo every
- * workspace package has one — so search upward for the caller-supplied
- * rules directory itself, falling back to the nearest project root so the
- * loader's error names the expected location.
+ * The nearest `package.json` is not enough. Inside a monorepo every workspace
+ * package has one. So search upward for the caller-supplied rules directory
+ * itself. Fall back to the nearest project root so the loader's error names
+ * the expected location.
  *
  * @param {import('@forwardimpact/libutil/runtime').Runtime} runtime
  * @param {string} rulesDir - Rules directory relative to the project root.
- * @returns {string} Project root directory path.
+ * @returns {string} Path of the project root directory.
  */
 export function findInvariantsRoot(runtime, rulesDir) {
   const found = runtime.finder.findUpward(runtime.proc.cwd(), rulesDir, 8);
   if (!found) return runtime.finder.findProjectRoot();
-  // Climb back out of the found rules directory — one level per segment of
-  // the caller-supplied path — to land on the project root that contains it.
+  // Climb back out of the found rules directory to the project root that
+  // contains it. Use one level for each segment of the caller-supplied path.
   const climb = rulesDir
     .split("/")
     .filter(Boolean)
@@ -64,10 +65,10 @@ export function findInvariantsRoot(runtime, rulesDir) {
 //     seed?: async ({ root, runtime }) => "text",   // e.g. a refreshed deny-list
 //   }
 //
-// `build` walks the repo and returns plain subjects per scope; `rules` are the
-// declarative checks `runRules` applies over them. The repository owns its
-// rule modules — this host only discovers, loads, and runs them, so the
-// policies themselves never ship with the CLI.
+// `build` walks the repo and returns plain subjects for each scope. `rules`
+// are the declarative checks that `runRules` applies over them. The repository
+// owns its rule modules. This host only discovers, loads, and runs them. So
+// the policies themselves never ship with the CLI.
 
 function assertModuleShape(mod, fileName) {
   const ok =
@@ -89,12 +90,12 @@ function resolveRules(mod) {
 }
 
 /**
- * Discover and import every rule module under `rulesDir` (sorted by file
- * name for a stable run order).
+ * Discover and import every rule module under `rulesDir`. Sort by file name
+ * for a stable run order.
  *
  * @param {{ root: string, rulesDir: string, runtime: import('@forwardimpact/libutil/runtime').Runtime }} options
- *   `rulesDir` is the rules directory relative to `root`, supplied by the
- *   caller (the library carries no discovery default).
+ *   `rulesDir` is the rules directory relative to `root`. The caller supplies
+ *   it. The library carries no discovery default.
  * @returns {Promise<object[]>} The modules' default exports.
  */
 export async function loadRuleModules({ root, rulesDir, runtime }) {
@@ -123,14 +124,14 @@ export async function loadRuleModules({ root, rulesDir, runtime }) {
 }
 
 /**
- * Run already-loaded rule modules: inject the build kit, build each module's
- * subjects, then apply its rule catalogue through the shared rules engine.
+ * Run already-loaded rule modules. Inject the build kit. Build each module's
+ * subjects. Then apply its rule catalogue through the shared rules engine.
  *
  * @param {object[]} modules - Rule-module default exports.
  * @param {{ root: string, runtime: import('@forwardimpact/libutil/runtime').Runtime, dir: string }} options
- *   `dir` is the modules' directory (for co-located config), supplied by
- *   the caller alongside the rules it loaded.
- * @returns {Promise<object[]>} Structured findings; empty when conformant.
+ *   `dir` is the modules' directory for co-located config. The caller supplies
+ *   it with the rules it loaded.
+ * @returns {Promise<object[]>} Structured findings, empty when conformant.
  */
 export async function runRuleModules(modules, { root, runtime, dir }) {
   const findings = [];
@@ -152,7 +153,7 @@ export async function runRuleModules(modules, { root, runtime, dir }) {
  * Load every rule module under `root`/`rulesDir` and run it.
  *
  * @param {{ root: string, rulesDir: string, runtime: import('@forwardimpact/libutil/runtime').Runtime }} options
- * @returns {Promise<object[]>} Structured findings; empty when conformant.
+ * @returns {Promise<object[]>} Structured findings, empty when conformant.
  *   Each finding is `{ id, level, path, lineNo?, message, hint? }` for use
  *   with `emitFindingsText` / `emitFindingsJson` from libutil.
  */

package/src/jtbd.js

@@ -66,7 +66,7 @@ export const JTBD_RULES = [
     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",
+    hint: "wrap the value in [], because even a single job is an array of one",
   },
   {
     id: "jtbd.invalid-user",
@@ -121,7 +121,7 @@ export const JTBD_RULES = [
     hint: "append a period to the hire sentence",
   },
   {
-    // Cross-entry uniqueness — mutates ctx.allHires across iterations.
+    // Cross-entry uniqueness. This rule mutates ctx.allHires across iterations.
     id: "jtbd.duplicate-hire",
     scope: "jtbd-entry",
     severity: "fail",
@@ -334,8 +334,8 @@ function makeFormatter(prettierConfig) {
       ...prettierConfig,
       parser: "markdown",
     });
-    // Prettier inserts a blank line between bold labels and bullet lists;
-    // remove it to match the hand-written JTBD.md style.
+    // 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();
   };
 }
@@ -491,15 +491,15 @@ async function processJtbdMd(root, fix, formatMarkdown, result, fsSync) {
 
 /**
  * Validate every `package.json .jobs` entry under products/, services/, and
- * libraries/, and (when `fix` is true) regenerate the marker-delimited catalog,
+ * libraries/. 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, runtime?: import('@forwardimpact/libutil/runtime').Runtime }} options
  * @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.
+ *   `findings` are validation failures, structured for `emitFindingsText` /
+ *   `emitFindingsJson` from libutil. `stale` is files whose generated blocks
+ *   are out of date, and it holds entries only when `fix` is false. `fixed`
+ *   is files that `checkJtbd` rewrote in place.
  */
 export async function checkJtbd({ root, fix = false, runtime }) {
   if (!runtime) throw new Error("runtime is required");