Skip to content

validation-playbook.md

Latest commit

 

History

History
151 lines (110 loc) · 3.33 KB

validation-playbook.md

File metadata and controls

151 lines (110 loc) · 3.33 KB
Raw

Agent Validation Playbook

Run the smallest validation set that matches the touched surface, then broaden when the change crosses package formats, launcher/runtime behavior, updater state, or patch drift handling.

Shell, Launcher, And Package Scripts

bash -n install.sh
bash -n scripts/lib/*.sh
bash -n launcher/start.sh.template
bash -n scripts/build-deb.sh
bash -n scripts/build-rpm.sh
bash -n scripts/build-pacman.sh
bash -n scripts/build-appimage.sh

For launcher behavior changes, rebuild or inspect the generated launcher:

sed -n '1,160p' codex-app/start.sh

If the change affects webview startup probes, run:

bash tests/webview_probe_equivalence.sh

Patch Registry And Linux Features

node --test scripts/patch-linux-window-ui.test.js
node --test linux-features/*/test.js
bash tests/scripts_smoke.sh

For upstream drift or protected surface analysis:

make inspect-upstream DMG=/path/to/Codex.dmg
make inspect-upstream-intel-devcontainer

For patch report validation:

scripts/ci/validate-patch-report.js codex-app/.codex-linux/patch-report.json

Local installs and scheduled CI share scripts/validate-upstream-dmg.js and scripts/lib/upstream-dmg-release-profile.js. Acceptance must inspect only the features recorded as enabled in the candidate patch report. Add fixtures proving enabled feature drift rejects promotion and disabled features are not probed. Exercise decision and issue behavior with:

node --test scripts/ci/upstream-dmg-acceptance.test.js
node --test scripts/ci/upstream-dmg-issue.test.js

Rust Crates

Updater:

cargo check -p codex-update-manager
cargo test -p codex-update-manager

Linux Computer Use:

cargo check -p codex-computer-use-linux
cargo test -p codex-computer-use-linux

Read Aloud:

cargo check -p codex-read-aloud-linux
cargo test -p codex-read-aloud-linux

Record & Replay:

cargo check -p codex-record-replay-linux
cargo test -p codex-record-replay-linux

Package Payloads

Build the relevant package format and inspect metadata/layout:

./scripts/build-deb.sh
dpkg-deb -I dist/codex-desktop_*.deb
dpkg-deb -c dist/codex-desktop_*.deb | sed -n '1,80p'

Run other package formats when shared payload logic, package hooks, updater bundles, desktop files, permissions, or runtime helpers are touched:

./scripts/build-rpm.sh
./scripts/build-pacman.sh
./scripts/build-appimage.sh

Use a package version override when a deterministic package name helps review:

PACKAGE_VERSION=2026.03.24.120000+deadbeef ./scripts/build-deb.sh

Updater Runtime Checks

When updater behavior changes, inspect service and state:

systemctl --user status codex-update-manager.service
codex-update-manager status --json
sed -n '1,120p' ~/.local/state/codex-update-manager/state.json
sed -n '1,160p' ~/.local/state/codex-update-manager/service.log

For rebuild candidates:

./scripts/rebuild-candidate.sh
./scripts/rebuild-candidate.sh --install

Broad CI

Run broader local CI when a change affects multiple package formats, updater install flows, launcher/runtime behavior, Nix pins, or core patch policy:

./scripts/ci-local.sh pr
./scripts/ci-local.sh all

For Nix hash refreshes:

scripts/ci/update-nix-hashes.sh
scripts/ci/validate-nix-pins.sh