[rochecompaan]

Summary

Adds the design for interactive Issue runs, explored in #225. Docs only. No code changes.

 docs/specs/
+└── 2026-10-14-issue-225-interactive-issue-runs-design.md

The maintainer works out the spec and plan with the agent in a Pi chat. Patchmill then runs the rest of its usual workflow, and the same chat stays open until the implementation PR is merged:

patchmill run-once --issue N --interactive
  open Pi chat with the Patchmill extension
  spec phase in chat  -> maintainer confirms -> Patchmill checks and publishes
  plan phase in chat  -> maintainer confirms -> Patchmill checks and publishes
    approval gate: maintainer says "merged" -> agent calls continue -> Patchmill checks the merge
  dev environment + implementation run in the background, progress shown in chat
    blocked worker -> questions in chat -> confirmed answer -> same stage goes on   (slice 2)
  implementation PR open
    maintainer says "merged" -> agent calls continue -> done state, cleanup
  Issue run ends; chat stays open -> start another issue                         (slice 3)

Points that most need review:

• Anti-goals. One Run-once workflow for both modes. The agent decides when to go on, after the maintainer's word. Patchmill decides what happens next.
• Patchmill tools in the console. Start an Issue run, submit a spec or plan, continue, confirm block guidance, read status.
• Slice order. Spec and plan through to a merged PR come first. Unblocking in place comes second.
• "My call" notes. These are decisions made while drafting that the maintainer has not confirmed one by one.

Refs #225

Evidence

• npx prettier --check and npx markdownlint-cli2 pass on the new file.
• A fresh-context reviewer read the draft as its builder. Its three findings are fixed in this version: retrying a failed spec or plan check in the same Run attempt, pointing the blocker change at the planning-pr-v1 workflow and its saved state, and defining where the run ends.

Merge Danger

Door: two-way

Docs only. A revert removes the file.

Blast Radius: issue-225

Once this merges, run-once sees the file on main as #225's spec (docs/specs/*-issue-225-*) and skips the spec phase. #225 is labeled agent-unsuitable, so no automatic run picks it up today.