diff options
Diffstat (limited to 'docs/design')
| -rw-r--r-- | docs/design/2026-05-28-generic-agent-runtime-spec-review.org | 188 | ||||
| -rw-r--r-- | docs/design/2026-05-28-generic-agent-runtime-spec.org | 24 |
2 files changed, 102 insertions, 110 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 index 90d7030..3acd16b 100644 --- a/docs/design/2026-05-28-generic-agent-runtime-spec-review.org +++ b/docs/design/2026-05-28-generic-agent-runtime-spec-review.org @@ -5,174 +5,144 @@ * 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. +Second review pass after the 2026-06-12 spec-response update. -Code and docs read: +Reviewed: -- [[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. +- [[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 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. +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 for the whole spec: =Not ready=. +Rubric by arc: -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. +- *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=. -* 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. +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. -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. +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. -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. +* Overall assessment -What to change: add a short "Decisions required before phases 2-5" section with accepted answers for: +The spec is now useful as two linked plans in one file: -- 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. +- 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. -** Reverify external runtime and model assumptions before the local-model phase +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. -Blocking status: blocks =Ready= for Phase 5, not for Phase 1.5. +* High-priority findings -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. +None for Phase 1.5. -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. +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 -** Add the exact cross-project handoff artifact for ai-term.el +None. -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. +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 -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. +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, 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. +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 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 stays correctly scoped. It builds on the shipped =AI_AGENT_ID= resolver without introducing runtime manifests, bundle splitting, or local-model service setup. -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. +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 -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. +Phase 1.5 now names the important robustness details: -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. +- 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 -Specific tests to add for Phase 1.5: +The spec's ring-1 test inventory is now concrete enough to implement: -- =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. +- 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 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. +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 -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. +No new documentation recommendation. -For phases 2-5, defer broad README renames until the runtime choices are resolved. +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 -- 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. +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 -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. +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 -- 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? +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 -- 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. +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 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. +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, 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). +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 [#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 [#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] 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 [#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 [#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). +** 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). diff --git a/docs/design/2026-05-28-generic-agent-runtime-spec.org b/docs/design/2026-05-28-generic-agent-runtime-spec.org index 0b37814..01be6d4 100644 --- a/docs/design/2026-05-28-generic-agent-runtime-spec.org +++ b/docs/design/2026-05-28-generic-agent-runtime-spec.org @@ -583,7 +583,7 @@ timestamps (=YYYY-MM-DD-HHMM-from-<project>-<slug>=). A helper and primary sending to the same target in the same minute with the same slug would collide; helper-originated sends include the agent id in the slug. -*** Open issue: the Emacs launch surface — unresolved, blocks readiness +*** Emacs launch surface — integration contract Corrected 2026-06-12 after reading the actual config (the first draft of this subsection assumed eat/vterm and was wrong). The facts, verified in @@ -954,6 +954,18 @@ Every recommendation from [[file:2026-05-28-generic-agent-runtime-spec-review.or Rejections: none. +** Second pass — 2026-06-12 + +The re-review after the fold-in confirmed every disposition (its Agreed +decisions section accepts the split rubric, the caveats, and the +one-document structure) and found no new high- or medium-priority issues. +One optional editorial edit was suggested and accepted: the Emacs +subsection heading no longer says "open issue / blocks readiness", since +its body and the Status checklist had already closed it — it now reads +/Emacs launch surface — integration contract/. The review's drop-in task +shapes are already represented in todo.org per the review itself; no new +tasks were filed. + * Review and iteration history ** 2026-06-12 Fri @ 02:09:10 -0500 — Codex — reviewer @@ -965,3 +977,13 @@ Rejections: none. - What changed: folded the review in. All recommendations accepted except the document-split open question, modified to a dual rubric in one document (see Review dispositions). Status now labels Phase 1.5 READY WITH CAVEATS and phases 2-5 NOT READY; the original readiness checklist is fully resolved. - Why: the review's top finding was that one Not-ready label hid an implementable slice; the rest hardened the slice's rollout (per-ring rollbacks, normative test inventory, exact .emacs.d handoff artifact, stale-helper message contract, roster platform behavior) and fenced the parked arc (decisions-required section, Phase 5 reverification prerequisite). - Artifacts: this spec's Status, Pre-live gating, Phase 5, Open decisions, and Review dispositions sections; the helper task in todo.org carries the same caveats. + +** 2026-06-12 Fri @ 02:39:38 -0500 — Codex — reviewer +- What changed or was recommended: re-ran the spec-review workflow after the response pass. Rubric by arc: Phase 1.5 helper instances =Ready with caveats=; phases 2-5 runtime-neutral refactor =Not ready=; combined document =ready only for the scoped helper slice. No new blocking findings for Phase 1.5. Optional editorial note: rename the stale "Open issue: the Emacs launch surface" heading now that the body is an integration contract. +- Why: the response pass accepted or modified every prior recommendation into the spec, so the remaining implementation risk is controlled by the caveats/gates already written. The broader runtime-neutral arc still correctly waits on explicit product decisions and current-source local-runtime verification. +- Artifacts: [[file:2026-05-28-generic-agent-runtime-spec-review.org][2026-05-28-generic-agent-runtime-spec-review.org]] updated with this second-pass review; existing [[file:../../todo.org][todo.org]] helper/runtime tasks remain the tracking surface. + +** 2026-06-12 Fri @ 02:47:07 -0500 — Claude — author (spec-response, second pass) +- What changed: folded the second review in. Nothing substantive remained to change — the review confirmed all dispositions with zero new high/medium findings — so the response is the accepted editorial heading rename (the Emacs subsection is now /Emacs launch surface — integration contract/) and the second-pass note under Review dispositions. +- Why: the review cycle has converged. Phase 1.5 stands at Ready-with-caveats with both reviewer and author aligned on the caveats; phases 2-5 stay parked behind the decisions fence. +- Artifacts: the renamed Emacs subsection; the Review dispositions second-pass note; Codex's second-pass review file and its todo.org/history edits ride in the same commit. |