refactor: assert warn sink, rename disk-pair sifter, trim WHAT docstrings

Capture loguru warning via project sink pattern and assert the dangling-orphan
warning is emitted; rename _sift_disk_pairs to _keep_complete_disk_pairs; drop
pure-WHAT docstrings on __init__/pending_orphans while keeping WHY notes.

app/question_gen/pair_atomic_writer.py

@@ -59,7 +59,7 @@ class PairPendingBuffer:
     """
 
     def __init__(self) -> None:
-        """初始化空缓冲器。pending 以 pair_id 索引首个到达的孪生对成员。"""
+        """pending 以 pair_id 索引首个到达的孪生对成员，等伙伴到齐再 emit。"""
         self._pending: dict[str, GeneratedQuestion] = {}
 
     def add(self, q: GeneratedQuestion) -> QuestionUnit | None:
@@ -89,11 +89,7 @@ class PairPendingBuffer:
         return unit
 
     def pending_orphans(self) -> list[GeneratedQuestion]:
-        """返回当前仍未配齐的孤儿成员（供批次末尾检测悬挂项）。
-
-        返回:
-            尚在缓冲、未等到伙伴的孪生对成员列表（按 pair_id 插入顺序）。
-        """
+        """返回仍未配齐的悬挂成员，供调用方在批次末尾检测"只落 P 未落 Q"。"""
         return list(self._pending.values())
 
 
@@ -138,7 +134,7 @@ def _validate_disk_pair(pair_id: str, group: list[GeneratedQuestion]) -> list[Ge
     )
 
 
-def _sift_disk_pairs(questions: list[GeneratedQuestion]) -> list[GeneratedQuestion]:
+def _keep_complete_disk_pairs(questions: list[GeneratedQuestion]) -> list[GeneratedQuestion]:
     """筛选磁盘读回的题目：single 全保留、pair 按 ``_validate_disk_pair`` 三态处理。
 
     悬挂孤儿 warn+drop、结构损坏/绑定不一致 raise ValueError、合法成对保留后交给
@@ -182,7 +178,7 @@ def write_accepted(path: Path, units: list[QuestionUnit]) -> None:
 def read_accepted(path: Path) -> list[QuestionUnit]:
     """读回 path 的 accepted JSON → 聚合为单元列表。
 
-    磁盘是外部输入，按 P5 全量校验后再用：``_sift_disk_pairs`` 对 pair 分组三态处理
+    磁盘是外部输入，按 P5 全量校验后再用：``_keep_complete_disk_pairs`` 对 pair 分组三态处理
     ——"只落 P 未落 Q"的悬挂孤儿 warn+drop（不进结果、不 raise）；结构损坏（超员/
     角色重复）或绑定不一致（video_id/task_type/flip_axis）显式 raise ValueError（不
     依赖 build_units 内会被 ``-O`` 剥除的 assert）。single 全保留。
@@ -196,5 +192,5 @@ def read_accepted(path: Path) -> list[QuestionUnit]:
 
     raw = json.loads(path.read_text(encoding="utf-8"))
     questions = [_dict_to_q(d) for d in raw]
-    kept = _sift_disk_pairs(questions)
+    kept = _keep_complete_disk_pairs(questions)
     return validate_units(build_units(kept))