/gm-finalize

name: gm-finalize
description: |
  Seal the current tag: snapshot the per-tag working docs into
  docs/tags/<Tag>/, write a CHANGELOG entry, run `git tag`, and reset
  per-tag runtime state for the next /gm-gdd round. Does NOT package a
  release — that lives in a separate skill.
  Explicit invocation only — use /gm-finalize.
disable-model-invocation: true

GodotMaker Finalize

$ARGUMENTS

You are sealing the **current tag** (vX.Y.Z) so the next `/gm-gdd` round can start cleanly. This is a per-tag operation, not a "the game is finished" operation. The user may continue to the next tag right after, or stop here — either way, this tag's deliverables are now archived and git-tagged.

Session Setup

**FIRST ACTION — before anything else:** Write `finalize` to `.godotmaker/current_role`.

Resume Check

Read `.godotmaker/stage.jsonl` (treat as empty if missing) — each line is `{"role": X, "ts": Y, ...}`.

• If `PLAN.md` does not exist or is missing the `**Tag:**` header → STOP. Tell the user the project is in a bad state; re-run `/gm-gdd` to regenerate the current tag's working docs.
• If **no event with `role == "accept"` and `decision == "accept"`** exists anywhere in the file → STOP. Tell user to run `/gm-accept` first.

(Events with `decision == "fix"` or `decision == "done"` are trace records, not completions.)

• If `.godotmaker/final_report.json` exists **and** `git tag <Tag>` already exists → STOP. Tell the user:

> "Tag {Tag} already finalized. Run /gm-gdd to start the next tag, or stop here. > If you need to redo this step or have other plans, just tell me."

• Otherwise → proceed.

Resolve `godot` binary

Read `godot_path` from `.claude/godotmaker.yaml` and substitute it verbatim for `<godot_path>` in every `godot --headless …` command below. The path was validated at publish time and is the source of truth for which Godot binary this project uses.

If `.claude/godotmaker.yaml` is missing the `godot_path` field, fall back to plain `godot` (PATH lookup). If THAT also fails, STOP and tell the user `Godot binary not configured — re-run tools/publish.py to set godot_path in .claude/godotmaker.yaml`. Do NOT spelunk through PATH directories or guess install locations.

Process

1. Read the current tag

Read `PLAN.md`, extract `**Tag:**` header value (e.g. `v0.2.0`). All later steps refer to this as `<Tag>`.

2. Quick Sanity Check

• `"<godot_path>" --headless --quit 2>&1` — builds clean
• `PLAN.md` — no `pending` or `in_progress` tasks; all `verified`
• `.godotmaker/evaluation.json` exists with `result: "approve"`

If any check fails, STOP and tell the user which one — finalize must not seal a broken tag.

3. Document Consistency Check (current tag scope)

Run these fast gates before archiving. For passing gates, continue silently. For failures, update the root doc to match reality and remember the path for `doc_updates`.

• **PLAN.md**: All tasks are `verified`; Tag Mechanics and Inherited Mechanics sections exist.
• **STRUCTURE.md**: `extends Component` and `extends System` filenames under `src/` appear in the component/system listings.
• **ASSETS.md**: Asset paths for current-tag generated rows exist under `assets/` or `references/`.
• **SCENES.md**: Scene paths referenced for this tag exist on disk.
• **MEMORY.md**: If a current-tag discovery is now superseded by the final implementation, mark it `(superseded by …)`.

Apply documentation fixes only. Finalize does not change code.

4. Archive into `docs/tags/<Tag>/`

From the project root run:

python tools/seal_tag.py archive <Tag>

The helper copies per-tag working docs and best-effort runtime evidence:

| Destination | Source | |---|---| | `docs/tags/<Tag>/GDD-snapshot.md` | `GDD.md` | | `docs/tags/<Tag>/PLAN.md` | `PLAN.md` | | `docs/tags/<Tag>/STRUCTURE.md` | `STRUCTURE.md` | | `docs/tags/<Tag>/STYLE.md` | `STYLE.md` | | `docs/tags/<Tag>/SCENES.md` | `SCENES.md` | | `docs/tags/<Tag>/MEMORY.md` | `MEMORY.md` | | `docs/tags/<Tag>/evaluation-final.json` | `.godotmaker/evaluation.json` | | `docs/tags/<Tag>/evidence/e2e/` | `e2e/` excluding `e2e/screenshots/` | | `docs/tags/<Tag>/evidence/screenshots/` | `e2e/screenshots/` | | `docs/tags/<Tag>/evidence/manifest.json` | generated by `tools/seal_tag.py archive` |

Exit codes: 2 if any required document source is missing, 1 if a required document copy fails.

Then verify the archive landed — list `docs/tags/<Tag>/` and confirm all document destination files are present. If a required document destination is missing or has stale content (size or mtime mismatching the source), STOP and report to the user.

Do not Edit/Write these destinations yourself.

Do NOT archive `ASSETS.md`, `.godotmaker/stage.jsonl`, `metrics.jsonl`, or `traces/`.

5. Generate `docs/tags/<Tag>/CHANGELOG.md`

From the project root run:

python tools/seal_tag.py bundle <Tag>

The bundle JSON on stdout has:

• `roadmap_entry` (heading + body from ROADMAP.md for `<Tag>`)
• `plan_tag_mechanics` (list of `<Tag>-Mn` IDs)
• `previous_tag` + `git_log_since_previous_tag` (`--oneline` slice)
• `test_count.unit` (count of `test/**/*.gd`) + `test_count.e2e` (count of `e2e/**/test_*.py`)
• `evidence.archive_path`, `evidence.e2e_files`, `evidence.screenshots`, `evidence.warnings`

Combine that with PLAN.md task table and `evaluation.json` `minor_issues`, and write `docs/tags/<Tag>/CHANGELOG.md` directly. Keep the entry concise. Use this format:

# Changelog — <Tag>

**Released:** <UTC ISO date>
**Theme:** <ROADMAP headline>

## Delivered mechanics

- [<Tag>-M1] <description>
- [<Tag>-M2] ...

## Added systems / scenes / assets

- <bulleted list pulled from PLAN.md>

## Refactored from prior tags (if any)

- <files / systems modified that belonged to a previous tag, with one-line reason>

## Known limitations

- <minor issues from evaluation.json that ship as-is>

6. Generate Final Report

Field sources for the schema below:

• `summary.tag_mechani