feat(main-street): Hint System (M3 US-3)

[Copilot]

Implements the per-turn Hint button for Main Street's MarketPhase: pressing it queries GreedyStrategy for the recommended action, highlights the target card/slot, and displays a one-line rationale. Limited to one use per turn.

New: MainStreetHint.ts

• generateHint(state) — delegates to GreedyStrategy.chooseAction() (same priority chain as AI auto-play) then scores the result via scoreAction(). Advances state.rng. Returns null outside MarketPhase.
• buildRationale(action, score, state) — maps action type to a one-line template per PRD §4.4:
  • buy-business → "Buy Cafe at slot 2 for +2 synergy bonus"
  • buy-upgrade → "Upgrade Bakery at slot 0 for +1/turn income"
  • buy-event → "Buy Trade Fair for +5 coins"
  • play-event → "Play Trade Fair now for immediate benefit"
  • end-turn → "No good buys available -- end your turn"

MainStreetScene changes

• Three scene-level fields: hintUsedThisTurn, hintedCardId, hintedSlotIndex — reset in create() and startDayPhase().
• Hint button rendered alongside End Turn in refreshActionButtons(); shows as disabled "Hint ✓" after use.
• Cyan border highlights applied to the recommended card (drawMarketCard, drawHeldEventCard) and target slot (drawEmptySlot, drawBusinessSlot) on hint activation.
• Rationale displayed via existing instructionText.

Tests (tests/main-street/hint.test.ts)

18 tests: null guard outside MarketPhase, action matches independent GreedyStrategy evaluation (separate state instances to avoid RNG contamination), score equality, all five rationale templates, multi-seed integration.

Note: Transcript recording for hint events is deferred to CG-0MMN8WCCD1AXQ2EU.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Main Street M3: Hint System</issue_title>
<issue_description>

Implement the hint generator and UI integration that lets players request a Greedy AI recommendation during MarketPhase.

User Story

As a player, I want to press a Hint button during my turn to see a suggested move highlighted with a brief explanation, so I can learn effective strategies.

Deliverables

• example-games/main-street/MainStreetHint.ts with generateHint(), buildRationale()
• hintUsedThisTurn state tracking, reset on DayStart
• Hint button in MainStreetScene with highlight rendering and rationale text display
• Unit tests: correct recommendation, per-turn limit, rationale text, MarketPhase-only

Acceptance Criteria

• Hint button visible during MarketPhase
• Pressing Hint queries GreedyStrategy for recommended action
• Recommended card is highlighted in market; target slot highlighted on grid (for buy-business)
• One-line rationale displayed (e.g., Buy Cafe at slot 5 for +2 synergy bonus)
• End-turn hint displays No good buys available -- end your turn
• Hint does not auto-execute the action
• Limited to 1 use per turn; button disabled after use until next turn
• Hint request recorded in game transcript
• All existing tests continue to pass

Dependencies

• Depends on: CG-0MMN8UTLC12Q1U2R (Greedy Strategy)

References

• PRD: docs/main-street/prd-milestone-3.md (US-3, Section 4.4, 5.5)

---

Related work (automated report)

• CG-0MMN8UTLC12Q1U2R — Main Street M3: Greedy AI Strategy and Scoring Heuristics (status: completed).
  This work implements GreedyStrategy and the helpers scoreAction() and enumerateAndScoreActions() that the hint generator should reuse to evaluate and rank candidate actions. GreedyStrategy's implementation is the primary source of truth for recommended moves.

• CG-0MMN8V9UU0MF2GHK — Main Street M3: Monte Carlo Harness Extension for AI Strategies (status: completed).
  Extends the Monte Carlo harness to run AI strategies (including Greedy). Useful for validation of hint quality and to generate sample scenarios for testing hint behavior across seeds.

• CG-0MMN8WCCD1AXQ2EU — Main Street M3: Transcript Extension for AI, Hint, and Undo Events (status: blocked).
  Specifies transcript schema additions required to record hint requests and undo/redo events. The hint implementation must record the hint request and rationale as a transcript event; this work item is the canonical reference.

• CG-0MM4REQ4C01X8C08 — Main Street: PRD Milestone 3 -- AI, Hints, and Undo System (status: in-progress, parent).
  The PRD contains detailed design, acceptance tests, and API sketches for hints (see section 4.4 and 5.5). Implementations should follow the API sketches (HintGenerator, HintResult) and acceptance criteria listed there.

• docs/main-street/prd-milestone-3.md (file)
  Design doc for Milestone 3 describing goals, success criteria, and a detailed hint architecture sketch. Useful for matching acceptance criteria and for tests referenced in the PRD.

• docs/main-street/ai-strategy.md (file)
  GDD section describing AI strategy tiers and hint-system design. Provides rationale and move-evaluation heuristics that inform buildRationale() templates.

Notes and conservative guidance:

• Prefer reusing GreedyStrategy's scoring helpers rather than duplicating heuristics; this keeps hints consistent with AI behaviour.
• Ensure hint transcript events follow the schema proposed in CG-0MMN8WCCD1AXQ2EU; coordinate with that item if schema details change.
• Use docs/main-street/prd-milestone-3.md acceptance tests (Appendix B) as the basis for unit tests listed in the Deliverables.

(Automated report generated by find_related skill)</issue_description>

Comments on the Issue (you are @copilot in this section)

@SorraTheOrc

Map

Intake draft created at .opencode/tmp/intake-draft-Main-Street-Hint-System-CG-0MMN8VNCH0C6XKC4.md; transcript recording left to CG-0MMN8WCCD1AXQ2EU; one-line rationale; non-blocking UI. Review requested.</comment_new>
<comment_new>@SorraTheOrc

Map

find_related report appended; coordinated decisions: transcript left to CG-0MMN8WCCD1AXQ2EU, one-line rationale, non-blocking UI. Intake brief saved to .opencode/tmp/intake-draft-Main-Street-Hint-System-CG-0MMN8VNCH0C6XKC4.md</comment_new>
<comment_new>@SorraTheOrc

Map

Intake brief approved by user. Proceeding to effort and risk estimation and final sync.</comment_new>
<comment_new>@SorraTheOrc

Map

Effort & risk estimate posted: expected ~30.7h (recommended 31h), Low-Medium risk. S...

• Fixes Main Street M3: Hint System #432

---

💬 Send tasks to Copilot coding agent from Slack and Teams to turn conversations into code. Copilot posts an update in your thread when it's finished.

[SorraTheOrc]

This PR is not ready to merge yet because a critical test-environment failure blocks full verification in the Ampa review container.

• Tests: unit suite passed (90 files, 2274 passed, 5 skipped); browser suite failed to start due to missing Playwright runtime dependency (`libnspr4.so`).
• Audit: could not execute in container (`opencode run` exited non-zero), so audit outcome is currently unavailable.
• Code Review: could not execute in container (`opencode run` exited non-zero), so structured review outcome is currently unavailable.

Critical/Blocking issues

• Browser test environment is incomplete in Ampa container (`libnspr4.so` missing), which prevents `npm test` browser project validation. Suggested fix: update Ampa image/runtime packages for Playwright dependencies and re-run the full suite.
• Automated audit/review tooling did not run in container. Suggested fix: restore working `opencode` execution in review containers, then re-run audit + code_review before merge.

Non-blocking issues

• Canonical Worklog id detection found multiple `CG-*` references in PR body; selected `CG-0MMN8VNCH0C6XKC4` by precedence (first valid work-item id in PR description block). Consider trimming extra IDs in PR body to reduce ambiguity for automation.