feat: Literature-aware librarian & archivist agents

[Baeora]

Note: I started adapting this for my own use case and then realized it requires an API key to actually use / test so I am going to rebuild it in a way that lets me use my max plan instead; you might find use from my additions though (although you'll need to test and finish if you do find it interesting)

TLDR It adds "Librarian" agents which have literature SME and then an "Archivist" which will settle disputes between literature that spans over the years / is eventually refuted etc.

Here is Claude's summary:

---

Summary

Adds two new agent roles to the generation loop — librarian and archivist — that ground strategy evolution in ingested literature. Users can ingest markdown books into a persistent library. Each active book
gets a dedicated librarian agent that reviews strategies against the book's principles, flags violations, and is available to other agents via a consult_library tool. When a librarian escalates a violation,
the archivist spot-pulls original passages from the chunked source material and renders a verdict: dismissed, soft_flag, or hard_gate. Hard gates force a retry before tournament matches proceed.

This is a complete component-level implementation with 85 new tests. The runtime wiring to invoke librarians during a live generation loop (orchestrator _init_library() and the --books flag on the run
command) is not yet connected — the individual components are built, tested, and integrated at the DAG/routing/pipeline level, but the final orchestrator plumbing is left for a follow-up.

What's included

Ingestion pipeline (knowledge/ingestion.py)

• register_book() — copies markdown, chunks on H1/H2 headings (preserving tables, code fences, math blocks, blockquotes, lists), writes meta.json
• chunk_markdown() — heading-based splitter with atomic block preservation and a small-file bypass (~6k token threshold)
• ingest_book() — LLM call that reads the full book and produces a condensed reference.md
• validate_ingestion(), remove_book(), list_books()

Agent runners

• LibrarianRunner — proactive review (run()) and reactive consultation (consult()) with structured output parser ()
• ArchivistRunner — conditional arbiter with spot_pull_sections() for original passage retrieval and structured output parser ()
• LibraryToolHandler — handles consult_library tool calls with per-role rate limiting, specific/broadcast routing, and consultation logging

Pipeline integration

• build_mts_dag(active_books=) — dynamically adds librarian_* and archivist nodes with correct dependency edges (translator → librarians → archivist → coach)
• Prefix-based routing in RoleRouter — librarian_clean-arch resolves to the librarian model/provider config
• evaluate_archivist_gate() — pipeline stage that converts archivist decisions into proceed/retry/skip actions
• consult_library added to Agent SDK ROLE_TOOL_CONFIG for competitor, analyst, coach, architect

Prompt system

• LibraryPromptBundle and build_library_context_block() — structured prompt components listing available books
• inject_library_context() — appends library context to any agent prompt

Storage & persistence

• ArtifactStore methods: write_librarian_notes(), read/append_cumulative_notes(), write_archivist_decision(), write_active_books(), append_consultation_log()
• SkillPackage.active_library_books field for knowledge export

CLI commands

• autoctx add-book --title "..." [--name slug] [--author ...] [--tag ...]
• autoctx list-books
• autoctx remove-book

Data contracts & configuration

• LibrarianFlag, LibrarianOutput, ArchivistDecision, ArchivistOutput dataclasses
• AgentOutputs extended with librarian_outputs, archivist_output, library_advisories
• 12 new AppSettings fields: library_root, library_books, librarian_enabled, model_librarian, model_archivist, librarian_provider, archivist_provider, library_max_consults_per_role, ingestion_model

Documentation

• Full design spec: docs/superpowers/specs/2026-03-13-librarian-archivist-design.md
• 21-task implementation plan: docs/superpowers/plans/2026-03-13-librarian-archivist.md
• CLAUDE.md and README.md updated with new roles, commands, and config variables

What's NOT included (follow-up work)

• --books flag on the run CLI command
• AgentOrchestrator._init_library() — the method that instantiates LibrarianRunner/ArchivistRunner and plugs them into the live pipeline
• build_role_handler() cases for librarian_* and archivist roles

These are the final wiring steps that connect the tested components to the running generation loop.