feat(atom): recursive agent atom keystone + deep-clean + docs consolidation

[drewstone]

Draft — the chore/atom-deep-clean work line (28 commits). Tracks the recursive-agent-atom keystone, the deep-clean, and the docs consolidation. ⚠️ Needs a rebase/conflict-resolve vs main before it's mergeable (~13 conflict points — main moved while this branch carried large deletions); resolving that is its own reviewed step.

What's in here

The recursive agent atom — agents driving agents, live (the keystone)

• c053e37 — coordination MCP over a live Scope: the real keystone for in-box driving.
• 2f7212d — proof a coding harness drives the Scope via the coordination MCP (live).
• 972707f — whole real e2e: an opencode supervisor drives opencode workers via the coordination MCP, with the real test suite gating delivery (no mock).
• 8ed2982 — the supervisor authors worker profiles from a skill (the intelligence is the authoring, not the plumbing).
• 525dc5a — animated visual replay of a recursive agent run (topology).

Atom deep-clean

• Dead-code + orphan removal across passes, each gates-verified; tracked precisely in docs/research/deletion-ledger.md.

Docs (this session)

• 9853f6a — the AgentProfile law (docs/canonical-api.md §1.5 + decision rows + CLAUDE.md §0): an agent IS its full profile (prompt+skills+tools/mcp+subagents+hooks); change behavior by authoring the profile and letting the sandbox substrate materialize it — never write a verify-loop or harness-specific config. The thing we kept forgetting, now in the first-read doc.
• daff034 — research-dir consolidation 28→14: retired design docs that shipped/were subsumed (evidence now in .evolve/current.json); refreshed the index, recorded rationale in the deletion ledger (Pass 2), fixed every inbound link. docs/ 51 → 37.

State / how to land

• Draft until the rebase vs main is resolved (and the unrelated in-flight bridge experiment on the branch is either committed or dropped).
• Substrate-layering and no-broken-links verified for the docs portion; the keystone commits carry their own live-e2e proofs.

[tangletools]

✅ Auto-approved PR — a6eab4ec

Blanket team auto-approval is enabled for this reviewer service.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: blanket_auto_approve · 2026-06-16T07:51:41Z}

[tangletools]

🟡 Value Audit — sound-with-nits

Verdict	sound-with-nits
Concerns	5 (2 low, 3 weak-concern)
Heuristic	0.2s
Duplication	0.0s
Interrogation	825.4s (2 bridge agents)
Total	825.6s

💰 Value — sound-with-nits

Adds the missing recursive-driver execution layer to the existing Scope/Supervisor substrate, plus an LLM-driven coordination driver, an HTTP MCP server, a deliverable gate, and authoring helpers; it is coherent and fills a real gap, though the authoring helper is thinner than the docs' full-profile

