fix(hyperframes_compose): stop scaffolding over hand-authored compositions

[hubooy]

Summary

hyperframes_compose's compose operation always scaffolds index.html from edit_decisions. In atelier mode index.html is the deliverable — hand-authored for that one piece — so scaffolding overwrites the composition it is about to render.

This adds preserve_workspace to render what is already on disk instead of regenerating it.

Related issue

None — filing the fix directly.

Changes

• New preserve_workspace boolean input (default false, so existing behavior is unchanged). When true, scaffolding is skipped and the workspace's existing index.html is rendered.
• lint and validate still run in preserve mode, so output stays gated by the same contract checks.
• preserve_workspace joins idempotency_key_fields: without it, a scaffolded run and a preserved run of the same edit_decisions would collide on one cache key.
• preserve_workspace=true with no index.html in the workspace fails with an actionable error rather than rendering a blank composition.

Testing

• python -m pytest tests/contracts/ -q — 630 passed, 7 skipped.

• python -m pytest tests/tools/test_hyperframes_compose.py -q — 46 passed.

• Guard verified directly: render with preserve_workspace=true against a workspace containing no index.html returns

  preserve_workspace=true but no index.html in <path>. Hand-author the composition first, or drop the flag to scaffold.
  

• Cache-key separation verified: idempotency_key() returns different keys for preserve_workspace true vs false on otherwise identical inputs.

• Not verified: a full atelier render end-to-end, which needs a real hand-authored composition and npx hyperframes on the machine. The scaffold-skip and guard paths above are what this diff changes.

Checklist

• The change is focused on a single logical concern.
• I ran the relevant tests locally (make test-contracts / make test) where applicable.
• I updated docs/README if behavior or usage changed. — the new input is documented in the tool's input_schema.
• No unrelated files (build artifacts, local config) are included in the diff.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GYThSL15CujvBwD1wuUmr9