legal-ai/docs/superpowers/plans/2026-05-30-system-spec-set.md

System Spec-Set (Sub-Project 1) Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Author the living system spec-set under docs/spec/ that canonically defines the עוזר משפטי system and its invariants ("what is correct"), each invariant backed by ≥3 authoritative sources.

Architecture: A 00-constitution.md keystone (mission, global invariants, engineering rules, invariant template, verification protocol, index) + lifecycle-organized domain files (01-ingest … 07-learning) + cross-cutting files (X1…X5). Existing docs are cited as verified sources, never duplicated. This is documentation, not code: the "test" is the verification gate — every invariant carries ≥3 verified sources or is marked ⚠ UNVERIFIED and escalated to the chair (never decided solo).

Tech Stack: Markdown. Sources verified via WebSearch/WebFetch + primary texts (Nevo for Israeli statutes). Design basis: docs/superpowers/specs/2026-05-30-system-spec-design.md.

Branch: system-spec (already created; design doc committed at a5b22da).

---

Conventions for every file (apply in each task)

• Invariant template (use verbatim structure):

  ### INV-<DOMAIN><n>: <short title>
  **כלל:** <one crisp normative statement — what MUST hold>
  **מקורות:** <≥3 authorities> | סטטוס: verified / ⚠ UNVERIFIED
  **אכיפה:** <where/how enforced — schema / write-validation / health-check / human gate>
  **הפרה ידועה:** <example from the system if any → links to audit; else "—">
  

• Language: Hebrew prose, English for technical terms and source names (matches project docs + RTL preference).
• Length target: ≤ ~500 lines/file. If exceeding, that domain needs splitting — note it, don't cram.
• Citing existing docs: reference (e.g., block-schema.md) as a source to verify; if it contradicts the ≥3 authorities, record a one-line audit-finding rather than silently trusting it.
• Cross-links: link sibling spec files by relative path; link global invariants as 00-constitution.md#inv-g<n>.

Per-file verification gate (the "test")

A file passes only when ALL hold (this checklist is a literal step in each task):

1. Every INV-* has either ≥3 named authoritative sources (verified) or is marked ⚠ UNVERIFIED with an escalation note.
2. No placeholder text (TBD/TODO/"להשלים").
3. All cross-links resolve to a real file/anchor.
4. Consistent with 00-constitution.md (no invariant contradicts a global invariant).
5. ≤ ~500 lines.

---

Phase 0 — Scaffold

Task 0: Create the spec directory

Files:

• Create: docs/spec/README.md

• Step 1: Create docs/spec/ with a short README

Write docs/spec/README.md:

# ספ המערכת — עוזר משפטי (Living System Spec)

זהו מקור-האמת הקנוני ל"מהו תקין" במערכת. שער-הכניסה: [00-constitution.md](00-constitution.md).
כל invariant מגובה ב-≥3 מקורות סמכותיים; פריט לא-מאומת מסומן ⚠ UNVERIFIED ומועלה ליו"ר.

מבנה: 00 חוקה · 01–07 מחזור-חיים · X1–X5 חוצי-שלבים. ראה אינדקס מלא בחוקה.
בסיס-עיצוב: docs/superpowers/specs/2026-05-30-system-spec-design.md

• Step 2: Commit

git add docs/spec/README.md
git commit -m "docs(spec): scaffold docs/spec/ living spec-set"

---

Phase 1 — Keystone (REVIEW CHECKPOINT after)

Task 1: 00-constitution.md — the keystone

Files:

• Create: docs/spec/00-constitution.md

