docs(17-04): complete subscribe/unsubscribe + notification dispatcher plan

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.planning/REQUIREMENTS.md

@@ -236,15 +236,15 @@ Requirements for initial release. Each maps to roadmap phases.
 - [ ] **TELE-02**: /verify command — key verification
 - [ ] **TELE-03**: /recon command — dork execution
 - [ ] **TELE-04**: /status, /stats, /providers, /help commands
-- [ ] **TELE-05**: /subscribe and /unsubscribe for auto-notifications
+- [x] **TELE-05**: /subscribe and /unsubscribe for auto-notifications
 - [ ] **TELE-06**: /key <id> command — full key detail in private chat
-- [ ] **TELE-07**: Auto-notification on new key findings
+- [x] **TELE-07**: Auto-notification on new key findings
 
 ### Scheduled Scanning
 
 - [x] **SCHED-01**: Cron-based recurring scan scheduling
 - [ ] **SCHED-02**: keyhunter schedule add/list/remove commands
-- [ ] **SCHED-03**: Auto-notify on scheduled scan completion
+- [x] **SCHED-03**: Auto-notify on scheduled scan completion
 
 ## v2 Requirements
 

.planning/ROADMAP.md

@@ -342,10 +342,10 @@ Plans:
 **Plans**: 5 plans
 
 Plans:
-- [ ] 17-01-PLAN.md — Bot package skeleton: telego dependency, Bot struct, long polling, auth middleware
+- [x] 17-01-PLAN.md — Bot package skeleton: telego dependency, Bot struct, long polling, auth middleware
-- [ ] 17-02-PLAN.md — Scheduler package + storage tables: gocron wrapper, subscribers/scheduled_jobs CRUD
+- [x] 17-02-PLAN.md — Scheduler package + storage tables: gocron wrapper, subscribers/scheduled_jobs CRUD
 - [ ] 17-03-PLAN.md — Bot command handlers: /scan, /verify, /recon, /status, /stats, /providers, /help, /key
-- [ ] 17-04-PLAN.md — Subscribe/unsubscribe handlers + notification dispatcher (scheduler→bot bridge)
+- [x] 17-04-PLAN.md — Subscribe/unsubscribe handlers + notification dispatcher (scheduler→bot bridge)
 - [ ] 17-05-PLAN.md — CLI wiring: cmd/serve.go + cmd/schedule.go replacing stubs
 
 ### Phase 18: Web Dashboard
@@ -391,5 +391,5 @@ Phases execute in numeric order: 1 → 2 → 3 → ... → 18
 | 14. OSINT CI/CD Logs, Web Archives & Frontend Leaks | 1/1 | Complete    | 2026-04-06 |
 | 15. OSINT Forums, Collaboration & Log Aggregators | 2/4 | Complete    | 2026-04-06 |
 | 16. OSINT Threat Intel, Mobile, DNS & API Marketplaces | 0/? | Complete    | 2026-04-06 |
-| 17. Telegram Bot & Scheduled Scanning | 0/5 | Not started | - |
+| 17. Telegram Bot & Scheduled Scanning | 3/5 | In Progress|  |
 | 18. Web Dashboard | 0/? | Not started | - |

.planning/STATE.md

@@ -3,14 +3,14 @@ gsd_state_version: 1.0
 milestone: v1.0
 milestone_name: milestone
 status: executing
-stopped_at: Completed 17-01-PLAN.md
+stopped_at: Completed 17-04-PLAN.md
-last_updated: "2026-04-06T14:28:54.411Z"
+last_updated: "2026-04-06T14:34:18.714Z"
 last_activity: 2026-04-06
 progress:
   total_phases: 18
   completed_phases: 14
-  total_plans: 85
+  total_plans: 90
-  completed_plans: 84
+  completed_plans: 86
   percent: 20
 ---
 
@@ -101,6 +101,7 @@ Progress: [██░░░░░░░░] 20%
 | Phase 15 P03 | 4min | 2 tasks | 11 files |
 | Phase 16 P01 | 4min | 2 tasks | 6 files |
 | Phase 17 P01 | 3min | 2 tasks | 4 files |
+| Phase 17 P04 | 3min | 2 tasks | 4 files |
 
 ## Accumulated Context
 
@@ -154,6 +155,7 @@ Recent decisions affecting current work:
 - [Phase 16]: IX uses three-step flow: POST search, GET results, GET file content
 - [Phase 16]: URLhaus tag lookup with payload endpoint fallback
 - [Phase 17]: telego v1.8.0 promoted from indirect to direct; context cancellation for graceful shutdown; rate limit 60s scan/verify/recon, 5s others
