fix(BG0575, CR0545): the documented verified install completes, and a release publishes the assets it verifies against

README and the website offered `SDLC_STUDIO_REQUIRE_CHECKSUM=1` with a pinned tag as the
path for a reader who will not accept an unverified download. It refused, at every version,
for everybody: both installers looked for a `.sha256` beside GitHub's GENERATED source
archive, and GitHub serves no such sidecar for any tag. The digest resolved empty, the
requirement made empty fatal, and the one command offered to that reader was the one command
guaranteed to fail. Nothing exercised it, so it was consumer-facing from the day it was
written and green the whole time.

A tagged version now prefers a release asset built from the tag and published with its digest
in the same automated step, so both halves of the pair are ours and cannot drift. GitHub's
generated archives are deliberately not verified: they are regenerated rather than published,
and a digest recorded for one can stop matching with nobody touching the tag, which reaches a
user as `Checksum mismatch` - indistinguishable from an attack.

CR0545 is the reason it is a workflow and not a command somebody runs. Everything after the
tag was un-tooled: `release_cut.py` stopped at `tag-check` and the runbook had no Release row
at all. That was paid for twice - v4.1.0 published an empty asset list, v5.0.0 was tagged with
no Release at all - and both were somebody meaning to and not doing it. `runbook.py` now
REQUIRES the Release step, so the section cannot be silently dropped the way the step was.

TWO REVIEWS, and the second one rejected this.

The plan review killed the argument this was built on. I justified publishing our own archives
by calling `git archive` deterministic; measured, the same tree yields three different digests
across three plausible invocations, so it is deterministic only with the command pinned. The
real argument is custody - bytes and digest published together, by us - and the build commands
are now pinned to the byte. That review also found the test problem I had called unsolvable was
already solved by a harness in the tree I had not looked for.

The fix review found six blocking defects, two of them mutants I had claimed were killed and
had not executed against the shipped surface:

  - The AC5 test ran its OWN `git archive` and never opened the workflow, so it asserted that
    git honours `--prefix` - a property of git, not of this repo - and stayed green while the
    workflow drifted. It now reads the workflow's command and executes THAT.
  - "Aborts before extraction" was unobservable: install.sh deletes its temp directory on exit,
    so the test could not tell "never extracted" from "extracted then cleaned up". A `tar` stub
    makes the ordering visible, with a positive control proving the successful path reaches it.
  - "A 404 and only a 404" was false. `curl -f` exits 22 for EVERY status at or above 400, so a
    403, a 429 or a CDN 503 was read as "no asset published" and silently downgraded a default
    install to the unverified archive. The status is now read rather than inferred.
  - The Windows control compared an uppercase digest against an uppercase digest, so `-ine` to
    `-cne` would have survived the only job that checks the PowerShell half while breaking every
    real verified install on Windows.

Nine mutants now execute and all nine are killed, with the unmutated suite green beside them.

The PowerShell half is NOT verified locally - `pwsh` is not on this machine - and that is
recorded in the bug rather than implied. It is covered by a green/red/404 trio in the
`windows-smoke` job, which runs `install.ps1` under real PowerShell on every push. A test
asserting over the TEXT of `install.ps1` would be a weaker claim than the criterion and is not
what shipped.

Tags before v5.0.1 have no published assets and still refuse under `REQUIRE_CHECKSUM=1`. The
fix is forward-only and says so rather than widening what counts as verified.

Also: `test_prd_cli_path` leaked the whole plan digest to stdout, so the suite's noise count
moved whenever the lessons ranking or the runbook grew - which is how adding a Release step
turned the tree red. It now captures stdout, as the test directly below it already did.

The stale disclosed-findings count in the v5.0.0 notes (38, against a page carrying 40) is
corrected here rather than left, which is why US0670 is referenced: that page is its Affects.

Refs: BG0575, CR0545, US0670

Author: DarrenBenson

.claude/skills/sdlc-studio/reference-sprint-toolchain.md

@@ -71,6 +71,24 @@ Read this at plan time. `sprint plan` prints it.
 | Take the backlog census | `status.py points` | counting artefacts by hand |
 | Mirror to the installed copy | `bash tools/forward-port.sh --yes` | `install.sh`, which clobbers the tree |
 
