Fix manual-run tag propagation, and make the human gate real

FOUR FINDINGS FROM REVIEW OF d0fa235, ALL CONFIRMED AGAINST THE FILE.

1. BLOCKING. `github-release` used `github.ref_name` for the release tag and
title. On a workflow_dispatch run that is the BRANCH the workflow was launched
from, not the tag typed into the form - so a manual release of v0.6.0 packaged
0.6.0 correctly and then created the release against `main`. The build job
already resolves and validates the tag; everything downstream now uses that
answer instead of re-deriving a different one from the context. The manual input
is also validated against ^v[0-9]+\.[0-9]+\.[0-9]+(-.+)?$ before anything acts
on it, because a typo used to travel silently into a checkout and a filename.

2. Packaging discarded the determinism it had just established. `npm ci`
installs the lockfile's vsce - 3.6.0 - and the next line ran
`npm install -g @vscode/vsce`, fetching whatever `latest` was that morning, in
the step that builds the artifact users install. Meanwhile the publish step was
being scrupulously pinned. Now `npm exec -- vsce package`, so the lockfile
governs the artifact and the exact pin covers only authentication and upload.

3. Open VSX was passed `--pre-release` for no effect. ovsx warns "Ignoring
option '--pre-release' for prepackaged extension" and continues: the channel is
in the VSIX manifest from package time. The flag implied the upload decided
something it does not. Removed, documented, and ovsx pinned to 1.1.1.

4. The `environment: marketplace` comment still explained Entra federated
credential subjects, from the discarded design. Removed before it sent somebody
back into the Klein bottle in six months.

THE HUMAN GATE IS NOW THE ENVIRONMENT, NOT THE DRAFT.

The guide said nothing reaches users until you edit the draft and press publish.
That stops being true the moment MARKETPLACE_PUBLISH is enabled - publishing the
GitHub draft and publishing to the Marketplace are independent acts, and only
the first was ever gated by a human.

So `marketplace` becomes a protected environment requiring a reviewer. A
protected environment does not pause a running job, it stops the job STARTING,
which means the OIDC token is never minted: the capability to publish does not
exist until a person approves it. That is a better property than a job that can
always publish and is trusted not to.

The variable and the approval do different jobs and both stay. MARKETPLACE_PUBLISH
decides whether the job is reachable at all - unset, it is skipped, so testing
with real tags raises no approval prompts to dismiss. The approval decides
whether a reachable job runs.

Documented too: do not enable "prevent self-review" on that environment. With
one maintainer it deadlocks the pipeline permanently.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: Wilson421

.github/workflows/release.yml

@@ -64,6 +64,7 @@ jobs:
       base: ${{ steps.meta.outputs.base }}
       is_prerelease: ${{ steps.meta.outputs.is_prerelease }}
       channel: ${{ steps.meta.outputs.channel }}
+      tag: ${{ steps.meta.outputs.tag }}
     steps:
       # On a manual run GITHUB_REF is a BRANCH, so the tag has to be named and checked out
       # explicitly. Without this the workflow advertised manual publishing and could not do it: the
@@ -110,6 +111,14 @@ jobs:
           # A manual run has no tag ref, so take the one that was asked for.
           TAG="${{ inputs.tag }}"
           if [[ -z "$TAG" ]]; then TAG="${GITHUB_REF#refs/tags/}"; fi
