explico 0.13.1 → 0.14.0

package/src/compiler/page-versions.ts

@@ -0,0 +1,359 @@
+/**
+ * A page's own content version (rule C5): the knowledge version its content
+ * last changed in, as against the course's, which moves at every release.
+ *
+ * A build sees one commit, and "unchanged since 0.2.0" is history, so the
+ * record is a committed file, `content/versions.json`, kept like a lockfile:
+ * `pnpm validate:content` works the next record out from the committed one
+ * and the content tree, writes it back on a developer's machine, and in CI
+ * (`CI` set) fails when the committed file is not the one it would write.
+ * The manifest carries each chapter's and part page's `since` either way,
+ * computed from the committed record by the same rules, so a build never
+ * depends on the file having been rewritten.
+ *
+ * What counts as the page: its own file, its `.checks.yml` and the
+ * assessments it lists, the shared notation entries its text uses, the
+ * sources it cites, and its numbers (`part.chapter` and the float offsets its
+ * earlier chapters leave it). A lab, `content/domain/`, a part's label or the
+ * engine change a page's PDF without changing its stamp.
+ *
+ * The three rules, applied to the committed entry of each page:
+ *
+ * 1. The record's `version` is not `about.version`: a release came after the
+ *    file was written, and a release takes every change `## [Unreleased]`
+ *    held. Every page with a `pending` hash, or never released, is now
+ *    `since` that version.
+ * 2. The page hashes as recorded: `since` stays. A pending edit undone
+ *    (the page hashes as it did at `since`) is unchanged again.
+ * 3. The page changed: with bullets under `## [Unreleased]` the change is
+ *    not yet released (`pending`); with none it is the release's own, or a
+ *    fix rule C1 lets go unlisted, and `since` is `about.version`.
+ *
+ * Pure except `readPageVersions` and `syncPageVersions`, which do the file IO.
+ */
+
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import type { KnowledgeVersionDiagnostic } from './knowledge-version';
+
+/** Repo-relative path of the record. */
+export const PAGE_VERSIONS_FILE = 'content/versions.json';
+export const PAGE_VERSIONS_GENERATED_BY = 'pnpm validate:content (rule C5); do not edit';
+/**
+ * The format of the record and of the hashes in it. A record of another
+ * format keeps every page's `since` and takes the hashes as they are now, so
+ * a change to what is hashed never marks every page changed.
+ */
+export const PAGE_VERSIONS_FORMAT = 1;
+
+export interface PageVersionEntry {
+  /** The release the page's content last changed in; `null` before its first. */
+  readonly since: string | null;
+  /** `sha256:…` of the page's inputs as of `since`. */
+  readonly source: string;
+  /** The inputs' hash now, while they differ from `source` and `## [Unreleased]` has bullets. */
+  readonly pending?: string;
+}
+
+export interface PageVersionsRecord {
+  readonly generatedBy: string;
+  readonly format: number;
+  /** `about.version` when the record was written. */
+  readonly version: string;
+  /** By docs slug (`motion/constant-acceleration`, `motion/index`), sorted. */
+  readonly pages: Readonly<Record<string, PageVersionEntry>>;
+}
+
+/** What the manifest carries for the record (`manifest.pageVersions`). */
+export interface ManifestPageVersions {
+  /** False when rule C5 is off: every page then carries the course's version. */
+  readonly enabled: boolean;
+  /** Repo-relative path of the record, `content/versions.json`. */
+  readonly file: string;
+  /** The record as `validate:content` should write it. */
+  readonly record: PageVersionsRecord;
+}
+
+const ENTRY_HASH = /^sha256:[0-9a-f]{64}$/u;
+
+function compareSlugs(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/** JSON with recursively sorted keys and a trailing newline, as the resolution reports are written. */
+function stableJson(value: unknown): string {
+  const sortKeys = (node: unknown): unknown => {
+    if (Array.isArray(node)) return node.map(sortKeys);
+    if (node && typeof node === 'object') {
+      return Object.fromEntries(
+        Object.keys(node as Record<string, unknown>)
+          .sort()
+          .map((key) => [key, sortKeys((node as Record<string, unknown>)[key])]),
+      );
+    }
+    return node;
+  };
+  return `${JSON.stringify(sortKeys(value), null, 2)}\n`;
+}
+
+/**
+ * The hash of one page's inputs: each labelled file digest, in label order,
+ * then the page's facts (its numbers) as sorted JSON.
+ */
+export function pageSourceDigest(
+  inputs: readonly { readonly label: string; readonly digest: string }[],
+  facts: Record<string, unknown> = {},
+): string {
+  const hash = createHash('sha256');
+  for (const { label, digest } of [...inputs].sort((a, b) => compareSlugs(a.label, b.label))) {
+    hash.update(`${label} ${digest}\n`);
+  }
+  hash.update(stableJson(facts));
+  return `sha256:${hash.digest('hex')}`;
+}
+
+/**
+ * Semver order over `x.y.z`, a prerelease below its release; `null` (not
+ * yet released) above everything, since it is the newest state a page can
+ * be in. A string that is not semver sorts by text, after every semver.
+ */
+export function compareKnowledgeVersions(a: string | null, b: string | null): number {
+  if (a === b) return 0;
+  if (a === null) return 1;
+  if (b === null) return -1;
+  const parse = (value: string) => /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/u.exec(value.trim());
+  const left = parse(a);
+  const right = parse(b);
+  if (!left || !right) {
+    if (left) return -1;
+    if (right) return 1;
+    return compareSlugs(a, b);
+  }
+  for (const index of [1, 2, 3]) {
+    const difference = Number(left[index]) - Number(right[index]);
+    if (difference !== 0) return Math.sign(difference);
+  }
+  const leftPre = left[4];
+  const rightPre = right[4];
+  if (leftPre === rightPre) return 0;
+  if (leftPre === undefined) return 1;
+  if (rightPre === undefined) return -1;
+  const leftParts = leftPre.split('.');
+  const rightParts = rightPre.split('.');
+  for (let index = 0; index < Math.max(leftParts.length, rightParts.length); index += 1) {
+    const l = leftParts[index];
+    const r = rightParts[index];
+    if (l === undefined) return -1;
+    if (r === undefined) return 1;
+    const numeric = /^\d+$/u.test(l) && /^\d+$/u.test(r);
+    const difference = numeric ? Number(l) - Number(r) : compareSlugs(l, r);
+    if (difference !== 0) return Math.sign(difference);
+  }
+  return 0;
+}
+
+/**
+ * The version of a document made of several pages: the newest among them,
+ * `null` when any page has a change not yet released, `null` for no pages.
+ */
+export function newestSince(values: readonly (string | null)[]): string | null {
+  if (values.length === 0) return null;
+  return values.reduce<string | null>(
+    (newest, value) => (compareKnowledgeVersions(value, newest) > 0 ? value : newest),
+    values[0]!,
+  );
+}
+
+/** The version a page's entry gives it: `null` while it has a change not yet released. */
+export function sinceOf(entry: PageVersionEntry): string | null {
+  return entry.pending !== undefined || entry.since === null ? null : entry.since;
+}
+
+/**
+ * The phrase every export prints for a document's version (rule C5):
+ * "unchanged since version 0.2.0", or, for a change not yet released, "with
+ * changes after version 0.4.0, not yet released", 0.4.0 being the newest
+ * release, the last one the document agrees with.
+ */
+export function versionPhrase(since: string | null, current: string): string {
+  return since === null
+    ? `with changes after version ${current}, not yet released`
+    : `unchanged since version ${since}`;
+}
+
+export interface NextPageVersionsInput {
+  /** The committed record, or `undefined` for a course without one. */
+  readonly previous: PageVersionsRecord | undefined;
+  /** `about.version`. */
+  readonly version: string;
+  /** Whether `## [Unreleased]` holds bullets. */
+  readonly unreleased: boolean;
+  /** Every tracked page, with its inputs' hash now. */
+  readonly pages: readonly { readonly slug: string; readonly source: string }[];
+}
+
+/** The record `validate:content` writes: the committed one, brought to the content as it is now. */
+export function nextPageVersions(input: NextPageVersionsInput): PageVersionsRecord {
+  const { previous, version, unreleased } = input;
+  const released = previous !== undefined && previous.version !== version;
+  const sameFormat = previous !== undefined && previous.format === PAGE_VERSIONS_FORMAT;
+  const pages: Record<string, PageVersionEntry> = {};
+  for (const page of [...input.pages].sort((a, b) => compareSlugs(a.slug, b.slug))) {
+    const current = page.source;
+    let entry = previous?.pages[page.slug];
+    if (entry && !sameFormat) {
+      // Another format hashed differently: the page keeps its version, and
+      // whether it has a pending change, with the hash as it is now.
+      entry = { since: entry.since, source: current, ...(entry.pending === undefined ? {} : { pending: current }) };
+    }
+    if (entry && released && (entry.pending !== undefined || entry.since === null)) {
+      // 1. The release took every change that was waiting.
+      entry = { since: version, source: entry.pending ?? entry.source };
+    }
+    if (entry === undefined) {
+      pages[page.slug] = unreleased ? { since: null, source: current } : { since: version, source: current };
+    } else if ((entry.pending ?? entry.source) === current) {
+      // 2. As recorded.
+      pages[page.slug] = entry;
+    } else if (entry.pending !== undefined && entry.source === current) {
+      // 2. A pending edit undone: the page is as it was at `since`.
+      pages[page.slug] = { since: entry.since, source: entry.source };
+    } else if (unreleased) {
+      // 3. Changed, and the change waits for a release.
+      pages[page.slug] =
+        entry.since === null ? { since: null, source: current } : { since: entry.since, source: entry.source, pending: current };
+    } else {
+      // 3. Changed with nothing waiting: the release's own change, or one rule C1 lets go unlisted.
+      pages[page.slug] = { since: version, source: current };
+    }
+  }
+  return { generatedBy: PAGE_VERSIONS_GENERATED_BY, format: PAGE_VERSIONS_FORMAT, version, pages };
+}
+
+/** The record's text as `syncPageVersions` writes it. */
+export function serializePageVersions(record: PageVersionsRecord): string {
+  return stableJson(record);
+}
+
+/**
+ * The committed record, or `undefined` when there is none. A file that is
+ * not a record (hand-edited, truncated) is reported as `page-versions-invalid`
+ * and treated as none: every page then counts as new.
+ */
+export function readPageVersions(
+  path: string,
+  file: string = PAGE_VERSIONS_FILE,
+): { readonly record: PageVersionsRecord | undefined; readonly diagnostics: readonly KnowledgeVersionDiagnostic[] } {
+  if (!existsSync(path)) return { record: undefined, diagnostics: [] };
+  const invalid = (reason: string) => ({
+    record: undefined,
+    diagnostics: [
+      {
+        code: 'page-versions-invalid' as const,
+        severity: 'warning' as const,
+        message: `${file} is not a record validate:content wrote (${reason}); it is rebuilt, and every page counts as new. Restore the committed file to keep the pages' versions (rule C5).`,
+        file,
+      },
+    ],
+  });
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    return invalid(error instanceof Error ? error.message : String(error));
+  }
+  if (!parsed || typeof parsed !== 'object') return invalid('not an object');
+  const { version, format, pages, generatedBy } = parsed as Record<string, unknown>;
+  if (typeof version !== 'string' || typeof format !== 'number' || !pages || typeof pages !== 'object') {
+    return invalid('missing version, format or pages');
+  }
+  const entries: Record<string, PageVersionEntry> = {};
+  for (const [slug, value] of Object.entries(pages as Record<string, unknown>)) {
+    if (!value || typeof value !== 'object') return invalid(`page ${slug} is not an object`);
+    const { since, source, pending } = value as Record<string, unknown>;
+    if (since !== null && typeof since !== 'string') return invalid(`page ${slug}: since must be a version or null`);
+    if (typeof source !== 'string' || !ENTRY_HASH.test(source)) return invalid(`page ${slug}: source is not a sha256`);
+    if (pending !== undefined && (typeof pending !== 'string' || !ENTRY_HASH.test(pending))) {
+      return invalid(`page ${slug}: pending is not a sha256`);
+    }
+    entries[slug] = { since, source, ...(pending === undefined ? {} : { pending }) };
+  }
+  return {
+    record: { generatedBy: typeof generatedBy === 'string' ? generatedBy : '', format, version, pages: entries },
+    diagnostics: [],
+  };
+}
+
+/** The one error rule C5 raises: frozen, and the committed record is not the content's. */
+export interface PageVersionsStaleDiagnostic {
+  readonly code: 'page-versions-stale';
+  readonly severity: 'error';
+  readonly message: string;
+  readonly file: string;
+}
+
+export interface PageVersionsSync {
+  /** Absolute path of the record. */
+  readonly path: string;
+  /** The record on disk was not the one the content gives. */
+  readonly stale: boolean;
+  /** The record was written (never when frozen). */
+  readonly written: boolean;
+  /** Pages whose entry changed, or `['*']` for a record written first. */
+  readonly changed: readonly string[];
+  /** Set when frozen and stale: the error that fails the build. */
+  readonly diagnostic?: PageVersionsStaleDiagnostic;
+}
+
+/** `CI` set (and not `false` or `0`): the record is frozen, like a lockfile. */
+export function pageVersionsFrozen(): boolean {
+  const ci = process.env.CI;
+  return !!ci && ci !== 'false' && ci !== '0';
+}
+
+/**
+ * Bring `content/versions.json` to what the manifest computed. On a
+ * developer's machine a stale record is rewritten and the caller logs the
+ * pages that moved; frozen (CI by default) a stale record is left as it is
+ * and the result carries a `page-versions-stale` error, so a content change
+ * cannot land without its record.
+ */
+export function syncPageVersions(
+  manifest: { readonly pageVersions: ManifestPageVersions },
+  options: { readonly frozen?: boolean; readonly root?: string } = {},
+): PageVersionsSync {
+  const root = options.root ?? process.cwd();
+  const { enabled, file, record } = manifest.pageVersions;
+  const path = join(root, file);
+  if (!enabled) return { path, stale: false, written: false, changed: [] };
+  const expected = serializePageVersions(record);
+  const onDisk = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
+  if (onDisk === expected) return { path, stale: false, written: false, changed: [] };
+  const previous = onDisk === undefined ? undefined : readPageVersions(path, file).record;
+  const changed =
+    previous === undefined
+      ? ['*']
+      : [...new Set([...Object.keys(previous.pages), ...Object.keys(record.pages)])]
+          .filter((slug) => JSON.stringify(previous.pages[slug] ?? null) !== JSON.stringify(record.pages[slug] ?? null))
+          .sort(compareSlugs);
+  const frozen = options.frozen ?? pageVersionsFrozen();
+  if (frozen) {
+    const moved = changed[0] === '*' ? 'the file is missing' : `${changed.length} page(s): ${changed.slice(0, 6).join(', ')}${changed.length > 6 ? ', …' : ''}`;
+    return {
+      path,
+      stale: true,
+      written: false,
+      changed,
+      diagnostic: {
+        code: 'page-versions-stale',
+        severity: 'error',
+        message: `${file} is out of date (${moved}). Run \`pnpm validate:content\` and commit ${file} with the change (rule C5).`,
+        file,
+      },
+    };
+  }
+  writeFileSync(path, expected);
+  return { path, stale: true, written: true, changed };
+}

