Skip to content

[codex] Stabilize WorldOS release gate evidence - #465

Merged
100yenadmin merged 5 commits into
mainfrom
codex/worldos-takeover-stabilization
May 31, 2026
Merged

[codex] Stabilize WorldOS release gate evidence#465
100yenadmin merged 5 commits into
mainfrom
codex/worldos-takeover-stabilization

Conversation

@100yenadmin

@100yenadmin 100yenadmin commented May 31, 2026

Copy link
Copy Markdown
Member

Summary

  • refreshes the takeover source-of-truth docs so origin/main, the canonical private-art checkout, the last measured gate build, and the last valid release gate are no longer conflated
  • hardens RRI/release-gate evidence handling so missing personas, missing disk-backed evidence, failed Part B loops, mixed build SHAs, image-denominator gaps, and missing real palette-source files cannot silently look release-ready
  • keeps the macOS app connected to the worktree code while reading private art from the canonical checkout, and moves player launch paths toward /openworlds/
  • records f5500ac as partial/harness-contaminated evidence, not a release verdict, and adds a model-tiering proposal as to-test guidance only

Why

This is the takeover stabilization lane, not a release lane. The previous gate evidence could mix harness failures with product failures and could overstate partial evidence. The Mac app also needed an explicit code-root/art-root split so Lexar worktrees can be tested without moving the private-art checkout.

Related follow-up: #466 tracks the first clean non-partial five-persona RRI rerun after this gate hardening lands.

Validation

  • python3 -m unittest qa.test_macos_app_static qa.test_release_gate_static viewer.tests.test_openworlds_static qa.test_release_readiness -> 53 tests OK
  • bash -n qa/ui_playtest_app.sh && bash -n qa/release_gate.sh && bash -n script/build_and_run.sh && bash -n scripts/install-desktop-shortcut.sh && node qa/playwright/screenshot_helper.test.js && git diff --check -> PASS
  • swift build --package-path macos/WorldOSApp -> PASS
  • WORLDOS_NO_STOP_EXISTING=1 WORLDOS_ART_REPO_ROOT=/Users/lume/ClawDnD-val WORLDOS_PREFER_LAUNCH_ROOTS=1 script/build_and_run.sh --verify -> launched dist/WorldOS.app and cleaned up the launched app/worktree viewer PIDs
  • WORLDOS_ART_REPO_ROOT=/Users/lume/ClawDnD-val qa/release_gate.sh --preflight-only -> PASS with expected takeover warnings: non-tip PR branch, occupied 8765, host swap pressure

Not Release Evidence Yet

  • no full local five-persona/RRI sweep was run on the 16GB Mac
  • release still requires the backend/persona sweep on the 32GB VM and a Mac/macOS CI built-app playtest gate
  • f5500ac RRI remains preserved only as partial/harness-contaminated evidence

Licensing / CLA

  • I have read CLA.md and submit this contribution under the WorldOS Contributor License Agreement.
  • I have not included confidential information, private customer data, private imported content, or third-party-restricted material.
  • Any third-party material in this PR is clearly identified with source and license.

Summary by CodeRabbit

  • New Features

    • Added configurable art repository path setting for users with custom art setups
    • Elevated OpenWorlds as the primary play surface across all UI and launch scripts
  • Documentation

    • Updated operational guidance for release readiness, quality assurance processes, and deployment procedures
    • Enhanced configuration documentation for repository and art setup
  • Tests

    • Added comprehensive contract validation suites for native app infrastructure, release gates, and viewer routing

@coderabbitai

coderabbitai Bot commented May 31, 2026

Copy link
Copy Markdown

Review Change Stack

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 150b89a0-853f-4771-baee-f1a85ad041f3

📥 Commits

Reviewing files that changed from the base of the PR and between 77a1578 and 03de0c4.

