# AroFlo Connector Scope and Audit

Status: `v1-draft`  
Last reviewed: 2026-08-01

## Product boundary

The connector exists to expose normalized AroFlo capabilities to platform
applications, WordPress App Packs, shortcodes, and the platform agent runtime.
It owns AroFlo authentication, API and BOT transports, routing, schemas,
normalization, concurrency, and technical diagnostics.

It does not own leave, payroll, booking, fleet, invoice, or other consumer
business workflows. A consumer must call published capabilities through
`platform.interapp.client.call_capability`; it must not import connector
modules, invoke its CLI, or call the UI worker directly.

## Official surfaces

1. Standard v1 capability actions through the platform gateway.
2. WordPress PHP helpers and authenticated REST routes supplied by the App Pack.
3. Agent tools generated from `ActionContract.agent` metadata.
4. An administrator-only diagnostic shortcode.

The legacy Flask blueprint, CLI, embedded agent, and worker routes are not
public product contracts.

## Structural classification

| Area | Classification | Direction |
|---|---|---|
| `client.py`, `auth.py`, `config.py` | `adapter_api` | Keep and normalize |
| `zones/` | `adapter_api` | Migrate one zone at a time |
| `bot_pool.py`, `bot_leases.py`, worker security | `core` | Keep |
| `ui_automation_zones/` | `adapter_bot` | Keep supported flows; remove duplication later |
| `ui_automation/` | `legacy` | Retire after parity is verified |
| `ui_automation_worker/routes.py` | `adapter_bot_internal` | Keep private; route through connector actions |
| `services/capabilities.py`, `dispatcher.py` | `legacy_contract` | Replace with the v1 operation catalog |
| `api/v1/routes.py` | `legacy_surface` | Do not extend; retire after gateway parity |
| `agent/` | `legacy_agent` | Retire after standard platform tools replace it |
| WordPress App Pack | `platform_surface` | Extend from published contracts only |
| screenshots, HTML dumps, state files | `artifact` | Never version; retain last three per BOT |

## Confirmed coupling outside the boundary

`leave_form_app` currently imports `bot_pool` and `worker_client`, calls the
connector CLI, and knows worker details. These are migration targets. The
connector must not add a reverse dependency on `leave_form_app`, and existing
consumer behavior must remain until equivalent Standard v1 capabilities exist.

## Current capability facts

- Registered API zones: 8.
- Declared operations: 62.
- BOT-backed domain operations: user document upload, timesheet create, and
  timesheet delete.
- BOT session lifecycle is implemented separately from domain operations.
- API responses currently expose provider-specific shapes.
- Legacy filters accept raw AroFlo `where` and `order` strings.
- Declared, implemented, tested, and published are not consistently separated.
- No domain operation is currently published as a Standard v1 or agent tool.

## Migration rule

An operation is publishable only when it has:

1. A zone manifest and canonical operation name.
2. A closed input schema and normalized output schema.
3. Explicit filter and field allowlists.
4. A declared transport policy and maturity per transport.
5. Stable errors, permission, risk, confirmation, and idempotency metadata.
6. Unit contract tests and a controlled provider verification record.
7. WordPress and agent exposure derived from the same contract.

## Pilot decision

The first vertical slice is read-only `users.search`, followed by `users.get`
and `users.list`. It establishes canonical user identity, allowlisted filters,
normalized records, the Standard v1 gateway action, WordPress PHP/REST helpers,
and a low-risk platform agent tool.

The second slice is `timesheets.list`. It adds date filtering, the canonical
`user_id` relationship, task references, pagination, duration normalization,
and the first useful cross-zone agent composition. BOT-backed timesheet writes
remain unpublished until this read path is stable.

No existing legacy operation is removed during either pilot. Publication is
additive and consumer migrations happen only after parity tests pass.