+## 6. Release
+
+| Do | Command | Instead of |
+| --- | --- | --- |
+| Compose the changelog section | `release_cut.py changelog-cut --version <v>` | hand-merging fragments |
+| Stamp the commit the gate passed on | `release_cut.py record-green --commit <sha> --gate <which>` | a green claim naming no gate |
+| Refuse a tag the gate never covered | `release_cut.py tag-check --version <v>` | tagging on memory |
+| Publish the release and its artefacts | your project's release automation, triggered by the tag | a hand-uploaded artefact, which is the step that gets skipped |
+
+Make the publish step something the tag triggers, not a line somebody runs. Where a project offers
+a verified install, the checksum a user verifies against is published by that step, so a release
+that skips it leaves the documented verification broken while everything else looks fine. Two
+releases shipped that way here before it was automated - one with no artefacts attached, one with
+no release entry at all - and both were somebody meaning to and not doing it. The second case is
+the quieter one: `skill-update` asks the forge for the LATEST RELEASE, so until the release entry
+exists, every installed copy still reports the previous version and prompts nobody to upgrade. A
+tag without a release is, to the update mechanism, unreleased.
+
 ## In-flight: changing a run that is already open
 
 | Do | Command | Instead of |

.claude/skills/sdlc-studio/scripts/tests/test_sprint.py

@@ -612,7 +612,12 @@ def test_prd_cli_path(self) -> None:
             root = Path(d)
             prd = root / "prd.md"
             prd.write_text("# PRD\n", encoding="utf-8")
-            rc = _load().main(["plan", "--prd", str(prd), "--root", str(root)])
+            # stdout captured, as the sibling test below already does: this call prints the whole
+            # plan digest - the lessons ranking and the toolchain runbook's step list - so the
+            # suite's leaked-line count moved every time either GREW. A green suite must print
+            # nothing, or a real error hides in the noise.
+            with contextlib.redirect_stdout(io.StringIO()):
+                rc = _load().main(["plan", "--prd", str(prd), "--root", str(root)])
             self.assertEqual(rc, 0)
 
     def test_plan_write_persists_artifact(self) -> None:  # CR0091

.github/workflows/lint.yml

@@ -200,3 +200,101 @@ jobs:
           }
           Write-Host 'NoSweep opt-out OK'
           Pop-Location
