#+TITLE: Review: Generic Agent Runtime Support for rulesets
#+AUTHOR: Codex
#+DATE: 2026-06-12
#+STARTUP: showall

* Scope reviewed

Second review pass after the 2026-06-12 spec-response update.

Reviewed:

- [[file:2026-05-28-generic-agent-runtime-spec.org][2026-05-28-generic-agent-runtime-spec.org]] end to end, including the new split readiness rubric, Review dispositions, Phase 1.5 rollback/test gates, and phases 2-5 decision fence.
- [[file:../../Makefile][Makefile]], [[file:../../claude-templates/bin/ai][claude-templates/bin/ai]], [[file:../../scripts/install-lang.sh][scripts/install-lang.sh]], and [[file:../../scripts/sync-language-bundle.sh][scripts/sync-language-bundle.sh]] as the current Claude-specific implementation surface the runtime-neutral arc would touch.
- [[file:../../.ai/scripts/session-context-path][.ai/scripts/session-context-path]] and [[file:../../.ai/scripts/tests/session-context-path.bats][session-context-path.bats]] as the already-shipped Phase 1 slice.
- [[file:../../todo.org][todo.org]] tracking for the Phase 1.5 helper task and the parked phases 2-5 runtime-neutral task.

I did not reverify current Hugging Face/model/backend facts online. The updated spec now makes that a Phase 5 prerequisite before implementation, so stale model facts no longer block the helper slice.

* Implementation-readiness

Rubric by arc:

- *Phase 1.5 helper instances:* =Ready with caveats=.
- *Phases 2-5 runtime-neutral refactor:* =Not ready=.
- *Combined document:* =Ready with caveats for Phase 1.5 only; not ready for phases 2-5=.

The 2026-06-12 response pass dispositioned the prior blockers for Phase 1.5. The spec now says exactly how helper startup is detected, how helpers get identity, what they may write, how wrap-up behaves, how synced-template rollout is gated and rolled back, how stale helper files are reported, what the Emacs handoff artifact is, and which tests/manual drills gate release.

Phases 2-5 remain intentionally parked. That is acceptable because the spec now fences them behind explicit decisions and a current-source verification prerequisite instead of pretending they are ready.

* Overall assessment

The spec is now useful as two linked plans in one file:

- a concrete, implementable helper-instance slice for same-project Claude concurrency; and
- a broader runtime-neutral architecture proposal that is deliberately not implementation-ready yet.

That split resolves the earlier ambiguity. An implementer can start the helper work without accidentally starting the manifest/local-model/bundle refactor, and the parked arc has a clear list of decisions that must be answered before code starts.

* High-priority findings

None for Phase 1.5.

For phases 2-5, the blocking state is already captured in the spec's =Decisions required before phases 2-5= section and Phase 5 reverification prerequisite. No new high-priority finding is needed beyond preserving that gate.

* Medium-priority findings

None.

The prior medium recommendations were folded in: exact =.emacs.d= handoff artifact, per-ring rollback actions, stale-helper message contract, unsupported-platform roster behavior, and normative ring-1 test inventory.

* UX observations

Phase 1.5 now matches the user's mental model: "spawn a helper" is a launcher/Emacs action, not a remembered workflow incantation. The safety-net path for raw =claude= launches also keeps accidental helper sessions from running full startup.

For phases 2-5, UX is not yet settled, but the spec now explicitly parks that work until the instruction-file/runtime/CLI choices are made.

* Architecture observations

The helper slice stays correctly scoped. It builds on the shipped =AI_AGENT_ID= resolver without introducing runtime manifests, bundle splitting, or local-model service setup.

The current implementation still supports the spec's current-state claims: =Makefile=, =install-lang.sh=, =sync-language-bundle.sh=, and =claude-templates/bin/ai= remain Claude-centered. That is fine for Phase 1.5 and remains the reason phases 2-5 need a separate go/no-go.

* Robustness and performance observations

Phase 1.5 now names the important robustness details:

