session-orchestrator 3.24.0 → 4.0.1

package/scripts/run-quality-gate.mjs

@@ -14,6 +14,9 @@
  *                            defaults from the policy file or built-in defaults apply.
  *   --files <f1,f2,...>      Comma-separated file list (incremental + per-file).
  *   --session-start-ref <r>  Git ref for diff base (incremental, to find changed files).
+ *   --ledger-root <path>     Repo root the telemetry event is pinned to (and the
+ *                            root session attribution is read from). Only the
+ *                            pre-push hook passes it; see the emission block below.
  *   -h, --help               Show this help and exit.
  *
  * Exit codes:
@@ -31,8 +34,8 @@
  *   scripts/lib/gates/gate-{baseline,incremental,full,per-file}.mjs
  */
 
-import { existsSync, readFileSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 
@@ -80,7 +83,7 @@ const argv = process.argv.slice(2);
 if (argv.includes('-h') || argv.includes('--help')) {
   process.stdout.write(
     'Usage: run-quality-gate.mjs --variant <variant> [--config <json-or-file>] ' +
-    '[--files <file1,file2,...>] [--session-start-ref <ref>]\n\n' +
+    '[--files <file1,file2,...>] [--session-start-ref <ref>] [--ledger-root <path>]\n\n' +
     'Variants: baseline, incremental, full-gate, per-file\n\n' +
     'Exit codes:\n' +
     '  0 — pass (non-blocking variants always exit 0)\n' +
@@ -94,6 +97,7 @@ let variant = '';
 let config = '';
 let files = '';
 let sessionStartRef = '';
+let ledgerRootArg = '';
 
 for (let i = 0; i < argv.length; i++) {
   const arg = argv[i];
@@ -114,6 +118,10 @@ for (let i = 0; i < argv.length; i++) {
       if (i + 1 >= argv.length) die('Missing value for --session-start-ref');
       sessionStartRef = argv[++i];
       break;
+    case '--ledger-root':
+      if (i + 1 >= argv.length) die('Missing value for --ledger-root');
+      ledgerRootArg = argv[++i];
+      break;
     default:
       die(`Unknown argument: ${arg}`);
   }
@@ -208,6 +216,76 @@ function suiteCountsFromGateStdout(stdout) {
   return admitSuiteCounts(test);
 }
 
+/**
+ * Lift `test.failed_files` out of a gate sub-script's JSON stdout envelope.
+ *
+ * Envelope adapter, same posture as {@link suiteCountsFromGateStdout}: it
+ * decides only whether a NAMED-FILE measurement exists, never what the names
+ * mean. `null` — never `[]` — for every non-measurement, so the caller OMITS
+ * the key instead of publishing an empty array that reads as "no file failed".
+ *
+ * Only `gate-full.mjs` publishes the key, and only when the runner printed a
+ * file-level summary; every other variant emits a bare status string.
+ *
+ * Never throws.
+ *
+ * @param {string} stdout — the gate sub-script's captured stdout.
+ * @returns {string[]|null}
+ */
+function failedFilesFromGateStdout(stdout) {
+  if (typeof stdout !== 'string' || !stdout.trim()) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    return null;
+  }
+  const files = parsed?.test?.failed_files;
+  if (!Array.isArray(files) || files.length === 0) return null;
+  const named = files.filter((f) => typeof f === 'string' && f.trim());
+  return named.length > 0 ? named : null;
+}
+
+/**
+ * Validate and resolve the `--ledger-root` flag (see the telemetry block below).
+ *
+ * Only the pre-push hook passes this, and it hands over a path the gate then
+ * WRITES to — so a typo must not silently create an `.orchestrator/metrics/`
+ * tree somewhere arbitrary. The check is therefore two-part: the value must be
+ * an existing DIRECTORY, and it must already contain an `.orchestrator/`
+ * directory — the marker of a root this harness has already been initialised in.
+ *
+ * The alternative check (`git rev-parse --show-toplevel` with cwd = that path,
+ * compared against the value) is rejected on cost: it spawns a process on every
+ * gate run to prove a property two `statSync` calls already prove. The one case
+ * it accepts and this one rejects — a git root that has never run the
+ * orchestrator — is precisely the case with no ledger to pin to.
+ *
+ * A bad value NEVER crashes the gate: it warns once on stderr and returns
+ * `null`, which restores the previous resolution
+ * (`CLAUDE_PROJECT_DIR ?? CODEX_PROJECT_DIR ?? repoRoot`) at the call sites.
+ * The gate's exit code is the authoritative output; telemetry is best-effort.
+ *
+ * @param {string} value — raw flag value (`''` when the flag was not passed).
+ * @returns {string|null} absolute, validated root — or `null` to fall back.
+ */
+function resolveLedgerRoot(value) {
+  const raw = (value || '').trim();
+  if (!raw) return null;
+  const abs = resolve(raw);
+  try {
+    if (statSync(abs).isDirectory() && statSync(join(abs, '.orchestrator')).isDirectory()) {
+      return abs;
+    }
+  } catch { /* falls through to the warn below */ }
+  warn(
+    `--ledger-root '${raw}' is not an initialised project root ` +
+    '(existing directory containing .orchestrator/) — falling back to the default ' +
+    'telemetry destination.',
+  );
+  return null;
+}
+
 /**
  * Resolve the active wave number from the wave-scope sidecar (#966 step 1).
  *
@@ -325,24 +403,63 @@ if (result.error && typeof result.status !== 'number') {
 // (single emission path). `sessionAttribution` is the shared helper in
 // events.mjs (#941); this CLI wrapper runs against the CWD `repoRoot`, so the
 // bare emitEvent destination (SO_PROJECT_DIR default) is correct here.
+//
+// EXCEPT under the pre-push hook, which is the one caller that runs the gate in
+// a tree that is about to be DELETED. `.husky/pre-push` materialises the tracked
+// tree into a temp dir and deliberately scrubs every `*PROJECT_DIR` name before
+// invoking the gate there, so `getProjectDir()` resolves to that temp tree (it
+// carries both a CLAUDE.md (or AGENTS.md) and a .git) and the record lands in
+// `<tmp>/.orchestrator/metrics/events.jsonl`, which the hook's EXIT trap then
+// removes. Measured 2026-09-06: a pre-push run that BLOCKED a push left no
+// `orchestrator.quality_gate.failed` line in this repo's ledger at all — the
+// gate failure was, by construction, the one event that could never be recorded.
+//
+// `--ledger-root` is that hook's channel for handing back the root it already
+// knows (`git rev-parse --show-toplevel`, read BEFORE it cds). It pins ONLY the
+// telemetry destination and the attribution root — every other path the gate
+// resolves stays inside the tree actually under test, which is the whole point
+// of the materialisation. Absent (every other caller) → unchanged behaviour:
+// `emitEvent`'s own default resolution.
+//
+// It is an ARGV FLAG and not an env var, and that is load-bearing. Measured
+// 2026-09-06 with the env-var form: `SO_GATE_LEDGER_ROOT=$tmp npx vitest run
+// tests/scripts/run-quality-gate.test.mjs -t "telemetry emission"` → `8 failed |
+// 1 passed`. The chain was: hook exports the var → `npm run quality-gate` →
+// `gate-full.mjs` spawns `npm test` → every vitest worker inherits it → the
+// suite's own gate spawns spread `...process.env`, so the pinned root outranked
+// their per-test project dir and the gate's telemetry tests wrote to the hook's
+// root. The gate that releases 4.0.0 would have blocked on itself. An env var is
+// inherited by every descendant; a flag reaches exactly one process.
+//
 // Best-effort: a telemetry failure must NEVER alter the gate's authoritative
 // exit code — which is why the counts parse also lives inside this try.
 const exitCode = result.status ?? 1;
+const ledgerRoot = resolveLedgerRoot(ledgerRootArg);
 try {
   const counts = suiteCountsFromGateStdout(gateStdout);
+  // The names behind `counts.failed`. Absent, never `[]` — see
+  // `failedFilesFromGateStdout`.
+  const failedFiles = failedFilesFromGateStdout(gateStdout);
   // Wave-scope sidecar is read from the SAME project dir the event lands in
   // (emitEvent's own destination precedence), so a tmp-scoped run cannot pick
   // up the host repo's live wave. Mirrors the hook's projectDir resolution.
   const waveNumber = resolveWaveNumber(
-    process.env.CLAUDE_PROJECT_DIR ?? process.env.CODEX_PROJECT_DIR ?? repoRoot,
+    ledgerRoot ?? process.env.CLAUDE_PROJECT_DIR ?? process.env.CODEX_PROJECT_DIR ?? repoRoot,
+  );
+  await emitEvent(
+    `orchestrator.quality_gate.${exitCode === 0 ? 'passed' : 'failed'}`,
+    {
+      variant,
+      exit_code: exitCode,
+      ...(counts ? { counts } : {}),
+      ...(failedFiles ? { failed_files: failedFiles } : {}),
+      ...(waveNumber !== null ? { wave_number: waveNumber } : {}),
+      ...sessionAttribution(ledgerRoot ?? repoRoot),
+    },
+    // `{}` is byte-identical to omitting the argument (`opts.repoRoot ??
+    // getProjectDir()`), so the default path is untouched.
+    ledgerRoot ? { repoRoot: ledgerRoot } : {},
   );
-  await emitEvent(`orchestrator.quality_gate.${exitCode === 0 ? 'passed' : 'failed'}`, {
-    variant,
-    exit_code: exitCode,
-    ...(counts ? { counts } : {}),
-    ...(waveNumber !== null ? { wave_number: waveNumber } : {}),
-    ...sessionAttribution(repoRoot),
-  });
 } catch { /* best-effort telemetry — gate result is authoritative */ }
 
 process.exit(exitCode);

package/scripts/site-numbers.mjs

@@ -66,6 +66,31 @@
  *   --write  rewrite the span contents in place, and refresh `site/_census.json`
  *            from the same measurement (only when --site is the repo's `site/`).
  *
+ * ## The two usage metrics (`npm-downloads-30d`, `github-stars`)
+ *
+ * These two are the only ones whose source is NOT this repository: they are
+ * fetched over the network, and only under `--write` (5 s timeout). `--check`
+ * never opens a socket — it compares the page against `site/_census.json`, which
+ * IS their truth between writes. That is what keeps the CI/build guard offline
+ * and deterministic; a `--check` that fetched would go red whenever npm's API
+ * was slow, which is a signal about npm and not about the page.
+ *
+ * On a fetch failure `--write` keeps the previous snapshot value and warns. It
+ * never writes a placeholder over a real number: the number on the page stays
+ * the last one that was actually measured, and the WARN names why it did not
+ * move. With no snapshot to keep, the metric simply has no value and the run
+ * fails loudly (the existing partial-census guard) rather than shipping "n/a".
+ *
+ * ## The census blocks in `site/llms-full.txt` and `site/llms.txt`
+ *
+ * The same measurement also fills a marker-bounded line in every file listed in
+ * `CENSUS_BLOCK_FILES` (`<!-- census:start -->` … `<!-- census:end -->`) — the
+ * two plain-text surfaces LLM crawlers read. Only the text BETWEEN the
+ * markers is rewritten; everything else in that file is hand-authored prose and
+ * is handed back byte-for-byte. A missing end marker is a hard error, never a
+ * silent skip — a generator that quietly stops filling a surface is the exact
+ * failure this file exists to end.
+ *
  * Exit codes (`.claude/rules/cli-design.md`):
  *   0 — no drift (--check) / files updated or already current (--write)
  *   1 — drift found (--check), or a contract violation in either mode
@@ -327,7 +352,7 @@ export function isDirty(root) {
       ['--no-optional-locks', 'status', '--porcelain', '--untracked-files=no'],
       { cwd: root, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] },
     );
-    return out.split('\n').filter(Boolean).length > 0;
+    return out.split('\n').some(Boolean);
   } catch {
     return null;
   }
@@ -458,6 +483,37 @@ export const METRIC_DEFS = Object.freeze([
     source: 'jq length .orchestrator/policy/blocked-commands.json',
     compute: (root) => fmtCount(countBlockedCommands(root)),
   },
+  {
+    id: 'npm-downloads-30d',
+    provenance: false,
+    // Network-sourced: absent from EVERY offline run, which is most of them
+    // (--check never fetches). The snapshot is therefore not a fresh-clone
+    // convenience here but the metric's normal answer between two --write runs.
+    snapshotFallback: true,
+    network: true,
+    url: 'https://api.npmjs.org/downloads/point/last-month/session-orchestrator',
+    field: 'downloads',
+    source:
+      'curl -s https://api.npmjs.org/downloads/point/last-month/session-orchestrator | jq .downloads   (fetched only under --write)',
+    compute: (root, ctx) => fmtCount(ctx?.usage?.['npm-downloads-30d'] ?? null),
+  },
+  {
+    id: 'github-stars',
+    provenance: false,
+    snapshotFallback: true,
+    network: true,
+    url: 'https://api.github.com/repos/Kanevry/session-orchestrator',
+    field: 'stargazers_count',
+    // The API answers unauthenticated requests but rejects ones without a
+    // User-Agent, and the Accept header pins the response schema version.
+    headers: {
+      Accept: 'application/vnd.github+json',
+      'User-Agent': 'session-orchestrator-site-numbers',
+    },
+    source:
+      'curl -s https://api.github.com/repos/Kanevry/session-orchestrator | jq .stargazers_count   (fetched only under --write)',
+    compute: (root, ctx) => fmtCount(ctx?.usage?.['github-stars'] ?? null),
+  },
   {
     id: 'counted-at',
     provenance: true,
@@ -606,7 +662,7 @@ export function writeCensusSnapshot(root, values) {
  *   `fromSnapshot` lists the metrics answered by `site/_census.json` because
  *   their live source was absent.
  */
-export function collect(root) {
+export function collect(root, ctx = {}) {
   const values = {};
   const missing = [];
   const warnings = [];
@@ -619,8 +675,8 @@ export function collect(root) {
     // LIVE FIRST, always. The snapshot is a fallback, never a cache: reading it
     // first (or memoising a live value into it) would freeze the page on the
     // last release's numbers while the repository moved on.
-    let v = def.compute(root);
-    if ((v === null || v === undefined || v === '') && def.snapshotFallback === true) {
+    let v = def.compute(root, ctx);
+    if ((v === null || v === undefined || v === '') && def.snapshotFallback) {
       if (snapshot === undefined) snapshot = readCensusSnapshot(root);
       const s = snapshot?.[def.id];
       if (s !== undefined) {
@@ -632,9 +688,17 @@ export function collect(root) {
     else values[def.id] = String(v);
   }
 
-  if (fromSnapshot.length > 0) {
+  // Only the REPOSITORY-sourced fallbacks are worth a warning. For the two
+  // network metrics the snapshot is not a degraded answer but the designed one
+  // between two `--write` runs — warning about them would fire on every single
+  // `--check`, and a warning that always fires is a broken instrument
+  // (`.claude/rules/host-resources.md` HR-101).
+  const localFallbacks = fromSnapshot.filter(
+    (id) => !METRIC_DEFS.find((d) => d.id === id)?.network,
+  );
+  if (localFallbacks.length > 0) {
     warnings.push(
-      `${fromSnapshot.join(', ')} read from ${CENSUS_FILE.join('/')} — the live source is absent under ${root} ` +
+      `${localFallbacks.join(', ')} read from ${CENSUS_FILE.join('/')} — the live source is absent under ${root} ` +
         '(expected in a fresh clone / tarball build; the snapshot is only as current as the last --write)',
     );
   }
@@ -662,6 +726,215 @@ export function collect(root) {
   return { values, missing, warnings, fromSnapshot };
 }
 
+// ---------------------------------------------------------------------------
+// The two network metrics
+// ---------------------------------------------------------------------------
+
+/** Metrics whose source is an HTTP endpoint rather than this repository. */
+export const NETWORK_METRIC_DEFS = Object.freeze(METRIC_DEFS.filter((d) => d.network));
+
+/** Hard ceiling on a single usage fetch. Revisit if a source starts answering slower. */
+export const FETCH_TIMEOUT_MS = 5000;
+
+/**
+ * Fetch the usage metrics. CALLED ONLY UNDER `--write` — see the header for why
+ * `--check` must stay offline.
+ *
+ * Every failure mode (timeout, non-2xx, unparseable body, missing/non-numeric
+ * field) lands in the same place: a WARN naming the reason and the snapshot
+ * value that will be kept, and NO entry in the returned map. `collect()` then
+ * falls back to the snapshot exactly as it does for a fresh clone's ledgers —
+ * so a failed fetch degrades to "the last measured number", never to a
+ * placeholder written over a real one.
+ *
+ * @param {string} root repo root (its `site/_census.json` supplies the WARN's value)
+ * @param {{fetchImpl?: Function, timeoutMs?: number, warn?: (s:string)=>void}} [opts]
+ * @returns {Promise<Record<string, number>>} only the metrics that actually resolved
+ */
+export async function fetchUsageMetrics(root, opts = {}) {
+  // Offline switch (tests, air-gapped CI): SO_SITE_NUMBERS_OFFLINE=1 skips every
+  // network call and lets the snapshot answer, exactly like a failed fetch would,
+  // minus the per-metric WARN noise. Measured 2026-09-07: two fixture tests that
+  // spawned --write went red on a GitHub 403 rate limit; a test must never depend
+  // on api.github.com being reachable.
+  if (process.env.SO_SITE_NUMBERS_OFFLINE === '1') {
+    (opts.warn ?? ((m) => process.stderr.write(`${m}\n`)))(
+      'site-numbers: SO_SITE_NUMBERS_OFFLINE=1 — usage metrics answered from the snapshot',
+    );
+    return {};
+  }
+  const doFetch = opts.fetchImpl ?? globalThis.fetch;
+  const timeoutMs = opts.timeoutMs ?? FETCH_TIMEOUT_MS;
+  const warn = opts.warn ?? ((s) => process.stderr.write(`${s}\n`));
+  const out = {};
+  let snapshot;
+
+  for (const def of NETWORK_METRIC_DEFS) {
+    try {
+      const res = await doFetch(def.url, {
+        signal: AbortSignal.timeout(timeoutMs),
+        headers: def.headers ?? {},
+      });
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      const body = await res.json();
+      const v = body?.[def.field];
+      if (typeof v !== 'number' || !Number.isFinite(v)) {
+        throw new Error(`no numeric "${def.field}" field in the response`);
+      }
+      out[def.id] = Math.trunc(v);
+    } catch (err) {
+      if (snapshot === undefined) snapshot = readCensusSnapshot(root);
+      const kept = snapshot?.[def.id];
+      warn(
+        `WARN site-numbers: ${def.id} fetch failed (${err?.message ?? String(err)}), keeping snapshot ` +
+          `${kept ?? '(none — this metric will have no value and the run will fail)'}`,
+      );
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// The marker-bounded census line in site/llms-full.txt
+// ---------------------------------------------------------------------------
+
+/** Files the census line lives in, relative to the SITE directory. */
+export const LLMS_FULL_FILE = 'llms-full.txt';
+export const LLMS_FILE = 'llms.txt';
+
+/**
+ * Every file carrying a marker-bounded census block.
+ *
+ * A CONSTANT LIST rather than a second code path per file: `site/llms.txt` used
+ * to hand-maintain its own "## Surface" line, and it drifted exactly as the page
+ * had — measured 2026-09-07 it claimed `661 vitest test files` while every other
+ * surface (and the repository) said 662, and `--check` exited 0 because the
+ * generator did not know that file existed. Adding a file to this array is the
+ * whole change needed to bring it under the guard.
+ */
+export const CENSUS_BLOCK_FILES = Object.freeze([LLMS_FULL_FILE, LLMS_FILE]);
+
+export const CENSUS_START = '<!-- census:start -->';
+export const CENSUS_END = '<!-- census:end -->';
+
+/**
+ * The metric ids the census line carries, with the label each one gets.
+ *
+ * A SUBSET of METRIC_IDS on purpose: the line is prose for a reader, not the
+ * machine receipt (`site/_census.json` is that, and carries all of them).
+ * `version`, `counted-at` and `counted-sha` are not in this list because they
+ * are rendered as the line's opening clause, not as `label value` pairs.
+ */
+export const CENSUS_LINE_FIELDS = Object.freeze([
+  { id: 'skills', label: 'skills' },
+  { id: 'commands', label: 'commands' },
+  { id: 'agents', label: 'agents' },
+  { id: 'hooks', label: 'hooks' },
+  { id: 'tests', label: 'test files' },
+  { id: 'sessions', label: 'sessions' },
+  { id: 'learnings', label: 'learnings' },
+  { id: 'npm-downloads-30d', label: 'npm downloads (30d)' },
+  { id: 'github-stars', label: 'GitHub stars' },
+]);
+
+/**
+ * Render the census line.
+ *
+ * The `Version X.Y.Z` opening is load-bearing beyond this file: `SURFACES` in
+ * `scripts/release.mjs` matches `/Version\s+(\d+\.\d+\.\d+)/g` against
+ * `site/llms-full.txt`, so the literal must keep exactly this shape or the
+ * release drift check stops seeing the surface it guards.
+ *
+ * @returns {{line: string, head: string, tail: string}}
+ *   `head` is the provenance clause (warn-only, like the spans), `tail` the
+ *   counts (real drift). Split so `--check` can tell the two apart.
+ */
+export function renderCensusLine(values) {
+  const head = `Version ${values.version} · counted ${values['counted-at']} at ${values['counted-sha']}`;
+  const tail = CENSUS_LINE_FIELDS.map((f) => `${f.label} ${values[f.id]}`).join(' · ');
+  return { line: `${head} · ${tail}`, head, tail };
+}
+
+/**
+ * Replace the text between the two markers, and nothing else.
+ *
+ * A start marker without an end marker is a HARD ERROR rather than an append:
+ * guessing where the block ends would let one bad edit swallow the rest of a
+ * hand-authored file.
+ *
+ * @returns {{ok: true, text: string, changed: boolean, current: string}
+ *          | {ok: false, reason: string}}
+ */
+export function rewriteCensusBlock(text, line) {
+  const start = text.indexOf(CENSUS_START);
+  const end = text.indexOf(CENSUS_END);
+  if (start === -1 && end === -1) return { ok: false, reason: 'no census markers' };
+  if (start === -1) return { ok: false, reason: `"${CENSUS_END}" without "${CENSUS_START}"` };
+  if (end === -1) return { ok: false, reason: `"${CENSUS_START}" without "${CENSUS_END}"` };
+  if (end < start) return { ok: false, reason: 'census markers are in the wrong order' };
+
+  const inner = text.slice(start + CENSUS_START.length, end);
+  const current = inner.trim();
+  const next = `${text.slice(0, start + CENSUS_START.length)}\n${line}\n${text.slice(end)}`;
+  return { ok: true, text: next, changed: next !== text, current };
+}
+
+/**
+ * Judge (and optionally rewrite) the census block of ONE file under `siteDir`.
+ *
+ * Mirrors the span policy: a difference only in the provenance clause is
+ * `stale` (warn-only — a claim about the past does not become false when HEAD
+ * moves), a difference in the counts is `drift`.
+ *
+ * @param {{write?:boolean, file?:string}} [opts] `file` is relative to `siteDir`
+ *   and defaults to `llms-full.txt`; `syncCensusBlocks` iterates CENSUS_BLOCK_FILES.
+ * @returns {{present:boolean, error?:string, drift?:boolean, stale?:boolean,
+ *            written?:boolean, file:string}}
+ */
+export function syncCensusBlock(siteDir, values, { write = false, file = LLMS_FULL_FILE } = {}) {
+  const abs = join(siteDir, file);
+  // Absent file: not this generator's business to create one. Every HTML
+  // fixture directory in the test suite is such a case.
+  if (!existsSync(abs) || !statSync(abs).isFile()) return { present: false, file: abs };
+
+  const { line, tail } = renderCensusLine(values);
+  const text = readFileSync(abs, 'utf8');
+  const res = rewriteCensusBlock(text, line);
+  if (!res.ok) return { present: true, file: abs, error: res.reason };
+
+  // Same split as the spans: `counted <date> at <sha>` lagging is a claim about
+  // the past, not a wrong number.
+  const provenanceOnly =
+    res.current !== line &&
+    res.current.startsWith(`Version ${values.version} · `) &&
+    res.current.endsWith(tail);
+  const out = {
+    present: true,
+    file: abs,
+    drift: res.current !== line && !provenanceOnly,
+    stale: provenanceOnly,
+    written: false,
+  };
+  if (write && res.changed) {
+    writeFileSync(abs, res.text, 'utf8');
+    out.written = true;
+  }
+  return out;
+}
+
+/**
+ * Judge (and optionally rewrite) EVERY file in `CENSUS_BLOCK_FILES`.
+ *
+ * One measurement, N surfaces — the same reason `writeCensusSnapshot` takes an
+ * already-computed `values` map: two census runs inside one invocation can
+ * disagree across midnight or a concurrent ledger append.
+ *
+ * @returns {Array<ReturnType<typeof syncCensusBlock>>} in CENSUS_BLOCK_FILES order
+ */
+export function syncCensusBlocks(siteDir, values, { write = false } = {}) {
+  return CENSUS_BLOCK_FILES.map((file) => syncCensusBlock(siteDir, values, { write, file }));
+}
+
 // ---------------------------------------------------------------------------
 // Markup
 // ---------------------------------------------------------------------------
@@ -881,7 +1154,7 @@ export function main(argv = process.argv.slice(2), env = {}) {
     return 2;
   }
 
-  const { values, missing, warnings, fromSnapshot } = collect(root);
+  const { values, missing, warnings, fromSnapshot } = collect(root, { usage: env.usage });
   if (missing.length > 0) {
     stderr(
       `Error: could not measure ${missing.join(', ')} under ${root} — ` +
@@ -961,6 +1234,38 @@ export function main(argv = process.argv.slice(2), env = {}) {
     });
   }
 
+  // The marker-bounded census line in site/llms-full.txt. Judged with the same
+  // split as the spans (counts = drift, provenance = warn-only) and rewritten
+  // BETWEEN the markers only.
+  const censusDriftLines = [];
+  const censusBlocks = syncCensusBlocks(siteDir, values, { write: args.write });
+  for (const b of censusBlocks) {
+    if (b.error) {
+      stderr(
+        `Error: ${b.file}: ${b.error} — the census block contract is broken ` +
+          `(expected "${CENSUS_START}" … "${CENSUS_END}")`,
+      );
+      contractTotal += 1;
+    } else if (b.present) {
+      if (b.drift && !args.write) {
+        // Held back rather than printed here: under --json, stdout carries the
+        // envelope and NOTHING else (`cli-design.md` — data on stdout). Printing
+        // it inline put a bare DRIFT line in front of the JSON and made the
+        // envelope unparseable, which is the same class of silent failure as an
+        // unjudged surface: a consumer sees a parse error, not a drift report.
+        censusDriftLines.push(`DRIFT ${b.file}: the census block does not match this measurement`);
+        driftTotal += 1;
+      } else if (b.drift) {
+        driftTotal += 1;
+      } else if (b.stale) {
+        stderr(`stale ${b.file}: only the counted date/sha of the census block lags`);
+      }
+    }
+  }
+  // Kept as its own name in the --json envelope for the consumers that already
+  // read `llmsFull`; `censusBlocks` below carries all of them.
+  const llms = censusBlocks[CENSUS_BLOCK_FILES.indexOf(LLMS_FULL_FILE)];
+
   // The named silent-failure class: a generator that matches nothing, changes
   // nothing, and reports success. Zero spans means the markup contract is not in
   // the page — that is a defect, in BOTH modes, never a no-op.
@@ -1040,6 +1345,23 @@ export function main(argv = process.argv.slice(2), env = {}) {
           written: writtenTotal,
           rejected: rejectedTotal,
           fromSnapshot,
+          llmsFull: {
+            file: llms.present ? relative(root, llms.file) : null,
+            present: llms.present,
+            error: llms.error ?? null,
+            drift: llms.drift === true,
+            stale: llms.stale === true,
+            written: llms.written === true,
+          },
+          censusBlocks: censusBlocks.map((b, i) => ({
+            name: CENSUS_BLOCK_FILES[i],
+            file: b.present ? relative(root, b.file) : null,
+            present: b.present,
+            error: b.error ?? null,
+            drift: b.drift === true,
+            stale: b.stale === true,
+            written: b.written === true,
+          })),
           censusWritten,
           ok,
         },
@@ -1051,6 +1373,9 @@ export function main(argv = process.argv.slice(2), env = {}) {
     stdout(
       `site-numbers: wrote ${writtenTotal} value(s) across ${files.length} file(s) in ${siteDir}` +
         ` (${spanTotal} metric cells @ ${values['counted-sha']}${dirty ? '+dirty' : ''})` +
+        censusBlocks
+          .map((b, i) => (b.written ? ` + ${CENSUS_BLOCK_FILES[i]}` : ''))
+          .join('') +
         (censusWritten ? ` + ${CENSUS_FILE.join('/')}` : ''),
     );
   } else {
@@ -1062,6 +1387,7 @@ export function main(argv = process.argv.slice(2), env = {}) {
         stderr(`stale ${f.file}:${s.line} ${s.metric}: "${s.actual}" → would become "${s.expected}" on --write`);
       }
     }
+    for (const l of censusDriftLines) stdout(l);
     stdout(
       driftTotal === 0 && !noSpans && contractTotal === 0
         ? `site-numbers: ${spanTotal} metric cell(s) current across ${files.length} file(s)`
@@ -1078,4 +1404,14 @@ const isMain =
   process.argv[1] !== undefined &&
   resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url));
 
-if (isMain) process.exit(main());
+if (isMain) {
+  const argv = process.argv.slice(2);
+  const parsed = parseArgs(argv);
+  // The ONLY network call in this file, and only on the write path — see the
+  // header. A `--check` (the CI/build guard) never reaches this branch.
+  const usage =
+    !parsed.error && parsed.write && !parsed.help && !parsed.version
+      ? await fetchUsageMetrics(resolve(parsed.root ?? process.cwd()))
+      : {};
+  process.exit(main(argv, { usage }));
+}