dd0c/products/06-runbook-automation/epics/epics.md

# dd0c/run — V1 MVP Epics

This document breaks down the V1 MVP of dd0c/run into implementation Epics and User Stories. Scope is strictly limited to V1 (read-only execution 🟢, copilot approval for 🟡/🔴, no autopilot, no terminal watcher).

---

## Epic 1: Runbook Parser
**Description:** The "5-second wow moment." Ingest raw unstructured text from a paste event, normalize it, and use a fast LLM (e.g., Claude Haiku via dd0c/route) to extract a structured JSON representation of executable steps, variables, conditional branches, and prerequisites in under 5 seconds.

**Dependencies:** None. This is the foundational data structure.

**Technical Notes:** 
- Pure Rust normalizer to strip HTML/Markdown before hitting the LLM to save tokens and latency.
- LLM prompt must enforce a strict JSON schema.
- Idempotent parsing: same text + temperature 0 = same output.
- Must run in < 3.5s to leave room for the Action Classifier within the 5s SLA.

### User Stories

**Story 1.1: Raw Text Normalization & Ingestion**
*As a runbook author (Morgan), I want to paste raw text from Confluence or Notion into the system, so that I don't have to learn a proprietary YAML DSL.*
- **Acceptance Criteria:**
  - System accepts raw text payload via API.
  - Rust-based normalizer strips HTML tags, markdown formatting, and normalizes whitespace/bullet points.
  - Original raw text and hash are preserved in the DB for audit/re-parsing.
- **Story Points:** 2
- **Dependencies:** None

**Story 1.2: LLM Structured Step Extraction**
*As a system, I want to pass normalized text to a fast LLM to extract an ordered JSON array of steps and commands, so that the runbook becomes machine-readable.*
- **Acceptance Criteria:**
  - Sends normalized text to `dd0c/route` with a strict JSON schema prompt.
  - Correctly extracts step order, natural language description, and embedded CLI/shell commands.
  - P95 latency for extraction is < 3.5 seconds.
  - Rejects/errors gracefully if the text contains no actionable steps.
- **Story Points:** 3
- **Dependencies:** 1.1

**Story 1.3: Variable & Prerequisite Detection**
*As an on-call engineer (Riley), I want the parser to identify implicit prerequisites (like VPN) and variables (like `<instance-id>`), so that I'm fully prepared before the runbook starts.*
- **Acceptance Criteria:**
  - Regex/heuristic scanner identifies common placeholders (`$VAR`, `<var>`, `{var}`).
  - LLM identifies implicit requirements ("ensure you are on VPN", "requires prod AWS profile").
  - Outputs a structured array of `variables` and `prerequisites` in the JSON payload.
- **Story Points:** 2
- **Dependencies:** 1.2

**Story 1.4: Branching & Ambiguity Highlighting**
*As a runbook author (Morgan), I want the system to map conditional logic (if/else) and flag vague instructions, so that my runbooks are deterministic and clear.*
- **Acceptance Criteria:**
  - Parser detects simple "if X then Y" statements and maps them to a step execution DAG (Directed Acyclic Graph).
  - Identifies vague steps (e.g., "check the logs" without specifying which logs) and adds them to an `ambiguities` array for author review.
- **Story Points:** 3
- **Dependencies:** 1.2

## Epic 2: Action Classifier
**Description:** The safety-critical core of the system. Classifies every extracted command as 🟢 Safe, 🟡 Caution, 🔴 Dangerous, or ⬜ Unknown. Uses a defense-in-depth "dual-key" architecture: a deterministic compiled Rust scanner overrides an advisory LLM classifier. A misclassification here is an existential risk.

**Dependencies:** Epic 1 (needs parsed steps to classify)

**Technical Notes:** 
- The deterministic scanner must use tree-sitter or compiled regex sets.
- Merge rules must be hardcoded in Rust (not configurable).
- LLM classification must run in parallel across steps to meet the 5-second total parse+classify SLA.
- If the LLM confidence is low or unknown, risk escalates. Scanner wins disagreements.

### User Stories

