Skip to content

docs: add agent QA navigation map - #509

Merged
100yenadmin merged 2 commits into
mainfrom
codex/worldos-agent-doc-nav
Jun 1, 2026
Merged

docs: add agent QA navigation map#509
100yenadmin merged 2 commits into
mainfrom
codex/worldos-agent-doc-nav

Conversation

@100yenadmin

@100yenadmin 100yenadmin commented Jun 1, 2026

Copy link
Copy Markdown
Member

Summary

  • add a central agent navigation/current TOC to WorldOS-OPERATING-GOAL.md
  • add a fresh GUI agent quick start, command table, and port truth table to WorldOS-GUI-RUNBOOK.md
  • add qa/QA_TOOLS.md as the QA command index for handoff, built-app smoke, browser persona diagnostics, RRI, and story/mechanics lanes
  • mark older audit/checklist/roadmap docs as historical so they do not override current handoff/RRI truth

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. (No third-party material added.)

Validation

  • git diff --check
  • reference-existence check for all newly linked docs and QA tools
  • navigation-pointer check for handoff and RRI docs

Notes

Docs-only. No app build, handoff gate, RRI, or heavy local suite was run.

Summary by CodeRabbit

Release Notes

  • Documentation
    • Reorganized runbooks and guides with improved cross-references for better discoverability
    • Clearly marked historical documents to prevent reliance on outdated procedures
    • Created new comprehensive QA tools reference guide with workflow routing
    • Added clarified instructions for validation and testing procedures
    • Updated evidence tracking and release-related documentation for current workflows

@coderabbitai

coderabbitai Bot commented Jun 1, 2026

Copy link
Copy Markdown

Review Change Stack

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: d3c46afa-7852-444a-93c8-59d1ba263b09

📥 Commits

Reviewing files that changed from the base of the PR and between 9f9c9ca and 04a0458.

📒 Files selected for processing (2)
  • docs/OPENWORLDS_NATIVE_APP_ROADMAP.md
  • qa/GUI_WORKBOOK.md
🚧 Files skipped from review as they are similar to previous changes (2)
  • docs/OPENWORLDS_NATIVE_APP_ROADMAP.md
  • qa/GUI_WORKBOOK.md

📝 Walkthrough

Walkthrough

This PR establishes a unified QA documentation structure by introducing qa/QA_TOOLS.md as a centralized command reference and updating runbooks, navigation guides, and legacy documents to point to current sources while marking historical artifacts accordingly.

Changes

QA Documentation Navigation & Tools Hub

Layer / File(s) Summary
QA tools hub & runbook routing
qa/QA_TOOLS.md, WorldOS-GUI-RUNBOOK.md, WorldOS-OPERATING-GOAL.md, WorldOS-RUNBOOK.md
qa/QA_TOOLS.md consolidates command guidance, app_handoff_gate.py invocation, handoff_score interpretation, and evidence review order. WorldOS-GUI-RUNBOOK.md gains a Fresh GUI Agent Quick Start section with quick-start tables and port/route guardrails. WorldOS-OPERATING-GOAL.md adds an Agent Navigation TOC mapping common questions to specific docs. WorldOS-RUNBOOK.md updates read-order to include qa/QA_TOOLS.md between GUI-RUNBOOK and SCORECARD.
Evidence baseline & GUI workbook reframing
qa/SCORECARD.md, qa/GUI_WORKBOOK.md
qa/SCORECARD.md adds a Current Evidence Index table tracking latest handoff proof, release verdict, and next RRI action. qa/GUI_WORKBOOK.md reframes from living punch-list to historical artifact, updates the fast-handoff proof SHA to fd9dba5, and tightens #466 requirements for palette_live proof and persona evidence.
App testability contract & supporting references
docs/AGENT_GRADE_APP_TESTABILITY.md, qa/SCORING.md, qa/UI_PLAYTEST.md
docs/AGENT_GRADE_APP_TESTABILITY.md clarifies that command routing lives in qa/QA_TOOLS.md and WorldOS-GUI-RUNBOOK.md, and adds a Default local invocation section with a sample python3 qa/app_handoff_gate.py command. qa/SCORING.md and qa/UI_PLAYTEST.md add context pointers to the new routing hubs.
Historical document disclaimers & scope clarification
docs/ARCHITECTURE.md, docs/OPENWORLDS_*.md, docs/RELEASE_1.0_CHECKLIST.md, docs/ui-audit/MASTER_TRACKER.md, macos/WorldOSApp/RELEASE_CHECKLIST.md
Architecture, OpenWorlds fidelity/roadmap/audit, and legacy release docs are marked as historical with redirects to current sources in WorldOS-OPERATING-GOAL.md, WorldOS-GUI-RUNBOOK.md, qa/QA_TOOLS.md, and qa/SCORECARD.md. macOS and legacy release checklists clarify scope and link to qa/release_readiness.py.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

  • electricsheephq/WorldOS#501: Updates the same GUI/operating runbook and evidence ledger docs to adjust the current evidence baseline alongside runbook routing guidance.
  • electricsheephq/WorldOS#504: Introduces the hybrid handoff gate concepts and app_handoff_gate.py tooling that this PR centralizes and documents in qa/QA_TOOLS.md.
  • electricsheephq/WorldOS#507: Aligns GUI handoff gate workflow and evidence baseline around fd9dba5 and #466 requirements, with synchronized updates to the same qa/GUI_WORKBOOK.md and qa/SCORECARD.md.

