openclaw-to-caret-migration/DEPENDENCIES.md

# Openclaw dependency matrix

Every openclaw-provided capability that the current gitea-webhooks pipeline uses, and what Caret's replacement does with it. Source citations: R01 = RESEARCH-01, R02 = RESEARCH-02, R03 = RESEARCH-03, PLAN = PLAN.md.

Categories:
- **REMOVE** — Caret's replacement doesn't need this at all
- **REPLACE** — Caret builds a standalone equivalent
- **KEEP** — Caret continues depending on openclaw for this (and why that's safe)
- **BLOCKING** — Caret cannot move forward without resolving this first (Rooh action required)

## By capability

### 1. HTTP webhook ingress (port 18789, `/hooks/agent`)
**Category:** REPLACE
**What Caret does:** Stand up a bun HTTP listener at a Caret-owned port (e.g. 18790 or unix socket), with its own path. Mirrors openclaw's `/hooks/agent` shape so existing scripts can be reused. [R01 §Ingress path, R02 §HTTP endpoints]
**Risk if kept:** Hard-couples Caret's lifecycle to the openclaw gateway container. Defeats the entire migration.
**Effort:** 1 day. Stateless request/response, well-understood. [R02 difficulty matrix: Easy]

### 2. HMAC verification (currently NOT done by openclaw)
**Category:** REPLACE (net-new — openclaw never had it)
**What Caret does:** Real HMAC-SHA256 of the raw body using `X-Gitea-Signature` header, timing-safe compare, raw body preserved before JSON parse. [R01 §HMAC recipe, R03 confirms all 4 known webhooks have `Secret: NOT SET`]
**Risk if kept:** No HMAC at all today; protection is bearer + nginx ACL only. Caret should do better.
**Effort:** 0.5 day. ~30 lines.
**Depends on BLOCKING #1 (webhook secret provisioning).**

### 3. Bearer token authentication (`OPENCLAW_HOOKS_TOKEN`)
**Category:** REPLACE
**What Caret does:** Own bearer token (`CARET_HOOKS_TOKEN`) stored in Caret's credentials dir, validated on each request as a second factor alongside HMAC. [R01 §Ingress path layer 3]
**Risk if kept:** Sharing the openclaw token cross-couples secret rotation.
**Effort:** Trivial.

### 4. nginx TLS termination and path rewriting
**Category:** KEEP (with new location block)
**What Caret does:** Adds a new nginx `location /hooks/caret` block that proxies to the Caret listener, same TLS cert. Reuses existing Let's Encrypt setup. [R01 §Ingress path]
**Risk if kept:** None — nginx is host-level infra, not openclaw-specific.
**Effort:** 1 hour, but requires host root access.
**See BLOCKING #2.**

### 5. Event dedup cache (`X-Gitea-Delivery` 24h)
**Category:** REPLACE
**What Caret does:** Own JSON-on-disk dedup cache at `/host/root/.caret/state/dedup-cache.json`, identical 24h TTL semantics. [R01 §Ingress path layer 4, R01 gotcha 4]
**Risk if kept:** Sharing openclaw's cache file is fragile and couples crash recovery.
**Effort:** 0.5 day.

### 6. Rate limiting (5 concurrent per agent)
**Category:** REPLACE
**What Caret does:** Per-route concurrency limiter in the listener. Caret's routing is simpler (one "agent") so this is mostly a global semaphore. [R01 gotcha 7]
**Risk if kept:** N/A.
**Effort:** Trivial.

### 7. Session lock manager (`hooks/locks/`)
**Category:** REPLACE
**What Caret does:** Own lock dir at `/host/root/.caret/state/locks/`, same 2h TTL, same file naming `{owner}-{repo}-{issue}`, same IS_DONE 5min grace. [R01 §Session lock]
**Risk if kept:** Two writers to one lock dir = race.
**Effort:** 0.5 day.

### 8. Queue daemon (`queue-inbox/` + `queue-daemon.js`)
**Category:** REPLACE
**What Caret does:** In-process queue inside the listener (or a sidecar bun script reading from `/host/root/.caret/state/queue/`). Re-verifies spawn signatures off the hot path. [R01 gotcha 12, R03 §queue-daemon.js]
**Risk if kept:** Couples Caret's spawn pipeline to openclaw container restart.
**Effort:** 1 day.

### 9. `sessions_spawn` agent orchestration primitive
**Category:** REPLACE (with Claude Code Channels plugin)
**What Caret does:** Build a Channels plugin at `/host/root/.caret/channels/gitea-judgment/` that receives an HTTP POST and starts a Claude Code session with the payload as initial prompt. [R02 §Caret's conclusion, PLAN §Phase 3 J3.1]
**Risk if kept:** Openclaw's `sessions_spawn` is the deepest coupling — see R02 difficulty matrix "Hard" rating. Keeping it means Caret can never fully cut over.
**Effort:** 2-3 days for the minimum viable plugin. Full parity (wakeMode, thinking, model selection) is more like 1 week.

### 10. Tool allowlist enforcement per agent
**Category:** KEEP (judgment path runs inside Claude Code, which has its own tool config)
**What Caret does:** Caret's deterministic path runs scripts directly with no tools concept. The judgment path is a Claude Code session whose tool allowlist is configured in Claude Code's settings.json (not openclaw's). [R02 §Tool policy resolution]
**Risk if kept:** None — Caret never touches openclaw's tool policy resolver.
**Effort:** 0 (already separated).

### 11. Plugin SDK (`src/plugin-sdk/`)
**Category:** REMOVE
**What Caret does:** Doesn't load openclaw plugins. Caret's listener is a plain bun script with no plugin loader. Channels plugin uses Claude Code's plugin mechanism, not openclaw's. [R02 §Don't reinvent #2]
**Risk if kept:** N/A.
**Effort:** 0.

### 12. Delivery system (Telegram, Mattermost, Discord)
**Category:** REPLACE (use tg-stream + Mattermost direct calls)
**What Caret does:** Calls tg-stream HTTP API for Telegram alerts and Mattermost webhook URL directly for incident posts. No multi-channel abstraction layer. [R02 §Don't reinvent #4 warns it's tightly coupled — we don't replicate, we use simpler primitives]
**Risk if kept:** Hard coupling to openclaw outbound system.
**Effort:** 0.5 day (just curl calls).

### 13. Session storage (JSONL transcripts at `~/.openclaw/sessions/`)
**Category:** KEEP (judgment path only — Claude Code's own session store)
**What Caret does:** Deterministic path has no sessions. Judgment path uses Claude Code's native session JSONL under Claude Code's config dir, NOT openclaw's. [R02 §Don't reinvent #1]
**Risk if kept:** None — Caret never reads/writes openclaw's session files.
**Effort:** 0.

### 14. Heartbeat scheduler (`heartbeat-runner.ts`)
**Category:** REPLACE (use Claude Code `schedule` skill / cron)
**What Caret does:** Use systemd timer in the Caret container OR Claude Code's schedule mechanism for the 6h policy sweep and 15min webhook audit. No 28-item checklist — Caret's heartbeat is much smaller. [R02 §Heartbeat loop, R03 §Heartbeat checklists]
**Risk if kept:** Couples to openclaw gateway uptime, which R03 shows is currently degraded.
**Effort:** 0.5 day for the timer setup.

### 15. Cron service (`CronService` in gateway)
**Category:** REPLACE (same as #14 — single mechanism)
**What Caret does:** Same as heartbeat — systemd timers or Claude Code schedule. [R02 §Cron service, R03 §Active cron jobs shows 8 of 12 currently failing]
**Risk if kept:** R03 shows openclaw cron is currently degraded; depending on it inherits the breakage.
**Effort:** Combined with #14.

### 16. Gitea API integration (token + curl wrappers)
**Category:** KEEP
**What Caret does:** Continue using the same `GITEA_TOKEN` and stateless curl calls. Wrapper scripts ported into `/host/root/.caret/tools/`. [R01 §Tools fan-out, PLAN B2.3]
**Risk if kept:** None — Gitea API is a third-party service, openclaw is not in the path.
**Effort:** Path-strip and copy, 1 hour.
**Depends on BLOCKING #3 (admin scope).**

### 17. Workspace directory (`/root/.openclaw/workspace/`)
**Category:** KEEP (155 projects stay owned by openclaw/Xen)
**What Caret does:** Caret's migration scope is the Gitea-facing slice ONLY. The 155-project workspace, the PROJ-XXX-* hierarchy, and Xen's project ownership stay as-is. Caret has its own `/host/root/.caret/workspace/` for migration artifacts only. [R03 §What the migration actually has to replace, PLAN §Goal]
**Risk if kept:** None for the in-scope migration.
**Effort:** 0.

### 18. Project registry (`projects/registry.json`)
**Category:** KEEP
**What Caret does:** Read-only access if needed (e.g., to look up which manager owns a project for a given issue). No writes. [R03 §Shared state]
**Risk if kept:** Stale reads possible but acceptable.
**Effort:** 0.

### 19. Memory system (`memory/`)
**Category:** REMOVE (from migration scope)
**What Caret does:** Caret's own memory is in `/root/.claude/projects/-app/memory/`. Doesn't touch openclaw's memory dir. [R03 §Shared state]
**Risk if kept:** N/A.
**Effort:** 0.

### 20. Credentials store (`credentials/`)
**Category:** KEEP (read-only for shared tokens like GITEA_TOKEN)
**What Caret does:** Read GITEA_TOKEN from openclaw credentials OR copy to Caret credentials store. Caret-owned secrets (HMAC webhook secret, CARET_HOOKS_TOKEN) live in `/host/root/.caret/credentials/`. [R03 §Shared state credentials]
**Risk if kept:** Cross-coupling on token rotation. Acceptable short-term.
**Effort:** Trivial.
**See BLOCKING #4 (secret rotation story).**

### 21. `post-repo-audit.sh`
**Category:** REPLACE (port the script verbatim)
**What Caret does:** Copy to `/host/root/.caret/tools/post-repo-audit.sh`, strip openclaw path prefixes, ship as-is. Pure script, zero tokens. [R01 §Tools fan-out, PLAN B2.3]
**Risk if kept:** Couples to openclaw tools dir lifecycle.
**Effort:** 1 hour.

### 22. `audit-repo-policies.sh`
**Category:** REPLACE (port verbatim)
**What Caret does:** Copy to Caret tools dir, point at sol/repo-policies template repo, run with `--fix` from Caret's heartbeat. [R01 §Tools fan-out]
**Risk if kept:** Same as #21.
**Effort:** 1 hour.

### 23. `spawn-manager.sh`
**Category:** REPLACE (port verbatim, but only after #9 is solved)
**What Caret does:** Copy script. Generates Manager spawn JSON from issue body, creates project workspace. Caret's listener calls it via execSync with same 30s timeout pattern. [R01 §Tools fan-out, R01 gotcha 9]
**Risk if kept:** Tightly coupled to openclaw workspace path conventions — depends on whether Caret keeps openclaw's PROJ-XXX scheme (R01 advises yes).
**Effort:** 0.5 day.

### 24. `create-implement-issue.sh`
**Category:** REPLACE (port verbatim)
**What Caret does:** Copy script. Creates signed `[IMPLEMENT]` issue with HMAC spawn signature using `/host/root/.caret/credentials/spawn-secret`. [R01 §Tools fan-out]
**Risk if kept:** Spawn secret coupling.
**Effort:** 1 hour.
**Depends on BLOCKING #5 (spawn secret ownership).**

### 25. `secret-scan.sh`
**Category:** REPLACE (port verbatim)
**What Caret does:** Copy script, used by both CI (`make check`) inside repos and Caret's push handler. [R01 §Tools fan-out]
**Risk if kept:** N/A.
**Effort:** 1 hour.

### 26. `check-implement-orphans.sh`
**Category:** REPLACE (port verbatim)
**What Caret does:** Copy script, run from Caret's 15min heartbeat to detect stale pending spawns and orphaned managers. [R01 §Tools fan-out]
**Risk if kept:** N/A.
**Effort:** 1 hour.

### 27. `auditLog → logs/audit.jsonl`
**Category:** REPLACE
**What Caret does:** Caret's listener writes to `/host/root/.caret/log/audit.jsonl`, same JSONL line schema. Rotation by line count. [R01 §Logging, PLAN B2.5]
**Risk if kept:** Two writers to one file = corruption.
**Effort:** 0.5 day.

### 28. Incident flagging (`logs/incidents.jsonl`)
**Category:** REPLACE
**What Caret does:** Caret writes to `/host/root/.caret/log/incidents.jsonl`. Critical incidents also fan out to Telegram via tg-stream. [R01 §Logging, T2.23]
**Risk if kept:** Same as #27.
**Effort:** 0.5 day (combined with #27).

## Summary by category

| Category | Count |
|---|---|
| REMOVE   | 2  (#11, #19) |
| REPLACE  | 19 (#1, #2, #3, #5, #6, #7, #8, #9, #12, #14, #15, #21, #22, #23, #24, #25, #26, #27, #28) |
| KEEP     | 6  (#4, #10, #13, #16, #17, #18, #20) — note #20 partially |
| BLOCKING | 5  (see below) |

## BLOCKING items — Rooh action required

These five items must be resolved by Rooh before Caret can write the production code. They are not engineering decisions; they are policy / access decisions only Rooh can make.

### BLOCKING #1 — Webhook secret provisioning and storage location
**Question:** Where is the new HMAC webhook secret stored? `/host/root/.caret/credentials/webhook-secret`? A vault entry? Reused from an existing openclaw secret?
**Why it blocks:** Cannot ship HMAC verification (T1.06–T1.11) without the secret being authoritative somewhere. Cannot register webhooks on sol/* repos without knowing what secret to set on the Gitea side.
**Reference:** R01 §HMAC recipe, R03 confirms all current webhooks have `Secret: NOT SET`.

### BLOCKING #2 — nginx config write access for `/hooks/caret` location
**Question:** Does Caret have permission to edit `/host/etc/nginx/...` and reload nginx, or does Rooh do that one-time setup?
**Why it blocks:** Without an nginx route, Gitea cannot reach the Caret listener via HTTPS. Direct port exposure is the only alternative and that needs firewall changes.
**Reference:** R01 §Ingress path nginx termination, dependency #4.

### BLOCKING #3 — Gitea token admin scope OR manual system-webhook registration
**Question:** Will Rooh elevate the sol token to include `read:admin` + `write:admin`, or will Rooh manually register the system-level webhook one time?
**Why it blocks:** Without admin scope Caret cannot list system-level webhooks (R03 confirmed) and cannot create them. The sol/* per-repo webhooks can be registered with the existing token, but for new repo bootstrap to register Caret's webhook automatically (T1.02), the admin scope or manual setup is required.
**Reference:** R03 §Registered Gitea webhooks, PLAN §Dependencies token scope.

### BLOCKING #4 — Secret rotation story across openclaw + Caret
**Question:** When `GITEA_TOKEN` or the webhook secret rotates, what's the rollout? Does Caret read from openclaw's credentials dir live, or get its own copy that needs separate rotation? Who is responsible for rotation drills?
**Why it blocks:** PLAN §Risks #1 explicitly calls this out as a first-class deliverable. Without a documented rotation procedure, T3.13 cannot pass and the migration leaves a security debt.
**Reference:** PLAN §Risks #1, dependency #20.

### BLOCKING #5 — Spawn signature secret ownership (`/root/.openclaw/hooks/spawn-secret`)
**Question:** Does Caret get its own spawn secret (and `create-implement-issue.sh` is updated to use it), or does Caret read openclaw's existing secret? If the latter, what happens when openclaw rotates it?
**Why it blocks:** T1.15–T1.17 (spawn signature verification) require Caret and `create-implement-issue.sh` to share a secret. Cross-system sharing is the cleaner short-term answer but locks Caret to openclaw's lifecycle until cut-over completes.
**Reference:** R01 §Ingress path "spawn signatures", dependency #24.