ScCsgoKnives: project instructions

# ScCsgoKnives: project instructions

One shared instruction source for Codex and Claude Code. Updated 2026-10-06.

Quality goal: preserve accepted functionality and compatibility while making responsibilities clear, dependencies directional, state ownership explicit, failures recoverable and behavior verifiable. Reduce actual maintenance cost; avoid abstraction for its own sake.

## Scope and current truth

- Follow the user's active request. Explain/review/diagnose requests do not authorize implementation, installation or release publication by themselves.
- Preserve explicit user requirements, including specified behavior or implementation choices and requirements the user adopts from images/documents. Keep those requirements separate from inferred goals, cause hypotheses and technical recommendations. Do not silently replace a requirement with a supposedly better alternative or a similar outcome. Explain any conflict or infeasibility; obtain direction only when a material departure is necessary, while continuing independent authorized work.
- Preserve existing accepted behavior: fixes, refactors and optimizations must not silently remove features or change gameplay, input timing, resource quality, data meanings or compatibility scope. Preserve unrelated dirty work. On both Windows and VPS inspect `git status --short` before editing in a Git checkout; never reset, restore, stash or commit someone else's work as routine cleanup.
- Historical dated requests are provenance, not current commands or permission to resume blocked milestones. Specialist documents below resolve superseded rules; consult release evidence relevant to the change.
- Define acceptance from the user's actual scenario before implementing: link each requirement to its implementation, a check that distinguishes it from an incorrect alternative, and its current result. Cover explicitly named actors, views, inputs and platforms; a similar case is not a substitute. Review requirement compliance first, scenario coverage second, and test results/regressions third. Passing tests never make an unmet requirement complete. Report partial work as partial, with concrete blockers; do not quietly defer requested cases or ask again for settled decisions. Every claimed passing test must have an executed runner, result and input identity.
- Do not install packages into the user's Mods/device, modify original worlds, patch third-party providers or delete source assets/backups without task-specific authorization.

## Branch, commit and merge workflow

- Before the first edit for a new feature, bug fix or any other code-changing task, create a new task branch from the agreed baseline. Continue that task on its branch; never implement directly on `main`. Apply this workflow to project-policy changes too.
- The synced tree has one checked-out branch at a time, so tasks run there one after another; a second concurrent task uses its own Git worktree outside the synced tree, on Windows. Before switching branches: commit or set aside every change (uncommitted edits travel with the checkout), confirm no other writer is active, both peers are idle without sync errors, and no game or test job is running; after the switch, wait for synchronization. A branch does not isolate the shared tree.
- Every commit must follow Conventional Commits: `<type>(<optional scope>): <description>` (for example, `feat(tactical): add airdrop guards`, `fix(travel): preserve gun state`, or `docs: clarify branch workflow`). Keep commits focused, reviewable and limited to the task's own changes.
- After completing the scoped changes and applicable verification, commit and push the task branch to its corresponding remote branch. Report the branch, commits, verification and any remaining acceptance gaps for review.
- Merge into `main` only after the user explicitly approves merging that specific task's changes. Approval to develop, commit or push is not merge approval; approval for a previous task does not carry over. Until approval arrives, leave the changes on the remote task branch and do not merge or enable automatic merging into `main`.
- Use PRs and manual, change-appropriate verification; follow [Git review and release tags](docs/agent-guide/git-and-release.md). GitHub CI is disabled by user choice; do not reintroduce automatic CI or required status checks without a new user request.

## Code quality and architecture

