[2026-05-15] vault restructure: personal-os plans → personal/projects/personal-os, briefs → work/briefs

2026-05-15 14:17:41 +06:00
parent 00f89f49d0
commit 4f4358d76b
72 changed files with 5797 additions and 0 deletions
@@ -0,0 +1,115 @@
+# Plan: Executor as Spawned Worker — Orchestrator Pattern
+
+**Date**: 2026-05-14
+**Status**: Planning
+**Parent**: [[executor-v2-redesign]]
+
+## Problem
+
+Currently Eagle (орёл) handles executor tasks inline in the conversation:
+- Takes on the task directly in the discussion thread
+- Asks Alex for permissions mid-task, blocking the flow
+- Creates tight coupling between conversational layer and execution layer
+
+## Desired Architecture
+
+```
+Alex  →  Eagle (orchestrator, in Zulip topic)
+               ↓  spawn
+          Executor (worker process, separate Hermes session)
+               ↓  writes to Zulip #executor topic
+          Eagle monitors #executor
+               ↓  reads recent output (not full thread)
+               ↓  auto-approve obvious decisions
+               ↓  escalate ambiguous → @mention Alex
+```
+
+## Roles
+
+### Eagle (Orchestrator)
+- Receives task request in any Zulip topic
+- Queues task to `executor_queue` DB table
+- Spawns Executor worker via `hermes cron run` or similar
+- Monitors `#executor` topic for Executor messages
+- Reads only recent N messages (sliding window, not full thread)
+- Auto-approval logic:
+  - "create worktree" → approve
+  - "run tests" → approve
+  - "open draft PR" → approve
+  - "push to branch" → approve
+  - "modify unrelated file" → DENY + escalate
+  - "post Asana comment" → escalate to Alex
+  - Any scope expansion → escalate to Alex
+- @mention Alex only when ambiguous or high-risk
+
+### Executor (Worker)
+- Separate Hermes session/process
+- Bot identity: "Executor" or "Исполнитель" (not Eagle)
+- Communicates via `#executor` Zulip topic
+- Posts structured messages: `[REQUEST: <action>]`, `[STATUS: <phase>]`, `[DONE: <result>]`
+- Does NOT ask Alex directly — all escalations go to Eagle
+- On permission denied → explain why, ask what to do differently
+
+## Message Protocol (Executor → Eagle)
+
+```
+[STATUS: investigation] Analysing bug GID 123456...
+[REQUEST: create_worktree] Branch: fix/tab-preview-stuck
+[REQUEST: run_tests] Scheme: macOS UI Tests CI
+[STATUS: pr_open] Draft PR: https://github.com/...
+[DONE: pr_ready] PR #1234 opened, CI green, ready for review
+[ESCALATE: scope_expansion] Found unrelated issue in TabBar.swift — should I fix it?
+```
+
+## Auto-approval Rules (Eagle)
+
+| Message type | Auto action |
+|---|---|
+| `[REQUEST: create_worktree]` | ✅ approve silently |
+| `[REQUEST: run_build]` | ✅ approve silently |
+| `[REQUEST: run_tests]` | ✅ approve silently |
+| `[REQUEST: open_draft_pr]` | ✅ approve silently |
+| `[REQUEST: push_branch]` | ✅ approve silently |
+| `[REQUEST: post_asana_comment]` | ⚠️ show Alex, wait |
+| `[REQUEST: merge_pr]` | ❌ always escalate |
+| `[ESCALATE: *]` | ⚠️ always escalate |
+| `[ESCALATE: scope_expansion]` | ❌ deny by default + notify Alex |
+
+## Eagle Monitoring Loop
+
+Eagle does NOT run a continuous monitoring process. Instead:
+- Option A: Hermes cron (every 2 min) → check `#executor` for unprocessed `[REQUEST]` or `[ESCALATE]` messages → process them
+- Option B: Webhook trigger on Zulip `#executor` stream → Eagle session wakes up
+
+**Recommendation: Option A** (simpler, uses existing cron infra)
+
+## Context Window Management
+
+Eagle reads Executor's thread with sliding window:
+- Last 20 messages from `#executor` for the current `executor_run_id`
+- Filter by `run_id` tag in messages to handle concurrent runs
+- Structured messages allow O(1) parsing without LLM
+
+## Relation to Executor v2
+
+This is a UI/coordination layer ON TOP of executor-v2 bash daemons:
+- executor-runner.sh still does the heavy lifting
+- Eagle becomes the gatekeeper/orchestrator that monitors and approves
+- Executor worker sends structured messages via Zulip API (or hermes platform API)
+
+## Implementation Steps
+
+1. Define message protocol (structured tags)
+2. Add Zulip message sender to executor worker prompts
+3. Create Eagle monitoring cron (2 min interval, `#executor` stream)
+4. Implement auto-approval logic in Eagle monitoring prompt
+5. Add escalation → `@mention Alex` in monitoring prompt
+6. Test with a real executor run in dry-run mode
+
+## Open Questions
+
+- How does Executor "spawn" as a separate bot persona? 
+  - Option A: Same Hermes instance, different SOUL/persona config
+  - Option B: Separate Hermes gateway with "Executor" identity
+  - Option C: `hermes run -p executor-worker.md` as subprocess (non-interactive)
+- Concurrent runs: Eagle needs to track run_id per conversation thread