flynn/docs/plans/2026-02-16-openclaw-gap-next-steps-3phase.md

# OpenClaw Gap Next Steps — 3-Phase Implementation Plan

**Date:** 2026-02-16  
**Parent analysis:** `docs/plans/2026-02-06-openclaw-feature-gap-analysis.md`  
**Related roadmap:** `docs/plans/2026-02-15-openclaw-gap-roadmap.md`

## Goal

Close the highest-impact remaining OpenClaw parity gaps that still affect day-to-day Flynn operator value, while keeping scope incremental and testable.

## Prioritization Rationale

1. Queue behavior parity improves real-world reliability under bursty chats.
2. Channel reach adds immediate user-facing utility with bounded engineering cost.
3. Protocol/app foundation unlocks companion-node and canvas-class features without committing to full mobile/mac app scope yet.

## Phase 1 — Queue Policy Parity v2 (P1)

### Scope

- Extend current lane queue controls to include:
  - `followup` mode semantics.
  - `steer_backlog` semantics.
  - lane debounce support.
  - overflow summarize behavior.
- Add runtime control surface for queue policy per session.

### File-Level Tasks

- `src/gateway/lane-queue.ts`
  - Add additional queue modes (`followup`, `steer_backlog`).
  - Add debounce handling and summarize-on-overflow strategy.
  - Add typed enqueue options for policy and enqueue metadata.
- `src/gateway/handlers/agent.ts`
  - Resolve new queue mode values from config/session overrides.
  - Add response payloads for summarized drops/interruption notices.
- `src/commands/builtin/index.ts`
  - Add `/queue` command group for inspect/set/reset queue behavior in current session.
- `src/session/manager.ts`
  - Persist per-session queue overrides (`queue.mode`, `queue.debounce_ms`, etc.).
- `src/config/schema.ts`
  - Add new queue keys and validation (`debounce_ms`, summarize settings).
- `src/gateway/handlers/config.ts`
  - Expose queue config fields in runtime config patch API (if applicable).
- `README.md`
  - Document queue modes and `/queue` command usage.
- `docs/api/PROTOCOL.md`
  - Update queue and cancellation behavior sections.

### Test Checklist

- `src/gateway/lane-queue.test.ts`
  - [ ] `followup` behavior under active+pending workloads.
  - [ ] `steer_backlog` replacement behavior across multiple pending entries.
  - [ ] debounce behavior timing and ordering.
  - [ ] summarize overflow behavior and payload integrity.
- `src/gateway/handlers/agent.test.ts`
  - [ ] queue policy resolution for new modes and debounce.
  - [ ] session override precedence over channel/global config.
- `src/commands/builtin/*.test.ts`
  - [ ] `/queue` parse and execution behavior.
- `src/config/schema.test.ts`
  - [ ] new queue schema defaults and validation errors.

### Acceptance Criteria

- Bursty same-session request streams behave deterministically with selected mode.
- Operators can inspect/change queue behavior per session without restart.
- Queue policy behavior is visible in docs and auditable.

## Phase 2 — Channel Reach Expansion (Mattermost First) (P2)

### Scope

- Add first additional high-value missing channel using existing adapter architecture.
- Mattermost is first due to enterprise overlap with existing Slack/Teams patterns.
- Keep LINE/Feishu/Zalo as follow-on adapters after Mattermost stabilizes.

### File-Level Tasks

- `src/channels/mattermost/adapter.ts`
  - Implement channel adapter with connect/disconnect/send/onMessage.
  - Support allowlists and mention gating consistent with other adapters.
- `src/channels/mattermost/index.ts`
  - Export adapter + types.
- `src/channels/index.ts`
  - Register adapter export.
- `src/daemon/channels.ts`
  - Wire config -> adapter construction and registry registration.
- `src/config/schema.ts`
  - Add `mattermost` config block (token/webhook/team/channel constraints).
- `src/gateway/handlers/services.ts`
  - Add services reporting entry for Mattermost.
- `README.md`
  - Add setup section and config example.
- `docs/architecture/CONTRIBUTOR_MAP.md`
  - Update channel map and ownership notes.

### Test Checklist

- `src/channels/mattermost/adapter.test.ts`
  - [ ] inbound normalization and sender/session IDs.
  - [ ] outbound send path.
  - [ ] allowlist and mention gating.
  - [ ] reconnect behavior and error handling.
- `src/config/schema.test.ts`
  - [ ] mattermost schema defaults/validation.
- `src/daemon/channels.test.ts`
  - [ ] adapter wiring and enable/disable lifecycle.
- `src/gateway/handlers/services.test.ts`
  - [ ] channel presence/status reporting.

### Acceptance Criteria

- Mattermost operates end-to-end with same safety model as existing channels.
- Docs and diagnostics are sufficient for first-time setup.
- No regressions in existing channel startup/wiring tests.

## Phase 3 — Companion Node + Capability Negotiation Foundation (P3)

### Scope

- Build protocol/runtime foundation for future companion apps and advanced surfaces.
- Do not build full macOS/iOS/Android nodes in this phase.
- Deliver capability discovery, version negotiation, and node role model.

### File-Level Tasks

- `src/gateway/protocol.ts`
  - Add capability/version negotiation types (`protocol.version`, feature flags).
  - Add `node.register`, `node.capabilities.get` RPC schema.
- `src/gateway/server.ts`
  - Track node-role connections and scoped auth constraints.
- `src/gateway/router.ts`
  - Route and validate node-specific RPC calls.
- `src/gateway/handlers/system.ts`
  - Add capability introspection endpoint(s).
- `src/config/schema.ts`
  - Add optional node policy config (`gateway.nodes.allowed_roles`, feature gates).
- `src/gateway/auth.ts`
  - Add scoped auth checks for node-role methods.
- `docs/api/PROTOCOL.md`
  - Document negotiation handshake and node method contracts.
- `README.md`
  - Add node foundation section and constraints.

### Test Checklist

- `src/gateway/protocol.test.ts`
  - [ ] validation for negotiation and node method payloads.
- `src/gateway/server.test.ts`
  - [ ] node registration lifecycle.
  - [ ] role-based method allow/deny behavior.
- `src/gateway/handlers/system.test.ts`
  - [ ] capability introspection output correctness.
- `src/gateway/auth.test.ts`
  - [ ] node-role scope enforcement.
- Integration tests:
  - [ ] backward compatibility for non-node clients with old flow.

### Acceptance Criteria

- Gateway supports explicit capability/version negotiation.
- Node connections can be constrained by role and method scope.
- Existing WebChat/TUI clients remain fully compatible.

## Cross-Phase Delivery Rules

- Keep each phase behind config flags where behavior risk is non-trivial.
- Land in small atomic commits with docs and tests in the same commit.
- Update `docs/plans/state.json` after each phase completion.
- Run at least:
  - `pnpm test:run` for touched suites.
  - `pnpm typecheck`.
  - `pnpm build` for protocol/runtime touching phases.

## Suggested Execution Order

1. Phase 1 (Queue parity v2).
2. Phase 2 (Mattermost adapter).
3. Phase 3 (Node/capability foundation).