eric-tramel/moraine/moraine-sandbox-qa

Moraine Sandbox QA

Overview

Use the dev sandbox for stack-facing QA so validation runs against an isolated Moraine state directory and sibling ClickHouse service instead of the host install.

When To Use

Use this workflow for changes touching:

• crates/moraine-ingest-core/, ingest source formats, or fixtures.
• crates/moraine-mcp-core/, apps/moraine-mcp/, or MCP tool behavior.
• crates/moraine-monitor-core/, apps/moraine-monitor/, or web/monitor/.
• sql/, ClickHouse migrations, config templates, or stack lifecycle behavior.
• Release or smoke-test work that needs end-to-end behavior.

For docs-only or narrow metadata changes, normal local checks are usually enough.

Boot

Boot from the authoritative worktree for the change. Use --quiet; do not pipe moraine-sandbox up through tail or head.

id=$(scripts/dev/sandbox/moraine-sandbox up --quiet)
echo "sandbox: $id"
scripts/dev/sandbox/moraine-sandbox status "$id"

If you spawned from an isolation worktree, compare with the parent or sibling feature worktree first. Boot the sandbox from the worktree that contains the actual in-progress code.

Validate

Use the sandbox shell for cargo and stack checks:

scripts/dev/sandbox/moraine-sandbox shell "$id"
cd /repo
cargo fmt --all -- --check
cargo test -p <crate> --locked
cargo test --workspace --locked
cargo clippy --workspace --all-targets -- -D warnings

Choose focused tests first, then broaden according to risk. For changes that affect ingest, MCP, monitor routes, or schema behavior, run the functional stack smoke test when feasible:

bash scripts/ci/e2e-stack.sh

Check the monitor health endpoint using the sandbox-reported port:

port=$(scripts/dev/sandbox/moraine-sandbox status "$id" | awk -F: '/^\[sandbox\] monitor/{print $NF}')
curl -fsS "http://127.0.0.1:${port}/api/v1/health"

For MCP tool surface changes or release-level confidence, consider scripts/dev/sandbox/agent-smoke-e2e --help. It requires ANTHROPIC_API_KEY.

Teardown

Always tear down the sandbox before reporting the task complete:

scripts/dev/sandbox/moraine-sandbox down "$id"

Final reporting should include the sandbox id, commands run, outcomes, and confirmation that down "$id" succeeded. If sandbox QA was expected but not run, explain why.