/land

Audience: coding agents and integration operators. CLI commands and schemas below are system reference, not a user checklist. Users can follow Quickstart.

In plain words: Land is the one step where you give the go-ahead and the proven work moves from the sandbox into your real checkout. You say /land (or any clear instruction to land). The harness re-checks that approval and proof are still current, applies the files, archives the agreement, and cleans up. You get an uncommitted diff: Git HEAD and the index do not change, and nothing is committed, pushed, or opened as a pull request. Review the diff, then commit through your normal Git process.

Only archived means done. proven means the evidence passed, not that the work reached your project.

For agents and integrators

/land <change>

This slash command is the explicit Land authority boundary. It runs:

claude-foundation advance <change> --through archived

The coordinator records current proof and external-operation assurance, prepares the recoverable apply transaction, applies the explicitly authorized projection, verifies target identity, archives through OpenSpec, and cleans up. Every writable repository receives an uncommitted diff while its HEAD and index stay unchanged. Completion means runtime status archived; proven is not completion.

Land is the single hard gate. It refuses unless the spec approval is still valid, the change is proven, assurance passed, and the proof matches the current workspace hash; there is no unproven or risk-accepted Land. When the proof is stale, the same advance --through archived route proves the current workspace first. land advance is only an alias of that route. When Prove recorded control-plane, CI, or secret paths or deletions, the Land output lists them as protected paths changed and paths deleted (paths only) before applying.

If the change edits the root package.json or a lockfile, Land then installs dependencies in your checkout with the same command the sandbox used (sandbox.setupCommand, or the lockfile’s install such as npm ci), so your project commands find the new packages. Set sandbox.installDependencies: false without a setup command to turn this off. A failed install never undoes Land: the result is recorded and Land prints the command to run yourself. Child repositories of a multi-repository change are not installed.

If Apply conflicts only with regenerable artifacts in the target (for example __pycache__/*.pyc) that were clean at isolation, the returned REPAIR restores them with advance <change> --through archived --restore-target <paths> inside the transaction. Any other conflicting edit in the target is kept. When it touches other lines than the change, the harness merges it into the sandbox copy, proves again, and applies; only an edit of the same lines is merged by the agent. Discarding a target edit is the user’s decision, and a file changed after the restore was recorded is never overwritten.

While the landed diff is still uncommitted, the user can undo an archived Land with advance <change> --undo-land --decision-ref <user-decision>: the harness returns every path Land wrote to its pre-Land bytes, retires the change, and keeps what it landed under .foundation/recovery/land-undone/. It refuses without writing if HEAD moved, a landed path is staged, or one was edited after Land.

Land is always allowed for stacked changes; nobody commits the first landed change before the next one lands. When an earlier change’s landed, uncommitted diff touches a file this change also changed, the harness merges that landed edit into this change’s sandbox copy, proves again what the merge invalidated, and applies. If both changed the same lines, the agent merges them in the sandbox copy and keeps the landed content. Earlier landed bytes are never offered for discard, and the user is asked only when the two intents contradict.

Only the harness-owned recoverable Land transaction may apply product files and synchronize the agreement; the agent does not edit them ad hoc. Land never implies permission to commit, push, publish, or open a pull request. While Land is active, the phase guard rejects those mutating shell commands unless they are children of the marked runtime transaction. After archive, commit, push, and pull requests happen only through /deliver (a direct request such as “open a PR” counts) or your direct instruction; a review follow-up that cites the delivered PR’s URL updates that same PR instead of opening another. A moved base, projection conflict, interrupted transaction, or unsafe repository identity stops with WAIT, REPAIR, RUN_EXTERNAL, or ASK_USER. The result names the cause, responsible actor, safe alternatives, state retained, and exact resume route.

A valid post-land and safe-before-activation declaration does not require a named acknowledgement to Land. It remains discoverable as an operational obligation after archive. Archive confirms code delivery; it does not claim that deployment, activation, or production verification has completed.

Safe automatic recovery—including host-permission integration and journal resume—runs within current authority. External delivery records and legacy transaction diagnostics remain available as advanced primitives under help --all; they are not user workflow steps. An already archived change returns DONE successfully.

Metrics preserve unknowns: when the host cannot report usage, cost stays null rather than becoming a misleading zero.