diff --git a/reports/next-phase-implementation-plan.md b/reports/next-phase-implementation-plan.md new file mode 100644 index 0000000..58e28eb --- /dev/null +++ b/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.