ci: enable merge queue validation

.github/workflows/merge-queue.yml

@@ -0,0 +1,73 @@
+name: Validate merge queue
+
+on:
+  merge_group:
+    types: [checks_requested]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: merge-queue-${{ github.event.merge_group.head_ref }}
+  cancel-in-progress: true
+
+jobs:
+  dco:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Confirm DCO admission gate
+        run: printf '%s\n' 'Required pull-request checks, including DCO, passed before this merge group became active.'
+
+  preview:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Check out merge-group tree
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+        with:
+          ref: ${{ github.event.merge_group.head_sha }}
+          path: submission
+          persist-credentials: false
+      - name: Use Node.js 20
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: submission/package-lock.json
+      - name: Install merge-group dependencies
+        working-directory: submission
+        run: npm ci --ignore-scripts
+      - name: Build merge-group preview
+        run: node submission/scripts/build-preview.mjs --root submission --contract-root submission --out-dir artifacts/preview
+      - name: Upload preview artifact
+        id: preview-artifact
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: cookbook-preview-${{ github.run_id }}
+          path: artifacts/preview
+          retention-days: 3
+          if-no-files-found: error
+
+  validate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Check out merge-group tree
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+        with:
+          ref: ${{ github.event.merge_group.head_sha }}
+          path: submission
+          persist-credentials: false
+      - name: Use Node.js 20
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: submission/package-lock.json
+      - name: Install merge-group dependencies
+        working-directory: submission
+        run: npm ci --ignore-scripts
+      - name: Validate merge-group tree
+        working-directory: submission
+        run: npm run check

docs/automated-checks.md

@@ -12,6 +12,8 @@ Automated checks run when a pull request is opened, reopened, or updated. Runnin
 
 Required checks block merge. Maintainers should not bypass a failed check; contract changes require a separate maintainer pull request that updates Schema, docs, templates, validator, and tests together.
 
+When Merge Queue is enabled, `.github/workflows/merge-queue.yml` handles `merge_group.checks_requested` and reports the same `dco`, `preview`, and `validate` contexts for the synthetic group. `preview` and `validate` check out exactly the merge-group head SHA. The pull-request `DCO / dco` job remains the authoritative check of every contributor commit; the merge-group `dco` job is only an admission attestation because GitHub's generated squash candidate is not a contributor commit.
+
 ## Validation families
 
 - `META`: Frontmatter, Schema version, single author, taxonomy, one-to-five tags, stable unique slug, related content, and platform-generated fields.
@@ -28,10 +30,27 @@ An Error blocks merge. A Warning is shown for human review but does not block by
 
 ## Security model
 
-Public and fork pull requests receive a read-only token and no Secrets. The workflow checks out validator code from the base commit into `trusted/`, checks out GitHub's synthetic merge tree into `submission/`, and invokes only code from `trusted/`. Fork-supplied scripts and workflows are never executed, even when the author is an organization member or collaborator.
+Public and fork pull requests receive a read-only token and no Secrets. The validation and preview jobs check out validator code from the base commit into `trusted/`, check out GitHub's synthetic merge tree into `submission/`, and use trusted tooling for ordinary external content validation. Demo files are always treated as data and are never executed.
+
+That data/tooling split does not make a green check an authorization decision. A pull request can propose changes to GitHub Actions workflow orchestration and, for Maintainer-owned repository branches, the proposed validation tooling is deliberately exercised. Therefore the check-producing configuration itself is part of the candidate change and must be reviewed as infrastructure.
 
 Ordinary external pull requests may change only valid article paths under `content/**` and strongly bound source under `demos/<slug>/**`. `demos/README.md`, contracts, templates, configuration, tooling, and workflows remain Maintainer-owned infrastructure. A trusted owner, member, or collaborator may change infrastructure only from a branch in this repository; that no-secret, read-only run additionally executes the complete proposed `npm run check`. All existing content is revalidated against the prospective merged contracts before merge.
 
 Demo dependency manifests, package scripts, Makefiles, Dockerfiles, tests, source, and README commands are never executed. Pull-request automation reads Demo files only as untrusted data using tooling from the trusted base revision.
 
 Automated checks do not determine factual correctness, public product status, Demo runtime behavior, operational safety, copyright ownership, customer authorization, or whether the content should be published. Maintainers review the Demo README and source manually.
