combat-systems-worker

name	combat-systems-worker
description	Implement shared combat-rule systems such as throws, cancels, combo logic, and simultaneous-action ordering.

Combat Systems Worker

NOTE: Startup and cleanup are handled by worker-base. This skill defines the WORK PROCEDURE.

When to Use This Skill

Use for shared combat engine features: generic throws/grabs, HitGrab, cancel windows, IASA/opponent-turn interrupts, combo history/proration, followup legality alignment, priority ordering, trades, and clashes.

Required Skills

None.

Work Procedure

1. Read the feature, its assertions, and the architecture/user-testing docs.
2. Inspect the authoritative Godot combat logic first (hustle/game.gd, hustle/characters/BaseChar.gd, relevant state files), then inspect the current Python sim and tests.
3. Identify the true ownership boundary before editing: ordering in simulation.py, durable state in fighter objects, authored timing in states, and env legality only after runtime truth exists.
4. Add failing targeted tests first. Cover both the direct runtime behavior and at least one training-facing consequence if the feature affects legality or symmetry. Ensure every assertion in the feature's fulfills list is directly proven by at least one test assertion or fixture expectation.
5. Implement the minimum source-backed changes needed. Avoid wrapper-only fixes for runtime bugs.
6. Run targeted tests iteratively, then add at least one deterministic manual sanity check (mirrored same-frame exchange, save/load replay, or scripted combo sequence) and record it.
7. Run manifest validators before handoff.
8. In the handoff, be explicit about what part of the combat chain is now source-backed and what remains blocked by later milestones.

Example Handoff

{
  "salientSummary": "Implemented generic throw/grab primitives plus throw-tech timing and directional throw routing. Updated HitGrab to ride the same primitives and validated the new behavior through simulation and parity tests.",
  "whatWasImplemented": "Added generic grabbed attachment/release behavior, throwability checks, directional throw routing, and tech-window resolution in the simulation/state layers; rewired HitGrab to use those primitives and updated tests for throw-vs-defense and replay stability.",
  "whatWasLeftUndone": "",
  "verification": {
    "commandsRun": [
      {
        "command": "uv run pytest tests/test_simulation.py tests/test_common_states.py -k 'grab or throw or tech' -v",
        "exitCode": 0,
        "observation": "Throw lifecycle and tech-window tests passed."
      },
      {
        "command": "uv run pytest tests/test_env_fidelity.py -k 'grab or throw' -v",
        "exitCode": 0,
        "observation": "Training-facing throw outcomes stayed aligned with runtime behavior."
      },
      {
        "command": "uv run pytest tests/ -v",
        "exitCode": 0,
        "observation": "Full suite passed after combat-system changes."
      }
    ],
    "interactiveChecks": [
      {
        "action": "Ran a scripted close-range throw scenario twice, once mirrored with swapped P1/P2 data.",
        "observed": "Directional routing and throw-tech behavior stayed invariant after mirroring back."
      }
    ]
  },
  "tests": {
    "added": [
      {
        "file": "tests/test_simulation.py",
        "cases": [
          {
            "name": "test_grab_routes_to_back_throw",
            "verifies": "Directional throw routing uses authored facing and input rules."
          },
          {
            "name": "test_throw_tech_only_within_authored_window",
            "verifies": "Throw tech is limited to the source-valid timing window."
          }
        ]
      }
    ]
  },
  "discoveredIssues": []
}

When to Return to Orchestrator

• The feature reveals a broader architectural conflict about where legality/timing should live.
• Source parity requires touching training signoff infrastructure far beyond the assigned combat feature.
• Pre-existing global-parity or physics regressions make the requested combat proof impossible to trust.