reznok/gmcabilitysystem/gmas-maintain

Behavior below was verified against GMC 2.3.x and GMAS 1.4. Confirm signatures in this project's own headers (paths are relative to each plugin's root, e.g. Source/GMCCore/Public/Components/GMCReplicationComponent.h); GMC's source is not part of this plugin.

This skill is for a checkout of reznok/GMCAbilitySystem (the SessionStart hook says "This is the GMAS plugin repository"), not for a project that consumes GMAS: that is gmas:gmas-setup and gmas:gmas-upgrade. The repository has three branches, one automated job, no compile CI (GMAS depends on the paid GMC plugin, so every build happens on the maintainer's machine), a spec suite that runs headless from a downstream project, and this Claude Code plugin under Claude/gmas/. docs/BRANCHING.md is the operative document; this skill condenses it and adds the plugin. Paths are relative to the repository root unless noted.

Branches

Fork commits are merged, never cherry-picked, so every later merge stays small and a merge commit records what arrived; an unwanted fork change is git reverted on dev afterwards. Your own change: build locally, push dev; if the push is rejected because a sync landed meanwhile, pull and push again. Consumers add GMAS as a submodule (gmas:gmas-setup has the commands: -b dev to follow integration, -b main for releases only); the plugin's internal name GMCAbilitySystem does not depend on the folder name. Fixes go upstream, then the consumer bumps its submodule pointer; no patch lives inside a submodule.

The DeepWorlds sync

.github/workflows/sync-deepworlds.yml runs daily at 06:00 UTC and on demand (Actions tab, Run workflow, with a dry_run box). It checks out dev with full history and runs .github/scripts/sync-deepworlds.sh (bash, ubuntu runner; sync-deepworlds.ps1 next to it is the PowerShell port for local runs on Windows: same behaviour, environment and gh calls, so change both together) with GH_TOKEN set to the job token (contents, pull-requests and issues: write; labels live in the Issues API). GitHub runs schedule triggers from the default branch only, so the workflow and .github/scripts/ must exist on main as well as on dev; whichever copy runs, it operates on dev. The script fetches DeepWorldsSA/DeepWorlds_GMCAbilitySystem dev and does one of three things:

All three exit 0; only fetch, push-after-retry and gh failures fail the job (and email the maintainer). Environment, defaults in parentheses: UPSTREAM_URL (the fork), UPSTREAM_BRANCH (dev), UPSTREAM_REMOTE (deepworlds), TARGET_BRANCH (dev), SYNC_BRANCH (sync/deepworlds), DRY_RUN (false); GH_TOKEN is required unless DRY_RUN=true; GH_REPO is set by the workflow (owner/repo) so gh targets this repository, while a local run lets gh infer it from origin; the Markdown report goes to GITHUB_STEP_SUMMARY when set, else to stdout. Preconditions it checks: TARGET_BRANCH checked out, clean tree, full (not shallow) clone.

Dry run locally, in a full clone of dev with a clean tree and network. It adds or re-points a deepworlds remote in your clone, fetches, reports, pushes nothing and opens nothing; a trial merge is reset to ORIG_HEAD. PowerShell, then bash:

$env:DRY_RUN = 'true'; powershell -NoProfile -ExecutionPolicy Bypass -File .github/scripts/sync-deepworlds.ps1; Remove-Item Env:DRY_RUN DRY_RUN=true bash .github/scripts/sync-deepworlds.sh

Expected while the fork is quiet: ## Sync DeepWorlds: up to date. Otherwise dry run, would merge N commits (…) with the overlap list, or dry run, N commits conflict in M files with the files.

Harness. powershell -NoProfile -ExecutionPolicy Bypass -File .github/scripts/tests/sync-deepworlds.test.ps1 for the PowerShell port, bash .github/scripts/tests/sync-deepworlds.test.sh for the bash script: each builds throwaway repositories under a temp dir and stubs gh with a shim first on PATH that logs its calls (gh.ps1 for the port); no network. T1 to T8 cover up to date, clean merge dry and live, conflict dry and live, PR update, a manual resolve closing the PR, a push rejected once, a real non-fast-forward race and a non-canonical origin. Final line 44 passed, 0 failed for both. Run both after any change to either script, and add a case to both for every new branch.

Resolving a conflict PR. Never press Merge on GitHub: the PR carries the unresolved fork tip and exists only to hold the report and the branch. Resolve in your clone:

git fetch origin dev sync/deepworlds git checkout dev git pull --ff-only git merge --no-ff origin/sync/deepworlds # resolve conflicts, build locally, then git push origin dev

Keep the fork's version of a shared fix and every local addition; the merge commit is where that choice is recorded. The next run finds the fork tip in dev, closes the PR and deletes the branch. If the fork moves while the PR is open, the branch is force-updated and the title and body recomputed; resolve against the newer tip.

Specs

Tests live in their own module, Source/GMCAbilitySystemTests/ (UncookedOnly: built for the editor and uncooked targets, never into a cooked or Shipping game; since 1.4.1, before that Source/GMCAbilitySystem/Private/Tests/): twenty-two GMAS_<Area>Spec.cpp files (533 cases under GMAS.* on 1.4.1, all passing), the shared GMAS_TestHelpers.h (attribute builders, clock seeds) and the UGMAS_Test* stub classes they configure through class defaults (UGMAS_TestAbility, UGMAS_TestCostEffect, UGMAS_TestMovementCmp, UGMAS_TestEventRecorder, UGMAS_TestCountingEffect, …). Each spec is a BEGIN_DEFINE_SPEC / END_DEFINE_SPEC block guarded by #if WITH_DEV_AUTOMATION_TESTS, flags EAutomationTestFlags::EditorContext | EAutomationTestFlags::ProductFilter, named GMAS.Unit.<Area> (GMAS.Stress.* for the combinatoric ones); the gameplay tags they register are GMAS.Test.*, GMAS.BugFix.* and GMAS.Cond.*. Expected logs are declared with AddExpectedErrorPlain (literal): AddExpectedError is a regex, and a bracketed tag would be a character class. The runtime module keeps the …ForTest seams under WITH_AUTOMATION_WORKER. This repository has no runner: the specs need an engine and a project with GMC enabled.

Headless run, from a downstream project with GMC and GMAS enabled, editor closed:

UnrealEditor-Cmd.exe <Project>.uproject -ExecCmds="Automation RunTests GMAS;Quit" -unattended -nullrhi -log

One LogAutomationController line per test and a summary land in Saved/Logs/<Project>.log; -ReportExportPath=<dir> writes the JSON and HTML report. Narrow with a +-joined substring list (GMAS.Unit.Effect+GMAS.Unit.Duration). Mechanics and the stub harness: gmas:gmas-testing.

Known failing set (1.4.0). About 150 cases fail by design: GMAS.Unit.Attribute*, GMAS.Stress.*, GMAS.Unit.ModifierMath and the GMAS.Unit.Ability cooldown case. Their helpers build FAttribute values with the default FAttributeClamp (bClampMin and bClampMax true, Min and Max 0: Public/Attributes/GMCAttributeClamp.h), which 1.4 applies as a [0, 0] pin, so every value reads 0 (gmas:gmas-attribute). The runtime is right; the fix belongs in the helpers (set Max, or clear the flags), never in FAttributeClamp. Until it lands, the promotion gate is "the same pass/fail set as the last promotion": compare the summary with the previous run and treat any name outside the set as a regression. When the set changes, update it in gmas:gmas-testing, gmas:gmas-upgrade, this section and the release notes' Known issues.

Adding specs. New behavior ships with a spec in the same folder: GMAS_<Area>Spec.cpp, same guard, flags and naming; stub configuration written to class defaults in BeforeEach and restored in AfterEach; time advanced by writing ActionTimer and calling TickActiveEffects then ProcessAttributes(true) (GMAS_DurationSpec.cpp is the model; GMAS_BugFixSpec.cpp and GMAS_ClientAuthSpec.cpp for server-operation and client-auth paths). When the behavior sits behind a role or replay decision the stub cannot produce, add a …ForTest seam at the bottom of Public/Components/GMCAbilityComponent.h, inside the existing #if WITH_AUTOMATION_WORKER block: a thin wrapper around the private function or a bForce…ForTest flag, never a change to the shipped path. Seams prove that a branch runs, not that the network takes it; anything about two machines is a networked PIE test in a downstream project (gmas:gmas-testing).

Promoting and releasing

main's 1.3 history is a squash, so a plain merge of dev conflicts; a promotion is a merge commit that carries dev's tree exactly (the 1.4 release is one: two parents, tree identical to dev's). Steps:

1. Gate. Build at least one downstream project against dev and run the specs headless (above); the failing set equals the known set. The plugin check (check.ps1 or check.sh, below) ends N passed, 0 failed: the plugin ships with every promotion.
2. Versions and plugin content, on `dev`. Bump VersionName in GMCAbilitySystem.uplugin ("1.4" to "1.5"; the tag adds the patch). Write the release notes and, from the same header diff (git diff v1.4.0 origin/dev -- Source/GMCAbilitySystem/Public), extend gmas:gmas-upgrade with a ## 1.4 → X.Y section (its Later releases section says how), re-tag (1.4+) facts across the skills where they changed again, update the known failing set in gmas:gmas-testing, and the hook's generation probe if the marker header (Public/Utility/GMASBoundQueueV2.h) moves. Then bump version in Claude/gmas/.claude-plugin/plugin.json: at least a patch bump whenever plugin content changes; X.Y.0 when GMAS's minor version changes. Claude Code updates an installed plugin only when that string changes, and the marketplace is read from main, so a promotion without the bump ships nothing to plugin users. The twelve verification notices (Behavior below was verified against GMC 2.3.x and GMAS 1.4) are re-verified and bumped with a GMAS minor release and left alone for a patch release. Push dev.
3. Promote. PowerShell, then bash:

git fetch origin $NEW = git commit-tree 'origin/dev^{tree}' -p origin/main -p origin/dev -m "Release X.Y: promote dev to main" git push origin "${NEW}:main"