feat: hermes-operator v1.0.0 — plans 1–7 implementation (#1)

## Summary

Implements **all seven plans** to bring `hermes-operator` to v1.0.0
quality. 175 commits delivering CRDs, reconcilers, webhooks, day-2 ops,
release pipeline, conformance suite, and v1 docs/examples.

### Plans landed

| Plan | Scope | Status |
|---|---|---|
| 1 | Kubebuilder v4 scaffold + minimal happy path | ✅ |
| 2 | Hardened defaults, observability, leader election, full feature
surface | ✅ |
| 3 | Gateways, Honcho profile store, web terminal, Tailscale | ✅ |
| 4 | `HermesSelfConfig` SSA controller + validator + GitOps coexistence
| ✅ |
| 5 | Day-2 ops: backup/restore, auto-update with rollback, OpenClaw
migration | ✅ |
| 6 | Distribution: release-please, GoReleaser, Cosign + SBOM, OLM
bundle, conformance suite | ✅ (heavy conformance variants 18/19/20/22
deferred) |
| 7 | v1 polish: api-versioning policy, deprecation policy, condition
catalogue, ROADMAP, README, CHANGELOG, 10 worked examples | ✅ (Grafana
16/17 + release-merge 19-24 still open) |

### Highlights

**API surface (`hermes.agent/v1`):** `HermesInstance` (namespaced),
`HermesSelfConfig` (namespaced), `HermesClusterDefaults` (cluster-scoped
singleton). Full validating/defaulting webhooks via cert-manager.

**Reconcilers:** Main `HermesInstanceReconciler` + four sub-reconcilers
(backup, restore, auto-update, migration) + dedicated
`HermesSelfConfigReconciler`. All finalizer mutations use `r.Patch(ctx,
inst, client.MergeFrom(original))` — never `r.Update` — enforced by
`hack/reconcile-guard.sh` grep check (lesson #437).

**SSA coexistence:** `HermesSelfConfig` writes via field manager
`hermes.agent/selfconfig`; FluxCD writes via `kustomize-controller`;
explicit envtest proves no flap.

**Day-2 ops:** Scheduled + on-delete + pre-update backups (restic to
S3/MinIO/R2); declarative `restoreFrom` with init-container;
OCI-registry-driven `autoUpdate` with channel resolution, pre-update
backup, probe-driven rollback, and `lastFailedTag` suppression; one-shot
OpenClaw migration (sibling PVC or S3 snapshot).

**Distribution pipeline:** `release-please-action` v4 → GoReleaser v2
multi-arch dockers → Cosign keyless OIDC signing of all three image tags
(`vX.Y.Z`, `X.Y`, `latest`) → Syft SPDX-JSON SBOM attest → Helm OCI push
to `ghcr.io/stubbi/charts` → OLM bundle (CSV + CRDs) auto-submitted to
`k8s-operatorhub/community-operators` and
`redhat-openshift-ecosystem/community-operators-prod`. Weekly
`verify-signing.yaml` drift detector opens an `infra-broken` issue if
cosign verification ever fails.

**Conformance:** Ginkgo suite at `test/conformance/` with 10 testdata
fixtures, negative tests for every webhook deny path, idempotency canary
(10-reconcile no-op proving lesson #437), and nightly
`.github/workflows/conformance.yaml` cron. envtest matrix runs k8s
1.28–1.32 on every PR.

**Docs:** `docs/api-versioning.md`, `docs/deprecations.md`,
`docs/conditions.md` (canonical catalogue), `docs/release-process.md`,
`docs/conformance.md`, `docs/supported-versions.md`,
`docs/backup-restore.md`, `docs/autoupdate.md`, `docs/migration.md`,
`docs/security/signing.md`, `docs/api-reference.md`,
`docs/selfconfig.md`. Public `ROADMAP.md`, `CHANGELOG.md` with v1.0.0
entry, README rewritten as v1 landing page.

**Examples (10 worked recipes under `examples/`):** `minimal`,
`full-featured`, `multi-platform`, `honcho`, `auto-update`, `backup-s3`
(MinIO on kind), `migration-from-openclaw` (both source modes),
`gitops-fluxcd`, `cluster-defaults`, plus `examples/README.md` index.

### What's deferred

- **Plan 6 Tasks 18/19/20/22** — upgrade-matrix / GitOps kind /
failure-injection / benchmark conformance jobs are scaffolded as
workflow stubs but the heavy test bodies are deferred. The non-stub
conformance jobs (negative, idempotency) gate PRs.
- **Plan 6 Task 24** — live end-to-end smoke of release pipeline
requires user-provided `RELEASE_PLEASE_TOKEN` PAT and cosign OIDC
permissions.
- **Plan 7 Tasks 16/17** — Grafana dashboard JSON + README still to
land.
- **Plan 7 Tasks 19–24** — release-merge / OperatorHub PR tracking /
launch announce / flip repo public are user-driven post-merge actions.

### Required repo secrets before first release

- `RELEASE_PLEASE_TOKEN` — fine-grained PAT with `contents: write` +
`pull-requests: write`; needed for tag creation + OperatorHub
fork-and-PR. Without it `release-please.yaml` and
`operatorhub-submit.yaml` will fail.
- Cosign keyless signing uses GitHub Actions OIDC — no key material to
store, but the `release.yaml` workflow needs `id-token: write`
permission (already set).

## Test plan

- [ ] Lint workflow green
- [ ] Test workflow green across k8s 1.28–1.32 envtest matrix
- [ ] Reconcile Guard workflow green (no `r.Update` near finalizer
mutations)
- [ ] Helm RBAC Sync + Bundle RBAC Sync workflows green
- [ ] Build workflow green (multi-arch)
- [ ] E2E workflow green (kind + cert-manager + MinIO + helm install)
- [ ] Conformance jobs (negative, idempotency) green; stub jobs may be
skipped
- [ ] Sample manifests under `config/samples/` apply cleanly
- [ ] `examples/` recipes apply on a kind cluster (manual)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: stubbi

.dockerignore

@@ -0,0 +1,3 @@
+# More info: https://docs.docker.com/engine/reference/builder/#dockerignore-file
+# Ignore build and test binaries.
+bin/

.github/ISSUE_TEMPLATE/bug.yaml

@@ -0,0 +1,64 @@
+name: Bug report
+description: Report a defect in hermes-operator
+labels: ["bug", "needs-triage"]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear description of the bug, including any error messages.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What did you expect?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: How to reproduce
+      description: A minimal HermesInstance / HermesSelfConfig manifest + the sequence of commands that triggers the bug.
+      render: yaml
+    validations:
+      required: true
+  - type: input
+    id: operator-version
+    attributes:
+      label: hermes-operator version
+      placeholder: "v0.1.0"
+    validations:
+      required: true
+  - type: input
+    id: kubernetes-version
+    attributes:
+      label: Kubernetes version
+      placeholder: "v1.30.4"
+    validations:
+      required: true
+  - type: dropdown
+    id: install-method
+    attributes:
+      label: Install method
+      options:
+        - Helm chart
+        - OLM bundle
+        - dist/install.yaml (kubectl apply)
+        - Other (please describe in "What happened?")
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant operator logs
+      description: |
+        Output of `kubectl logs -n hermes-system -l control-plane=controller-manager --tail=200`
+      render: shell
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Code of Conduct
+      options:
+        - label: I agree to follow this project's [Code of Conduct](https://github.com/stubbi/hermes-operator/blob/main/CODE_OF_CONDUCT.md).
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Questions
+    url: https://github.com/stubbi/hermes-operator/discussions/categories/q-a
+    about: Ask usage questions in Discussions (Q&A category).
+  - name: Ideas + proposals
+    url: https://github.com/stubbi/hermes-operator/discussions/categories/ideas
+    about: Discuss ideas before opening a formal feature request.
+  - name: Security vulnerabilities
+    url: https://github.com/stubbi/hermes-operator/security/advisories/new
+    about: Report privately via GitHub Security Advisories — do not open a public issue.

.github/ISSUE_TEMPLATE/feature.yaml

@@ -0,0 +1,29 @@
+name: Feature request
+description: Suggest a new capability or improvement
+labels: ["enhancement", "needs-triage"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem are you trying to solve?
+      description: Describe the user-facing problem, not the implementation. Skip if this is a pure DX/quality-of-life improvement.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: How would this look from the user's perspective? Sketch CRD fields, CLI flags, condition reasons, etc.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Code of Conduct
+      options:
+        - label: I agree to follow this project's [Code of Conduct](https://github.com/stubbi/hermes-operator/blob/main/CODE_OF_CONDUCT.md).
+          required: true

.github/dependabot.yml

@@ -0,0 +1,38 @@
+version: 2
+updates:
+  - package-ecosystem: gomod
+    directory: "/"
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 10
+    groups:
+      kubernetes:
+        patterns:
+          - "k8s.io/*"
+          - "sigs.k8s.io/*"
+      otel:
+        patterns:
+          - "go.opentelemetry.io/*"
+    labels:
+      - dependencies
+      - go
+
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+      - github-actions
+
+  - package-ecosystem: docker
+    directory: "/"
+    schedule:
+      interval: weekly
+      day: monday
+    labels:
+      - dependencies
+      - docker

.github/pull_request_template.md

@@ -0,0 +1,17 @@
+## Summary
+
+<!-- 1-3 sentences. What does this change and why? -->
+
+## Test plan
+
+- [ ] Lint passes (`make lint`)
+- [ ] Tests pass (`make test`)
+- [ ] Reconcile-guard passes (`bash hack/reconcile-guard.sh`)
+- [ ] Helm RBAC sync passes (`bash hack/check-helm-rbac.sh`)
+- [ ] For CRD/API changes: `make manifests` + `make generate` regenerated
+- [ ] For RBAC changes: `make sync-bundle-rbac` if the bundle is affected
+- [ ] For behavior changes: added/updated an envtest or e2e test
+
+## Related issues
+
+<!-- Closes #123 / refs #456 -->

.github/workflows/agent-image-smoke.yaml

@@ -0,0 +1,73 @@
+# .github/workflows/agent-image-smoke.yaml
+#
+# Per-PR smoke test: build the agent image on amd64, verify --help exits 0 and
+# entrypoint.sh refuses to start without a config. Does NOT push.
+name: agent-image-smoke
+
+on:
+  pull_request:
+    paths:
+      - 'images/hermes-agent/**'
+      - '.github/workflows/agent-image-smoke.yaml'
+      - 'Makefile'
+
+permissions:
+  contents: read
+
+jobs:
+  smoke:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Guard — skip when uv.lock is absent
+        id: guard
+        run: |
+          if [ ! -f images/hermes-agent/uv.lock ]; then
+            echo "uv.lock not yet committed; skipping smoke."
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Set up Buildx
+        if: steps.guard.outputs.skip != 'true'
+        uses: docker/setup-buildx-action@v3
+
+      - name: Read pinned HERMES_VERSION from uv.lock
+        if: steps.guard.outputs.skip != 'true'
+        id: ver
+        run: |
+          set -eux
+          ver=$(awk '/^name = "hermes-agent"$/{getline; if ($0 ~ /^version =/) {gsub(/[" ]/, "", $3); print $3; exit}}' images/hermes-agent/uv.lock)
+          # uv.lock records the bare package version; tag form has a leading v.
+          echo "tag=v${ver}" >> "$GITHUB_OUTPUT"
+
+      - name: Build image locally
+        if: steps.guard.outputs.skip != 'true'
+        run: |
+          docker buildx build \
+            --platform linux/amd64 \
+            --build-arg HERMES_VERSION=${{ steps.ver.outputs.tag }} \
+            --load \
+            -t hermes-agent:smoke \
+            images/hermes-agent
+
+      - name: Smoke — --help exits 0
+        if: steps.guard.outputs.skip != 'true'
+        run: docker run --rm hermes-agent:smoke hermes-agent --help >/dev/null
+
+      - name: Smoke — entrypoint refuses missing config with EX_CONFIG (78)
+        if: steps.guard.outputs.skip != 'true'
+        run: |
+          set +e
+          docker run --rm --entrypoint /usr/local/bin/hermes-entrypoint hermes-agent:smoke
+          rc=$?
+          if [ "${rc}" != "78" ]; then
+            echo "Expected exit 78 (EX_CONFIG), got ${rc}" >&2
+            exit 1
+          fi
+
+      - name: Smoke — non-root by default
+        if: steps.guard.outputs.skip != 'true'
+        run: |
+          uid=$(docker run --rm --entrypoint id hermes-agent:smoke -u)
+          [ "${uid}" = "1000" ] || { echo "Expected UID 1000, got ${uid}"; exit 1; }

.github/workflows/agent-image.yaml

@@ -0,0 +1,112 @@
+# .github/workflows/agent-image.yaml
+#
+# Builds and publishes ghcr.io/stubbi/hermes-agent for every hermes-agent
+# release in the supported matrix. Triggered:
+#   - Manually via workflow_dispatch (engineer picks the HERMES_VERSION).
+#   - On every push of a tag matching `agent/vX.Y.Z`.
+#
+# Cosign-signed (keyless OIDC) and SBOM via Syft.
+name: agent-image
+
+on:
+  workflow_dispatch:
+    inputs:
+      hermes_version:
+        description: "Upstream hermes-agent release tag (e.g. v0.13.0)"
+        required: true
+        type: string
+  push:
+    tags:
+      - 'agent/v*'
+
+permissions:
+  contents: read
+  packages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Resolve HERMES_VERSION
+        id: ver
+        run: |
+          set -eux
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            v="${{ inputs.hermes_version }}"
+          else
+            v="${GITHUB_REF#refs/tags/agent/}"
+          fi
+          # Strip any leading "v" for the bare package version, keep the tag form too.
+          bare="${v#v}"
+          echo "tag=${v}" >> "$GITHUB_OUTPUT"
+          echo "bare=${bare}" >> "$GITHUB_OUTPUT"
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Verify uv.lock matches the requested HERMES_VERSION
+        run: |
+          set -eux
+          # The lockfile is the source of truth; refuse to ship if the committed lock
+          # disagrees with the requested version.
+          ver=$(awk '/^name = "hermes-agent"$/{getline; if ($0 ~ /^version =/) {gsub(/[" ]/, "", $3); print $3; exit}}' images/hermes-agent/uv.lock)
+          if [ "${ver}" != "${{ steps.ver.outputs.bare }}" ]; then
+            echo "uv.lock pins hermes-agent==${ver} but workflow requested ${{ steps.ver.outputs.bare }}" >&2
+            echo "Run: make agent-image-relock HERMES_VERSION=${{ steps.ver.outputs.tag }} and commit." >&2
+            exit 1
+          fi
+
+      - name: Build and push
+        id: build
+        uses: docker/build-push-action@v5
+        with:
+          context: images/hermes-agent
+          file: images/hermes-agent/Dockerfile
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: |
+            ghcr.io/stubbi/hermes-agent:${{ steps.ver.outputs.tag }}
+            ghcr.io/stubbi/hermes-agent:latest
+          build-args: |
+            HERMES_VERSION=${{ steps.ver.outputs.tag }}
+          provenance: true
+          sbom: true
+
+      - name: Install Cosign
+        uses: sigstore/cosign-installer@v3
+
+      - name: Sign image (keyless OIDC)
+        env:
+          DIGEST: ${{ steps.build.outputs.digest }}
+        run: |
+          cosign sign --yes "ghcr.io/stubbi/hermes-agent@${DIGEST}"
+
+      - name: Install Syft
+        uses: anchore/sbom-action/download-syft@v0
+
+      - name: Generate SBOM
+        run: |
+          syft "ghcr.io/stubbi/hermes-agent:${{ steps.ver.outputs.tag }}" \
+            -o spdx-json=sbom.spdx.json
+
+      - name: Attach SBOM as Cosign attestation
+        env:
+          DIGEST: ${{ steps.build.outputs.digest }}
+        run: |
+          cosign attest --yes \
+            --predicate sbom.spdx.json \
+            --type spdxjson \
+            "ghcr.io/stubbi/hermes-agent@${DIGEST}"

.github/workflows/build.yaml

@@ -0,0 +1,33 @@
+name: Build
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+      # Multi-arch builds for releases happen in release.yaml via GoReleaser
+      # (uses native runners + Go cross-compile, not QEMU). This job is a fast
+      # PR smoke test — single-platform, host-arch.
+      - uses: docker/login-action@v3
+        if: github.event_name == 'push'
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64
+          push: ${{ github.event_name == 'push' }}
+          tags: ghcr.io/stubbi/hermes-operator:dev,ghcr.io/stubbi/hermes-operator:${{ github.sha }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max