Clean code gate

Clean Code Gate

A quality gate on how a change gets built — reuse before invention, and repair the contract that produced the bad state instead of compensating for it downstream. The target is not the amount of defensive code; it's the layer a fix lands at.

This file is the procedure. The trap catalog and the external-skill index live in references/ and are loaded on demand — do not restate them here.

When this fires (and when it doesn't)

Fires when you're about to:

• add a new function / type / abstraction that might duplicate something the repo already has;
• add an if, clamp, default, fallback, early-return, or a second copy of a validation to a consumer of trusted internal data, so a wrong value reads as correct;
• record/return a value in one representation that another component consumes in a different one;
• propose a fix direction in a review (this is the "recommended fix" half of a review).

Does not fire for: typo/format/comment/config-value edits; or defenses at a real boundary — external input, auth, memory/resource safety, public-API compatibility, transaction rollback, concurrency, fault containment. Those are covered by §5 and stay.

Step 0 — Proportional gate

Match effort to blast radius. Do not run the full procedure on trivia.

• Trivial (typo, rename in one scope, format, comment, config value): skip to a sanity read.
• Local (one function's body, a contained bug fix): Steps 1–4, lightly.
• Structural (new mechanism, cross-file change, a fix touching an undo/serialize/coordinate boundary, or any review fix-direction): full procedure, and pull references/contract-traps.md.

State which tier you're in. Over-gating a one-liner discredits the gate as much as under-gating a structural change.

Step 1 — Search the repo before you create

Repo-first is the load-bearing rule (public precedent: figma-implement-design "Reuse Over Recreation", ECC coding-standards — see references/external-skills.md). Before adding anything, look for: existing types/fields for this concept, sibling implementations of the same operation, helpers/utilities, a canonical-vs-display split already in place, tests/asserts encoding the invariant, and past fixes for the same class of bug.

Output (judgeable): either a reuse candidate as file:line, or an explicit one-line reason no existing mechanism fits. "Couldn't find it quickly" and "faster to rewrite" are not reasons. If two snippets merely look similar, do not merge them unless meaning, change-reason, and invariant are the same.

Step 2 — State the violated invariant

Write, in one sentence, what should always have been true. Examples: offsets passed to mutation APIs are in model-text coordinates; a returned insertion position equals the position actually used; canonical text is not overwritten by display expansion; an undo record identifies an operation that can be exactly reversed.

Output: the invariant, one sentence. Do not proceed while it's implicit.

Step 3 — Trace to the first violation

Distinguish four sites — symptom, consumption, production, first violation — per references/contract-traps.md. Follow the bad value backward from the symptom through its caller, conversions, constructors, mutation functions, and any cached/derived representation. Stop at the earliest operation where the value stops satisfying the invariant — not at the first place an if makes the test pass. If reading can't find the origin, switch to the execution-based method in references/dynamic-tracing.md — stack-trace instrumentation before the dangerous op, and bisection for test-pollution origins.

Output: the first-violation file:line, and which component owns that invariant.

Step 4 — Fix at the contract owner

The owner is whoever creates the value, converts representations, performs the mutation, defines the coordinate/index space, owns canonical state, or returns the result. A consumer does not get to reinterpret a value whose meaning its producer already promised. Prefer, highest applicable first:

1. restore the canonical representation (single source of truth);
2. correct the representation conversion, making coordinate/unit/identity explicit;
3. correct the producer's returned value so it describes what actually happened;
4. enforce the invariant at construction/mutation, or make the illegal state unrepresentable;
5. add an assertion that exposes future violations;
6. a downstream guard — only when it's an independent boundary (§5), not to shrink the diff.

Result honesty: a function's return must describe the operation that occurred — reject "clamp internally but return the unclamped position", "delete nothing but report success", "fallback returned as canonical". Fix the dishonest result at its source, not in every caller.

Output: the chosen level, and why a lower (more downstream) level was not used.

Step 5 — Adjacent consumers, then remove the scaffolding

Ask whether the same invalid state can reach another consumer. If several would each need the same clamp/special-case, the fix is upstream — do not duplicate downstream compensation (this is exactly where superpowers' "validate at every layer" is the wrong instinct for internal contracts; it's right only for the boundaries below). After the producer-side fix, delete clamps, branches, fallbacks, and duplicate validations that existed solely to tolerate the now-fixed violation.

Keep defenses that are independently justified: external input, auth, memory/resource safety, public-API compatibility, corrupted-persistence recovery, transaction rollback, idempotent retry, concurrency, fault containment, debug assertions. When you keep one, name the boundary.

Output: the list of scaffolding removed, and any boundary defense retained with its reason.

Step 6 — Pass check

• Reuse considered before invention? (Step 1 output present.)
• Invariant stated, first violation identified at file:line?
• Fix at the contract owner, not the symptom site?
• Producer no longer emits the invalid value; return describes the real operation?
• No adjacent consumer left exposed; obsolete scaffolding removed?
• Smallest change in semantic scope (contracts touched, concepts added), not smallest diff?
• No speculative generality — every branch/abstraction has a present caller, test, or spec?

A downstream one-line clamp can be larger in semantic scope than a several-line producer fix, because the clamp leaves inconsistent state in circulation and adds a special case every future reader must remember. Judge scope, not line count.

Non-goals

Do not use this gate to reject validation of untrusted input, authorization, bounds checks for memory safety, explicit API-compatibility handling, transaction rollback, concurrency checks, fault handling, security defense-in-depth, or assertions that expose internal violations. The question is never "does this patch contain an if?" — it is "does this patch restore the contract, or just make one consequence of breaking it look correct?"

Governing principles

DRY (but clear duplication over premature abstraction) · KISS (fewest concepts, not fewest lines) · YAGNI · Separation of Concerns · Single Responsibility · Design by Contract · Fail Fast · Make Illegal States Unrepresentable · Parse-Don't-Validate · Single Source of Truth · Root-Cause-Fix · Boy Scout Rule.

Three final questions: Does this reuse an answer the repo already has? Does it prevent the invalid state, or only correct the result? Is it the smallest semantic change that restores the contract?