Code Standards (2026-10-29)

Applies to new code and amended code from this date. Existing modules are grandfathered until their migration is scheduled in the breadth map; no mass renames.

Specification level (the horizontal-capability rule)

Specifications describe the way and the concept, not per-target inventories.

A spec defines capabilities of the acquisition mechanism: how recognition knowledge for any target is represented, proposed, verified, and promoted. It never enumerates a target's vocabulary (ServletHolder, doNotifyCommit, voteOnAttribute, ...) as work items or acceptance criteria.
Per-target knowledge is data (fact rows, strategy registrations) produced through the acquisition pipeline -- an LLM can produce it per target; the engine verifies it.
Concrete repositories and frameworks appear in specs only as benchmark evidence: named cases the acquired data must satisfy, never lists to implement.
Litmus: if a requirement's acceptance criteria would not survive swapping the target repository family, the requirement is written at the wrong level. Lift it.

Engine / target split (the anti-monolith rule)

The abstract-interpretation engine is agnostic. Target knowledge (framework names, recognition vocabulary, WordPress/Stapler/Symfony/Jetty/Laravel specifics) never lives inside engine modules.

Engine modules (semantic/obligations/check.py, dominance.py, cfg_dominance.py, paths.py, resolution.py, operations.py, trace.py): no framework or product names. If a framework identifier appears in an engine module, the split has been violated.
Target knowledge lives in exactly two visible places:
1. Data: ruleset/obligations/*.toml and future fact files -- operation rows, discharger rows, handler-name families. Adding a framework's vocabulary is a data change, reviewable in one place.
2. Strategy modules: one module per recognition concern under mapping/ (registry pattern, see below), each file naming its target in its filename and registering itself in one table.
The system adjusts by growing data and strategies, never by editing the engine. The fact-proposal lane (LLM proposes, engine verifies, repetition promotes to rows) is the automated path for the same rule.

Pattern discipline (GoF)

Strategy + Registry for entry recognisers: mapping/ gains a recogniser registry; each framework family is one strategy module. New recognisers land there; the legacy blocks inside mapping.py migrate family by family (tracked in the breadth map).
Interpreter (data-driven) for obligation facts: TOML rows are the language; the checker interprets them. New target vocabulary = new rows.
Adapter at engine seams: hunt/prover.py's callers adapter binds the IR to the caller index; witnesses flow into the checker through one interface (check_obligations).
Factory for witnesses stays inside obligations/enforcement.py for now, but enforcement is a target-aware seam (it reads Symfony/Laravel/Tornado constructs): treat it as adapter territory; engine modules must not import it.

Complexity caps

Cyclomatic (McCabe) complexity: <= 10 per function.
Logical lines of code: <= 50 per function, <= 400 per new module.
A task is not done while a function it touched exceeds the caps; split the function.
Automated gate (ruff C901 / xenon in CI) is not wired yet; caps are enforced at review time. Wiring the gate is tracked in the breadth map.

Idiomatic naming

Names state what a value semantically is, in the pipeline's vocabulary: entry_point, trace, obligation, witness, discharge, finding, judgment.
Collections name their elements: entry_point_records, judgments_by_key, findings_by_push. Mappings use _by_<key>; sequences are plural. No eps, recs, d2, tmp2.
Booleans are predicates: is_public, has_dominating_guard, dominates_entry. Avoid negated names (not_unflagged).
Row/record destructuring uses the record's field names, not positional a, b.
Renaming debt in existing modules is recorded in the breadth map, not fixed drive-by.

4.1 KiB Raw Blame History