feat: share village needs with helpers

docs/ACTION_SYSTEM_ARCHITECTURE.md

@@ -75,11 +75,13 @@ It also publishes the latest `ActionSelectionResult` for presentation; the UI
 does not recompute decisions. Each idle selection re-derives the capable helper
 instead of consulting persisted assignment state. At completion it atomically
 pays any definition-backed stored-resource cost before applying the action
-effect. A late shortfall suppresses the effect and records a `task_blocked` fact. The
-manager also captures actor/nearby knowledge before forwarding newly recorded
-events into `RelationshipSystem`. When an NPC arrives beside a worker at the
-same non-storage activity site, the manager may transfer one direct known fact
-and applies its consequence only to that newly informed listener. It exposes
+effect. A late shortfall suppresses the effect and records a `task_blocked`
+fact. The manager also captures actor/nearby knowledge before forwarding newly
+recorded events into `RelationshipSystem`. When an NPC arrives beside a worker
+at the same non-storage activity site, the manager may transfer one direct
+known fact and applies its consequence only to that newly informed listener. An
+open opportunity's exact trigger receives bounded priority in that conversation
+before normal lasting/recent ranking. It exposes
 knowledge, provenance, relationship, and cause queries without moving social
 authority into UI. After consequences are known, it protects current causal
 facts, enforces the recent-memory cap, and runs age review from authoritative
@@ -108,8 +110,9 @@ simulation ticks.
   legacy, with a stable source NPC ID for direct communication;
 - permits one performed/witnessed fact to cross one co-located social hop, but
   does not relay communicated or ambiguous legacy facts;
-- orders communication by lasting relationship relevance, then acquisition
-  recency;
+- tries the active opportunity trigger first when the speaker directly knows
+  it, then orders remaining communication by lasting relationship relevance
+  and acquisition recency;
 - retains current relationship causes and at most three other recent facts per
   NPC, expiring day-old recent facts at deterministic review boundaries;
 - captures evidence only when the event happens, never from current positions

docs/ARCHITECTURE_OVERVIEW.md

@@ -38,7 +38,8 @@ would otherwise obscure that lifecycle:
 - `simulation/knowledge/EventKnowledgeSystem.gd` owns per-NPC references to
   known objective events, immutable acquisition provenance, proximity witnesses
   at record time, one-hop direct fact transfer, and deterministic recent-fact
-  retention/importance ranking;
+  retention/importance ranking. It can place the active opportunity trigger
+  first without weakening its direct-source or one-hop checks;
 - `simulation/relationships/RelationshipSystem.gd` owns directed relationship
   queries, event-driven trust changes, and deterministic social tie-breaking;
 - `simulation/opportunities/VillageOpportunitySystem.gd` observes immutable
@@ -96,8 +97,10 @@ improving ownership.
   retained knowledge. Opportunity presentation is likewise query-only.
   Relationship cues, interested-villager concern, physical pantry stock, and
   refill feedback consume authoritative state or state-change signals and are
-  intentionally absent from saves and checksums. Stable visuals are rebuilt
-  from state after restore; transient reactions are not replayed.
+  intentionally absent from saves and checksums. The transient village-whisper
+  HUD likewise formats need, transfer, response, and resolution signals without
+  owning them. Stable visuals are rebuilt from state after restore; transient
+  reactions are not replayed.
 - Resource changes go through `ResourceStateRecord`, NPC inventory, and
   `VillageEconomy`; `village.food` and `village.wood` are synchronized views.
 - New mutable features define serialization and deterministic continuation at

docs/BUILD_IN_PUBLIC_PLAN.md

@@ -741,13 +741,18 @@ Completed:
     and sleep/meal precedence. Existing target resolution chooses and reserves
     the finite source, while no quest acceptance, reward, or helper assignment
     is introduced.
+30. Village whisper: direct witnesses/performers now report the active need's
+    exact trigger before unrelated facts at shared work, allowing a newly
+    informed trusted helper to respond autonomously. One cardless warm-amber HUD
+    ribbon gently rises, pulses, and fades through need, named report, response,
+    and resolution beats while remaining separate from development overlays.
 
 Next:
 
-1. Prove one direct information-to-help chain: transfer the exact open-need
-   trigger at an existing shared activity, then let the newly informed trusted
-   villager be re-derived and respond through the same autonomous selector.
-   Keep generic dialogue and multi-hop rumours out of scope, as sequenced in
+1. When no capable helper exists, show one contextual player response hint
+   derived from a current player-usable finite source and the real storage
+   target. Clear it as soon as help emerges or the need closes; do not add quest
+   acceptance, waypoint state, or a generic tracker, as sequenced in
    `LEARNING_ROADMAP.md`.
 
 Do not start with GIS data, a full city, a large asset pack, or more NPC

docs/ECONOMIC_EVENTS.md

@@ -99,6 +99,14 @@ opening; invalidation emits no event and stores the close tick and stable
 reason. Resolution or invalidation returns the trigger to normal bounded
 retention.
 
+When a performer or direct witness meets another villager at an eligible shared
+activity, the active opportunity's trigger is attempted before normal
+lasting/recent communication ranking. `EventKnowledgeSystem` still requires
+performed/witnessed source provenance and records only the existing event ID,
+speaker ID, source method, listener, and acquisition tick. A newer unrelated
+fact cannot displace the active report, while communicated listeners still
+cannot relay it onward.
+
 For an open need, the same system can derive one capable helper without
 assigning work. A candidate must know the exact trigger and have a familiar
 directed relationship with at least 0.6 trust toward the interested villager.