+
+## Merge Queue admission
+
+Auto-merge must remain disabled. Only a Maintainer with write access may manually add a pull request to the queue, and green checks alone are never sufficient authorization. Capture the PR's `headRefOid` before reviewing both outputs in full:
+
+```bash
+TASK_REVIEWED_SHA="$(gh pr view <PR> --repo QoderAI/cloud-agents-cookbook --json headRefOid --jq .headRefOid)"
+gh pr diff <PR> --name-only
+gh pr diff <PR>
+TASK_CURRENT_SHA="$(gh pr view <PR> --repo QoderAI/cloud-agents-cookbook --json headRefOid --jq .headRefOid)"
+test "$TASK_CURRENT_SHA" = "$TASK_REVIEWED_SHA"
+gh pr merge <PR> --repo QoderAI/cloud-agents-cookbook --match-head-commit "$TASK_REVIEWED_SHA" --squash
+```
+
+Replace the `TASK_` prefix with a name unique to the operation. Read `headRefOid` again immediately before enqueueing and require strict equality with the reviewed SHA. If the head changes, stop and repeat the complete review; `--match-head-commit` is mandatory. Do not queue an external pull request that touches `.github/**`, `scripts/**`, `tests/**`, root `package*.json`, `config/**`, `schema/**`, `docs/**`, or other Maintainer-owned automation/security infrastructure. Recreate and review that work as a Maintainer-owned infrastructure pull request. The Ruleset keeps zero required approvals only because the repository currently has a single Maintainer; it compensates with an empty bypass list and this explicit manual admission boundary. When a second Maintainer is available, require approval, Code Owner review, and latest-push approval.

docs/maintainers/implementation-plan.md

@@ -1,5 +1,7 @@
 # Qoder Cloud Agents Cookbook Public Repository Implementation Plan
 
+> **Historical design note:** This plan records the repository's initial build sequence and is not the source of truth for live GitHub settings. The current single-Maintainer Merge Queue, zero-approval review parameters, SHA-bound manual admission gate, and future second-Maintainer upgrade are defined in `docs/maintainers/repository-settings.md`. If this historical plan conflicts with that document, follow `repository-settings.md`.
+
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 
 **Goal:** Build, verify, and publish a production-grade public content-source repository for Qoder Cloud Agents Cookbook.
@@ -20,7 +22,7 @@
 - Mermaid supports only flowchart, sequenceDiagram, and stateDiagram-v2 with no click, external resource, HTML label, or init directive.
 - Content and documentation use CC BY 4.0; executable code uses Apache-2.0; every contributed commit requires DCO sign-off.
 - No fabricated launch article is stored under `content/`; examples belong under `tests/fixtures/`.
-- External pull requests never receive secrets and never execute contributor-supplied code.
+- External pull requests never receive secrets; intended content validation treats contributor content and Demo source as data. Because a candidate can modify check-producing workflow infrastructure, the live SHA-bound manual queue-admission policy in `repository-settings.md` remains authoritative.
 
 ---
 
@@ -146,7 +148,7 @@
 **Interfaces:**
 - Produces: exact remote setup, branch protection, secrets, preview, publication acknowledgement, rollback, and incident procedures.
 
-- [ ] Document required GitHub settings: `main`, pull requests, one approval, CODEOWNERS, resolved conversations, required checks, no force push, no deletion, and Actions budget controls.
+- [ ] Document live GitHub settings in `repository-settings.md`: `main`, pull requests, current single-Maintainer zero-approval parameters, informational CODEOWNERS, resolved conversations, required checks, empty bypass list, conservative Merge Queue, disabled Auto-merge, SHA-bound manual admission, no force push, no deletion, and Actions budget controls. Record the future upgrade to approval, Code Owner review, and latest-push approval after a second Maintainer is available.
 - [ ] Define preview and publish payloads, expected acknowledgement, idempotency key, source commit, checksum, and failure behavior.
 - [ ] Document release rollback by revert and republish, with slug redirects and lifecycle state behavior.
 - [ ] Run the repository link checker and full `npm run check`.

