Packet rules
Rules for mission packets that survive both the guard and the reviewer. Each rule names what fails without it. Sources: docs/architecture/mission-packet-schema.md, docs/tool-guard.md, docs/runtime-targets.md, docs/runbooks/independent-review.md.
1. Declare every touched file in expected_outputs
Section titled “1. Declare every touched file in expected_outputs”List every file the packet must produce under expected_outputs.files — for a single mission at mission level, and for a team worker in that worker’s contract.
- When a worker declares
expected_outputs.files, the harness inspects the worker worktree on completion. If any declared output is missing, unreadable, or outside the workspace, the worker settlesblockedinstead ofsucceeded,team-state.jsonrecords ablocked_reasonnaming the file, and the worker’s branch is not committed and is excluded from leader integration. - A missing declared output also blocks salvage: a stopped worker’s worktree is only committed to a salvage branch when its declared outputs and required checks both pass in the worktree.
- Mission-level
expected_outputsare evaluated against the integrated repository tree at leader verification.
An undeclared file is invisible to settlement: the work can pass while the artifact you actually wanted was never produced. The registry’s acceptance campaigns use the same mechanism — C1-missing-output expects the missing file to block exactly its worker while a sibling succeeds.
2. Keep every requested action inside guard.write_roots
Section titled “2. Keep every requested action inside guard.write_roots”The guard allows writes and deletes only under write_roots (default ["."]). Paths outside them are denied as write_outside or delete_outside with the instruction to put the file under the first write root instead. Rules for the author:
- Make
write_rootscover every path the packet asks the runtime to create, edit, or delete, and nothing more. Roots are compared by path boundary: a sibling directory whose name merely starts with a configured root does not match. - Never rely on the template to widen the boundary: when a session template is applied, the mission’s
write_roots(even an empty list) always win. Strict-containment templates refuse a root of.and any absolute path outright. - Protected roots (
.harness,.commandcode,.omp,.pi,.gitby default) are read-only no matter whatwrite_rootssays; a mutation there is aprotected_rootdenial, and the supervisor turns it into a hardpolicystop that is never resumed.guard_tamper— writing to the guard’s own policy or log — is a hard stop too, and it is checked first. - Do not ask for package installs, git mutations, network clients, agent clients, or out-of-tree process launches: each has a denial class, and denials accumulate against
limits.max_denialsuntil the run stops withdenial_budget. If a dependency or input is genuinely missing, the denial text says what to do: end withBLOCKED: <what is missing>; if the work exceeds your scope, end withESCALATE: <what should be delegated>.
3. Put incident context under a heading that says it is not for verification
Section titled “3. Put incident context under a heading that says it is not for verification”Anything declared in acceptance_criteria or verification.required_checks is verified and can fail the run; anything the independent reviewer finds under acceptance or checks must match a listed id exactly, and invented ids are rejected. So:
- Keep
acceptance_criteriato the claims a check can decide, each with a stableidand acheck_command. Advisory material belongs inseverity: warnentries (recorded for the audit trail, not blocking) or outside verification entirely. - For reviewers and review packets, the report schema provides
observationsas the outlet: every id the request lists must be covered exactly once underacceptanceandchecks, and anything verified that no listed id covers goes intoobservations— it is surfaced in the assessment without changing the recommendation. An empty list must be stated as[] exactly; add nothing, never left to inference. - Guard denials follow the same principle from the other side: the denial text tells the runtime to record the refusal in its final message and continue, rather than to retry by another route. A final message that narrates denied attempts in a clearly-labelled, non-verification section is the compliant shape.
The rule in one line: incident context, caveats, and narration must be visibly separated from the things that are verified, so neither the validator nor a human reviewer can mistake one for the other.
4. Set both top-level max_turns and limits.max_turns
Section titled “4. Set both top-level max_turns and limits.max_turns”Turn caps reach the runtime through two paths, and a packet should pin both:
limits.max_turnsis enforced by UH supervision for every runtime (turn_start/turn_endevaluation; a native terminalstopReason: "max_turns"settles asturn_limittoo).- Top-level
max_turnsis what reaches a runtime’s own native flag. Forcommand-codethe precedence is: explicit top-levelmax_turns, elselimits.max_turns, else no flag. Print mode caps at 100 turns by default (exit 8) when neither field is configured — a silent native default recorded on the plan asnative_default_turn_cap: 100.
A packet that sets only limits.max_turns can run under a native cap different from its supervised one; a packet that sets both gets the native flag and the supervisor to agree on the same budget, and a turn-budget exhaustion then settles predictably as turn_limit (not automatically resumed) instead of tripping the silent default.
5. State empty lists explicitly
Section titled “5. State empty lists explicitly”Where “omitted” and “empty” mean different things, write the empty list:
guard.agent_clientsis always enforced; an explicitagent_clients: []is the only opt-out. Omitting the field takes the default client list.- Review packets spell out empty id lists as
[] exactly; add nothingso the reviewer cannot improvise coverage; the generated report schema pins the enum to the empty set. - The strict schemas reject unknown fields rather than guessing intent: a guard block with an unrecognized key fails validation, and
limits.memory_mbon a worker fails with “Per-worker memory is governed by team.resources.worker_memory_mb”. An explicit emptyskills.required: []orsource_links: []documents that the omission is deliberate.
Writing [] costs nothing and removes the one ambiguity — “forbidden” versus “forgotten” — that both the guard and the reviewer would otherwise have to guess at.
6. Run uh mission check before launching the packet
Section titled “6. Run uh mission check before launching the packet”uh mission check <mission.yaml> [--runtime <id>] validates a packet without starting a runtime and without writing to .harness. It prints one line per check (PASS, or FAIL with the reason), exits non-zero on any failure, and takes --json for tooling. It reuses the adapter planner uh mission dry-run uses to validate runtime_config_overrides, so the two cannot disagree; --runtime defaults to hermes for a single-shape packet, and each team worker is validated against its own declared adapter. A team packet also validates every worker packet it names through mission_id.
The checks map to the launch failures that keep recurring:
- The packet parses and satisfies the strict schemas — broken YAML, duplicate worker roles, and protected expected-output paths fail here.
runtime_config_overridesare accepted by the chosen runtime: a key that belongs only to another adapter (for example a command-code-onlypermission_modeon an omp packet) fails instead of launching.- Every
context.read_firstpath exists. - Every expected output — mission-level
expected_outputs.filesand each worker’s — lies inside itsguard.write_roots, compared by path boundary, so a write root that does not cover the packet’s own outputs fails. - Every path a
constraintsentry names after “Change only” exists or lies inside a write root. - Every
groundingclaim holds.
grounding is an optional, strict list of { claim, path, contains }. Each entry is a falsifiable statement about the code as it is now; uh mission check passes the claim only when path exists relative to the project root and its text contains the exact contains literal (case-sensitive). Absent or empty the field is a no-op, so existing packets stay valid. Use it to pin the facts a prompt asserts — file locations, exported symbol names, configuration keys — so a packet whose claims no longer hold fails the check instead of launching on a false premise.
7. Install a validated packet with uh mission put
Section titled “7. Install a validated packet with uh mission put”An orchestrator (a runtime with runtime_config.role: orchestrator, such as Claude Code or Command Code) may only run harness controller commands and may not write under .harness, which is protected. It therefore cannot author a packet in place, and uh mission create/new and uh propose persist only a subset of the packet fields — no guard, runtime_config_overrides, recovery, team or shape. uh mission put is the coordinator’s allowed path to persist a complete packet:
uh mission put <packet.yaml> [<more.yaml> ...] [--replace] [--root <path>] [--json]- Checks run first. Each packet is validated with the same
checkMissionPacketsengineuh mission checkuses, and a team packet validates each referenced worker through its own adapter. Any failed check refuses and prints the check output (PASS/FAILlines, or the JSON result with--json); nothing is written — no mission directory, no audit line. - Install is atomic. The packet is written to
.harness/missions/<id>/mission.yaml, where<id>is the packet’s ownid. Every installed packet appends onemission.putevent to.harness/audit/events.ndjsoncarrying the packet id and the sha256 of the installed bytes. - An existing target needs
--replace. Without it the command refuses and leaves the installed packet untouched. --replaceneeds no live run. While the live-run registryuh psreads reports a non-settled run of that mission (itsmission_idor a team worker’s),--replaceis refused so a running packet’s contract cannot change under it.- Workers are never fabricated. A team packet installs each worker packet it references by
mission_idonly when that packet is given alongside on the same command line or is already present at.harness/missions/<worker_id>/mission.yaml. A referenced worker that is neither fails the team packet’s own check.
The observability and control verbs an orchestrator needs are controller commands: uh ps, uh report, uh steer, uh resume, uh kill, uh experiment, alongside the existing uh mission/uh acceptance runs and uh mission put. The tool guard admits them to the orchestrator role and denies them to a worker as agent_client; read-only harness commands (uh status, uh validate, uh mission check, uh mission dry-run) stay available to every role, and the --force/--yolo-style flag refusals still apply.