docs: add next-phase implementation plan / 新增下一階段實作計畫

reports/next-phase-implementation-plan.md

@@ -0,0 +1,171 @@
+# reply-end-controls - Next Phase Implementation Plan
+
+## Goal
+
+Turn the current Telegram + OpenClaw PoC from a working patch set into a clean, maintainable implementation.
+
+The PoC has already proven that the core interaction works:
+
+- buttons can be attached to assistant replies
+- callback clicks can be received
+- callback state can be persisted
+- later turns can change behavior based on that state
+
+The next phase is therefore not about feasibility. It is about productizing the implementation.
+
+## Current technical debt
+
+The current PoC depends on direct patching inside the `openclawtest` runtime.
+
+This is useful for proof, but not acceptable as the long-term implementation model.
+
+Main debt items:
+
+1. direct runtime patching inside OpenClaw distribution files
+2. callback handling mixed into Telegram bot internals
+3. state persistence implemented as a local file patch rather than a proper integration surface
+4. stop behavior implemented as an injected text rule rather than a first-class runtime policy hook
+5. no clean install/update/uninstall path
+
+## Target end-state
+
+The feature should become a clean integration layer with clear boundaries:
+
+### A. Core layer
+
+Reusable logic independent of Telegram specifics:
+
+- reply-end state model
+- callback contract
+- continuation policy rules
+- state read/write helpers
+
+### B. Telegram integration layer
+
+Telegram-specific logic only:
+
+- inline keyboard rendering
+- callback payload parsing
+- message button updates
+- Telegram acknowledgement behavior
+
+### C. OpenClaw adapter layer
+
+OpenClaw-specific logic only:
+
+- where reply-end buttons are attached to outbound assistant replies
+- where callback events enter the runtime
+- where conversation/session state is stored
+- where stop/continue policy is read before later turns
+
+## Recommended implementation path
+
+### Milestone 1 - replace direct runtime patching with a maintained adapter patch set
+
+Objective:
+
+- move from ad hoc manual runtime edits to a repeatable patch or extension workflow
+
+Done when:
+
+- all current PoC logic is reproducible from project files
+- updating `openclawtest` no longer depends on hand-editing runtime code
+
+### Milestone 2 - clean state integration
+
+Objective:
+
+- replace the ad hoc `reply-end-controls.json` persistence with a cleaner state management contract
+
+Possible options:
+
+- session-scoped OpenClaw state
+- conversation-scoped OpenClaw state
+- dedicated small state file managed through a clear adapter API
+
+Done when:
+
+- state reads/writes are explicit and documented
+- callback state is not hidden inside fragile inline patch logic
+
+### Milestone 3 - clean behavior policy hook
+
+Objective:
+
+- replace raw text injection for stop behavior with a clearer policy integration point
+
+Done when:
+
+- later-turn behavior change is explicit in adapter logic
+- it does not depend on vague natural-language injection alone
+
+### Milestone 4 - repeatable verification flow
+
+Objective:
+
+- convert the PoC verification steps into a clean acceptance flow
+
+Done when:
+
+- button rendering can be verified
+- callback receipt can be verified
+- state persistence can be verified
+- stop behavior can be verified
+
+## Suggested directory-level deliverables
+
+### In this repo
+
+- `core/` finalized state/policy contract
+- `telegram/` finalized button/callback contract
+- `adapters/openclaw.md` expanded into real implementation notes
+- `reports/` containing implementation decisions and validation results
+
+### In integration work
+
+- a reproducible OpenClaw patch set or integration package
+- an install/apply script
+- a verify script
+- a rollback script
+
+## Design constraints
+
+### Constraint 1
+
+Do not mix this feature into the governance project.
+
+### Constraint 2
+
+Do not expand scope to other channels yet.
+
+### Constraint 3
+
+Do not rebuild the full conversation system.
+
+The feature only needs to:
+
+- append reply-end controls
+- capture user intent
+- influence follow-up behavior
+
+## Recommended next coding task
+
+If implementation work continues immediately, the next best task is:
+
+### Task
+
+Extract the current Telegram/OpenClaw PoC changes into a documented, reproducible patch set.
+
+Why this first:
+
+- it removes the biggest maintenance risk
+- it makes later refactors safer
+- it avoids losing the working PoC in future runtime upgrades
+
+## Final note
+
+The project should not go back to pure brainstorming.
+
+The PoC is already real.
+
+The next phase is about turning that real PoC into a maintainable implementation path.