**Story 2.1: Deterministic Safety Scanner**
*As a system, I want to pattern-match commands against a compiled database of known signatures, so that destructive commands are definitively blocked without relying on an LLM.*
- **Acceptance Criteria:**
  - Rust library with compiled regex sets (allowlist 🟢, caution 🟡, blocklist 🔴).
  - Uses tree-sitter to parse SQL/shell ASTs to detect destructive patterns (e.g., `DELETE` without `WHERE`, piped `rm -rf`).
  - Executes in < 1ms per command.
  - Defaults to `Unknown` (🟡 minimum) if no patterns match.
- **Story Points:** 5
- **Dependencies:** None (standalone library)

**Story 2.2: LLM Contextual Classifier**
*As a system, I want an LLM to assess the command in the context of surrounding steps, so that implicit state changes or custom scripts are caught.*
- **Acceptance Criteria:**
  - Sends the command, surrounding steps, and infrastructure context to an LLM via a strict JSON prompt.
  - Returns a classification (🟢/🟡/🔴), a confidence score, and suggested rollbacks.
  - Escalate classification to the next risk tier if confidence < 0.9.
- **Story Points:** 3
- **Dependencies:** Epic 1 (requires structured context)

**Story 2.3: Classification Merge Engine**
*As an on-call engineer (Riley), I want the system to safely merge the LLM and deterministic scanner results, so that I can trust the final 🟢/🟡/🔴 label.*
- **Acceptance Criteria:**
  - Implements the 5 hardcoded merge rules exactly as architected (e.g., if Scanner says 🔴, final is 🔴; if Scanner says 🟡 and LLM says 🟢, final is 🟡).
  - The final risk level is `Safe` ONLY if both the Scanner and the LLM agree it is safe.
- **Story Points:** 2
- **Dependencies:** 2.1, 2.2

**Story 2.4: Immutable Classification Audit**
*As an SRE manager (Jordan), I want every classification decision logged with full context, so that I have a forensic record of why the system made its choice.*
- **Acceptance Criteria:**
  - Emits a `runbook.classified` event to the PostgreSQL database for every step.
  - Log includes: scanner result (matched patterns), LLM reasoning, confidence scores, final classification, and merge rule applied.
- **Story Points:** 1
- **Dependencies:** 2.3

## Epic 3: Execution Engine
**Description:** A state machine orchestrating the step-by-step runbook execution, enforcing the Trust Gradient (Level 0, 1, 2) at every transition. It never auto-executes 🟡 or 🔴 commands in V1. Handles timeouts, rollbacks, and tracking skipped steps.

**Dependencies:** Epics 1 & 2 (needs classified runbooks to execute)

**Technical Notes:** 
- V1 is Copilot-only. State transitions must block 🔴 and prompt for 🟡.
- Engine must communicate with the Agent via gRPC over mTLS.
- Each step execution receives a unique ID to prevent duplicate deliveries.

### User Stories

**Story 3.1: Execution State Machine**
*As a system, I want a state machine to orchestrate step-by-step runbook execution, so that no two commands execute simultaneously and the Trust Gradient is enforced.*
- **Acceptance Criteria:**
  - Starts in `Pending` state upon alert match.
  - Progresses to `AutoExecute` ONLY if the step is 🟢 and trust level allows.
  - Transitions to `AwaitApproval` for 🟡/🔴 steps, blocking execution until approved.
  - Aborts or transitions to `ManualIntervention` on timeout (e.g., 60s for 🟢, 300s for 🔴).
- **Story Points:** 5
- **Dependencies:** 2.3

**Story 3.2: gRPC Agent Communication Protocol**
*As a system, I want to communicate securely with the dd0c Agent in the customer VPC, so that commands are executed safely without inbound firewall rules.*
- **Acceptance Criteria:**
  - Outbound-only gRPC streaming connection initiated by the Agent.
  - Engine sends `ExecuteStep` payload (command, timeout, risk level, environment variables).
  - Agent streams `StepOutput` (stdout/stderr) back to the Engine.
  - Agent returns `StepResult` (exit code, duration, stdout/stderr hashes) on completion.
- **Story Points:** 5
- **Dependencies:** 3.1

