Land a step

/land <entry> <step> brings a refuted step from its worktree onto main. It leaves behind the step on main in one commit with its booking and its landing report, the rewritten state file, and the step's worktree and branches removed. After a red line no fix inside the brief closes, it leaves the step out of main instead, with the worktree and branches kept for /spec and the failure recorded in the step's Step 0 in plan.md.

Quick start

/land <entry> <step>     the only way a step reaches main: bring the refuted step over, check it there, book it, commit it, remove its worktree

Use instead

What it reads

1. .agents/plan.yaml, its required keys and defaults as /plan states them.
   • A required key missing is a refusal ("Stops").
2. The ledger folder: <entry> resolves to the folder under <ledger_root>/ whose plan.md opens with # Plan: <entry> (the number, or the number and title).
   • /plan names a new folder by the entry's slug, and an older plan keeps whatever folder it has.
   • No such folder is a refusal ("Stops").
3. The dispatch block naming this step, with its worktree and base.
   • None, or an entry at landing: preparing, whatever it names, is a refusal ("Stops").
4. This skill's templates/land.sh and templates/checks.sh, as "The landing script" says.
   • A checks.sh missing beside land.sh is a refusal ("Stops").
5. agents/reviews/<step>-report.md and the refuter report agents/reviews/<step>-refuter.md, as the Stops row "The step not ready" requires them.
6. Main, in the state the Stops row "Main not clean" requires.
   • The user's unrelated changes are listed by path.
     • They are left alone.
7. The step's diagnosis record agents/reviews/<step>-diagnosis.md, when it exists, for the booking of Steps 9.
8. The verification page .agents/plan.yaml's verification: names, for the compare of Steps 2.
   • Its copy in the step's worktree when the step changed it since the base, main's copy otherwise, and the merge of the two when main and the worktree both changed it.

Steps

1. Stop the step's builder and every reviewer of the step, before anything in the worktree is committed.
   • An agent is stopped through the runner's stop tool.
   • Then the runner's agent listing must show none of them left.
   • A check that fails is a refusal before main is touched ("Stops").
2. Set landing: cherry-picking in the step's dispatch entry.
   • Then compare the plan's verify list with the verification page's commands, as the spec skill's Steps 1 says.
   • The page is read as the cherry-pick of Steps 4 will bring it.
     • From the step's worktree when its page differs from the base's there (git diff --quiet <base> -- <page>, run from inside the worktree, exits 1).
       • templates/land.sh's Steps 3 commits the worktree's changes into the range.
     • From main otherwise.
     • When main and the worktree both changed the page since the base, as the merge of the two in place of either copy.
   • Rewrite the list in the state file on a difference, before templates/land.sh runs it.
   • The booking (Steps 9) names the change.
   • The landing commit carries the state file (Steps 12).
   • Done when landing: cherry-picking is set and the verify list equals the page's commands as the cherry-pick brings the page.
3. In the worktree, from inside it, after waiting for its index.lock to go: git add -A of the whole tree with the ledger root left out.
   • git commit -q -m wip when something is staged.
   • A builder that committed everything leaves nothing staged, and the landing makes no wip commit.
   • The landing removes a lock older than 60 s while no git process runs, as stale.
   • Each wait for a lock, here and on main before Steps 4, is bounded at 60 s of waiting.
     • At the bound the landing stops ("Stops").
4. On main: git cherry-pick -n <base>..<slug>-<step>, the whole range from the recorded base, so the landing applies the complete reviewed change and never only the last fix.
   • A conflict is resolved by the orchestrator or the session, never by an agent.
   • templates/land.sh prints the conflicting paths and exits 2 instead.
   • A range with no commit, as when the step's only output is a ledger file, has nothing to copy, and the landing goes on to Steps 6.
