# 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-07-13

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

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

## 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.
- No important decision is left only in chat.