# standards and conventions

_Status: direction (Option B decided) — as of 2026-07-17_
_Connects to: [deterministic-gates](deterministic-gates.md), [agent-design-principles](agent-design-principles.md), [never-ask-twice](never-ask-twice.md), [self-improvement-loops](self-improvement-loops.md), [overview](../OVERVIEW.md)_

## Purpose

Defines once, and reuses everywhere, the coding standards and conventions the factory
applies across many languages and frameworks (e.g. Sandi Metz 99-Bottles OOP for all OOP
languages) — so a standard is authored a single time, not redefined per project. Load this
before designing project onboarding, the green command, or any standard-carrying context
packet for a pipeline agent.

## Design

- **Three layers, separated on purpose:**
  1. **The opinion** — language-agnostic prose (the Metz rules themselves). Written once.
  2. **Per-language bindings** — executable configs (`.rubocop.yml`, eslint fragment,
     `ruff.toml`) each tagged with the standard + version it implements. One opinion, N
     bindings: this is where cross-language overlap resolves.
  3. **Per-project adoption** — a project copies the right bindings, wires the green command,
     and records a repo ADR ("adopts `sandi-metz-oop` v2 for Ruby") linking the vault opinion.
- **Layout — Option B (DECIDED).** Opinion lives in the vault as a `convention/` note (the
  cross-project source of truth, per [never-ask-twice](never-ask-twice.md)); executable
  bindings ship in the plugin because they are deployable, git-versioned/diffable artifacts
  and the vault is a knowledge graph, not an artifact store. Precedent:
  `plugins/cc-architect/references/conventions/cc-os-naming.md` (canonical repo copy; vault
  note defers to it).
  ```
  ~/Documents/SecondBrain/convention/sandi-metz-oop.md   # opinion; links to bindings
  plugins/os-sdlc/standards/sandi-metz-oop/
    standard.md            # canonical prose (vault note defers here)
    ruby/rubocop.yml   javascript/eslintrc.json   python/ruff.toml
  ```
- **The residue rule: anything lint-enforceable is in nobody's prompt.** An agent is never
  told the arity/length/naming limit — the green command's linter tells it, only on
  violation, injected into its own next turn (mechanism: [deterministic-gates](deterministic-gates.md)).
  Standing context cost of enforceable rules is therefore zero. Only the *judgment residue* a
  linter cannot check (abstraction choice, "composition over inheritance", pattern selection)
  is ever routed into a prompt — and only into the reviewer's ([pipeline-stages](pipeline-stages.md)).
- **Routing key: standard × language × audience × facet.** Each standard's prose is sectioned
  by facet (interface / implementation / test) and audience-tagged, so the context packet is
  a mechanical section-filter, not a per-session judgment call:
  - **programmer** — gets *nothing* standing; learns quality rules only as gate feedback.
  - **test-writer** — is the interface designer in a red-first pipeline, so it gets test
    conventions **plus the interface facet** (naming, public message shape, arity-as-interface)
    — but not implementation-facing rules (method length, private structure, duplication).
  - **reviewer** — gets the judgment-facet residue; it is the designated judgment actor.
- **How far linting reaches (Ruby, the deep case):** `rubocop` (metrics/style/naming, custom
  cops for house rules), **`reek`** (semantic smells — feature envy, data clumps, control
  coupling; much of "Metz taste" is reek findings), `flay`/`flog` (structural duplication /
  complexity), **`mutant`** (mutation testing — deterministically proves the tests *constrain*
  behavior, keeping the test-writer honest and mechanically answering the "gaming the
  green-assert gate" concern in [pipeline-stages](pipeline-stages.md)). JS (eslint+plugins) /
  Python (ruff) are shallower but workable. Ceiling: tools detect **symptoms, not choices** —
  they police the boundaries of good code; the reviewer polices the choices within them.
- **Pre-seeding, not just mining.** The Mobbin move from [never-ask-twice](never-ask-twice.md)
  generalizes: our own standards are self-sourced pre-seeds — writing `convention/sandi-metz-oop`
  up front lets the "OOP approach" decision category start at `afk-ready` instead of being
  re-asked per project. This is the concrete cure for "defined Metz a dozen times."
- **Sequencing (hard constraint):** all of this is **post-tracer-bullet**. v1 nails the flow
  with disposable code and trivial prompts; standards/gate-tuning land afterward, alongside
  [self-improvement-loops](self-improvement-loops.md). Do not add quality gates before the
  happy path is trusted.

## Open questions

- **Adoption/update ownership.** First-time adoption (copy bindings, wire green command) is
  naturally an os-sdlc onboarding skill. Drift-checking (a project on an outdated standard
  version) *might* extend os-status — but os-status:fix is scoped to "the cc-os approach,"
  whereas this layer targets arbitrary client projects in many languages. Ownership unsettled.
- **Gate strictness is a tuning parameter, not an ideology.** A maximal cop wall can thrash a
  cheap model (fix one violation → trigger another) and burn the iteration budget. Tune
  strictness against iteration counts via autoresearch, same as prompt text — baseline at
  *zero* standards first (audit defaults before customizing) and admit each rule only if it
  beats that baseline.
- **Auditing existing projects is deferred.** One cheap harvest now: seed the canonical Metz
  standard + first Ruby binding from the *best* of the dozen existing definitions. The other
  projects reconcile later via the version-check path, one at a time (like ADR rollout).
- Bindings for non-OOP standards (functional, framework-conformance) — schema unproven.

## Sources

- SecondBrain vault: `convention/` facet, `matt-pocock-skills-v1-1-changes.md`
- `plugins/cc-architect/references/conventions/cc-os-naming.md` (Option B precedent)
- Ruby toolchain: rubocop, reek, flay, flog, mutant
- ADR-0037; [never-ask-twice](never-ask-twice.md) (vault-as-source-of-truth split)
- 2026-07-17 design session (this doc's origin)
