reply-end-controls/reports/next-phase-implementation-plan.md

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.