hello-nested-worlds-adventure: Instructions file for Claude Code

Working in Enfolded

This file is the shared engineering contract for Codex, GitHub Copilot, and Claude Code. CLAUDE.md imports it for compatibility. Maintain shared rules here and in the matching skill. Use an already-loaded copy; follow task-specific pointers as needed. Supporting procedures are not required startup reading.

Enfolded is a persistent multiverse inhabited by human players and agents. The covenants below define correctness across agents and models. Use the referenced code and decisions for the area being changed; unrelated work does not require a full roadmap, CHANGELOG, or ADR review.

World covenants (the rules that never made it into a spec)

These are house taste, encoded once at a point of use and easy to break by a well-meaning change. Honour them; a reviewer would catch a violation, so catch it first.

• Every player owns their actions. Human and AI players may suggest, invite, persuade or refuse; one player cannot select another as the performer or force their consent. Check this at acceptance, not only in the interface. A model proposal is not another player's decision. Earlier recorded events stay truthful.
• Extend or replace an experience; never duplicate it. One player purpose has one interaction surface in each client. New action capabilities belong in Act, conversation in Speak, and history in its existing views. Do not add a parallel composer, quest controller, or status pane for the same function. Use progressive disclosure; no preselected action plan or compulsory story route.
• Scale is meaning, not decoration. New verbs must change real properties at their own scale; sound must distinguish scales through musical form and timbre, with within-scale differences grounded in node state. Generic operations renamed per scale or one score transposed at every level do not satisfy this contract.
• The seal never imprisons. A locked (sealed) subtree never traps someone already inside it. puzzles/gates.py (# already inside — the seal never imprisons).
• Difficulty is per-node, never a depth curve. Traversal is non-linear — players drop in at any scale — so scale sets a puzzle's flavour, never how hard it is; each node draws its own 1–4 difficulty from its identity. puzzles/generators.py (node_difficulty), README puzzle row.
• Failure stays in fiction — on every authored surface. Anything a player reads as the world's voice speaks in fiction: AI/budget/kill-switch paths return HTTP 200 with ai: false and an authored line of silence (consciousness.LEVEL_FALLBACKS, fallback_voice, guard.QUIET_RESPONSE), image failures answer the authored quiet line with images: false (handlers._IMAGE_QUIET_LINE — never "FAL_KEY not set" or a raw upstream error), and rate-limit denials carry the pace line (handlers._PACE_LINE) because both clients render error text verbatim. Transport-level refusals sit outside the fiction by scoped decision (2026-07-18 evaluation §4): the invite-gate 403, payload 413, malformed-body 400, and WS-cap 503 are plumbing a browser client never surfaces — they may stay mechanical, but must be clean JSON. What is never acceptable: a stack trace, or a 5xx for a client-shaped mistake (malformed bodies and non-string answers are the client's 400/200, guarded by tests/test_guard.py::TestBodyShapeRobustness).
• The chronicle blurs; live presence may distinguish. Whether a trace was left by human or agent is deliberately left open — one ledger voices them the same way, and /chronicle carries no actor-type flag. Live presence is the scoped exception, decided when the travelers panel shipped (PR #59) and made explicit on 2026-07-18: the panel persona-tags the walking cast and routes presences to /agent/voice vs /speak, because addressability needs an addressee. Don't extend taxonomization into the chronicle, history feeds, or node voices. README concept, docs/evaluation/2026-07-04-deep-evaluation.md G1.
• Agent solves don't count as human progress. An ambient/FSM agent standing on a puzzle never claims a co-op session, opens a seal, or lights a constellation. persistence/__init__.py (Agent solves (payload carries "agent")), CHANGELOG constellations entry.
• The chronicle is append-only; three sanctioned mechanisms, no more. Never delete or rewrite world_mutations rows in application code. Abuse is handled by content-level redaction (python main.py redact, runbook §7 — mechanical fields survive so counters and epochs stay intact); pruning exists but is double-gated behind NESTED_WORLDS_MUTATION_TTL_DAYS and NESTED_WORLDS_ALLOW_HISTORY_PRUNE=1 (and prune_mutations() must never be called directly); whole-DB restore (python main.py restore) is the disaster path, not an edit path. persistence/__init__.py redaction section, fly-deployment.md §7.