"""Board 3 „Guide": one card per block, linear stages with gates between them.

  lernziele   judge-Rolle   Backward Design — objectives BEFORE writing
  zuweisung   code          chapter/order from the outline artefact + facts grounding
  writer      guide-Rolle   ONE coherent per-block text, only from VERIFIED FACTS
  fakten_gate judge-Rolle   CoVe: atomic claims, each binary against the facts → minimal fix
  coverage    judge-Rolle   objective↔section mapping; gap → back to writer (max 2 rounds)
  lesbarkeit  judge-Rolle   Lese-Check + deterministic readability gate → fix → done

Runner: one asyncio task per card (cards are fixed from the start — no queue engine
needed); stage transitions are persisted in guide_cards, so the board is live and
cancel/resume just picks cards up at their stored stage. Assembly keeps the exact
legacy content format → content_fuer_level / TopicDetail stay untouched.
"""

import asyncio
import json
import logging
import re

import database as db
import readability
from blocks import _sink_json
from config import (FORMAT_PURPOSE, GUIDE_LAENGE_MAX, GUIDE_LAENGE_MIN, READABILITY_ACTIVE,
                    TEMPLATES_DIR, MAX_CONCURRENT_AGENTS_PER_TOPIC)
from fsutil import atomic_write_json
from jsonio import read_json_file as _json_file
from pipeline import (CANCELLED, FAILED, OK, GenContext, _extra, _log, _prompt,
                      _timeout, is_guide_cancelled, run_single_slot)
from textkit import _norm_title, _parse_fragment, _title

log = logging.getLogger("creator.guide_board")

GUIDE_STAGES = ("lernziele", "zuweisung", "writer", "fakten_gate", "coverage", "lesbarkeit")
STAGE_LABELS = {"lernziele": "Lernziele", "zuweisung": "Zuweisung", "writer": "Writer",
                "fakten_gate": "Fakten-Gate", "coverage": "Coverage",
                "lesbarkeit": "Lesbarkeit", "done": "Fertig"}
from config import GATE_FIX_MIN, MAX_WRITER_ROUNDS, WRITER_SPLIT_SUBS  # zentral tunebar
# Simultaneous cards = the per-topic agent cap: every card busies exactly ONE agent at a
# time (its stages run serially), so a lower number just idles slots (was hardcoded 10
# from the old 10-slot era while the .env already allowed 24).
CARD_CONCURRENCY = MAX_CONCURRENT_AGENTS_PER_TOPIC


def _safe(norm: str) -> str:
    return re.sub(r"\W+", "_", norm)[:50] or "block"


def _ziele_schema(data):
    """{"ziele":[{id,text,sub}]} → list of dicts · None on invalid structure."""
    if not isinstance(data, dict) or not isinstance(data.get("ziele"), list) or not data["ziele"]:
        return None
    out, seen = [], set()
    for z in data["ziele"]:
        if not isinstance(z, dict):
            return None
        zid = str(z.get("id", "")).strip()
        text = str(z.get("text", "")).strip()
        if not zid or not text or zid in seen or len(out) >= 12:
            continue
        seen.add(zid)
        out.append({"id": zid, "text": text, "sub": str(z.get("sub", "")).strip()})
    return out or None


def _gate_schema(data):
    """{"ok":true} → [] · {"claims":[{text,grund,urteil}]} → list · None invalid.
    urteil "falsch" (contradicts the facts/itself) vs "unbelegt" (true but underivable) —
    default unbelegt. Entries whose grund starts with "belegt" are dropped: one judge
    returned a 65-entry full inventory including SUPPORTED claims."""
    if not isinstance(data, dict):
        return None
    if data.get("ok") is True:
        return []
    claims = data.get("claims")
    if not isinstance(claims, list) or not claims:
        return None
    out = []
    for c in claims:
        if isinstance(c, dict) and str(c.get("text", "")).strip():
            grund = str(c.get("grund", "")).strip()
            if grund.casefold().startswith("belegt"):
                continue
            urteil = str(c.get("urteil", "")).strip().casefold()
            out.append({"text": str(c["text"]).strip(), "grund": grund,
                        "urteil": urteil if urteil == "falsch" else "unbelegt"})
    return out


def _coverage_schema(data, ziel_ids: set[str]):
    """{"ziele":{id:bool}, "luecken":[{ziel,fehlt}], "ballast":[str]} — ziele must cover all ids."""
    if not isinstance(data, dict) or not isinstance(data.get("ziele"), dict):
        return None
    ziele = {}
    for k, v in data["ziele"].items():
        ziele[str(k)] = str(v).strip().casefold() in ("true", "ja", "yes", "1")
    if not ziel_ids <= set(ziele):
        return None
    luecken = [{"ziel": str(l.get("ziel", "")), "fehlt": str(l.get("fehlt", ""))}
               for l in data.get("luecken", []) if isinstance(l, dict) and str(l.get("fehlt", "")).strip()]
    ballast = [str(b).strip() for b in data.get("ballast", []) if str(b).strip()]
    return {"ziele": ziele, "luecken": luecken, "ballast": ballast}


