feat: quality machinery (thesis, voice, insight gate) + interactive TUI + export fixes

Quality - originality over slop-absence (all three tiers from the code review):
- Thesis node: contestable claim + counterargument/rebuttal generated per article,
  injected into every writer+critic call; critic blocks sections that merely cover
- Voice exemplars (brain/users/<uid>/voice/) injected as register to match; /praise
  saves a great chapter/section there and feeds the learner positive signal
- Surgical humanizer: detect tells deterministically, rewrite only flagged sentences,
  guard every rewrite (citations/numbers/length) - no more wholesale re-generation
- Divergent first drafts (best-of-N at varied temps, parallel) + insight score (1-5)
  with min_insight approval gate + deterministic structural style metrics
- Researcher on by default; uncited stats flagged as fabrication risk when off
- Critic routed to deepseek-v4-pro (insight scoring needs real judgment)

TUI/UX - autonomous and manual runs:
- Escalation picker: [f]ix / [i]nstruct / [a]pprove as-is / [g]o autonomous / [r]ead
- revise --chapter N --instruction: rewrite one committed unit of a finished piece,
  patch section + manuscript (books re-run production)
- Outline+thesis approval gate after `new` (manual mode, TTY only)
- Manual divergent-variant picking via ask callback (Live pauses around input)
- Post-run summary card (words/time/tokens/cost/avg insight) + terminal bell
- Table read: whole-piece cold read by a skeptical reader -> table_read.md
- /auto on|off + run --autonomous/--manual (clears stuck escalations); red toolbar
  when review pending; draft-opening glimpse in the dashboard

Export fixes (all formats):
- PDF: code/diagram lines wrap instead of clipping (pre/code CSS, A4, br in pre)
- Mermaid blocks render to PNG via mermaid.ink with per-project disk cache (offline
  re-exports); EPUB packages diagrams as real items; EPUB code-wrap CSS
- U+2011/U+202F tofu normalized; [AUTHOR NAME] placeholder dropped; "Section N:"
  heading prefixes stripped; per-section references consolidated + renumbered

149 tests pass (38 new); ruff clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: Smrutiranjan Patri

config/models.yaml

@@ -8,7 +8,8 @@ nodes:
   writer:        deepseek/deepseek-v4-pro      # prose quality
   consolidation: deepseek/deepseek-v4-pro      # global reasoning across the whole book
   toc:           deepseek/deepseek-v4-flash
-  critic:        deepseek/deepseek-v4-flash    # independent judge - a different model than the writer
+  critic:        deepseek/deepseek-v4-pro      # pro-tier judge: insight scoring + thesis checks
+                                               # need real judgment, worth the extra cost/latency
   summarizer:    deepseek/deepseek-v4-flash    # chapter summaries + canon extraction
   production:    deepseek/deepseek-v4-flash    # front/back matter + assembly
   learner:       deepseek/deepseek-v4-flash    # distill skills from a finished book
@@ -21,4 +22,5 @@ temperature:
   toc:        0.4
   critic:     0.2
   summarizer: 0.0
-  humanizer:  0.7
+  humanizer:  0.3   # surgical line edits - low temp; it must not get creative
+  writer:     0.9   # explicit base temp; divergent first drafts sample 0.7/1.0/1.2

resume.md

@@ -5,8 +5,70 @@
 
 ## Current status
 
-- **Phase:** **Production-ready.** Books and articles both live-validated end-to-end. **111 tests
+- **Phase:** **Production-ready.** Books and articles both live-validated end-to-end. **149 tests
   pass**; ruff clean.
