@opengsd/gsd-core 1.20.0 → 1.21.0

package/scripts/ci-test-scope.cjs

@@ -6,34 +6,68 @@ const { execFileSync } = require('child_process');
 const { existsSync, readdirSync, appendFileSync, readFileSync } = require('fs');
 
 const { ExitError, runMain } = require('./lib/cli-exit.cjs');
-const { classifyContent, NOISY_FOR_SOURCE_REACHABILITY } = require('./gen-platform-conformance-tier.cjs');
-
-// Workflow files that are purely administrative / policy bots. Changes to these
-// files do NOT require the cross-platform test matrix — only a lightweight
-// ubuntu lane running workflow-lint tests is needed.
-// FAIL-SAFE: any .github/workflows/*.yml NOT listed here is treated as a
-// pipeline workflow and gets the full matrix. New workflow files default to full.
-const INERT_WORKFLOWS = new Set([
-  'stale.yml',
-  'branch-cleanup.yml',
-  'branch-naming.yml',
-  'auto-label-issues.yml',
-  'auto-branch.yml',
-  'auto-backmerge.yml',
-  'close-draft-prs.yml',
-  'dismiss-unauthorized-pr-approvals.yml',
-  'pr-target-validator.yml',
-  'pr-template-format.yml',
-  'require-issue-link.yml',
-  'changeset-required.yml',
-  'docs-required.yml',
-  'discord-changelog.yml',
-]);
+const { classifyUnstrippedContent, NOISY_FOR_SOURCE_REACHABILITY } = require('./gen-platform-conformance-tier.cjs');
+
+// #6075: CI YAML (any `.github/**/*.yml|*.yaml`: workflows, composite actions,
+// dependabot/labeler/issue-form config) is "inert" CI. A PR that changes only CI
+// YAML never runs the matrix: it reports code_changed=true, product_changed=false,
+// full_matrix=false and targets only the workflow-lint tests (the `test-inert`
+// lane). Mixed with product code, the product files decide the scope.
+// Anchored at the repo root: a nested `.github/` under a product prefix is not CI YAML.
+const CI_YAML_RE = /^\.github\/.+\.ya?ml$/;
+function isCiYaml(filePath) {
+  return CI_YAML_RE.test(filePath);
+}
+
+// Tests shared by both the 'workflow automation' and 'inert CI' rules.
+const WORKFLOW_LINT_TESTS = [
+  'tests/workflow-shell-pinning.test.cjs',
+  'tests/pr-template-policy.test.cjs',
+  'tests/lint-pr-check-project-dir.test.cjs',
+];
+
+// #6075: tests that read `.github/**` YAML content (workflow contracts). A CI
+// YAML edit re-runs them in the targeted lane (never full_matrix). Several are
+// conformance-tier members; that does not flip full_matrix for a CI-YAML-only
+// change because classify() exempts isCiYaml(file) from the windows-hint
+// escalation and forces full_matrix=false when only CI YAML changed.
+const WORKFLOW_CONTRACT_TESTS = [
+  'tests/adr-218-release-version-validation.test.cjs',
+  'tests/adr-230-pr-target-policy.test.cjs',
+  'tests/ci-conformance-pr-gating.test.cjs',
+  'tests/ci-docs-guard-registry.test.cjs',
+  'tests/ci-durations-upload-nonfatal.test.cjs',
+  'tests/ci-full-lane-sharding.test.cjs',
+  'tests/ci-merge-group-wiring.test.cjs',
+  'tests/ci-pr-mergeability.test.cjs',
+  'tests/ci-test-job-timeout-budget.test.cjs',
+  'tests/ci-test-scope.test.cjs',
+  'tests/merge-commit-pr.test.cjs',
+  'tests/mutation-tap-runner-wiring.test.cjs',
+  'tests/mutation-workflow-base-ref.test.cjs',
+  'tests/policy-release-no-npm-self-upgrade.test.cjs',
+  'tests/policy-shell-pinning.test.cjs',
+  'tests/release-backmerge-invariants.test.cjs',
+  'tests/release-coverage-scope.test.cjs',
+  'tests/release-finalize-notes-5922.test.cjs',
+  'tests/release-finalize-syncs-next-version.test.cjs',
+  'tests/release-hotfix-empty-cherry-pick.test.cjs',
+  'tests/release-notes-real-os-5922.test.cjs',
+  'tests/release-shard-lane-sharding.test.cjs',
+  'tests/release-tarball-smoke-workflow.test.cjs',
+  'tests/require-issue-link-policy.test.cjs',
+  'tests/reviewed-or-maintainer-workflow.test.cjs',
+  'tests/security-scan.security.test.cjs',
+  'tests/self-test-report-workflow.test.cjs',
+  'tests/workflow-token-permissions.test.cjs',
+];
 
 // Workflows that gate merges, ship the product, or run security/cross-platform