def _problems_schema(data):
    """Lese-Check: {"ok":true} → [] · {"problems":[{section,problem}]} → [problem…]."""
    if not isinstance(data, dict):
        return None
    if data.get("ok") is True:
        return []
    probs = data.get("problems")
    if not isinstance(probs, list) or not probs:
        return None
    out = [str(p.get("problem", "")).strip() for p in probs
           if isinstance(p, dict) and str(p.get("problem", "")).strip()]
    return out or None


def _first_section(md: str) -> dict | None:
    secs = _parse_fragment(md) if md else []
    return secs[0] if secs else None


class _Env:
    """Shared per-run context for the card tasks."""

    def __init__(self, ctx, guide_id, topic, format_name, instructions, content_path,
                 subs_by_title, chapter_map, fallback_facts, spec):
        self.ctx = ctx
        self.guide_id = guide_id
        self.topic = topic
        self.format = format_name
        self.instructions = instructions
        self.content_path = content_path
        self.subs_by_title = subs_by_title    # block title → [sub dicts]
        self.chapter_map = chapter_map        # block_norm → (chapter title, ord)
        self.fallback_facts = fallback_facts  # generic source hint (legacy topics without facts)
        self.spec = spec

    def slot(self, name: str):
        return self.content_path.parent / f"{self.content_path.stem}.{name}"


def _card_facts(env: _Env, block_title: str) -> str:
    from guide import _facts_grounding  # lazy: guide imports this module
    grounding = _facts_grounding({block_title: env.subs_by_title.get(block_title, [])})
    return grounding or env.fallback_facts


async def _card_examples(env: _Env, block_norm: str, subs: list[dict],
                         include_unmatched: bool = True) -> str:
    """Verified worked examples of the block as writer input, matched to `subs` via
    sub_norm (a split half gets only its own). Rows whose sub does not match (generation
    mismatch) go to the full writer / split part 1 so they never vanish silently."""
    rows = await db.get_sub_artefakte(env.topic, type="example", block_norm=block_norm)
    if not rows:
        return ""
    wanted = {_norm_title(s["title"]) for s in subs}
    out = []
    for r in rows:
        matched = r["sub_norm"] in wanted
        if not matched and not include_unmatched:
            continue
        data = json.loads(r["data"]) if isinstance(r["data"], str) else (r["data"] or {})
        steps = " ".join(f"{i}) {s}" for i, s in enumerate(data.get("steps") or [], 1))
        where = (f"Subbaustein „{r['sub_title']}“" if matched
                 else "Subbaustein unklar — dort einweben, wo es fachlich passt")
        out.append(f"- {where}:\n  Problem: {data.get('problem', '')}\n"
                   f"  Schritte: {steps}\n  Ergebnis: {data.get('result', '')}")
    if not out:
        return ""
    return ("VERIFIED WORKED EXAMPLES (already fact-checked; each belongs to ONE subblock):\n"
            + "\n".join(out) + "\n"
            "Weave each example into the ausführlich text of EXACTLY its subblock, right "
            "after the concept it applies has been explained — as a short worked-through "
            "passage (problem → steps → result recognizable, flowing prose or a compact "
            "numbered list). Take all values and results over VERBATIM, never recompute "
            "or alter them. NEVER put examples into the compact layer. Subblocks without "
            "an example get none.")


def _card_assignment(env: _Env, card: dict) -> str:
    from guide import _level_label
    lines = [f"- {card['block']}"]
    for s in env.subs_by_title.get(card["block"], []):
        lines.append(f"    [{_level_label(s)}] {s['title']}")
    return "\n".join(lines)


# Live info per active card (in-memory): what the card is doing RIGHT NOW —
# board_snapshot shows it as the info line while status == active.
_live_info: dict[tuple[str, str, str], str] = {}


def _live(env: _Env, card: dict, msg: str) -> None:
    _live_info[(env.topic, env.format, card["block_norm"])] = msg


async def _set(env: _Env, card: dict, **fields):
    card.update(fields)
    await db.set_guide_card(env.topic, env.format, card["block_norm"], **fields)


