Contributing To Antshiv Engineering Repositories

Changes should be small enough to review, explicit enough to reproduce, and grounded in the behavior the system must produce. This default policy applies to public repositories under the antshiv account unless a repository defines a stricter local policy.

Before Changing Code

• Identify the mathematical, physical, numerical, timing, interface, or product behavior that must remain true.
• Read the current implementation, tests, and canonical HTML documentation.
• Check whether the change crosses repository or submodule boundaries.
• Do not replace a measured hardware or software constraint with an assumption.
• Preserve units, coordinate frames, sign conventions, dimensions, precision, sampling rates, and ownership explicitly.

Implementation Standard

• Keep one coherent behavior change per commit.
• Add or update tests at the boundary where a regression would first appear.
• Fail explicitly when dimensions, capabilities, hardware, permissions, timing, or numerical requirements are invalid.
• Record rejected approaches when they explain an important correctness, locality, stability, or performance decision.
• Do not create planning Markdown files for temporary reasoning. Commit messages preserve change intent; tests preserve behavior; canonical HTML documents the current system; generated reports preserve evidence.
• Markdown is reserved for repository entry points or files required by GitHub and other external tooling.

Commit Message Contract

Use an imperative subject that identifies the changed subsystem and behavior:

area: make the behavior explicit

Why:
State the defect, ambiguity, physical constraint, performance bottleneck, or
architectural risk that required the change.

Mathematics / Physical Contract:
State relevant equations, frames, units, dimensions, precision, discretization,
sampling, saturation, timing, and assumptions. Omit this section only when it
is genuinely not applicable.

Implementation:
Explain ownership, dataflow, interfaces, algorithms, memory, threading, and
hardware behavior changed by the commit.

Hardening:
Explain new validation, fail-closed behavior, regression gates, and ambiguity
removed by the change.

Validation:
List exact commands, fixtures, simulations, models, hardware, thread counts,
and measured results. Distinguish PASS, FAIL, and SKIP. A hardware skip is not
hardware evidence.

Limits:
State what remains unverified, hardware-gated, simulated, unsupported, or
outside the tested operating envelope.

Do not use vague subjects such as update code, fix issue, or changes.

Domain Requirements

Attitude Mathematics

Record quaternion ordering, handedness, active versus passive rotation, intrinsic versus extrinsic sequence, coordinate frames, angle units, normalization policy, singularities, and tolerance.

State Estimation

Record the state vector, process and measurement models, covariance meaning, noise assumptions, Jacobians, discretization, timestamps, update order, observability limits, and numerical stability checks.

Control Systems

Record plant assumptions, sample time, controller form, units, gains, saturation, anti-windup, filters, actuator limits, stability expectations, and simulation or hardware operating envelope.

Dynamics And Flight Systems

Record reference frames, mass and inertia assumptions, force and moment signs, integration method, timestep, environmental model, sensor/actuator behavior, and comparison against analytical, simulation, test-rig, or flight evidence.

Embedded Systems

Record target, toolchain, RTOS or operating system, clocks, memory, peripherals, interrupt and task timing, concurrency, power state, hardware revision, and hardware-dependent test status. Named vendors are evidence examples, not the limits of supported engineering work.

AI, Kernels, And HPC

Record model, precision, layout, reduction order, compiler, ISA, memory and NUMA topology, threads, runtime, hardware, commands, parity criteria, profiler data, and whether measurements came from managed, virtualized, containerized, or bare-metal infrastructure.

Pull Requests

A pull request must make the commit history reviewable without reconstructing intent from chat or temporary notes. Include:

• The problem and required behavior
• Relevant equations, physical assumptions, and interfaces
• Exact validation commands and outcomes
• Hardware or simulation context
• Cross-repository or submodule dependencies
• Known limitations and follow-up evidence gates
• Canonical HTML documentation updated when the current system changed

Generated artifacts should be committed only when they are part of a defined evidence or publication contract.