Architecture
Sister docs: PRD (intent), Implementation (deep-dive), Notes (decision log).
System view
flowchart TB
classDef trigger fill:#cce0e8,stroke:#1a1a1d,color:#1a1a1d,stroke-width:2px
classDef detect fill:#faedd6,stroke:#1a1a1d,color:#1a1a1d,stroke-width:2px
classDef judge fill:#e0d5ed,stroke:#1a1a1d,color:#1a1a1d,stroke-width:2px
classDef fix fill:#f4d6db,stroke:#1a1a1d,color:#1a1a1d,stroke-width:2px
classDef out fill:#d8e8d0,stroke:#1a1a1d,color:#1a1a1d,stroke-width:2px
subgraph Triggers["⏰ 4-tier cadence (launchd)"]
Daily["Daily 03:01
4B + Haiku 4.5"]
Weekly["Weekly Sat 21:00
8B + Haiku 4.5"]
Monthly["Monthly 1st 22:00
32B alone"]
Event["Event: post-commit
on KB-s3 mount"]
end
subgraph Detect["🔍 3-layer detection"]
L1["Layer 1 — Intra-file
static + lint-style checks
(path exists, IP/port format)"]
L2["Layer 2 — Cross-file
within workspace
(LLM contradiction scan)"]
L3["Layer 3 — Cross-workspace
(LLM, longest context)"]
end
subgraph Retrieval["📚 Reuses Personal-RAG"]
BGE["bge-m3 retrieval
+ Postgres + pgvector"]
end
subgraph Judge["⚖️ Production judge"]
Grok["Grok 4.3
(verify finding real?)"]
end
subgraph Fix["🛠 Auto-fix pipeline (weekly/monthly)"]
Propose["Grok propose patch"]
Safety["Safety heuristics
(reversible? scoped?)"]
Snap["git snapshot"]
Apply["Apply patch"]
end
subgraph Out["📨 Output"]
Tele["Telegram digest
🟢🟡🔴 + action verb"]
Bundle["Bundle 2×/day"]
end
Daily --> L1
Daily --> L2
Weekly --> L1
Weekly --> L2
Monthly --> L1
Monthly --> L2
Monthly --> L3
Event --> L1
Event --> L2
L1 --> Judge
L2 --> Judge
L3 --> Judge
L2 -.uses.-> BGE
L3 -.uses.-> BGE
Judge -->|verified real| Tele
Tele --> Bundle
Weekly -.weekly+monthly only.-> Propose
Monthly -.-> Propose
Propose --> Safety
Safety -->|pass| Snap
Safety -->|fail| Tele
Snap --> Apply
Apply --> Tele
class Daily,Weekly,Monthly,Event trigger
class L1,L2,L3,BGE detect
class Grok judge
class Propose,Safety,Snap,Apply fix
class Tele,Bundle out
The 3 detection layers
Different drift patterns need different detection methods. Layers escalate in cost and depth.
| Layer | Detects | How | Cost/file | Example caught |
|---|
| 1 — Intra-file | broken paths, malformed URL/IP/port, dangling reference | static check (Python regex + os.path.exists + socket.inet_aton) | $0 | ”I cite /Users/old/path/foo.py but it doesn’t exist” |
| 2 — Cross-file (within workspace) | contradiction between two files about the same fact, stale claim, broken assumption | LLM scan over bundled context (Qwen local + Haiku/Grok verify) | ~$0.001 | Memory says “Postgres 14” → project NOTES updated to “Postgres 16” → memory not updated |
| 3 — Cross-workspace | contradiction between LL work + personal + shared, infra topology drift | LLM with longest-context bundle (Qwen 32B alone, monthly only) | ~$0.01 | Workspace CLAUDE.md says “OCI A1 VM live” but personal memory says “couldn’t register A1” |
The Oracle A1 hallucination = Layer 3. The Postgres 14 vs 16 drift = Layer 2. The dangling code path = Layer 1.
The 4 trigger tiers
| Tier | When | Model stack | Scope | Cost |
|---|
| Daily | 03:01 local (catch-up via RunAtLoad: true) | Qwen 4B local + Anthropic Haiku 4.5 verifier on borderline | files touched in last 24h | ~$0.05/mo |
| Weekly | Saturday 21:00 | Qwen 8B local + Haiku 4.5 verifier | full personal corpus | ~$0.30/mo |
| Monthly | 1st of month 22:00 | Qwen 32B alone, longer context | full + cross-workspace (Layer 3) | ~$0.05/mo |
| Event | post-commit hook on KB-s3 mount (debounced) | Qwen 4B + Haiku 4.5 | only changed files in commit | ~$0.10/mo |
| Judge layer | Every finding from all tiers | Grok 4.3 (xAI) | verify finding is real before surfacing | ~$0.61/mo |
Total ≈ $5/mo including Telegram delivery and git snapshots.
Why this split
| Decision | Alternative | Why this won |
|---|
| 3 layers (not 1 monolithic) | One LLM scans everything | Each layer’s signal type is different; static catches mechanical drift for free |
| 4 tiers (not 1 weekly run) | Run nightly only | Event-triggered catches drift within minutes of write; monthly catches slow cross-workspace drift static cadence misses |
| Local model (Qwen) for bulk | Pure cloud LLM | 90%+ of audit volume is well within local capability; cloud only for borderline + judge |
| Separate judge layer (Grok 4.3) | Detector also judges | Eval-Framework bake-off showed Haiku 13% accuracy when judging-own-finding; Grok 4.3 verified 99% real on holdout |
| Re-use Personal-RAG retrieval | Build own index | bge-m3 already indexes the corpus; duplicating wastes 3.2 GB and dev time |
| Telegram delivery | Email | Inline triage with ✅/⏸/❌ buttons; ADHD-friendly format |
| Auto-fix with git snapshot gate | Direct overwrite | Reversibility is mandatory; review-and-merge gate retained for high-risk types |
Data flow — Detection run
[1] Trigger fires (one of daily/weekly/monthly/event)
│
▼
[2] Select scope:
- daily: files mtime > now-24h
- weekly: full _personal workspace
- monthly: full corpus + cross-workspace bundle
- event: files in latest git commit on KB-s3 mount
│
▼
[3] Layer 1 — static checks (Python):
for each file:
- extract claims (path / port / URL / IP / version)
- verify mechanically
- emit raw findings
│
▼
[4] Layer 2 — cross-file LLM scan:
- bundle ALL files in scope into one prompt (Qwen local)
- "find facts that contradict each other or look stale"
- output JSON with confidence + evidence_chain
│
▼
[5] Layer 3 (monthly only) — cross-workspace:
- bundle _personal + _shared + workspace CLAUDE.md
- longest context window
- same prompt shape, wider source diversity
│
▼
[6] Judge layer (Grok 4.3):
for each raw finding:
- feed (finding + cited quotes + surrounding context)
- "is this a real contradiction or a false positive?"
- keep only real findings
│
▼
[7] Severity tag (🟢🟡🔴):
- 🔴 RED: directly contradicts another source with verbatim quote
- 🟡 YELLOW: looks dated/unverified
- 🟢 (skipped or low confidence)
│
▼
[8] Telegram digest (bundled 2×/day):
- action verb first ("Fix Postgres version in memory")
- time-boxed estimate ("~2 min")
- inline triage buttons
Data flow — Auto-fix (weekly + monthly only)
verified finding from judge
│
▼
[A] Grok proposes patch (unified diff format)
│
▼
[B] Safety heuristics filter:
- is patch <5 lines?
- reversible (markdown edit, not config write)?
- touches NO file in high-risk set (credentials, infra topology, URLs)?
- scoped to ONE file?
│
├─ fail → skip auto-fix, surface to Telegram for manual triage
│
▼ pass
[C] Grok 4.3 judge re-verifies:
"given the patch, does it correctly resolve the finding
without introducing regression?"
│
├─ fail → skip
│
▼ pass
[D] git snapshot:
git add -A && git commit -m "knowledge-audit: pre-fix snapshot <run-id>"
│
▼
[E] Apply patch
│
▼
[F] Telegram digest:
"Auto-fixed: <finding> · <file>:<line> · revert: git revert <sha>"
Failure modes & recovery
| Failure | Detect | Recovery | Time |
|---|
| Mac asleep at 03:00 | launchd RunAtLoad: true + state file | Audit fires on wake, dedupes via skip-if-recent guard | <1 min |
| Grok 4.3 API down | exponential backoff + fallback to Haiku 4.5 verifier | Findings still surface (lower precision) | retry up to 5× |
| Local Qwen OOM | mlx-lm watchdog | Restart Qwen process, retry tier with smaller batch | <30s |
| Auto-fix mis-applies | git snapshot taken before apply | git revert <sha> | <30s |
| Telegram delivery fails | retry queue with persistence to disk | Drains on next run | <10 min |
| LLM rephrases findings each run (fingerprint drift) | manual review notices duplicate-shaped findings | Add explanatory comment in source file (deprecates fingerprint suppression) | per finding |
| PII leak in LLM call | regex redaction + 6 unit tests on every commit | Hard fail in CI before deploy | n/a |
Component responsibilities
| Component | Owns | Doesn’t own |
|---|
| launchd plists (4 tiers + 1 watcher) | Cadence, catch-up, state-file dedupe | Detection logic |
audit.py driver | Tier selection, scope assembly, layer orchestration | Storage, delivery |
| Layer 1 static checker | Mechanical claim verification (path/IP/port/URL) | Semantic claims |
| Layer 2/3 LLM scanner | Cross-source semantic contradiction | Mechanical claims |
| Grok 4.3 judge | Verify finding is real, not LLM-hallucinated | Source acquisition, fix proposal |
| Safety heuristics | Filter unsafe auto-fix candidates | Patch generation |
| Telegram digest | Delivery, ADHD format, triage buttons | Detection, fix |
| git snapshot | Reversibility of auto-fix | Detection |
| Personal-RAG (shared) | bge-m3 retrieval, Postgres index | Audit logic |
See also