# ── Stages ─────────────────────────────────────────────────────────────────────────
async def _stage_lernziele(env: _Env, card: dict) -> bool:
    norm = card["block_norm"]
    if not await db.list_lernziele(env.topic, norm):
        subs = "\n".join(f"- [{s.get('level', 'beginner')}] {s['title']}"
                         for s in env.subs_by_title.get(card["block"], [])) or "(keine)"

        async def _versuch(suffix: str):
            path = env.slot(f"ziele-{_safe(norm)}{suffix}.json")
            return await run_single_slot(
                env.ctx, f"Lernziele {card['block']}", key=f"{env.guide_id}-ziele-{_safe(norm)}{suffix}",
                prompt=_prompt("Guide-Lernziele", topic=env.topic, block=card["block"],
                               subs=subs, facts=_card_facts(env, card["block"]),
                               out_path=path, extra=_extra(env.instructions)),
                role="judge", capabilities="files",
                payload=lambda result, p=path: _ziele_schema(_json_file(p)),
                timeout=_timeout("lernziele", len(env.subs_by_title.get(card["block"], []))))

        status, ziele = await _versuch("")
        if status == CANCELLED:
            return False
        if status == FAILED:
            await _set(env, card, status="error", gate_info="Lernziele ohne Ergebnis")
            return False
        if not ziele:  # ein Ersatz-Versuch — leere Liste heißt: das Coverage-Gate läuft leer
            status, ziele = await _versuch("-2")
            if status == CANCELLED:
                return False
            if not isinstance(ziele, list):
                ziele = []
            if not ziele:
                _log(env.topic, f"Lernziele {card['block']}: zweimal leer — Block ohne Coverage-Gate")
        for z in ziele:
            await db.put_lernziel(env.topic, norm, z["id"], z["text"], _norm_title(z["sub"]))
    await _set(env, card, stage="zuweisung", status="open")
    return True


async def _stage_zuweisung(env: _Env, card: dict) -> bool:
    chapter, ord_ = env.chapter_map.get(card["block_norm"], ("Weitere Inhalte", 10_000))
    await _set(env, card, chapter=chapter, ord=ord_, stage="writer")
    return True


# A single section over ~45 subs measurably breaks the writer/coverage (Front Matter:
# 4/6 objectives open after 2 rounds). First drafts of oversized cards are written in two
# halves and merged back into ONE canonical section (all gates/assembly read one section).
# WRITER_SPLIT_SUBS: siehe config.py


def _merge_split_sections(sec_a: dict, sec_b: dict) -> str:
    """Rebuild ONE canonical fragment from two half-sections: header + anchor from part A,
    sub blocks of both parts in order, both layers. Part B's framing is dropped — its
    prompt forbids an intro; keeping it would inject a second lead-in mid-section."""
    lines = []
    if sec_a.get("chapters"):
        lines.append(f"<!-- kapitel: {sec_a['chapters']} -->")
    lines.append(f"<!-- section: {sec_a['title']} -->")
    lines.append("<!-- compact -->")
    if sec_a.get("anker_compact"):
        lines.append(sec_a["anker_compact"])
    for sub in [*sec_a["subs"], *sec_b["subs"]]:
        if sub.get("compact"):
            lines.append(f"<!-- sub: {sub['level']} | {sub['title']} -->")
            lines.append(sub["compact"])
    lines.append("<!-- ausführlich -->")
    if sec_a.get("anchor"):
        lines.append(sec_a["anchor"])
    for sub in [*sec_a["subs"], *sec_b["subs"]]:
        if sub.get("md"):
            lines.append(f"<!-- sub: {sub['level']} | {sub['title']} -->")
            lines.append(sub["md"])
    return "\n\n".join(lines)


def _writer_budget(n_subs: int, sockel: int = 800) -> int:
    """Length guideline (chars) for the detailed version — unguided sections measured 2–4×
    too long (23k) or, after the readability fix, far too thin (180 chars/sub)."""
    return sockel + 400 * max(n_subs, 1)


