# 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.