🐰 A runbook walks through the door,
With tables, links, and paths galore,
QA tools now stand in one clear place—
No more docs spinning through cyberspace!

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title 'docs: add agent QA navigation map' directly describes the main change: adding navigation and QA tooling documentation to guide agents through the testing workflow.
Description check ✅ Passed The pull request description follows the template with complete sections: Summary lists all four major changes, Licensing/CLA checklist is fully checked, and Validation lists specific checks performed.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.


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

@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: 2

🤖 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 `@docs/OPENWORLDS_NATIVE_APP_ROADMAP.md`:
- Line 4: Replace the host-specific absolute path '/Users/lume/ClawDnD-val' in
the "validation path" sentence with a portable repo-relative instruction such as
'<repo-root>/ClawDnD-val' or simply 'repo-root/ClawDnD-val' (or use the
placeholder '<repo-root>') so the note is not tied to a single user's machine
and is clear to all contributors.

In `@qa/GUI_WORKBOOK.md`:
- Around line 21-23: Change the compound modifier "web scripted smoke" to the
hyphenated form "web-scripted smoke" in the sentence that lists the tests (the
phrase currently inside the parentheses starting with
`handoff-20260601T085319Z-fd9dba5`), so the line reads "...passed web-scripted
smoke, built-app scripted smoke, and a...". Ensure only the modifier is
hyphenated and surrounding punctuation/spacing remains unchanged.
🪄 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: fb755693-207d-462c-a714-0a2a24e240d8

📥 Commits

Reviewing files that changed from the base of the PR and between 520136b and 9f9c9ca.

📒 Files selected for processing (16)
  • WorldOS-GUI-RUNBOOK.md
  • WorldOS-OPERATING-GOAL.md
  • WorldOS-RUNBOOK.md
  • docs/AGENT_GRADE_APP_TESTABILITY.md
  • docs/ARCHITECTURE.md
  • docs/OPENWORLDS_FIDELITY_PLAN.md
  • docs/OPENWORLDS_NATIVE_APP_ROADMAP.md
  • docs/OPENWORLDS_UI_AUDIT.md
  • docs/RELEASE_1.0_CHECKLIST.md
  • docs/ui-audit/MASTER_TRACKER.md
  • macos/WorldOSApp/RELEASE_CHECKLIST.md
  • qa/GUI_WORKBOOK.md
  • qa/QA_TOOLS.md
  • qa/SCORECARD.md
  • qa/SCORING.md
  • qa/UI_PLAYTEST.md

Comment thread docs/OPENWORLDS_NATIVE_APP_ROADMAP.md Outdated
Comment thread qa/GUI_WORKBOOK.md Outdated
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