📒 Files selected for processing (14)
  • WorldOS-GUI-RUNBOOK.md
  • macos/WorldOSApp/Sources/WorldOSApp/Views/RootView.swift
  • qa/GUI_WORKBOOK.md
  • qa/release_gate.sh
  • qa/release_readiness.py
  • qa/test_macos_app_static.py
  • qa/test_release_gate_static.py
  • qa/test_release_readiness.py
  • qa/ui_playtest_app.sh
  • script/build_and_run.sh
  • scripts/install-desktop-shortcut.sh
  • viewer/monitor.html
  • viewer/openworlds/app.jsx
  • viewer/tests/test_openworlds_static.py

📝 Walkthrough

Walkthrough

This PR migrates the play surface to OpenWorlds, adds separate art-repo path resolution and wiring across the macOS app and viewer, and expands release-readiness/gating scripts and tests to model evidence gaps and partial-gate behavior.

Changes

OpenWorlds migration, art repo feature, and release infrastructure

Layer / File(s) Summary
Ignore and docs additions
.gitignore, docs/MODEL-TIERING-STRATEGY.md, README.md, qa/SCORECARD.md
Ignore QA output (/qa/RRI.json), add model-tiering proposal, and update README/SCORECARD status text and partial sweep entries.
Operational runbooks & goals
WorldOS-OPERATING-GOAL.md, WorldOS-GUI-RUNBOOK.md, WorldOS-NORTH-STAR.md, WorldOS-RUNBOOK.md, qa/GUI_WORKBOOK.md
Rewrite STATE-OF-TRUTH and takeover/read-order; tighten RRI gate wording and add RRI output contract; update Lexar worktree and verification steps.
OpenWorlds routing and branding migration
README.md, scripts/play.sh, scripts/play_party.sh, qa/play_human.sh, viewer/monitor.html, worldos-dashboard.command, worldos-play.command, scripts/install-desktop-shortcut.sh, docs/OPENWORLDS_FIDELITY_PLAN.md
Replace legacy /dashboard with /openworlds/ in docs, scripts, launchers, and viewer links; update user messages and desktop shortcuts.
Viewer art-root resolution & exports
viewer/server.py, viewer/openworlds/screen-character.jsx, viewer/tests/test_openworlds_static.py
Add _art_repo_root() and use it for ingested-image roots, compute distinct legacyDashboardUrl, remove SpellcastingHeader from window exports, and strengthen OpenWorlds static tests and env isolation.
macOS app art-repo configuration
macos/.../Models/ProviderModels.swift, macos/.../Services/RepositoryLocator.swift, macos/.../Services/AppProcessService.swift, macos/.../Services/ProviderAdapters.swift, macos/.../Views/*
Add artRepoPath to ProviderPreferences, implement launch/default art-repo resolvers, resolve/validate artRepoPath in AppProcessService, inject WORLDOS_ART_REPO_ROOT/CLAWDND_* into launched processes, and add UI bindings and validation across views and settings.
RootView active-override wiring
macos/.../Views/RootView.swift, DebugControlCenterView
Persist artRepoPath, add activeRepoPath/activeArtRepoPath honoring launch overrides, thread active values into starts/reloads, and refresh UI on changes.
Build-and-run integration
script/build_and_run.sh
Derive ART_ROOT from env overrides, add plist serialization helpers and new Info.plist keys for repo/art roots and prefer-launch-roots, honor WORLDOS_NO_STOP_EXISTING, and wait for launched bundle PID during verify.
UI playtest harness and persistence
qa/ui_playtest_app.sh, qa/play_human.sh
Use bundle-specific PID detection, optional global-kill opt-out, pass ART-pref flags to build script, persist session_surface.final.json, compute Part-aware exit logic and score pass.
Release gate automation
qa/release_gate.sh
Add free-port helpers, multi-root art discovery/export, dependency checks, preflight-only behavior, partial-gate flow when first persona missing score, and palette-live detection via persisted session_surface files.
Release readiness evidence-gap framework
qa/release_readiness.py
Introduce REQUIRED_RELEASE_PERSONAS, search multiple network evidence sources, infer personas, record harness failures, compute image denominators, synthesize evidence_gaps, and block gates on evidence presence as well as thresholds; extend JSON output and console diagnostics.
Static contract tests
qa/test_macos_app_static.py, qa/test_release_gate_static.py, qa/test_release_readiness.py, viewer/tests/test_openworlds_static.py
Add unit/static contract suites validating native art-repo wiring, release-gate contracts, UI playtest persistence, OpenWorlds routes, and many release_readiness scenarios (missing evidence, image rates, build-sha mismatches, palette-source cases, full-pass).

Sequence Diagram(s)

sequenceDiagram
  participant RootView
  participant AppProcessService
  participant RepositoryLocator
  participant ProviderAdapters
  participant ProviderProcess
  RootView->>AppProcessService: startProviderSession(artRepoPath)
  AppProcessService->>RepositoryLocator: resolve art repo path
  RepositoryLocator-->>AppProcessService: resolved path
  AppProcessService->>ProviderAdapters: build budgetEnvironment(with artRepoPath)
  ProviderAdapters->>ProviderProcess: launch with WORLDOS_ART_REPO_ROOT / CLAWDND_ART_REPO_ROOT
Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related issues

Possibly related PRs

Poem

🐰 I hopped to OpenWorlds at dawn’s early light,
Paths for art untangled and set just right,
Gates now check proofs and JSONs that sing,
Tests and runbooks hum — let the scorecards bring spring!

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch

@100yenadmin

Copy link
Copy Markdown
Member Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented May 31, 2026

Copy link
Copy Markdown
✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@100yenadmin

Copy link
Copy Markdown
Member Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented May 31, 2026

Copy link
Copy Markdown
✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 6

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)
WorldOS-GUI-RUNBOOK.md (1)

27-35: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add language identifiers to fenced code blocks.

Line 27 and Line 80 use unlabeled fenced blocks, which will keep failing MD040 checks. Please tag them as bash for consistency with the rest of the docs.

Also applies to: 80-85

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@WorldOS-GUI-RUNBOOK.md` around lines 27 - 35, The two unlabeled fenced code
blocks (one starting with "cd /Users/lume/ClawDnD-val" and the other at the
block around lines 80–85) must be tagged with a language identifier to satisfy
MD040; update each triple-backtick fence to use ```bash so both blocks are
labeled consistently with other examples in WorldOS-GUI-RUNBOOK.md and will pass
the linter.
scripts/install-desktop-shortcut.sh (1)

33-34: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Fix stale installed-filename output in post-install messaging.

The script installs WorldOS OpenWorlds.command and WorldOS OpenWorlds.webloc, but these lines still print WorldOS Dashboard.*, which is misleading during setup verification.

Proposed fix
-echo "  • 'WorldOS Dashboard.command'  — double-click: starts the viewer + opens $URL"
-echo "  • 'WorldOS Dashboard.webloc'   — clickable link to $URL (once the server is running)"
+echo "  • 'WorldOS OpenWorlds.command'  — double-click: starts the viewer + opens $URL"
+echo "  • 'WorldOS OpenWorlds.webloc'   — clickable link to $URL (once the server is running)"
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@scripts/install-desktop-shortcut.sh` around lines 33 - 34, Update the
post-install echo messages so they match the actual installed filenames: change
the strings that currently print "WorldOS Dashboard.command" and "WorldOS
Dashboard.webloc" to "WorldOS OpenWorlds.command" and "WorldOS
OpenWorlds.webloc" respectively in the echo statements in
install-desktop-shortcut.sh so the output correctly reflects the installed
artifacts.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@qa/GUI_WORKBOOK.md`:
- Around line 22-25: The markdown table under the section header "## REAL bugs
(verified; the actual punch-list)" violates MD058 by being adjacent to paragraph
text; fix it by inserting a blank line before the table and a blank line after
the table block so the table is isolated from surrounding text, ensuring the
header and subsequent paragraphs are separated from the table.

In `@qa/release_readiness.py`:
- Around line 191-205: The code currently only flags mismatched or mixed
non-empty run_build_sha values; update the logic around
build_shas/persona_scores to also treat missing run_build_sha as an evidence
gap: after computing persona_scores (and before validating mixed or matching
SHAs) detect any persona p where p.get("run_build_sha") is falsy and append an
evidence_gaps entry (gate "native_gate", missing like "build_sha provenance",
detail listing personas missing run_build_sha e.g. ", ".join(p['persona'] for p
in missing)). Keep the existing mismatched (args.build_sha) and mixed-build
checks but ensure the missing-provenance check runs first so a missing
run_build_sha prevents passing the native_gate.

In `@qa/ui_playtest_app.sh`:
- Line 236: The guard relying on app_pid_for_bundle is ineffective because
app_pid_for_bundle can exit 0 even when it finds no PID; modify the
app_pid_for_bundle function so it returns a non-zero exit status when no
matching process is found (i.e., set a failure exit code and/or call return 1
when the PID variable is empty) and ensure callers like the check in the script
that does app_pid_for_bundle "$APP_BUNDLE" >/dev/null 2>&1 || { ... } will
correctly take the error branch; update any other call sites (the similar block
around the 564-573 check) to rely on this new non-zero exit behavior.

In `@script/build_and_run.sh`:
- Around line 66-75: The current wait_for_bundle_pid function returns the first
PID from bundle_pid which may be a pre-existing instance; change the logic to
validate candidate PIDs from bundle_pid before returning by ensuring the PID
belongs to the process started by this run (e.g., compare process start time
against this script's start time, or check the process command-line/environment
for a unique marker set when launching the new instance); implement a helper
like pid_belongs_to_current_launch(pid) and use it in wait_for_bundle_pid (and
the other similar block at lines 186-190) to skip PIDs that do not match the
current launch context and only return a PID that passes validation.

In `@viewer/monitor.html`:
- Around line 113-118: The user-facing copy still refers to "the dashboard"
while the link and flow have moved to OpenWorlds; update all visible text around
the OpenWorlds link created in the title variable (where heading, c.name/c.id
and the href "/openworlds/" are used) to say "OpenWorlds" instead of "dashboard"
and ensure any adjacent meta or help text that directs users to start a game is
changed to reference OpenWorlds (and any phrasing like "start a game in the
dashboard" is replaced with "start a game in OpenWorlds").

In `@viewer/tests/test_openworlds_static.py`:
- Around line 29-32: In setUp, after saving the existing environment values
(self._old_worldos_art_repo_root, self._old_clawdnd_art_repo_root,
self._old_worldos_repo_root, self._old_clawdnd_repo_root) clear those env vars
(os.environ.pop or del) so host-specific WORLDOS_ART_REPO_ROOT,
CLAWDND_ART_REPO_ROOT, WORLDOS_REPO_ROOT and CLAWDND_REPO_ROOT do not influence
tests; keep the existing tearDown restore logic that resets those four
attributes back into os.environ to avoid side effects.

---

Outside diff comments:
In `@scripts/install-desktop-shortcut.sh`:
- Around line 33-34: Update the post-install echo messages so they match the
actual installed filenames: change the strings that currently print "WorldOS
Dashboard.command" and "WorldOS Dashboard.webloc" to "WorldOS
OpenWorlds.command" and "WorldOS OpenWorlds.webloc" respectively in the echo
statements in install-desktop-shortcut.sh so the output correctly reflects the
installed artifacts.

In `@WorldOS-GUI-RUNBOOK.md`:
- Around line 27-35: The two unlabeled fenced code blocks (one starting with "cd
/Users/lume/ClawDnD-val" and the other at the block around lines 80–85) must be
tagged with a language identifier to satisfy MD040; update each triple-backtick
fence to use ```bash so both blocks are labeled consistently with other examples
in WorldOS-GUI-RUNBOOK.md and will pass the linter.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 4a94ee3a-b880-48ab-a0ca-eb6c876abc87

📥 Commits

Reviewing files that changed from the base of the PR and between 82aeaf2 and bb89dc5.

📒 Files selected for processing (37)
  • .gitignore
  • README.md
  • WorldOS-GUI-RUNBOOK.md
  • WorldOS-NORTH-STAR.md
  • WorldOS-OPERATING-GOAL.md
  • WorldOS-RUNBOOK.md
  • docs/MODEL-TIERING-STRATEGY.md
  • docs/OPENWORLDS_FIDELITY_PLAN.md
  • macos/WorldOSApp/Sources/WorldOSApp/Models/ProviderModels.swift
  • macos/WorldOSApp/Sources/WorldOSApp/Services/AppProcessService.swift
  • macos/WorldOSApp/Sources/WorldOSApp/Services/ProviderAdapters.swift
  • macos/WorldOSApp/Sources/WorldOSApp/Services/RepositoryLocator.swift
  • macos/WorldOSApp/Sources/WorldOSApp/Views/CampaignsView.swift
  • macos/WorldOSApp/Sources/WorldOSApp/Views/MonitorView.swift
  • macos/WorldOSApp/Sources/WorldOSApp/Views/PlayView.swift
  • macos/WorldOSApp/Sources/WorldOSApp/Views/ProvidersView.swift
  • macos/WorldOSApp/Sources/WorldOSApp/Views/RootView.swift
  • macos/WorldOSApp/Sources/WorldOSApp/Views/SettingsView.swift
  • qa/GUI_WORKBOOK.md
  • qa/SCORECARD.md
  • qa/play_human.sh
  • qa/release_gate.sh
  • qa/release_readiness.py
  • qa/test_macos_app_static.py
  • qa/test_release_gate_static.py
  • qa/test_release_readiness.py
  • qa/ui_playtest_app.sh
  • script/build_and_run.sh
  • scripts/install-desktop-shortcut.sh
  • scripts/play.sh
  • scripts/play_party.sh
  • viewer/monitor.html
  • viewer/openworlds/screen-character.jsx
  • viewer/server.py
  • viewer/tests/test_openworlds_static.py
  • worldos-dashboard.command
  • worldos-play.command

Comment thread qa/GUI_WORKBOOK.md
Comment thread qa/release_readiness.py
Comment thread qa/ui_playtest_app.sh
Comment thread script/build_and_run.sh
Comment thread viewer/monitor.html
Comment thread viewer/tests/test_openworlds_static.py

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@qa/release_readiness.py`:
- Around line 275-276: The existence check treats every args.palette_source as a
filesystem path which falsely flags valid labels; update the check in
qa/release_readiness.py so that you only verify
Path(args.palette_source).exists() when the value looks like a path (e.g.
contains a path separator or is an absolute/relative path indicator) and
otherwise treat it as a label and skip the existence check; keep using the same
evidence_gaps append with gate "palette_live" when a real path is missing and
leave label values untouched (references: args.palette_source, evidence_gaps,
and the "palette_live" gate).
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c02d62be-1c66-4898-a657-bc5f2fcd58fd

📥 Commits

Reviewing files that changed from the base of the PR and between bb89dc5 and 77a1578.

📒 Files selected for processing (4)
  • README.md
  • qa/SCORECARD.md
  • qa/release_readiness.py
  • qa/test_release_readiness.py
✅ Files skipped from review due to trivial changes (1)
  • qa/SCORECARD.md
🚧 Files skipped from review as they are similar to previous changes (1)
  • qa/test_release_readiness.py

Comment thread qa/release_readiness.py Outdated
@100yenadmin

Copy link
Copy Markdown
Member Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented May 31, 2026

Copy link
Copy Markdown
✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@100yenadmin
100yenadmin marked this pull request as ready for review May 31, 2026 14:28
@100yenadmin
100yenadmin merged commit b15ad3c into main May 31, 2026
9 of 10 checks passed
100yenadmin added a commit that referenced this pull request May 31, 2026
Sync takeover docs after PR #465, anchor the UX-first sprint in #467, preserve #466 as the clean RRI gate, and record PR #464 M0 contract issue cleanup.
100yenadmin added a commit that referenced this pull request May 31, 2026
Replace self-staling origin-tip wording with a doc-sync baseline, keep #466 anchored to the post-#465 code baseline, and require agents to re-verify current origin/main before acting.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant