Dimillian/pokeswift-tuist-refactor-guard

PokeSwift Tuist Refactor Guard

Read AGENTS.md and SWIFT_PORT.md before changing milestone-sensitive code.

Optimize for safe structure changes, not broad churn. Keep public behavior stable unless the user explicitly asked for behavior changes.

Workflow

1. Map the refactor boundary first. Start with git status --short. Identify which layer owns the change: PokeExtractCLI, PokeContent, PokeDataModel, PokeCore, PokeUI, PokeTelemetry, or App/PokeMac. Prefer one ownership slice at a time.

2. Preserve the target graph. Do not invent new targets unless the user explicitly needs an architectural change. Prefer moving logic inside existing targets and files that already compile under the current Project.swift. Keep façade APIs stable when splitting oversized files so downstream call sites do not drift unnecessarily.

3. Refactor by feature slice. Split large files along existing seams: app shell into coordinator, router, path, scene, or input bridge pieces; runtime into state, title, field, dialogue, scripts, battle, telemetry, or save extensions; UI into scene, shared view, render, and props-builder files. Keep extracted helpers close to the current target-owned boundary.

4. Regenerate Tuist immediately after moves or deletions. After renames, deletions, or new source files, run tuist generate --no-open before deeper validation. In this repo, stale generated project references are a common failure mode after file moves.

5. Validate in layers. Run the smallest relevant focused tests first. Then run the broader workspace or app build that matches the refactor surface. If scripts mutate generated metadata, restore or regenerate it before final staging.

Refactor Patterns

• GameRuntime-scale changes Keep the façade stable. Extract extensions by domain such as +State, +Title, +Field, +Dialogue, +Scripts, +Battle, +Telemetry, or +Save.

• PokeUI scene cleanup Separate scene props, stage views, overlays, and shared primitives. Do not move gameplay logic from PokeCore into SwiftUI views.

• PokeMac shell changes Split host concerns such as lifecycle, commands, launch orchestration, and activation behavior without changing gameplay ownership.

• PokeExtractCLI and content-loading changes Keep extraction deterministic and runtime consumption explicit. Do not let a refactor hide a schema change.

File Checklist

• Read Project.swift, Workspace.swift, and Tuist.swift before making graph-sensitive changes.
• Read AGENTS.md for repo constraints.
• Read SWIFT_PORT.md if the touched code affects milestones, parity boundaries, or shipped scope.
• Inspect the owning target under Sources or App before moving code.

Validation Matrix

• After file moves, deletes, or additions: Run tuist generate --no-open.

• For runtime or shared logic refactors: Prefer xcodebuild -workspace PokeSwift.xcworkspace -scheme PokeSwift-Workspace -derivedDataPath .build/DerivedData test.

• For UI-only refactors: Run the smallest relevant PokeUITests or PokeRenderTests, then build PokeMac.

• For app-shell changes: Build with ./scripts/build_app.sh. Use ./scripts/launch_app.sh only when native run behavior is part of the refactor risk.

• For extractor-adjacent refactors: Run ./scripts/extract_red.sh and focused extractor/content tests if the change could affect generated artifacts or content loading.

Failure Shields

• Do not hand-edit generated Content/Red/** files to compensate for refactor fallout.
• Do not trust swift test; this repo validates through the workspace.
• Do not leave file moves unverified; regenerate Tuist immediately.
• Do not widen a refactor into behavior changes unless the user asked for both.
• Do not move code across target boundaries casually; check dependencies in Project.swift first.
• Do not edit generated Xcode artifacts as a source of truth.

Review Mode

When reviewing a proposed refactor:

• Check whether the write set crosses too many targets at once.
• Look for hidden contract changes in schemas, save models, telemetry, or generated content.
• Confirm the public API remains stable where the refactor claims behavior preservation.
• Ask whether tuist generate --no-open was run after moves.
• Treat stale project references, missing target membership, and broken workspace builds as first-class findings.

Output Expectations

Report these points clearly:

• refactor boundary
• target ownership
• whether the Tuist graph stayed stable
• validation run
• residual risks, especially around moved files, generated content, and unverified runtime paths