+
+          # Validate before anything acts on it. A typo in the manual form used to travel silently
+          # into a checkout, a package name, and a release title.
+          if [[ ! "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-.+)?$ ]]; then
+            echo "::error::'$TAG' is not a release tag. Expected vX.Y.Z or vX.Y.Z-suffix."
+            exit 1
+          fi
+
           VERSION="${TAG#v}"
           PKG=$(node -p "require('./package.json').version")
 
@@ -183,8 +192,12 @@ jobs:
           FLAG=""
           if [[ "${{ steps.meta.outputs.channel }}" == "prerelease" ]]; then FLAG="--pre-release"; fi
 
-          npm install -g @vscode/vsce
-          vsce package $FLAG --out "excel-power-query-editor-${{ steps.meta.outputs.base }}.vsix"
+          # THE LOCKFILE'S vsce, not whatever `latest` is this morning.
+          #
+          # `npm install -g @vscode/vsce` threw away the determinism `npm ci` had just established -
+          # and it did so in the step that builds the artifact users install, while the publish step
+          # was being scrupulously pinned. `npm exec` uses the copy npm ci placed in node_modules.
+          npm exec -- vsce package $FLAG --out "excel-power-query-editor-${{ steps.meta.outputs.base }}.vsix"
 
       - name: Check the package contains what it must
         run: |
@@ -220,11 +233,17 @@ jobs:
         with:
           name: vsix
 
+      # USE THE TAG THE BUILD RESOLVED, NOT `github.ref_name`.
+      #
+      # On a manual run `github.ref_name` is the BRANCH the workflow was launched from, so a
+      # dispatch for v0.6.0 packaged 0.6.0 correctly and then created the release against `main`.
+      # The build job already does the work of resolving and validating the tag; everything
+      # downstream must use its answer rather than re-deriving a different one from the context.
       - name: Create the draft release
         uses: softprops/action-gh-release@v2
         with:
-          tag_name: ${{ github.ref_name }}
-          name: Excel Power Query Editor ${{ github.ref_name }}
+          tag_name: ${{ needs.build.outputs.tag }}
+          name: Excel Power Query Editor ${{ needs.build.outputs.tag }}
           # DRAFT deliberately: nothing becomes visible until a human reads it and clicks publish.
           draft: true
           prerelease: ${{ needs.build.outputs.is_prerelease }}
@@ -254,11 +273,20 @@ jobs:
       needs.build.outputs.channel != 'none' &&
       (vars.MARKETPLACE_PUBLISH == 'enabled' || inputs.publish_marketplace == true)
 
-    # The identity lives on the environment, not on the branch or tag.
+    # THE HUMAN GATE. Make this a protected environment requiring a reviewer.
     #
-    # A federated credential is matched by SUBJECT, and a subject built from a ref would need one
-    # credential per tag - or a wildcard, which is the opposite of the point. `environment:marketplace`
-    # is one stable subject that covers tag pushes and manual runs alike.
+    # A protected environment does not merely pause the job - the job does not START, so the OIDC
+    # token is never minted. The capability to publish does not exist until a person approves it,
+    # which is a stronger property than checking a box in a form and hoping.
+    #
+    # It is also what keeps "nothing reaches users without a human" true once MARKETPLACE_PUBLISH is
+    # enabled. Publishing the draft GitHub release and publishing to the Marketplace are independent
+    # acts, and only the first one was ever gated by a human editing a draft.
+    #
+    # The Marketplace trust policy may also name this environment.
+    #
+    # (Nothing to do with Entra any more. An earlier design used this name as a federated-credential
+    # subject; trusted publishing has no subject, and that reasoning is gone.)
     environment: marketplace
 
     permissions:
@@ -315,15 +343,17 @@ jobs:
       - name: Publish
         env:
           OVSX_PAT: ${{ secrets.OVSX_PAT }}
+          OVSX_VERSION: 1.1.1
         run: |
           if [[ -z "$OVSX_PAT" ]]; then
             echo "::warning::OVSX_PAT is not configured - skipping Open VSX."
             exit 0
           fi
-          FLAG=""
-          if [[ "${{ needs.build.outputs.channel }}" == "prerelease" ]]; then FLAG="--pre-release"; fi
 
-          npx --yes ovsx publish --packagePath *.vsix $FLAG -p "$OVSX_PAT"
+          # NO --pre-release HERE, DELIBERATELY. ovsx warns "Ignoring option '--pre-release' for
+          # prepackaged extension" and moves on: the channel is already baked into the VSIX manifest
+          # at package time. Passing it would look like it decided something.
+          npx --yes "ovsx@${OVSX_VERSION}" publish --packagePath *.vsix -p "$OVSX_PAT"
 
   summary:
     name: Summary
@@ -335,7 +365,7 @@ jobs:
         run: |
           CHANNEL="${{ needs.build.outputs.channel }}"
           {
-            echo "### ${{ github.ref_name }}"
+            echo "### ${{ needs.build.outputs.tag }}"
             echo ""
             echo "| Step | Result |"
             echo "| --- | --- |"

docs/PUBLISHING_GUIDE.md

@@ -9,9 +9,11 @@ git tag v0.6.0
 git push origin v0.6.0
 ```
 
-That builds, packages, and creates a **draft** GitHub release with the `.vsix` attached. Nothing is
-published to the Marketplace and nothing is visible to users until you edit the draft and press
-publish.
+That builds, tests, packages, and creates a **draft** GitHub release with the `.vsix` attached.
+
+**Publishing the draft and publishing to the Marketplace are two independent acts.** Editing the
+draft and pressing publish makes the GitHub release visible; it does nothing to the Marketplace. The
+Marketplace gate is the `marketplace` environment approval described below.
 
 ## Marketplace publishing is OFF
 
@@ -88,10 +90,40 @@ repository's workflow, and it replaces every step an Entra route would have need
 
 | Kind | Name | Value |
 | --- | --- | --- |
-| Environment | `marketplace` | must exist — the publish job declares it |
+| Environment | `marketplace` | must exist, **with a required reviewer** — see below |
 | Variable | `MARKETPLACE_PUBLISH` | `enabled`, when you want tags to publish |
 | Secret | `OVSX_PAT` | Open VSX token — optional, see below |
 
+### The human gate is the environment, not the draft
+
+**Make `marketplace` a protected environment requiring a reviewer.** Settings → Environments →
+`marketplace` → Required reviewers → add yourself.
+
+This is stronger than it looks. A protected environment does not pause a running job — **the job
+never starts**, so the OIDC token is never minted. The *capability* to publish does not exist until
+a person approves it, rather than existing continuously and being politely unused.
+
+```text
+push v0.6.0
+  ├─ build, test, package
+  ├─ draft GitHub release          (visible to nobody until you publish it)
+  ▼
+marketplace environment
+  ├─ REQUIRED HUMAN APPROVAL  ◄── the gate
+  ▼
+OIDC token minted → Marketplace publish → Open VSX
+```
+
+**Do not enable "prevent self-review."** With a single maintainer it deadlocks the pipeline
+permanently: the only person who can approve is the person who triggered it.
+
+**Two gates, doing different jobs.** `MARKETPLACE_PUBLISH` decides whether the job is *reachable* —
+unset, it is skipped entirely, so testing the pipeline with real tags produces no approval prompts
+to dismiss. The environment approval decides whether a reachable job *runs*. Keep both.
+
+An approval request expires after 30 days and the run fails, which is the correct outcome for a
+release nobody remembered to approve.
+
 **No `AZURE_CLIENT_ID`, no `AZURE_TENANT_ID`, no secrets for the Marketplace at all.** The
 `id-token: write` permission on the job is what lets `vsce` request the token; without it the error
 is explicit about the missing permission.
@@ -141,6 +173,11 @@ access token stored as the **`OVSX_PAT`** secret.
 a token must not turn a successful Marketplace publish into a red release. Without `OVSX_PAT` it
 warns and skips.
 
+**Open VSX is not passed `--pre-release`, on purpose.** Given an already-packaged VSIX it warns
+*"Ignoring option '--pre-release' for prepackaged extension"* and carries on — the channel is baked
+into the manifest at package time. Passing the flag would suggest the upload decides something it
+does not. `ovsx` is pinned to `1.1.1` for the same reason `vsce` is pinned.
+
 ## Why the pipeline was rebuilt
 
 Worth knowing, because the failure was invisible for a year.

docs/project/EPQE_Development_Roadmap.md

@@ -129,7 +129,7 @@ The two write paths currently disagree about deletion, and nobody chose that. Se
 | PQ-29 | ✅ done | USER_GUIDE.md has no mention of live sync | S | [Live_Sync](../Live_Sync.md) | feature doc written; User_Guide now carries a section pointing into it |
 | PQ-30 | ✅ done | Retire the RELEASE_SUMMARY pattern | S | — | removed; CHANGELOG and the release body are the two homes |
 | PQ-32 | ✅ done | docs: link and orphan checking in CI | S | [Overview](../Overview.md) | `npm run docs:links` found 11 dead links and 1 unreachable doc on its first run |
-| PQ-34 | 🟡 wired | Marketplace pre-release channel, and PAT-free auth before PATs die | M | [PQ-34][pq-34] | pipeline done 2026-08-17: **trusted publishing** (`--oidc`, pinned to 3.9.3-5), odd/even channel derivation with an intent assertion, Open VSX non-blocking. Blocked on one Marketplace trust policy; no Entra tenant needed after all. `--oidc` is absent from 3.9.2 but shipped on `next` 2026-08-11 |
+| PQ-34 | 🟡 wired | Marketplace pre-release channel, and PAT-free auth before PATs die | M | [PQ-34][pq-34] | pipeline done 2026-08-17: **trusted publishing** (`--oidc`, pinned to 3.9.3-5), odd/even channel derivation with an intent assertion, Open VSX non-blocking. Blocked on one Marketplace trust policy; no Entra tenant needed after all. `--oidc` is absent from 3.9.2 but shipped on `next` 2026-08-11 Human gate is a **protected `marketplace` environment**, so the OIDC token cannot be minted without an approval. |
 | PQ-31 | 🟡 partial | bump-version: drop commit analysis, sync the README badge | S | [PUBLISHING_GUIDE](../PUBLISHING_GUIDE.md) | badge sync DONE by docs-tools `values`; commit analysis still there, and the `npm version` tag hazard is now documented rather than fixed |
 
 ### Data safety — the thing that must never break