The load & analysis harness

Analysis & code quality

Every chunk gets a meaning and a risk profile. One tightly-scoped LLM call names what the code is for; deterministic analysers score its structure; and a fleet of background agents turns those signals into human-gated findings and — through a heavily-guarded pipeline — into live pull requests.

Groq intent / layer / pattern analysis

For every chunk the ledger asks one question: "what is this code for, architecturally?" — producing an intent sentence, an architectural layer, and a design pattern. GroqService.AnalyzeAsync(codeSnippet, filePath, repoId) builds a single prompt (MOTMaster-domain preamble, strict JSON schema, a repo+language scope line, up to 6,000 chars) and calls Groq's OpenAI-compatible endpoint (GroqService.cs:79-134). The intent is constrained to name the primary symbol plus a MOTMaster domain concept and forbids generic phrasings, so design embeddings don't collide on vague intents (:104-110). Layer and pattern are coerced to CanonicalLayers / CanonicalPatterns via NormalizeEnum (exact-then-fuzzy), so out-of-set answers fall back cleanly (:47-50,321-334). The parse is defensive — a failure yields a minimal analysis, never a throw (:224-289) — and up to 4 attempts retry on 429, honouring the "try again in Nms" hint with jittered backoff (:129-208).

Content-hash → analysis cache

Each unique chunk is sent to Groq only once. The chunk text is normalized before hashing, so a pure reformat still hits cache (IngestionEngine.cs:377-381). MetricsService.TryGetCachedAnalysis(contentHash, promptVersion, out analysis) returns the cached intent/layer/pattern and rubric on a hit; SetCachedAnalysis persists only successful analyses (MetricsService.cs:287-326; IngestionEngine.cs:420). The cache is versioned by GroqService.PromptVersion (currently "v5-intent-symbol-domain-nofiller", :41): an entry counts as a hit only if its stored version equals the current one, so bumping the constant forces a one-time global re-analysis.

ChunkAnalysis join — chunk classification onto the file-level graph

Classification happens per chunk, but the dependency graph is per file. ChunkAnalysisJoinService.EnrichAsync (:38) runs once per ingest, after the graph merge and before reachability. It scrolls Qdrant payloads (no vectors, no Groq) to build a per-file modal Layer/Pattern map (:54-57) and stamps node.Layer/node.Pattern onto every MergedNode matching by absolute file path, handling /-vs-\ path drift with a secondary forward-slash map (:71-101).

Layer-skip tagging — the architectural-integrity lens

LayerSkipTaggerService.TagLayerSkips flags edges that jump the stack (UI→Persistence directly). It ranks layers by a configurable order (default UI, API, Business_Logic, Integration, Persistence, Infrastructure, :28-31) and sets MergedEdge.IsLayerSkip=true when the source/target ranks differ by more than LayerSkip:MaxStepDistance (default 1) (:55,95-99). It is direction-symmetric, leaves unknown-endpoint edges untagged to avoid false positives, and is reset and recomputed every run.

The code-quality rubric — structural q_* + LLM rubric

Two sources merge into one QualityMetrics. The structural half is deterministic and LLM-free: QualityAnalyserRegistry dispatches by extension to C#/TS/SQL/Generic analysers. The C# analyser is Roslyn-syntax-tree-based and works on snippets — cyclomatic complexity (CsharpQualityAnalyser.cs:59-91), nesting-weighted cognitive complexity (:96-134), LOC, comment density, max nesting and max parameter count (:138-220), plus a normalised-token SHA-256 duplication hash for clone detection (:225-242). The LLM rubric rides the same Groq call: QualityRubricPrompt.Delta is appended when Groq:IncludeQualityRubric (default true), asking for six 1-5 fields (readability, testability, error_handling, single_responsibility, naming) plus a one-sentence risk note. The two are merged at ingest (IngestionEngine.cs:425-437), the model also carrying joined TestCoverageCount and ErrorEmissionCount, and written as q_* payload keys (QdrantService.cs:493-507). A rubric-only backfill patches missing q_readability… for legacy entries (POST /api/admin/rubric/backfill, :2144-2186).

Pattern signatures — cheap boolean flags

TRUE-only boolean flags describe concrete code characteristics: uses async/await, calls a sproc, has a try/catch. PatternSignatureRegistry dispatches by extension; the C# extractor emits cs_async_await, cs_configureawait_false, cs_try_catch, cs_dapper, cs_ado_sqlcommand, cs_logs_error, cs_calls_sproc and cs_nullable_enabled via cheap string/regex checks (CsharpSignatureExtractor.cs:36-58). Absent means false; the extractor is pure and never throws. Flags are stored on the chunk (IngestionEngine.cs:451-455,501).

Groq spend / budget guardrails