**Story 3.3: Rollback Integration**
*As an on-call engineer (Riley), I want every state-changing step to record its inverse command, so that I can undo it with one click if it fails.*
- **Acceptance Criteria:**
  - If a step fails, the Engine transitions to `RollbackAvailable` and awaits human approval.
  - Engine stores the rollback command before executing the forward command.
  - Executing rollback triggers an independent execution step and returns the state machine to `StepReady` or `ManualIntervention`.
- **Story Points:** 3
- **Dependencies:** 3.1

**Story 3.4: Divergence Analysis**
*As an SRE manager (Jordan), I want the system to track what the engineer actually did vs. what the runbook prescribed, so that runbooks get better over time.*
- **Acceptance Criteria:**
  - Post-execution analyzer compares prescribed steps with executed/skipped steps and any unlisted commands detected by the agent.
  - Flags skipped steps, modified commands, and unlisted actions.
  - Emits a `divergence.detected` event with suggested runbook updates.
- **Story Points:** 3
- **Dependencies:** 3.1

## Epic 4: Slack Bot Copilot
**Description:** The primary 3am interface for on-call engineers. Guides the engineer step-by-step through an active incident, enforcing the Trust Gradient via interactive buttons for 🟡 actions and explicit typed confirmations for 🔴 actions.

**Dependencies:** Epic 3 (needs execution state to drive the UI)

**Technical Notes:** 
- Uses Rust + Slack Bolt SDK in Socket Mode (no inbound webhooks).
- Must use Slack Block Kit for formatting.
- Respects Slack's 1 message/sec/channel rate limit by batching rapid updates.
- Uses dedicated threads to keep main channels clean.

### User Stories

**Story 4.1: Alert Matching & Notification**
*As an on-call engineer (Riley), I want a Slack message with the relevant runbook when an alert fires, so that I don't have to search for it.*
- **Acceptance Criteria:**
  - Integrates with PagerDuty/OpsGenie webhook payloads.
  - Matches alert context (service, region, keywords) to the most relevant runbook.
  - Posts a `🔔 Runbook matched` message with [▶ Start Copilot] button in the incident channel.
- **Story Points:** 3
- **Dependencies:** None

**Story 4.2: Step-by-Step Interactive UI**
*As an on-call engineer (Riley), I want the bot to guide me through the runbook step-by-step in a thread, so that I can focus on one command at a time.*
- **Acceptance Criteria:**
  - Tapping [▶ Start Copilot] opens a thread and triggers the Execution Engine.
  - Shows 🟢 steps auto-executing with live stdout snippets.
  - Shows 🟡/🔴 steps awaiting approval with command details and rollback.
  - Includes [⏭ Skip] and [🛑 Abort] buttons for every step.
- **Story Points:** 5
- **Dependencies:** 3.1, 4.1

**Story 4.3: Risk-Aware Approval Gates**
*As a system, I want to block dangerous commands until explicit confirmation is provided, so that accidental misclicks don't cause outages.*
- **Acceptance Criteria:**
  - 🟡 steps require clicking [✅ Approve] or [✏️ Edit].
  - 🔴 steps require opening a text input modal and typing the resource name exactly.
  - Cannot bulk-approve steps. Each step must be individually gated.
  - Approver's Slack identity is captured and passed to the Execution Engine.
- **Story Points:** 3
- **Dependencies:** 4.2

**Story 4.4: Real-Time Output Streaming**
*As an on-call engineer (Riley), I want to see the execution output of commands in real-time, so that I know what's happening.*
- **Acceptance Criteria:**
  - Slack messages update dynamically with command stdout/stderr.
  - Batches rapid output updates to respect Slack rate limits.
  - Truncates long outputs and provides a link to the full log in the dashboard.
- **Story Points:** 2
- **Dependencies:** 4.2

## Epic 5: Audit Trail
**Description:** The compliance backbone and forensic record. An append-only, immutable, partitioned PostgreSQL log that tracks every runbook parse, classification, approval, execution, and rollback.

**Dependencies:** Epics 2, 3, 4 (needs events to log)

**Technical Notes:** 
- PostgreSQL partitioned table (by month) for query performance.
- Application role must have `INSERT` and `SELECT` only. No `UPDATE` or `DELETE` grants.
- Row-Level Security (RLS) enforces tenant isolation at the database level.
- V1 includes a basic PDF/CSV export for SOC 2 readiness.

### User Stories

