System architecture: the code-level panorama

Every file is recorded as analysed or skipped, with the reason. Coverage is explainable; nothing is silently dropped.The first stop of every scan.
language.py decides which frontend each file goes to.
report/analyze.py ScanInventory records analysed or skipped, with the reason, so coverage is explainable.
path_context.py weights path roles (production 1.0 · fixture 0.1) so test fixtures cannot drown the real source.
vcs_risk.py reads commit metadata only and adds the bus-factor governance lens.

Every language difference is confined to its own frontend. Adding a language means adding one frontend; the rules never change.python.py uses the stdlib ast; C and C++ use tree-sitter and share one CFamilySpec walker, so dialect differences live in a spec instead of a copied parser.
clang_index.py is the optional libclang precision tier: it sees the real malloc/free after macro expansion and degrades gracefully without compile_commands.json.
Adding a language means adding one file here; nothing downstream changes.

Cheap rules find candidates and deep tools provide proof; beyond single-file rules sit the project-wide import and call graphs.signals/ holds 28 capability-gated rules in six families.
graph/ adds the cross-file view: graded import cycles, call-graph hubs, static test linkage.
tools/ brings semgrep, clang-tidy and friends in as second opinions.
code_context.py lets the same rule reach different verdicts on a sanitizer versus a parallel variant: the "do not split" judgment comes from this layer.

Every source converges on one finding schema, ranked by three explainable axes; every threshold knows its percentile in the reference corpus.Every source (native rules, graphs, external tools, history) converges on one Finding.
Severity is calibrated by the corpus percentiles in norms/; score = severity × (0.5 + 0.5·leverage) × removability, all three axes explainable.
report/ renders an 862KB zero-CDN single-file HTML; serve.py is the stdlib web front door, and the settings panel shows each threshold's corpus percentile as you tune it.

vcs.py takes history with blobless clones (--filter=blob:none), pins HTTP/1.1 against mid-transfer drops on large repos and never touches the working tree.
corpus/ reconstructs whole before/after files.
dataset/scan.py snapshots every release with git archive: at most 60 tags per repo, resumable.

trajectory.py classifies each function's transition across releases as new / renamed / fixed / improved / unchanged, detecting renames by body-hash first.
labels.py uses a fix-commit regex and hunk line numbers to locate each fix back to the function it belonged to in that commit.
release_transitions.py emits the training table.

Which metrics actually predict later refactoring is measured and written into the weights; every smell family can cite a real grew → fixed → stayed case.multivariate.py runs k-fold CV-AUC with a pure-Python logistic regression (zero dependencies), measuring cognitive / cyclomatic at 0.78–0.79.
evidence.py builds the grew → fixed → stayed arcs and the build_degraded() long-term-debt query.
The de-risk series records the negative results: DL defect prediction, fan-in ranking and ownership ranking were all measured here and vetoed.

Every finding is tried as a suspect: the verifier's starting position is that the finding is wrong.Every finding is tried as a suspect: three-class verdicts (CONFIRMED / FALSE_POSITIVE / NOT_ACTIONABLE) with the verifier starting from "this finding is wrong".
Every false positive must name the responsible location in CUPID's own source.
After a fix the eval set replays in both directions: false positives must disappear, confirmed findings must survive.
Human overrides outrank every automated verdict, and engine-vs-doc disagreements are DOC_CONFLICTs that need a ruling, never an automatic verdict.
The loop drains its own backlog: one gated merge per item, 20 verified correction classes now catalogued in the Precision view.