docs/paperclip-quirks.md

@@ -230,3 +230,48 @@ pm2 start paperclip && pm2 save                         # reuse ל-cache המת
 - **תוקן ב-start script** ע"י `ensure_patched_before_run()` (06/06/26) — שער סינכרוני שמחלץ+מתקן לפני exec.
 - **הערה מטעה תוקנה**: ההערה הישנה בראש ה-script טענה ש-`npx run` מחלץ-מחדש בכל הפעלה (לכן הסתמכו על לולאת-הרקע בלבד) — זה לא נכון, npx עושה reuse ל-cache תקין; הסכנה היא cache **מחוק**.
 - **לקח כללי**: כל patch שה-target שלו הוא assert בזמן-startup חייב להיות מוחל לפני `exec`, לא בלולאת-רקע.
+
+---
+
+## 6. `issue.comment.created` — מזהה-ה-issue ב-`entityId`, לא ב-`payload.issueId`
+
+### מה קורה
+
+ל-event `issue.comment.created` שה-host שולח לפלאגין, **מזהה-ה-issue נמצא ב-`event.entityId`** (ה"ישות הראשית" של ה-event), ולא ב-`payload`. ה-`payload` נושא דווקא:
+- `commentId` — מזהה התגובה
+- `bodySnippet` — גוף **קצוץ** (לא הטקסט המלא)
+- `reopened` / `reopenedFrom` — נדלקים כשהתגובה פתחה-מחדש issue ב-`done`
+
+**אין** `payload.issueId` ו**אין** `payload.body` מלא. מקור-אמת: `@paperclipai/plugin-sdk` `index.d.ts` — `issueId: event.entityId`.
+
+### ראיה אמפירית — תיק 8124-09-24, CMPA (17/06/26)
+
+תגובת-משתמש על sub-issue של המנתח המשפטי (במצב `done`) **לא הגיעה ל-CEO**. הניתוב ב-`plugin-legal-ai/src/worker.ts` קרא `payload.issueId` (תמיד `undefined`) ולכן דילג בשקט:
+
+```
+WARN [plugin] issue.comment.created event missing issueId in payload, skipping
+  { entityId: "6eb905ea-…",           ← זה ה-issue id האמיתי
+    payload: { commentId: "31e35676-…", bodySnippet: "…", reopened: true,
+               reopenedFrom: "done", identifier: "CMPA-94", … } }   ← אין issueId
+```
+
+### ההשפעה על הצינור שלנו
+
+הניתוב **"תגובת-משתמש → CEO"** (CLAUDE.md §"ניתוב comments דרך CEO") היה **מת בשקט** — כל תגובה דולגה. במקרה של תגובה על issue בבעלות ה-CEO זה "עבד" רק במקרה דרך מנגנון reopen-on-comment הנייטיב של Paperclip (פותח-מחדש `done` ומעיר את הסוכן-המשויך). על sub-issue של סוכן אחר, ה-wake הנייטיב כיוון לסוכן הלא-נכון וריצת-ה-CEO בתור בוטלה עם `errorCode: issue_assignee_changed` ("the new owner will be woken instead" — וה"בעלים" ב-`done` ⇒ כלום).
+
+### תיקון — בצד שלנו (PR ezer-mishpati/plugin-legal-ai#2)
+
+ב-handler של `issue.comment.created`:
+1. `issueId = event.entityId` (fallback ל-`payload.issueId` לעמידות מול גרסאות-host).
+2. גוף-תגובה מלא: התאמת `payload.commentId` מתוך `listComments` (ה-payload נושא רק snippet); fallback ל-latest/snippet.
+3. **guard לדה-דופ:** אם התגובה פתחה-מחדש issue **שכבר משויך ל-CEO** (`issue.assigneeAgentId === ceoAgentId && payload.reopened`), ה-wake הנייטיב כבר מטפל — מדלגים כדי לא להריץ את ה-CEO פעמיים. לכל issue אחר עדיין מנתבים ל-CEO.
+
+### אימות (17/06/26)
+
+תגובת-בדיקה על אותו sub-issue של המנתח (`543f997b`, `done`) לאחר deploy → לוג `Routed user comment to CEO agent` עם `runId`, וריצת-CEO `succeeded` (לא `cancelled`).
+
+### סטטוס
+
+- **תוקן בצד שלנו** (PR #2, נפרס דרך `npm run build` + `pm2 restart paperclip` — הפלאגין נטען מ-`/home/chaim/plugin-legal-ai` לפי `package_path`).
+- **לקח כללי**: ל-events של הפלאגין — מזהה-הישות-הראשית הוא תמיד `event.entityId`; אל תניח ששדות נמצאים ב-`payload` בלי לאמת מול ה-`.d.ts` של ה-SDK או מול לוג חי.
+- TaskMaster: `legal-ai` #149.