# Dragginzgame Engineering Baseline
Shared Tooling is the authoritative source of mandatory common engineering rules
and canonical shared tooling for all `dragginzgame` repositories. This file is
normative for automated contributors. Keep it compact; the
[shared principles](docs/principles/README.md) explain the decision tests.
Consumer choices described in those guides remain subject to this baseline.
## Adoption and local authority
- Every consumer must adopt a reviewed revision through a recorded local snapshot
or explicit revision-bound reference. Their AGENTS.md must identify that baseline
and the local overlay. A moving sibling checkout is not hidden inheritance.
- Shared rules govern engineering practice. Product architecture, identities,
numeric limits, validation gates and release identities stay local. Release
target names and workflow follow the common contract below. Do not copy one
consumer's architecture into the common baseline.
- Local overlays may strengthen the baseline or define product-specific choices
within its delegated scope. A change to an explicit common rule, including
command authority or delivery cadence, requires a maintainer-approved exception
with scope and reason; calling it stricter does not bypass that requirement.
- Apply the shared baseline and the local overlay within its delegated scope.
Local instructions do not silently override the common baseline.
Read the current handoff for accepted work and implementation status. Treat
historical documents as evidence, not current authority. Verify documentation
against implementation; distinguish supported behavior from unfinished plans.
- Every repository must have a concise, accurate GitHub description of its
current purpose and scope, consistent with its README and implementation.
Review it during baseline adoption and whenever the repository's purpose,
scope or maintenance status changes. Correct missing, stale or misleading
descriptions; do not present retired behavior or planned features as current.
## Scope and authorization
- Work within the authorized repositories and preserve unrelated dirty work.
Re-read dirty files before editing. Inspection does not authorize mutation;
siblings are read-only unless a named mutation is explicitly authorized.
- Never create or amend Git commits, directly or through helpers. The maintainer
owns commits. Inspect scripts before invoking targets that may commit.
- Agents may execute package/manifest version changes, tags, pushes, publication,
deployment and paid effects when explicitly authorized for their target and effect.
Continuation and readiness requests do not supply that authority. Commits
remain maintainer-owned, including inside otherwise authorized helpers.
- An explicit instruction is sufficient for its named action. Carry established
authorization forward; do not require magic phrases or repeated confirmation.
Complete authorized preparation so any required approval concerns a concrete
result. Recording feedback does not authorize upstream messages or writes.
## Ownership and simplification
- Prefer deleting an obsolete mechanism, reusing its canonical owner or narrowing
an existing contract before adding a concept. More abstraction, more tests and
fewer lines are not goals in themselves.
- Give each state, identity, policy and invariant one authoritative owner. Carry
decisions structurally; consumers project rather than reconstruct them. Keep
independent validation at real trust, corruption and recovery boundaries.
- New modes, flags, caches, registries, traits and state machines need a
demonstrated requirement, a canonical owner and a simpler alternative check.
Do not build a framework to remove a little repetition or support hypothetical
consumers. No change is a valid outcome when the need is unproven.
- Trace callers and failure contracts before merging similar flows. Preserve
ordering, authorization, atomicity, recovery and platform constraints. Generated
code is changed at its generator, then regenerated by the authorized workflow.
- Dependencies own their established contracts; do not reproduce them downstream.
Libraries must not silently claim consumer endpoints or lifecycle ownership.
## Complete, reviewable changes
- Ordinary continuation resumes the accepted coherent in-repository batch through
its directly required implementation, focused checks, propagation and cleanup.
Do not impose a one-slice-per-turn stop. Stop at new independent scope or a
release boundary; continuation does not authorize starting another release line.
- Deliver one coherent outcome with its directly required implementation,
rejection/recovery evidence, callers, fixtures, documentation and cleanup.
Split independent outcomes, not compiler fallout or each proof of one change.
- Contract changes must trace producers, consumers, codecs, generated artifacts,
persisted data and installation/recovery helpers. Reuse the canonical encoder
rather than reconstructing its payload in another path.
- Remove superseded paths completely when their obligations permit retirement.
Name any remaining consumer or deployment blocker and the evidence needed to
close it. Do not leave replacement and old implementation indefinitely active.
- When cleaning up code, list every removed function, method and type in the final
user-facing output, including private symbols and those inside deleted files.
Give exact names, their former file or module, why each was removed and its
replacement when applicable. Distinguish deletions from moves or renames.
Shared reasons may be grouped, but every removed name must still be listed.
- Complete changelog maintenance under the [common changelog rules](rules/changelogs.md)
as part of the coherent batch, including automatically selecting and maintaining
the numbered next release at the top. Do not wait for a separate notes request.
## Pre-1.0 contracts
- Pre-1.0 is a hard cut: maintain one current contract. No deprecated aliases,
compatibility shims, dual readers/writers, legacy fallbacks, staged deprecations
or migration engines for superseded repository-owned models.
- Repository-owned models are unversioned or V1 before 1.0. No V2 or higher,
parallel aliases or hidden versions such as Next/New/Legacy/Compat or numbered
modules. This does not prohibit package versions or external standard versions.
- Breaking public API or semantic changes require a minor release before 1.0;
a hard cut does not make an incompatible patch acceptable. Select the pending
changelog version automatically under the common rules; changing package
versions or executing a release remains an explicitly authorized consumer action.
- Never reuse a wire/storage discriminator for an incompatible layout or interpret
retained bytes under a new layout merely because both contracts use V1.
A hard cut identifies the frozen format,
producers, consumers and retained installations, and coordinates their update
and explicit retirement/reset disposition before replacing the current contract.
Pre-1.0 is not proof that stored data or external consumers are disposable.
- Hard cuts do not remove same-contract interruption recovery, backup/restore,
uncertainty or external obligations. Never discard the only record of effects,
assets, balances or liabilities merely to remove old source. Product-specific
transition and retirement procedures remain local; do not invent a migration
engine or another reader to avoid resolving their prerequisites.
## Validation and evidence
- Use the [shared audit methods](audits/README.md) for reusable code-hygiene,
structural and module reviews. Keep product invariants and validation commands
in consumer overlays. Audit adoption adds no automatic broad gate or schedule;
findings do not supply repair authority. Preserve historical reports locally.
- Run the smallest relevant checks automatically during authorized development.
Broad workspace, full CI and release gates run only when explicitly requested
or in their configured CI pipeline. Local command lists must distinguish focused
checks from those complete gates; continuation and readiness do not authorize them.
- Check for active builds before compilation or source mutation. Do not change
source under active validation or compete for its build lock. Use the owning
repository's build directory; preserve unrelated artifacts.
- For offline validation, prepare caches for the selected lockfile explicitly
before validation or release mutation. Preserve lock selection and report
preparation failures. Network use and dependency upgrades require their own
authority; do not silently retry offline failures online or select new versions.
- Test maintained observable behavior, typed failures and genuine architectural
boundaries. Delete tests that only prohibit a removed name or remember an old
implementation. Source inspection can enforce a live architectural invariant;
private layout, error prose and fixed test counts are not behavior contracts.
- Bind evidence to its actual source, inputs, dependencies, artifacts and commands.
Distinguish source review, mocks/substitutes, local execution and live observations.
Retain failed/inconclusive attempts and limitations; a rebuild or new release
never relabels old evidence. State measured results separately from expectations.
- Where external effects need interruption recovery or reconciliation, persist
intent and exact identity before dispatch; define precise retry/replay semantics.
A lost reply is not proof of failure and does not authorize repetition. Preserve
required recovery without adding journals to tools that do not need them.
- Enforce structured facts, schemas, hashes and executable behavior in guards.
Do not freeze explanatory prose or require manual status-marker rotation.
## Release commands
- Every `dragginzgame` repository, including Shared Tooling, must expose
`make release-patch`, `make release-minor` and `make release-major`.
All three use the same [release contract and Makefile pattern](docs/releases.md):
preflight, validate, bump and finalize the changelog, stage, commit and tag,
then push. Only the selected semantic-version component differs.
- Keep one release workflow per repository. The three entry points must delegate
to it; do not give patch releases an implicit fast lane or change effects by
repository. Consumer-owned validation gates, metadata files, branches and
remotes are explicit inputs, not alternate meanings for the commands.
- These are maintainer-owned one-shot commands. Agents must not execute them
because they create commits. Separate preparation and inspection remain
available within their authorized effects; adding targets is not a release.
- Use standard semantic-version increments: patch increments the patch; minor
increments the minor and resets the patch; major increments the major and
resets both lower components. Apply the pre-1.0 compatibility rule above.
- Stop on failure and preserve build and evidence artifacts. Preflight or
validation-only failures restart through the normal target against current
source with fresh preflight and complete validation; retain earlier evidence.
Persist exact release intent before preparation may begin, then reconcile an
interrupted release automatically when a normal target is rerun, at its saved
version and commit. If that release is already committed and HEAD has newer
fixes or a different increment is requested, reconcile it first, then run fresh
preflight and complete validation for the requested increment from the actual
local version. Late evidence checks use the selected `RELEASE_COMMIT`, which
may precede HEAD. Select unfinished intent before computing another increment;
stop for identity, payload, destination or concurrency conflicts.
Do not force-push, overwrite tags, silently bump again or add implicit package
publication, deployment or post-release cleanup.
## Changelogs and artifact preservation
- Before editing a changelog, read and apply [the changelog rules](rules/changelogs.md).
They are part of this mandatory baseline and own release-note content, issue
links, draft/history preservation and detailed-note structure.
- Releases and deployments preserve consumer-owned build and evidence artifacts
on success, failure and retry. Never append cargo clean or equivalent cleanup.
Cleanup requires explicit scope and authority. Tools may clean temporary files
they own; they must not erase consumer artifacts or the only retained evidence.
## Rust workspaces and portable tooling
- Provide [local developer setup](docs/local-setup.md) through explicit
`make install-tools` and offline `make tools-check`, including pinned jq and
Mike Farah yq under `.tools/host/bin`. Make/CI callers select the local tools;
document system bootstrap packages and product toolchains separately.
- Provide the [common local IC executable setup](docs/ic-tools.md) through
`make install-ic-tools` and offline `make ic-tools-check`. Keep the common tool
names available under the checkout's `.tools/ic/bin`, with one reviewed pin
matrix and explicit installation. Consumers own version qualification and
scoped pin exceptions; ordinary validation never downloads tools implicitly.
- Apply the [dependency pinning rules](rules/dependency-pinning.md): immutable
Git/action identities, compatible registry requirements with locked builds,
verified tool downloads, and explicitly qualified sibling or moving inputs.
Run the declaration checker in CI and release gates; consumers own the chosen
versions, approved exceptions and runtime qualification evidence.
- Cargo workspace members inherit package versions from the root. Apply the
[Cargo dependency rules](rules/cargo-dependencies.md): every direct dependency
is declared in root `[workspace.dependencies]`, and every child manifest uses
`workspace = true`, including development, build and target-specific tables.
Keep version/source selections in the root; children select target conditions,
features and publication policy. Do not upgrade a toolchain or raise MSRV
without an established need and appropriate validation.
- Follow the [Rust hygiene baseline](docs/principles/rust-code-hygiene.md): narrow
visibility, documented APIs/invariants, ordinary module discovery, bounded
fallible decoding and typed errors. Exact edition, layout and lint choices stay
local. Do not fake platform behavior with production cfg(test) paths.
- Rust repositories adopt the [standard formatting hook](rules/git-hooks.md):
`make install-hooks` enables a reviewed repository-local pre-commit hook that
auto-formats and refreshes only selected files, rejects partial staging and
preserves unrelated working edits. Formatting includes `cargo sort --workspace`
for root and child manifests before Rust formatting. Keep matching `fmt-check`
sorting and Rust checks in CI and release gates;
hook activation and independent formatting qualification are separate checks.
- Keep shell wrappers small and declare dependencies and effects. Use the
project's maintained implementation language for substantial tooling. Do not
add Python tooling. Fail on invalid inputs rather than hiding broken assumptions.
- CI/release tools use [reviewed snapshots](docs/consuming-snapshots.md), not symlinks
or mutable sibling/network sources. Do not patch vendored copies; fix upstream
or keep an explicit consumer-owned adapter outside the snapshot.
- Portable scripts use Bash strict mode and preserve Bash 3.2 compatibility unless
the support matrix is deliberately changed. Downloaded executables need exact
consumer-owned versions, pinned digests, HTTPS, verification before extraction
and a version check before installation. No implicit credentials or targets.
## Host support
- Every `dragginzgame` package must work on macOS. This includes its applicable
dependency setup, native tools, build, test, CI and deployment workflows.
For canister and frontend packages, support includes running their host
workflows on macOS; product runtime targets remain locally owned.
- Consumers declare supported macOS versions and architectures in their local
host matrix. Missing coverage or a macOS failure is a support gap to fix,
not permission to classify macOS as unsupported. Exceptions require explicit
maintainer approval with scope and reason.
- Host-specific dependency installation, CI setup and deployment commands may
differ while preserving the same product contracts, validation obligations,
authorization, recovery and artifact preservation. Document prerequisites and
isolate host differences at their owning boundary; do not assume Linux tools,
paths, package managers or GNU behavior are available on macOS.
- Qualify supported hosts through native CI or recorded native execution of the
relevant workflows. Linux passes, cross-compilation and installer branches
alone do not prove macOS behavior. Align evidence with
[the host guidance](docs/supported-hosts.md) and the consumer's matrix; report
outstanding qualification without weakening the support requirement.
## Feedback and handoff
- Follow the [user-triggered agent maintenance rules](rules/agent-maintenance.md)
when asked to check CI, review issues or inspect for work after completing a
task. Session activation carries forward within its scope; inspection and
repair requests retain their distinct authority.
- GitHub issues in the owning repository are the sole tracker for bugs, feature
requests, review findings, reusable gaps and follow-up work. Search existing
issues before filing; update matching evidence rather than creating duplicates.
Do not create or maintain local upstream issue files, feedback ledgers,
project-prefixed issue IDs or parallel tracking queues. Handoffs and design
documents link to GitHub issues without duplicating triage or issue status.
Supporting evidence stays with its existing owner; it is not another tracker.
- A reusable-gap issue records the reviewed upstream revision, affected owner,
symptom, focused evidence, smallest proposal and disposition. Identify dirty
source separately from a committed revision. Include affected callers/hosts
and the smallest useful verification.
- Track upstream acceptance separately from verified consumer adoption. Resolve
product-specific feedback locally instead of promoting it to universal policy.
Submit feedback or change another repository only within explicit authority.
If issue access or a remote is unavailable, report the finding and blocker to
the maintainer without inventing an issue URL or creating a local tracker.
- Report the outcome, changed files, relevant verification, skipped checks,
remaining risks and open consumer actions. State compatibility and host impact
when relevant. Do not claim a release proves publication, adoption or deployment.