fix(puzzles): harden existing puzzle feedback, recovery, and shared state

[zoeyrose]

Architecture amendment — one authored content source (2026-08-13)

Initiative atrinik/atrinik#357 supersedes every future live-branch instruction below. atrinik/content@main is the sole mutable authored source for replacement and Classic targets. Future authored changes land only on main; supported Classic artifacts are deterministically derived from the same immutable main revision. Do not create, restore, author, backport, validate, or publish through a live 1.x branch.

Exact historical 1.x commits, tags, releases, assets, preserved local snapshots, provenance, parity records, and comparisons remain valid immutable evidence. This amendment changes no other feature, balance, lore, compatibility, licensing, validation, or ownership acceptance criterion.

Parent audit: #141.

Outcome

Make the existing authored puzzle set legible, recoverable, accessible, and safe under reset/re-entry and multiplayer use without flattening its good regional identity.

This issue is the remediation umbrella for the legacy puzzles identified by #141. Deliver changes in small regional batches with their own validation notes; do not rewrite every dungeon at once. Glacial Hollow's absent fire-crystal puzzle is tracked separately because it is restoration rather than hardening.

Priority matrix

Puzzle	Required correction
Promethia/Scursaur maze	Mark the visual rule for success/failure tiles, add at least one progress landmark, and warn/gate the transition from difficulty 1 into difficulty 65–75 content. Coordinate route danger with #20.
Abandoned Mine gate	Replace the Tolkien-derived “mellon” answer with an Atrinik-native clue/response, reconcile the inscription text, normalize input safely, and retain a nearby progressive hint that does not print the answer.
Berri Lur statues and Loki temple	Preserve trickster flavor while distinguishing readable misdirection from arbitrary lethal choice; define shared-object ownership/reset and prevent one player from punishing an unrelated bystander.
Loki ladder	Keep the wall-herding insight, but make movement/reset feedback deterministic enough to learn and recover; handle missing/shared ladder state across tiled maps.
Brynknot Sewer rocks	Add progressive pad/gate feedback, define party/shared ownership, and recover missing rocks or a lost/consumed key without resetting another active solve.
Underground City II torches	Add a deterministic local clue and visible gate-state feedback; make cross-map timer/monster/waypoint failure recoverable.
Underground City III expedition/security	Preserve the journal/fake-torch/northwest deduction; provide a capability-neutral alternative to one exact spell; add checkpoint/reset/escape behavior and clear safe-bridge confirmation.
Incuna Water Well	Verify the full connection graph, especially apparently orphaned connection 144; expose pressure/flow state to the player; test retrigger, drowning escape, reset, and concurrent use.

Scope and design rules

• Preserve successful lore-mechanic matches: Loki should remain playful, Incuna industrial, Berri genealogical, and Underground City archaeological/drow-engineered.
• Prefer localized readables, plaques, visible apparatus, animation, sound, and magic-mouth feedback over global/random-only clue delivery.
• Wrong actions may cost time or create a bounded encounter, but must teach something and leave a deterministic recovery.
• A puzzle may remain shared-world state only if active ownership, timeout, reset, spectator behavior, and a second party's interaction are explicit. Otherwise use character/party-local progression or a lock with readable feedback.
• Do not convert every puzzle into a quest marker trail or reveal complete solutions in readiness hints; follow Add explicit elemental-readiness paths for Dark Cave and Old Outpost #21's distinction between preparation and spoilers.
• Treat the Abandoned Mine wording as a provenance/lore correction as well as a usability fix. New text must be Atrinik-native.
• Keep combat difficulty and puzzle tier separate in UI/dialogue and map metadata.

Acceptance criteria

• Each priority puzzle has a before/after row recording tier, clue path, state owner, failure state, reset/recovery, reward, route danger, and runtime scenario.
• Promethia cannot silently present a difficulty-1 route as safe and then strand an unprepared player in level-65+ content.
• The Abandoned Mine no longer depends on copied recognizability of “mellon,” has internally consistent text, and accepts intentional variants without accepting arbitrary input.
• Shared rocks, statues, ladder, torches, altars, and flood state cannot be permanently lost or trivially griefed; another active party is not silently reset.
• Underground City III remains a real deduction and is solvable without belonging to one class or owning one irreplaceable spell/item.
• Every puzzle provides initial, intermediate or wrong-state, success, and already-complete feedback through at least two suitable channels where accessibility requires it.
• Death, escape, abandon, map reset/reload, disconnect/re-entry, missing object/beacon, duplicate activation, and two-party interference have deterministic results.
• Puzzle rewards are duplicate-safe and lost progression items are recoverable without farming permanent rewards.
• Focused catalog/world audits, map/package validation, python3 tools/validate.py, and git diff --check pass on each release line.
• Classic runtime playtests cover the exact changed routes and record map, character/party setup, reset interval, results, and cleanup.

