@opengsd/gsd-core 1.12.0 → 1.13.0

package/scripts/lib/shellcheck-fetch.cjs

@@ -0,0 +1,247 @@
+'use strict';
+
+/**
+ * shellcheck-fetch.cjs
+ *
+ * Dependency-free replacement for the `shellcheck` npm package (removed in
+ * #4120 — its extraction step pulled in `decompress@4.2.1`, which carries an
+ * unpatched CRITICAL zip-slip vulnerability, GHSA-mp2f-45pm-3cg9, CVSS 9.1,
+ * plus two moderate findings, with no patched version available upstream).
+ *
+ * This module fetches a PINNED koalaman/shellcheck release directly from
+ * GitHub releases (never "latest" — see SHELLCHECK_VERSION below), extracts
+ * the single `shellcheck` binary from the release's `.tar.gz` asset using
+ * only Node's built-in `https`/`zlib` modules plus a small hand-written tar
+ * reader (no third-party archive library), and caches the extracted binary
+ * for reuse across runs.
+ *
+ * Zip-slip defense: unlike `decompress`, which wrote extracted files using
+ * PATHS TAKEN FROM THE ARCHIVE (the exact defect class in GHSA-mp2f-45pm-
+ * 3cg9 — a malicious archive entry named e.g. `../../etc/passwd` gets
+ * written there verbatim), this reader NEVER uses an archive-supplied name
+ * as a filesystem path. `extractFileFromTar` only ever returns the matched
+ * entry's raw byte content; the caller (`resolveShellcheckBin`) writes those
+ * bytes to a path it constructs itself (`<cacheDir>/shellcheck`), and the
+ * archive's own name field is used only for a string-equality/suffix CHECK
+ * (`name === targetName || name.endsWith('/' + targetName)`), never
+ * interpolated into a path passed to `fs.writeFileSync`/`fs.mkdirSync`/etc.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const zlib = require('node:zlib');
+const https = require('node:https');
+const { ExitError } = require('./cli-exit.cjs');
+
+// Pinned explicitly — verified against `koalaman/shellcheck`'s GitHub
+// releases API as the current latest tag at the time this was written
+// (2026-08-31). Never resolved dynamically ("latest") — a moving target
+// would make this lint's exact ShellCheck version, and therefore its exact
+// finding set against scripts/lint-workflow-shellcheck-baseline.json,
+// non-reproducible across runs/machines/CI.
+const SHELLCHECK_VERSION = 'v0.11.0';
+
+const ROOT = path.join(__dirname, '..', '..');
+const CACHE_DIR = path.join(ROOT, 'node_modules', '.cache', 'shellcheck', SHELLCHECK_VERSION);
+const CACHED_BIN_PATH = path.join(CACHE_DIR, 'shellcheck');
+
+// process.arch -> the arch token ShellCheck's release asset names use.
+// Only the two architectures that actually matter for this repo (per
+// .github/workflows/test.yml: the lint-tests job that runs this script only
+// runs on ubuntu-latest, which is x86_64; and Apple Silicon dev machines are
+// aarch64) are supported — anything else fails with a clear error rather
+// than guessing.
+const ARCH_MAP = { x64: 'x86_64', arm64: 'aarch64' };
+
+const MAX_REDIRECTS = 5;
+
+// Bounds each individual HTTP hop (the initial request AND every redirect
+// hop get their own fresh 30s budget, rather than one shared budget across
+// the whole redirect chain) — a stalled connection on any single hop is
+// caught in a bounded time, mirroring lint-workflow-shellcheck.cjs's own
+// SHELLCHECK_TIMEOUT_MS bound on the ShellCheck subprocess. A bare `timeout`
+// option on the request does NOT abort it by itself — Node only emits a
+// 'timeout' event, which must be handled by destroying the request (see the
+// `req.on('timeout', ...)` below).
+const DOWNLOAD_TIMEOUT_MS = 30_000;
+
+/**
+ * Issue one real HTTPS request. Exists as its own function purely so tests
+ * can inject a fake in its place (see `httpsGetFollowingRedirects`'s
+ * `requestFn` parameter) — production callers never pass an override, so
+ * the real download path always uses this exact implementation.
+ */
+function defaultRequestFn(url, options, callback) {
+  return https.get(url, options, callback);
+}
+
+/**
+ * GET `url` following HTTP redirects manually — `https.get` does NOT follow
+ * redirects automatically, and GitHub release asset URLs redirect through
+ * `objects.githubusercontent.com`. Resolves with the full response body as a
+ * Buffer once a 200 response is received.
+ *
+ * `requestFn` defaults to a real `https.get`-based transport
+ * (`defaultRequestFn`) and is only ever overridden in tests, so calling this
+ * with zero/one arg from `resolveShellcheckBin` is unchanged behavior.
+ */
+function httpsGetFollowingRedirects(url, redirectsLeft = MAX_REDIRECTS, requestFn = defaultRequestFn) {
+  return new Promise((resolve, reject) => {
+    const req = requestFn(
+      url,
+      { headers: { 'User-Agent': 'gsd-core-shellcheck-fetch' }, timeout: DOWNLOAD_TIMEOUT_MS },
+      (res) => {
+        const status = res.statusCode || 0;
+        if (status >= 300 && status < 400 && res.headers.location) {
+          res.resume(); // drain so the socket can be reused/closed
+          if (redirectsLeft <= 0) {
+            reject(new Error(`too many redirects fetching ${url}`));
+            return;
+          }
+          const next = new URL(res.headers.location, url).toString();
+          httpsGetFollowingRedirects(next, redirectsLeft - 1, requestFn).then(resolve, reject);
+          return;
+        }
+        if (status !== 200) {
+          res.resume();
+          reject(new Error(`unexpected HTTP ${status} fetching ${url}`));
+          return;
+        }
+        const chunks = [];
+        res.on('data', (chunk) => chunks.push(chunk));
+        res.on('end', () => resolve(Buffer.concat(chunks)));
+        res.on('error', reject);
+      },
+    );
+    req.on('error', reject);
+    // `timeout` in the options above only ARMS a timer — Node emits a
+    // 'timeout' event on the request but does not abort it. Without this
+    // handler the request (and this Promise) would hang indefinitely past
+    // the configured bound on a stalled connection.
+    req.on('timeout', () => {
+      req.destroy(new Error(`timed out after ${DOWNLOAD_TIMEOUT_MS}ms fetching ${url}`));
+    });
+  });
+}
+
+/**
+ * Find the entry named (or path-ending-in) `targetName` inside a raw
+ * (already gunzipped) POSIX tar byte stream and return its content as a
+ * Buffer, or `null` if not found.
+ *
+ * Tar format: a sequence of 512-byte headers — name at offset 0/length 100,
+ * size at offset 124/length 12 (octal ASCII), typeflag at offset 156 — each
+ * followed by that many content bytes, padded up to the next 512-byte
+ * boundary, terminated by an all-zero 512-byte block. This deliberately
+ * implements only enough to locate ONE known entry name (no general
+ * multi-file extraction, no symlink handling, no GNU long-name `@LongLink`
+ * entries — ShellCheck's own release tarballs never need them) — see this
+ * module's header comment for why the entry's NAME is never used as a
+ * filesystem path.
+ */
+function extractFileFromTar(buffer, targetName) {
+  let offset = 0;
+  while (offset + 512 <= buffer.length) {
+    const header = buffer.subarray(offset, offset + 512);
+    if (header.every((b) => b === 0)) break; // end-of-archive marker
+    const name = header.subarray(0, 100).toString('utf8').replace(/\0.*$/, '');
+    const sizeRaw = header.subarray(124, 136).toString('utf8').replace(/\0.*$/, '').trim();
+    const size = sizeRaw === '' ? 0 : parseInt(sizeRaw, 8);
+    const typeflag = String.fromCharCode(header[156]);
+    const dataStart = offset + 512;
+    const isRegularFile = typeflag === '0' || typeflag === '\0';
+    if (isRegularFile && (name === targetName || name.endsWith(`/${targetName}`))) {
+      return buffer.subarray(dataStart, dataStart + size);
+    }
+    const contentBlocks = Math.ceil(size / 512);
+    offset = dataStart + contentBlocks * 512;
+  }
+  return null;
+}
+
+/**
+ * Resolve the local path to a working, executable `shellcheck` binary,
+ * downloading and caching the pinned release on first use. Subsequent calls
+ * (same version) reuse the cached binary with no network activity — mirrors
+ * the `fs.accessSync(bin, F_OK | X_OK)` cache-check pattern already used by
+ * this script's own `runShellcheck`.
+ */
+async function resolveShellcheckBin() {
+  try {
+    fs.accessSync(CACHED_BIN_PATH, fs.constants.F_OK | fs.constants.X_OK);
+    return CACHED_BIN_PATH;
+  } catch {
+    // not cached yet — fall through to download
+  }
+
+  if (process.platform === 'win32') {
+    throw new ExitError(
+      1,
+      'lint-workflow-shellcheck: automatic ShellCheck download is not supported on Windows yet ' +
+        '(this lint only ever runs in the ubuntu-latest lint-tests CI job — see .github/workflows/test.yml — ' +
+        'so this is an honest platform gap, not expected to be hit in CI).',
+    );
+  }
+  const platform = process.platform === 'darwin' || process.platform === 'linux' ? process.platform : null;
+  if (!platform) {
+    throw new ExitError(
+      1,
+      `lint-workflow-shellcheck: unsupported platform '${process.platform}' for ShellCheck auto-download ` +
+        `(supported: linux, darwin).`,
+    );
+  }
+  const arch = ARCH_MAP[process.arch];
+  if (!arch) {
+    throw new ExitError(
+      1,
+      `lint-workflow-shellcheck: unsupported architecture '${process.arch}' for ShellCheck auto-download ` +
+        `(supported: x86_64 [node arch 'x64'], aarch64 [node arch 'arm64']).`,
+    );
+  }
+
+  const assetName = `shellcheck-${SHELLCHECK_VERSION}.${platform}.${arch}.tar.gz`;
+  const url = `https://github.com/koalaman/shellcheck/releases/download/${SHELLCHECK_VERSION}/${assetName}`;
+
+  let gz;
+  try {
+    gz = await httpsGetFollowingRedirects(url);
+  } catch (e) {
+    throw new ExitError(1, `lint-workflow-shellcheck: failed to download ShellCheck (${url}): ${e.message}`);
+  }
+
+  let tarBuf;
+  try {
+    tarBuf = zlib.gunzipSync(gz);
+  } catch (e) {
+    throw new ExitError(1, `lint-workflow-shellcheck: failed to gunzip downloaded ShellCheck archive: ${e.message}`);
+  }
+
+  const entry = extractFileFromTar(tarBuf, 'shellcheck');
+  if (!entry) {
+    throw new ExitError(
+      1,
+      `lint-workflow-shellcheck: could not find a 'shellcheck' entry inside downloaded archive ${assetName}`,
+    );
+  }
+
+  fs.mkdirSync(CACHE_DIR, { recursive: true });
+  // Write to a per-process temp path and rename into place — avoids any
+  // other concurrent invocation observing (and trying to execute) a
+  // partially-written binary at the real cache path.
+  const tmpPath = path.join(CACHE_DIR, `.shellcheck.tmp-${process.pid}`);
+  fs.writeFileSync(tmpPath, entry);
+  fs.chmodSync(tmpPath, 0o755);
+  fs.renameSync(tmpPath, CACHED_BIN_PATH);
+
+  return CACHED_BIN_PATH;
+}
+
+module.exports = {
+  SHELLCHECK_VERSION,
+  CACHED_BIN_PATH,
+  MAX_REDIRECTS,
+  DOWNLOAD_TIMEOUT_MS,
+  extractFileFromTar,
+  httpsGetFollowingRedirects,
+  resolveShellcheckBin,
+};