docs/maintainers/repository-design.md

@@ -57,11 +57,11 @@ dist/                    generated output; never committed
 
 Validation is deterministic and runs locally with `npm run check` and in GitHub Actions for every pull request. A public contribution may change valid article paths and `demos/<slug>/**`; repository infrastructure changes are handled in separate Maintainer pull requests.
 
-For public content pull requests, the workflow checks out trusted tooling from the default branch and treats the contributor tree strictly as input data. It uses read-only permissions, receives no secrets, and does not execute contributor-supplied scripts. Infrastructure changes are restricted to repository owners, organization members, and collaborators; those trusted pull requests additionally install, test, and exercise the proposed tooling, still without secrets or write permissions. Required status checks block merge when validation, tests, DCO, or preview generation fails.
+For public content pull requests, the intended validation path checks out trusted tooling from the default branch and treats content and Demo files as input data. It uses read-only permissions, receives no secrets, and never executes Demo source. A candidate PR can still propose changes to the workflow orchestration that produces status checks, so green checks are not authorization; the SHA-bound manual admission gate prevents an external infrastructure change from entering the queue. Maintainer-owned infrastructure pull requests additionally install, test, and exercise the proposed tooling, still without secrets or write permissions. Required status checks block merge when validation, tests, DCO, or preview generation fails.
 
 Automated checks cover metadata schema, global slug uniqueness, path consistency, taxonomy, article structure, required sections, images, links, Markdown fences, footnotes, Mermaid syntax and safety, unsupported elements, common secret patterns, Demo binding and static safety, configuration references, and deterministic catalog generation. Submitted Demo commands and source are never executed.
 
-Automated checks do not decide factual accuracy, Demo runtime correctness or operational safety, publication value, copyright ownership, customer authorization, or whether a statement describes a public product capability. Maintainers review these areas and Demo source manually and merge approved pull requests.
+Automated checks do not decide factual accuracy, Demo runtime correctness or operational safety, publication value, copyright ownership, customer authorization, or whether a statement describes a public product capability. Maintainers review these areas and Demo source manually. In the current single-Maintainer configuration, Auto-merge is disabled and only a write-access Maintainer may manually queue a change after binding the full file-list and diff review to the PR's immutable `headRefOid`. The head SHA is read again immediately before `gh pr merge --match-head-commit`; any change requires a complete re-review. Green checks are evidence, not queue authorization. After a second Maintainer is available, require approval, Code Owner review, and latest-push approval while retaining the SHA-bound manual infrastructure review.
 
 ## Preview and publication
 
@@ -85,7 +85,7 @@ The final PRD marks launch content as pending. Therefore `content/` initially co
 
 ## Operational safety
 
-- `main` is protected and requires pull requests, required checks, resolved conversations, and maintainer approval.
+- `main` is protected and requires pull requests, required checks, resolved conversations, an empty bypass list, and a conservative single-entry Merge Queue. The present single-Maintainer Ruleset requires zero approvals; admission instead uses the SHA-bound manual gate documented in `docs/maintainers/repository-settings.md`.
 - Fork pull requests receive read-only tokens and no repository secrets.
 - Preview artifacts have short retention and standard GitHub-hosted runners only.
 - Publication secrets are available only to the trusted `push` workflow on `main`.

docs/maintainers/repository-settings.md

@@ -13,17 +13,37 @@ Apply these settings after creating `QoderAI/cloud-agents-cookbook` and before a
 ## Branch protection for `main`
 
 - Require a pull request before merging.
-- Require at least one approving review.
-- Require review from Code Owners.
 - Dismiss stale approvals after new commits.
 - Require all conversations to be resolved.
