diff --git a/history/260730-ExecutorRepos-ArchitectureFindings.md b/history/260730-ExecutorRepos-ArchitectureFindings.md new file mode 100644 index 0000000..6aa92cc --- /dev/null +++ b/history/260730-ExecutorRepos-ArchitectureFindings.md @@ -0,0 +1,172 @@ +# executor-sandbox / executor-worker — Architecture Findings + +**Document status:** Dated investigation record, non-normative, append-only. +Triggered by the org-wide TRSL rollout follow-up (`history/260730-TRSL-OrgWideLicenseRollout.md`): +the maintainer asked what `executor-sandbox` and `executor-worker` actually +are, how they relate to `sand-boxer`, `glas-harness`, `rein-aharness`, +`kaizen-agentic`, `agentic-resources`, `phase-memory`, and `llm-connect`, +and to establish/update their `INTENT.md`/`SCOPE.md` from real repo content. + +--- + +## 1. `executor-sandbox` — reconciled + +**Finding:** the local `~/executor-sandbox` directory on this workstation +is a **stale, disconnected local clone** — its git history (`init sandbox`, +`executor smoke: add NOTES.md`) is completely unrelated to the real +Forgejo `coulomb/executor-sandbox` repository's history (`init: sandbox +for harness smoke`, then timestamped `harness smoke: ` commits +from 2026-07-18 and 2026-07-26). The local directory had no `origin` +remote configured at all — it was never actually wired to the real repo. + +**The real Forgejo repo** is a disposable smoke-test target for +`rein-aharness` (see §3): its `SMOKE.md` literally reads "rein-aharness +smoke," and its commit history is a stream of automated smoke-run +timestamps, not human feature work. + +**Action taken:** worked directly against a fresh clone of the real +Forgejo repo (not the stale local directory). Established `INTENT.md` and +`SCOPE.md` there from its actual observed purpose (disposable smoke +target, no independent product scope), and applied TRSL V1C1. Committed +and pushed to `coulomb/executor-sandbox.git` directly. + +**Left as-is, flagged:** the stale local `~/executor-sandbox` directory on +this workstation still contains its old, disconnected history and our +earlier (now superseded) license commit on top of it. It was never the +real repo, so nothing of value was lost by leaving it alone, but it may +be worth deleting/re-cloning that local directory so it doesn't confuse +a future session into thinking it's a working copy of the real repo. + +## 2. `executor-worker` — retired prototype, no Forgejo repo exists + +**Finding:** `executor-worker`'s own `README.md` already says it plainly: + +> "executor-worker (retired prototype) — Adopted into the shared runtime +> repo `agent-harness` on 2026-07-17 (DEC-2026-002 / agent-harness +> ADR-001). Package renamed to `agent_harness`; all further work happens +> there (HARNESS-WP-0001). This directory is kept only for the prototype +> git history." + +Confirmed via `git ls-remote`: **no `coulomb/executor-worker` repo exists +on Forgejo**, and no `coulomb/agent-harness` repo exists either — because +`agent-harness` was itself later renamed again, to **`rein-aharness`** +(`glas-harness` ADR-001, 2026-07-26), which **does** exist and is live. + +**The maintainer's own founder note** (`binky-control`'s +`integrations/llm-connect-executor-assessment.md`, 2026-07-16) is the +origin of this whole lineage: *"llm-connect should enable real automated +work based on activity-core independently from this workstation... This +will hopefully connect well with kaizen-agentic, too."* That assessment's +"Ownership decision (2026-07-17, BINKY-WP-0004-T01)" recorded **DEC-2026-002**: +the executor worker lives in a new small repo, not inside `activity-core` +or `kaizen-agentic`. That new small repo was `executor-worker`, prototyped +to completion (`64681e7` MVP, `31a8566` mail-scan mode), then formally +adopted/renamed to `agent-harness`, then renamed again to `rein-aharness`. + +**executor-worker's function is not missing — it already has a live, +production successor.** No new Forgejo repo is needed to "complete" this +lineage; `rein-aharness` already is that repo, already has its own +`INTENT.md`-equivalent scope, and is deployed live on Railiance for +tenant `binky-control`. + +**Open question for the maintainer, not resolved here:** should a +`coulomb/executor-worker` Forgejo repo still be created purely to hold +this retired prototype's git history for the record, or is that history +adequately preserved by staying local-only (as it is today) / +folded into `rein-aharness`'s own history if it isn't already? Creating a +new remote repo is a real, if small, infrastructure action — this +document deliberately stops short of doing that without asking, since the +investigation itself changed the premise of the original request (the +maintainer's message assumed executor-worker might need "establishing"; +it turns out its function is already fully established elsewhere, under +a different, twice-renamed name). + +## 3. Full architecture map (verified against each repo's own SCOPE/README/ADRs) + +```text +activity-core (Temporal schedules, Railiance) + └─ definition fires → rule emits task → issue-core (REST task sink) + └─ glas-harness (meta-framework/router, ADR-001, 2026-07-26) + owns the harness CONTRACT (session lifecycle, tool dispatch, + actor attribution, sandbox consumption) — routes to + pluggable concrete backends called "reins": + │ + ├─ rein-aharness (formerly agent-harness, formerly the + │ executor-worker prototype) — Claude-Code-CLI-driven, + │ deployed live on Railiance for tenant binky-control + │ + └─ rein-openweights — drives current open-weight models via + OpenRouter; the gap ADR-001 explicitly named ("no + harness today runs an open-weight model") and filled + + glas-harness consumes sand-boxer for OS-level isolation (the reins + themselves, per ADR-001's own Context section, historically had *no* + real sandbox — sand-boxer is what fixes that gap for both reins + uniformly, rather than each rein reinventing its own isolation). + + Both reins use llm-connect as their LLM adapter "engine block" (a + provider-neutral client library, explicitly not an agent framework + itself per its own SCOPE) — ClaudeCodeAdapter for rein-aharness, + OpenRouter-backed adapters for rein-openweights. + + kaizen-agentic supplies agent personas + project memory + coordination + (get_kaizen_agent) — its own WP-0006/ADR-005 ("scheduled agent + execution via activity-core") is the exact convergence point the + founder's 2026-07-16 note hoped for. Kaizen's own verb is "prepare," + not "execute" — runtime execution is the reins' job, not kaizen's. + + executor-sandbox is rein-aharness's disposable smoke-test scratch + target (§1) — infrastructure supporting the harness, not a product. +``` + +**`phase-memory`**: "the profile-driven memory operating layer for +agentic systems... interprets Markitect memory profiles as runtime plans, +models memory phases, and produces deterministic dry-run actions for +retention." Not directly named in any of the ADRs/assessments read for +this investigation — its relationship to `kaizen-agentic`'s own +"persistent project-scoped memory" is plausible (both are agent-memory +concerns) but **not confirmed cross-referenced in either repo's own +docs during this pass** — flagged as needing a closer look if the +maintainer wants that relationship pinned down precisely, rather than +asserted here without verification. + +**`agentic-resources`**: still carries an auto-generated, unrefined +`statehub register` placeholder SCOPE ("Iterating towards optimal +agentic performance" — a one-liner with no elaborated Core Idea beyond +restating INTENT.md exists). Its `session_memory/` directory contains +stored session blobs from multiple agent CLIs (Grok, Claude), suggesting +it may be functioning as a de facto session-memory scratch store — +possibly overlapping with `phase-memory`'s stated purpose, but this +repo's own scope is genuinely too thin to confirm that relationship +confidently. **This repo's SCOPE.md itself is a candidate for the same +"outdated/unrefined, should be updated from actual content" treatment +the maintainer asked for on executor-sandbox/executor-worker** — flagged, +not fixed in this pass (out of the scope the maintainer actually asked +about). + +## 4. Utilization signal (what's actually active vs. dormant) + +Based on commit recency and `status: finished`/`status: active` workplan +markers found during this pass: + +- **Actively developed / live:** `rein-aharness` (live on Railiance), + `glas-harness` (ADR-001 dated 2026-07-26, recent), `rein-openweights` + (exists specifically to fill ADR-001's named gap), `sand-boxer` + (consumed by glas-harness). +- **Stable, supporting role:** `llm-connect` (pre-release 0.1.0 per the + 2026-07-16 assessment, adapter library, not itself under heavy churn), + `kaizen-agentic` (mature, v1.1.0, 18-agent library, active WP-0006 for + the scheduling convergence). +- **Retired:** `executor-worker` (explicit, by its own README). +- **Throwaway/infrastructure, not a product:** `executor-sandbox`. +- **Unclear/thin:** `agentic-resources` (§3) — not confidently placed in + this architecture map without further investigation. + +## 5. Non-goals of this document + +- Creating a `coulomb/executor-worker` Forgejo repo — explicitly left as + an open question for the maintainer (§2), not decided here. +- Refining `agentic-resources`' own SCOPE.md — flagged, not fixed. +- Confirming the `phase-memory` ↔ `kaizen-agentic`/`agentic-resources` + relationship with certainty — flagged as unconfirmed, not asserted as + fact.