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

name, description, compatibility, metadata

name	description	compatibility	metadata
gig-line-release-qa	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.	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.	project domain version triggers Gig Line release-qa 1.0.0 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

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

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:

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

./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:

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:

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

Verify artifact names/sizes and checksums:

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

Check package contents:

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:

./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:

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

6. Tag and publish

Only after every gate is green:

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:

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 — version, build, tag, CI, publish and rollback sequence.
• 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.