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.

[SorraTheOrc]

Automated PR review is currently blocked: the Ampa review container could not be provisioned for this run (wl ampa start-work failed with fatal: could not create work tree dir 'project': Permission denied).\n\n- Tests: not executed in this run due to container provisioning failure.\n- Audit: not executed in this run due to container provisioning failure.\n- Code Review: not executed in this run due to container provisioning failure.\n\n### Critical/Blocking issues\n- Ampa review workspace setup fails before checkout/tests, so no repository checks could be completed for this run. Suggested fix: repair Ampa workspace mount/permissions for project clone path and rerun review.\n\n### Non-blocking issues\n- Canonical Worklog id was selected as CG-0MMN8VNCH0C6XKC4 from the PR body/linked issue metadata; PR body includes multiple additional CG-* references, which may confuse automation.

[SorraTheOrc]

Automated review rerun is still blocked by a critical Ampa provisioning failure, so this PR is not ready to merge yet.\n\n- Tests: not executed in this run because the review container never reached a usable checkout state.\n- Audit: not executed in this run because container setup failed before branch checkout.\n- Code Review: not executed in this run because container setup failed before branch checkout.\n\n### Critical/Blocking issues\n- wl ampa start-work fails during setup with fatal: could not create work tree dir 'project': Permission denied (reproduced after pool warm-up and retry), blocking checkout and all repository checks. Suggested fix: repair Ampa workspace mount/permissions for project clone path, then rerun review.\n\n### Non-blocking issues\n- Canonical work-item detection found multiple CG-* ids in the PR body; selected CG-0MMN8VNCH0C6XKC4 by precedence (first match in PR description).

[SorraTheOrc]

This PR is not ready to merge because the review container is missing required runtime/tooling, so critical checks could not be completed in this run.

• Tests: not executable in container (npm test failed immediately: vitest: not found).
• Build: not executable in container (npm run build failed immediately: tsc: not found).
• Audit: unavailable (opencode run exited non-zero).
• Code Review: unavailable (opencode run exited non-zero).

Critical/Blocking issues

• Ampa review environment lacks required project tooling/dependencies, preventing meaningful verification of this branch. Suggested fix: ensure review containers bootstrap Node dependencies (or include required toolchain) before running checks, then rerun review.
• Automated audit/code_review execution is still failing in container. Suggested fix: restore reliable opencode execution in review containers and rerun audit + code review.

Non-blocking issues

• Canonical work-item detection found multiple CG-* ids in the PR body; selected CG-0MMN8VNCH0C6XKC4 by precedence using the explicit worklog:id marker in the description block.

[SorraTheOrc]

Automated review rerun: this PR is still not ready to merge because critical verification checks could not run in the Ampa review container.

• Tests: failed to start (npm test -> vitest: not found).
• Build: failed to start (npm run build -> tsc: not found).
• Audit: unavailable (opencode run exited non-zero).
• Code Review: unavailable (opencode run exited non-zero).

Critical/Blocking issues

• Review container is missing required Node project tooling/dependencies, preventing meaningful repo verification. Suggested fix: bootstrap workspace dependencies/toolchain in Ampa review startup, then rerun checks.
• Automated audit/code_review execution is still failing in the container. Suggested fix: restore reliable opencode execution in review containers and rerun before merge.

Non-blocking issues

• Canonical work-item selection was reproducible via explicit PR marker worklog:id=CG-0MMN8VNCH0C6XKC4; PR body includes multiple additional CG-* ids that can cause automation ambiguity.

[SorraTheOrc]

Automated review rerun: this PR is not ready to merge because critical verification could not start in the Ampa review environment for this run.

• Tests: not executed (container setup failed before checkout).
• Build: not executed (container setup failed before checkout).
• Audit: not executed (container setup failed before audit step).
• Code Review: not executed (container setup failed before code review step).

Critical/Blocking issues