- roster unavailable is explicit and takes the no-op path;
- startup helper routing happens before pulls/rsync;
- helpers avoid full-file passes, inbox processing, memory writes, and concurrent git mutation;
- stale helper files surface path, timestamps, and concrete actions;
- file-wide passes require =/tmp= backups, including =todo-cleanup.el=;
- template-wide rollout has rollback semantics even during partial propagation.

No additional robustness blocker found.

* Test strategy recommendations

The spec's ring-1 test inventory is now concrete enough to implement:

- roster alone / not-alone / ancestry-exclusion cases;
- startup byte-identity when roster is absent or alone;
- startup helper branch skips pulls, rsync, and inbox processing;
- =ai --helper= id/export/opener behavior;
- primary/helper distinct context paths;
- helper-originated =inbox-send= slug id;
- live-helper wrap-up pause;
- orphaned-helper close only when alone;
- =todo-cleanup.el= backup before mutation.

Manual gates are also explicit: live helper scoped edit, corruption drill, orphaned-helper close, raw-launch safety net, and Emacs F9 helper path.

* Documentation and tooling recommendations

No new documentation recommendation.

Phase 1.5 already names the documentation surface: =protocols.org= points to =helper-mode.org=, =startup.org= and =wrap-it-up.org= carry branches, and =INDEX.org= marks =helper-mode.org= auto-routed rather than user-triggered.

* Suggested spec edits

No blocking edits.

Optional clarity edit: change the heading =Open issue: the Emacs launch surface — unresolved, blocks readiness= because the body now says the integration is designed and the Status checklist marks the launch surface closed. A neutral heading such as =Emacs launch surface — integration contract= would better match the current status. This is editorial and does not block implementation.

* Agreed decisions

The second pass accepts the spec-response dispositions:

- Phase 1.5 helper instances are =Ready with caveats=.
- Phases 2-5 remain =Not ready= until the five listed decisions and Phase 5 reverification happen.
- The spec stays in one document with split rubrics rather than being physically split.

* Open questions

Only for phases 2-5:

- generic instruction-file strategy;
- local runtime manager/server default;
- first supported local editing CLI;
- phase-2 adapter scope;
- compatibility behavior for existing =CLAUDE.md= / =.claude/= projects.

These do not block Phase 1.5.

* vNext candidates

Same as the parked runtime-neutral arc:

- runtime manifests for Claude plus one local runtime;
- common/runtime language-bundle split;
- local-model doctor checks after archsetup owns install/cache setup;
- Codex adapter support after the first non-Claude runtime proves the manifest shape.

* Implementation tasks (drop-in for todo.org)

These are already represented in [[file:../../todo.org][todo.org]]. The helper task can proceed under the caveats; phases 2-5 remain parked.

** TODO [#B] Helper instances — concurrent same-project Claude :feature:
Implement Phase 1.5: =agent-roster=, =ai --helper=, =helper-mode.org=, startup/wrap-up helper branches, live-helper gates, the =.emacs.d= handoff, and helper write-safety docs. Spec: [[file:2026-05-28-generic-agent-runtime-spec.org]] (Migration plan, Phase 1.5).

** TODO [#B] Helper instances — test surface :test:
Unit: roster detection, id generation/sanitization, context path resolution, backup-before-mutation. Integration: startup no-op and helper branch behavior, launcher helper exports/opener, inbox-send helper slug, wrap-up live-helper pause. Manual: live helper scoped edit, corruption drill, orphaned-helper close, raw-launch safety net, Emacs F9 helper path. Spec: [[file:2026-05-28-generic-agent-runtime-spec.org]] (Phase 1.5 pre-live gating).

** TODO [#D] Runtime-neutral arc — decision pass :spec:
Answer the five =Decisions required before phases 2-5= items before implementation starts. Spec: [[file:2026-05-28-generic-agent-runtime-spec.org]] (Open decisions).

** TODO [#D] Local model assumptions — current-source recheck :spec:
Before Phase 5, record current model URLs, file sizes, licenses, backend support, smoke command, memory fit, and fallback behavior against live sources. Spec: [[file:2026-05-28-generic-agent-runtime-spec.org]] (Migration plan, Phase 5).