- Verify the current baseline and reproduce defects before making the smallest sufficient change. State what may change and what must remain; inspect affected callers, data, protocols and supported conditional builds. Keep unrelated fixes, fixture corrections and structural changes separately reviewable and reversible; do not bundle unrelated optimization or broad rewrites.
- Keep business rules as independent as practical from UI, rendering, transport and engine APIs. Entry points coordinate validation, rules and feedback; do not keep accumulating complex rules or transactions in giant update methods, callbacks or loaders. Avoid new dependency cycles; justify necessary exceptions.
- Give each state one authoritative owner, with explicit player/world/session/process scope. Define how mirrors are synchronized and invalidated instead of letting duplicate mutable copies become competing authorities. Use clear contracts across layers, not mutual callbacks to keep hidden state consistent.
- Reuse established transaction, protocol and lifecycle guarantees across every affected entry point. Verify actual effects, including relevant silent refusal, partial mutation, exceptions and repeated calls. Never report partial completion as success or hide failure by swallowing exceptions. Roll back when safe; otherwise retain traceable recovery obligations without guessing, losing or duplicating state. A code rollback does not itself restore persisted data.
- Define creation, invalidation and release for state, callbacks, subscriptions and resources. Cover affected player departures, disconnects, world exit/re-entry and repeated cleanup; stale cleanup must not affect a new owner/session or valid process resources. Bound asynchronous requests as appropriate by timeout, count and session identity. Distinguish unknown outcomes from confirmed non-execution; do not blindly retry side effects.
- Align sender, reader, domain and total-message limits with supported legal data while rejecting malformed/oversized input. Give sustained remote inputs a validity lifetime. Verify affected normal operation as well as legal maxima, stale input and boundary rejection; do not remove limits merely to pass a test.
- Introduce abstractions only for a concrete responsibility and real use; prefer existing reliable mechanisms and simple implementations. Improve touched legacy boundaries under regression protection without turning a small fix into a core rewrite. Review structural changes for new cycles, duplicate authority, transaction bypasses and unjustified cross-layer dependencies; use dependency analysis when core boundaries change. File length, warning counts and test counts alone do not establish quality.
- Defect regressions should distinguish the old error from the fix and protect normal neighboring paths through production behavior. Preserve authentic historical fixture formats/provenance; assert rejection reasons or stages, not just any rejection. Do not fabricate prerequisites, weaken assertions or alter product protections to make tests green.
- Check entrypoints must actually invoke the maintained runners for the relevant products and supported configurations. Report passed, failed, missing prerequisites and not run separately; neither a build nor CI configuration proves behavior checks executed. Do not blindly include historical installation, cleanup or release tools. Keep concrete findings and progress in the current task brief, not this policy.

## Windows and VPS

- Windows project: `E:/projects/ScCsgoKnives`; raw source assets: `E:/projects/CSMCReverse`.
- VPS active source tree: `/home/dev/source-sync/ScCsgoKnives`. Old `/home/dev/workspaces/*` trees are legacy and partly cleaned, not current edit/build roots.
- Windows desktop agent handles user media, planning and review; readily visible/audible changes default to user acceptance under the verification rules below. VPS agent verifies causes against code and implements scoped changes. Treat visual diagnoses as hypotheses until verified.
- Maintain one current decision/implementation brief per active workstream, separating user requirements, proposed changes, evidence and unfinished acceptance. Update it in place; handoffs must preserve the requirements, not replace them with a planner's interpretation. Keep one consistent current status; mark obsolete conclusions as historical rather than leaving contradictory completion claims. Use short handoff prompts linking the brief, not chains of mandatory old plans. Do not turn optional ideas into unrequested systems. Follow [collaboration](docs/agent-guide/collaboration.md).
- Both hosts may use Git under the workflow above, but the files are one shared set: a checkout, merge, pull, reset or stash on one host arrives on the other as uncommitted edits. Operations that rewrite shared files therefore run from one host only, Windows at present; VPS Git stays read-only (status, diff, log) or goes through Windows jobs. Text files are LF on both hosts (`.gitattributes`); never let a checkout rewrite line endings. Syncthing shares source, scripts, small descriptors/docs and handoffs; each host keeps its own `.git`, excluded from Syncthing.
- One writer per file at a time. Before handing off, stop the previous writer and verify both peers have no sync errors, pending items or conflicts. OWNER/task notes are not locks.
- Keep models, textures, recordings, packages and bulk AnimationData on Windows. Run resource parsing/conversion/full builds via Windows worker; return bounded JSON/logs/previews. Do not copy the resource tree to VPS to satisfy missing Linux paths.
- For pictures/video, remote jobs or cross-agent handoff, read [collaboration](docs/agent-guide/collaboration.md) first. Use [the task template](docs/agent-guide/TASK_TEMPLATE.md) under `docs/tasks/`.
- A media path or base64 dump is not proof an agent saw an image. Video keyframes need timestamps; do not infer timing/audio correctness from sparse stills. Do not assume automatic agent messaging or dispatch exists.
- Follow `.stignore.shared`; `.psh` and `.xdb` are included, large binary assets/output/caches are not. Do not broaden synchronization as a workaround for resource processing.

