# Requirements Archive: v1.0 MVP

**Archived:** 2026-03-24
**Status:** SHIPPED

For current requirements, see `.planning/REQUIREMENTS.md`.

---

# Requirements: vmcluster-mcp

**Defined:** 2026-03-22
**Core Value:** Agents can provision and reset realistic multi-node VM clusters end-to-end without requiring human intervention.

## v1 Requirements

Requirements for initial release. Each maps to roadmap phases.

### Foundation

- [x] **FOUND-01**: Server starts via `python -m vmcluster_mcp.server` and accepts MCP stdio connections.
- [x] **FOUND-02**: All tool results are returned as structured `ToolResult[T]` — no raw exceptions reach the agent.
- [x] **FOUND-03**: Server configuration is loadable from `/etc/vmcluster/config.yaml` or environment variables.
- [x] **FOUND-04**: YAML topology files are parsed and validated, with clear schema errors on malformed input.

### Cluster Lifecycle

- [x] **CLUS-01**: Agent can define a cluster from a named topology file (creates libvirt domain definitions and overlay disks without booting).
- [x] **CLUS-02**: Agent can start all nodes in a cluster and optionally wait for SSH reachability.
- [x] **CLUS-03**: Agent can stop all nodes gracefully (shutdown) or forcibly (destroy).
- [x] **CLUS-04**: Agent can destroy a cluster and optionally remove overlay disk images.
- [x] **CLUS-05**: Agent can query current status of all nodes (domain state, SSH reachability, installed artifact).
- [x] **CLUS-06**: Agent can obtain a `ClusterHandle` descriptor for downstream direct-SSH consumers.
- [x] **CLUS-07**: `cluster_define` is idempotent — safe to call on an already-defined cluster.

### SSH Execution

- [x] **EXEC-01**: Agent can run a shell command on a single node and receive structured output (exit code, stdout, stderr, duration).
- [x] **EXEC-02**: Agent can run the same command across all or a subset of nodes, in parallel or sequentially.
- [x] **EXEC-03**: SSH connections are reestablished automatically after a node reboot (snapshot revert or node_crash).

### Snapshot Management

- [x] **SNAP-01**: Agent can create a named disk snapshot of all cluster nodes simultaneously.
- [x] **SNAP-02**: Agent can revert all nodes to a named snapshot atomically and optionally restart and wait for SSH.
- [x] **SNAP-03**: Agent can list all snapshots for a cluster with creation time and size.
- [x] **SNAP-04**: Agent can delete a named snapshot from all nodes.

### Artifact Management

- [x] **ART-01**: Agent can register a local build tree as a content-addressed artifact (sha256 of tree content).
- [x] **ART-02**: Agent can sync a registered artifact to cluster nodes via rsync, skipping nodes where it is already present.
- [x] **ART-03**: Agent can install a synced artifact on nodes using `modprobe_path` (default), `make_install`, `rpm`, or `deb` modes.
- [x] **ART-04**: Agent can list all registered artifacts.
- [x] **ART-05**: Agent can diff two artifacts to see which `.ko` files and binaries changed.

### Kernel Observability

- [x] **OBS-01**: Agent can insert a timestamped dmesg marker on nodes before an operation.
- [x] **OBS-02**: Agent can collect structured dmesg output from nodes since a named marker, filtered by log level.
- [x] **OBS-03**: Collected dmesg is classified for oops, panics, KASAN/UBSAN events, and warnings.

### Fault Injection

- [x] **FAULT-01**: Agent can partition a cluster into two groups by installing iptables DROP rules on the bridge.
- [x] **FAULT-02**: Agent can apply `tc netem` impairment to egress traffic between specific nodes (latency, jitter, loss, corruption).
- [x] **FAULT-03**: Agent can heal a specific network fault by handle ID.
- [x] **FAULT-04**: Agent can heal all active network faults for a cluster.
- [x] **FAULT-05**: Agent can list all currently active network faults.
- [x] **FAULT-06**: Agent can hard-reset a node (virsh destroy + start) to simulate unclean failure.
- [x] **FAULT-07**: Active fault state survives MCP server restart (persisted to disk, not in-memory only).

## v2 Requirements

Deferred to future release. Tracked but not in current roadmap.

### Extended Artifact Support

- **ART-V2-01**: Agent can trigger a local build (`configure` + `make`) and register the resulting artifact automatically.
- **ART-V2-02**: Structured compiler error extraction (file, line, column, message) from build output.

### Observability Enhancements

- **OBS-V2-01**: Agent can collect per-node CPU/memory/disk metrics over a time window.
- **OBS-V2-02**: Agent can stream dmesg in real time during a test run.

