Source: oshun/minerva/minerva/linters/ (63 files, 19,702 LOC) Analysis date:
2026-02-28 Purpose: Document linter framework, finding types, integration for
@metis/linters-types
Overview#
- Total linters: 50+ specialized linters
- Total files: 63
- Total LOC: 19,702
- Framework: BaseLinter abstract class with async generator pattern
- Integration: StatefulLinterManager for persistent generator state
- Types: 60% programmatic, 30% LLM-based, 10% specialized analysis
Linter Framework#
BaseLinter (34 LOC)#
python
class BaseLinter(ABC):
@abstractmethod
async def lint(self, course: Course) -> AsyncGenerator[LinterFinding, None]:
"""Analyzes course content and yields findings."""
StatefulLinterManager (322 LOC)#
Solves critical bug: original CritiqueAgent created fresh instances per call,
only accessing first finding.
Key features:
- Persistent async generators (resume from last position)
- Deterministic ordering (sorted by name, PlaceholderLinter & TitleQualityLinter
preferred)
- Category filtering for finding types
- Quota/cooldown support via exclusions
- Exhaustion tracking per linter
- Recoverable exception handling
Methods: register_linter(), get_next_finding(), reset_linter(),
exclude_linter(), get_status()
Finding Model#
| Field |
Type |
Description |
| finding_type |
string |
e.g. "PLACEHOLDER_TEXT_FOUND" |
| message |
string |
Human-readable issue |
| description |
string? |
Detailed explanation |
| target_ids |
string[] |
Affected element IDs |
| topic_id |
string? |
Parent topic for routing |
| category |
FindingCategory |
13-value enum |
| severity |
"LOW"|"MEDIUM"|"HIGH"|"CRITICAL" |
|
| linter_name |
string? |
Provenance |
Linter Taxonomy#
STEM Accuracy (Domain-Specific)#
| Linter |
LOC |
Type |
What it checks |
| lean_chemistry_linter |
976 |
Analysis |
Chemical equations, reactions, balancing |
| scientific_consistency_linter |
888 |
Analysis |
Cross-domain scientific consistency |
| lean_math_linter |
866 |
Analysis |
Mathematical expressions, proofs |
| mathematical_accuracy_linter |
743 |
Analysis |
SymPy + numeric verification (3 depth levels) |
| proof_pedagogy_linter |
703 |
LLM |
Mathematical proof instruction quality |
| physics_accuracy_linter |
700 |
Analysis |
Physics concepts, formulas, units |
| chemistry_accuracy_linter |
656 |
Analysis |
Chemistry content accuracy |
| stem_consistency_linter |
524 |
LLM |
STEM concept coherence across topics |
Assessment Quality#
| Linter |
LOC |
Type |
What it checks |
| quiz_quality_linter |
492 |
LLM |
Overall quiz design quality |
| quiz_answer_accuracy_linter |
468 |
LLM |
Answer correctness and explanation quality |
| quiz_linter |
447 |
LLM |
Quiz structure and question diversity |
| quiz_feedback_quality_linter |
271 |
LLM |
Feedback helpfulness and specificity |
| quiz_richness_linter |
211 |
Programmatic |
Quiz coverage and variety |
| quiz_media_compliance_linter |
101 |
Programmatic |
Media requirements in quizzes |
Content & Pedagogy#
| Linter |
LOC |
Type |
What it checks |
| reading_level_linter |
657 |
Analysis |
Flesch-Kincaid, SMOG, Lexile readability |
| age_appropriateness_linter |
632 |
Analysis |
COPPA compliance, grade-level content |
| bias_and_fairness_linter |
449 |
LLM |
Implicit bias, representation, stereotypes |
| semantic_linter |
409 |
LLM |
Semantic accuracy and coherence |
| fact_checking_linter |
382 |
LLM+RAG |
Claim extraction + RAG verification |
| content_linter |
330 |
LLM |
General content quality |
| difficulty_progression_linter |
326 |
Programmatic |
Cognitive load progression |
| engagement_linter |
325 |
LLM |
Student engagement factors |
| placeholder_linter |
297 |
Programmatic |
Generic/stub placeholder text |
| terminology_linter |
294 |
LLM |
Consistent terminology usage |
| lesson_richness_linter |
279 |
Programmatic |
Example variety, section detail |
| learning_objective_linter |
271 |
LLM |
Bloom's taxonomy alignment |
| title_quality_linter |
242 |
Programmatic |
Descriptive, non-generic titles |
| pedagogical_linter |
202 |
LLM |
Teaching best practices |
| Linter |
LOC |
Type |
What it checks |
| wcag_accessibility_linter |
366 |
Analysis |
WCAG 2.1 AA compliance |
| multimedia_quality_linter |
325 |
Programmatic |
Template detection, content presence |
| media_timestamp_alignment_linter |
318 |
Programmatic |
Audio-visual sync timing |
| multi_modal_linter |
274 |
Programmatic |
Cross-modal consistency |
| image_accessibility_linter |
257 |
Programmatic |
Alt text, captions |
| media_audio_description_linter |
224 |
Programmatic |
Audio description presence |
| media_caption_language_linter |
202 |
Programmatic |
Caption quality and language |
| media_transcript_linter |
152 |
Programmatic |
Transcript availability |
| diagram_data_quality_linter |
105 |
Programmatic |
Diagram data integrity |
Curriculum & Structure#
| Linter |
LOC |
Type |
What it checks |
| concept_graph_linter |
399 |
Analysis |
Ontological consistency |
| course_linter |
379 |
LLM |
Course-level structure quality |
| syllabus_alignment_linter |
367 |
LLM |
Alignment with curriculum standards |
| curriculum_editor_linter |
304 |
Programmatic |
Editor compliance rules |
| prerequisite_linter |
199 |
Programmatic |
Prerequisite validation |
| scaffolding_linter |
174 |
Programmatic |
Learning scaffolding presence |
| syllabus_linter |
122 |
Programmatic |
Syllabus format compliance |
Policy & Compliance#
| Linter |
LOC |
Type |
What it checks |
| plagiarism_license_linter |
286 |
Analysis |
Content originality, licensing |
| ghana_policy_compliance_linter |
238 |
Programmatic |
Ghana education standards |
| bece_format_linter |
157 |
Programmatic |
BECE exam format |
| book_v2_compliance_linter |
133 |
Programmatic |
Book format standards |
Text & Language#
| Linter |
LOC |
Type |
What it checks |
| clarity_linter |
70 |
Programmatic |
Sentence complexity |
| acronym_linter |
130 |
Programmatic |
Acronym definitions |
| citation_requirement_linter |
116 |
Programmatic |
Citation presence |
| citation_needed_linter |
54 |
Programmatic |
Missing citations |
Other#
| Linter |
LOC |
Type |
What it checks |
| cognitive_load_linter |
153 |
Analysis |
Cognitive load estimation |
| code_block_linter |
149 |
Programmatic |
Code example quality |
| ontological_validation_linter |
121 |
Analysis |
Knowledge structure validity |
| content_balance_linter |
85 |
Programmatic |
Content distribution |
| topic_depth_linter |
92 |
Programmatic |
Topic coverage depth |
| graph_schema_linter |
74 |
Programmatic |
Graph structure validity |
| rich_media_majority_linter |
69 |
Programmatic |
Media presence threshold |
Integration: CritiqueAgent → StatefulLinterManager#
text
CritiqueAgent
↓
StatefulLinterManager.register_linter(PlaceholderLinter, ...)
StatefulLinterManager.register_linter(QuizLinter, ...)
StatefulLinterManager.register_linter(...50+ more...)
↓
Loop:
finding = await manager.get_next_finding(
excluded_linters={...}, # quota exhausted
allowed_linters=None, # or whitelist
target_category=None # or filter
)
↓
if finding: route to appropriate agent for fix
if None: all linters exhausted → done
Mathematical Verification (Deep Analysis)#
MathematicalAccuracyLinter Verification Depths#
| Depth |
Tools |
What it does |
| QUICK |
Pattern matching |
Basic arithmetic, syntax checks |
| STANDARD |
SymPy + numeric |
Symbolic computation, numerical verification |
| DEEP |
+ SageMath |
Full proof checking, advanced algebra |
Domain Detection#
Arithmetic, Algebra, Calculus, Logic, Set Theory, Linear Algebra, Statistics
Features to KEEP#
- StatefulLinterManager — Elegant state tracking, solves critical
first-finding-only bug
- Async generator pattern — Memory-efficient streaming of findings
- MathematicalAccuracyLinter — Multi-layer SymPy + numeric verification
- ReadingLevelLinter — Flesch-Kincaid, SMOG, Lexile formulas
- WCAGAccessibilityLinter — WCAG 2.1 AA compliance
- FactCheckingLinter — RAG-enhanced with fallback
- AgeAppropriatenessLinter — COPPA-aware grade-level analysis
- BiasAndFairnessLinter — Implicit bias detection for edtech
- Recoverable exception handling — Graceful degradation
- Deterministic ordering — Priority-based linter execution
Technical Debt to DISCARD#
- Ghana-hardcoded linters — Parameterize to locale config
- Redundant quiz linters — 6 quiz linters with overlap
- Lazy loading via
__getattr__ — Replace with explicit registry
- No severity/priority system — Linters have no execution priority
- No composition/chaining — Can't compose linters into pipelines
- Hardcoded rules — Many linters embed rules in code instead of config
- LLM call inefficiency — Each LLM linter makes separate calls instead of
batching