-// suites — these must ALWAYS get the full pipeline treatment and can never be
-// added to INERT_WORKFLOWS. A module-load assertion enforces this so a mistaken
-// or malicious addition fails CI loudly in the `changes` job on every PR.
+// suites. Kept as a registry of gating workflows. Enforced by the test
+// 'every protected workflow name refers to a real file' in
+// tests/ci-pr-mergeability.test.cjs (existence parity) and, at module load, by
+// missingProtectedWorkflows() below. Since #6075 a change to any of them is CI
+// YAML and, alone, runs only the workflow-lint and workflow-contract tests.
 const PROTECTED_WORKFLOWS = new Set([
   'test.yml',
   'install-smoke.yml',
@@ -41,41 +75,16 @@ const PROTECTED_WORKFLOWS = new Set([
   'security-scan.yml',
   'release.yml',
   // #3833: the reusable gate every `pull_request` compute lane depends on —
-  // marking it inert would let a change to the gate itself ship without ever
-  // running the full matrix it is responsible for enforcing.
+  // the gate it defines is exercised by tests/ci-pr-mergeability.test.cjs.
   'pr-mergeable-preflight.yml',
 ]);
-for (const wf of PROTECTED_WORKFLOWS) {
-  if (INERT_WORKFLOWS.has(wf)) {
-    throw new Error(`ci-test-scope: protected workflow "${wf}" must not be in INERT_WORKFLOWS (it requires the full test matrix).`);
-  }
-}
-
-/**
- * Returns true if the path is an inert (non-pipeline) workflow file.
- * Only `.github/workflows/<name>` where <name> is in INERT_WORKFLOWS qualifies.
- */
-function isInertCi(filePath) {
-  if (!filePath.startsWith('.github/workflows/')) return false;
-  const name = filePath.slice('.github/workflows/'.length);
-  // Must be a direct child (no further slashes) and in the allowlist.
-  return !name.includes('/') && INERT_WORKFLOWS.has(name);
-}
-
-// Tests shared by both the 'workflow automation' and 'inert CI' rules.
-const WORKFLOW_LINT_TESTS = [
-  'tests/workflow-shell-pinning.test.cjs',
-  'tests/pr-template-policy.test.cjs',
-  'tests/lint-pr-check-project-dir.test.cjs',
-];
 
 const RULES = [
   {
     name: 'workflow automation',
-    // Only NON-inert .github/workflows/* and all .github/rulesets/* trigger full matrix.
-    // FAIL-SAFE: any .github/workflows/*.yml not in INERT_WORKFLOWS is treated as pipeline.
-    match: filePath => (filePath.startsWith('.github/workflows/') && !isInertCi(filePath)) ||
-      filePath.startsWith('.github/rulesets/'),
+    // .github/rulesets/* (JSON branch protection) trigger the full matrix.
+    // CI YAML (.github/**/*.y{a,}ml) is the 'inert CI' rule below (#6075).
+    match: filePath => filePath.startsWith('.github/rulesets/'),
     fullMatrix: true,
     tests: [
       ...WORKFLOW_LINT_TESTS,
@@ -84,11 +93,12 @@ const RULES = [
   },
   {
     name: 'inert CI',
-    match: filePath => isInertCi(filePath),
+    match: filePath => isCiYaml(filePath),
     fullMatrix: false,
     tests: [
       ...WORKFLOW_LINT_TESTS,
       'tests/policy-lint-shallow-checkout.test.cjs',
+      ...WORKFLOW_CONTRACT_TESTS,
     ],
   },
   {
@@ -530,7 +540,7 @@ function reachesConformanceTierOrSeam(file, deps = {}) {
 
     if (file.startsWith('src/')) {
       const content = readFileSync(file, 'utf8');
-      const { signals } = classifyContent(content);
+      const { signals } = classifyUnstrippedContent(content);
       const narrowSignals = signals.filter(signal => !NOISY_FOR_SOURCE_REACHABILITY.has(signal));
       return narrowSignals.length > 0;
     }
@@ -549,7 +559,7 @@ function classify(files, reachabilityDeps = {}) {
   const targeted = new Set();
   const reasons = [];
   let productOrPipelineChanged = false; // product/pipeline code (excludes docs)
-  let inertCiChanged = false;           // inert workflow files
+  let inertCiChanged = false;           // CI YAML files (#6075)
   let fullMatrix = false;
 
   for (const file of files) {
@@ -571,13 +581,8 @@ function classify(files, reachabilityDeps = {}) {
       productOrPipelineChanged = true;
     }
 
-    // Non-inert .github/workflows/* are pipeline code → full matrix.
-    if (file.startsWith('.github/workflows/') && !isInertCi(file)) {
-      productOrPipelineChanged = true;
-    }
-
-    // Inert workflow files set a lightweight signal.
-    if (isInertCi(file)) {
+    // CI YAML sets a lightweight signal; it is never product/pipeline code.
+    if (isCiYaml(file)) {
       inertCiChanged = true;
     }
 
@@ -637,11 +642,13 @@ function classify(files, reachabilityDeps = {}) {
         // 14 of 16 rules, newly escalating most ordinary product-code PRs
         // (src/, agents/, commands/, hooks/, skills/, config paths). Only one
         // rule's escalation is live today: 'portability lint rules (ADR-1703)'.
-        // Four others already had fullMatrix: true (no-op here), and 'inert
-        // CI''s escalation is overridden downstream by the inert-CI reset.
+        // Four others already had fullMatrix: true (no-op here), and CI YAML
+        // (the 'inert CI' rule) is excluded from this escalation entirely.
         // Distinct, greppable reason so the conformance-lane coverage for it
         // is traceable per rule.
-        if (rule.tests.some(t => isWindowsHint(t) && reachesConformanceTierOrSeam(t, reachabilityDeps))) {
+        // #6075: CI YAML never escalates (it is lint-only scope, also when mixed
+        // with product code, so the product files alone decide full_matrix).
+        if (!isCiYaml(file) && rule.tests.some(t => isWindowsHint(t) && reachesConformanceTierOrSeam(t, reachabilityDeps))) {
           fullMatrix = true;
           reasons.push(`${file}: ${rule.name} (windows-hint rule test, #4641)`);
         }
@@ -660,7 +667,7 @@ function classify(files, reachabilityDeps = {}) {
   ]);
   for (const f of SCOPED_LANE_EXCLUDE) { targeted.delete(f); }
 
-  // code_changed: true when product/pipeline OR inert CI changed.
+  // code_changed: true when product/pipeline code OR CI YAML changed.
   // Docs-only PRs (neither flag set) get code_changed=false → full matrix skip.
   const codeChanged = productOrPipelineChanged || inertCiChanged;
 
@@ -672,7 +679,7 @@ function classify(files, reachabilityDeps = {}) {
     targetedTests.push('unit');
   }
 
-  // Inert-CI-only: full_matrix must be false (override any RULES that fired).
+  // CI-YAML-only: full_matrix must be false (override any RULES that fired).
   if (inertCiChanged && !productOrPipelineChanged) {
     fullMatrix = false;
   }
@@ -732,7 +739,6 @@ module.exports = {
   RULES,
   missingRuleTestFiles,
   PROTECTED_WORKFLOWS,
-  INERT_WORKFLOWS,
   missingProtectedWorkflows,
   classify,
   reachesConformanceTierOrSeam,

package/scripts/command-contract-helpers.cjs

@@ -939,21 +939,70 @@ const REMEDIES = Object.freeze({
  *
  * File-derived strings (registry cells, marker tokens, workflow text) are
  * echoed into lint output that AI agents read as trusted instructions —
- * every interpolated field is control-char-stripped and length-capped
- * before it is written, so a malicious repo file cannot make the lint emit
- * instruction-shaped text. Implemented as a code-point filter rather than a
- * regex so no control-character regex literal exists to lint.
+ * every interpolated field has its hostile code points ESCAPED and is
+ * length-capped before it is written, so a malicious repo file cannot make
+ * the lint emit instruction-shaped text, and the reader can still trace the
+ * spelling as written (a dropped character would show text that does not
+ * occur in the file).
+ *
+ * Escape format: each hostile code point (see isEchoHostile) is rendered as
+ * `\u{X}` with UPPERCASE hex and no padding, e.g. U+0085 -> `\u{85}`,
+ * U+200B -> `\u{200B}`, tag characters (U+E0000-U+E007F) -> `\u{E0041}`. The
+ * escape introducer itself, a literal backslash U+005C, is escaped as `\u{5C}`
+ * so a spelled-out `\u{202E}` in the input can never print identically to a
+ * real U+202E: whenever nothing was dropped (guaranteed when the output is at
+ * most 190 code points, since the longest escape `\u{10FFFF}` is 10), the
+ * output decodes back to exactly the input, so distinct inputs have distinct
+ * output. Once the cap truncates, the tail is dropped and inputs differing
+ * only beyond it can share one output (e.g. 195 `a` with and without a
+ * trailing U+0085). The output is free of every hostile character.
+ *
+ * Cap: 200 code points of OUTPUT (an escape counts as its own length, never
+ * split), so the result is bounded however hostile the input; scanning stops
+ * as soon as the next unit would exceed the cap, costing O(200) matches on a
+ * huge input. A surrogate pair is never split.
+ *
+ * Implemented as a code-point filter rather than a regex so no
+ * control-character regex literal exists to lint.
  */
 function sanitizeEcho(text) {
+  const CAP = 200;
   let out = '';
+  let used = 0;
   for (const ch of String(text)) {
     const code = ch.codePointAt(0);
-    if (code <= 0x1f || code === 0x7f) continue;
-    out += ch;
+    const hostile = code === 0x5c || isEchoHostile(code);
+    const unit = hostile ? `\\u{${code.toString(16).toUpperCase()}}` : ch;
+    const len = hostile ? unit.length : 1; // escapes are ASCII: one code point per char
+    if (used + len > CAP) break;
+    out += unit;
+    used += len;
   }
-  return out.length > 200 ? out.slice(0, 200) : out;
+  return out;
+}
+
+/**
+ * Code points sanitizeEcho escapes: C0 + DEL, C1 (incl. 8-bit CSI U+009B),
+ * line/paragraph separators, zero-width + LRM/RLM, bidi embeddings/overrides
+ * and isolates, the Arabic letter mark, word joiner/invisible operators, the
+ * Mongolian vowel separator, the soft hyphen and the BOM; all able to forge
+ * or hide output a reader (human or agent) trusts. Escaping U+200D makes
+ * joined emoji sequences visible as `\u{200D}`, which is acceptable for echoed paths.
+ * @param {number} code
+ * @returns {boolean}
+ */
+function isEchoHostile(code) {
+  return ECHO_HOSTILE_RE.test(String.fromCodePoint(code));
 }
 
+// Category-based: Cc controls (C0, DEL, C1), Cf format chars (zero-width, bidi,
+// soft hyphen, BOM, tags U+E0000-E007F, interlinear annotation, musical
+// format), Zl/Zp separators, Cs surrogates, Co private use, Cn unassigned;
+// plus variation selectors and the invisible filler characters that are not Cf.
+// Each combining/variation/filler member is its own alternative so no
+// character class holds a combining sequence (no-misleading-character-class).
+const ECHO_HOSTILE_RE = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}\p{Cs}\p{Co}\p{Cn}]|[\u{FE00}-\u{FE0F}]|[\u{E0100}-\u{E01EF}]|\u{180B}|\u{180C}|\u{180D}|\u{180F}|\u{34F}|\u{115F}|\u{1160}|\u{3164}|\u{FFA0}|\u{17B4}|\u{17B5}|\u{2800}/u;
+
 module.exports = {
   CANONICAL_TOOLS,
   parseFrontmatter,

package/scripts/docs-guard-registry.cjs

@@ -180,6 +180,7 @@ const DOCS_GUARD_TESTS = {
   // against the milestone-release-map module's exported enums.
   'tests/milestone-release-map.test.cjs': ['docs/CONFIGURATION.md'],
   'tests/analyze-dependencies.test.cjs': ['docs/COMMANDS.md'],
+  'tests/smart-discuss-classification.test.cjs': ['docs/COMMANDS.md'],
   'tests/auto-select-attribute.test.cjs': ['docs/reference/plan-md.md'],
   'tests/autonomous-converge.test.cjs': [
     'docs/COMMANDS.md',
@@ -192,6 +193,7 @@ const DOCS_GUARD_TESTS = {
     'docs/reference/capability-manifest.md',
   ],
   'tests/claude-md.test.cjs': ['docs/COMMANDS.md'],
+  'tests/claude-orchestration-4747.test.cjs': ['docs/how-to/enable-claude-orchestration-workflow-backend.md'],
   'tests/claude-orchestration.test.cjs': ['docs/explanation/claude-orchestration-capability.md'],
   'tests/command-contract.test.cjs': [
     'docs/INVENTORY.md',
@@ -309,6 +311,7 @@ const DOCS_GUARD_TESTS = {
     'docs/pt-BR/context-monitor.md',
     'docs/zh-CN/context-monitor.md',
   ],
+  'tests/gen-cli-surface-manifest.test.cjs': ['docs/CLI-SURFACE-MANIFEST.json'],
   'tests/gen-state-md-docs.test.cjs': [
     'docs/reference/state-md.md',
     'docs/ja-JP/reference/state-md.md',

package/scripts/gen-cli-surface-manifest.cjs

@@ -0,0 +1,287 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Generates docs/CLI-SURFACE-MANIFEST.json from the CLI surface registry
+ * (`src/cli-surface.cts`, compiled to `gsd-core/bin/lib/cli-surface.cjs`) and the
+ * command aliases (`gsd-core/bin/lib/command-aliases.cjs`). ADR-4909 D2, #6087.
+ *
+ * Usage:
+ *   node scripts/gen-cli-surface-manifest.cjs                 # print the manifest to stdout
+ *   node scripts/gen-cli-surface-manifest.cjs --write          # rewrite the manifest file
+ *   node scripts/gen-cli-surface-manifest.cjs --check          # exit 1 if the manifest is missing/stale
+ *   node scripts/gen-cli-surface-manifest.cjs --check --json   # machine-readable report
+ *   node scripts/gen-cli-surface-manifest.cjs --manifest-path <p>  # test-only: target another file
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const ROOT = path.resolve(__dirname, '..');
+const MANIFEST_REL = 'docs/CLI-SURFACE-MANIFEST.json';
+const MANIFEST_PATH = path.join(ROOT, MANIFEST_REL);
+const SURFACE_REL = 'gsd-core/bin/lib/cli-surface.cjs';
+const SURFACE_PATH = path.join(ROOT, SURFACE_REL);
+const ALIASES_PATH = path.join(ROOT, 'gsd-core/bin/lib/command-aliases.cjs');
+
+const USAGE =
+  'Usage: node scripts/gen-cli-surface-manifest.cjs [--write | --check] [--json] [--manifest-path <path>]';
+
+// Each compiled module the manifest reads, beside the source it is built from. The registry
+// is read through its compiled form, so a stale compile would write or check a stale manifest.
+const COMPILED_PAIRS = [
+  { source: path.join(ROOT, 'src/cli-surface.cts'), compiled: SURFACE_PATH },
+  {
+    source: path.join(ROOT, 'src/command-arg-projection.cts'),
+    compiled: path.join(ROOT, 'gsd-core/bin/lib/command-arg-projection.cjs'),
+  },
+];
+
+/**
+ * Whether the compiled file is exactly what the build would emit for the source: true or false,
+ * or null when typescript or the build options cannot be loaded (the caller falls back to mtime).
+ */
+function compiledMatchesSource(source, compiled, loadTypescript) {
+  try {
+    const ts = loadTypescript();
+    const config = ts.readConfigFile(path.join(ROOT, 'tsconfig.build.json'), ts.sys.readFile);
+    if (config.error !== undefined) return null;
+    // parseJsonConfigFileContent resolves `extends`; 18003 (no input files) is about the include globs, not the options.
+    const { options, errors } = ts.parseJsonConfigFileContent(config.config, ts.sys, ROOT);
+    if (errors.some((e) => e.code !== 18003)) return null;
+    const emitted = ts.transpileModule(fs.readFileSync(source, 'utf8'), { compilerOptions: options, fileName: source });
+    return emitted.outputText === fs.readFileSync(compiled, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Why the compiled registry cannot be trusted, or null when it is fresh: a compiled file that
+ * is missing, or older than the source beside it, means `npm run build:lib` has not run since
+ * the source changed. A source that is not on disk (an installed package) is not checked.
+ * Pairs are compared one to one: tsc leaves an unchanged module's output alone, so a source that
+ * is newer by mtime only (a checkout, a touch) is judged by content: the source is transpiled
+ * with the repo's own typescript and the build options of tsconfig.build.json, and equal to the
+ * compiled text means fresh. When typescript cannot be loaded the mtime comparison decides.
+ *
+ * @param {Array<{source: string, compiled: string}>} [pairs]
+ * @param {() => object} [loadTypescript]
+ * @returns {string | null}
+ */
+function staleCompileProblem(pairs = COMPILED_PAIRS, loadTypescript = () => require('typescript')) {
+  for (const { source, compiled } of pairs) {
+    const rel = (p) => path.relative(ROOT, p) || p;
+    if (!fs.existsSync(compiled)) {
+      return `compiled artifact not found at ${rel(compiled)}. Run \`npm run build:lib\` first.`;
+    }
+    if (!fs.existsSync(source)) continue;
+    if (fs.statSync(source).mtimeMs > fs.statSync(compiled).mtimeMs) {
+      if (compiledMatchesSource(source, compiled, loadTypescript) === true) continue;
+      return (
+        `${rel(compiled)} is older than ${rel(source)}. Run \`npm run build:lib\` first ` +
+        '(if it emits nothing, delete tsconfig.build.tsbuildinfo and run it again).'
+      );
+    }
+  }
+  return null;
+}
+
+function loadSurface() {
+  const problem = staleCompileProblem();
+  if (problem !== null) throw new ExitError(2, `gen-cli-surface-manifest: ${problem}`);
+  return require(SURFACE_PATH);
+}
+
+/** canonical -> sorted, unique aliases, across every `*_COMMAND_ALIASES` array. */
+function aliasMap() {
+  const mod = require(ALIASES_PATH);
+  const collected = new Map();
+  for (const [key, value] of Object.entries(mod)) {
+    if (!key.endsWith('_COMMAND_ALIASES') || !Array.isArray(value)) continue;
+    for (const entry of value) {
+      if (!entry || typeof entry.canonical !== 'string') continue;
+      const set = collected.get(entry.canonical) ?? new Set();
+      for (const alias of entry.aliases ?? []) set.add(alias);
+      collected.set(entry.canonical, set);
+    }
+  }
+  return new Map([...collected].map(([canonical, set]) => [canonical, [...set].sort()]));
+}
+
+const sorted = (list) => [...(list ?? [])].sort();
+
+function flagKinds(spec) {
+  const repeatable = new Set(spec.repeatableFlags ?? []);
+  const bare = new Set(spec.bareEmptyFlags ?? []);
+  const kinds = {};
+  for (const f of spec.valueFlags ?? []) {
+    kinds[f] = repeatable.has(f) ? 'repeatable' : bare.has(f) ? 'value-or-bare' : 'value';
+  }
+  for (const f of spec.booleanFlags ?? []) kinds[f] = 'boolean';
+  for (const f of spec.optionalValueFlags ?? []) kinds[f] = 'optional-value';
+  for (const f of spec.listFlags ?? []) kinds[f] = 'list';
+  for (const f of spec.multiwordFlags ?? []) kinds[f] = 'multiword';
+  return sortedObject(kinds);
+}
+
+function sortedObject(obj) {
+  const out = {};
+  for (const k of Object.keys(obj).sort()) out[k] = obj[k];
+  return out;
+}
+
+function buildVerbEntry(verb, spec, aliases) {
+  const entry = {
+    verb,
+    aliases: sorted(aliases.get(verb)),
+    positionals: spec.positionals,
+    flags: flagKinds(spec),
+    required: sorted(spec.requiredFlags),
+    workstreamScoped: !!spec.workstreamScoped,
+  };
+  if (spec.freePositionals) entry.freePositionals = true;
+  if (spec.rejectShortFlags) entry.rejectShortFlags = true;
+  if ((spec.eqFlags ?? []).length > 0) entry.eq = sorted(spec.eqFlags);
+  if ((spec.nonEmptyFlags ?? []).length > 0) entry.nonEmpty = sorted(spec.nonEmptyFlags);
+  if ((spec.emptyValueFlags ?? []).length > 0) entry.emptyValue = sorted(spec.emptyValueFlags);
+  if ((spec.emptyEqFlags ?? []).length > 0) entry.emptyEq = sorted(spec.emptyEqFlags);
+  if (spec.passthroughAfter) entry.passthroughAfter = spec.passthroughAfter;
+  if (spec.thirdParty) entry.thirdParty = true;
+  return entry;
+}
+
+function buildManifest() {
+  const { CLI_SURFACE, GLOBAL_FLAGS, UNDECLARED_VERBS } = loadSurface();
+  const aliases = aliasMap();
+  const flags = {};
+  for (const f of GLOBAL_FLAGS.valueFlags ?? []) flags[f] = 'value';
+  for (const f of GLOBAL_FLAGS.booleanFlags ?? []) flags[f] = 'boolean';
+  const verbs = Object.keys(CLI_SURFACE)
+    .sort()
+    .map((verb) => buildVerbEntry(verb, CLI_SURFACE[verb], aliases));
+  return {
+    schema: 1,
+    global: {
+      flags: sortedObject(flags),
+      eq: sorted(GLOBAL_FLAGS.eqFlags),
+      help: [...(GLOBAL_FLAGS.helpTokens ?? [])],
+      rejected: [...(GLOBAL_FLAGS.rejectedTokens ?? [])],
+    },
+    verbs,
+    undeclared: sorted(UNDECLARED_VERBS),
+  };
+}
+
+function serialize(manifest) {
+  return JSON.stringify(manifest, null, 2) + '\n';
+}
+
+function diffVerbs(expected, actual) {
+  const exp = new Map(expected.verbs.map((v) => [v.verb, JSON.stringify(v)]));
+  const act = new Map((actual.verbs ?? []).map((v) => [v.verb, JSON.stringify(v)]));
+  const added = [...exp.keys()].filter((k) => !act.has(k));
+  const removed = [...act.keys()].filter((k) => !exp.has(k));
+  const changed = [...exp.keys()].filter((k) => act.has(k) && act.get(k) !== exp.get(k));
+  return { added, removed, changed };
+}
+
+/**
+ * @param {{manifestPath?: string}} [opts]
+ * @returns {{ok: boolean, problems: Array<{kind: 'missing'|'stale'|'invalid-json', subject: string, message: string}>}}
+ */
+function checkReport({ manifestPath = MANIFEST_PATH } = {}) {
+  const problems = [];
+  if (!fs.existsSync(manifestPath)) {
+    problems.push({
+      kind: 'missing',
+      subject: manifestPath,
+      message: `${manifestPath} not found. Run: node scripts/gen-cli-surface-manifest.cjs --write`,
+    });
+    return { ok: false, problems };
+  }
+  const text = fs.readFileSync(manifestPath, 'utf8');
+  let actual;
+  try {
+    actual = JSON.parse(text);
+  } catch (err) {
+    problems.push({
+      kind: 'invalid-json',
+      subject: manifestPath,
+      message: `${manifestPath} is not valid JSON (${err.message}). Run: node scripts/gen-cli-surface-manifest.cjs --write`,
+    });
+    return { ok: false, problems };
+  }
+  const expected = buildManifest();
+  if (serialize(expected) !== text) {
+    const { added, removed, changed } = diffVerbs(expected, actual);
+    const parts = [];
+    if (added.length) parts.push(`missing verbs: ${added.join(', ')}`);
+    if (removed.length) parts.push(`removed verbs: ${removed.join(', ')}`);
+    if (changed.length) parts.push(`changed verbs: ${changed.join(', ')}`);
+    if (!parts.length) parts.push('global/undeclared sections or formatting differ');
+    const subject = [...added, ...removed, ...changed][0] ?? 'global';
+    problems.push({
+      kind: 'stale',
+      subject,
+      message: `${manifestPath} is stale (${parts.join('; ')}). Run: node scripts/gen-cli-surface-manifest.cjs --write`,
+    });
+  }
+  return { ok: problems.length === 0, problems };
+}
+
+function parseArgs(argv) {
+  const opts = { write: false, check: false, json: false, manifestPath: MANIFEST_PATH };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--write') opts.write = true;
+    else if (arg === '--check') opts.check = true;
+    else if (arg === '--json') opts.json = true;
+    else if (arg === '--manifest-path') {
+      const value = argv[i + 1];
+      if (value === undefined) throw new ExitError(2, `--manifest-path requires a path argument.\n${USAGE}`);
+      opts.manifestPath = path.resolve(value);
+      i++;
+    } else {
+      throw new ExitError(2, `unknown argument: ${arg}\n${USAGE}`);
+    }
+  }
+  if (opts.write && opts.check) throw new ExitError(2, `--write and --check are mutually exclusive.\n${USAGE}`);
+  return opts;
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+
+  if (opts.write) {
+    const manifest = buildManifest();
+    fs.mkdirSync(path.dirname(opts.manifestPath), { recursive: true });
+    const tmp = `${opts.manifestPath}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, serialize(manifest), 'utf8');
+    fs.renameSync(tmp, opts.manifestPath);
+    process.stdout.write(`Wrote ${opts.manifestPath} - ${manifest.verbs.length} verb(s).\n`);
+    return 0;
+  }
+
+  if (opts.check) {
+    const report = checkReport({ manifestPath: opts.manifestPath });
+    if (opts.json) {
+      process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    } else if (report.ok) {
+      process.stdout.write(`${opts.manifestPath} is up to date.\n`);
+    } else {
+      for (const p of report.problems) process.stderr.write(`${p.kind}: ${p.subject}: ${p.message}\n`);
+    }
+    if (!report.ok) throw new ExitError(1);
+    return 0;
+  }
+
+  process.stdout.write(serialize(buildManifest()));
+  return 0;
+}
+
+if (require.main === module) runMain(main);
+
+module.exports = { buildManifest, checkReport, serialize, staleCompileProblem, aliasMap, MANIFEST_PATH };