# Full-Stack Contract & Integration Intelligence

## Purpose

Webdev Agent OS v28 unifies the frontend and backend architecture twins through a governed contract layer. It answers a single operational question: **does a user action remain compatible from the browser interface through services, data, events, releases, and runtime outcomes?**

The system treats integration as evidence, not assumption. A route existing and an API returning data are not enough. Shared schemas, consumers, events, webhooks, error behavior, performance budgets, release versions, and rollback paths must remain traceable and testable.

## Evidence chain

1. User journey and intended business outcome
2. Frontend route and interaction
3. Request and response schema
4. API contract and owning service
5. Data-flow, event, queue, or webhook boundary
6. Consumer-driven contract test
7. End-to-end integration test
8. Cross-layer performance budget
9. Coordinated frontend/backend release train
10. Runtime and outcome evidence

## Major records

### Journey contracts

Journey contracts connect customer behavior to frontend routes, backend services, API contracts, data flows, and business outcomes. They surface at-risk journeys even when aggregate contract scores appear healthy.

### Shared schemas

Schemas are versioned, repository-relative, test-backed contracts. A schema may be pending, verified, or failed. Verified schemas require test evidence.

### Route/API bindings

Bindings define the exact HTTP method, path, frontend route, backend service, API contract, and request/response schemas. Verified bindings require consumer-test evidence.

### Events and webhooks

Asynchronous contracts document producer and consumer ownership, delivery semantics, version, schema, signature requirements, replay protection, and tests.

### Consumer-driven tests

A consumer test records the consumer, provider, assertion count, failures, status, and supporting evidence. A test cannot pass with failures.

### Compatibility matrices

Matrices compare frontend/backend versions, event consumers, webhook versions, error envelopes, mobile clients, and coordinated release trains. A matrix cannot pass while incompatible entries remain.

### Release trains

A release train coordinates frontend, backend, and schema versions. Verified trains require independent approval, test evidence, and rollback instructions.

### Breaking changes

Breaking-change records preserve affected consumers, severity, mitigation, evidence, and rollback. Open critical changes reduce the system health score and block unsafe evolution.

## Health model

The v28 health score combines:

- Shared-schema verification
- Route/API binding verification
- Event compatibility
- Webhook compatibility
- Consumer-test pass rate
- Compatibility-matrix pass rate
- Integration-test pass rate
- Cross-layer budget compliance
- Release-train readiness
- Journey traceability

Open and critical breaking changes apply explicit deductions so severe compatibility risk cannot disappear inside a high average.

## Human approval boundary

Webdev Agent may inventory, calculate, test, compare, report, and recommend automatically. It cannot independently approve a breaking contract change, activate a coordinated release, or claim external deployment evidence.

## Commands

```bash
npm run full-stack-integration:stats
npm run full-stack-integration:report
node scripts/full-stack-integration-cli.js view
```

Generate evidence-backed campaigns:

```bash
node scripts/full-stack-integration-cli.js portfolio full-stack-contract-hdp-web
```