Make release tags immutable; pin consumer examples to @v1.2

README.md

@@ -62,20 +62,17 @@ jobs:
         PLAYWRIGHT_PROXY_PASSWORD=${{ secrets.PLAYWRIGHT_PROXY_PASSWORD }}
 ```
 
-A reusable-workflow ref is the one thing this repo cannot pin by SHA for you:
-the correct SHA is the release commit itself, which does not exist while the
-file is being written. **For an immutable pin, resolve the tag once and paste
-the SHA**, since a tag can be moved after you adopt it:
+Pin to a release tag, never `@main`. Release tags are protected against
+deletion, updates and force-pushes, so a tag you adopt keeps pointing at the
+code you adopted. To pin a commit instead — a guarantee that does not depend on
+this repo's settings — resolve the tag first:
 
 ```console
-$ git ls-remote https://github.com/ShiplightAI/ci-triage refs/tags/v1.2
+$ git ls-remote https://github.com/ShiplightAI/ci-triage 'refs/tags/v1.2^{}'
 ```
 
-```yaml
-    uses: ShiplightAI/ci-triage/.github/workflows/triage.yml@<that SHA> # v1.2
-```
-
-Every other example below is already SHA-pinned.
+The `^{}` matters: releases are annotated tags, so without it you get the tag
+object rather than the commit, and `uses:` needs the commit.
 
 The consumer's test workflows must upload their `shiplight-report/` so triage can
 read the failure evidence. Use the **`upload-report` helper action** — it bakes in
@@ -86,7 +83,7 @@ the right path and excludes the heavy Playwright traces (`*.zip`) and videos
 ```yaml
 - name: Upload test report (for triage)
   if: ${{ !cancelled() }}
-  uses: ShiplightAI/ci-triage/upload-report@bc2459322269c0a38a5e1c642845604480233005 # v1.2
+  uses: ShiplightAI/ci-triage/upload-report@v1.2
   # matrix/sharded jobs: give each shard a unique name
   # with:
   #   name: test-report-shard-${{ matrix.shardIndex }}
@@ -124,7 +121,7 @@ The test workflow's report upload takes the prefix directly, since the
 `upload-report` action's path is a literal:
 
 ```yaml
-- uses: ShiplightAI/ci-triage/upload-report@bc2459322269c0a38a5e1c642845604480233005 # v1.2
+- uses: ShiplightAI/ci-triage/upload-report@v1.2
   with:
     report-dir: yaml-examples/shiplight-report
 ```
@@ -272,18 +269,19 @@ the repository root, and is empty when the target never resolved to a real file.
 These scripts run in a **privileged** job (`contents: write`, agent in bypassed-
 permissions mode, live credentials). Treat this repo as high-trust:
 
-- Consumers should pin by full commit SHA with the release tag as a trailing
-  comment, never `@main`. Tags in this repo have moved before, so a bare
-  `@v1.x.y` is mutable in practice and not a supply-chain pin. The only ref the
-  examples above cannot pre-resolve is the reusable workflow itself; resolve
-  that one with `git ls-remote` as shown in the quick-start.
-- Cut the release tag immediately after merging the pin bump. Between those two
-  moments the documented tag does not resolve, so a consumer copying the
-  quick-start gets an unresolved-ref failure.
+- Consumers pin to a release tag (`@v1.x.y`), never `@main`. The `release-tags`
+  ruleset protects `refs/tags/v*` with no bypass actors, so no push can repoint
+  a published release. That is a policy guarantee rather than a cryptographic
+  one — anyone who can edit repository settings can undo it — so do not relax
+  the ruleset, and pin a commit instead if you need a guarantee independent of
+  it. The pattern covers every `v*` tag, including any moving major-version
+  alias.
+- Cutting a release is three steps, in order. Merge the feature. Merge a second
+  PR bumping the internal pins to the feature's merge commit. Tag that second
+  merge commit — tags cannot be moved afterwards, so confirm the commit first.
 - The internal `uses: ShiplightAI/ci-triage[/setup]@<SHA> # v1.x` references in
-  `triage.yml` are pinned by SHA and are immutable. Bump both the SHA and its
-  release-tag comment when cutting a new version so the whole pipeline runs at
-  one ref. They necessarily name the *previous* commit — a commit cannot pin
-  itself — so the release tag is cut on the commit that bumps them, and the
-  composite-action code at the pinned SHA is identical to the tagged release.
+  `triage.yml` are pinned by SHA. Bump both the SHA and its release-tag comment
+  when cutting a new version so the whole pipeline runs at one ref. They name
+  the *previous* commit, since a commit cannot pin itself; the composite-action
+  code is unchanged between it and the release.
 - Restrict who can push/tag here more tightly than the consumer repos.