Doctor Auto-Heal and Scoring Improvements

Summary

The modusbrain doctor health score system has several false-positive patterns and missing auto-heal capabilities. After the crash classification fix (shipped in this PR), these are the remaining improvements ranked by impact.

1. Frontmatter severity levels

Problem

NESTED_QUOTES warnings dominate the frontmatter check (6,900+ of ~7,100 total issues). These are cosmetic YAML style issues — values like title: "foo" where the quotes are technically unnecessary. They don’t affect sync, search, embedding, or any functionality. By counting them the same as YAML_PARSE (actual parse failures) or MISSING_OPEN (missing frontmatter delimiters), the frontmatter check is perpetually WARN and the real issues are lost.

Evidence

frontmatter_integrity: 7131 issues across 3 sources
  default: 7012 (NESTED_QUOTES=6922, YAML_PARSE=90)
  media-corpus: 16 (MISSING_OPEN=15, YAML_PARSE=1)
  zion-brain: 103 (MISSING_OPEN=14, NESTED_QUOTES=89)

Only 280 of 7,131 issues are real problems. 96% are cosmetic noise.

Proposed Fix

Introduce severity levels: error (YAML_PARSE, MISSING_OPEN) vs info (NESTED_QUOTES)
Doctor WARN/FAIL only on error-level issues
Report info-level in the message text but don’t affect check status
Optional --pedantic flag includes info-level in status

Test Cases

Frontmatter issues	Severity breakdown	Expected status
0 issues	n/a	OK
50 NESTED_QUOTES only	0 error, 50 info	OK (with note)
3 YAML_PARSE	3 error	WARN
6900 NESTED_QUOTES + 3 YAML_PARSE	3 error, 6900 info	WARN (mentions 3 errors)

2. Temporal contradiction awareness

Problem

The contradiction probe flags temporal evolutions as contradictions. Example:

Page A (April): “Considering option X”
Page B (May): “Decided on option Y”

These aren’t contradictions — they’re the same topic evolving over time. The probe has no time awareness.

Evidence

From a probe run on 50 queries with top-k=15:

120 contradictions detected (112 high, 8 medium)
After manual review: ~60% were temporal evolutions, not real conflicts
Pages have effective_date or created timestamps that could disambiguate

Proposed Fix

Pass effective_date / created to the judge prompt
Add verdict: temporal_supersession (later claim supersedes earlier)
When both pages have dates and claims overlap, bias toward temporal interpretation
Already designed in PR #993

Test Cases

Page A date	Page A claim	Page B date	Page B claim	Expected verdict
2026-04	”Considering X”	2026-05	”Chose Y”	temporal_supersession
2026-04	”Revenue is $1M”	2026-04	”Revenue is $500K”	contradiction
null	”X is true”	null	”X is false”	contradiction
2025-01	”CEO of Company”	2026-01	”Former CEO”	temporal_supersession

3. Multi-source drift baseline

Problem

4,791 pages show “multi-source drift” due to a pre-v0.30.3 putPage routing bug. These pages exist at the default source but should be at a named source. The sources rehome command to fix this hasn’t shipped yet. Every doctor run shows WARN for ~4,800 pages nobody can fix.

Proposed Fix

Allow doctor.baselines config to acknowledge known-unfixable counts:

doctor:
  baselines:
    multi_source_drift: 4800

When actual drift ≤ baseline: OK. When drift exceeds baseline: WARN (new drift). Store in .modusbrain/doctor-baselines.json so it works without config too:

{
  "multi_source_drift": { "count": 4800, "acknowledged_at": "2026-05-15", "reason": "pre-v0.30.3 putPage misroutes" }
}

Test Cases

Actual drift	Baseline	Expected
4791	4800	OK
4900	4800	WARN (“100 new drift beyond baseline”)
4791	0 (no baseline)	WARN (current behavior)

4. Image assets acknowledgment

Problem

When image files are missing from disk (stored externally, purged from git), the check permanently warns. No way to say “these are intentionally external.”

Proposed Fix

doctor --acknowledge image_assets marks current missing count as accepted
Stored in .modusbrain/doctor-baselines.json
WARN only for NEW missing images beyond acknowledged count
Optional image_assets.external_storage: true config to skip disk check entirely

5. Auto-heal mode

Problem

