Design #18 — autonomous obot operations: the --auto session and the goal layer

1. Context and goals

The July 2026 stage model makes autonomy the next act: Stage 2 ("safety.viz released") closed with gsm.safety v1.0.0 shipped on 2026-07-22; Stage 3 is "autonomy experiments" — obot picks up and completes roadmap work with @jwildfire reviewing outcomes rather than driving every session. Requirement #18 scoped this as a small set of named autonomous lanes under the obotclaw App identity, each with a defined human gate.

Everything below builds on machinery that already exists and has survived production use:

This design covers the whole requirement but its centerpiece is the background dev lane's local form: a --auto flag on /session-init that turns the standard session opening into a fully autonomous dev session — init, pick the next increment, execute it through spawned agents, wrap up, and leave a reviewable morning surface. The GHA-hosted lanes (rollup, responder, and eventually the dev lane itself) share the same identity and grant model and are specified in §8.

2. The autonomy model: goals → increments → sessions

Three layers, each with a crisp owner:

2.1 Goal definitions — a new, small artifact

Goals live as one file per goal in obot.agent/goals/{slug}.md — YAML frontmatter over prose, the same shape as skills, so they are agent-parsable, human-reviewable, and versioned next to the machinery that consumes them (precedent: scripts/merge-policy.json):

---
name: charts
title: "G1 — keep adding charts (static + interactive)"
status: active            # active | paused — paused goals are never selected
anchors:                  # hub requirements that feed this goal
  - jwildfire/obot.roadmap#35   # nepExplorer
  - jwildfire/obot.roadmap#37   # QT Explorer Phase 2
  - jwildfire/obot.roadmap#9    # FDA static charts (phased)
backlog:                  # secondary feed, worked only when no anchor is eligible
  - jwildfire/safety.viz        # improvement backlog (e.g. #83–#89)
grant_profile: standard   # row set in the grant matrix (§5)
---
Prose: intent, boundaries, what "done for the summer" looks like,
anything a selecting session should weigh that the issues don't say.

The hub stays the source of truth for the work (requirements, stages, sub-issues); the goal file only records the standing direction plus pointers. Pausing a goal is a one-line edit; retiring one is deleting the file. Placement decided 2026-07-22 (O2): obot.agent.

3. The /goal built-in, and why we need our own layer

Claude Code ships a /goal command (v2.1.139+; facts verified against current docs 2026-07-22): a session-scoped completion condition, implemented as a prompt-based Stop hook and evaluated after each turn by a small fast model (Haiku by default). It clears when the condition is met (or via /goal clear), survives --resume, and pairs cleanly with auto permission mode and background runs; headless one-shots (claude -p "/goal …") run the loop to completion in a single invocation — the likely shape of the eventual GHA-hosted dev lane. It answers "is this session done yet?" — it does not persist across sessions, select work, or hold portfolio intent.

So the division of labor is:

The --auto init sets the in-session goal to the selected increment's exit criteria — e.g. "a draft PR exists on safety.viz implementing sv#85 with CI green, the heartbeat has a close-out line, and the wrapup draft is written" — so the built-in provides a per-turn doneness check and a natural stop, independent of the model's own judgment.

4. The --auto session lifecycle

4.1 Launch

