citation-verifier

Citation Verifier

Triggers & routing

• Trigger: citation, BibTeX, ref.bib, verified.jsonl, references, 引用, 参考文献.
• Use when: 已有 papers/paper_notes.jsonl，需要为 prose/LaTeX 准备可追溯的引用（每条都有 url/date/title 验证记录）。

Generate citations/ref.bib and ensure every entry has a traceable verification record in citations/verified.jsonl.

When network access is restricted, prefer a “record now, verify later” workflow: keep URLs/titles consistent and leave a clear verification note.

Input

• papers/paper_notes.jsonl

Outputs

• citations/ref.bib
• citations/verified.jsonl

Workflow (heuristic)

1. Collect bibkey, title, url, year, authors from papers/paper_notes.jsonl.
2. Write/refresh citations/ref.bib:
   • Prefer arXiv-style fields when arxiv_id / primary_category exist (eprint, archivePrefix, primaryClass).
3. Write one verification record per BibTeX entry to citations/verified.jsonl with at least:
   • bibkey, title, url, date
4. If you cannot verify via network, record a clear notes field (e.g., “auto-generated; needs manual verification”) and/or request human confirmation depending on your policy.

Quality checklist

• Every BibTeX entry has a corresponding verified.jsonl record.
• No missing url/date/title in verification records.

Offline Mode

When network access is restricted, run in offline mode to produce auditable records now, then verify later.

• Generate offline records: verification_status: offline_generated
• Verify later (when network is available): --verify-only

verification_status

• offline_generated: record was generated without network verification (needs later verification)
• verified_online: URL/title verified successfully by the script
• verify_failed: verification was attempted but failed (network error or title mismatch)
• needs_manual_verification: missing/ambiguous fields (e.g., empty url/title)

Script

Quick Start

• uv run python .codex/skills/citation-verifier/scripts/run.py --help
• Offline (record now, verify later): uv run python .codex/skills/citation-verifier/scripts/run.py --workspace <workspace> --offline

All Options

• --offline: do not attempt network verification; write verification_status=offline_generated
• --verify-only: verify existing citations/verified.jsonl records (does not rewrite BibTeX)
• --verification-note <text>: stored in citations/verified.jsonl notes

Examples

• Generate BibTeX + offline verification records:
  • uv run python .codex/skills/citation-verifier/scripts/run.py --workspace <workspace> --offline --verification-note "auto-generated; needs manual verification"
• Later, verify-only (when network is available):
  • uv run python .codex/skills/citation-verifier/scripts/run.py --workspace <workspace> --verify-only

Notes

• Minimal requirement for every verification record: url, date, title.
• The script sanitizes stray/unbalanced {} in titles to keep bibtex parsing robust.
• The script escapes LaTeX special chars in text fields (& % $ # _) and rewrites superscript patterns like X^N or X$^N$ as X\textsuperscript{N} to keep LaTeX builds stable.
• URLs are kept raw in BibTeX url fields (BibTeX styles wrap them with \url{...}); @misc uses howpublished=\url{...}.
• In offline mode, records are not truly verified; treat offline_generated as a to-do for human/network verification.

Troubleshooting

Common Issues

Issue: Missing bibkey / missing url in notes

Symptom:

• citations/ref.bib is missing entries, or verified.jsonl has empty url/title.

Causes:

• papers/paper_notes.jsonl lacks bibkey/url fields.

Solutions:

• Ensure each core paper note has a stable bibkey and a canonical url.
• Rerun citation generation after fixing notes.

Issue: verification_status=offline_generated

Symptom:

• Records exist but are not truly verified.

Causes:

• --offline was used, or network verification was unavailable.

Solutions:

• When network is available, run --verify-only to upgrade records.
• Or manually verify and update citations/verified.jsonl with notes.

Recovery Checklist

• Every BibTeX entry has a matching citations/verified.jsonl record.
• Verification records include url, date, title.