docguard-cli 0.40.0__tar.gz → 0.40.1__tar.gz

{docguard_cli-0.40.0 → docguard_cli-0.40.1}/.agent/skills/docguard-fix/SKILL.md

@@ -6,10 +6,10 @@ description: AI-driven documentation repair with structured research workflow, t
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.40.0
+  version: 0.40.1
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.40.0 -->
+<!-- docguard:version: 0.40.1 -->
 
 # DocGuard Fix Skill
 

{docguard_cli-0.40.0/extensions/spec-kit-docguard → docguard_cli-0.40.1/.agent}/skills/docguard-guard/SKILL.md

@@ -7,10 +7,10 @@ description: Run DocGuard guard validation against Canonical-Driven Development
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.40.0
+  version: 0.40.1
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.40.0 -->
+<!-- docguard:version: 0.40.1 -->
 
 # DocGuard Guard Skill
 

{docguard_cli-0.40.0/extensions/spec-kit-docguard → docguard_cli-0.40.1/.agent}/skills/docguard-review/SKILL.md

@@ -6,10 +6,10 @@ description: Cross-document consistency analysis and quality assessment. Perform
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.40.0
+  version: 0.40.1
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.40.0 -->
+<!-- docguard:version: 0.40.1 -->
 
 # DocGuard Review Skill
 

{docguard_cli-0.40.0/extensions/spec-kit-docguard → docguard_cli-0.40.1/.agent}/skills/docguard-score/SKILL.md

@@ -6,10 +6,10 @@ description: CDD maturity assessment with category-aware improvement roadmap. Ru
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.40.0
+  version: 0.40.1
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.40.0 -->
+<!-- docguard:version: 0.40.1 -->
 
 # DocGuard Score Skill
 

{docguard_cli-0.40.0 → docguard_cli-0.40.1}/.agent/skills/docguard-sync/SKILL.md

@@ -4,10 +4,10 @@ description: Keep canonical documentation ALWAYS UP TO DATE. Refreshes code-trut
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.40.0
+  version: 0.40.1
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
-<!-- docguard:version: 0.40.0 -->
+<!-- docguard:version: 0.40.1 -->
 
 # DocGuard Sync Skill
 

{docguard_cli-0.40.0 → docguard_cli-0.40.1}/.docguard-specs.json

@@ -180,7 +180,7 @@
           },
           {
             "path": "specs/006-document-lifecycle/tasks.md",
-            "digest": "sha256:66a553bdcd7fb5e2d3a21755d1f8ec16a5800450453b4dc188065541cdb3e2ca"
+            "digest": "sha256:a53716e90ad72020860a378a05dddb399bacd7f3126ff53bf98a95d042fcbeed"
           }
         ],
         "taskCompletion": {
@@ -953,7 +953,7 @@
           },
           {
             "path": "specs/009-language-repository-coverage/plan.md",
-            "digest": "sha256:91e9b6a5bf6d6cd63080bfddb3f323a40d9b59d549d77897b6e2484777d3ac82"
+            "digest": "sha256:a843cdac74fd5405e2bc5029d5a710e6b841cc615ab2cb97706d2e67cbe3885e"
           },
           {
             "path": "specs/009-language-repository-coverage/tasks.md",
@@ -1803,7 +1803,7 @@
           },
           {
             "path": "specs/010-task-specific-agent-context/plan.md",
-            "digest": "sha256:cf2e094cde54afc06b316bc2ef252309f66781aa86684d0d7dcf74bd631f48cf"
+            "digest": "sha256:9eae19f760f1ff5a6fffd2d2817b4afb202bedaed03cff291896d8a1faafccc5"
           },
           {
             "path": "specs/010-task-specific-agent-context/tasks.md",
@@ -2004,6 +2004,197 @@
           }
         ]
       }
