@opengsd/gsd-core 1.8.0 → 1.9.1

package/scripts/mutation-matrix.cjs

@@ -145,6 +145,10 @@ const COVERED = {
     tests: [
       'tests/frontmatter.property.test.cjs',
       'tests/frontmatter.unit.test.cjs',
+      // #1882 added the unterminated-fence detection to frontmatter.cjs, and the tests that
+      // constrain it live here. Without this entry the mutants in that branch are covered by
+      // no test in the shard, so the module's score drops even though the behaviour is tested.
+      'tests/unusable-input.test.cjs',
     ],
     minScore: 62,
   },

package/scripts/prompt-injection-scan.sh

@@ -102,6 +102,12 @@ ALLOWLIST=(
   # exec command strings (execFileSync('npm', ['install'])) as test DATA the rule
   # must lint — not attack vectors. ADR-1703 Phase 4 (#1726).
   'tests/no-bare-npm-exec.rule.test.cjs'
+  # #2547 — the Kimi field-shadowing regression proves gsd-prompt-guard still
+  # SCANS the reconstructed edit[].new content when a model-supplied new_string
+  # tries to shadow it. The fixture must be a real injection phrase or the test
+  # asserts nothing: it is the payload the guard is required to catch, carried
+  # as test DATA. Same class as the read-injection-scanner suites above.
+  'tests/kimi-payload-field-shadowing.security.test.cjs'
 )
 
 is_allowlisted() {

package/scripts/registry-schema.cjs

@@ -2,11 +2,12 @@
 
 /**
  * scripts/registry-schema.cjs — pure schema/vocab constants + validation +
- * markdown-generation logic for the two third-party discoverability catalogs
- * (issue #2182):
+ * markdown-generation logic for the three third-party discoverability catalogs
+ * (issue #2182, plus #2904):
  *
  *   - `docs/registries/capabilities.json`  → "GSD Community Capability Registry"
  *   - `docs/registries/eos.json`           → "GSD EoS Registry" (PR2)
+ *   - `docs/registries/reviewers.json`     → "GSD Reviewer Lane Registry" (issue #2904)
  *
  * The vocabulary constants below are ADDITIVE CONTRACTS that track the
  * runtime/ADR closed vocabularies they describe — they are a documentation-
@@ -36,10 +37,19 @@
  *     (`{ namedDispatch, nested, maxDepth, background, subagentToolkit }`) —
  *     this registry accepts a free-form human summary string instead, so it
  *     carries the `AXES_FREE_STRING` sentinel rather than an enum array.
- *   - `CAPABILITY_REQUIRED` / `EOS_REQUIRED` mirror the required top-level
- *     fields for each entry type, including `enginesGsd` (ADR-1244 D1
- *     "Versioned capability manifest" — the `engines.gsd` semver-range gate,
- *     modelled on VS Code's `engines.vscode`).
+ *     `OPTIONAL_AXES` adds one further, OPTIONAL key on top of those eight:
+ *     `effortSurface` (ADR-1239 amendment #2481). An entry may omit it
+ *     (every entry published before the amendment stays valid) or declare
+ *     it as `argv` | `none`, mirroring `HOST_INTEGRATION_AXES.effortSurface`
+ *     in `src/host-integration.cts`.
+ *   - `CAPABILITY_REQUIRED` / `EOS_REQUIRED` / `REVIEWER_REQUIRED` mirror the
+ *     required top-level fields for each entry type, including `enginesGsd`
+ *     (ADR-1244 D1 "Versioned capability manifest" — the `engines.gsd`
+ *     semver-range gate, modelled on VS Code's `engines.vscode`).
+ *   - `REVIEWER_LANE_TRANSPORTS` / `REVIEWER_EVIDENCE_CLASSES` /
+ *     `REVIEWER_SLUG_RE` / `REVIEWER_FLAG_RE` / `REVIEWER_SECTION_MAX` mirror
+ *     the ADR-2782 reviewer-lane vocabulary (`capability-validator.cjs`) for
+ *     the `reviewer` entry type's `interactions` sub-object (issue #2904).
  *
  * This module is pure — no `fs`/`process`/child-process access — so tests
  * can `require()` it directly and assert on structured return values.
@@ -90,37 +100,130 @@ const AXES = Object.freeze({
   runtime: Object.freeze(['node', 'bun', 'sandboxed-web', 'python', 'go', 'rust', 'electron', 'other']),
 });
 
+// ─── ADR-1239 amendment #2481 — one additional, OPTIONAL negotiated axis ─────
+// `effortSurface` was added to the runtime-descriptor vocabulary AFTER the
+// original eight (`HOST_INTEGRATION_AXES.effortSurface` in
+// `src/host-integration.cts`). It is kept OPTIONAL here — not folded into
+// `AXES` — because registry entries mirror their upstream
+// `registry/eos-entry.json` byte-for-byte, and requiring it would
+// retroactively invalidate every entry published before the amendment.
+// Values must match `HOST_INTEGRATION_AXES.effortSurface` exactly.
+const OPTIONAL_AXES = Object.freeze({
+  effortSurface: Object.freeze(['argv', 'none']),
+});
+
+// ─── ADR-2782 reviewer-lane vocabulary (issue #2904) ─────────────────────────
+// A THIRD catalog: third-party reviewer lanes (`role: "reviewer"`, ADR-2782
+// D3). A lane registers on ZERO Loop Extension Points and is forbidden from
+// declaring `steps`/`contributions`/`gates`/`skills`/`agents`/`hooks`
+// (`FEATURE_FIELDS_FORBIDDEN_ON_REVIEWER`, capability-validator.cjs), so the
+// Capability entry's two required `interactions` fields are unsatisfiable by
+// construction for a lane — hence its own entry type rather than a relaxation
+// of the Capability schema.
+//
+// These constants are ADDITIVE CONTRACTS mirroring the canonical runtime
+// vocabulary in `gsd-core/bin/lib/capability-validator.cjs`, exactly the way
+// `AXES` mirrors `HOST_INTEGRATION_AXES`. They are hand-written mirrors, NOT
+// imports: this module is documented pure (no `fs`/`process`), and requiring a
+// `gsd-core/bin/lib` runtime module from a docs-pipeline script would invert
+// that. Parity is enforced instead by `tests/registry-reviewer-parity.test.cjs`.
+//
+// `REVIEWER_SLUG_RE` deliberately does NOT reuse the registry's kebab-case `id`
+// grammar. `LANE_SLUG_RE` permits underscores AND a leading digit —
+// `lm_studio`, `llama_cpp`, `4o-mini` are real shipped lane slugs — and
+// capability-validator.cjs:807-810 requires the two grammars stay
+// byte-identical. A kebab-only rule here would reject well-formed entries and
+// leave authors with a schema satisfiable only by lying.
+const REVIEWER_LANE_TRANSPORTS = Object.freeze(['spawn', 'openai-http']);
+const REVIEWER_EVIDENCE_CLASSES = Object.freeze(['source-grounded', 'diff-only']);
+const REVIEWER_SLUG_RE = /^[a-z0-9][a-z0-9_-]*$/;
+// Flags are kebab even when the slug is snake: `lm_studio` → `--lm-studio`.
+const REVIEWER_FLAG_RE = /^--[a-z0-9][a-z0-9-]*$/;
+// Cap for the one free-text reviewer interactions field, mirroring the 300-cap
+// on the equivalently free-form `axes.dispatch`. A REVIEWS.md heading is short.
+const REVIEWER_SECTION_MAX = 200;
+
 // ─── Required top-level fields ───────────────────────────────────────────────
-const CAPABILITY_REQUIRED = Object.freeze([
-  'id',
-  'name',
-  'type',
-  'repo',
-  'description',
-  'author',
-  'license',
-  'enginesGsd',
-  'install',
-  'uninstall',
-  'interactions',
-  'discussion',
+// The twelve fields every entry type requires. Each type's set is DERIVED from
+// this one so a future shared field cannot be added to one type's list and
+// silently forgotten in another (DEFECT.GENERATIVE-FIX). The three sets are
+// distinct frozen arrays, not aliases, so a type may still diverge deliberately
+// — as `eos` already does with `protocolVersion`.
+const BASE_REQUIRED = Object.freeze([
+  'id', 'name', 'type', 'repo', 'description', 'author', 'license',
+  'enginesGsd', 'install', 'uninstall', 'interactions', 'discussion',
 ]);
+const CAPABILITY_REQUIRED = Object.freeze([...BASE_REQUIRED]);
+const EOS_REQUIRED = Object.freeze([...BASE_REQUIRED, 'protocolVersion']);
+// A lane is installed with `gsd capability install`, owns a repo, a license and
+// an `engines.gsd` range exactly as a Feature Capability does — so it requires
+// the same twelve top-level fields. Only `interactions` differs.
+const REVIEWER_REQUIRED = Object.freeze([...BASE_REQUIRED]);
+
+// Control-character rejection (defense in depth): `allowTabNewline` widens the
+// reject-set exception for the two shell-snippet fields (install/uninstall),
+// which legitimately contain tabs/newlines; every other free text field
+// disallows ALL C0 control characters plus DEL (incl. \n/\t). Checked via char
+// codes (not a literal control-char regex range) — same approach as
+// capability-validator.cjs's hooks[].matcher check, which avoids tripping
+// ESLint's no-control-regex rule. Module-scope so both the top-level field
+// checks inside `validateEntries` and the `interactions` sub-object
+// validators (module-level functions, outside that closure) share the ONE
+// implementation rather than each keeping their own copy.
+function hasDisallowedControlChar(v, allowTabNewline) {
+  for (let c = 0; c < v.length; c += 1) {
+    const code = v.charCodeAt(c);
+    if (allowTabNewline && (code === 0x09 || code === 0x0a)) continue;
+    if (code < 0x20 || code === 0x7f) return true;
+  }
+  return false;
+}
 
-const EOS_REQUIRED = Object.freeze([
-  'id',
-  'name',
-  'type',
-  'repo',
-  'description',
-  'author',
-  'license',
-  'enginesGsd',
-  'install',
-  'uninstall',
-  'interactions',
-  'discussion',
-  'protocolVersion',
-]);
+// Caps for `interactions` array-of-strings fields (configKeys, requires,
+// runtimeCompat, produces, consumes, requiresBinaries, ...). These bound
+// UNTRUSTED third-party strings that are rendered verbatim (after mdInline
+// escaping) into a committed Markdown catalog — an unbounded count or length
+// lets a malicious registry PR blow up the generated doc.
+const INTERACTION_STRING_MAX = 200;
+const INTERACTION_ARRAY_MAX = 50;
+
+/**
+ * Validate an interactions field that is an array of free-form untrusted
+ * strings: shape, element count, per-element length, and control characters.
+ * `allowEmpty` distinguishes "may be empty" fields from non-empty-required
+ * ones — non-empty-required fields' blank-array message is expected to be
+ * handled by the caller (this helper does not special-case emptiness itself
+ * beyond letting an empty array with `allowEmpty: true` through).
+ *
+ * @param {object} interactions
+ * @param {string} field
+ * @param {(field: string, reason: string) => void} addError
+ * @param {{allowEmpty?: boolean}} [opts]
+ * @returns {void}
+ */
+function validateStringArrayField(interactions, field, addError, { allowEmpty = true } = {}) {
+  const v = interactions[field];
+  const qualifiedField = `interactions.${field}`;
+
+  if (!Array.isArray(v) || !v.every((x) => typeof x === 'string')) {
+    addError(qualifiedField, 'must be an array of strings');
+    return;
+  }
+
+  if (!allowEmpty && v.length === 0) return;
+
+  if (v.length > INTERACTION_ARRAY_MAX) {
+    addError(qualifiedField, `exceeds max entries ${INTERACTION_ARRAY_MAX}`);
+  }
+
+  for (const x of v) {
+    if (x.length > INTERACTION_STRING_MAX) {
+      addError(qualifiedField, `exceeds max length ${INTERACTION_STRING_MAX}`);
+    } else if (hasDisallowedControlChar(x, false)) {
+      addError(qualifiedField, 'must not contain control characters');
+    }
+  }
+}
 
 // Escape Markdown inline metacharacters in UNTRUSTED free text so a registry
 // entry cannot inject links/tables/code-spans into the generated catalog.
@@ -204,10 +307,7 @@ function validateCapabilityInteractions(interactions, addError) {
 
   for (const field of ['configKeys', 'requires', 'runtimeCompat', 'produces', 'consumes']) {
     if (interactions[field] === undefined) continue;
-    const v = interactions[field];
-    if (!Array.isArray(v) || !v.every((x) => typeof x === 'string')) {
-      addError(`interactions.${field}`, 'must be an array of strings');
-    }
+    validateStringArrayField(interactions, field, addError);
   }
 }
 
@@ -246,15 +346,39 @@ function validateEosInteractions(interactions, addError) {
     if (typeof axes !== 'object' || axes === null || Array.isArray(axes)) {
       addError('interactions.axes', 'axes must be an object');
     } else {
-      const expectedKeys = Object.keys(AXES);
+      const requiredKeys = Object.keys(AXES);
+      const optionalKeys = Object.keys(OPTIONAL_AXES);
       const actualKeys = Object.keys(axes);
       const actualKeySet = new Set(actualKeys);
-      const keysMatch = expectedKeys.length === actualKeys.length && expectedKeys.every((k) => actualKeySet.has(k));
-      if (!keysMatch) {
-        addError('interactions.axes', 'axes key set must exactly match the eight negotiated axes');
-      } else {
-        for (const key of expectedKeys) {
-          const allowedValues = AXES[key];
+
+      // Every AXES key is mandatory; an extra key is tolerated ONLY when it is
+      // a recognized OPTIONAL_AXES key (currently just `effortSurface`) — any
+      // other extra key is still rejected as unknown.
+      const missingRequiredKeys = requiredKeys.filter((k) => !actualKeySet.has(k));
+      const unknownKeys = actualKeys.filter((k) => !requiredKeys.includes(k) && !optionalKeys.includes(k));
+
+      if (missingRequiredKeys.length > 0) {
+        addError('interactions.axes', `axes is missing required key(s): ${missingRequiredKeys.join(', ')}`);
+      }
+      if (unknownKeys.length > 0) {
+        addError('interactions.axes', `axes has unknown key(s): ${unknownKeys.join(', ')}`);
+      }
+
+      // Only validate individual values once the key set itself is sound —
+      // mirrors the original gate (values were never checked against a
+      // malformed key set either).
+      if (missingRequiredKeys.length === 0 && unknownKeys.length === 0) {
+        for (const key of actualKeys) {
+          // Inline literal guards — CodeQL barrier pattern. Reaching here already
+          // implies `key` is one of the nine literal axis names (the unknown-key
+          // gate above rejected everything else), so this is unreachable in
+          // practice; it is written inline anyway because CodeQL cannot follow
+          // that gate across the `.includes()` filter and would otherwise flag
+          // the bracket reads below as prototype-pollution sinks.
+          if (key === '__proto__') continue;
+          if (key === 'constructor') continue;
+          if (key === 'prototype') continue;
+          const allowedValues = Object.hasOwn(AXES, key) ? AXES[key] : OPTIONAL_AXES[key];
           const v = axes[key];
           if (allowedValues === AXES_FREE_STRING) {
             if (typeof v !== 'string' || v.trim() === '') {
@@ -271,12 +395,93 @@ function validateEosInteractions(interactions, addError) {
   }
 }
 
+/**
+ * Validate the `interactions` sub-object for a reviewer entry (ADR-2782 D3
+ * lane vocabulary — issue #2904).
+ *
+ * @param {object} interactions
+ * @param {(field: string, reason: string) => void} addError
+ * @returns {void}
+ */
+function validateReviewerInteractions(interactions, addError) {
+  const allowedKeys = new Set([
+    'slug',
+    'flags',
+    'transport',
+    'evidenceClass',
+    'reviewsSection',
+    'requiresBinaries',
+    'configKeys',
+    'runtimeCompat',
+  ]);
+  for (const key of Object.keys(interactions)) {
+    if (!allowedKeys.has(key)) addError(`interactions.${key}`, 'unknown field');
+  }
+
+  for (const field of allowedKeys) {
+    if (interactions[field] === undefined) addError(`interactions.${field}`, 'missing required field');
+  }
+
+  if (interactions.slug !== undefined) {
+    const v = interactions.slug;
+    if (typeof v !== 'string' || !REVIEWER_SLUG_RE.test(v)) {
+      addError('interactions.slug', 'must match the reviewer lane slug grammar');
+    }
+  }
+
+  if (interactions.flags !== undefined) {
+    const v = interactions.flags;
+    if (!Array.isArray(v) || v.length === 0 || !v.every((x) => typeof x === 'string' && REVIEWER_FLAG_RE.test(x))) {
+      addError('interactions.flags', 'must be a non-empty array of lane CLI flags');
+    }
+  }
+
+  if (interactions.transport !== undefined) {
+    const v = interactions.transport;
+    if (typeof v !== 'string' || !REVIEWER_LANE_TRANSPORTS.includes(v)) {
+      addError('interactions.transport', 'must be one of the allowed lane transports');
+    }
+  }
+
+  if (interactions.evidenceClass !== undefined) {
+    const v = interactions.evidenceClass;
+    if (typeof v !== 'string' || !REVIEWER_EVIDENCE_CLASSES.includes(v)) {
+      addError('interactions.evidenceClass', 'must be one of the allowed evidence classes');
+    }
+  }
+
+  if (interactions.reviewsSection !== undefined) {
+    const v = interactions.reviewsSection;
+    if (typeof v !== 'string' || v.trim() === '') {
+      addError('interactions.reviewsSection', 'must be a non-empty string');
+    } else if (v.length > REVIEWER_SECTION_MAX) {
+      addError('interactions.reviewsSection', `exceeds max length ${REVIEWER_SECTION_MAX}`);
+    } else if (hasDisallowedControlChar(v, false)) {
+      addError('interactions.reviewsSection', 'must not contain control characters');
+    }
+  }
+
+  for (const field of ['requiresBinaries', 'configKeys', 'runtimeCompat']) {
+    if (interactions[field] === undefined) continue;
+    validateStringArrayField(interactions, field, addError);
+  }
+}
+
+// Per-type rules. A Map (not a plain object) so the lookup below is not a
+// bracket-read on a caller-supplied key — that shape reads as a
+// prototype-pollution sink to CodeQL, and a Map.get does not.
+const TYPE_RULES = new Map([
+  ['capability', { required: CAPABILITY_REQUIRED, validateInteractions: validateCapabilityInteractions }],
+  ['eos', { required: EOS_REQUIRED, validateInteractions: validateEosInteractions }],
+  ['reviewer', { required: REVIEWER_REQUIRED, validateInteractions: validateReviewerInteractions }],
+]);
+
 /**
  * Validate an array of registry entries against the closed schema for
- * `opts.type` ('capability' | 'eos').
+ * `opts.type` ('capability' | 'eos' | 'reviewer').
  *
  * @param {object[]} entries
- * @param {{type: 'capability'|'eos'}} opts
+ * @param {{type: 'capability'|'eos'|'reviewer'}} opts
  * @returns {{ok: boolean, errors: Array<{index: number, id?: string, field: string, reason: string}>}}
  */
 function validateEntries(entries, opts) {
@@ -284,13 +489,22 @@ function validateEntries(entries, opts) {
     return { ok: false, errors: [{ index: -1, field: '(root)', reason: 'entries must be an array' }] };
   }
 
+  // An unrecognized type is a hard error, not a silent fallthrough. Before the
+  // third type existed this was a binary ternary whose ELSE branch was
+  // `capability`, so a typo'd type validated against the wrong schema and
+  // reported plausible-looking per-entry errors.
+  const rules = TYPE_RULES.get(opts.type);
+  if (!rules) {
+    return { ok: false, errors: [{ index: -1, field: '(root)', reason: `unknown registry type "${opts.type}"` }] };
+  }
+
   // Entry-count cap: a pathologically large array (e.g. from an automated or
   // malicious PR) is rejected wholesale rather than validated entry-by-entry.
   if (entries.length > 2000) {
     return { ok: false, errors: [{ index: -1, field: '(root)', reason: 'too many entries (max 2000)' }] };
   }
 
-  const required = opts.type === 'eos' ? EOS_REQUIRED : CAPABILITY_REQUIRED;
+  const required = rules.required;
   const requiredSet = new Set(required);
   const seenIds = new Set();
   const errors = [];
@@ -322,21 +536,9 @@ function validateEntries(entries, opts) {
       }
     }
 
-    // Control-character rejection (defense in depth): `allowTabNewline` widens
-    // the reject-set exception for the two shell-snippet fields (install/
-    // uninstall), which legitimately contain tabs/newlines; every other free
-    // text field disallows ALL C0 control characters plus DEL (incl. \n/\t).
-    // Checked via char codes (not a literal control-char regex range) — same
-    // approach as capability-validator.cjs's hooks[].matcher check, which
-    // avoids tripping ESLint's no-control-regex rule.
-    const hasDisallowedControlChar = (v, allowTabNewline) => {
-      for (let c = 0; c < v.length; c += 1) {
-        const code = v.charCodeAt(c);
-        if (allowTabNewline && (code === 0x09 || code === 0x0a)) continue;
-        if (code < 0x20 || code === 0x7f) return true;
-      }
-      return false;
-    };
+    // Control-character rejection (defense in depth) — delegates to the
+    // module-scope `hasDisallowedControlChar` (shared with the `interactions`
+    // sub-object validators below) so there is exactly one implementation.
     const checkNoControlChars = (field, allowTabNewline) => {
       if (missing.has(field)) return;
       const v = entry[field];
@@ -419,10 +621,8 @@ function validateEntries(entries, opts) {
       const interactions = entry.interactions;
       if (typeof interactions !== 'object' || interactions === null || Array.isArray(interactions)) {
         addError('interactions', 'interactions must be an object');
-      } else if (opts.type === 'eos') {
-        validateEosInteractions(interactions, addError);
       } else {
-        validateCapabilityInteractions(interactions, addError);
+        rules.validateInteractions(interactions, addError);
       }
     }
 
@@ -436,12 +636,92 @@ function validateEntries(entries, opts) {
   return { ok: errors.length === 0, errors };
 }
 
+// Per-type page presentation AND per-type interaction summary both live in
+// this ONE table (Map, for the same CodeQL reason as TYPE_RULES): title/
+// addNoun drive the page header, buildSummary drives the per-entry "Every
+// interaction with GSD" line. Folding both into a single lookup means a
+// future fourth registry type MUST supply its own buildSummary or the
+// `RENDER_META.get` miss below throws — it cannot silently inherit
+// capability's (or any other type's) rendering the way the old if/else-if/
+// else chain's final `else` branch used to.
+const RENDER_META = new Map([
+  [
+    'capability',
+    {
+      title: 'GSD Community Capability Registry',
+      addNoun: 'capability',
+      buildSummary(entry, interactions) {
+        let summary =
+          `Loop Extension Points: ${(interactions.loopExtensionPoints || []).join(', ')}; ` +
+          `hook kinds: ${(interactions.hookKinds || []).join(', ')}`;
+        for (const field of ['configKeys', 'requires', 'runtimeCompat', 'produces', 'consumes']) {
+          const v = interactions[field];
+          if (Array.isArray(v) && v.length > 0) summary += `; ${field}: ${v.join(', ')}`;
+        }
+        // configKeys/requires/runtimeCompat/produces/consumes are untrusted
+        // free-form strings (schema only requires "array of strings") — same
+        // single-pass mdInline rationale as the eos branch above.
+        return summary;
+      },
+    },
+  ],
+  [
+    'eos',
+    {
+      title: 'GSD EoS Registry',
+      addNoun: 'integration',
+      buildSummary(entry, interactions) {
+        // Required AXES keys always render, in their fixed order; an OPTIONAL_AXES
+        // key (e.g. `effortSurface`) renders ONLY when the entry actually carries
+        // it — an entry that omits it must render byte-identical to before
+        // OPTIONAL_AXES existed (no `effortSurface=undefined` noise).
+        const presentOptionalKeys = Object.keys(OPTIONAL_AXES).filter(
+          (key) => interactions.axes && Object.hasOwn(interactions.axes, key),
+        );
+        const axesSummary = [...Object.keys(AXES), ...presentOptionalKeys]
+          .map((key) => `${key}=${interactions.axes ? interactions.axes[key] : undefined}`)
+          .join(', ');
+        return (
+          `Interface points: ${(interactions.interfacePoints || []).join(', ')}; ` +
+          `profile: ${interactions.profile}; protocol v${entry.protocolVersion}; axes: ${axesSummary}`
+        );
+      },
+    },
+  ],
+  [
+    'reviewer',
+    {
+      title: 'GSD Reviewer Lane Registry',
+      addNoun: 'reviewer lane',
+      buildSummary(entry, interactions) {
+        let summary =
+          `Lane: ${interactions.slug}; ` +
+          `flags: ${(interactions.flags || []).join(', ')}; ` +
+          `transport: ${interactions.transport}; ` +
+          `evidence: ${interactions.evidenceClass}; ` +
+          `REVIEWS.md section: ${interactions.reviewsSection}`;
+        for (const field of ['requiresBinaries', 'configKeys', 'runtimeCompat']) {
+          const v = interactions[field];
+          if (Array.isArray(v) && v.length > 0) summary += `; ${field}: ${v.join(', ')}`;
+        }
+        // slug/flags/transport are vocab-constrained; reviewsSection and the
+        // three arrays are untrusted free text — same single-pass mdInline
+        // rationale as the eos/capability branches above: none of the literal
+        // separator text contains Markdown metacharacters, so one pass over the
+        // assembled summary neutralizes every embedded value.
+        return summary;
+      },
+    },
+  ],
+]);
+
 /**
  * Render the deterministic Markdown document for a registry.
  *
  * @param {object[]} entries
- * @param {{type: 'capability'|'eos', sourceFile?: string}} opts
+ * @param {{type: 'capability'|'eos'|'reviewer', sourceFile?: string}} opts
  * @returns {string}
+ * @throws {Error} when opts.type is not a known registry type
  */
 function renderMarkdown(entries, opts) {
   const sorted = [...entries].sort((a, b) => {
@@ -450,19 +730,27 @@ function renderMarkdown(entries, opts) {
     return 0;
   });
   const isEos = opts.type === 'eos';
+  // An unrecognized type must fail loudly rather than silently render a
+  // "GSD Community Capability Registry" page — mirroring the validateEntries
+  // unknown-type guard above. This function writes a COMMITTED catalog file,
+  // so a silent wrong-title render is the worst failure mode available.
+  // Message shape mirrors gen-registry.cjs#renderFor's existing
+  // `gen-registry: unknown registry type "..."` throw.
+  const meta = RENDER_META.get(opts.type);
+  if (!meta) throw new Error(`registry-schema: unknown registry type "${opts.type}"`);
   const lines = [];
 
   lines.push(
     `<!-- GENERATED by scripts/gen-registry.cjs from docs/registries/${opts.sourceFile} — do not edit by hand; run \`npm run gen:registry\` -->`,
   );
   lines.push('');
-  lines.push(isEos ? '# GSD EoS Registry' : '# GSD Community Capability Registry');
+  lines.push(`# ${meta.title}`);
   lines.push('');
   lines.push(
     "> **Not an endorsement.** Inclusion means only that a maintainer merged a PR linking the author's repository — GSD has not reviewed, tested, or verified any listing. See the [registry README](./README.md).",
   );
   lines.push('');
-  lines.push(`_To add your ${isEos ? 'integration' : 'capability'}, see the [registry README](./README.md)._`);
+  lines.push(`_To add your ${meta.addNoun}, see the [registry README](./README.md)._`);
   lines.push('');
 
   if (sorted.length === 0) {
@@ -495,31 +783,12 @@ function renderMarkdown(entries, opts) {
     lines.push(`- **What it is:** ${mdInline(entry.description)}`);
     lines.push(`- **Author:** ${mdInline(entry.author)}`);
 
-    if (isEos) {
-      const axesSummary = Object.keys(AXES)
-        .map((key) => `${key}=${interactions.axes ? interactions.axes[key] : undefined}`)
-        .join(', ');
-      const summary =
-        `Interface points: ${(interactions.interfacePoints || []).join(', ')}; ` +
-        `profile: ${interactions.profile}; protocol v${entry.protocolVersion}; axes: ${axesSummary}`;
-      // Single mdInline pass over the fully-assembled summary: none of the
-      // literal separator text above contains Markdown metacharacters, so
-      // this equally neutralizes every embedded free-text/vocab value
-      // (notably interactions.axes.dispatch, a free-form untrusted string).
-      lines.push(`- **Every interaction with GSD:** ${mdInline(summary)}`);
-    } else {
-      let summary =
-        `Loop Extension Points: ${(interactions.loopExtensionPoints || []).join(', ')}; ` +
-        `hook kinds: ${(interactions.hookKinds || []).join(', ')}`;
-      for (const field of ['configKeys', 'requires', 'runtimeCompat', 'produces', 'consumes']) {
-        const v = interactions[field];
-        if (Array.isArray(v) && v.length > 0) summary += `; ${field}: ${v.join(', ')}`;
-      }
-      // configKeys/requires/runtimeCompat/produces/consumes are untrusted
-      // free-form strings (schema only requires "array of strings") — same
-      // single-pass mdInline rationale as the eos branch above.
-      lines.push(`- **Every interaction with GSD:** ${mdInline(summary)}`);
-    }
+    // Single mdInline pass over the fully-assembled per-type summary: none of
+    // the literal separator text in any RENDER_META buildSummary implementation
+    // contains Markdown metacharacters, so one pass over the assembled string
+    // equally neutralizes every embedded free-text/vocab value (notably eos's
+    // interactions.axes.dispatch, a free-form untrusted string).
+    lines.push(`- **Every interaction with GSD:** ${mdInline(meta.buildSummary(entry, interactions))}`);
 
     // Code-span content (install/uninstall) is NOT mdInline-escaped — it is a
     // verbatim shell snippet, not inline prose. Instead each block picks a
@@ -556,9 +825,18 @@ module.exports = {
   INTERFACE_POINTS,
   PROFILES,
   AXES,
+  OPTIONAL_AXES,
   AXES_FREE_STRING,
   CAPABILITY_REQUIRED,
   EOS_REQUIRED,
+  REVIEWER_REQUIRED,
+  REVIEWER_LANE_TRANSPORTS,
+  REVIEWER_EVIDENCE_CLASSES,
+  REVIEWER_SLUG_RE,
+  REVIEWER_FLAG_RE,
+  REVIEWER_SECTION_MAX,
+  INTERACTION_STRING_MAX,
+  INTERACTION_ARRAY_MAX,
   isValidGsdRange,
   validateEntries,
   renderMarkdown,

package/scripts/release-notes/conventional-title.cjs

@@ -30,18 +30,36 @@ const HEADER_RE = /^([a-z]+)(\([^)]*\))?(!)?:/i;
 // An issue reference inside a scope: `(#123)`, `(#123, core)`, etc.
 const ISSUE_REF_IN_SCOPE_RE = /#\d+/;
 
+// #2716: recognized non-user-facing conventional-commit types. A title whose
+// START-anchored type prefix is one of these is internal work (tests, chores,
+// CI, docs, refactors, perf, reverts) and must NOT render under the user-facing
+// "Enhancement" heading in release notes. Only a CLEAN prefix match qualifies —
+// untyped or anchor-defeated titles fall through to the visible Enhancement
+// fallback (a safety net so possibly-user-facing content is never hidden).
+const NON_USER_FACING_TYPES = new Set([
+  'docs', 'refactor', 'test', 'ci', 'chore', 'perf', 'revert',
+]);
+
 /**
  * Classify a clean conventional title into a changelog bucket.
  * Callers that hold a full changelog bullet line (with a `* ` marker and a
  * ` by @author` suffix) must strip those first; this operates on the title.
  *
  * @param {string} title
- * @returns {'Feature'|'Fix'|'Enhancement'}
+ * @returns {'Feature'|'Fix'|'Enhancement'|'Internal'}
  */
 function classifyBucket(title) {
   const t = String(title == null ? '' : title).trim();
   if (FEATURE_RE.test(t)) return 'Feature';
   if (FIX_RE.test(t)) return 'Fix';
+  // #2716: a clean non-user-facing type prefix → Internal (omitted from user-facing
+  // release-note sections). The HEADER_RE anchor ensures a leading tag/prefix
+  // (e.g. `[security] fix(...)`) does NOT match here — those keep falling through
+  // to the visible Enhancement fallback.
+  const headerMatch = HEADER_RE.exec(t);
+  if (headerMatch && NON_USER_FACING_TYPES.has(headerMatch[1].toLowerCase())) {
+    return 'Internal';
+  }
   return 'Enhancement';
 }