Autonomous run

Autonomous Run

Unsure whether a full run is warranted or a lighter structure fits? Start at mega-orchestration:orchestrating, the decision root.

Long unattended work fails in two ways: state lost across sessions, and an irreversible action the human did not want. This skill fixes both with a small durable file contract and an explicit autonomy dial. The files are plain text and identical across runtimes; nothing here depends on a specific harness.

The file contract

Everything for a run lives under .megapowers/run/<run-id>/. Scaffold it with scripts/run-init <run-id> --model <model-id>; the model flag records provenance so every journal entry names the acting model. run-init refuses to overwrite an existing charter.

Run IDs are lowercase kebab case (a-z, 0-9, and single hyphens), for example release-check. Every run helper rejects other forms before touching the run directory.

File	Contract
charter.md	The frozen spec: goal, explicit done-when acceptance criteria, autonomy level, blast-radius limits, and external stop budgets (time, step, or token caps) declared up front. Written once, never edited; a changed goal is a new run.
plan.md	Milestones, each with its own acceptance check, preferably an executable oracle. Update as milestones complete; do not rewrite history.
runbook.md	The operating loop: how to pick the next unmet milestone, when to stop, what to do on failure.
journal.md	Append-only audit trail of every action, decision, and result. Never rewritten.
status	Machine-readable KEY=value lines the loop and any hook read: STATE, CURSOR, LEVEL, LAST_VERIFY, PLAN_WARNINGS. Derived, never hand-written; the pointer, not the history.
evidence.md	Literal acceptance map: implementation target, local oracle, required external, UX, or database oracle, earned state, and evidence.

Milestone format matters because status derivation parses it: headings are ## <tag>: <name> where <tag> matches [A-Za-z][A-Za-z0-9_-]* (one token, then a colon; ## M2: rollout, not ## Phase 2: rollout), and each acceptance check sits on a line starting with - acceptance:. A heading that does not parse drops out of done-derivation, so scripts/run-derive-status counts it into PLAN_WARNINGS and refuses done while any remain. An acceptance check written any other way escapes the digest freeze, so it can change mid-run without the done-claim noticing.

Where the charter comes from

The run executes a goal that already survived design scrutiny; it does not invent one. Refine an ambiguous goal through megapowers:brainstorming (if installed) and copy the resulting spec's acceptance criteria into the charter's done-when list verbatim, each with an executable check where one can exist. A code milestone gets a plan only when a durable multi-step handoff is useful. Autonomous execution chooses inline work for small or coupled milestones and SDD for independently owned tasks where delegation pays for itself, then journals that choice. Its declared check names the literal acceptance oracle, never the executor's say-so. While a charter is active at level autonomous or on-the-loop, the megapowers process skills' interactive gates resolve themselves and journal the decision instead of stopping; in-the-loop keeps every gate interactive. Without the megapowers plugin, write the charter and milestones directly; the contract stands on its own.

The loop

The runbook owns the procedure. The outcomes it must produce:

• In each controlling session, explicitly invoke scripts/run-claim <run-id> before relying on the Stop hook to continue the run. The command binds that session ID to the run's owner.json; merely reading run files never claims ownership.
• Once plan.md is authored, freeze it with scripts/run-init <run-id> --replan before working the first milestone, so the milestone digest exists to certify the eventual done-claim; run-verify-status fails a done-claim that has none. After a restart or context compaction, trust the files, not your memory. The journal and git history are the truth.
• Before opening a new milestone, confirm the completed ones still pass their acceptance checks (or the declared fast subset). A run whose earlier work broke is regressing, not progressing. Delegate milestone work where a different model is better (mega-orchestration:multi-agent-delegation).
• A milestone completes only against the acceptance check declared for it in plan.md, not a substitute the work happens to pass. For an external dependency, the declared check asserts where it resolves from (for example its import path), not merely that it imports, so a vendored local substitute cannot satisfy it. Detect failure honestly; on failure, fix and re-verify within the stopping rule's bounds.
• Keep evidence.md literal. Distinguish implemented, locally verified, and externally verified, and claim only the highest state earned. User-facing criteria require the supported ordinary-user path. External database-backed criteria record caller, service, database, response, and visible-result cutpoints with environment and correlation keys.
• Journal at every decision point with scripts/run-journal <run-id> <kind> <confidence> <msg> (kind = action, decision, result, blocked, paused; confidence 0.0 to 1.0). Tag messages with their milestone ("M2: ..."). Ground every progress claim in a tool result: a result entry cites the declared check it ran and what it output, evidence rather than intention. A trailing paused entry derives STATE=paused; any later entry resumes.
• At each milestone boundary, checkpoint the work using an already authorized commit or the durable ledger and working tree, then regenerate status with scripts/run-derive-status <run-id>.
• Stop when every done-when criterion in charter.md is met, a stop budget declared in the charter is exhausted, or you hit a blocker only the human can clear. Near a budget cap, finish the current milestone cleanly and report rather than start new work.

