Milestones and review in the new loop (M2.1, PR C)

A work item starts from a fresh workspace: fetch, set aside (never
discard) leftover changes, branches and unpushed commits, a clean default
branch, and a branch of its own (D3, #62). start_milestone cuts the
milestone's branch; finish_milestone commits only the work, pushes and
opens a PR that closes the issue, under an intent, adopting an open PR and
treating a closed one as the operator's answer (D4). Between runs the
loop watches each item's PR: operator comments and inline review notes
(#69) reach the item, a merge or close hands back to the driver. A review
fix is checked after it's pushed and goes out as a new PR if the PR merged
first (D5). At boot an interrupted publish is settled against Gitea (L8).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PPQ14L3LikyefCMFBqEbKE

nisse-dev/src/nisse_dev/loop/agent.py

@@ -26,6 +26,7 @@ from nisse_dev.loop.items import (
     ANSWER,
     CLOSED,
     GO_AHEAD,
+    MERGE,
     READY,
     RUNNING,
     WAITING,
@@ -35,7 +36,14 @@ from nisse_dev.loop.items import (
     loop_of,
     save,
 )
-from nisse_dev.loop.tools import ASK_HUMAN, CLOSE_ITEM, RESTATE
+from nisse_dev.loop.milestones import OPEN_PR, Milestones
+from nisse_dev.loop.tools import (
+    ASK_HUMAN,
+    CLOSE_ITEM,
+    FINISH_MILESTONE,
+    RESTATE,
+    START_MILESTONE,
+)
 from nisse_dev.oplog import OpLog
 from nisse_dev.state import StateStore, WorkItem
 from nisse_dev.tools import EXECUTOR_TOOLS, Workspace
@@ -58,8 +66,14 @@ understanding to the operator: what you take the request to mean, how it fits
 the project, and your first step. Wait for their go-ahead. If the request is
 unclear, ask_human instead of guessing.
 
-After the go-ahead, do the work. When it is done, call close_item with a
-summary of what was done, what was verified, and what is left open.
+After the go-ahead, work in a milestone: call start_milestone before
+changing anything (never create or switch branches yourself), make the
+change, run the project's tests, then call finish_milestone with a summary.
+The harness commits, pushes and opens a PR, and you wait for review. Review
+comments arrive as messages: make the changes, run the tests, and call
+finish_milestone again to push the fix. When the PR has merged, call
+close_item with what was done, what was verified, and what is left open. If
+the PR is closed without merging, ask the operator what next.
 
 {workspace}"""
 
@@ -82,6 +96,7 @@ class LoopAgent:
         cancel: Cancel,
         oplog: OpLog,
         roles: dict[str, str] | None = None,
+        milestones: Milestones | None = None,
         intake_interval_s: float = INTAKE_INTERVAL_S,
     ) -> None:
         self._store = store
@@ -98,6 +113,7 @@ class LoopAgent:
         self._cancel = cancel
         self._oplog = oplog
         self._roles = roles or {}
+        self._milestones = milestones
         self._interval = intake_interval_s
         # thread root -> revision on screen there, read on the transport's
         # thread to stamp replies on arrival (L3).
@@ -145,6 +161,7 @@ class LoopAgent:
         """Resume waiting points as they were, and never resume interrupted
         work blindly: an item cut off mid-run waits on the operator."""
         self._store.set_active(None, cause="boot")
+        self._reconcile_publishing()
         for item in self._store.work_items("open"):
             loop = loop_of(item)
             if item.position == RUNNING:
@@ -164,6 +181,37 @@ class LoopAgent:
                         thread=loop.thread,
                     )
 
+    def _reconcile_publishing(self) -> None:
+        """L8 step 2: a publish cut off by a crash is settled against Gitea.
+        An open PR for the branch is adopted; otherwise the intent is aborted
+        and the operator is told, never a blind retry."""
+        for intent in self._store.pending_intents():
+            if intent.kind != OPEN_PR or not intent.work_item:
+                continue
+            item = self._store.work_item(intent.work_item)
+            branch = str(intent.payload.get("branch", ""))
+            try:
+                pr = self._gitea.find_pull_request(self._repo, branch)
+            except GiteaError:
+                continue  # unverifiable: left pending, asked about below
+            if item is None or item.status != "open":
+                self._store.abort_intent(intent.id, cause="item no longer open")
+            elif pr is not None and pr.state == "open":
+                self._store.commit_intent(intent.id, cause=f"adopted PR #{pr.number}")
+                loop = replace(loop_of(item), pr=pr.number, pr_url=pr.url)
+                self._fact(item, f"after a restart, adopted PR #{pr.number} ({pr.url})")
+                save(
+                    self._store,
+                    item.id,
+                    WAITING,
+                    replace(loop, wait=MERGE, note=f"PR #{pr.number}"),
+                    cause="adopted PR after restart",
+                )
+            else:
+                self._store.abort_intent(intent.id, cause="no PR was opened")
+                note = "publishing was cut off by a restart; reply to try again."
+                self._wait(item, replace(loop_of(item), wait=ANSWER, note=note), note)
+
     # -- intake (D1) ---------------------------------------------------------
 
     def intake(self) -> None:
@@ -185,8 +233,66 @@ class LoopAgent:
                 )
                 continue
             self._open(issue)
+        self.watch()
         self._schedule()
 
+    # -- PR review and merge (D4, D5) -------------------------------------------
+
+    def watch(self) -> None:
+        """New operator comments on an item's PR, and its merge or close,
+        reach the item; a waiting item becomes ready to act on them."""
+        for item in self._store.work_items("open"):
+            loop = loop_of(item)
+            if not loop.pr:
+                continue
+            try:
+                pr = self._gitea.pull_request(self._repo, loop.pr)
+                comments = self._gitea.list_comments(self._repo, loop.pr)
+                notes = self._gitea.review_notes(self._repo, loop.pr)
+            except GiteaError as exc:
+                self._oplog.emit("loop.watch_unavailable", cause=str(exc))
+                continue
+            log = self._store.transcript(item.id, "operator")
+            new = False
+            for comment in comments:
+                if comment.id <= loop.comments:
+                    continue
+                loop = replace(loop, comments=comment.id)
+                if comment.author in self._gitea_operators:
+                    log.append(
+                        UserMessage(
+                            text=comment.body,
+                            source=f"gitea:pr:{loop.pr}:comment:{comment.id}",
+                        )
+                    )
+                    new = True
+            for note in notes:
+                if note.key in loop.notes:
+                    continue
+                loop = replace(loop, notes=(*loop.notes, note.key))
+                if note.author in self._gitea_operators:
+                    where = f"on {note.where}: " if note.where else ""
+                    log.append(
+                        UserMessage(
+                            text=f"{where}{note.body}",
+                            source=f"gitea:pr:{loop.pr}:review:{note.key}",
+                        )
+                    )
+                    new = True
+            position = item.position
+            if pr.merged:
+                self._fact(item, f"PR #{loop.pr} merged")
+                loop, position = replace(loop, pr=0, pr_url="", branch=""), READY
+            elif pr.state != "open":
+                self._fact(item, f"PR #{loop.pr} was closed without merging")
+                loop, position = replace(loop, pr=0, pr_url="", branch=""), READY
+            elif new and item.position == WAITING:
+                position = READY
+            if position != item.position or loop != loop_of(item):
+                if position == READY:
+                    loop = replace(loop, wait="", note="")
+                save(self._store, item.id, position, loop, cause="PR update")
+
     def _from_an_operator(self, issue: Issue) -> bool:
         """L11: only an operator's issue, or one an operator assigned, is
         an instruction."""
@@ -326,11 +432,30 @@ class LoopAgent:
     def _run(self, item: WorkItem) -> None:
         loop = loop_of(item)
         self._store.set_active(item.id, cause="ready")
+        if not loop.prepared and self._milestones is not None:
+            # D3: a fresh workspace when a work item starts.
+            try:
+                notes = self._milestones.prepare(f"{item.id}-work")
+            except Exception as exc:  # noqa: BLE001 -- the item waits, not the loop
+                note = f"I couldn't prepare the workspace: {exc}. Reply to retry."
+                self._wait(item, replace(loop, wait=ANSWER, note=note), note)
+                self._store.set_active(None, cause="workspace failed")
+                return
+            self._fact(item, "workspace prepared from the latest default branch")
+            if notes:
+                said = "Set aside from the workspace: " + "; ".join(notes)
+                self._fact(item, said)
+                self._transport.post(said, thread=loop.thread)
+            loop = replace(loop, prepared=True)
         save(self._store, item.id, RUNNING, loop, cause="driver run")
         tools = [
             RESTATE,
             ASK_HUMAN,
-            *(_LOOK if not loop.started else [CLOSE_ITEM, *EXECUTOR_TOOLS]),
+            *(
+                _LOOK
+                if not loop.started
+                else [START_MILESTONE, FINISH_MILESTONE, CLOSE_ITEM, *EXECUTOR_TOOLS]
+            ),
         ]
         system = SYSTEM.format(
             repo=self._repo,
@@ -345,6 +470,7 @@ class LoopAgent:
                 system=system,
                 tools=tools,
                 workspace=self._workspace,
+                handlers={"start_milestone": lambda args: self._start(item.id, args)},
             )
         finally:
             self._running = False
@@ -372,6 +498,8 @@ class LoopAgent:
         elif outcome.kind == "wait" and outcome.tool == "ask_human":
             question = str(args.get("question", "")).strip()
             self._wait(item, replace(loop, wait=ANSWER, note=question), question)
+        elif outcome.kind == "wait" and outcome.tool == "finish_milestone":
+            self._finish(item, loop, str(args.get("summary", "")).strip())
         elif outcome.kind == "wait" and outcome.tool == "close_item":
             summary = str(args.get("summary", "")).strip()
             self._transport.post(f"Done: {summary}", thread=loop.thread)
@@ -384,6 +512,123 @@ class LoopAgent:
             self._wait(item, replace(loop, wait=ANSWER, note=note), note)
         self._store.set_active(None, cause="item waiting")
 
+    # -- milestones (D4) -----------------------------------------------------
+
+    def _start(self, item_id: str, args: dict[str, object]) -> tuple[str, bool]:
+        """start_milestone, mid-run: cut the milestone's branch."""
+        item = self._store.work_item(item_id)
+        assert item is not None
+        loop = loop_of(item)
+        if loop.branch:
+            busy = f"milestone {loop.milestone} is still open; finish it first"
+            return busy, False
+        if self._milestones is None:
+            return "milestones aren't available here", False
+        number = loop.milestone + 1
+        branch = f"{item.id}-milestone-{number}-{uuid.uuid4().hex[:4]}"
+        self._milestones.start(branch)
+        name = str(args.get("name", "")).strip()
+        self._fact(item, f"milestone {number} started ({name}) on branch {branch}")
+        save(
+            self._store,
+            item.id,
+            RUNNING,
+            replace(loop, milestone=number, branch=branch),
+            cause=f"milestone {number} started",
+        )
+        return f"started milestone {number} on branch {branch}", True
+
+    def _finish(self, item: WorkItem, loop: Loop, summary: str) -> None:
+        """finish_milestone: publish the milestone, or push a review fix."""
+        if self._milestones is None:
+            note = "milestones aren't available here"
+            self._wait(item, replace(loop, wait=ANSWER, note=note), note)
+            return
+        if loop.pr:
+            fixed = self._milestones.push_fix(
+                item_id=item.id,
+                branch=loop.branch,
+                pr=loop.pr,
+                message=summary or "Address review comments",
+                attempt=loop.fixes + 1,
+            )
+            self._fact(item, f"review fix: {fixed.note}")
+            if fixed.kind in ("pushed", "nothing"):
+                self._gitea_comment(loop.pr, fixed.note)
+                self._wait(
+                    item,
+                    replace(loop, wait=MERGE, note=f"PR #{loop.pr}"),
+                    f"PR #{loop.pr}: {fixed.note}",
+                )
+            elif fixed.kind == "new-pr" and fixed.pr is not None:
+                loop = replace(
+                    loop, pr=fixed.pr.number, pr_url=fixed.pr.url, fixes=loop.fixes + 1
+                )
+                self._wait(
+                    item,
+                    replace(loop, wait=MERGE, note=f"PR #{fixed.pr.number}"),
+                    f"The PR merged before the fix landed, so it's a new PR: "
+                    f"#{fixed.pr.number} {fixed.pr.url}",
+                )
+            else:
+                self._wait(
+                    item,
+                    replace(loop, wait=ANSWER, note=fixed.note),
+                    f"{fixed.note}. What next?",
+                )
+            return
+        if not loop.branch:
+            # D4: finishing without a start cuts the branch now.
+            number = loop.milestone + 1
+            branch = f"{item.id}-milestone-{number}-{uuid.uuid4().hex[:4]}"
+            self._milestones.start(branch)
+            loop = replace(loop, milestone=number, branch=branch)
+        published = self._milestones.publish(
+            item_id=item.id,
+            branch=loop.branch,
+            title=f"{item.title} (milestone {loop.milestone})",
+            summary=summary,
+            issue=loop.issue,
+        )
+        left = (
+            f" (left out {len(published.left_out)} build artifact(s))"
+            if published.left_out
+            else ""
+        )
+        if published.pr is not None and published.kind in ("opened", "adopted"):
+            pr = published.pr
+            self._fact(
+                item,
+                f"milestone {loop.milestone} published: PR #{pr.number} "
+                f"({pr.url}){left}",
+            )
+            self._wait(
+                item,
+                replace(
+                    loop,
+                    pr=pr.number,
+                    pr_url=pr.url,
+                    wait=MERGE,
+                    note=f"PR #{pr.number}",
+                ),
+                f"Milestone {loop.milestone} is up for review: {pr.url}{left}",
+            )
+        else:
+            self._fact(
+                item, f"milestone {loop.milestone} not published: {published.note}"
+            )
+            self._wait(
+                item,
+                replace(loop, wait=ANSWER, note=published.note),
+                f"Milestone {loop.milestone}: {published.note}. What next?",
+            )
+
+    def _gitea_comment(self, pr: int, text: str) -> None:
+        try:
+            self._gitea.post_comment(self._repo, pr, text)
+        except GiteaError:
+            pass  # courtesy only; the pushed commit is the answer
+
     def _wait(self, item: WorkItem, loop: Loop, say: str | None) -> None:
         if say:
             self._transport.post(say, thread=loop.thread)

nisse-dev/src/nisse_dev/loop/build.py

@@ -18,6 +18,7 @@ from nisse_dev.config import AgentConfig
 from nisse_dev.gitea import GiteaClient
 from nisse_dev.loop.agent import LoopAgent
 from nisse_dev.loop.driver import Driver
+from nisse_dev.loop.milestones import Milestones
 from nisse_dev.matrix import MatrixTransport
 from nisse_dev.oplog import OpLog
 from nisse_dev.state import StateStore
@@ -76,7 +77,7 @@ def build_loop_agent(config: AgentConfig) -> RunningLoop:
     host = build_host(config)
     credential = push_credential(config)
     remote = remote_url(gitea, config.gitea_repo, credential)
-    prepare_workspace(host, config, account, remote, credential)
+    git = prepare_workspace(host, config, account, remote, credential)
     workspace = Workspace(
         host,
         config.workspace,
@@ -108,6 +109,15 @@ def build_loop_agent(config: AgentConfig) -> RunningLoop:
         cancel=cancel,
         oplog=oplog,
         roles=config.roles.pinned(),
+        milestones=Milestones(
+            store,
+            git,
+            gitea,
+            repo=config.gitea_repo,
+            remote=remote,
+            credential=credential,
+            base=config.base_branch,
+        ),
     )
     return RunningLoop(
         config=config,

nisse-dev/src/nisse_dev/loop/driver.py

@@ -7,6 +7,7 @@ go to the build VM (L13); control tools are answered here, and a waiting one
 ends the run, so the scheduler can put it to the operator.
 """
 
+from collections.abc import Callable, Mapping
 from dataclasses import dataclass
 from typing import Any, Literal
 
@@ -55,7 +56,12 @@ class Driver:
         system: str,
         tools: list[dict[str, Any]],
         workspace: Workspace | None,
+        handlers: Mapping[str, Callable[[dict[str, Any]], tuple[str, bool]]]
+        | None = None,
     ) -> RunOutcome:
+        """``handlers`` answer control tools that don't end the run (e.g.
+        start_milestone): each returns a result and whether it succeeded."""
+        handlers = handlers or {}
         offered = names(tools)
         nudged = False
         for turn in range(self._max_turns):
@@ -95,7 +101,9 @@ class Driver:
                         transcript, calls[index + 1 :], "not run: the turn had ended"
                     )
                     return RunOutcome("wait", call.tool, dict(call.arguments))
-                if call.tool not in offered or workspace is None:
+                if call.tool in handlers and call.tool in offered:
+                    result, ok = handlers[call.tool](dict(call.arguments))
+                elif call.tool not in offered or workspace is None:
                     result, ok = (
                         f"no such tool: {call.tool}; the tools are "
                         + ", ".join(sorted(offered)),

nisse-dev/src/nisse_dev/loop/items.py

@@ -18,6 +18,7 @@ CLOSED = "closed"
 # What a waiting item waits for.
 GO_AHEAD = "go-ahead"  # a go on the restatement up (L3, D1)
 ANSWER = "answer"  # an answer to a question
+MERGE = "merge"  # the PR's review and merge (D4, D5)
 
 
 @dataclass(frozen=True)
@@ -28,13 +29,23 @@ class Loop:
     rev: int = 0  # the latest proposal put up (L3)
     started: bool = False  # scope agreed: a go-ahead was given (D1)
     note: str = ""  # what a waiting item said it is waiting on
+    prepared: bool = False  # its fresh workspace was made (D3)
+    milestone: int = 0  # the current milestone (D4)
+    branch: str = ""  # the current milestone's branch, while one is open
+    pr: int = 0  # the current milestone's PR, once published
+    pr_url: str = ""
+    comments: int = 0  # the last PR conversation comment taken (L8)
+    notes: tuple[str, ...] = ()  # review notes taken (#69)
+    fixes: int = 0  # review fixes pushed, for follow-up branch names
 
     def to_data(self) -> dict[str, Any]:
         return asdict(self)
 
 
 def loop_of(item: WorkItem) -> Loop:
-    return Loop(**item.data.get("loop", {}))
+    data = dict(item.data.get("loop", {}))
+    data["notes"] = tuple(data.get("notes", ()))
+    return Loop(**data)
 
 
 def save(

nisse-dev/src/nisse_dev/loop/milestones.py

@@ -0,0 +1,195 @@
+"""The workspace and milestones of a work item (D3, D4, D5).
+
+The harness owns branches: a work item starts from a fresh default branch on
+a branch of its own, a milestone is cut by start_milestone, and finishing it
+commits only the work, pushes with the push credential, and opens the PR.
+Publishing is idempotent under an intent (L8): an open PR for the branch is
+adopted, and a PR the operator closed is an answer, never reopened.
+"""
+
+import time
+from dataclasses import dataclass
+from typing import Literal
+
+from nisse_dev.git import GitError, GitRepo, PushCredential
+from nisse_dev.gitea import GiteaClient, GiteaError, PullRequest
+from nisse_dev.state import StateStore
+
+OPEN_PR = "open_pr"
+SET_ASIDE = "set-aside"
+
+
+@dataclass(frozen=True)
+class Published:
+    kind: Literal["opened", "adopted", "nothing", "closed", "failed"]
+    note: str
+    pr: PullRequest | None = None
+    left_out: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class Fixed:
+    kind: Literal["pushed", "nothing", "new-pr", "closed", "failed"]
+    note: str
+    pr: PullRequest | None = None
+
+
+class Milestones:
+    def __init__(
+        self,
+        store: StateStore,
+        git: GitRepo,
+        gitea: GiteaClient,
+        *,
+        repo: str,
+        remote: str,
+        credential: PushCredential | None,
+        base: str = "main",
+    ) -> None:
+        self._store = store
+        self._git = git
+        self._gitea = gitea
+        self._repo = repo
+        self._remote = remote
+        self._credential = credential
+        self._base = base
+
+    # -- a work item's workspace (D3) ------------------------------------------
+
+    def prepare(self, item_branch: str) -> list[str]:
+        """A fresh workspace for a work item: fetch, set aside (never
+        discard) whatever was left, check out a clean default branch, and put
+        the item on a branch of its own. Returns what was set aside."""
+        git = self._git
+        git.fetch(credential=self._credential)
+        stamp = time.strftime("%Y%m%d-%H%M%S")
+        notes: list[str] = []
+        if git.has_changes():
+            aside = f"{SET_ASIDE}/{stamp}/worktree"
+            git.checkout_new_branch(aside)
+            git.commit_all("Set aside: uncommitted changes left in the workspace")
+            notes.append(f"uncommitted changes, as {aside}")
+        for branch in git.local_branches():
+            if branch == self._base or branch.startswith(f"{SET_ASIDE}/"):
+                continue
+            git.rename_branch(branch, f"{SET_ASIDE}/{stamp}/{branch}")
+            notes.append(f"branch {branch}, as {SET_ASIDE}/{stamp}/{branch}")
+        if self._base in git.local_branches() and self._ahead_of_origin():
+            aside = f"{SET_ASIDE}/{stamp}/{self._base}"
+            git.branch_at(aside, self._base)
+            notes.append(f"unpushed commits on {self._base}, as {aside}")
+        git.reset_to(self._base, f"origin/{self._base}")
+        git.checkout_new_branch(item_branch)
+        return notes
+
+    def _ahead_of_origin(self) -> bool:
+        current = self._git.current_branch()
+        try:
+            self._git.checkout_existing_branch(self._base)
+            return self._git.commits_since(f"origin/{self._base}") > 0
+        finally:
+            if current and current != self._base:
+                self._git.checkout_existing_branch(current)
+
+    # -- milestones (D4) -------------------------------------------------------
+
+    def start(self, branch: str) -> str:
+        """Cut the milestone's branch where the item is; returns its start."""
+        self._git.checkout_new_branch(branch)
+        return self._git.head_sha()
+
+    def publish(
+        self,
+        *,
+        item_id: str,
+        branch: str,
+        title: str,
+        summary: str,
+        issue: int,
+    ) -> Published:
+        git = self._git
+        try:
+            if git.current_branch() != branch:
+                git.checkout_new_branch(branch)
+            git.commit_all(title)
+            left_out = tuple(git.left_out())
+            if git.commits_since(f"origin/{self._base}") == 0:
+                return Published("nothing", "no changes to publish", left_out=left_out)
+            existing = self._gitea.find_pull_request(self._repo, branch)
+            if existing is not None and existing.state != "open":
+                # D4: the operator closed it; that is their answer.
+                return Published(
+                    "closed",
+                    f"PR #{existing.number} for this branch was closed",
+                    existing,
+                    left_out,
+                )
+            intent = self._store.begin_intent(
+                OPEN_PR,
+                {"branch": branch, "title": title, "issue": issue},
+                cause=f"publishing {branch}",
+                work_item=item_id,
+            )
+            git.push(self._remote, branch, credential=self._credential)
+            existing = self._gitea.find_pull_request(self._repo, branch)
+            if existing is not None and existing.state == "open":
+                self._store.commit_intent(
+                    intent, cause=f"adopted PR #{existing.number}"
+                )
+                return Published("adopted", "pushed to the open PR", existing, left_out)
+            pr = self._gitea.open_pull_request(
+                self._repo,
+                head=branch,
+                base=self._base,
+                title=title,
+                body=_body(summary, issue, left_out),
+            )
+            self._store.commit_intent(intent, cause=f"opened PR #{pr.number}")
+            return Published("opened", f"opened PR #{pr.number}", pr, left_out)
+        except (GitError, GiteaError) as exc:
+            return Published("failed", f"publishing failed: {exc}")
+
+    def push_fix(
+        self, *, item_id: str, branch: str, pr: int, message: str, attempt: int
+    ) -> Fixed:
+        """Push a review fix to the PR's branch, then check the PR: one that
+        merged before the fix landed gets the fix as a new PR, and one that
+        was closed is reported (D5)."""
+        git = self._git
+        try:
+            if git.current_branch() != branch:
+                git.checkout_existing_branch(branch)
+            sha = git.commit_all(message) or git.head_sha()
+            if git.remote_sha(self._remote, branch, credential=self._credential) == sha:
+                return Fixed("nothing", "no change was needed")
+            git.push(self._remote, branch, credential=self._credential)
+            state = self._gitea.pull_request(self._repo, pr)
+            if state.merged:
+                git.fetch(credential=self._credential)
+                if git.is_ancestor(sha, f"origin/{self._base}"):
+                    return Fixed("pushed", "pushed, and it was merged with the PR")
+                follow = f"{branch}-fix-{attempt}"
+                git.checkout_new_branch(follow)
+                new = self.publish(
+                    item_id=item_id,
+                    branch=follow,
+                    title=f"Follow-up to #{pr}: {message}",
+                    summary=f"PR #{pr} merged before this review fix landed.",
+                    issue=0,
+                )
+                return Fixed("new-pr", new.note, new.pr)
+            if state.state != "open":
+                return Fixed("closed", f"PR #{pr} was closed", state)
+            return Fixed("pushed", f"pushed {sha[:8]}", state)
+        except (GitError, GiteaError) as exc:
+            return Fixed("failed", f"pushing the fix failed: {exc}")
+
+
+def _body(summary: str, issue: int, left_out: tuple[str, ...]) -> str:
+    parts = [summary]
+    if issue:
+        parts += ["", f"Closes #{issue}"]
+    if left_out:
+        parts += ["", "## Left out", "", "Build artifacts, never part of the work:"]
+        parts += [f"- `{path}`" for path in left_out]
+    return "\n".join(parts)

nisse-dev/src/nisse_dev/loop/tools.py

@@ -5,11 +5,11 @@ the item then waits on the operator."""
 from typing import Any
 
 
-def _tool(name: str, description: str, **params: str) -> dict[str, Any]:
+def _tool(tool: str, description: str, /, **params: str) -> dict[str, Any]:
     return {
         "type": "function",
         "function": {
-            "name": name,
+            "name": tool,
             "description": description,
             "parameters": {
                 "type": "object",
@@ -42,7 +42,22 @@ CLOSE_ITEM = _tool(
     summary="What was done, verified, and left open.",
 )
 
-WAITING = frozenset({"restate", "ask_human", "close_item"})
+START_MILESTONE = _tool(
+    "start_milestone",
+    "Start a milestone before changing code: the harness cuts its branch. "
+    "Never create or switch branches yourself.",
+    name="A short name for the milestone.",
+)
+FINISH_MILESTONE = _tool(
+    "finish_milestone",
+    "The milestone's work is done and its tests pass: the harness commits "
+    "the work, pushes it and opens a PR, or, after review comments, pushes "
+    "your fix to the PR. Ends your turn; you continue when the PR is "
+    "reviewed or merged.",
+    summary="What the milestone did and how it was verified, for the PR.",
+)
+
+WAITING = frozenset({"restate", "ask_human", "close_item", "finish_milestone"})
 
 
 def names(tools: list[dict[str, Any]]) -> set[str]: