diff --git a/deploy/repositories/world-at-ruin.yaml b/deploy/repositories/world-at-ruin.yaml
index 0d4d63e..8db5cbe 100644
--- a/deploy/repositories/world-at-ruin.yaml
+++ b/deploy/repositories/world-at-ruin.yaml
@@ -5,12 +5,28 @@ metadata:
   annotations:
     crossplane.io/external-name: world-at-ruin
 spec:
-  # Observe-only for now: adopts the imperatively bootstrapped repo (org
-  # custom-property requirement — see the repo-creation bootstrap pattern)
-  # without writing to it; the shared merge-policy patch would otherwise apply
-  # before the observed state is reviewed. Promote to the full set except
-  # Delete (and pin visibility/description as authoritative) once Synced/Ready
-  # shows the observed state, per the two-stage flow in kustomization.yaml.
+  # Observe-only: adopts the imperatively bootstrapped repo (org custom-property
+  # requirement — see the repo-creation bootstrap pattern) and mirrors live state
+  # into status.atProvider without writing to it.
+  #
+  # Synced/Ready already reports the observed state, so the two-stage flow's
+  # review precondition is met — but promotion is blocked on the provider, not on
+  # review. The shared patch in kustomization.yaml adds webCommitSignoffRequired
+  # to every Repository, and provider-upjet-github v0.19.1 (the latest release,
+  # embedding terraform-provider-github v6.6.0) sends that field on every update
+  # PATCH. GitHub rejects such a PATCH while the organization enforces signoff,
+  # even when the requested value is true —
+  # integrations/terraform-provider-github#2077. Promoting to Update would
+  # therefore not apply this repository's merge policy; it would leave a failed
+  # asynchronous update, the state platform-tenant-template already carries and
+  # that tests/repository-update-policy.sh pins against.
+  #
+  # Live allowMergeCommit and allowRebaseMerge are true against a declared false,
+  # so the drift check reports this repository. Correcting that divergence needs a
+  # repository settings change and is tracked in #188. Promote to the full set
+  # except Delete (pinning visibility/description as authoritative) once a
+  # provider-upjet-github release embeds terraform-provider-github v6.12.0 or
+  # later.
   managementPolicies:
     - Observe
   forProvider: