Task: Generate OPERATIONS.md — Deployment, Config, Runbooks, Integrations

Task: Generate OPERATIONS.md — Deployment, Config, Runbooks, Integrations

Objective

Produce an OPERATIONS.md that serves as the single source of truth for how the system runs, ships, is configured, integrates, and is recovered: per-environment deployment topology (compute, region, network, data plane, per-component placement, scaling behaviour), CI/CD pipelines with stages, gates, artifacts, promotion, and rollback, environment strategy (config differences, data strategy, access control), a config catalogue under stable CFG_NAME IDs with owner and scope per entry, a secrets inventory with storage, rotation policy, read/rotate principals, and audit trail, an integration catalogue with auth, SLA, failure behaviour, and privacy notes for every external dependency, a runbook entry for every alert named in QUALITY, a disaster-recovery plan with concrete RTO/RPO numbers and a step-by-step restore procedure, observability infrastructure (where logs, metrics, traces land — what is emitted lives in QUALITY), change management, and an initial-setup runbook executable as-is by a new operator. An agent reading this document alone can — for any environment, alert, config var, secret, or external integration — name the compute shape, the config delta, the rotation schedule, the failure mode, or the on-call response, without opening ARCHITECTURE, INTERFACES, DATA, QUALITY, or SECURITY.

OPERATIONS.md consolidates what older guidance split into DEPLOYMENT.md, RUNBOOK.md, CONFIG_CATALOG.md, and INTEGRATION_CATALOG.md, because every reader doing ops work reads them together: the on-call engineer opens a runbook, needs the config var to flip, sees which integration is degraded, and checks the rollback path — all in one page. The defining discipline — and the commonest violation — is every alert in QUALITY § 6 has a § 7 runbook entry here, every config var has a stable CFG_NAME, every external integration has a named failure behaviour, every production secret has a rotation policy. Orphan alerts page humans with no script; orphan config vars rename without deprecation and break production; orphan integrations fail silently at 3am; secrets that never rotate are the easiest persistent-access path an attacker has.

Inputs

1. ARCHITECTURE.md (required) — § 2 Components supplies the list of things that run in the deployment topology; § 6 (or equivalent) deployment-shape headline frames § 1; every ADR-NN on runtime choice (Kubernetes vs Cloud Run vs bare metal, single-region vs multi-region, push vs pull deployment) is cited verbatim here.
2. INTERFACES.md (required) — § 1 Boundaries supplies the inventory of external dependencies that drive § 6 Integration Catalogue; § 6 Endpoints supply the inbound surfaces whose ingress / egress shape § 1 Network; § 7 Events supply the event bus dependencies.
3. DATA.md (required) — datastore list, provisioning shape, migration mechanism, and retention windows drive the data-plane rows of § 1, the backup/restore in § 8, and the per-environment data strategy in § 3.
4. QUALITY.md (required) — § 6 Alert Catalogue is the authoritative list of alerts; every ALERT-* there has a matching runbook entry in § 7 here. § 9 Observability Infrastructure references storage locations whose concrete choices live here.
5. SECURITY.md (optional — required if produced) — § 9 Secret & Credential Management names secret classes and rotation policies; § 5 and § 11 drive audit trail and abuse-prevention config vars; § 13 Incident Response references paging destinations this document pins.
6. BEHAVIOR.md (optional) — § 2 Sagas frame integration-failure compensation paths that § 6 Integration Catalogue cites in its Failure-Behaviour rows.
7. Existing OPERATIONS.md or deployment docs (auto-discovered — only if refining) — read fully. Every assigned CFG_NAME, RUNBOOK-*, and integration entry is permanent. New entries take new unused IDs. Retired entries retain their row with (retired — superseded by {new-id}).

Read set size: 4 required artifacts + SECURITY and BEHAVIOR when present + optional prior OPERATIONS. Read all required inputs end-to-end. Truncated reads cause three specific failure modes: runbooks missing for alerts QUALITY catalogs (QUALITY § 6 not fully read — produces blind paging), integration catalogue missing services INTERFACES § 1 names (INTERFACES not fully read — produces "why did this fail at 3am" surprises), and backup strategy missing datastores DATA lists (DATA not fully read — produces data-loss blind spots).

Workflow

Operations-contract construction proceeds in six phases: deployment and CI/CD, config and secrets, integrations, runbooks, disaster recovery and observability, change management and setup. Phases are sequential — later phases cite IDs introduced by earlier phases — but revisit earlier phases if a later one reveals a missing environment, an un-routed alert, or an un-rotated secret.

Phase 1: Deployment Topology, CI/CD, Environment Strategy

Produce §§ 1–3 together — they share the environment axis.

§ 1 Deployment Topology has one block per environment (typically dev / staging / prod; additional environments like sandbox, preview, dr get their own block when they exist). Each block fills the Output Format template: purpose and scope (who accesses, what traffic), compute (cloud provider, service type — Kubernetes / Cloud Run / Lambda / EC2 / bare metal — instance sizes), region strategy (single-region / multi-region / active-passive), network (VPCs, subnets, firewalls, ingress, egress policies), data plane (managed DBs, object storage, queues, caches — every row citing DATA), per-component mapping (which ARCHITECTURE § 2 component runs in which compute resource), scaling behaviour (horizontal / vertical, auto-scaling triggers). Every component from ARCHITECTURE § 2 appears in at least one environment's per-component mapping, or surfaces in § 13 as a missing-placement open question. A Mermaid diagram or an external link per environment illustrates the layout.

§ 2 CI/CD Pipelines has one block per pipeline. Each block fills repo and branch, stages (lint → test → build → deploy) with the tool family per stage (not specific product versions — those are /implement concerns), gates (required checks, approvals, review counts), artifacts (Docker image tag format, release version scheme — v{major}.{minor}.{patch} plus commit SHA), promotion model (staging → prod: auto with guardrails / manual with two-approver / canary with percentage ramp), rollback mechanism (image tag pinning / feature-flag flip / blue-green switch / DB-migration reverse script). Every environment in § 1 is reachable by exactly one pipeline path (or has an explicit "bootstrap-only, no CI deploy" annotation).

§ 3 Environment Strategy has three fixed subsections. Config difference matrix: a table of what varies per environment, citing CFG_NAME entries from § 4 (domains, rate limits, feature flags, retention windows). Data strategy per environment: dev = synthetic, staging = production clone (scrubbed — cite § 5 and SECURITY § 10 for scrubbing rules), prod = production. Access control per environment: who can deploy to what, who can read production logs, who can execute § 7 runbook commands — cites SECURITY § 8 roles where available.

Phase 2: Config Catalogue & Secrets Inventory