@opengsd/gsd-core 1.20.1 → 1.21.0

package/scripts/ci-fix-next-rerun.cjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+'use strict';
+
+// ci-fix-next-rerun.cjs — #6076: re-run ONLY the `Base branch health` job of a
+// PR's latest Tests run after the `fix-next` label was added or removed.
+//
+// Runs from .github/workflows/fix-next-rerun.yml (pull_request_target) against
+// the BASE sha's copy of this file, never the PR's. The core is dependency
+// injected (`gh`, `now`, `sleep`) so every branch is tested without a network.
+
+const { execFile } = require('node:child_process');
+const { runMain } = require('./lib/cli-exit.cjs');
+
+const BASE_HEALTH_JOB_NAME = 'Base branch health';
+const TESTS_WORKFLOW_FILE = 'test.yml';
+const GH_TIMEOUT_MS = 30000;
+const DEFAULT_DEADLINE_MS = 85 * 60 * 1000;
+const DEFAULT_POLL_MS = 30 * 1000;
+const PR_NUMBER_PATTERN = /^[1-9]\d*$/;
+const HEAD_SHA_PATTERN = /^[0-9a-f]{40}$/i;
+
+/**
+ * @param {object} opts
+ * @param {(args:string[]) => Promise<string>} opts.gh  stdout of `gh <args>`; throws on failure
+ * @param {string} opts.repo      owner/repo
+ * @param {string} opts.headSha   head sha from the label event payload
+ * @param {string} opts.prNumber  PR number
+ * @param {() => number} opts.now ms clock (read once at start, once per incomplete poll)
+ * @param {(ms:number) => Promise<void>} opts.sleep
+ * @param {number} opts.deadlineMs  how long to wait for the run to complete
+ * @param {number} opts.pollMs
+ * @returns {Promise<{action:'rerun'|'skip'|'error', reason:string, runId?:string, jobId?:string}>}
+ */
+async function rerunBaseHealth({
+  gh, repo, headSha, prNumber, now, sleep, deadlineMs = DEFAULT_DEADLINE_MS, pollMs = DEFAULT_POLL_MS,
+}) {
+  try {
+    const deadline = now() + deadlineMs;
+    let run;
+    for (;;) {
+      const listed = JSON.parse(await gh([
+        'run', 'list', '--workflow', TESTS_WORKFLOW_FILE, '--commit', headSha,
+        '--event', 'pull_request', '--limit', '1', '--json', 'databaseId,status,conclusion',
+      ]));
+      if (!Array.isArray(listed) || listed.length === 0) return { action: 'skip', reason: 'no-run' };
+      [run] = listed;
+      if (run.status === 'completed') break;
+      if (now() >= deadline) return { action: 'error', reason: 'timeout', runId: String(run.databaseId) };
+      await sleep(pollMs);
+    }
+    const runId = String(run.databaseId);
+
+    // A cancelled run was superseded by a newer one, which reads the label from
+    // the API; re-running a job here would rejoin the Tests concurrency group
+    // and could cancel that newer run.
+    if (run.conclusion === 'cancelled') return { action: 'skip', reason: 'run-cancelled', runId };
+
+    // A run waiting for approval has not executed; there is nothing to re-run.
+    if (run.conclusion === 'action_required') return { action: 'skip', reason: 'run-awaiting-approval', runId };
+
+    const readHead = async () => (await gh(['api', `repos/${repo}/pulls/${prNumber}`, '--jq', '.head.sha'])).trim();
+    if ((await readHead()) !== headSha) return { action: 'skip', reason: 'head-moved', runId };
+
+    const view = JSON.parse(await gh(['run', 'view', runId, '--json', 'jobs']));
+    const jobs = view && Array.isArray(view.jobs) ? view.jobs : [];
+    const job = jobs.find((j) => j && j.name === BASE_HEALTH_JOB_NAME);
+    if (!job) return { action: 'error', reason: 'no-job', runId };
+    const jobId = String(job.databaseId);
+
+    // Second read immediately before the re-run, to shrink the stale-run window.
+    if ((await readHead()) !== headSha) return { action: 'skip', reason: 'head-moved', runId };
+
+    await gh(['run', 'rerun', runId, '--job', jobId]);
+    return { action: 'rerun', reason: 'rerun', runId, jobId };
+  } catch (err) {
+    return { action: 'error', reason: `gh-failed: ${err && err.message ? err.message : String(err)}` };
+  }
+}
+
+function realGh(args) {
+  return new Promise((resolve, reject) => {
+    execFile('gh', args, { timeout: GH_TIMEOUT_MS, maxBuffer: 8 * 1024 * 1024, encoding: 'utf8' }, (err, stdout) => {
+      if (err) reject(err);
+      else resolve(stdout);
+    });
+  });
+}
+
+/**
+ * @param {object} [deps]  test seams: env, gh, now, sleep, stdout, stderr, deadlineMs, pollMs
+ * @returns {Promise<number>} exit code
+ */
+async function main(deps = {}) {
+  const env = deps.env || process.env;
+  const out = deps.stdout || ((s) => process.stdout.write(s));
+  const errOut = deps.stderr || ((s) => process.stderr.write(s));
+
+  const prNumber = (env.PR_NUMBER || '').trim();
+  if (!PR_NUMBER_PATTERN.test(prNumber)) {
+    errOut(`::error::PR_NUMBER must be a positive integer, got ${JSON.stringify(prNumber)}\n`);
+    return 1;
+  }
+  const headSha = (env.HEAD_SHA || '').trim();
+  if (!HEAD_SHA_PATTERN.test(headSha)) {
+    errOut('::error::HEAD_SHA must be a 40-character hex sha\n');
+    return 1;
+  }
+  const repo = (env.GH_REPO || '').trim();
+  if (!/^[\w.-]+\/[\w.-]+$/.test(repo)) {
+    errOut('::error::GH_REPO must be owner/repo\n');
+    return 1;
+  }
+
+  const result = await rerunBaseHealth({
+    gh: deps.gh || realGh,
+    repo,
+    headSha,
+    prNumber,
+    now: deps.now || Date.now,
+    sleep: deps.sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
+    deadlineMs: deps.deadlineMs,
+    pollMs: deps.pollMs,
+  });
+
+  if (result.action === 'error') {
+    errOut(`::error::fix-next re-run failed (${result.reason})${result.runId ? ` on Tests run ${result.runId}` : ''}; re-run "${BASE_HEALTH_JOB_NAME}" by hand.\n`);
+    return 1;
+  }
+  if (result.action === 'skip') {
+    out(`::notice::fix-next re-run skipped (${result.reason}); the newer or upcoming run reads the label from the API.\n`);
+    return 0;
+  }
+  out(`Re-ran "${BASE_HEALTH_JOB_NAME}" (job ${result.jobId}) on Tests run ${result.runId}.\n`);
+  return 0;
+}
+
+if (require.main === module) {
+  runMain(main);
+}
+
+module.exports = {
+  BASE_HEALTH_JOB_NAME,
+  TESTS_WORKFLOW_FILE,
+  DEFAULT_DEADLINE_MS,
+  DEFAULT_POLL_MS,
+  GH_TIMEOUT_MS,
+  rerunBaseHealth,
+  main,
+};

