GIA/LLM_CODING_STANDARDS.md

LLM Coding Standards (GIA)

This document defines implementation standards for coding LLM agents working in this repository.

1) Repository Context

GIA is a multi-transport communication workspace with these major domains:

• Transport runtime and relay (core/modules/router.py, core/clients/*)
• Shared transport abstraction (core/clients/transport.py)
• Manual compose UX and APIs (core/views/compose.py + templates)
• AI workspace and mitigation operations (core/views/workspace.py)
• OSINT/search UX (core/views/osint.py)
• Core identity/history models (core/models.py)

The stack is containerized and commonly managed via make commands in Makefile.

2) Core Design Principles

• Fix root causes first; avoid papering over with UI-only patches.
• Keep behavior symmetric across signal, whatsapp, xmpp, instagram where protocol permits.
• Centralize shared logic in one place; avoid copy/paste service forks.
• Prefer small reusable helpers over monolithic in-function branching.
• Preserve existing UX unless a task explicitly changes interaction behavior.

3) Runtime / Restart Policy

• If runtime code changes (core/clients/*, router, relay, transport), restart runtime before validating.
• Preferred full stack recycle: make stop && make run.
• Single-service restart is acceptable, but if dependency state is improper, use full recycle.

4) Media Pipeline Rules

• Use one shared attachment prep pipeline (transport layer) for outbound service sends.
• Service adapters should only execute provider-specific API calls after shared prep.
• Preserve MIME type and filename semantics; infer when source metadata is missing.
• Never inject internal /compose/media/blob/... links as relay body text for attachment-only messages.
• Blob links are fallback for web/history continuity, not preferred transport payloads.

5) XMPP Upload/Share Rules

• Preferred config: XMPP_UPLOAD_SERVICE or XMPP_UPLOAD_JID.
• If config absent, use XEP-0363 discovery and normalize discovery to a valid JID.
• Do not pass raw stanza XML where JID is expected.
• Keep one place for upload slot and upload error handling semantics.

6) Transport Symmetry & Performance

• Improvements for one service’s media path should be mirrored for others when applicable.
• Keep performance tuning entry points centralized in shared transport helpers.
• One TODO location per shared bottleneck (e.g. stream-as-completed optimization), not repeated per service.

7) Logging and Diagnostics

• Keep production logs high signal:
  • lifecycle at info
  • warnings/errors for operational failures
  • high-volume traces at debug
• Temporary deep diagnostics must be gated (e.g. WHATSAPP_DEBUG) and removable in one patch.
• Avoid ad-hoc/unprofessional debug strings.

8) Large File Refactoring Policy

When touching large files (especially ~2000+ lines):

• Extract minimal reusable helpers in-place or to shared modules.
• Add short docstrings for shared utility functions.
• Avoid introducing new repeated service-specific branches.

9) Documentation Maintenance Standards

Maintain docs as follows:

• INSTALL.md owns setup/config/restart/troubleshooting.
• README.md owns capability map, operation modes, architecture, and interface workflows.
• Keep README setup instructions short and point to INSTALL first.
• Update both docs when operational commands/env requirements change.
• Reflect significant behavior changes (relay semantics, media fallback rules, runtime handoff) in docs immediately.

10) Validation Workflow

• Run targeted checks for changed files.
• Validate runtime behavior with real channel tests after restart.
• For media/relay changes, validate both directions:
  • XMPP -> service
  • service -> XMPP
• Confirm no regression in web compose display semantics.

11) Security & TLS Operational Baseline

• Keep upload endpoints compatible and modern (TLSv1.2 + TLSv1.3).
• Maintain valid certificate chain/stapling where configured.
• Treat TLS/protocol mismatch as infra blocker before application-layer debugging.

12) Current Operational Priorities (Living Guidance)

As of current project state:

• Stabilize live WhatsApp<->XMPP sync behavior.
• Complete media relay parity and offline/backfill consistency.
• Continue reducing transport-specific duplication through shared abstractions.
• Keep compose and workspace indicators clear and non-ambiguous.