refactor(requirements): dedupe the ledger load, unpick a nested ternary

Simplifier pass over the four gate scripts and the renderer.

The strict ledger load plus its "does not load" error report was repeated
verbatim in three scripts, down to the `errors.length > 0 || root === undefined`
guard — the same duplication this shared module already existed to close for the
population walk. It is now `loadLedgerOrReport(dir, gate, detail?)`, with the one
caller's extra clause passed rather than the whole block copied.

The requirement-test renderer's body assignment had become a NESTED ternary when
`retired` got its own text — which this repo's own style notes call out. Same
three branches, same order, now an if/else chain, with the comment explaining why
the two skipped statuses must not share a body left verbatim.

Smaller: check-requirements-vocabulary walked the requirement tree twice, once to
validate and once again only to count the L5s; check-requirements-ledger computed
its own REPO_ROOT instead of importing the shared one; and the three self-tests'
`expect` helpers had drifted into two shapes.

Behaviour is unchanged and checked rather than assumed: the harness regenerates
byte-identically, all seven gates and self-tests pass, codegen-ts is 1332 pass /
0 fail, the workspace typechecks, and `ci-local.sh --only gates` is green. Every
fix from the preceding review pass was re-verified intact — bun_install first in
each gate, the round-trip derivation check, the validated --expect-warnings flag,
the scaffolder's non-zero bare run, textual --apply, the architectural filter, and
esc() on every prose interpolation.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NynrRND6ZUwGvq3ZUTCfxG

Author: dmealing

scripts/check-requirements-ledger.ts

@@ -26,8 +26,8 @@
 // it needs a machine-readable verify output, which is a product change and out
 // of scope for this ledger.
 import { spawnSync } from "node:child_process";
-import { fileURLToPath } from "node:url";
-import { dirname, resolve } from "node:path";
+import { resolve } from "node:path";
+import { REPO_ROOT } from "./lib/requirement-vocabulary.js";
 
 /** The one diagnostic code this ledger is expected to emit, and why. */
 const EXPECTED_WARNING = "WARN_REQUIREMENT_NOTHING_IMPLEMENTS";
