launcher/CONVENTIONS.md

sm121-launcher — Conventions

Shared rules for all AI agents. Read before any git operation.

Always Green / Shift Left

Gate failures cost more downstream. Fix them at the source. Preflight MUST pass before every commit. No exceptions. CI MUST pass before every merge. No exceptions. Red gates block all forward work. Invoke fix-or-log immediately.

Preflight: make check (fmt → clippy -D warnings → test → ≤500 lines). CI: gh pr checks (when a PR is open).

Discovered Defects

Found a bug unrelated to your task? Fix-or-log, then proceed.

1. Run quick-fix for trivial data-only fixes.
2. Run fix-bug for logic fixes needing investigation.
3. Commit discovered fixes separately from feature work.
4. Never silently fix a discovered defect inside a feature commit.

Banned Dismissive Phrases

Banned phrase	Action
"pre-existing"	Shifts blame. Fix or log it.
"unrelated to session"	Red gates are never unrelated.
"not introduced by my changes"	Irrelevant if the gate is red.
"out of scope"	Never ignore a red gate.

Project Hard Rules

• Files MUST stay ≤500 lines. make check-lines enforces this.
• Extract submodules when a file approaches 500 lines.
• NEVER add #[allow(...)] attributes. Refactor instead.
• #![deny(clippy::wildcard_imports)] — no use foo::*;.
• NEVER add Co-authored-by footers. Author solely as the user.
• Use Conventional Commits: feat(...), fix(...), docs(...).
• Solve clippy warnings by refactoring. NEVER suppress with allow attributes.

Cluster Safety

The cluster serves live traffic. A model runs at any time. Run sm121 health before stop, power off, or power switch. Confirm with the user that the cluster is idle before proceeding. Never assume the cluster is idle. Verify first. logs, health, doctor, and dry-runs (-d) are always safe.

Shell Quoting

Use shq() for SSH command interpolation. Keep shq() output bare. NEVER wrap it in double quotes. Single quotes inside "..." become literal characters in the path. Use printf for path assembly inside SSH commands. See commit 0208fc1 for the bug this prevents.

Specs

Write all planning output to specs/. Read specs/ before writing code. specs/tech-architecture/tech-stack.md is the project long-term memory. specs/state.yaml tracks session state and active flow.

i18n

fluent-i18n crate, 6 locales: en, ru, es, it, fr, de. Use t! macro with { "key" => value } args. Pluralize via Fluent selectors: { $count -> [one] ... *[other] ... }. set_locale is thread-local. Spawned tasks miss non-en locales. Pass counts as u32 to match the cluster-selected pattern.