package/scripts/lint-allow-test-rule-refs.allowlist.json

@@ -24,7 +24,6 @@
   "tests/code-review-pipeline-regression.test.cjs :: source-text-is-the-product",
   "tests/code-review.test.cjs :: source-text-is-the-product",
   "tests/codebuddy-install.test.cjs :: source-text-is-the-product",
-  "tests/codex-config.test.cjs :: source-text-is-the-product",
   "tests/command-contract.test.cjs :: source-text-is-the-product",
   "tests/commands.test.cjs :: source-text-is-the-product",
   "tests/config-field-docs.test.cjs :: docs-parity",
@@ -52,7 +51,6 @@
   "tests/frontmatter-cli.test.cjs :: source-text-is-the-product",
   "tests/gates-taxonomy.test.cjs :: source-text-is-the-product",
   "tests/git-base-branch.test.cjs :: source-text-is-the-product",
-  "tests/gsd-check-update-worker-platform-gate.test.cjs :: structural-regression-guard",
   "tests/gsd-researcher-app-aware.test.cjs :: source-text-is-the-product",
   "tests/gsd-researcher-flow-diagram.test.cjs :: source-text-is-the-product",
   "tests/gsd-settings-advanced.test.cjs :: source-text-is-the-product",
@@ -74,13 +72,11 @@
   "tests/next-safety-gates.test.cjs :: source-text-is-the-product",
   "tests/next-up-clear-order.test.cjs :: source-text-is-the-product",
   "tests/no-hardcoded-home-gsd-tools.test.cjs :: source-text-is-the-product",
