# Lessons Learned

Reusable lessons from this OpenClaw multi-agent Cursor workflow.

## 2026-05-15

- A public Gitea repository can be cloned anonymously over HTTPS, but push still requires credentials. Do not treat clone success as sync readiness.
- Cursor's Git askpass can surface authentication failures differently from a normal terminal. Use explicit credential setup or SSH remote when long-running sync scripts need push access.
- Git polling is useful as an MVP control plane, but it needs heartbeat files and CORRECTION monitoring. Otherwise silent sync failure makes agents reason from stale state.
- Push can be rejected when PC and VPS sync scripts race. Sync scripts should rebase and retry once before blocking.
- The user should not manage internal task IDs such as `T3` or `T7`. Maintain `USER_STATUS.md` as the user-facing status page.
- COACH and ORCHESTRATOR should remain separate roles: ORCHESTRATOR manages tasks; COACH manages usability, method, and knowledge capture.
- Sync scripts are infrastructure and should not be owned by normal chat agents. They should remain in dedicated terminals for now and later become managed services after safety gates allow persistence.
- Session freeze is mandatory for long-running work. Handoff files and lessons are more reliable than chat memory.

## 2026-05-19

- Multi-window Cursor work needs visible role confirmation. A prompt intended for ORCHESTRATOR can land in a VPS_VERIFIER window and produce plausible but out-of-scope control-plane edits.
- Role mismatch should be treated as a safety blocker for execution or authorization. Pause tasks first, then let ORCHESTRATOR adopt or correct affected files.
- Authorization should name the target role, workspace, task, and exact allowed action. Short prompts like "go ahead" are unsafe when several role windows are open.
- Verifier roles should refuse ORCHESTRATOR/EXECUTOR work even when the requested edit is reasonable.
- Recovery should check for five facts before resuming: cross-role file edits, secret leakage, live PC/VPS commands, frozen website mutation, and sync health.
- Keep `docs/ROLE_MISDIRECTION_RECOVERY.md` and `.cursor/rules/role-confirmation.mdc` as reusable guardrails for future multi-agent sessions.
- COACH should guide with copy/paste action cards: target window, exact prompt, and expected result. This reduces user burden and avoids asking the user to reason about internal task IDs.