diff --git a/docs/CHATWOOT_PARITY_DEVELOPMENT_PLAN.md b/docs/CHATWOOT_PARITY_DEVELOPMENT_PLAN.md index 47ad3035..e68293c1 100644 --- a/docs/CHATWOOT_PARITY_DEVELOPMENT_PLAN.md +++ b/docs/CHATWOOT_PARITY_DEVELOPMENT_PLAN.md @@ -16,8 +16,9 @@ Build GoChat as a Go backend that can directly reuse the frontend from `referenc ## Current Baseline -- Latest implementation checkpoint: this checkpoint, prepared as `feat(captain): align task payload persistence`. -- Latest documentation checkpoint: this checkpoint, recorded with the B11.3d Captain task/tool-call persistence implementation. +- Plan freeze checkpoint: 2026-06-05 docs-only tracker landing after `13cb750 feat(captain): align task payload persistence`. +- Latest implementation checkpoint: `13cb750 feat(captain): align task payload persistence`. +- Latest documentation checkpoint before this freeze: `3263ed9 docs: land copilot task execution plan`; this document now carries the active follow-up plan directly. - Worktree status at this implementation checkpoint: B11.1a aligns Captain assistant CRUD/tools/inbox bindings; B11.1b aligns Captain scenarios and custom tools; B11.1c aligns Captain documents, assistant responses, bulk actions, and custom-tool test payloads; B11.2 aligns Copilot thread/message create/list/get/delete payloads, account/user scoping, and no-LLM fallback persistence; B11.3a aligns Captain preferences show/update payloads and account-level model/feature storage; B11.3b aligns Captain playground request/response payloads, account scoping, v2 history handling, and no-LLM fallback; B11.3c adds the fakeable Captain document sync backend gate with disabled, failed, and fake-success states; B11.3d aligns Captain task request/response payloads, no-provider disabled states, follow-up context, suggestion persistence, and Copilot message tool-call key validation. Next active implementation slice is B11.3e streaming/realtime compatibility, followed by B12 reused frontend smoke. - `go test ./...` passes. - Route dump succeeds with `TOTAL: 830` after adding the Chatwoot-compatible applied-SLA index route. @@ -46,6 +47,30 @@ Next ordered checkpoints: | --- | --- | --- | --- | | 1 | B11.3e | Streaming/realtime paths have frontend-compatible non-streaming or disabled fallbacks until true streaming is wired. | Deterministic response tests and event/push payload tests. | | 2 | B12 | Reused Chatwoot frontend smoke runs repeatably against GoChat. | Checked smoke command plus gap report under `docs/parity/`. | +| 3 | Phase 5 job parity | Any async behavior deferred from B7-B11 has a durable worker decision, fakeable delivery boundary, and replay/idempotency tests. | Focused worker/job tests plus a Phase 5 gap ledger update. | +| 4 | Phase 2/3 audit pass | Route/controller/serializer drift found by B12 or new reference inspection is captured as named slices, not free-form TODOs. | Regenerated route parity artifacts and fixture-backed serializer tests. | +| 5 | Phase 6 placeholder burn-down | Remaining account/contact/conversation/message/inbox placeholder handlers are either real Chatwoot-compatible flows or explicitly tracked as unsupported reference gaps. | `rg` placeholder audit, route smoke, and endpoint-family tests. | + +## Handoff Contract + +This checkpoint is intended to make the development plan complete enough to track without reading Hermes notes first. + +- The only active implementation slice is B11.3e. Do not start B12 until Captain/Copilot stream and realtime disabled states are deterministic and tested. +- The Hermes search plan is fully represented by Phase 1/B6. Future search changes must be Meilisearch-first and must not reintroduce production DB fallback. +- The Hermes automation/macro/CSAT plan is fully represented by B8/B9 and Phase 5. Durable delayed execution and channel-specific template delivery remain visible Phase 5 work, not hidden Done work. +- Enterprise scope is fixed: SLA, Audit, CustomRole, AgentCapacity, Captain/Copilot, CSAT, InboxLimit, automation, macros, assignment policies, and related limits/workflows are in scope; SSO/SAML/LDAP/OIDC are out of scope. +- Every future commit must update one of: the Current Baseline, Commit Ledger, active B-slice board, Phase 5 backlog, B12 smoke report link, or Progress Log. + +Open work after the current checkpoint: + +| Area | Next concrete action | Tracking location | Done boundary | +| --- | --- | --- | --- | +| B11.3e Captain streams | Reuse non-stream task DTOs for stream routes, guard nil/non-streaming LLM provider, and emit stable SSE error/done events. | `B11.3e streaming/realtime landing contract` | Focused SSE tests cover no-provider, invalid operation, provider error, and success chunks. | +| B11.3e Copilot realtime | Add or verify push payload serializers that match Chatwoot `CopilotThread#push_event_data` and `CopilotMessage#push_event_data`. | `B11.3e streaming/realtime landing contract` | Event payload tests prove raw thread/message shapes and allowed message keys. | +| B12 smoke | Create repeatable GoChat plus reused Chatwoot frontend boot and seed path. | `B12 reused frontend verification breakdown` | `docs/parity/frontend_smoke_report.md` exists and maps failures to slices. | +| Phase 5 jobs | Decide durable worker mechanism and wire deferred SLA/automation/macro/export/template delivery jobs behind idempotent boundaries. | `Phase 5: Background Jobs And Integrations` | Worker tests prove enqueue, retry, idempotency, and fakeable external effects. | +| Phase 2/3 drift | Expand tracked route/serializer fixtures when B12 exposes frontend-critical gaps. | `Phase 2`, `Phase 3`, `docs/parity/` | Route parity remains 0 missing for tracked frontend routes; serializers have reference fixtures. | +| Phase 6 placeholders | Re-run placeholder audit and burn down any frontend-reachable stub. | `Phase 6: Core Product Placeholder Burn-down` | Stub list has no reused-frontend critical path without a named owner. | ## Execution Snapshot @@ -78,6 +103,7 @@ This ledger records the committed parity checkpoints that future slices should b | Commit | Scope | Verification summary | Follow-up state | | --- | --- | --- | --- | +| `docs: land parity tracker handoff` | Froze the active tracker after B11.3d, copied the remaining Hermes-derived work into explicit B11.3e/B12/Phase 5/Phase 6 tracking rows, and clarified the commit/update rules for future checkpoints. | Documentation-only checkpoint; `git diff --check` is sufficient. | Start B11.3e streaming/realtime compatibility. | | `6aa62c6 docs: consolidate chatwoot parity roadmap` | Promoted Hermes-era plans into this master tracker; locked user decisions; added milestone, slice, enterprise, and webhook provider tracking. | Documentation-only checkpoint. | B1/P6.7 selected as next implementation slice. | | `9e3f561 feat(webhook): align chatwoot ingress routes` | Added Chatwoot public webhook paths for Twitter, Telegram, LINE, SMS/Twilio, WhatsApp, Instagram, TikTok, and Shopify; removed generic fallback success masking. | `go test ./...`; route dump regenerated with `TOTAL: 801`; route parity stayed `251 exact, 0 missing`. | Provider-specific lookup and verification moved to review. | | `bc7da9e feat(webhook): implement instagram and shopify ingress` | Implemented Instagram verify/event handling, Shopify HMAC/redact/event forwarding, and WhatsApp verify-token/app-secret signature corrections. | Focused webhook tests, `go test ./...`, route dump `TOTAL: 801`, route parity `251 exact, 0 missing`, `git diff --check`. | Remaining P6.7 work is durable incoming-message persistence and provider dispatch parity. | @@ -1615,3 +1641,4 @@ Verification milestone gates: - 2026-06-05: B11.3c Captain document sync gate checkpoint prepared as `feat(captain): gate document sync backend`; document sync now has a fakeable backend boundary and account-scoped worker entry, disabled config is recorded as `sync_disabled`, backend failures become `sync_error` or preserve explicit backend error codes, fake success updates content/title/fingerprint/timestamps as `synced`, and default tests avoid external network/LLM calls. Focused Captain/Copilot tests, handler/service package tests, full `go test ./...`, and `git diff --check` passed. Next slice is B11.3d Copilot task/tool-call persistence. - 2026-06-05: B11.3d/B11.3e/B12 planning checkpoint prepared as `docs: land copilot task execution plan`; the active tracker now records exact Chatwoot Captain task request/response contracts, current Go handler/service gaps, follow-up context and allowed operation rules, reloadable Copilot message/tool-call persistence requirements, no-provider disabled-state expectations, streaming/realtime fallback gates, B12 smoke harness deliverables, and focused exit commands. Documentation-only checkpoint; `git diff --check` passed. Next slice is B11.3d implementation. - 2026-06-05: B11.3d Captain task/tool-call checkpoint prepared as `feat(captain): align task payload persistence`; rewrite/summarize/reply suggestion now accept Chatwoot task payloads and return raw `{ message, follow_up_context }` or `422 { error }`, label suggestion and follow-up POST routes consume dashboard `tasks.js` bodies, no-provider paths return `Captain is disabled`, task outputs persist to `copilot_suggestion_messages`, and `CopilotMessage` validates reloadable tool-call keys. Focused CaptainTask/Captain/Copilot handler and service tests, Copilot/Captain repository tests, handler/service package tests, full `go test ./...` with workspace `TMPDIR`, and `git diff --check` passed. Next slice is B11.3e streaming/realtime compatibility. +- 2026-06-05: Parity tracker handoff checkpoint prepared as `docs: land parity tracker handoff`; the plan now has a front-loaded handoff contract, explicit open-work table for B11.3e/B12/Phase 5/Phase 2/3/Phase 6, exact Hermes source-plan mapping, and a rule that every future checkpoint updates this tracker before commit. Documentation-only checkpoint; `git diff --check` passed.