@opengsd/gsd-core 1.20.0 → 1.20.1

package/scripts/merge-commit-pr.cjs

@@ -0,0 +1,186 @@
+'use strict';
+
+/**
+ * Land one of the release pipeline's history-carrying PRs as a merge commit (#5894).
+ *
+ * Two PRs must keep a parent edge, or main and next stop sharing history and
+ * the next release -> main merge conflicts in every version field:
+ *
+ *   release-merge           release/X.Y.0 | hotfix/X.Y.Z -> main        keeps the v<version> tag in main
+ *   main-to-next-backmerge  chore/backmerge-main-to-next-<sha> -> next  keeps main an ancestor of next
+ *
+ * v1.19.0 broke both (#5729 and #5730 were squash-merged). This script is the
+ * one sanctioned way to merge them, from auto-backmerge.yml, release.yml and a
+ * maintainer's shell alike:
+ *
+ *   1. it merges through `PUT /repos/{repo}/pulls/{n}/merge` with
+ *      merge_method=merge: never the merge queue, which squashes, and not
+ *      `gh pr merge --admin`, which does not honor a ruleset bypass;
+ *   2. the merge is pinned to the head sha it read (`sha=`), so a push after
+ *      the read is refused rather than merged unseen;
+ *   3. afterwards it proves the result: the merge commit has two parents, one
+ *      of them the PR head, and the base branch now contains the PR head.
+ *
+ * Usage: node scripts/merge-commit-pr.cjs <pr-number> [--repo owner/name]
+ * Prints one JSON result line; exits 0 when merged and verified, else 1.
+ */
+
+const { execFileSync } = require('node:child_process');
+const { RELEASE_PIPELINE_PR_KIND, releasePipelinePrKind } = require('./release-pipeline-pr.cjs');
+const { runMain } = require('./lib/cli-exit.cjs');
+
+const MERGE_COMMIT_PR_REASON = Object.freeze({
+  MERGED: 'merged',
+  USAGE: 'usage',
+  PR_UNREADABLE: 'pr-unreadable',
+  NOT_OPEN: 'not-open',
+  NOT_A_HISTORY_PR: 'not-a-history-pr',
+  MERGE_REFUSED: 'merge-refused',
+  NOT_A_MERGE_COMMIT: 'not-a-merge-commit',
+  ANCESTRY_BROKEN: 'ancestry-broken',
+  TAG_NOT_IN_BASE: 'tag-not-in-base',
+  VERIFY_UNREADABLE: 'verify-unreadable',
+});
+
+const HISTORY_KINDS = Object.freeze([
+  RELEASE_PIPELINE_PR_KIND.RELEASE_MERGE,
+  RELEASE_PIPELINE_PR_KIND.MAIN_TO_NEXT_BACKMERGE,
+]);
+
+const PR_NUMBER_RE = /^[1-9][0-9]*$/;
+const REPO_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const GH_TIMEOUT_MS = 30000;
+const GH_MERGE_TIMEOUT_MS = 60000;
+
+/** The release tag a release/hotfix head branch publishes: release/1.20.0 -> v1.20.0. */
+function releaseTagFor(headRef) {
+  const match = /^(?:release|hotfix)\/((?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*))$/.exec(String(headRef || ''));
+  return match ? `v${match[1]}` : null;
+}
+
+/** Parse argv. Returns { prNumber, repo } or { error }. */
+function parseArgs(argv, env = process.env) {
+  let prNumber = null;
+  let repo = env.GITHUB_REPOSITORY || 'open-gsd/gsd-core';
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--repo') {
+      const value = argv[i + 1];
+      if (typeof value !== 'string' || !REPO_RE.test(value)) return { error: '--repo needs owner/name' };
+      repo = value;
+      i += 1;
+    } else if (prNumber === null && PR_NUMBER_RE.test(arg)) {
+      prNumber = Number(arg);
+    } else {
+      return { error: `unexpected argument: ${arg}` };
+    }
+  }
+  if (prNumber === null) return { error: 'usage: merge-commit-pr.cjs <pr-number> [--repo owner/name]' };
+  if (!REPO_RE.test(repo)) return { error: `invalid repository: ${repo}` };
+  return { prNumber, repo };
+}
+
+/** Default gh runner: returns stdout; throws on non-zero exit (err.stderr carries gh's text). */
+function defaultGh(args, { timeout = GH_TIMEOUT_MS } = {}) {
+  return execFileSync('gh', args, { encoding: 'utf8', timeout, stdio: ['ignore', 'pipe', 'pipe'] });
+}
+
+function errorText(err) {
+  return String((err && (err.stderr || err.message)) || err).trim();
+}
+
+/**
+ * Merge PR `prNumber` of `repo` with a merge commit and verify the history.
+ * `gh(args, opts)` returns gh's stdout (JSON for `gh api`) and throws on failure.
+ *
+ * @returns {{ ok: boolean, reason: string, kind?: string, mergeSha?: string, detail?: string }}
+ */
+function mergeWithMergeCommit({ prNumber, repo, gh = defaultGh }) {
+  let pr;
+  try {
+    pr = JSON.parse(gh(['api', `repos/${repo}/pulls/${prNumber}`]));
+  } catch (err) {
+    return { ok: false, reason: MERGE_COMMIT_PR_REASON.PR_UNREADABLE, detail: errorText(err) };
+  }
+  if (!pr || pr.state !== 'open' || pr.merged === true) {
+    return { ok: false, reason: MERGE_COMMIT_PR_REASON.NOT_OPEN };
+  }
+  const head = pr.head || {};
+  const base = pr.base || {};
+  const headRepo = head.repo && typeof head.repo.full_name === 'string' ? head.repo.full_name : null;
+  const kind = releasePipelinePrKind({
+    headRef: head.ref,
+    baseRef: base.ref,
+    sameRepo: headRepo !== null && headRepo.toLowerCase() === repo.toLowerCase(),
+  });
+  if (!HISTORY_KINDS.includes(kind)) {
+    return { ok: false, reason: MERGE_COMMIT_PR_REASON.NOT_A_HISTORY_PR, kind: kind || undefined };
+  }
+  const headSha = head.sha;
+
+  let merge;
+  try {
+    merge = JSON.parse(gh(
+      ['api', '-X', 'PUT', `repos/${repo}/pulls/${prNumber}/merge`, '-f', 'merge_method=merge', '-f', `sha=${headSha}`],
+      { timeout: GH_MERGE_TIMEOUT_MS },
+    ));
+  } catch (err) {
+    return { ok: false, reason: MERGE_COMMIT_PR_REASON.MERGE_REFUSED, kind, detail: errorText(err) };
+  }
+  if (!merge || merge.merged !== true || typeof merge.sha !== 'string') {
+    return { ok: false, reason: MERGE_COMMIT_PR_REASON.MERGE_REFUSED, kind, detail: JSON.stringify(merge) };
+  }
+  const mergeSha = merge.sha;
+
+  let commit;
+  let compare;
+  try {
+    commit = JSON.parse(gh(['api', `repos/${repo}/commits/${mergeSha}`]));
+    compare = JSON.parse(gh(['api', `repos/${repo}/compare/${headSha}...${base.ref}`]));
+  } catch (err) {
+    return { ok: false, reason: MERGE_COMMIT_PR_REASON.VERIFY_UNREADABLE, kind, mergeSha, detail: errorText(err) };
+  }
+  const parents = commit && Array.isArray(commit.parents) ? commit.parents.map((p) => p && p.sha) : [];
+  if (parents.length !== 2 || !parents.includes(headSha)) {
+    return { ok: false, reason: MERGE_COMMIT_PR_REASON.NOT_A_MERGE_COMMIT, kind, mergeSha, detail: `parents=${parents.join(',')}` };
+  }
+  if (!compare || compare.behind_by !== 0) {
+    return { ok: false, reason: MERGE_COMMIT_PR_REASON.ANCESTRY_BROKEN, kind, mergeSha, detail: `behind_by=${compare && compare.behind_by}` };
+  }
+  if (kind === RELEASE_PIPELINE_PR_KIND.RELEASE_MERGE) {
+    const tag = releaseTagFor(head.ref);
+    if (tag === null) {
+      return { ok: false, reason: MERGE_COMMIT_PR_REASON.VERIFY_UNREADABLE, kind, mergeSha, detail: 'no release tag for ' + head.ref };
+    }
+    let tagCompare;
+    try {
+      tagCompare = JSON.parse(gh(['api', `repos/${repo}/compare/${tag}...${base.ref}`]));
+    } catch (err) {
+      return { ok: false, reason: MERGE_COMMIT_PR_REASON.VERIFY_UNREADABLE, kind, mergeSha, detail: errorText(err) };
+    }
+    if (!tagCompare || tagCompare.behind_by !== 0) {
+      return { ok: false, reason: MERGE_COMMIT_PR_REASON.TAG_NOT_IN_BASE, kind, mergeSha, detail: `${tag} behind_by=${tagCompare && tagCompare.behind_by}` };
+    }
+  }
+  return { ok: true, reason: MERGE_COMMIT_PR_REASON.MERGED, kind, mergeSha };
+}
+
+function main(argv = process.argv.slice(2), { gh = defaultGh, env = process.env, stdout = process.stdout, stderr = process.stderr } = {}) {
+  const args = parseArgs(argv, env);
+  if (args.error) {
+    stderr.write(`::error::${args.error}\n`);
+    stdout.write(`${JSON.stringify({ ok: false, reason: MERGE_COMMIT_PR_REASON.USAGE })}\n`);
+    return 1;
+  }
+  const result = mergeWithMergeCommit({ prNumber: args.prNumber, repo: args.repo, gh });
+  stdout.write(`${JSON.stringify(result)}\n`);
+  if (!result.ok) {
+    stderr.write(`::error::PR #${args.prNumber} was not landed as a verified merge commit (${result.reason})${result.detail ? `: ${result.detail}` : ''}. `
+      + 'Never put a release or back-merge PR in the merge queue or squash it: main and next must keep sharing history (#5894).\n');
+  }
+  return result.ok ? 0 : 1;
+}
+
+if (require.main === module) runMain(main);
+
+module.exports = { MERGE_COMMIT_PR_REASON, HISTORY_KINDS, GH_TIMEOUT_MS, GH_MERGE_TIMEOUT_MS, releaseTagFor, parseArgs, mergeWithMergeCommit, main };

