docs(02-03): record D-16 deploy-gate APPROVAL + finalize SUMMARY

- User verdict verbatim in 02-03-APPROVAL.md: "it works! Menu or / has /help and /privacy! approved!" - Walkthrough checks a-e all green; reply-language D-05 behavior confirmed (no force-ms) - Four live-debug remediations documented: webhook path, revoked runtime BOT_TOKEN, empty webhook re-arm, menu cache (setChatMenuButton + all_private_chats scope) - SUMMARY finalized: 3/3 tasks, APPROVED walkthrough, self-check PASSED
2026-10-22 19:57:28 +08:00
parent d600d6e71a
commit aedff86542
2 changed files with 111 additions and 12 deletions
@@ -0,0 +1,75 @@
+# 02-03 Deployment-Gate Approval Record (D-16, ONBD-01, PRIV-01)
+
+Recorded: 2026-10-22, after the real-client walkthrough of the plan 02-03 checkpoint
+(`checkpoint:human-verify`, task 3). Committed under `.planning/` gitignore via
+force-add because the approval trail is planning metadata, not shipped code.
+
+**Verdict: APPROVED.** The user verified the deployed bot in the real Telegram
+client and explicitly said "approved" after the final check.
+
+## Deployed target
+
+- Worker (public, not a secret): `https://araharah-bot.araharah-bot.workers.dev`
+- Route: `/telegram/webhook` (secret-token header armed) + `/api/session` gate
+- KV namespace: `chat_sessions` → `59f58a54bc44483e89872b20a005a5eb`
+- Commands: setMyCommands registered in default scope + `language_code:"ms"` scope
+
+## User's response (verbatim)
+
+> "it works! Menu or / has /help and /privacy! approved!"
+
+## Real-client walkthrough results (checks a–e from 02-03-PLAN.md)
+
+| Check | Expected | Observed | Result |
+|-------|----------|----------|--------|
+| a. `/start` | one clinical sentence, no buttons | one sentence, text-only, no reply/inline keyboard | ✓ |
+| b. menu button + `/` autocomplete | exactly `/help` and `/privacy` | both surfaces show exactly those two commands | ✓ |
+| c. `/privacy` | stored-facts block (user id, chat id, language, ~15 min) + never-block (location, routes, history, profile) | both blocks presented as written | ✓ |
+| d. `/mula` | behaves exactly like `/start`; reply language follows the app's `language_code` (D-05) | alias routed to the same handler; user's app is English → English reply is correct behavior (user did not request forcing ms) | ✓ |
+| e. gibberish `/xyz` | no crash, no menu drift | silent, no error, menu unchanged | ✓ |
+
+## Live-debug remediations during the walkthrough (deployment-environment fixes, not code bugs in the tested suites)
+
+1. **Webhook registered without the route path.** First `setWebhook` armed the
+   bare workers.dev origin; Telegram answered ok but updates landed on `/` →
+   404, silent drop. Remedy: re-registered with `url` =
+   `https://araharah-bot.araharah-bot.workers.dev/telegram/webhook` via
+   `node scripts/set-webhook.mjs`. `set-webhook.mjs` was then hardened
+   (same commit as this file) to auto-append `/telegram/webhook` when the
+   configured URL has no path, preventing recurrence.
+2. **Worker runtime secret held a revoked bot token.** `wrangler secrets` had a
+   stale `BOT_TOKEN`; webhook updates 401'd inside the Worker (`Error: Empty
+   token!` / token validation failure surfaced via `wrangler tail`).
+   Remedy: `npx wrangler secret put BOT_TOKEN` re-run from `bot/` with the
+   value from `.dev.vars`; verified via `wrangler secret list` and live
+   `/start` delivery.
+3. **Empty webhook + pending update queue.** After the URL fix the queue was
+   still draining to nothing; re-armed by re-running `setWebhook` and confirming
+   `getWebhookInfo` (pending_update_count → 0, url/secret header correct).
+4. **Menu/or-`/`-autocomplete cache.** The menu initially showed nothing new
+   because Telegram's client caches `setMyCommands`; even correct default-scope
+   results were not picked up. Resolved by explicitly calling
+   `setChatMenuButton` (type `commands`) **and** registering the
+   `all_private_chats` scope; the user then confirmed the menu and the `/`
+   autocomplete both listed exactly `/help` and `/privacy` and approved.
+
+## Evidence commands (run by the orchestrator session, in `bot/`)
+
+- `node scripts/set-webhook.mjs` → `setWebhook ok:true` (post-fix)
+- `curl -s https://api.telegram.org/bot$BOT_TOKEN/getWebhookInfo` → url correct,
+  secret header armed, pending_update_count 0, last_error freed
+- `node scripts/register-commands.mjs` → default + ms scopes `ok:true`
+- `curl -s https://api.telegram.org/bot$BOT_TOKEN/getMyCommands` and
+  `.../getMyCommands?language_code=ms` → exactly `/help`, `/privacy`
+- `curl -s https://api.telegram.org/bot$BOT_TOKEN/getChatMenuButton` → `commands`
+- Live Worker smokes: webhook without secret header → 401; wrong header → 401;
+  `POST /api/session` garbage → 401 `{"error":"malformed"}` (category-only);
+  `GET /api/session` → 405; unknown route → 404; KV key list baseline `[]`
+
+## Post-approval state
+
+- ONBD-01 / PRIV-01 real-client gates observed by the user; PRIV-02 KV
+  spot-check command remains available:
+  `cd bot && npx wrangler kv key list --namespace-id 59f58a54bc44483e89872b20a005a5eb`
+  (only `session:*`/`chat:*`-shaped TTL keys, gone after ~15 min)
+- No STATE.md / ROADMAP.md changes made by the executor — orchestrator-owned.