async def _write_split(env: _Env, card: dict, ziele_text: str):
    """First draft in two halves (parallel), merged into one section.
    → merged text | None (failed) | False (cancelled)."""
    from guide import _level_label
    norm = card["block_norm"]
    subs = env.subs_by_title.get(card["block"], [])
    half = (len(subs) + 1) // 2
    parts = (subs[:half], subs[half:])
    hints = (
        "TEIL 1/2: Schreibe den Abschnitts-EINSTIEG und die folgenden Unterpunkte. "
        "Weitere Unterpunkte folgen in Teil 2 — KEIN Fazit, KEIN Ausblick am Ende.",
        "TEIL 2/2: FORTSETZUNG desselben Abschnitts. KEIN neuer Einstieg, KEINE "
        "Wiederholung von Teil 1 — direkt mit den Unterpunkten weitermachen.",
    )

    async def _one(i):
        assignment = "\n".join([f"- {card['block']}"]
                               + [f"    [{_level_label(s)}] {s['title']}" for s in parts[i]])
        path = env.slot(f"card-{_safe(norm)}-r0-{'ab'[i]}.md")
        path.unlink(missing_ok=True)

        def _payload(result, p=path):
            t = p.read_text(encoding="utf-8") if p.exists() else ""
            sec = _first_section(t)
            return t if sec and sec.get("md", "").strip() else None

        return await run_single_slot(
            env.ctx, f"Writer {card['block']} ({i + 1}/2)",
            key=f"{env.guide_id}-w-{_safe(norm)}-r0-{'ab'[i]}",
            prompt=_prompt("Guide-Writer-Board", topic=env.topic, format_name=env.format,
                           chapter=card.get("chapter") or "Inhalte",
                           assignment=assignment, ziele=ziele_text,
                           facts=_card_facts(env, card["block"]),
                           examples=await _card_examples(env, norm, parts[i],
                                                         include_unmatched=(i == 0)),
                           gaps="\n" + hints[i] + "\n",
                           budget=_writer_budget(len(parts[i]), sockel=400),
                           spec=env.spec, out_path=path, extra=_extra(env.instructions)),
            role="guide", capabilities="files", payload=_payload,
            timeout=_timeout("writer", 1))

    results = await asyncio.gather(_one(0), _one(1))
    if any(s == CANCELLED for s, _ in results):
        return False
    if any(s == FAILED for s, _ in results):
        return None
    return _merge_split_sections(_first_section(results[0][1]), _first_section(results[1][1]))


async def _stage_writer(env: _Env, card: dict) -> bool:
    norm = card["block_norm"]
    ziele = await db.list_lernziele(env.topic, norm)
    ziele_text = "\n".join(f"- ({z['ziel_id']}) {z['text']}" for z in ziele) or "(keine definiert)"
    gaps = ""
    if card["writer_rounds"] > 0 and card.get("gate_info"):
        gaps = ("\nREVISION ROUND — a previous version exists. Revise it: close exactly the gaps "
                "below, cut the listed ballast, keep everything else as-is.\n"
                f"PREVIOUS VERSION:\n{card.get('md', '')}\n\nGAPS/BALLAST:\n{card['gate_info']}\n")
    # oversized first drafts: two halves, merged into one canonical section
    if card["writer_rounds"] == 0 and len(env.subs_by_title.get(card["block"], [])) > WRITER_SPLIT_SUBS:
        text = await _write_split(env, card, ziele_text)
        if text is False:
            return False
        if text is None:
            await _set(env, card, status="error", gate_info="Writer (Split) ohne Ergebnis")
            return False
        await _set(env, card, md=text, stage="fakten_gate", status="open")
        return True

    path = env.slot(f"card-{_safe(norm)}-r{card['writer_rounds']}.md")
    path.unlink(missing_ok=True)

    def _payload(result):
        text = path.read_text(encoding="utf-8") if path.exists() else ""
        sec = _first_section(text)
        return text if sec and sec.get("md", "").strip() else None

    status, text = await run_single_slot(
        env.ctx, f"Writer {card['block']}", key=f"{env.guide_id}-w-{_safe(norm)}-r{card['writer_rounds']}",
        prompt=_prompt("Guide-Writer-Board", topic=env.topic, format_name=env.format,
                       chapter=card.get("chapter") or "Inhalte",
                       assignment=_card_assignment(env, card), ziele=ziele_text,
                       facts=_card_facts(env, card["block"]),
                       examples=await _card_examples(env, norm, env.subs_by_title.get(card["block"], [])),
                       gaps=gaps, spec=env.spec,
                       budget=_writer_budget(len(env.subs_by_title.get(card["block"], []))),
                       out_path=path, extra=_extra(env.instructions)),
        role="guide", capabilities="files", payload=_payload,
        timeout=_timeout("writer", 1))
    if status == CANCELLED:
        return False
    if status == FAILED:
        await _set(env, card, status="error", gate_info="Writer ohne Ergebnis")
        return False
    await _set(env, card, md=text, stage="fakten_gate", status="open")
    return True