• What it does: The change turns the existing Scope/Supervisor atom into a genuinely recursive one: a spawned child can itself be a driver that mounts a nested Scope and spawns more children, all sharing one conserved budget pool, journal, and blob store. Concretely it adds: (1) driver-executor.ts (driverChild, withDriverExecutor, driverExecutorFactory) which runs a driver child inside a nested Scope one
• Goals it achieves: The change achieves three goals evident from the code: (1) make agents-driving-agents real — the recursive driver-executor closes the gap between the project's 'recursive atom' architecture and actual recursive execution; (2) let external coding harnesses act as supervisors by mounting the coordination verbs as an MCP server, not just in-process code; (3) enforce that 'done' means a deliverable ch
• Assessment: This is a good change on its merits. It is built in the grain of the codebase: it extends the existing Scope/Supervisor/createCoordinationTools substrate rather than replacing it, preserves the conserved-budget/equal-k invariant by construction, adds a depth ceiling, and bubbles spend and delivery verdicts up the recursion tree. The new primitives are well-layered (tools → in-process driver
• Better / existing approach: none — this is the right approach. I checked main directly and the recursive capability the PR adds is not present: main:src/runtime/personify/persona.ts:102 explicitly warns that a spawned child run as a driver 'drives a leaf', and main:src/runtime/supervise/scope.ts has no nestedScopeSeamKey/NestedScopeSeam (the PR adds these at src/runtime/supervise/scope.ts:117-160). main has `cr

🎯 Usefulness — sound-with-nits

A coherent, grain-following change: it lands a real recursive agent atom (Scope/Supervisor + LLM-driven coordination driver + MCP server), layers strategy/persona on top, removes verified dead code, and consolidates docs; only minor export and doc-link cleanup misses.

• Integration: The new behavior is reachable and wired in. coordinationDriverAgent and the supervisor primitives are exported from src/runtime/index.ts (src/runtime/index.ts:296-303, :333-336) and consumed by tests (tests/loops/coordination-driver.test.ts, tests/loops/coordination-mcp.test.ts), benchmarks (bench/src/atom-humaneval.mts:173, bench/src/atom-mcp-e2e.mts:136), and higher-level runtime
• Fit with existing patterns: It fits the codebase's architecture rather than competing with it. The new code sits on top of the existing Scope/Supervisor/driver-executor recursion primitives (src/runtime/supervise/supervisor.ts:64, driver-executor.ts:125) and reuses createCoordinationTools from src/mcp/tools/coordination.ts:91. It directly implements the workflow described in skills/supervise/SKILL.md (decompo
• Real-world viability: The primitives are exercised beyond the happy path: tests cover budget conservation, abort cascade, recursion, join barriers, intensity breaker, MCP over HTTP, completion-oracle selection, and worker-profile authoring. The benchmark harnesses use real router models and real deterministic checks (HumanEval Docker checker, pytest file). Production deployment would still need to swap the in-memory bl

🔎 Heuristic Signals

🟡 Cruft: console debug added bench/src/atom-humaneval.mts

• console.log(atom-humaneval: N=${N} K=${K} offset=${OFFSET} worker=${cfg.model} driver=${driverCfg.model})

🟡 Cruft: magic number added src/topology/replay.ts

+function setMs(ms){ ms=Math.max(0,Math.min(span,ms)); scrub.value=(ms/span*1000)|0; applyTo(ms); }

🎯 Usefulness Audit

🟡 serveCoordinationMcp is not re-exported from the runtime barrel [integration] ``

serveCoordinationMcp is called in tests and benchmarks (tests/loops/coordination-mcp.test.ts:64, bench/src/atom-mcp-e2e.mts:136, bench/src/mcp-mount-probe.mts:76) and is the "capable/primary" keystone path per docs/research/rsi-atom-masterplan.md:20, but a grep of src/runtime/index.ts finds no re-export. coordinationDriverAgent is re-exported at src/runtime/index.ts:298. Either add serveCoordinationMcp to the barrel or document that it is intentionally deep-import-only.

🟡 Stale docstring link to deleted research doc [integration] ``

bench/src/commit0-env.ts:2 still links to docs/research/long-horizon-benchmark-survey.md, which was retired in Pass 2 of the doc consolidation (docs/research/deletion-ledger.md:42). Update the comment to point to .evolve/current.json or docs/research/long-horizon-agent-map.md.

💰 Value Audit

🟡 AuthoredProfile is thinner than the AgentProfile law it advertises [against-grain] ``

The PR's docs establish that 'the supervisor's only intelligence is AUTHORING full profiles' and that an agent IS 'prompt + skills + tools/mcp + subagents + hooks' (docs/canonical-api.md:15-25). But AuthoredProfile only carries name, systemPrompt, and model (src/runtime/supervise/authoring.ts:23-29), and authoredWorker materializes it as a single router call with a bare { name } AgentProfile (src/runtime/supervise/authoring.ts:65-117). The supervisor skill tells the superviso

---

What this audit checks

It judges the change on its merits — not whether it was tasked out in an issue. Unticketed, fast-moving work is fine; the question is whether the change is good and whether a better or existing approach should be used instead.

Pass	What it asks
Heuristic	Vague title? Whitespace-only or cruft-bearing diff? (content signals only)
Duplication	Do added function/class names already exist elsewhere in the repo?
Value Audit	What does it do? What goal does it achieve? Is it good? Better architecture or already-exists?
Usefulness Audit	Does it integrate and fit? Will it hold up in real use and actually get used?

Findings are concerns, not blocks — the human reviewer decides what to do with them.

_{value-audit · 20260616T080709Z}