Change lifecycle

A change is the unit of work that turns a request into a locally tested pull request. Its page shows one state at a time; the badge names below are the ones the console displays.

States

State (badge)	Meaning	What moves it on
Clarifying	The request was created.	A clarification, an AI criteria draft, or a criteria confirmation.
Criteria needed	Criteria were drafted or the thread changed; the original requester must confirm.	Confirm criteria by the original requester.
Ready to plan	Criteria are confirmed.	Prepare implementation plan.
Planning	A planning job is producing an exact plan from the authorized snapshot.	The system validates the plan, or the job fails safely back to Ready to plan.
Plan review	An immutable plan with a hash and expiry awaits a decision.	A Developer approves or rejects.
Approved	One exact plan hash is approved.	Start implementation by a Developer.
Implementing	A runner is working inside the exact source and planned paths.	Success moves to Reviewing; failure or cancellation is terminal.
Reviewing	An independent review is running, then delivery is brokered.	Approval brokers the pull request; changes required returns to Ready to plan.
Pull request delivery	Shown while the broker is creating the branch and pull request.	The pull request opens.
Pull request ready	The pull-request link is recorded; Helmhive’s workflow is complete.	Your Git provider, reviewers, and release process.
Needs attention	A job failed, review declined, or authority was lost.	Follow the safe next action on the page.
Cancelled	A Developer cancelled it, or its authority was revoked.	Prepare a fresh plan once the cause is resolved.

Within Implementing and Reviewing, the execution itself reports its own step: Queued, Implementing, Reviewing, Pull request delivery, Pull request ready, Failed, or Cancelled. See Change and run states.

Who does what

Create, clarify, prepare a plan: Requesters and Developers.
Confirm criteria: only the original requester, whatever other roles exist.
Draft criteria with AI, approve or reject, start, cancel: Developers.
Cancel: available while work is queued, implementing, or reviewing; not once brokering has started.

What a plan binds

The plan hash covers the change and service, the repository (provider, candidate, connection, URL, owner and name, base branch and commit, root, permission and capabilities), the service policy (id, revision, hash), the execution environment (revision, fingerprint, snapshot), the confirmed success criteria, and the plan content (scope, affected paths, checks, assumptions, risks, rollback, protected-path impact).

A plan is valid only if every check is an exact command from the service policy, at most ten checks are declared, every affected path that matches a protected pattern is declared in the protected-path impact, and the scope and rollback text are present. It expires seven days after it is prepared.

Freshness rules

Any drift in the bound identifiers makes the plan stale: a new commit on the branch, a policy revision, changed source capabilities, a changed environment binding, or a lost repository.
Only the latest plan revision can be decided, and each plan can be decided once.
An approval expires with its plan and is never reused; rejection returns the change to Ready to plan with the reason recorded.
Pausing or archiving the service, revising its policy, losing repository access, or revoking a runner cancels queued work and cooperatively stops running work. Reactivating a service may authorize a new workflow but never resurrects cancelled work.

Review and delivery rules

Review approval requires all three: a verdict of approve, every declared check exiting with code zero, and no blocking finding. Approved reviews queue the broker with an idempotency key derived from the execution and the review evidence hash, so a retried delivery reuses the same branch and pull request. Branches are named helmhive/change-<id>-<execution>; the pull request title is prefixed Helmhive: and its body cites the change, plan hash, and review evidence hash.