+- **New (2026-06-12, session 9b - TUI/UX batch + headroom actually installed):**
+  - **Escalation picker**: a stalled run now shows the critic's blocking issues and prompts
+    `[f]ix · [i]nstruct · [a]pprove as-is · [g]o autonomous · [r]ead draft · [s]top` - one
+    keypress instead of `review --chapter N --instruction "..."`. Backed by new
+    `orchestrator.approve_escalation()` (commits the stalled draft via the normal commit path).
+  - **`revise` command** (post-completion loop): `revise --chapter N --instruction "..."`
+    rewrites ONE committed unit of a finished piece (write→critique→optional fix pass→
+    humanize), patches the section file AND the assembled manuscript
+    (`_replace_manuscript_section`); books re-run production. Canon deliberately not
+    re-extracted. NL chat maps "make section 3 more technical" to it.
+  - **Outline gate** (manual mode, TTY only): after `new`, the outline + thesis claim are
+    shown with `[Enter] write · r regenerate · g regenerate with guidance` (max 3 rounds).
+  - **Manual variant pick**: in manual interactive runs the human chooses among divergent
+    drafts (glimpse + critic verdict/insight per variant; Enter = critic's pick) via an
+    `ask` callback threaded through `run()` (Live display pauses/resumes around input).
+  - **Summary card + bell**: finished runs ring the terminal and show words/time/tokens/
+    cost/avg-insight (state["insights"] tracked per commit) + table-read pointer.
+  - **Table read** (`table_read: true`): whole-article cold read by a skeptical
+    target-audience reader -> `table_read.md` report (boredom/trust/unclear/missing),
+    report-only, feeds `revise`.
+  - **Toolbar turns red** (prompt_toolkit HTML) when a review is pending; dashboard now
+    shows a draft-opening glimpse line per attempt.
+  - **Headroom fixed**: `headroom-ai` was configured but NOT INSTALLED (silent no-op since
+    day one). Installed the Windows pure-Python build (0.10.17 + opentelemetry-api +
+    tiktoken); verified through `llm._compress`. Caveat: transforms target long multi-turn
+    payloads - expect savings on late-book context, not every call.
+- **New (2026-06-12, session 9 - quality machinery: originality over slop-absence):**
+  Code review concluded the pipeline guaranteed the floor (no slop symptoms) but had no
+  machinery for the ceiling (a thesis, a voice, a risk). Implemented all three tiers:
+  - **Thesis node** (`nodes.generate_thesis`, `schemas.Thesis`): contestable claim + stakes +
+    arguments + steelmanned counterargument/rebuttal + non-goals, generated at `start_article`,
+    persisted as `thesis.json`/`thesis.md`, injected into every section writer + critic call.
+    Critic blocks sections that cover the topic without advancing the thesis.
+  - **Voice exemplars** (`brain.voice_dir`/`voice_exemplars`): drop admired paragraphs in
+    `brain/users/<uid>/voice/`; they're injected into every writer call as register to MATCH.
+    New **`/praise [N]`** command saves a committed chapter/section there (falls back to
+    manuscript extraction for finished articles) - feeds both the writer and the learner
+    (`nodes.learn` now takes `praised=` positive exemplars).
+  - **Surgical humanizer** (humanizer.py rewritten): tells detected deterministically
+    (lexicon regex), ONLY flagged sentences rewritten (structured `LineEdits`), each rewrite
+    guarded (citations/numbers/length/tell-gone) before splicing. No more wholesale
+    re-generation of approved prose. "optimize" removed from the lexicon (wrong for technical
+    prose - the old ban was leaky anyway).
+  - **Divergent first drafts** (`divergent_drafts: 2` setting): attempt 0 samples N drafts at
+    temps 0.7/1.0/1.2 in parallel; critic scores all; the winner gets refined. Both loops.
+  - **Insight gate** (`Critique.insight` 1-5, `min_insight: 3` setting): approve now requires
+    insight >= bar; correct-but-generic drafts get a sharpening revision note. Deterministic
+    `structural_report()` (paragraph uniformity, rule-of-three density, specificity density)
+    feeds the critic as computed evidence. `_crit_better` prefers higher insight.
+  - **Critic = DeepSeek v4-pro** (user decisions: DeepSeek pro/flash only - no other
+    providers; then critic upgraded flash→pro since insight scoring + thesis checks need
+    real judgment). Writer temp now explicit (0.9); humanizer 0.3.
+  - **Researcher default ON** (`use_researcher: true`); critic treats uncited stats as
+    fabrication risk when research is off; production logs a warning when [n] citations exist
+    with an empty source registry.
+  - Earlier same day: `/auto` autonomous↔manual toggle (clears stuck escalations),
+    `run --autonomous/--manual`, chat escalation playbook, export fixes (PDF code wrap,
+    Mermaid→PNG with disk cache, U+2011 tofu, byline, "Section N:" strip, per-section
+    reference consolidation, EPUB code-wrap CSS).
+  - **Next:** live-validate a real article run end-to-end with the new machinery (thesis +
+    divergent drafts + insight gate + cross-family critic); compare output quality against
+    the voice-agent article; tune `min_insight`/`divergent_drafts` from telemetry cost data.
 - **New (2026-06-12, sessions 1-8):**
   - **Chat NL flow** - propose abstract → refine with plain English → "run it"/"go ahead"
     creates + starts writing in one turn. Fixed the regex that silently dropped every

src/book_agent/brain.py

@@ -76,6 +76,40 @@ def watch_list(uid: str = "default") -> Path:
     return user_dir(uid) / "prefs" / "watch_list.md"
 
 
+def voice_dir(uid: str = "default") -> Path:
+    """Admired writing samples: user-dropped .md/.txt files plus /praise'd passages.
+    Injected into writer calls as register to MATCH (showing voice beats describing
+    it) and read by the learner as positive exemplars."""
+    return user_dir(uid) / "voice"
+
+
+def voice_exemplars(uid: str = "default", max_chars: int = 2400) -> str | None:
+    """Assemble exemplar paragraphs from voice_dir under a character budget.
+
+    Takes leading prose paragraphs (skipping headings and code fences) from each
+    file in name order until the budget is spent, so users control priority by
+    file naming. Returns None when there are no exemplars.
+    """
+    d = voice_dir(uid)
+    if not d.exists():
+        return None
+    chunks: list[str] = []
+    total = 0
+    for p in sorted(list(d.glob("*.md")) + list(d.glob("*.txt"))):
+        text = read_text(p) or ""
+        for para in re.split(r"\n\s*\n", text):
+            para = para.strip()
+            if not para or para.startswith("#") or para.startswith("```"):
+                continue
+            if total + len(para) > max_chars:
+                break
+            chunks.append(para)
+            total += len(para)
+        if total >= max_chars:
+            break
+    return "\n\n".join(chunks) or None
+
+
 # ── Book scope ───────────────────────────────────────────────────────────────
 class BookPaths:
     """All paths for one book. The brain on disk is the source of truth."""

src/book_agent/cli.py

@@ -94,6 +94,35 @@ def _spin(label: str, fn):
     return fn()
 
 
+def _outline_gate(uid, project_id, abstract, create_fn, *, is_article, gate_on: bool):
+    """Manual-mode checkpoint after `new`: show the outline (and thesis) BEFORE any
+    prose is written. Reviewing 6 headings costs the human 30 seconds; a bad outline
+    costs the whole run. Enter accepts; 'r' regenerates; 'g' regenerates with guidance.
+    Skipped for autonomous runs and non-interactive stdin (tests, pipes, CI)."""
+    if not gate_on or not sys.stdin.isatty():
+        return project_id
+    for _round in range(3):   # cap regenerations - the planner won't improve forever
+        paths = ArticlePaths(project_id, uid) if is_article else BookPaths(project_id, uid)
+        outline_md = brain.read_text(paths.outline_md if is_article else paths.toc) or ""
+        print("\n" + outline_md.strip())
+        thesis_md = brain.read_text(paths.root / "thesis.md") if is_article else None
+        if thesis_md:
+            claim = next((ln for ln in thesis_md.splitlines() if ln.startswith("**Claim:**")), "")
+            if claim:
+                print(f"\n{claim}")
+        ans = input("\n[Enter] start writing · r regenerate outline · "
+                    "g regenerate with guidance: ").strip().lower()
+        if ans not in ("r", "g"):
+            return project_id
+        if ans == "g":
+            guidance = input("guidance for the planner: ").strip()
+            if guidance:
+                abstract = f"{abstract}\n\nAuthor guidance (honor exactly): {guidance}"
+        orchestrator.delete_book(uid, project_id)
+        project_id = create_fn(abstract)
+    return project_id
+
+
 def _cmd_new_book(args, cfg, settings, uid, abstract):
     directions = _spin("planning directions", lambda: nodes.planner_directions(cfg, abstract)).directions
     for i, d in enumerate(directions, 1):
@@ -102,11 +131,16 @@ def _cmd_new_book(args, cfg, settings, uid, abstract):
     chosen = directions[idx - 1]
     chapters = args.chapters or settings.num_chapters
     max_rev = args.max_revisions if args.max_revisions is not None else settings.max_revisions
+    autonomous = _autonomous_value(args, settings)
     print(f"\n-> {chosen.title}")
-    book_id = _spin("building plan + TOC", lambda: orchestrator.start_book(
-        cfg, settings, uid, abstract, chosen, args.book_id, chapters, max_rev,
-        autonomous=_autonomous_value(args, settings),
-        humanize=(False if getattr(args, "no_humanize", False) else None)))
+
+    def _create(abs_):
+        return _spin("building plan + TOC", lambda: orchestrator.start_book(
+            cfg, settings, uid, abs_, chosen, args.book_id, chapters, max_rev,
+            autonomous=autonomous,
+            humanize=(False if getattr(args, "no_humanize", False) else None)))
+    book_id = _outline_gate(uid, _create(abstract), abstract, _create,
+                            is_article=False, gate_on=not autonomous)
     print(f"\n[OK] Created book '{book_id}'.")
     print(f"     Next: python book.py run --book-id {book_id}")
 
@@ -119,11 +153,16 @@ def _cmd_new_article(args, cfg, settings, uid, abstract):
     chosen = angles[idx - 1]
     num_sections = args.chapters or settings.num_sections
     max_rev = args.max_revisions if args.max_revisions is not None else settings.max_revisions
+    autonomous = _autonomous_value(args, settings)
     print(f"\n-> {chosen.title}")
-    article_id = _spin("building outline", lambda: orchestrator.start_article(
-        cfg, settings, uid, abstract, chosen, args.book_id, num_sections, max_rev,
-        autonomous=_autonomous_value(args, settings),
-        humanize=(False if getattr(args, "no_humanize", False) else None)))
+
+    def _create(abs_):
+        return _spin("building outline", lambda: orchestrator.start_article(
+            cfg, settings, uid, abs_, chosen, args.book_id, num_sections, max_rev,
+            autonomous=autonomous,
+            humanize=(False if getattr(args, "no_humanize", False) else None)))
+    article_id = _outline_gate(uid, _create(abstract), abstract, _create,
+                               is_article=True, gate_on=not autonomous)
     print(f"\n[OK] Created article '{article_id}'.")
     print(f"     Next: python book.py run --book-id {article_id}")
 
@@ -303,7 +342,8 @@ def cmd_write(args, cfg, settings, uid):
 
 def cmd_run(args, cfg, settings, uid):
     orchestrator.run(cfg, uid, _resolve_book(uid, args.book_id),
-                     force=getattr(args, "force", False))
+                     force=getattr(args, "force", False),
+                     autonomous=getattr(args, "autonomous", None))
 
 
 def cmd_status(args, cfg, settings, uid):