# v1: Jeremy-triggered, one command
obot.agent/scripts/obot-auto [--goal charts|app] [--increment owner/repo#N] [--dry-run]

# which expands to roughly:
claude --bg --permission-mode auto -n "🦾🤖 {date} {goal-slug}" \
  "/session-init --auto {args}"

• Identity: autonomous sessions get their own tag — 🦾🤖 {YYYY-MM-DD} {goal-or-increment-slug}, purple in the session hub — so the dashboard distinguishes them from interactive leads (😺), siblings (👯), and ultracode jobs (⚡️). Decided 2026-07-22 (O4).
• Pre-flight (in the wrapper, fail-fast): auth freshness (the 07-12 login-expiry stall), obotclaw token mintable, workspace halt-file absent (§7), no conflicting --auto session already running, disk/worktree hygiene. Any failure aborts before a token is spent.
• --dry-run: run init + selection, print the chosen increment and planned scope, and stop — the cheap way to sanity-check selection rules early.

4.2 Init and increment selection

The init phase is the existing lean init unchanged: read the hand-off (scratchpad Overview, diary loose ends, next-session memory), reconcile with one GitHub delta agent, write the prioritized list to the scratchpad. The flag changes what happens next: instead of presenting the list and stopping, the session selects the top eligible increment and proceeds. Selection rules, in order:

1. Directed: --increment repo#N was passed → take it (still subject to the eligibility checks below; refuse and stop with needs input: if it fails them).
2. Resume: an unchecked agent-actionable item from a previous --auto run's hand-off that is still eligible → continue it before starting anything new (momentum rule).
3. Implementation-ready: highest-priority hand-off item that (a) belongs to an active goal, (b) traces to a hub requirement whose Design is signed off, (c) has its repo work scoped (sub-issue or equivalent), and (d) touches only repos the goal's grant profile allows.
4. Pipeline-advancement: if nothing is implementation-ready, take the goal's next requirement stuck earliest in the lifecycle and advance the artifact: draft the requirement/design doc, publish it, and end at the review gate. The session still produces a deliverable; the deliverable is the draft.

Hard skips, never selected: anything gated on @jwildfire (reviews, decisions, approval-tier merges); anything without a filed hub requirement (roadmap-first — the 07-12 lesson); anything touching a repo outside the grant matrix; release publishing (release prep — notes draft + staged promotion PR — is allowed, §5); ultracode launches (⚡️ scale stays an explicit human opt-in).

v1 works one increment per run. Multi-increment nights come later, if ever — a bounded, reviewable unit per run is the point of the experiment.

4.3 Execution

Per the orchestration vision (2026-07-12), the --auto lead stays thin: roadmap hygiene, session management, and scaffold work in its own hands; product work goes to spawned agents — session-spawn siblings carrying the standard briefing (heartbeat contract, merge-lane rules, deliverables-to-disk), with model/effort chosen per the allocation grant. The existing conventions apply unchanged, notably:

• TDD for code changes (the tdd skill), draft PRs from obotclaw with the 5-section obot PR template, Closes #N linkage;
• Heartbeat: every phase transition and shipped artifact logged to the shared scratchpad — the session hub is the live window into the run;
• Push verification by headRefOid comparison before trusting or cleaning anything (runbook rule 4);
• Worktrees for all branch work; cleanup per the worktree-cleanup grant (merged ⇒ remove; unmerged ⇒ leave and note).

4.4 Autonomous wrapup and the morning surface

The wrapup runs its normal collect + verify phases (fold the scratchpad, one GitHub delta agent), then hits the interactivity boundary: the checkpoint is a draft-diary review, and the standing rule for unattended sessions is explicit — stop with needs input: and the full draft; never post without review. So a --auto session ends by leaving, in order:

1. standing-grant mechanical applies done (board stage moves, issue comments, scratchpad fold);
2. the diary draft committed as a draft file (not posted) + rendered for morning review;
3. a morning digest in the scratchpad: increment attempted, what shipped (links), CI state, token/cost note per the allocation grant, anything skipped or failed, and a numbered morning-actions queue;
4. the session's own job state ending in needs input: with the digest headline.

Morning review is deliberately the same surface Jeremy already uses: draft PRs on GitHub, the session hub, the diary draft, the deployed hub site.

5. Guardrails and the K4 per-repo grant matrix

K4 (2026-07-19) calls for wider standing per-repo autonomy grants for Aug–Sept, with review reserved for designs and releases. This is the first concrete draft of those grants, scoped to what a --auto session may do unattended (interactive sessions keep today's rules — this matrix never widens what requires approval, it narrows what autonomy may touch):

Matrix as clarified with @jwildfire live, 2026-07-22 (four decisions: issue-close rule, policy-file carve-out, gsm.safety standard tier, release prep-only).

Enforcement is layered, mostly already built: the merge-gate-guard hook + two-tier merge-policy.json (merges), auto permission mode's classifier (destructive ops), the no-delete rule, and obotclaw attribution. New: the matrix above ships as obot.agent/scripts/autonomy-grants.json next to the merge policy, read by the --auto init at selection time and citable in refusals. Per O5 (decided 2026-07-22) it ships soft — consulted by the session, not hook-enforced — since the risky writes (merges) are already hard-gated; hardening is revisited after the first A1 runs.

6. Autonomy levels: A0 → A1 → A2

The level is a single field in autonomy-grants.json (shipping value: A1); promotion is a reviewed one-line change, demotion is instant (§7).

7. Kill switches and failure modes

7.1 Stopping it

• Halt file: .claude/autonomy-halt in the workspace root. Checked by the wrapper pre-flight and by the session at every phase boundary (init → select → execute → wrapup) and between spawned-agent waves; if present, the session parks cleanly: heartbeat line, digest of state so far, needs input:. Creating the file is the one-command stop (touch), removable only by Jeremy's say-so.
• Attach and interrupt: claude attach {job} works on any --auto run at any time — it is a normal background session.
• Capability revocation: remove a repo from merge-policy.json / autonomy-grants.json, or set the level back to A0, or set a goal's status: paused — each takes effect at the next boundary check without killing the session.
• Budgets: hard caps per run — wall-clock (default 4h) and a token target — checked at boundaries; hitting either parks the increment with a digest rather than pushing on.
• Built into auto mode (verified 2026-07-22): the permission classifier still hard-gates ~15 categories unattended (home-directory removals, git reset --hard, amending pushed commits, pushes to deploy-named branches, explicit ask rules — and boundaries stated in the prompt, so the launch briefing's "draft PRs only" line is itself enforced). If the classifier blocks 3 consecutive or 20 total actions, auto mode pauses the session back into prompting — an unattended run that starts fighting its guardrails self-parks into needs input rather than escalating.

7.2 Failure modes → one behavior

Every failure ends the same way: park, log, digest, needs input: — never silent, never retry-forever, never widen scope to route around a block. Specifically:

8. Scheduling and the other v1 lanes

• Trigger, v1: Jeremy-manual via obot-auto (evening launch, morning review — the proven ultracode rhythm). Scheduling is deliberately deferred to A2; when it arrives, candidates in order of fit: Claude Code's desktop scheduled tasks or local cron/launchd on the Mac (lid-open constraint noted), then GHA-hosted headless (claude -p "/goal …") once the local form is boring. Cloud routines stay out until the push-identity gap is solved (still research preview; the paused diary routine's lesson).
• Requirement-status rollup lane: scheduled GHA job on obot.roadmap posting sub-issue status rollups on open requirements — read-mostly, write scope = issue comments under obotclaw. Sequenced after --auto ships (decided 2026-07-22 — O6): the requirement stays single-threaded on the centerpiece.
• Event-driven responder lane: the @claude PR/issue responder on portfolio repos — triage, review-comment responses, check runs. Depends only on #3's permission set; specified enough by the requirement; its detailed design can ride the implementation sub-issue.
• Lane runbook: one page per lane in obot.agent (identity, trigger, scope, kill switch, escalation) — the requirement's cross-cutting deliverable, kept where the machinery lives.

9. Implementation plan

Sequenced so each piece is independently reviewable (sub-issues to be filed via requirement-tasks after design sign-off):

1. obot.agent — the --auto core (one PR): session-init SKILL.md gains the --auto mode section (§4); session-wrapup SKILL.md gains the unattended variant (§4.4, codifying the existing needs-input rule); goals/charts.md + goals/app.md; scripts/obot-auto (pre-flight + launch); scripts/autonomy-grants.json (§5, level=A1); merge-policy.json gains gsm.safety dev as a standard lane and main in the approval tier; halt-file checks documented in both skills. This PR touches policy files, so by its own carve-out it merges only with @jwildfire's approval.
2. gsm.safety branch-model adoption (repo ops, per the 2026-07-22 decision): create dev from the v1.0.0 main tip, make it the default branch, protect main as release-only via promotion PRs — mirroring safety.viz.
3. Maiden A1 run (no code): evening launch on sv#85 (decided — O1); digest reviewed next morning; grant-matrix and selection-rule fixes fed back as small PRs.
4. Rollup lane (obot.roadmap workflow + small script) — after --auto ships (O6).
5. Responder lane (workflow per target repo) — after the rollup proves the GHA + App identity path; scheduling (A2) as a separate later sub-issue.

10. Dependencies and risks

• Dependencies: hub #3 App identity (live; §7 credential retirement still pending, not blocking); obot.agent session framework v0.2.0 (shipped); merge lane (shipped); gsm.safety dev branch + protection (implementation step 2 — gates its standard lane, not the rest); obotclaw app install on open.gismo (pending — blocks G2 merges, not G1); /goal built-in availability at the pinned CLI version.
• Wrong-increment selection: mitigated by the roadmap-first gate, the hand-off list as the priority source, --dry-run, and one-increment-per-run. Worst case at A1 is an unwanted change on an integration branch — revertible, and visible in the morning digest before it goes anywhere near a release.
• Runaway cost: budgets in §7.1 + the allocation-grant cost note in every digest; A1 runs are Jeremy-triggered so frequency is human-controlled.
• Unattended failure opacity: the heartbeat + Monitor + digest triad exists precisely for this; the 07-12 overnight runs are the evidence it works.
• Drift between the /goal built-in and our layer: we depend on it only as an in-session stop check — if its semantics change, the session degrades to its own judgment plus budgets, nothing structural breaks.
• Trust erosion from one bad merge: A1 only ever reaches standard-tier integration branches where a bad merge is a revert, never a release; the policy-file carve-out keeps the machinery itself out of unattended reach; demotion to A0 is a one-line instant response.

11. Judgement calls — resolved 2026-07-22

All six calls decided by @jwildfire in the same-day live review (plus the four grant-matrix clarifications recorded in §5).