async def _stage_fakten_gate(env: _Env, card: dict) -> bool:
    norm = card["block_norm"]
    sec = _first_section(card["md"])
    if sec is None:
        await _set(env, card, status="error", gate_info="Writer-Fragment unlesbar")
        return False
    facts = _card_facts(env, card["block"])
    ex = await _card_examples(env, norm, env.subs_by_title.get(card["block"], []))
    if ex:  # the fix agent sees the same facts variable — examples survive the fix pass
        facts += "\n\nVERIFIED WORKED EXAMPLES (count as verified facts for this check):\n" + ex
    path = env.slot(f"gate-{_safe(norm)}-r{card['writer_rounds']}.json")
    status, claims = await run_single_slot(
        env.ctx, f"Fakten-Gate {card['block']}", key=f"{env.guide_id}-gate-{_safe(norm)}-r{card['writer_rounds']}",
        prompt=_prompt("Guide-Fakten-Gate", topic=env.topic, block=card["block"],
                       section=sec["md"], facts=facts, out_path=path,
                       extra=_extra(env.instructions)),
        role="judge", capabilities="files",
        payload=lambda result: _gate_schema(_json_file(path)),
        timeout=_timeout("fakten_gate", 1))
    if status == CANCELLED:
        return False
    if status == FAILED:
        claims = []  # gate failure must not block the card — logged, text stands
        _log(env.topic, f"Fakten-Gate {card['block']}: kein Ergebnis — Text bleibt ungeprüft")
    falsch = [c for c in claims if c.get("urteil") == "falsch"] if claims else []
    if claims and not falsch and len(claims) < GATE_FIX_MIN:
        # 1–2 merely UNSUPPORTED claims don't justify a fix pass (it ran for 19/20 blocks,
        # 40 agent-minutes) — but a WRONG claim always does: one slipped through this
        # threshold and cost the guide 1.5 QA points
        _log(env.topic, f"Fakten-Gate {card['block']}: {len(claims)} Claim(s) unter Schwelle — kein Fix")
        claims = []
    if claims:
        _log(env.topic, f"Fakten-Gate {card['block']}: {len(claims)} Claims ({len(falsch)} falsch) → Fix")
        fixp = env.slot(f"gatefix-{_safe(norm)}-r{card['writer_rounds']}.md")
        fixp.unlink(missing_ok=True)
        claims_text = "\n".join(f"- {c['text']}" + (f" ({c['grund']})" if c["grund"] else "")
                                for c in claims)

        def _fixload(result):
            text = fixp.read_text(encoding="utf-8") if fixp.exists() else ""
            return text if _first_section(text) else None

        fstatus, fixed = await run_single_slot(
            env.ctx, f"Fakten-Fix {card['block']}", key=f"{env.guide_id}-gatefix-{_safe(norm)}-r{card['writer_rounds']}",
            prompt=_prompt("Guide-Fakten-Fix", topic=env.topic, block=card["block"],
                           section=card["md"], claims=claims_text, facts=facts,
                           out_path=fixp, extra=_extra(env.instructions)),
            role="guide", capabilities="files", payload=_fixload,  # Fix auf der Schreib-Rolle, Gate auf der Judge-Rolle
            timeout=_timeout("fakten_gate", 1))
        if fstatus == CANCELLED:
            return False
        if fstatus == OK and fixed:
            new_sec = _first_section(fixed)
            # marker invariant: a fix that loses the sub markers kills the level filter → discard
            if sec.get("subs") and not (new_sec and new_sec.get("subs")):
                _log(env.topic, f"Fakten-Fix {card['block']} ohne Sub-Marker — verworfen")
            else:
                card["md"] = fixed
    await _set(env, card, md=card["md"], stage="coverage", status="open")
    return True


async def _stage_coverage(env: _Env, card: dict) -> bool:
    norm = card["block_norm"]
    ziele = await db.list_lernziele(env.topic, norm)
    if not ziele:
        await _set(env, card, stage="lesbarkeit")
        return True
    sec = _first_section(card["md"])
    ziele_text = "\n".join(f"- ({z['ziel_id']}) {z['text']}" for z in ziele)
    path = env.slot(f"coverage-{_safe(norm)}-r{card['writer_rounds']}.json")
    ids = {z["ziel_id"] for z in ziele}
    status, res = await run_single_slot(
        env.ctx, f"Coverage {card['block']}", key=f"{env.guide_id}-cov-{_safe(norm)}-r{card['writer_rounds']}",
        prompt=_prompt("Guide-Coverage", topic=env.topic, block=card["block"],
                       ziele=ziele_text, section=sec["md"] if sec else card["md"],
                       out_path=path, extra=_extra(env.instructions)),
        role="judge", capabilities="files",
        payload=lambda result: _coverage_schema(_json_file(path), ids),
        timeout=_timeout("coverage", len(ziele)))
    if status == CANCELLED:
        return False
    if status == FAILED:
        _log(env.topic, f"Coverage {card['block']}: kein Ergebnis — weiter ohne Gate")
        await _set(env, card, stage="lesbarkeit")
        return True
    for zid, ok in res["ziele"].items():
        if zid in ids:
            await db.set_ziel_covered(env.topic, norm, zid, ok)
    if res["luecken"] and card["writer_rounds"] < MAX_WRITER_ROUNDS:
        info = "\n".join(f"- Lücke ({l['ziel']}): {l['fehlt']}" for l in res["luecken"])
        if res["ballast"]:
            info += "\n" + "\n".join(f"- Ballast (kürzen): {b}" for b in res["ballast"])
        _log(env.topic, f"Coverage {card['block']}: {len(res['luecken'])} Lücke(n) → Writer-Runde "
                        f"{card['writer_rounds'] + 1}")
        await _set(env, card, writer_rounds=card["writer_rounds"] + 1, gate_info=info,
                   stage="writer", status="open")
        return True
    if res["luecken"]:
        _log(env.topic, f"Coverage {card['block']}: Lücken bleiben nach {MAX_WRITER_ROUNDS} Runden")
    await _set(env, card, gate_info="", stage="lesbarkeit")
    return True


async def _stage_lesbarkeit(env: _Env, card: dict) -> bool:
    norm = card["block_norm"]
    sec = _first_section(card["md"])
    if sec is None:
        await _set(env, card, status="error", gate_info="Fragment unlesbar")
        return False
    problems: list[str] = []
    path = env.slot(f"lese-{_safe(norm)}-r{card['writer_rounds']}.json")
    # Text-Antwort + Engine-Sink: Datei-schreibende Judges lieferten invalides JSON
    # (3 kaputte Check-Dateien im Messlauf) — der Sink validiert vor dem Persistieren
    status, res = await run_single_slot(
        env.ctx, f"Lese-Check {card['block']}", key=f"{env.guide_id}-lese-{_safe(norm)}",
        prompt=_prompt("Guide-Lese-Check", topic=env.topic, format_name=env.format,
                       spec=env.spec, sections=f"SECTION: {card['block']}\n{sec['md']}",
                       extra=_extra(env.instructions)),
        role="judge", capabilities="none",
        payload=lambda result: _sink_json(result, path, _problems_schema),
        timeout=_timeout("lese_check", 1))
    if status == CANCELLED:
        return False
    if status == OK and res:
        problems += res
    if READABILITY_ACTIVE:  # deterministic gate, external grounding
        hints = await asyncio.to_thread(readability.rate_sections, {1: sec["md"]})
        if hints.get(1):
            problems.append(hints[1])
    # deterministic length trigger, same formula as the QA detector: prompt guidelines
    # alone left writers 2.7–4.1× over target — a measured overshoot forces the fix pass
    subs_all = env.subs_by_title.get(card["block"], [])
    n_rel = max(sum(1 for s in subs_all if s.get("relevance") != "peripheral"), 1)
    aus = re.split(r"<!--\s*ausführlich\s*-->", sec["md"], maxsplit=1)
    pro_sub = len(aus[1] if len(aus) == 2 else sec["md"]) / n_rel
    if not (GUIDE_LAENGE_MIN <= pro_sub <= GUIDE_LAENGE_MAX * 0.9):
        ziel = _writer_budget(len(subs_all))
        problems.append(
            f"Länge {round(pro_sub)} Zeichen/Sub (Rahmen {GUIDE_LAENGE_MIN}–{round(GUIDE_LAENGE_MAX * 0.9)}): "
            f"schreibe den ausführlich-Teil auf etwa {ziel} Zeichen GESAMT um — Sockel-Prosa und "
            f"Wiederholungen streichen, alle Sub-Marker und Beispiele behalten")
    if problems:
        from guide import _level_label
        subs = env.subs_by_title.get(card["block"], [])
        sub_list = "\n".join(f"- [{_level_label(s)}] {s['title']}" for s in subs) or "(none)"
        tasks = (f"SECTION: {card['block']}\n"
                 f"SUBBLOCKS (set one `<!-- sub: LABEL | title -->` marker each, label/order as here):\n{sub_list}\n"
                 f"LENGTH TARGET: about {_writer_budget(len(subs))} characters for the detailed "
                 f"version (guideline — covering every subblock beats brevity).\n"
                 f"PROBLEM: {' · '.join(problems)}\nCURRENT CONTENT:\n{sec['md']}")
        fixp = env.slot(f"lesefix-{_safe(norm)}.md")
        fixp.unlink(missing_ok=True)

        def _fixload(result):
            text = fixp.read_text(encoding="utf-8") if fixp.exists() else ""
            return text if _first_section(text) else None

        fstatus, fixed = await run_single_slot(
            env.ctx, f"Lese-Fix {card['block']}", key=f"{env.guide_id}-lesefix-{_safe(norm)}",
            prompt=_prompt("Guide-Sections-Fix", topic=env.topic, format_name=env.format,
                           facts=_card_facts(env, card["block"]), spec=env.spec, tasks=tasks,
                           out_path=fixp, extra=_extra(env.instructions)),
            role="guide", capabilities="files", payload=_fixload,
            timeout=_timeout("writer", 1))
        if fstatus == CANCELLED:
            return False
        if fstatus == OK and fixed:
            new_sec = _first_section(fixed)
            if sec.get("subs") and not (new_sec and new_sec.get("subs")):
                _log(env.topic, f"Lese-Fix {card['block']} ohne Sub-Marker — verworfen")
            else:
                card["md"] = fixed
    await _set(env, card, md=card["md"], stage="done", status="ok", gate_info="")
    return True


