# AI Repo Operating Contract (Repository-Wide)


<!-- lifehub-reader-view-link -->
> **Reader View:** [Open the generated HTML reader view](../../07_outputs/reader_site/pages/LifeHub/08_admin/03_operator/AI_REPO_OPERATING_CONTRACT.html). Markdown remains the canonical source of truth.

Last updated: 2026-10-04

## Purpose
Repository-wide operating contract for any AI operator/agent working in LifeHub.
This is not app-specific.

## Source-of-truth rule
- Repository files are authoritative.
- Chat is execution interface, not canonical memory.
- Important decisions must be written to the correct file surface.

## Owner-Facing Reporting Contract

All substantive LifeHub progress and closeout reports must follow `LIFEHUB_OWNER_REPORTING_PROTOCOL.md` (`lifehub-owner-v1`).

The owner-facing layer must state the outcome, current status, practical significance, `Your action` including `None`, and one next operator action. When the response exceeds 750 words, it must begin with a TL;DR of roughly 10% of the response.

Detailed commands, logs, test matrices, changed-path inventories, and exact technical evidence belong in durable repository or external evidence artifacts. The owner report links that technical evidence; it does not reproduce it unless a technical fact materially changes the owner's decision.

## Action Surface Precedence

For Custom GPT / connector-enabled operation, the GitHub connector/action is the default surface for ordinary repository reads and writes. Use local repository worktrees only when local execution is required.

Local execution includes Codex/Hermes dispatch, shell scripts, tests, builds, grep-heavy validation, runtime inspection, or explicit user-requested machine inspection/modification. A local checkout must not be used for routine source-of-truth edits merely because it exists.

Canonical main worktrees are infrastructure, not scratchpads. They are for read-only inspection, clean fast-forward, and sentinel checks. They must not be used for routine documentation edits or mixed with GitHub connector writes.

VM-based repo mutation must happen on a dedicated task branch/worktree. After local-agent work completes, routine follow-up edits return to the GitHub connector unless continued local execution is still required.

If GitHub connector writes have occurred against the relevant repository/base, any later VM operation must fetch and reconcile before local mutation. Canonical main must be clean and fast-forwarded to `origin/main`; a task worktree must be clean and reconciled with its intended target base or upstream branch. If the worktree is dirty or behind its intended base, stop and reconcile before editing. Preserve meaningful local changes on a branch/commit before reset or fast-forward.

## Provider-Aware Bounded Execution Policy

This section is the canonical execution-shaping policy for ChatGPT-facing LifeHub work. Its purpose is to make legitimate operations explicit, bounded, typed, auditable, and easier for provider-side systems to classify correctly. It is **not** authority expansion and must never be used to weaken, evade, bypass, conceal from, or work around provider safeguards or LifeHub security controls.

### Default execution decision order

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

1. **GitHub-native** read/write/action when the task is fundamentally repository or GitHub work.
2. **Purpose-built structured LifeHub or SentinelX operation** when machine execution is required.
3. **Governed privileged broker action** only when privilege is actually required and the exact action is already authorized.
4. **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.
5. **Remote Desktop Commander (RDC)** only as the last-resort direct-execution surface after the preceding direct routes are insufficient.
6. **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.

This is an execution-shaping preference, not a reduction or expansion of authority. A route that lacks the required authorization, qualification, or trust boundary is skipped rather than treated as implicitly permitted.

### 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`

The classification is an operator aid, not a new authority source.

### 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;
- fixed working directories and allowlisted parameters;
- read-only inspection before mutation when practical;
- fixed schemas and typed parameters instead of free-form command text;
- small deterministic outputs;
- quiet validation executed on the governed machine surface with only a bounded summary, tail, or artifact pointer returned through ChatGPT;
- lifecycle-aware status polling of an existing job instead of reissuing the work;
- native package, repository, and service-management tools instead of download-and-execute patterns;
- idempotency keys or deterministic job identities for mutations where the surface supports them.

Discourage unless technically necessary:

