Finish and land a change

When your agent finishes a task, you get the change to try and a Proof. It shows which of your project's commands passed on the exact commit you'll review. The change lands on your shared branch only when you say so, now or in advance.

If other work lands first, discerndiscern↗A tool that lets you hand real work to coding agents and still decide what joins your project. checks the two changes together instead of sending yours back to the start.

Say your agent is adding search to your recipe app. Tell it what "finished" means:

"Finish the recipe search and bring it back for review. Show me how to try it, what you tested, and what still needs my decision. Don't land it until I say so."

The last sentence keeps the landing decision with you.

You don't need to run any of these commands yourself. Each result tells your agent what to do next.

It works in its own worktree, a separate copy of the project on its own branch, so your shared branch, the trunk (usually main), stays untouched until the change lands.

It hears about failures early. discern prepare runs your formatter and quicker checks, such as the linter. Each failure comes with its output and a command that reproduces it, so your agent fixes it while the change is still small.

It hears about files it may have missed. By default, when discern prepare or discern done passes, discern checks your Git history for files that usually change together with the ones your agent touched. It names any the change left out:

Start with `search.test.js`: it changed in 4 of the 4 recent commits that touched `search.js` (100%), and this branch changed `search.js` without it.

The finding is advice and never fails a run, so your agent checks whether its change to how search matches words needs new tests.

It commits, then runs the gate with discern done. The gate runs your project's own commands, such as its linter and tests. A change counts as finished only when every one of them passes. The gateGate↗The full set of checks your project requires before a change counts as finished. only runs on committed work, so the Proof always describes a version that can land.

If your project defines scopes, areas such as docs/ with a check of their own, that check runs only when a change touches the area, so unrelated checks don't slow a focused change. Every other command runs on every change. If a command fails, your agent fixes the cause.

If the change touches files a checkpoint watches, your agent answers that review question first. The answer goes into the Proof. If it's unmet, only you can let the change land anyway.

It keeps up with main, bringing in new work with discern update. It rereads the files both changes touched, because changes can merge cleanly and still clash.

The handoff ends with the Proof line. A pass means your project's commands passed on that commit, and nothing more. The change is ready for your review, and it isn't on main until it lands.

Try search as your users would: a recipe you know is there, a word that matches several, and one that matches nothing. Then ask:

"Which of these behaviors have automated tests? What did you try by hand? Is there anything this change affects that I haven't seen?"

For what you can't judge yourself, such as security, ask for an independent review. To see the full Proof, run discern status --verbose in the task's worktreeWorktree↗A separate copy of your project, on its own branch, where one task's work happens..

Describe the result you want:

"When nothing matches, suggest trying another word, and keep the search text so people can edit it."

Your agent makes the change in the same worktree and commits it. Then it runs discern done again, because any new commit makes the old Proof stale. discern reuses the result of any command it can show the edit didn't affect.

When you're happy, say so:

"Land the recipe search."

Your agent runs discern accept --confirmed, which records that you said yes in this conversation. The command submits the change, recording the commit and Proof where later edits can't reach them, so what lands is what you reviewed. Then it lands the change. The result's first sentence says whether it landed and what happens next.

Landed agent/recipe-search-0a7563 at 3f9c2d81a4b7 on main; its checkout, branch, and resources are gone. You are on main in /Users/ada/projects/recipes.

Another task may land on main while yours waits for review. That doesn't make your Proof stale or send your change back to the start.

When your change lands, discern combines it with the new main in a temporary copy, called an integration worktree. It runs the gate on the combined code and lands exactly what passed, instead of landing your change on top of work its tests never saw.

If the changes conflict, or a command fails on the combined code, nothing lands. Your agent gets the conflicting files or failing command, fixes the problem in its worktree, and tries again. If the combined code triggers a checkpointCheckpoint↗A review question your project asks your agent whenever a certain kind of change happens., your agent answers it and the same landing continues. An unmet answer still waits for you.

Without permission, discern accept records the submissionSubmission↗Your agent's recorded request to land one exact commit. and lands nothing. The change waits in the landing queue, and the result starts:

The revision is submitted and waits in the landing queue for the owner.

Your agent passes you the Proof lineProof↗discern's record of which of your project's checks passed, on exactly which commit. and stops. To land the change later, approve it in conversation, pre-approve it, or ask an agent in your main checkout, your original project folder. Coordinate parallel tasks explains the queue.

A grant is permission to land that you set up in advance, so routine changes land without asking you. Everything else still comes back to you. Permission can come from:

At every landing, discern checks a standing grant against each file the change touches. Any file outside the granted areas, such as code in a documentation change, sends the change back to you. Your approval in conversation, or a one-task grant, covers every file.

A one-task grant follows the task's branch, so it still covers the change after review fixes. It lasts until the change lands, you revoke it from the deskDesk↗The interactive view that opens when you run discern in your main checkout., or the worktree is removed.

No grant covers a variance (your permission to land despite an unmet checkpoint), a looser limit for a standard (one of your project's measured limits), or an emergency landing. Each needs your explicit decision at the time.

When the change lands, discern moves main to the exact commit it checked and attaches the Proof as a Git note. It updates your main checkout and removes the task's worktree, branch, and resources.

If anything stays behind, the change has still landed. The result's first sentence says why and what finishes the job:

• The branch has newer commits that haven't landed.
• The worktree has uncommitted changes, which discern keeps.
• The Proof noteProof note↗A copy of a landed change's Proof, stored with its commit in Git. couldn't be recorded.
• Another program was using the folder, or a resource couldn't be removed.

A landed task's worktree stayed behind matches each message to its fix.

Landing isn't releasing, which your release process still handles. From green to live shows every stageStage↗A group in the order the gate runs its work..