fix(G1): play_party.sh drives the story arc per beat (port the shared runbook)

[100yenadmin]

Closes the G1 gap from the 2026-06-03 sweep: combat-through-engine=0 across all 5 personas — no one reached the full 8-beat arc (parley → engine combat → travel → rest → travel).

Root cause: the 5-persona .app DM path (play_party.sh) was purely reactive — it has NO runbook, so free-play personas explored and finished satisfied at the intro (2–8 beats) and the arc never escalated to combat. run_duo.sh drives the arc via the shared clawdnd_runbook_for_beat (scene-intro / midpoint reversal / climax / travel-peopling) and does reach combat (45 start_combat/spawn_monster calls). play_party.sh already sources the same lib but never called it.

Fix: port the per-beat runbook into play_party.sh's main beat loop + inject it into the DM turn (4 minimal edits: a beat counter, the runbook call, the injection, a location tracker for the travel cue). A genuine DM improvement — the .app DM now drives the story like the duo — not just a gate tweak.

Guard: test_play_party_drives_the_arc_runbook. bash -n clean. Validation: the next re-sweep measures whether a persona now reaches engine combat + the full arc (G1). Honest note: G1 may also need a light persona 'play a complete session' nudge if personas still finish before the climax — the re-sweep will tell.

Summary by CodeRabbit

Release Notes

• New Features

  • Enhanced beat-by-beat session tracking with intelligent guidance that adapts based on story progression and location changes for improved narrative flow during gameplay.

• Tests

  • Added validation test for arc-driven guidance system integration.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 706a819f-68e5-43e2-814f-81489dc578d4

📥 Commits

Reviewing files that changed from the base of the PR and between ed7a975 and 082f718.

📒 Files selected for processing (2)

• scripts/play_party.sh
• servers/engine/tests/test_dm_session_remint.py

---

📝 Walkthrough

Walkthrough

The PR adds stateful arc-driver guidance to the beat loop in play_party.sh. It initializes a beat counter and prior-location tracker, selects a beat-appropriate runbook via engine API each turn, prepends that runbook into the DM prompt, and updates the location tracker from progress so subsequent runbooks reflect travel and state changes. A contract test validates the wiring.

Changes

Arc-driver runbook navigation

Layer / File(s)	Summary
Arc-driver runbook selection and injection scripts/play_party.sh	Beat loop initializes BEAT_NO and PREV_LOC state variables before the loop. Each beat, the script increments the counter, calls clawdnd_runbook_for_beat() to compute a beat-specific runbook, and prepends that runbook into the DM prompt. After DM narration is recovered, the script updates PREV_LOC from engine progress so the next beat's runbook selection can detect location/state changes.
Contract test for arc-driver integration servers/engine/tests/test_dm_session_remint.py	New test test_play_party_drives_the_arc_runbook asserts that play_party.sh references clawdnd_runbook_for_beat, increments BEAT_NO per beat, and injects the runbook into the DM turn invocation.

Possibly related PRs

• electricsheephq/WorldOS#567: Modifies the same scripts/play_party.sh DM turn() path by wrapping per-beat invocations with tiered timeouts.
• electricsheephq/WorldOS#631: Also changes scripts/play_party.sh's DM turn message construction (prepending a CLAWDND_LIVE_PROGRESS_RULE) and adds a related contract test in servers/engine/tests/test_dm_session_remint.py.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 A beat counter hops, a location stays put,
Each turn asks the engine which arc to befit.
The runbook guides DM through story's design—
No loops, no retreads, just forward in time! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The PR description covers the problem statement, root cause analysis, implemented fix, and validation approach. However, the required Licensing/CLA and Validation checklist sections from the template are missing.	Add the Licensing/CLA checkbox section and the Validation checklist section from the repository template to complete the required description structure.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: porting the shared runbook into play_party.sh to drive the story arc per beat, which directly addresses the G1 gap identified in the PR.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

Warning

Review ran into problems

🔥 Problems

Git: Failed to clone repository. Please run the @coderabbitai full review command to re-trigger a full review. If the issue persists, set path_filters to include or exclude specific files.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}