-  "tests/orphaned-hooks.test.cjs :: structural-regression-guard",
   "tests/package-legitimacy-gate.test.cjs :: source-text-is-the-product",
   "tests/parallel-dependent-plans.test.cjs :: source-text-is-the-product",
   "tests/path-replacement.test.cjs :: source-text-is-the-product",
   "tests/phase.test.cjs :: source-text-is-the-product",
   "tests/phase6-capability-docs.test.cjs :: source-text-is-the-product",
-  "tests/phase6-capstone-conformance.test.cjs :: source-text-is-the-product",
   "tests/phase6-planning-capabilities.test.cjs :: source-text-is-the-product",
   "tests/plan-bounce.test.cjs :: source-text-is-the-product",
   "tests/plan-phase-drift-guard.test.cjs :: source-text-is-the-product",
@@ -105,7 +101,6 @@
   "tests/research-agent-profiles.test.cjs :: source-text-is-the-product",
   "tests/roadmap.test.cjs :: source-text-is-the-product",
   "tests/runtime-launcher-parity.test.cjs :: structural-regression-guard",
-  "tests/runtime-name-policy.test.cjs :: source-text-is-the-product",
   "tests/scan-command.test.cjs :: source-text-is-the-product",
   "tests/secret-scan-lint.security.test.cjs :: source-text-is-the-product",
   "tests/secure-phase.test.cjs :: source-text-is-the-product",