## Persistent game and data contracts

- Preserve existing gun/knife/skin IDs, ordering, package identities and permanent gun records; never recycle identities or reset player state to solve a bug.
- No automatic player-world backups/snapshots, including compatibility/migration paths. Players back up manually; preserve existing user backups.
- Current capacity family uses layout 6 / schema 7, reserves 0/1023 and preserves legacy meanings.
- Starting with the official 1.4.0 release, all official releases must support direct bidirectional save switching between any pair, with compatible platforms/dependencies: load, save and return without mod-caused errors or state loss/reset. Preserve unavailable newer content for restoration. Before each release, verify against every earlier official release from 1.4.0 using actual released binaries/hashes; failures block release. Pre-1.4.0 versions are excluded from this mandatory matrix; this supersedes older compatibility-scope rules.
- Before touching saves, IDs, inventory, growth, durability, charge or migration, read [compatibility](docs/agent-guide/compatibility.md). Design 1.4.0 and later readers/writers to preserve future data within the release contract; validate conversions and refuse unsafe formats outside that contract before writes. Never guess missing/corrupt records.
- First-person CS weapons use CS2 resources and real skinned hands. Preserve original-quality source resources and derive editions separately. Do not re-enable the old CS:MC/block-hand route.
- For models, poses, shaders, materials, audio, caches or appearance integrations, read [rendering/resources](docs/agent-guide/rendering-and-resources.md) before changes.

## Build and verification