• wl ampa start-work CG-0MMSC540Y1O5MIJA failed twice (including after wl ampa warm-pool) with fatal: could not create work tree dir 'project': Permission denied, blocking checkout and all repository checks. Suggested fix: repair Ampa workspace clone-path permissions/mounts, then rerun the full review.

Non-blocking issues

• Canonical Worklog detection found multiple CG-* references in the PR body; selected CG-0MMN8VNCH0C6XKC4 by precedence using explicit worklog:id marker.

[SorraTheOrc]

Automated PR review is currently blocked by Ampa container provisioning, so this run did not execute checkout, tests, audit, or code-review checks.\n\n- Tests: not run (container session did not start).\n- Audit: not run (container session did not start).\n- Code Review: not run (container session did not start).\n\nBlocking issue: Creating sandbox container to work on CG-0MMSC540Y1O5MIJA...
Syncing worklog data...
Using pre-warmed container "ampa-pool-1".
Running setup inside container... returns non-zero during setup and no claimed container is created. Please resolve the existing Ampa follow-up items before rerunning this review.

[SorraTheOrc]

Canonical Worklog id selection note: multiple CG-* ids are present in the PR body context. Using for review tracking by precedence (explicit worklog:id marker in PR description), and treating other ids as related references.

[SorraTheOrc]

This PR is not ready to merge because the automated review environment could not be provisioned, so repository checks were not executed in this run.

• Tests: not run (Ampa review container setup failed before checkout).
• Audit: not run (no claimed review container available).
• Code Review: not run (no claimed review container available).

Critical/Blocking issues

• "Review infrastructure failure: Creating sandbox container to work on CG-0MMSC540Y1O5MIJA...
  Syncing worklog data...
  Using pre-warmed container "ampa-pool-3".
  Running setup inside container... returned non-zero and no container was claimed for the review item; checkout/audit/tests could not start. Suggested fix: resolve Ampa start-work provisioning/claiming so PR review commands can run inside an isolated container."

Non-blocking issues

• "No additional code-level non-blocking items were assessed in this run because execution stopped at container provisioning."

[SorraTheOrc]

Worklog ID note: multiple CG-* IDs appear in the PR body context; this review used CG-0MMN8VNCH0C6XKC4 as canonical based on precedence via linked issue #432 worklog marker.

[SorraTheOrc]

Automated review run is blocked and this PR is not ready to merge yet because the Ampa review container could not be claimed for execution.\n\n- Tests: not run (review container provisioning failed before checkout).\n- Audit: not run (no claimed review container/workspace).\n- Code Review: not run (no claimed review container/workspace).\n\n### Critical/Blocking issues\n- Worklog ID mismatch in PR metadata/body: multiple IDs are present in context text; canonical ID selected for this review is CG-0MMN8VNCH0C6XKC4 (from explicit worklog:id marker / linked issue #432).\n- Ampa provisioning failure: wl ampa start-work CG-0MMSC540Y1O5MIJA returned non-zero and did not register a claimed container, so checkout and repository checks could not execute. Suggested fix: resolve the Ampa start-work/container claim path, then rerun automated review.\n\n### Non-blocking issues\n- None identified in this run because code-level checks were not executed.

[SorraTheOrc]

This PR is not ready to merge because the review container could not be provisioned for this run, so critical checks were not executed.

• Tests: not run (container setup failed before checkout).
• Audit: not run (no claimed review container).
• Code Review: not run (no claimed review container).

Critical/Blocking issues

• "Ampa provisioning failed for review item CG-0MMSC540Y1O5MIJA: `wl ampa start-work` returned non-zero during setup and no container was claimed in `wl ampa list-containers`, so checkout/tests/audit could not start. Suggested fix: repair Ampa start-work claim/setup path, then rerun automated review."

Non-blocking issues

• "Multiple CG-* ids are present in PR body context; canonical id selected by precedence is CG-0MMN8VNCH0C6XKC4 (explicit worklog:id marker)."