+
+      - name: install.ps1 - the verified install path, green and red (BG0575)
+        shell: pwsh
+        run: |
+          # The Windows half of BG0575. install.ps1 must prefer the release ASSET for a tagged
+          # version, because GitHub serves no .sha256 beside a generated source archive - so the
+          # documented SDLC_STUDIO_REQUIRE_CHECKSUM=1 install could never complete.
+          #
+          # Invoke-WebRequest cannot be shadowed on PATH the way `curl` can, so it is shadowed as
+          # a FUNCTION in the invoking scope - the same technique test_install_atomic.py uses for
+          # `cp`. The real install.ps1 runs; only its downloader is answered locally.
+          $ErrorActionPreference = 'Stop'
+          $work = Join-Path $env:RUNNER_TEMP 'verified'
+          New-Item -ItemType Directory -Force $work | Out-Null
+
+          # Build a payload shaped like the real asset: one sdlc-studio-<ver>/ at the top,
+          # holding the skill tree, which is what install.ps1's Get-ChildItem -Filter reads.
+          $stage = Join-Path $work 'sdlc-studio-9.9.9'
+          $skill = Join-Path $stage '.claude/skills/sdlc-studio'
+          New-Item -ItemType Directory -Force $skill | Out-Null
+          Set-Content -Path (Join-Path $skill 'SKILL.md') -Value "---`nname: sdlc-studio`n---`n"
+          Set-Content -Path (Join-Path $stage 'CHANGELOG.md') -Value "# Changelog`n"
+          $zip = Join-Path $work 'asset.zip'
+          Compress-Archive -Path $stage -DestinationPath $zip -Force
+          # LOWERCASE, because that is what `sha256sum` publishes and therefore what a real
+          # sidecar contains. Get-FileHash returns uppercase, so serving its output unchanged
+          # would compare uppercase against uppercase - and the mutant `-ine` -> `-cne` would
+          # survive this whole job while breaking every real verified install on Windows.
+          $digest = (Get-FileHash -Path $zip -Algorithm SHA256).Hash.ToLower()
+
+          $script:ServedDigest = $digest
+          $script:AssetZip = $zip
+
+          function Invoke-WebRequest {
+            param([string]$Uri, [string]$OutFile, [switch]$UseBasicParsing)
+            if ($Uri -like '*/releases/download/*sdlc-studio-v9.9.9.zip.sha256') {
+              return [pscustomobject]@{ Content = "$script:ServedDigest  sdlc-studio-v9.9.9.zip" }
+            }
+            if ($Uri -like '*/releases/download/*sdlc-studio-v9.9.9.zip') {
+              Copy-Item $script:AssetZip $OutFile -Force; return
+            }
+            # Anything else is "not there". install.ps1 reads the status off
+            # $_.Exception.Response.StatusCode, so the thrown exception must actually CARRY one -
+            # a bare WebException has a null Response, which install.ps1 correctly treats as a
+            # transport error, and the 404 branch would then be exercised by nothing at all.
+            $msg = [System.Net.Http.HttpResponseMessage]::new([System.Net.HttpStatusCode]::NotFound)
+            throw [Microsoft.PowerShell.Commands.HttpResponseException]::new('404 Not Found', $msg)
+          }
+
+          $env:SDLC_STUDIO_REQUIRE_CHECKSUM = '1'
+          $proj = Join-Path $work 'proj'
+          New-Item -ItemType Directory -Force $proj | Out-Null
+          Push-Location $proj
+          & "$env:GITHUB_WORKSPACE/install.ps1" -Target claude -Local -NoSweep -Version v9.9.9
+          if (-not (Test-Path '.claude/skills/sdlc-studio/SKILL.md')) {
+            throw 'BG0575 green control: the verified install did not place SKILL.md'
+          }
+          Write-Host 'BG0575 green control OK - verified install completed from the asset'
+          Pop-Location
+
+          # RED control: corrupt the sidecar. The install must abort before extraction.
+          $script:ServedDigest = 'deadbeef'
+          $proj2 = Join-Path $work 'proj2'
+          New-Item -ItemType Directory -Force $proj2 | Out-Null
+          Push-Location $proj2
+          $failed = $false
+          try { & "$env:GITHUB_WORKSPACE/install.ps1" -Target claude -Local -NoSweep -Version v9.9.9 }
+          catch { $failed = $true }
+          if (-not $failed) { throw 'BG0575 red control: a mismatched digest did not abort' }
+          if (Test-Path '.claude/skills/sdlc-studio/SKILL.md') {
+            throw 'BG0575 red control: extraction happened despite a digest mismatch'
+          }
+          Write-Host 'BG0575 red control OK - mismatched digest aborted before extraction'
+          Pop-Location
+
+          # THIRD control: no asset published for the tag. This is the only one that reaches the
+          # 404 branch, so without it the fallback install.ps1 gained for BG0575 is exercised by
+          # nothing. The tag must fall back to the source archive, find no digest there, and
+          # refuse under REQUIRE_CHECKSUM rather than invent verification.
+          $script:NoAsset = $true
+          function Invoke-WebRequest {
+            param([string]$Uri, [string]$OutFile, [switch]$UseBasicParsing)
+            $m = [System.Net.Http.HttpResponseMessage]::new([System.Net.HttpStatusCode]::NotFound)
+            throw [Microsoft.PowerShell.Commands.HttpResponseException]::new('404 Not Found', $m)
+          }
+          $proj3 = Join-Path $work 'proj3'
+          New-Item -ItemType Directory -Force $proj3 | Out-Null
+          Push-Location $proj3
+          $refused = $false
+          $err = ''
+          try { & "$env:GITHUB_WORKSPACE/install.ps1" -Target claude -Local -NoSweep -Version v9.9.9 }
+          catch { $refused = $true; $err = $_.Exception.Message }
+          if (-not $refused) { throw 'BG0575 404 control: a tag with no asset did not refuse' }
+          if ($err -match 'transport error') {
+            throw "BG0575 404 control: a 404 was read as a transport error - the status is not being extracted from the exception. Got: $err"
+          }
+          Write-Host "BG0575 404 control OK - fell back, found no digest, refused: $err"
+          Pop-Location

.github/workflows/release.yml

