bigpowers 2.87.4 → 2.87.6

package/.cursor/rules/verify-work.mdc

@@ -0,0 +1,190 @@
+---
+description: "Multi-phase UAT gate — cold-start smoke, build, typecheck, lint, tests, step-by-step manual verification, gaps-closure loop. Use after execute-plan or develop-tdd, before audit-code."
+alwaysApply: false
+---
+
+<!-- story: e02s01 e46s03 -->
+<!-- story: e38s05 -->
+<!-- story: e45s05 -->
+<!-- story: e45s09 -->
+<!-- story: e45s13 -->
+<!-- story: e45s40 -->
+<!-- story: e51s03 -->
+<!-- story: e20s04 -->
+<!-- story: e20s06 -->
+
+
+# Verify Work
+
+> **HARD GATE** — No story is "done" until manual UAT for the active story is confirmed with evidence.
+>
+> **HARD GATE** — Do NOT run on `main` or `master`. Use the feature branch from `kickoff-branch`.
+
+Review answers "is the code good?"; Verify answers "does the built thing do what was promised?"
+
+## Modes
+
+- Default: full UAT plus gaps loop
+- --smoke: Cold-start only plus one happy-path flow. Use for hotfixes.
+- --cli: CLI tool verification — replaces cold-start with binary smoke checklist. Use for CLI tools with no server process.
+
+## Risk-Scaled Depth
+
+`verify-work` reads the `risk:` field from the story template (defaults to `P1` if absent) to scale verification rigor:
+- **P0**: Full verify-work multi-phase + `security-review` (step 5) + NFR evidence gate (step 5b).
+- **P1**: Standard verify-work (build, test, lint, step-by-step manual).
+- **P2**: Smoke, typecheck, lint only. Skip tests, security scan, and step-by-step manual UAT.
+- **P3**: Typecheck and lint only. Skip smoke, tests, security scan, and step-by-step manual UAT.
+
+## Process
+
+> **Timing:** `bash scripts/bp-timing.sh start verify-work` at invocation; `bash scripts/bp-timing.sh end verify-work` before handoff.
+
+0. **Branch check** — must not be `main`/`master`.
+
+0a. **Preflight / CI green (HARD GATE — e51s03)** — Run Preflight from `CLAUDE.md` or `BP_PREFLIGHT` (`bp-read-agents.sh`). If PR open: `gh pr checks` (**CI green**). Failure blocks all phases → `quick-fix` or `fix-bug`.
+
+1. Read active story tasks from `specs/epics/<capsule>/eNNsYY-tasks.yaml` and story spec from `specs/epics/<capsule>/eNNsYY-<slug>.md` (countable-story-format, Gherkin in §17). Note the `risk:` level (`P0`–`P3`).
+1a. **Pre-UAT verify validation** — for each task's `verify:` command, run it and detect pattern mismatches before UAT begins. If a grep/awk/jq command fails, check whether the pattern is wrong vs. a genuine failure:
+    ```bash
+    # For a failing grep -q 'PATTERN' FILE, check what is actually in FILE
+    grep 'PATTERN' FILE || grep -n '' FILE | head -20   # show nearest lines
+    ```
+    Report: `"Pattern 'X' not found. Nearest match: 'Y' at line N"` and ask `"Update verify command? [Y/n]"`. Fix before proceeding — a mismatched verify command produces false failures during UAT.
+2. **Cold-start smoke** (if app; skip if P3): stop server, clear caches, boot from scratch.
+3. **AGENTS.md preflight** — if 0a skipped BP_PREFLIGHT, run `bash scripts/bp-read-agents.sh` and use detected command.
+4. Mechanical gates: build → typecheck → lint → tests (from `CLAUDE.md` or AGENTS.md). Skip tests if P2/P3.
+
+> **HARD GATE — One-test-minimum terminal verdict (e45s13):** At least one mechanical gate MUST be a **real terminal-verdict command** (shell exits 0 or non-zero — not prose, not combined log excerpts). Record that command's stdout/stderr from a **single contiguous run** in `specs/verifications/eNNsYY-verify.yaml` under `terminal_verdict`. Bug reports and gap logs MUST NOT merge evidence from multiple runs into one verdict — each failing run gets its own evidence block.
+
+5. **Security scan** (skip if P2/P3) — run `security-review` against the git diff (working tree vs merge-base). Parse findings report. If any HIGH findings with confidence ≥ 8 exist → **block the gate**. Write findings to `specs/security/REVIEW.md`. Allow documented exceptions via `specs/security/EXCEPTIONS.md`. MEDIUM/LOW findings warn but don't block.
+5a. **Blind-spot check** — run `bash scripts/check-blind-spots.sh`. This detects structural quality gaps (verify-gap, test-gap, stale-tag, etc.) beyond percentage coverage. If any HIGH-severity findings exist → **block the verify-work PASS gate**. Findings are written to `specs/blind-spots.json`. MEDIUM/LOW findings warn but don't block.
+5a2. **Completeness critic (e45s05)** — `bash scripts/lib/completeness-critic.sh`. **BLOCKER** aborts merge gate; WARNING → gaps loop; FILLED = evidence only.
+
+5b. **NFR Evidence Gate** (P0 only) — Produces go/no-go output on three dimensions: Performance (response time, throughput), Reliability (error rate, recovery), and Operability (logging, health checks). Reads thresholds from `specs/tech-architecture/eNN-TEST_PLAN_LATEST.md` and writes evidence as OKF verification-report bundles to `specs/verifications/NFR-eNNsYY.json`. FAIL on any dimension blocks the gate.
+6. **Step-by-step UAT** (skip if P2/P3) — one user-observable action at a time.
+7. **Gaps loop** — failures → log → `plan-work` → re-verify. Unaddressed HIGH findings from step 5 feed into this loop alongside other quality gaps.
+
+7a. **Validation gate (e45s09)** — All tasks `status: passing`; evidence in `specs/verifications/`; update `execution-status.yaml`.
+7b. **Reopen-don't-refile (e45s09)** — Regressions reopen existing story/bug — no duplicate capsule entries.
+
+## Verify sub-operations
+
+### Cold-Start Smoke (absorbed)
+
+Stop server, clear caches, boot from scratch; confirm no stale config affects behavior.
+
+### Gaps Loop (absorbed)
+
+After UAT, identify and close any gaps between promised behavior and actual behavior:
+
+- Capture what was promised in the epic task description
+- Document what actually happened (expected vs actual)
+- If behavior doesn't match the promises, log the gap
+- Loop back to `plan-work` or `develop-tdd` to fix the gap
+- Re-verify until all gaps are closed (gaps count = 0)
+
+## UAT dialogue
+
+- Pass: user confirms per step.
+- Fail: capture expected vs actual; do not mark done in `execution-status.yaml`.
+
+## Persist verification evidence
+
+After UAT passes, write structured evidence to `specs/verifications/eNNsYY-verify.yaml`:
+
+```yaml
+story_id: e01s01
+verified_at: "2026-06-11T14:30:00Z"
+verifier: verify-work
+phases:
+  smoke:
+    passed: true
+  build:
+    passed: true
+    command: "npm run build"
+  typecheck:
+    passed: true
+  lint:
+    passed: true
+  tests:
+    passed: true
+    coverage: "94.2%"
+  terminal_verdict:
+    command: "npm test"
+    exit_code: 0
+    captured_at: "2026-06-11T14:25:00Z"
+    note: "Single run — do not merge output from other attempts"
+  manual:
+    steps:
+      - step: "Open /login"
+        expected: "Login form renders"
+        actual: "Login form rendered correctly"
+        passed: true
+  gaps:
+    closed: true
+```
+
+### 5b. OKF wiki LINT (e39s08)
+
+```bash
+for p in specs/skills-wiki/skills/*.md; do s="skills/$(basename "$p" .md)/SKILL.md"; [ -f "$s" ]&&[ "$p" -ot "$s" ]&&echo "STALE: $p"; done
+for p in specs/conventions-wiki/*.md; do [ "$(basename "$p")" = "index.md" ]&&continue; grep -q "$(basename "$p" .md)" CONVENTIONS.md||echo "ORPHAN: $p"; done
+```
+
+> **HARD GATE** — Verification evidence MUST be persisted before marking the story done. No evidence = not verified.
+
+## --cli mode
+
+CLI tools: use `--cli` when no server process. Binary detect + checklist: [REFERENCE.md](REFERENCE.md#cli-mode).
+
+## Verify
+
+→ verify: `find specs/verifications -maxdepth 1 -name '*-verify.yaml' 2>/dev/null | grep -q .`
+
+## Handoff
+READY -> next: audit-code
+Writes: state.yaml handoff.next_skill = audit-code
+
+---
+
+# Verify Work — Reference
+
+## Cold-start smoke
+
+```bash
+# Example — adapt to project CLAUDE.md
+pkill -f "<dev-server>" 2>/dev/null || true
+rm -rf .next/cache node_modules/.cache 2>/dev/null || true
+<run command> &
+sleep 3 && curl -sf http://localhost:<port>/health || echo "BOOT FAIL"
+```
+
+## Gaps template
+
+```markdown
+## Gaps (verify-work)
+
+| Step | Expected | Actual | Status |
+|------|----------|--------|--------|
+| 1 | ... | ... | FAIL |
+```
+
+Feed gaps to `plan-work` as new steps with verify commands, then re-run verify-work.
+
+## CLI mode
+
+For CLI tools where cold-start smoke does not apply. Auto-detected when no server process; or use `--cli`.
+
+**Auto-detect binary name:**
+```bash
+BINARY=$(grep '^name' Cargo.toml | head -1 | awk -F'"' '{print $2}')  # Cargo
+BINARY=$(node -e "console.log(require('./package.json').bin && Object.keys(require('./package.json').bin)[0] || '')" 2>/dev/null)
+BINARY=$(grep '^BIN\s*=' Makefile 2>/dev/null | awk '{print $3}')
+```
+
+**Checklist (replaces cold-start smoke):**
+1. `$BINARY --help` → output contains "Usage"
+2. `$BINARY --version` → matches manifest
+3. README example command → non-empty output
+4. `$BINARY --invalid-flag` → exit ≠ 0 with error message

package/.cursor/rules/visual-dashboard.mdc

@@ -0,0 +1,49 @@
+---
+description: "Start a browser-based dashboard that visualizes architecture, implementation plans, and project status. Persists artifacts in .bigpowers/dashboard/. Reads specs/state.yaml, release-plan.yaml, epics, and planning-status via HTTP API or opencode panel."
+alwaysApply: false
+---
+
+# Visual Dashboard
+> **HARD GATE** — **HARD GATE** — Dashboards are read-only. Do NOT use visualization to make decisions without consulting the source data. 'The chart looks better' is not a decision.
+
+
+Browser-based visual companion for bigpowers. Visualizes architecture, plans, and status.
+
+## HTTP cockpit (YAML SoT)
+
+Start the server:
+
+```bash
+bash visual-dashboard/scripts/start-server.sh
+```
+
+Endpoints:
+
+| Route | Purpose |
+|-------|---------|
+| `GET /api/status?projectDir=<abs>` | JSON: `state`, `release`, `epics[]`, `planning_status`, `active_epic` |
+| `GET /cockpit.html?projectDir=<abs>` | Read-only PM view (planning left, epics right) |
+| `GET /` | Agent-pushed HTML screens (legacy, unchanged) |
+
+Example:
+
+```bash
+curl -s "http://127.0.0.1:PORT/api/status?projectDir=$PWD" | jq .release.version
+```
+
+Implementation: `visual-dashboard/scripts/read-specs-status.cjs` + `server.cjs`.
+
+## Opencode Progress Panel
+
+Projects using bigpowers in opencode can read `specs/state.yaml`, `specs/release-plan.yaml`, and active `specs/epics/*.yaml` directly (no checkbox `### WS1` markdown).
+
+Required YAML keys:
+
+- **state.yaml** — `active_flow`, `active_epic_id`, `git`, `handoff`, `epic_cycle`
+- **release-plan.yaml** — `release.version`, `epics[]` with `id`, `title`, `wsjf`, `file`
+- **execution-status.yaml** — `development_status` map (story/epic → `done` | `pending`)
+- **planning-status.yaml** — discover workflows and `status: done|pending`
+
+## Agent screens (optional)
+
+Push HTML to the dashboard session dir for rich diagrams. See `start-server.sh` for `CONTENT_DIR`.

package/.cursor/rules/wire-ci.mdc

@@ -0,0 +1,380 @@
+---
+description: "CI pipeline setup with bundled, forge-neutral templates and local validation. Detects the forge from the git remote, generates workflows for supported forges, and skips honestly for the rest. The CI equivalent of wire-observability."
+alwaysApply: false
+---
+
+# Wire CI
+
+> **HARD GATE (supported forges only)** — Do not ship a project without CI. Run this skill before first merge to main.
+>
+> On a forge bigpowers ships no templates for, this skill **is not a gate**: it reports the forge, explains what it cannot do, and exits 3. A gate that cannot run must not claim it did. See § Unsupported forges.
+>
+> **HARD GATE** — CI that is untestable locally will break every cycle. Always run `--validate` after generating workflows and `--dry-run` before pushing.
+
+Generate, validate, and test CI workflows. Detects the forge and project type, copies a **bundled** template, and verifies locally before anything reaches CI.
+
+## Forge resolution
+
+`scripts/lib/detect-forge.sh` resolves the forge, first match wins: `BIGPOWERS_FORGE` env var → `forge:` in `specs/forge.yaml` → the `origin` remote URL → `unknown`.
+
+```bash
+bash scripts/wire-ci.sh --detect     # report forge + stack, write nothing
+bash scripts/wire-ci.sh --plan       # show the template that would be used
+bash scripts/wire-ci.sh --apply      # write the workflow
+```
+
+GitHub ships templates (`.github/workflows/`). GitLab, Bitbucket, Codeberg, and Gitea are detected but **unsupported** — `--apply` writes nothing and exits 3.
+
+## Template source — configurable, bundled by default
+
+Templates live in `docs/templates/ci/<forge>/` **inside the bigpowers package**, so there is no network dependency on any third party's repository. Override with `BIGPOWERS_CI_TEMPLATES=/path/to/your/templates`, laid out as `<root>/<forge>/test-build-release-<stack>.yml`.
+
+## What this sets up
+
+1. **Test Build Release workflow** — lint → test → build → release in one `needs:` chain
+2. **`--validate` mode** — YAML syntax, workflow permissions, required secrets, common pitfalls
+3. **`--dry-run` mode** — runs workflows locally via `act` before push
+4. **Failure pattern documentation** — see the table below
+
+Deploy workflows are **not** bundled: they are platform-specific. See [REFERENCE.md](REFERENCE.md) for a worked example.
+
+## Process
+
+### 1. Detect forge and stack
+
+```bash
+bash scripts/wire-ci.sh --detect
+```
+
+Stack detection reads the project root:
+
+| Manifest | Stack | Bundled template |
+|----------|-------|------------------|
+| `Cargo.toml` | Rust | `test-build-release-rust.yml` |
+| `package.json` | Node | `test-build-release-node.yml` |
+| `pyproject.toml` / `setup.py` | Python | `test-build-release-python.yml` |
+| `go.mod` | Go | `test-build-release-go.yml` |
+
+No recognized manifest → exit 3 with the list of manifests it looked for. Do not guess.
+
+### 2. Apply the template
+
+```bash
+bash scripts/wire-ci.sh --apply
+```
+
+**Do not rename the workflow `name:` field** — deploy listens for `"Test Build Release"`.
+
+Edit placeholders after copying: language versions, `APP_TYPE`, `SITE_URL`.
+
+### 3. Unsupported forges
+
+`--apply` writes nothing and exits 3. Your options, in the order the runner prints them:
+
+- point `BIGPOWERS_CI_TEMPLATES` at templates for your forge
+- pin `forge: github` in `specs/forge.yaml` if the remote is misdetected
+- write the CI config by hand
+
+Contributing a `docs/templates/ci/gitlab/` set and adding `gitlab` to `FORGE_SUPPORTED_LIST` is the natural next slice — per-forge command mapping (`gh pr checks` → `glab ci status`) is not implemented yet.
+
+### 4. Validate workflows (`--validate`)
+
+See [REFERENCE.md](REFERENCE.md). Exit codes: `0` clean, `1` YAML syntax errors, `2` warnings only.
+
+### 5. Dry-run workflows (`--dry-run`)
+
+See [REFERENCE.md](REFERENCE.md).
+
+> **act** runs workflows in a local Docker environment — the most accurate pre-push validation.
+> **gh workflow run** sends the workflow to GitHub but does not execute locally.
+
+### 6. Document common CI failure patterns
+
+| Failure | Cause | Fix |
+|---------|-------|-----|
+| `npm publish` fails | `NPM_TOKEN` not set as repo secret | Add `NPM_TOKEN` to repo secrets |
+| `semantic-release` fails on push | Missing `permissions: contents: write` | Add it to the release job |
+| `cargo publish` auth fail | `CARGO_REGISTRY_TOKEN` not set | Add token to env or `~/.cargo/config.toml` |
+| `go vet` fails | Go version mismatch | Use `go-version-file: go.mod` |
+| `cargo clippy` errors | New nightly lints | Pin the toolchain; `cargo clippy --fix` |
+| `act` not found | Docker not running or act missing | `brew install act`; `docker ps` |
+| Hardcoded Node version stale | `.nvmrc` exists but workflow hardcodes | Use `node-version-file: .nvmrc` |
+| Deploy never runs | TBR workflow renamed | Keep `name: Test Build Release` |
+| Release rebuilds binary | Artifact not downloaded | `release` must `download-artifact` from `build` |
+
+## Verify
+
+→ verify: `bash scripts/wire-ci.sh --self-test`
+→ verify: `test -f docs/templates/ci/github/test-build-release-node.yml && test -f scripts/lib/detect-forge.sh`
+→ verify: `grep -q wire-ci SKILL-INDEX.md`
+
+---
+
+# Wire Ci — Reference
+
+## Navigation
+
+| Lines | Section |
+|-------|---------|
+| 1 | Title |
+| 3–20 | Navigation |
+| 21–22 | Examples |
+| 23–39 | Create CI for a Go project (TBR + optional deploy) |
+| 40–49 | Create CI for a CLI tool (TBR only, no deploy) |
+| 50–57 | Validate existing workflows (no generation) |
+| 58–70 | Options |
+| 71–79 | Integration with build-epic |
+| 80–154 | Reference block 1 — test-build-release.yml (Go, excerpt) |
+| 155–204 | Reference block 2 — deploy.yml (generic web app, excerpt) |
+| 205–232 | Reference block 3 — CLI dogfood (big-release pattern) |
+| 233–257 | Reference block 4 — validate script |
+| 258–268 | Reference block 5 — dry-run |
+
+## Examples
+
+### Create CI for a Go project (TBR + optional deploy)
+
+```bash
+# Resolve forge + stack, then apply the bundled template
+bash scripts/wire-ci.sh --detect
+bash scripts/wire-ci.sh --apply
+
+wire-ci --validate
+wire-ci --dry-run
+```
+
+To use your own org templates instead of the bundled ones:
+
+```bash
+BIGPOWERS_CI_TEMPLATES=/path/to/your/templates bash scripts/wire-ci.sh --apply
+```
+
+### Create CI for a CLI tool (TBR only, no deploy)
+
+```bash
+bash scripts/wire-ci.sh --apply
+# Edit release job to download build artifact — see big-release dogfood
+# CLI/library repos: delete deploy.yml; the release job is terminal.
+
+wire-ci --validate
+```
+
+### Validate existing workflows (no generation)
+
+```bash
+wire-ci --validate --check-only
+```
+
+---
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--validate` | Check YAML syntax, permissions, secrets, common pitfalls |
+| `--dry-run` | Run workflows locally via `act` or dispatch via `gh` |
+| `--check-only` | Only validate, do not generate new files |
+| `--type <type>` | Force project type (skip auto-detection) |
+| `--force` | Overwrite existing workflow files |
+| `--no-deploy` | Skip deploy.yml even for hosted stacks |
+
+---
+
+## Integration with build-epic
+
+When `wire-ci` is used as part of `build-epic`:
+
+1. **During develop-tdd**: If the task modifies `.github/workflows/`, run `wire-ci --validate` as a CI dry-run sub-step
+2. **During release-branch**: After push, run `gh run list --limit 1 --branch main --json status,conclusion` to verify CI passes
+
+---
+
+## Reference block 1 — test-build-release.yml (Go, excerpt)
+
+```yaml
+name: Test Build Release
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pipeline-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-22.04
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+      - uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16  # v6.5.0
+        with:
+          go-version: '1.22'
+          cache: true
+      - uses: golangci/golangci-lint-action@55c2c1448f86e01eaae002a5a3a9624417608d84  # v6.5.2
+        with:
+          version: v1.64.8
+
+  test:
+    needs: [lint]
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+      - uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16  # v6.5.0
+        with:
+          go-version: '1.22'
+          cache: true
+      - run: go vet ./...
+      - run: go test ./... -count=1
+
+  build:
+    needs: [test]
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+      - uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16  # v6.5.0
+        with:
+          go-version: '1.22'
+          cache: true
+      - run: go build ./...
+      - run: jq -n --arg sha "${{ github.sha }}" '{sha: $sha}' > deploy-meta.json
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: deploy-meta
+          path: deploy-meta.json
+
+  release:
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    needs: [build]
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+        with:
+          fetch-depth: 0
+      - run: npx semantic-release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+---
+
+## Reference block 2 — deploy.yml (generic web app, excerpt)
+
+```yaml
+name: Deploy
+on:
+  workflow_run:
+    workflows: ["Test Build Release"]
+    types: [completed]
+
+permissions:
+  contents: read
+  actions: read
+
+concurrency:
+  group: deploy-production
+  cancel-in-progress: false
+
+env:
+  SITE_URL: "https://CHANGE-ME.example.com"
+
+jobs:
+  deploy:
+    if: >
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.head_branch == 'main'
+    runs-on: ubuntu-22.04
+    environment: production
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+        with:
+          name: deploy-meta
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          run-id: ${{ github.event.workflow_run.id }}
+          path: deploy-meta
+      # Placeholder deploy step — bigpowers ships no deploy templates and pins
+      # no third-party action. Substitute your platform's own step here, or drop
+      # the deploy job entirely for CLI and library repos. Pin whatever action
+      # you choose to a full commit SHA rather than a tag. (GH #104)
+      - name: Deploy
+        run: |
+          echo "Replace this step with your platform's deploy command."
+          echo "commit=$(jq -r .sha deploy-meta/deploy-meta.json)"
+          exit 1
+      - name: Health check
+        run: |
+          curl -sf "${{ env.SITE_URL }}" || exit 1
+```
+
+---
+
+## Reference block 3 — CLI dogfood (big-release pattern)
+
+```yaml
+  build:
+    needs: [test]
+    steps:
+      - run: make build
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: big-release-${{ github.sha }}
+          path: bin/big-release
+
+  release:
+    needs: [build]
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+        with:
+          name: big-release-${{ github.sha }}
+          path: bin
+      - run: make release   # cross-compile assets only; host binary from artifact
+      - run: big-release release --verbose
+```
+
+No `deploy.yml` — CLI publishes via the release job.
+
+---
+
+## Reference block 4 — validate script
+
+```bash
+for f in .github/workflows/*.yml .github/workflows/*.yaml; do
+  [ -f "$f" ] || continue
+  python3 -c "import yaml; yaml.safe_load(open('$f'))" || echo "FAIL: $f has YAML syntax errors"
+done
+
+for f in .github/workflows/test-build-release.yml; do
+  if grep -q "permissions:" "$f"; then
+    echo "OK: $f has permissions block"
+  else
+    echo "WARNING: $f missing permissions block"
+  fi
+done
+
+if grep -q 'workflows: \["Test Build Release"\]' .github/workflows/deploy.yml 2>/dev/null; then
+  if ! grep -q 'name: Test Build Release' .github/workflows/test-build-release.yml; then
+    echo "WARNING: deploy.yml listens for Test Build Release but TBR name may differ"
+  fi
+fi
+```
+
+---
+
+## Reference block 5 — dry-run
+
+```bash
+if command -v act &>/dev/null; then
+  act push --dry-run -W .github/workflows/test-build-release.yml
+elif command -v gh &>/dev/null; then
+  gh workflow run test-build-release.yml --ref "$(git branch --show-current)"
+else
+  echo "Install act or gh for dry-run"
+fi
+```