- broad recursive host or filesystem scans;
- broad `/proc`, credential, network, process, or host enumeration;
- large mixed read/write/admin shell programs;
- multiple unrelated actions in one command;
- arbitrary root shell when a typed privileged action exists;
- transporting large raw validation logs through ChatGPT;
- repeated near-identical attempts after a provider-side filter event.

Free-form shell remains available when it is the least-sufficient authorized tool; the policy narrows its shape rather than banning it.

### Filtered or delayed tool action

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

1. Determine whether the target actually received or created the request/job. For a mutation, distinguish confirmed receipt, confirmed non-receipt, and unknown receipt.
2. 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.
3. Do not weaken provider safeguards, SentinelX policy, Linux permissions, Git `safe.directory`, sudoers, repository ownership, review controls, or other LifeHub protections.
4. Do not encode, disguise, fragment, rename, or obfuscate the intended command to evade provider safeguards.
5. After confirmed non-receipt, or when a durable shared idempotency/job mechanism makes duplicate execution impossible, decompose the operation into smaller semantically clear actions.
6. Prefer a GitHub-native or typed structured endpoint when one can perform the task.
7. If no suitable structured route exists and direct execution remains sufficient, use one narrowly scoped bounded-shell operation rather than a large chained program.
8. If the preceding direct routes are insufficient, use RDC only when it is a technically applicable last-resort direct recovery surface.
9. Only after direct execution is factually insufficient may an independent worker be used, and only when its exact worker/delegation gate is satisfied. Prefer the qualified native Codex lane for substantial repo-local implementation or validation when scope-matched; otherwise use the exact authorized Hermes, Adam, or other worker lane. Keep ChatGPT as coordinator of authority, GitHub state, review, integration, and reporting.

Do not repeatedly resend increasingly reformulated variants merely because a provider-side filter occurred. A filter is a routing fact, not permission to broaden capability or obscure intent.

### 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.

Recurring provider-side friction may be recorded only at an aggregate operational level sufficient to improve LifeHub routing, for example:

- operation class;
- selected execution surface;
- whether the target received the request;
- provider-side filtered/delayed vs target-side failed;
- successful fallback class;
- bounded timestamp/correlation ID when available.

Do not preserve a catalog of obfuscation attempts, classifier-trigger guesses, or instructions intended to defeat provider detection.

### 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.


## Validation authority

Repository-contained validator code and contracts are authoritative. A GitHub Actions workflow is one replaceable execution venue for those validators and produces commit-scoped operational evidence only.

The portable validation entrypoint is:

```bash
python3 LifeHub/04_assets/operator_continuity/lifehub-validate.py \
  --root . \
  --changed-from <verified-base-ref> \
  --expected-head <full-head-sha> \
  --require-clean \
  --evidence-file <outside-repository-path>
```

Suite definitions and path-selection rules are tracked in:

`LifeHub/04_assets/operator_continuity/lifehub-validation-suites.json`

## Approved publication gates

Approved local repository publication paths are fail-closed:

1. every ordinary local commit must pass the installed shared `pre-commit` hook, including the exact staged-index Publication Policy validator;
2. every ordinary local push must pass the installed shared `pre-push` hook, which validates each exact non-deletion commit/ref in a disposable detached worktree through `lifehub-validate.py`;
3. `git push --no-verify`, suppressing hooks, replacing the shared wrappers, or otherwise bypassing these gates is outside approved publication paths; and
4. connector/API writes cannot be intercepted by local Git hooks, so their exact PR head must pass portable exact-head validation before the PR is advanced, approved for merge, or merged.

Publication Policy is the deliberately scoped normalization and protection layer for material entering repository history. Its rules are declarative and reusable; the first declarative rule protects the canonical Agent Adam name, while future approved rules may cover other high-value publication invariants without adding bespoke hook code. It is not a general repository-governance or authorization engine.

The hooks are local execution controls backed by repository-tracked source. They do not replace review, branch protection, independent-review requirements, or exact-head merge evidence.

### 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. The scratch parent and root are authenticated before use: no symlinked path components, repository-owner identity, no group/world-writable parent, exact `0700` scratch-root mode, and location outside every registered worktree and the shared Git directory.

