diff --git a/docs/releasing.md b/docs/releasing.md index 9c1c18f4..46eb4650 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -63,45 +63,43 @@ If the commit or version changes, the job stops and must be started again. A GitHub Actions success alone from an unchecked run is a dry-run, not evidence of npm publication. -## Single-maintainer exception — v1.15.6 only +## Single-maintainer release -A project with one authorized repository maintainer may release **v1.15.6 only** -without inventing a second GitHub reviewer, but this is **not** an implicit -override of CI or governance approvals: +While Kucell is the sole collaborator with write access, the maintainer uses +the single-maintainer release path after the required CI checks pass. +GitHub Actions checks the collaborator list before publication. 1. The canonical private governance `/release` Decision must be genuinely `approved`, `resolved_by=interactive-user`, `workflow_gate=user`, `type=approval`, selected option **`approve-single-maintainer`**, and `options` must explicitly include that option. Its `rationale` must mention - `single-maintainer` and `v1.15.6`. + `single-maintainer` and the exact package version, for example `v1.16.0`. 2. A matching `released` Waitpoint must be released by `/release` with `workflow_gate=owner`. Both records must bind to the **actual current main** - using `release:cortex-agent@`; prior 1.15.0 release records are invalid - for this candidate. -3. The release-preparation PR must really have merged, modify only reviewed - metadata/verification paths, and its merge SHA must be an ancestor of current - main. It need not equal current main when later safe fixes landed. Any - `CHANGES_REQUESTED` review blocks the waiver. + using `release:cortex-agent@`. +3. The release-preparation PR must modify only the allowed release paths and + its merge SHA must match current main. For the transition to this policy, + v1.16.0 may use [PR #190](https://github.com/Kucell/cortex-agent/pull/190) + at its pinned merge commit `9cdf6ae9978dad96de1594465a0010d3dbf0a02d` + when that commit is an ancestor of the authorized main commit. A + `CHANGES_REQUESTED` review blocks the single-maintainer path. 4. The release-workflow preflight, exact-head tests, packaging, npm/tag collision checks and effect-time authority checks remain mandatory. - This exception does not change GitHub permissions, npm Trusted Publishing - or the Auto Release opt-in variable. -5. Future versions require independent reviewer approval unless a separately - reviewed policy explicitly extends this exception. A chat message or PR - comment does not create authoritative Decision/Waitpoint records. + GitHub permissions, npm Trusted Publishing and the Auto Release opt-in + variable continue to apply. -The existing independent-review path remains the default when selected option -is `approve`. **Do not falsify an APPROVED GitHub Review to activate this mode.** +When more collaborators have write access, use the independent-review path +with the Decision option `approve`. ## Approval-driven release - **Automatic preflight:** `.github/workflows/npm-release-preflight.yml` runs after version-file changes land on `main`. This workflow has read-only permissions, runs architecture/contract tests and `npm pack --dry-run`, and never publishes. - **Publish trigger:** the owner dispatches `npm-release.yml` from `main` with `publish=true` and the governance inputs listed above. Publication always runs under the `workflow_dispatch` event, because npm Trusted Publishing rejects OIDC tokens minted for `issue_comment` runs. - **Credential prerequisite:** configure a read-only credential in secret `CORTEX_GOVERNANCE_READ_TOKEN` capable of reading the private `Kucell/cortex-agent-agent` Decision/Waitpoint files. Prefer a short-lived GitHub App installation token; do not use npm tokens or put credentials in versioned files. -- The release gate must verify the exact main commit, actual merged release-preparation PR (matching main or an ancestor in the explicitly approved v1.15.6 single-maintainer mode), accepted file scope, private interactive-user-approved Decision and owner-released Waitpoint for the exact main, and current package version. An ordinary approval requires a distinct write-authorized reviewer; the explicit v1.15.6 `approve-single-maintainer` mode waives only this reviewer identity requirement. Active `CHANGES_REQUESTED` is never waived. +- The release gate verifies the exact main commit, the merged release-preparation PR, allowed file scope, current package version, a private interactive-user-approved Decision and an owner-released Waitpoint. With the `approve` option, a distinct reviewer with write access must approve the exact PR head. With `approve-single-maintainer`, GitHub must report Kucell as the sole collaborator with write access. - **Input format:** `release_pr` is the merged release-preparation PR number, `expected_sha` is the exact current `main` SHA, and `decision_id` / `waitpoint_id` are the IDs created by the authoritative `/release` owner after the exact-commit dry-run / approval process. Do not confuse a GitHub PR comment with the authoritative Cortex Decision/Waitpoint itself. - Failure to verify anything (including unavailable private governance credential) blocks publication; no fallback to simulated approvals or `--force`. -- Publisher remains `npm-release.yml` with npm Trusted Publishing/OIDC. Publication uses `release_type=current`, `dist_tag=latest` and the existing validations/retry logic. **Manual dispatch is the only publication path; `publish=true` is not an authorization bypass.** It requires the same live private Decision + released Waitpoint, independent write-authorized review, and exact-head verification. +- The owner dispatches `npm-release.yml` with `release_type=current`, `dist_tag=latest` and `publish=true`. npm Trusted Publishing uses the resulting OIDC identity. The workflow verifies the live private Decision and released Waitpoint, the exact source commit, and the applicable review path above. **Important:** A pull request that adds this automation cannot activate the trigger until it is separately reviewed and merged. The publish path is owner-dispatched and fail-closed; do not weaken the gate without a separately reviewed policy. diff --git a/scripts/release/verify-approved-release.cjs b/scripts/release/verify-approved-release.cjs index 06fd943d..d97c07d3 100644 --- a/scripts/release/verify-approved-release.cjs +++ b/scripts/release/verify-approved-release.cjs @@ -9,14 +9,13 @@ const MATCH = /^\/cortex-release publish v(\d+\.\d+\.\d+) decision=(D-[A-Za-z0-9 // the changelog and the consistency test that guards the carrier versions. const { carrierFiles } = require(path.join(__dirname, "..", "..", "lib", "release", "version-carriers")); const ALLOWED = new Set([...carrierFiles(), "pnpm-lock.yaml", "CHANGELOG.md", "tests/release/release-version-consistency.test.js"]); -// The single-maintainer exception is bound to one exact release version. The -// binding lives in a single constant because it used to be hardcoded twice — -// once in the command check and once in the Decision-rationale pattern — and -// the two must name the same version or the waiver becomes unusable. -const SINGLE_MAINTAINER_EXCEPTION_VERSION = "1.15.6"; -const SINGLE_MAINTAINER_EXCEPTION_VERSION_RE = new RegExp( - SINGLE_MAINTAINER_EXCEPTION_VERSION.replace(/\./g, "\\."), -); +// Metadata for 1.16.0 was merged before the single-maintainer policy. +// Later releases must use a metadata PR merged at the current main commit. +const SINGLE_MAINTAINER_TRANSITION = Object.freeze({ + version: "1.16.0", + number: 190, + mergeSha: "9cdf6ae9978dad96de1594465a0010d3dbf0a02d", +}); function must(ok, reason) { if (!ok) throw new Error("RELEASE_GATE_BLOCKED: " + reason); } function parseCommand(body) { const m = String(body || "").trim().match(MATCH); @@ -42,9 +41,12 @@ function hasIndependentApproval(pr, reviews, eligibleReviewers = null) { (eligibleReviewers === null || eligibleReviewers.has(r.user.login.toLowerCase())) && r.commit_id === pr.head.sha); } -function validateGovernance(decision, waitpoint, sha, now=new Date()) { +function validateGovernance(decision, waitpoint, sha, now=new Date(), version) { const target = "release:cortex-agent@" + sha; const waiver = decision.selected_option === "approve-single-maintainer"; + const rationaleVersion = /^\d+\.\d+\.\d+$/.test(version) + ? new RegExp("\\bv" + version.replace(/\./g, "\\.") + "(?![\\w+-]|\\.\\d)") + : null; must(decision.type === "approval" && decision.status === "approved" && (decision.selected_option === "approve" || waiver) && (!waiver || ( @@ -52,7 +54,7 @@ function validateGovernance(decision, waitpoint, sha, now=new Date()) { decision.options.includes("approve-single-maintainer") && typeof decision.rationale === "string" && /single-maintainer/i.test(decision.rationale) && - SINGLE_MAINTAINER_EXCEPTION_VERSION_RE.test(decision.rationale) + rationaleVersion && rationaleVersion.test(decision.rationale) )) && decision.resolved_by === "interactive-user" && decision.workflow_gate === "user" && decision.resolved_at && Number.isFinite(Date.parse(decision.resolved_at)) && @@ -143,19 +145,29 @@ async function verifyApproval({event,eventName="issue_comment",actor="Kucell",re const decision = decode(await getJson(base+"/decisions/"+command.decision+".json?ref=main",governanceToken,http)); const waitpoint = decode(await getJson(base+"/waitpoints/"+command.waitpoint+".json?ref=main",governanceToken,http)); must(decision.decision_id === command.decision && waitpoint.waitpoint_id === command.waitpoint,"governance ID mismatch"); - validateGovernance(decision,waitpoint,mainSha,now); + validateGovernance(decision,waitpoint,mainSha,now,command.version); const waiver = decision.selected_option === "approve-single-maintainer"; if (waiver) { - must(command.version === SINGLE_MAINTAINER_EXCEPTION_VERSION, - "single-maintainer exception limited to v" + SINGLE_MAINTAINER_EXCEPTION_VERSION); - // A reviewed metadata PR can precede later main commits. The actual release - // approval still binds to the newest exact main SHA (not the stale PR SHA). - const comparison = await getJson(api+"/compare/"+ - encodeURIComponent(pr.merge_commit_sha)+"..."+encodeURIComponent(mainSha),repoToken,http); - must(["ahead","identical"].includes(comparison.status) && comparison.behind_by === 0, - "approved release PR is not an ancestor of current main"); + const collaborators = await getJson(api+"/collaborators?per_page=100",repoToken,http); + must(Array.isArray(collaborators) && collaborators.length < 100 && + collaborators.every(row=>row && typeof row.login === "string" && + row.permissions && typeof row.permissions.push === "boolean"), + "complete collaborator evidence required for single-maintainer release"); + const writers = collaborators.filter(row=>row.permissions.push); + must(writers.length === 1 && writers[0].login === actor, + "single-maintainer release requires the repository owner to be the sole writer"); + if (pr.merge_commit_sha !== mainSha) { + must(command.version === SINGLE_MAINTAINER_TRANSITION.version && + pr.number === SINGLE_MAINTAINER_TRANSITION.number && + pr.merge_commit_sha === SINGLE_MAINTAINER_TRANSITION.mergeSha, + "release preparation PR merge SHA differs from current main"); + const comparison = await getJson(api+"/compare/"+ + encodeURIComponent(pr.merge_commit_sha)+"..."+encodeURIComponent(mainSha),repoToken,http); + must(["ahead","identical"].includes(comparison.status) && comparison.behind_by === 0, + "approved release PR is not an ancestor of current main"); + } must(!reviews.some(r=>r.state === "CHANGES_REQUESTED"), - "unresolved PR change request forbids review waiver"); + "PR change request blocks single-maintainer release"); } else { must(pr.merge_commit_sha === mainSha, "release PR merge digest differs from current HEAD"); must(hasIndependentApproval(pr,reviews,eligible), @@ -174,4 +186,4 @@ async function main() { console.log("Governed release gate verified exact HEAD "+result.sha+" from merged PR #"+result.pr); } if (require.main === module) main().catch(e=>{console.error(e.message);process.exitCode=1;}); -module.exports = {parseCommand,hasIndependentApproval,validateGovernance,resolveReleaseTrigger,verifyApproval,ALLOWED,SINGLE_MAINTAINER_EXCEPTION_VERSION}; +module.exports = {parseCommand,hasIndependentApproval,validateGovernance,resolveReleaseTrigger,verifyApproval,ALLOWED}; diff --git a/tests/release/verify-approved-release.test.js b/tests/release/verify-approved-release.test.js index 158149cb..08528a53 100644 --- a/tests/release/verify-approved-release.test.js +++ b/tests/release/verify-approved-release.test.js @@ -1,7 +1,7 @@ "use strict"; const test = require("node:test"); const assert = require("node:assert/strict"); -const { parseCommand, hasIndependentApproval, validateGovernance, verifyApproval, SINGLE_MAINTAINER_EXCEPTION_VERSION } = require("../../scripts/release/verify-approved-release.cjs"); +const { parseCommand, hasIndependentApproval, validateGovernance, verifyApproval } = require("../../scripts/release/verify-approved-release.cjs"); const sha = "a".repeat(40); const decision = {decision_id:"D-release-1",type:"approval",status:"approved",selected_option:"approve",resolved_by:"interactive-user",workflow_gate:"user",resolved_at:"2026-10-09T06:00:00Z",gate:{action:"release",resource_ref:"release:cortex-agent@"+sha}}; const waitpoint = {waitpoint_id:"WP-release-1",status:"released",decision_id:"D-release-1",released_by:"/release",workflow_gate:"owner",released_at:"2026-10-09T06:05:00Z",gate:{action:"release",resource_ref:"release:cortex-agent@"+sha}}; @@ -118,53 +118,80 @@ test("unknown release event never becomes approval",async()=>{ await assert.rejects(()=>verifyApproval({...opts(),event:manualEvent,eventName:"push"})); }); -test("the single-maintainer exception is bound to exactly one version",()=>{ - assert.equal(SINGLE_MAINTAINER_EXCEPTION_VERSION,"1.15.6"); - // Both the command check and the Decision-rationale pattern read the same - // constant. They used to hardcode the version twice, so the two could drift - // apart and make the waiver silently unusable. - const ok={...decision,selected_option:"approve-single-maintainer", - options:["approve","reject","approve-single-maintainer"], - rationale:"single-maintainer v"+SINGLE_MAINTAINER_EXCEPTION_VERSION}; - assert.equal(validateGovernance(ok,waitpoint,sha),"release:cortex-agent@"+sha); - // A rationale naming any other version is rejected. - assert.throws(()=>validateGovernance({...ok,rationale:"single-maintainer v1.15.5"},waitpoint,sha)); -}); -test("single maintainer release exception is explicit, version-bound and ancestry-checked", async () => { - const waiver = {...decision,selected_option:"approve-single-maintainer", - options:["approve","reject","approve-single-maintainer"], - rationale:"Single-maintainer review waiver for cortex-agent v1.15.6; user approved this exception after CI source audit"}; - assert.equal(validateGovernance(waiver,waitpoint,sha),"release:cortex-agent@"+sha); - const run=await verifyApproval({...opts(),http:uri=>{ - if (uri.includes("/decisions/")) return Promise.resolve(ok(b64(waiver))); - if (uri.includes("/pulls/51/reviews")) return Promise.resolve(ok([])); - return http(uri); - }}); - assert.deepEqual(run,{version:"1.15.6",sha,pr:51,review_mode:"single-maintainer"}); - await assert.rejects(()=>verifyApproval({...opts(),http:uri=>{ - if (uri.includes("/decisions/")) return Promise.resolve(ok(b64(waiver))); - if (uri.includes("/pulls/51/reviews")) return Promise.resolve(ok([])); - if (uri.includes("/compare/")) return Promise.resolve(ok({status:"diverged",ahead_by:2,behind_by:1})); - return http(uri); - }}),/not an ancestor/); -}); -test("waiver cannot be implicitly inferred from 'approve' or rationale alone",()=>{ - assert.throws(()=>validateGovernance({...decision,selected_option:"approve-single-maintainer",options:["approve","reject"], - rationale:"single-maintainer v1.15.6"},waitpoint,sha)); - assert.throws(()=>validateGovernance({...decision,selected_option:"approve-single-maintainer",options:["approve","reject","approve-single-maintainer"], - rationale:"v1.15.6"},waitpoint,sha)); - assert.throws(()=>validateGovernance({...decision,selected_option:"approve-single-maintainer",options:["approve","reject","approve-single-maintainer"], - rationale:"single-maintainer but for v1.16.0"},waitpoint,sha)); +const singleMaintainerPr = { + ...pr, + number: 190, + merge_commit_sha: "9cdf6ae9978dad96de1594465a0010d3dbf0a02d", +}; +const singleMaintainerDecision = { + ...decision, + selected_option: "approve-single-maintainer", + options: ["approve", "reject", "approve-single-maintainer"], + rationale: "Single-maintainer review exception for cortex-agent v1.16.0.", +}; +function verifySingleMaintainer({ + releasePr = singleMaintainerPr, + releaseReviews = [], + comparison = {status:"ahead",ahead_by:1,behind_by:0}, + packageVersion = "1.16.0", + releaseDecision = singleMaintainerDecision, + collaborators = [{login:"Kucell",permissions:{push:true}}], +} = {}) { + const prPath = "/pulls/" + releasePr.number; + return verifyApproval({ + ...opts(), + packageVersion, + eventName: "workflow_dispatch", + event: {...manualEvent, inputs:{...manualEvent.inputs, release_pr:String(releasePr.number)}}, + http: uri => { + if (uri.endsWith(prPath)) return Promise.resolve(ok(releasePr)); + if (uri.includes(prPath+"/files")) return http(uri.replace(prPath, "/pulls/51")); + if (uri.includes(prPath+"/reviews")) return Promise.resolve(ok(releaseReviews)); + if (uri.includes("/compare/")) return Promise.resolve(ok(comparison)); + if (uri.includes("/collaborators?")) return Promise.resolve(ok(collaborators)); + if (uri.includes("/decisions/")) return Promise.resolve(ok(b64(releaseDecision))); + return http(uri); + }, + }); +} + +test("single maintainer approval rationale names the exact candidate version",()=>{ + const now = new Date("2026-11-18T06:00:00Z"); + assert.equal(validateGovernance(singleMaintainerDecision,waitpoint,sha,now,"1.16.0"),"release:cortex-agent@"+sha); + for(const version of ["1.16.1","1.16.0-rc.1","1.16.0+test",undefined]) { + assert.throws(()=>validateGovernance(singleMaintainerDecision,waitpoint,sha,now,version),/approved release Decision/); + } + assert.throws(()=>validateGovernance({...singleMaintainerDecision,rationale:"single-maintainer v1.16.0-rc.1"},waitpoint,sha,now,"1.16.0"),/approved release Decision/); +}); +test("the 1.16.0 transition accepts only the pinned ancestor PR", async () => { + const run=await verifySingleMaintainer(); + assert.deepEqual(run,{version:"1.16.0",sha,pr:190,review_mode:"single-maintainer"}); + await assert.rejects(()=>verifySingleMaintainer({comparison:{status:"diverged",ahead_by:2,behind_by:1}}),/not an ancestor/); + await assert.rejects(()=>verifySingleMaintainer({releasePr:{...singleMaintainerPr,number:191}}),/differs from current main/); + await assert.rejects(()=>verifySingleMaintainer({releasePr:{...singleMaintainerPr,merge_commit_sha:"d".repeat(40)}}),/differs from current main/); +}); +test("later single maintainer releases require sole writer and metadata merged at current main", async () => { + const releaseDecision = {...singleMaintainerDecision,rationale:"single-maintainer v1.16.1"}; + const future = {packageVersion:"1.16.1",releasePr:{...pr,number:192},releaseDecision}; + assert.deepEqual(await verifySingleMaintainer(future),{version:"1.16.1",sha,pr:192,review_mode:"single-maintainer"}); + await assert.rejects(()=>verifySingleMaintainer({...future,releasePr:singleMaintainerPr}),/differs from current main/); + await assert.rejects(()=>verifySingleMaintainer({...future,collaborators:[ + {login:"Kucell",permissions:{push:true}}, {login:"other-writer",permissions:{push:true}}, + ]}),/sole writer/); +}); +test("single maintainer permission requires an explicit option and rationale",async()=>{ + await assert.rejects(()=>verifySingleMaintainer({ + releaseDecision:{...singleMaintainerDecision,options:["approve","reject"]}, + }),/approved release Decision/); + await assert.rejects(()=>verifySingleMaintainer({ + releaseDecision:{...singleMaintainerDecision,rationale:"v1.16.0"}, + }),/approved release Decision/); + await assert.rejects(()=>verifySingleMaintainer({ + releaseDecision:{...singleMaintainerDecision,selected_option:"approve"}, + releasePr:{...singleMaintainerPr,merge_commit_sha:sha}, + }),/independent write-authorized/); }); test("waiver does not allow unanswered change-requested reviews",async()=>{ - const waiver = {...decision,selected_option:"approve-single-maintainer", - options:["approve","reject","approve-single-maintainer"], - rationale:"single-maintainer v1.15.6 explicit review exception"}; - await assert.rejects(()=>verifyApproval({...opts(),http:uri=>{ - if (uri.includes("/decisions/")) return Promise.resolve(ok(b64(waiver))); - if (uri.includes("/pulls/51/reviews")) return Promise.resolve(ok([{ - state:"CHANGES_REQUESTED",user:{login:"different-reviewer"},commit_id:pr.head.sha - }])); - return http(uri); - }}),/change request/); + const objection={state:"CHANGES_REQUESTED",user:{login:"different-reviewer"},commit_id:pr.head.sha}; + await assert.rejects(()=>verifySingleMaintainer({releaseReviews:[objection]}),/change request/); });