# Webdev Agent OS v10 — Connected Agency Orchestration

## Purpose

Connected Agency Orchestration links commercial, delivery, project, and production evidence through controlled connector contracts. It is intentionally not a credential vault and does not claim external systems are connected merely because an adapter is registered.

## Operating boundary

- Connector records describe capabilities, direction, and environment-variable names.
- Secrets and OAuth tokens remain outside the JSON store.
- Signed inbound webhooks require an environment-backed HMAC secret.
- Duplicate events are rejected through idempotency keys.
- Outbound writes, client messages, financial changes, and production actions require approval or explicit operator execution.
- The default examples do not call external services.

## Core records

### Connectors

CRM, email, calendar, payment, accounting, source-control, and internal evidence adapters. Each connector has an enabled flag, health state, capabilities, and credential references.

### Synchronization runs

Every import, export, reconciliation, or health check records direction, status, counts, errors, timestamps, and an idempotency key.

### Entity links

Links preserve the relationship between a local client, invoice, opportunity, project, or deployment and an external record without treating external IDs as the source of truth by default.

### Change orders

Unplanned scope receives a written reason, scope list, estimated hours, commercial impact, capacity window, and an authorized decision before entering delivery.

### Capacity plans

Plans make available, committed, and incident-reserve hours explicit. New work can therefore be evaluated against delivery reality rather than calendar optimism.

### Workflows

Workflow definitions document triggers, steps, connectors, approval modes, and measured run outcomes. A workflow is not considered automated merely because it is described.

### Next-best actions

Actions are generated from evidence such as failed synchronization, incomplete onboarding, pending change orders, overdue financial evidence, and constrained capacity. Approval-required actions cannot be completed until approved.

## Signed connector webhooks

Each connector may name an environment variable containing its webhook secret. Send the exact raw request body with:

```text
X-Webdev-Signature: sha256=<HMAC-SHA256 hex digest>
X-Webdev-Idempotency-Key: <stable provider event ID>
```

Endpoint:

```text
POST /api/orchestration/connectors/:connectorId/webhook
```

The server rejects missing configuration, invalid signatures, malformed JSON, and duplicate event IDs.

## API surface

- `GET /api/orchestration`
- `GET /api/orchestration/stats`
- `GET /api/orchestration/export`
- `POST /api/orchestration/connectors`
- `POST /api/orchestration/sync-runs`
- `POST /api/orchestration/entity-links`
- `POST /api/orchestration/change-orders`
- `POST /api/orchestration/change-orders/:id/decision`
- `POST /api/orchestration/capacity`
- `POST /api/orchestration/workflows`
- `POST /api/orchestration/actions/generate`
- `POST /api/orchestration/actions/:id/decision`
- `POST /api/orchestration/actions/:id/complete`
- `POST /api/orchestration/report`

## CLI

```bash
npm run orchestration:stats
npm run orchestration:report
node scripts/orchestration-cli.js generate-actions
```

## Production implementation sequence

1. Register a connector contract with `enabled: false`.
2. Add least-privilege credentials to the host environment.
3. Run a read-only health check.
4. Record baseline synchronization evidence.
5. Reconcile sample records and validate idempotency.
6. Enable only the required direction and capabilities.
7. Require approval for outbound writes.
8. Monitor failures, lag, duplicate events, and unmatched records.
9. Maintain a documented disconnect and rollback procedure.