# 25.1.1.6 — Minerva Quality Control Linters

> 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                    |

### Multimedia & Accessibility

| 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

```
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

1. **StatefulLinterManager** — Elegant state tracking, solves critical
   first-finding-only bug
2. **Async generator pattern** — Memory-efficient streaming of findings
3. **MathematicalAccuracyLinter** — Multi-layer SymPy + numeric verification
4. **ReadingLevelLinter** — Flesch-Kincaid, SMOG, Lexile formulas
5. **WCAGAccessibilityLinter** — WCAG 2.1 AA compliance
6. **FactCheckingLinter** — RAG-enhanced with fallback
7. **AgeAppropriatenessLinter** — COPPA-aware grade-level analysis
8. **BiasAndFairnessLinter** — Implicit bias detection for edtech
9. **Recoverable exception handling** — Graceful degradation
10. **Deterministic ordering** — Priority-based linter execution

## Technical Debt to DISCARD

1. **Ghana-hardcoded linters** — Parameterize to locale config
2. **Redundant quiz linters** — 6 quiz linters with overlap
3. **Lazy loading via `__getattr__`** — Replace with explicit registry
4. **No severity/priority system** — Linters have no execution priority
5. **No composition/chaining** — Can't compose linters into pipelines
6. **Hardcoded rules** — Many linters embed rules in code instead of config
7. **LLM call inefficiency** — Each LLM linter makes separate calls instead of
   batching
