infospace-bench/docs/lefevre-readiness.md

# Lefevre Infospace — Final Readiness Report

Date: 2026-05-17
Workplan: IB-WP-0016
Status: ready for a single-chapter live run; full-book run gated on
human review of that first chapter's output

This is the human-facing readiness summary that closes IB-WP-0016. It
records what is wired, where generated outputs live, what gets
committed, the review checks a reviewer must perform before scaling
beyond one chapter, and a few load-bearing risks that should be
re-checked before any full-book run.

## What is wired (T01–T06)

- **T01 spine-aware EPUB3 intake.** Parses `META-INF/container.xml` and
  the OPF package document; iterates documents in spine order; tags
  every spine entry with a section role (`body`, `cover`, `nav`, `toc`,
  `header`, `footer`, `notes`, `license`, `auxiliary`); excludes
  non-body sections by default with an `include_non_body=True` opt-in.
  Full OPF book metadata (title, creator, language, subjects, rights,
  identifier, source_url, modified) reaches every chunk.
- **T02 chapter-aware chunking and stable IDs.** Resolves chapter
  labels from the nav doc and from in-document headings; parses roman
  numerals and "Chapter N" labels into numeric indices; emits stable
  IDs `chapter-NN` with `-part-NNN` suffix on multi-part chapters.
  `id="Page_*"` anchors are extracted upfront and distributed per
  chunk; an `overlap_words` parameter supports an evidence window
  between adjacent parts.
- **T03 scale-aware planning.** `generate plan` returns a compact
  summary by default (selected chunks, per-workflow calls, prompt
  tokens, rough USD). Selection filters `--chapter`, `--from-chapter`,
  `--to-chapter`, `--chunk` and budget caps `--max-calls`, `--cost-cap`,
  `--cost-per-1k` are all wired. `--full` opts back into the full
  per-workflow plan when needed.
- **T04 trading-literature profile.** Eight entity categories (trader,
  market, strategy, error, psychological_pattern, institution,
  instrument, evidence_bearing_claim), five relation types
  (cause_effect, lesson_evidence, risk_mitigation, actor_venue,
  strategy_outcome), four evaluation criteria (groundedness,
  lesson_clarity, historical_context, overgeneralization_risk).
- **T05 deterministic Lefevre fixture.** A checked-in Lefevre-shaped
  EPUB fixture under `tests/fixtures/lefevre/` plus a trading-tuned
  responses YAML. Three tests prove the full pipeline produces a
  manifest-backed infospace with stable `chapter-NN.md` source slugs
  and that PG boilerplate is excluded by default.
- **T06 OpenRouter live-run guardrails.** `--chapter` selection on
  `init` and `from-source` so a one-chapter live run is a one-flag
  command. Provider metadata (model, request_id, usage tokens,
  retry_count, duration_seconds) lives in run records *and* in the
  generated artifact provenance under `provider_metadata`. The optional
  live smoke test in `tests/test_openrouter_live.py` is gated on
  `OPENROUTER_API_KEY` plus `INFOSPACE_BENCH_ENABLE_LIVE_OPENROUTER=1`.

The IB-WP-0019 budget registry rides along: every `generate plan`
appends a snapshot, every `generate run` writes a usage rollup +
variance summary + a state-hub token event with failure isolation.

## Output policy

Where things live, and what to commit:

| Path | Status | Notes |
|---|---|---|
| `tests/fixtures/lefevre/sources/` | **Committed** | Inspectable XHTML; the smoke test rebuilds the EPUB at test time. |
| `tests/fixtures/lefevre/responses.yaml` | **Committed** | Trading-tuned fixture responses. |
| `docs/` | **Committed** | This file, the validation note, generator docs. |
| `infospaces/<slug>/` | **Disposable** | Generated infospaces — do not commit. |
| `infospaces/<slug>/output/budget/` | **Disposable but archive-relevant** | Carried into archive packages by IB-WP-0014 / IB-WP-0019-T07. |
| Live-run outputs (entities, relations, evaluations, reports) | **Review then archive** | After a successful chapter review, archive via `infospace-bench archive` rather than commit. |

The repo gitignore already excludes `infospaces/` content at the
working-copy level; the only Lefevre input shape committed today is the
small fixture under `tests/fixtures/lefevre/`. Archived outputs live in
the artifact-store registry, not in git.

## Reviewer checklist (per chapter)