**Story 5.1: Append-Only Audit Schema**
*As a system, I want a partitioned database table to store all execution events immutably, so that no one can tamper with the forensic record.*
- **Acceptance Criteria:**
  - Creates a PostgreSQL table partitioned by month.
  - Revokes `UPDATE` and `DELETE` grants from the application role.
  - Schema captures `tenant_id`, `event_type`, `execution_id`, `actor_id`, `event_data` (JSONB), and `created_at`.
- **Story Points:** 2
- **Dependencies:** None

**Story 5.2: Event Ingestion Pipeline**
*As an SRE manager (Jordan), I want every action recorded in real-time, so that I know exactly who did what during an incident.*
- **Acceptance Criteria:**
  - Ingests events from Parser, Classifier, Execution Engine, and Slack Bot.
  - Logs `runbook.parsed`, `runbook.classified`, `step.auto_executed`, `step.approved`, `step.executed`, etc., exactly as architected.
  - Captures the exact command executed, exit code, and stdout/stderr hashes.
- **Story Points:** 3
- **Dependencies:** 5.1

**Story 5.3: Compliance Export**
*As an SRE manager (Jordan), I want to export timestamped execution logs, so that I can provide evidence to SOC 2 auditors.*
- **Acceptance Criteria:**
  - Generates a PDF or CSV of an execution run, including the approval chain and audit trail.
  - Includes risk classifications and any divergence/modifications made by the engineer.
  - Links to S3 for full stdout/stderr logs if needed.
- **Story Points:** 3
- **Dependencies:** 5.2

**Story 5.4: Multi-Tenant Data Isolation (RLS)**
*As a system, I want to ensure no tenant can see another tenant's data, so that security boundaries are guaranteed at the database level.*
- **Acceptance Criteria:**
  - Enables Row-Level Security (RLS) on all tenant-scoped tables (`runbooks`, `executions`, `audit_events`).
  - API middleware sets `app.current_tenant_id` session variable on every database connection.
  - Cross-tenant queries return zero rows, not an error.
- **Story Points:** 2
- **Dependencies:** 5.1

## Epic 6: Dashboard API
**Description:** The control plane REST API served by the dd0c API Gateway. Handles runbook CRUD, parsing endpoints, execution history, and integration with the Alert-Runbook Matcher. Provides the backend for the Dashboard UI and external integrations.

**Dependencies:** Epics 1, 3, 5

**Technical Notes:** 
- Served via Axum (Rust) and secured with JWT.
- Integrates with the shared dd0c API Gateway.
- Enforces tenant isolation (RLS) on every request.

### User Stories

**Story 6.1: Runbook CRUD & Parsing Endpoints**
*As a runbook author (Morgan), I want to create, read, update, and soft-delete runbooks via a REST API, so that I can manage my team's active runbooks.*
- **Acceptance Criteria:**
  - Implements `POST /runbooks` (paste raw text → auto-parse), `GET /runbooks`, `GET /runbooks/:id/versions`, `PUT /runbooks/:id`, `DELETE /runbooks/:id`.
  - Implements `POST /runbooks/parse-preview` for the 5-second wow moment (parses without saving).
  - Returns 422 if parsing fails.
- **Story Points:** 3
- **Dependencies:** 1.2

**Story 6.2: Execution History & Status Queries**
*As an SRE manager (Jordan), I want to view active and completed execution runs, so that I can monitor incident response times and skipped steps.*
- **Acceptance Criteria:**
  - Implements `POST /executions` to start copilot manually.
  - Implements `GET /executions` and `GET /executions/:id` to retrieve status, steps, exit codes, and durations.
  - Implements `GET /executions/:id/divergence` to get the post-execution analysis (skipped steps, modified commands).
- **Story Points:** 2
- **Dependencies:** 3.1, 5.2

**Story 6.3: Alert-Runbook Matcher Integration**
*As a system, I want to match incoming webhooks (e.g., PagerDuty) to the correct runbook, so that the Slack bot can post the runbook immediately.*
- **Acceptance Criteria:**
  - Implements `POST /webhooks/pagerduty`, `POST /webhooks/opsgenie`, and `POST /webhooks/dd0c-alert`.
  - Uses keyword + metadata matching (and optionally pgvector similarity) to find the best runbook for the alert payload.
  - Generates the `alert_context` and triggers the Slack bot notification (Epic 4).
