@opengsd/gsd-core 1.19.0 → 1.20.1

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

@@ -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
@@ -29,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);
@@ -52,7 +62,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}'`);
@@ -63,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 });
@@ -100,11 +122,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 +171,4 @@ if (require.main === module) {
   }
 }
 
-module.exports = { isReleaseVersion, versionFromPackageJson, applyVersion, syncViaPr, main };
+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/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.19.0",
+  "version": "1.20.1",
   "publisher": "opengsd",
   "engines": {
     "vscode": "^1.105.0"