+    },
+    {
+      "specId": "docguard.tokenless-scheduled-releases",
+      "path": "specs/011-tokenless-scheduled-releases/spec.md",
+      "reviewed": {
+        "lifecycle": {
+          "approval": "approved",
+          "delivery": "verified",
+          "context": "current",
+          "retirementReason": null,
+          "storage": "working_tree",
+          "persistenceModel": "living"
+        },
+        "relations": {
+          "extends": [],
+          "duplicates": [],
+          "conflictsWith": [],
+          "supersedes": [],
+          "supersededBy": []
+        },
+        "scope": {
+          "canonicalDocs": [
+            "docs-canonical/CI-RECIPES.md"
+          ]
+        },
+        "reconciliation": {
+          "lastReviewedRevision": "46531e4918f9479b81ffb52e6e27c24b533575da",
+          "outcomes": [
+            {
+              "revision": "46531e4918f9479b81ffb52e6e27c24b533575da",
+              "reason": "Reviewed tokenless scheduled-release policy, exact-run gates, missing-tag recovery, Node 18/20/22/24 CI, supply-chain scan, live dispatch-chain refusal probe, and durable evidence approval with no accepted deviations.",
+              "evidence": [
+                "cli/release-pr-policy.mjs",
+                "docs-canonical/CI-RECIPES.md",
+                "tests/scheduled-release.test.mjs"
+              ],
+              "deviations": [],
+              "successor": null
+            }
+          ]
+        }
+      },
+      "intent": {
+        "requirements": [
+          "docguard.tokenless-scheduled-releases#FR-001",
+          "docguard.tokenless-scheduled-releases#FR-002",
+          "docguard.tokenless-scheduled-releases#FR-003",
+          "docguard.tokenless-scheduled-releases#FR-004",
+          "docguard.tokenless-scheduled-releases#FR-005",
+          "docguard.tokenless-scheduled-releases#FR-006",
+          "docguard.tokenless-scheduled-releases#FR-007",
+          "docguard.tokenless-scheduled-releases#FR-008",
+          "docguard.tokenless-scheduled-releases#FR-009",
+          "docguard.tokenless-scheduled-releases#FR-010",
+          "docguard.tokenless-scheduled-releases#FR-011",
+          "docguard.tokenless-scheduled-releases#FR-012",
+          "docguard.tokenless-scheduled-releases#SC-001",
+          "docguard.tokenless-scheduled-releases#SC-002",
+          "docguard.tokenless-scheduled-releases#SC-003",
+          "docguard.tokenless-scheduled-releases#SC-004"
+        ]
+      },
+      "observed": {
+        "artifacts": [
+          {
+            "path": "specs/011-tokenless-scheduled-releases/spec.md",
+            "digest": "sha256:c62dbe1182cf3a6e94ec8a1e1d4b6c2fce7adba57233d11a679d699634228cd5"
+          },
+          {
+            "path": "specs/011-tokenless-scheduled-releases/plan.md",
+            "digest": "sha256:1e52fed9a92d0bbf3e6d639bf60e434b8b2b906c43d080143cbcee653a9e4772"
+          },
+          {
+            "path": "specs/011-tokenless-scheduled-releases/tasks.md",
+            "digest": "sha256:38734825899c685dfbb7346d8b15c626900399b3756ea33598aeff9adc80012a"
+          }
+        ],
+        "taskCompletion": {
+          "checked": 12,
+          "total": 13
+        },
+        "implementationEvidence": [
+          {
+            "requirementId": "FR-005",
+            "file": "cli/release-pr-policy.mjs",
+            "line": 4
+          },
+          {
+            "requirementId": "FR-006",
+            "file": "cli/release-pr-policy.mjs",
+            "line": 5
+          },
+          {
+            "requirementId": "FR-007",
+            "file": "cli/release-pr-policy.mjs",
+            "line": 6
+          },
+          {
+            "requirementId": "FR-008",
+            "file": "cli/release-pr-policy.mjs",
+            "line": 7
+          },
+          {
+            "requirementId": "FR-011",
+            "file": "cli/release-pr-policy.mjs",
+            "line": 8
+          }
+        ],
+        "testEvidence": [
+          {
+            "requirementId": "FR-001",
+            "file": "tests/scheduled-release.test.mjs",
+            "line": 11
+          },
+          {
+            "requirementId": "FR-002",
+            "file": "tests/scheduled-release.test.mjs",
+            "line": 12
+          },
+          {
+            "requirementId": "FR-003",
+            "file": "tests/scheduled-release.test.mjs",
+            "line": 13
+          },
+          {
+            "requirementId": "FR-004",
+            "file": "tests/scheduled-release.test.mjs",
+            "line": 14
+          },
+          {
+            "requirementId": "FR-005",
+            "file": "tests/scheduled-release.test.mjs",
+            "line": 15
+          },
+          {
+            "requirementId": "FR-006",
+            "file": "tests/scheduled-release.test.mjs",
+            "line": 16
+          },
+          {
+            "requirementId": "FR-007",
+            "file": "tests/scheduled-release.test.mjs",
+            "line": 17
+          },
+          {
+            "requirementId": "FR-008",
+            "file": "tests/scheduled-release.test.mjs",
+            "line": 18
+          },
+          {
+            "requirementId": "FR-009",
+            "file": "tests/scheduled-release.test.mjs",
+            "line": 19
+          },
+          {
+            "requirementId": "FR-010",
+            "file": "tests/scheduled-release.test.mjs",
+            "line": 20
+          },
+          {
+            "requirementId": "FR-011",
+            "file": "tests/scheduled-release.test.mjs",
+            "line": 21
+          },
+          {
+            "requirementId": "FR-012",
+            "file": "tests/scheduled-release.test.mjs",
+            "line": 22
+          },
+          {
+            "requirementId": "SC-001",
+            "file": "tests/scheduled-release.test.mjs",
+            "line": 23
+          },
+          {
+            "requirementId": "SC-002",
+            "file": "tests/scheduled-release.test.mjs",
+            "line": 24
+          },
+          {
+            "requirementId": "SC-003",
+            "file": "tests/scheduled-release.test.mjs",
+            "line": 25
+          },
+          {
+            "requirementId": "SC-004",
+            "file": "tests/scheduled-release.test.mjs",
+            "line": 26
+          }
+        ]
+      }
     }
   ],
   "tombstones": [

{docguard_cli-0.40.0 → docguard_cli-0.40.1}/.github/workflows/auto-merge.yml

@@ -10,15 +10,18 @@ name: Auto-merge (green bot PRs)
 # the head SHA, re-verifies every matrix leg via the API, and merges itself.
 # No repo settings required, and it is fail-closed: anything unexpected → skip.
 #
-# SECURITY: workflow_run runs in the BASE repo context with write scope, so it
-# NEVER checks out or executes PR code. It reads PR metadata + check results
-# via the API only. (Same rule as jules-triage.yml / AGENTS.md CI rule.)
+# SECURITY: workflow_run runs in the BASE repo context with write scope. It
+# checks out only the default branch policy with persisted credentials disabled,
+# then reads PR metadata and candidate files as inert API data. It never checks
+# out or executes PR code.
 #
 # WHAT AUTO-MERGES:
 #   - dependabot: patch + minor only. Majors NEVER (v0.34.1 shipped a Node-18
 #     break from an auto-accepted @babel/parser major; bug-255).
 #   - jules: test-only and docs-only changes. Anything touching cli/ logic,
 #     .github/, or package.json is labeled and left for a human.
+#   - release: exact scheduler-owned next-version surfaces after a maintainer
+#     approves the repository-token PR's ordinary pull-request CI.
 
 on:
   workflow_run:
@@ -26,20 +29,28 @@ on:
     types: [completed]
 
 permissions:
+  actions: write
   contents: write
   pull-requests: write
   checks: read
-  actions: read
 
 jobs:
   auto-merge:
-    if: github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event == 'pull_request'
+    if: github.event.workflow_run.conclusion == 'success' && (github.event.workflow_run.event == 'pull_request' || github.event.workflow_run.event == 'workflow_dispatch')
     runs-on: ubuntu-latest
     steps:
+      - name: Check out trusted release policy
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          persist-credentials: false
+
       - name: Evaluate and merge if safe
         uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
+            const policyPath = process.env.GITHUB_WORKSPACE + '/cli/release-pr-policy.mjs';
+            const { evaluateReleaseCandidate, evaluateReleaseJobs } = await import(policyPath);
             const owner = context.repo.owner;
             const repo = context.repo.repo;
             const run = context.payload.workflow_run;
@@ -56,10 +67,14 @@ jobs:
 
             const BOT_DEPENDABOT = 'dependabot[bot]';
             const BOT_JULES = 'google-labs-jules[bot]';
-            const releasePr = pr.head.repo.full_name === `${owner}/${repo}` &&
+            const releaseShape = pr.head.repo.full_name === `${owner}/${repo}` &&
               /^release\/v\d+\.\d+\.\d+$/.test(pr.head.ref || '') &&
               /^release: v\d+\.\d+\.\d+ — automated weekly batch$/.test(pr.title || '');
-            if (![BOT_DEPENDABOT, BOT_JULES].includes(author) && !releasePr) {
+            if (run.event === 'workflow_dispatch' && !releaseShape) {
+              core.info(`#${num} is not a release PR — dispatched recovery CI cannot auto-merge it.`);
+              return;
+            }
+            if (![BOT_DEPENDABOT, BOT_JULES].includes(author) && !releaseShape) {
               core.info(`#${num} authored by ${author} (not a handled bot) — leaving alone.`);
               return;
             }
@@ -75,21 +90,17 @@ jobs:
               core.notice(`#${num} held: ${why}`);
             };
 
-            // ── Re-verify EVERY matrix leg independently ─────────────────
-            // workflow_run.conclusion=success covers this run, but be explicit:
-            // all four Node legs must be present AND successful. Fail closed.
-            const { data: checks } = await github.rest.checks.listForRef({
-              owner, repo, ref: headSha, per_page: 100,
-            });
-            const REQUIRED = ['test (18)', 'test (20)', 'test (22)', 'test (24)'];
-            const bad = [];
-            for (const name of REQUIRED) {
-              const c = checks.check_runs.find((r) => r.name === name);
-              if (!c) bad.push(`${name}: missing`);
-              else if (c.conclusion !== 'success') bad.push(`${name}: ${c.conclusion}`);
+            // ── Re-verify this exact workflow run independently ───────────
+            if (headSha !== pr.head.sha || run.head_branch !== pr.head.ref) {
+              core.info(`#${num} not merging — triggering run does not match the current PR head.`);
+              return;
             }
-            if (bad.length) {
-              core.info(`#${num} not merging — checks not all green: ${bad.join(', ')}`);
+            const { data: runJobs } = await github.rest.actions.listJobsForWorkflowRun({
+              owner, repo, run_id: run.id, filter: 'latest', per_page: 100,
+            });
+            const jobPolicy = evaluateReleaseJobs(runJobs.jobs);
+            if (!jobPolicy.ok) {
+              core.info(`#${num} not merging — exact-run checks failed: ${jobPolicy.errors.join(', ')}`);
               return;
             }
 
@@ -99,17 +110,54 @@ jobs:
             });
             const paths = files.map((f) => f.filename);
 
-            if (releasePr) {
-              // Release PRs cut by scheduled-release.yml. Tightly constrained:
-              // must come from a release/ branch and touch ONLY the exact
-              // version, changelog, extension and generated skill surfaces.
-              const ALLOWED = /^(package(-lock)?\.json|pyproject\.toml|server\.json|CHANGELOG\.md|templates\/ci\/github-actions\.yml|extensions\/spec-kit-docguard\/(extension\.yml|templates\/github-workflows\/(docguard-guard|docguard-autofix)\.yml|skills\/docguard-(fix|guard|review|score|sync)\/SKILL\.md)|\.agent\/skills\/docguard-(fix|guard|review|score|sync)\/SKILL\.md)$/;
-              const unexpected = paths.filter((p) => !ALLOWED.test(p));
-              if (unexpected.length) {
-                await hold('needs-review', `a release PR touching unexpected files:\n${unexpected.map((p) => `- \`${p}\``).join('\n')}`);
+            if (releaseShape) {
+              const textAt = async (path, ref) => {
+                const { data } = await github.rest.repos.getContent({ owner, repo, path, ref });
+                if (Array.isArray(data) || !data.content) throw new Error(`${path}: expected a file`);
+                return Buffer.from(data.content, 'base64').toString('utf8');
+              };
+              try {
+                const candidateFiles = {
+                  packageJson: await textAt('package.json', headSha),
+                  packageLock: await textAt('package-lock.json', headSha),
+                  pyproject: await textAt('pyproject.toml', headSha),
+                  server: await textAt('server.json', headSha),
+                  extension: await textAt('extensions/spec-kit-docguard/extension.yml', headSha),
+                };
+                const baseVersion = JSON.parse(await textAt('package.json', pr.base.sha)).version;
+                const policyInput = {
+                  repository: `${owner}/${repo}`,
+                  headRepo: pr.head.repo.full_name,
+                  defaultBranch: context.payload.repository.default_branch,
+                  baseRef: pr.base.ref,
+                  headRef: pr.head.ref,
+                  title: pr.title,
+                  author,
+                  baseVersion,
+                  paths,
+                  files: candidateFiles,
+                  tagExists: false,
+                };
+                const preliminary = evaluateReleaseCandidate(policyInput);
+                let tagExists = false;
+                if (preliminary.version && /^\d+\.\d+\.\d+$/.test(preliminary.version)) {
+                  try {
+                    await github.rest.git.getRef({ owner, repo, ref: `tags/v${preliminary.version}` });
+                    tagExists = true;
+                  } catch (e) {
+                    if (e.status !== 404) throw e;
+                  }
+                }
+                const candidatePolicy = evaluateReleaseCandidate({ ...policyInput, tagExists });
+                if (!candidatePolicy.ok) {
+                  await hold('needs-review', `release policy rejected the candidate:\n${candidatePolicy.errors.map((error) => `- ${error}`).join('\n')}`);
+                  return;
+                }
+                core.info(`#${num} authenticated tokenless release PR (${pr.head.ref}) — eligible.`);
+              } catch (e) {
+                await hold('needs-review', `release metadata could not be verified: ${e.message}`);
                 return;
               }
-              core.info(`#${num} authenticated release PR (${pr.head.ref}, author ${author}) — eligible.`);
             } else if (author === BOT_DEPENDABOT) {
               // Version delta from the title: "bump X from 1.2.3 to 1.2.4"
               const m = /from (\d+)\.(\d+)\.(\d+)\S* to (\d+)\.(\d+)\.(\d+)/.exec(pr.title || '');
@@ -135,12 +183,32 @@ jobs:
 
             // ── Merge ────────────────────────────────────────────────────
             try {
-              await github.rest.pulls.merge({
+              const { data: merge } = await github.rest.pulls.merge({
                 owner, repo, pull_number: num, merge_method: 'squash',
               });
+              if (!merge.merged) throw new Error(merge.message || 'GitHub declined the merge');
+              if (releaseShape) {
+                try {
+                  await github.rest.actions.createWorkflowDispatch({
+                    owner,
+                    repo,
+                    workflow_id: 'release.yml',
+                    ref: context.payload.repository.default_branch,
+                  });
+                } catch (dispatchError) {
+                  await github.rest.issues.createComment({
+                    owner,
+                    repo,
+                    issue_number: num,
+                    body: `⚠️ **Merged, publication dispatch failed** — ${dispatchError.message}. The next scheduled release run will retry the untagged package version.`,
+                  });
+                  core.setFailed(`Merged #${num}, but release dispatch failed: ${dispatchError.message}`);
+                  return;
+                }
+              }
               await github.rest.issues.createComment({
                 owner, repo, issue_number: num,
-                body: `🤖 **Auto-merged** — all four Node legs (18/20/22/24) green, within the test-runtime budget, and inside the auto-merge policy in \`.github/workflows/auto-merge.yml\`.`,
+                body: `🤖 **Auto-merged** — the exact CI run passed all four Node legs (18/20/22/24), stayed within the test-runtime budget, and satisfied the policy in \`.github/workflows/auto-merge.yml\`.${releaseShape ? ' Publication was dispatched on main.' : ''}`,
               });
               core.notice(`Merged #${num}.`);
             } catch (e) {

{docguard_cli-0.40.0 → docguard_cli-0.40.1}/.github/workflows/release.yml

@@ -11,6 +11,10 @@ on:
 permissions:
   contents: write # Needed to create tags and releases
 
+concurrency:
+  group: docguard-release
+  cancel-in-progress: false
+
 jobs:
   # ── Step 1: Detect if version changed ──────────────────────────────────
   detect-version:

{docguard_cli-0.40.0 → docguard_cli-0.40.1}/.github/workflows/scheduled-release.yml

@@ -8,10 +8,11 @@ name: Scheduled Release
 # patch and publish constantly. Weekly batching keeps releases hands-off
 # without turning the registry into a changelog.
 #
-# HOW IT TRIGGERS THE ACTUAL RELEASE: this workflow only bumps package.json
-# and pushes. release.yml is triggered by pushes that touch package.json, so
-# it picks up from there and does tag → GitHub Release → npm → PyPI → catalog
-# reminder. Keeping the publish logic in one place (release.yml) on purpose.
+# HOW IT TRIGGERS THE ACTUAL RELEASE: the repository token opens a protected PR.
+# GitHub intentionally holds that PR's workflows for one maintainer approval.
+# Once approved, ordinary PR CI satisfies branch protection and the metadata-only
+# auto-merge gate dispatches release.yml. A later schedule retries publication
+# when package.json has no corresponding tag.
 #
 # NO-OP WHEN NOTHING CHANGED: if there are no commits since the last release
 # tag, this exits without bumping — no empty releases.
@@ -29,9 +30,14 @@ on:
         options: [patch, minor]
 
 permissions:
+  actions: write
   contents: write
   pull-requests: write
 
+concurrency:
+  group: scheduled-release
+  cancel-in-progress: false
+
 jobs:
   cut-release:
     runs-on: ubuntu-latest
@@ -46,11 +52,20 @@ jobs:
 
       - name: Check for unreleased changes
         id: check
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           CURRENT=$(node -p "require('./package.json').version")
           LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
           echo "current=$CURRENT" >> "$GITHUB_OUTPUT"
 
+          if ! git ls-remote --tags origin "refs/tags/v$CURRENT" | grep -q "refs/tags/v$CURRENT$"; then
+            echo "v$CURRENT is not published — dispatching idempotent release recovery."
+            gh workflow run release.yml --ref main
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
           if [ -z "$LAST_TAG" ]; then
             echo "No tags yet — nothing to compare against, skipping."
             echo "changed=false" >> "$GITHUB_OUTPUT"
@@ -129,36 +144,35 @@ jobs:
           npm test
           node cli/docguard.mjs guard || [ $? -eq 2 ]
 
-      # Two stacked constraints make a direct `git push origin HEAD:main`
-      # impossible here, so this opens a PR instead:
+      # Main requires a PR and four pull-request runtime checks. GitHub holds
+      # workflows for PRs opened by GITHUB_TOKEN until a maintainer approves them;
+      # workflow_dispatch jobs do not satisfy those required PR contexts. The
+      # approval is the deliberate human boundary that avoids a stored PAT or App
+      # private key. After approval, auto-merge validates the exact PR run.
       #
       #   1. main requires a pull request. github-actions[bot] is not an admin
       #      and has no bypass, so a direct push is rejected outright.
-      #   2. A PR opened with GITHUB_TOKEN starts pull_request workflows in an
-      #      approval-required state. A separately dispatched CI run is not a
-      #      pull_request run, so it cannot activate the fail-closed auto-merge
-      #      workflow even when its checks pass.
-      #
-      # RELEASE_PR_TOKEN must be a repository-scoped GitHub App token or a
-      # fine-grained user token with Contents and Pull requests write access.
-      # Using that token to create the PR produces an ordinary pull_request run;
-      # auto-merge.yml then merges only after all four required legs pass.
-      - name: Require release PR credential
-        if: steps.check.outputs.changed == 'true'
-        env:
-          RELEASE_PR_TOKEN: ${{ secrets.RELEASE_PR_TOKEN }}
-        run: |
-          if [ -z "$RELEASE_PR_TOKEN" ]; then
-            echo "::error::RELEASE_PR_TOKEN is required. Configure a repository-scoped GitHub App or fine-grained token with Contents and Pull requests write access."
-            exit 1
-          fi
-
       - name: Open release PR
         if: steps.check.outputs.changed == 'true'
         env:
-          GH_TOKEN: ${{ secrets.RELEASE_PR_TOKEN }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           BRANCH="release/v${NEW_VERSION}"
+          EXISTING=$(gh pr list --base main --head "$BRANCH" --state open --json url --jq '.[0].url // ""')
+          if [ -n "$EXISTING" ]; then
+            echo "Reusing existing release PR: $EXISTING"
+            git fetch origin "$BRANCH"
+            if ! git merge-base --is-ancestor HEAD "origin/$BRANCH"; then
+              echo "::error::Existing $BRANCH does not contain current main; refusing to validate a stale release."
+              exit 1
+            fi
+            echo "Maintainer action required: approve the PR workflows in GitHub."
+            exit 0
+          fi
+          if git ls-remote --exit-code --heads origin "$BRANCH" >/dev/null 2>&1; then
+            echo "::error::Remote branch $BRANCH exists without an open PR; refusing to overwrite it."
+            exit 1
+          fi
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
           git checkout -b "$BRANCH"
@@ -166,7 +180,7 @@ jobs:
           git commit -m "release: v${NEW_VERSION} — automated weekly batch
 
           Cut by .github/workflows/scheduled-release.yml. Publishing itself is
-          handled by release.yml, which triggers once this lands on main."
+          handled by release.yml, which the merge gate dispatches on main."
           git push origin "$BRANCH"
 
           gh pr create \
@@ -175,8 +189,8 @@ jobs:
             --title "release: v${NEW_VERSION} — automated weekly batch" \
             --body "Automated weekly release cut by \`scheduled-release.yml\`.
 
-          Batches everything merged since \`${{ steps.check.outputs.last_tag }}\`. Tests and \`guard\` already passed on this tree before the PR was opened. The release credential creates a normal pull request so required CI checks can run and the fail-closed auto-merge policy can evaluate them.
+          Batches everything merged since \`${{ steps.check.outputs.last_tag }}\`. Tests and \`guard\` already passed on this tree before the PR was opened.
 
-          Once green, \`auto-merge.yml\` merges this, and the \`package.json\` change triggers \`release.yml\` to tag and publish."
+          **Maintainer action required:** select **Approve workflows to run** in GitHub. The ordinary pull-request CI then satisfies branch protection; once green, \`auto-merge.yml\` validates the exact run, merges this PR, and dispatches \`release.yml\` to tag and publish."
 
-          echo "Opened $BRANCH; pull-request CI will report on its merge revision."
+          echo "Opened $BRANCH. Approve its workflows in GitHub to continue the release."