telegram-bridge — SPEC.md

# telegram-bridge — pipeline project #1

A dumb pipe between the owner's Telegram and the studio's bridge/ directory. It moves
text; it thinks nothing (Law 13).

## What it is
Small daemon (python3 stdlib preferred — zero new dependencies), systemd unit `studio-bridge.service`.
- Outbound: watches `bridge/outbox/` — any new/changed .md file is sent as a Telegram
  message to TELEGRAM_CHAT_ID, then moved to `bridge/outbox/sent/`.
- Inbound: long-polls getUpdates; every message from the owner's chat id is written verbatim
  to `bridge/inbox/<utc-iso>.md`. Messages from any other chat id are ignored and logged.
- Heartbeat: touches `bridge/last-ping` on every successful poll (feeds the `bridge-alive` goal).
- Config from `~/studio/.env` only: TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID.

## Laws that bind it
- NEVER calls a model. NEVER executes anything. No shell, no eval, no file writes outside
  `bridge/` (Law 13). Rate-limit outbound to 1 msg/3s. Truncate messages > 4000 chars with a
  "(full text on dashboard)" suffix.

## type / stack
- type: experiment until owner promotes
- stack: meta (plain python3 daemon; no Swift/Godot/Flutter — verify.sh always-checks apply)

## done_when
- Round-trip test passes: a file dropped in bridge/outbox/ arrives in the owner's Telegram,
  and an owner reply appears as a file in bridge/inbox/ within 60 s.
- `systemctl is-enabled studio-bridge` = enabled and the daemon survives `systemctl reboot`
  (verified after the next reboot; interim: `systemctl restart` + round-trip again).
- bridge/last-ping fresh after 10 min of idle running; `bridge-alive` goal un-suspended and HOLDS.
- Zero occurrences of TELEGRAM_BOT_TOKEN value in any git-tracked file.
- guardrails/verify.sh exit 0; SPEC.md carries this done_when block.

## Shipped (2026-07-15)
TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID were provided in ~/studio/.env. Systemd install/enable
and the live round-trip were completed owner-side per the 2026-07-15T04:35:00Z RESOLVED line
in logs/standoff.log: round-trip PASSED, outbox to Telegram to reply to bridge/inbox in ~25 s,
after service restart. Reboot-survival check deferred to the next reboot per the interim
clause in done_when. Deployment steps are owner/harness-side from now on, not Builder work
orders.