- **Story Points:** 3
- **Dependencies:** 6.1

**Story 6.4: Classification Query Endpoints**
*As a runbook author (Morgan), I want to query the classification engine directly, so that I can test commands before publishing a runbook.*
- **Acceptance Criteria:**
  - Implements `POST /classify` for testing/debugging.
  - Implements `GET /classifications/:step_id` to retrieve full classification details.
  - Rate-limited to 30 req/min per tenant.
- **Story Points:** 1
- **Dependencies:** 2.3

## Epic 7: Dashboard UI
**Description:** A React Single-Page Application (SPA) for runbook authors and managers to view runbooks, past executions, and risk classifications. The primary interface for onboarding, reviewing runbooks, and analyzing post-incident data.

**Dependencies:** Epic 6 (needs APIs to consume)

**Technical Notes:** 
- React SPA, integrates with the shared dd0c portal.
- Displays the 5-second "wow moment" parse preview.
- Must visually distinguish 🟢 Safe, 🟡 Caution, and 🔴 Dangerous commands.

### User Stories

**Story 7.1: Runbook Paste & Preview UI**
*As a runbook author (Morgan), I want to paste raw text and instantly see the parsed steps, so that I can verify the structure before saving.*
- **Acceptance Criteria:**
  - Large text area for pasting raw runbook text.
  - Calls `POST /runbooks/parse-preview` and displays the structured steps.
  - Highlights variables, prerequisites, and ambiguities.
  - Allows editing the raw text to trigger a re-parse.
- **Story Points:** 3
- **Dependencies:** 6.1

**Story 7.2: Execution Timeline & Divergence View**
*As an SRE manager (Jordan), I want to view a timeline of an incident's execution, so that I can see what was skipped or modified.*
- **Acceptance Criteria:**
  - Displays the execution run with a visual timeline of steps.
  - Shows who approved each step, the exact command executed, and the exit code.
  - Highlights divergence (skipped steps, modified commands, unlisted actions).
  - Provides a "Apply Updates" button to update the runbook based on divergence.
- **Story Points:** 5
- **Dependencies:** 6.2

**Story 7.3: Trust Level & Risk Visualization**
*As a runbook author (Morgan), I want to clearly see the risk level of each step in my runbook, so that I know what requires approval.*
- **Acceptance Criteria:**
  - Color-codes steps: 🟢 Green (Safe), 🟡 Yellow (Caution), 🔴 Red (Dangerous).
  - Clicking a risk badge shows the classification reasoning (scanner rules matched, LLM explanation).
  - Displays the runbook's overall Trust Level (0, 1, 2) and allows authorized users to change it (V1 max = 2).
- **Story Points:** 3
- **Dependencies:** 7.1

**Story 7.4: Basic Health & MTTR Dashboard**
*As an SRE manager (Jordan), I want a high-level view of my team's runbooks and execution stats, so that I can measure the value of dd0c/run.*
- **Acceptance Criteria:**
  - Displays a list of runbooks, their coverage, and average staleness.
  - Shows MTTR (Mean Time To Resolution) for incidents handled via Copilot.
  - Displays the total number of Copilot runs and skipped steps per month.
- **Story Points:** 2
- **Dependencies:** 6.2

## Epic 8: Infrastructure & DevOps
**Description:** The foundational cloud infrastructure and CI/CD pipelines required to run the dd0c/run SaaS platform and build the customer-facing Agent. Ensures strict security isolation (mTLS), observability, and zero-downtime ECS Fargate deployments.

**Dependencies:** None (can be built in parallel with Epic 1).

**Technical Notes:** 
- All infrastructure defined as code (Terraform) and deployed to AWS.
- ECS Fargate for all core services (Parser, Classifier, Engine, APIs).
- Agent binary built for Linux x86_64 and ARM64 via GitHub Actions.
- mTLS certificate generation and rotation pipeline for Agent authentication.

### User Stories