A hard cap governs total Groq spend. Groq:BudgetUsd (default 25); IngestionEngine.IsBudgetExceeded compares lifetime cost plus the current run's cost against the cap (≤0 means unlimited, :1510-1517). When exceeded, remaining chunks are indexed with a "(budget cap reached — not analysed)" placeholder that is not cached, so raising the budget re-analyses them later (:397-405). Cost is metered per call from token usage times a configurable Groq:Pricing. Crucially the bug-hunt and conversation-review agents honour the same lifetime cap: BugHuntAgentJob.BudgetExhausted mirrors the ingestion gate (:303-308) and records every chat call's spend via RecordGraphifySpend (:274-287); bug-hunt also has a per-run ceiling MaxGroqCallsPerRun (default 150).

The agents quality platform — detection agents

A fleet of background agents scans the corpus and raises Findings into a shared queue. Each is a singleton with an opt-in interval loop (mostly OFF by default) plus an on-demand POST /api/admin/agents/<name>/run (Program.cs:1889-1971). Six detection agents:

A seventh agent, fix-agent, is the actuator (below). Run receipts are AgentRunResult; incremental agents persist watermarks via AgentStateStore.

The findings queue — shared, human-gated, self-learning

FindingsCollection stores one point per finding in the Findings collection with a zero 384-d vector (lookups are payload-filter, not ANN) (FindingsCollection.cs:25-56). Identity is stable: the id is a deterministic GUID of repo|path|ruleKey (ComputeId :63-64), so re-detecting upserts in place — and on upsert, agent-owned fields refresh but human-owned Status/PrUrl are preserved, so a re-scan can't reopen an approved or dismissed finding (:73-127). Impact ranking: PriorityFor = severity weight (high 60/med 30/low 10) + graph blast-radius (capped 40), sorted priority-then-recency (:302-310,245-251). The learning loop reads human approve/dismiss history per (agent, rule), penalises priority by the dismiss rate, and once a pattern is dismissed ≥85% over ≥5 samples suppresses new findings of that pattern — never dropping a human-touched one (FeedbackDecision :135-141,88-119). The lifecycle is new → approved/dismissed → in-progress → pr-open → merged, flipped via SetStatusAsync.

The fixing dispatcher & fix agent — finding to live code fix

An approved finding can become a draft PR (optionally auto-merged) through a heavily-gated pipeline that defaults to doing nothing dangerous. The dispatcher (Findings/FindingsDispatcher.cs) is a BackgroundService pulling approved findings, running each through the fix agent one at a time, capped at Agents:Fix:MaxPerRun (default 3). It is DISABLED by default (DispatcherEnabled=false, IntervalMinutes=0) and even when enabled honours Git:DryRun (default true). On-demand: POST /api/admin/agents/fix/dispatch?max=&dryRun=. The fix agent (Agents/FixAgentJob.cs) runs a gated chain in RunOnceAsync:

1. Approval gate — skips anything not approved.
2. Repo & lock — repo must be a local git checkout; finding flips to in-progress so the dispatcher won't double-pick it.
3. Plan + blast-radius guard — RefactorPlanGenerator runs; rejected if the in-repo scope exceeds MaxBlastRadiusFiles (default 3).
4. Caller-safety guard — for interface-changing types, enumerates the complete caller set across ALL repos via ReferenceReconciliationService; rejects cross-repo callers or more than MaxOutOfScopeCallers (default 8) that a single-repo build can't validate (:91-111,251-305) — the safety net for the ~0% inbound-edges era.
5. Isolated worktree on a fix/<type>/<id> branch.
6. Scoped engine edit — GroqFixEngine (Fixing/GroqFixEngine.cs) asks Llama at temp 0 for COMPLETE new file contents (never diffs) for only in-scope files, prompted to make the minimal change or decline (ok=false); out-of-scope edits are dropped, applied with path-escape protection.
7. Drift guard — DriftChecker rejects off-piste, scope-creep changes that left the plan.
8. Validation — PatchValidator runs the per-repo build+test in the worktree; if none is configured it SKIPS with Ran=false (CI becomes the gate) unless RequireLocalValidation.
9. Dry-run stop — worktree removed, finding → approved, outcome reports what WOULD change.
10. Live path — commit → push → gh draft PR → finding → pr-open with the PR URL.
11. Opt-in auto-merge — Agents:Fix:AutoMerge (default false) squash-merges only after the full green chain (ShouldAutoMerge); a merge failure leaves the draft.

Any rejection or failure reverts the finding to approved (retryable), never to dismissed (human-only). PR bodies carry the finding, rationale, validation, drift verdict, and caller-safety note.

The Quality dashboard

wwwroot/quality.html is a public per-file risk ranking. The client fetches GET /api/quality?repo=&sort=risk|churn|coverage|complexity&limit=100; the server scrolls Qdrant, aggregates q_* per file, computes Composite = Cyclomatic + Cognitive − Coverage×5 (Program.cs:2585), and surfaces up to three risk notes per file. The sortable table shows Repo, File, Composite, Cyclomatic, Cognitive, Coverage, Churn 90d, Last Modified, and Risk Notes.

Open Brain — the MOTMaster Architectural Ledger · generated from source 2026-07-07