Verification and proof

Understand what a result proves, which commit was checked, and what still blocks acceptance.

Recorded checks

Issues without BDD scenarios use ordinary project tests. The agent commits the implementation, starts meaningful commands through the host, and submits their command IDs with the issue revision and tested commit.

The host checks completion, exit status, and a clean matching commit at command start and finish. A message saying “tests passed” is not a substitute for that record.

Optional BDD scenarios

When an issue declares behavior scenarios, the worker runs them with Cucumber.js. Stable scenario IDs are carried by @bdd-<scenario-id> tags. The agent submits Cucumber Messages NDJSON for the current issue revision and tested commit.

The host parses the messages and compares them with the declared scenarios. Without BDD scenarios, Cucumber is not required.

Inspect proof artifacts

Proof can include Markdown, images, video, HTML, other files, and links. Screenshots show the observed interface; live previews let you inspect a running result. Verification records and pull request checks answer different questions and remain individually inspectable.

Agents publish artifacts explicitly with share_proof and register loopback previews with register_preview_target. Command output remains in command history; it is not automatically published as a proof artifact.

The primary pull request’s observed head must match the tested commit. If the branch changes, verification must run again. Earlier proof remains part of the history.

Repository closeout policy

A repository can declare .acpdash/closeout.yaml. The host pins this policy from the base commit for each issue revision, so edits by the worker cannot loosen the current requirements.

Required commands identify the issue, revision, and policy item. Ordinary commands do not satisfy those policy items. Depending on the policy, acceptance can also wait for independent review, CI, or resolved review threads.

Independent review currently supports a Codex read-only execution path. A different Codex model does not count as a different provider. A Codex implementation therefore needs an applicable receipt policy or an eligible different provider. A missing review capability remains a blocker.

The optional retry.maxFailedAttemptsPerItem setting limits failed executions of each pinned command item. At the limit, the host asks for corrective feedback in Needs you. With no retry setting, the host imposes no attempt limit.

See preflight and retries for a policy example, the agent’s closeout steps, and how to restore attempts. The canonical agent instructions live in AGENTS.md.

Verify ACPDash itself

From the repository root:

bun run check
bun run test
bun run bdd

check covers types, lint, CSS, formatting, dead code, and the web build. Tests run separately. For isolated browser verification:

bunx playwright install chromium webkit
bun .agents/skills/verify-acpdash/scripts/verify.ts

The helper owns a temporary host, repository, storage, browser, and worktrees. It writes screenshots, assertions, and traces to .verification/, then cleans up the temporary instance. The default scenario covers project creation, not every feature. The feature map lists additional scenarios.