_STAGE_FN = {"lernziele": _stage_lernziele, "zuweisung": _stage_zuweisung,
             "writer": _stage_writer, "fakten_gate": _stage_fakten_gate,
             "coverage": _stage_coverage, "lesbarkeit": _stage_lesbarkeit}


async def _run_card(env: _Env, card: dict, sem: asyncio.Semaphore) -> None:
    async with sem:
        try:
            await _run_card_inner(env, card)
        finally:
            _live_info.pop((env.topic, env.format, card["block_norm"]), None)


async def _run_card_inner(env: _Env, card: dict) -> None:
    while card["stage"] != "done":
        if is_guide_cancelled(env.guide_id):
            await _set(env, card, status="open")  # no longer being worked
            return
        fn = _STAGE_FN.get(card["stage"])
        if fn is None:  # unknown stage → park as error
            await _set(env, card, status="error", gate_info=f"Unbekannte Stage {card['stage']}")
            return
        if card["status"] != "active":
            await _set(env, card, status="active")  # live board: this card is being worked
        _live(env, card, STAGE_LABELS.get(card["stage"], card["stage"]) + "…")
        try:
            if not await fn(env, card):
                return
        except Exception as e:
            log.exception("[%s] guide card %s failed", env.topic, card["block"])
            await _set(env, card, status="error", gate_info=f"{type(e).__name__}: {e}"[:300])
            return


# ── Orchestration ──────────────────────────────────────────────────────────────────
async def _chapter_map(topic: str, entries: dict[int, str]) -> dict[str, tuple[str, int]]:
    """block_norm → (chapter title, global order) from the outline artefact."""
    from guide import _outline_from_db, _fallback_outline, _with_remainder
    plan = await _outline_from_db(topic, entries) or _fallback_outline(entries)
    plan = _with_remainder(plan, entries)
    out: dict[str, tuple[str, int]] = {}
    i = 0
    for ch in plan:
        for num in ch.get("nums", []):
            if num in entries:
                out[_norm_title(_title(entries[num]))] = (ch.get("title") or "Kapitel", i)
                i += 1
    return out


async def run_guide_board(guide_id: str, topic: str, format_name: str, entries: dict[int, str],
                          instructions: str, provider: str, content_path) -> list[dict] | None:
    """Seed one card per block (existing cards keep their stage — resume), run all cards,
    assemble the chapters in the legacy content format. → chapters | None (cancel/empty)."""
    from blocks import source_folder
    from guide import _load_subblocks
    ctx = GenContext(topic=topic, provider=provider,
                     is_cancelled=lambda: is_guide_cancelled(guide_id), guide_id=guide_id)
    import uuid
    from datetime import datetime, timezone
    db.set_current_run(topic, f"{datetime.now(timezone.utc).strftime('%Y%m%d-%H%M')}-g{uuid.uuid4().hex[:4]}")
    spec = (TEMPLATES_DIR / "Format" / "Section.md").read_text(encoding="utf-8")
    subs_raw = await _load_subblocks(topic)
    project = source_folder(topic)
    fallback = (_prompt("Guide-Facts-Projekt", project=project) if project
                else _prompt("Guide-Facts-Thema"))
    env = _Env(ctx, guide_id, topic, format_name, instructions, content_path,
               subs_raw, await _chapter_map(topic, entries), fallback, spec)
    for num, line in entries.items():
        title = _title(line)
        await db.upsert_guide_card(topic, format_name, _norm_title(title), title)
    cards = await db.list_guide_cards(topic, format_name)
    open_cards = [c for c in cards if c["stage"] != "done"]
    if open_cards:
        sem = asyncio.Semaphore(CARD_CONCURRENCY)

        async def _progress():
            while True:
                counts = await db.guide_stage_counts(topic, format_name)
                done = counts.get("done", 0)
                total = sum(counts.values())
                await db.update_guide(guide_id, progress=f"Board: {done}/{total} Karten fertig")
                await asyncio.sleep(2.0)

        reporter = asyncio.create_task(_progress())
        try:
            await asyncio.gather(*[_run_card(env, c, sem) for c in open_cards])
        finally:
            reporter.cancel()
            db.set_current_run(topic, None)
    else:
        db.set_current_run(topic, None)
    if is_guide_cancelled(guide_id):
        return None
    # assembly — identical shape to the legacy pipeline
    cards = await db.list_guide_cards(topic, format_name)
    chapters: list[dict] = []
    by_chapter: dict[str, list[dict]] = {}
    order: list[str] = []
    for c in sorted(cards, key=lambda c: (c["ord"], c["block_norm"])):
        if c["stage"] != "done":
            _log(topic, f"Guide: Karte '{c['block']}' nicht fertig ({c['stage']}) — Abschnitt fehlt")
            continue
        sec = _first_section(c["md"])
        if sec is None:
            continue
        ch = c["chapter"] or "Inhalte"
        if ch not in by_chapter:
            by_chapter[ch] = []
            order.append(ch)
        by_chapter[ch].append({
            "num": c["ord"], "title": c["block"], "md": sec["md"],
            "compact": sec.get("compact", ""), "anchor": sec.get("anchor", ""),
            "anker_compact": sec.get("anker_compact", ""), "subs": sec.get("subs", []),
            "checkable": format_name == "Guide" or bool(
                any(s.get("relevance") == "relevant" for s in subs_raw.get(c["block"], []))),
        })
    for ch in order:
        chapters.append({"title": ch, "sections": by_chapter[ch]})
    if chapters:
        try:  # Abschluss-Guide-QA (best-effort): speist das Badge mit einer frischen Note
            import guide_qa
            rep = await guide_qa.guide_qa_report(topic, llm=True)
            if rep:
                await asyncio.to_thread(guide_qa._write_report, rep)
        except Exception:
            log.exception("[%s] Abschluss-Guide-QA fehlgeschlagen", topic)
    return chapters or None