• Step 1: Write the constitution with these sections (content is already determined by the approved design):

  1. ייעוד — paste the confirmed mission paragraph from the design doc §2.

  2. עקרונות-עבודה — the 4 work principles (design doc §3): don't assume existing is correct; 3-source protocol; research→draft; collaboration model.

  3. תבנית-invariant — the template from "Conventions" above.

  4. פרוטוקול-אימות — verified vs ⚠ UNVERIFIED; escalation to chair; never decide solo.

  5. Invariants גלובליים G1–G11 — each written with the full template. Content + sources from design doc §6 / §9:

     • INV-G1 מזהה קנוני מנורמל בכתיבה — SSOT/normalization · Codd 1NF (CACM 13(6), 1970) · Kleppmann DDIA. אכיפה: normalization-on-write in the ingest path + X1-identifiers.md. הפרה ידועה: tolerant _normalize_case_number on read only; 8126-25 vs 8126-03-25.
     • INV-G2 מקור-אמת יחיד, אין מסלולים מקבילים מתפצלים — Kleppmann (system of record) · Fowler (Canonical Data Model) · SSOT. אכיפה: one canonical ingest path; siblings share it. הפרה ידועה: ingest_precedent vs ingest_internal_decision asymmetry.
     • INV-G3 ingest אחיד ו-idempotent (upsert על מפתח דטרמיניסטי) — Kleppmann · Stripe/CDC idempotency · ISO 8000. אכיפה: 01-ingest.md unified path.
     • INV-G4 חוזה-שלמות לפני "שמיש/ניתן-לחיפוש" — ISO 8000 · DAMA-UK (completeness) · ISO 15489 (reliability). אכיפה: write-validation + health-check; 02-data-model.md. הפרה ידועה: ערן סופר 8046/24 indexed with empty headnote/summary/tags.
     • INV-G5 metadata מלא לכל פריט מואנדקס + הפרדת-קורפוס בכל query — Pinecone (multitenancy) · RAG attribution (Lewis et al.) · ISO 8000. אכיפה: 03-retrieval.md. הפרה ידועה: task #56 halacha_filters source_kind leak.
     • INV-G6 re-index בכל שינוי תוכן — Pinecone · Weaviate · RAG freshness. אכיפה: ingest/update path.
     • INV-G7 מיזוג RRF לא סכום-ציונים — Elastic (RRF) · Weaviate · OpenSearch/Azure (corrob.). אכיפה: retrieval fusion (already implemented — codified).
     • INV-G8 איכות-אחזור נמדדת (precision+recall) — Manning IR textbook · RAG eval literature · (Elastic eval guidance). אכיפה: eval harness in 03-retrieval.md.
     • INV-G9 עקיבוּת-מקור + audit-trail ל-AI — CEPEJ (user control) · NCSC · ISO 15489. אכיפה: X5-audit-provenance.md.
     • INV-G10 המערכת מסייעת; שערים אנושיים = invariant — NCSC ("never replace human judgment") · CEPEJ · FJC. אכיפה: 05-qa-review.md human gates.
     • INV-G11 תוכן החלטה מנומקת (רקע ניטרלי · ללא כפילות · מענה לטענות המפסיד · מבחן-השופט · טענות מקוריות) — FJC Writing Manual · South Bucks [2004] UKHL 33 · חוק לתיקון סדרי המינהל (החלטות והנמקות) תשי"ט-1958. אכיפה: 04-analysis-writing.md + 05-qa-review.md.

  6. כללי-הנדסה — סימטריה · נרמול-לא-תיקון-תסמין · quality-at-source (Fowler/Data-Mesh) · אין בליעה שקטה.

  7. אינדקס — table linking all spec files (00, 01–07, X1–X5) with one-line purpose each.

  8. נספח מקורות — paste the full source appendix from design doc §9.

• Step 2: Run the per-file verification gate (the 5-point checklist above). Fix inline.

• Step 3: Commit

git add docs/spec/00-constitution.md
git commit -m "docs(spec): 00-constitution — mission, 11 global invariants, engineering rules"

• Step 4: REVIEW CHECKPOINT — present 00-constitution.md to חיים. Do not start Phase 2 until approved. If the constitution's framing changes, the domain files adapt to it.

---

Phase 2 — Lifecycle domain files

Each task: (a) targeted research to verify domain-specific invariants to ≥3 sources (global invariants already verified — reuse their sources; only NEW domain claims need fresh sourcing); (b) draft the file; (c) run the verification gate; (d) commit. Group review checkpoint at end of Phase 2.

Task 2: 01-ingest.md — unified intake contract

Files: Create docs/spec/01-ingest.md

• Step 1: Document the target single ingest path for all three intake kinds (case documents / external precedent / internal-committee decisions). Describe the canonical pipeline: stage file → extract text → chunk → embed → store → queue metadata extraction → queue halacha extraction → set statuses. State which steps are uniform across all kinds (this is the fix for the asymmetry).
• Step 2: Define domain invariants applying INV-G2/G3/G4/G6 to ingest, e.g.:
  • INV-ING1: every intake kind flows through the same canonical ingest function; a new kind extends it via parameters, never a parallel function. (sources: INV-G2 set)
  • INV-ING2: ingest is idempotent on the canonical identifier (re-ingest = upsert, no duplicate row/chunks). (sources: INV-G3 set)
  • INV-ING3: metadata extraction is queued for every kind that has extractable metadata — not conditional per path. (sources: INV-G4 set; הפרה ידועה: internal path skipped request_metadata_extraction)
• Step 3: Cite current reality as audit-findings (the 8 documented asymmetries from the design research) — as הפרה ידועה lines, not as "correct."
• Step 4: Run verification gate. Step 5: Commit docs(spec): 01-ingest unified intake contract.

Task 3: 02-data-model.md — entities + completeness contract

Files: Create docs/spec/02-data-model.md

