AI-Development-Server/docs/OPERATING-MODEL.md

Operating Model

This document defines how Nick, ChatGPT, and Codex work together on Atlas.

Roles

• Nick owns architecture approval, operational judgement, production access decisions, and commit approval.
• ChatGPT supports planning, review, documentation, and implementation guidance.
• Codex runs on Atlas to inspect the repository, make approved changes, run validation, and report diffs.

Git as Source of Truth

Git is the source of truth for repository-managed infrastructure and operational intent.

• Infrastructure documentation belongs in this repository.
• Installation scripts must be version-controlled.
• Configuration templates must be version-controlled.
• Manual changes should be recorded and converted to automation where practical.
• Live secrets and generated artefacts must not be committed.

Documentation-First Changes

Substantial changes should begin with documentation:

1. Define the problem or objective.
2. Record relevant assumptions and unknowns.
3. Update standards, architecture, runbooks, or ADRs as needed.
4. Implement scripts or templates.
5. Validate the result.
6. Review the diff before commit.

Codex Planning Before Implementation

Codex must inspect the repository and produce a plan before making architecture-level or broad repository changes.

Implementation should start only after Nick approves the plan, unless the request is a narrow mechanical change that clearly does not affect architecture or operations.

Human Approval of Architecture

Architecture decisions require human approval. Use ADRs for decisions that affect:

• Infrastructure management approach.
• Service topology.
• Storage layout.
• Deployment model.
• Backup and recovery model.
• Security boundaries.
• Tooling choices with long-term maintenance impact.

Commit Control

Codex must not commit unless explicitly instructed.

Before commit:

• Review git status.
• Review the full relevant diff.
• Run validation appropriate to the change.
• Confirm no secrets are present.
• Ensure documentation and implementation agree.

Branching Expectations

Default branch:

• main

Branching model:

• TODO: Confirm during the relevant implementation phase.

Until a fuller branching model exists, keep work small, reviewable, and easy to revert.

Diff Review

Every change should be reviewed with git diff before commit.

Review should check:

• Behavioural intent.
• File paths.
• Secrets exposure.
• Inconsistent terminology.
• Broken Markdown links.
• Missing validation.
• Unintended generated files.

Testing Before Commit

Run the strongest practical validation before commit.

For documentation-only changes, validation should include:

• Repository tree inspection.
• Markdown link checks where practical.
• Search for accidental secrets.
• Search for inconsistent server names, IP addresses, and mount paths.
• git diff --check.

For scripts and service changes, validation should also include syntax checks, dry runs where available, and smoke tests.

Phase 2A adds two read-only host checks that should be used before later installation phases:

scripts/system/discover-system.sh
scripts/system/validate-host.sh

Generated logs and reports should remain outside the repository unless a sanitised snapshot is deliberately reviewed and committed.

Rollback Expectations

• Prefer changes that can be reversed through Git and idempotent scripts.
• Document rollback steps for service-affecting changes.
• Preserve previous configuration where practical before replacing live files.
• Remember that Git rollback does not automatically undo external system state.

Handling of Secrets

• Do not commit secrets.
• Do not print secrets in logs or command output.
• Do not copy Codex authentication material into the repository.
• Use templates, examples, and documented environment variable names.
• Store live secrets outside this repository.
• Rotate credentials after suspected exposure.

Secret storage mechanism is TODO: Confirm during the relevant implementation phase.

Handling of Production Access

Production access must be deliberate and documented.

• Do not assume development and production permissions are the same.
• Do not embed production credentials in scripts.
• Do not run production-impacting commands without explicit approval.
• Record deployment and rollback expectations before automating production changes.

Production access model is TODO: Confirm during the relevant implementation phase.

Development and Production Responsibilities

Atlas is currently documented as a development server. Future production responsibilities must be explicitly approved before they are added.

Expected separation:

• Development: source work, automation development, local validation, builds, and staging-like testing.
• Production: live application availability, production data protection, externally exposed endpoints, customer-impacting deployments, and incident response.

Whether Atlas will host production workloads is TODO: Confirm during the relevant implementation phase.