@@ -148,6 +156,10 @@ world cue remains specific to the pantry shortage rather than representing a
 wood need as hunger. The active summary additionally names the currently
 derived helper, supply action, trust fact, and inventory or finite-source route,
 or states that no informed trusted villager is currently able to supply it.
+One separate cardless player HUD gives transient warm-amber feedback for the
+authoritative need opening, exact named report, newly informed helper decision,
+and real resolution. It stays available when development overlays are hidden,
+but clears on restore and never becomes objective or save state.
 
 ## Deliberate limits
 

docs/LEARNING_ROADMAP.md

@@ -807,13 +807,27 @@ The first bounded autonomous helper consumer is complete:
 - focused headless and Jajce runtime regressions prove autonomous selection,
   precedence, finite-source targeting, reservation, and restore-time re-query.
 
-Milestone 7 is not complete. The immediate next slice should connect the
-existing one-hop fact transfer to this path: prove that a direct witness or
-performer can communicate an open need's exact trigger at a real shared
-activity, after which the newly informed trusted villager is re-derived as the
-helper and responds through the same autonomous selection contract. Keep this
-as a truthful event-reference transfer, not generic dialogue or multi-hop
-rumour infrastructure.
+The first direct information-to-help path is complete:
+
+- at an eligible shared activity, a speaker who performed or witnessed the
+  active need's exact trigger discusses it before other retained direct facts;
+- the transfer still references the original event, preserves the speaker and
+  direct source method, stops after one hop, and creates no dialogue/event copy;
+- a regression places a newer unrelated fact ahead under normal ranking, then
+  proves active-need priority transfers only the trigger to the trusted capable
+  listener;
+- the newly informed villager is immediately re-derived as helper and, once
+  idle, chooses the same ordinary autonomous gather/deposit path;
+- a cardless warm-amber player HUD briefly shows the real need, named report,
+  helper response, and resolution. It is signal-driven, survives debug-overlay
+  hiding, and neither serializes nor replays after restore.
+
+Milestone 7 is not complete. The immediate next slice should expose one bounded
+player response affordance when an open need has no capable helper: derive a
+concise contextual hint from the existing player-usable finite source and real
+storage target, then clear it when a helper emerges or the need closes. Reuse
+the current interaction/economy rules; do not add quest acceptance, waypoint
+state, or a generic objective tracker.
 
 Recently completed:
 

docs/PROJECT_CONTEXT.md

@@ -472,7 +472,9 @@ follow camera.
 The UI subscribes to village, task, event, knowledge, relationship, and
 opportunity changes. It formats aggregate state and resolves known facts,
 relationship causes, and opportunity lifecycle details through manager queries
-without owning or recomputing simulation facts.
+without owning or recomputing simulation facts. `village_whisper_hud.gd` is a
+separate transient player layer that formats the same authoritative signals and
+remains independent of the development overlays.
 
 ## Current runtime flow
 
@@ -556,6 +558,7 @@ NpcVisual navigates through the active world
 │   ├── knowledge_retention_consequence_test.gd
 │   ├── jajce_runtime_integration_test.gd
 │   ├── npc_visual_lifecycle_test.gd
+│   ├── opportunity_communication_helper_test.gd
 │   ├── relationship_consequence_test.gd
 │   ├── resource_node_player_parity_test.gd
 │   ├── simulation_definitions_test.gd
@@ -579,7 +582,9 @@ NpcVisual navigates through the active world
 │   │   └── ResourceNode.tscn
 │   ├── active_world_adapter.gd
 │   ├── world_view_manager.gd
-│   └── ui/ui.gd
+│   └── ui/
+│       ├── ui.gd
+│       └── village_whisper_hud.gd
 ├── main.tscn
 └── project.godot
 ```
@@ -922,11 +927,19 @@ The ordinary in-progress NPC task can save normally, but no helper assignment,
 quest acceptance, reward, or opportunity-specific event is persisted; ordinary
 task-start history remains unchanged.
 
-Milestone 7 remains in progress. The immediate next slice should prove the
-combined information-to-help path: communicate an open need's exact trigger
-once at a real shared activity, then re-derive the newly informed trusted NPC as
-the autonomous helper. Keep the transfer direct and source-backed rather than
-introducing generic dialogue or multi-hop rumours.
+The first direct information-to-help path is complete. At shared activity, a
+performer or direct witness now discusses the active need's exact trigger before
+newer unrelated facts. The original event and first-source provenance remain
+authoritative and one-hop. A newly informed trusted, supplied villager is then
+re-derived and autonomously responds through ordinary action selection. A
+single cardless warm-amber HUD ribbon presents the real need, named report,
+helper response, and resolution without entering simulation or save state.
+
+Milestone 7 remains in progress. The immediate next slice should add one
+bounded player response hint only when no capable helper exists, derived from
+the current player-usable finite source and real destination. It should clear
+when help emerges or the need closes, without quest acceptance, waypoint state,
+or a generic tracker.
 
 The remaining simulation-garden target still aims for:
 

docs/SIMULATION_STATE_SCHEMA.md

@@ -207,6 +207,11 @@ existing NPC task, task-state, target, travel, and reservation fields serialize.
 The helper result remains absent: restore retains any in-progress ordinary task
 and independently re-derives current capability from restored facts.
 
+Active-need communication adds no schema fields. It persists through the
+existing `KnownEventStateRecord` event, listener, source NPC, direct source
+method, and acquisition-tick fields. Communication/HUD animations are transient
+and are cleared rather than replayed after restore.
+
 ## Resource authority
 
 `SimulationManager` owns `ResourceStateRecord` instances independently of the