Implementor Guidelines

Audience: developers and implementer agents landing changes anywhere in the Stella Ops monorepo. Purpose: the baseline engineering rules every change must satisfy — determinism, provenance, boundary discipline, and the documentation/versioning hygiene that keeps a supply-chain-sensitive, offline-first platform auditable.

Use this alongside sprint task 18 (IMPLEMENTOR-GAPS-300-018). For the binding standards these guidelines summarize, see the repo Code of Conduct (docs/code-of-conduct/CODE_OF_CONDUCT.md) and Testing Practices (docs/code-of-conduct/TESTING_PRACTICES.md).

Determinism & offline posture

• Pin toolchains, seeds, and inputs (inputs.lock); no live network calls in examples or fixtures.
• Prefer UTC timestamps, sorted outputs, and pinned seeds so runs are byte-reproducible.
• Add or update inputs.lock whenever you introduce a new fixture or pack.

Provenance & tenancy

• DSSE-sign schemas and results; keep tenant scoping explicit on every persisted artifact.

Boundaries

• Respect module working directories and the shared-library allowlist; do not edit outside your sprint’s declared scope.

Performance & quotas

• Capture performance budgets and quota impacts when changing hot paths.

Documentation & versioning

• Docs touch rule: every commit/PR carries a docs: tag — either a doc reference or an explicit docs: n/a.
• Schema changes require a version bump and a changelog note.

CI enforcement

• A lint hook (tools/lint/implementor-guidelines.sh) is planned to enforce these rules. It is not yet wired into CI; add it to pre-commit or the CI pipeline when the determinism checks are implemented.