<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/architecture/04_implementation_mapping/code-patterns/">
  <id>https://docs.spec-kitty.ai/architecture/04_implementation_mapping/code-patterns/</id>
  <title>Core Code Patterns Applied in the Codebase</title>
  <updated>2026-10-08T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/architecture/04_implementation_mapping/code-patterns/"/>
  <summary>The core code patterns applied across the Spec Kitty codebase, mapping recurring implementation idioms to the architecture components they realize (2.x-era record).</summary>
  <content type="html">&lt;span id=&quot;core-code-patterns-applied-in-the-codebase&quot;&gt;&lt;/span&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Field&lt;/th&gt;&lt;th&gt;Value&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;Status&lt;/td&gt;&lt;td&gt;Draft&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Date&lt;/td&gt;&lt;td&gt;2026-05-14&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Scope&lt;/td&gt;&lt;td&gt;Catalog of recurring code patterns used across Spec Kitty modules&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Parent&lt;/td&gt;&lt;td&gt;&lt;a href=&quot;/architecture/04_implementation_mapping/&quot;&gt;Implementation Mapping&lt;/a&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h2 id=&quot;purpose&quot;&gt;Purpose&lt;/h2&gt;
&lt;p&gt;This is the in-code conventions catalog. It is the answer to: “When I open a
new module in Spec Kitty, what shapes should I expect to see, and which one
should I reach for when adding code?”&lt;/p&gt;
&lt;p&gt;Each entry names the pattern, links to the doctrine tactic that codifies it,
points at one or two canonical implementations already in the tree, and
states when to use it (and when not).&lt;/p&gt;
&lt;p&gt;This document is descriptive, not aspirational. Every entry below names a
pattern that currently appears in two or more places in the codebase. Future
contributions to this catalog should keep the same bar — list a pattern only
once it has at least two real consumers.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;1-rule-based-pipeline-chain-of-responsibility&quot;&gt;1. Rule-Based Pipeline (Chain of Responsibility)&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Doctrine:&lt;/strong&gt; &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty-open-packs/blob/main/packs/built-in/tactics/code-patterns/chain-of-responsibility-rule-pipeline.tactic.yaml&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;chain-of-responsibility-rule-pipeline&lt;/code&gt;&lt;/a&gt;&lt;/p&gt;
&lt;p&gt;A pipeline of small, pure functions, each one (1) checking applicability,
(2) optionally executing its narrow piece of work, and (3) returning a result
object that the runner threads to the next function in the chain.&lt;/p&gt;
&lt;p&gt;Three flavors are in use, distinguished by what each rule produces:&lt;/p&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Flavor&lt;/th&gt;&lt;th&gt;Rule contract&lt;/th&gt;&lt;th&gt;Composition&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Validator&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;(input, ctx) -&gt; list[Finding]&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Accumulate findings; order usually free; no short-circuit&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Transformer&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;(state, ctx) -&gt; StepResult(state&apos;, actions, error?)&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Thread state forward; order matters; short-circuit on &lt;code dir=&quot;auto&quot;&gt;error&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Scorer&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;(candidate, ctx) -&gt; float&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Weighted sum; global adjustments applied outside the rule set&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;&lt;strong&gt;Canonical implementations in tree:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Validator: &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/audit/detectors.py&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;detect_legacy_keys&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;detect_forbidden_keys&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;detect_corrupt_jsonl&lt;/code&gt;); composed by
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/audit/classifiers/*&lt;/code&gt; (one classifier per artifact type).&lt;/li&gt;
&lt;li&gt;Validator (class-based): &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/charter_runtime/lint/checks/*&lt;/code&gt; —
&lt;code dir=&quot;auto&quot;&gt;OrphanChecker&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;StalenessChecker&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;ContradictionChecker&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;ReferenceIntegrityChecker&lt;/code&gt;, each with &lt;code dir=&quot;auto&quot;&gt;run(drg, scope) -&gt; list[LintFinding]&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Transformer: &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/migration/canonicalization.py::CanonicalRule&lt;/code&gt;
(Protocol + &lt;code dir=&quot;auto&quot;&gt;apply_rules&lt;/code&gt; runner). Consumed by
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/migration/mission_state.py::_canonicalize_status_row&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/migration/rebuild_state.py&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Scorer: &lt;code dir=&quot;auto&quot;&gt;src/charter/offering/agent_profiles/repository.py::_score_profile&lt;/code&gt; —
DDR-011 weighted-signal profile matching.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Reach for it when:&lt;/strong&gt; you have 3+ independent decisions over a shared input
shape and a uniform per-decision contract. Cognitive complexity stays low,
adding/removing a rule is a localized change, and each rule is independently
testable as a value transformer.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Do not force it onto:&lt;/strong&gt; CLI multiplexers (extract per-mode runners
instead), renderers/formatters (often deliberately linear for traceability —
see &lt;code dir=&quot;auto&quot;&gt;_auth_doctor.render_report&lt;/code&gt;), orchestrators with side effects.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;2-append-only-event-log--reducer&quot;&gt;2. Append-Only Event Log + Reducer&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Reference documentation:&lt;/strong&gt; &lt;a href=&quot;/architecture/status-model/&quot;&gt;Status Model&lt;/a&gt;;
canonical specs in
&lt;code dir=&quot;auto&quot;&gt;kitty-specs/034-feature-status-status-state-model-remediation/data-model.md&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;Per-mission state is persisted as an append-only JSONL event log
(&lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt;). A deterministic reducer (&lt;code dir=&quot;auto&quot;&gt;materialize()&lt;/code&gt;) replays
the events to produce a current-state snapshot (&lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt;). The event log
is the sole authority; the snapshot is derived.&lt;/p&gt;
&lt;p&gt;Properties:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Immutable history.&lt;/strong&gt; Events are never edited or deleted; corrections are
represented as new events with a &lt;code dir=&quot;auto&quot;&gt;from_lane&lt;/code&gt; reflecting the prior state.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Deterministic projection.&lt;/strong&gt; Same event sequence always produces the same
snapshot. The reducer is a pure function.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Single entry point for mutation.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;emit_status_transition()&lt;/code&gt; validates
the (from, to) transition, persists the event, regenerates the snapshot,
and pushes views. No code path bypasses it.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Canonical implementation:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/status/&lt;/code&gt; —
&lt;code dir=&quot;auto&quot;&gt;store.py&lt;/code&gt; (JSONL I/O), &lt;code dir=&quot;auto&quot;&gt;reducer.py&lt;/code&gt; (event → snapshot),
&lt;code dir=&quot;auto&quot;&gt;transitions.py&lt;/code&gt; (legality matrix), &lt;code dir=&quot;auto&quot;&gt;emit.py&lt;/code&gt; (orchestration).
Per-merge state at &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/consolidation/state.py&lt;/code&gt; uses the same event-log
shape for resumable merge operations.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Reach for it when:&lt;/strong&gt; you need an audit trail, resumable operations after a
crash, or a single source of truth across multiple readers. The cost is that
every mutation becomes an event, which feels heavy on small problems — match
the pattern to genuine state-machine work, not every dict update.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;3-two-source-doctrine-repository-shipped--project-override&quot;&gt;3. Two-Source Doctrine Repository (Shipped + Project Override)&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Doctrine:&lt;/strong&gt; Implemented in &lt;code dir=&quot;auto&quot;&gt;src/charter/offering/base.py::BaseArtifactRepository&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;Doctrine artifacts (tactics, directives, paradigms, toolguides, agent
profiles) load from &lt;strong&gt;two sources&lt;/strong&gt;: the shipped package data
(&lt;code dir=&quot;auto&quot;&gt;rglob(&quot;*.tactic.yaml&quot;)&lt;/code&gt; under the shipped tree) and a project override
directory (non-recursive &lt;code dir=&quot;auto&quot;&gt;glob&lt;/code&gt; by default). Field-level merge semantics let
a project replace specific fields without redeclaring the whole artifact.&lt;/p&gt;
&lt;p&gt;Properties:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Shipped is authoritative and never modified by user code.&lt;/li&gt;
&lt;li&gt;Project overrides are additive and field-scoped.&lt;/li&gt;
&lt;li&gt;Schema validation runs against both sources via &lt;code dir=&quot;auto&quot;&gt;validation.py&lt;/code&gt; modules.&lt;/li&gt;
&lt;li&gt;Inline references to other artifacts are rejected (&lt;code dir=&quot;auto&quot;&gt;reject_inline_refs&lt;/code&gt;) —
artifacts reference each other by id, never by embedding.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Canonical implementations:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;src/charter/offering/tactics/repository.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;src/charter/offering/directives/repository.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;src/charter/offering/agent_profiles/repository.py&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Reach for it when:&lt;/strong&gt; introducing a new artifact type that benefits from
both a shipped default and project-level override. Use the existing
&lt;code dir=&quot;auto&quot;&gt;BaseArtifactRepository[T]&lt;/code&gt; generic; do not write a parallel loader.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;4-preflight-validation-with-structured-result-object&quot;&gt;4. preflight validation with Structured Result Object&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Doctrine:&lt;/strong&gt; Reflected in
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty-open-packs/blob/main/packs/built-in/tactics/refactoring/refactoring-extract-first-order-concept.tactic.yaml&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;refactoring-extract-first-order-concept&lt;/code&gt;&lt;/a&gt;
applied to the “validate-then-act” boundary.&lt;/p&gt;
&lt;p&gt;Before any non-trivial mutating operation (merge, migration, upgrade), a
&lt;code dir=&quot;auto&quot;&gt;run_preflight(...) -&gt; PreflightResult&lt;/code&gt; checks all preconditions and returns
a structured result containing per-target status entries plus an aggregated
&lt;code dir=&quot;auto&quot;&gt;passed&lt;/code&gt; flag. The mutating function never starts work without consulting
preflight first, and never repeats preflight’s checks itself.&lt;/p&gt;
&lt;p&gt;Properties:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The preflight result is a value object (dataclass) — no behavior, only
data. Callers branch on &lt;code dir=&quot;auto&quot;&gt;passed&lt;/code&gt; and surface &lt;code dir=&quot;auto&quot;&gt;errors&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;warnings&lt;/code&gt; to the
user.&lt;/li&gt;
&lt;li&gt;Per-target detail (per-WP status, per-file findings) lives on the result
so the user can see &lt;em&gt;which&lt;/em&gt; item failed without re-running.&lt;/li&gt;
&lt;li&gt;Preflight is idempotent and side-effect-free.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Canonical implementations:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/consolidation/preflight.py&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;PreflightResult&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;WPStatus&lt;/code&gt;); the same shape extends to
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/post_merge/&lt;/code&gt; and the bulk-edit gate.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Reach for it when:&lt;/strong&gt; an operation has expensive setup or destructive
effects and needs to fail fast with actionable detail. Do not inline the
checks into the mutator — split for testability and reusability.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;5-pure-function-finding-code--severity--path--detail-tuple&quot;&gt;5. Pure-Function Finding (Code / Severity / Path / Detail Tuple)&lt;/h2&gt;
&lt;p&gt;A &lt;code dir=&quot;auto&quot;&gt;Finding&lt;/code&gt;-shaped dataclass appears across audit, charter-lint, and bulk-edit
modules. The shape is uniform:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;plaintext&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;@dataclass(frozen=True)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;class XxxFinding:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;code: str           # machine-readable category (LEGACY_KEY, MISSING_EVIDENCE, ...)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;severity: Severity  # info | warning | error&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;artifact_path: str  # forward-slash relative path&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;detail: str         # short human-readable explanation&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Properties:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Frozen / immutable — findings flow through pipelines as values.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;code&lt;/code&gt; is documented in an &lt;code dir=&quot;auto&quot;&gt;ERROR_CODES.md&lt;/code&gt; adjacent to the module
that produces it. Codes are part of the public contract; renames are
breaking.&lt;/li&gt;
&lt;li&gt;Findings compose into &lt;code dir=&quot;auto&quot;&gt;list[Finding]&lt;/code&gt; via &lt;code dir=&quot;auto&quot;&gt;.extend()&lt;/code&gt; or
&lt;code dir=&quot;auto&quot;&gt;itertools.chain.from_iterable&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Canonical implementations:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/audit/models.py::MissionFinding&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/charter_runtime/lint/findings.py::LintFinding&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/review/ERROR_CODES.md&lt;/code&gt; and adjacent finding
emitters in &lt;code dir=&quot;auto&quot;&gt;review/&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Reach for it when:&lt;/strong&gt; a new module needs to emit machine-readable
observations about an input. Reuse the existing &lt;code dir=&quot;auto&quot;&gt;MissionFinding&lt;/code&gt; or
&lt;code dir=&quot;auto&quot;&gt;LintFinding&lt;/code&gt; shape; do not introduce a third type unless it carries
genuinely new fields (e.g. structured fix suggestions).&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;how-to-extend-this-catalog&quot;&gt;How to Extend This Catalog&lt;/h2&gt;
&lt;p&gt;To add a pattern to this catalog:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;The pattern must already appear in &lt;strong&gt;two or more&lt;/strong&gt; modules in the
codebase. New patterns introduced by a single feature do not belong here
yet.&lt;/li&gt;
&lt;li&gt;There must be a corresponding doctrine artifact (tactic, directive, or
toolguide) that codifies the pattern. The catalog entry links to it.&lt;/li&gt;
&lt;li&gt;Cite canonical implementations by file path. Keep the citation small (two
or three exemplars), not exhaustive.&lt;/li&gt;
&lt;li&gt;State when &lt;strong&gt;not&lt;/strong&gt; to use the pattern. Catalog entries without a
counter-indication tend to drive over-application.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;This catalog is reviewed as part of mission-review for any mission that
introduces or extracts a pattern. If a refactor turns three ad-hoc
implementations into one shared one, the consolidated location updates the
relevant entry here.&lt;/p&gt;</content>
</entry>
