zulip-xmpp/pm/tasks.org

#+title: Task Log
#+updated: [2026-04-14 Tue 13:26]
#+startup: overview

* [X] 0.1.0: Define v0 bridge contract (estimate 1 commit)
Write a one-page spec for the first bridge: one XMPP MUC room <-> one Zulip stream/topic, append-only relay, no edits/reactions/history sync.
keep scope painfully small so transport bugs are obvious.
my preference is for python-based systems.

** Acceptance Criteria
1. A short design note exists under pm/ or docs/
   - includes message flow in both directions
   - identifies system actors: Zulip bot, XMPP client, relay core
2. Explicit non-goals are listed
   - no thread mapping beyond fixed topic
   - no rich sync
   - no presence mirroring
3. First-run assumptions are frozen
   - single room
   - single stream/topic
   - trusted private deployment

** evidence
- commit: 5ad2b6b
- tests: n/a (design note only)
- datetime: [2026-04-14 Tue 14:28]
- artifact: pm/0.1.0-v0-bridge-contract.org

** notes
- This is the boundary-setting task; everything else depends on it.

* [X] 0.1.1: Define canonical relay envelope + anti-loop rules (estimate 1 commit)
Specify the minimal message metadata the bridge must preserve and the exact loop-prevention mechanism.

** Acceptance Criteria
1. Canonical fields are listed
   - origin
   - source message id
   - sender display name
   - target room mapping
   - timestamp
2. Loop prevention rule is explicit
   - bridge stamps outgoing messages
   - bridge ignores messages carrying its own origin marker
3. Failure handling is defined
   - duplicate delivery behavior
   - malformed message behavior
   - reconnect replay policy

- pm note: this is the real core of v0; if this is fuzzy the bridge will thrash.

** evidence
- commit: c72b1d8
- tests: n/a (design note only)
- datetime: [2026-04-14 Tue 14:40]
- artifact: pm/0.1.1-relay-envelope-and-loop-rules.org

** notes
- Prefer boring explicit metadata over clever heuristics.

* [ ] 0.1.2: Survey Zulip bot constraints + auth model (estimate 1 commit)
Confirm what kind of bot/client should be used on the Zulip side and document any constraints that change architecture.

** Acceptance Criteria
1. Zulip integration mode is chosen
   - bot user vs normal user account
   - event queue / polling approach
2. Constraints are captured
   - message formatting limitations
   - topic requirements
   - rate limits / event semantics if relevant
3. Setup checklist is written
   - credentials needed
   - permissions needed
   - minimal stream access needed

- pm note: Zulip quirks may force the shape of the relay more than XMPP will.

** evidence
- commit:
- tests:
- datetime:

** notes
- Keep this empirical; document only constraints that affect v0.

* [X] 0.1.3: Survey XMPP MUC event model + library options (estimate 1 commit)
Pick the first XMPP client library/runtime and document the exact events needed for room relay.

** Acceptance Criteria
1. First implementation language/runtime is chosen
   - likely Python unless a strong reason says otherwise
2. Library candidates are compared briefly
   - connection support
   - MUC message receive/send
   - reconnect behavior
3. Required event subset is documented
   - groupchat message receive
   - send message to MUC
   - ignore join/leave/presence noise

- pm note: avoid solving the Emacs client here; this is just relay transport.

** evidence
- commit:
- tests: n/a (design note only)
- datetime: [2026-04-14 Tue 15:05]
- artifact: pm/0.1.3-xmpp-event-model-and-library-choice.org

** notes
- Goal is “good enough to prototype,” not perfect XMPP abstraction.

* [ ] 0.1.4: Write config schema for single-room bridge (estimate 1 commit)
Design the smallest possible config file/environment contract for running one bridge instance.

** Acceptance Criteria
1. Config fields are listed
   - Zulip site/email/api key
   - Zulip stream/topic
   - XMPP jid/password/muc room/nick
2. One-room mapping is represented simply
   - avoid generalized many-room config unless needed
3. Secrets vs non-secrets are separated
   - env vars or secrets file for credentials
   - checked-in example config for everything else

- pm note: optimize for easy local bring-up, not future elegance.

** evidence
- commit:
- tests:
- datetime:

** notes
- If the config shape feels overdesigned, shrink it again.

* [ ] 0.1.5: Define observability + manual test plan for v0 (estimate 1 commit)
Specify how to tell whether the bridge is healthy before adding Hermes.

** Acceptance Criteria
1. Logs are defined
   - startup config summary without secrets
   - inbound message event
   - outbound relay result
   - duplicate/loop drop reason
2. Manual test cases are listed
   - Zulip -> XMPP happy path
   - XMPP -> Zulip happy path
   - duplicate suppression
   - reconnect after disconnect
3. Success criteria are concrete
   - messages appear once on each side
   - sender attribution preserved enough for humans
   - no infinite echo loops

- pm note: make the bridge boring before attaching Hermes or Retcon.

** evidence
- commit:
- tests:
- datetime:

** notes
- This should become the operator checklist for first deploy.

* [ ] 0.1.6: Sketch Hermes/Retcon follow-on integration points (estimate 1 commit)
Document where Hermes and Retcon could attach after transport is stable, without implementing them yet.

** Acceptance Criteria
1. Hermes interaction modes are listed
   - passive listener
   - command-triggered actor
   - summarizer
2. Retcon integration points are listed
   - append raw inbox
   - synthesize summaries
   - extract durable notes
3. Trust boundaries are explicit
   - what can be written automatically
   - what should remain user-confirmed

- pm note: this keeps the long-term vision visible without contaminating v0 scope.

** evidence
- commit:
- tests:
- datetime:

** notes
- Hermes should arrive after transport and logging are stable.