# 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.