package/scripts/release-ancestry.cjs

@@ -0,0 +1,86 @@
+'use strict';
+
+/**
+ * Release ancestry check (#5894): `main` must be an ancestor of `next`.
+ *
+ * auto-backmerge.yml keeps that true by landing a merge commit of main into
+ * next after every release. When the back-merge is squashed (#5730), main and
+ * next stop sharing history and the next release -> main merge conflicts in
+ * every version field. release.yml runs this before cutting or finalizing a
+ * release so the break surfaces there, with the fix, instead of as a 91-file
+ * conflict on the merge-back PR.
+ *
+ * Usage: node scripts/release-ancestry.cjs [--ancestor origin/main] [--descendant origin/next]
+ * Exits 0 when the ancestor is reachable from the descendant, else 1.
+ */
+
+const { execFileSync } = require('node:child_process');
+const { runMain } = require('./lib/cli-exit.cjs');
+
+const ANCESTRY_VERDICT = Object.freeze({
+  ANCESTOR: 'ancestor',
+  DIVERGED: 'diverged',
+  UNKNOWN: 'unknown',
+});
+
+const GIT_TIMEOUT_MS = 15000;
+const REF_RE = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/;
+
+/** Default git runner: returns { status } for `git <args>`. */
+function defaultGit(args) {
+  try {
+    execFileSync('git', args, { stdio: 'ignore', timeout: GIT_TIMEOUT_MS });
+    return { status: 0 };
+  } catch (err) {
+    return { status: typeof err.status === 'number' ? err.status : null };
+  }
+}
+
+/**
+ * `git merge-base --is-ancestor` exits 0 (ancestor), 1 (not), or another code
+ * (an error, e.g. an unknown ref). Only 0 and 1 are verdicts; anything else is
+ * UNKNOWN, and the CLI treats UNKNOWN as a failure.
+ */
+function checkAncestry({ ancestor, descendant, git = defaultGit }) {
+  const { status } = git(['merge-base', '--is-ancestor', ancestor, descendant]);
+  if (status === 0) return ANCESTRY_VERDICT.ANCESTOR;
+  if (status === 1) return ANCESTRY_VERDICT.DIVERGED;
+  return ANCESTRY_VERDICT.UNKNOWN;
+}
+
+function parseArgs(argv) {
+  const out = { ancestor: 'origin/main', descendant: 'origin/next' };
+  for (let i = 0; i < argv.length; i += 1) {
+    const flag = argv[i];
+    const value = argv[i + 1];
+    if ((flag === '--ancestor' || flag === '--descendant') && typeof value === 'string' && REF_RE.test(value)) {
+      out[flag.slice(2)] = value;
+      i += 1;
+    } else {
+      return { error: `unexpected argument: ${flag}` };
+    }
+  }
+  return out;
+}
+
+function main(argv = process.argv.slice(2), { git = defaultGit, stdout = process.stdout, stderr = process.stderr } = {}) {
+  const args = parseArgs(argv);
+  if (args.error) {
+    stderr.write(`::error::${args.error}\n`);
+    return 1;
+  }
+  const verdict = checkAncestry({ ancestor: args.ancestor, descendant: args.descendant, git });
+  stdout.write(`${JSON.stringify({ verdict, ancestor: args.ancestor, descendant: args.descendant })}\n`);
+  if (verdict === ANCESTRY_VERDICT.ANCESTOR) return 0;
+  stderr.write(verdict === ANCESTRY_VERDICT.DIVERGED
+    ? `::error::${args.ancestor} is not an ancestor of ${args.descendant}, so the next release -> main merge will conflict (#5894). `
+      + 'Land a back-merge of main into next as a merge commit first: push chore/backmerge-main-to-next-<short sha of main> '
+      + '(next plus `git merge -s ours --no-ff origin/main`), open it against next, and merge it with '
+      + '`node scripts/merge-commit-pr.cjs <PR>` as a repo admin. Never send it through the merge queue.\n'
+    : `::error::could not read the ancestry of ${args.ancestor} and ${args.descendant} (git failed). Fetch both refs and retry.\n`);
+  return 1;
+}
+
+if (require.main === module) runMain(main);
+
+module.exports = { ANCESTRY_VERDICT, GIT_TIMEOUT_MS, checkAncestry, parseArgs, main };