+- [Phase 17]: Separated format from send for testable notifications without telego mock
 
 ### Pending Todos
 
@@ -168,6 +170,6 @@ None yet.
 
 ## Session Continuity
 
-Last session: 2026-04-06T14:28:54.406Z
+Last session: 2026-04-06T14:34:18.710Z
-Stopped at: Completed 17-01-PLAN.md
+Stopped at: Completed 17-04-PLAN.md
 Resume file: None

.planning/phases/17-telegram-scheduler/17-04-SUMMARY.md

@@ -0,0 +1,103 @@
+---
+phase: 17-telegram-scheduler
+plan: 04
+subsystem: telegram
+tags: [telego, telegram, notifications, subscribers, scheduler]
+
+requires:
+  - phase: 17-01
+    provides: Bot struct, Config, command dispatch, Start/Stop lifecycle
+  - phase: 17-02
+    provides: subscribers table CRUD (AddSubscriber, RemoveSubscriber, ListSubscribers, IsSubscribed), scheduler JobResult
+
+provides:
+  - /subscribe and /unsubscribe command handlers
+  - NotifyNewFindings dispatcher (scheduler to bot bridge)
+  - NotifyFinding real-time individual finding notification
+  - formatNotification/formatErrorNotification/formatFindingNotification helpers
+
+affects: [17-05, serve-command, scheduled-scanning]
+
+tech-stack:
+  added: []
+  patterns: [separate-format-from-send for testable notification logic, per-subscriber error resilience]
+
+key-files:
+  created:
+    - pkg/bot/subscribe.go
+    - pkg/bot/notify.go
+    - pkg/bot/subscribe_test.go
+  modified:
+    - pkg/bot/bot.go
+
+key-decisions:
+  - "Separated formatting from sending for testability without mocking telego"
+  - "Nil bot field used as test-mode indicator to skip actual SendMessage calls"
+  - "Zero-finding results produce no notification (silent success)"
+
+patterns-established:
+  - "Format+Send separation: formatNotification returns string, NotifyNewFindings iterates subscribers"
+  - "Per-subscriber resilience: log error and continue to next subscriber on send failure"
+
+requirements-completed: [TELE-05, TELE-07, SCHED-03]
+
+duration: 3min
+completed: 2026-04-06
+---
+
+# Phase 17 Plan 04: Subscribe/Unsubscribe + Notification Dispatcher Summary
+
+**/subscribe and /unsubscribe handlers with NotifyNewFindings dispatcher bridging scheduler job completions to Telegram messages for all subscribers**
+
+## Performance
+
+- **Duration:** 3 min
+- **Started:** 2026-04-06T14:30:33Z
+- **Completed:** 2026-04-06T14:33:36Z
+- **Tasks:** 2
+- **Files modified:** 4
+
+## Accomplishments
+- /subscribe checks IsSubscribed before adding, /unsubscribe reports rows affected
+- NotifyNewFindings sends formatted message to all subscribers when scheduled scans find keys
+- NotifyFinding provides real-time per-finding notification with always-masked keys
+- 6 tests covering subscribe DB round-trip, no-subscriber no-op, zero-finding skip, message format validation
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Implement /subscribe, /unsubscribe handlers** - `d671695` (feat)
+2. **Task 2: Notification dispatcher and tests (RED)** - `f7162aa` (test)
+3. **Task 2: Notification dispatcher and tests (GREEN)** - `2643927` (feat)
+
+## Files Created/Modified
+- `pkg/bot/subscribe.go` - /subscribe and /unsubscribe command handlers using storage layer
+- `pkg/bot/notify.go` - NotifyNewFindings, NotifyFinding dispatchers with format helpers
+- `pkg/bot/subscribe_test.go` - 6 tests for subscribe/unsubscribe and notification formatting
+- `pkg/bot/bot.go` - Removed stub implementations replaced by subscribe.go
+
+## Decisions Made
+- Separated formatting from sending: formatNotification/formatErrorNotification/formatFindingNotification return strings, tested independently without telego mock
+- Nil telego.Bot field used as test-mode indicator to skip actual SendMessage calls while still exercising all logic paths
+- Zero-finding scan completions produce no notification (avoids subscriber fatigue)
+- Error results get a separate error notification format
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+- go.sum had merge conflict markers from worktree merge; resolved by removing conflict markers and running go mod tidy
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Notification pipeline complete: scheduler OnComplete -> NotifyNewFindings -> all subscribers
+- Ready for Plan 17-05 (serve command integration wiring bot + scheduler together)
+
+---
+*Phase: 17-telegram-scheduler*
+*Completed: 2026-04-06*