Brings the legal-ai ↔ Paperclip integration in line with the official
Paperclip skill. Net effect: HEARTBEAT.md -47% (370→195 lines), all 14
agents on uniform runtime_config + budget + instructionsBundleMode, and
two cross-company helpers replacing manual SQL.
Highlights:
- HEARTBEAT.md refactor: project-specific only, delegates to the official
paperclipai/paperclip skill (loaded per agent). Adds heartbeat-context
fast-path (§1.7) and PAPERCLIP_WAKE_PAYLOAD_JSON shortcut (§1.5).
- Issue Thread Interactions API: legal-ceo.md now uses
ask_user_questions / request_confirmation / suggest_tasks instead of
free-text comments — gives chair structured UI with idempotency keys.
- pc.sh + paperclip_api.pc_request: every API call goes through helpers
that inject Authorization + X-Paperclip-Run-Id (audit trail).
- sync_agents_across_companies.py: master(CMP)→mirror(CMPA) sync via
Paperclip API, idempotent, with --verify and --apply modes.
- skills/new-company-setup: 11-step blueprint distilling all 11 gaps
into a single onboarding runbook for the next company.
- .taskmaster: 12 tasks covering each gap (one already closed: #29).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
When Paperclip wakes the CEO and the model issues an mcp__legal-ai__*
call within ~10s of session init, Claude Code sometimes returns
"No such tool available" because the legal-ai MCP server hasn't
finished bringing up its tool catalog yet. Observed twice today on
CMPA precedent-extraction wakeups (sessions 9989fbaf and a9c61801);
the agent fell back to bash + .venv/bin/python and finished the work,
but the race needed fixing on the server side.
Three changes that close the window:
1. Lazy schema init (services/db.py + server.py)
`init_schema()` was awaited inside the FastMCP lifespan, blocking
the `initialize`/`tools/list` handshake until ~10 CREATE TABLE IF
NOT EXISTS statements ran. Under contention (two CEOs waking at
once for different companies) this stretched. Now the lifespan
returns immediately and `get_pool()` runs the schema migrations
exactly once on first DB access, guarded by an asyncio.Lock.
tools/list is answered in milliseconds regardless of DB state.
2. Lazy heavy imports
- services/embeddings.py: voyageai (~450ms) loaded only inside
_get_client()
- services/extractor.py: google.cloud.vision (~550ms) loaded only
inside _get_vision_client() and _ocr_with_google_vision()
These two were being imported at module top from
legal_mcp.tools.documents -> services.processor -> services.{
extractor,embeddings}, so the FastMCP server couldn't even start
responding until both finished. Cold start dropped from 2.7s to
1.17s end-to-end (init + tools/list response).
3. Agent-side warmup + retry guidance (.claude/agents/legal-ceo.md)
Even with a fast server, the model can still race on the very
first call. The precedent-extraction section now tells the CEO
to call workflow_status as a warmup probe and to retry after a
short sleep if it sees "No such tool available", before falling
back to the python bypass.
Also expanded the precedent-tool whitelists on the sub-agents that
delegate halacha/library work (commits 4a9a6b7 + 7ee90dc added the
tools to the MCP server but only the CEO got them in its allowed
list). Added to: legal-researcher (full extraction set), legal-analyst
(library_get/list + halacha review), legal-writer (library lookups +
halacha_review), legal-qa (library_get + halacha_review), and the two
that the CEO was already missing (halacha_review, halachot_pending).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds a third corpus of legal authority distinct from style_corpus
(Daphna's prior decisions for voice) and case_precedents (chair-attached
quotes per case). The new corpus holds chair-uploaded court rulings and
other appeals committee decisions, with binding rules (הלכות) extracted
automatically and queued for chair approval.
Pipeline (web/app.py + services/precedent_library.py):
file → extract → chunk → Voyage embed → halacha_extractor → store +
publish progress over the existing Redis SSE channel.
Schema V7 (services/db.py): extends case_law with source_kind +
extraction status fields under a CHECK constraint pinning practice_area
to the three appeals committee domains (rishuy_uvniya, betterment_levy,
compensation_197). New precedent_chunks (vector(1024)) and halachot
tables (vector(1024) over rule_statement, IVFFlat indexes, gin on
practice_areas/subject_tags). Halachot start as pending_review; only
approved/published rows are visible to search_precedent_library.
Agents: legal-writer, legal-researcher, legal-analyst, legal-ceo,
legal-qa get search_precedent_library. legal-writer prompt explains
the three-corpus distinction and CREAC use; legal-qa now verifies that
every cited halacha resolves to an approved row in the corpus.
UI: /precedents page with four tabs — library / semantic search /
pending review (J/K nav, A/R/E shortcuts, badge count) / stats.
Reuses the existing upload-sheet progress + SSE pattern.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The retry loop bug we fixed in legal-analyst yesterday existed in every
single sub-agent skill. They all post a comment + wake the CEO + exit,
leaving their own issue in `in_progress`. Paperclip's "in_progress with
no live execution" watchdog then re-wakes them, repeating until something
external transitions the issue. Watched it happen on CMPA-17 (researcher)
today — 4 iterations + manual SIGTERM + manual PATCH.
Same fix applied to all 5 remaining agents:
• legal-researcher.md
• legal-writer.md
• legal-qa.md
• legal-exporter.md
• legal-proofreader.md (file was incomplete — also added the missing
שלב 5: דיווח and wake-CEO sections to bring it to parity with the
other agents)
Each gets a "סגור את ה-issue של עצמך — חובה!" section with two PATCH
templates: one for `done` after a successful run, one for `blocked` if
checks fail or output is incomplete. The section sits before the
wake-CEO block, with an explicit reference to the CMPA-17 incident so
the rule has a concrete anchor.
Result: every agent now has the same close-issue contract. No more
zombie in_progress issues, no more 4× wakeup loops.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two structural bugs surfaced while monitoring the fresh end-to-end
run on case 8174-24:
1. **No appraiser_facts extraction.** legal-analyst.md's "what to
extract" table didn't mention doc_type='appraisal' at all, and
`extract_appraiser_facts` wasn't in its tools frontmatter. The
CEO compounded this by writing in CMPA-16's body that all 3
appraisals were "reference materials, do not extract" — which
is correct for `extract_claims` but wrong for the appraisal-
specific extractor. Result: 0 appraiser_facts in DB after a
full run, even though the user had carefully tagged each
appraisal's `appraiser_side` (committee/appellant) precisely
so detect_conflicts could compare them.
2. **Issue stays in_progress, Paperclip retries forever.** Step 7
("שמירה ודיווח") instructed the analyst to update the *case*
status, post a comment, send email, and wake the CEO — but
never to PATCH the issue itself to `done`. Paperclip's
"in_progress with no live execution" watchdog then re-woke the
analyst, which posted "I'm done" again, which re-triggered
another wakeup. We saw three iterations on CMPA-16 before the
issue finally transitioned. The PATCH pattern was already
documented in HEARTBEAT.md §4ב — the analyst skill just never
referenced it.
Changes:
• legal-analyst.md
- Added mcp__legal-ai__extract_appraiser_facts to tools list.
- Rewrote the "what to extract" table to use doc_type as the
key column and added an `appraisal` row + a callout explaining
why it goes through a different extractor.
- Added explicit step 5 "חלץ עובדות שמאי" with the call.
- Step 7 now PATCHes the issue to `done` (or `blocked` on
failure) before waking the CEO. Refers to the actual incident
so the rule has a concrete anchor.
- Cleaned up the chunking guidance — phase 1 of claude_session
already handles big docs automatically; no need to manually
split.
• legal-ceo.md (analyst issue template section)
- Replaced the generic "list of docs not to extract from" with a
per-doc_type action table that explicitly says
`appraisal → extract_appraiser_facts (NOT extract_claims)`.
- Added an explicit guard: "for every appraisal in the case,
verify the issue body says to run extract_appraiser_facts —
otherwise the writer gets a numbers-free block ז".
- Added the close-the-issue-with-PATCH instruction so the CEO
knows to write that into every analyst issue.
These edits don't affect the run currently in flight (the CEO's
prompt was already cached and the analyst already ran). They take
effect on the next analyst invocation.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Until now only legal-writer referenced the voice corpus. Without these
references the qa agent can't validate writer output, the researcher
chooses precedents outside Daphna's canon, and the analyst's claims
classification doesn't match block-zayin rules.
- legal-qa: adds 8th check "voice_compliance" — block ז structure,
block י voice (אכן/אולם, "אנחנו" verbs, no numbered lists), correct
precedent from canon, acceptance template match.
- legal-researcher: must check daphna-precedent-network.md before
proposing any precedent; cross-reference with Daphna's own past
decisions via search_decisions.
- legal-analyst: reads block-zayin-claims.md — its output is the
writer's input for block ז.
- legal-ceo: lists all 6 voice docs and which agent reads each.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- legal-analyst: opus 4.6 → opus 4.7
- legal-proofreader: opus 4.6 → opus 4.7
- legal-writer: sonnet 4.6 → opus 4.7 (complex block writing benefits from stronger model)
- block_writer MODEL_MAP: updated opus ID to 4.7
Opus 4.7 brings: high-res images (2576px), better file-based memory,
improved DOCX generation, and task budgets for agentic loops.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The agents used /api/agents/{id}/wake (404) with a fallback of INSERT
INTO agent_wakeup_requests. The DB insert creates only the wakeup
record without a heartbeat_run, so the Paperclip dispatcher never
processes it — agents get stuck in queued forever.
Fix:
- All agents: /wake → /wakeup (correct Paperclip API endpoint)
- Remove all DB INSERT fallbacks, replace with warning
- Document the rule in CLAUDE.md: always API, never DB insert
- Save to memory for future conversations
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
After Dafna fills her positions in the analysis document, the analyst
now runs a second pass to: verify cited case law against corpus and
case documents, deepen factual findings based on the chosen direction,
close open questions, and strengthen CREAC preparation.
Pipeline flow updated: direction_approved → analyst pass 2 →
analysis_enriched → CEO creates writer issue → ready_for_writing.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Every agent now has explicit instructions in its own definition file,
not just in HEARTBEAT.md. An agent following only its own step-by-step
instructions will do the right thing on any new case.
All 6 non-CEO agents: explicit wakeup CEO block in completion step
(curl API + psql fallback, with agent name customized)
legal-ceo.md: issue template for analyst with 5 mandatory items
(document mapping table, no-extract list, split large docs,
wakeup CEO, blocked if failed)
legal-writer.md: explicit Read of decision-methodology.md as step 1
(before case_get, not just "read before starting")
legal-qa.md: methodology_compliance severity → critical
(was warning — decisions without syllogisms/steel-man now blocked)
legal-proofreader.md: added case_update tool + status='proofread'
(was missing entirely — CEO couldn't know proofreading was done)
legal-researcher.md: added case_update + mail notification
(was missing — CEO couldn't know research was done)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Documents >15K chars must be split by chapter/section and extracted
in parts. If extract_claims times out, retry with chunks or extract
manually. This prevents the Matmon document issue (108K chars, 4x timeout).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Test run on case 1130-25 revealed critical gaps. This commit fixes:
HEARTBEAT.md (#1, #11):
- Agents MUST wake CEO after completing any task (wakeup request)
- New "blocked" status option — agents cannot mark "done" if something failed
- Fallback: direct DB insert if API wake doesn't work
legal-analyst.md (#2):
- New step 6: completeness checks BEFORE finishing
- Verify all appeal/response documents extracted successfully
- Verify all extracted documents produced claims
- Verify classification is correct (no claims from committee)
- If any check fails → status = "blocked", not "done"
legal-ceo.md (#3, #6, #7, #12, #13, #14, #15):
- Step A rewritten with 3 sub-checks:
A1: extraction completeness (no missing documents)
A2: negative checks (wrong classification, abnormal counts, missing parties)
A3: methodology compliance (syllogisms, CREAC prep, steel-man, etc.)
- Any failure blocks progress to step B
legal-qa.md (#6 reinforcement):
- New step 2b: negative checks on the written decision
- Missing issues, bare quotes, empty formulas, mixed findings/conclusions
Also:
- Synced all agent files to /home/chaim/legal-ai/ (Paperclip reads from there)
- Synced methodology + lessons + corpus docs
- Fixed claim classification in DB: 20 committee/applicant claims → response (#5)
Remaining gaps (3):
- #4: Paperclip cache may need restart to pick up new definitions
- #7: Matmon document retry (25K words, 0 claims extracted)
- #9: 53 appellant claims may need synthesis (high but not blocking)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add "עמדת ועדת הערר" placeholder to legal-analyst agent template
for each legal issue, to be filled by the chair as guidance for the
writing agent
- Fix green checkmark not showing for proofread documents (treat
'proofread' status same as 'completed')
- Show time alongside date in local files listing
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add delete_document_chunks for reprocessing, save extracted text to disk
- Expand case directory structure (original/extracted/proofread/backup)
- Update classifier patterns (תגובה, הודעת עמדה)
- Fix proofreader agent paths for new directory layout
- Update HEARTBEAT to notify on every task completion
- Improve bidi_table with LRE/PDF directional embedding
- Add Paperclip project verification and auto-close setup issue
- Add auto-sync-cases.sh for Gitea synchronization
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Remove cases/new|in-progress|completed subdivision (status managed in DB)
- Rename documents/original → documents/originals (consistent plural)
- Move exports from global data/exports/ into cases/{num}/exports/
- Add documents/research/ for case law and analysis files
- Update all agents, scripts, config, web API endpoints, and DB paths
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Defines the agent's role, tools, document type rules, and workflow.
Linked to Paperclip agent via --agent legal-analyst extraArg.
Key rules:
- Claims only from appeal docs, responses from response docs, replies from supplementary
- Never extract from precedents, plans, or protocols
- Must report results to Paperclip before finishing
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
