flowchart LR
  b1["1 Skill"] --> b2["2 Assertions"]
  b1 --> b3["3 Bounds"]
  b1 --> b4["4 Facades"]
  b1 --> b5["5 Naming"]
  b3 --> b6["6 Result and value lints"]
  b2 --> b7["7 Zeroed padding"]
  b1 --> b8["8 Baselines"]

flowchart TB
  skill["smith-style skill"] --> authors["Authors and agents"]
  lints["xtask production lint set"] --> gate["cargo x check"]
  clippy[".config/clippy.toml values and disallowed list"] --> gate
  arch["cargo x arch: facades, naming"] --> gate
  perf["cargo x perf: floor ratios"] --> report["perf report"]
  authors --> code["Production Smith code"]
  gate --> code

---
id: SMH-PLAN-C_BQ3QLQ
type: plan
title: "Smith Style: Facades, Bounds, Naming, Assertions"
spec: SMH-SPEC-SPEC0001
status: approved
---

# Smith Style: Facades, Bounds, Naming, Assertions

## Intent

Adopt the parts of TigerStyle that fit Smith.
Mechanical checks where a machine can judge; a project-local skill where judgment is needed.
Every check lands green: existing violations are fixed in the same behavior.

## Decisions

- Instructions live in `.pi/skills/smith-style/SKILL.md`, loaded before writing or reviewing production Rust; one line per rule with its reason.
- Checks cover code Smith writes; std and third-party identifiers and APIs we cannot change never fail a check.
- Assertions enforce internal invariants; `Result` carries expected states, including exceeded bounds.
- Every third-party crate is named in exactly one facade module; facades speak Smith types; vocabulary crates stay exempt.
- Every resource has a named bound with units; unbounded APIs are banned by a maintained list that also covers Smith's own unbounded helpers.
- Speed-of-light baselines: each hot-path bench pairs with a floor bench doing only unavoidable work; the acceptable gap is judged and recorded per task, never a fixed factor.

## Mechanical versus instruction

| Rule | Mechanical | Skill instruction |
| --- | --- | --- |
| Assertions | assert messages required | assert pre/postconditions and invariants; pair across encode and decode; compile-time asserts for sizes and constant relations |
| Facades | arch: one module per crate names each dependency | facade APIs shaped for Smith, not mirrors |
| Bounds | disallowed unbounded std and Smith APIs, list maintained | named bound constants; endless loops asserted; recursion only with tested depth bound |
| Naming | arch scan of Smith declarations: banned abbreviations, qualifier-last names | precise nouns and verbs; units last; index, count, size distinct |
| Ignored results | lints against silently dropped results | handle every result |
| Pass by reference | tuned large-value threshold | none |
| Baselines | perf report shows implementation to floor ratio | measure floor first; justify the budget from task difficulty |
| Remaining guidance | none | smallest scope, check near use, nested simple conditions, explicit call-site options, simple return types, control and data plane split, mix-up-prone parameters as newtypes, file order, why and how comments, zeroed padding |

## Behaviors

Ordered by delivery value.

1. Skill: `smith-style` exists and is referenced by deslop and compress.
2. Assertions: RULES line approved; assert-message lint on; key invariants asserted in codecs, store, alloc; compile-time size asserts replace runtime size tests where possible.
3. Bounds: unbounded channel and unbounded read APIs banned in production; each call site moves to a named bound; spinning `next_session_path` loop gets a bound.
4. Facades: arch check lands; each dependency moves behind one module per crate.
5. Naming: arch scan lands with its token list; Smith declarations renamed across the workspace.
6. Ignored results and pass-by-reference lints land with fixes.
7. Zeroed padding: property test that reserved and padding frame bytes are zero.
8. Baselines: benchmarking skill gains the floor method; paired floor benches for frame decode, canonical JSON, provider SSE, proquint codec; `perf.md` reports ratios.

```mermaid
flowchart LR
  b1["1 Skill"] --> b2["2 Assertions"]
  b1 --> b3["3 Bounds"]
  b1 --> b4["4 Facades"]
  b1 --> b5["5 Naming"]
  b3 --> b6["6 Result and value lints"]
  b2 --> b7["7 Zeroed padding"]
  b1 --> b8["8 Baselines"]
```

## Structure

```mermaid
flowchart TB
  skill["smith-style skill"] --> authors["Authors and agents"]
  lints["xtask production lint set"] --> gate["cargo x check"]
  clippy[".config/clippy.toml values and disallowed list"] --> gate
  arch["cargo x arch: facades, naming"] --> gate
  perf["cargo x perf: floor ratios"] --> report["perf report"]
  authors --> code["Production Smith code"]
  gate --> code
```

## Touches

- `.pi/skills/smith-style/SKILL.md` new; `.pi/skills/benchmarking/SKILL.md`, `deslop`, `compress` cross-reference it.
- `xtask`: production lint set, arch facade and naming checks, perf ratio report.
- `.config/clippy.toml`: disallowed-methods list, value thresholds.
- All production crates: renames, facade moves, bound constants, assertions.
- `smith-bench`: floor benches; new budget pins need human approval.
- `.system/RULES.md`: assertion line; needs human approval.

## Risks

- Naming renames churn the whole workspace; land per crate to keep diffs reviewable; wire and serde names stay unchanged.
- Facade moves may cost instructions; budgets gate it.
- The disallowed list rots unless new unbounded Smith helpers are added when written; the skill says so and review checks it.
- Line-based arch scans have documented limits; they catch common cases, review catches the rest.

## Exit

- [ ] Every mechanical check runs in `cargo x check` with zero violations.
- [ ] No third-party crate is named outside its facade module.
- [ ] Every production queue, loop, read, and retry has a named bound.
- [ ] Floor benches exist and each hot-path budget records its judged gap.
- [ ] Instruction budgets hold or are deliberately re-pinned with approval.