Merge branch 'feature/phase-19-ground-swatches-bounds'

.codex/agents/architect.toml

@@ -13,6 +13,10 @@ You are the Lead Systems Architect specializing in Godot 4 and idiomatic GDScrip
 3. **Design:** Define API payload shapes, static GDScript type hints, node hierarchies, and signal flows.
 4. **Log:** Append trade-offs to `docs/architecture/tech_debt_and_optimizations.md`.
 
+## Feature worktree
+
+Before writing a feature document, confirm that the orchestrator has asked the user whether this task should use a Git worktree and supplied the selected project path and branch. If the user has not chosen yet, ask the orchestrator to get that preference before writing. Use the supplied path whether it is a worktree or the current checkout; do not create a worktree or switch branches yourself. Follow `AGENTS.md`.
+
 ### Shared Stage inspector UI
 For an in-stage selected-object inspector, first read `docs/specs/stage_panel_ui_system.md`
 and inspect `scripts/shared/stage_ui/` plus the `stage_panels` theme tokens. Use the existing

.codex/agents/artist.toml

@@ -32,6 +32,8 @@ Clothing currently has no standalone format. Author clothing as layered shapes i
 
 ## Review workflow
 
+Before creating an asset review bundle, confirm that the orchestrator has asked the user whether this task should use a Git worktree and supplied the selected project path and branch. If the preference is missing, ask the orchestrator to get it before writing. Use the selected path whether it is a worktree or the current checkout; do not create a worktree or switch branches yourself. Follow `AGENTS.md`.
+
 Create every unapproved deliverable under `content/review/artist/<request-slug>/`. Use descriptive, versioned filenames and never overwrite an existing production asset unless the user explicitly requests replacement.
 
 Each review bundle must contain:

.codex/agents/designer.toml

@@ -40,6 +40,7 @@ Wait for the user to answer before analyzing or proposing feature work.
 
 ## Editing limits
 
+- **Worktree choice:** Before preparing an accepted phase brief or updating the backlog, confirm that the orchestrator has asked the user whether this task should use a Git worktree and supplied the selected project path and branch. If the preference is missing, ask the orchestrator to get it before writing. Use the supplied path whether it is a worktree or the current checkout. Do not create a worktree, switch branches, or write into another checkout yourself. Follow `AGENTS.md`.
 - You may edit only `docs/ideas/feature_backlog.md` and accepted phase briefs under `docs/plans/` during normal use. Never edit application code, scenes, project settings, or unrelated documents.
 - Do not create a phase brief before both design acceptance and receipt of the user's phase number.
 - Keep idea discussion conversational and concise. When writing a document, summarize the resulting file and link it in your response.

.codex/agents/developer.toml

@@ -9,6 +9,7 @@ You are a Godot 4 / GDScript 2.0 implementation developer. Adhere to coding stan
 
 ## Rules
 
+- **Worktree choice:** Before persistent edits, confirm that the orchestrator has asked the user whether this task should use a Git worktree and supplied the selected project path and branch. If the preference is missing, ask the orchestrator to get it before editing. Use the supplied path whether it is a worktree or the current checkout. Do not create a worktree, switch branches, merge, or edit another checkout yourself. Follow `AGENTS.md` for the selected path.
 - **Targeted Edits Only:** Do NOT output full unchanged files. Output only modified functions, concise diffs, or specific node configurations.
 - **Static Typing:** Enforce explicit type hints for all signatures and variables.
 - **Decoupling:** Follow "call down, signal up".

.codex/agents/uiux.toml