Coordination and non-goals

• Audit progression-route danger and pilot safer travel loops #20 owns the wider progression-route danger program.
• Add explicit elemental-readiness paths for Dark Cave and Old Outpost #21 owns readiness/hint conventions around difficult content.
• feat(maps): continue the Underground City skeletal-dragon arc in Bone Cairn #107 owns the Bone Cairn continuation, not general Underground City puzzle repair.
• atrinik/server#54 and atrinik/server#59 own replacement trigger/action-graph migration. Open a narrower runtime issue only after an authored puzzle proves a missing reusable behavior.
• Do not rebalance all monsters, redesign every map touched by a connection, or turn optional secrets into mandatory progression.

Release lines

The target maps and scripts are currently identical on main and 1.x. Author canonical changes on main, backport separately to 1.x, validate both, and close this issue only from the canonical pull request.

[zoeyrose]

Incuna Water Well investigation update

The source graph does not show the Water Well map set as detached from Incuna:

• world_3_83 has two surface exits to world_3_83_-2;
• world_4_83 has the visible well entrance to world_4_83_-2, with a reciprocal well_bucket return;
• world_5_84_-2 has the emergency ladder/sewer exit to world_5_84;
• the coordinate-named underground tiles link dynamically when their adjacent files exist.

Walkable reachability and state transitions still need the focused Classic runtime scenario already required here, but this is not evidence that the whole well was replaced or detached.

The static orphan is specifically connection 144 on the terminal boulder detector in world_5_84_-2. History explains it:

• 2011 connection-system migration: the old connection-144 detector plus duplicator pair became one detector with last_heal 1; the duplicator was removed, while connected 144 remained.
• 2015 world-map move: preserved that terminal detector while moving the well into coordinate-named world tiles and repointing the Incuna surface entrances.
• The 2026 author-name normalization changed no mechanics.

This makes 144 most likely a vestigial terminal link: last_heal 1 consumes the arriving boulder directly, while the lone connection has no downstream target. Runtime verification should decide the final correction. If it is only the terminal sink, remove or explicitly document the stale ID; do not blindly restore the obsolete duplicator. If a missing downstream effect is observed, author that effect explicitly under current connection semantics.

The recent Clearhaven Mine port is unrelated. It changed only Clearhaven surface world_8_78 from a non-traversable wet-well message into the Clearhaven Mine entrance and touched no Incuna map. Clearhaven Mine and Incuna Water Well already coexist at separate world locations and destinations.

The five Incuna well tiles are byte-identical on main and 1.x; focused content-core validation reports each valid with zero diagnostics on both lines. That validates authored structure, not retrigger/reset/concurrency behavior.

[zoeyrose]

Incuna endpoint and unfinished-route follow-up

The historical route trace identifies one implemented endpoint and two old unfinished hooks; it does not identify a removed maze:

• The authored flood/stair loop ends at the one-way emergency ladder in world_5_84_-2, which explicitly exits to the locked sewer plate on Incuna's dyke at world_5_84 (9,8). This is the only source-backed endpoint.
• The reachable exit_green at world_4_84_-2 (16,6) has no slaying, hp/sp, connection, script, or usable subtype. It therefore produces the default closed-exit response and a “leads nowhere” server log.
• The ladder down at world_3_83_-2 (14,9) also has no available lower tile/destination. Its historical source was targetless too.
• The green exit was introduced already without a destination in 2011. Under-the-Barn and Slime-Pit content arrived later, and no historical path links either to the portal.
• The deleted well_02aa was only a 104-line, two-column terrain seam with no exit, trigger, message, machinery, or destination. Its geometry was repacked into the current world tiles; restoring that file would not restore gameplay.

This makes the immediate #143 decision concrete:

1. For a minimal repair, replace each intentionally inert hook with non-exit scenery or honest disabled-state feedback so it cannot imply a usable route.
2. If traversal is retained, give it an explicit reviewed destination and reciprocal/safe return; do not rely on implicit exit pairing.
3. If a new pressure/cistern maze is desired, treat it as new authored design. Put it in named maps under maps/shattered_islands/incuna/water_well/, link explicitly from the existing well, preserve the current flood machine and sewer egress, and prevent the new route from bypassing the flood sequence.
4. Expose initial/intermediate/wrong/success pressure state, define shared/party ownership and reset, and test walk/fly activation, drowning escape, death, reconnect, reload, retrigger, and two-party use on both release lines.

No separate issue is needed for the existing dead-exit defect because the Incuna full-graph audit is already in scope here. A focused feature child becomes appropriate only after choosing to author the new cistern/maintenance-maze route; history supplies no canonical destination to restore.