# Webdev Agent OS v8 — Agent-Native Delivery and Client Operations

## Purpose

Webdev Agent OS v8 connects the development and operations systems to an accountable client-delivery layer. It is designed for an internal product studio, an agency, or a managed web-operations team that needs to coordinate client access, reviews, service requests, service-level objectives, status reporting, incident learning, and CI evidence without giving clients or automation unrestricted production control.

The operating sequence is:

**Prepare → Submit → Review → Decide → Deliver → Verify → Measure → Support → Learn**

## Hard safety boundary

The delivery layer can create records, collect evidence, request decisions, publish status information, and generate reports. It does not silently deploy code, execute arbitrary shell commands, bypass the release gate, or grant a client access to another account.

- Production deployments remain governed by the v7 approval and verification workflow.
- Client users only receive records attached to their client account.
- Trusted role headers are disabled by default.
- Signed CI webhooks are disabled until a secret is configured.
- Email and outbound webhook notification adapters remain suppressed unless a real adapter is explicitly supplied.
- Example records are labeled and must not be represented as verified production evidence.

## Roles

| Role | Intended authority |
|---|---|
| Owner | Administer clients, users, SLOs, status pages, exports, and all delivery records. |
| Developer | Submit deliverables, manage service work, create postmortems, record builds, and dispatch configured notifications. |
| Reviewer | Approve or reject deliverables and publish complete postmortems. |
| Client | View only the matching client account, decide assigned deliverables, and submit service requests. |
| Viewer | Read permitted non-sensitive data only. |

The local Control Center runs as the responsible owner when the service is bound to localhost. Header-provided roles are ignored unless `WEBDEV_TRUST_ROLE_HEADERS=true` is set for a trusted reverse proxy or test environment.

## Data model

The persistent delivery store is `config/delivery-store.json`. Its formal schema is `config/delivery-store.schema.json`.

### Clients

Clients connect projects to a service plan, contact, branding, and scoped portal token hash. Portal tokens are never saved in plaintext.

### Users

Users carry a role and optional client ID. v8 provides the role model and enforcement boundary; production identity-provider integration is a future adapter rather than a fabricated authentication claim.

### Deliverables

A deliverable represents a reviewable release, design, content package, report, or other completed work product. It records the version, summary, artifact, checklist, submission, decision, reviewer, notes, and dates.

Decisions are:

- `pending`
- `approved`
- `changes-requested`
- `rejected`

### Service requests

Client requests become durable work records with type, priority, owner, status, response target, due date, resolution, and timeline.

### Service-level objectives

The system supports three objective types:

- Availability percentage
- P95 latency in milliseconds
- Conversion percentage

Availability error budget is estimated from the objective window, target, failed checks, and monitor interval. This is useful operating evidence, but the estimate should be replaced with exact outage duration when a more precise monitoring source is available.

### Postmortems

Incident postmortems include impact, detection, root cause, contributing factors, what went well, what went poorly, and corrective actions. A reviewer cannot publish a postmortem until summary, impact, detection, and root cause are present.

### Status pages

Status pages are generated from recorded monitors, incidents, projects, and SLOs. A status page can be opened dynamically at:

```text
/status/<status-page-slug>
```

Generated static versions are placed under:

```text
reports/agent-native-delivery/status/<slug>/index.html
```

### CI and build evidence

The generic CI webhook endpoint is:

```text
POST /api/delivery/webhooks/ci
```

The raw JSON body must be signed with HMAC-SHA256 using `WEBDEV_CI_WEBHOOK_SECRET`. The signature header is:

```text
X-Webdev-Signature: sha256=<hex-digest>
```

Minimum payload:

```json
{
  "clientId": "client-hdp-internal",
  "projectId": "project-6511427790e0",
  "provider": "github-actions",
  "buildId": "12345",
  "status": "succeeded",
  "branch": "main",
  "commit": "abc123"
}
```

The endpoint records signed evidence. It does not automatically deploy the build.

Generate a matching signature for a JSON payload with:

```bash
export WEBDEV_CI_WEBHOOK_SECRET="replace-with-a-long-random-secret"
npm run delivery:sign-webhook -- examples/agent-native-delivery/ci-webhook-payload.json
```

The helper signs the exact file bytes, so submit the file with `--data-binary` rather than reserializing it.

### Notifications

The built-in adapters are deliberately conservative:

- `console` — can be dispatched immediately.
- `email` — remains suppressed until an email adapter is configured.
- `webhook` — remains suppressed unless outbound webhooks are explicitly enabled and a sender is supplied.

This prevents the example kit from pretending to send external messages or making arbitrary outbound requests.

## Client portal

Open:

```text
http://127.0.0.1:8080/client-portal/
```

The portal can:

- View scoped projects and delivery metrics
- Review deliverables
- Approve or request changes
- View SLO status and error-budget evidence
- View service requests
- Submit a new service request
- Open the assigned public status page

It cannot access the main Control Center, production deployment controls, Git evidence, monitor configuration, or another client account.

The included local demonstration account is:

```text
Client ID: client-hdp-internal
Portal token: webdev-demo-client
```

This token is illustrative and must be replaced before real use.

Issue a new client token:

```bash
node scripts/delivery-cli.js issue-token <clientId>
```

The plaintext token is shown once. Only its scrypt hash is stored.

## CLI

Show delivery statistics:

```bash
npm run delivery:stats
```

Show a scoped view:

```bash
node scripts/delivery-cli.js view client-hdp-internal
```

Generate status and client reports:

```bash
npm run delivery:report
```

Reset the working store to the illustrative seed:

```bash
node scripts/delivery-cli.js reset
```

## HTTP API

### Read

- `GET /api/delivery`
- `GET /api/delivery?clientId=<id>`
- `GET /api/delivery/session`
- `GET /api/delivery/export`
- `GET /api/delivery/client-portal?clientId=<id>`
- `GET /status/<slug>`

### Write

- `POST /api/delivery/clients`
- `POST /api/delivery/deliverables`
- `POST /api/delivery/deliverables/:id/decision`
- `POST /api/delivery/service-requests`
- `POST /api/delivery/service-requests/:id`
- `POST /api/delivery/slos`
- `POST /api/delivery/postmortems`
- `POST /api/delivery/postmortems/:id/publish`
- `POST /api/delivery/status-pages`
- `POST /api/delivery/notifications/dispatch`
- `POST /api/delivery/report`
- `POST /api/delivery/webhooks/ci`

### Portal writes

- `POST /api/delivery/client-portal/deliverables/:id/decision`
- `POST /api/delivery/client-portal/service-requests`

Portal requests require `X-Client-Portal-Token` and the matching `clientId`.

## Environment variables

```text
DELIVERY_STORE=/absolute/path/to/delivery-store.json
WEBDEV_CI_WEBHOOK_SECRET=replace-with-a-long-random-secret
WEBDEV_TRUST_ROLE_HEADERS=false
```

`WEBDEV_TRUST_ROLE_HEADERS` should only be enabled when an authenticated reverse proxy removes untrusted incoming role headers and supplies verified identity information.

## Reports

`npm run delivery:report` produces:

```text
reports/agent-native-delivery/
├── delivery-report.json
├── clients/
│   └── <client-id>/
│       ├── delivery-report.html
│       └── delivery-report.md
└── status/
    └── <slug>/
        └── index.html
```

## Verification

The v8 tests verify:

- Portal token hashing and verification
- Cross-client access denial
- Role-gated client administration
- Deliverable submission and client decision
- Client service-request creation
- SLO calculations
- Postmortem publication requirements
- Signed and unsigned CI webhook behavior
- Notification suppression and dispatch behavior
- Status and client report generation
- Delivery API persistence
- Client portal serving
- Control Center rendering without duplicate IDs or browser-console failures

Run:

```bash
npm run test:delivery
npm test
```

## Production integration work still required

v8 creates a defensible delivery boundary, but a real public deployment still requires:

- A production identity provider or authenticated reverse proxy
- Secure session management and CSRF protection if cookie sessions are introduced
- Secret management outside source control
- Real email or messaging adapters
- Provider-specific GitHub, GitLab, Azure DevOps, or other CI payload mapping
- Rate limiting and abuse protection
- Database-backed multi-process persistence for scale
- Legal review of client agreements, privacy, retention, and service commitments
- Verified monitoring targets and real analytics sources