parallax: Instructions file for Claude Code

Parallax — project instructions

Render-in-the-loop self-verification primitive for coding agents + a factorial-decomposition study of why it works. Part of the SunnyCode workspace.

Status

M1 (library MVP) usable. The crosscheck primitive runs end-to-end with two adapters (SQL-result-shape, regex-highlight), an offline heuristic critic + an Anthropic vision critic, a CLI (parallax), and an MCP server (parallax-mcp). The full design package lives in docs/; start from docs/TASKS.md (TDD-first, split into M1 library MVP and M2 study). Read docs/EVAL.md before touching any eval code and docs/RED-TEAM.md to understand why the design is shaped the way it is. M2 (the factorial study) is not started.

Names & handles

• Brand: Parallax · PyPI/npm dist: parallax-verify · import package: parallax · repo: sani-savaliya/parallax
• API function: crosscheck(artifact, render_fn) (kept deliberately — only the product name changed away from the collision-heavy "crosscheck").
• Domains available if wanted: parallaxverify.com, parallax.sh.

Build & test (planned)

• Language: Python. Package layout src/parallax/, tests/, pyproject.toml, ruff + mypy.
• TDD is mandatory — tests before implementation, 80%+ coverage (unit + integration + the eval harness has its own fixtures).
• Run tests from this project root (see docs/TASKS.md for exact commands once scaffolded).

Key design invariants (do not violate)

• Single multimodal model across all model arms — never a text-LLM vs a separate VLM (that's a sixth confound).
• The feature set F shown to model arms contains no verdict flags — only raw/derived quantities. All thresholding lives in the deterministic A5 arm, whose thresholds are disjoint from the defect-generating parameters. (This is the leak that collapsed v1.)
• Compute is measured, not gated — never abort a run on token-equality (selection on the dependent variable). Match on cost + passes + FLOP proxies; report them.
• Symmetrize tuning effort, never read-back outcome — capping the render to what the text reaches is mediator/collider adjustment that erases real effects.
• Renders sandbox-safe: DuckDB with httpfs/COPY/external-file access disabled, timeouts, no network; beware the subprocess socket-monkeypatch bypass (see docs/ARCHITECTURE.md).