docs: require a single Codex launch trigger (#1243)

Co-authored-by: Steven Enamakel <31011319+senamakel@users.noreply.github.com>
Co-authored-by: WOZCODE <contact@withwoz.com>
Co-authored-by: sanil-23 <sanil@vezures.xyz>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Cyrus Gray <144336577+graycyrus@users.noreply.github.com>
Co-authored-by: CodeGhost21 <164498022+CodeGhost21@users.noreply.github.com>
Co-authored-by: oxoxDev <164490987+oxoxDev@users.noreply.github.com>
Co-authored-by: Mega Mind <146339422+M3gA-Mind@users.noreply.github.com>
Co-authored-by: Gaurang Patel <ptelgm.yt@gmail.com>
Co-authored-by: unn-Known1 <unn-known1@users.noreply.github.com>
Co-authored-by: Steven Enamakel <enamakel@tinyhumans.ai>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Steven Enamakel <senamakel@users.noreply.github.com>
Co-authored-by: Steven Enamakel's Droid <enamakel.agent@tinyhumans.ai>
Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>
Co-authored-by: senamakel-droid <281415773+senamakel-droid@users.noreply.github.com>
Co-authored-by: YellowSnnowmann <167776381+YellowSnnowmann@users.noreply.github.com>
Co-authored-by: Neil <neil@maha.xyz>
Co-authored-by: Neel Mistry <neelmistry@Neels-MacBook-Pro.local>
Co-authored-by: obchain <167975049+obchain@users.noreply.github.com>
Co-authored-by: Jwalin Shah <jshah1331@gmail.com>

AGENTS.md

@@ -73,6 +73,12 @@ cargo check --manifest-path app/src-tauri/Cargo.toml
 
 **Quality**: ESLint + Prettier + Husky in the `app` workspace.
 
+### Codex web / Linear-launched PR checklist
+
+Before opening AI-authored PRs from Codex web sessions or Linear-launched implementation agents, follow [`docs/agent-workflows/codex-pr-checklist.md`](docs/agent-workflows/codex-pr-checklist.md).
+
+This checklist is required for remote agents because OpenHuman has several merge gates that are easy to miss in partial environments: Prettier, Rust formatting, TypeScript typecheck, focused Vitest coverage, controller dispatch parity, and Tauri vendored dependency availability. If a command cannot run in the remote environment, the PR body must report the exact blocked command and error instead of claiming validation passed.
+
 ### Agent debug runners (`scripts/debug/`)
 
 Use these wrappers instead of invoking Vitest / WDIO / cargo directly when iterating — they keep stdout summary-sized and tee full output to `target/debug-logs/<kind>-<suffix>-<timestamp>.log`. Add `--verbose` to also stream raw output. See [`scripts/debug/README.md`](scripts/debug/README.md).
@@ -631,4 +637,4 @@ Stats: 20 obs (8,333t read) | 593,112t work | 99% savings
 2882 " 🔵 openhuman Eval Infra: Does Not Exist; Phase D Requires Bootstrap from Scratch
 
 Access 593k tokens of past work via get_observations([IDs]) or mem-search skill.
-</claude-mem-context>
+</claude-mem-context>

docs/agent-workflows/codex-pr-checklist.md

@@ -0,0 +1,108 @@
+# Codex PR Checklist
+
+Use this checklist for Codex web sessions, Linear-launched implementation agents, and any other remote agent that opens OpenHuman PRs.
+
+## Required Preflight
+
+Run this before editing files:
+
+```bash
+pwd
+git status --porcelain
+git branch --show-current
+git remote -v
+test -f AGENTS.md
+test -f docs/src/README.md
+test -f Cargo.toml
+test -f app/package.json
+```
+
+Expected repository path in Codex web is `/workspace/openhuman`. If the checkout is missing or the command shows another project, stop immediately and report the environment binding problem. Do not edit files in the wrong repository.
+
+## Launch Trigger Rule
+
+Use exactly one Codex trigger per Linear issue.
+
+Preferred launch pattern:
+
+```md
+@Codex use the Codex environment for jwalin-shah/openhuman.
+
+Work issue <ISSUE-KEY>.
+Expected path: /workspace/openhuman.
+Start from latest origin/main.
+Create branch codex/<ISSUE-KEY>-<short-title>.
+Follow docs/agent-workflows/codex-pr-checklist.md exactly.
+Do not open duplicate PRs. If validation is blocked, report exact command and error in the PR body and Linear.
+```
+
+Do not also set `delegate: Codex` when posting an explicit `@Codex` launch comment. Linear delegate metadata can start its own Codex thread, so combining both mechanisms can double-trigger the same issue.
+
+If using `delegate: Codex` as the only trigger for an integration that requires it, do not add an `@Codex` comment. Record in the issue which trigger was used.
+
+## Branch And PR Rules
+
+- Start from latest `origin/main` unless the Linear issue explicitly says otherwise.
+- Use one branch and one PR per Linear issue.
+- Name branches `codex/<ISSUE-KEY>-<short-title>`.
+- Do not open duplicate PRs for the same issue. If a retry is needed, update the existing PR branch or close the stale duplicate and state which PR is canonical.
+- PRs should target `jwalin-shah/openhuman:main` unless upstream permissions allow `tinyhumansai/openhuman:main`.
+
+## Validation Before PR
+
+Run the smallest checks that prove the changed surface, plus the relevant merge gates:
+
+```bash
+# Always run for app or docs-visible app changes
+pnpm --filter openhuman-app format:check
+pnpm typecheck
+
+# Focused app tests for changed TS/React behavior
+pnpm --dir app exec vitest run <changed-test-files> --config test/vitest.config.ts
+
+# Root Rust changes
+cargo fmt --manifest-path Cargo.toml --all --check
+
+# Tauri shell changes
+cargo fmt --manifest-path app/src-tauri/Cargo.toml --all --check
+```
+
+For Rust behavior changes, prefer focused tests through the repo wrappers where available:
+
+```bash
+pnpm debug rust <test-filter>
+```
+
+If a command cannot run because the environment lacks vendored files or system packages, do not claim it passed. Copy the exact command and blocker into the PR body.
+
+## Refactor Parity Rules
+
+For behavior extraction and architecture refactors:
+
+- Identify the old guard order, fallback order, dispatch contract, or public API being preserved.
+- Add focused parity tests when the behavior can be tested without broad integration setup.
+- Do not reorder guards, fallback layers, RPC methods, or dispatch paths unless the issue explicitly asks for a behavior change.
+- When adding a drift guard, verify it checks the source of truth as it exists in this repo. Do not assume generated strings are written literally in source files.
+
+## PR Body Requirements
+
+Every AI-authored PR must include:
+
+- Linear issue key and URL.
+- Branch name.
+- Commit SHA.
+- Files changed summary.
+- Validation commands run.
+- Validation commands blocked, with exact error text.
+- Behavior intentionally changed, or `No intended behavior change`.
+- Any duplicate/stale PRs that were closed or superseded.
+
+## Review Before Handoff
+
+Before handing off:
+
+- Re-check GitHub CI status for the PR.
+- Pull failed check logs before guessing.
+- Fix format/type/test failures that are local to the PR.
+- Leave broad system dependency or environment failures as explicit blockers.
+- Update the Linear issue with PR URL, commit SHA, validations, and blockers.