Merge pull request 'fix: Hardcoded TWAP/cooldown values not documented (#825)' (#839) from fix/issue-825 into master

docs/ARCHITECTURE.md

@@ -50,6 +50,10 @@ All managed by LiquidityManager via ThreePositionStrategy abstract:
 
 **Recenter** = atomic repositioning of all three positions. Triggered by anyone, automated by txnBot.
 
+**Recenter constraints** (enforced on-chain):
+- **60-second cooldown**: `MIN_RECENTER_INTERVAL = 60` (`LiquidityManager.sol:61`). A second recenter cannot succeed until at least 60 seconds have elapsed since the last one.
+- **300-second TWAP window**: `PRICE_STABILITY_INTERVAL = 300` (`PriceOracle.sol:14`). `recenter()` validates the current tick against a 5-minute TWAP average (±`MAX_TICK_DEVIATION = 50` ticks). The pool must have at least 300 seconds of observation history; a fallback to a 60 000-second window is used if recent data are unavailable.
+
 ## Optimizer Parameters
 
 `getLiquidityParams()` returns 4 values:

docs/PRODUCT-TRUTH.md

@@ -84,6 +84,8 @@ The three-position structure creates **asymmetric slippage** — buys push the p
 - The optimizer adjusts position parameters based on sentiment
 - "Recenter" = atomic repositioning of all liquidity in one transaction
 - Anyone can trigger a recenter; the protocol bot does it automatically
+- Recenter has a **60-second cooldown** (`MIN_RECENTER_INTERVAL = 60` in `LiquidityManager.sol`) — successive recenters are rate-limited on-chain
+- Recenter requires **300 seconds of TWAP oracle history** (`PRICE_STABILITY_INTERVAL = 300` in `PriceOracle.sol`) and validates the current tick is within ±50 ticks of the 5-minute average before proceeding
 - The three positions together create asymmetric slippage — buys have more price impact upward than sells have downward
 - With normal trading activity, this structural asymmetry accumulates ETH, raising the floor over time
 

scripts/harb-evaluator/red-team-program.md

@@ -232,6 +232,7 @@ python3 -c "b={{LM_ETH_BEFORE}}; a=int('$TOTAL'); d=b-a; print(f'Delta: {d} wei
 
 ### Advance time (REQUIRED before each recenter call)
 recenter() has a 60-second cooldown AND requires 300s of TWAP oracle history.
+<!-- Source constants: MIN_RECENTER_INTERVAL = 60 (LiquidityManager.sol), PRICE_STABILITY_INTERVAL = 300 (PriceOracle.sol) -->
 You MUST advance time before calling recenter:
 ```bash
 /home/debian/.foundry/bin/cast rpc evm_increaseTime 600 --rpc-url http://localhost:8545