An explicit `LIFEHUB_PRE_PUSH_TMPDIR` remains an admitted override only when it is already present at hook entry and satisfies the same trust checks. A transient systemd unit that requires the override must pass it explicitly through the unit contract (for example `Environment=` or `systemd-run --setenv=`); setting it only in the process that asks systemd to create the unit is not a supported propagation mechanism. Correctness must remain safe when the override is absent or the transient unit strips caller environment.

The same repository-contained commands may be executed by a local operator, Codex/Hermes task worktree, GitHub Actions, or a future authorized LifeHub Mesh validation worker. No execution venue may silently redefine, omit, or weaken the registered suite.

## GitHub Actions degraded mode

Classify the result before treating a red check as a repository failure.

### Repository assertion failure

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

This is a real validation failure. Correct the candidate or document a separately authorized exception. Do not relabel it as infrastructure failure.

### 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.

This is not a failed repository assertion. During a confirmed Actions outage or exhausted-credit period:

1. do not repeatedly rerun the same no-step failure;
2. validate the exact PR head in a clean isolated checkout or task worktree;
3. use the portable validation entrypoint or the exact registered suite commands;
4. record the base SHA, head SHA, selected suites, results, changed paths, and semantic review in the PR;
5. inspect the published diff and applicable integration-group conflicts;
6. proceed under existing merge authorization when local exact-head evidence passes and GitHub reports the candidate mergeable;
7. do not weaken branch protection, workflow permissions, or repository authority merely to clear a red UI result.

When the failure classification is ambiguous, inspect the available steps and logs. If it cannot be established whether repository commands ran, treat validation as unproven and run exact-head local validation.

## Required PR validation evidence

Use this compact block when GitHub-hosted execution is unavailable or non-substantive:

```yaml
validation_mode: local-exact-head
validated_base_sha: <full-base-sha>
validated_head_sha: <full-head-sha>
runner_condition: <no-step, capacity, billing, runner-allocation, or none>
selected_suites:
  - <suite-id>
changed_paths_reviewed: true
suite_results:
  passed: <count>
  failed: 0
git_diff_check: passed
semantic_review: passed
evidence_location: <outside-repository artifact path or PR summary>
```

The evidence must correspond to the current PR head. A new relevant commit invalidates earlier exact-head evidence and requires rerunning the affected suites.

## Fast-Track Execution Lane

`LifeHub/08_admin/03_operator/FAST_TRACK_EXECUTION_POLICY.md` defines the explicit owner-authorized alternate lane for accelerated experimental or canonical work. Fast-Track changes only the safeguards it explicitly waives or compresses; source-of-truth, task authority, scope, recoverability, Publication Policy, red-zone boundaries, and truthful reporting remain active.

For a valid eligible Canonical Fast-Track binding, exact-head path-selected deterministic validation, coordinator semantic review, current-target reconciliation, integration-domain controls, mergeability, and expected-head protection remain mandatory. Repository merge under Fast-Track creates no deployment, activation, production, credential, destructive, spending, legal, or external-write authority.

When `independent_review` is validly waived by Fast-Track, **do not enter independent-review machinery**: do not create a review request, reviewer reservation, reviewer preflight, approval challenge, freeze, or review circuit-breaker execution merely to mark it skipped. Record the waiver and resulting assurance debt in the work's existing durable owner surface. If Fast-Track is absent, ambiguous, expired, red-zone blocked, or self-protection excluded, use the normal review lane below.

## Independent review gate for risk-qualified pull requests

Apply `LifeHub/08_admin/03_operator/workspace_protection/INDEPENDENT_REVIEW_COST_AND_EXECUTION_POLICY.md`.

M1 review admission resolves to A0–A3 assurance. A0 uses deterministic protection only. A1 requires an autonomous independent reviewer at or above C1. A2 requires C2 and uses the policy-defined asymmetric approval challenge only after qualifying approvals. A3 requires C3 and fails closed when no autonomous C3 model+adapter pairing meets the minimum critical floor.

Model, reasoning, capability, and adapter are selected from the authenticated current-control-plane registry by the deterministic selector. Product model names are operational provenance, not policy classes. For A1/A2, use the nearest acceptable qualified fallback when the ideal route is unavailable.