@@ -113,7 +108,6 @@
   "tests/security-scan.security.test.cjs :: source-text-is-the-product",
   "tests/seed-scan-new-milestone.test.cjs :: source-text-is-the-product",
   "tests/settings-integrations.test.cjs :: source-text-is-the-product",
-  "tests/settings-jsonc.test.cjs :: structural-regression-guard",
   "tests/skill-frontmatter-contract.test.cjs :: source-text-is-the-product",
   "tests/spawn-liveness-banner.test.cjs :: source-text-is-the-product",
   "tests/state.test.cjs :: source-text-is-the-product",

package/scripts/lint-allow-test-rule-refs.effective-ceiling.json

@@ -1,4 +1,4 @@
 {
-  "maxSites": 10,
+  "maxSites": 84,
   "grace": 2
 }

package/scripts/lint-allow-test-rule-refs.unverified-ceiling.json

@@ -1,3 +1,3 @@
 {
-  "maxFiles": 282
+  "maxFiles": 283
 }

package/scripts/lint-docs-guard-registration.exempt-baseline.cjs

@@ -31,6 +31,7 @@
  * `docs-guard-exempt:` marker for its specific reason.
  */
 const DOCS_GUARD_EXEMPT_BASELINE = [
+  'adr-612-bracket-phase-counting.test.cjs',
   'adr-parser.test.cjs',
   'adr-parser.unit.test.cjs',
   'agent-marker-documentation-guard.test.cjs',
@@ -103,6 +104,10 @@ const DOCS_GUARD_EXEMPT_BASELINE = [
  * exact same scan.
  */
 const DOCS_GUARD_EXEMPT_DOCS_PATHS = {
+  // #2761: cites docs/adr/612-bracket-phase-id-convention.md in an explanatory
+  // comment describing ADR-612's Decision 1; the file never reads that (or any)
+  // docs/ file — every read call it makes targets a tmpdir .planning fixture.
+  'adr-612-bracket-phase-counting.test.cjs': ['docs/adr/612-bracket-phase-id-convention.md'],
   'adr-parser.test.cjs': ['docs/adr/0001.md', 'docs/adr/0002.md', 'docs/adr/0010.md', 'docs/adr/NNNN.md'],
   'adr-parser.unit.test.cjs': ['docs/adr/0001.md', 'docs/adr/0099.md', 'docs/adr/NNNN.md'],
   'agent-marker-documentation-guard.test.cjs': ['docs/reference', 'docs/reference/workflow-fragments.md'],

package/scripts/lint-phase-enumeration-drift.cjs

@@ -84,9 +84,13 @@
  *     shape as `collectDiskPhases` and the `audit.cts` scanners; it must see
  *     every phase directory regardless of milestone window to catch a
  *     naming/duplicate defect wherever it lives.
- *   - `src/verify.cts` `cmdVerifySchemaDrift`: resolves ONE caller-supplied
+ *   - `src/verify.cts` `resolvePhaseDirByToken`: resolves ONE caller-supplied
  *     `phase` argument to its directory (falling back to an exact-name
  *     match) — a single-phase LOOKUP, not a current-milestone enumeration.
+ *     Originally `cmdVerifySchemaDrift`'s own inline block; #3348 lifted it
+ *     into this shared helper (also used by the new `cmdVerifyContextDrift`)
+ *     without changing what question it asks, so the exemption moved with
+ *     the call site rather than multiplying.
  *   - `src/init.cts` `detectHasPriorPhases`: answers "has this project EVER
  *     completed a phase", explicitly excluding the current one. A history
  *     probe across all milestones, not a current-milestone enumeration.
@@ -128,8 +132,10 @@
  *     `--include-archived` merge are phase LOCATION and archive
  *     enumeration, not current-milestone enumeration; both legitimately
  *     read the physical set. Its ENUMERATION path routes through the owner.
- *   - `src/roadmap-parser.cts` `getMilestonePhaseFilter` and its #3262-extracted
- *     set-building owner `scanMilestonePhaseIds` (the same two heading/
+ *   - `src/roadmap-parser.cts` `getMilestonePhaseFilter` and its shared
+ *     set-building implementation `scanMilestonePhaseIdSets` (the public
+ *     `scanMilestonePhaseIds` wrapper remains a directly iterable Set; the
+ *     same two heading/
  *     #3577 `collectTablePhaseRows` — the table-scan sibling feeding the same
  *     membership set; its local 999-only exclusion mirrors the owner's
  *     deliberate NOT-isSentinelPhaseId choice (a leading 0 is a real decimal
@@ -142,6 +148,18 @@
  *     ("00.1" is a real phase, not milestone 0). This scan asks a narrower
  *     question — "which phase ids does this milestone's window declare" —
  *     where only the 999 icebox range is excluded.
+ *   - `src/state.cts` `countRoadmapPhaseHeadings`: its bracket branch composes
+ *     bracket-milestone sentinel detection through `isSentinelPhaseId`, but
+ *     retains a separate bare-token `999` rule. That rule intentionally does
+ *     NOT use the convention-blind canonical predicate: the latter also reads
+ *     leading `0`/`00.1` as milestone-0 sentinels, while a legacy-spelled bare
+ *     zero token inside an opted-in bracket project is a real mid-migration
+ *     phase. This is the state-counter twin of the roadmap-parser exemption.
+ *     The guard has no per-detector exemption scope: it ORs the enumeration
+ *     and sentinel detectors before consulting this function-only map. The
+ *     whole-function exemption is therefore accepted; it is bounded because
+ *     this counter performs no phases-directory `readdirSync` and needs the
+ *     exemption only for its intentional bare-token `999` sentinel literal.
  *   - `src/state.cts` `cmdStateValidate` ("Gate 1: Validate STATE.md against
  *     filesystem"): resolves ONE directory — the disk match for STATE.md's
  *     own `Current Phase` field — by prefix, a single-phase LOOKUP, not an
@@ -291,7 +309,7 @@ const OWNER_FILES = new Set([
 // `lint-milestone-window-drift.cjs`'s FUNCTION_SCOPED_EXEMPTIONS mechanism.
 // See the header comment for the full written reason behind each entry.
 const FUNCTION_SCOPED_EXEMPTIONS = new Map([
-  [path.join('src', 'verify.cts'), new Set(['cmdValidateHealth', 'cmdVerifySchemaDrift'])],
+  [path.join('src', 'verify.cts'), new Set(['cmdValidateHealth', 'resolvePhaseDirByToken'])],
   [path.join('src', 'init.cts'), new Set(['detectHasPriorPhases', 'detectUiPhaseActive'])],
   [path.join('src', 'milestone.cts'), new Set(['archivePhaseDirectories', 'cmdMilestoneComplete', 'cmdPhasesClear'])],
   // #3849: collectSiblingWorktreePhaseNums reads a SIBLING worktree's phases dir —
@@ -300,10 +318,10 @@ const FUNCTION_SCOPED_EXEMPTIONS = new Map([
   [path.join('src', 'phase.cts'), new Set(['cmdPhasesList', 'cmdPhaseNextDecimal', 'cmdPhasePlanIndex', 'cmdPhaseInsert', 'renameDecimalPhases', 'renameIntegerPhases', 'collectSiblingWorktreePhaseNums'])],
   [path.join('src', 'audit.cts'), new Set(['listAuditPhaseTargets'])],
   [path.join('src', 'commands.cts'), new Set(['cmdHistoryDigest'])],
-  [path.join('src', 'state.cts'), new Set(['cmdStateValidate', 'cmdStateSync', 'cmdStateRebuild'])],
+  [path.join('src', 'state.cts'), new Set(['cmdStateValidate', 'cmdStateSync', 'cmdStateRebuild', 'countRoadmapPhaseHeadings'])],
   [path.join('src', 'roadmap-upgrade.cts'), new Set(['computeMigrationPlan'])],
   [path.join('src', 'smart-entry.cts'), new Set(['detectVerifyFailed'])],
-  [path.join('src', 'roadmap-parser.cts'), new Set(['getMilestonePhaseFilter', 'scanMilestonePhaseIds', 'collectTablePhaseRows'])],
+  [path.join('src', 'roadmap-parser.cts'), new Set(['getMilestonePhaseFilter', 'scanMilestonePhaseIdSets', 'collectTablePhaseRows'])],
   [path.join('src', 'planning-snapshot.cts'), new Set(['buildAllPhaseDirNamesField'])],
 ]);
 

package/scripts/lint-phase-id-drift.cjs

@@ -53,6 +53,35 @@ const TOKEN_DRIFT_RE = /(?:\\{1,2}d|\[0-9\])\+\[A-Z(?:a-z)?\]\??\(\?:(?:\\{1,2}\
 const OWNER_RE = /^\s*\/\/.*phase-id-owner:/;
 const CANON_REF = 'PHASE_NUMBER_TOKEN_SOURCE';
 
+// #2761 M3 (trek-e review): the SECOND grammar this seam owns — the BRACKET
+// project-code class of `[CODE.MM]`, spelled `[A-Z][A-Z0-9_]*` (with its
+// case-widened `[A-Za-z]`/`[A-Za-z0-9_]` variant tolerated so a trivial rewrite
+// does not evade the rule). The token guard above only ever knew the phase-
+// NUMBER grammar, so three files re-typed this class verbatim — roadmap-parser's
+// bracket-fallback selector, state's `isMilestoneBounded`, verify's
+// `checkBracketCoherence` — and `check:phase-id-drift` reported clean the whole
+// time. That is the blind spot which let #2761's own "no token literal outside
+// src/phase-id.cts" gate pass while being violated. Build from
+// `BRACKET_PROJECT_CODE_SRC`, `BRACKET_ID_SRC`, `bracketMilestoneIntroSrcFor`
+// or `BRACKET_MILESTONE_INTRO_CAPTURING_SRC` instead.
+const BRACKET_CODE_DRIFT_RE = /\[A-Z(?:a-z)?\]\[A-Z(?:a-z)?0-9_\]\*/;
+
+// This rule has NO counterpart to the token rule's `line.includes(CANON_REF)`
+// escape, and that omission is the point.
+//
+// That escape is LINE-level: a line naming the canonical source anywhere on it
+// is taken as built-from-the-owner. verify.cts's copy read
+//
+//   new RegExp(`^\\[[A-Z][A-Z0-9_]*\\.(${BRACKET_MILESTONE_NUMERIC_SRC})\\]`, 'i')
+//
+// — an owner reference for the MILESTONE field sharing a line with a re-typed
+// PROJECT-CODE class. A line-level escape waves that through, so a bracket rule
+// that copied it would have kept reporting clean on the very site under review.
+// Partial ownership IS the drift. Only a `// phase-id-owner:` sanction
+// suppresses this rule, and a sanction has to state which half is deliberate.
+const BRACKET_OWNER_HINT =
+  'BRACKET_PROJECT_CODE_SRC / BRACKET_ID_SRC / bracketMilestoneIntroSrcFor / BRACKET_MILESTONE_INTRO_CAPTURING_SRC';
+
 /**
  * Pure: find every literal re-derivation of the canonical phase-number token in
  * `text` that is NOT sanctioned. A site is sanctioned when the nearest preceding
@@ -79,6 +108,28 @@ function findPhaseIdRegexDrift(text) {
   return out;
 }
 
+/**
+ * Pure: find every literal re-derivation of the BRACKET project-code grammar in
+ * `text` that is NOT sanctioned. Same sanction mechanism as the token rule — a
+ * dedicated `// phase-id-owner:` comment on the nearest preceding non-blank
+ * line — but deliberately WITHOUT its line-level owner-reference escape, so a
+ * site that references the owner for one field while re-typing the other is
+ * still reported (see BRACKET_CODE_DRIFT_RE's note). Returns [{ line, found }].
+ */
+function findBracketGrammarDrift(text) {
+  const out = [];
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const m = BRACKET_CODE_DRIFT_RE.exec(lines[i]);
+    if (!m) continue;
+    let j = i - 1;
+    while (j >= 0 && lines[j].trim() === '') j--; // nearest preceding non-blank line
+    if (j >= 0 && OWNER_RE.test(lines[j])) continue;
+    out.push({ line: i + 1, found: m[0] });
+  }
+  return out;
+}
+
 // Authored TypeScript source only (the generated bin/lib/*.cjs mirror it).
 const SCAN_DIRS = ['src'];
 const SCAN_EXT = new Set(['.cts', '.ts', '.mts']);
@@ -104,6 +155,67 @@ function walk(dir, acc) {
   return acc;
 }
 
+// ─── #2761 M4: the heading-baseline selector census ────────────────────────
+//
+// `phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.<MODE>)` is the other half
+// of this seam: it decides which intro grammar a call site compiles, and the
+// MODE argument is a fact about that site's history that no behavioural test
+// can recover — flipping verify's milestone-complete site from LABEL_ONLY to
+// ANY_BRACKET grants a tolerance it has never had, and every behavioural test
+// still passes. Pinning it therefore requires reading the authored source.
+//
+// That reading lives HERE, not in the test suite. `tests/**` runs
+// `local/no-source-grep` at ERROR, and its documented exemption
+// (CONTEXT.md: RULESET.TESTS.no-source-grep.exemption) is reserved for tests
+// whose subject is a runtime CONTRACT FILE — STATE.md, config.toml,
+// hooks.json, agent .md — which `src/*.cts` is not. The suite had claimed that
+// exemption anyway. Scripts are the sanctioned home for source scanning (the
+// rule runs at `warn` in `scripts/**`, and this file already scans src/ for the
+// grammar rules above), so the scan is exported as structured data and the test
+// asserts on the returned census instead of on file text.
+const SELECTOR_CALL_RE = /phaseHeadingPrefixSrcFor\(/g;
+const SELECTOR_BASELINE_RE = /phaseHeadingPrefixSrcFor\(\s*PHASE_HEADING_BASELINE\.(ANY_BRACKET|LABEL_ONLY)/g;
+
+/**
+ * Pure: census the heading-baseline selector calls in `text`.
+ *
+ * `total` counts EVERY invocation, so a call that does not name a
+ * `PHASE_HEADING_BASELINE` member shows up as `total > ANY_BRACKET +
+ * LABEL_ONLY` — a hole in the pin rather than a silently uncounted site.
+ * Returns { ANY_BRACKET, LABEL_ONLY, total }.
+ */
+function countSelectorBaselines(text) {
+  const out = { ANY_BRACKET: 0, LABEL_ONLY: 0, total: 0 };
+  for (const m of text.matchAll(SELECTOR_BASELINE_RE)) out[m[1]] += 1;
+  out.total = (text.match(SELECTOR_CALL_RE) || []).length;
+  return out;
+}
+
+/**
+ * Scan the authored source tree and return the selector census keyed by
+ * repo-relative path, for every file that consumes the selector at least once.
+ * `phase-id.cts` is excluded: it DEFINES the selector, so its own occurrences
+ * are the declaration, not a consumer's choice of baseline.
+ */
+function scanSelectorBaselines(root) {
+  const census = {};
+  for (const dir of SCAN_DIRS) {
+    for (const file of walk(path.join(root, dir), [])) {
+      const rel = path.relative(root, file);
+      if (EXEMPT.has(rel)) continue;
+      let text;
+      try {
+        text = fs.readFileSync(file, 'utf8');
+      } catch {
+        continue;
+      }
+      const counts = countSelectorBaselines(text);
+      if (counts.total > 0) census[path.basename(file)] = counts;
+    }
+  }
+  return census;
+}
+
 /**
  * Scan the authored source tree and return every unsanctioned phase-token
  * re-derivation, each annotated with the repo-relative file path.
@@ -121,7 +233,11 @@ function scanRepo(root) {
         continue;
       }
       for (const d of findPhaseIdRegexDrift(text)) {
-        violations.push({ file: rel, ...d });
+        violations.push({ file: rel, kind: 'token', ...d });
+      }
+      // #2761 M3: the bracket grammar is the second thing this seam owns.
+      for (const d of findBracketGrammarDrift(text)) {
+        violations.push({ file: rel, kind: 'bracket', ...d });
       }
     }
   }
@@ -132,19 +248,28 @@ function main() {
   const root = path.join(__dirname, '..');
   const violations = scanRepo(root);
   if (violations.length === 0) {
-    process.stdout.write('ok phase-id-drift: no unsanctioned phase-token re-derivations outside phase-id.cts\n');
+    process.stdout.write('ok phase-id-drift: no unsanctioned phase-token or bracket-grammar re-derivations outside phase-id.cts\n');
     return;
   }
-  process.stderr.write('phase-id-drift: literal re-derivation(s) of the canonical phase-number token found.\n');
-  process.stderr.write('Build the regex from phase-id.cjs `PHASE_NUMBER_TOKEN_SOURCE` (or phaseMarkdownRegexSource for a\n');
-  process.stderr.write('known number), or sanction the site with a dedicated `// phase-id-owner: <reason>`\n');
-  process.stderr.write('comment on the line directly above the regex:\n');
+  process.stderr.write('phase-id-drift: literal re-derivation(s) of a canonical grammar found.\n');
+  process.stderr.write(`Build the regex from phase-id.cjs \`${CANON_REF}\` (or phaseMarkdownRegexSource for a\n`);
+  process.stderr.write(`known number) for the phase-number token, or from ${BRACKET_OWNER_HINT}\n`);
+  process.stderr.write('for the bracket grammar — or sanction the site with a dedicated\n');
+  process.stderr.write('`// phase-id-owner: <reason>` comment on the line directly above the regex:\n');
   for (const d of violations) {
-    process.stderr.write(`  ${d.file}:${d.line}  ${d.found}\n`);
+    process.stderr.write(`  [${d.kind}] ${d.file}:${d.line}  ${d.found}\n`);
   }
   process.exitCode = 1;
 }
 
 if (require.main === module) main();
 
-module.exports = { findPhaseIdRegexDrift, scanRepo, TOKEN_DRIFT_RE };
+module.exports = {
+  findPhaseIdRegexDrift,
+  findBracketGrammarDrift,
+  scanRepo,
+  countSelectorBaselines,
+  scanSelectorBaselines,
+  TOKEN_DRIFT_RE,
+  BRACKET_CODE_DRIFT_RE,
+};