Freeze HA scoring and document reported production failover

README.md

@@ -1,13 +1,13 @@
 # PostgreSQL HA OCF resource agent
 
-A behavior-preserving modular refactor of `ocf:loxthelion:managed-container`.
+A modular PostgreSQL HA implementation of `ocf:loxthelion:managed-container`.
 Pacemaker invokes the agent to manage a rootless systemd/Quadlet maintenance
 container. PostgreSQL is started and stopped independently with `pg_ctl`.
 
 ## Project layout
 
 - `reference/`: original agent and immutable known-good reference copy.
-- `refactored/`: executable agent and nine sourced shell modules.
+- `refactored/`: executable agent, nine sourced shell modules, and a Python state helper.
 - `tests/`: offline structural and behavioral comparison checks.
 - `cluster-context/` and `runtime-context/`: saved lab configuration and state;
   these snapshots are not live status. Environment credentials are redacted.
@@ -21,21 +21,25 @@ Requires Bash, Python 3, and the OCF shell library (normally
 
 ```bash
 python3 tests/verify_refactor.py
+python3 tests/test_promotion_scores.py
+python3 tests/test_promotion_scheduler.py
+python3 tests/test_disconnected_state.py
+python3 tests/test_promotion_cleanup.py
 sha256sum -c notes/REFACTOR-SHA256SUMS
 ```
 
-The tests compare the refactor against the frozen reference without operating
-the live cluster. Target-node validation and controlled HA transition tests
-remain outstanding. Existing function names and recovery configuration blocks
-are retained in this initial modular baseline.
+The tests preserve the original 29 lifecycle function bodies and exercise the
+added promotion-scoring layer without operating the live cluster. The operator
+has reported successful production SBD fencing, automatic promotion, VIP movement,
+and former-primary rewind/rejoin in a three-node cluster.
 
-Read [the refactor report](notes/REFACTOR-REPORT.md) for installation commands,
-validation results, limitations, and the recommended lab comparison sequence.
-The public entrypoint remains
-`/usr/lib/ocf/resource.d/loxthelion/managed-container`.
+Read [operations](docs/operations.md), [testing and snapshot provenance](docs/testing.md),
+and [the review findings](docs/review.md). Historical lab snapshots and notes are
+not current production configuration. Keep `target-role=Promoted`, single-primary
+limits, and the VIP's Promoted-role colocation and promotion-before-start ordering.
 
-Keep lab Pacemaker maintenance mode enabled during this work. Do not modify
-the frozen reference or automatically run destructive HA tests.
+The public entrypoint remains `/usr/lib/ocf/resource.d/loxthelion/managed-container`.
+No production changes are part of this documentation freeze.
 
 ## Clone
 
@@ -49,4 +53,12 @@ Gitea Actions builds development RPMs on `main` pushes and pull requests using
 an `ubuntu-latest` runner with a Fedora 43 job container. See
 [packaging instructions](packaging/README.md) for local builds and artifacts.
 [License provenance remains pending](packaging/PROVENANCE.md); release publishing
-and deployment are not configured.
+and automated deployment are not configured.
+
+## Promotion scoring
+
+Scores are 1000 for a healthy primary, 100 for a strictly verified streaming
+standby, 50 for a recently verified eligible disconnected standby, and -INFINITY
+otherwise. See [the scoring design](notes/DISCONNECTED-STANDBY.md) for identity,
+local state ownership, the 300-second default freshness policy and limitations.
+Fencing remains mandatory; scores do not authorize unfenced manual promotion.