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

Inv	Severity	Description	Auto-fix
I1	ERROR	state is a valid FSM state	no
I2	ERROR	slug is unique across the registry	no
I3	ERROR	uid has a valid prefix (doi:, arxiv:, isbn:, etc.)	no
I4	WARN	pdf_path is properly relative (no 10_SOURCES/ prefix)	yes
I5	ERROR	If state implies PDF, file exists on disk	semi (→ needs_reacquisition)
I6	ERROR	pdf_sha256 is 64 hex chars (recompute if missing)	yes
I7	ERROR	If page1_validated, the log is consistent	semi (→ needs_reacquisition)
I8	ERROR	state_history is monotonic in at timestamps	no
I9	WARN	acquisition_attempts[].n is strictly 1..N (no gap)	yes
I10	ERROR	If blocked_human:*, blocked_reason is non-empty	no
I11	WARN	Each cited_in[].name exists in vault	no
I12	WARN	Each SOTA citation [[slug]] is declared in cited_in	no
I13	WARN	pdf_sha256 is unique (no duplicates)	no
I14	ERROR	No transition out of sota_cited_confirmed or retracted	no
I15	INFO	awaiting_rtfm_ocr not older than 30 days	no
I16	WARN/ERROR	RTFM failure mirrored (Couche 5, opt-in via --correlate-rtfm)	no
I17	ERROR	PDF format defective (Couche 5, opt-in)	no
I18	ERROR	sha256 drift between YAML and disk (Couche 5, opt-in --check-sha)	no
I19	INFO	PDF image-only without alternative text source tested (Couche 5)	no

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