5. Restore to main's copy, before anything else, a ledger file the cherry-pick deleted or rewrote, since the ledger is written only on main.
   • templates/land.sh leaves the ledger root out of the worktree's add, so a ledger file left uncommitted in the worktree (a builder's report, any other ledger copy) never reaches main, though a ledger file that a commit of the range holds still does.
6. Run the verification commands of the configuration block on main, in order, each through its filter.
   • templates/land.sh runs the step's verify list through templates/checks.sh <state file> from the root of the checkout it checks (main here).
   • The lines checks.sh prints are what the booking quotes.
   • The plan's whole verify list runs on main for a small text step as for every other step.
   • A finding of the refutation of the last repair round that is small and inside the brief is fixed on main here.
     • It is counted and named the same way as a red line.
   • A finding of a small text step's review that is small and inside the brief is fixed on main here the same way.
   • A finding of an unapproved script is never fixed here, by naming the script in a report or otherwise; it is raised to the user, as refute's "Finding dispositions" says.
   • A finding that is a clash between two of the user's rulings is never fixed at landing; it is the stop "A rule clash" of plan-orchestration.
     • It takes the step back out of main as a red line for the user does (the bullets below), before any other commit.
     • It is raised as the open item of the stop "A rule clash" ("Stops").
   • A ruling is carried out on what it names; another place its reason reaches is raised as an open item before it is changed.
     • The landing goes on with the ruling carried out on what it names.
     • The other place is booked as an open item in the state file and named in the booking (Steps 9).
     • This is no stop.
   • A red line that a fix inside the brief closes is fixed on main.
     • It is counted as a fix at landing.
     • It is named in the booking with its cause.
   • A red line whose file is an uncommitted ledger record of another step of the same plan, or of another open plan, is closed by who wrote the record.
     • A record the session wrote is fixed in place on disk, to the rules file's character set, without changing what the record says.
       • The fix is counted as a fix at landing and named in the booking with the file's path.
       • The fix is not part of this landing's commit: the record waits for the resume point of its own step or plan (Steps 12).
     • A record the session did not write is not the session's to change.
       • The red line takes the step back out of main as any other red line does, and the failure goes to the user as an open item that names the file.
   • Any other red line ends the landing there, leaving main in a state the resumption rules of plan-orchestration recognise.
   • It takes the step back out of main: git restore --staged --worktree -- <paths> for changed files, git rm --cached and delete for added ones, run without asking the user.
   • The dispatch block is then set to landing: backed-out.
     • The step's worktree and branches are kept.
     • The step stays unticked in plan.md.
   • The failure is never sent back to the builder.
     • It is recorded in the step's Step 0 in plan.md.
   • The step keeps its line and its tag.
     • It is worked again as that step, with no new ruling.
   • The failure goes to the user as an open item only when what to do is a decision for the user.
   • A step is taken back out of main and prepared again at most once: a second failure of its landing always goes to the user as an open item, and the step waits for the ruling.
   • The step's agents are booked in plan.md's Agents section by the rules of Steps 9, since /spec later removes the step's dispatch entry.
     • The booking is written and read back before the commit below.
     • The agents of its later landing are appended when it lands, those already in the section skipped.
   • The state file and plan.md are then committed, a resume point, in the form Steps 12 states.
     • The commit also holds the other ledger records of this plan that the session wrote since the last one, other than the brief and the brief-check report of a /spec waiting on its brief check (the spec skill's "Steps / The brief check" 1).
   • /spec then saves the step's work as a patch and prepares it again from main's head, as the spec skill's "Steps / A step taken back out of main" says.
   • Done when every verification command has run on main and each red line is fixed on main, or the step is taken back out of main.
7. Open the changed views, as "The look" says.
8. Run the A/B: the benchmark commands the configuration block's bench: line names, the staged base binary and the new one run alternately after warm-ups, at least ten runs each.
   • The mean, the standard deviation and the standard error of the difference are written to the scratchpad.
     • They are quoted in the booking.
   • A change past the noise band is a finding, fixed before the booking.
9. Append the booking to plan.md (or the part file the plan names): what landed and where, every premise correction, every finding outside the brief with the open item it was raised as, the verification lines, the A/B.
   • The verification lines it quotes carry <REDACTED> in place of the value of a secret, as the rules file's rule on secrets in quoted command output says.
   • The booking states the builder's, each reviewer's and each brief-check agent's tokens, tool uses and time, from their completion notices, read from the dispatch block's builder_usage, reviewer_report and brief_check, and each diagnosis agent's, read from the head of its diagnosis record.
   • A brief_check that reads none, a small text step names no agent, and the booking states none for it.
   • The booking also appends to plan.md's ## Agents section one bullet per agent the step's dispatch entry names, - <agent id>: <role>, <served model>, with the roles below.
     • The builder from session_id, and each builder under builders_before: builder of step <n>.
     • The brief-check agent from brief_check: brief check of step <n>.
     • Each first-run reviewer from reviewer_report, a stopped one included: reviewer of step <n>.
     • Each reviewer over a round, a stopped one included: reviewer of step <n> over round <r>.
   • An inline or academic-paper builder has no agent id and gets no bullet.
   • An agent whose id already has a bullet or a numbered item in the section gets none, so a brief-check agent booked at a back-out, or at a stop of /spec, is not booked twice.
   • A diagnosis agent has its numbered item already, which the session wrote right after its start as the diagnose skill's "Rules" say, so the booking adds none.
   • A plan.md without the section gets it before ## Blocked, and by what.
   • The section is read back after the write, and each agent of the entry has exactly one bullet.
   • It names the change Steps 2 made to the plan's verify list, when it made one.
   • It states whether the builder's first report passed its bar, and the fixes at landing.
   • It names each diagnosis record of the step (agents/reviews/<step>-diagnosis.md, one heading per diagnosis) with its cause and its diagnosis agent's usage from the record's head, or with "cause not found" and the open item it was raised as.
   • Tick the step.
   • Done when the booking is in plan.md, the step is ticked, and the Agents section, read back, holds each agent of the step once.
10. Read the step's worktree from its dispatch entry, for Steps 13.
    • Then rewrite this plan's state file, as "Rules" says: the step's dispatch entry removed, the position line, the open items as they stand.
    • Every other entry of the dispatch block stays as it stands, a preparing entry included.
11. Write the landing report, agents/reviews/<step>-landing.md, so it lands with the step and stands alone on disk.
    • It opens with the position line of its own plan: the roadmap entry with its title, the plan step as "step n of m" with its name, and the next step.
    • Then the open items, verbatim, which hold only what the user must rule on.
    • Then the check of Steps 1 with what it showed, anything NOT DONE, what landed with the commit, what was found, and what is next.
    • Then the agents' usage, whether the first report passed its bar and the fixes at landing, as the booking of Steps 9 states them.
    • The verification lines it quotes are redacted as Steps 9 says.
    • Under the loop it is also the report the orchestrator prints.
    • Run by hand, it is the message that ends the turn.
12. Commit by explicit path, a resume point: every path from git diff --cached --name-only --no-renames, so a rename's old path is named too.
    • The commit also holds the files of this plan's ledger that the session wrote since the last resume point, the landing report among them, as plan-orchestration's "Resuming, and handing the plan over" says.
    • A /spec waiting on its brief check is carried as the spec skill's "Steps / The brief check" 1 says.
    • Not among them either is a record that Steps 6 fixed in place.
    • It also holds the choices file when a choice of this plan changed it.
    • The paths are written out in the git add -- <path> ... command, never through a shell variable.
    • Deleted paths are already staged by the cherry-pick and are not re-added.
    • The commit names the same paths: git commit -m <message> -- <path> ....
    • The message is in the repository's shape.
    • The message's last bullet is the booking.
    • No attribution.
    • Never push.
    • Afterwards git status --short shows nothing of the step's and no ledger file of this plan that the session wrote.
    • Such a ledger file left modified means the commit missed the booking, and it is staged with git add -- <path> and the head is amended with git commit --amend --no-edit -- <path>.
    • A ledger file of another open plan left modified is that plan's record, which waits for that plan's next resume point.
    • The brief and the brief-check report of a waiting /spec, and a record that Steps 6 fixed, left modified are not a missed booking.
13. Remove the step's worktree and its branches, as "Removing a step's worktree" says, with the worktree Steps 10 read.

The look

• When the configuration block's look: names where a changed view is shown and the step changes a view, the shell or anything a reader sees, the changed views are opened there at Steps 7.
• A screenshot is taken of each changed view and of each state the step's brief names, under the themes the step touches.
• What is wrong in them is fixed at landing when it is small and inside the brief, and raised to the user as an open item, as plan-orchestration's Stops section says otherwise.
• The landing note names every view and state looked at and what was seen.
• An empty look: means the step has no look, and the note says so.

The landing script

• templates/land.sh does Steps 3, 4 and 6 as one command, run from the repository root as sh <this skill's folder>/templates/land.sh <state file> <slug>-<step> <base>.
  • <state file> is the plan's orchestrator-state.md, relative to the repository root or absolute.
  • <slug>-<step> is the step's branch, which is also its worktree folder's name, <slug> being the name of the plan's ledger folder.
  • <base> is the base the dispatch block records.
• It reads worktree_root and ledger_root from .agents/plan.yaml.
  • In the projects: form it reads them from the project whose ledger_root holds the state file.
  • The step's worktree is <worktree_root>/<slug>-<step>, and the worktree's add leaves that ledger_root out.
  • No .agents/plan.yaml, an empty one or one that is not valid YAML, no worktree_root, no ledger_root, a state file under no project's ledger_root, or no checks.sh in land.sh's own folder is refused with exit 64 before anything is touched.
• Its check on main (Steps 6) is the plan's verify list: after main's cherry-pick it runs sh <its own folder>/checks.sh <state file> from the repository root.
  • Its own folder is the one that holds land.sh, and it looks for checks.sh nowhere else.
  • A non-zero exit fails the landing with exit 1 and the output of checks.sh printed.
• When <base>..<slug>-<step> holds no commit, it skips both cherry-picks.
  • It prints nothing to copy: <base>..<slug>-<step> holds no commit in place of the cherry-picks' output.
  • It still runs the verify list on main (Steps 6).
• It then prints the booking data: the diff stat against <base> and the paths staged on main.
• It exits 0 when the step landed and every check passed, 1 on a failed check or a stop, 2 on a conflict, 64 when it refuses its arguments or its configuration, and 127 when python3 is not installed, or with git's own status when a git step fails.
• templates/checks.sh <state file>, run from the root of the checkout it checks, runs the verify: list of the state file's first yaml block in order, each command through bash -o pipefail -c.
  • Before each command it prints $ <command>, then the command's output.
  • Every command runs, whatever the exit of the one before.
  • After the output of a command that exits non-zero, it prints checks: failed with exit <status>: <command>.
  • After the last command, when one or more failed, it prints checks: <k> of <n> commands failed.
  • When one or more commands failed, it exits 1.
  • When every command exits 0, it prints checks: <n> commands passed.
  • When every command exits 0, it exits 0.
  • A list it cannot read is refused with exit 2 before anything runs, and never passes.
• templates/land.test.sh proves land.sh on scratch repositories: a conflict exits 2 and leaves main as it was, a ledger file left uncommitted in the worktree never reaches main, a failing check fails the landing, a clean landing stages the step on main, and a step whose new test script and its command, left uncommitted in the worktree, reach main, where checks.sh runs that command after the cherry-pick with the verify list the fixture gives.
• land.sh's zero exit passes the checks on main (Steps 6).
  • It never passes the look (Steps 7), which it does not do.

Removing a step's worktree

/land does this at Steps 13, after the landing commit, from the repository root of the main checkout. The spec skill's "Steps / A step taken back out of main" does it the same way for a kept worktree.

1. Take the step's worktree: /land read it from the dispatch entry at Steps 10, before the state file was rewritten, and a back-out reads it from the entry.
   • The branch is the worktree folder's name, and <branch>-land beside it, as land.sh names them.
   • No path or branch is built from the step id.
2. When the worktree still exists (git worktree list names it), from inside it, git status --porcelain --untracked-files=all lists every change, untracked files included.
   • A worktree already gone skips steps 2 and 3.
   • Each path must be under the ledger root, .agents/plan.yaml's ledger_root (in the projects: form, the one that holds the state file's folder), since the ledger is written only on main and its copies in the worktree are records already saved there or copies the orchestrator put there.
   • Any other path is a stop ("Stops") that names it, and nothing is removed.
