@opengsd/gsd-core 1.12.0 → 1.14.0

package/hooks/lib/isolation-sentinel.js

@@ -56,6 +56,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { parseDispatchIdentity } = require('./dispatch-identity.js');
 
 // Isolation modes ADR-1239 declares (mirrors gsd-tools.cjs
 // routeDispatchIsolation / routeRecordDispatchIsolation).
@@ -223,26 +224,40 @@ function readSentinel(cwd, { clock = Date } = {}) {
 }
 
 /**
- * #3045 SECURITY F2: extract the `{plan, phase}` a specific Agent()/Task()
- * dispatch is FOR, from the one place that data is reliably embedded today —
- * the dispatch prompt/description text (`execute-phase.md`'s Agent() block
- * uses the literal shape `description="Execute plan {plan_number} of phase
- * {phase_number}"`, and the prompt body's `<objective>` repeats "Execute plan
- * {plan_number} of phase {phase_number}-{phase_name}." verbatim — the SAME
- * text the orchestrator-worktree EXECUTOR_PROMPT template and Cursor's `task`
- * field carry, since Cursor dispatches the same prompt content). There is no
- * structured per-dispatch kwarg carrying plan/phase identifiers today (#3045
- * would need a larger dispatch-protocol change to add one) — this is
- * therefore a best-effort, NOT a guaranteed, extraction: a dispatch whose
- * text doesn't match the expected shape returns `{ plan: null, phase: null }`
- * and the caller must NOT treat that as a mismatch (see
- * `sentinelAppliesToDispatch`).
+ * #3045 SECURITY F2 / #4594: extract the `{plan, phase}` a specific
+ * Agent()/Task() dispatch is FOR. Variadic — accepts any number of text
+ * sources (short description, full prompt body, etc) and delegates to
+ * `hooks/lib/dispatch-identity.js::parseDispatchIdentity`, the one canonical
+ * owner of both the `[gsd:dispatch phase="…" plan="…"]` marker format and its
+ * prose fallback (see `.gsd/phase/fix-4594-dispatch-identity-seam/40-design.md`).
+ *
+ * MARKER-FIRST CONTRACT: producers embed a structured marker carrying the
+ * exact shell values the sentinel itself records (`$PHASE_NUMBER`,
+ * `$plan_id`), so producer and consumer agree by construction, independent
+ * of how the prose reads or whether a model paraphrases the dispatch
+ * sentence. Only when no marker is found anywhere in the supplied texts does
+ * this fall back to scanning for the prose frame "execute plan <token> of
+ * phase <PHASE TOKEN>".
+ *
+ * The prose fallback is now CORRECT-OR-ABSENT rather than possibly-wrong:
+ * the phase token is bounded by the same grammar `src/phase-id.cts` owns
+ * (ADR-2121), so a directory-name slug or trailing punctuation can no longer
+ * leak into the phase value, and the prose plan token is never reported at
+ * all (it lives in a different namespace than the sentinel's phase-prefixed,
+ * slugged `plan_id` — reporting it was the #4594 false-mismatch bug).
+ *
+ * This is still a best-effort, NOT a guaranteed, extraction: a dispatch that
+ * carries neither a marker nor a matching prose frame in ANY supplied text
+ * returns `{ plan: null, phase: null }`, and the caller MUST NEVER treat
+ * that as a mismatch — see `sentinelAppliesToDispatch`, whose whole
+ * contract depends on "missing" and "wrong" being distinguishable.
+ *
+ * Returns only the two-field `{ plan, phase }` shape existing callers
+ * depend on — `parseDispatchIdentity`'s `source` field is discarded here.
  */
