Protect your first behavior
This guide covers the additional sealed CI verification path that establishes Balladeer’s hosted Protected status. For the everyday agentic workflow, start with agentic code review on push: it checks agreed promises without a sealed verifier, working CI, or a manually built behavior map.
For sealed protection, start with one checkable behavior, workspace access, and an enrolled repository with working CI.
1. Ask your agent to propose the behavior#
Your agent can also offer to capture a promise during ordinary work.
For example:
Propose a Balladeer promise: an invited teammate can join an existing workspace without connecting another repository. Joining must not enroll a new repository or modify CI.
This is a request to draft a proposal. The agent should preserve your intended behavior, identify the beneficiary and trigger, describe the expected outcome, and supply passing and failing cases. It should clarify uncertainty that changes the meaning instead of inventing a product decision.
For this example, a passing case could join an invited person to the intended workspace while the repository enrollment list and workflow remain unchanged. A failing case could require repository enrollment before allowing that person to join. An expired invitation needs an explicit boundary: the promise need not imply that an expired invitation must work.
Review the proposed owner as well as the words. An agent may propose; it cannot agree on your behalf merely because you asked it to draft something.
2. Have the named owner agree#
The named owner can agree on the proposal's Balladeer page after reading the behavior, cases, and scope. Correct wording that would permit the wrong result before agreeing.
The owner can also agree in their own connected agent conversation. The agent reads the current
proposal with get_proposal, shows its full meaning, and asks whether the owner agrees. On a clear
yes, it submits that exact displayed proposalDigest as shownDigest, with the owner's actual
words. The server checks that this connection belongs to the named owner and the proposal has not
changed. A tool refusal means agreement did not happen; a chat reply alone is not a recorded action.
For someone else's connection, or another lifecycle action, use the browser sign-off path and its one-time code. The agent cannot substitute its judgment for the person's agreement.
Expected result: the behavior is now agreed. It is Unprotected until a verifier qualifies. It can already be returned to agents as agreed context, with the lack of protection clearly shown.
3. Build a verifier in your repository#
After successful agreement in the conversation, your agent can continue to build the check unless you asked it not to. There is no second meaning-approval step for that work. Normal repository and host permissions still apply.
If you agreed in the browser, use the owner-only Ask your agent to build the checks card and Copy agent instruction, then give that instruction to your connected agent. It names the promise, workspace, and repository and asks the agent to reuse existing setup. Copying it alone does not start an agent or prepare a packet.
The agent reads the agreed meaning and uses the supported qualification packet. The
prepare_qualification tool or balladeer prepare <promise-id> supplies the metadata; the agent
must not invent it.
Preparing the packet does not require a new approval of already-agreed meaning and does not start protection. If a live packet already exists, follow the response and locate that packet. Preparing a replacement deliberately invalidates the earlier one; it is not a generic retry.
The verifier must exercise the actual behavior. For our example, it must test the joining path and the relevant effects on enrollment and CI. Checking that a particular sentence exists on a page would establish only that the sentence exists.
Qualification must establish that working behavior passes, a deliberate violation is caught, a behavior-preserving refactor still passes, and changes to locked verification material are detected. The workflow also verifies the reporting identity and exact checked materials. A crashing test is not proof that a deliberate behavioral violation was caught.
4. Qualify through CI#
Review the verifier and workflow changes through your normal development process. Qualification requires a push to the enrolled protected default branch. A pull-request run is advisory and cannot qualify a verifier, even if it passes.
When qualification succeeds for the exact agreed meaning, protection starts automatically. There is no separate activation button or owner sign-off for starting protection.
Expected result: the promise shows its qualified verifier and result, and identifies the checked commit. Follow the packet's cleanup guidance for one-time qualification metadata. Completed qualification packets are not a reason to repeatedly prepare new ones. An ordinary subsequent run provides ongoing evidence.
5. Check what you have accomplished#
You should be able to point to the agreed behavior, its owner, the qualified verifier, and the CI evidence. If you have only completed agreement, say so: the result is agreed but unprotected.
For any inconclusive result, read promise states and resolve a result. Do not weaken the promise or its failing case to obtain a passing check.