3. Run git worktree remove --force <worktree>, when it still exists, since without --force git refuses a worktree holding untracked or modified files, such as those ledger copies.
4. Run rm -r on each <worktree>-round-<n> folder beside the worktree, when it exists.
5. Run git branch -D for <branch> and for <branch>-land, each only when it exists, since after a cherry-pick neither is merged into main (the cherry-pick made new commits) and only -D deletes an unmerged branch.
6. These commands run without asking the user, since the step's work is committed on main.
   • When the runner refuses one of them, the session gives the user the command to run and waits.

Stops

• The first two rows are stops: each leaves an open item.
• The third row is a stop that leaves no open item: main is untouched, and landing again resumes it.
  • Under templates/land.sh, the stop leaves the worktree on <slug>-<step> or, after the script's checkout of <slug>-<step>-land, on that branch, and the script exits 1.
  • templates/land.sh, run again on a main with nothing staged, returns the worktree to <slug>-<step>, deletes <slug>-<step>-land and lands from the start.
• The rows after those three, up to the last, are refusals: they come before main is touched.
• The last row is a stop after the landing's commit that leaves an open item: the step is on main, and only its worktree and branches are left, named in the open item.
  • The open item is booked in the state file's open items and committed as a resume point, in the form Steps 12 states.
  • Removing them, as "Removing a step's worktree" says, finishes the landing and closes the open item.
