# HANDOFF.md

## Purpose
Immediate baton-pass for the next fresh implementation session.

## Current objective
Run operator/polish pass (3/3): tighten operator docs, approval policy clarity, recurring verification flow, and low-noise execution reporting now that Gmail + Calendar passes are complete.

## Use these state files first
1. `WIP.md` — full standing plan and checkpoints
2. `memory/2026-03-12.md` — detailed execution history and evidence
3. `memory/tasks.json` — task status tracking

## What is already true
- `openclaw-action` is live in n8n and active.
- Google auth via `gog` is working headlessly through local env auto-load.
- Local automation env lives in `/home/openclaw/.openclaw/credentials/gog.env` and stays out of git.
- Host bridge exists at `skills/n8n-webhook/scripts/resolve-approval-with-gog.py`.
- Real approval-routed Gmail draft and Calendar event flows have both been verified multiple times end-to-end with cleanup.

## Fresh-session proof completed (2026-03-12 19:44Z)
- Gmail draft flow (`send_email_draft`):
  - approval id: `approval-mmnvn4t2-w2rjlwz2`
  - draft id: `r-3319106208870238577`
  - subject: `[zap n8n e2e] Gmail draft test 20260312T194450Z`
  - verified via `gog gmail drafts get`
  - cleaned via `gog gmail drafts delete --force`
- Calendar event flow (`create_calendar_event`):
  - approval id: `approval-mmnvn6i8-e9eq8gdf`
  - event id: `m7prri8vk2opuo6loq3qgtvsv4`
  - title: `[zap n8n e2e] Calendar test 20260312T194450Z`
  - verified via `gog calendar get primary <eventId>`
  - cleaned via `gog calendar delete primary <eventId> --force`

## Gmail pass 1 completed in this handoff cycle
- Added workflow actions:
  - `list_email_drafts`
  - `delete_email_draft`
  - `send_gmail_draft` (alias: `send_approved_email`)
- Added host bridge executors:
  - `email_list_drafts` (`gog gmail drafts list`)
  - `email_draft_delete` (`gog gmail drafts delete`)
  - `email_draft_send` (`gog gmail drafts send`)
- Added explicit approval metadata in workflow responses (`approval.policy`, `approval.required`, `approval.mutation_level`).
- Updated docs/test payloads/validator to match the expanded Gmail contract.

## Calendar pass 2 completed in this handoff cycle
- Added workflow actions:
  - `list_upcoming_events`
  - `update_calendar_event`
  - `delete_calendar_event`
- Added host bridge executors:
  - `calendar_list_events` (`gog calendar events`)
  - `calendar_event_update` (`gog calendar update`)
  - `calendar_event_delete` (`gog calendar delete`)
- Preserved explicit approval policy:
  - read-only calendar listing stays `low`
  - mutating calendar update/delete stay `high`
- Added docs/test payloads/validator coverage for the expanded calendar contract.

## Highest-priority next actions
1. Add a compact operator command/reference section for common approval flows.
2. Add one or two canned recurring verification flows (queue → approve → verify → cleanup).
3. Decide/document approval defaults clearly per action family.
4. Improve low-noise execution/result reporting in approval history.

## Success criteria for the next session
- Operator/polish pass completed with docs/playbook/history-reporting improvements.
- Approval defaults are explicit and easy to skim.
- `WIP.md` and memory updated with concrete evidence.
- Meaningful commit(s) captured.

## Relevant files
- `WIP.md`
- `HANDOFF.md`
- `skills/n8n-webhook/assets/openclaw-action.workflow.json`
- `skills/n8n-webhook/scripts/call-action.sh`
- `skills/n8n-webhook/scripts/resolve-approval-with-gog.py`
- `skills/n8n-webhook/references/openclaw-action.md`
- `memory/2026-03-12.md`
- `memory/tasks.json`
- `/home/openclaw/.openclaw/credentials/gog.env` (local-only)

## Relevant branch / commits
- branch: `feat/n8n-action-bus-v2`
- latest checkpoints before this handoff include:
  - `afa48a3` — bridge approvals to gog executors
  - `044e36f` — auto-load local gog automation env
  - `06fa582` — track google workspace and n8n plan

## Operator note
Use the live n8n public API/webhook surface directly when it is the right path. Do not act blocked on n8n API access.