Review Squad — Release Notes

What’s new in V4.0

Date 1 April 2026

Scope Father Christmas Craft Intelligence

Agents updated FC (4 modes) + canonical craft reference

V4.0 adds Craft Intelligence to Father Christmas — a structured knowledge layer covering code smell taxonomy, naming precision, structure standards, error handling philosophy, quality enforcement tiers (REJECT/WARN/NOTE), SOLID deep cuts, design pattern intelligence, and elegance heuristics. The layer also extends Database Authority with formal rules on query patterns, index intelligence, schema design, migration safety, and integrity patterns. A three-part finding reporting standard is enforced across all FC findings. Seven precision fixes were applied following a Review Squad audit: cyclomatic complexity formula corrected, idempotency pre-check added to integrity patterns, quality gates template structured, FK REJECT rule scoped, finding reporting standard mode-qualified for consult, role block drive ordering aligned with spec, and thoughtfulness check expanded to the full code smell taxonomy.

Father Christmas Craft Intelligence — all four modes

Code Smell Taxonomy — 8 named smells Feature Envy, Shotgun Surgery, Data Clumps, Primitive Obsession, Long Method, God Object, Refused Bequest, Divergent Change. Each entry includes: signature (how to recognise it in code) and fix (concrete remedy). FC now names the specific smell rather than generic "bad design" findings.
Naming Precision rules Verb phrases for functions, is/has/can/should/was prefix for booleans, plural nouns for collections, predicate naming for boolean-returning functions, on/handle prefix for event handlers, SCREAMING_SNAKE_CASE for module-level constants, typed generic parameters, and a banned-standalone-names list: data, info, manager, processor, handler, helper, utils.
Structure Standards with hard limits Function length: 20-line soft limit, 40-line hard limit. File length: 300-line soft, 500-line hard. Cyclomatic complexity: ≤10 clean, 11–14 warning, ≥15 REJECT. Nesting depth: ≤3 levels. Parameter count: ≤3, introduce a param object at 4+.
Quality Enforcement Tiers: REJECT / WARN / NOTE REJECT (block the PR): swallowed exceptions, N+1 in production paths, missing transaction on multi-table mutations, cyclomatic complexity ≥15, missing FK constraint (same-schema, same-database, non-polymorphic; audit/event log tables exempt), SELECT * in production queries, Primitive Obsession on cross-domain identifiers. WARN (address before next release): function >40 lines, file >500 lines, param count >3, naming violations, missing indexes, SOLID violations, missing created_at/updated_at. NOTE (informational): soft-limit breaches, minor naming improvements, elegance opportunities.
SOLID Deep Cuts — all five principles with violation examples Each principle includes: the real test (not the textbook definition), a classic violation with concrete code example, and a fix. SRP framed as reason-to-change, not "does one thing." OCP: switch/if-else dispatch = OCP violation. LSP: Square extends Rectangle as the canonical example. ISP: read/write interface segregation. DIP: inject abstractions, never instantiate concretions.
Design Pattern Intelligence — use / don't-use guidance Repository, Factory, Strategy, Observer/Event Emitter, Decorator. Each includes an explicit don't-use case to prevent over-engineering — a Repository on a solo CRUD service is indirection for no gain; one Strategy is just a function.
Elegance Heuristics — five named tests The naming test, the comment test (WHAT comments are naming failures; WHY comments belong), the indirection test, the cleverness test, and the extraction test. These give FC a vocabulary for elegance findings that isn't "I'd write it differently."
Database Authority — Query Patterns N+1 with explicit not-N+1 rule (chunked batch loops are O(n/CHUNK), not N+1). SELECT * prohibition. OFFSET pagination degradation with keyset/cursor fix. Implicit Cartesian product detection.
Database Authority — Index Intelligence Coverage rule for WHERE/JOIN ON/ORDER BY columns. Composite index column ordering for point lookups vs. range scans. Partial indexes for soft-delete patterns. CONCURRENTLY requirement on live tables. UUID vs sequential ID tradeoffs for high-insert tables.
Database Authority — Migration Safety NOT NULL addition: 3-step pattern (add nullable, backfill, add constraint). Column rename: 4-step pattern (add, dual-write, backfill+migrate reads, drop). Idempotent migrations always: IF NOT EXISTS / IF EXISTS guards on every DDL statement.
Three-part Finding Reporting Standard Every FC finding must include: (1) pattern/smell name — named issue from the taxonomy, (2) exact citation — file:line in review/audit; proposed design component in consult (mode-qualified), (3) concrete fix — replacement code or schema change. A finding that cannot satisfy all three is a phantom finding and must not be raised.

Precision Fixes Review Squad audit — 7 required corrections

Cyclomatic complexity formula corrected Removed bare else from the token list. McCabe complexity counts decision points — if, else if, loop keywords, logical operators — not bare else branches. The previous formula would over-count by 1 for every if/else pair. Applied to canonical and all four agent modes.
Idempotency pre-check added to Integrity Patterns New pattern in Integrity Patterns section of Craft Intelligence: before flagging a missing transaction, verify whether every mutation is idempotent. Upserts, SET to fixed values, and timestamp fields are idempotent — a re-run after partial failure reaches the correct final state without a transaction. Flag missing transactions only when at least one mutation is non-idempotent. Previously this rule existed only as a review-mode enforcement bullet; it now lives in the shared knowledge layer.
Consult quality gates template structured The Quality Gates section of the FC Architecture Brief output template previously had a single generic placeholder. It now explicitly structures output as REJECT / WARN / NOTE — matching the enforcement tier vocabulary established in Craft Intelligence and preventing vague quality gate statements.
FK REJECT rule scoped Missing FK constraint rule now includes scoping: same-schema, same-database, non-polymorphic; audit/event log tables exempt. This prevents false positives on cross-database references (where FKs are architecturally impossible), polymorphic associations (already addressed separately in Schema Design), and append-only audit/event tables where FK constraints add write overhead without integrity benefit.
Finding Reporting Standard mode-qualified for consult The "exact citation" requirement in the Finding Reporting Standard was unqualified — it demanded a file:line even in consult mode where no code exists yet. The standard now specifies: in consult mode, cite the proposed interface, component, or design decision being assessed; in review/audit modes, file:line is required.
Role block drive ordering corrected The role block in all four agent definitions listed Database Authority first, Quality Absolutist second, Creative Craftsman third — contradicting the Drive 1/2/3 numbering in the Craft Intelligence layer. Reordered to match the spec: Quality Absolutist (Drive 1), Creative Craftsman (Drive 2), Database Authority (Drive 3).
Thoughtfulness check expanded to full taxonomy The Thoughtfulness check in review mode previously cited five of the eight code smells parenthetically (Feature Envy, God Object, Refused Bequest, Primitive Obsession, Shotgun Surgery), leaving Data Clumps, Long Method, and Divergent Change unmentioned. Updated to reference the full taxonomy of eight smells and to require file:line citation alongside smell naming.

← V3.9 V4.0 V4.1 →