• A refusal names its cause and leaves nothing.
• A red line recorded in the step's Step 0 is not a stop: the step is out of main and keeps its line and its tag.
• It is worked again as that step, with no new ruling, through /spec, once (Steps 6).

Anti-patterns

Rules

• One step stays one implementation commit, which keeps each step traceable to its brief, its review and its booking.
• A landed step found short of its brief, or wrong, is raised to the user as an open item, by plan-orchestration's "Stops".
  • The step that finishes it on top of what landed enters the plan only as plan-orchestration's "What earns a step of its own" says.
• A landed commit is reverted only on a ruling of the user, or, under self_rule: on, on a choice plan-orchestration's references/self-rule.md, "Closing an open item", books when the step's authority is a bullet ending "(self-rule)" alone.
  • The revert of a step the user approved, or one a ruling of the user added, is kind 3 of plan-orchestration's references/self-rule.md, "The six kinds left open".
  • The revert runs git revert --no-commit <commit>, and then the commit of Steps 12 with the paths of git diff --cached --name-only --no-renames.
  • Its preparation commit stays.
  • Only a step so reverted is booked as reverted.
• A landing runs from its cherry-pick (Steps 4) to its commit (Steps 12) before the session makes any other commit or starts any other skill; builders and reviewers already running go on.
  • The range stays staged on main until that commit.
  • A brief-check report that arrives during a landing is saved after the landing's commit.
• The landing rewrites its own plan's state file before the commit, and no other plan's state file.
  • The state file then describes that plan as of its own last resume point, as plan-orchestration's "Resuming, and handing the plan over" says.