**Story 8.1: Core AWS Infrastructure Provisioning**
*As a system administrator (Brian), I want the base AWS infrastructure provisioned via Terraform, so that the services have a secure, scalable environment to run in.*
- **Acceptance Criteria:**
  - Terraform configures VPC, public/private subnets, NAT Gateway, and ALB.
  - Provisions RDS PostgreSQL 16 (Multi-AZ) with pgvector and S3 buckets for audit/logs.
  - Provisions ECS Fargate cluster and SQS queues.
- **Story Points:** 3
- **Dependencies:** None

**Story 8.2: CI/CD Pipeline & Agent Build**
*As a developer (Brian), I want automated build and deployment pipelines, so that I can ship code to production safely and distribute the Agent binary.*
- **Acceptance Criteria:**
  - GitHub Actions pipeline runs `cargo clippy`, `cargo test`, and the "canary test suite" on every PR.
  - Merges to `main` auto-deploy ECS Fargate services with zero downtime.
  - Release tags compile the Agent binary (x86_64, aarch64), sign it, and publish to GitHub Releases / S3.
- **Story Points:** 3
- **Dependencies:** None

**Story 8.3: Agent mTLS & gRPC Setup**
*As a system, I want secure outbound-only gRPC communication between the Agent and the Execution Engine, so that commands are transmitted safely without VPNs or inbound firewall rules.*
- **Acceptance Criteria:**
  - Internal CA issues tenant-scoped mTLS certificates.
  - API Gateway terminates mTLS and validates the tenant ID in the certificate against the request.
  - Agent successfully establishes a persistent, outbound-only gRPC stream to the Engine.
- **Story Points:** 5
- **Dependencies:** 8.1

**Story 8.4: Observability & Party Mode Alerting**
*As the solo on-call engineer (Brian), I want comprehensive monitoring and alerting, so that I am woken up if a safety invariant is violated (Party Mode).*
- **Acceptance Criteria:**
  - OpenTelemetry (OTEL) collector deployed and routing metrics/traces to Grafana Cloud.
  - PagerDuty integration configured for P1 alerts.
  - Alert fires immediately if the "Party Mode" database flag is set or if Agent heartbeats drop unexpectedly.
- **Story Points:** 2
- **Dependencies:** 8.1

## Epic 9: Onboarding & PLG
**Description:** Product-Led Growth (PLG) and frictionless onboarding. Focuses on the "5-second wow moment" where a user can paste a runbook and instantly see the parsed, classified steps without installing an agent, plus a self-serve tier to capture leads.

**Dependencies:** Epics 1, 6, 7.

**Technical Notes:** 
- The demo uses the `POST /runbooks/parse-preview` endpoint (does not persist data).
- Tenant provisioning must be fully automated upon signup.
- Free tier enforced via database limits (no Stripe required initially for free tier).

### User Stories

**Story 9.1: The 5-Second Interactive Demo**
*As a prospective customer, I want to paste my messy runbook into the marketing website and see it parsed instantly, so that I immediately understand the product's value without signing up.*
- **Acceptance Criteria:**
  - Landing page features a prominent text area for pasting a runbook.
  - Submitting calls the unauthenticated parse-preview endpoint (rate-limited by IP).
  - Renders the structured steps with 🟢/🟡/🔴 risk badges dynamically.
- **Story Points:** 3
- **Dependencies:** 6.1, 7.1

**Story 9.2: Self-Serve Signup & Tenant Provisioning**
*As a new user, I want to create an account and get my tenant provisioned instantly, so that I can start using the product without talking to sales.*
- **Acceptance Criteria:**
  - OAuth/Email signup flow creates a User and a Tenant record in PostgreSQL.
  - Automated worker initializes the tenant workspace, generates the initial mTLS certs, and provides the Agent installation command.
  - Limits the free tier to 5 active runbooks and 50 executions/month.
- **Story Points:** 3
- **Dependencies:** 8.1

**Story 9.3: Agent Installation Wizard**
*As a new user, I want a simple copy-paste command to install the read-only Agent in my infrastructure, so that I can execute my first runbook within 10 minutes of signup.*
- **Acceptance Criteria:**
  - Dashboard provides a dynamically generated `curl | bash` or `kubectl apply` snippet.
  - Snippet includes the tenant-specific mTLS certificate and Agent binary download.
  - Dashboard shows a live "Waiting for Agent heartbeat..." state that turns green when the Agent connects.
