The change loop
This page describes the PR workflow, selected with clue init --acceptance=pr. New adoption defaults to local acceptance and uses the same proposal, evidence, digest and review obligations, with a human-run command and a Git-retained brief replacing the PR handoff. ID allocation and coordination stay the same.
Before editing, the agent asks one question: does this work change a promise the repository has already made? If not, it recommends the direct route, which is the default. If it does, or nobody is sure, it recommends the tracked route, which plans the change, tests it against acceptance criteria, and ends in a pull request you merge. The agent says why and names what it might still discover that would change the recommendation.
| Direct | Tracked | |
|---|---|---|
| Use when | The work keeps every promise the repository has already made | The work changes a promise, or nobody is sure |
| Examples | A bug fix that restores behavior an unchanged criterion already promises, regression tests, refactoring, maintenance, configuration within what was agreed, prose edits, an investigation someone will use | A new, changed, or retired acceptance criterion; a capability, decision, policy, or methodology change; a change to what a plan promises; behavior no criterion covers |
| What it involves | The change and the checks that apply to it | A change ID, a proposal in /changes/CH-xxx-*, a digest into docs/, an acceptance brief, and an agent review before you merge |
The number of files or the folders touched can prompt a second look, but they never decide the route. What decides it is whether a promise changes. The agent looks again when it learns more, and once more against the complete diff before integration. If direct work turns out to change a promise, it pauses and recommends tracked.
You can overrule a tracked recommendation. The work then goes ahead as direct, the repository is still kept truthful, and the final commit records your choice in three trailer lines: Cliewen-Route: direct, Cliewen-Recommendation: tracked, and a short Cliewen-Override stating the risk. Older commits that say simple and full, the routes' previous names, still count. A route never gives an agent permission to push. An agent pushes directly to an integration branch only when you explicitly allow it and the repository permits it. Releasing is not part of either route; your repository decides how, or whether, it releases.
Once the route is set, the agent reads only the part of the corpus that governs the task. clue context <id> prints the named artifact and the artifacts it links to, one hop by default, and says what it left out; --depth follows more hops. An acceptance-criterion or milestone ID resolves to the file that declares it. When the request names no usable ID, the agent starts at docs/README.md, picks the closest artifact, and runs the command there. It follows links outward only, because following them backward from a shared goal would pull in most of the corpus.
The tracked route has six stages, and only the last one is yours:
One real change, end to end
Cliewen pull request #2 made the last edge of the thread machine-checkable. Before that change, an active acceptance criterion could lose its test reference without clue noticing; after it, the validator reports the criterion and exits non-zero.
| Stage | What the change carried |
|---|---|
| Need | Make acceptance-criterion-to-test traceability enforceable rather than conventional |
| Proposal | CH-003 declared the intended AC↔test contract and served the baseline plan's traceability milestone |
| Durable capability | clue validate owns criteria such as AC-009, which requires a supported reference for every active legacy machine-proven criterion |
| Classified evidence | Focused tests show both the missing-reference failure and referenced-evidence success path; new or revised criteria also declare proof type and evidence direction |
| Implementation | Repository-owned exporters read executable metadata; the validator reads the common manifest and diagnoses missing or stale references |
| Digest | The transient CH-003 workspace disappeared; the capability, criteria, decisions, implementation, and tests remained |
| Acceptance | The branch became PR #2, CI ran the candidate, and a human merge accepted it into main |
The same shape applies to an ordinary product request. State the behavior, connect it to a criterion and evidence, implement until the thread and tests are green, digest the temporary proposal, and hand the exact verified commit to the protected pull request.
A correction that restores behavior already promised by an unchanged criterion may stay direct, with focused regression evidence. If the criterion must change or the implementation introduces behavior it does not cover, the accepted contract changes and the tracked route is recommended.
1. Branch
For a chosen tracked route, create ch-xxx-your-slug from accepted main. One initiating author takes one tracked change to its ready pull request before starting another. From the first commit onward, every changed session commits and pushes the branch: a push is durability, not readiness. Direct work and help on another pull request consume no tracked-change slot. Tracked work depending on an unmerged change stops at a blocking question until a human authorizes and records that dependency.
2. Propose
A tracked change commits /changes/CH-xxx-your-slug/proposal.md before implementation, pushes it, and opens the pull request as a draft. The proposal says what will change, why it matters, which plan item it serves or that it is plan-less, and where the decision boundary lies. The draft is where unfinished work lives and stays visible: it claims nothing and cannot be merged.
When the human wants to review the shape before code exists, they can opt into a spec-first pause. It is not the default. Proposing and implementing are different work, and their boundary is where a change can still be split, redirected, or handed to another agent. That is why the proposal is committed first. At the pause, the agent records it in tasks, briefly explains the proposal and implementation, and asks whether implementation should begin. The proposal is already pushed and readable on the draft pull request. The agent then waits for an answer.
tasks.md is an ordered checklist with dependencies first, and a task you mark [-] as infeasible says why on the same line. If a blocking question appears, write it to open-questions.md and stop. Record the answer as a typed decision only when it makes a future-shaping choice.
3. Implement
Before starting or resuming work for a milestone, the agent checks that the plan still serves its goal, the milestone is still wanted and achievable, and the remaining dependencies and order still make sense. It checks again when new evidence challenges the campaign. A passing check needs no record. If the plan no longer holds, the agent writes the mismatch and options in open-questions.md, pauses affected work, and asks a human to choose the replan. It declares that revision in the plan before resuming. Most replans are delivery adjustments, not decisions. A typed decision record is needed only when the selected course will constrain future work.
Change the permanent corpus and implementation together. Behavior-changing work names the Gherkin criteria it serves. A new or revised machine-proven criterion declares Test-type: Unit, Integration, E2E, or Performance and requires classified positive and negative executable references in .clue/evidence.yaml, unless it explicitly records (single-direction). Each executable carries one canonical AC identity, type and direction in native metadata, executable-bound custom metadata, or a stable naming fallback. Repository-owned exporters attribute and aggregate those references across every framework. The judge checks their identities and input fingerprints without running exporters or tests. A genuine Test-type: Human uses the acceptance brief; @draft exempts one not-yet-proven criterion; an unannotated legacy criterion retains one reference. Regenerate the repository's export after changing tests or their discovery inputs.
Never weaken a test or lint rule to make the build pass. A failing check is evidence about the change.
4. Digest
Once every implementation task is complete or explicitly infeasible, update durable documentation, decisions, indexes, plan bookkeeping, and release notes for shipped behavior or workflow changes. Then delete the /changes workspace.
Plan bookkeeping includes closing the plan. When a change completes a campaign's last milestone, the same digest sets that plan completed — a campaign is over once its last milestone is evidenced, and leaving it open makes the plan index claim work is in flight that is not. A successor plan is designated in that digest when one is decided; not having decided one is no reason to keep the finished plan open.
Deletion is the digest: the proposal has been absorbed into the current system truth, and Git retains the delta. main never contains /changes.
5. Verify and review
Commit the complete candidate, run the repository tests and clue validate --forbid-changes against that commit, then run clue-verify on the same commit. The skill challenges the full candidate before the pull request is marked ready. A host with context-isolated delegation starts a fresh read-only reviewer with the declared intent but without the implementation conversation; other hosts disclose an in-context fallback. Blocking findings are repaired, rechecked, and reviewed again. Keep advisories in the handoff rather than rewriting a clean commit. The loop stops after a pass with no blocking findings, or at the repository's maximum while waiting for a human decision. If accepted main advances, reconciliation means merging newer accepted main into the branch with a normal push instead of rewriting hosted history before checks repeat.
Several agents can collaborate without waiting for one another. Separate authors keep separate branches from accepted main, and collaboration stays within one pull request. A review of an existing PR names the hosted head it inspected. Where the forge supports them, actionable findings stay in unresolved review conversations. Any agent asked to fix one becomes the updater for that turn. It fetches and records that head, commits and pushes the repair with the turn that made it, which returns a ready pull request to draft. It reviews the repaired commit, confirms the hosted head is the reviewed commit, marks the pull request ready again, and only then resolves the finding. If another updater moved the head, normal Git non-fast-forward protection forces reconciliation and a new verification pass. If findings cannot be published as resolvable conversations, the agent says the PR is not merge-ready and names the enforcement gap. No forge can detect an edit or intent that remained only in a private worktree.
6. Open the review gate
For a tracked change, the pull request is an authorization and protected-integration gate, not a demand for duplicate human code review. The agent may publish the branch but does not accept its own tracked change; the human-controlled merge commit is the acceptance act. Configure that branch for merge commits and disable squash and rebase-and-merge so proposal, implementation, and digest remain reachable; from first publication, hosted history is never rebased or rewritten. Direct integration instead follows explicit user authorization and repository policy.
For a tracked change, the PR starts with an acceptance brief. It asks whether the plan item is still wanted, puts the added or changed criteria and their scenarios in front of the human, and names what merge binds. An authorized dependent change repeats its unmerged base, authorization, and binding meaning there; disclosure does not make the base accepted. The review loop adds an advisory verdict for each changed criterion — whether its referenced tests verify the scenario, something adjacent, or leave it undetermined. That is evidence for human judgment, not a semantic claim by clue validate: a green build and a fluent agent do not establish that the outcome is right.
The PR also gives hosted CI an exact candidate, but a PR alone does not enforce anything. Enforcement requires the CI workflow to run on the PR, its result to be a required status check, and branch protection to block merge until that check passes. Local verification remains fast evidence; protected hosted CI is the safeguard that the agent cannot silently skip. The CI wall guide gives the setup and failing-PR probe. Workflow and protection changes must never weaken the gate merely to make a change pass.
That protection is a setting at your Git host, so nothing in your repository records it and clue validate cannot see it — which is how a repository can run Cliewen for a long time, pass every check, and enforce nothing. So before an agent marks a PR ready for the first time in a repository, it asks the host what the branch actually enforces. If something is missing it stops, says what, and offers the commands your host accepts; it changes no setting without your go-ahead, and on a host it cannot query it reports the state as unknown rather than assuming you are covered. You can decline — the PR still goes ready, and the handoff records that the boundary is unenforced and why.
Mark the pull request ready for review only after local review and verification pass on the current head. Report the review mode, reviewed commit, number of passes run, and advisory findings left open, then confirm that the hosted head branch and SHA equal the clean, locally reviewed branch and HEAD before and immediately after marking it ready. Stopping anywhere else is ordinary rather than an exception: the branch is pushed, the pull request is a draft, and no claim of readiness exists.
Review fixes are committed and pushed with the turn that made them, then locally verified and agent-reviewed again on the same branch; a repair returns a ready pull request to draft until the repaired head has its own clean pass. Once it does and the worktree is clean, repeat the hosted-head check and mark the pull request ready again. After the human merges, orient on the next unfinished plan milestone and ask before beginning it.
Next
See the default local acceptance and the explicit PR choice.