refactor(tests): migrate functional tests to content-based stubbing and enable unconditionally

CONTRIBUTING.md

@@ -137,3 +137,38 @@ You can run the `make spell` command for this.
 
 `make doublecheck` will run the code formatter, spell checker and unit tests.
 
+
+### Functional tests: moving away from brittle ID hooks
+
+Historically the functional test suite relied on stabber's id based helpers like `stbbr_for_id("prof_presence_1", ...)` to register canned responses that would be sent once Profanity emitted a stanza carrying that exact `id` attribute. This made the tests fragile:
+
+* Changes to stanza id generation (sequence, format) broke tests unexpectedly.
+* Reordering internal requests produced hard-to-debug race conditions when an `id` no longer matched.
+* Parallel additions of new features could shift which stanzas received a given id causing unrelated test failures.
+
+We are incrementally migrating to content based stubbing using direct sends (`stbbr_send`) and query hooks (`stbbr_for_query`). Instead of tying a response to a predicted id we now send the required server stanzas explicitly after initiating actions. Example (see `tests/functionaltests/proftest.c`):
+
+```c
+// Old brittle approach
+stbbr_for_id("prof_presence_1", "<presence id='prof_presence_1' ...>");
+
+// New approach: after authentication, send presence directly
+stbbr_send("<presence from='stabber@localhost/profanity' to='stabber@localhost/profanity'>...caps...</presence>");
+```
+
+Benefits:
+
+* Eliminates dependency on internal id sequencing.
+* Clearer intent inside test code ("send presence now" vs "register hook and hope client triggers it").
+* Simplifies adding new tests—no need to inspect logs for generated ids.
+
+Guidelines when writing new functional tests:
+
+1. Prefer `stbbr_for_query(namespace, xml)` for IQ roster or disco queries where the namespace is stable.
+2. Use `stbbr_send(xml)` for presence, message, and other push style stanzas.
+3. Avoid `stbbr_for_id` unless the protocol flow genuinely requires correlating a specific request/response pair not covered by a namespace query.
+4. Keep assertions tolerant of ordering when possible; rely on `exp_expectl` regex matches rather than hard-coded positions.
+5. If timing flakiness appears, temporarily raise `exp_timeout` around the critical expectation and reset it immediately afterwards.
+
+During the migration it's acceptable for a test file to mix old and new styles; opportunistically refactor brittle sections when touching a test for other reasons.
+