docs: known-issues 아카이빙 + Collector 폐기 마킹 + 레퍼런스 문서 보강 #task-409

.agents/references/conventions.md

@@ -89,3 +89,37 @@ Extension 모듈 분리 시 사용하는 패턴:
 | Extension | `logToFile(msg)` → bridge/log/ | `[HH:MM:SS] message` + `[WS]` prefix |
 | Hub | `[HUB]` prefix | `[HUB] Auth OK: {conn_id} project={project}` |
 | Gateway | `[GATEWAY]` prefix | `[GATEWAY] HTTP API started on {host}:{port}` |
+
+## WS / File Bridge 상호 배타 패턴
+
+> [!IMPORTANT]
+> WS Hub과 파일 bridge는 **항상 상호 배타적**이어야 합니다.
+> 양쪽에 동시에 쓰면 이중 전달 버그가 발생합니다. (known-issues-archive 참조)
+
+**Extension (TypeScript):**
+```typescript
+// ✅ 올바른 패턴
+if (ctx.wsBridge?.isConnected()) {
+    ctx.wsBridge.sendPending(data);
+    return;  // ← 반드시 return으로 파일 쓰기 건너뛰기
+}
+// File fallback
+fs.writeFileSync(pendingPath, JSON.stringify(data));
+```
+
+**Bot (Python):**
+```python
+# ✅ 올바른 패턴
+if self.hub:
+    await self.hub.send_response(...)
+else:
+    bridge.write_response(...)
+```
+
+**금지 패턴:**
+```python
+# ❌ 이중 쓰기 — 절대 금지
+if self.hub:
+    await self.hub.send_response(...)
+bridge.write_response(...)  # ← Hub 성공해도 파일에도 씀 → 이중 처리
+```