mtgodot-poc/.agents/skills/metin2-40250-parity-audit/SKILL.md

name, description

name	description
metin2-40250-parity-audit	Audit, implement, fix, or verify behavioral parity between the Metin2 40250 Windows C++ client and this Godot client. Use whenever a request mentions 40250 comparison, 1:1 parity, missing original-client behavior, parity regressions, or continuing the client audit. Do not use for unrelated features that have no 40250 compatibility requirement.

Metin2 40250 parity audit

Treat the reachable 40250 implementation semantics and its observable behavior as the reference contract. The Godot architecture and APIs may differ, but its gameplay algorithms, branch conditions, state-transition order, constants, units, timing/event sources, resource/data sources, protocol side effects, and failure/cleanup behavior must not differ unless the difference is a documented platform adapter with evidence of semantic equivalence. Compare complete call chains, not filenames or similarly named functions.

Persistent state

The audit ledger is the source of truth:

• audit/manifest.json: current contract states and evidence links.
• audit/history.jsonl: append-only state-change history.
• audit/contracts/: detailed evidence for individual contracts.
• audit/reports/: generated summaries; never treat these as the source of truth.
• audit/remediation-roadmap.md: current repair order, anti-repeat rules, and the next primary contract.

Before auditing, fixing, or claiming parity:

1. Run python3 .agents/skills/metin2-40250-parity-audit/scripts/audit_ledger.py refresh --write.
2. Run python3 .agents/skills/metin2-40250-parity-audit/scripts/audit_ledger.py report.
3. Read the relevant existing contract and tests. Do not repeat a still-valid TEST_VERIFIED audit unless the user explicitly requests revalidation.
4. If no contract exists, add one with a stable behavior ID before marking work complete.

Before selecting the next repair target, read audit/remediation-roadmap.md and the latest relevant history entries. Select by the documented priority and end-to-end user flow, not by whichever local difference is easiest to patch. A contract may not be used to repeat an already completed issue or branch. Every round must select an explicit issue/branch ID using the roadmap's stable format and compare it with audit/history.jsonl before editing. Older contract-level history entries do not prove that every branch in that contract is complete; create the branch-level ID when first selecting it. The same issue/branch ID may be revisited only for a new regression, a substantive implementation change, or new evidence that invalidates the earlier conclusion. The same contract may be selected in a later round when a different remaining branch is selected; contract IDs group behavior and are not deduplication keys. A PARTIAL contract is not permission to repeat already verified work.

Read references/audit-schema.md whenever creating or changing ledger entries. Read references/project-map.md when locating reference code, current implementation, existing gap documents, or test runners.

Full-client inventory gate

This skill covers the complete reachable 40250 client behavior surface, not only the first few reported bugs. Before claiming the audit is broadly complete:

1. Inventory active 40250 runtime areas across UserInterface, GameLib, EffectLib, EterLib, EterGrnLib, PRTerrainLib, MilesLib, EterPack, and EterLocale, then map each externally meaningful behavior to project/, extension/, formats/, resources, and tests.
2. Keep one stable contract ID per externally meaningful behavior, not one per source file. Group helper files under the behavior they implement, but do not omit a reachable behavior because its implementation is spread across several libraries.
3. Put every mapped behavior in audit/manifest.json, including behaviors not yet checked. Use UNMAPPED when no current implementation or reference mapping is established, MAPPED when both entry points are located, and PARTIAL when a material gap is known.
4. Record current-client-only features as EXCLUDED only with an explicit reason that they have no 40250 counterpart and are outside the parity target. Never silently omit them from the inventory.
5. The inventory is incomplete while any active runtime area has no contract entry. A clean test suite or a high percentage of mapped files does not waive this gate.

Audit method

For each behavior:

