150 lines
5.0 KiB
Markdown
150 lines
5.0 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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.`
|