# מדריך הקמת חברה חדשה — היטלי השבחה (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` הנכון