verify-bot-foundry

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.