package/scripts/release-pipeline-pr.cjs

@@ -0,0 +1,92 @@
+'use strict';
+
+/**
+ * The release pipeline's own back-merge PRs (#5890).
+ *
+ * The pipeline opens three kinds of PR, and none of them has an issue to link:
+ *
+ *   kind                    head branch                         base   opened by
+ *   release-merge           release/X.Y.0 | hotfix/X.Y.Z (Z>0)  main   release.yml "merge release back to main"
+ *   next-version-sync       chore/sync-next-version-<version>   next   scripts/sync-next-version.cjs
+ *   main-to-next-backmerge  chore/backmerge-main-to-next-<sha>  next   auto-backmerge.yml (#1389)
+ *
+ * Callers, each with its trust model:
+ *
+ *   - scripts/require-issue-link-policy.cjs (`Issue link required`) and
+ *     .github/workflows/pr-title-validator.yml (`validate-title`) run on
+ *     pull_request_target and load this module from a BASE-branch checkout,
+ *     so a PR cannot edit the predicate that judges it.
+ *   - scripts/changeset/lint.cjs (changeset-lint, #5903) runs on pull_request
+ *     and executes PR-tree code, so the base-checkout guarantee does not apply
+ *     (a PR could already edit lint.cjs itself). The fork guard is what blocks
+ *     forgery: sameRepo is derived from the GitHub event payload.
+ *
+ * What each caller exempts:
+ *
+ *   - `Issue link required`: the closing-reference requirement.
+ *   - `validate-title`: only the missing-issue-ref verdict; the title's type
+ *     prefix (`bad-prefix`) is still enforced on these PRs.
+ *   - changeset-lint: the fragment requirement; a malformed fragment or `pr:`
+ *     drift still fails.
+ *
+ * Anti-forgery (#1389): a branch name alone is attacker-chosen — a fork can
+ * name its branch anything. The exemption therefore also requires
+ * `sameRepo === true` (head.repo.full_name == the base repository), which only
+ * someone with push access to this repository can satisfy, and the exact base
+ * branch each kind targets.
+ */
+
+const { isReleaseVersion, SYNC_BRANCH_PREFIX } = require('./sync-next-version.cjs');
+
+const RELEASE_PIPELINE_PR_KIND = Object.freeze({
+  RELEASE_MERGE: 'release-merge',
+  NEXT_VERSION_SYNC: 'next-version-sync',
+  MAIN_TO_NEXT_BACKMERGE: 'main-to-next-backmerge',
+});
+
+// release.yml validate-version: X.Y.0 cuts release/X.Y.0; X.Y.Z with Z>0 cuts
+// hotfix/X.Y.Z. Same no-leading-zero grammar as its `grep -qE` checks.
+const RELEASE_BRANCH_RE = /^release\/(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.0$/;
+const HOTFIX_BRANCH_RE = /^hotfix\/(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.[1-9][0-9]*$/;
+
+// auto-backmerge.yml: BR="chore/backmerge-main-to-next-${SHORT_SHA}" (#1389),
+// SHORT_SHA=$(git rev-parse --short origin/main): 7 to 40 lowercase hex.
+const BACKMERGE_BRANCH_PREFIX = 'chore/backmerge-main-to-next-';
+const BACKMERGE_SHA_RE = /^[0-9a-f]{7,40}$/;
+
+/**
+ * Classify a PR as one of the release pipeline's own PRs.
+ *
+ * @param {{ headRef?: unknown, baseRef?: unknown, sameRepo?: unknown }} [pr]
+ * @returns {string|null} a RELEASE_PIPELINE_PR_KIND value, or null when the PR
+ *   is not a release-pipeline PR (including every fork PR).
+ */
+function releasePipelinePrKind({ headRef, baseRef, sameRepo } = {}) {
+  if (sameRepo !== true) return null;
+  if (typeof headRef !== 'string' || typeof baseRef !== 'string') return null;
+
+  if (baseRef === 'main' && (RELEASE_BRANCH_RE.test(headRef) || HOTFIX_BRANCH_RE.test(headRef))) {
+    return RELEASE_PIPELINE_PR_KIND.RELEASE_MERGE;
+  }
+  if (baseRef === 'next' && headRef.startsWith(SYNC_BRANCH_PREFIX)
+    && isReleaseVersion(headRef.slice(SYNC_BRANCH_PREFIX.length))) {
+    return RELEASE_PIPELINE_PR_KIND.NEXT_VERSION_SYNC;
+  }
+  if (baseRef === 'next' && headRef.startsWith(BACKMERGE_BRANCH_PREFIX)
+    && BACKMERGE_SHA_RE.test(headRef.slice(BACKMERGE_BRANCH_PREFIX.length))) {
+    return RELEASE_PIPELINE_PR_KIND.MAIN_TO_NEXT_BACKMERGE;
+  }
+  return null;
+}
+
+/** True iff the PR is one of the release pipeline's own PRs (see releasePipelinePrKind). */
+function isReleasePipelinePr(pr) {
+  return releasePipelinePrKind(pr) !== null;
+}
+
+module.exports = {
+  RELEASE_PIPELINE_PR_KIND,
+  BACKMERGE_BRANCH_PREFIX,
+  releasePipelinePrKind,
+  isReleasePipelinePr,
+};

package/scripts/require-issue-link-policy.cjs

@@ -37,10 +37,14 @@ const ISSUE_LINK_REASON = Object.freeze({
   FAIL_FILE_LIST_INCOMPLETE: 'fail_file_list_incomplete',
 });
 
-// #1389: backmerge PRs are opened by CI against `next`, never by a human or a
-// fork, so they are exempt from the issue-link requirement outright — but
-// ONLY when combined with `sameRepo === true` below (see header comment).
-const BACKMERGE_BRANCH_PREFIX = 'chore/backmerge-main-to-next-';
+// #1389 / #5890: the release pipeline's own back-merge PRs (release/hotfix ->
+// main, chore/sync-next-version-* and chore/backmerge-main-to-next-* -> next)
+// are opened by CI, never by a human or a fork, and have no issue to link, so
+// they are exempt outright. The predicate lives in release-pipeline-pr.cjs —
+// shared with pr-title-validator.yml so the two gates agree — and requires
+// `sameRepo === true` plus the exact base branch, so a fork cannot forge it
+// by naming its branch.
+const { releasePipelinePrKind, BACKMERGE_BRANCH_PREFIX } = require('./release-pipeline-pr.cjs');
 
 // #4196: Dependabot has no mechanism to link a PR it opens to a repo issue —
 // its alerts live in the Security tab, not as issues, so there is nothing
@@ -135,7 +139,7 @@ function allPathsAreTestsOrDocs(changedFiles) {
   });
 }
 
-function evaluateIssueLink({ prBody, headRef, sameRepo, authorLogin, changedFiles, changedFilesTotal }) {
+function evaluateIssueLink({ prBody, headRef, baseRef, sameRepo, authorLogin, changedFiles, changedFilesTotal }) {
   if (authorLogin === DEPENDABOT_LOGIN) {
     return { ok: true, reason: ISSUE_LINK_REASON.OK_DEPENDABOT_EXEMPT };
   }
@@ -144,10 +148,14 @@ function evaluateIssueLink({ prBody, headRef, sameRepo, authorLogin, changedFile
     return { ok: true, reason: ISSUE_LINK_REASON.OK_CLOSING_KEYWORD };
   }
 
-  // #1389: `sameRepo === true` is required, not just the branch-name prefix —
-  // a fork PR could otherwise name its branch to forge this exemption.
-  if (String(headRef || '').startsWith(BACKMERGE_BRANCH_PREFIX) && sameRepo === true) {
-    return { ok: true, reason: ISSUE_LINK_REASON.OK_BACKMERGE_EXEMPT };
+  // #1389: `sameRepo === true` is required, not just the branch name — a fork
+  // PR could otherwise name its branch to forge this exemption (#5890 adds the
+  // base branch and the release/sync shapes; see release-pipeline-pr.cjs).
+  const releaseKind = releasePipelinePrKind({ headRef, baseRef, sameRepo });
+  if (releaseKind) {
+    // `kind` names which release-pipeline PR this is (the reason keeps its
+    // #1389 name so existing consumers of the enum are unchanged).
+    return { ok: true, reason: ISSUE_LINK_REASON.OK_BACKMERGE_EXEMPT, kind: releaseKind };
   }
 
   if (!hasFollowUpReference(prBody)) {
@@ -175,6 +183,7 @@ function main() {
   const result = evaluateIssueLink({
     prBody: process.env.PR_BODY || '',
     headRef: process.env.HEAD_REF || '',
+    baseRef: process.env.BASE_REF || '',
     sameRepo: process.env.SAME_REPO === 'true',
     authorLogin: process.env.PR_AUTHOR_LOGIN || '',
     changedFiles,

package/scripts/sync-next-version.cjs

@@ -30,6 +30,15 @@ function isReleaseVersion(v) {
   return typeof v === 'string' && RELEASE_VERSION.test(v);
 }
 
+// The branch syncViaPr opens. scripts/release-pipeline-pr.cjs exempts exactly
+// this shape from the issue-link and PR-title gates (#5890).
+const SYNC_BRANCH_PREFIX = 'chore/sync-next-version-';
+
+/** The head branch of the sync PR for `version`. */
+function syncBranchName(version) {
+  return `${SYNC_BRANCH_PREFIX}${version}`;
+}
+
 /** Read the `version` field out of a package.json text blob. Throws on a missing/non-string version. */
 function versionFromPackageJson(text) {
   const parsed = JSON.parse(text);
@@ -76,7 +85,7 @@ function syncViaPr(version, { run = defaultRun } = {}) {
     process.stdout.write(`next already at ${version} — nothing to sync\n`);
     return 'noop';
   }
-  const branch = `chore/sync-next-version-${version}`;
+  const branch = syncBranchName(version);
   run('git', ['checkout', '-B', branch, 'origin/next'], { timeout: 15000 });
   applyVersion(version, { run });
   run('git', ['add', '-u'], { timeout: 15000 });
@@ -162,4 +171,4 @@ if (require.main === module) {
   }
 }
 
-module.exports = { isReleaseVersion, versionFromPackageJson, applyVersion, syncViaPr, main, defaultRun };
+module.exports = { isReleaseVersion, versionFromPackageJson, applyVersion, syncViaPr, main, defaultRun, SYNC_BRANCH_PREFIX, syncBranchName };

package/skills/gsd-new-milestone/SKILL.md

@@ -28,7 +28,7 @@ Brownfield equivalent of new-project. Project exists, PROJECT.md has history. Ga
 - `.planning/ROADMAP.md` — phase structure (continues numbering)
 - `.planning/STATE.md` — reset for new milestone
 
-**After:** `/gsd-plan-phase [N]` to start execution.
+**After:** Run `/gsd-discuss-phase [N]` to clarify the approach (or `/gsd-plan-phase [N]` to plan directly); then `/gsd-execute-phase [N]` to execute.
 </objective>
 
 <execution_context>

package/skills/gsd-new-project/SKILL.md

@@ -36,7 +36,7 @@ Initialize a new project through unified flow: questioning → research (optiona
 - `.planning/ROADMAP.md` — phase structure
 - `.planning/STATE.md` — project memory
 
-**After this command:** Run `/gsd-plan-phase 1` to start execution.
+**After this command:** Run `/gsd-discuss-phase 1` to clarify the approach (or `/gsd-plan-phase 1` to plan directly); then `/gsd-execute-phase 1` to execute.
 </objective>
 
 <execution_context>

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.20.0",
+  "version": "1.20.1",
   "publisher": "opengsd",
   "engines": {
     "vscode": "^1.105.0"