Chaim
1e4c5c1518
All checks were successful
Build & Deploy / build-and-deploy (push) Successful in 3m16s
New "Agents" tab in case detail shows all Paperclip agent comments,
issue status, and agent status for each case — eliminating the need
to switch between Legal-AI and Paperclip UIs.
Backend: 4 new DB query functions in paperclip_client.py (issues,
comments, agents, post_comment) + 2 new API endpoints (GET/POST
/api/cases/{case_number}/agents). Comment posting uses Board API
with DB+wakeup fallback to ensure CEO routing.
Frontend: agents.ts hooks (10s polling), AgentActivityFeed component
(markdown timeline + comment input), AgentStatusWidget (sidebar),
4th tab in case detail page.
Also includes new-company-setup-guide.md documenting the process
for setting up the betterment levy (CMPA) company.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
404 lines
20 KiB
Markdown
404 lines
20 KiB
Markdown
# מדריך הקמת חברה חדשה — היטלי השבחה (CMPA)
|
||
|
||
> נוצר: 2026-04-15
|
||
> מטרה: תיעוד מפורט של התהליך להקמת קורפוס אימון והגדרת חברה בשתי המערכות
|
||
|
||
---
|
||
|
||
## רקע
|
||
|
||
המערכת שלנו בנויה מ-**2 חברות** (boards) ב-Paperclip, שמייצגות את שני תחומי העבודה העיקריים:
|
||
|
||
| # | חברה | קוד | Prefix | סוגי תיקים | סטטוס קורפוס |
|
||
|---|-------|------|--------|------------|---------------|
|
||
| 1 | רישוי ובנייה | CMP | `42a7acd0...` | 1xxx | 24 החלטות אימון, ניתוח סגנון מלא |
|
||
| 2 | היטלי השבחה + פיצויים | CMPA | `8639e837...` | 8xxx, 9xxx | **ריק — אין אף החלטת אימון** |
|
||
|
||
**המצב היום**: חברת CMPA כבר קיימת ב-Paperclip ומופתה בקוד (ניתוב אוטומטי לפי מספר תיק). אבל אין לה **קורפוס אימון** — המערכת לא מכירה את הסגנון של דפנה בהחלטות היטל השבחה ולא יכולה לחפש תקדימים.
|
||
|
||
**מה שצריך לעשות**: להעלות את ההחלטות, לעבד אותן, ולהריץ ניתוח סגנון — בדיוק כמו שנעשה עם 24 ההחלטות של רישוי ובנייה.
|
||
|
||
---
|
||
|
||
## שתי המערכות — הגדרת תפקידים
|
||
|
||
### מערכת 1: עוזר משפטי (Legal-AI)
|
||
|
||
**תפקיד**: מערכת הידע, הניתוח והניסוח — מחזיקה את כל התוכן המשפטי ומספקת כלים לכתיבת החלטות.
|
||
|
||
**מה חי רק במערכת הזו**:
|
||
|
||
| רכיב | תיאור | טבלת DB |
|
||
|-------|--------|---------|
|
||
| תיקים (Cases) | מספר תיק, כותרת, סטטוס, צדדים | `cases` |
|
||
| מסמכי מקור | כתבי ערר, תגובות, פרוטוקולים (PDF/DOCX) | `documents` + filesystem |
|
||
| חלקים סמנטיים (Chunks) | embeddings לחיפוש RAG (Voyage AI, 1024 ממדים) | `document_chunks` + pgvector |
|
||
| קורפוס אימון | החלטות קודמות של דפנה — גרסאות מנוקות | `style_corpus` |
|
||
| דפוסי סגנון | ביטויי מעבר, נוסחאות פתיחה/סיום, מבנה ניתוח | `style_patterns` |
|
||
| בלוקי החלטה | 12 בלוקים (מבנה ההחלטה) + פסקאות | `decision_blocks`, `decision_paragraphs` |
|
||
| טענות צדדים | טענות שחולצו מכתבי טענות | `claims` |
|
||
| תקדימים (פסיקה) | ספריית case law + embeddings | `case_law`, `case_law_embeddings` |
|
||
| חקיקה | סעיפי חוק שאוזכרו | `statutory_provisions` |
|
||
| הערות יו"ר | feedback של דפנה על טיוטות | `chair_feedback` |
|
||
| לקחים | תובנות שחולצו מ-feedback | `lessons_learned` |
|
||
| צ'קליסטים | רשימות בדיקה לבלוק דיון (לפי סוג ערר) | hardcoded ב-`lessons.py` |
|
||
| מיפוי חברות | קישור appeal_subtype ← company_id | `tag_company_mappings` |
|
||
|
||
**שירותי הליבה**:
|
||
- **RAG** — חיפוש סמנטי בתקדימים ובמסמכי מקור, מסונן לפי `appeal_subtype`
|
||
- **Proofreading** — ניקוי מסמכי נבו מ-artifacts
|
||
- **Style Analysis** — ניתוח קורפוס וחילוץ דפוסי כתיבה
|
||
- **Decision Drafting** — ייצור טיוטות לפי ארכיטקטורת 12 בלוקים
|
||
- **DOCX Export** — מסמך מעוצב מוכן להגשה
|
||
|
||
---
|
||
|
||
### מערכת 2: Paperclip
|
||
|
||
**תפקיד**: מערכת התזמור והסוכנים — מנהלת את תהליך העבודה, מפעילה סוכני AI, ומספקת ממשק Kanban.
|
||
|
||
**מה חי רק במערכת הזו**:
|
||
|
||
| רכיב | תיאור | טבלת DB |
|
||
|-------|--------|---------|
|
||
| חברות (Companies) | CMP (רישוי), CMPA (היטלי השבחה) — boards נפרדים | `companies` |
|
||
| פרויקטים | כרטיס Kanban לכל תיק | `projects` |
|
||
| Issues | משימות עבודה (CMP-123, CMPA-456) | `issues` |
|
||
| תגובות | דיון בין סוכנים ומשתמשים | `issue_comments` |
|
||
| סוכנים (Agents) | CEO, Researcher, Writer — Claude Code agents | מערכת agents |
|
||
| SOUL.md | הנחיות לכל סוכן | קונפיגורציית agent |
|
||
| Skills | workflows לשימוש חוזר (SKILL.md) | `company_skills` + filesystem |
|
||
| Plugin state | נתוני plugin (case_number ← issue) | `plugin_state` |
|
||
|
||
**תפקידי הליבה**:
|
||
- **תזמור** — CEO agent מקבל בקשות, מנתב לסוכן המתאים
|
||
- **ניהול משימות** — Kanban board עם issues, מעקב סטטוס
|
||
- **הפעלת סוכנים** — wakeup mechanism, heartbeat cycle
|
||
- **ממשק דיון** — comments על issues (משתמש ← agent ← agent)
|
||
|
||
---
|
||
|
||
### תהליכי גומלין — מי מדבר עם מי
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────────────────┐
|
||
│ תהליכי גומלין │
|
||
│ │
|
||
│ LEGAL-AI PAPERCLIP │
|
||
│ ════════ ═════════ │
|
||
│ │
|
||
│ ┌─────────┐ יצירת project+issue ┌─────────┐ │
|
||
│ │ Cases │ ─────── DB insert ──────→ │Projects │ │
|
||
│ │ │ ─────── DB insert ──────→ │ Issues │ │
|
||
│ └─────────┘ └─────────┘ │
|
||
│ │
|
||
│ ┌─────────┐ wakeup signal ┌─────────┐ │
|
||
│ │Workflow │ ─────── HTTP POST ───────→ │ CEO │ │
|
||
│ │ Start │ (issueId + mutation) │ Agent │ │
|
||
│ └─────────┘ └─────────┘ │
|
||
│ │
|
||
│ ┌─────────┐ קריאת case_number ┌─────────┐ │
|
||
│ │ Data │ ←──── plugin_state ────── │ Plugin │ │
|
||
│ │ (API) │ ←──── HTTP GET/POST ───── │legal-ai │ │
|
||
│ └─────────┘ (תקדימים, טענות, סגנון) └─────────┘ │
|
||
│ │
|
||
│ ┌─────────┐ skill sync ┌─────────┐ │
|
||
│ │ Skills │ ──── DB + filesystem ────→ │company_ │ │
|
||
│ │ (disk) │ │ skills │ │
|
||
│ └─────────┘ └─────────┘ │
|
||
│ │
|
||
│ ┌─────────┐ שאילתת חברות ┌─────────┐ │
|
||
│ │Settings │ ←──── DB query ────────── │companies│ │
|
||
│ │ UI │ │ table │ │
|
||
│ └─────────┘ └─────────┘ │
|
||
└──────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
#### כיוון 1: Legal-AI → Paperclip (יצירה ושליטה)
|
||
|
||
| פעולה | מנגנון | מתי |
|
||
|-------|--------|-----|
|
||
| יצירת Project | DB insert ישיר ב-Paperclip | יצירת תיק חדש |
|
||
| יצירת Issue | DB insert ישיר ב-Paperclip | יצירת תיק / התחלת workflow |
|
||
| קישור case ← issue | DB insert ב-`plugin_state` | יצירת project |
|
||
| הערת אימות | DB insert ב-`issue_comments` | אחרי יצירת project |
|
||
| הפעלת CEO | **HTTP POST** ל-`/api/agents/{id}/wakeup` | התחלת workflow |
|
||
| סנכרון skill | DB insert/update ב-`company_skills` | התקנת/עדכון skill |
|
||
|
||
#### כיוון 2: Paperclip → Legal-AI (שאילתות וקריאות חזרה)
|
||
|
||
| פעולה | מנגנון | מתי |
|
||
|-------|--------|-----|
|
||
| קריאת case_number | plugin קורא `plugin_state` | סוכן מקבל issue |
|
||
| שליפת מסמכים | HTTP GET/POST ל-API של legal-ai | סוכן עובד על תיק |
|
||
| חיפוש תקדימים | HTTP ל-`/api/precedents/search` | researcher מחפש |
|
||
| קריאת style guide | HTTP ל-MCP / API | writer כותב טיוטה |
|
||
| רשימת חברות | DB query ישיר מ-`companies` | UI הגדרות |
|
||
|
||
#### החוליה המקשרת: `plugin_state`
|
||
|
||
```
|
||
plugin_state:
|
||
plugin_id = "53461b5a..." (marcusgroup.legal-ai)
|
||
scope_kind = "issue"
|
||
scope_id = "{issue-uuid}"
|
||
state_key = "legal-case-number"
|
||
value_json = "\"1234\""
|
||
```
|
||
|
||
זו ה"כתובת" שמאפשרת לסוכן Paperclip לדעת איזה תיק ב-Legal-AI שייך ל-issue שהוא עובד עליו.
|
||
|
||
---
|
||
|
||
### מצב קיים לכל חברה
|
||
|
||
#### CMP — רישוי ובנייה (מוכן לעבודה)
|
||
|
||
**ב-Legal-AI**:
|
||
- 24 החלטות אימון בקורפוס
|
||
- ניתוח סגנון מלא (דפוסים, ביטויים, יחסי אורך)
|
||
- content checklists ל-3 סוגי משנה (substantive, threshold, property)
|
||
- RAG פעיל עם chunks + embeddings
|
||
|
||
**ב-Paperclip**:
|
||
- חברה CMP פעילה
|
||
- סוכנים מוגדרים ופעילים
|
||
- Plugin פעיל
|
||
- Skills מותקנים
|
||
|
||
#### CMPA — היטלי השבחה (דורש הקמה)
|
||
|
||
**ב-Legal-AI**:
|
||
- appeal_subtype `betterment_levy` מוגדר בקוד
|
||
- ניתוב אוטומטי (8xxx → CMPA) עובד
|
||
- **חסר**: 0 החלטות אימון, 0 style patterns, 0 chunks, אין content checklist
|
||
|
||
**ב-Paperclip**:
|
||
- חברה CMPA קיימת
|
||
- **לוודא**: סוכנים מקושרים, plugin פעיל, skills מותקנים
|
||
|
||
---
|
||
|
||
## התהליך המלא — צעד אחר צעד
|
||
|
||
### שלב 1: הכנת הקבצים
|
||
|
||
**מיקום**: הנח את כל קבצי ה-DOCX בתיקייה נגישה (למשל `~/Downloads/hitlei-hashbacha/`)
|
||
|
||
**בדיקות מקדימות**:
|
||
1. וודא שכל הקבצים בפורמט DOCX או PDF
|
||
2. וודא שהשמות כוללים מספר תיק (לצורך metadata)
|
||
3. ספור כמה החלטות יש — זה ישפיע על זמן העיבוד
|
||
|
||
**דגשים**:
|
||
- ההחלטות מגיעות מנבו — יש להן watermarks, headers, footnotes שצריך לנקות
|
||
- מערכת ה-proofreading שלנו מטפלת בזה אוטומטית
|
||
|
||
---
|
||
|
||
### שלב 2: העלאה — 3 נתיבים אפשריים
|
||
|
||
#### נתיב א: ממשק Web (מומלץ להעלאה המונית)
|
||
|
||
```
|
||
כתובת: https://legal-ai.nautilus.marcusgroup.org
|
||
נתיב: /api/training/upload
|
||
```
|
||
|
||
**מה קורה מאחורי הקלעים**:
|
||
1. הקובץ נשמר כ-temp file
|
||
2. **Proofreading** — ניקוי אוטומטי של תוספות נבו:
|
||
- הסרת watermarks ("ספרות:", "חקיקה שאוזכרה:")
|
||
- הסרת headers/footers של עמודים
|
||
- הסרת קודי נבו inline
|
||
- הסרת URLs וזכויות יוצרים
|
||
3. **שמירת גרסה מנוקה** → `data/training/proofread/{filename}.md`
|
||
4. **שמירת מקור** → `data/training/{filename}.docx`
|
||
5. **הוספה ל-DB** → טבלת `style_corpus` עם metadata
|
||
6. **חיתוך לחלקים** → chunks סמנטיים
|
||
7. **יצירת embeddings** → Voyage AI → וקטורים 1024 ממדים
|
||
8. **שמירה ב-RAG** → טבלת `document_chunks` (עם practice_area + appeal_subtype)
|
||
|
||
#### נתיב ב: MCP Tool (מ-Claude Code)
|
||
|
||
```
|
||
tool: document_upload_training
|
||
params:
|
||
file_path: "/path/to/file.docx"
|
||
decision_number: "ARAR-24-8001"
|
||
decision_date: "2024-06-15"
|
||
subject_categories: ["היטל השבחה"]
|
||
title: "שם ההחלטה"
|
||
practice_area: "appeals_committee"
|
||
appeal_subtype: "betterment_levy"
|
||
```
|
||
|
||
#### נתיב ג: Skill Command (אינטראקטיבי)
|
||
|
||
```
|
||
/upload-training
|
||
```
|
||
עונים על שאלות: נתיב קובץ, מספר החלטה, תאריך, קטגוריות.
|
||
|
||
---
|
||
|
||
### שלב 3: ביקורת (Proofreading QA)
|
||
|
||
**קריטי**: לפני שממשיכים לניתוח — **לבדוק כל החלטה שהועלתה**.
|
||
|
||
**מה לבדוק**:
|
||
- [ ] הטקסט המנוקה (`data/training/proofread/`) קריא ושלם
|
||
- [ ] לא נחתכו חלקים מהותיים
|
||
- [ ] ה-metadata נכון (מספר תיק, תאריך, קטגוריה)
|
||
- [ ] אין שאריות של artifacts מנבו
|
||
- [ ] appeal_subtype = `betterment_levy` (ולא `building_permit`)
|
||
|
||
**כלי בדיקה**:
|
||
```
|
||
GET /api/training/status — סטטוס העלאה ועיבוד
|
||
```
|
||
|
||
---
|
||
|
||
### שלב 4: ניתוח סגנון (Style Analysis)
|
||
|
||
אחרי שכל ההחלטות הועלו ונבדקו, מריצים ניתוח סגנון:
|
||
|
||
```
|
||
POST /api/training/analyze-style
|
||
```
|
||
|
||
**מה קורה**:
|
||
1. שליפת כל ההחלטות מ-`style_corpus` (לפי practice_area/subtype)
|
||
2. בדיקת תקציב tokens:
|
||
- עד 900K tokens → pass יחיד (הכל ל-Claude בבת אחת)
|
||
- מעל 900K → multi-pass (כל החלטה בנפרד + סינתזה)
|
||
3. **חילוץ דפוסים** באמצעות Claude:
|
||
- נוסחאות פתיחה
|
||
- ביטויי מעבר
|
||
- סגנון ציטוט פסיקה
|
||
- מבנה ניתוח
|
||
- נוסחאות סיום
|
||
- ביטויים אופייניים
|
||
- זרימת טיעון
|
||
- טיפול בראיות
|
||
4. שמירה בטבלת `style_patterns` עם תדירות, הקשר, ודוגמאות
|
||
|
||
**תוצר**: מדריך סגנון מבוסס-נתונים ספציפי להיטלי השבחה.
|
||
|
||
---
|
||
|
||
### שלב 5: ניתוח קורפוס (Corpus Analysis)
|
||
|
||
בדומה ל-`docs/corpus-analysis.md` שנבנה עבור רישוי ובנייה, צריך ליצור ניתוח מקביל:
|
||
|
||
**מה לנתח**:
|
||
- הרכב הקורפוס: כמה החלטות, תוצאות (קבלה/דחייה/חלקית)
|
||
- אורך פרק דיון טיפוסי
|
||
- נושאים ייחודיים להיטלי השבחה:
|
||
- שומות (שומה מוסכמת, שומה אחרת, שמאי מכריע)
|
||
- תכנית משביחה — זיהוי, פרשנות
|
||
- מועד השבחה / "מועד אישור התכנית"
|
||
- חישוב עליית ערך (לפני/אחרי)
|
||
- פטורים (ס' 19 לתוספת השלישית)
|
||
- שיעור היטל
|
||
- דיני ראיות שמאיים
|
||
- ביטויי מעבר ייחודיים
|
||
- סגנון דיון — "קר ומקצועי" (לפי CLAUDE.md)
|
||
- השוואה לרישוי ובנייה (מה שונה)
|
||
|
||
**תוצר**: מסמך `docs/corpus-analysis-betterment.md`
|
||
|
||
---
|
||
|
||
### שלב 6: עדכון Content Checklists
|
||
|
||
הקובץ `lessons.py` מכיל צ'קליסטים לבלוק י (דיון) לפי סוג ערר.
|
||
|
||
**מה צריך**:
|
||
- ליצור `CONTENT_CHECKLISTS["betterment_levy"]` עם נושאים ייחודיים
|
||
- נושאים צפויים: שומות, תכנית משביחה, מועד, חישוב, פטורים, ראיות שמאיות
|
||
- הצ'קליסט ייבנה מתוך ניתוח הקורפוס (שלב 5)
|
||
|
||
---
|
||
|
||
### שלב 7: אימות Paperclip
|
||
|
||
לוודא שחברת CMPA מוגדרת נכון:
|
||
|
||
**בדיקות**:
|
||
- [ ] חברה CMPA קיימת ופעילה ב-Paperclip DB
|
||
- [ ] Issue prefix = CMPA
|
||
- [ ] Plugin `legal-ai` פעיל בחברה
|
||
- [ ] סוכנים (CEO, researcher, writer) מוגדרים
|
||
- [ ] tag_company_mappings נכון ב-legal-ai DB:
|
||
- `betterment_levy` → `8639e837...`
|
||
- `compensation_197` → `8639e837...`
|
||
- [ ] יצירת תיק 8xxx מנותבת נכון
|
||
|
||
**כלי בדיקה**:
|
||
```
|
||
GET /api/settings/tag-mappings
|
||
GET /api/paperclip/companies
|
||
```
|
||
|
||
---
|
||
|
||
## סיכום — סדר פעולות
|
||
|
||
| # | שלב | מה | כלי | זמן משוער |
|
||
|---|------|----|------|-----------|
|
||
| 1 | הכנה | איסוף קבצי DOCX, בדיקת פורמט | ידני | — |
|
||
| 2 | העלאה | העלאת כל ההחלטות + proofreading אוטומטי | Web API / MCP | דקות לכל החלטה |
|
||
| 3 | ביקורת | בדיקת כל טקסט מנוקה + metadata | ידני / Claude | כמה שעות |
|
||
| 4 | ניתוח סגנון | חילוץ דפוסים מהקורפוס | API analyze-style | ~30 דק |
|
||
| 5 | ניתוח קורפוס | מפת תוכן + נושאים + השוואה | Claude + מסמך | כמה שעות |
|
||
| 6 | צ'קליסט | יצירת content checklist להיטלי השבחה | עדכון קוד | — |
|
||
| 7 | אימות Paperclip | בדיקת הגדרות חברה + ניתוב | API / DB | — |
|
||
|
||
---
|
||
|
||
## הערות חשובות
|
||
|
||
### ההבדל בין רישוי ובנייה להיטלי השבחה (מ-CLAUDE.md)
|
||
|
||
| מאפיין | רישוי ובנייה (1xxx) | היטלי השבחה (8xxx) |
|
||
|---------|---------------------|-------------------|
|
||
| טון | חם יחסית | קר ומקצועי |
|
||
| תוכן | הקשר תכנוני רחב, אלמנטים אנושיים | יבש, ללא רגשות |
|
||
| נושאי דיון | תכניות, חניה, קווי בניין, שכנים | שומות, חישובי השבחה, פטורים |
|
||
| פסיקה | ס' 152, הלכת שפר, דיני הקלה | ס' 196-198, תוספת שלישית, שמאי מכריע |
|
||
|
||
### סינון RAG לפי סוג
|
||
כל ה-chunks נשמרים עם `appeal_subtype`, כך שחיפוש סמנטי בתיק היטל השבחה ימצא רק תקדימים רלוונטיים מהתחום — לא יערבב עם רישוי ובנייה.
|
||
|
||
### ניתוח סגנון נפרד
|
||
ייתכן שנצטרך **מדריך סגנון נפרד** להיטלי השבחה, כי הטון שונה מהותית. הניתוח בשלב 4 יחשוף את ההבדלים.
|
||
|
||
---
|
||
|
||
## סוכנים — שיתוף בין החברות
|
||
|
||
### עיקרון: אותם סוכנים, הקשר שונה
|
||
|
||
**אין צורך בסוכנים נפרדים** לכל חברה. הסוכנים (CEO, researcher, writer) עובדים לפי **מתודולוגיה** — ארכיטקטורת 12 בלוקים, CREAC, מבחן השופט — שחלה על כל סוגי העררים.
|
||
|
||
**מה שמשתנה אוטומטית לפי `appeal_subtype`**:
|
||
|
||
| רכיב | מקור | מנגנון הפרדה |
|
||
|-------|------|--------------|
|
||
| Style patterns | טבלת `style_patterns` | ניתוח סגנון נפרד per-subtype |
|
||
| Content checklists | `lessons.py` | key שונה: `building_permit` vs `betterment_levy` |
|
||
| תקדימים (RAG) | טבלת `document_chunks` | סינון לפי `appeal_subtype` בחיפוש |
|
||
| טון | style guide + patterns | דפוסים שונים מהקורפוס |
|
||
|
||
**למה שיתוף סוכנים עדיף**:
|
||
1. שיפור במתודולוגיה חל אוטומטית על שני התחומים
|
||
2. אין כפילות בתחזוקת סוכנים
|
||
3. ההפרדה היא **ברמת הנתונים**, לא ברמת הלוגיקה
|
||
|
||
**מה כן צריך לוודא**:
|
||
- [ ] הסוכנים ב-Paperclip מקושרים לשתי החברות (CMP + CMPA)
|
||
- [ ] כש-issue נפתח ב-CMPA, הסוכנים מופעלים באותו אופן
|
||
- [ ] ה-context שהסוכן מקבל כולל את ה-`appeal_subtype` הנכון
|