-- Require the latest reviewed commit.
-- Require `Validate content / validate`, `DCO / dco`, and `Preview content / preview`.
-- Require branches to be up to date before merging so the required checks always represent the prospective merged tree. Do not enable Merge Queue until the workflows explicitly support the `merge_group` event.
+- Keep required approvals at zero, Code Owner review disabled, and last-push approval disabled while the repository has only one Maintainer. GitHub does not allow an author to approve their own pull request, so enabling these controls now would block Maintainer infrastructure pull requests.
+- Require the `validate`, `dco`, and `preview` status contexts.
+- Enable Merge Queue only while `.github/workflows/merge-queue.yml` handles `merge_group.checks_requested` and reports those same three contexts.
+- Configure the queue for one entry at a time: `ALLGREEN`, squash, one entry to build, one entry to merge, minimum one entry, zero-minute wait, and a ten-minute check-response timeout.
+- Disable strict branch freshness after enabling the queue. The merge group, rather than the contributor branch, is tested against the latest `main`.
+- Keep Auto-merge disabled. Only a Maintainer with write access may manually add a pull request to the queue after completing the admission review below.
 - Block force pushes and branch deletion.
-- Do not allow bypass except for documented emergency recovery.
+- Keep the Ruleset bypass list empty.
 
-The initial CODEOWNER is `@anchenqlw`. Replace it with an organization maintainer team after that GitHub team exists and has write access.
+The initial CODEOWNER is `@anchenqlw`, but CODEOWNERS is currently routing information rather than a required approval gate. After a second Maintainer or organization Maintainer team has write access, require at least one approval, Code Owner review, and approval of the latest push. Re-evaluate whether the manual queue-admission procedure can then be narrowed, but do not weaken the infrastructure diff review.
+
+## Manual queue admission
+
+Green checks show that the candidate produced the expected contexts; they do not authorize a merge. A pull request can propose changes to the workflows, scripts, and tests that produce those contexts. Every admission review is bound to one immutable pull-request head SHA. Use a task-specific variable name when operating on a real PR:
+
+```bash
+TASK_REVIEWED_SHA="$(gh pr view <PR> --repo QoderAI/cloud-agents-cookbook --json headRefOid --jq .headRefOid)"
+gh pr diff <PR> --name-only
+gh pr diff <PR>
+TASK_CURRENT_SHA="$(gh pr view <PR> --repo QoderAI/cloud-agents-cookbook --json headRefOid --jq .headRefOid)"
+test "$TASK_CURRENT_SHA" = "$TASK_REVIEWED_SHA"
+gh pr merge <PR> --repo QoderAI/cloud-agents-cookbook --match-head-commit "$TASK_REVIEWED_SHA" --squash
+```
+
+Replace the `TASK_` prefix with a name unique to the operation, such as `INFRA_` or `PR11_`. Capture the reviewed SHA before inspecting the complete file list and full diff. Immediately before the queue command, read `headRefOid` again and require strict equality. If it changed for any reason, stop and restart the review against the new SHA. `--match-head-commit` is mandatory and prevents the enqueue operation from racing with a later push.
+
+Do not queue an external pull request that changes `.github/**`, `scripts/**`, `tests/**`, root `package*.json`, `config/**`, `schema/**`, `docs/**`, or other Maintainer-owned repository automation/security infrastructure. Recreate such work on a Maintainer-owned branch and submit it as a separate infrastructure pull request.
+
+The first queue acceptance case, PR #11, must contain only the expected content translation under `content/**`. Any other path is a stop condition, even if all checks are green.
 
 ## Fork pull-request Actions
 
@@ -53,4 +73,4 @@ Rotate the token through the receiver and GitHub Secrets. Do not store it in con
 
 ## One-time verification
 
-Open a signed test pull request from a public fork. Confirm that no Secrets appear, infrastructure changes are rejected, all three required checks run, the preview Artifact opens, an unsigned commit fails DCO, and a valid content correction can be merged by a Maintainer.
+Open a signed test pull request from a public fork. Confirm that no Secrets appear, all three required checks run, the preview Artifact opens, an unsigned commit fails DCO, Auto-merge remains disabled, only a write-access Maintainer can enqueue, and a valid content correction completes all three `merge_group` checks before being squash-merged. Separately verify that an external infrastructure change is stopped by the manual admission review even if it displays green checks.