Run after each chapter's generation completes and before scaling:

1. **Duplicate entities.** `artifacts/entities/` and the report's
   `## Entities` list. Look for near-duplicates (e.g. `Larry
   Livingston` vs `The narrator`, or `Bucket Shop` vs
   `Cosmopolitan Stock Brokerage Company` when the latter is intended
   as a specific instance). Merge or split before continuing.
2. **Relation endpoints.** Every relation's `## Subject` and
   `## Object` should match an existing entity title. Anything that
   does not should either gain an entity or be dropped.
3. **Weak evidence.** Open the `## Evidence` section of each relation
   and confirm it quotes a concrete phrase from the source chunk, not
   a paraphrase. Relations with evidence like "the chapter implies…"
   should be downgraded or removed.
4. **Overgeneralization.** For every entity whose category is
   `strategy`, `error`, `psychological_pattern`, or
   `evidence_bearing_claim`, check the evaluation's
   `overgeneralization_risk` score and read the `## Review Notes` it
   produced. Anything that silently universalises a chapter-local
   claim ("traders always…", "every market does…") should be
   re-scoped or dropped.
5. **Page anchor coverage.** The report's `## Page anchors` section
   should show anchors actually present in the source. If the anchor
   count is zero for a chapter that should have them, intake mis-fired.
6. **Unmapped source chunks.** The report's `## Unmapped source
   chunks` section must be empty before a full-book run. Any chunk
   listed there had its entity or relation stage skip silently — fix
   the underlying workflow or re-run with a different selection.
7. **Plan-vs-actual variance.** `output/budget/summary.yaml` and the
   "Plan variance" line of the report. If actual is more than 1.5×
   estimated for either calls or tokens, re-plan before scaling.

## Scale-up plan

To go from a reviewed one-chapter run to the full Lefevre book:

1. Re-plan against the full book: `infospace-bench generate plan
   <root> --cost-per-1k <rate>` and inspect
   `total_provider_calls_estimate`, `total_prompt_tokens_estimate`,
   and `estimated_cost_usd`. The current real-book numbers are 730
   calls / ~518k tokens / ~$155 at $0.30/1k.
2. Pick a defensible cost-cap. If the plan shows estimated cost above
   the cap, narrow selection with `--from-chapter`/`--to-chapter`
   before running.
3. Pick the final model. Confirm an entry exists in
   `src/infospace_bench/model_rates.yaml` (or a workspace override) so
   `cost_usd_estimated` lines up with reality. List prices drift —
   refresh `captured_at` if older than 90 days.
4. Run one chapter, review per the checklist above, then either
   continue chapter-by-chapter or batch via
   `--from-chapter`/`--to-chapter`. Resume is whole-run-skip today
   (see Risks); avoid relying on it for partial recovery.
5. After each successful range, archive the infospace with
   `infospace-bench archive` so the budget log, the metrics, and the
   generated artifacts all land in a single content-addressed package.

## Risks still load-bearing

These do not block a one-chapter run but should be re-checked before a
full-book run:

- **Cross-chunk entity dedupe.** Exact-title upsert works (same entity
  title across chunks collapses to one file), but near-duplicate dedup
  is still a reviewer responsibility. Plan: only proceed to multi-
  chapter once a chapter's entity list has been hand-pruned.
- **Whole-run resume.** `generate resume` skips a completed run; it
  does not skip just-completed-chunks. For a real 24-chapter run that
  fails midway, the safest recovery today is a new infospace with the
  remaining chapter range — not resume on the original.
- **Adaptive routing.** The current single-model run is fine for one
  chapter but expensive at full-book scale. The cost-quality routing
  layer is parked in `llm-connect` `LLM-WP-0004`; the consumer wiring
  is parked in `infospace-bench` `IB-WP-0018`. Either land that work
  first or accept the single-model bill.
- **Provider rate drift.** The default rate table in
  `src/infospace_bench/model_rates.yaml` captured prices on 2026-05-17.
  Refresh before a full-book run if the file is older than 90 days.

## Sign-off

IB-WP-0016 T01–T07 are done. The pipeline can plan a chapter, run it
against OpenRouter, write a manifest-backed infospace with provider
metadata, record budget and variance, archive the result, and surface
the review-oriented sections that this checklist depends on. The full
Lefevre book is not yet a committed artifact and should not become one
until at least one chapter has cleared the reviewer checklist above.