AI Repo Operating Contract

Default execution decision order

For ordinary LifeHub work, prefer the least-indirect sufficient route in this order:

• GitHub-native read/write/action when the task is fundamentally repository or GitHub work.
• Purpose-built structured LifeHub or SentinelX operation when machine execution is required.
• Governed privileged broker action only when privilege is actually required and the exact action is already authorized.
• Bounded free-form shell when no suitable structured primitive exists and direct execution remains sufficient; keep the command narrowly scoped, single-purpose, and tied to an explicit working directory or target.
• Remote Desktop Commander (RDC) only as the last-resort direct-execution surface after the preceding direct routes are insufficient.
• Authorized independent worker only when direct execution, including RDC where it is technically applicable, is factually insufficient and the separate worker/delegation gate is satisfied. For substantial repo-local coding or validation, prefer the production-qualified native Codex lane when it matches the authorized worker class; otherwise use the exact authorized Hermes, Adam, or other worker contract and transport.

Operation classification

Before machine execution, classify the intended action using the smallest applicable class:

• github-native
• structured-machine-read
• structured-machine-mutation
• governed-privileged-broker
• bounded-shell
• authorized-independent-worker
• native-codex-repo-work (worker subtype)
• rdc-last-resort

Preferred command and action shape

Favor:

• one operation per request;
• an explicit repository, worktree, service, or path;
• exact known identifiers such as PR number, full SHA, job ID, unit name, or fixed action name;

Filtered or delayed tool action

If a legitimate action appears to be filtered, delayed, or blocked before reaching the target:

• Determine whether the target actually received or created the request/job. For a mutation, distinguish confirmed receipt, confirmed non-receipt, and unknown receipt.
• If receipt is unknown for a non-idempotent mutation and there is no durable job identity or idempotency mechanism that is guaranteed to cover the fallback path, stop and reconcile the original request outcome before any retry, decomposition, surface switch, or worker fallback. Do not create a second potentially effective mutation while the first may still complete.
• Do not weaken provider safeguards, SentinelX policy, Linux permissions, Git safe.directory, sudoers, repository ownership, review controls, or other LifeHub protections.

Bounded output and observability

Keep high-volume validation, build, and runtime logs on the governed execution surface whenever practical. Return only the decision-relevant bounded result: exact target identity, exit/disposition, selected test counts, concise failure summary, and a durable evidence reference when available.

• operation class;
• selected execution surface;
• whether the target received the request;

Relationship to structured review execution

Issue #758 and merged PR #761 establish the same direction for Independent Review: GitHub-native portable validation first, bounded structured SentinelX/LifeHub execution for machine work, deterministic job identity, fixed repositories/worktrees/actions, structured bounded results, and no arbitrary credential/path/merge/deploy authority. This section generalizes that execution-shaping doctrine to ordinary LifeHub work without altering Independent Review assurance, reviewer independence, merge authority, deployment authority, or production controls.

Pre-push scratch boundary

The pre-push helper must not depend on the caller's default temporary directory. When LIFEHUB_PRE_PUSH_TMPDIR is absent, it derives a deterministic host-visible scratch root from the repository owner's account home (~/.lifehub-pre-push), not TMPDIR, HOME, /tmp, or accidental transient-service environment inheritance.

Repository assertion failure

A validator command started and returned a nonzero result, failed assertion, syntax error, test failure, or other substantive repository result.

Runner or execution-boundary failure

The workflow produced no validator step, steps: none or steps: null, no job log for a validator command, or an account-capacity, billing, runner-allocation, or job-start failure before the first repository command executed.

• do not repeatedly rerun the same no-step failure;
• validate the exact PR head in a clean isolated checkout or task worktree;
• use the portable validation entrypoint or the exact registered suite commands;