legal-ai/docs/spec/X17-information-architecture.md

X17 — ארכיטקטורת-המידע ומשטח-ההפעלה (Information Architecture)

מה זה. ספ-היעד לאיך משטח-ההפעלה (דפים/טאבים/תורים/ניווט/cache) צריך להיות מאורגן — שכבה מעל X6 (חוזה UI↔API). X6 קובע שטיפוס נכון (OpenAPI=SSoT, provenance); X17 קובע שמשטח נכון (מקור-אמת יחיד לכל datum, שער אחד לכל החלטה, ניווט מבוסס-משימה).

למה. חיים (2026-06-11): "המערכת מסובכת מדי לתפעול." האבחון (../ia-audit-redesign.md, #127) אימת 37 ממצאים שכולם ביטוי-UI של G2 מופר שלא הורחב לשכבת-ה-UI. X17 מרים את G2 (מקור-אמת יחיד) ו-G10 (שערים-אנושיים) לשכבת-המשטח, ומקודד את feedback_operational_simplicity (שער/מקום/ערוץ אחד) כ-invariants אכיפים.

גבול קשיח (G10): X17 מסיר משטחים/ערוצים כפולים, לעולם לא שער. כל שער-אנושי (אישור-הלכה, פתרון-הערה, אישור-לקח, בחירת-תוצאה) נשאר חובה ומפורש. "שער אחד" = מקום-אחד-להחליט, לא אפס-החלטה.

---

INV-IA1 — בעלים-משטח-יחיד לכל datum/מונה (G2 בשכבת-UI)

ל-aggregate/מונה נגזר-שרת יש משטח-בעלים יחיד שמריץ את השאילתה; משטחים אחרים מצביעים אליו (deep-link/pointer), ולעולם לא מריצים מונה-מתחרה client-side. (אכיפה: מונה-הגייטים חי רק ב-/approvals+['chair','pending']; /operations מצביע. תופס APR-2/3, ADM-2/3.)

• Maintain Consistency and Adhere to Standards (Heuristic #4) — Nielsen Norman Group — https://www.nngroup.com/articles/consistency-and-standards/
• 3 Common IA Mistakes (Low Information Scent) — Nielsen Norman Group — https://www.nngroup.com/articles/3-ia-mistakes/
• Information Architecture: For the Web and Beyond, 4th ed. (Organization & Labeling Systems) — Rosenfeld, Morville & Arango (O'Reilly) — https://www.oreilly.com/library/view/information-architecture-4th/9781491913529/

INV-IA2 — mutation מבטל כל קורא (no stale cross-surface state)

כל mutation שמשנה ערך הנקרא במשטח אחר חייב לבטל כל queryKey שקורא אותו — כולל aggregators חוצי-namespace. אסור שמשטח יציג ערך תקוע אחרי שינוי במשטח אחר. (תופס את 16 פערי-הסנכרון: CAS-1/2, APR-1/4/5/6, LRN-6/8/10, MET-1/8, ADM-2/3/5.)

• Query Invalidation — TanStack Query (official docs) — https://tanstack.com/query/latest/docs/framework/react/guides/query-invalidation
• Deriving Client State from Server State — TkDodo (Dominik Dorfmeister, TanStack maintainer) — https://tkdodo.eu/blog/deriving-client-state-from-server-state
• Visibility of System Status (Heuristic #1) — Nielsen Norman Group — https://www.nngroup.com/articles/visibility-system-status/

INV-IA3 — שער-אחד / ערוץ-אחד לכל החלטה (G10/INV-LRN1 נשמרים)

לכל החלטה-אנושית משטח-יחיד ומסלול-כתיבה-יחיד. אסור משטח-אישור שני או כותב-מקביל לאותה שורה. הלמידה מנותבת דרך העורך הקנוני, לא כותבת-במקביל. (תופס LRN-1/2/3, MET-2/3 — "שני השערים" של חיים, ומירוץ ה-lost-update.)

• Preventing User Errors / Error Prevention (Heuristic #5) — Nielsen Norman Group — https://www.nngroup.com/articles/slips/
• Do the hard work to make it simple (Government Design Principles) — GOV.UK / GDS — https://www.gov.uk/guidance/government-design-principles
• Don't Make Me Think, Ch.5 — Omit Needless Words/Controls — Steve Krug (O'Reilly) — https://www.oreilly.com/library/view/dont-make-me/0321344758/ch05.html

INV-IA4 — ניווט מבוסס-משימה, לא מבוסס-פורמט

משטחים מאורגנים לפי מה המשתמש עושה (לאשר / לנטר / להגדיר / לחבר), לא לפי מקור-הנתונים הטכני (pm2 מול DB מול תורים). דלת-כניסה אחת לכל משימה. (אכיפה: /operations⊇/diagnostics — אותו intent-ניטור; הורדת /feedback מהראשי. תופס D5, ADM.)

• Avoid Format-Based Primary Navigation — Nielsen Norman Group — https://www.nngroup.com/articles/format-based-navigation/
• Intranet IA Methods (task-based endures over structure-based) — Nielsen Norman Group — https://www.nngroup.com/articles/intranet-ia-methods/
• Task list pattern (one list of outstanding tasks per service) — GOV.UK Design System — https://design-system.service.gov.uk/components/task-list/

INV-IA5 — סטטוס-אמיתי מגובה-צרכן

כל מספר מוצג ממופה לצרכן אמיתי ומקור שלם. אסור KPI שסופר דגל-ללא-צרכן; אסור aggregate מדויק כש-partial-failure השמיט תורם (להציג חלקיות); שדה ב-response — לרנדר או להסיר. (תופס LRN-1/4/5, ADM-1/6, APR-3.)

• Visibility of System Status (Heuristic #1) — Nielsen Norman Group — https://www.nngroup.com/articles/visibility-system-status/
• Design with data (Government Design Principles) — GOV.UK / GDS — https://www.gov.uk/guidance/government-design-principles
• Minimize Cognitive Load to Maximize Usability — Nielsen Norman Group — https://www.nngroup.com/articles/minimize-cognitive-load/

INV-IA6 — שפת-מפעיל מובנת-מאליה (no jargon; precedence in-context)

קופי פונה-למפעיל מתאר את האפקט המשמעותי, לא מזהי-משימות פנימיים (T7/T15). התנהגות-תחולה/קדימות (universal מוקדם; checklist→appeal_type) מוצגת בהקשר דרך progressive disclosure, לא במסמך נפרד. (תופס MET-4/5/6/7.)

• Don't Make Me Think — Krug's First Law (self-evident) — Steve Krug — https://www.oreilly.com/library/view/dont-make-me/0789723107/ch02.html
• Plain language / write for users (Design principles) — U.S. Web Design System (USWDS) — https://designsystem.digital.gov/design-principles/
• Progressive Disclosure — Nielsen Norman Group — https://www.nngroup.com/articles/progressive-disclosure/

---

משטח-היעד (Target IA)

שלושה משטחי-intent ברמת-העל

משטח	intent	בעלים	כלל
/approvals	לאשר (החלטה-אנושית)	תיבת-הגייטים הקנונית	המקום היחיד שפועלים על שער. כרטיס לכל סוג (הלכות/פסיקה-חסרה/הערות/QA) עם מונה+קישור.
/operations	לנטר (קריאה-בלבד)	משטח-המכונה	בולע את /diagnostics. שירותים+תורים+סוכנים+בריאות+halacha_backlog. אפס שער נפעל כאן; מצביע ל-/approvals.
/settings	להגדיר	משטח-התצורה	Paperclip/סוכנים/env/כלים/בלוקים. עריכת-env משלימה-את-עצמה (staleness+redeploy באותה שורה).

משטחי-תחום (בעלים-יחיד לכל ישות)

תחום	יעד
תיק	workspace-החלטה אחד — block-editing + DOCX-פעיל, מחוון-מקור-אמת אחד בבעלות-המערכת, cache-slice משותף. אזור "השלמה והעברה" אחד לשערי-הסיום.
למידה	תיבת-אישור אחת (לפי זוג draft↔final) · ערוץ-כותב אחד + סטטוס "זורם-לכותב" אחד (review_status='approved') · applied_to_skill מוסר · כל artifact תלוי-בזוג (progressive disclosure).
מתודולוגיה	/methodology = העורך הקנוני היחיד (PUT אחד; תג-מקור "ידני/מאומץ-מלמידה"); הלמידה מנותבת-דרכו ומבטלת שני-caches; explainer-תחולה inline.
פסיקה	3 קורפוסים נפרדים (גבול אמיתי, G2/INV-DIG1) אך מתפעלים אחיד — שם-חיפוש עקבי, תבנית-"ממתין" אחת, authority בכל-מקום.

---

דלתות-ספ (deltas — ✅ קודדו בגל-2 #131)

כל שינוי-ספ דורש ≥3 מקורות (לעיל) + אישור-יו"ר. אושר ע"י חיים (2026-06-11, /goal "בצע את כל הגלים").

1. X6: ✅ נוספו INV-UI7 (aggregate-נגזר=SSoT; mutation מבטל queryKey; אין מונה-מתחרה — מקדד INV-IA1/IA2) · INV-UI8 (שדה-response מרונדר-או-מוסר; חלקיות מוצגת — INV-IA5).
2. 07-learning §0.4: ✅ שער-אישור אחד (review_status='approved'), טרנזקציית-כותב אחת (FOR UPDATE), applied_to_skill הוסר (מקדד INV-IA3; מיישב את "שני-השערים" של feedback_operational_simplicity).
3. 00-constitution §G2 "הפרות ידועות": ✅ נוסף תאום-המתודולוגיה (discussion_rules['universal'] נכתב ע"י PUT וגם promote — MET-2/3) + המיתון (append אטומי FOR UPDATE + invalidation).

הפניות-אחיות

• ../ia-audit-redesign.md — מצב-קיים: 34 משטחים, 37 ממצאים (file:line), כיוון-יעד פר-אשכול.
• X6-ui-api-contract.md (UI1–UI6 — X17 מעליו) · ui-audit.md (ממצאי-קוד פר-רכיב — שכבה מתחת).
• 00-constitution.md — G2 (מקור-אמת יחיד) · G10 (שערים-אנושיים) — X17 מרים אותם לשכבת-המשטח.