Production Readiness Policies

This is the Company OS contract for three VertiSwarm commercialization blockers:

• production database writes and rollback;
• OAuth connector polish;
• customer-specific evidence packs.

The backend exposes the machine-readable contract at:

GET /api/company/production-readiness/contract

Implementation: src/company_os/production_readiness.rs.

Production Write / Rollback Policy

Default mode is dry-run shadow. Agents may inspect schemas, generate mutation plans, run validation queries, and prepare rollback plans without human approval. They may not perform production writes until a workflow has an explicit mutation policy and evidence trail.

Required gates before a production write:

1. Schema catalog describes the target source, tables, columns, and sensitive fields.
2. Mutation policy declares allowed tables, columns, verbs, and risk class.
3. Idempotency key is present.
4. Human approval exists for non-reversible, high-value, customer-facing, or permission-changing actions.
5. Pre-write snapshot or compensating rollback plan exists.
6. Post-write verification query is defined.
7. Run execution event records actor, before/after evidence, and outcome.
8. Governance event records approval or rejection.

Blocked until explicit policy:

• delete;
• bulk update;
• external payment or purchase;
• customer email send;
• credential or permission change;
• cross-tenant data move.

Evidence artifacts:

• mutation_plan.json
• dry_run_result.json
• approval_event.json
• rollback_plan.json
• post_write_verification.json
• trace.jsonl

OAuth Polish Policy

OAuth-backed connectors should be treated as not production-polished until the operator experience covers account health, granted scopes, refresh state, and disconnect/revocation.

Required gates:

1. Provider template declares auth mode and scopes.
2. OAuth2 uses PKCE or server-side exchange.
3. State nonce is bound to company and user.
4. Tokens are encrypted at rest or stored in an external credential provider.
5. Refresh worker status is visible.
6. Revocation/disconnect path exists.
7. Scope changes require reapproval.

Token handling rules:

• never return raw access tokens to the browser;
• redact access tokens, refresh tokens, API keys, secrets, passwords, and private keys;
• store only access-token hints in public responses;
• record token expiry and refresh status;
• support strict credential-encryption mode.

Evidence artifacts:

• oauth_provider_manifest.json
• connector_account_redacted.json
• refresh_health.json
• scope_review.json
• disconnect_or_revocation_log.json

Customer-Specific Evidence Policy

Customer evidence must be scenario-specific. Generic platform screenshots are not enough to claim productivity savings or production readiness.

Minimum artifacts:

• customer_context.md
• workflow_baseline.md
• demo_task.ndjson
• trace.jsonl
• governance.json
• rollback_or_repair_evidence.jsonl
• screenshots/
• metrics.md

Minimum demo surfaces:

1. Dashboard or browser session.
2. Schema-aware database read or guarded write.
3. External API, portal, email, or document.
4. Human approval gate.
5. Trace export.

Metrics to capture:

• manual baseline minutes;
• agent runtime minutes;
• human interventions;
• tool calls;
• error count before and after;
• rollback or recovery time;
• estimated cost per run.

Forbidden claims without pilot data:

• proven 40-60% savings;
• fully autonomous recovery;
• liability eliminated;
• production-ready for regulated enterprise.

Next Wiring Steps

1. Add a mutation_policy table or runtime-policy section for allowed write scopes.
2. Add a guarded write endpoint that only accepts mutation_plan.json plus approval id.
3. Persist rollback and post-write verification artifacts beside run execution events.
4. Complete OAuth connect/disconnect UX against the connector account contract.
5. Generate a dated customer evidence folder from one logistics or finance demo workflow.