5.7 KiB
Task Log
- [X] 0.1.0: Define v0 bridge contract (estimate 1 commit)
- [X] 0.1.1: Define canonical relay envelope + anti-loop rules (estimate 1 commit)
- [ ] 0.1.2: Survey Zulip bot constraints + auth model (estimate 1 commit)
- [X] 0.1.3: Survey XMPP MUC event model + library options (estimate 1 commit)
- [ ] 0.1.4: Write config schema for single-room bridge (estimate 1 commit)
- [ ] 0.1.5: Define observability + manual test plan for v0 (estimate 1 commit)
- [ ] 0.1.6: Sketch Hermes/Retcon follow-on integration points (estimate 1 commit)
[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
-
A short design note exists under pm/ or docs/
- includes message flow in both directions
- identifies system actors: Zulip bot, XMPP client, relay core
-
Explicit non-goals are listed
- no thread mapping beyond fixed topic
- no rich sync
- no presence mirroring
-
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
-
Canonical fields are listed
- origin
- source message id
- sender display name
- target room mapping
- timestamp
-
Loop prevention rule is explicit
- bridge stamps outgoing messages
- bridge ignores messages carrying its own origin marker
-
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
-
Zulip integration mode is chosen
- bot user vs normal user account
- event queue / polling approach
-
Constraints are captured
- message formatting limitations
- topic requirements
- rate limits / event semantics if relevant
-
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
-
First implementation language/runtime is chosen
- likely Python unless a strong reason says otherwise
-
Library candidates are compared briefly
- connection support
- MUC message receive/send
- reconnect behavior
-
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
-
Config fields are listed
- Zulip site/email/api key
- Zulip stream/topic
- XMPP jid/password/muc room/nick
-
One-room mapping is represented simply
- avoid generalized many-room config unless needed
-
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
-
Logs are defined
- startup config summary without secrets
- inbound message event
- outbound relay result
- duplicate/loop drop reason
-
Manual test cases are listed
- Zulip -> XMPP happy path
- XMPP -> Zulip happy path
- duplicate suppression
- reconnect after disconnect
-
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
-
Hermes interaction modes are listed
- passive listener
- command-triggered actor
- summarizer
-
Retcon integration points are listed
- append raw inbox
- synthesize summaries
- extract durable notes
-
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.