@@ -76,11 +76,11 @@ function expectedWarnings(argv: readonly string[]): number {
 
 const EXPECTED_WARNING_COUNT = expectedWarnings(process.argv.slice(2));
 
-// Resolved against THIS FILE, not the working directory: the self-test runs the
-// gate from a temp directory holding a throwaway ledger, so a cwd-relative path
-// to the CLI would resolve to nothing there and every case would "fail" for the
-// wrong reason.
-const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+// REPO_ROOT (shared with the sibling gates, resolved against THAT FILE rather than the
+// working directory) is what makes this safe to resolve here too: the self-test runs
+// the gate from a temp directory holding a throwaway ledger, so a cwd-relative path to
+// the CLI would resolve to nothing there and every case would "fail" for the wrong
+// reason.
 const CLI = resolve(REPO_ROOT, "server/typescript/packages/cli/bin/meta.ts");
 
 function main(): number {

scripts/check-requirements-vocabulary.ts

@@ -35,13 +35,13 @@
  * statement about portability, not a licence to leave the vocabulary unpromised — an
  * adopter can author `view.textarea` today, so something must say what it is for.
  */
-import { MetaDataLoader } from "../server/typescript/packages/metadata/src/index.js";
 import { collectAddressedRequirements } from "../server/typescript/packages/cli/src/lib/requirement-check.js";
 import {
   DEFAULT_LEDGER_DIR,
   LEVEL_ATTR,
   LEVEL_SUBTYPE,
   derivationProblems,
+  loadLedgerOrReport,
   participatesInVocabularyLink,
   population,
   splitName,
@@ -65,17 +65,14 @@ async function main(): Promise<number> {
     return 1;
   }
 
-  const { root, errors } = await MetaDataLoader.fromDirectory(LEDGER_DIR, { strict: true });
-  if (errors.length > 0 || root === undefined) {
-    console.error("requirements-vocabulary: the ledger does not load.\n");
-    for (const e of errors) console.error(`  ${e.code ?? ""} ${e.message}`);
-    return 1;
-  }
+  const root = await loadLedgerOrReport(LEDGER_DIR, "requirements-vocabulary");
+  if (root === undefined) return 1;
 
   const claimed = new Map<string, string>();      // type.subType -> requirement address
   const problems: string[] = [];
+  const addressed = collectAddressedRequirements(root);
 
-  for (const { node, path } of collectAddressedRequirements(root)) {
+  for (const { node, path } of addressed) {
     // Architectural requirements are object-independent and name no subtype (0.23.0
     // made them levellable, so one can legally sit at L4).
     if (!participatesInVocabularyLink(node)) continue;
@@ -127,7 +124,7 @@ async function main(): Promise<number> {
     return 1;
   }
 
-  const l5 = collectAddressedRequirements(root)
+  const l5 = addressed
     .filter((r) => participatesInVocabularyLink(r.node) && r.node.level() === LEVEL_ATTR).length;
   console.log(
     `requirements-vocabulary: OK — ${pop.size} registered subtype(s), each promised by exactly ` +

scripts/generate-requirement-harness.ts

@@ -36,13 +36,13 @@
  */
 import { mkdirSync, writeFileSync, readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
-import { MetaDataLoader } from "../server/typescript/packages/metadata/src/index.js";
 import { collectAddressedRequirements } from "../server/typescript/packages/cli/src/lib/requirement-check.js";
 import {
   DEFAULT_LEDGER_DIR,
   LEVEL_ATTR,
   LEVEL_SUBTYPE,
   REPO_ROOT,
+  loadLedgerOrReport,
   participatesInVocabularyLink,
 } from "./lib/requirement-vocabulary.js";
 
@@ -188,12 +188,8 @@ const renderers: Record<string, { file: string; render: (ps: Promise_[]) => stri
 
 async function main(): Promise<number> {
   const check = process.argv.includes("--check");
-  const { root, errors } = await MetaDataLoader.fromDirectory(DEFAULT_LEDGER_DIR, { strict: true });
-  if (errors.length > 0 || root === undefined) {
-    console.error("requirement-harness: the ledger does not load.\n");
-    for (const e of errors) console.error(`  ${e.code ?? ""} ${e.message}`);
-    return 1;
-  }
+  const root = await loadLedgerOrReport(DEFAULT_LEDGER_DIR, "requirement-harness");
+  if (root === undefined) return 1;
   const promises = collect(root);
   if (promises.length === 0) {
     console.error("requirement-harness: the ledger declares no L4 or L5 promise — nothing to scaffold.\n");

scripts/lib/requirement-vocabulary.ts

@@ -9,6 +9,7 @@
 import { readdirSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join, resolve } from "node:path";
+import { MetaDataLoader, type MetaRoot } from "../../server/typescript/packages/metadata/src/index.js";
 import {
   REQUIREMENT_SUBTYPE_ARCHITECTURAL,
 } from "../../server/typescript/packages/metadata/src/core/requirement/requirement-constants.js";
@@ -27,6 +28,31 @@ export const DEFAULT_LEDGER_DIR = join(REPO_ROOT, "metaobjects");
 export const LEVEL_SUBTYPE = 4;
 export const LEVEL_ATTR = 5;
 
+/**
+ * Load the ledger under `dir` in strict mode, reporting load errors the same way
+ * everywhere and returning `undefined` so the caller can exit non-zero.
+ *
+ * Repeated identically (down to the `errors.length > 0 || root === undefined` guard)
+ * across `check-requirements-vocabulary.ts`, `scaffold-metamodel-entry.ts` and
+ * `generate-requirement-harness.ts` before this was pulled out — the same duplication
+ * this module already exists to close for `population()`. `gate` names the caller for
+ * the printed message; `detail` is one caller's extra clause ("; fix it before
+ * scaffolding from it") appended before the trailing period.
+ */
+export async function loadLedgerOrReport(
+  dir: string,
+  gate: string,
+  detail = "",
+): Promise<MetaRoot | undefined> {
+  const { root, errors } = await MetaDataLoader.fromDirectory(dir, { strict: true });
+  if (errors.length > 0 || root === undefined) {
+    console.error(`${gate}: the ledger does not load${detail}.\n`);
+    for (const e of errors) console.error(`  ${e.code ?? ""} ${e.message}`);
+    return undefined;
+  }
+  return root;
+}
+
 export interface Entry { key: string; attrs: Set<string> }
 
 /**

scripts/scaffold-metamodel-entry.ts

@@ -32,13 +32,13 @@
  */
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
-import { MetaDataLoader } from "../server/typescript/packages/metadata/src/index.js";
 import { collectAddressedRequirements } from "../server/typescript/packages/cli/src/lib/requirement-check.js";
 import {
   DEFAULT_LEDGER_DIR,
   DEFAULT_MANIFEST,
   DEFAULT_SPEC_DIR,
   LEVEL_SUBTYPE,
+  loadLedgerOrReport,
   participatesInVocabularyLink,
   population,
   splitName,
@@ -65,7 +65,6 @@ function parseArgs(argv: string[]): Args {
   };
 }
 
-
 /**
  * Append one entry to a provider file's `types` array by editing TEXT, not by
  * re-serialising the document. Returns undefined when the array's end cannot be
@@ -89,12 +88,8 @@ async function main(): Promise<number> {
   const pop = population(specDir, manifest);
   const types = typeAxis(pop);
 
-  const { root, errors } = await MetaDataLoader.fromDirectory(ledgerDir, { strict: true });
-  if (errors.length > 0 || root === undefined) {
-    console.error("scaffold-metamodel: the ledger does not load; fix it before scaffolding from it.\n");
-    for (const e of errors) console.error(`  ${e.code ?? ""} ${e.message}`);
-    return 1;
-  }
+  const root = await loadLedgerOrReport(ledgerDir, "scaffold-metamodel", "; fix it before scaffolding from it");
+  if (root === undefined) return 1;
 
   // A requirement naming vocabulary nothing registers is the SIGNAL, not an error.
   const wanted: { key: string; path: string; title: string }[] = [];

scripts/test-requirements-ledger.ts

@@ -79,13 +79,9 @@ metadata.root:
 `;
 
 let failures = 0;
-function expect(label: string, condition: boolean, detail: string): void {
-  if (condition) {
-    console.log(`  ok   ${label}`);
-  } else {
-    console.error(`  FAIL ${label}\n${detail}`);
-    failures++;
-  }
+function expect(label: string, ok: boolean, detail: string): void {
+  if (ok) console.log(`  ok   ${label}`);
+  else { console.error(`  FAIL ${label}\n${detail}`); failures++; }
 }
 
 console.log("test-requirements-ledger:");

server/typescript/packages/codegen-ts/src/templates/requirement-test.ts

@@ -124,15 +124,20 @@ export function renderRequirementTest(a: RequirementTestArgs): string {
   // to write it "when this becomes live" instructs them to revive the capability —
   // inverting the one guardrail 0.24.2 restored `retired` for. The repo's own harness
   // generator already branches here; the shipped renderer now does too.
-  const body = skipped
-    ? a.view.status === REQUIREMENT_STATUS_RETIRED
-      ? `  // Retired: this capability was deliberately removed and must not be rebuilt.\n` +
-        `  // If you assert anything here, assert that it STAYS removed.`
-      : `  // Intended, not built. Write the assertion when this becomes live.`
-    : `  expect.unreachable(\n` +
+  let body: string;
+  if (!skipped) {
+    body =
+      `  expect.unreachable(\n` +
       `    "unimplemented requirement stub: ${testName} — " +\n` +
       `    "replace this with an assertion that fails when: ${forStringLiteral(a.counterexample)}",\n` +
       `  );`;
+  } else if (a.view.status === REQUIREMENT_STATUS_RETIRED) {
+    body =
+      `  // Retired: this capability was deliberately removed and must not be rebuilt.\n` +
+      `  // If you assert anything here, assert that it STAYS removed.`;
+  } else {
+    body = `  // Intended, not built. Write the assertion when this becomes live.`;
+  }
 
   return (
     `// ${GENERATED_HEADER}.\n` +