• Step 1: Enumerate the canonical entities (cases, case_law, documents, chunks, halachot, chair_feedback, …) — name, purpose, key fields. Mark this as the target model (verify field names against current schema during execution; divergences → audit-findings).
• Step 2: Define the completeness contract per entity — the mandatory-field set that makes a record "usable/searchable" (INV-G4). For case_law: e.g., canonical case_number, case_name, court, practice_area, source_kind, + (for searchable) ≥1 chunk and non-empty metadata. State explicitly that records failing the contract are flagged, not silently searchable.
  • INV-DM1: a case_law row is "searchable" only when its completeness contract is satisfied. (sources: ISO 8000 · DAMA-UK · ISO 15489)
  • INV-DM2: each entity has exactly one canonical identifier; no field stores a full citation as the identifier. (sources: INV-G1 set; הפרה ידועה: citation-as-case_number for סופר entries)
• Step 3: Run gate. Step 4: Commit docs(spec): 02-data-model entities + completeness contract.

Task 4: 03-retrieval.md — corpora + retrieval invariants

Files: Create docs/spec/03-retrieval.md

• Step 1: Document the 3 corpora + their search tools (source_kind mapping) and the hybrid/RRF design. (Reuse research from design §9 RAG sources — already verified.)
• Step 2: Define invariants (apply INV-G5/G6/G7/G8/G9):
  • INV-RET1: corpus separation enforced on 100% of query paths (chunks AND halachot filters). (Pinecone · ISO · RAG; הפרה ידועה: task #56)
  • INV-RET2: no item indexed without complete required metadata + resolvable source locator. (INV-G5 set)
  • INV-RET3: heterogeneous retrievers fused by RRF, never raw-score sum. (Elastic · Weaviate)
  • INV-RET4: retrieval quality measured by a standing precision+recall eval harness on a fixed labeled query set. (Manning · RAG eval)
  • INV-RET5: every returned span is attributable to its source. (CEPEJ · RAG)
• Step 3: Run gate. Step 4: Commit docs(spec): 03-retrieval corpora + retrieval invariants.

Task 5: 04-analysis-writing.md — claims, 12 blocks, Dafna style

Files: Create docs/spec/04-analysis-writing.md

• Step 1: Reference (cite, don't duplicate) block-schema.md, decision-methodology.md, skills/decision/SKILL.md as sources; summarize the 12-block model + claims extraction at spec altitude.
• Step 2: Verify the Israeli reasoned-decision sources (design doc §8 open items #1–#3): confirm exact section of חוק 1958 (תשכ"ט-1969 amendment) on Nevo; confirm/locate ברק-ארז citation; confirm בג"ץ 143/56 / עע"ם 2994/21. Mark each verified or ⚠ UNVERIFIED + escalate.
• Step 3: Define invariants from INV-G11:
  • INV-WR1: block ו (background) is neutral — no judgment words, no party quotes. (FJC · חובת הנמקה)
  • INV-WR2: no duplication — block י references prior blocks, does not restate facts. (FJC §non-duplication)
  • INV-WR3: every losing-side principal argument is addressed. (FJC · South Bucks adequacy)
  • INV-WR4: block ז = original claims only; supplements go to block ח. (project rule; cite corpus-analysis)
  • INV-WR5: judge-unfamiliar-with-case test — decision is self-contained and traceable. (FJC · South Bucks)
• Step 4: Run gate. Step 5: Commit docs(spec): 04-analysis-writing — 12 blocks + reasoned-decision invariants.

Task 6: 05-qa-review.md — QA gates + human gates

Files: Create docs/spec/05-qa-review.md

• Step 1: Document the existing automated QA gates (validate_decision: neutral_background, claims_coverage, weight_compliance, structural_integrity, no_duplication, sequential_numbering) — as the QA contract (verify against qa_validator.py at execution).
• Step 2: Define human-gate invariants (INV-G10):
  • INV-QA1: halacha approval is a manual chair decision; auto-extracted halachot are pending_review until the chair approves. (NCSC · CEPEJ · project rule)
  • INV-QA2: outcome selection and chair feedback are human gates, never automated. (NCSC · CEPEJ · FJC)
  • INV-QA3: a decision cannot be exported while critical QA gates fail. (FJC · validate_decision design)
• Step 3: Run gate. Step 4: Commit docs(spec): 05-qa-review — QA + human gates.

Task 7: 06-export.md — DOCX export contract

Files: Create docs/spec/06-export.md

• Step 1: Reference skills/dafna-decision-template/SKILL.md; document the export contract: line classification, dash policy, placeholder handling, template styles. Define:
  • INV-EX1: export is deterministic from the stored decision blocks (single source = DB blocks; the DOCX is derived). (INV-G2 derived-data set)
  • INV-EX2: export preserves source traceability where required. (INV-G9)
• Step 2: Run gate. Step 3: Commit docs(spec): 06-export DOCX contract.

Task 8: 07-learning.md — Hermes, lessons, feedback loop

Files: Create docs/spec/07-learning.md

• Step 1: Document the learning loop: Hermes curator (post-export analysis), docs/legal-decision-lessons.md, chair-feedback weekly analysis. Define:

  • INV-LRN1: curator proposes; changes to SKILL.md/lessons.md require manual chair approval. (INV-G10; project rule)
  • INV-LRN2: quality accountability sits at the source (ingest/authoring), not downstream. (Fowler/Data-Mesh)

• Step 2: Run gate. Step 3: Commit docs(spec): 07-learning loop.

• Phase 2 REVIEW CHECKPOINT — present 01–07 to חיים for review before Phase 3.

---

Phase 3 — Cross-cutting files (final REVIEW after)

Task 9: X1-identifiers.md — canonical identifier model

Files: Create docs/spec/X1-identifiers.md

• Step 1: Define the canonical case_number model: the normalized written form, the relationship cases.case_number vs case_law.case_number, and citation formats. Specify normalize-on-write (INV-G1), with tolerant-match-on-read as a secondary convenience, not the primary mechanism.
  • INV-ID1: case_number is normalized to canonical form at write time. (SSOT · Codd · Kleppmann)
  • INV-ID2: no entity uses a full citation string as its identifier. (INV-G1; הפרה ידועה: סופר entries)
• Step 2: Run gate. Step 3: Commit docs(spec): X1-identifiers canonical model.

Task 10: X2-multi-company.md

Files: Create docs/spec/X2-multi-company.md

• Step 1: Document CMP (1xxx) / CMPA (8xxx), 14 agents (7×2), and the sync rules (cite sync_agents_across_companies.py, HEARTBEAT.md). Define:
  • INV-MC1: any agent-config change in master must be synced to the mirror company via the API sync script. (project rule)
• Step 2: Run gate. Step 3: Commit docs(spec): X2-multi-company.

Task 11: X3-integration-deploy.md

Files: Create docs/spec/X3-integration-deploy.md

• Step 1: Document Paperclip integration (wakeup via API not DB; comment routing via CEO; outbound case-status webhook) and the deploy model (Coolify dockerimage for legal-ai; pm2 for paperclip/chat-service). Define:
  • INV-INT1: Paperclip wakeup goes through POST /api/agents/{id}/wakeup with payload.issueId, never a direct DB insert. (project rule; cite memory reference)
  • INV-INT2: legal-ai code changes require commit→push→Coolify deploy; no local uvicorn. (project rule)
• Step 2: Run gate. Step 3: Commit docs(spec): X3-integration-deploy.

Task 12: X4-agents.md

Files: Create docs/spec/X4-agents.md

• Step 1: Map the domain agents (ceo, researcher, analyst, writer, qa, proofreader, exporter, hermes) — role + which spec files each must read. Reserve a section for the process agents (sub-project 5: add-feature / fix-feature / spec-guardian) to be defined later. Define:
  • INV-AG1: every agent reads 00-constitution.md first and the relevant domain spec before acting. (governance rule)
• Step 2: Run gate. Step 3: Commit docs(spec): X4-agents map.

Task 13: X5-audit-provenance.md

Files: Create docs/spec/X5-audit-provenance.md

• Step 1: Define the audit-trail + provenance requirements (INV-G9): logging of AI-assisted generation, traceability of every cited authority/source in a decision back to the corpus, record integrity over time.

  • INV-AUD1: every AI-assisted artifact records what sources/data produced it. (CEPEJ user-control · NCSC · ISO 15489)
  • INV-AUD2: record integrity — a stored decision/record is complete and unaltered except via tracked, attributed changes. (ISO 15489 §5.2.2.3)

• Step 2: Run gate. Step 3: Commit docs(spec): X5-audit-provenance.

• FINAL REVIEW — present the complete spec-set to חיים. On approval, sub-project 1 is done; proceed to sub-project 2 (Audit) in its own spec→plan cycle.

---

Self-Review (run after writing this plan)

• Spec coverage: every design-doc section maps to a task — mission/principles → Task 1; G1–G11 → Task 1 + applied in 2–13; spec-set structure → Tasks 0–13; verification protocol → conventions + gate; open legal items → Task 5 Step 2. ✓
• Placeholder scan: domain-file invariants are enumerated with IDs + sources, not "define later"; the only deferred content is the process-agents section (Task 12) which is explicitly sub-project 5, and the legal ⚠ UNVERIFIED items (Task 5) which are an intentional escalation, not a placeholder. ✓
• Type/name consistency: invariant IDs are unique (G1–G11, ING1–3, DM1–2, RET1–5, WR1–5, QA1–3, EX1–2, LRN1–2, ID1–2, MC1, INT1–2, AG1, AUD1–2); file names consistent with design doc §5. ✓