vanillagreencom/kendex/code-quality

Code Quality

Repo-specific standards live in each repo's ## Project Instructions section and add to these rules, winning where they conflict. Before changing code, load the reference for each affected stack under § Language Discipline.

Core Principle

Do not trade correctness for a smaller change. A failed check limits the evidence; it does not establish a product defect. Name the reachable failure before claiming user impact.

Every rule here serves an outcome: correct results for the user, reliability under change, low cost to carry. Before adding or removing a guard, check, abstraction, test or dependency, state what it protects and for whom, what it costs to carry and what is lost without it, and act on that reading. When two rules pull apart, the one that better serves those outcomes for this change wins, and the deviation is written where the decision lives. A finding that no shipped producer, supported external caller or untrusted input reaches, or that only new code written to bypass the guard reaches, is a note on the model, not a defect to fix.

Correctness

• Fix the cause in its existing owner. When the correct fix exceeds the scope, report that conflict instead of adding a workaround.
• A defect has a class: the rule the code broke, not the line that broke it. Name the class and fix it once in its owner, so code that goes through the owner cannot repeat it, and never widen that fix to a route § Core Principle calls unreached. An instance that recurs after the fix is a design finding, not a bug to patch: restate what the fix serves and who it is against before widening it.
• Unreadable evidence is not evidence. A dependency failure, an unreadable input or an unevaluated check never becomes a passing result, a default value or a zero. A required gate refuses with the cause; an advisory check reports unavailable with the cause. A decision over a set of candidates stands only when every candidate was read. An absent or unknown application input is a separate contract choice; state why refusing it is necessary where that choice is made.
• A relation to an external system that code or its tests rely on, such as how a tool builds a row, what an API field means or which identifier is unique, is cited to that system's source, its documentation or a recorded run of it, never modeled from memory. A relation with none of these is not relied on.
• A state with mutually exclusive cases is one tagged value with exhaustive handling. Convert an untouched field only when it has a reachable invalid state.
• A gate or guard that needs an exemption list is wrong at the exempted sites: narrow the rule, or state it at the point where the code cannot judge. Keep an exemption only with its reason beside it.
• An unexpected branch asserts or returns the violated invariant. An error names the failed operation, not a neighbouring dependency, and the value it acted on unless that value is a secret; each diagnostic is emitted in one place. Where a program reads the diagnostic, lead with a stable key and put the human explanation after it.

Structure

• One lifetime, one owner. Resources with a shared lifetime have one owner whose teardown releases them. Resources with independent lifetimes have separate owners, each responsible for acquisition, recovery and release. Phases of one lifetime are private functions, not separate owners.
• Acquire ownership before registering cleanup. A pathname alone grants no right to replace or delete a file, and a saved process number grants no right to signal: hold what the ownership mechanism keeps unique, an exclusively created file or a process handle, or verify identity while the ownership mechanism still prevents reuse.
• A deletion command an agent issues names its target as a literal path, scratch roots included. Resolve the target and verify it is the one to delete, then write the resolved path in the command, quoted or escaped as the shell needs. Never name the target through a variable, a positional parameter, or a variable joined to a slash or glob. A resolved path grants no ownership and no right to delete another actor's output. This governs the shell commands an agent issues, not variables in project runtime source.
• A child launch that changes identity, credentials or home directory selects the inherited values it needs, in production and in tests. A transparent launcher passes the caller's environment and states that contract.
• Test access expands no shipped API and adds no fixture command to a product executable; fixtures live in the stack's test boundary. A diagnostic command or output surface that ships names its production consumer at its declaration. A private readback with no production effect is not a defect.

Over-Engineering

Build only what the current callers need. Add no speculative abstraction, extension point, forwarding wrapper or error path for an impossible state. Add an interface or injection point only when two implementations exist; production plus a test fake counts as two. Justify a new dependency in the commit message. A plan or brief is a route, not a contract: take a discovered path that serves the stated goals better and adds no machinery, and record the change where the plan lives. A planned approach is no reason to keep a worse one; a better path is no reason to widen the goals.

One owner makes each decision: classification, validation, parsing of external input and state detection. Compute it once, in one module, and let callers consume the typed result instead of repeating casts or matches; a classification of upstream text lives in one table, tested on real examples. Before adding a script, background watcher, setting or rule, find and extend the existing owner; if none exists, state that in the commit message. A check that compares a declaration with its implementation checks consistency; it is not a second implementation of the decision, and its expected contract stays independent of the implementation.

A new gate, check or guard names the failure it prevents, a run that failed or a shipped producer that reaches it, and who it is against: ordinary code calling by accident, untrusted input crossing a trust boundary, or a developer bypassing it on purpose, which review holds, not the guard. Weigh its upkeep against that harm; with no failure to name, it is not added. A guard over source code claims only what the platform's own enforcement holds, such as the type system, the compiler or a lint on resolved calls; past that line, review holds the rule. A guard over source that needs a second enumerator, a parser of its own source or a second build to prove itself complete has left its goal: narrow the claim.

Integrate through the system's documented interface: read its current documentation before building on it, and among its documented extension points, an SDK or plugin API, events or RPC, hooks or settings, use the one that holds the need with the least code to carry. Documented text output is an interface. Name the interface used and why. An indirect read of screen text, internal files or undocumented output names the interface it replaces and why that interface cannot serve.

Prove Your Guards

A must-fail control (§ Tests) proves that an instrument detects the defect it claims to. Run only the rows under proof, by name, through the suite's case filter or a disposable wrapper. Mutate a disposable copy of the source outside the worktree, never the tracked source; keep a compiled control's build output under that copy, set per command and never in the session's environment, and remove the copy when the control is done. Keep the matched text when removing behavior: deleting the code under test only proves the assertion runs. Reject an assertion that also matches a skip note, a fixture that never reaches the guarded bound or claimed workload, and harness code that keeps alive what the implementation should.

• Before changing behavior, name the invariants the change must hold and the probe that would falsify each: an input, a crash point, a reused identity, an unreadable read. Those probes are the candidate test rows, each admitted under § Tests, and one of them is the must-fail control. A falsifying probe a review finds that the change did not name is a missing row; it is a design finding when the same class recurs.
• An automated text edit asserts its match count and that the file changed, or uses an edit tool that refuses a missed match. Resolve or refuse a symlink before replacing a path.
• An inventory or collection-driven check discovers its members from the artifact under test, not from a second list, proves discovery completed and enforces a coverage floor that catches a broken extractor; failed or partial discovery never reports a valid empty set. Under-inclusion needs a required member and over-inclusion a forbidden member; state which direction stays unproved.
• Verify a benchmark's workload before timing it, and bound or reset retained state outside the timed operation. A loop-cost estimate is not a latency percentile; a percentile needs a distribution of the events the claim names.
• Match the evidence to the claim. A source check proves source shape, not runtime behavior or rendered output; a scan of one directory establishes nothing about unscanned files; a copied model proves its own behavior. Prefer an instrument that visibly rejects a planted counterexample.
• Exercise the shared production operation where a small existing boundary permits it; otherwise label the result a design demonstration or narrow the claim. Build no production abstraction to rescue a model's claim.

Tests