cold_display_guard/docs/superpowers/plans/2026-06-09-webhook-case-management-implementation.md

Webhook Case Management Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Build local case management plus outbound/inbound webhook support on top of the existing runtime batch-event flow.

Architecture: Keep BatchEngine as the factual event source, then add a separate case-state module that consumes selected events and persists case snapshots. Add a webhook delivery module for both batch events and case events, expose management APIs for case listing and handling, and render the resulting case workflow in the existing management console without mixing facts and workflow state.

Tech Stack: Python 3.12 via pyenv, Python standard library HTTP/JSON/TOML stack, JSONL files, unittest, Vite + vanilla JavaScript, Node test runner.

---

File Map

• Create: src/cold_display_guard/cases.py
• Create: src/cold_display_guard/webhooks.py
• Modify: src/cold_display_guard/config.py
• Modify: src/cold_display_guard/main.py
• Modify: src/cold_display_guard/manage_api.py
• Modify: web/src/main.js
• Modify: web/src/zone-state.js
• Create: tests/test_cases.py
• Create: tests/test_webhooks.py
• Modify: tests/test_manage_api.py
• Modify: tests/test_main.py
• Modify: web/test/zone-state.test.js

Task 1: Backend Case State Layer

Files:

• Create: src/cold_display_guard/cases.py

• Create: tests/test_cases.py

• Modify: src/cold_display_guard/main.py

• Modify: tests/test_main.py

• Write failing tests for case creation, case escalation, manual/callback/auto close, and restore behavior in tests/test_cases.py.

• Run: eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_cases.py -v Expected: failing assertions or import errors for missing case helpers.

• Implement minimal case dataclasses, JSONL load/save helpers, event-to-case transitions, and restore logic in src/cold_display_guard/cases.py.

• Wire runtime event processing in src/cold_display_guard/main.py so emitted batch events produce persisted case snapshots.

• Run:

  • eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_cases.py -v
  • eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_main.py -v Expected: PASS.

Task 2: Webhook Configuration And Delivery

Files:

• Create: src/cold_display_guard/webhooks.py

• Create: tests/test_webhooks.py

• Modify: src/cold_display_guard/config.py

• Modify: src/cold_display_guard/main.py

• Write failing tests for webhook config parsing, batch event payload delivery, case event payload delivery, and delivery-failure logging in tests/test_webhooks.py.

• Run: eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_webhooks.py -v Expected: FAIL because webhook helpers/config support do not exist yet.

• Implement webhook settings parsing/saving in src/cold_display_guard/config.py and synchronous delivery plus audit logging in src/cold_display_guard/webhooks.py.

• Integrate webhook sending into src/cold_display_guard/main.py after local event and case persistence.

• Run:

  • eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_webhooks.py -v
  • eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_config.py -v Expected: PASS.

Task 3: Management API For Cases And Callback Handling

Files:

• Modify: src/cold_display_guard/manage_api.py

• Modify: tests/test_manage_api.py

• Modify: src/cold_display_guard/config.py

• Write failing API tests for /api/manage/cases, /api/manage/cases/summary, /api/manage/cases/{case_id}/handle, and /api/manage/webhooks/case-update in tests/test_manage_api.py.

• Run: eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_manage_api.py -v Expected: FAIL because the new endpoints and case summary behavior are missing.

• Implement case listing, case summary, manual handle, and token-protected callback handling in src/cold_display_guard/manage_api.py.

• Ensure config payloads expose webhook settings and case/log sink paths without leaking secrets unnecessarily.

• Run: eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_manage_api.py -v Expected: PASS.

Task 4: Frontend Case Management UI

Files:

• Modify: web/src/main.js

• Modify: web/src/zone-state.js

• Modify: web/test/zone-state.test.js

• Write failing frontend tests for case summary mapping, case table rendering helpers, event/case separation, and manual handle request shaping in web/test/zone-state.test.js.

• Run: node --test web/test/zone-state.test.js Expected: FAIL because case helpers and UI state handling do not exist yet.

• Implement frontend model helpers and UI rendering for case summaries, case rows, and manual handle actions while preserving the existing runtime event table semantics.

• Run:

  • node --test web/test/zone-state.test.js
  • cd web && pnpm build Expected: PASS.

Task 5: Full Verification And Documentation Alignment

Files:

• Modify: README_zh.md

• Modify: tasks/todo.md

• Update documentation for new webhook config, case logs, and management endpoints if implementation changed the documented surface area.

• Run targeted verification:

  • eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_cases.py -v
  • eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_webhooks.py -v
  • eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest tests/test_manage_api.py -v
  • node --test web/test/zone-state.test.js Expected: PASS.

• Run full verification:

  • eval "$(/opt/homebrew/bin/pyenv init -)" && PYTHONPATH=src python -m unittest discover -s tests -v
  • cd web && pnpm build Expected: PASS.

• Record final verification outcomes and any environmental caveats in tasks/todo.md.