security-game/.agents/skills/gig-line-release-qa/SKILL.md

---
name: gig-line-release-qa
description: Use when preparing, validating, tagging or publishing a Gig Line release or release candidate, or when running the full screenshot, screen-design and realism QA gates. Covers version/changelog discipline, smoke and tooling matrices, clean-worktree builds, checksums, Web/HQ verification, publish rollback and post-release records. Do not use for ordinary asset edits or feature work.
compatibility: Gig Line repository checkout with Godot 4.7.2 on PATH and Python 3 + Pillow. Release export needs installed Godot export templates; publishing needs Gitea credentials and is intentionally CI/tag-driven.
metadata:
  project: Gig Line
  domain: release-qa
  version: "1.0.0"
  triggers: release, tag, version bump, changelog, build releases, publish, screenshots, screen design, realism judge, release candidate, deployment
---

# Gig Line Release and Visual QA

Use this skill for version bumps, release candidates, tags, artifact builds,
publishing, and the full visual/QA gate. For a Blender/asset rebuild, use
`gig-line-blender-asset-contract` first.

## Read first

1. `AGENTS.md` — release procedure and verification rules.
2. `TODO.md` — current milestone, blockers and release exit criteria.
3. `docs/process/RELEASING.md` — build/publish commands, artifact list, macOS policy.
4. `docs/process/release-qa.md` — manual QA matrix and balance protocol.
5. `docs/project/development-status.md`, `CHANGELOG.md`, `README.md` — current claims.
6. `MEMORY.md` — release gotchas, especially the clean-worktree rule.

A release is not just a tag. It includes a version bump, changelog, clean build,
artifact/checksum verification, CI publication, and post-release records.

## Hard rules

- **Do not tag while the TODO still lists unresolved release blockers.** Check
  external playtest, legal/AI provenance, signing and target-hardware items.
- **Never reuse a tag.** If a published version needs a fix, bump the patch and
  create a new tag.
- **Build from a clean checkout or detached worktree.** A normal working tree can
  pack ignored `tmp/` and `build/` content into exports, inflating a ~160 MB
  package to 1.6–3.1 GB.
- A tag push triggers CI checks/build/publish. Do not upload manually unless CI is
  unavailable and you have followed the same preflight.
- Do not commit generated realism runs, raw captures, API keys, or build artifacts.
- The vision judge is an optional development aid with external API cost, never a
  hard CI gate.
- Keep `project.godot`, changelog, tag and release asset version equal.

## Release workflow

### 1. Scope and version

Choose the semantic increment from `AGENTS.md`:

- MAJOR: incompatible/removed behavior, save/config contract or core-pillar
  replacement.
- MINOR: new user-facing feature/venue.
- PATCH: fixes and polish.

Update:

1. `project.godot` `config/version`.
2. `CHANGELOG.md` with a dated entry.
3. `README.md`, `PLAN.md`, `docs/project/architecture.md`,
   `docs/project/development-status.md`, `TODO.md`/`DONE.md` and `MEMORY.md` as needed.

For a release candidate, use a prerelease version only if the project policy
allows it and never present it as the final release.

### 2. Preflight

```bash
git status --short
git log --oneline -5
git tag -l "v<version>"
rg -n 'config/version' project.godot
```

Expected: only intended release changes; tag does not exist; version matches the
changelog and planned artifacts.

### 3. Automated checks

```bash
godot --headless --path . --script res://src/test/test_runner.gd
python3 -m unittest discover -s tools/tests -t tools -p 'test_*.py'
python3 tools/check_docs.py
python3 tools/blender_assets.py audit
python3 tools/blender_assets.py fit
python3 tools/npc_proportions.py report
python3 tools/npc_pipeline.py audit
```

Then run the smoke matrix, using isolated user-data directories for
tutorial/campaign:

```bash
for s in smoke_audio smoke_crowd smoke_emergency smoke_npc_budget \
         smoke_plan_verbs smoke_scenario_content smoke_session_shell \
         smoke_timeline smoke_ui_flows; do
  godot --headless --path . --script res://src/test/$s.gd || exit 1
done

XDG_DATA_HOME=/tmp/gig-line-campaign godot --path . --fixed-fps 60 \
  --script res://src/test/smoke_campaign.gd
XDG_DATA_HOME=/tmp/gig-line-tutorial godot --path . --fixed-fps 60 \
  --script res://src/test/smoke_tutorial.gd -- --tutorial

godot --path . --script res://src/test/smoke_movement.gd
godot --path . --script res://src/test/smoke_props.gd
godot --path . --script res://src/test/smoke_focus_radial.gd
```

Use a fresh `$XDG_DATA_HOME` for campaign/tutorial and check the exit code, not
just the log.

### 4. Visual and judge gates

```bash
./tools/check_screenshots.sh
python3 tools/screen_designs.py compare
python3 tools/screen_designs.py judge --model auto   # optional, record model/verdicts
```

For realism/venue work:

```bash
godot --path . --script res://src/test/capture_realism.gd \
  -- --out=res://docs/screens/realism/<run>/after
python3 tools/scene_concepts.py realism --run docs/screens/realism/<run> \
  --judge --model <pinned-model>
```

Requirements:

- Gallery: 21 good / 0 bad; screen judge has no unexplained `diff`.
- Realism runs stay under `docs/screens/realism/` (gitignored); only decisions and
  committed sheets/docs are tracked.
- Record judge model, run count/attempts, spend if exposed, and verdicts.
- Review every `review` verdict; turn layout regressions into fixes or documented
  known limitations.

### 5. Clean build

Commit the release preparation first, then build the committed tree in a clean
worktree:

```bash
git worktree add --detach /tmp/gig-line-release HEAD
cd /tmp/gig-line-release
./tools/build_releases.sh
```

Verify artifact names/sizes and checksums:

```bash
ls -lh build/gig-line-*<version>*
PUBLISH_DRY_RUN=1 ./tools/publish_release.sh <version>
sha256sum -c build/SHA256SUMS-<version>.txt
```

Check package contents:

```bash
unzip -l build/gig-line-web-<version>.zip | head
unzip -l build/gig-line-desktop-hq-<version>.zip | head
unzip -p build/gig-line-desktop-hq-<version>.zip override.cfg
```

Check the runnable Linux and HQ packages:

```bash
./build/gig-line-linux-<version>.x86_64 --headless --quit-after 60
unzip -q build/gig-line-desktop-hq-<version>.zip -d /tmp/gig-line-hq
/tmp/gig-line-hq/gig-line-linux-<version>.x86_64 --headless --quit-after 60
```

Check Web static serving with a local HTTP server and `curl` for `index.html`,
`index.wasm`, `index.pck` and the player docs. Windows/macOS/AppImage/installer
checks require the target matrix; if unavailable, record that explicitly.

Remove the worktree after verification:

```bash
git worktree remove --force /tmp/gig-line-release
```

### 6. Tag and publish

Only after every gate is green:

```bash
git add -A
git commit -m "Release <version> <topic>"
git tag -a "v<version>" -m "Gig Line <version>"
git push origin main "v<version>"
```

CI builds and publishes on the tag. Verify:

- Tag commit equals the release commit.
- CI checks/build job succeeded.
- Release page has the expected 7 assets (Linux, Windows, macOS, NSIS setup,
  AppImage, Web, Desktop HQ).
- Asset names and download links point at the released version.

`tools/publish_release.sh` preflights artifact size/free space, writes SHA-256
checksums, rolls back newly uploaded assets/release on failure, and supports
opt-in retention:

```bash
RETAIN_RELEASES=7 ./tools/publish_release.sh <version>
```

The default `RETAIN_RELEASES=0` never prunes.

### 7. Post-release record

Update `README.md`, `docs/project/development-status.md`, `MEMORY.md`, `CHANGELOG.md`,
`TODO.md`/`DONE.md` and the release page with the built/CI result. Commit the
release record and push. Record any skipped check and the reason; never leave a
tag with unreported missing verification.

## Known gotchas

- **Dirty build inflation:** always use the clean worktree above.
- **`Class ... hides a global script class`:** remove stray `.gd` backups in
  `tmp/`, delete `.godot`, re-import.
- **Screenshot staging:** `capture_ui_states.gd` needs its settle frames and
  staged state; do not capture a paused frame or a stale modal.
- **Judge keys:** OpenRouter calls need `.env`/`OPENROUTER_API_KEY`; never commit
  the key or generated review folders.
- **Tag builds publish automatically:** do not run a second manual publish that
  duplicates assets; use the existing release if re-running.
- **macOS is unsigned unless policy changes:** record quarantine instructions and
  do not claim notarization.
- **Release blockers are real:** external playtest, legal/storefront approval,
  AI-provider rights and target-hardware checks cannot be replaced by green unit
  tests.

## Bundled references

- [`references/release-runbook.md`](references/release-runbook.md) — version,
  build, tag, CI, publish and rollback sequence.
- [`references/qa-gates.md`](references/qa-gates.md) — full command matrix,
  expected results and evidence to record.

## Completion checklist

- [ ] Version/changelog/docs/tag match.
- [ ] No unresolved release blockers for a final tag.
- [ ] Godot, Python, smokes, asset and docs gates pass.
- [ ] Gallery and optional judges reviewed with evidence.
- [ ] Clean worktree build and checksums verified.
- [ ] Linux/HQ/Web checks recorded; unavailable platforms noted.
- [ ] Tag pushed; CI/publish succeeded; seven assets verified.
- [ ] Release record and durable docs committed.