Status is derived, never declared. The journal is the only hand-written record; run-derive-status reads done only when every milestone declared in plan.md (and every tagged milestone in the journal) has a final result entry, and a milestone whose last entry is blocked derives to blocked. Before finishing, run scripts/run-verify-status <run-id>; a run that fails the check cannot claim completion. That closure is the only sanctioned way a run reads finished, and it is eval-guarded (evals/scenarios/autonomous-run-contract). When a step delegates, the exact brief lives in the delegation artifacts; reference them from the journal message so the run stays replayable without bloating the log.

Selecting an autonomous workflow never grants permission to commit, push, merge, deploy, or perform another external side effect. Existing user and repository authorization remains binding.

Roll the controller after 8 to 10 completed tasks, or before another task would cross 80 percent of the context or cache budget. Persist status and the journal first. Reserve the final 20 percent for integration, verification, and synthesis.

Autonomy level (the dial, not blind autonomy)

charter.md declares one level; scripts/autonomy-level <level> prints the policy so every step reads the same dial. The dial gates by reversibility and blast radius, never by "is it simple":

• autonomous: do reversible and staged work without asking; only irreversible or high-blast actions stop for approval (stage them through an effect broker).
• on-the-loop (default): proceed, but checkpoint legibly so a human watching the journal can interrupt; pause for irreversible actions.
• in-the-loop: the tightest oversight cadence. Pause for approval before every staged or irreversible action, and checkpoint at each milestone boundary so the human approves the direction before the next milestone.

The invariant is about actions, not cadence: at every level a reversible action proceeds without a human gate, and an irreversible one always waits for one. What the level sets is checkpoint granularity, the oversight the user asked for, not per-action friction on reversible work. Minimizing human presence means making supervision cheap (a legible journal, a readable report, decisions ranked by confidence), not removing the human's ability to see. Scheduled and cloud runners execute without permission prompts; anything the effect broker would gate must be simulated or deferred to an attended session, and the runbook says so.

The stopping rule (adaptive compute)

Spend by stakes and uncertainty, and stop deliberately. Cap fix/re-verify attempts per milestone (default 3); at the cap, journal the milestone as blocked with what you tried and the next idea, then move on or surface it rather than loop. Scale verification effort to the milestone's stakes: a money- or auth-touching milestone earns a cross-model verification pass, a doc tweak does not.

Reporting

scripts/run-report <run-id> emits a skimmable report: what is done, what is left, decisions ranked by confidence lowest first (that is where to look), failures surfaced plainly, and the provenance trail. Run it at checkpoints and at the end so supervision costs the human a glance, not an investigation. Journal messages and report prose use the handoff register (megapowers:using-megapowers, Communication, if installed): conclusion first, declarative, self-contained.

Guards

• The frozen charter and append-only journal are what let the run be trusted and replayed. Do not tidy them.
• Declared milestones are fingerprinted: run-init snapshots each milestone heading and its acceptance line into plan-digest. Thereafter run-verify-status fails a done-claim (and run-derive-status refuses done) if a declared milestone vanishes or its acceptance line changes. To change the plan deliberately, re-run --replan, which re-snapshots and journals a decision; the charter still never changes. This is drift detection, not a security control: a long run forgets what it promised, and the fingerprint makes a mid-run redefinition of success explicit rather than silent. Anything that can edit the plan can also re-baseline the digest, so it stops accidents and self-deception, not a determined actor.
• Irreversible actions go through staging appropriate to the autonomy level; the effect broker, when present, is the mechanism.
• On Claude Code, the run-loop.sh Stop hook blocks a premature stop while a run this session explicitly claimed still reads active and points at the next unmet milestone. It is an accelerator, not the mechanism: it fails open on any doubt, respects in-the-loop (milestone checkpoints belong to the human), and the honest exit is a journaled blocked, paused, or final result entry plus a re-derived status. A hand-edited STATE is not an exit; the next run-derive-status overwrites it and run-verify-status fails a done-claim the journal does not support. On other harnesses the loop rides on the runbook discipline alone.