@opengsd/gsd-core 1.18.0 → 1.20.0

package/scripts/reviewed-or-maintainer-policy.cjs

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * "Reviewed or maintainer" policy (#5607).
+ *
+ * A pull request passes when EITHER
+ *   1. its author is listed in .github/MAINTAINERS (a maintainer's own PR needs
+ *      no second reviewer), OR
+ *   2. someone other than the author, holding write/maintain/admin permission,
+ *      has an APPROVED review on the CURRENT head sha as their latest standing
+ *      review.
+ *
+ * Why this is a check and not a ruleset review count: a ruleset's
+ * required_approving_review_count is one number for every author, so it cannot
+ * say "required unless the author is a maintainer". The sole maintainer cannot
+ * approve their own PR, which is what pushed merges onto `--admin` (#4990).
+ *
+ * Everything that could wrongly COUNT an approval fails closed here: a stale
+ * sha, the author's own review, a reviewer without write access, a later
+ * dismissal or change request by the same reviewer, a truncated review list, an
+ * unreadable maintainer file. Wrongly FAILING only asks a maintainer for one
+ * more review.
+ *
+ * This module is pure. The workflow gathers reviews and roles with `gh api` and
+ * hands them in as files; the policy and the maintainer list are read from the
+ * BASE branch, never from the PR (.github/workflows/reviewed-or-maintainer.yml).
+ */
+
+const fs = require('node:fs');
+const { runMain } = require('./lib/cli-exit.cjs');
+
+const REASON = Object.freeze({
+  OK_MAINTAINER_AUTHOR: 'ok_maintainer_author',
+  OK_APPROVED: 'ok_approved',
+  FAIL_NO_APPROVAL: 'fail_no_approval',
+  FAIL_STALE_APPROVAL_ONLY: 'fail_stale_approval_only',
+  FAIL_MAINTAINERS_UNREADABLE: 'fail_maintainers_unreadable',
+  FAIL_REVIEWS_INCOMPLETE: 'fail_reviews_incomplete',
+  FAIL_INPUT_INVALID: 'fail_input_invalid',
+});
+
+// Permission levels allowed to give a qualifying approval. GitHub's
+// `role_name` for collaborators: read, triage, write, maintain, admin.
+const APPROVER_ROLES = new Set(['write', 'maintain', 'admin']);
+
+// A GitHub login: alphanumerics and single hyphens, 1-39 chars, optional
+// `[bot]` suffix. Anything else on a MAINTAINERS line is reported, not trusted.
+const LOGIN_RE = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?(?:\[bot\])?$/;
+const SHA_RE = /^[0-9a-f]{40}$/i;
+
+// Review states that change a reviewer's standing. COMMENTED and PENDING do
+// not: a later comment does not withdraw an approval on GitHub either.
+const STANDING_STATES = new Set(['APPROVED', 'CHANGES_REQUESTED', 'DISMISSED']);
+
+/**
+ * @param {unknown} text - contents of .github/MAINTAINERS
+ * @returns {{ok: boolean, logins: Set<string>, invalid: string[]}}
+ */
+function parseMaintainers(text) {
+  const logins = new Set();
+  const invalid = [];
+  if (typeof text !== 'string') return { ok: false, logins, invalid };
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.replace(/#.*$/, '').trim();
+    if (line === '') continue;
+    if (LOGIN_RE.test(line)) logins.add(line.toLowerCase());
+    else invalid.push(line);
+  }
+  return { ok: logins.size > 0, logins, invalid };
+}
+
+function isBot(entry) {
+  const user = entry && entry.user;
+  return Boolean(user && (user.type === 'Bot' || /\[bot\]$/i.test(String(user.login || ''))));
+}
+
+function lower(value) {
+  return typeof value === 'string' ? value.toLowerCase() : '';
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.authorLogin
+ * @param {Set<string>} input.maintainers - lowercase logins
+ * @param {Array<{user: {login: string}, state: string, commit_id: string}>} input.reviews - chronological
+ * @param {Record<string, string>} input.roles - lowercase login -> permission role name
+ * @param {string} input.headSha - 40 hex
+ * @param {boolean} input.reviewsComplete - false when the review list may be truncated
+ * @returns {{ok: boolean, reason: string}}
+ */
+function evaluateReviewed({ authorLogin, maintainers, reviews, roles, headSha, reviewsComplete }) {
+  if (typeof authorLogin !== 'string' || authorLogin === '') {
+    return { ok: false, reason: REASON.FAIL_INPUT_INVALID };
+  }
+  if (typeof headSha !== 'string' || !SHA_RE.test(headSha)) {
+    return { ok: false, reason: REASON.FAIL_INPUT_INVALID };
+  }
+  if (!(maintainers instanceof Set) || maintainers.size === 0) {
+    return { ok: false, reason: REASON.FAIL_MAINTAINERS_UNREADABLE };
+  }
+
+  const author = lower(authorLogin);
+  if (maintainers.has(author)) return { ok: true, reason: REASON.OK_MAINTAINER_AUTHOR };
+
+  if (!Array.isArray(reviews)) return { ok: false, reason: REASON.FAIL_INPUT_INVALID };
+  if (reviewsComplete !== true) return { ok: false, reason: REASON.FAIL_REVIEWS_INCOMPLETE };
+
+  // Latest standing review per reviewer (input is chronological).
+  const standing = new Map();
+  for (const entry of reviews) {
+    const login = lower(entry && entry.user && entry.user.login);
+    if (login === '' || !STANDING_STATES.has(entry.state)) continue;
+    standing.set(login, entry);
+  }
+
+  let sawStaleApproval = false;
+  for (const [login, entry] of standing) {
+    if (login === author) continue;
+    if (entry.state !== 'APPROVED') continue;
+    // An app or bot (for example github-actions[bot] when Actions may approve
+    // PRs) is not a human review, whatever permission it holds.
+    if (isBot(entry)) continue;
+    const role = roles && typeof roles === 'object' ? roles[login] : undefined;
+    if (!APPROVER_ROLES.has(role)) continue;
+    if (lower(entry.commit_id) === lower(headSha)) return { ok: true, reason: REASON.OK_APPROVED };
+    sawStaleApproval = true;
+  }
+
+  return {
+    ok: false,
+    reason: sawStaleApproval ? REASON.FAIL_STALE_APPROVAL_ONLY : REASON.FAIL_NO_APPROVAL,
+  };
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return undefined;
+  }
+}
+
+function main() {
+  const maintainersText = (() => {
+    try {
+      return fs.readFileSync(process.env.MAINTAINERS_FILE || '.github/MAINTAINERS', 'utf8');
+    } catch {
+      return undefined;
+    }
+  })();
+  const parsed = parseMaintainers(maintainersText);
+  for (const line of parsed.invalid) {
+    process.stderr.write(`::warning::MAINTAINERS: ignored malformed line: ${JSON.stringify(line)}\n`);
+  }
+
+  const reviews = process.env.REVIEWS_FILE ? readJson(process.env.REVIEWS_FILE) : undefined;
+  const roles = process.env.ROLES_FILE ? readJson(process.env.ROLES_FILE) : undefined;
+
+  const result = evaluateReviewed({
+    authorLogin: process.env.PR_AUTHOR_LOGIN || '',
+    maintainers: parsed.ok ? parsed.logins : null,
+    reviews,
+    roles: roles && typeof roles === 'object' ? roles : {},
+    headSha: process.env.HEAD_SHA || '',
+    // The workflow's `gh api --paginate` either returns every page or exits
+    // non-zero before this runs; it states completeness explicitly.
+    reviewsComplete: process.env.REVIEWS_COMPLETE === 'true',
+  });
+
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (process.env.GITHUB_OUTPUT) {
+    fs.appendFileSync(process.env.GITHUB_OUTPUT, `ok=${result.ok ? 'true' : 'false'}\n`);
+    fs.appendFileSync(process.env.GITHUB_OUTPUT, `reason=${result.reason}\n`);
+  }
+  return result.ok ? 0 : 1;
+}
+
+if (require.main === module) runMain(main);
+
+module.exports = { REASON, APPROVER_ROLES, parseMaintainers, evaluateReviewed };

package/scripts/select-docs-guards.cjs

@@ -22,7 +22,7 @@
  */
 
 /**
- * @param {string} changedPath - a single changed docs/ path (e.g. 'docs/AGENTS.md').
+ * @param {string} changedPath - a single changed docs/ path (e.g. 'docs/reference/agents.md').
  * @param {string} pattern - one entry from a registry value array.
  * @returns {boolean}
  */

package/scripts/self-test-report-policy.cjs

@@ -0,0 +1,350 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Self-test report policy (#5612).
+ *
+ * A fix PR from someone who is not a listed maintainer must carry a
+ * `## Self-test report` section holding a fenced `json` block that records what
+ * the submitter ran: a failing-first test (fails on the base, passes on the
+ * head), the commands, the environment, and a passing full suite, bound to the
+ * PR's CURRENT head commit.
+ *
+ * TRUST MODEL. This validates shape and sha binding, not truth. A local run
+ * cannot be attested; CI on the merge-group commit stays authoritative. The
+ * report is a head start for the reviewer and a nudge on effort, nothing more.
+ * Every result here is advisory until a maintainer chooses to require it.
+ *
+ * Pure module: the workflow hands in the PR body, head ref, title, author, head
+ * sha and the maintainer list (read from the BASE sha, never the PR).
+ */
+
+const fs = require('node:fs');
+const { runMain } = require('./lib/cli-exit.cjs');
+const { parseMaintainers } = require('./reviewed-or-maintainer-policy.cjs');
+
+const REASON = Object.freeze({
+  OK_NOT_A_FIX: 'ok_not_a_fix',
+  OK_MAINTAINER_AUTHOR: 'ok_maintainer_author',
+  OK_BOT_AUTHOR: 'ok_bot_author',
+  OK_REPORT: 'ok_report',
+  FAIL_NO_REPORT: 'fail_no_report',
+  FAIL_MALFORMED_JSON: 'fail_malformed_json',
+  FAIL_SCHEMA: 'fail_schema',
+  FAIL_STALE_SHA: 'fail_stale_sha',
+  FAIL_NOT_FAILING_FIRST: 'fail_not_failing_first',
+  FAIL_SUITE_NOT_PASSED: 'fail_suite_not_passed',
+  FAIL_MAINTAINERS_UNREADABLE: 'fail_maintainers_unreadable',
+  FAIL_INPUT_INVALID: 'fail_input_invalid',
+});
+
+const SCHEMA_VERSION = 1;
+const TOOLS = new Set(['gsd-test', 'npm-test', 'manual']);
+const SUITE_RESULTS = new Set(['passed', 'failed', 'skipped']);
+const SHA_RE = /^[0-9a-f]{40}$/i;
+const PLACEHOLDER_RE = /^<[^<>]*>$/;
+const EXCERPT_MAX = 2000;
+const SECTION_TITLE = 'self-test report';
+
+/** A PR is a "fix PR" when its head ref is fix/… or its title is a fix. */
+function isFixPr({ headRef, title }) {
+  if (typeof headRef === 'string' && headRef.startsWith('fix/')) return true;
+  return typeof title === 'string' && /^fix(\([^)]*\))?!?:/i.test(title.trim());
+}
+
+function isBotLogin(login) {
+  return typeof login === 'string' && /\[bot\]$/i.test(login);
+}
+
+/**
+ * Find the first fenced ```json block inside the `## Self-test report` section.
+ *
+ * - Fence-aware: a `#` line inside a fence is not a heading. A fence may carry
+ *   trailing info after the language (```json title="x"); only its first word
+ *   names the language. A closing fence has no info and is at least as long as
+ *   the opener, with the same character.
+ * - HTML comments are skipped outside fences, so a block hidden in a comment
+ *   (invisible in the rendered PR) is not the report.
+ * - The section ends at the next heading of the same or a higher level.
+ * - The first json block wins.
+ *
+ * @returns {{found: boolean, json: string|null}}
+ */
+// Lines longer than this are not fence or heading syntax. Capping what the
+// regexes see keeps a crafted line of whitespace from costing more than a bounded
+// amount of work (the body is attacker-controlled); captured JSON keeps its full text.
+const SYNTAX_LINE_MAX = 1000;
+
+/**
+ * ATX heading → {level, text}, parsed without a backtracking regex: a body line
+ * is attacker input and the obvious `^(#+)\s+(.*?)\s*#*\s*$` is cubic on a long
+ * run of spaces. A trailing run of `#` is a closing sequence only when preceded
+ * by whitespace (or the text is only hashes).
+ */
+function parseHeading(line) {
+  const trimmed = line.trim();
+  let level = 0;
+  while (level < trimmed.length && trimmed[level] === '#') level += 1;
+  if (level < 1 || level > 6) return null;
+  if (level >= trimmed.length || !/\s/.test(trimmed[level])) return null;
+  let text = trimmed.slice(level).trim();
+  let end = text.length;
+  while (end > 0 && text[end - 1] === '#') end -= 1;
+  if (end < text.length && (end === 0 || /\s/.test(text[end - 1]))) text = text.slice(0, end).trimEnd();
+  return { level, text: text.replace(/\*\*/g, '').trim().toLowerCase() };
+}
+
+function extractReport(body) {
+  const lines = String(body || '').split(/\r?\n/);
+  let inFence = false;
+  let fenceChar = '';
+  let fenceLen = 0;
+  let inComment = false;
+  let sectionLevel = 0;
+  let capturing = false;
+  let captured = [];
+
+  for (const full of lines) {
+    const line = full.length > SYNTAX_LINE_MAX ? full.slice(0, SYNTAX_LINE_MAX) : full;
+    if (!inFence) {
+      if (inComment) {
+        if (line.includes('-->')) inComment = false;
+        continue;
+      }
+      const commentAt = line.indexOf('<!--');
+      if (commentAt !== -1 && line.indexOf('-->', commentAt + 4) === -1) {
+        inComment = true;
+        continue;
+      }
+    }
+
+    if (!inFence) {
+      const open = /^\s*(`{3,}|~{3,})\s*([^\s`]*)(?:\s.*)?$/.exec(line);
+      if (open) {
+        if (sectionLevel > 0 && !capturing && open[2].toLowerCase() === 'json') {
+          capturing = true;
+          captured = [];
+        }
+        inFence = true;
+        fenceChar = open[1][0];
+        fenceLen = open[1].length;
+        continue;
+      }
+    } else {
+      const close = /^\s*(`{3,}|~{3,})\s*$/.exec(line);
+      if (close && close[1][0] === fenceChar && close[1].length >= fenceLen) {
+        inFence = false;
+        if (capturing) return { found: true, json: captured.join('\n') };
+        continue;
+      }
+      if (capturing) captured.push(full);
+      continue;
+    }
+
+    const heading = parseHeading(line);
+    if (heading) {
+      if (sectionLevel === 0) {
+        if (heading.text === SECTION_TITLE) sectionLevel = heading.level;
+      } else if (heading.level <= sectionLevel) {
+        return { found: false, json: null };
+      }
+    }
+  }
+  return { found: false, json: null };
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim() !== '';
+}
+
+function isCount(value) {
+  return Number.isInteger(value) && value >= 0;
+}
+
+/** Names of report fields whose string value is still an unfilled `<…>` placeholder. */
+function placeholderFields(report) {
+  const found = [];
+  const check = (name, value) => {
+    if (typeof value === 'string' && PLACEHOLDER_RE.test(value.trim())) found.push(name);
+  };
+  check('head_sha', report.head_sha);
+  check('output_excerpt', report.output_excerpt);
+  if (report.failing_first && typeof report.failing_first === 'object') {
+    check('failing_first.test', report.failing_first.test);
+    check('failing_first.not_applicable_reason', report.failing_first.not_applicable_reason);
+  }
+  if (Array.isArray(report.commands)) report.commands.forEach((c) => check('commands', c));
+  if (report.full_suite && typeof report.full_suite === 'object') check('full_suite.command', report.full_suite.command);
+  if (report.environment && typeof report.environment === 'object') {
+    check('environment.os', report.environment.os);
+    check('environment.node', report.environment.node);
+  }
+  return [...new Set(found)];
+}
+
+/**
+ * @param {unknown} report - parsed JSON
+ * @param {string} headSha
+ * @returns {{ok: boolean, reason: string, problems: string[]}}
+ */
+function validateReport(report, headSha) {
+  const problems = [];
+  const fail = (reason) => ({ ok: false, reason, problems });
+
+  if (!report || typeof report !== 'object' || Array.isArray(report)) {
+    problems.push('the report must be a JSON object');
+    return fail(REASON.FAIL_SCHEMA);
+  }
+  if (report.schema !== SCHEMA_VERSION) problems.push(`schema must be ${SCHEMA_VERSION}`);
+  if (typeof report.head_sha !== 'string' || !SHA_RE.test(report.head_sha)) {
+    problems.push('head_sha must be the 40-hex sha of your final commit');
+  }
+  if (!TOOLS.has(report.tool)) problems.push(`tool must be one of ${[...TOOLS].join(', ')}`);
+
+  const ff = report.failing_first;
+  if (!ff || typeof ff !== 'object' || Array.isArray(ff)) {
+    problems.push('failing_first must be an object');
+  } else if (ff.not_applicable_reason !== undefined) {
+    if (!isNonEmptyString(ff.not_applicable_reason)) {
+      problems.push('failing_first.not_applicable_reason must be a non-empty explanation');
+    }
+  } else {
+    if (!isNonEmptyString(ff.test)) problems.push('failing_first.test must name the test file');
+    if (typeof ff.fails_on_base !== 'boolean') problems.push('failing_first.fails_on_base must be true or false');
+    if (typeof ff.passes_on_head !== 'boolean') problems.push('failing_first.passes_on_head must be true or false');
+  }
+
+  if (!Array.isArray(report.commands) || report.commands.length === 0 || !report.commands.every(isNonEmptyString)) {
+    problems.push('commands must be a non-empty list of the commands you ran');
+  }
+
+  const suite = report.full_suite;
+  if (!suite || typeof suite !== 'object' || Array.isArray(suite)) {
+    problems.push('full_suite must be an object');
+  } else {
+    if (!isNonEmptyString(suite.command)) problems.push('full_suite.command must name the command');
+    if (!SUITE_RESULTS.has(suite.result)) problems.push(`full_suite.result must be one of ${[...SUITE_RESULTS].join(', ')}`);
+    if (!isCount(suite.passed)) problems.push('full_suite.passed must be a non-negative integer');
+    if (!isCount(suite.failed)) problems.push('full_suite.failed must be a non-negative integer');
+  }
+
+  const env = report.environment;
+  if (!env || typeof env !== 'object' || Array.isArray(env) || !isNonEmptyString(env.os) || !isNonEmptyString(env.node)) {
+    problems.push('environment must give os and node');
+  }
+
+  if (!isNonEmptyString(report.output_excerpt) || report.output_excerpt.length > EXCERPT_MAX) {
+    problems.push(`output_excerpt must be a non-empty excerpt of at most ${EXCERPT_MAX} characters`);
+  }
+
+  // A value still in `<…>` is the template, not something the submitter filled in.
+  for (const name of placeholderFields(report)) problems.push(`${name} is still the template placeholder; fill it in`);
+
+  if (problems.length > 0) return fail(REASON.FAIL_SCHEMA);
+
+  // Structurally sound. Now the substantive checks, most informative first.
+  if (report.head_sha.toLowerCase() !== String(headSha).toLowerCase()) {
+    problems.push(`head_sha ${report.head_sha} is not the PR's current head ${headSha}; update the report after your last push`);
+    return fail(REASON.FAIL_STALE_SHA);
+  }
+  if (ff.not_applicable_reason === undefined && !(ff.fails_on_base === true && ff.passes_on_head === true)) {
+    problems.push('the failing-first test must fail on the base and pass on your head');
+    return fail(REASON.FAIL_NOT_FAILING_FIRST);
+  }
+  if (suite.result !== 'passed' || suite.failed !== 0 || suite.passed < 1) {
+    problems.push('the full suite must have passed, with at least one passing test and no failures');
+    return fail(REASON.FAIL_SUITE_NOT_PASSED);
+  }
+  return { ok: true, reason: REASON.OK_REPORT, problems };
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.body
+ * @param {string} input.headRef
+ * @param {string} input.title
+ * @param {string} input.authorLogin
+ * @param {string} input.headSha - 40 hex, read live
+ * @param {Set<string>|null} input.maintainers - lowercase logins
+ * @returns {{ok: boolean, reason: string, problems: string[]}}
+ */
+function evaluateSelfTestReport({ body, headRef, title, authorLogin, headSha, maintainers }) {
+  const none = [];
+  if (typeof authorLogin !== 'string' || authorLogin === '' || typeof headSha !== 'string' || !SHA_RE.test(headSha)) {
+    return { ok: false, reason: REASON.FAIL_INPUT_INVALID, problems: none };
+  }
+  if (!isFixPr({ headRef, title })) return { ok: true, reason: REASON.OK_NOT_A_FIX, problems: none };
+  if (isBotLogin(authorLogin)) return { ok: true, reason: REASON.OK_BOT_AUTHOR, problems: none };
+  if (!(maintainers instanceof Set) || maintainers.size === 0) {
+    return { ok: false, reason: REASON.FAIL_MAINTAINERS_UNREADABLE, problems: none };
+  }
+  if (maintainers.has(authorLogin.toLowerCase())) {
+    return { ok: true, reason: REASON.OK_MAINTAINER_AUTHOR, problems: none };
+  }
+
+  const extracted = extractReport(body);
+  if (!extracted.found) {
+    return { ok: false, reason: REASON.FAIL_NO_REPORT, problems: ['no ```json block under a "## Self-test report" heading'] };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(extracted.json);
+  } catch (error) {
+    return { ok: false, reason: REASON.FAIL_MALFORMED_JSON, problems: [`the report is not valid JSON: ${error.message}`] };
+  }
+  return validateReport(parsed, headSha);
+}
+
+/** A value from the environment, or from the file named by `<NAME>_FILE` (live reads are too big for env). */
+function fromEnvOrFile(name) {
+  const file = process.env[`${name}_FILE`];
+  if (file) {
+    try {
+      return fs.readFileSync(file, 'utf8');
+    } catch {
+      return undefined;
+    }
+  }
+  return process.env[name] || '';
+}
+
+function main() {
+  let maintainersText;
+  try {
+    maintainersText = fs.readFileSync(process.env.MAINTAINERS_FILE || '.github/MAINTAINERS', 'utf8');
+  } catch {
+    maintainersText = undefined;
+  }
+  const parsed = parseMaintainers(maintainersText);
+
+  const body = fromEnvOrFile('PR_BODY');
+  const title = fromEnvOrFile('PR_TITLE');
+
+  const result = body === undefined || title === undefined
+    ? { ok: false, reason: REASON.FAIL_INPUT_INVALID, problems: [] }
+    : evaluateSelfTestReport({
+      body,
+      headRef: process.env.HEAD_REF || '',
+      title,
+      authorLogin: process.env.PR_AUTHOR_LOGIN || '',
+      headSha: process.env.HEAD_SHA || '',
+      maintainers: parsed.ok ? parsed.logins : null,
+    });
+
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  for (const problem of result.problems) {
+    // The annotation text is the validator's own wording plus, for a JSON syntax
+    // error, the parser's message (which can echo attacker text): strip newlines
+    // so no extra workflow command can start a line.
+    process.stderr.write(`::error::Self-test report: ${problem.replace(/[\r\n]+/g, ' ').slice(0, 300)}\n`);
+  }
+  if (process.env.GITHUB_OUTPUT) {
+    fs.appendFileSync(process.env.GITHUB_OUTPUT, `ok=${result.ok ? 'true' : 'false'}\n`);
+    fs.appendFileSync(process.env.GITHUB_OUTPUT, `reason=${result.reason}\n`);
+  }
+  return result.ok ? 0 : 1;
+}
+
+if (require.main === module) runMain(main);
+
+module.exports = { REASON, SCHEMA_VERSION, EXCERPT_MAX, isFixPr, extractReport, validateReport, evaluateSelfTestReport };

package/scripts/sync-next-version.cjs

@@ -9,7 +9,8 @@
  * release type (rc / hotfix / final). See issue #1104.
  *
  * Modes:
- *   default     — open + admin-merge a `chore: sync next version` PR (used by
+ *   default     — open + admin-merge a `chore: sync next version` PR, or enqueue it
+ *                 when the base requires the merge queue (#5746) (used by
  *                 release.yml's rc job, which has no next-targeting PR of its
  *                 own). Idempotent: a no-op when `next` is already at the target.
  *   --in-place  — set the version (+ manifests, via the npm `version` hook) in
@@ -52,7 +53,19 @@ function applyVersion(version, { run = defaultRun } = {}) {
   run('npm', ['version', version, '--no-git-tag-version', '--allow-same-version'], { timeout: 60000 });
 }
 
-/** Full PR-based sync to the `next` branch. Returns 'noop' | 'synced'. */
+// What `gh pr merge --admin` says when the base branch is behind a merge-queue ruleset.
+const MERGE_QUEUE_REJECTION_RE = /merge queue/i;
+
+// stdin ignored, stdout and stderr captured so a failed `gh` call carries its own text.
+const PIPED_STDERR = ['ignore', 'pipe', 'pipe'];
+
+/** Piped stderr is not visible on its own: write it out, then rethrow. */
+function rethrowWithStderr(err) {
+  if (err && err.stderr) process.stderr.write(String(err.stderr));
+  throw err;
+}
+
+/** Full PR-based sync to the `next` branch. Returns 'noop' | 'synced' | 'queued' (enqueued, not yet merged). */
 function syncViaPr(version, { run = defaultRun } = {}) {
   if (!isReleaseVersion(version)) {
     throw new Error(`refusing to sync next to invalid/non-release version '${version}'`);
@@ -100,11 +113,30 @@ function syncViaPr(version, { run = defaultRun } = {}) {
     /* labels are best-effort; admin-merge below still lands the PR */
   }
   try {
-    run('gh', ['pr', 'merge', '--admin', '--merge', prNum], { timeout: 60000 });
+    // stderr is piped, not inherited: with the default 'inherit' the GitHub text goes
+    // to the terminal and err.stderr is null, so the classification below would only
+    // ever see "Command failed: gh pr merge ..." (#5746).
+    run('gh', ['pr', 'merge', '--admin', '--merge', prNum], { timeout: 60000, stdio: PIPED_STDERR });
   } catch (err) {
-    // tolerate "already merged"; rethrow anything else
     const msg = String((err && (err.stderr || err.message)) || '');
-    if (!/already merged|not mergeable|Merged/i.test(msg)) throw err;
+    if (/already merged/i.test(msg)) {
+      // a PR that is already merged must never be enqueued
+    } else if (MERGE_QUEUE_REJECTION_RE.test(msg)) {
+      // #5746: `next` is governed by a merge-queue ruleset, which --admin cannot bypass.
+      // Enqueue instead; the queue chooses the merge strategy, so no --merge here. A
+      // failed enqueue is a real failure: its text is surfaced and it propagates.
+      try {
+        run('gh', ['pr', 'merge', '--auto', prNum], { timeout: 60000, stdio: PIPED_STDERR });
+      } catch (enqueueErr) {
+        rethrowWithStderr(enqueueErr);
+      }
+      process.stdout.write(`queued sync of next -> ${version} via PR #${prNum}\n`);
+      return 'queued';
+    } else if (!/not mergeable|Merged/i.test(msg)) {
+      // the older tolerance, kept after the queue rule so a queue rejection that happens
+      // to mention "mergeable" is not mistaken for success
+      rethrowWithStderr(err);
+    }
   }
   process.stdout.write(`synced next -> ${version} via PR #${prNum}\n`);
   return 'synced';
@@ -130,4 +162,4 @@ if (require.main === module) {
   }
 }
 
-module.exports = { isReleaseVersion, versionFromPackageJson, applyVersion, syncViaPr, main };
+module.exports = { isReleaseVersion, versionFromPackageJson, applyVersion, syncViaPr, main, defaultRun };

package/skills/gsd-update/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: gsd-update
 description: "Update GSD to latest version with changelog display"
-argument-hint: "[--sync | --reapply | --next | --rc]"
+argument-hint: "[--sync | --reapply | --next | --rc] [--interactive=exceptions|all]"
 allowed-tools:
   - Read
   - Write
@@ -36,14 +36,17 @@ Routes to the update workflow which handles:
 <flags>
 - **--sync**: Sync managed GSD skills across runtime roots so multi-runtime users stay aligned after an update. Runs the sync-skills workflow (--from, --to, --dry-run, --apply flags supported).
 - **--reapply**: Reapply local modifications after a GSD update. Uses three-way comparison (pristine baseline, user-modified backup, newly installed version) to merge user customizations back. Runs the reapply-patches workflow.
+  - **--interactive[=exceptions|all]** (with `--reapply` only): show each user edit next to the stock text with a recommended disposition and wait for a keep / retire / rewrite decision per edit. `all` shows every edit; `exceptions` (bare `--interactive`) shows only edits upstream adopted, partly adopted, reworded around, or orphaned, and keeps the rest. Without it, `--reapply` behaves exactly as before.
 - **--next** (alias **--rc**): Target the `@next` RC dist-tag instead of `@latest` so you can install or refresh a release candidate (e.g. `1.4.0-rc.1`) through the normal update flow — scope/runtime detection, changelog preview, custom-file backup, and cache clearing all still apply. Omitting it keeps targeting `@latest` (no change). See ADR #660 for the RC channel.
 - **(no flag)**: Standard update — check for new version, show changelog, install.
 </flags>
 
 <process>
+If the arguments contain `--interactive` (bare or with a value) but not `--reapply`, STOP with: `--interactive applies only to --reapply (for example: /gsd-update --reapply --interactive=all)`. Do nothing else.
+
 Parse the first token of the `<arguments>` block:
 - If it is `--sync`: strip the flag, execute the sync-skills workflow (passing remaining args for --from/--to/--dry-run/--apply).
-- If it is `--reapply`: strip the flag, execute the reapply-patches workflow.
+- If it is `--reapply`: strip the flag, execute the reapply-patches workflow, passing the remaining arguments (for example `--interactive=all`) to it.
 - Otherwise (including `--next` / `--rc`): execute the update workflow end-to-end, passing the `<arguments>` block through so the workflow's parse_update_channel step can select the release channel.
 
 </process>

package/vscode/package.json

@@ -2,7 +2,7 @@
   "name": "gsd-core-vscode",
   "displayName": "GSD Core",
   "description": "GSD orchestration engine embedded in VS Code (ADR-1239 IDE profile).",
-  "version": "1.18.0",
+  "version": "1.20.0",
   "publisher": "opengsd",
   "engines": {
     "vscode": "^1.105.0"