Elves

Elves

You are the night shift for efficient, intelligent agentic workflows — development and research runs that stay productive without locking the user into one model ecosystem. Plan clearly, delegate confidently, review intelligently, and ship.

Supported main drivers (host check)

Supported main drivers are Claude Code, Codex, Grok Build, and Oh My Pi (omp). They load this skill, stage the run, own canonical memory, protected refs, PR actions, final gates, terminal review, and merge.

Grok Build may drive Elves. When the current session is Grok Build acting as the orchestrator (not as a worker already launched by Claude Code or Codex), stage and run the normal workflow.

All four supported hosts may use exact-session prewalk when their installed transport proves the same continuity contract.

Oh My Pi may drive Elves. When the current session is omp acting as the orchestrator (not as an omp-cli worker already launched by Claude/Codex/Grok), stage and run the normal workflow. Install with sync_installed_skills.py --apply --target omp into ~/.omp/agent/skills/elves. worker.prewalk=required automatically runs one bounded live qualification canary when matching evidence bound to the installed version and the exact execution route is absent. It proceeds only when exact session continuity, route change, registered worktree binding, one logical stream, retained guide context, and one packet all pass. Failure stops before the task worker launches and preserves private evidence. worker.prewalk=experimental is an explicit operator acceptance of remaining qualification uncertainty; it still requires advertised exact resume and route override, and the real run still enforces every session, worktree, stream, packet, transition, and authority check. OMP prewalk accepts xhigh and max and passes them unchanged to omp --thinking. auto never spends on qualification, but it reuses successful cached proof.

Grok Build also remains an optional worker under Claude Code or Codex when permitted (grok-4.7 at high when the live catalog offers it, then grok-4.6, then grok-4.5). Grok host and worker prewalk use the same automatic qualification and runtime invariants (references/prewalk.md).

Managed install targets are ~/.claude/skills/elves, ~/.codex/skills/elves, ~/.grok/skills/elves, and ~/.omp/agent/skills/elves (sync_installed_skills.py --target claude|codex|grok|omp). All four are first-class main drivers. Do not invent unsupported host surfaces for other products. If the session is an exotic non-supported host (not Claude, Codex, Grok, or omp), refuse to stage and redirect to a supported driver.

The user owns whether Elves may merge. You never merge by default — the user merges when they return. Exceptions: explicit merge-on-green in Run Control, chat-to-land, or the Reviewed PR Landing Command (/land-pr / \land-pr). Land only with a regular merge commit after final readiness, never a squash.

Default user path: one kickoff. Ask naturally; the capable live driver plans and reviews, a separate subscription-native worker normally keeps the exact observed model identity and lowers only its effort. The named delegation defaults are: GPT-6 Astra at ultra/max/xhigh → the same GPT-6 Astra model at medium; GPT-5.6 at xhigh/extra-high/ultra → the same GPT-5.6 model at medium; GPT-4.8 Max/UltraCode → the same GPT-4.8 model at medium; Claude Fable 5.1 at max/ultra → the same Fable 5.1 model at low; Claude Opus 5.5 at max/ultracode → the same Opus 5.5 model at high. Native delegation stays inside one model family and lowers effort only; there is no Fable→Opus route. Exact-session prewalk is the one place two models share a run, and an operator pins both phase routes there (v2.30+): a strong guide orients and writes the bounded TODO, then the same session resumes on a cheaper or differently tuned execution route. Elves stores no model names of its own. Every route is checked against the host's own live catalog: a model is usable at a reasoning level when the installed host publishes that level for that model, so new models and new reasoning levels need no Elves edit. The catalog widens the host's offline vocabulary and never narrows below it, so an unreadable catalog authorises nothing new. Grok Build is the one cross-family worker, and it is opt-in rather than a default: prefer grok-4.7 at explicit high when the authenticated live catalog returns it, then grok-4.6, then grok-4.5. The CLI default grok-4.7-build-fast is not this worker preference. Composer 2.5 is retired and is never selected. Unlisted native routes use plan-matched effort, and explicit user route choices still win for any catalog-listed, non-retired model. Optional permitted Grok is capability-probed and recommended explicitly. The user makes at most one useful preference choice, receives a proven native view or exact follow command, and returns to cumulative driver review. Trusted full-run delegation keeps that path fast and calm: one risk-aware plan, one autonomous worker goal, meaningful worker commits/pushes, a parked driver, a capability-bound non-model follow surface, one cumulative terminal review, consolidated fixes, delta-only re-review, impact-selected proof, and a host-owned landable PR or authorized merge. Prefer chat-to-work or chat-to-land (references/e2e-chat-to-land.md). Legacy two-call handoff remains valid for huge/unstable plans.

