docs(spec): fold the Codex review into the agent-runtime spec

The review's top finding was that one Not-ready label hid an implementable slice. Status now splits by arc: Phase 1.5 helper instances are READY WITH CAVEATS (the three-ring gate and the manual drills are binding, and the ai-term.el work is a coordinated .emacs.d handoff with an exact artifact), while phases 2-5 stay NOT READY behind a decisions-required section and a Phase 5 reverification prerequisite that demotes the model table to a recommendation.

The remaining findings hardened the slice: per-ring rollback actions including the half-propagated-sync case, the review's test inventory adopted as normative, a message contract for stale helper files, and explicit roster-unavailable behavior on unsupported platforms. All recommendations accepted except the document split, modified to a dual rubric in one document. The review file and dispositions table ride along.

1 files changed, 178 insertions, 0 deletions

diff --git a/docs/design/2026-05-28-generic-agent-runtime-spec-review.org b/docs/design/2026-05-28-generic-agent-runtime-spec-review.org
new file mode 100644
index 0000000..90d7030
--- /dev/null
+++ b/docs/design/2026-05-28-generic-agent-runtime-spec-review.org
@@ -0,0 +1,178 @@
+#+TITLE: Review: Generic Agent Runtime Support for rulesets
+#+AUTHOR: Codex
+#+DATE: 2026-06-12
+#+STARTUP: showall
+
+* Scope reviewed
+
+Reviewed the target spec at [[file:2026-05-28-generic-agent-runtime-spec.org][2026-05-28-generic-agent-runtime-spec.org]], the spec-review workflow, the current launcher/install/template implementation, existing tests, and existing task tracking.
+
+Code and docs read:
+
+- [[file:../../Makefile][Makefile]] — global install/deps targets still install Claude-only roots and the Claude launcher.
+- [[file:../../claude-templates/bin/ai][claude-templates/bin/ai]] — tmux launcher still hard-codes =CLAUDE_CMD=claude=, project detection via =.ai/protocols.org=, and one window per project name.
+- [[file:../../scripts/install-lang.sh][scripts/install-lang.sh]] and [[file:../../scripts/sync-language-bundle.sh][scripts/sync-language-bundle.sh]] — language bundle install/sync still writes =.claude/= and =CLAUDE.md=.
+- [[file:../../.ai/scripts/session-context-path][.ai/scripts/session-context-path]] and [[file:../../.ai/scripts/tests/session-context-path.bats][its bats tests]] — Phase 1 resolver exists and covers unset, empty, distinct, and sanitized =AI_AGENT_ID= values.
+- [[file:../../.ai/protocols.org][.ai/protocols.org]], [[file:../../.ai/workflows/startup.org][startup.org]], and [[file:../../.ai/workflows/wrap-it-up.org][wrap-it-up.org]] — protocols documents the agent-scoped path; startup/wrap-up resolve that path but do not yet implement roster-first helper branching or live-helper gates.
+- [[file:../../.ai/scripts/todo-cleanup.el][todo-cleanup.el]], [[file:../../.ai/scripts/lint-org.el][lint-org.el]], and [[file:../../.ai/scripts/wrap-org-table.el][wrap-org-table.el]] — =lint-org= and =wrap-org-table= already take =/tmp= backups; =todo-cleanup= does not.
+- [[file:../../todo.org][todo.org]] — existing Phase 1.5 helper task and broader generic-runtime parent task.
+
+I did not re-verify the time-sensitive Hugging Face model recommendations online during this review. Treat the local-model picks as stale-until-checked before Phase 5.
+
+* Implementation-readiness
+
+Rubric for the whole spec: =Not ready=.
+
+The spec is strong enough to implement the Phase 1.5 helper-instance slice if Craig accepts the caveats already captured in tracking: the synced-template rollout must stay gated, the live sandbox drills must pass, and the Emacs =ai-term.el= work must land as a coordinated cross-project change. The broader runtime-neutral refactor in phases 2-5 is not implementation-ready because it still has unresolved product choices and time-sensitive external assumptions.
+
+* Overall assessment
+
+The spec correctly identifies the current architecture: the reusable project core lives under =.ai/=, while the install surface, bundle layout, launcher, hooks, and user-facing docs remain Claude-specific. Phase 1 is already done in the repo: =session-context-path= is present, tested, and wired into startup/wrap-up path resolution.
+
+The helper-instance amendment is the most actionable part. It names the concurrency risk, defines a role contract, narrows helper writes, and gives concrete tests and manual drills. The main risk is rollout, not design: =startup.org= and =.ai/scripts/= sync broadly, so a partially validated helper branch could affect every project.
+
+The generic runtime arc is still a product decision package, not an implementation plan. It names plausible phases, but the open decisions determine file names, local runtime UX, adapter scope, and support burden.
+
+* High-priority findings
+
+** Split the ready helper slice from the not-ready runtime-neutral arc
+
+Blocking status: blocks =Ready= for the whole spec; does not block a scoped Phase 1.5 implementation if tracked as its own accepted slice.
+
+Why it matters: the spec now contains two different projects. Phase 1.5 solves a near-term same-runtime concurrency problem. Phases 2-5 rename and generalize the entire distribution. The current Status section says the spec is not implementation-ready, while the Phase 1.5 section is detailed enough for implementation. Without an explicit split, an implementer has to decide whether "start implementation" means helper support only or the full runtime-neutral refactor.
+
+What to change: in the spec Status or Recommended next step, state two rubrics separately:
+
+- Phase 1.5 helper instances: =Ready with caveats= once Craig accepts the pre-live gating and cross-project Emacs handoff.
+- Phases 2-5 generic runtime refactor: =Not ready= until the open decisions are answered and model/runtime assumptions are reverified.
+
+** Resolve the phase 2-5 product choices before implementation
+
+Blocking status: blocks =Ready= for phases 2-5.
+
+Why it matters: the spec still asks which generic instruction file to use, whether to standardize on =llama.cpp= or =ollama=, and which local agent CLI is first-supported. Those choices affect manifest schema, install paths, docs, doctor checks, runtime command templates, and test fixtures. If implementation starts now, those decisions will be made inside code.
+
+What to change: add a short "Decisions required before phases 2-5" section with accepted answers for:
+
+- generic instruction file strategy;
+- default local runtime manager/server;
+- first supported local editing CLI;
+- whether phase 2 should support only Claude + one local runtime or also Codex immediately;
+- compatibility behavior for existing =CLAUDE.md= and =.claude/= projects during the transition.
+
+** Reverify external runtime and model assumptions before the local-model phase
+
+Blocking status: blocks =Ready= for Phase 5, not for Phase 1.5.
+
+Why it matters: the local-model recommendations are inherently time-sensitive. Model availability, quant files, serving backends, GPU support, context behavior, and practical latency can change. The spec cites sources, but implementation of =rulesets doctor= and archsetup handoff should not bake in stale assumptions.
+
+What to change: make Phase 5 start with a research/verification task that records current model URLs, file sizes, license, backend support, smoke command, memory fit, and fallback behavior. Keep the spec's current model table as a recommendation, not as an implementation constant.
+
+* Medium-priority findings
+
+** Add the exact cross-project handoff artifact for ai-term.el
+
+Blocking status: not blocking for the rulesets side if the handoff is created before or during implementation.
+
+The spec correctly says =ai-term.el= lives in =~/.emacs.d= and is not a rulesets edit. That means the implementation plan should say exactly how the rulesets task hands off the required Emacs change: an inbox file, a linked task, or a commit in that repo. Otherwise the rulesets implementation can finish with shell helpers working while the F9 path remains unsafe.
+
+** Name the rollback point for template-wide helper rollout
+
+Blocking status: not blocking if the three-ring gate is accepted; it is a release-safety improvement.
+
+The pre-live gate is good: bats, sandbox, pilot, then template-wide release. Add the rollback action for each ring: remove =agent-roster= from the pilot project, revert the =startup.org= helper branch, or disable helper detection when =agent-roster= is absent. This matters because startup template sync has broad blast radius.
+
+* UX observations
+
+The helper UX is concrete enough for v1: launcher path, raw-launch safety net, helper opener, helper workflow, and wrap-up behavior are all named. The no-trigger-phrase decision for =helper-mode.org= is good because humans should not have to remember a workflow incantation when the launcher can route.
+
+For phases 2-5, the user mental model is not yet settled. A user will need to know whether they are installing a runtime, choosing a model profile, or creating project instructions. That should be decided before docs or commands ship.
+
+* Architecture observations
+
+The spec fits the current repo boundaries. =.ai/= remains core; runtime adapters can sit beside existing Claude-specific layout; the launcher and install scripts are the right integration points. The current implementation confirms the major refactor points: =Makefile=, =install-lang.sh=, =sync-language-bundle.sh=, and =claude-templates/bin/ai= all hard-code Claude assumptions today.
+
+The helper slice is intentionally smaller than the runtime manifest work and should stay that way. Do not introduce TOML manifests, local model service config, or bundle splitting while implementing =agent-roster= and helper startup/wrap-up.
+
+* Robustness and performance observations
+
+The helper data-integrity rules cover the important local lost-update shapes: scoped org edits, no helper memory writes, git mutation primary-only while concurrent, and log-before-write. The remaining robustness question is how stale helper files are surfaced without permanently blocking hygiene. The spec says this is a judgment call; implementation should make the message explicit and include file path, timestamp, and suggested actions.
+
+The =agent-roster= scan is cheap enough for startup on Linux, but it is Linux =/proc= specific. That is fine for v1 if the script reports a clear unsupported-platform result and startup treats "roster unavailable" as the no-op path described in the pre-live gate.
+
+* Test strategy recommendations
+
+Specific tests to add for Phase 1.5:
+
+- =agent-roster= returns alone when no other matching process has cwd under the project.
+- =agent-roster= excludes its own process ancestry.
+- =agent-roster= reports not-alone when a spawned sleeper or test helper has cwd at the project root or below it.
+- Startup helper branch is byte-identical to today's path when =agent-roster= is missing or reports alone.
+- Startup routes to =helper-mode.org= and skips pulls/rsync/inbox processing when =agent-roster= reports another live agent.
+- =ai --helper= assigns a sanitized helper id, exports =AI_AGENT_ID= and =AI_HELPER=, and uses the helper opener.
+- Primary and helper resolve distinct context paths.
+- Helper-originated inbox send includes the helper id in same-minute slug generation.
+- Wrap-up with live helpers pauses before hygiene/commit.
+- Orphaned-helper wrap-up runs the full closing path only when the roster reports alone.
+- =todo-cleanup.el= copies a =/tmp= backup before any mutating mode.
+
+Manual drills from the spec are necessary and should remain gates: live helper + primary scoped edit, primary wrap-up while helper is mid-task, orphaned helper closes the tree, and raw =claude= launch gets caught by startup.
+
+* Documentation and tooling recommendations
+
+For Phase 1.5, update:
+
+- =protocols.org= with a short pointer to =helper-mode.org= and the helper write tiers.
+- =startup.org= with the roster-first branch and the no-op guarantee when unavailable.
+- =wrap-it-up.org= with helper/primary wrap-up ordering and live-helper pause messages.
+- =INDEX.org= with =helper-mode.org= marked auto-routed, not user-triggered.
+- README only if the user-facing launcher gains =ai --helper= before broader runtime docs exist.
+
+For phases 2-5, defer broad README renames until the runtime choices are resolved.
+
+* Suggested spec edits
+
+- Add separate readiness labels for "Phase 1.5 helper instances" and "Phases 2-5 runtime-neutral refactor."
+- Add a "Decisions required before phases 2-5" section listing the instruction-file, local runtime, first CLI, and adapter-scope choices.
+- Add a Phase 5 prerequisite to reverify model/backend assumptions against current sources before implementation.
+- Add the exact =.emacs.d= handoff artifact for the =ai-term.el= helper path.
+- Add rollback actions for the bats/sandbox/pilot/template rollout rings.
+
+* Agreed decisions
+
+None newly agreed during this review. Existing decisions in the spec stand: primary keeps the singleton path for Phase 1.5, helpers use =helper-<rand4>= and =session-context.d/=, =helper-mode.org= is canonical, =agent-roster= is the shared detection primitive, and =ai-term.el= owns its own tmux naming/wiring on top of the shared roster.
+
+* Open questions
+
+- Are phases 2-5 still desired near-term, or should the spec be split so the helper-instance slice can ship independently and the runtime-neutral arc remains parked?
+- Which local runtime stack and editing CLI should become the first supported v1 target?
+- What exact handoff path should be used for the =~/.emacs.d= =ai-term.el= changes?
+
+* vNext candidates
+
+- Runtime manifests for Claude plus one local runtime.
+- Generic bundle layout split into common + runtime adapters.
+- Local-model doctor checks once archsetup owns install and model cache setup.
+- Codex adapter support after the first non-Claude runtime proves the manifest shape.
+
+* Implementation tasks (drop-in for todo.org)
+
+These tasks are already represented in [[file:../../todo.org][todo.org]] as parent tasks. If copied elsewhere, keep Phase 1.5 separate from the parked runtime-neutral arc.
+
+** 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, and helper write-safety docs. Spec: [[file:2026-05-28-generic-agent-runtime-spec.org]] (Migration plan, Phase 1.5).
+
+** TODO [#C] Runtime manifests and generic install commands :feature:
+Resolve the phase 2 decisions, then add =runtimes/claude.toml=, one local runtime manifest, and =make install-runtime= while keeping =make install= Claude-compatible. Spec: [[file:2026-05-28-generic-agent-runtime-spec.org]] (Migration plan, Phase 2).
+
+** TODO [#C] Runtime-aware language bundles :feature:
+Split common language material from runtime-specific adapters and add at least elisp support for the first local runtime. Spec: [[file:2026-05-28-generic-agent-runtime-spec.org]] (Migration plan, Phase 3).
+
+** TODO [#D] Runtime-neutral user-facing docs and aliases :chore:
+After compatibility aliases exist, rename Claude-specific public docs and source directories where the behavior is actually runtime-neutral. Spec: [[file:2026-05-28-generic-agent-runtime-spec.org]] (Migration plan, Phase 4).
+
+** TODO [#D] Local model install handoff and doctor checks :feature:
+After current model/backend assumptions are reverified and archsetup owns install/cache setup, add doctor checks for server availability, model files, and smoke prompts. Spec: [[file:2026-05-28-generic-agent-runtime-spec.org]] (Migration plan, Phase 5).
+
+** TODO [#B] Generic agent runtime — test surface :test:
+Unit: launcher id/runtime selection, session-context path/archive names, roster detection, helper id sanitization. Integration: two fake runtimes or primary/helper sessions writing distinct contexts; install-lang/sync-language-bundle legacy compatibility. Manual: live helper scoped edit, corruption drill, orphaned-helper close, raw-launch safety net, and Emacs F9 helper path. Spec: [[file:2026-05-28-generic-agent-runtime-spec.org]] (Test strategy and Phase 1.5 pre-live gating).