| name | verify-bot-foundry |
| description | Verifies Pi Bot Foundry through its real CLI and generated Bot surface. Use after changing botctl, the Bot contract, templates, validation, or launch behavior. |
Verify Pi Bot Foundry
Launch
This is a short-lived CLI. No server stays running. From the repository root, run each drive in a fresh process:
python3 scripts/botctl.py --help
For the full deterministic pass:
python3 scripts/verify_foundry.py
Add --live only when Pi credentials and runtime access are available.
Doctor
Run these read-only checks first:
python3 -m py_compile scripts/botctl.py scripts/verify_foundry.py
python3 scripts/botctl.py --help
A useful offline instance has parseable Python and all five subcommands in help. Check pi --version only before an explicitly requested live drive.
Drive
Use scripts/botctl.py. Its public surface is:
python3 scripts/botctl.py create --spec examples/evidence-scout.json --output <scratch> --dry-run --json
python3 scripts/botctl.py create --spec examples/evidence-scout.json --output <scratch> --json
python3 scripts/botctl.py validate <scratch>/evidence-scout --json
python3 scripts/botctl.py inspect <scratch>/evidence-scout --json
umask 077
TASK_FILE="$(mktemp "${TMPDIR:-/tmp}/pi-bot-task.XXXXXX")"
${EDITOR:-vi} "$TASK_FILE"
python3 scripts/botctl.py run <scratch>/evidence-scout --task-file "$TASK_FILE" --json
rm -f -- "$TASK_FILE"
python3 scripts/botctl.py smoke <scratch>/evidence-scout --json
Fill, save, and close the editor before the run. Never interpolate task text into a shell command. The final command removes only the private TASK_FILE created and owned by this caller.
Read references/features/README.md and the matching feature file before a focused drive.
Evidence
verify_foundry.py writes no report by default. Use --report <private-path> only when a private audit artifact is actually needed; reports can contain local paths and runtime output and must never be committed. A profile smoke returns JSON with timestamp, command, Pi version, exit code, stdout, and stderr. It launches with parent context files disabled, drives the real /start prompt, and requires the workflow Skill's unique marker plus the exact one job and every anti-job from BOT.json; process exit alone is insufficient. Settings/tool consistency remains a static validator check.
Cleanup
verify_foundry.py owns a unique system temporary directory and removes it after the run. Manual drives must also use a new temporary path. Never point a test at bots/ unless the resulting Bot is an intentional deliverable.
Helpers
scripts/botctl.py is the product CLI.scripts/verify_foundry.py is the rerunnable end-to-end verifier.tests/test_botctl.py covers contract parsing, atomic creation, dry-run, overwrite refusal, tool boundaries, generated settings, and adversarial argv-safe task execution.tests/test_public_release.py checks portability and the public manifest.
