/moraine-sandbox-qa

name: moraine-sandbox-qa
description: Run isolated Moraine dev sandbox validation. Use when testing ingest, MCP, monitor, ClickHouse schema, source formats, stack behavior, or any change where QA must not touch the developer's host ~/.moraine install; use before reporting completion for stack-facing changes.

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.