- **Story Points:** 3
- **Dependencies:** 8.3, 9.2

**Story 9.4: First Runbook Copilot Walkthrough**
*As a new user, I want an interactive guide for my first runbook execution, so that I learn how the Copilot approval flow and Trust Gradient work safely.*
- **Acceptance Criteria:**
  - System automatically provisions a "Hello World" runbook containing safe read-only commands (e.g., `kubectl get nodes`).
  - In-app tooltip guides the user to trigger the runbook via the Slack integration.
  - Completing this first execution unlocks the "Runbook Author" badge/status.
- **Story Points:** 2
- **Dependencies:** 4.2, 9.3


---

## Epic 10: Transparent Factory Compliance
**Description:** Cross-cutting epic ensuring dd0c/run adheres to the 5 Transparent Factory tenets. Of all 6 dd0c products, runbook automation carries the highest governance burden — it executes commands in production infrastructure. Every tenet here is load-bearing.

### Story 10.1: Atomic Flagging — Feature Flags for Execution Behaviors
**As a** solo founder, **I want** every new runbook execution capability, command parser, and auto-remediation behavior behind a feature flag (default: off), **so that** a bad parser change never executes the wrong command in a customer's production environment.

**Acceptance Criteria:**
- OpenFeature SDK integrated into the execution engine. V1: JSON file provider.
- All flags evaluate locally — no network calls during runbook execution.
- Every flag has `owner` and `ttl` (max 14 days). CI blocks if expired flags remain at 100%.
- Automated circuit breaker: if a flagged execution path fails >2 times in any 10-minute window, the flag auto-disables and all in-flight executions using that path are paused (not killed).
- Flags required for: new command parsers, conditional logic handlers, new infrastructure targets (K8s, AWS, bare metal), auto-retry behaviors, approval bypass rules.
- **Hard rule:** any flag that controls execution of destructive commands (`rm`, `delete`, `terminate`, `drop`) requires a 48-hour bake time at 10% rollout before full enablement.

**Estimate:** 5 points
**Dependencies:** Epic 3 (Execution Engine)
**Technical Notes:**
- Circuit breaker threshold is intentionally low (2 failures) because production execution failures are high-severity.
- Pause vs. kill: paused executions hold state and can be resumed after review. Killing mid-execution risks partial state.
- 48-hour bake for destructive flags: enforced via flag metadata `destructive: true` + CI check.

### Story 10.2: Elastic Schema — Additive-Only for Execution Audit Trail
**As a** solo founder, **I want** all execution log and runbook state schema changes to be strictly additive, **so that** the forensic audit trail of every production command ever executed is never corrupted or lost.

**Acceptance Criteria:**
- CI rejects any migration that removes, renames, or changes type of existing columns/attributes.
- New fields use `_v2` suffix for breaking changes.
- All execution log parsers ignore unknown fields.
- Dual-write during migration windows within the same transaction.
- Every migration includes `sunset_date` comment (max 30 days).
- **Hard rule:** execution audit records are immutable. No `UPDATE` or `DELETE` statements are permitted on the `execution_log` table/collection. Ever.

**Estimate:** 3 points
**Dependencies:** Epic 4 (Audit & Forensics)
**Technical Notes:**
- Execution logs are append-only by design and by policy. Use DynamoDB with no `UpdateItem` IAM permission on the audit table.
- For runbook definition versioning: every edit creates a new version record. Old versions are never mutated.
- Schema for parsed runbook steps: version the parser output format. V1 steps and V2 steps coexist.

### Story 10.3: Cognitive Durability — Decision Logs for Execution Logic
**As a** future maintainer, **I want** every change to runbook parsing, step classification, or execution logic accompanied by a `decision_log.json`, **so that** I understand why the system interpreted step 3 as "destructive" and required approval.

**Acceptance Criteria:**
- `decision_log.json` schema: `{ prompt, reasoning, alternatives_considered, confidence, timestamp, author }`.
- CI requires a decision log for PRs touching `pkg/parser/`, `pkg/classifier/`, `pkg/executor/`, or `pkg/approval/`.
- Cyclomatic complexity cap of 10 enforced via linter. PRs exceeding this are blocked.
- Decision logs in `docs/decisions/`.
- **Additional requirement:** every change to the "destructive command" classification list requires a decision log entry explaining why the command was added/removed.

