Promise lifecycle and states
A promise has separate states for recorded intent, agreed meaning, and evidence about the behavior. Recorded intent can guide future work before agreement. Agreement makes a promise eligible for agentic checks. Qualified sealed CI evidence supplies the additional Protected status. None of those steps proves deployment or every possible input.
From recorded intent to checks#
flowchart TD
A[Intent recorded with consent] --> R[Relevant agents see it as not agreed]
A -->|Named owner agrees the meaning| B[Agreed meaning]
B --> P[Agent pushes a related change]
P --> J[Agentic check of selected promises]
J --> K[Kept / Broken / Could not tell]
K -->|Reproduced break repaired| T[Regression test in the ordinary suite]
B -->|Separate sealed verifier qualifies on default branch| C[Protected through sealed CI]
C --> D[Ongoing sealed CI evidence]
D --> E[Healthy / Threatened / Unknown]Scroll the diagram horizontally on small screens. The states and transitions are explained in the text below.
The push-check path does not require sealed CI qualification and does not update its protection posture. An agentic verdict applies to the selected promise and checked change. A missing or unselected check is a gap, never a pass.
Can a proposal be visible before agreement?#
Yes. Relevant recorded promises can reach their recorder's agent and, when enabled in the workspace, teammates' agents, with attribution and the label not agreed. Agents preserve applicable intent and expose conflicts before acting, while keeping its standing visible. See capture.
Explicit sharing for coordination is a separate route for tentative work. Sharing does not agree or protect the meaning. The named owner can agree the current proposal in their own connected conversation or browser; see the agreement path.
Agentic check results#
| Result | Meaning |
|---|---|
| Kept | Passing cases were exercised on the checked commit. |
| Broken | A reproduction failed on the changed commit and passed on the base, verified by the runner. |
| Could not tell | No usable verdict was established. |
These are advisory local-check results, not the sealed CI states below. They do not qualify protection. See agentic code review on push for selection, gaps, and repair.
What the sealed CI states mean#
Labels vary slightly between the catalog, promise page, and agent responses. Read the explanation, checked commit, and time alongside the label.
| State or label | What it means | What to do next |
|---|---|---|
| Proposed / awaiting agreement | Intent is recorded and can guide relevant work with its standing shown. It is not agreed or Protected. | The named owner reviews the meaning and cases. |
| Agreed, Unprotected | The owner agreed the meaning, but no verifier has qualified against it. | Keep using agreed context and checking on push. Qualify a verifier for sealed protection. |
| Qualified · protection starting | A verifier qualified and the system is starting protection from that result. | Inspect the qualification result. There is no manual activation step. |
| Protected / Healthy | A bound verifier checked this meaning and usable evidence says it held. | Preserve the behavior in future changes; inspect the checked commit and time when making a claim. |
| Threatened / Broken | A completed check reported that the agreed behavior did not hold. | Investigate and repair the behavior, or ask the owner to review an intentional meaning change. |
| Unknown | There is no usable verdict establishing whether the behavior holds. | Read the specific reason and restore usable evidence. |
| Stale | The bound verifier no longer matches the agreed meaning. Agent responses may label this Unknown and supply the stale explanation. | Restore verification of the current agreed meaning through the supported qualification path. |
| Seal broken | The checked materials or enrolled workflow identity could not be verified. The result cannot establish protection. | Inspect repair/requalification progress and its outcome. Do not rely on the previous pass. |
| Superseded | The meaning or promise has been replaced through the appropriate lifecycle action. | Use its current replacement; keep the old record as history. |
| Retired | The promise has been ended through an owner-approved action. It is no longer current planning context or scheduled protection. | Consult its history if needed; do not treat it as a current requirement. |
What does Unknown mean?#
Unknown means Balladeer cannot establish whether the behavior holds from usable evidence. It is neither a passing result nor a caught regression.
Consider the invited-teammate promise:
- The test completes and shows that joining requires adding a repository: the behavior was refuted, so the default-branch result can make the promise Threatened.
- The test process crashes before it can decide whether joining works: the result is Unknown.
- The run is canceled, the result is missing, or an earlier result is replayed: these cannot establish a current pass.
- The verifier no longer matches the agreed meaning: the evidence is stale, and the explanation must say why it cannot establish protection.
- The materials or workflow identity cannot be verified: a Seal broken explanation describes that evidence gap. It does not prove a customer-visible regression.
The promise is still agreed during these gaps. The team should preserve its meaning while restoring verification. An older passing run can remain in the history; that does not turn the current state green. A displayed “last checked” time can identify the last actual check rather than the moment a missing-result condition was detected.
Recovery depends on the reason. A canceled run needs a valid replacement run; a verifier that cannot execute needs a technical repair; a verifier that no longer matches the meaning needs appropriate qualification. Restored evidence may pass or refute the behavior. It is not automatically a pass.
See resolve an Unknown result for the procedure.
How does a promise change intentionally?#
Changing the agreed behavior requires a new meaning proposal and fresh owner agreement. Previous approval does not carry over to edited words or cases.
Where an existing protected revision is being revised, it remains authoritative while the new agreed revision awaits qualification. The pending revision is shown as agreed but unprotected. Once its verifier qualifies, the new revision becomes active and the old one is superseded. “The owner approved the new draft” alone does not complete that switch.
For example, if the team wants joining to include an optional repository connection, the owner must decide whether that is allowed variation under the current promise or a change to its meaning. An agent should expose that question rather than silently changing the expected result.
Is repairing a verifier the same as changing the promise?#
No. A technical repair restores a check of the same agreed behavior. A semantic revision changes what behavior the team is asking the software to preserve.
Balladeer can re-establish verification after locked materials change without asking the owner to agree the same meaning again. Evidence remains unusable during the gap, and a failed requalification needs attention. A separately proposed verifier replacement follows its named-owner review path. In either case, changing a test expectation to accept previously forbidden behavior is not a technical repair of the same promise.
What about ownership and retirement?#
Ownership transfer changes who is responsible for the meaning and requires the appropriate human action. It does not prove the behavior holds. Supersession and retirement preserve history while removing the old promise from current planning context.
Why does my PR result differ from the promise state?#
Pull-request checks describe a proposed change and are advisory. Only eligible protected default-branch evidence updates the recorded protection state or qualifies a verifier. A passing PR does not clear a broken default-branch result. Read the two kinds of CI evidence.