-function extractDispatchIdentifiers(text) {
-  if (typeof text !== 'string' || text.length === 0) return { plan: null, phase: null };
-  const m = /execute\s+plan\s+(\S+)\s+of\s+phase\s+(\S+)/i.exec(text);
-  if (!m) return { plan: null, phase: null };
-  return { plan: m[1], phase: m[2] };
+function extractDispatchIdentifiers(...texts) {
+  const { phase, plan } = parseDispatchIdentity(...texts);
+  return { plan, phase };
 }
 
 /**
@@ -265,6 +280,29 @@ function sentinelAppliesToDispatch(sentinel, dispatchIds) {
   return true;
 }
 
+/**
+ * #4594 F3: build the structured "a fresh sentinel was present but did not
+ * apply to this dispatch" descriptor, mirroring the exact comparison
+ * `sentinelAppliesToDispatch` performs. Returns `null` when the sentinel is
+ * absent, stale, malformed, or DOES apply — i.e. exactly when there is
+ * nothing to report as discarded. Otherwise returns the nested
+ * `{ sentinel: {phase, plan}, dispatch: {phase, plan} }` shape, reusing the
+ * `{phase, plan}` pair already flowing through this module end to end rather
+ * than renaming its fields into an ad hoc `sentinelPhase`/`dispatchPlan` bag
+ * (previously rebuilt identically at two call sites in the guard hooks).
+ */
+function buildSentinelDiscard(sentinel, dispatchIds) {
+  if (!sentinel || !sentinel.present || sentinel.stale) return null;
+  if (sentinelAppliesToDispatch(sentinel, dispatchIds)) return null;
+  return {
+    sentinel: { phase: sentinel.phase ?? null, plan: sentinel.plan ?? null },
+    dispatch: {
+      phase: dispatchIds ? (dispatchIds.phase ?? null) : null,
+      plan: dispatchIds ? (dispatchIds.plan ?? null) : null,
+    },
+  };
+}
+
 module.exports = {
   VALID_ISOLATION,
   SENTINEL_RELATIVE_PATH,
@@ -274,4 +312,5 @@ module.exports = {
   readSentinel,
   extractDispatchIdentifiers,
   sentinelAppliesToDispatch,
+  buildSentinelDiscard,
 };

package/hooks/managed-hooks-registry.cjs

@@ -36,6 +36,7 @@ const MANAGED_HOOKS = [
   'gsd-prompt-guard.js',
   'gsd-read-guard.js',
   'gsd-read-injection-scanner.js',
+  'gsd-secret-read-guard.js',
   'gsd-session-state.sh',
   'gsd-statusline.js',
   'gsd-update-banner.js',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengsd/gsd-core",
-  "version": "1.12.0",
+  "version": "1.14.0",
   "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
   "main": ".opencode/plugins/gsd-core.js",
   "bin": {
@@ -75,7 +75,8 @@
     "espree": "^10.4.0",
     "fast-check": "^4.8.0",
     "globals": "^16.5.0",
-    "js-yaml": "^4.3.1",
+    "gpt-tokenizer": "4.0.0",
+    "js-yaml": "^4.3.2",
     "mutation-testing-metrics": "^3.7.3",
     "re2js": "^2.8.6",
     "typescript": "^6.0.3",
@@ -84,7 +85,8 @@
   "overrides": {
     "qs": ">=6.15.2",
     "body-parser": ">=2.3.0",
-    "@hono/node-server": ">=2.0.5"
+    "@hono/node-server": ">=2.0.5",
+    "hono": ">=4.13.5"
   },
   "optionalDependencies": {
     "fallow": "^2.70.0"
@@ -108,7 +110,7 @@
     "gen:registry": "node scripts/gen-registry.cjs --write",
     "gen:install-tree": "node scripts/gen-install-tree-fixtures.cjs",
     "gen:section-manifest": "node scripts/gen-section-manifest.cjs --write",
-    "regen:derived": "npm run build && npm run gen:registry && node scripts/gen-adr-index.cjs --write && node scripts/gen-features.cjs --write && node scripts/gen-capability-matrix.cjs --write && node scripts/gen-inventory-manifest.cjs --write && node scripts/gen-context-index.cjs --write && node scripts/gen-state-md-docs.cjs --write && npm run gen:section-manifest && node scripts/sync-manifest-versions.cjs && npm run gen:install-tree && node scripts/gen-scripts-cli-exit.cjs --write && node scripts/gen-hooks-cli-exit.cjs --write && node scripts/gen-exit-code-registry.cjs --write && node scripts/gen-exit-code-docs.cjs --write",
+    "regen:derived": "npm run build && npm run gen:registry && node scripts/gen-adr-index.cjs --write && node scripts/gen-features.cjs --write && node scripts/gen-capability-matrix.cjs --write && node scripts/gen-inventory-manifest.cjs --write && node scripts/gen-context-index.cjs --write && node scripts/gen-state-md-docs.cjs --write && npm run gen:section-manifest && node scripts/sync-manifest-versions.cjs && npm run gen:install-tree && node scripts/gen-scripts-cli-exit.cjs --write && node scripts/gen-hooks-cli-exit.cjs --write && node scripts/gen-exit-code-registry.cjs --write && node scripts/gen-exit-code-docs.cjs --write && node scripts/gen-platform-conformance-tier.cjs --write && node scripts/gen-platform-conformance-tier.cjs --target macos --write",
     "validate:registry": "node scripts/validate-registry.cjs",
     "prepack": "npm run build:lib",
     "prepare": "npm run build:lib",
@@ -121,7 +123,8 @@
     "lint:table-schema-drift": "node scripts/lint-table-schema-drift.cjs",
     "lint:frontmatter-scalar-broad-grep": "node scripts/lint-frontmatter-scalar-broad-grep.cjs",
     "lint:removed-but-needed": "node scripts/lint-removed-but-needed.cjs",
-    "lint:ci": "npm run lint && npm run lint:skill-deps && npm run lint:generated-sync && node scripts/lint-test-file-count.cjs && node scripts/lint-command-contract.cjs && node scripts/lint-pr-check-project-dir.cjs && npm run lint:legacy-name && node scripts/lint-regression-test-names.cjs && node scripts/lint-allow-test-rule-refs.cjs && node scripts/lint-resolution-provenance.cjs && node scripts/lint-portable-timeout.cjs && node scripts/validate-registry.cjs && node scripts/lint-table-schema-drift.cjs && node scripts/lint-fix-has-regression-tests.cjs && node scripts/lint-example-parser-parity.cjs && node scripts/lint-docs-command-form.cjs && node scripts/lint-plan-count-drift.cjs && node scripts/lint-milestone-window-drift.cjs && node scripts/lint-phase-enumeration-drift.cjs && node scripts/lint-planning-prompt-drift.cjs && node scripts/lint-unreachable-guard-drift.cjs && node scripts/lint-completion-ratio-drift.cjs && node scripts/lint-slug-derivation-drift.cjs && node scripts/lint-state-field-drift.cjs && node scripts/lint-state-write-path-drift.cjs && node scripts/lint-completion-predicate-drift.cjs && node scripts/lint-planning-snapshot-bypass-drift.cjs && node scripts/lint-health-diagnostic-rule-table.cjs && node scripts/lint-planning-artifact-writer-drift.cjs && node scripts/lint-frontmatter-scalar-broad-grep.cjs && node scripts/lint-removed-but-needed.cjs && node scripts/lint-no-adhoc-regex-escape.cjs && node scripts/lint-vendored-deps.cjs && node scripts/lint-docs-guard-registration.cjs && node scripts/lint-source-test-name-collision.cjs && npm run lint:hooks-runtime-build-seam && node scripts/check-contract-drift.cjs && node scripts/lint-mutation-test-derivation-drift.cjs && node scripts/lint-seam-enforcement.cjs",
+    "lint:response-language": "node scripts/lint-response-language-coverage.cjs",
+    "lint:ci": "npm run lint && npm run lint:skill-deps && npm run lint:generated-sync && node scripts/lint-test-file-count.cjs && node scripts/lint-command-contract.cjs && node scripts/lint-pr-check-project-dir.cjs && npm run lint:legacy-name && node scripts/lint-regression-test-names.cjs && node scripts/lint-allow-test-rule-refs.cjs && node scripts/lint-resolution-provenance.cjs && node scripts/lint-portable-timeout.cjs && node scripts/lint-portable-grep.cjs && node scripts/lint-allowed-tools-parity.cjs && node scripts/validate-registry.cjs && node scripts/lint-table-schema-drift.cjs && node scripts/lint-fix-has-regression-tests.cjs && node scripts/lint-example-parser-parity.cjs && node scripts/lint-docs-command-form.cjs && node scripts/lint-plan-count-drift.cjs && node scripts/lint-milestone-window-drift.cjs && node scripts/lint-phase-enumeration-drift.cjs && node scripts/lint-planning-prompt-drift.cjs && node scripts/lint-unreachable-guard-drift.cjs && node scripts/lint-completion-ratio-drift.cjs && node scripts/lint-slug-derivation-drift.cjs && node scripts/lint-state-field-drift.cjs && node scripts/lint-state-write-path-drift.cjs && node scripts/lint-completion-predicate-drift.cjs && node scripts/lint-planning-snapshot-bypass-drift.cjs && node scripts/lint-health-diagnostic-rule-table.cjs && node scripts/lint-planning-artifact-writer-drift.cjs && node scripts/lint-frontmatter-scalar-broad-grep.cjs && node scripts/lint-removed-but-needed.cjs && node scripts/lint-no-adhoc-regex-escape.cjs && node scripts/lint-vendored-deps.cjs && node scripts/lint-docs-guard-registration.cjs && node scripts/lint-source-test-name-collision.cjs && npm run lint:hooks-runtime-build-seam && node scripts/check-contract-drift.cjs && node scripts/lint-mutation-test-derivation-drift.cjs && node scripts/lint-seam-enforcement.cjs && node scripts/lint-workflow-shellcheck.cjs && npm run lint:response-language",
     "lint:allow-test-rule-refs": "node scripts/lint-allow-test-rule-refs.cjs",
     "lint:regression-names": "node scripts/lint-regression-test-names.cjs",
     "lint:descriptions": "node scripts/lint-descriptions.cjs",
@@ -129,7 +132,7 @@
     "lint:test-file-count": "node scripts/lint-test-file-count.cjs",
     "lint:pr-checks": "node scripts/lint-pr-check-project-dir.cjs",
     "lint:changeset": "node scripts/changeset/lint.cjs",
-    "lint:generated-sync": "node scripts/gen-capability-registry.cjs --check && node scripts/gen-loop-host-contract.cjs --check && node scripts/gen-capability-matrix.cjs --check && node scripts/sync-manifest-versions.cjs --check && node scripts/gen-inventory-manifest.cjs --check && node scripts/generate-package-identity.cjs --check && node scripts/gen-plugin-skills.cjs --check && node scripts/gen-registry.cjs --check && node scripts/gen-adr-index.cjs --check && node scripts/gen-features.cjs --check && node scripts/check-glossary-refs.cjs --check && node scripts/lint-compiled-artifact-sync.cjs --check && node scripts/gen-context-index.cjs --check && node scripts/gen-section-manifest.cjs --check && node scripts/gen-health-docs.cjs --check && node scripts/gen-state-md-docs.cjs --check && node scripts/gen-scripts-cli-exit.cjs --check && node scripts/gen-hooks-cli-exit.cjs --check && node scripts/gen-exit-code-registry.cjs --check && node scripts/gen-exit-code-docs.cjs --check",
+    "lint:generated-sync": "node scripts/gen-capability-registry.cjs --check && node scripts/gen-loop-host-contract.cjs --check && node scripts/gen-capability-matrix.cjs --check && node scripts/sync-manifest-versions.cjs --check && node scripts/gen-inventory-manifest.cjs --check && node scripts/generate-package-identity.cjs --check && node scripts/gen-plugin-skills.cjs --check && node scripts/gen-registry.cjs --check && node scripts/gen-adr-index.cjs --check && node scripts/gen-features.cjs --check && node scripts/check-glossary-refs.cjs --check && node scripts/lint-compiled-artifact-sync.cjs --check && node scripts/gen-context-index.cjs --check && node scripts/gen-section-manifest.cjs --check && node scripts/gen-health-docs.cjs --check && node scripts/gen-state-md-docs.cjs --check && node scripts/gen-scripts-cli-exit.cjs --check && node scripts/gen-hooks-cli-exit.cjs --check && node scripts/gen-exit-code-registry.cjs --check && node scripts/gen-exit-code-docs.cjs --check && node scripts/gen-platform-conformance-tier.cjs --check && node scripts/gen-platform-conformance-tier.cjs --target macos --check",
     "lint:docs": "node scripts/lint-docs-required.cjs",
     "lint:qa-smells": "node scripts/qa-smell-ratchet.cjs",
     "lint:legacy-name": "node scripts/lint-legacy-dir-name.cjs",
@@ -137,6 +140,8 @@
     "lint:docs-command-form": "node scripts/lint-docs-command-form.cjs",
     "lint:hooks-runtime-build-seam": "node scripts/lint-hooks-runtime-build-seam.cjs",
     "ci:test-scope": "node scripts/ci-test-scope.cjs",
+    "benchmark:compact-content": "node scripts/benchmark-compact-content.cjs --check",
+    "benchmark:compact-content-variants": "node scripts/benchmark-compact-content-variants.cjs --check",
     "changeset": "node scripts/changeset/new.cjs",
     "changelog:render": "node scripts/changeset/cli.cjs render",
     "test": "node scripts/run-tests.cjs",
@@ -148,13 +153,12 @@
     "test:qa": "node scripts/run-tests.cjs --suite qa",
     "test:affected": "node scripts/run-affected-tests.cjs",
     "test:coverage": "c8 --check-coverage --lines 70 --branches 60 --reporter text --include 'gsd-core/bin/lib/**/*.cjs' --exclude 'tests/**' --all node scripts/run-tests.cjs",
-    "test:coverage:scripts-floor": "c8 check-coverage --lines 55 --include 'scripts/**/*.cjs' --exclude 'tests/**' --all",
+    "test:coverage:scripts-floor": "c8 report --check-coverage --lines 55 --merge-async --include 'scripts/**/*.cjs' --exclude 'tests/**' --all",
     "test:coverage:unit": "c8 --reporter text --reporter json-summary --merge-async --include 'gsd-core/bin/lib/**/*.cjs' --exclude 'tests/**' --all node scripts/run-tests.cjs --suite unit && node scripts/check-coverage-gate.cjs",
-    "test:coverage:unit:raw": "c8 --reporter none node scripts/run-tests.cjs --suite unit",
+    "test:coverage:unit:raw": "c8 --reporter none --merge-async node scripts/run-tests.cjs --suite unit",
     "test:coverage:report": "c8 report --reporter text --reporter json-summary --merge-async --include 'gsd-core/bin/lib/**/*.cjs' --exclude 'tests/**' --all && node scripts/check-coverage-gate.cjs",
     "test:coverage:all": "npm run test:coverage",
     "test:mutation": "stryker run",
-    "test:mutation:since": "stryker run --incremental --since origin/next",
     "gen:features": "node scripts/gen-features.cjs",
     "gen:state-md-docs": "node scripts/gen-state-md-docs.cjs"
   },

package/scripts/benchmark-compact-content-variants.cjs

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Benchmarks the token-count effect of every registered variant-swap pair
+ * (ADR-4139, Phase 6 #4406 — `gsd-core/workflows/<name>/{modes,steps,templates}/*.compact.md`
+ * and `gsd-core/templates/**\/*.compact.md`). Sibling to
+ * `scripts/benchmark-compact-content.cjs` (Phase 3's spine/detail benchmark) rather than an
+ * extension of it — the two are different data shapes (a variant pair is two independent,
+ * deliberately-overlapping complete files; a spine/detail split is one document partitioned in
+ * two disjoint halves), and mixing them into one report would conflate an "off" total that means
+ * something different in each case.
+ *
+ * For every registered pair it reports the "off" token count (the canonical file — what
+ * `workflow.compact_content=false`, the default, pays at that call site) against the "on" token
+ * count (the `.compact.md` sibling — what `workflow.compact_content=true` pays once the gate
+ * resolves to it). See `gsd-core/references/compact-content-gate.md` §"Streams 1b and 4" for the
+ * resolution rule this measures.
+ *
+ * PROXY-TOKENIZER CAVEAT: same as the sibling script — `gpt-tokenizer` is a stand-in tokenizer;
+ * Anthropic publishes none for Claude 3+. The on/off comparison is exact under this one pinned
+ * tokenizer applied identically to both sides; the absolute counts are not Claude's real counts.
+ *
+ * Discovery is REIMPLEMENTED here rather than imported from
+ * `tests/helpers/compact-content-variant.cjs`, for the same reason
+ * `benchmark-compact-content.cjs` reimplements spine/detail discovery instead of importing it: a
+ * `scripts/` reporting tool depending on a test-only helper module inverts this repo's normal
+ * layering, and a test-only module changing shape should never be able to break a benchmark.
+ *
+ * Usage:
+ *   node scripts/benchmark-compact-content-variants.cjs                 # print JSON to stdout
+ *   node scripts/benchmark-compact-content-variants.cjs --write         # write the committed baseline
+ *   node scripts/benchmark-compact-content-variants.cjs --check         # recompute, diff vs committed baseline
+ *   node scripts/benchmark-compact-content-variants.cjs --check --baseline-path=<path>
+ *
+ * Same CRITICAL contract as the sibling script: this — and `--check` especially — MUST NEVER
+ * exit non-zero because a baseline is drifted, stale, or missing. Only a genuine I/O error
+ * reading a SOURCE file the benchmark measures may throw. This is a reporting instrument, never
+ * a gate.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { countTokens } = require('gpt-tokenizer');
+const { runMain } = require('./lib/cli-exit.cjs');
+
+const ROOT = path.resolve(__dirname, '..');
+// #4407: agents/ joins the scan. Reachability there is a code seam
+// (cmdAgentSkills), not a markdown literal reference, but token accounting
+// doesn't care how a pair is reached — only that it's registered.
+const VARIANT_ROOTS = [
+  path.join(ROOT, 'gsd-core', 'workflows'),
+  path.join(ROOT, 'gsd-core', 'templates'),
+  path.join(ROOT, 'agents'),
+];
+const BASELINE_PATH = path.join(ROOT, 'tests', 'fixtures', 'compact-content-variant-benchmark-baseline.json');
+const COMPACT_SUFFIX = '.compact.md';
+
+function getTokenizerVersion() {
+  const pkgPath = require.resolve('gpt-tokenizer/package.json');
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  return pkg.version;
+}
+
+/**
+ * Discover every registered variant pair under `roots`: a `.compact.md` file
+ * with a same-directory, same-stem canonical `.md` sibling. Mirrors
+ * `tests/helpers/compact-content-variant.cjs`'s `discoverRegisteredVariants`
+ * in shape but is a from-scratch, self-contained implementation (see module
+ * header for why this is not a shared import). Skips an orphaned compact
+ * file with no canonical sibling — that is the guard's problem, not this
+ * benchmark's; a pair with no canonical baseline has no "off" number to
+ * report against.
+ *
+ * @param {string[]} [roots]
+ * @returns {Array<{name: string, canonicalPath: string, compactPath: string}>}
+ */
+function discoverRegisteredVariants(roots = VARIANT_ROOTS) {
+  const pairs = [];
+
+  function walk(dir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (entry.isFile() && entry.name.endsWith(COMPACT_SUFFIX)) {
+        const stem = entry.name.slice(0, -COMPACT_SUFFIX.length);
+        const canonicalPath = path.join(dir, `${stem}.md`);
+        if (fs.existsSync(canonicalPath)) {
+          const name = path.relative(ROOT, canonicalPath).split(path.sep).join('/');
+          pairs.push({ name, canonicalPath, compactPath: full });
+        }
+      }
+    }
+  }
+
+  for (const root of roots) walk(root);
+  return pairs.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Compute the off/on/reduction numbers for ONE registered variant pair.
+ * Throws on a genuine read failure of a source file (the one thing allowed
+ * to throw, per the module-header CRITICAL note).
+ *
+ * @param {{canonicalPath: string, compactPath: string}} pair
+ * @returns {{offTokens: number, onTokens: number, reductionPct: number}}
+ */
+function computePairTokens(pair) {
+  const offTokens = countTokens(fs.readFileSync(pair.canonicalPath, 'utf8'));
+  const onTokens = countTokens(fs.readFileSync(pair.compactPath, 'utf8'));
+  const reductionPct = offTokens === 0 ? 0 : round2(((offTokens - onTokens) / offTokens) * 100);
+  return { offTokens, onTokens, reductionPct };
+}
+
+function round2(n) {
+  return Math.round(n * 100) / 100;
+}
+
+/**
+ * Aggregate per-pair numbers from SUMMED off/on totals, never averaged
+ * per-pair percentages. Reports `0` (not `NaN`) for zero registered pairs.
+ * @param {Record<string, {offTokens: number, onTokens: number}>} pairResults
+ */
+function computeAggregate(pairResults) {
+  let offTokens = 0;
+  let onTokens = 0;
+  for (const key of Object.keys(pairResults)) {
+    offTokens += pairResults[key].offTokens;
+    onTokens += pairResults[key].onTokens;
+  }
+  const reductionPct = offTokens === 0 ? 0 : round2(((offTokens - onTokens) / offTokens) * 100);
+  return { offTokens, onTokens, reductionPct };
+}
+
+const LABEL =
+  "PROXY-TOKENIZER DELTA — gpt-tokenizer is a stand-in; Anthropic publishes no tokenizer for Claude 3+. " +
+  "The on/off COMPARISON is exact under this pinned tokenizer; absolute counts are not Claude's real token counts.";
+
+/**
+ * @param {string[]} [roots]
+ * @returns {object}
+ */
+function buildReport(roots = VARIANT_ROOTS) {
+  const pairs = discoverRegisteredVariants(roots);
+  const pairReports = {};
+  for (const pair of pairs) {
+    pairReports[pair.name] = computePairTokens(pair);
+  }
+  return {
+    schema_version: 1,
+    generated_by: 'scripts/benchmark-compact-content-variants.cjs',
+    tokenizer: { name: 'gpt-tokenizer', version: getTokenizerVersion() },
+    label: LABEL,
+    pairs: pairReports,
+    aggregate: computeAggregate(pairReports),
+  };
+}
+
+/**
+ * Format a human-readable drift summary between a (possibly missing/invalid)
+ * committed baseline and a freshly-computed live report. Never throws.
+ * @param {string} baselinePath
+ * @param {object} live
+ * @returns {string}
+ */
+function formatDriftReport(baselinePath, live) {
+  const lines = [];
+  let baseline = null;
+  let baselineReadError = null;
+  try {
+    const raw = fs.readFileSync(baselinePath, 'utf8');
+    try {
+      baseline = JSON.parse(raw);
+    } catch (parseErr) {
+      baselineReadError = `baseline at ${baselinePath} could not be parsed as JSON: ${parseErr.message}`;
+    }
+  } catch {
+    baselineReadError = `no baseline found at ${baselinePath}`;
+  }
+
+  if (baselineReadError) {
+    lines.push(`DRIFT: ${baselineReadError} — treating as fully drifted (this is reported, not an error).`);
+    lines.push('Live pairs:');
+    for (const name of Object.keys(live.pairs).sort()) {
+      const p = live.pairs[name];
+      lines.push(`  + ${name}: off=${p.offTokens} on=${p.onTokens} reduction=${p.reductionPct}%`);
+    }
+    lines.push(
+      `Live aggregate: off=${live.aggregate.offTokens} on=${live.aggregate.onTokens} ` +
+      `reduction=${live.aggregate.reductionPct}%`,
+    );
+    return lines.join('\n');
+  }
+
+  const baselinePairs = (baseline && typeof baseline === 'object' && baseline.pairs) || {};
+  const livePairs = live.pairs;
+  const allNames = new Set([...Object.keys(baselinePairs), ...Object.keys(livePairs)]);
+  let anyDrift = false;
+
+  if (!baseline || typeof baseline.label !== 'string' || !baseline.label.includes('PROXY-TOKENIZER')) {
+    anyDrift = true;
+    lines.push('DRIFT: committed baseline is missing the required "PROXY-TOKENIZER" label.');
+  }
+
+  for (const name of [...allNames].sort()) {
+    const b = baselinePairs[name];
+    const l = livePairs[name];
+    if (!b) {
+      anyDrift = true;
+      lines.push(`DRIFT: pair "${name}" is new (not in committed baseline) — live off=${l.offTokens} on=${l.onTokens} reduction=${l.reductionPct}%`);
+    } else if (!l) {
+      anyDrift = true;
+      lines.push(`DRIFT: pair "${name}" was removed (present in committed baseline, not found live) — baseline off=${b.offTokens} on=${b.onTokens} reduction=${b.reductionPct}%`);
+    } else if (b.offTokens !== l.offTokens || b.onTokens !== l.onTokens || b.reductionPct !== l.reductionPct) {
+      anyDrift = true;
+      lines.push(
+        `DRIFT: pair "${name}": off ${b.offTokens} -> ${l.offTokens} (${l.offTokens - b.offTokens >= 0 ? '+' : ''}${l.offTokens - b.offTokens}), ` +
+        `on ${b.onTokens} -> ${l.onTokens} (${l.onTokens - b.onTokens >= 0 ? '+' : ''}${l.onTokens - b.onTokens}), ` +
+        `reduction ${b.reductionPct}% -> ${l.reductionPct}% (${round2(l.reductionPct - b.reductionPct) >= 0 ? '+' : ''}${round2(l.reductionPct - b.reductionPct)}pp)`,
+      );
+    }
+  }
+
+  const ba = (baseline && baseline.aggregate) || {};
+  const la = live.aggregate;
+  if (ba.offTokens !== la.offTokens || ba.onTokens !== la.onTokens || ba.reductionPct !== la.reductionPct) {
+    anyDrift = true;
+    lines.push(
+      `DRIFT: aggregate: off ${ba.offTokens} -> ${la.offTokens}, on ${ba.onTokens} -> ${la.onTokens}, ` +
+      `reduction ${ba.reductionPct}% -> ${la.reductionPct}%`,
+    );
+  }
+
+  if (!anyDrift) {
+    lines.push(`Baseline at ${baselinePath} is up to date with the live recompute.`);
+  } else {
+    lines.push('');
+    lines.push('Run `node scripts/benchmark-compact-content-variants.cjs --write` to refresh the committed baseline.');
+    lines.push('(This is a REPORT, not a gate — exiting 0 regardless of drift, per this script\'s own contract.)');
+  }
+  return lines.join('\n');
+}
+
+function parseArgs(argv) {
+  const opts = { write: false, check: false, baselinePath: BASELINE_PATH };
+  for (const arg of argv) {
+    if (arg === '--write') opts.write = true;
+    else if (arg === '--check') opts.check = true;
+    else if (arg.startsWith('--baseline-path=')) opts.baselinePath = arg.slice('--baseline-path='.length);
+  }
+  return opts;
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+
+  if (opts.write) {
+    const report = buildReport();
+    fs.mkdirSync(path.dirname(BASELINE_PATH), { recursive: true });
+    fs.writeFileSync(BASELINE_PATH, JSON.stringify(report, null, 2) + '\n');
+    process.stdout.write(`Wrote ${BASELINE_PATH}\n`);
+    return;
+  }
+
+  if (opts.check) {
+    const live = buildReport();
+    process.stdout.write(formatDriftReport(opts.baselinePath, live) + '\n');
+    return;
+  }
+
+  process.stdout.write(JSON.stringify(buildReport(), null, 2) + '\n');
+}
+
+/* c8 ignore next 3 -- CLI entry guard; this repo measures coverage with c8, which does not honor istanbul pragmas */
+if (require.main === module) {
+  runMain(main);
+}
+
+module.exports = {
+  discoverRegisteredVariants,
+  computePairTokens,
+  computeAggregate,
+  buildReport,
+  formatDriftReport,
+  getTokenizerVersion,
+  parseArgs,
+  LABEL,
+  BASELINE_PATH,
+  VARIANT_ROOTS,
+};