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>
Two latent issues surfaced today while watching the case 8174-24
end-to-end run, both worth documenting and engineering around because
they will recur on every future case.
Bug 1 — issue.released flips done→todo
After an agent successfully PATCHes its issue to "done", Paperclip's
internal issue.released action reverts the status to "todo" within
~30 seconds. This triggers a fresh wakeup of the same agent on a
task that is already complete.
Reproduced on CMPA-18 (30/04/26):
18:14:57 agent PATCH → status: done
18:15:35 Paperclip → issue.released → status: todo
18:15:54 new researcher run started
The fix at the right altitude (Paperclip itself) is outside our repo.
Mitigation in HEARTBEAT.md §3 — when an agent boots and finds the
issue in `todo` while expected outputs (file, DB rows) already exist,
it must short-circuit: post a "no change" comment, PATCH back to done,
and exit. Costs ~$0.20 per false wakeup but breaks the loop.
Bug 2 — Bash backtick trap on long comment bodies
Researcher agent built a curl pipeline like:
curl ... -d "$(python3 -c "body = '''...
📁 קובץ מחקר: `/path/to/file.md`
'''")"
The backticks around the file path (markdown convention) get
evaluated by the OUTER bash $(...) as command substitution. Bash
then tries to exec /path/to/file.md, which is not executable, and
prints "Permission denied" — a misleading error since the actual
file ownership is fine. The curl itself succeeded; only the bash
prelude noised up the log.
Fix in HEARTBEAT.md §4א: long bodies must go via Write→tempfile
then `curl -d @file`. Avoids every shell quoting edge case.
Files:
• docs/paperclip-quirks.md — new. Full writeup of both bugs plus
two prior known-quirks (CEO auto-block in_progress, INSERT vs
API for wakeups). Each section: what happens, empirical evidence
from logs, impact, workaround, status.
• .claude/agents/HEARTBEAT.md — added the self-recovery section to
§3 and the temp-file pattern to §4א. The temp-file pattern is the
canonical answer for any agent posting markdown comments —
applies to all 7 agents in this skill set.
• CLAUDE.md — referenced the new doc from the docs index.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Agent JWT cannot wake other agents directly (returns "Agent can only
invoke itself"). The correct pattern: create an issue + assign to the
target agent → Paperclip triggers wakeup automatically.
Also documented all correct API routes in HEARTBEAT.md:
- POST /api/issues/{id}/comments (not /issues/)
- POST /api/companies/{company-id}/issues (not /api/issues)
- PATCH /api/issues/{id}
- POST /api/agents/{id}/wakeup (self only, with payload.issueId)
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>
When a user comments on a Paperclip issue, the built-in automation wakes
the assigned agent directly, bypassing the CEO. This meant user instructions
(like "read the uploaded draft and route to the right agent") were ignored.
Changes:
- Plugin: add issue.comment.created event handler that wakes the CEO agent
with the comment context (plugin-legal-ai, separate repo)
- HEARTBEAT: add steps 2b (read recent user comments) and 2c (check
attachments) before agents start working
- CEO agent: add comment-routing section — read, check attachments, route
- Writer agent: add step 0 — check for uploaded DOCX drafts before writing
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Install git in Docker image and wrap all subprocess git calls in
try/except so a missing or failing git binary never kills an upload
that already succeeded.
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 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>
New: scripts/notify.py — sends via SMTP (notify@marcus-law.co.il → paperclip+chaim@marcus-law.co.il)
Updated: HEARTBEAT.md — agents must send email when waiting for human decision
Triggers: outcome choice, direction approval, QA failures, review ready.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
All agent output — comments, status, errors, summaries, thinking — must be in Hebrew.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Symlinked to Paperclip instructions directory for each agent.
Single source of truth: .claude/agents/ files → symlinked to Paperclip.
Cleaned duplicate soul_md from DB metadata.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