Many doctor warnings have known fixes that are safe to auto-apply:

Warning	Auto-fix
Supervisor not running	Start supervisor
Stale embeddings	Submit `embed --stale` job
Extract coverage < 70%	Submit `extract all --skip-existing` job
Stale sync	Submit sync job
Effective date drift	Run `reindex-frontmatter`

Proposed Fix

doctor --auto-heal mode:

Run all checks
For fixable WARNs: submit fix as a job (not inline — via job queue)
Report what was fixed vs needs manual attention
Idempotent: check queue first, don’t submit duplicates
Safety gate: never auto-heals FAILs, only WARNs

Config:

doctor:
  autoHeal:
    enabled: true
    minInterval: "6h"
    skip:
      - image_assets
      - multi_source_drift

Test Cases

Check status	Auto-heal enabled	Job already queued	Expected
WARN: stale embeds	yes	no	Submit embed job
WARN: stale embeds	yes	yes	Skip (idempotent)
FAIL: max_crashes	yes	n/a	Don’t auto-fix FAILs
WARN: stale embeds	no	n/a	Report only
WARN: image_assets	yes (but skipped)	n/a	Report only

6. Score delta tracking

Problem

No history — each doctor run is a snapshot. Can’t tell if score is improving or degrading.

Proposed Fix

Write each run to .modusbrain/doctor-history.jsonl:

{"ts":"2026-05-15T12:00:00Z","score":60,"brain_score":79,"checks":{"supervisor":"ok","embeddings":"ok",...}}

doctor --trend shows last N scores with deltas
doctor --json includes previous_score and delta fields

7. Weighted scoring

Problem

Going from 99% → 100% embed coverage weighs the same as 50% → 51%. But the last percent is the hardest (oversized pages, rate limits).

Proposed Fix

Threshold-based scoring:

100% = full points
≥95% = 90% of points
≥80% = 70% of points
< 80% = proportional

Priority Order

Frontmatter severity levels (highest noise reduction)
Temporal contradiction awareness (highest false positive reduction, already designed)
Auto-heal mode (biggest long-term value)
Score delta tracking (enables monitoring)
Multi-source drift baseline (quality of life)
Image assets acknowledgment (quality of life)
Weighted scoring (nice to have)

CLI & Core Reference

Evals & Metrics

Database & Schemas

Schema Development

AI Providers

Incidents & Issues

Migrations & Plans

Internal Designs

Ethos & Origin

Doctor Auto-Heal & Scoring

Doctor Auto-Heal and Scoring Improvements

Summary

1. Frontmatter severity levels

Problem

Evidence

Proposed Fix

Test Cases

2. Temporal contradiction awareness

Problem

Evidence

Proposed Fix

Test Cases

3. Multi-source drift baseline

Problem

Proposed Fix

Test Cases

4. Image assets acknowledgment

Problem

Proposed Fix

5. Auto-heal mode

Problem

Proposed Fix

Test Cases

6. Score delta tracking

Problem

Proposed Fix

7. Weighted scoring

Problem

Proposed Fix

Priority Order

​Doctor Auto-Heal and Scoring Improvements

​Summary

​1. Frontmatter severity levels

​Problem

​Evidence

​Proposed Fix

​Test Cases

​2. Temporal contradiction awareness

​Problem

​Evidence

​Proposed Fix

​Test Cases

​3. Multi-source drift baseline

​Problem

​Proposed Fix

​Test Cases

​4. Image assets acknowledgment

​Problem

​Proposed Fix

​5. Auto-heal mode

​Problem

​Proposed Fix

​Test Cases

​6. Score delta tracking

​Problem

​Proposed Fix

​7. Weighted scoring

​Problem

​Proposed Fix

​Priority Order

Doctor Auto-Heal and Scoring Improvements

Summary

1. Frontmatter severity levels

Problem

Evidence

Proposed Fix

Test Cases

2. Temporal contradiction awareness

Problem

Evidence

Proposed Fix

Test Cases

3. Multi-source drift baseline

Problem

Proposed Fix

Test Cases

4. Image assets acknowledgment

Problem

Proposed Fix

5. Auto-heal mode

Problem

Proposed Fix

Test Cases

6. Score delta tracking

Problem

Proposed Fix

7. Weighted scoring

Problem

Proposed Fix

Priority Order