async def done_step(topic: str, format_name: str) -> int:
    """Sidebar dots: highest fully completed stage index. -1 = nothing, len(stages) at done."""
    counts = await db.guide_stage_counts(topic, format_name)
    if not counts:
        return -1
    if set(counts) == {"done"}:
        return len(GUIDE_STAGES)
    lowest = min(GUIDE_STAGES.index(s) for s in counts if s in GUIDE_STAGES)
    return lowest - 1 if lowest > 0 else -1


async def board_snapshot(topic: str, format_name: str, limit: int = 20) -> dict:
    """Live guide board: columns with counts + cards (title, rounds, covered objectives)."""
    cards = await db.list_guide_cards(topic, format_name)
    ziele = {}
    for z in await db.list_lernziele(topic):
        d = ziele.setdefault(z["block_norm"], [0, 0])
        d[1] += 1
        d[0] += 1 if z["covered"] else 0
    columns = []
    for stage in (*GUIDE_STAGES, "done"):
        in_stage = [c for c in cards if c["stage"] == stage]
        views = []
        for c in in_stage[:limit]:
            zc = ziele.get(c["block_norm"])
            info = c["gate_info"][:200] if c["status"] == "error" else ""
            if c["status"] == "active":
                info = _live_info.get((topic, format_name, c["block_norm"]), "") or info
            views.append({"title": c["block"], "card_id": c["block_norm"],
                          "status": c["status"] if c["status"] in ("error", "active") else "open",
                          "rounds": c["writer_rounds"],
                          "info": info,
                          "ziele": f"{zc[0]}/{zc[1]}" if zc else ""})
        columns.append({"key": stage, "label": STAGE_LABELS[stage],
                        "total": len(in_stage), "cards": views})
    import qa as qa_mod  # lazy wie in board_inventory
    tdir = qa_mod.QA_DIR / topic
    greports = sorted(tdir.glob("guide-*.json"), key=lambda p: p.stat().st_mtime) if tdir.is_dir() else []
    note_guide = (_json_file(greports[-1]) or {}).get("note_guide") if greports else None
    return {"columns": columns, "qa_guide": note_guide}


async def reset_card(topic: str, format_name: str, block_norm: str, ab_stage: int) -> bool:
    """Reset ONE guide card to a stage (single-card variant of reset_from_stage):
    fields re-zeroed, md only wiped for writer(2) and earlier, lernziele only for 0."""
    ab_stage = max(0, min(ab_stage, len(GUIDE_STAGES) - 1))
    cards = {c["block_norm"]: c for c in await db.list_guide_cards(topic, format_name)}
    if block_norm not in cards:
        return False
    fields = dict(stage=GUIDE_STAGES[ab_stage], status="open", writer_rounds=0, gate_info="")
    if ab_stage <= 2:
        fields["md"] = ""
    if ab_stage == 0:
        await db.delete_lernziele(topic, block_norm)
    await db.set_guide_card(topic, format_name, block_norm, **fields)
    return True


async def reset_from_stage(topic: str, format_name: str, ab_stage: int) -> int:
    """Cards in stages ≥ ab_stage (incl. done) back to GUIDE_STAGES[ab_stage]."""
    ab_stage = max(0, min(ab_stage, len(GUIDE_STAGES) - 1))
    target = GUIDE_STAGES[ab_stage]
    stages = list(GUIDE_STAGES[ab_stage:]) + ["done"]
    if ab_stage == 0:
        for c in await db.list_guide_cards(topic, format_name):
            await db.delete_lernziele(topic, c["block_norm"])
    moved = await db.reset_guide_cards_from_stage(topic, format_name, stages, target,
                                                  clear_md=ab_stage <= 2)
    return moved