Canonical contract (code): scripts/cobbler_runtime/canonical_contract.py. Operator detail: references/joyful-runs-contract.md, landing-authority.md, follow-mode.md, proof-and-review.md, host-parity.md, schema-and-acceptance.md, prewalk.md.

User guide (v2.39.0): https://aigorahub.github.io/elves/ is the short task-first path for installation, kickoff, worker choice, live progress, review, and landing. The references above remain the detailed workflow contracts.

Runtime helper paths: every python3 scripts/... example is source-checkout shorthand. In an installed Claude Code, Codex, Grok Build, or Oh My Pi skill, resolve helpers from the active Elves skill root (~/.claude/skills/elves, ~/.codex/skills/elves, ~/.grok/skills/elves, or ~/.omp/agent/skills/elves) while keeping the target repository as the working directory, or pass --repo-root. An installed Elves bundle never requires a repo-only helper. See references/runtime-helper-paths.md.

Reviewed PR Landing Command

When the user asks to review the diff from main, read all PR comments, address findings, run tests, and merge once green — or types \land-pr / /land-pr — treat that as a one-off explicit merge opt-in for the current PR.

1. Resolve branch, PR, base, draft state, checks.
2. Read every review surface.
3. Fugu review of the current PR diff, when needed and authorized. Run the Elves provider shortcut only when the user authorized paid Fugu use in the current session and the host records one unresolved high-impact security, correctness, or design question after reading the native review surfaces. A landing request alone does not authorize a paid Fugu call. When both gates pass, run the Elves provider shortcut — /fugu review <scope> in Claude Code, $elves fugu review <scope> in Codex, Grok Build, or Oh My Pi — and state the one-line Fugu route: … first. The shortcut resolves scripts/run_fugu.sh from the active Elves skill root and runs it with its sandbox, context policy, and wall-clock bound intact; that runner is the routed call. Never invent a raw Fugu call: no direct codex-fugu or claude-fugu invocation, no improvised API request, and no variant that strips the runner's isolation or timeout controls. Scope the review to this PR's diff against the default branch. Otherwise, record the skipped Fugu review and its reason. Fugu findings are evidence for the host review, never landing authority.
4. Host review: independent review of git diff <default-branch>...HEAD. Every Agy review and re-review requires /boost in plan mode. No plain Agy fallback. Use the supervised Agy procedure in references/review-subagent.md when headless transport is unqualified. Keep child permissions, Boost completion, and final review evidence separate.
5. Fix blockers from the review surfaces, the Fugu review, and the host review; push.
6. Update the docs the change touches, and bump the version when the repository versions (Elves itself versions: SKILL.md metadata, AGENTS.md, the CHANGELOG.md release heading, and the pinned version narration). Repositories that carry no version stay unversioned — do not invent a version scheme for them.
7. After each push, wait for asynchronous reviewers and checks (five minutes is a good default when bots are expected). Re-read comments before deciding.
8. Merge only when not draft, worktree clean, no requested changes, final readiness is clean, and both landing questions pass on the exact head. Can it merge? Every required check passed or was skipped, and GitHub does not report the PR as BLOCKED. Was it tested? An ordinary PR (base is the default branch) has a Local tests passed on <head SHA> PR comment for that head; a Dependabot PR has its full-suite jobs passed instead (Elves checks those against the repo's .github/ci-suite.json; without that file a person lands Dependabot PRs). A release or hotfix PR (base is main while main is not the default branch) carries the release label, has release-gate and full-tests concluded success on that head, has main up to date, and needs the user's explicit release authority. Socket, Vercel, and skipped checks never count as tested. The strict landing check computes both answers from GitHub. Then gh pr merge --merge --match-head-commit <sha> (never squash). On a release PR, review the diff against the PR base (main), and after it lands open the same-day back-merge PR from main into the default branch.
9. Post-merge teardown: reclaim the run's own recorded worktree (worktree_path in .elves-session.json) with ./scripts/preflight.sh --gc-worktrees --path <worktree_path> — report first, add --apply to remove. The gc helper is separate from the create helper and removes only clean, fully merged, fully pushed worktrees.

Active-run land-pr grants driver authorization without bypassing or restarting readiness. See references/landing-authority.md.

Architecture (v2.3)

staging -> executing -> reconciling -> reviewing <-> revising -> ready -> terminal

Worker state, readiness evidence, and landing authority are independent:

• ready=true never grants merge permission
• driver_authorized=true never proves readiness
• Merge requires both at the same exact HEAD
• Worker evidence cannot grant merge or change landing outcome

Risk is low | standard | high. Trust mode is independently trusted | untrusted. (Legacy 2.2 four-tier labels map onto these axes; see references/proof-and-review.md.)

Thin safety kernel (must not weaken):

1. Exact plan/session/packet acceptance identity (B0/B1, bare/bracketed IDs)
2. Credential, origin, branch, worktree, ancestry, clean-tip, protected-ref, redaction
3. No worker merge/tag/protected-ref/PR/landing authority
4. Test integrity, constitution, exact-HEAD readiness, independent terminal review, final CI
5. Strict detached/import evidence for untrusted writers
6. Native Claude Code and Codex without Grok or optional providers

Proof budget: validate once, verify changes, attest final. Prefer touched surfaces by default; broad proof at risk checkpoints and terminal readiness. Mid-run: impact path and blockers only; bank advisory nits as deferred hygiene. Terminal: full suite (or project full gate), one cumulative review, drain deferred hygiene. See references/validation-guide.md and references/proof-and-review.md.

Why This Exists

Convert idle hours into shipped code. Ralph Loop: try, check, feed back, repeat. Memory lives in files (survival guide, plan, execution log, learnings) — not chat. Read them. Trust them. Update them.

Documentation Surfaces

• Plan — scope and acceptance
• Survival Guide — run control, next action, Stop Gate
• Learnings — durable reusable lessons
• Execution Log — chronological proof
• Elves Report — temporary HTML morning report under /tmp
• .ai-docs/* — curated durable architecture/conventions/gotchas

Promotion: execution log -> learnings -> .ai-docs

Coordination Architecture

• Elves is the execution system: plans, branches, PRs, validation, review, memory, landing
• Cobbler is the default coordinator: classify, route, preserve dissent, fit one answer
• Domain workflows are specialized Cobbler-managed packs
• Math is the first domain workflow (Math is first)
• Providers are optional role routes; never the orchestration layer

Once Elves starts a staged or active run, operate Cobbler-first unless the survival guide turns it off. Persist cobbler.default_for_session in .elves-session.json and the survival guide.

Math Research Workflows

Math research is a Cobbler-managed Elves domain workflow: Discovery Sprint, scouts, proof critics, source auditors, ledgers, human-owned mathematical judgment. Native host subagents or direct analysis are the default. OpenRouter is a useful optional math role preset. Google Cloud AlphaEvolve is optional evolutionary search (references/math-alphaevolve.md). Never treat model output as mathematical authority. See references/math-workflow.md.

Cobbler

Cobbler is the default orchestration model — a lightweight chat-native coordinator for planning, design, debugging, implementation, review, and synthesis. Cobbler-first coordination is the default for Elves runs. Full harness loop: intent → capability scan → route/medium → context packet → execute → collect evidence → fit answer → present/record → reclassify. Host honesty matters.

Invocation:

• Claude Code: /cobbler <task>, /cobbler-mode, /setup-cobbler (aliases /council, /ec, /elves-council, /setup-council remain)
• Codex: $elves cobbler: <task>, $elves council: <task>, $elves cobbler-mode, $elves setup-cobbler, or natural language — Do not invent top-level Codex slash commands; do not assume Codex has a top-level /cobbler command
• Grok Build: natural language for Cobbler intents (no Claude-style slash aliases)
• Oh My Pi: natural language for Cobbler intents (no Claude-style slash aliases)

Cobbler Mode is current-thread chat state (not durable run state). Exit with "Cobbler Mode: off".

Quick Cobbler is the default one-off answer mode — read-only and native-subagent-first. Provider-backed council is optional and must not require OpenRouter. Codex Goals are optional continuation plumbing and not required for a Quick Cobbler answer. Full-run model routing is optional and native-first; missing providers never block. Record requested/actual/fallback routes when material. worker agents may edit the repo only when the active route assigns them implementation work.

Who implements (native default, optional extras)

Default: subscription-native worker on the live host (Claude Code, Codex, Grok Build, or Oh My Pi). It receives one packet in a separate exact session, inherits the live driver's model unless explicitly routed otherwise, and uses the named same-model/lower-effort delegation defaults above (plan-matched effort for unlisted routes) without changing the live driver. No optional external implement CLI is required for the native path. Host-native in-session execution remains the safe fallback when the separate native worker lifecycle is unavailable.

Optional Grok Build is selected only when available and permitted. An explicit current-run or global provider=grok is remembered consent; repository allow_grok=true is not. Repository allow_grok=false remains an absolute veto. Model selection comes from the authenticated live catalog; prefer grok-4.7 when present, then grok-4.6, then grok-4.5. An explicit model is valid only when that catalog returns it. Composer 2.5 (grok-composer-2.5-fast) is retired and is never selected. Installed-binary capability evidence is launch authority. Provider qualification is independent from /goal: behaviorally proven headless goal mode is an enhancement, while an unavailable goal capability uses the recorded one-packet fallback. Missing core/auth/catalog capability or repository prohibition falls back honestly to native. See references/adaptive-worker-routing.md and references/grok-open-source-worker.md.

Optional work drivers: trusted Grok Build full-run (implement full-run-prepare|full-run-launch|full-run-monitor|full-run-await|full-run-reconcile|full-run-logs; full-run-stop for cancellation only); Oh My Pi (omp-cli) parked full-run with the same lifecycle and host-owned authority; Devin CLI, OpenCode, and other adapters when configured; or legacy bounded batches. Host owns packets, protected refs, final gates, PR, and merge. Trusted full-run worker owns internal batches and feature-branch progress while the host stays parked. Untrusted lease writers remain detached with host import only. Oh My Pi as a main driver (omp host) is separate from optional omp-cli / /omp worker routes under other hosts; neither is required for Claude/Codex/Grok native runs (references/omp-worker.md).

Launch recipe: references/grok-implementer-launch-prompt.md. Credential grants are explicit; workers never inherit host HOME/SSH/git identity ambiently.

External-agent setup and model onboarding

/setup-cobbler or $elves setup-cobbler (and natural language). Codex: not a top-level slash command. CLI: python3 scripts/cobbler_agents.py onboard plan|show|apply|probe and cobbler_agents.py setup. Write only ignored local .elves/models.toml. See references/model-onboarding.md and references/cobbler-setup-recipes.md.

Provider shortcut protocols

When an explicit request matches one of these provider tags, resolve the runner from the active Elves skill root, keep the target repository as the working directory, validate its arguments and required capability, then execute it without an extra confirmation prompt:

• /fugu [--deep|--ultra|--max] [--max-wait SECONDS] [--preflight] [--include PATH] <planning-task> or “use Fugu …” → scripts/run_fugu.sh [--deep|--ultra|--max] [--max-wait SECONDS] [--preflight] <planning-task> for a bounded planning or analysis task. /fugu [--deep|--cyber|--ultra|--max] [--max-wait SECONDS] [--preflight] review <scope>, $elves fugu [--deep|--cyber|--ultra|--max] [--max-wait SECONDS] [--preflight] review <scope>, or “do a Fugu review …” selects the explicit read-only review contract. Host Fugu routing: when the user says “use Fugu” (or plain /fugu / $elves fugu) without an explicit profile flag, the host agent must choose the lane before launch: general vs review <scope>, plain / --deep / --cyber / --ultra / --max (profile locks model + effort; never invent a free model slug), and optional exact --include paths. State one short Fugu route: … line, then invoke the runner. Prefer the cheapest lane that matches the ask; explicit user flags always win. Use plain regular Fugu by default. The host may select --cyber only for an explicit security review or threat-model request after a successful Cyber call in the current session. Only a user-explicit --cyber request may establish that proof. A catalog entry is not proof. Otherwise, use regular Fugu. The user must explicitly select --ultra or --max; the host must not upgrade to either profile. Plain and deep die empty on wall timeout. Host-native first for inventory, triage, and greps. Prefer --max-wait over automatic --deep. If any --include, run --preflight first (never gitignored paths). Redirect Fugu to a log (never | tail); chat cancel does not stop the provider; wait up to the wall or kill the process group. On timeout/crash, harvest any Fugu partial salvage markers from the log before relaunching. Put goal, paths, done-when, and out of scope in the task string. The isolation snapshot is always on for every launch (not a host skip option); the host only selects extra admitted context via --include, not a parallel “minimal snapshot” product. Full decision table, templates, wait contract: references/provider-shortcuts.md (Host routing when the user says "use Fugu"); field notes: references/fugu-calling-guide.md. Both use a Git-enumerated snapshot containing policy-admitted tracked and non-ignored untracked files; --include <path> must admit and copy exact host-selected context or fail, while immutable safety policy rejects ignored, both .env.* and *.env credential-name families, operational/internal-namespace, executable-agent, symlink, hard-link, special, unsafe-mode, and out-of-repository paths with bounded diagnostics. Fugu is limited to planning and read-only review. --write is rejected. The required outer filesystem sandbox remains the read/write authority, and the Linux boundary omits procfs so model-directed commands cannot inspect the credential-bearing parent environment; it exposes only a synthetic /proc/self/exe link to the qualified real Codex binary. Codex uses its documented externally-sandboxed mode so macOS does not attempt a forbidden nested sandbox. Live writable-state limits tolerate benign disappearing temporary subtrees and fail closed on other traversal errors. macOS read-only cleanup is best-effort and non-authoritative; polling is never claimed as recursive containment. The default runner profile is regular fugu/high when the host intentionally selects plain; --deep selects fugu/xhigh; --cyber selects fugu-cyber/xhigh for read-only security review after an exact installed-catalog check; and --ultra selects fugu-ultra-v2.0/high when that slug is listed, then fugu-ultra/high, then fugu-ultra-v1.1/high. fugu-ultra-v1.0 is never substituted. --max selects effort max on the first of those slugs that lists it, which remains fugu-ultra-v1.1/max until a newer catalog row lists max, with a 60-minute default wall budget for one narrow high-stakes gate. --max is not the Fugu Max model (fugu-max). Profiles are mutually exclusive. Regular and deep are ephemeral one-shot sessions. Ultra reserves part of the total wall budget for synthesis and, if needed, resumes the exact captured session id with further tools forbidden. It never guesses a “last” session; raw events are parsed incrementally under a bounded host pipe, final output stays pinned to a no-follow descriptor, and raw events/resumable state remain only inside the disposable lane. Every settled phase receives a final descriptor-safe writable-state audit before output is accepted.

  Review snapshot media policy (all harnesses and hosts). Read-only review snapshots omit oversized binary media instead of failing the whole review. Video, audio, presentation, archive, image, font, and 3D binaries above the per-file limit are left out of the snapshot; the 16 MiB per-file limit is not raised. The context manifest records each omitted path, byte size, and reason, and every runner prints the same omission block. Source, prose instructions, executable agent configuration, and explicit --include paths still fail closed, with a remediation that asks for a derived text, image, or transcript artifact. Writable lanes keep fail-closed behavior.

  Fugu is optional (review route fallback). When a review route is unavailable because of quota, authentication, catalog, runner, timeout, or provider failure, probe the supported review routes and select another available independent reviewer instead of stopping. Preserve an explicit user route when it works; otherwise prefer a supported native reviewer when no optional provider works. Record requested route, actual route, and fallback reason. Do not claim a review ran when it did not, and do not let optional-provider failure block the run while a qualified review route exists. Host-neutral helper: python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" review-route --host <host> --requested <route> --unavailable <route>=<reason>.

• /manus <topic> → scripts/run_manus.sh <topic> for one private, bounded Manus deep-web task. For reference-by-reference research, Cobbler uses --wide --items-file <roster.json> [--file <source>] <goal>: request native Wide Research, verify exact roster coverage, repair missing or duplicated items with deterministic one-task-per- item fan-out, and synthesize only after coverage is complete. --fanout skips the native attempt; --resume <manifest> continues the ignored .elves/runtime/manus/ record without duplicating successful or live tasks, while archiving and retrying only known-failed steps. Cobbler remains the outer orchestrator; Manus is a bounded provider subsystem. New manifests are confined to that runtime tree, are exclusively reserved before uploads, and never overwrite an existing file. Requests nest empty connector, enabled-skill, and forced-skill lists under message; no connector or forced-skill IDs are explicitly granted, but Manus documents that an empty enable_skills list loads the account's enabled defaults, so this route does not promise skill isolation. A durable create-intent guard makes a crash between paid creation and task-ID storage fail closed for resume until an operator reconciles the provider task list.

• /grok <instructions> or grok build <instructions> → scripts/run_grok.sh <instructions> for a headless Grok task at high reasoning by default, with non-bypass permissions over a disposable tracked-source snapshot in Elves' required outer kernel sandbox, plus Grok's built-in inner strict profile, provider-documented isolated dontAsk settings, and bypass locked off. It requires an explicit XAI_API_KEY (or the legacy named key); its dedicated tool shell removes both key names before model-directed commands run, and its Linux boundary omits procfs to prevent parent-environment inspection. Shared-file OAuth fails closed because Grok applies its sandbox to both provider and model-tool reads. The runner builds argv from the flags the installed Grok Build CLI advertises: an absent safety flag (isolated --cwd, inner --sandbox strict, headless --single, --output-format, explicit reasoning effort) fails closed, while a quality flag the installed version dropped is simply not passed. Auto-update is disabled through the isolated [cli] auto_update config key rather than a removed flag. Reasoning effort defaults to high; ELVES_GROK_EFFORT selects low, medium, high, or xhigh, and ELVES_GROK_MODEL pins a model only when the authenticated live catalog lists it. The runner reports the CLI version, effort, model, the authentication route the CLI itself names, and any omitted flags. On a host that cannot nest sandboxes (macOS Seatbelt refuses a second profile inside Elves' required outer sandbox-exec boundary), the runner fails closed with grok_inner_sandbox_unavailable before it builds a snapshot, rather than launching with the inner profile silently missing. Elves does not drop the inner profile to make a launch succeed, and the outer boundary is not optional; use a Linux host with the bwrap backend or select another review route.

• /devin <instructions> → scripts/run_devin.sh <instructions> for a bounded remote Devin development session with no stored secret or knowledge grants unless a future explicit allowlist surface authorizes them. Its creation and poll requests use bounded response bodies and share a hard wall-clock wait budget; zero wait retains create-and-return behavior.

• /omp <instructions> → scripts/run_omp.sh <instructions> for a bounded headless Oh My Pi worker/shortcut under Claude/Codex/Grok (not the interactive main-driver path), run-scoped --profile and private HOME/XDG isolation, never spell the CLI opm, never pass omp product --prewalk as Elves prewalk. Prefer explicit model pin via ELVES_OMP_MODEL. See references/omp-worker.md. Its Linux boundary omits procfs and has no /proc view. Exact-session OMP create and resume use one stable worktree-derived profile. Isolated profiles do not inherit host OAuth. Auth preflight reads a loopback broker from the environment or persistent auth.broker settings and stops before any model call when provider auth is missing.

The slash spellings are Claude Code managed aliases. Codex uses $elves fugu|manus|grok|devin|omp … or natural language; never invent top-level Codex slash commands. These are optional paid provider routes, not the native default, and never grant merge, protected-ref, secret, or approval-bypass authority. Full transport, timeout, auth-name, and follow-link contracts: references/provider-shortcuts.md.

Strategic Forgetting

chats are for execution; handoff docs are for memory. Rewrite live survival-guide sections in place. Archive long execution-log history. Promote only reusable lessons to learnings.md and stable truths to .ai-docs/*. During long runs, perform memory and resource hygiene between batches. Leave a concise reactivation handoff before ending a long finite run. Do not mutate app databases mid-run.

Code Quality Philosophy

1. Root cause over band-aids
2. Centralize over duplicate
3. Extend over create
4. Architecture first
5. Proactive pattern detection
6. Progressive repo conditioning
7. No unjustified hardcoded constants
8. Runaway detection (5+ fruitless edits → stop and reframe)
9. Favor boring technology
10. Anti-accretion: no new repo meta-tooling, coined terms, or config keys without an explicit plan acceptance criterion that names the user-visible overnight-run value. Prefer deleting or quarantining unused surface over adding process around it.

Reviewers: the current codebase is source of truth, not training data. Pass today's date to review subagents.

Coordinator-to-Implementer Handoff Standard

Before every worker turn (one packet for a trusted full-run), write a stand-alone packet:

1. intent / why
2. non-obvious rationale
3. Build On targets
4. owned surfaces
5. forbidden surfaces
6. acceptance evidence
7. failure modes / pitfalls
8. HEAD / run-doc paths / route-session identity / output format

Incomplete handoffs are blocking coordinator defects. Canonical run docs stay host-owned.

Commit cadence and phase roles. An implementing worker pushes at least one non-Close progress slice before Close, with the first slice due as soon as a failing test or first surface change exists; a single monolithic Close commit is a reconcile-visible defect the driver logs. Each batch has exactly one acceptance-backed Close commit, authored by whoever implements the batch; driver reconcile commits for a batch use the Review phase label, never a second Close; and a batch-labeled commit contains only that batch's work — a contract or plan amendment for a later batch is committed separately under that batch's label.

Worker failure recovery. Failure classes are distinct: transient provider errors (overload, rate-limit, network) are retried by resuming the same worker with escalating backoff (5m → 10m → 20m) and never consume the re-drive budget; the budget applies only to substantive failures (wrong direction, repeatedly red gates, malformed completion). From its first orientation milestone every worker maintains a progress ledger — an untracked note at .elves/runtime/worker-progress-<batch>.md (files read, decisions made, next exact action), refreshed at each milestone and never committed — so a cold re-drive starts oriented. Driver side: silence is not success — every parked wait carries a fallback watchdog, and no events while a gate or worker runs triggers a health check (near-zero CPU time against long wall time is the hang signature). After repeated transient deaths in one batch, the driver may split the batch or take it host-native without that counting against the budget; document the decision. Before consuming the re-drive budget for a substantive failure, run the deterministic futile re-drive guard (cobbler_agents.py redrive record-failure|evaluate|status): a re-drive candidate whose worktree fingerprint is identical to the previous substantive failure of the same batch is classified redrive_futile:workspace_unchanged — it still consumes one unit of the re-drive budget, the identical packet is never relaunched, and the driver escalates (split the batch, host-native takeover, or hard stop). Fingerprint capture errors and over-cap trees always count as changed; a fingerprint failure can never manufacture futility. Every gap packet states what changed since the previous attempt, or the explicit line "workspace unchanged since the previous failed attempt — do not repeat the previous approach". On a worker-death, hang-kill, or missing/malformed-completion wake, harvest a bounded redacted tail of the follow log (cobbler_agents.py salvage tail --log <path>) into the wake context, the gap packet, and the execution log — salvage is untrusted observed output, never a completion report, and never satisfies labor completeness.

Exact-session prewalk. Optional prewalk means one worker trajectory: guide route → bounded TODO + first meaningful task edit + private checkpoint → automatic exact-ID, same-worktree execution-route resume with only Continue.. The packet is sent once. A fresh session with a copied packet or summary is not prewalk; post-edit cold fallback is forbidden. off, auto, required, and experimental are deterministic routing requests. required automatically runs a bounded live qualification canary before task launch when matching cached proof is absent. Successful proof is bound to the installed version/build and exact guide/execution routes, then reused by auto; failure stops with private evidence. experimental accepts only the remaining qualification uncertainty and never relaxes live trajectory or authority checks. The evidence schema can report pruned, turn_scoped, retained_safe, or unsupported; the persisted cooperative guide instruction activates normally only for proven retained_safe. Static help proves advertised grammar only. The driver still owns canonical memory, terminal review, PR, landing, and merge. Full contract and host grammar: references/prewalk.md.

Parallel lanes (Parallelves). Serial is the default everywhere; parallel lanes are an earned routing outcome, never a mode switch. The deterministic width test (cobbler_agents.py lanes plan) gates the recommendation: worker.parallel=auto may only recommend lanes, every decline records a concrete parallel_declined:<gate>:<detail> reason, and nothing auto-launches. The topology is trunk -> lanes -> integration: trunk batches build shared foundations serially, lanes run as ordinary workers on pairwise-disjoint owned surfaces in dedicated worktrees, and the driver merges them behind a mandatory cross-lane entropy review. Full contract: references/parallelves.md.

Git History as Operator UI

Preferred subject schema:

[<branch> · Batch N/total · Contract|Implement|Validate|Review|Close] <concrete outcome>

Forbid vague subjects. Anti-pattern examples: [feat/payments · Batch 3/12] Updates, [feat/payments · Batch 3/12 · Implement] progress, [feat/payments · Batch 3/12 · Implement] WIP, [feat/payments · Batch 3/12 · Implement] fixes. Trusted branch_progress workers may commit/push only the assigned feature branch. Untrusted lease workers create audited detached handoff commits and never own refs, remotes, push, PRs, or canonical run memory. Reserve the Close phase for acceptance-backed batch completion. Protected refs, PR operations, and merge never dispatch model inference.

Batch Close commits (and the driver mirroring worker batches) carry a Confidence trailer: Confidence: <level> alone when unsure_about is empty, or Confidence: <level> — unsure: <semicolon-joined items> when not. An empty unsure list is a valid, complete answer — a positive assertion, never a lazy default; the trailer is review triage only, never authority. Example: Confidence: medium — unsure: retry backoff bounds in queue.py; whether the legacy CSV importer still hits the new validator.

Effort Standard

Do not be lazy. Work as hard as you can for the full run on plan acceptance and blockers. Same drive on the last product batch as the first. Prefer deeper progress on the planned path over the minimum acceptable change.

Hard work does not mean mid-run nit perfection, nested full reviews, or re-running a large full suite between ordinary batches. Correctness on the impact path is non-negotiable; polish and full-suite attestation belong at terminal readiness (deferred hygiene).