@idea1/cli 1.10.4 → 1.11.1

package/dist/workflow/engine/release-engine.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { logger } from '../../lib/logger.js';
 import { readReleaseSettings } from '../../lib/settings.js';
@@ -6,6 +6,7 @@ import { exec, execOrThrow } from '../../lib/shell.js';
 import { promptConfirm, promptInput } from '../../lib/prompt.js';
 import * as git from '../../services/git.js';
 import * as github from '../../services/github.js';
+import * as platform from '../../services/platform.js';
 export const RELEASE_KIND = {
     commandName: 'idea1 release',
     label: 'Release',
@@ -20,6 +21,13 @@ export const HOTFIX_RELEASE_KIND = {
     gate: 'This PR is the review, approval and release of the hotfix it carries: its assignee reviews it, ' +
         'it must pass the required CI/CD checks, and the merge of this PR is its approval.'
 };
+export const CONTENT_RELEASE_KIND = {
+    commandName: 'idea1 release',
+    label: 'Content release',
+    assigneeReviewsCommits: true,
+    gate: 'This PR is the release of the content it carries: it changes only the content release\'s paths, ' +
+        'it must pass the required checks, and the merge of this PR is its approval - performed by its assignee.'
+};
 export const CHANGE_KIND = {
     commandName: 'idea1 ready-for-approval',
     label: 'Change',
@@ -30,8 +38,9 @@ export const CHANGE_KIND = {
 /**
  * The `--pr-mode` option of `idea1 release`. `create` is the default: the PR is opened and the
  * approver merges it in GitHub once the required checks are green - that merge is the approval of
- * record, exactly as in `merge` mode, where the CLI turns on GitHub's auto-merge on the approver's
- * behalf (or, where GitHub can't auto-merge, waits for the checks and merges here).
+ * record. In `merge` mode the CLI waits for the checks and has the Idea1 platform merge the PR as
+ * the approver's recorded approval, exactly as `idea1 release --approve` does. A content release is
+ * always merged the second way.
  */
 export const PR_MODE_OPTION = {
     longName: 'pr-mode',
@@ -41,7 +50,7 @@ export const PR_MODE_OPTION = {
     promptWhenDefaultExists: true,
     choices: [
         { label: 'create - Create the PR and open it in the browser; merge it there once the required checks pass', value: 'create' },
-        { label: 'merge - Enable auto-merge so GitHub merges once the required checks pass (or wait for the checks with gh and merge here)', value: 'merge' }
+        { label: 'merge - Wait for the required checks, then have Idea1 merge the PR as your recorded approval', value: 'merge' }
     ]
 };
 /** The first line of the comment that records an admin override; the evidence script keys on it. */
@@ -70,6 +79,17 @@ export const CHANGE_APPROVAL_COMMENT_MARKER = '**Change-management approval: cha
 const UNRECORDED_APPROVER = '_unrecorded (merged by a GitHub App)_';
 /** The heading of the approval chain in a gated PR's body, which both the CLI and the platform write. */
 const APPROVAL_CHAIN_HEADING = '## Approval chain';
+/**
+ * The markers around the approval chain section of a gated PR's body, which both the CLI and the
+ * platform write: `<!-- approval-chain:start head=<sha> -->` before the heading and
+ * `<!-- approval-chain:end -->` after the last line. The section is rendered from the branch and
+ * re-rendered while the PR is open, replacing only what lies between the markers, so the rest of
+ * the body - its opening line and anything a person adds - stays as it is. `head` is the source
+ * branch's tip the section was rendered at.
+ */
+const APPROVAL_CHAIN_START_MARKER = '<!-- approval-chain:start';
+const APPROVAL_CHAIN_END_MARKER = '<!-- approval-chain:end -->';
+const RENDERED_HEAD_PATTERN = /<!-- approval-chain:start head=([0-9a-f]{40}) -->/;
 /**
  * The local checkout must be the source branch, clean, fully pushed and level with origin, so the
  * PR carries exactly what the person running the command is looking at.
@@ -113,8 +133,6 @@ export async function validateSourceBranch(sourceBranch) {
     logger.newline();
 }
 export const VERSION_BUMP_TYPES = ['patch', 'minor', 'major'];
-/** The subject prefix of the commit a version bump makes, which both the CLI and the platform write. */
-const VERSION_BUMP_SUBJECT_PREFIX = 'chore: bump ';
 /** The tree of `path` at `origin/<branch>`, or null when the branch has no such path. */
 async function readRemoteTreeSha(branch, path) {
     const result = await exec('git', ['rev-parse', '--verify', '--quiet', `origin/${branch}:${path}`]);
@@ -223,22 +241,18 @@ function setVersion(json, path, entryKey, version) {
     return edited;
 }
 /**
- * Move one package to `version` in the working tree: its `package.json`, and each lockfile at or
- * above its folder that records it. Returns the repo-relative paths of the files that changed.
+ * Move one package to `version` in `files`, the version files' content as edited so far (read from
+ * the checkout when not yet edited): its `package.json`, and each lockfile at or above its folder
+ * that records it.
  *
  * A lockfile in the package's own folder records the package as its root; a workspace root's
  * lockfile records it as the entry for its path relative to the lockfile. These are the files
  * `npm version` would touch, edited in place so nothing else in them changes.
  */
-function writeVersionFiles(repoRoot, pkg, version) {
-    const changed = [];
+function editVersionFiles(repoRoot, files, pkg, version) {
     const edit = (path, entryKeys) => {
-        const original = readFileSync(join(repoRoot, path), 'utf-8');
-        const content = entryKeys.reduce((current, entryKey) => setVersion(current, path, entryKey, version) ?? current, original);
-        if (content !== original) {
-            writeFileSync(join(repoRoot, path), content);
-            changed.push(path);
-        }
+        const original = files.get(path) ?? readFileSync(join(repoRoot, path), 'utf-8');
+        files.set(path, entryKeys.reduce((current, entryKey) => setVersion(current, path, entryKey, version) ?? current, original));
     };
     edit(`${pkg.path}/package.json`, [null]);
     for (const directory of ancestorDirectories(pkg.path)) {
@@ -248,7 +262,6 @@ function writeVersionFiles(repoRoot, pkg, version) {
             edit(lockfile, relativePath === '' ? [null, ''] : [relativePath]);
         }
     }
-    return changed;
 }
 /** A folder and each folder above it, ending with the repository root (the empty path). */
 function ancestorDirectories(directory) {
@@ -267,9 +280,11 @@ function versionFilePaths(packages) {
     return new Set(packages.flatMap(pkg => [`${pkg.path}/package.json`, ...ancestorDirectories(pkg.path).map(lockfilePath)]));
 }
 /**
- * Bump the versions of the pending packages in one commit on the release branch and push it, so
- * the release PR opens against a branch that already carries them. The commit is `chore: bump
- * <package> <version>, ...` and is made as whoever runs the command.
+ * Bump the versions of the pending packages in one commit on the release branch, so the release PR
+ * opens against a branch that already carries them. The bump is computed from the checkout, which is
+ * level with origin, and the Idea1 platform commits it onto the branch as the Idea1 GitHub App -
+ * `chore: bump <package> <version>, ...`, naming the releaser - only while the branch is still at the
+ * checkout's tip. The checkout is then fast-forwarded to the bump.
  */
 export async function commitVersionBumps(options) {
     const { releaseBranch, pending, bumps } = options;
@@ -278,17 +293,19 @@ export async function commitVersionBumps(options) {
     if (missing.length > 0) {
         throw new Error(`Choose a version bump for: ${missing.join(', ')}.`);
     }
-    const changedFiles = [];
-    const summary = [];
+    const files = new Map();
     for (const pkg of pending) {
-        const version = nextVersion(pkg.currentVersion, bumps[pkg.name]);
-        changedFiles.push(...writeVersionFiles(repoRoot, pkg, version));
-        summary.push(`${pkg.name} ${version}`);
-    }
-    logger.status(`Committing the version bump to ${releaseBranch} (${summary.join(', ')})...`);
-    await execOrThrow('git', ['add', '--', ...changedFiles]);
-    await execOrThrow('git', ['commit', '-m', `${VERSION_BUMP_SUBJECT_PREFIX}${summary.join(', ')}`]);
-    await git.pushToRemote(releaseBranch);
+        editVersionFiles(repoRoot, files, pkg, nextVersion(pkg.currentVersion, bumps[pkg.name]));
+    }
+    const changed = [...files.entries()]
+        .filter(([path, content]) => content !== readFileSync(join(repoRoot, path), 'utf-8'))
+        .map(([path, content]) => ({ path, content }));
+    const head = (await execOrThrow('git', ['rev-parse', 'HEAD'])).trim();
+    await platform.commitVersionBump(await git.getRepositoryFullName(), releaseBranch, head, changed);
+    await git.fetchRemoteBranch(releaseBranch);
+    if (await git.fastForwardCheckoutToOrigin(releaseBranch, repoRoot) !== 'fast-forwarded') {
+        throw new Error(`The version bump is on origin/${releaseBranch}, but this checkout could not be fast-forwarded to it. Pull ${releaseBranch} before going on.`);
+    }
     logger.success('Versions bumped');
 }
 /**
@@ -335,18 +352,26 @@ async function changesOnlyVersionFiles(commit, versionFiles) {
     const changedFiles = result.stdout.split('\n').filter(file => file.trim().length > 0);
     return result.exitCode === 0 && changedFiles.length > 0 && changedFiles.every(file => versionFiles.has(file));
 }
+/** A commit abbreviated as the approval chain and the direct-push record list it. */
+const shortSha = (sha) => sha.slice(0, 9);
 /**
  * The refusal of a planned release that carries direct pushes, and the one way past it. A change
  * reaches a planned release through its own approved PR; a commit pushed straight to the branch
  * instead is released only when a repository admin - the production root tier, the only accounts
  * able to push past the branch's pull request requirement - confirms it and records why, and the
  * reason goes on the release PR (change-management-policy.md, "Pull requests and direct pushes").
+ * `prIsOpen` says whether the release PR already exists: a direct push that lands while it is open
+ * needs its reason recorded on it before it can merge.
  */
-async function resolveDirectPushes(commits, sourceBranch, targetBranch, kind) {
-    const refusal = `Refusing to open the ${kind.label.toLowerCase()} PR: ${commits.length} commit(s) on origin/${sourceBranch} ` +
-        `beyond origin/${targetBranch} reached ${sourceBranch} without a pull request. A change reaches a release ` +
-        'through its own approved PR; a direct push is released only with its reason recorded on the release PR ' +
-        'by a repository admin (change-management-policy.md, "Pull requests and direct pushes").';
+async function resolveDirectPushes(commits, sourceBranch, targetBranch, kind, prIsOpen) {
+    const label = kind.label.toLowerCase();
+    const commitsWithNoPr = `${commits.length} commit(s) on origin/${sourceBranch} beyond origin/${targetBranch} ` +
+        `reached ${sourceBranch} without a pull request`;
+    const lead = prIsOpen
+        ? `The ${label} PR records no reason for ${commitsWithNoPr}.`
+        : `Refusing to open the ${label} PR: ${commitsWithNoPr}.`;
+    const refusal = lead + ' A change reaches a release through its own approved PR; a direct push is released only ' +
+        'with its reason recorded on the release PR by a repository admin (change-management-policy.md, "Pull requests and direct pushes").';
     if (!(await github.getRepoAccess()).admin) {
         throw new Error(refusal + '\n\nYou are not a repository admin, so you cannot record the reason.');
     }
@@ -355,7 +380,7 @@ async function resolveDirectPushes(commits, sourceBranch, targetBranch, kind) {
     logger.newline();
     logger.warning('The commits with no pull request are:');
     for (const commit of commits) {
-        logger.dim(`  ${commit.sha.slice(0, 9)}  ${commit.author}  ${commit.subject}`);
+        logger.dim(`  ${shortSha(commit.sha)}  ${commit.author}  ${commit.subject}`);
     }
     logger.newline();
     const proceed = await promptConfirm('Release them anyway, recording on the PR why they were pushed directly?', { default: false });
@@ -382,12 +407,36 @@ function buildDirectPushesComment(kind, record) {
         'Commits with no pull request:',
         '',
         '```',
-        ...record.commits.map(commit => `${commit.sha.slice(0, 9)}  ${commit.author}  ${commit.subject}`),
+        ...record.commits.map(commit => `${shortSha(commit.sha)}  ${commit.author}  ${commit.subject}`),
         '```',
         '',
         `Recorded automatically by \`${kind.commandName}\` for the quarterly review.`
     ].join('\n');
 }
+/**
+ * The direct-push records on a PR, read from its comments. Each names the person who posted it -
+ * the GitHub login on the comment, not any name written in it - with the reason and the commits it
+ * covers. Only a repository admin, the production root tier, records why commits were pushed
+ * directly (change-management-policy.md, "Pull requests and direct pushes"), so a record posted by
+ * anyone else is left out; each author's permission is read once. The platform's `ReleaseEngine`
+ * reads the same records the same way.
+ */
+async function readDirectPushRecords(comments) {
+    const records = comments.filter(comment => comment.body.startsWith(DIRECT_PUSHES_COMMENT_MARKER));
+    const admins = new Set();
+    for (const author of new Set(records.map(comment => comment.author))) {
+        if (await github.isRepoAdmin(author)) {
+            admins.add(author);
+        }
+    }
+    return records
+        .filter(comment => admins.has(comment.author))
+        .map(comment => ({
+        recordedBy: comment.author,
+        reason: (/^Reason given: (.*)$/m.exec(comment.body)?.[1] ?? '').trim(),
+        shortShas: [...comment.body.matchAll(/^([0-9a-f]{9}) {2}/gm)].map(match => match[1])
+    }));
+}
 /**
  * The GitHub App a login belongs to, or null for a person. `gh`'s GraphQL fields name an app
  * `app/<slug>`; the REST API names it `<slug>[bot]`.
@@ -422,20 +471,30 @@ async function resolveApprover(record) {
     return approvals.at(-1) ?? null;
 }
 /**
- * The PR body, written as the approval record for everything the PR carries.
+ * The approval chain of everything the PR carries, rendered from the source branch as origin last
+ * showed it.
  *
  * SOC2 change management asks who approved a change and when. Each change on the source branch
  * was already approved by its assignee, who merged its PR into that branch. Listing those merges
- * here makes this PR self-contained evidence: the whole chain is readable from the one PR an
+ * here makes the PR self-contained evidence: the whole chain is readable from the one PR an
  * auditor lands on. Commits are attributed to PRs through GitHub's own association, so squash and
  * rebase merges are covered, and a commit with no PR is shown rather than silently dropped.
+ *
+ * `recorded` holds the direct-push records already on the PR, or is null before the PR exists. A
+ * direct push no record covers is refused, or released with its reason, as `resolveDirectPushes`
+ * decides; the record that returns is posted on the PR once the body is written. The section's
+ * start marker records the source branch's tip it was rendered at.
  */
-export async function buildApprovalChain(sourceBranch, targetBranch, kind) {
+async function renderApprovalChain(sourceBranch, targetBranch, kind, recorded) {
     const commits = await listFirstParentCommits(sourceBranch, targetBranch);
     if (commits.length === 0) {
         throw new Error(`Nothing to ${kind.label.toLowerCase()}: origin/${targetBranch} already contains everything on origin/${sourceBranch}.`);
     }
-    const versionFiles = versionFilePaths((await readReleaseSettings(await git.getRepoRoot())).versionedPackages);
+    const releaseSettings = await readReleaseSettings(await git.getRepoRoot());
+    const versionFiles = versionFilePaths(releaseSettings.versionedPackages);
+    // Whose review a commit with no PR gets: the release PR's assignee, when the kind of PR or the
+    // repository's release branch policy lets such a commit in, else a repository admin, who records why.
+    const assigneeReviewsDirectCommits = kind.assigneeReviewsCommits || releaseSettings.releaseBranchChanges === 'direct-allowed';
     logger.step(`Attributing ${commits.length} commit(s) on ${sourceBranch} to their pull requests...`);
     const prNumbers = new Set();
     const versionBumps = [];
@@ -456,15 +515,22 @@ export async function buildApprovalChain(sourceBranch, targetBranch, kind) {
         unapprovedCommits.push(commit);
     }
     // A version bump is release automation, so it is never refused. A change PR or a hotfix release
-    // is never refused over direct commits either: they are what its assignee reviews.
-    const directPushRecord = !kind.assigneeReviewsCommits && unapprovedCommits.length > 0
-        ? await resolveDirectPushes(unapprovedCommits, sourceBranch, targetBranch, kind)
+    // is never refused over direct commits either: they are what its assignee reviews. Nor is a
+    // release of a repository that accepts direct changes on its release branch (`direct-allowed`).
+    const unapprovedShas = new Set(unapprovedCommits.map(commit => shortSha(commit.sha)));
+    const recordedReasons = (recorded ?? []).filter(record => record.shortShas.some(sha => unapprovedShas.has(sha)));
+    const recordedShas = new Set(recordedReasons.flatMap(record => record.shortShas));
+    const unrecordedCommits = unapprovedCommits.filter(commit => !recordedShas.has(shortSha(commit.sha)));
+    const directPushRecord = !assigneeReviewsDirectCommits && unrecordedCommits.length > 0
+        ? await resolveDirectPushes(unrecordedCommits, sourceBranch, targetBranch, kind, recorded !== null)
         : null;
+    const reasons = directPushRecord
+        ? [...recordedReasons, { recordedBy: directPushRecord.recordedBy, reason: directPushRecord.reason, shortShas: [] }]
+        : recordedReasons;
     const records = new Map((await github.listMergedPrsInto(sourceBranch)).map(record => [record.number, record]));
     const sortedNumbers = [...prNumbers].sort((a, b) => a - b);
     const lines = [
-        `${kind.label} from \`${sourceBranch}\` into \`${targetBranch}\`, created by \`${kind.commandName}\`.`,
-        '',
+        `${APPROVAL_CHAIN_START_MARKER} head=${commits[0].sha} -->`,
         APPROVAL_CHAIN_HEADING,
         ''
     ];
@@ -515,37 +581,132 @@ export async function buildApprovalChain(sourceBranch, targetBranch, kind) {
         lines.push('| Commit | Author | Subject |');
         lines.push('|---|---|---|');
         for (const commit of versionBumps) {
-            lines.push(`| ${commit.sha.slice(0, 9)} | ${escapeTableCell(commit.author)} | ${escapeTableCell(commit.subject)} |`);
+            lines.push(`| ${shortSha(commit.sha)} | ${escapeTableCell(commit.author)} | ${escapeTableCell(commit.subject)} |`);
         }
     }
     if (unapprovedCommits.length > 0) {
         lines.push('');
-        if (directPushRecord) {
-            // The reason goes in the body as well as the comment, so it can never end up missing from the
-            // PR if the comment fails to post.
+        if (!assigneeReviewsDirectCommits) {
+            // The reasons go in the body as well as the comments, so they can never end up missing from
+            // the PR if a comment fails to post.
             lines.push('## Direct commits (no pull request)');
             lines.push('');
             lines.push(`The commits below were pushed straight to \`${sourceBranch}\`, with no pull request of their own; this PR is`);
             lines.push('their approval. change-management-policy.md, "Pull requests and direct pushes", permits this for the');
             lines.push('production root access tier with the reason recorded on the release PR.');
-            lines.push('');
-            lines.push(`> **Reason recorded by @${directPushRecord.recordedBy}:** ${escapeTableCell(directPushRecord.reason)}`);
+            for (const record of reasons) {
+                lines.push('');
+                lines.push(`> **Reason recorded by @${record.recordedBy}:** ${escapeTableCell(record.reason)}`);
+            }
         }
         else {
             lines.push(`## Commits in this ${kind.label.toLowerCase()}`);
             lines.push('');
             lines.push(`The commits below were pushed to \`${sourceBranch}\`. They are the change this PR asks its assignee to`);
-            lines.push('review and approve by merging it, so they are not an exception under change-management-policy.md,');
-            lines.push('"Pull requests and direct pushes" - this PR is their approval.');
+            if (kind.assigneeReviewsCommits) {
+                lines.push('review and approve by merging it, so they are not an exception under change-management-policy.md,');
+                lines.push('"Pull requests and direct pushes" - this PR is their approval.');
+            }
+            else {
+                lines.push(`review and approve by merging it: this repository accepts changes made directly on \`${sourceBranch}\``);
+                lines.push('(`release.releaseBranchChanges` is `direct-allowed`), so this PR is their approval.');
+            }
         }
         lines.push('');
         lines.push('| Commit | Author | Subject |');
         lines.push('|---|---|---|');
         for (const commit of unapprovedCommits) {
-            lines.push(`| ${commit.sha.slice(0, 9)} | ${escapeTableCell(commit.author)} | ${escapeTableCell(commit.subject)} |`);
+            lines.push(`| ${shortSha(commit.sha)} | ${escapeTableCell(commit.author)} | ${escapeTableCell(commit.subject)} |`);
+        }
+    }
+    lines.push('', APPROVAL_CHAIN_END_MARKER);
+    return {
+        intro: `${kind.label} from \`${sourceBranch}\` into \`${targetBranch}\`, created by \`${kind.commandName}\`.`,
+        section: lines.join('\n'),
+        directPushRecord
+    };
+}
+/**
+ * The body of a new gated PR, written as the approval record for everything the PR carries: its
+ * opening line, then the approval chain section. A direct push it carries with no recorded reason
+ * is refused unless a repository admin records why; that record is returned for posting on the PR.
+ */
+export async function buildApprovalChain(sourceBranch, targetBranch, kind) {
+    const chain = await renderApprovalChain(sourceBranch, targetBranch, kind, null);
+    return { body: `${chain.intro}\n\n${chain.section}`, directPushRecord: chain.directPushRecord };
+}
+/**
+ * The body with its approval chain section replaced by `section`, and everything outside it as it
+ * was. The section lies between its markers; in a body written before the markers existed, it runs
+ * from the approval chain heading to the end of the body, all of which the release wrote.
+ */
+function replaceApprovalChainSection(body, section) {
+    const start = body.indexOf(APPROVAL_CHAIN_START_MARKER);
+    const end = start < 0 ? -1 : body.indexOf(APPROVAL_CHAIN_END_MARKER, start);
+    if (end >= 0) {
+        return body.slice(0, start) + section + body.slice(end + APPROVAL_CHAIN_END_MARKER.length);
+    }
+    return body.slice(0, Math.max(body.indexOf(APPROVAL_CHAIN_HEADING), 0)) + section;
+}
+/** The source branch's tip the body's approval chain section was rendered at, or null when it does not say. */
+function readRenderedHead(body) {
+    return RENDERED_HEAD_PATTERN.exec(body)?.[1] ?? null;
+}
+/**
+ * Re-render the approval chain section of an open gated PR from the source branch as it stands on
+ * origin now, and write it to the PR when it differs; the rest of the body stays as it is. Returns
+ * whether the body changed. The direct pushes already recorded on the PR stay accounted for; one
+ * that landed with no recorded reason is resolved as when the PR was opened - a repository admin
+ * records why, on the PR - or refused.
+ */
+export async function refreshApprovalChain(pr, sourceBranch, targetBranch, kind) {
+    await git.fetchLatest();
+    const recorded = await readDirectPushRecords(await github.listPrComments(pr.number));
+    const chain = await renderApprovalChain(sourceBranch, targetBranch, kind, recorded);
+    const body = replaceApprovalChainSection(pr.body, chain.section);
+    if (body !== pr.body) {
+        await github.updatePrBody(pr.url, body);
+    }
+    if (chain.directPushRecord) {
+        logger.step('Recording why the release carries direct pushes on the PR...');
+        await github.addPrComment(sourceBranch, buildDirectPushesComment(kind, chain.directPushRecord));
+        logger.success('Reason recorded on the PR');
+    }
+    return body !== pr.body;
+}
+/**
+ * Bring the open PR's change list up to date before anything merges it: the release PR lists every
+ * change it contains (change-management-policy.md, "Approval and release gates"), and a change
+ * merged into the source branch after the PR was opened ships inside it. When the re-render fails,
+ * the merge goes ahead only if the branch is still at the tip the body's list was rendered at, so
+ * the list it shows is complete; otherwise nothing is merged.
+ */
+async function ensureChangeListCurrent(sourceBranch, targetBranch, kind) {
+    const pr = await github.getOpenPr(sourceBranch, targetBranch);
+    if (!pr) {
+        throw new Error(`There is no open ${kind.label.toLowerCase()} PR from ${sourceBranch} into ${targetBranch}.`);
+    }
+    logger.step(`Bringing the change list of PR #${pr.number} up to date...`);
+    try {
+        if (await refreshApprovalChain(pr, sourceBranch, targetBranch, kind)) {
+            logger.success('Change list updated with what the branch carries now');
         }
+        else {
+            logger.success('The change list already lists everything the branch carries');
+        }
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        const renderedAt = readRenderedHead(pr.body);
+        const tip = await github.getRemoteBranchTip(sourceBranch);
+        if (renderedAt === null || renderedAt !== tip) {
+            throw new Error(`Refusing to merge PR #${pr.number}: ${sourceBranch} moved since its change list was written, and the list could ` +
+                'not be brought up to date, so the PR would merge changes it does not list (change-management-policy.md, ' +
+                `"Approval and release gates").\n\n${reason}`);
+        }
+        logger.warning(`Could not bring the change list of PR #${pr.number} up to date (${reason}). ${sourceBranch} has not moved ` +
+            'since the list was written, so it still lists every change the PR carries.');
     }
-    return { body: lines.join('\n'), directPushRecord };
 }
 /**
  * Open the PR with its approval-chain body and its approver as assignee. Returns the PR URL.
@@ -570,33 +731,48 @@ export async function createGatedPr(options) {
     return prUrl;
 }
 /**
- * The PR's assignee is its approver of record, and GitHub records whoever merges as `merged_by`.
- * The two must be the same person for the record to name the right approver: no assignee means
- * no approver, and a different merger is an exception the evidence report calls out - so it
- * takes an explicit, eyes-open confirmation.
+ * The signed-in Idea1 user's linked GitHub login: the identity the platform records an approval
+ * under, checks against a PR's assignees and checks a release role for.
  */
-export async function confirmApproverIdentity(branchName) {
-    const assignees = await github.getPrAssignees(branchName);
-    if (assignees.length === 0) {
-        throw new Error('This PR has no assignee, so it has no approver of record. Assign one first - the assignee is who ' +
-            'approves the change by merging it (change-management-policy.md, "Approval and release gates"). For a work-item PR run ' +
-            'idea1 ready-for-approval --assignee <teammate email>; otherwise set the assignee on the PR in GitHub.');
+export async function signedInGitHubLogin() {
+    const signedIn = await platform.getSignedInUser();
+    const login = (await platform.resolveTeammate(signedIn.emailAddress)).gitHubUsername;
+    if (!login) {
+        throw new Error(`Link your GitHub account in Idea1 first: an approval is recorded under it, so ${signedIn.emailAddress} cannot approve without one.`);
     }
-    const login = await github.getCurrentLogin();
-    const names = assignees.map(assignee => `@${assignee}`).join(', ');
-    if (assignees.includes(login)) {
-        logger.info(`Assigned to ${names} - you are the approver of record`);
+    return login;
+}
+/**
+ * Refuse `login` a release role they lack: only the members of `team`, a GitHub team of the
+ * repository's organization named by `setting` in `.idea1/settings.json`, may `action`. A repository
+ * that names no team for the role leaves it to anyone the release workflow admits. The platform
+ * checks the same role again before it merges or commits anything.
+ */
+export async function requireReleaseRole(team, setting, login, action) {
+    if (team === null) {
         return;
     }
-    logger.newline();
-    logger.warning(`This PR is assigned to ${names}, but you are @${login}.`);
-    logger.warning('The merge record will name YOU as the approver, not the assignee, and the evidence');
-    logger.warning('report lists that merge as an exception (change-management-policy.md, "Approval and release gates").');
-    logger.newline();
-    const proceed = await promptConfirm(`Merge anyway as @${login}, knowing ${names} is the named approver and is not the one approving?`, { default: false });
-    if (!proceed) {
-        throw new Error(`Merge cancelled: reassign the PR to @${login}, or have ${names} run the merge.`);
+    const organization = (await git.getRepositoryFullName()).split('/')[0];
+    if (!await github.isTeamMember(team, login)) {
+        throw new Error(`Only members of the GitHub team @${organization}/${team} (${setting} in .idea1/settings.json) may ${action}, and @${login} is not one.`);
+    }
+    logger.info(`@${login} is a member of @${organization}/${team}`);
+}
+/**
+ * Refuse a release by anyone outside the release role for its kind: `release.releaserTeam` for a
+ * planned or hotfix release, `release.contentRelease.releaserTeam` for a content release. Returns
+ * the releaser's linked GitHub login.
+ */
+export async function requireReleaser(kind, sourceBranch) {
+    const login = await signedInGitHubLogin();
+    const settings = await readReleaseSettings(await git.getRepoRoot());
+    if (kind === CONTENT_RELEASE_KIND) {
+        await requireReleaseRole(settings.contentRelease?.releaserTeam ?? null, 'release.contentRelease.releaserTeam', login, `release '${sourceBranch}'`);
+    }
+    else {
+        await requireReleaseRole(settings.releaserTeam, 'release.releaserTeam', login, `make a ${kind.label.toLowerCase()}`);
     }
+    return login;
 }
 function buildOverrideComment(kind, reason, checkSummary) {
     return [
@@ -618,19 +794,19 @@ function buildOverrideComment(kind, reason, checkSummary) {
     ].join('\n');
 }
 /**
- * Merge the PR once the required checks pass. Checks that fail, never start or never finish stop
- * the merge; a repository with no CI/CD configured has nothing to wait for and merges straight
- * away. The one sanctioned admin override remains: it needs an explicit confirmation, a stated
- * reason, and the exception must be recorded as a comment on the PR *before* the merge - if the
- * comment cannot be posted, nothing is merged.
+ * Merge the release PR once the required checks pass: the Idea1 platform records the releaser's
+ * approval on the PR and merges it as the Idea1 GitHub App, after the PR's change list is brought up
+ * to date with what landed on the branch while the checks ran. Checks that fail, never start or
+ * never finish stop the merge; a repository with no CI/CD configured has nothing to wait for. The one
+ * sanctioned admin override remains, merged here as the admin: it needs an explicit confirmation, a
+ * stated reason, and the exception must be recorded as a comment on the PR *before* the merge - if
+ * the comment cannot be posted, nothing is merged.
  */
-export async function mergeWithCheckGate(branchName, kind) {
+export async function mergeWithCheckGate(branchName, targetBranch, kind) {
     const checks = await github.waitForPrChecks(branchName);
     if (checks.passed) {
-        const result = await github.mergePr(branchName);
-        if (!result.success) {
-            throw new Error(`Failed to merge PR: ${result.error}`);
-        }
+        await ensureChangeListCurrent(branchName, targetBranch, kind);
+        await platform.approveRelease(await git.getRepositoryFullName(), branchName);
         return;
     }
     logger.newline();
@@ -644,6 +820,7 @@ export async function mergeWithCheckGate(branchName, kind) {
     const reason = (await promptInput('Reason for the override (required - recorded on the PR):', {
         validate: input => input.trim() ? true : 'A reason is required for an admin override'
     })).trim();
+    await ensureChangeListCurrent(branchName, targetBranch, kind);
     logger.step('Recording the exception on the PR...');
     await github.addPrComment(branchName, buildOverrideComment(kind, reason, checks.summary));
     const result = await github.mergePrWithAdminOverride(branchName);
@@ -652,33 +829,6 @@ export async function mergeWithCheckGate(branchName, kind) {
     }
     logger.success('Exception recorded on the PR');
 }
-/**
- * GitHub's answers to an auto-merge request that mean auto-merge is not the way to merge this PR:
- * it is already mergeable (nothing left to gate on), the repository doesn't allow auto-merge, or
- * the base branch has no protection for auto-merge to wait on.
- */
-const AUTO_MERGE_UNAVAILABLE = /\b(clean|unstable) status\b|auto.?merge is not allowed|protected branch rules not configured/i;
-/**
- * Merge the PR the way that records the person running this as `merged_by`, without them having to
- * wait: GitHub's auto-merge, which merges once the required checks pass. Where GitHub can't
- * auto-merge (the PR is already mergeable, or the repository doesn't allow auto-merge), it falls
- * back to waiting for the checks here and merging (`mergeWithCheckGate`, with its admin-override
- * path). Any other refusal throws.
- */
-export async function enableAutoMergeOrPoll(branchName, kind) {
-    const result = await github.enablePrAutoMerge(branchName);
-    if (result.success) {
-        logger.success('Auto-merge enabled: GitHub merges the PR once the required checks pass, recording you as the merger.');
-        return 'auto-merge-enabled';
-    }
-    const error = result.error ?? '';
-    if (!AUTO_MERGE_UNAVAILABLE.test(error)) {
-        throw new Error(`Could not enable auto-merge on the PR for ${branchName}: ${error}`);
-    }
-    logger.dim(`GitHub can't auto-merge this PR (${error.split('\n')[0]}) - waiting for the checks and merging here instead.`);
-    await mergeWithCheckGate(branchName, kind);
-    return 'merged';
-}
 /**
  * Open URL in browser (cross-platform)
  */
@@ -706,13 +856,20 @@ async function openGitHubActions() {
 /**
  * Finish the sequence in the chosen mode. Either way the merge is the approval of record: in
  * `create` mode the approver performs it in GitHub once the checks are green; in `merge` mode the
- * CLI turns on GitHub's auto-merge as the approver, so GitHub merges once the checks pass and
- * records the approver as the merger - or, where GitHub can't auto-merge, waits for the checks and
- * merges here.
+ * CLI waits for the checks and the Idea1 platform merges it as the approver's recorded approval. A
+ * content release is merged only the second way, since its releaser cannot merge into the release
+ * target in GitHub, so `create` mode leaves it for `idea1 release --approve`.
  */
 export async function runPrMode(options) {
     const { mode, sourceBranch, targetBranch, prUrl, kind } = options;
     const noun = `${kind.label.toLowerCase()} PR`;
+    if (mode === 'create' && kind === CONTENT_RELEASE_KIND) {
+        logger.success('================================================');
+        logger.success(`${kind.label} PR created`);
+        logger.success('================================================');
+        logger.hint(`Once its required checks pass, run idea1 release --branch ${sourceBranch} --approve: Idea1 records your approval and merges it.`);
+        return;
+    }
     if (mode === 'create') {
         logger.step('Opening PR in browser...');
         await exec('gh', ['pr', 'view', sourceBranch, '--web']);
@@ -723,25 +880,18 @@ export async function runPrMode(options) {
         logger.hint(`Merge it in GitHub once the required checks pass - that merge is the ${kind.label.toLowerCase()} approval of record.`);
         return;
     }
-    await confirmApproverIdentity(sourceBranch);
     const confirmMerge = options.confirmed || await promptConfirm(`Merge ${noun} (${sourceBranch} -> ${targetBranch}) once the required checks pass?`, { default: true });
     if (!confirmMerge) {
-        logger.info(`Merge cancelled. The ${noun} is created and can be merged from GitHub instead.`);
+        logger.info(`Merge cancelled. The ${noun} is created; approve it with idea1 release --branch ${sourceBranch} --approve.`);
         logger.hint(`PR: ${prUrl}`);
         return;
     }
-    const outcome = await enableAutoMergeOrPoll(sourceBranch, kind);
+    await ensureChangeListCurrent(sourceBranch, targetBranch, kind);
+    await mergeWithCheckGate(sourceBranch, targetBranch, kind);
     logger.newline();
-    await reportMergeOutcome(outcome, kind, targetBranch, prUrl, options.openActionsAfterMerge);
+    await reportMerged(kind, targetBranch, options.openActionsAfterMerge);
 }
-async function reportMergeOutcome(outcome, kind, targetBranch, prUrl, openActionsAfterMerge) {
-    if (outcome === 'auto-merge-enabled') {
-        logger.success('================================================');
-        logger.success(`${kind.label} PR will merge to ${targetBranch} once the required checks pass`);
-        logger.success('================================================');
-        logger.hint(`Follow it on the PR: ${prUrl}`);
-        return;
-    }
+async function reportMerged(kind, targetBranch, openActionsAfterMerge) {
     if (openActionsAfterMerge) {
         await openGitHubActions();
         logger.newline();
@@ -751,10 +901,9 @@ async function reportMergeOutcome(outcome, kind, targetBranch, prUrl, openAction
     logger.success('========================================');
 }
 /**
- * Why the person running the command cannot release, or null when they can. A release pushes its
- * version bump to the release branch and opens and merges the release PR, all as that person, so
- * they need push access to the repository. The platform's `ReleaseEngine` checks its GitHub App's
- * permissions the same way.
+ * Why the person running the command cannot release, or null when they can. A release opens its PR
+ * and records direct-push and override reasons on it as that person, so they need push access to the
+ * repository. The platform's `ReleaseEngine` checks its GitHub App's permissions the same way.
  */
 async function getMissingPermissionsMessage() {
     const access = await github.getRepoAccess();
@@ -806,12 +955,14 @@ export async function ensureReleasable(sourceBranch, targetBranch) {
     throw new Error(`A release PR is already open: ${pr.url}. Run idea1 release --approve to approve it.`);
 }
 /**
- * `idea1 release --approve`: approve and merge the open release PR from the source branch into the
- * target, as its approver. Only a PR that follows the release workflow is approved, and only by one
- * of its assignees, its approvers of record, exactly as the Idea1 web app approves it. With every
- * check passed it merges now; with checks still running it turns on auto-merge (or waits and merges
- * where GitHub can't auto-merge); with a failed check it goes to the gate's admin-override path,
- * which refuses unless the override is confirmed, reasoned and recorded.
+ * `idea1 release --approve`: approve the open release PR from the source branch into the target, as
+ * its approver, and have the Idea1 platform merge it. Only a PR that follows the release workflow is
+ * approved, and only by one of its assignees, its approvers of record, who holds the release role for
+ * its kind of release - the platform checks both again. The CLI waits for the required checks, and
+ * the platform records the approval on the PR and merges it as the Idea1 GitHub App; with a failed
+ * check it goes to the gate's admin-override path, which refuses unless the override is confirmed,
+ * reasoned and recorded. Before any of that, the PR's change list is brought up to date with what
+ * landed on the branch since it was opened.
  */
 export async function approveRelease(sourceBranch, targetBranch, kind) {
     const missingPermissions = await getMissingPermissionsMessage();
@@ -827,33 +978,17 @@ export async function approveRelease(sourceBranch, targetBranch, kind) {
     if (violation) {
         throw new Error(violation);
     }
-    const login = await github.getCurrentLogin();
+    const login = await signedInGitHubLogin();
     const assignees = pr.assignees.map(assignee => `@${assignee}`).join(', ');
     if (!pr.assignees.some(assignee => assignee.toLowerCase() === login.toLowerCase())) {
         throw new Error(`The release PR is assigned to ${assignees}, its approver(s) of record, not @${login}. ` +
             'Reassign it in GitHub, or have the assignee approve it.');
     }
     logger.info(`Assigned to ${assignees} - you are the approver of record`);
-    const checkState = await github.getPrCheckState(sourceBranch);
-    logger.info(`Checks: ${checkState}`);
-    let outcome;
-    if (checkState === 'passed') {
-        const result = await github.mergePr(sourceBranch);
-        if (!result.success) {
-            throw new Error(`Failed to merge PR: ${result.error}`);
-        }
-        outcome = 'merged';
-    }
-    else if (checkState === 'pending') {
-        outcome = await enableAutoMergeOrPoll(sourceBranch, kind);
-    }
-    else {
-        // Failed checks reach the gate's admin-override path; checks not reported yet are waited for
-        // there, and a repository with no CI/CD at all merges straight through it.
-        await mergeWithCheckGate(sourceBranch, kind);
-        outcome = 'merged';
-    }
+    await requireReleaser(kind, sourceBranch);
+    await ensureChangeListCurrent(sourceBranch, targetBranch, kind);
+    await mergeWithCheckGate(sourceBranch, targetBranch, kind);
     logger.newline();
-    await reportMergeOutcome(outcome, kind, targetBranch, pr.url, true);
+    await reportMerged(kind, targetBranch, true);
 }
 //# sourceMappingURL=release-engine.js.map