# Contributing & Development Workflow

How work is version-controlled for this repository. This complements the governance rules in
[`AGENTS.md`](AGENTS.md) (what agents may/may not change) — this file covers *how changes land in
git*.

## Interim state (now): local git, feature branches → main

There is **no remote git host on this network today**. (The previous `home-network` Gitea instance is
gone from this network; the infrastructure it built still runs but is not reachable here.) So for now:

- **Local git only.** The repository lives on the workstation; there is no push target yet.
- **No work on `main`.** `main` holds only reviewed, completed work. Do **not** commit work-in-
  progress directly to `main`.
- **Every change is a feature branch.** Create `feature/<short-description>` (or `fix/…`, `docs/…`)
  for any unit of work, commit there, then **merge into `main`** when the work is complete and — for
  implementation work — its conformance tests pass ([`agents/definition-of-done.md`](agents/definition-of-done.md)).
- **Merge to `main` = "done".** Keep `main` always in a coherent, mergeable state.

### Branch naming
- `feature/<slug>` — new capability or spec area
- `fix/<slug>` — corrections
- `docs/<slug>` — documentation-only changes
- `chore/<slug>` — tooling/repo housekeeping

### Commit hygiene
- Small, single-responsibility commits; imperative subject lines.
- Reference requirement IDs / ADR numbers / task-board IDs where relevant (they're stable across
  file moves).
- **Never commit plaintext secrets** — secrets are SOPS-encrypted only ([`docs/07-security-and-secrets.md`](docs/07-security-and-secrets.md));
  the [`.gitignore`](.gitignore) guards common leak paths but is not a substitute for care.

## Target state (soon): Gitea-hosted, CI/CD-driven GitOps

The platform will **host its own git**. **Gitea is one of the first services brought online on the
cluster** ([`docs/13-service-catalog.md`](docs/13-service-catalog.md), roadmap Phase 6 is pulled
early — see [`roadmap/phases.md`](roadmap/phases.md)). Once Gitea is up and stable, the workflow
shifts:

1. **Repos move to Gitea** (`gitea.home.keithjackson.dev`). This local repo is pushed up as the
   origin of record.
2. **GitOps source migrates** from local/bootstrap to Gitea: Flux reconciles the cluster from Gitea
   ([`docs/05-gitops-and-delivery.md`](docs/05-gitops-and-delivery.md)).
3. **CI/CD runs in Gitea** (Gitea Actions): the Kyverno L0 policy gate and the trigger for the
   in-cluster Chainsaw conformance Job run as pipelines on push/PR
   ([`docs/14-testing-and-conformance.md`](docs/14-testing-and-conformance.md)); Renovate opens
   update PRs ([`docs/11-automated-updates.md`](docs/11-automated-updates.md)).
4. **Pull requests become the merge gate** into `main`, with CI (policy + conformance) required
   green before merge — the same no-work-in-main rule, now enforced by the platform instead of by
   convention.

### The bootstrapping caveat (self-hosted git is circular)
Gitea runs *on* the cluster that Flux reconciles *from* Gitea — a chicken-and-egg. Handling:
- Bring the cluster up from a **bootstrap source** (this local repo / an out-of-band source), stand
  up Gitea, then **cut Flux's source over to Gitea**.
- Because a cluster loss would take its own git host with it, **Gitea is DR-critical**: its repos are
  backed up **off-cluster** ([`docs/04-storage-and-state.md`](docs/04-storage-and-state.md)), and an
  off-cluster mirror of the platform repo is kept so the platform can always be rebuilt from a source
  that outlives the cluster.

## What does not change
- Specs remain **human-owned and immutable to agents** ([`AGENTS.md` §11](AGENTS.md)) regardless of
  where git is hosted.
- "Done" remains a **green, reproducible conformance test**, not "merged."