feat(telegram): digest → Notion 파이프라인 통합

AGENTS.md

@@ -84,4 +84,9 @@
 | OMC         | Claude + Gemini 듀얼 | 대규모 작업 보조    |
 | GSD quick   | 원자적 단발 패치     | 유지보수            |
 
-<!-- Last Updated: 2026-05-21 -->
+## Commit discipline
+
+- After completing implementation or verification work, create a git commit for the completed scope unless the user explicitly says not to commit.
+- Keep commits scoped to the task and do not include unrelated worktree changes.
+
+<!-- Last Updated: 2026-05-28 -->

docs/agent/telegram-ingest.md

@@ -0,0 +1,99 @@
+---
+title: Telegram ingest
+owner: human
+status: approved
+updated: 2026-05-28
+tags: [agent, telegram, ops]
+---
+
+# Telegram ingest
+
+`packages/web` has a local Telegram ingest lane for `getUpdates` polling. It can replay stored raw updates into Telegram Digest previews and can run a guarded Notion write pilot for exactly one selected digest.
+
+## Commands
+
+Run from `packages/web`:
+
+```bash
+bun run telegram:ingest
+bun run telegram:replay
+bun run telegram:replay --json
+bun run telegram:digest:write --json --limit 1
+```
+
+## Environment
+
+- `TELEGRAM_BOT_TOKEN`: Bot API token.
+- `TELEGRAM_BOT_TOKEN_SECRET_REF`: Optional env var name that contains the token. Defaults to `TELEGRAM_BOT_TOKEN`.
+- `TELEGRAM_WEBHOOK_SECRET`: Secret token expected in Telegram's `X-Telegram-Bot-Api-Secret-Token` webhook header.
+- `TELEGRAM_WEBHOOK_SECRET_REF`: Optional env var name that contains the webhook secret. Defaults to `TELEGRAM_WEBHOOK_SECRET`.
+- `TELEGRAM_CHAT_ID`: Optional chat filter for printed digest candidates.
+- `TELEGRAM_INGEST_DIR`: Optional local store directory. Defaults to `.logs/telegram`.
+- `TELEGRAM_RAW_STORE_PATH`: Optional replay input path. Defaults to `${TELEGRAM_INGEST_DIR}/raw-updates.jsonl`.
+- `TELEGRAM_GETUPDATES_LIMIT`: Optional poll limit. Defaults to `100`.
+- `TELEGRAM_GETUPDATES_TIMEOUT`: Optional Bot API long-poll timeout. Defaults to `0`.
+- `NOTION_TELEGRAM_DIGEST_DATA_SOURCE_ID`: Required for `telegram:digest:write --commit`. Points to the dedicated Telegram Digest database, not the Meeting Summary database.
+- `TELEGRAM_DIGEST_WRITE_CONFIRM`: Must be `1` before `telegram:digest:write --commit` creates Notion rows.
+
+## Local store contract
+
+Raw updates are appended as JSONL envelopes:
+
+```json
+{ "fetchedAt": "2026-05-07T12:00:00.000Z", "update": { "update_id": 10 } }
+```
+
+Offset state is stored separately:
+
+```json
+{
+  "nextOffset": 12
+}
+```
+
+The next offset is `max(update_id) + 1`. Empty polls do not rewrite the offset.
+
+## Output contract
+
+The ingest flow returns:
+
+- raw update count
+- normalized text messages
+- topic digest candidates grouped by chat and `message_thread_id`
+
+Digest candidates use the dedicated Telegram Digest payload shape. `telegram:replay --json` prints the exact candidate payloads without writing.
+
+`telegram:digest:write` defaults to dry-run mode. It only writes when all of these are true:
+
+- `--commit` is present.
+- `TELEGRAM_DIGEST_WRITE_CONFIRM=1` is set.
+- candidate filters select exactly one digest.
+
+The Notion write path checks the Telegram Digest data source for an existing `Trace ID` before creating a row, so repeated runs with the same trace do not create duplicates. Phase 1 writes only a Telegram Digest row; it does not create Meeting Summary or Action Item rows. Candidate task text is stored on the digest row as `Action Item Candidate`.
+
+## Webhook front door
+
+`POST /api/telegram/webhook` validates Telegram's secret token header before reading the payload. Malformed update payloads return `400` and are not stored. Supported `message` and `channel_post` updates return `202` with a stable event id shaped as `telegram:<chat_id>:<message_id>`.
+
+Unsupported update types are acknowledged with `200` and `accepted: false` so Telegram does not keep retrying non-actionable membership or service updates.
+
+When registering the webhook with Telegram, restrict `allowed_updates` to:
+
+```json
+["message", "channel_post"]
+```
+
+The app-side payload builder uses `drop_pending_updates: false` by default so registration does not silently discard unprocessed updates.
+
+Accepted updates are upserted into `telegram_raw_events` using `event_id` as the conflict key before the route returns `202`. The expected row contract is:
+
+- `event_id`
+- `source`
+- `update_id`
+- `update_kind`
+- `trace_id`
+- `received_at`
+- `payload`
+- `status`
+
+Creating or migrating this table remains an infra task and should be handled separately with a human checkpoint.