### Multi-User / Team Support

- **TEAM-01**: Multiple concurrent MCP clients can manage independent clusters without interference.
- **TEAM-02**: Role-based access control for cluster operations.

### RDMA Support

- **RDMA-01**: Topology can provision soft-RoCE (rxe) on the virtual bridge for RDMA testing.

### Performance

- **PERF-01**: SSH connection pooling with configurable pool size per cluster.
- **PERF-02**: Parallel snapshot creation using libvirt async jobs rather than sequential.

## Out of Scope

Explicitly excluded from v1. Documented to prevent scope creep.

| Feature | Reason |
|---------|--------|
| Application-specific cluster configuration | Downstream consumers handle app/domain setup via ClusterHandle; this server is infrastructure-only |
| Runtime orchestration after ClusterHandle handoff | Downstream tools SSH directly; no callback into this server at runtime |
| Full RDMA / o2ib provisioning | Implementation complexity; deferred to v2 |
| In-memory SSH connection pooling | v1 correctness-first; pooling deferred until performance data justifies it |
| Multi-user RBAC | v1 targets solo developer use; team features deferred |
| `artifact_build` (local build trigger) | Agents can build externally and register via `artifact_register`; deferred to v2 |
| Memory-state snapshots as default | External disk-only snapshots are the baseline; memory dumps are an option but not default |
| Web UI or dashboard | Pure MCP stdio interface; no GUI in v1 |

## Traceability

Populated during roadmap creation — 2026-03-22.

| Requirement | Phase | Status |
|-------------|-------|--------|
| FOUND-01 | Phase 1: Foundation | Complete |
| FOUND-02 | Phase 1: Foundation | Complete |
| FOUND-03 | Phase 1: Foundation | Complete |
| FOUND-04 | Phase 1: Foundation | Complete |
| CLUS-01 | Phase 2: Core VM Lifecycle → Phase 8: Retroactive Verification | Complete |
| CLUS-02 | Phase 2: Core VM Lifecycle → Phase 8: Retroactive Verification | Complete |
| CLUS-03 | Phase 2: Core VM Lifecycle → Phase 8: Retroactive Verification | Complete |
| CLUS-04 | Phase 2: Core VM Lifecycle → Phase 8: Retroactive Verification | Complete |
| CLUS-05 | Phase 2: Core VM Lifecycle → Phase 8: Retroactive Verification | Complete |
| CLUS-06 | Phase 2: Core VM Lifecycle → Phase 8: Retroactive Verification | Complete |
| CLUS-07 | Phase 2: Core VM Lifecycle → Phase 8: Retroactive Verification | Complete |
| EXEC-01 | Phase 3: SSH Execution → Phase 8: Retroactive Verification | Complete |
| EXEC-02 | Phase 3: SSH Execution → Phase 8: Retroactive Verification | Complete |
| EXEC-03 | Phase 3: SSH Execution → Phase 8: Retroactive Verification | Complete |
| SNAP-01 | Phase 4: Snapshot Management | Complete |
| SNAP-02 | Phase 4: Snapshot Management | Complete |
| SNAP-03 | Phase 4: Snapshot Management | Complete |
| SNAP-04 | Phase 4: Snapshot Management | Complete |
| ART-01 | Phase 5: Artifact Pipeline | Complete |
| ART-02 | Phase 5: Artifact Pipeline | Complete |
| ART-03 | Phase 5: Artifact Pipeline | Complete |
| ART-04 | Phase 5: Artifact Pipeline | Complete |
| ART-05 | Phase 5: Artifact Pipeline | Complete |
| OBS-01 | Phase 6: Kernel Observability | Complete |
| OBS-02 | Phase 6: Kernel Observability | Complete |
| OBS-03 | Phase 6: Kernel Observability | Complete |
| FAULT-01 | Phase 7: Network & Node Fault Injection | Complete |
| FAULT-02 | Phase 7: Network & Node Fault Injection | Complete |
| FAULT-03 | Phase 7: Network & Node Fault Injection | Complete |
| FAULT-04 | Phase 7: Network & Node Fault Injection | Complete |
| FAULT-05 | Phase 7: Network & Node Fault Injection | Complete |
| FAULT-06 | Phase 7: Network & Node Fault Injection | Complete |
| FAULT-07 | Phase 7: Network & Node Fault Injection | Complete |

**Coverage:**
- v1 requirements: 33 total
- Mapped to phases: 33
- Unmapped: 0 ✓

---
*Requirements defined: 2026-03-22*
*Last updated: 2026-03-24 — gap closure phases 8-10 added*