**Estimate:** 2 points
**Dependencies:** None
**Technical Notes:**
- The destructive command list is the most sensitive config in the entire product. Changes must be documented, reviewed, and logged.
- Parser logic decision logs should include sample runbook snippets showing before/after interpretation.

### Story 10.4: Semantic Observability — AI Reasoning Spans on Classification & Execution
**As an** SRE manager investigating an incident caused by automated execution, **I want** every runbook classification and execution decision to emit an OpenTelemetry span with full reasoning metadata, **so that** I have a complete forensic record of what the system decided, why, and what it executed.

**Acceptance Criteria:**
- Every runbook execution creates a parent `runbook_execution` span. Child spans for each step: `step_classification`, `step_approval_check`, `step_execution`.
- `step_classification` attributes: `step.text_hash`, `step.classified_as` (safe/destructive/ambiguous), `step.confidence_score`, `step.alternatives_considered`.
- `step_execution` attributes: `step.command_hash`, `step.target_host_hash`, `step.exit_code`, `step.duration_ms`, `step.output_truncated` (first 500 chars, hashed).
- If AI-assisted classification: `ai.prompt_hash`, `ai.model_version`, `ai.reasoning_chain`.
- `step_approval_check` attributes: `step.approval_required` (bool), `step.approval_source` (human/policy/auto), `step.approval_latency_ms`.
- No PII. No raw commands in spans — everything hashed. Full commands only in the encrypted audit log.

**Estimate:** 5 points
**Dependencies:** Epic 3 (Execution Engine), Epic 4 (Audit & Forensics)
**Technical Notes:**
- This is the highest-effort observability story across all 6 products because execution tracing is forensic-grade.
- Span hierarchy: `runbook_execution` → `step_N` → `[classification, approval, execution]`. Three levels deep.
- Output hashing: SHA-256 of command output for correlation. Raw output only in encrypted audit store.

### Story 10.5: Configurable Autonomy — Governance for Production Execution
**As a** solo founder, **I want** a `policy.json` that strictly controls what dd0c/run is allowed to execute autonomously vs. what requires human approval, **so that** no automated system ever runs a destructive command without explicit authorization.

**Acceptance Criteria:**
- `policy.json` defines `governance_mode`: `strict` (all steps require human approval) or `audit` (safe steps auto-execute, destructive steps require approval).
- Default for ALL customers: `strict`. There is no "fully autonomous" mode for dd0c/run. Even in `audit` mode, destructive commands always require approval.
- `panic_mode`: when true, ALL execution halts immediately. In-flight steps are paused (not killed). All pending approvals are revoked. System enters read-only forensic mode.
- Governance drift monitoring: weekly report of auto-executed vs. human-approved steps. If auto-execution ratio exceeds the configured threshold, system auto-downgrades to `strict`.
- Per-customer, per-runbook governance overrides. Customers can lock specific runbooks to `strict` regardless of system mode.
- **Hard rule:** `panic_mode` must be triggerable in <1 second via API call, CLI command, Slack command, OR a physical hardware button (webhook endpoint).

**Estimate:** 5 points
**Dependencies:** Epic 3 (Execution Engine), Epic 5 (Approval Workflow)
**Technical Notes:**
- No "full auto" mode is a deliberate product decision. dd0c/run assists humans, it doesn't replace them for destructive actions.
- Panic mode implementation: Redis key `dd0c:panic` checked at the top of every execution loop iteration. Webhook endpoint `POST /admin/panic` sets the key and broadcasts a halt signal via pub/sub.
- The <1 second requirement means panic cannot depend on a DB write — Redis pub/sub only.
- Governance drift: cron job queries execution logs weekly. Threshold configurable per-org (default: 70% auto-execution triggers downgrade).

### Epic 10 Summary
| Story | Tenet | Points |
|-------|-------|--------|
| 10.1 | Atomic Flagging | 5 |
| 10.2 | Elastic Schema | 3 |
| 10.3 | Cognitive Durability | 2 |
| 10.4 | Semantic Observability | 5 |
| 10.5 | Configurable Autonomy | 5 |
| **Total** | | **20** |