@@ -5,6 +5,10 @@ model_reasoning_effort = "high"
 sandbox_mode = "read-only"
 
 developer_instructions = """
+## Worktree choice
+
+You are read-only and must not create worktrees or write project files. For any handoff that will create project files, confirm that the orchestrator has asked the user whether to use a worktree and supplied the selected project path and branch. Do not require a worktree when the user chooses the current checkout.
+
 ## 0. Editor Visual Style Guide
 
 Before making, mocking, reviewing, or suggesting any Prop Editor or Stickman Editor UI/UX

.codex/agents/writer.toml

@@ -16,4 +16,5 @@ You are a technical writer for Godot 4 / GDScript projects. You document game ar
 
 1. **Targeted Edits Only:** Touch only the specific markdown sections affected by recent changes. Never output full unchanged files.
 2. **Scannable & Technical:** Lead directly with code blocks, tables, and structured lists. Eliminate marketing fluff or generic introductions.
-"""
+3. **Worktree Choice:** Before any persistent documentation work, confirm that the orchestrator has asked the user whether this task should use a Git worktree and supplied the selected project path and branch. If the preference is missing, ask the orchestrator to get it first. Use the selected path whether it is a worktree or the current checkout; do not create a worktree yourself.
+"""

.codex/skills/asset-creation/SKILL.md

@@ -7,6 +7,10 @@ description: "Create or revise Stickman Studio props, stickmen, embedded clothin
 
 Use the `artist` subagent for project graphical-asset and animation work. This skill manages delegation, review, approval, and handoff; it does not replace the Artist's visual judgment.
 
+## Choose a worktree before creating files
+
+Before creating an asset review bundle or other project files, ask whether the user wants this task to use a Git worktree unless they have already stated a preference. For small, self-contained asset changes, offer the current checkout as the default. Wait for the answer before creating a worktree. Follow `AGENTS.md`, and pass Artist the absolute path and branch the user selected, whether that is a worktree or the current checkout. Do not require a worktree when the user declines one.
+
 ## Delegate to Artist
 
 Spawn `artist` with `agent_type: "artist"`. Reuse the same Artist for revisions while it is available. Tell it that other agents may share the workspace and that it must preserve unrelated changes.

.codex/skills/feature-ideation/SKILL.md

@@ -37,6 +37,8 @@ Treat the user's clear statement that they are ready to work on the discussed, s
 
 ## Stage 3: Write and hand off the brief
 
-Once the user is ready and the phase number is known, have Designer create the accepted product/design brief at `docs/plans/phase_<number>_<feature_slug>.md`, following `docs/plans/README.md`. The brief should cover the goal and audience, desired child outcome, behavior/flow and feedback, story or directing value where relevant, success criteria, included and excluded scope, known risks/dependencies, project references, and remaining questions for the spec-pipeline. Keep architecture/API decisions for the architect's later technical specification in `docs/specs/`.
+Once the user is ready and the phase number is known, ask whether the brief and later feature work should use a Git worktree unless the user has already stated a preference for this task. Follow the choice and the `Feature branches and worktrees` rules in `AGENTS.md`; do not create a worktree before the user answers. Use the selected checkout consistently for the brief, later specs, implementation, and verification. Pass its absolute path and current branch to Designer. Do not switch branches or write outside the selected checkout.
+
+Have Designer create the accepted product/design brief at `docs/plans/phase_<number>_<feature_slug>.md`, following `docs/plans/README.md`. The brief should cover the goal and audience, desired child outcome, behavior/flow and feedback, story or directing value where relevant, success criteria, included and excluded scope, known risks/dependencies, project references, and remaining questions for the spec-pipeline. Keep architecture/API decisions for the architect's later technical specification in `docs/specs/`.
 
 Do not overwrite an existing phase brief without the user's direction. Confirm the resulting file exists, update the matching backlog entry to `Planned` with a link to the brief, then tell the user where the plan is using a clickable local file link. Stop there; this skill creates the design handoff, not the technical spec or implementation.

.codex/skills/spec-pipeline/SKILL.md

@@ -5,6 +5,14 @@ description: "Stickman Studio feature workflow: UI/UX and architecture specs, im
 
 ## Execution Logic
 
+### Feature branch and worktree setup
+
+Before creating a worktree for a task, ask the user whether they want one and wait for the answer. For small, self-contained fixes or documentation changes, offer the current checkout as the default; for larger feature phases, explain the benefit of a dedicated worktree. Do not create a worktree before the user chooses. Keep the user's choice for the task from the first persistent artifact through implementation and verification.
+
+Follow the `Feature branches and worktrees` rules in `AGENTS.md`: inspect `git status --short`, the current branch, and worktree list before the first persistent change. If the user chooses the current checkout, stay on its branch. If they choose a worktree, reuse a matching one or create `.worktrees/<feature-slug>` on `feature/<feature-slug>` from the integration branch, including the phase number when known. Do not switch branches, transfer uncommitted changes without direction, or merge automatically.
+
+Pass every delegated agent the absolute selected project path and its branch, whether that path is a worktree or the current checkout. Tell each agent to use it for all repository reads, writes, Godot runs, and visual checks. Do not stop file-writing work solely because the user chose not to use a worktree.
+
 1. **Phase 0a: UI/UX Proposal & Alternative Ideas (User-Facing Features Only)**
    - `@uiux` analyzes the user's initial idea for cognitive friction, accessibility, and kid-friendliness.
    - Before proposing, mocking, reviewing, or suggesting UI/UX changes, `@uiux` reads `docs/guides/editor_visual_style_guide.md` and checks the relevant implemented controls/specs. Treat the guide as the current visual baseline; distinguish implemented behavior from recommendations and explain intentional departures. This also applies to direct `@uiux` requests outside the pipeline.

.gitignore

@@ -1,5 +1,6 @@
 # Godot 4+ specific ignores
 .godot/
+.worktrees/
 .images/
 /android/
 addons/

AGENTS.md

@@ -6,6 +6,17 @@
 - Headless tests + command-line scene playback exist (see "Command-line testing & debug playback" below); the GUI editor runs via `run/main_scene`.
 - **Main scene:** `res://scenes/main.tscn` (set as `run/main_scene` in `project.godot`; hosts the Stickman Editor)
 
+## Feature branches and worktrees
+
+- Before creating a Git worktree for a task, ask the user whether they want this task to use one. Do not create a worktree until they answer. For small, self-contained fixes and documentation changes, offer the current checkout as the default; for larger feature phases, explain why a worktree may help and let the user choose.
+- Read-only discussion and proposals do not need a worktree. Before the first persistent change, inspect `git status --short`, `git branch --show-current`, and `git worktree list`.
+- If the user chooses the current checkout, keep working on its current branch. Do not switch branches, stash, reset, clean, move, or overwrite unrelated work.
+- If the user chooses a worktree, reuse a matching one when present. Otherwise, create `.worktrees/<feature-slug>` with branch `feature/<feature-slug>`, based on the integration branch (usually `main`). Include the phase number in the slug when known, such as `phase-20-stage-search`. Example: `git worktree add .worktrees/phase-20-stage-search -b feature/phase-20-stage-search main`. Confirm the path and branch with `git worktree list` and `git branch --show-current`.
+- If relevant uncommitted changes need to be carried into a chosen worktree, ask how to handle them before proceeding.
+- Pass every subagent the absolute path and branch the user chose, whether that is a worktree or the current checkout. All project reads, writes, Godot commands, and visual checks must target that path. Do not require a worktree when the user chose the current checkout.
+- Do not merge feature branches automatically. Keep each feature branch available for review and merge only when the user asks or the active workflow explicitly authorizes it.
+- `.worktrees/` is a local worktree container and must remain gitignored.
+
 ## Repository layout
 
 - `scripts/` and `scenes/` stay as separate roots with matching feature groups. Editor controllers live in `scripts/editors/{stickman,prop,stage}`; stage, stickman runtime, props, terrain, and speech systems live in `scripts/{stage,characters/stickman,props,terrain,speech}`.

sandbox_theme.json

@@ -159,9 +159,13 @@
       "choice_font_size": 18,
       "choice_min_width": 104,
       "choice_corner_radius": 12,
+      "choice_content_inset_x": 8,
+      "choice_content_inset_y": 6,
       "compact_choice_height": 50,
       "compact_choice_preview_height": 22,
       "compact_choice_font_size": 16,
+      "compact_choice_content_inset": 4,
+      "compact_choice_content_separation": 2,
       "compact_grid_gap": 6,
       "compact_layout_max_width": 600,
       "compact_layout_max_height": 460,

scripts/shared/stage_ui/stage_ground_finish_chooser.gd

@@ -33,6 +33,10 @@ var _grid_gap: int = 8
 var _compact_choice_height: int = 54
 var _compact_choice_preview_height: int = 22
 var _compact_choice_font_size: int = 16
+var _choice_content_inset_x: int = 8
+var _choice_content_inset_y: int = 6
+var _compact_choice_content_inset: int = 4
+var _compact_choice_content_separation: int = 2
 var _compact_grid_gap: int = 6
 var _compact_layout_max_width: int = 600
 var _compact_layout_max_height: int = 460
@@ -107,6 +111,10 @@ func _configure_theme_values() -> void:
 	_compact_choice_height = _theme_int("compact_choice_height", 50, 48, 72)
 	_compact_choice_preview_height = _theme_int("compact_choice_preview_height", 22, 16, 36)
 	_compact_choice_font_size = _theme_int("compact_choice_font_size", 16, 14, 20)
+	_choice_content_inset_x = _theme_int("choice_content_inset_x", 8, 4, 20)
+	_choice_content_inset_y = _theme_int("choice_content_inset_y", 6, 3, 16)
+	_compact_choice_content_inset = _theme_int("compact_choice_content_inset", 4, 3, 12)
+	_compact_choice_content_separation = _theme_int("compact_choice_content_separation", 2, 0, 8)
 	_compact_grid_gap = _theme_int("compact_grid_gap", 6, 4, 12)
 	_compact_layout_max_width = _theme_int("compact_layout_max_width", 600, 440, 760)
 	_compact_layout_max_height = _theme_int("compact_layout_max_height", 460, 360, 640)
@@ -158,7 +166,9 @@ func _build_choice_buttons() -> void:
 		button.focus_mode = Control.FOCUS_ALL
 		_apply_choice_style(button)
 		var contents := VBoxContainer.new()
+		contents.name = "ChoiceContent"
 		contents.set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT)
+		contents.clip_contents = true
 		contents.add_theme_constant_override("separation", 4)
 		contents.mouse_filter = Control.MOUSE_FILTER_IGNORE
 		var sample := GROUND_PREVIEW.new() as StageGroundFinishPreview
@@ -327,13 +337,28 @@ func _apply_choice_density(compact: bool) -> void:
 		var button: Button = _choice_buttons[finish_id] as Button
 		button.custom_minimum_size.y = target_height
 		_apply_choice_style(button)
+		var inset_y: float = float(_compact_choice_content_inset if compact else _choice_content_inset_y)
+		var content_separation: int = _compact_choice_content_separation if compact else 4
+		var label_height: float = 18.0 if compact else 20.0
+		var available_preview_height: float = maxf(
+			16.0,
+			target_height - inset_y * 2.0 - label_height - float(content_separation)
+		)
+		var preview_height: float = minf(target_preview_height, available_preview_height)
+		var contents: VBoxContainer = button.get_node_or_null("ChoiceContent") as VBoxContainer
+		if contents != null:
+			contents.offset_left = float(_choice_content_inset_x)
+			contents.offset_top = inset_y
+			contents.offset_right = -float(_choice_content_inset_x)
+			contents.offset_bottom = -inset_y
+			contents.add_theme_constant_override("separation", content_separation)
 		var sample: StageGroundFinishPreview = _choice_previews[finish_id] as StageGroundFinishPreview
 		if sample != null:
-			sample.custom_minimum_size.y = target_preview_height
+			sample.custom_minimum_size.y = preview_height
 		var label: Label = _choice_labels[finish_id] as Label
 		if label != null:
 			label.add_theme_font_size_override("font_size", target_font_size)
-			label.custom_minimum_size.y = 18.0 if compact else 20.0
+			label.custom_minimum_size.y = label_height
 
 
 func _focus_selected_choice() -> void:
@@ -363,9 +388,9 @@ func _choice_box(background: Color, border: Color, border_width: int) -> StyleBo
 	style.border_color = border
 	style.set_border_width_all(border_width)
 	style.set_corner_radius_all(_theme_int("choice_corner_radius", 12, 8, 24))
-	style.content_margin_left = 8.0
-	style.content_margin_right = 8.0
-	var vertical_padding: float = 2.0 if _is_compact_layout else 6.0
+	style.content_margin_left = float(_choice_content_inset_x)
+	style.content_margin_right = float(_choice_content_inset_x)
+	var vertical_padding: float = float(_compact_choice_content_inset) if _is_compact_layout else float(_choice_content_inset_y)
 	style.content_margin_top = vertical_padding
 	style.content_margin_bottom = vertical_padding
 	return style

scripts/stage/sandbox_theme.gd

@@ -134,9 +134,13 @@ func _apply_phase19_defaults() -> void:
 		"choice_font_size": 18,
 		"choice_min_width": 104,
 		"choice_corner_radius": 12,
+		"choice_content_inset_x": 8,
+		"choice_content_inset_y": 6,
 		"compact_choice_height": 50,
 		"compact_choice_preview_height": 22,
 		"compact_choice_font_size": 16,
+		"compact_choice_content_inset": 4,
+		"compact_choice_content_separation": 2,
 		"compact_grid_gap": 6,
 		"compact_layout_max_width": 600,
 		"compact_layout_max_height": 460,