roomi-fields/paper-trail/registry-doctor

Skill : registry-doctor

Purpose

Wraps the paper-trail worker B's invariant doctor. Runs all 19 checks (I1-I19) on the registry, reports violations classified by severity (ERROR / WARN / INFO), and offers auto-fix for safe cases.

The doctor is read-only by default. Auto-fixes (--fix) only apply to invariants whose semantic is mechanically safe : I4 (path prefix strip), I6 (sha256 recompute), I9 (attempt renumber), I5/I7 semi (state → needs_reacquisition when PDF missing or page1 log broken).

Never decides anything semantic — that's sota-auditor.

When to invoke

• User asks to audit the registry, run doctor, fix drift
• User runs /paper-trail:doctor or /paper-trail:doctor --fix
• Hooks trigger it post-edit on a ref or at session end (cf.

hooks/hooks.json)

• sota-writer validates that all proposed refs are coherent before

using them in a SOTA

How it works

The skill delegates to the worker B Python CLI:

# Run all 19 invariants, severity ≥ info, no fix
python -m pipeline doctor
 
# Filter to errors only
python -m pipeline doctor --severity error
 
# Auto-fix safe invariants (I4, I6, I9, I5 semi, I7 semi)
python -m pipeline doctor --fix --severity warn
 
# JSON output for machine processing
python -m pipeline doctor --json
 
# Couche 5 — correlate with RTFM indexing failures
python -m pipeline doctor --correlate-rtfm
 
# Couche 5 (slow) — recompute sha256 on all PDFs to detect drift
python -m pipeline doctor --check-sha

Invariants reference

Output format

Markdown report by default :

# Pipeline doctor — YYYY-MM-DD
 
## ERROR (N)
- I5 ref_slug : pdf_path inexistant sur disque
- ...
 
## WARN (N)
- I4 ref_slug : pdf_path préfixé "10_SOURCES/" (auto-fixable)
- ...
 
## INFO (N)
- I15 ref_slug : awaiting_rtfm_ocr depuis 47 jours, last check il y a 12j
- ...
 
Récap : N ERROR / N WARN / N INFO — N auto-fixable(s) avec --fix

JSON format with --json :

{
  "violations": [
    {"invariant": "I5", "ref_slug": "...", "severity": "ERROR",
     "message": "...", "auto_fixable": false},
    ...
  ],
  "summary": {"error": N, "warn": N, "info": N, "auto_fixable": N}
}

Auto-fix safety

--fix only applies to invariants whose correction is semantically safe. It NEVER auto-fixes :

• I10 (blocked_reason empty) — humain must decide the reason
• I8 (state_history non-monotonic) — likely a bug, needs investigation
• I14 (transition from terminal) — likely a manual mutation, needs

audit

For these, the doctor reports them but the curator (you) handles them.

Integration with hooks

The plugin's hooks/hooks.json invokes pipeline doctor :

• PostToolUse(Write|Edit) on **/refs/*.md → mini-check on the

edited ref (warn-level)

• SessionEnd → full doctor sweep (error-level)

These are non-blocking by default — they emit warnings but don't fail the session. To skip the SessionEnd doctor, set RESEARCH_SKIP_END_DOCTOR=1.

Examples

Quick audit

User: "lance le doctor" Skill: python -m pipeline doctor

Fix the cosmetic drift

User: "auto-fix les warn" Skill: python -m pipeline doctor --fix --severity warn

Inspect RTFM correlation

User: "vérifie les invariants avec RTFM" Skill: python -m pipeline doctor --correlate-rtfm --severity warn

Slow integrity check (recompute all sha256)

User: "vérifie l'intégrité des PDFs" Skill: python -m pipeline doctor --check-sha

When NOT to use

• If the user wants to delete a ref or change its state manually →

guide them to edit the YAML directly (PostToolUse will catch any invariant violation)

• If the user asks "is this citation hallucinated ?" → that's

sota-auditor, not registry-doctor

• If the user wants to audit a SOTA or article → that's sota-auditor

or citation-receipts