Chuck MCP Layering Lab

Chuck MCP Layering Lab is a research and implementation workspace for a mokuhanga-style Block / Impression / Mask planner around the Chuck Close / Emma printmaking problem. It proposes a physically inspectable print plan; it does not claim to recover an artist's historical process from one image.

This repository is separate from emma-mokuhanga-mcp. Its source lineage began in ReidSurmeier/woodblock-reidsurmeier-wtf, but ReidSurmeier/chuck-mcp-layering-lab is the canonical repository and issue tracker for this experiment.

The current v5/v6 research path implements:

• a SNIC/cell graph and production-plan candidates;
• Mask-truth validators and progressive proof rendering;
• a hybrid optimization loop with carried-forward state;
• an MCP stdio surface for planning, inspection, scoring, and export; and
• research fixtures, reference notes, and human Review previews.

The latest retained iter-13 result is a known failing baseline. It proves useful plumbing, but its sparse dot-cell buildup is not a plausible mokuhanga methodology. The next accepted result must begin with connected carved-region Masks and pass the visual Methodology gate before color telemetry counts as progress.

The repository is not deployed. It has no GitHub Pages site or owned Droplet runtime. The inherited Next.js color-separator frontend remains a dormant prototype scaffold; its package metadata and routes are not evidence of a Chuck service.

See PROJECT.md for the operational resume point, CONTEXT.md for domain language, and docs/adr for accepted decisions.

V1 is a visually plausible mokuhanga Block / Impression / proof plan:

• validators score authoritative Masks and proof states, not contact-sheet pixels;
• Order and proof progression read as incremental woodblock printing;
• Mask geometry is connected and separable enough for jigsaw carving;
• Underprints are designed support structures, not inferred physical evidence;
• mirrored Block previews and normal-orientation proofs remain distinct; and
• final-match delta E remains telemetry until Overprint calibration exists.

Python 3.12 is the verified development version. Use a local virtual environment and choose CPU or CUDA solver dependencies for the host:

python3.12 -m venv .venv-renderer
. .venv-renderer/bin/activate
python -m pip install -e ".[solver-cpu,mcp,io,viz,dev]"

For a compatible CUDA host, install the solver extra instead of solver-cpu, then verify the backend before running an expensive solve:

python - <<'PY'
import jax
print(jax.__version__)
print(jax.default_backend())
print(jax.devices())
PY

The portable CI boundary is:

python -m pytest -q tests/test_repository_contract.py backend/tests/v23/scaffold
ruff check backend/mcp backend/services/v23 backend/tests/v23 tests
python -m compileall -q backend chuck_mcp_v2 tests

With the solver, image, and visualization extras installed, run the active research tests:

python -m pytest -q research/v3-construction/validators-reconstruction
python -m pytest -q research/v4-build/hybrid-optimizer
python -m pytest -q research/v5-overnight/loop-runner

These suites use repository fixtures. Full-size inputs, generated iterations, Review previews, and CNC handoff artifacts belong outside Git and must be supplied through explicit command arguments.

The stdio registry in backend/mcp/registry.py exposes these main families:

• stack proposal and inspection;
• pigment and Render-tier introspection;
• cell and printability review; and
• production planning and diagnostic export.

Run the server after installing the package:

chuck-layering-mcp

Treat exported SVG and ZIP artifacts as experimental diagnostics until a physical print series verifies carving, registration, transfer, pigment, and paper tolerances.

GitHub Issues in ReidSurmeier/chuck-mcp-layering-lab own the PRD and implementation slices. Issue #4, connected carved-region Mask topology, is the next engineering slice. Issues #3, #5, and #7 own output custody, semantic Underprint scoring, and empirical Overprint calibration respectively.

Useful evidence:

• research/v6-methodology-reset/README.md
• research/v6-methodology-reset/VISUAL_BASELINE_REJECTION.md
• docs/diagnosis/2026-05-17-v5-validator-and-outer-loop.md
• docs/architecture/deepening-opportunities-2026-05-17.md
• docs/audit-response-and-reconstruction-plan-2026-05-17.md
• research/v5-overnight/loop-runner/FINAL_REPORT.md

MIT. See LICENSE.