whetstone_DSL/sprint112_plan.md

# Sprint 112 Plan: Environment Snapshot and Diff

## Context

Before iterating on a failing environment, you must read it deterministically.
"Environment" means the intersection of: installed packages, active config files,
running processes, and file system state that your project depends on. Without a
structured snapshot, the iteration session has no baseline to compare against and
no way to tell whether a change actually helped.

Sprint 112 adds `EnvironmentSnapshot` — a structured, serializable record of the
environment at a point in time — and `EnvironmentDiff` — the delta between two
snapshots. These are the observability primitives that the build, test, and setup
feedback loops in later sprints will use.

---

## Goals

1. Define `EnvironmentSnapshot` schema covering deps, configs, processes, and paths
2. Implement probes that read each domain from the actual system
3. Define `EnvironmentDiff` as a typed delta between two snapshots
4. Expose snapshot and diff as MCP tools
5. Produce a setup verification report (what is present vs what is needed)

---

## Steps

### Step 1349: `EnvironmentSnapshot` core schema (12 tests)

Create `editor/src/EnvironmentSnapshot.h`.

Fields: `snapshot_id`, `captured_at`, `workspace_root`, `platform`
(os, arch, shell), `packages[]` (name, version, source: apt/pip/npm/cargo/etc.),
`config_files[]` (path, hash, key_values[] for known formats),
`processes[]` (name, pid, port, status), `env_vars[]` (key, value — filtered
to relevant set, never secrets).

Tests (12): constructable with defaults, snapshot_id non-empty, platform fields
populated, packages list starts empty, config list starts empty, process list
starts empty, env_vars list starts empty, JSON serialization, JSON deserialization,
unknown package source passthrough, schema version present, deterministic output.

### Step 1350: Package state probe (10 tests)

Create `editor/src/PackageProbe.h`.

Probes installed packages from available managers on the current platform.
Strategy: try each manager (dpkg-query, pip list, npm list -g, cargo --list)
via subprocess, parse stdout into PackageRecord rows, tag with source.
Failures are non-fatal — missing manager produces empty list for that source.

Tests (10): probe runs without crashing, result is parseable, known-installed
package appears in results, unknown package absent, source tag correct,
failed probe returns empty not error, deterministic sort order, version field
populated, JSON round-trip, timeout respected (default 5s).

### Step 1351: Config file probe (10 tests)

Create `editor/src/ConfigFileProbe.h`.

Scans workspace for known config files: `.env`, `*.yaml`, `*.toml`, `*.json`
(at workspace root depth only — no deep recursion). Reads content, computes
SHA-256 hash, extracts key_values for .env and simple YAML/TOML maps.
Sensitive keys (PASSWORD, SECRET, KEY, TOKEN) are redacted to `"[REDACTED]"`.

Tests (10): .env file parsed into key_values, sensitive keys redacted,
hash computed and stable, yaml keys extracted, toml keys extracted,
json keys extracted (top-level only), missing file produces absent entry,
hash changes on content change, deterministic key ordering, depth limit
respected.

### Step 1352: Process state probe (10 tests)

Create `editor/src/ProcessProbe.h`.

Lists running processes filtered to a known-relevant set (configurable list of
process name substrings). Uses `/proc` on Linux, `ps` subprocess on macOS.
Captures name, pid, and listening ports (from `ss -tlnp` or `netstat`).

Tests (10): probe runs without crashing, result parseable, known process
appears when running, absent process not in list, port captured when listening,
no port when not listening, deterministic sort, name filter respected,
JSON round-trip, timeout respected.

### Step 1353: `EnvironmentDiff` schema and computation (10 tests)

Create `editor/src/EnvironmentDiff.h`.

Compares two `EnvironmentSnapshot` instances. Fields: `added_packages[]`,
`removed_packages[]`, `changed_packages[]` (name + old_version + new_version),
`added_configs[]`, `removed_configs[]`, `changed_configs[]` (path + old_hash
+ new_hash), `added_processes[]`, `removed_processes[]`, `unchanged` (bool —
true when all diff lists are empty).

Tests (10): empty diff on identical snapshots, unchanged true on identical,
added package detected, removed package detected, changed package detected,
added config detected, changed config hash detected, process added detected,
JSON round-trip, deterministic diff ordering.

### Step 1354: Snapshot persistence (sidecar integration) (8 tests)

Extend `SessionStore.h` (or add `SnapshotStore.h`) to persist
`EnvironmentSnapshot` alongside iteration sessions.

Convention: `.whetstone/snapshots/<snapshot_id>.json`

Tests (8): save creates file, load round-trips, list returns ids, overwrite
preserves new data, missing snapshot returns nullopt, atomic write, path
derivation correct, sidecar dir created on first save.

### Step 1355: Setup verification report (8 tests)

Create `editor/src/SetupVerificationReport.h`.

Given a `RequiredEnvironment` spec (a list of expected packages, config files,
and processes) and a current `EnvironmentSnapshot`, produces a structured report:
`satisfied[]`, `missing[]`, `version_mismatch[]`, `ready` (bool — true when
missing and version_mismatch are both empty).

Tests (8): ready true when all present, missing package detected, version
mismatch detected, correct version passes, empty required produces ready=true,
JSON round-trip, deterministic output, report serializable.

### Step 1356: `whetstone_snapshot_environment` MCP tool (8 tests)

Input: `{ "workspace": string, "process_filter": string[]? }`
Output: full `EnvironmentSnapshot` JSON + `snapshot_id`.

Runs all three probes (packages, configs, processes) and persists result.

Tests (8): tool registered, snapshot_id returned, packages field present,
configs field present, processes field present, snapshot persisted to disk,
invalid workspace returns structured error, deterministic output shape.

### Step 1357: `whetstone_diff_environments` MCP tool (8 tests)

Input: `{ "before_id": string, "after_id": string }`
Output: `EnvironmentDiff` JSON + `unchanged` bool.

Loads both snapshots from store, computes diff, returns result.

Tests (8): tool registered, unchanged true on same snapshot, added package
appears in diff, removed package appears, changed package appears, missing
snapshot_id returns error, diff persisted to session if session_id provided,
deterministic output.

### Step 1358: Sprint 112 integration summary + regression (8 tests)

Create `editor/src/Sprint112IntegrationSummary.h`.

End-to-end test: capture snapshot → mutate environment (add a dummy config
file) → capture second snapshot → diff → verify change detected.

Tests (8): headers constructable, tools registered, end-to-end diff detects
change, verification report correct, sidecar files created, no header exceeds
600 lines, deterministic snapshots, full prior regression passes.

---

## Architecture Gate

- Probes are non-fatal: subprocess failure returns empty list, not panic
- No new dependencies — subprocess via std::system or popen, parsing in C++
- Sensitive data never stored in snapshots (redaction in ConfigFileProbe)
- Max 600 lines per header
- All MCP outputs stable and machine-readable