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

{docguard_cli-0.40.0 → docguard_cli-0.40.2}/.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.2
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.40.0 -->
+<!-- docguard:version: 0.40.2 -->
 
 # DocGuard Fix Skill
 

{docguard_cli-0.40.0/extensions/spec-kit-docguard → docguard_cli-0.40.2/.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.2
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.40.0 -->
+<!-- docguard:version: 0.40.2 -->
 
 # DocGuard Guard Skill
 

{docguard_cli-0.40.0/extensions/spec-kit-docguard → docguard_cli-0.40.2/.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.2
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.40.0 -->
+<!-- docguard:version: 0.40.2 -->
 
 # DocGuard Review Skill
 

{docguard_cli-0.40.0/extensions/spec-kit-docguard → docguard_cli-0.40.2/.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.2
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.40.0 -->
+<!-- docguard:version: 0.40.2 -->
 
 # DocGuard Score Skill
 

{docguard_cli-0.40.0 → docguard_cli-0.40.2}/.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.2
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
-<!-- docguard:version: 0.40.0 -->
+<!-- docguard:version: 0.40.2 -->
 
 # DocGuard Sync Skill
 

{docguard_cli-0.40.0 → docguard_cli-0.40.2}/.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:b5e9f78c62a085b06c30a1ef2a67c45df9a2177aa75f25049c42c7c71e99e543"
+          },
+          {
+            "path": "specs/011-tokenless-scheduled-releases/plan.md",
+            "digest": "sha256:f833cdcbe825ab6a75ab484ac586ef3e36a984b7856f196730bb6ca5cdd0393e"
+          },
+          {
+            "path": "specs/011-tokenless-scheduled-releases/tasks.md",
+            "digest": "sha256:9b49cf5672efd0bea5ccca4e1c83239c77854e5733630ab64e800185e1fa44a9"
+          }
+        ],
+        "taskCompletion": {
+          "checked": 14,
+          "total": 15
+        },
+        "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": 15
+          },
+          {
+            "requirementId": "FR-002",
+            "file": "tests/scheduled-release.test.mjs",
+            "line": 16
+          },
+          {
+            "requirementId": "FR-003",
+            "file": "tests/scheduled-release.test.mjs",
+            "line": 17
+          },
+          {
+            "requirementId": "FR-004",
+            "file": "tests/scheduled-release.test.mjs",
+            "line": 18
+          },
+          {
+            "requirementId": "FR-005",
+            "file": "tests/scheduled-release.test.mjs",
+            "line": 19
+          },
+          {
+            "requirementId": "FR-006",
+            "file": "tests/scheduled-release.test.mjs",
+            "line": 20
+          },
+          {
+            "requirementId": "FR-007",
+            "file": "tests/scheduled-release.test.mjs",
+            "line": 21
+          },
+          {
+            "requirementId": "FR-008",
+            "file": "tests/scheduled-release.test.mjs",
+            "line": 22
+          },
+          {
+            "requirementId": "FR-009",
+            "file": "tests/scheduled-release.test.mjs",
+            "line": 23
+          },
+          {
+            "requirementId": "FR-010",
+            "file": "tests/scheduled-release.test.mjs",
+            "line": 24
+          },
+          {
+            "requirementId": "FR-011",
+            "file": "tests/scheduled-release.test.mjs",
+            "line": 25
+          },
+          {
+            "requirementId": "FR-012",
+            "file": "tests/scheduled-release.test.mjs",
+            "line": 26
+          },
+          {
+            "requirementId": "SC-001",
+            "file": "tests/scheduled-release.test.mjs",
+            "line": 27
+          },
+          {
+            "requirementId": "SC-002",
+            "file": "tests/scheduled-release.test.mjs",
+            "line": 28
+          },
+          {
+            "requirementId": "SC-003",
+            "file": "tests/scheduled-release.test.mjs",
+            "line": 29
+          },
+          {
+            "requirementId": "SC-004",
+            "file": "tests/scheduled-release.test.mjs",
+            "line": 30
+          }
+        ]
+      }
     }
   ],
   "tombstones": [

docguard_cli-0.40.2/.github/scripts/validate-release-candidate.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+
+/**
+ * Validate the scheduler-generated release diff before it leaves the trusted
+ * default-branch checkout. GitHub's native auto-merge then enforces the
+ * repository's required pull-request checks on every candidate revision.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { evaluateReleaseCandidate } from '../../cli/release-pr-policy.mjs';
+
+const SCRIPT_PATH = fileURLToPath(import.meta.url);
+
+function read(root, path) {
+  return readFileSync(resolve(root, path), 'utf8');
+}
+
+export function validateReleaseWorkspace({
+  root = process.cwd(),
+  baseVersion,
+  branch,
+  repository,
+  defaultBranch = 'main',
+}) {
+  const paths = execFileSync('git', ['diff', '--name-only', 'HEAD', '--'], {
+    cwd: root,
+    encoding: 'utf8',
+  }).trim().split('\n').filter(Boolean);
+  const version = JSON.parse(read(root, 'package.json')).version;
+  const result = evaluateReleaseCandidate({
+    repository,
+    headRepo: repository,
+    defaultBranch,
+    baseRef: defaultBranch,
+    headRef: branch,
+    title: `release: v${version} — automated weekly batch`,
+    author: 'github-actions[bot]',
+    baseVersion,
+    paths,
+    files: {
+      packageJson: read(root, 'package.json'),
+      packageLock: read(root, 'package-lock.json'),
+      pyproject: read(root, 'pyproject.toml'),
+      server: read(root, 'server.json'),
+      extension: read(root, 'extensions/spec-kit-docguard/extension.yml'),
+    },
+    tagExists: false,
+  });
+  if (!result.ok) {
+    throw new Error(result.errors.join('; '));
+  }
+  return { version: result.version, paths };
+}
+
+function valueAfter(flag) {
+  const index = process.argv.indexOf(flag);
+  return index >= 0 ? process.argv[index + 1] : undefined;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === SCRIPT_PATH) {
+  try {
+    const result = validateReleaseWorkspace({
+      baseVersion: valueAfter('--base-version'),
+      branch: valueAfter('--branch'),
+      repository: process.env.GITHUB_REPOSITORY,
+    });
+    console.log(`Validated v${result.version} release candidate (${result.paths.length} changed files).`);
+  } catch (error) {
+    console.error(`Release candidate validation failed: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

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

@@ -2,17 +2,13 @@ name: Auto-merge (green bot PRs)
 
 # Hands-off merging for bot PRs that have ALREADY passed the full CI matrix.
 #
-# WHY workflow_run AND NOT `gh pr merge --auto`: GitHub's native auto-merge
-# requires the repo-level `allow_auto_merge` setting plus REQUIRED status
-# checks in branch protection. Without required checks configured, `--auto`
-# merges IMMEDIATELY without waiting for CI — worse than merging by hand.
-# This workflow instead fires only after "DocGuard CI" reports success for
-# 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.
+# Release PRs use GitHub's native auto-merge because main now has four required
+# runtime checks. This workflow remains the stricter policy gate for Dependabot
+# and Jules PRs, which have separate version and changed-file restrictions.
 #
-# 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,
+# reads PR metadata through the API, and never checks out or executes PR code.
 #
 # WHAT AUTO-MERGES:
 #   - dependabot: patch + minor only. Majors NEVER (v0.34.1 shipped a Node-18
@@ -29,17 +25,24 @@ permissions:
   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'
     runs-on: ubuntu-latest
     steps:
+      - name: Check out trusted auto-merge 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 { evaluateReleaseJobs } = await import(policyPath);
             const owner = context.repo.owner;
             const repo = context.repo.repo;
             const run = context.payload.workflow_run;
@@ -56,10 +59,7 @@ jobs:
 
             const BOT_DEPENDABOT = 'dependabot[bot]';
             const BOT_JULES = 'google-labs-jules[bot]';
-            const releasePr = 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 (![BOT_DEPENDABOT, BOT_JULES].includes(author)) {
               core.info(`#${num} authored by ${author} (not a handled bot) — leaving alone.`);
               return;
             }
@@ -75,21 +75,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,18 +95,7 @@ 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')}`);
-                return;
-              }
-              core.info(`#${num} authenticated release PR (${pr.head.ref}, author ${author}) — eligible.`);
-            } else if (author === BOT_DEPENDABOT) {
+            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 || '');
               if (!m) { await hold('needs-review', 'could not parse the version delta from the PR title.'); return; }
@@ -135,12 +120,13 @@ 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');
               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\`.`,
               });
               core.notice(`Merged #${num}.`);
             } catch (e) {

{docguard_cli-0.40.0 → docguard_cli-0.40.2}/.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.2}/.github/workflows/scheduled-release.yml

@@ -8,10 +8,12 @@ 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 validates and opens a
+# protected PR, then arms GitHub's native squash auto-merge. GitHub intentionally
+# holds that PR's workflows for one maintainer approval. Once approved, ordinary
+# PR CI satisfies the required checks, native auto-merge updates main, and the
+# package.json push starts 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 +31,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 +53,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 +145,40 @@ 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. Native auto-merge remains blocked until all required checks
+      # succeed and resets if the candidate head changes.
       #
       #   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}"
+          node .github/scripts/validate-release-candidate.mjs \
+            --base-version "${{ steps.check.outputs.current }}" \
+            --branch "$BRANCH"
+          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
+            gh pr merge --auto --squash "$EXISTING"
+            echo "Auto-merge armed. 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,17 +186,18 @@ 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 after protected native auto-merge updates main."
           git push origin "$BRANCH"
 
-          gh pr create \
+          PR_URL=$(gh pr create \
             --base main \
             --head "$BRANCH" \
             --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; GitHub's protected native auto-merge merges the exact green head, and the resulting \`package.json\` push starts \`release.yml\` to tag and publish.")
 
-          echo "Opened $BRANCH; pull-request CI will report on its merge revision."
+          gh pr merge --auto --squash "$PR_URL"
+          echo "Opened $BRANCH with auto-merge armed. Approve its workflows in GitHub to continue the release."