package/scripts/ci-next-health.cjs

@@ -17,7 +17,8 @@
 // with a non-success conclusion for the base branch's last push-triggered Tests
 // run, that is treated as authoritative and blocks — with one explicit, visible,
 // human-operated escape hatch (the `fix-next` label) for the PR that is itself
-// the fix-forward.
+// the fix-forward. On a pull request the label is read from the API (#6076), so
+// after it is added the fix-next-rerun workflow re-runs this check and sees it.
 //
 // Every non-success conclusion (`failure`, `cancelled`, `timed_out`,
 // `action_required`, ...) is treated as RED, not just `failure` — a cancelled or
@@ -205,11 +206,14 @@ async function evaluateQueueBypass({ headRef, baseRef, baseSha, headSha, repo, g
  * (or throwing) — injected so tests never touch the network.
  * `evaluateQueueBypass` (merge_group only) is an async function returning
  * `{authorized, reason, actor}`; it is how a queued fix-forward is recognised.
+ * `fetchPrLabels` (pull_request only, RED base only) is an async function
+ * returning the PR's current label names (or throwing, which keeps the gate
+ * RED with reason `label-read-failed`); when absent, `labels` decides (#6076).
  *
  * @returns {Promise<{verdict:string, payload:*, reason:string}>}
  */
 async function resolveNextHealth({
-  fetchLatestRun, eventName, baseRef, labels, evaluateQueueBypass: queueBypass,
+  fetchLatestRun, eventName, baseRef, labels, fetchPrLabels, evaluateQueueBypass: queueBypass,
 } = {}) {
   if (!APPLICABLE_EVENTS.has(eventName)) {
     return { verdict: VERDICT.SKIPPED_NOT_APPLICABLE, payload: null, reason: 'not-applicable-event' };
@@ -235,10 +239,25 @@ async function resolveNextHealth({
     return { verdict: assessed.verdict, payload: evidence, reason };
   }
 
-  // Escape hatch for the PR that is itself the fix-forward. pull_request runs
-  // read the label from the event (`labels`). merge_group events carry no
-  // labels, so the queue run asks the API instead (evaluateQueueBypass).
-  const labelList = Array.isArray(labels) ? labels : [];
+  // Escape hatch for the PR that is itself the fix-forward. A pull_request run
+  // with `fetchPrLabels` reads the PR's CURRENT labels from the API (#6076), so
+  // a re-run sees a label added or removed after the run started; a failed read
+  // keeps the gate RED. Without it, the event's `labels` decide (bootstrap).
+  // merge_group events carry no labels, so the queue run asks the API instead
+  // (evaluateQueueBypass).
+  let labelList = Array.isArray(labels) ? labels : [];
+  if (eventName === 'pull_request' && typeof fetchPrLabels === 'function') {
+    try {
+      const current = await fetchPrLabels();
+      labelList = Array.isArray(current) ? current : [];
+    } catch (err) {
+      return {
+        verdict: VERDICT.RED,
+        payload: evidence,
+        reason: `${assessed.reason === 'resolved' ? 'red' : assessed.reason}; label-read-failed: ${err.message}`,
+      };
+    }
+  }
   if (labelList.includes(BYPASS_LABEL)) {
     return { verdict: VERDICT.BYPASSED, payload: evidence, reason: 'bypass-label' };
   }
@@ -281,6 +300,9 @@ function usage() {
     'newest settled run decides. Every other case (wrong event, no',
     'resolvable base ref, an unreadable API read) fails open (exit 0).',
     '',
+    'On pull_request with PR_NUMBER set, the label is read from the API, so a',
+    're-run sees the PR\'s current labels (#6076); a failed read keeps the gate RED.',
+    '',
     'On merge_group the label is read back from the API: the queue ref must',
     'name a PR, the group must hold exactly one commit, the PR must carry the',
     'label, and whoever applied it must have write or admin permission.',
@@ -300,7 +322,15 @@ function usage() {
     '  PR_LABELS             comma-separated PR label names (pull_request events;',
     '                        the caller workflow must populate this from',
     '                        github.event.pull_request.labels.*.name); checked',
-    '                        for the literal "fix-next" bypass label',
+    '                        for the literal "fix-next" bypass label; the fallback',
+    '                        when PR_NUMBER is unset or malformed',
+    '  PR_NUMBER             PR number (pull_request events; from',
+    '                        github.event.pull_request.number); trimmed, then it',
+    '                        must match /^[1-9]\\d*$/. When valid, the label is',
+    '                        read from the API so a re-run sees the current',
+    '                        label; a failed read keeps the gate RED. A',
+    '                        malformed value (0, 07, -1, abc, empty) falls back',
+    '                        to PR_LABELS',
     '  MERGE_GROUP_HEAD_REF  merge-group queue branch',
     '                        (github.event.merge_group.head_ref; falls back to',
     '                        GITHUB_REF)',
@@ -437,8 +467,19 @@ async function main(argv = process.argv.slice(2)) {
     ghGet,
   });
 
+  // #6076: with a valid PR number, read the PR's current labels from the API.
+  const prNumber = (process.env.PR_NUMBER || '').trim();
+  const fetchPrLabels = /^[1-9]\d*$/.test(prNumber)
+    ? async () => {
+      const body = await ghGet(`/repos/${repo}/issues/${prNumber}/labels?per_page=100`);
+      return Array.isArray(body)
+        ? body.map((l) => l && l.name).filter((name) => typeof name === 'string')
+        : [];
+    }
+    : undefined;
+
   const result = await resolveNextHealth({
-    fetchLatestRun, eventName, baseRef, labels, evaluateQueueBypass: evaluateQueue,
+    fetchLatestRun, eventName, baseRef, labels, fetchPrLabels, evaluateQueueBypass: evaluateQueue,
   });
 
   writeOutput([`verdict=${result.verdict}`]);
@@ -450,7 +491,9 @@ async function main(argv = process.argv.slice(2)) {
       `::error::the base branch "${baseRef}"'s own last Tests run is red or still re-running after a failure: ${runUrl} (${result.reason}) — `
       + 'wait for a fix-forward merge, or if THIS pull request is the fix, ask a '
       + `maintainer with write access to apply the "${BYPASS_LABEL}" label and re-queue it `
-      + '(the queue run reads the label from the API; it must be the only PR in its merge group).\n',
+      + '(the queue run reads the label from the API; it must be the only PR in its merge group). '
+      + 'On a pull request the label is read from the API too, so after it is added the '
+      + 'fix-next-rerun workflow re-runs this check.\n',
     );
     return 1;
   }

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',