1. Define the external trigger, preconditions, state transitions, outputs, timing, interruption, failure, and cleanup behavior.
2. Trace the complete reachable 40250 call chain, including resource-driven branches and compile-time feature flags.
3. Build a branch-by-branch equivalence table mapping the reference preconditions, decisions, formulas, state writes, ordering, timing sources, resource reads, outputs, and cleanup paths to the current native extension, GDScript, resources, protocol handling, and UI.
4. Classify every difference as missing, partial, wrong order, wrong value/unit, wrong algorithm, wrong timing/event source, wrong resource/data source, duplicate, platform adapter, or intentionally excluded.
5. Treat automated output equality as necessary but not sufficient: tests can miss branches, so a different algorithm cannot be approved merely because sampled outputs currently match.
6. Fix root mechanisms rather than coordinates, entity IDs, individual assets, one-off timing constants, or simplified approximations.
7. Add or strengthen an automated test that fails before the fix and covers the reference behavior. Include boundary, rejection, interruption, and cleanup paths when they materially affect the behavior.
8. Run the narrow test first, then related subsystem tests, then git diff --check.
9. Update the contract's implementation-equivalence matrix, manifest, fingerprints, and history in the same change. Never mark STATIC_VERIFIED or TEST_VERIFIED without complete equivalence evidence.

For classic network phase audits, run scripts/audit_packet_registry.py together with scripts/audit_phase_dispatch.py. The former compares registered wire header values and static/dynamic kinds; the latter compares Login/Select/Loading/ Game phase branches by numeric value while explicitly reporting transport-control and observer-stream exclusions. A PASS from either script is structural evidence, not proof that handler side effects are equivalent.

Implementation-equivalence gate

Source text and engine-facing APIs do not need to be identical, but the implementation must be semantically unified with 40250. Before verification, prove all of these independently:

• identical effective preconditions and early-return rules;
• identical reachable branch structure and branch outcomes;
• equivalent algorithms and formulas, without simplified substitutes;
• identical state mutations and mutation order;
• identical constants, tolerances, coordinate conversions, and units after explicit platform conversion;
• identical timing authority and event source, such as .msa events rather than replacement timers;
• identical resource, table, and protocol data authority rather than hardcoded substitutes;
• identical network and externally visible side effects and their ordering;
• identical interruption, rejection, rollback, failure, and cleanup behavior.

Permitted differences are limited to documented platform adapters such as C++ containers to Godot collections, DirectX matrices to Transform3D, or Windows input APIs to Godot input APIs. For every adapter, document both sides, the conversion invariant, and a focused equivalence test. If any material item differs or lacks proof, status must remain PARTIAL or MAPPED.

Evidence rules

• MAPPED means only that both sides were located.
• STATIC_VERIFIED requires a documented call-chain and implementation-equivalence matrix covering every material branch. Similar output alone is insufficient.
• TEST_VERIFIED additionally requires meaningful automated behavior tests with a recorded passing result; tests do not waive the implementation-equivalence gate.
• Engine/platform replacement may be EXCLUDED only when the replacement and externally observable verification are documented.
• A source or test fingerprint change makes prior verification STALE; investigate only the affected contracts.
• Existing prose in docs/CLIENT-GAP.md and similar documents is useful evidence, but it is not a current verification state unless represented in the ledger.
• Do not claim that code inspection proves visual, timing, input-feel, driver, or Windows-specific parity. Record those limits explicitly.

Scope and safety

• Preserve unrelated dirty-worktree changes.
• Prefer the active files from the 40250 Visual Studio build; do not audit disabled, third-party, or obsolete code as product behavior without evidence that it is reachable.
• Keep credentials, live-server data, copyrighted binary dependencies, generated captures, and local run outputs out of the ledger.
• Do not change live servers or external systems unless the user requested it.

Completion report

Report the contract IDs changed, reference and implementation call chains, discrepancies fixed, tests run, remaining unverified branches, and resulting ledger status. A subsystem is complete only when its in-scope contracts have no unexplained UNMAPPED, PARTIAL, STALE, or REGRESSION entries.

Also report whether the round followed audit/remediation-roadmap.md, the selected issue/branch ID, why it was not already completed in audit/history.jsonl, and the next priority candidate. Do not claim that a single subsystem is complete merely because its focused tests pass while its ledger contract still has material remaining branches.