@@ -360,6 +400,15 @@ def cmd_review(args, cfg, settings, uid):
           f"--book-id {book_id}")
 
 
+def cmd_revise(args, cfg, settings, uid):
+    """Post-completion revision: rewrite one committed chapter/section to an instruction."""
+    if args.chapter is None or not args.instruction:
+        sys.exit('revise needs --chapter and --instruction (e.g. revise --chapter 3 '
+                 '--instruction "more technical, add a benchmark table")')
+    book_id = _resolve_book(uid, args.book_id)
+    orchestrator.revise_unit(cfg, uid, book_id, args.chapter, args.instruction)
+
+
 def cmd_read(args, cfg, settings, uid):
     # Articles and books store a manuscript/sections at different paths; pick the
     # right one so `read --manuscript` works for both project types.
@@ -504,6 +553,7 @@ def cmd_config(args, cfg, settings, uid):
 
 _COMMANDS = {
     "new": cmd_new, "write": cmd_write, "run": cmd_run, "status": cmd_status, "review": cmd_review,
+    "revise": cmd_revise,
     "read": cmd_read, "memory": cmd_memory, "produce": cmd_produce,
     "consolidate": cmd_consolidate, "skills": cmd_skills, "config": cmd_config,
     "list": cmd_list, "export": cmd_export, "seed-skills": cmd_seed_skills,
@@ -544,12 +594,23 @@ def build_parser(settings):
 
     p_run = sub.add_parser("run", parents=[common], help="Drive the pipeline until done or escalation")
     p_run.add_argument("--force", action="store_true", help="Proceed past a consolidation review")
+    # Tri-state (default None): switch the project's run mode as it resumes. --autonomous
+    # also unblocks an escalated unit so the run finishes without pausing.
+    p_run.add_argument("--autonomous", dest="autonomous", action="store_const", const=True,
+                       default=None, help="Stop pausing for review; commit best drafts and finish")
+    p_run.add_argument("--manual", dest="autonomous", action="store_const", const=False,
+                       help="Re-enable human-in-the-loop review at each chapter/section")
     sub.add_parser("status", parents=[common], help="Show run state + open reviews")
 
     p_rev = sub.add_parser("review", parents=[common], help="Answer an escalation")
     p_rev.add_argument("--chapter", type=int)
     p_rev.add_argument("--instruction")
 
+    p_revise = sub.add_parser("revise", parents=[common],
+                              help="Rewrite one committed chapter/section of a finished piece")
+    p_revise.add_argument("--chapter", type=int, help="Chapter/section number to rewrite")
+    p_revise.add_argument("--instruction", help="What to change, in your words")
+
     p_read = sub.add_parser("read", parents=[common], help="Print chapter/summary/manuscript")
     p_read.add_argument("--chapter", type=int)
     p_read.add_argument("--summary", action="store_true")

src/book_agent/config.py

@@ -52,8 +52,11 @@ class Settings:
     num_chapters: int = 8
     max_revisions: int = 2
     consolidate_every: int = 5
-    use_researcher: bool = False
+    use_researcher: bool = True              # web grounding per unit - off means citations are unverifiable
     deep_research: bool = False               # multi-source fetch+synthesize (needs use_researcher; plan §15)
+    divergent_drafts: int = 2                # first-attempt drafts at varied temps; critic picks best (1 = off)
+    min_insight: int = 3                     # critic insight (1-5) required to approve (0 = off)
+    table_read: bool = True                  # whole-article cold read by a skeptical reader (report only)
     escalate_below_confidence: float = 0.5   # critic confidence below this -> escalate (plan §7)
     escalate_on_contradiction: bool = True   # consolidation contradictions -> review (plan §9)
     autonomous: bool = False                 # no human-in-the-loop: never pause, commit best draft