diff --git a/.gitea/PULL_REQUEST_TEMPLATE.md b/.gitea/PULL_REQUEST_TEMPLATE.md index 5daa1a1..7078c32 100644 --- a/.gitea/PULL_REQUEST_TEMPLATE.md +++ b/.gitea/PULL_REQUEST_TEMPLATE.md @@ -1,6 +1,6 @@ . --> @@ -11,8 +11,9 @@ ## Invariants — הצהרה (חובה) @@ -22,6 +23,7 @@ - [ ] קראתי את `docs/spec/00-constitution.md` + ספ-התחום הרלוונטי לפני הכתיבה - [ ] השינוי **לא** יוצר מסלול מקביל ליכולת קיימת (G2) ולא מתקן תסמין בקריאה (G1) +- [ ] **לא** הוספתי מגע-Paperclip מחוץ ל-Platform Port (G12) — `mcp-server/src` וה-skills נקיים - [ ] אין בליעה שקטה של שגיאות — רשומה חסרה/פגומה מסומנת ומדווחת (כלל-הנדסה §6) - [ ] בדקתי מול `docs/spec/gap-audit.md` — אם נגעתי ב-GAP/FU ממופה, התאמתי ליחידת-התיקון - [ ] בדיקות עוברות (אם רלוונטי) / לא נדרשות diff --git a/CLAUDE.md b/CLAUDE.md index e8123f1..8728df3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -74,14 +74,14 @@ **לפני יצירה/שינוי של קוד ב-`web/`, `mcp-server/`, `web-ui/`, `scripts/`:** -1. **קרא** [`docs/spec/00-constitution.md`](docs/spec/00-constitution.md) — ייעוד, ה-invariants הגלובליים G1–G11, וכללי-ההנדסה (§6). אינדקס-הספ ב-§7. -2. **קרא את ספ-התחום הרלוונטי** לפי האינדקס (§7) — לדוגמה: אחזור→[`03-retrieval.md`](docs/spec/03-retrieval.md), קליטה→[`01-ingest.md`](docs/spec/01-ingest.md), נתונים→[`02-data-model.md`](docs/spec/02-data-model.md), כלי-MCP→[`X9-mcp-tool-contract.md`](docs/spec/X9-mcp-tool-contract.md), UI↔API→[`X6-ui-api-contract.md`](docs/spec/X6-ui-api-contract.md), Paperclip→[`X3`](docs/spec/X3-integration-deploy.md)/[`X7`](docs/spec/X7-paperclip-client-params.md), env/secrets→[`X10-deploy-env-secrets.md`](docs/spec/X10-deploy-env-secrets.md). +1. **קרא** [`docs/spec/00-constitution.md`](docs/spec/00-constitution.md) — ייעוד, ה-invariants הגלובליים G1–G12, וכללי-ההנדסה (§6). אינדקס-הספ ב-§7. +2. **קרא את ספ-התחום הרלוונטי** לפי האינדקס (§7) — לדוגמה: אחזור→[`03-retrieval.md`](docs/spec/03-retrieval.md), קליטה→[`01-ingest.md`](docs/spec/01-ingest.md), נתונים→[`02-data-model.md`](docs/spec/02-data-model.md), כלי-MCP→[`X9-mcp-tool-contract.md`](docs/spec/X9-mcp-tool-contract.md), UI↔API→[`X6-ui-api-contract.md`](docs/spec/X6-ui-api-contract.md), Paperclip/שער-הפלטפורמה→[`X3`](docs/spec/X3-integration-deploy.md)/[`X7`](docs/spec/X7-paperclip-client-params.md)/[`X15`](docs/spec/X15-agent-platform-port.md) (G12), עמידות-פייפליין→[`X16`](docs/spec/X16-pipeline-durability.md), env/secrets→[`X10-deploy-env-secrets.md`](docs/spec/X10-deploy-env-secrets.md). 3. **ודא שהשינוי *מקיים* את ה-invariants** — לא יוצר מסלול מקביל ליכולת קיימת ([G2](docs/spec/00-constitution.md)), לא מתקן תסמין בקריאה במקום נרמול במקור (G1), לא בולע שגיאות בשקט (כלל-הנדסה §6). 4. **בדוק מול** [`gap-audit.md`](docs/spec/gap-audit.md) — אם אתה נוגע ב-GAP/FU שכבר ממופה, התאם את העבודה ליחידת-התיקון; אל תפתור מחדש. 5. **כל PR מצהיר invariants** — אילו G*/INV-* ה-PR נוגע בהם / מקיים (ראה תבנית ה-PR ב-[`.gitea/PULL_REQUEST_TEMPLATE.md`](.gitea/PULL_REQUEST_TEMPLATE.md)). > **שתי שכבות-כללים מובחנות, שתיהן חלות:** -> - **הנדסה (G1–G10)** — הסעיף הזה + `docs/spec/`. סמכות: ≥3 מקורות חיצוניים. +> - **הנדסה (G1–G10, G12)** — הסעיף הזה + `docs/spec/`. סמכות: ≥3 מקורות חיצוניים. > - **תוכן משפטי (G11)** — סעיף "עקרונות כתיבה קריטיים" למטה (12 בלוקים, רקע ניטרלי...). סמכות: היו"ר + מסמכי-הפרויקט. > > אכיפה אוטומטית: hook `PreToolUse` ([scripts/spec-guard.sh](scripts/spec-guard.sh)) מזכיר את הפרוטוקול בכל Edit/Write על נתיב-קוד. @@ -129,6 +129,8 @@ cd ~/legal-ai && claude --worktree # או, בתוך סשן: "עבוד **פירוט מלא + דוגמאות + פקודות sync: [`docs/operations-runbook.md`](docs/operations-runbook.md).** +> **G12 — שער-הפלטפורמה ([`docs/spec/X15-agent-platform-port.md`](docs/spec/X15-agent-platform-port.md)):** Paperclip היא **מעטפת ניתנת-להחלפה** מאחורי Port יחיד. מגע-Paperclip מותר רק ב-`web/agent_platform_port.py` + `HEARTBEAT.md` (לפרומפטים) + המעטפת המוצהרת (`paperclip_client/api`, plugin, adapters). **אסור** סמל ספציפי-Paperclip ב-`mcp-server/src` או ב-skills של ההחלטה/הסגנון. כל מגע חדש → דרך ה-Port. + - **Wakeup תמיד דרך API**: `POST /api/agents/{agent-id}/wakeup` עם `payload.issueId`. **אסור** `INSERT INTO agent_wakeup_requests` ישיר — הסוכן לא יתעורר לעולם (אין `heartbeat_run`). - **ניתוב comments דרך CEO**: תגובת-משתמש → פלאגין מעיר CEO → CEO מנתב ויוצר issue. סוכנים קוראים comments אחרונים לפני עבודה (HEARTBEAT 2b-2c). - **קריאות API דרך helper בלבד**: bash → `scripts/pc.sh`; Python → `pc_request()` מ-`web/paperclip_api.py`. **אסור** `curl` ישיר ל-Paperclip או `httpx.AsyncClient` ישיר. diff --git a/docs/spec/00-constitution.md b/docs/spec/00-constitution.md index 3996145..2f40a52 100644 --- a/docs/spec/00-constitution.md +++ b/docs/spec/00-constitution.md @@ -78,13 +78,14 @@ אלה החוקים החוצים את כל המערכת — לב החוקה. הם נחלקים לשני סוגים לפי **מקור-הסמכות**: -- **G1–G10 — invariants הנדסיים** (תכנון/בניית האפליקציה): כל אחד מגובה ב-**≥3 סמכויות +- **G1–G10, G12 — invariants הנדסיים** (תכנון/בניית האפליקציה): כל אחד מגובה ב-**≥3 סמכויות טכניות מוכרות** (נספח §8). ביחד הם מייבשים את כשל-השורש החוזר: מסלולים/קורפוסים - מקבילים שמתפצלים (drift) בלי שכבה שמגדירה ואוכפת "תקין". + מקבילים שמתפצלים (drift) בלי שכבה שמגדירה ואוכפת "תקין". (G12 — שער-הפלטפורמה — מוסף + במחזור-3; ראה [X15](X15-agent-platform-port.md).) - **G11 — invariant תוכן-משפטי:** הסמכות עליו היא **היו"ר (דפנה) + מסמכי-הפרויקט**, לא מקורות חיצוניים, ואינו כפוף לפרוטוקול ≥3-המקורות. -### 5א. Invariants הנדסיים (G1–G10) +### 5א. Invariants הנדסיים (G1–G10, G12) ### INV-G1: מזהה קנוני מנורמל בכתיבה **כלל:** לכל ישות יש מזהה קנוני יחיד, **מנורמל בנקודת-הכתיבה** (לא תיקון-סלחני בקריאה @@ -196,6 +197,22 @@ Hellyer (Law Library Journal 110:4, 2018, open-access) — טיפול-שיפוט **הפרה ידועה:** 10/19 הלכות מאושרות, התגלה במקרה — שער ידני שקוף בלי נראות backlog → ממצא ל-[audit](../audit-report.md). +### INV-G12: שער-הפלטפורמה — Paperclip מאחורי Port יחיד +**כלל:** פלטפורמת-הסוכנים (Paperclip) נגישה אך-ורק דרך **ה-Platform Port** +(`web/agent_platform_port.py` + `.claude/agents/HEARTBEAT.md` לפרומפטים). שכבת-האינטליגנציה +— `mcp-server/src` וה-skills של ההחלטה/הסגנון — מכילה **אפס** סמלים ספציפיים-לפלטפורמה +(שם-מוצר, wakeup/heartbeat, pc.sh/pc_request, X-Paperclip-Run-Id, enums של הפלטפורמה). +פרומפטי-הסוכנים אינם משכפלים את פרוטוקול-הריצה — הם מצביעים ל-HEARTBEAT.md בלבד. כל מגע +חדש עם הפלטפורמה עובר דרך ה-Port — כך המעטפת נשארת ניתנת-להחלפה בלי לגעת באינטליגנציה. +**מקורות:** Alistair Cockburn — *Hexagonal Architecture (Ports & Adapters)* · Robert C. +Martin — *Clean Architecture* (The Dependency Rule) · Eric Evans — *Domain-Driven Design* +(Anti-Corruption Layer) | סטטוס: verified +**אכיפה:** רשימת-ה-Port + leak-guard ב-[scripts/spec-guard.sh](../../scripts/spec-guard.sh) +(מול baseline) + fitness-test ב-CI על `mcp-server/src` + הצהרת-G12 בתבנית-ה-PR; מפורט ב- +[X15-agent-platform-port.md](X15-agent-platform-port.md). +**הפרה ידועה:** `web/app.py` קורא ל-`pc_*` inline בלוגיקת מחזור-חיים; 10 פרומפטי-סוכנים +משכפלים את פרוטוקול-הריצה במקום להצביע ל-HEARTBEAT (baseline ב-[X15](X15-agent-platform-port.md) §3 → R1–R4). + ### 5ב. Invariant תוכן-משפטי (G11) ### INV-G11: תוכן החלטה מנומקת @@ -227,11 +244,11 @@ Hellyer (Law Library Journal 110:4, 2018, open-access) — טיפול-שיפוט ## 7. אינדקס הספ -> הערה: כל קבצי הספ (00, 01–07, X1–X12) קיימים. החוקה היא שער-הכניסה; כל קובץ-תחום כפוף לה. +> הערה: כל קבצי הספ (00, 01–07, X1–X16) קיימים. החוקה היא שער-הכניסה; כל קובץ-תחום כפוף לה. | קובץ | תפקיד | אוכף invariants | |------|--------|-----------------| -| [00-constitution.md](00-constitution.md) | חוקה — ייעוד, invariants גלובליים, כללי-הנדסה, אינדקס | G1–G11 | +| [00-constitution.md](00-constitution.md) | חוקה — ייעוד, invariants גלובליים, כללי-הנדסה, אינדקס | G1–G12 | | [01-ingest.md](01-ingest.md) | קליטה מאוחדת: מסמכי-תיק / פסיקה חיצונית / החלטות-ועדה — חוזה מסלול-יחיד | G2, G3 | | [02-data-model.md](02-data-model.md) | אחסון: ישויות (cases, case_law, documents, chunks, halachot…) + חוזה-שלמות לכל ישות | G1, G4, G6 | | [03-retrieval.md](03-retrieval.md) | 3 קורפוסים + כלי-חיפוש · hybrid/RRF · attribution · eval harness | G4, G5, G6, G7, G8, G9 | @@ -252,6 +269,9 @@ Hellyer (Law Library Journal 110:4, 2018, open-access) — טיפול-שיפוט | [X11-citation-corroboration.md](X11-citation-corroboration.md) | citator פנימי — תיקוף הלכות בטיפול-שיפוטי מצטבר · תיקון-G10 מבוקר · סף-corroboration · התאמה-להלכה | G9, G10 | | [X12-digests-radar.md](X12-digests-radar.md) | יומונים כשכבת-גילוי (radar) — מקור-משני המצביע על הפסק המקורי · לא קורפוס-ציטוט רביעי · לא מצוטט/לא מחלץ-הלכות | G2, G4, G9 | | [X13-court-fetch.md](X13-court-fetch.md) | אחזור-פסיקה אוטומטי מנט המשפט — 3 שכבות (עליון/מנהלי/skip) · שירות-מארח · reCAPTCHA · שער-אנושי | G2, G3, G4, G5, G9, G10 | +| [X14-storage-minio.md](X14-storage-minio.md) | אחסון-אובייקטים (MinIO/S3) · `storage.py` כמסלול-I/O יחיד · git=טקסט/MinIO=בינאריים · WORM סופי | G2, G9 | +| [X15-agent-platform-port.md](X15-agent-platform-port.md) | שער-הפלטפורמה — Paperclip מאחורי Port יחיד · baseline-דליפה · R0–R4 · leak-guard | G2, G12 | +| [X16-pipeline-durability.md](X16-pipeline-durability.md) | עמידות-פייפליין — LangGraph כספרייה · checkpointing/replay · `_pipeline_runtime.py` משותף | G3 | > **X6–X10 (מחזור-2):** מכסים את 8 משטחי-האפליקציה שמחוץ לצינור-הליבה (אינטגרציה, web-ui, מילוי-שדות, > אחסון-ניתוחים, כלי-MCP, deploy/env). הממצאים ב-[gap-audit.md](gap-audit.md) (GAP-24..62 → FU-9..15) diff --git a/docs/spec/X15-agent-platform-port.md b/docs/spec/X15-agent-platform-port.md index 6692895..62f03a1 100644 --- a/docs/spec/X15-agent-platform-port.md +++ b/docs/spec/X15-agent-platform-port.md @@ -81,9 +81,8 @@ Martin, *Clean Architecture* (The Dependency Rule) · Eric Evans, *Domain-Driven **הפרה ידועה:** ראו מצאי-הדליפה ב-§3 — `web/app.py` קורא ל-`pc_*` inline בלוגיקת מחזור-חיים של תיקים; 10 פרומפטי-סוכנים משכפלים את פרוטוקול-הריצה במקום להצביע ל-HEARTBEAT. -> **סיווג:** invariant הנדסי (≥3 מקורות חיצוניים, verified). מורחב מ-G1–G10 בתור **G12**. -> רישומו ברשימת-הגלובליים ובאינדקס של [00-constitution.md](00-constitution.md) מתבצע במשימת -> R0b (תיקון-תיעוד) — עד אז המסמך הזה הוא מקור-האמת ל-G12. +> **סיווג:** invariant הנדסי (≥3 מקורות חיצוניים, verified). מורחב מ-G1–G10 בתור **G12**, +> ורשום ברשימת-הגלובליים ובאינדקס של [00-constitution.md](00-constitution.md) §5א (R0b הושלם). ---