Canonical review admission carries standing authority for `policy-admitted independent-review execution`; do not return to Yesh for per-review authorization or manual review launch. Unrelated implementation workers remain separately gated.

The implementer execution may not approve its own work. Preserve exact-head identity, candidate/control-plane separation, deterministic validation, target reconciliation, structured findings, result binding, final publication refresh, and the repeated-review stabilization gate. A review approval does not authorize merge, deployment, activation, credentials, destructive action, or production mutation.

## Canonical clone model
- Canonical operational clone for local VM operations: `/home/cloudhermes/work/LifeHub2.0-cloudrepo-main`
- Preview/sandbox clone: `/home/cloudhermes/work/LifeHub2.0-preview-mongumeal`
- Default local behavior: use the canonical clone for read-only inspection, clean synchronization, or task-worktree creation unless task is explicitly preview/sandbox. Do not use the canonical clone itself as a routine editing surface.

## Cross-clone boundary rule
- Never edit the same logical artifact in both clones during one task unless doing an intentional sync.
- If intentional sync is required, state it explicitly in task notes and validate both trees after edit.

## Scope coverage (all domains)
Any AI operator must support and route work across:
- `LifeHub/01_inbox` intake and triage
- `LifeHub/02_projects` active project execution
- `LifeHub/03_systems` reusable methods and continuity systems
- `LifeHub/04_assets` SOPs/templates/checklists
- `LifeHub/05_specs` requirements and behavior contracts
- `LifeHub/06_apps` shared/cross-project implementation
- `LifeHub/07_outputs` final reports and operator logs
- `LifeHub/08_admin` governance and navigation authority

## Startup checklist (every session)
1. Confirm workdir and git branch.
2. Confirm target domain and environment (production vs preview).
3. Load `LifeHub/08_admin/03_operator/context_runtime/TIER_A_CORE.md`.
4. Route with `LifeHub/08_admin/03_operator/context_runtime/CONTEXT_DIRECTORY.index.json`.
5. Load only the minimum route-selected Tier-C or governance files.
6. Escalate to Tier-B, navigation, active state, system state, logs, lessons, or skills only when triggered.

## Common task -> destination routing
| Task type | Primary surface |
|---|---|
| New capture/intake | `LifeHub/01_inbox` |
| Active project execution | `LifeHub/02_projects` |
| Reusable method/standard | `LifeHub/03_systems` |
| SOP/template/checklist | `LifeHub/04_assets` |
| Requirement/spec contract | `LifeHub/05_specs` |
| Shared app implementation | `LifeHub/06_apps` |
| Final report/export/log | `LifeHub/07_outputs` |
| Governance/routing/structure | `LifeHub/08_admin` |

## Change-control rule
Any change affecting behavior, structure, ownership, runtime, monitoring, or deployment must update relevant authoritative docs in the same change set.

## Continuity-guard filename resilience rule
When governance files are renamed for neutrality or clarity, update continuity/onboarding guards in the same change set.

Guard behavior standard:
1. Prefer the current canonical filename first.
2. Keep prior-name compatibility fallback only as a non-authoritative backup.
3. Add pattern fallback for future variants when appropriate (for example `*_REPO_OPERATING_CONTRACT.md`).
4. Never keep a legacy filename as a hard requirement after a canonical rename.

Validation standard:
- Re-run guard scripts after rename changes and require clean exit before calling migration complete.
- Scan for stale hard-coded references and leave only intentional compatibility fallbacks.

## Automation rule
All LifeHub-related cron jobs must pin `workdir` to the intended clone path.

## Periodic consistency check
Run lightweight drift checks weekly and after major infra/runtime changes.
Reference: `HERMES_WEEKLY_DOC_CONSISTENCY_CHECK.md` (filename retained; rule applies to all AI operators).

## Definition of done
- Task artifacts are written to correct repository surfaces.
- Routing/governance docs remain consistent.
- Applicable validation is tied to the exact candidate head rather than to one execution vendor.
- No important decision is left only in chat.