@@ -0,0 +1,102 @@
+# Publish the release assets the verified install path depends on (BG0575, CR0545).
+#
+# WHY THIS IS A WORKFLOW AND NOT A COMMAND SOMEBODY RUNS. The installers verify a download
+# against a `.sha256` sidecar published beside it. GitHub serves no sidecar next to a generated
+# source archive, so before this file existed the sidecar could never resolve and the documented
+# `SDLC_STUDIO_REQUIRE_CHECKSUM=1` install refused at every version. The repair is to publish our
+# own archives and their digests - which only works if they are published EVERY time. The v4.1.0
+# Release carries zero assets and v5.0.0 was tagged with no Release at all, both by a person
+# meaning to and not doing it. A repair that is correct and depends on somebody remembering is
+# the same defect one version later, so it binds to the tag rather than to a runbook line.
+#
+# Determinism: `git archive` output is a function of the tree AND the compressor invocation, so
+# the commands here are pinned to the byte. `--format=tar.gz` uses git's internal gzip rather
+# than whatever `gzip` is on the runner, and the digest recorded is taken from the file actually
+# uploaded - never recomputed elsewhere, so the pair cannot disagree.
+name: release
+
+on:
+  push:
+    tags:
+      - 'v*'
+  # The manual leg exists for a tag pushed before this workflow did - v5.0.0 is one - and as the
+  # recovery path when a publish fails halfway. It is deliberately the exception: a step anybody
+  # can forget is the step this file exists to stop being forgettable.
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Existing tag to publish assets for (e.g. v5.0.0)'
+        required: true
+
+permissions:
+  contents: write        # required to create a Release and upload its assets
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        with:
+          fetch-depth: 0
+
+      - name: Resolve the tag being published
+        id: tag
+        # The dispatch input reaches the shell through `env:` rather than by interpolation.
+        # `${{ }}` substitutes BEFORE the shell parses, so a crafted tag would be script rather
+        # than data - only write-access holders can dispatch this, but the house style does not
+        # make that the thing standing between an input and `set -euo pipefail`.
+        env:
+          INPUT_TAG: ${{ inputs.tag }}
+          REF_NAME: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          tag="${INPUT_TAG:-$REF_NAME}"
+          git rev-parse -q --verify "refs/tags/$tag" >/dev/null \
+            || { echo "no such tag: $tag" >&2; exit 1; }
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
+
+      - name: Build the release assets from the tag
+        id: build
+        run: |
+          set -euo pipefail
+          tag="${{ steps.tag.outputs.tag }}"
+          prefix="sdlc-studio-${tag#v}/"
+          mkdir -p dist
+          git archive --format=tar.gz --prefix="$prefix" -o "dist/sdlc-studio-$tag.tar.gz" "$tag"
+          git archive --format=zip    --prefix="$prefix" -o "dist/sdlc-studio-$tag.zip"    "$tag"
+          # The digest is taken from the uploaded file itself. Deriving it any other way is how
+          # bytes and sidecar drift, which presents to a user as `Checksum mismatch` - a message
+          # indistinguishable from an attack.
+          for f in "dist/sdlc-studio-$tag.tar.gz" "dist/sdlc-studio-$tag.zip"; do
+            sha256sum "$f" | awk -v n="$(basename "$f")" '{print $1 "  " n}' > "$f.sha256"
+          done
+          ls -l dist/
+
+      - name: Verify the sidecars before anything is published
+        run: |
+          set -euo pipefail
+          cd dist
+          # Refuse to publish a pair that does not already verify. A sidecar that does not match
+          # its own asset would reach users as an aborted install, and this is the last moment
+          # the failure costs nothing.
+          for f in *.sha256; do
+            sha256sum -c "$f"
+          done
+
+      - name: Publish the Release with its assets
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          tag="${{ steps.tag.outputs.tag }}"
+          notes="docs/release-notes-${tag}.md"
+          # A Release may already exist if the tag was pushed before this workflow shipped; upload
+          # into it rather than failing, so an existing Release can be completed rather than
+          # duplicated. --clobber keeps a re-run idempotent.
+          if gh release view "$tag" >/dev/null 2>&1; then
+            gh release upload "$tag" dist/* --clobber
+          elif [ -f "$notes" ]; then
+            gh release create "$tag" dist/* --title "$tag" --notes-file "$notes"
+          else
+            gh release create "$tag" dist/* --title "$tag" --generate-notes
+          fi

README.md

@@ -57,9 +57,11 @@ irm https://raw.githubusercontent.com/DarrenBenson/sdlc-studio/main/install.ps1
 **Installing in a sensitive environment?** The default install tracks `main`, which publishes no `.sha256` sidecar, so the installer warns and proceeds unverified. Pin a tagged release and make the checksum mandatory instead:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/DarrenBenson/sdlc-studio/main/install.sh | SDLC_STUDIO_REQUIRE_CHECKSUM=1 bash -s -- --version v4.1.0
+curl -fsSL https://raw.githubusercontent.com/DarrenBenson/sdlc-studio/main/install.sh | SDLC_STUDIO_REQUIRE_CHECKSUM=1 bash -s -- --version v5.0.1
 ```
 
+What that verifies: an archive this project built from the tag and published as a release asset, against a `.sha256` published beside it in the same step. Both halves are ours, so they cannot drift apart. Tags before v5.0.1 have no published assets and this command will refuse them rather than pretend - see [Verifying the download](docs/INSTALL.md#verifying-the-download).
+
 </details>
 
 <details>

changelog.d/BG0575.md

@@ -0,0 +1,50 @@
+<!-- section: Fixed -->
+- **The documented verified install could never complete, at any version, and now does (BG0575).**
+  README and the website both offer `SDLC_STUDIO_REQUIRE_CHECKSUM=1` with a pinned tag as the path
+  for a reader who will not accept an unverified download. It refused every time. `install.sh`
+  looked for a `.sha256` sidecar beside GitHub's GENERATED source archive, and GitHub serves no
+  such sidecar at any version - so the digest resolved empty, the requirement made empty fatal,
+  and the one command offered to that reader was the one command guaranteed to fail. `install.ps1`
+  carried the identical defect against the `.zip`. Nothing exercised either, so both were
+  consumer-facing from the day they were written and green the whole time.
+  A tagged version now prefers a release ASSET that this project builds from the tag and publishes
+  with its digest in the same automated step (`.github/workflows/release.yml`), so both halves of
+  the pair are ours and cannot drift. GitHub's generated archives are deliberately NOT verified:
+  they are regenerated rather than published, and a recorded digest for one can stop matching with
+  nobody touching the tag - which reaches a user as `Checksum mismatch`, indistinguishable from an
+  attack. Falling back to the unverified archive now happens on a 404 and only on a 404, because
+  reading a fault as an absence silently downgrades a user from bytes we published to bytes we did
+  not. That distinction needed the HTTP status to be READ rather than inferred: `curl -f` exits 22
+  for every status at or above 400, so a 403, a rate-limiting 429 and a CDN 503 were
+  indistinguishable from a genuine 404 by exit code alone - the first version of this fix claimed
+  to separate them and did not. `wget` collapses the same range onto exit 8 and has its `-S` trace
+  read instead. Tags before v5.0.0 have no assets and still refuse, honestly, rather than widening
+  what counts as verified.
+  The regression test drives the shipped `install.sh` end to end with a `PATH`-stubbed `curl` over
+  a local origin - no network, and no base-URL argument added to production for a test's benefit.
+  It has to: a unit test of `verify_download` cannot see this defect, because that function is
+  correct and always was, and the bug is the URL handed to it. **The PowerShell half is not
+  verified locally** - `pwsh` is absent on the development machine - and is covered instead by a
+  green-and-red pair in the `windows-smoke` job, which runs `install.ps1` under real PowerShell on
+  every push. Asserting over the text of `install.ps1` would have been a weaker claim than the
+  criterion, and is not what shipped.
+  Nobody should publish a digest for a generated archive later: a user pinning it via
+  `SDLC_STUDIO_SHA256` would now mismatch against the asset.
+
+<!-- section: Added -->
+- **Releases publish their own assets, and the runbook finally has a step for the release
+  (BG0575, CR0545).** Everything after the tag was un-tooled: `release_cut.py` stopped at
+  `tag-check`, and `reference-sprint-toolchain.md` - the document AGENTS.md tells every session to
+  read BEFORE starting a step - had no row for release at all. It was paid for twice. The v4.1.0
+  Release carries an empty asset list, and v5.0.0 was tagged and pushed with no Release published
+  at all, which matters more than it reads: `version_check.py` polls `releases/latest`, so every
+  installed copy still reported v4.1.0 as current and prompted nobody to upgrade. A tag without a
+  Release is, to the tool's own update mechanism, unreleased.
+  `.github/workflows/release.yml` now builds a `.tar.gz` and a `.zip` from the tag with pinned
+  commands, records each digest from the file it actually uploads, verifies both sidecars before
+  publishing anything, and creates or completes the Release. It binds to the tag push rather than
+  to a runbook line for the reason the history shows: the assets are what the verified install
+  depends on, and a step that depends on somebody remembering is the same defect one version
+  later. A `workflow_dispatch` leg exists for a tag pushed before the workflow did, and for
+  recovery. The runbook gains a Release section naming each command beside the hand-rolled shape
+  it replaces.