package/src/compiler/resolution-report.ts

@@ -9,13 +9,16 @@
  * lesson — plus `resolution/consistency-report.json` for the Tier-3 corpus
  * checks. `pnpm validate:content` regenerates them and **fails if a committed
  * file is stale**, so a drift between content and the checked-in report cannot
- * pass CI unnoticed.
+ * pass CI unnoticed. A report git does not track (a course that ignores
+ * `build/`) is refreshed and reported, never a failure: nothing could be
+ * committed, so nothing can be stale, and the first run passes.
  *
  * The reports are deterministic: keys are sorted recursively, rows follow the
  * manifest's stable ordering, and nothing records a timestamp or a content
  * hash — a file changes only when a resolution or a finding changes.
  */
 
+import { execFileSync } from 'node:child_process';
 import {
   existsSync,
   mkdirSync,
@@ -100,14 +103,38 @@ export function buildResolutionReports(
 
 export interface ResolutionReportSync {
   readonly written: number;
-  /** Repo-relative paths that were out of date (created, changed, or removed). */
+  /**
+   * Repo-relative paths git tracks that were out of date (created, changed,
+   * or removed): the caller fails on these so the checked-in reports stay honest.
+   */
   readonly stale: readonly string[];
+  /** Paths rewritten or removed that git does not track: refreshed, nothing to commit. */
+  readonly refreshed: readonly string[];
+}
+
+/**
+ * The report files git tracks under `dir`, by name. Empty when `dir` is
+ * ignored, outside a repository, or git is not on the path: then no report
+ * can be committed, so none can be stale.
+ */
+export function trackedReportNames(dir: string): Set<string> {
+  try {
+    const out = execFileSync('git', ['ls-files', '-z', '--', '.'], {
+      cwd: dir,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      encoding: 'utf8',
+    });
+    return new Set(out.split('\0').filter((name) => name !== ''));
+  } catch {
+    return new Set();
+  }
 }
 
 /**
  * Write every expected report and prune orphans. Returns the paths that did not
- * already match on disk — the caller turns a non-empty list into a build
- * failure so the checked-in reports stay honest.
+ * already match on disk, split by whether git tracks them — the caller turns a
+ * non-empty `stale` list into a build failure so the checked-in reports stay
+ * honest, and prints `refreshed` as information.
  */
 export function syncResolutionReports(
   manifest: Manifest,
@@ -120,7 +147,9 @@ export function syncResolutionReports(
       ? readdirSync(RESOLUTION_DIR).filter((name) => name.endsWith('.json'))
       : [],
   );
+  const tracked = trackedReportNames(RESOLUTION_DIR);
   const stale: string[] = [];
+  const refreshed: string[] = [];
 
   for (const [relPath, content] of [...expected].sort(([a], [b]) =>
     a.localeCompare(b),
@@ -133,7 +162,7 @@ export function syncResolutionReports(
       : undefined;
     if (current !== content) {
       writeFileSync(absolute, content);
-      stale.push(
+      (tracked.has(name) ? stale : refreshed).push(
         `${relPath} (${current === undefined ? 'missing' : 'changed'})`,
       );
     }
@@ -141,10 +170,12 @@ export function syncResolutionReports(
 
   for (const orphan of [...onDisk].sort()) {
     rmSync(join(RESOLUTION_DIR, orphan));
-    stale.push(`${RESOLUTION_PREFIX}${orphan} (stale, removed)`);
+    (tracked.has(orphan) ? stale : refreshed).push(
+      `${RESOLUTION_PREFIX}${orphan} (stale, removed)`,
+    );
   }
 
-  return { written: expected.size, stale };
+  return { written: expected.size, stale, refreshed };
 }
 
 export { RESOLUTION_DIR };

package/src/compiler/validate-content.ts

@@ -0,0 +1,212 @@
+/**
+ * `pnpm validate:content` — regenerate `build/manifest.json` and report its
+ * diagnostics, whole. A course's `scripts/compile-manifest.ts` is three lines:
+ *
+ *   import { runValidateContent } from 'explico/compiler/validate-content';
+ *   import { courseConfig } from '../content/course.config';
+ *   process.exitCode = await runValidateContent(courseConfig);
+ *
+ * It compiles the one manifest (the single walk of the content tree), writes
+ * it deterministically, prints the warnings, refreshes the per-lesson
+ * resolution reports, `content/versions.json` (rule C5) and the
+ * rules-in-effect page, and returns 1 if any blocking diagnostic is present.
+ * `pnpm build` runs it first, so `astro build` and every page component read a
+ * current manifest and never re-read the content tree.
+ *
+ * Every line printed is also recorded, in Python's `logging` format, to
+ * `build/logs/<timestamp>/{error,warning,info}.log` (`./logging`); `log.<level>()`
+ * returns its message so the printed line and the recorded one cannot drift.
+ */
+import { notationSourceLocatorGaps } from './collections';
+import type { CourseConfig } from './course-config';
+import { createRunLog, diagnosticLine } from './logging';
+import { compileManifest, MANIFEST_PATH, writeManifest } from './manifest';
+import { syncPageVersions } from './page-versions';
+import { syncResolutionReports } from './resolution-report';
+import { consistencyCounts } from '../reference/consistency';
+import { curriculumErrors } from '../curriculum/validation';
+import { writeRulesInEffect } from '../rules/in-effect';
+
+export async function runValidateContent(courseConfig: CourseConfig): Promise<number> {
+  const log = createRunLog();
+
+  let manifest;
+  try {
+    manifest = await compileManifest(courseConfig);
+  } catch (error) {
+    // The log keeps why the run ended; the console gets the message, not a stack.
+    const message = error instanceof Error ? error.message : String(error);
+    log.error('manifest', `Manifest compilation failed: ${message}`);
+    const summary = log.close();
+    console.error(`Manifest compilation failed: ${message}\nRun log: ${summary.relativeDirectory}.`);
+    return 1;
+  }
+  writeManifest(manifest);
+
+  const {
+    curriculum,
+    notation,
+    alignment,
+    math,
+    consistency,
+    equations,
+    tables,
+    figures,
+    diagrams,
+    checks,
+    examples,
+    folds,
+    knowledge,
+    rawFloats,
+    config,
+    waivers,
+  } = manifest.diagnostics;
+
+  for (const warning of curriculum.filter((issue) => issue.severity === 'warning')) {
+    console.warn(log.warning('curriculum', `[${warning.kind}] ${warning.message}`));
+  }
+  for (const warning of notation.filter((d) => d.severity === 'warning')) {
+    console.warn(log.warning('notation', `[${warning.code}] ${warning.message}`));
+  }
+  for (const warning of alignment.filter((d) => d.severity === 'warning')) {
+    console.warn(log.warning('alignment', `[${warning.code}] ${warning.message}`));
+  }
+  const floatGroups = [
+    ['equations', equations],
+    ['tables', tables],
+    ['figures', figures],
+    ['diagrams', diagrams],
+    ['checks', checks],
+    ['examples', examples],
+    ['folds', folds],
+    ['rawFloats', rawFloats],
+  ] as const;
+  for (const [source, group] of floatGroups) {
+    for (const warning of group.filter((d) => d.severity === 'warning')) {
+      console.warn(log.warning(source, `[${warning.code}] ${warning.message}`));
+    }
+  }
+  // `diagnosticLine` prefixes a code owned by a lettered rule with its ID
+  // (`[N9 prose-notation] file:line: …`), so the console names the rule page.
+  for (const issue of math.filter((item) => item.severity === 'warning')) {
+    console.warn(log.warning('math', diagnosticLine(issue)));
+  }
+  for (const warning of knowledge) {
+    console.warn(log.warning('knowledge', `[${warning.code}] ${warning.message}`));
+  }
+  // The course settings themselves: a deprecated top-level block, a retired rule.
+  for (const warning of config) {
+    console.warn(log.warning('config', `[${warning.code}] ${warning.message}`));
+  }
+  // Per-place waivers: a stale one is a warning; a malformed or invalid one
+  // fails below with the other errors.
+  for (const warning of waivers.filter((d) => d.severity === 'warning')) {
+    console.warn(log.warning('waivers', diagnosticLine(warning)));
+  }
+
+  const locatorGaps = notationSourceLocatorGaps();
+  if (locatorGaps.bare > 0) {
+    console.warn(
+      log.warning(
+        'consistency',
+        `[notation-source-locator] ${locatorGaps.bare} of ${locatorGaps.total} notation source citations lack a non-empty locator.`,
+      ),
+    );
+  }
+
+  const consistencyWarnings = consistency.filter((diagnostic) => diagnostic.severity === 'warning');
+  if (consistencyWarnings.length > 0) {
+    console.warn(
+      log.warning(
+        'consistency',
+        `[consistency] ${consistencyWarnings.length} Tier-3 finding(s): ` +
+          Object.entries(consistencyCounts(consistencyWarnings))
+            .filter(([, count]) => count > 0)
+            .map(([code, count]) => `${code}=${count}`)
+            .join(', '),
+      ),
+    );
+  }
+
+  // Every severity-`info` diagnostic goes to the log only.
+  log.infoDiagnostics(manifest.diagnostics);
+  for (const diagnostic of consistencyWarnings) {
+    log.info('consistency', `[${diagnostic.code}] ${diagnostic.message}`);
+  }
+
+  const reports = syncResolutionReports(manifest);
+  console.log(
+    log.info(
+      'manifest',
+      `Resolution report: ${reports.written} file(s) under resolution/` +
+        (reports.refreshed.length > 0
+          ? ` (${reports.refreshed.length} refreshed; git does not track them, nothing to commit).`
+          : '.'),
+    ),
+  );
+  // Each page's own version (rule C5): rewritten here and committed with the
+  // change; in CI a record that would change fails below, like a lockfile.
+  const pageVersions = syncPageVersions(manifest);
+  if (pageVersions.written) {
+    console.log(
+      log.info(
+        'page-versions',
+        `content/versions.json ${
+          pageVersions.changed[0] === '*' ? 'written' : `updated for ${pageVersions.changed.length} page(s)`
+        } — commit it with the change (rule C5).`,
+      ),
+    );
+  }
+  // The page an agent reads before drafting. Regenerated every run, never committed.
+  writeRulesInEffect(manifest);
+  console.log(
+    log.info('manifest', `Rules in effect: build/rules-in-effect.md (${manifest.rules.disabled.length} rule(s) off).`),
+  );
+
+  const failures: string[] = [];
+  // `block(source, …)`: a blocking finding under its log source (not a diagnostic code).
+  const block = (source: string, message: string): void => {
+    failures.push(log.error(source, message));
+  };
+  for (const stalePath of reports.stale) {
+    block('resolution-report', `[resolution-report] ${stalePath} is out of date — commit the regenerated resolution/ files`);
+  }
+  if (pageVersions.diagnostic) block('page-versions', diagnosticLine(pageVersions.diagnostic));
+  for (const issue of curriculumErrors(curriculum)) block('curriculum', `[curriculum:${issue.kind}] ${issue.message}`);
+  for (const issue of notation.filter((d) => d.severity === 'error')) block('notation', `[notation:${issue.code}] ${issue.message}`);
+  for (const issue of alignment.filter((d) => d.severity === 'error')) block('alignment', `[alignment:${issue.code}] ${issue.message}`);
+  for (const issue of math.filter((item) => item.severity === 'error')) block('math', diagnosticLine(issue));
+  for (const issue of waivers.filter((d) => d.severity === 'error')) block('waivers', diagnosticLine(issue));
+  for (const [source, group] of floatGroups) {
+    for (const issue of group.filter((d) => d.severity === 'error')) block(source, `[${issue.code}] ${issue.message}`);
+  }
+
+  if (failures.length > 0) {
+    const summary = log.close();
+    console.error(
+      `Content manifest has ${failures.length} blocking diagnostic(s):\n${failures.map((line) => `- ${line}`).join('\n')}\n` +
+        `Run log: ${summary.relativeDirectory} (${summary.counts.ERROR} error(s), ${summary.counts.WARNING} warning(s)).`,
+    );
+    return 1;
+  }
+
+  const itemCount = manifest.lessons.reduce((count, lesson) => count + lesson.assessments.length, 0);
+  const relPath = MANIFEST_PATH.replace(`${process.cwd()}/`, '');
+  console.log(
+    log.info(
+      'manifest',
+      `Manifest written to ${relPath} (schema v${manifest.schemaVersion}, knowledge v${manifest.about.knowledge.version}): ` +
+        `${manifest.competencies.length} competencies, ${manifest.lessons.length} lessons, ` +
+        `${itemCount} lesson assessment links, ${manifest.notation.definitions.length} notation definitions, ` +
+        `${manifest.sources.length} sources, ${manifest.tracks.length} track(s). ` +
+        `Content fingerprint ${manifest.hashes.contentTree}.`,
+    ),
+  );
+
+  const summary = log.close();
+  console.log(
+    `Run log: ${summary.relativeDirectory} ` +
+      `(${summary.counts.ERROR} error(s), ${summary.counts.WARNING} warning(s), ${summary.counts.INFO} info).`,
+  );
+  return 0;
+}