feat: case-study notebooks (envir + KK afgørelse), conductor.viz, dep-graph fix

[mhenrichsen]

Summary

Two new case-study notebooks demonstrating Conductor against real-world processes, a graph-visualization helper, and one engine bug fix surfaced while building them.

Notebooks

• examples/09_case_study_miljorapport.ipynb — the PLST environmental-impact-report pipeline. Models the parse → context extraction → external data fan-out → 14 chapter generation → revise/ground → resume → docx assembly chain. Uses for-each for the external fetches, shared references for project_context / EA index broadcast across chapters, SKIPPED-sentinel routing for the eval/revise branch, ConnectionList aggregation for the cumulative chapter and the docx assembler, and a HumanInputRequired pause modeling the dataset-mapping review.
• examples/10_case_study_kk_afgorelse.ipynb — the Copenhagen Municipality kolonihave decision-draft pipeline. Showcases a different mix: parallel OCR fan-out (for-each + execution_mode="Parallel"), a sequential checkpoint chain folded through FlowStore, decision-node + edge-guard CEL routing to one of five draft generators, and a human-in-the-loop approval gate that lets a case officer override the AI recommendation.

Both notebooks run end-to-end with stubbed services (no API keys, no network).

conductor.viz

New module: to_mermaid(compiled, *, direction="LR") renders any CompiledGraph as a Mermaid flowchart string. Wrap in a fenced ```mermaid block — GitHub renders it natively, Jupyter via IPython.display.Markdown. Visual conventions:

• regular IO node → [rectangle]
• decision node → {diamond}
• compound start → [[subroutine]]
• managed body / end → [/parallelogram/]
• explicit edge → solid arrow with handle labels and CEL guards rendered between ⟦…⟧
• shared reference (consume binding) → dashed arrow

7 unit tests in tests/test_core/test_viz.py. Both case-study notebooks include a render cell using it.

Engine fix

packages/conductor/src/conductor/execution/engine.py:_build_dep_graph now redirects edge-based dependencies through managed_to_region_start exactly like consume_map already did. Without this, any node positioned downstream of a for-each-end had in_degree=0 (because end is not in schedulable), so it dispatched immediately and raced the region body — observed as a node firing with empty/missing inputs in the envir notebook's index-results step. Regression test added at tests/test_core/test_compound.py::TestForEachDownstreamNode::test_node_after_end_sees_collected_results.

Index updates

• CLAUDE.md notebook count (7 → 10).
• README.md examples table — rows for 09 and 10.

Test plan

• Full suite: 438 tests pass (was 430; +1 regression test for the engine fix, +7 for conductor.viz).
• uvx ruff check . clean.
• Both notebooks execute end-to-end via jupyter nbconvert --execute and produce sensible output (chapter drafts assembled, kk decision routes to the chosen branch).
• Open the notebooks locally and inspect the rendered Mermaid diagrams.

🤖 Generated with Claude Code