- Before builds/tests/resource processing or packaging, read [build/release](docs/agent-guide/build-and-release.md).
- On Windows run project tooling through `./tools/dev.ps1 <command> <arguments>`; temporary files stay under `.tmp/dev-temp`. VPS source-only trees cannot perform every resource-dependent build.
- Test standalone functionality on an isolated copy of **SurvivalcraftAPI 1.9.3.1**. Use **1.9.3.2_MP only for multiplayer functionality or a concrete affected multiplayer compatibility check**; do not use its single-player mode as a substitute for 1.9.3.1 acceptance merely because its automation is convenient. For changes affecting both, verify standalone behavior on 1.9.3.1 and the affected multiplayer behavior on MP separately. If 1.9.3.1 tooling is missing, adapt the scoped harness or report that specific test gap; do not silently switch platforms. Record the actual engine version/build with every runtime result. This applies to both Windows and VPS and supersedes older task scripts/plans that default standalone tests to MP.
- Iterate narrowly: minimal reproduction → affected code/build → focused verification by the least costly adequate method → freeze a candidate → applicable final release/compatibility gates. Do not run the full multi-edition build/resource/package pipeline after each fixture or script edit. Reuse unchanged artifacts/evidence only with matching source, tool, configuration and dependency identities. Repeat broad checks only for changed inputs, new failures or unresolved concerns, and state which results became invalid. This does not waive required final gates. Documentation-only edits need no release pipeline.
- Choose verification by what must be proved, not merely the size of the edit. For text, icons, HUD layout/color/scale and other readily observable low-risk changes, perform relevant code/resource/build checks and hand the user a candidate with two or three concrete observation points; do not launch the game solely to collect a screenshot. Animation, holding poses, smoke appearance and audio feel normally use user visual/listening acceptance, with targeted agent runtime probes only for specific unresolved behavior. Hidden correctness (ammo, damage, durability, material consumption, saves, duplicate effects and synchronization) remains the agent's responsibility; use meaningful offline checks where sufficient. A visual change with hidden state implications needs both forms of verification.
- Before launching a game test, briefly identify the exact question and why inspection/offline checks cannot answer it, or identify the applicable mandatory runtime gate; this is an explanation, not a new permission request. Engine callbacks, input timing, runtime-only third-party interactions and multiplayer may require isolated game runs. Batch independent checks on the same platform/candidate into one session where state can be reset safely; restart only for changed binaries, isolation, lifecycle coverage or another concrete reason. Do not build extensive automation merely to replace a quick user visual check.
- Distinguish code/build checks, automated behavior checks and pending user visual/listening acceptance. A user-reviewable candidate is not full acceptance, but pending user observation must not stop independent authorized work. Preserve explicit user requests for agent-run reproduction or recordings. The user-acceptance default supersedes older blanket demands for agent gameplay capture on every cosmetic change; actual data-integrity and applicable runtime/release gates remain required.
- Verify test prerequisites (input delivery, camera/type, position, inventory, terrain and dependencies as applicable) before long scenarios. Stop dependent checks when setup fails; repair and rerun the smallest relevant probe first. Preserve failed attempts and diagnose intermittent failures; rerunning until green is not evidence of a fix. Do not weaken assertions or use test-only compensation to conceal a product defect.
- Preserve user-accepted functionality. Do not repeat unaffected specialist acceptance or expand into unrelated work without a concrete dependency or regression reason; required final gates still apply. Missing third-party inputs block only the dependent diagnosis/acceptance: complete independent in-scope implementation and contract tests, and explicitly distinguish those from untested target compatibility.
- Deliver requested installable packages in root `output/`, using the current manifest; don't ship incremental leftovers. Keep technical revision/schema notes out of player-facing names.
- Standing user authorization (2026-09-29): after applicable release gates pass, directly replace the current latest matching packages in `output/` under their ordinary names; do not ask for repeat output-replacement approval. This is not installation, public upload, arbitrary version-bump or original-world-write permission. Never label partial/unverified work complete.
- After verified output replacement, clean this task's obsolete/reproducible intermediate packages, copied sources, builds and derived test assets without repeat approval. Resolve exact paths, check active jobs and build dependencies, retain compact evidence and protected originals/fixtures/worlds. Follow the cleanup safeguards in [build/release](docs/agent-guide/build-and-release.md); never delete `.tmp` wholesale.
- Clean as you iterate (user, 2026-10-05), without waiting for delivery: when a new dev build/stage supersedes the previous one, delete the superseded one (keep the build the user is currently testing); once comparison sheets/previews are made from raw capture frames, delete those raw frames and keep the sheets, result JSON and logs. Same safeguards; record removals in the task's cleanup receipt.
- Do not silently change Full/Lite/Mini scope, resource quality or optional addon ownership. Check actual current package metadata/hashes; old release labels are not current versions.
- Do not add overloads to methods tests resolve using `GetMethod(name)`; use distinct method names.
- Self-tests may run before BlocksManager registration. Graphics resources needed by terrain workers must be prepared on the main/graphics thread.
- Report changed behavior, requirement coverage, tests and remaining uncertainty. Distinguish static checks, native loading, offline rendering, real Windows gameplay and Android acceptance. For prolonged or repeated iterations, summarize measured build/test time, worker waits, fixture rework and environment failures separately where available; mark unknown time as unknown. Use that evidence to remove repeated work, not arbitrary deadlines or reduced functional coverage.

## Instruction maintenance

- Keep this file short and current. Put new task status in `docs/tasks/`, details in specialist/release documents, not another dated override here.
- [Maintenance and official sources](docs/agent-guide/README.md) explains loading behavior and historical conflict resolution.
- Complete pre-refactor files are in `docs/agent-guide/history/`. Do not load the whole history at startup or treat it as active instructions.