README.md

Scripts

Purpose

Document the executable validation and orchestration utilities under scripts/, including which commands are canonical and how to interpret their results.

Run commands from the repository root unless a command explicitly says otherwise.

Canonical Repository Validation

Use:

python3 scripts/validate-agentdefaults.py

This is the normal entrypoint after AgentDefaults changes. It composes the repository's core and specialist validators rather than requiring contributors to remember every component command.

Do not report it as passed unless it actually completed successfully.

Component Validators

Component validators exist for focused development and regression diagnosis:

validate-agentdefaults-core.py
validate-ponytail-graft.py
validate-engineering-contracts.py
validate-cross-tool-routing.py
validate-documentation-stack.py
validate-devsecops-security-stack.py
validate-github-actions-stack.py
validate-codebase-maintenance-stack.py
validate-claude-video-editing-stack.py
validate-bounded-completion.py

Use the relevant component while iterating, then run validate-agentdefaults.py before declaring repository validation complete.

validate-ponytail-graft.py checks the repository-local Ponytail + Graft installer contract: exact sidecar pins, compatibility-prompt routing, hardening requirements, the repo-local Graft runtime-health gate, bounded dependency repair, and rejection of canonical global/floating install paths.

validate-github-actions-stack.py checks the GitHub Actions specialist's manifest registration, authority/trust schema, canonical agent/skill/prompt/example/acceptance invariants, cross-tool routing, Copilot adapter references, and inclusion in the primary validation suite.

validate-claude-video-editing-stack.py checks the local Claude Code video-editing stack's manifest/routing, native /youtube-edit skill, Parakeet and EDL helper contracts, HyperFrames/FFmpeg/evidence/licensing/style-learning invariants, and acceptance-test coverage. It also runs tools/video/test_video_tools.py: model-free Parakeet normalization tests plus FFmpeg render/QC tests on synthetic media, which skip when FFmpeg is absent.

A repository-level validator does not replace build/lint/type/test/e2e/security checks or actual GitHub Actions runtime qualification in a target repository being operated by one of the agents.

Bounded Completion Control Plane

bounded-completion.py is the stable command entrypoint for the formal bounded completion loop. Its implementation is split across bounded_completion/.

Authoritative runtime evidence is stored under ignored .agent-loop/ in the target repository root.

Basic lifecycle:

python3 scripts/bounded-completion.py init --contract <contract.json>
python3 scripts/bounded-completion.py status
python3 scripts/bounded-completion.py advance --description "implemented coherent slice"
python3 scripts/bounded-completion.py verify
python3 scripts/bounded-completion.py gate

Use the full operator guide at ../docs/loops/README.md.

Bounded Completion Command Reference

Command	Purpose
init --contract <path>	Initialize a new active task.
init --contract <path> --replace-active	Archive the current task and deliberately start another.
status	Read current durable state and findings.
advance --description <text>	Advance the full-loop counter for a genuine new implementation/review cycle.
verify	Run configured deterministic verification and persist evidence.
criterion --id <id> --status <status> --evidence <text>	Record acceptance-criterion state/evidence.
`record-review --kind plan	diagnosis
add-finding --from-file <json>	Add a structured reviewer finding.
dispose-finding --id <id> --disposition <value> [--evidence <text>]	Record the current disposition of a finding.
resolve-finding --id <id> --evidence <text>	Resolve an accepted finding with evidence.
record-visual --criterion <id> --artifact <path> --inspected-by <who> --review <text>	Record actual visual artifact review.
record-diff --summary <text>	Record final/current diff inspection evidence.
record-integrity --summary <text> <assertion flags>	Record validation-integrity assertions after inspecting the current diff.
`approve --name --source operator-confirmed	runtime-policy --evidence `
gate	Evaluate the objective completion gate against fresh evidence.
escalate --reason <text>	Persist a terminal escalation reason.
stop-hook	VS Code custom-agent Stop-hook entrypoint; normally invoked by the runtime, not by hand.

Use:

python3 scripts/bounded-completion.py --help
python3 scripts/bounded-completion.py <command> --help

for exact arguments.

Exit Codes

For the bounded-completion CLI:

0  command succeeded; verify/gate passed when those commands were used
1  verify or gate completed but did not pass
2  control-plane/input/JSON/OS error

A nonzero gate result is not a reason to weaken a criterion or validator. Continue with materially useful work or escalate when the configured limits require it.

Do Not Manually Edit Loop State

When an equivalent control-plane command exists, do not hand-edit:

.agent-loop/current/task-contract.json
.agent-loop/current/state.json
.agent-loop/current/findings.json

The control plane maintains invariants and workspace fingerprints used to invalidate stale evidence.

Platform Notes

The canonical examples use python3 on macOS/Linux and CI. The bounded-completion Stop hook has Windows handling documented in ../docs/quickstarts/bounded-completion.md.

Do not invent or commit runtime/model identifiers that the repository cannot verify.

Safety

Verification commands are evidence-producing operations and should not intentionally dump secrets or unrelated credential stores.

The control plane does not itself create authorization for deployment, release publication, production mutation, credential rotation, force-push, destructive cloud actions or other privileged operations. Those remain governed by the selected owner and explicit task approval.

Validation Changes

When modifying validators or control-plane code:

1. inspect the acceptance-test document for the affected stack;
2. add a regression case for any material defect;
3. run the focused validator;
4. run python3 scripts/validate-agentdefaults.py;
5. report anything not executable in the current environment as unverified.

Ponytail + Graft installer or surrounding setup-documentation changes should run:

python3 scripts/validate-ponytail-graft.py
python3 scripts/validate-agentdefaults.py

GitHub Actions stack changes should run:

python3 scripts/validate-github-actions-stack.py
python3 scripts/validate-agentdefaults.py

Bounded-completion control-plane changes should run:

python3 scripts/validate-bounded-completion.py
python3 scripts/validate-agentdefaults.py

Claude Code local video-editing stack changes should run:

python3 scripts/validate-claude-video-editing-stack.py
python3 scripts/validate-agentdefaults.py