feat(metrics)!: label branch-worker metrics by GitBranch, act on the metrics review, and reconcile the docs

.docs-lint-scope

@@ -24,6 +24,7 @@
 
 README.md
 docs/architecture.md
+docs/interpreting-metrics.md
 docs/configuration.md
 docs/bi-directional-flux.md
 docs/bi-directional-argocd.md

cmd/main.go

@@ -99,7 +99,7 @@ func main() {
 
 	// Initialize metrics
 	setupCtx := ctrl.SetupSignalHandler()
-	_, err := telemetry.InitOTLPExporter(setupCtx)
+	_, err := telemetry.InitPrometheusExporter(setupCtx)
 	fatalIfErr(err, "unable to initialize metrics exporter")
 
 	// TLS/options

docs/TODO.md

@@ -20,7 +20,7 @@ Nothing open. The 0.54.0 release PR's changelog was checked against what ships o
   discard or race an open commit window or pending live edits
   ([render-fidelity.md](design/support-boundary/render-fidelity.md) §6b).
 - [ ] **Watch the held applier**, so a switch-on or a `flux resume` is undone at once instead of
-  within the one-minute `heldClaimSteadyInterval`. Also makes `claimed_resource_reconciled_total`
+  within the one-minute `heldClaimSteadyInterval`. Also makes `apply_claimed_resource_reconciled_total`
   (ask #31) count at the moment of the resume.
   [applier-claim-held-applier-watch.md](design/applier-claim-held-applier-watch.md).
 - [ ] **F3: a Flux fetch is made before the hold is checked**, so a `Kustomization` resumed by hand

docs/UPGRADING.md

@@ -187,8 +187,53 @@ A `WatchRule` or `ClusterWatchRule` no longer reads the GitProvider and no longe
 Deleting a `GitBranch` stops its branch worker after it has pushed or refused every pending write and
 settled every `CommitRequest` it held. It never deletes the branch on the remote.
 
-The metrics keep their `provider_namespace` and `provider_name` labels, which name the `GitProvider`
-of the `GitBranch` holding the branch. Log lines name a branch as `repository@branch`.
+The branch worker's metrics are labeled by the `GitBranch`; see the metrics entry below. Log lines
+name a branch as `repository@branch`.
+
+## Metrics: the branch worker's series name their `GitBranch`, and three apply series are renamed
+
+**Every series a branch worker records carries `gitbranch_namespace` and `gitbranch_name`, and no
+longer carries `branch`.** `provider_namespace` and `provider_name` stay. That is the
+`git_commits_total`, `git_pushes_total`, `git_push_retries_total`, `git_push_duration_seconds`,
+`git_fetches_total`, `git_queue_refusals_total`, `git_commit_failures_total`,
+`git_writes_dropped_total` and `git_materialization_failures_total` counters; the
+`git_queue_depth`, `git_retained_bytes`, `git_retained_writes`, `git_intake_paused`,
+`git_oldest_retained_write_timestamp_seconds` and `git_next_retry_timestamp_seconds` gauges; and
+the apply window and echo series below. Select a branch by its `GitBranch`:
+
+```promql
+# 0.53.0: gitopsreverser_git_pushes_total{provider_namespace="platform", branch="main"}
+gitopsreverser_git_pushes_total{gitbranch_namespace="platform", gitbranch_name="platform-main"}
+```
+
+`git_branch_targets` maps each `GitTarget` to its `GitBranch` (`gitbranch_namespace`,
+`gitbranch_name`) and no longer carries the provider or the branch.
+
+**Three apply series are renamed** so that every apply series starts with `apply_`:
+
+| 0.53.0 | Now |
+| --- | --- |
+| `appliers_held` | `apply_appliers_held` |
+| `stale_snapshots_total` | `apply_stale_snapshots_total` |
+| `claimed_resource_reconciled_total` | `apply_claimed_resource_reconciled_total` |
+
+**Labels that changed elsewhere:**
+
+- `git_resync_failures_total` gains `reason`: `error` and `timeout` are a snapshot that did not
+  land; `refused` and `deferred` are counted too, and lose nothing. Alert on
+  `reason=~"error|timeout"`.
+- `git_fetches_total` no longer has `reason="bootstrap"`, which never emitted.
+- `git_commit_failures_total` and `git_writes_dropped_total` no longer carry `kind`, and
+  `git_commit_windows_total` no longer has `close_reason="atomic_before_apply"`: the atomic write
+  path they described had no producer, and is gone.
+- `attribution_resolution_wait_seconds` carries only `tier` and `event_kind`; the type is on
+  `attribution_resolutions_total`.
+- `apply_requests_total` and `apply_revision_mismatches_total` gain `gitbranch_namespace`,
+  `gitbranch_name`, `provider_namespace`, `provider_name`, `claim_namespace` and `claim_name`;
+  `audit_events_total` gains `audit_route`; `secret_encryptions_total` gains
+  `gittarget_namespace` and `gittarget_name`; `watch_sessions_ended_total`,
+  `watch_replay_duration_seconds` and `watch_event_handling_seconds` gain `source_cluster`. A query
+  that sums over these reads as before.
 
 ## Grants say who may use a provider or a branch; `allowedBranches` is `allowedGitBranches`
 

docs/api-first-publication.md

@@ -467,7 +467,6 @@ provider and branch so different workers do not hide one another's behavior.
 | Same counter, reason `push_failure_probe` | Remote-state lookup after an unclassified push failure |
 | Same counter, reason `recovery` | Attempts to rebuild unsafe retained work or clean a dirty checkout |
 | Same counter, reason `forced_recheck` | Explicit refresh, and the snapshot a resync judges against |
-| Same counter, reason `bootstrap` | Instrumented bootstrap helper; currently called only by tests |
 | `gitopsreverser_git_pushes_total` and `gitopsreverser_git_push_retries_total` | Completed publication cycles and contention retries within them |
 | `gitopsreverser_git_push_duration_seconds` | Time inside a push cycle, including its inline replays |
 | `gitopsreverser_git_queue_depth` and `gitopsreverser_git_queue_refusals_total` | Outstanding work and queue overload |