@henryqw/pi-pr 6.0.7 → 6.2.0

package/README.md

@@ -12,7 +12,17 @@ Requires an authenticated GitHub CLI session (`gh auth login`) and a checkout on
 
 ## Feedback snapshots
 
-`pr-feedback.mjs fetch --out FILE` prints a compact feedback index. The index
+Run the bundled read-only diagnostic CLI from the installed package directory:
+
+```bash
+node skills/pi-pr-comment-sweep/scripts/pr-feedback.mjs fetch [--pr PR] (--out FILE | --json)
+node skills/pi-pr-comment-sweep/scripts/pr-feedback.mjs show --snapshot FILE --id ID
+node skills/pi-pr-comment-sweep/scripts/pr-feedback.mjs checks [--pr PR] --expected-head SHA
+node skills/pi-pr-comment-sweep/scripts/pr-feedback.mjs self-test
+```
+
+`checks` verifies the current pull request and its checks against the full head SHA; `self-test`
+checks local CLI behavior. `pr-feedback.mjs fetch --out FILE` prints a compact feedback index. The index
 includes IDs, kinds, states, authors, locations, and parent IDs as needed. It
 does not print comment or review bodies.
 
@@ -42,16 +52,13 @@ GitHub, use the network, or write files.
 
 ## Use
 
-Run `/pr` in a GitHub checkout. It reads fresh pull request and local state, then runs one route. The PR hostname selects its GitHub API host, and the extension works outside Herdr.
-
-For creation, put an optional base branch first. For example, run `/pr --base release/2026 Keep the title concise.` The base is a branch name, not a host or repository. Only creation accepts the base and remaining guidance. Other routes reject them instead of ignoring them.
+Run `/pr` in a GitHub checkout. It reads fresh pull request and local state, then continues through safe routes in one invocation until it needs external input, meets an ambiguous blocker, waits for CI or review, or merges. The PR hostname selects its GitHub API host, and the extension works outside Herdr.
 
-Run `/pr --feedback` to explicitly start or resume a feedback sweep. Use it for actionable conversation comments that do not select the sweep automatically. It cannot be combined with a base, other options, or instructions.
+`/pr` takes no flags, prose, or base argument. The package selects the branch base from one `branch.<branch>.gh-merge-base` setting or the validated `origin` default branch. After each published change, the extension rediscovers fresh GitHub mergeability, feedback, and CI before another action; no remembered flags or second `/pr` are needed. A stopped workflow may be resumed with a new `/pr` after the blocker is addressed.
 
 | Surface | Type | Purpose |
 | --- | --- | --- |
-| `/pr [--base BRANCH] [creation instructions]` | command | Run the current pull request's next safe route. |
-| `/pr --feedback` | command | Explicitly start or resume the guarded feedback sweep. |
+| `/pr` | command | Inspect and run the current pull request's next safe route. |
 | Footer | ui | Show a linked `PR #number` and one plain-language status. |
 | Widget | ui | Show one action hint or transient routing status. |
 
@@ -63,32 +70,33 @@ The widget switches to `⠋ Checking pull request…` as soon as `/pr` starts di
 
 Each footer entry is one linked `PR #number` plus one plain-language status: `N unresolved`, `draft`, `open`, `approved`, `CI running`, `CI failed`, `changes requested`, `base update required`, `merge conflict`, `merge-ready`, `merged`, or `closed`. Colors support the text; they do not carry meaning alone.
 
-![Flowchart showing /pr reading fresh GitHub and local state, choosing the first matching condition, and stopping after one route](./docs/pr-routing.svg)
+![Flowchart showing /pr reading fresh GitHub and local state and choosing the next safe route](./docs/pr-routing.svg)
 
 ### Routes
 
 | Current condition | `/pr` route |
 | --- | --- |
 | No current-branch pull request, no published matching ref, safe Git push configuration, and a commit or ordinary pending work | Start pull-request creation. |
-| One open pull request inferred from a published matching ref | Confirm the exact `remote/ref`, then link the local branch. |
+| One open pull request inferred from a published matching ref | Revalidate the exact `remote/ref`, link the local branch without another prompt, then rediscover and continue. |
 | Ambiguous or unsafe discovery | Show the blocked reason and do not mutate Git or GitHub. |
-| Base update required or merge conflict | Update from the base branch's current target when the tree is clean and local HEAD equals the PR head. |
+| Open PR with intended uncommitted or ahead local work | Only when local HEAD descends from the published PR head: inspect, scope, commit if needed, validate and push the exact OID with the saved lease. A behind or diverged HEAD blocks commits. Stop and report when ownership is ambiguous or unrelated work cannot be separated. |
+| Confirmed merge conflict | Rebase onto the pinned base commit when the tree is clean and local HEAD equals the PR head. Resolve conflicts only with clear intent; otherwise stop and report. A previously verified rebase resumes guarded publication instead of rewriting HEAD again. |
 | GitHub Actions job failed | Run the CI fix workflow when the same local prerequisite holds. |
 | External check or commit status failed | Show `CI failed` as a no-action blocker. |
 | Changes requested or unresolved review threads | Start or resume the package comment sweep when the same local prerequisite holds. |
-| Explicit `/pr --feedback` on an open, configured pull request | Start or resume the sweep when the tree is clean and local HEAD equals the PR head. |
+| New standalone feedback (including conversation comments) | Start or resume a guarded sweep when the tree is clean and local HEAD equals the PR head. |
 | No-action state | Report the state without taking action. |
-| Merge-ready pull request | Ask for final confirmation, recheck fresh state, and squash-merge if confirmed. |
+| Merge-ready pull request | Recheck fresh state and squash-merge without another prompt. |
 
-`pi-pr-create` selects its base in this order: the leading `/pr --base BRANCH`, one `branch.<branch>.gh-merge-base` value, then the default branch of validated `origin`. It captures the selected base OID and merge-base. Creation requires a commit ahead or ordinary pending work, including untracked files. A Git operation in progress does not count as pending work. If the current branch is the selected base, pi-pr stays silent because GitHub cannot create a pull request from a ref to itself.
+`pi-pr-create` selects its base in this order: one `branch.<branch>.gh-merge-base` value, then the default branch of validated `origin`. It captures the selected base OID and merge-base. Creation requires a commit ahead or ordinary pending work, including untracked files. A Git operation in progress does not count as pending work. If the current branch is the selected base, pi-pr stays silent because GitHub cannot create a pull request from a ref to itself.
 
 The base always comes from validated `origin`. The head may use that repository or a fork with the same GitHub source. Base and head must use the same GitHub host. Other fork relationships stop before mutation.
 
-It merges the captured base commit before validation and push. It resolves clear conflicts and stops when the base or conflict intent is ambiguous.
+It does not merge or rebase the base during creation. The package helper inspects and commits selected pending paths, including both sides of a staged rename. After a clean verification and relevant validation, it pushes the captured OID.
 
 A configured target never changes branch upstream settings. Without a target, the helper pushes the captured OID to the local branch ref on validated `origin` and fetches its tracking ref. It leaves upstream unset. It creates or updates and validates the exact PR before it sets and verifies upstream. A failed setup rolls back only unchanged helper-owned settings. If configuration changed concurrently, it stops without overwriting it. Retrying `publish` resumes setup without another push or PR mutation.
 
-Without a configured push target, discovery checks validated remotes for the same branch ref. One exact open PR becomes an inferred target. `/pr` names the exact `remote/ref` and asks before linking it. The extension revalidates the branch, PR, remote OID, and Git configuration before mutation. It rolls back its upstream and remote-tracking changes if final verification fails.
+Without a configured push target, discovery checks validated remotes for the same branch ref. One exact open PR becomes an inferred target. `/pr` links the single exact `remote/ref` without a separate confirmation, then rediscovers the same configured PR before continuing. The extension revalidates the branch, PR, remote OID, and Git configuration before mutation. It rolls back its upstream and remote-tracking changes if final verification fails.
 
 Multiple candidate remotes, multiple matching PRs, OID mismatches, and unsafe Git push configuration block routing. A published ref with no PR also blocks creation. If no candidate ref exists, creation uses only a validated `origin` destination.
 
@@ -96,13 +104,13 @@ The creation workflow repeats destination, remote OID, PR, and configuration che
 
 Each helper workflow receives a random run ID and its first action. The run stays bound to one session, canonical worktree, route, and fresh authority. Helper calls from another run, session, worktree, or route fail.
 
-For comment sweeps, `/pr` checks the package recovery file without changing it. It selects `start` when recovery is absent. It selects `resume` only when valid recovery matches the fresh route authority. Invalid recovery stays unchanged and blocks dispatch with its path and reason.
+For comment sweeps, `/pr` checks the package recovery file without changing it. It selects `start` when recovery is absent. It selects `resume` only when valid recovery matches the fresh route authority. Invalid recovery stays unchanged and blocks dispatch with its path and reason. One `/pr` inspects all feedback, records a complete disposition ledger and exact owned paths, then makes scoped fixes, validates, and publishes without a second approval. New sweeps require a clean worktree at the original head before recording the plan; publication validates the clean scoped commit. Recovery preserves the saved plan and checks owned paths and remote authority before continuing. After publication, the helper carries unchanged decisions through a fresh feedback snapshot; new or edited feedback remains blocked for a later fix cycle. It does not expand path ownership or push again in the same sweep.
 
-`/pr --feedback` uses the same discovery, reservation, recovery, and guard checks. It can select the sweep even when CI failure or merge readiness would otherwise select another route. Without the flag, route priority stays unchanged.
+A flagless `/pr` reads complete standalone and inline feedback before merge or waiting when the tree is clean and HEAD equals the configured PR head. It compares feedback against the last finalized sweep. New or edited feedback selects the guarded sweep; comments already assessed in that sweep do not. Immediately before merging, it checks again and cancels if feedback arrived meanwhile. A malformed attention marker is preserved and blocks routing rather than silently losing triage history.
 
 Direct skill or `pi_pr_*` tool calls cannot create route authority. Run `/pr` to reserve a fresh route.
 
-Only one helper run can exist at a time. Most runs expire when the agent settles. A create or branch-update conflict stays available for one user-guided continuation, then expires after that continuation settles. Session replacement and shutdown forget the run without aborting or cleaning a pending merge.
+Only one helper run can exist at a time. Most runs expire when the agent settles. A branch-update conflict stays available for one user-guided continuation, then expires after that continuation settles. Session replacement and shutdown forget the run without aborting or cleaning a pending rebase. A verified rebase can be resumed through a fresh `/pr` run; an unverified rebase intent requires manual recovery, never an automatic retry.
 
 After a `/pr` create workflow settles, the extension waits for a refresh that finds a configured current PR. It then prefixes the Herdr workspace label with `#<number> • `.
 
@@ -116,26 +124,26 @@ If Herdr lookup, JSON validation, or rename fails, the PR and normal UI refresh
 
 Current-branch discovery reads pull requests associated with the exact push repository ref. It does not run a global branch search. It finds a fork-head PR whose base is an upstream repository. A unique historical match uses the exact remote push-ref OID, not local HEAD.
 
-A no-action state includes drafts, merged or closed pull requests, unsupported failed CI, pending review, and blocked merge policy. Running CI blocks merge but not other mutating workflows. A dirty tree or mismatched local HEAD also blocks a mutating workflow.
+A no-action state includes drafts, merged or closed pull requests, unsupported failed CI, pending review, and blocked merge policy. Running CI blocks merge but not other mutating workflows. A matching verified branch-update recovery takes priority, then matching comment-sweep recovery. Otherwise a dirty tree or ahead local HEAD selects the scoped local publication helper first. A behind or diverged head remains a blocker unless matching recovery can resume.
 
 ### Route priority
 
-A missing pull request uses creation. For an existing pull request, the first matching condition wins:
+A missing pull request uses creation. For an existing configured open, non-draft pull request, verified branch-update recovery is checked first, then matching sweep recovery. They can resume guarded publication or owned edits before the local clean/equal gate. Otherwise, the first matching condition wins:
 
 1. Merged, closed, or draft: no action.
-2. Base update required or merge conflict. Run only with a clean tree and equal local and PR heads.
-3. A failed GitHub Actions job. Apply the same local prerequisite. Other failed checks remain blockers.
-4. Changes requested or unresolved review threads. Apply the same local prerequisite.
-5. Waiting or local safety block: no action.
-6. Merge-ready: allow clean local HEAD equal to or behind the PR head. Confirm, then merge directly.
+2. Dirty worktree or ahead local HEAD: scope and publish intended local work. In-progress Git operations block its helper; unrelated pending paths require an ownership decision.
+3. Confirmed merge conflict: rebase onto the pinned base OID only with a clean, equal local HEAD. A behind base alone never triggers a rebase.
+4. Diagnosable GitHub Actions failure: run CI fix with the same local prerequisite.
+5. Changes requested or unresolved review threads: run the comment sweep.
+6. New or edited standalone feedback, including conversation comments and review bodies: triage and fix scoped issues without another approval.
+7. Running CI, pending review, blocked policy, or unsafe local merge state: wait or report the blocker.
+8. Merge-ready: allow a clean local HEAD equal to or behind the PR head. Revalidate, then squash-merge directly.
 
-Ordinary conversation comments do not trigger a route or block a merge. Changes requested and unresolved review threads can select the package comment sweep. Use `/pr --feedback` when a conversation comment needs action.
+The sweep finalizes its feedback marker only after checking the complete refreshed generation. GitHub offers no resolution control for standalone comments or review bodies; they are triaged and reported, not marked resolved.
 
 The comment sweep resolves its bundled helper and references from the installed package skill path. It does not require an external `jq` executable.
 
-After publishing, `refresh` freezes the complete latest feedback and returns only IDs and kinds. Use `show` to inspect every fresh item.
-
-A second guarded `record` must cover that exact snapshot before resolution or finalization. It keeps the paths from the initial record.
+After publishing, `refresh` freezes the complete latest feedback, retains unchanged decisions, and blocks new or edited actionable items for the next `/pr` cycle. It needs no second record or approval. `resolve` selects eligible unresolved review threads with no blocked children, posts a commit URL for addressed threads or a one-sentence ledger reason for non-actionable threads, and verifies the returned reply ID before resolving. The helper checks feedback capacity and leaves blocked threads open. If a reply response is lost without a saved ID, recovery stops without replaying or guessing from a matching comment body. `finalize` uses its saved projection and rechecks complete live feedback. Standalone comments and review bodies have no GitHub resolution state; report them without claiming they were resolved.
 
 The sweep runs existing non-destructive checks on the clean committed `HEAD` before publishing. Finalization reruns them as a later state guard.
 
@@ -143,7 +151,7 @@ The sweep runs existing non-destructive checks on the clean committed `HEAD` bef
 
 PR discovery starts in the background at session start, so the Pi footer appears before the PR status is ready. When switching sessions, the previous PR status and action hint clear immediately; the new ones appear when discovery finishes. A directory outside a Git worktree stays silent. The UI shows `PR · status unavailable` for other discovery failures and reports only a generic error.
 
-They refresh after local commits, PR creation, pushes, and each dispatched workflow settles. During creation, intermediate refreshes wait until the workflow settles. They also refresh after any successful delegated task settles. There is no periodic presentation refresh, so external changes may leave the footer and widget stale indefinitely. `/pr` cancels any pending presentation lookup and reads fresh state before routing or acting; it remains authoritative.
+They refresh after local commits, PR creation, pushes, and each dispatched workflow settles. A successful terminal helper action redispatches through fresh discovery before settlement; an incomplete or failed helper does not chain. During creation, intermediate refreshes wait until the workflow settles. They also refresh after any successful delegated task settles. There is no periodic presentation refresh, so external changes may leave the footer and widget stale indefinitely. `/pr` cancels any pending presentation lookup and reads fresh state before routing or acting; it remains authoritative.
 
 The create widget stays hidden on a clean branch with no commit ahead. It appears for a commit ahead or ordinary pending work. It stays hidden during a Git operation and when the current branch is the selected base. `/pr` replaces any hint with routing feedback while it selects a route. The feedback clears before route interaction. A dispatched workflow keeps the widget hidden until the agent settles. Direct and no-action routes refresh it after completion. A failed command restores the prior hint and schedules a refresh, except when fresh lookup hits the GitHub API quota: it shows the sanitized message `GitHub API rate limit exhausted; retry after GitHub resets it` and does not immediately retry.
 
@@ -159,23 +167,39 @@ The GitHub response must match the observed URL, host, repository, head ref, hea
 
 ## Limits and recovery
 
-- `/pr` accepts either standalone `--feedback` or creation syntax with leading `--base BRANCH` and optional guidance. It rejects unknown or conflicting options. It does not open a browser.
+A comment sweep keeps a private, atomically replaced recovery file under
+`<agent-dir>/config/pi-pr/sweep/<worktree-id>/state.json`. It contains the frozen PR identity,
+original head and lease, full feedback, ledger, owned paths, and mutation attempts. After a push,
+`refresh` stores the new complete snapshot before a replacement ledger; `show` and `record` must
+cover it before thread mutations or finalization. Resume rechecks local state and the remote head
+and reconciles attempted mutations before issuing a new run. Malformed or mismatched recovery is
+preserved and blocks dispatch; never remove it or replay an uncertain mutation to continue.
+
+A branch update keeps a private recovery file under `<agent-dir>/config/pi-pr/update-branch/`.
+It records the original lease before rewriting HEAD, then the verified HEAD after checking the clean
+branch against the pinned base. A fresh `/pr` run checks that record and the branch before returning
+the verified result for validation and exact-lease publication; it never repeats Git rebase.
+If a rebase ended without verification, the record is preserved and routing stops for manual
+recovery. After an uncertain push, publication checks the exact remote postcondition without
+replaying the push. Malformed or mismatched records stay unchanged and block routing.
+
+- `/pr` accepts no arguments and does not open a browser.
 - It does not run `/done` or `/sweep`.
-- Presentation refreshes do not auto-triage comments or start a workflow. The package comment sweep starts or resumes only when an explicit `/pr` selects it.
+- Presentation refreshes do not auto-triage comments or start a workflow. The package comment sweep starts or resumes only when an explicit `/pr` selects it. New or blocked standalone comments can select the sweep again after fresh inspection.
 - It does not enable auto-merge or add a merge queue.
-- It does not rebase the local branch, overwrite concurrent remote updates, delete branches, or clean up worktrees. Creation uses exact leases plus ancestry checks; an empty lease is only an atomic absence check.
+- It rebases only after a confirmed conflict. It never rebases merely because the base is behind, overwrites concurrent remote updates, deletes branches, or cleans up worktrees. Creation uses exact leases and an empty lease is only an atomic absence check.
 - Creation, discovery, and comment-sweep pushes require one unambiguous push URL for the configured destination.
 - Presentation fetches use that exact push URL and exact advertised OID. They do not use shared fetch state.
-- A pull request that GitHub reports as behind requires a base update.
+- GitHub may block merging while the base is behind. That alone does not authorize a rebase.
 - Direct merges always use squash. GitHub rejects the mutation if repository policy does not allow it.
 - Before merge, `/pr` fetches the exact head OID from the validated push URL without shared fetch state.
 - A merge, rebase, cherry-pick, revert, or sequencer state blocks direct merge, even when `git status` is empty.
-- A branch update resolves the base repository ref directly. It stops if that ref moves before merge or push.
+- A conflict rebase resolves the base repository ref directly. It stops if that ref moves before rebase or force-with-lease push. Branches with merge commits since the fork point cannot be rebased automatically; preserve their merge resolutions manually.
 - Before a comment-sweep push, it revalidates the configured destination, full PR identity, and local HEAD. It pushes the captured OID.
 - CI repair resolves workflow runs from check-suite IDs. It does not treat HTML details links as identity.
 - It streams a bounded failed-step log tail and runs one narrow local reproducer before editing.
 - Before push, CI repair revalidates the saved destination, open PR, failure evidence, and repair HEAD.
 - An already-published local HEAD needs no second push.
-- Direct merge requires final confirmation and a fresh readiness check.
+- Direct merge requires a fresh readiness check and an exact head OID; `/pr` is the authorization, not a separate confirmation dialog.
 - After a successful merge, the create widget stays hidden until a new local commit.
 - Only authenticated GitHub.com and GitHub Enterprise repositories are supported.

package/docs/pr-routing.svg

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <svg xmlns="http://www.w3.org/2000/svg" width="1280" height="720" viewBox="0 0 1280 720" role="img" aria-labelledby="pr-routing-title pr-routing-desc">
-      <title id="pr-routing-title">How /pr picks one route</title>
-      <desc id="pr-routing-desc">The /pr command creates a pull request when needed, gates branch update, feedback sweep, and CI repair on a clean worktree with local HEAD equal to the PR head, and permits direct merge when clean local HEAD is equal to or behind the PR head.</desc>
+      <title id="pr-routing-title">How /pr picks each next route</title>
+      <desc id="pr-routing-desc">The /pr command creates a pull request when needed, scopes local work before publication, rebases only confirmed conflicts, and checks new feedback before merge, and permits direct merge when clean local HEAD is equal to or behind the PR head.</desc>
       <defs>
         <style>@import url("https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&amp;family=Geist:wght@400;500;600&amp;family=Geist+Mono:wght@400;500;600&amp;display=swap");</style>
         <marker id="pr-routing-arrow" markerWidth="8" markerHeight="8" refX="8" refY="4" orient="auto">
@@ -18,10 +18,10 @@
       <rect width="1280" height="720" fill="#f0eee9"/>
 
       <!-- Header -->
-      <text x="80" y="68" fill="#101828" font-size="28" font-weight="400" font-family="'Instrument Serif', serif">How /pr picks one route</text>
-      <text x="80" y="88" fill="#4c5665" font-size="8" font-family="'Geist', sans-serif">Fresh state enters a strict, top-down priority ladder.</text>
+      <text x="80" y="68" fill="#101828" font-size="28" font-weight="400" font-family="'Instrument Serif', serif">How /pr picks each next route</text>
+      <text x="80" y="88" fill="#4c5665" font-size="8" font-family="'Geist', sans-serif">Fresh state enters a strict, top-down priority ladder after each completed route.</text>
       <text x="1200" y="48" fill="#4c5665" font-size="8" font-weight="500" font-family="'Geist Mono', monospace" text-anchor="end" letter-spacing="0.12em">FIRST MATCHING CONDITION WINS</text>
-      <text x="1200" y="68" fill="#4c5665" font-size="8" font-weight="500" font-family="'Geist Mono', monospace" text-anchor="end" letter-spacing="0.12em">AT MOST ONE ROUTE</text>
+      <text x="1200" y="68" fill="#4c5665" font-size="8" font-weight="500" font-family="'Geist Mono', monospace" text-anchor="end" letter-spacing="0.12em">FRESH AFTER EACH ROUTE</text>
 
       <!-- Continuation arrows, drawn before nodes -->
       <g fill="none" stroke="#4c5665" stroke-width="1.2" marker-end="url(#pr-routing-arrow)">
@@ -67,10 +67,10 @@
       <line x1="704" y1="296" x2="704" y2="328" stroke="rgba(16,24,40,0.141)" stroke-width="1"/>
       <text x="148" y="320" fill="#4c5665" font-size="12" font-family="'Geist Mono', monospace" text-anchor="middle">3</text>
       <text x="200" y="304" fill="#4c5665" font-size="8" font-weight="500" font-family="'Geist Mono', monospace" letter-spacing="0.12em">CONDITION</text>
-      <text x="200" y="324" fill="#101828" font-size="12" font-weight="600" font-family="'Geist', sans-serif">Base behind or conflicted</text>
+      <text x="200" y="324" fill="#101828" font-size="12" font-weight="600" font-family="'Geist', sans-serif">Dirty/ahead work or confirmed conflict</text>
       <text x="728" y="304" fill="#4c5665" font-size="8" font-weight="500" font-family="'Geist Mono', monospace" letter-spacing="0.12em">ROUTE</text>
-      <text x="728" y="324" fill="#101828" font-size="12" font-weight="600" font-family="'Geist', sans-serif">Update if clean + equal</text>
-      <text x="1136" y="324" fill="#4c5665" font-size="8" font-family="'Geist Mono', monospace" text-anchor="end">otherwise no action</text>
+      <text x="728" y="324" fill="#101828" font-size="12" font-weight="600" font-family="'Geist', sans-serif">Publish work or rebase conflict</text>
+      <text x="1136" y="324" fill="#4c5665" font-size="8" font-family="'Geist Mono', monospace" text-anchor="end">safe authority required</text>
 
       <!-- 4 -->
       <rect x="120" y="352" width="1040" height="48" rx="6" fill="#ffffff" stroke="rgba(16,24,40,0.141)" stroke-width="1"/>
@@ -89,7 +89,7 @@
       <line x1="704" y1="424" x2="704" y2="456" stroke="rgba(16,24,40,0.141)" stroke-width="1"/>
       <text x="148" y="448" fill="#4c5665" font-size="12" font-family="'Geist Mono', monospace" text-anchor="middle">5</text>
       <text x="200" y="432" fill="#4c5665" font-size="8" font-weight="500" font-family="'Geist Mono', monospace" letter-spacing="0.12em">CONDITION</text>
-      <text x="200" y="452" fill="#101828" font-size="12" font-weight="600" font-family="'Geist', sans-serif">Changes requested or unresolved threads</text>
+      <text x="200" y="452" fill="#101828" font-size="12" font-weight="600" font-family="'Geist', sans-serif">Changes requested or new feedback</text>
       <text x="728" y="432" fill="#4c5665" font-size="8" font-weight="500" font-family="'Geist Mono', monospace" letter-spacing="0.12em">ROUTE</text>
       <text x="728" y="452" fill="#101828" font-size="12" font-weight="600" font-family="'Geist', sans-serif">Sweep if clean + equal</text>
       <text x="1136" y="452" fill="#4c5665" font-size="8" font-family="'Geist Mono', monospace" text-anchor="end">otherwise no action</text>
@@ -103,7 +103,7 @@
       <text x="200" y="516" fill="#101828" font-size="12" font-weight="600" font-family="'Geist', sans-serif">Other waiting or merge-local block</text>
       <text x="728" y="496" fill="#4c5665" font-size="8" font-weight="500" font-family="'Geist Mono', monospace" letter-spacing="0.12em">ROUTE</text>
       <text x="728" y="516" fill="#101828" font-size="12" font-weight="600" font-family="'Geist', sans-serif">No action</text>
-      <text x="1136" y="516" fill="#4c5665" font-size="8" font-family="'Geist Mono', monospace" text-anchor="end">CI running, review or policy pending, dirty, ahead, or diverged</text>
+      <text x="1136" y="516" fill="#4c5665" font-size="8" font-family="'Geist Mono', monospace" text-anchor="end">CI running, review or policy pending, behind, or diverged</text>
 
       <!-- 7 -->
       <rect x="120" y="544" width="1040" height="48" rx="6" fill="rgba(29,78,216,0.08)" stroke="#1d4ed8" stroke-width="1.2"/>
@@ -121,7 +121,7 @@
       <line x1="80" y1="636" x2="80" y2="664" stroke="#4c5665" stroke-width="1.2" marker-end="url(#pr-routing-arrow)"/>
       <text x="104" y="640" fill="#4c5665" font-size="8" font-weight="500" font-family="'Geist Mono', monospace" letter-spacing="0.12em">DOWNWARD CONNECTOR</text>
       <text x="104" y="664" fill="#101828" font-size="8" font-family="'Geist', sans-serif">Otherwise, continue to the next condition.</text>
-      <text x="668" y="660" fill="#101828" font-size="28" font-weight="400" font-family="'Instrument Serif', serif">1×</text>
-      <text x="724" y="640" fill="#4c5665" font-size="8" font-weight="500" font-family="'Geist Mono', monospace" letter-spacing="0.12em">ONE-ROUTE RULE</text>
-      <text x="724" y="664" fill="#101828" font-size="8" font-family="'Geist', sans-serif">At most one route: first matching condition wins, then /pr stops.</text>
+      <text x="668" y="660" fill="#101828" font-size="28" font-weight="400" font-family="'Instrument Serif', serif">↻</text>
+      <text x="724" y="640" fill="#4c5665" font-size="8" font-weight="500" font-family="'Geist Mono', monospace" letter-spacing="0.12em">CONTINUATION RULE</text>
+      <text x="724" y="664" fill="#101828" font-size="8" font-family="'Geist', sans-serif">The first match runs; completed routes return to fresh discovery.</text>
     </svg>

package/extensions/pr-command.ts

@@ -1,8 +1,9 @@
 import type {
 	ExtensionAPI,
-	ExtensionCommandContext,
+	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import { executeGitHubMerge } from "./pr-merge.ts";
+import { needsFeedbackAttention } from "./pr-feedback-attention.ts";
 import {
 	linkInferredPullRequest,
 	loadCurrentPullRequest,
@@ -11,35 +12,34 @@ import {
 } from "./pr-github.ts";
 import {
 	deriveNextStep,
-	deriveRouteDecision,
-	type FeedbackRouteBlocker,
 	type NextStep,
 	type PullRequestTarget,
-	type RouteIntent,
 } from "./pr-routing.ts";
 
-type WorkflowNextStep = Extract<NextStep, "create" | "update-branch" | "sweep" | "fix-ci">;
+type WorkflowNextStep = Extract<NextStep, "create" | "publish-work" | "update-branch" | "sweep" | "fix-ci">;
 
 const WORKFLOWS: Record<WorkflowNextStep, string> = {
 	create: "skill:pi-pr-create",
+	"publish-work": "skill:pi-pr-publish-work",
 	"update-branch": "skill:pi-pr-update-branch",
 	sweep: "skill:pi-pr-comment-sweep",
 	"fix-ci": "skill:pi-pr-fix-ci",
 };
 type WorkflowReservation =
-	| { route: "create"; target: PullRequestTarget; base?: string }
+	| { route: "create"; target: PullRequestTarget }
 	| { route: Exclude<WorkflowNextStep, "create">; pullRequest: CurrentPullRequest };
-type WorkflowLaunchAction = "prepare" | "merge" | "start" | "resume" | "collect";
+type WorkflowLaunchAction = "prepare" | "inspect" | "rebase" | "start" | "resume" | "collect";
 type WorkflowReservationResult = { runId: string; action: WorkflowLaunchAction };
 
 type PrCommandPi = Pick<ExtensionAPI, "exec" | "getCommands" | "sendUserMessage">;
 export type PrCommandInvocation = ((nextStep: NextStep) => void) & {
 	sessionGeneration: number;
 	assertCurrent(): void;
+	completedRoutes?: ReadonlySet<string>;
 };
 export type PrCommandHandler = (
 	args: string,
-	ctx: ExtensionCommandContext,
+	ctx: ExtensionContext,
 	onRouteResolved?: PrCommandInvocation | ((nextStep: NextStep) => void),
 ) => Promise<NextStep>;
 
@@ -52,67 +52,27 @@ export type WorkflowPromptIdentity = Readonly<{
 
 export type PrCommandDependencies = {
 	loadCurrentPullRequest?: typeof loadCurrentPullRequest;
+	needsFeedbackAttention?: typeof needsFeedbackAttention;
 	linkInferredPullRequest?: typeof linkInferredPullRequest;
+	inspectSweepRecovery?: (pullRequest: CurrentPullRequest, ctx: ExtensionContext) => Promise<boolean>;
+	inspectBranchRecovery?: (pullRequest: CurrentPullRequest, ctx: ExtensionContext) => Promise<boolean>;
 	reserveWorkflow?: (
 		reservation: WorkflowReservation,
-		ctx: ExtensionCommandContext,
+		ctx: ExtensionContext,
 		invocation?: PrCommandInvocation,
 	) => Promise<WorkflowReservationResult>;
 	markWorkflowPromptQueued?: (identity: WorkflowPromptIdentity, queued: boolean) => void;
 	releaseWorkflow?: (runId: string, invocation?: PrCommandInvocation) => void;
 };
 
-type ParsedPrArguments = {
-	base?: string;
-	intent: RouteIntent;
-	instructions: string;
-};
-
-function parsePrArguments(args: string): ParsedPrArguments {
-	const leading = args.trimStart();
-	const trimmed = leading.trim();
-	if (leading.startsWith("--feedback=")) throw new Error("/pr feedback syntax is --feedback");
-	if (/^--feedback(?:\s|$)/.test(leading)) {
-		if (trimmed !== "--feedback") throw new Error("/pr --feedback cannot be combined with other options or instructions");
-		return { intent: "feedback", instructions: "" };
-	}
-	if (/(?:^|\s)--feedback(?=\s|=|$)/.test(leading)) {
-		throw new Error("/pr --feedback cannot be combined with other options or instructions");
-	}
-	if (leading.startsWith("--base=")) throw new Error("/pr base syntax is --base <branch>");
-	if (/^--base(?:\s|$)/.test(leading)) {
-		const value = /^--base\s+(\S+)/.exec(leading);
-		if (!value) throw new Error("/pr --base requires a branch");
-		const instructions = leading.slice(value[0].length).trim();
-		if (instructions.startsWith("--")) throw new Error(`Unknown /pr option: ${instructions.split(/\s+/, 1)[0]}`);
-		return { base: value[1]!, intent: "automatic", instructions };
-	}
-	if (leading.startsWith("--")) throw new Error(`Unknown /pr option: ${leading.split(/\s+/, 1)[0]}`);
-	return { intent: "automatic", instructions: args.trim() };
-}
-
-function feedbackBlockerMessage(blocker: FeedbackRouteBlocker): string {
-	switch (blocker.kind) {
-		case "discovery-blocked": return "/pr --feedback is blocked because pull request discovery is unsafe";
-		case "pull-request-unavailable": return "/pr --feedback requires a current pull request";
-		case "pull-request-not-open": return "/pr --feedback requires an open pull request";
-		case "target-not-configured": return "/pr --feedback requires a configured pull request target; run /pr to link the branch first";
-		case "worktree-dirty": return "/pr --feedback is blocked by a dirty worktree";
-		case "head-not-equal": return `/pr --feedback is blocked by local HEAD ${blocker.relation}`;
-	}
-}
-
 function workflowReservation(
 	nextStep: WorkflowNextStep,
 	discovery: Awaited<ReturnType<typeof loadCurrentPullRequest>>,
-	base: string | undefined,
-	instructions: string,
 ): WorkflowReservation {
 	if (nextStep === "create") {
 		if (discovery.kind !== "none") throw new Error("/pr create failed: creation target is unavailable");
-		return { route: "create", target: discovery.creationTarget, ...(base === undefined ? {} : { base }) };
+		return { route: "create", target: discovery.creationTarget };
 	}
-	if (instructions) throw new Error("The current /pr helper route does not accept instructions");
 	if (discovery.kind !== "current") throw new Error(`/pr ${nextStep} failed: pull request is unavailable`);
 	return { route: nextStep, pullRequest: discovery.pullRequest };
 }
@@ -130,14 +90,13 @@ function packageWorkflowCommand(pi: PrCommandPi, route: WorkflowNextStep) {
 
 async function dispatchWorkflow(
 	pi: PrCommandPi,
-	ctx: ExtensionCommandContext,
+	ctx: ExtensionContext,
 	route: WorkflowNextStep,
 	reservation: WorkflowReservation,
 	invocation: PrCommandInvocation | undefined,
 	reserve: NonNullable<PrCommandDependencies["reserveWorkflow"]>,
 	markPromptQueued: NonNullable<PrCommandDependencies["markWorkflowPromptQueued"]>,
 	release: NonNullable<PrCommandDependencies["releaseWorkflow"]>,
-	instructions: string,
 ): Promise<void> {
 	const workflow = packageWorkflowCommand(pi, route);
 	let runId: string | undefined;
@@ -152,7 +111,7 @@ async function dispatchWorkflow(
 			? { deliverAs: "followUp" as const, expandPromptTemplates: true }
 			: { expandPromptTemplates: true };
 		invocation?.assertCurrent();
-		pi.sendUserMessage(`/${identity.skill} runId=${identity.runId} action=${identity.action}${instructions ? ` ${instructions}` : ""}`, options);
+		pi.sendUserMessage(`/${identity.skill} runId=${identity.runId} action=${identity.action}`, options);
 	} catch (error) {
 		if (runId !== undefined) release(runId, invocation);
 		throw error;
@@ -169,7 +128,7 @@ function noActionNotification(pullRequest: CurrentPullRequest): { message: strin
 	if (pullRequest.conditions.ci === "failure-blocked") {
 		return { message: `PR #${pullRequest.number} has a failed CI check that cannot run the CI fix workflow`, type: "warning" };
 	}
-	const mutatingWorkflowSelected = pullRequest.conditions.baseUpdateRequired || pullRequest.conditions.conflict ||
+	const mutatingWorkflowSelected = pullRequest.conditions.conflict ||
 		pullRequest.conditions.changesRequested || pullRequest.conditions.unresolvedThreads > 0 ||
 		pullRequest.conditions.ci === "failure";
 	if (mutatingWorkflowSelected && pullRequest.local.worktree === "dirty") {
@@ -207,16 +166,11 @@ function isSameConfirmedMerge(current: CurrentPullRequest, fresh: CurrentPullReq
 
 async function mergePullRequest(
 	pi: PrCommandPi,
-	ctx: ExtensionCommandContext,
+	ctx: ExtensionContext,
 	current: CurrentPullRequest,
 	load: typeof loadCurrentPullRequest,
-): Promise<boolean> {
-	const confirmed = await ctx.ui.confirm(
-		`Merge PR #${current.number}?`,
-		"Method: squash.",
-	);
-	if (!confirmed) return false;
-
+	needsFeedback: typeof needsFeedbackAttention,
+): Promise<void> {
 	await executeGitHubMerge({
 		exec: (command, args, options) => pi.exec(command, args, {
 			...options,
@@ -241,32 +195,27 @@ async function mergePullRequest(
 			if (deriveNextStep(discovery) !== "merge") {
 				throw new Error(`PR #${fresh.number} merge cancelled: pull request is no longer merge-ready`);
 			}
+			if (await needsFeedback(fresh, { cwd: ctx.cwd, signal: ctx.signal, load })) {
+				throw new Error(`PR #${fresh.number} merge cancelled: new feedback needs review`);
+			}
 		},
 	});
-	return true;
 }
 
 async function linkPullRequest(
 	pi: PrCommandPi,
-	ctx: ExtensionCommandContext,
+	ctx: ExtensionContext,
 	current: CurrentPullRequest,
 	load: typeof loadCurrentPullRequest,
 	link: typeof linkInferredPullRequest,
-): Promise<void> {
-	const targetName = `${current.target.remote}/${current.target.ref}`;
-	const confirmed = await ctx.ui.confirm(
-		`Link pull request branch to ${targetName}?`,
-		`Set ${targetName} as the push target for this branch.`,
-	);
-	if (!confirmed) return;
-
+): Promise<CurrentPullRequest> {
 	const discovery = await load(pi, ctx);
 	if (
 		discovery.kind !== "current" ||
 		discovery.pullRequest.target.provenance !== "inferred" ||
 		!samePullRequestSnapshot(current, discovery.pullRequest)
 	) throw new Error("Link branch cancelled: inferred pull request context changed");
-	await link(pi, ctx, discovery.pullRequest);
+	return await link(pi, ctx, discovery.pullRequest);
 }
 
 export function createPrCommandHandler(
@@ -274,32 +223,51 @@ export function createPrCommandHandler(
 	dependencies: PrCommandDependencies = {},
 ): PrCommandHandler {
 	const load = dependencies.loadCurrentPullRequest ?? loadCurrentPullRequest;
+	const needsFeedback = dependencies.needsFeedbackAttention ?? needsFeedbackAttention;
 	const link = dependencies.linkInferredPullRequest ?? linkInferredPullRequest;
+	const inspectSweepRecovery = dependencies.inspectSweepRecovery ?? (async () => false);
+	const inspectBranchRecovery = dependencies.inspectBranchRecovery ?? (async () => false);
 	const reserve = dependencies.reserveWorkflow ?? (async () => {
 		throw new Error("/pr workflow tools are unavailable");
 	});
 	const markPromptQueued = dependencies.markWorkflowPromptQueued ?? (() => {});
 	const release = dependencies.releaseWorkflow ?? (() => {});
-	return async (args, ctx, onRouteResolved) => {
+	const handle = async (
+		args: string, ctx: ExtensionContext,
+		onRouteResolved?: PrCommandInvocation | ((nextStep: NextStep) => void),
+		linkedAuthority?: CurrentPullRequest,
+	): Promise<NextStep> => {
 		const commandInvocation = onRouteResolved && "assertCurrent" in onRouteResolved
 			? onRouteResolved as PrCommandInvocation
 			: undefined;
-		const { base, intent, instructions } = parsePrArguments(args);
-		const discovery = await load(pi, ctx, undefined, undefined, base);
+		if (args.trim()) throw new Error("/pr does not accept arguments");
+		const discovery = await load(pi, ctx);
 		commandInvocation?.assertCurrent();
-		const decision = deriveRouteDecision(discovery, intent);
-		if (decision.kind === "feedback-blocked") {
-			onRouteResolved?.("blocked");
-			throw new Error(feedbackBlockerMessage(decision.blocker));
+		if (linkedAuthority && (discovery.kind !== "current" || discovery.pullRequest.target.provenance !== "configured" ||
+			!isSameConfirmedMerge(linkedAuthority, discovery.pullRequest))) {
+			throw new Error("Link branch continuation cancelled: configured pull request context changed");
 		}
-		const nextStep = decision.nextStep;
-		onRouteResolved?.(nextStep);
-		if (base !== undefined && nextStep !== "create") {
-			throw new Error("/pr --base is accepted only for pull request creation");
+		let nextStep = deriveNextStep(discovery);
+		if (discovery.kind === "current" && discovery.pullRequest.lifecycle === "open" &&
+			!discovery.pullRequest.conditions.draft && discovery.pullRequest.target.provenance === "configured" &&
+			await inspectBranchRecovery(discovery.pullRequest, ctx)) {
+			nextStep = "update-branch";
+			commandInvocation?.assertCurrent();
+		}
+		if (nextStep !== "update-branch" && discovery.kind === "current" && discovery.pullRequest.lifecycle === "open" &&
+			!discovery.pullRequest.conditions.draft && discovery.pullRequest.target.provenance === "configured" &&
+			await inspectSweepRecovery(discovery.pullRequest, ctx)) {
+			nextStep = "sweep";
+			commandInvocation?.assertCurrent();
 		}
-		if (instructions && !(nextStep in WORKFLOWS)) {
-			throw new Error("The current /pr route does not accept instructions");
+		if (discovery.kind === "current" && (nextStep === "merge" || nextStep === "none") &&
+			discovery.pullRequest.lifecycle === "open" && !discovery.pullRequest.conditions.draft &&
+			discovery.pullRequest.target.provenance === "configured" &&
+			discovery.pullRequest.local.worktree === "clean" && discovery.pullRequest.local.head === "equal") {
+			if (await needsFeedback(discovery.pullRequest, { cwd: ctx.cwd, signal: ctx.signal, load })) nextStep = "sweep";
+			commandInvocation?.assertCurrent();
 		}
+		onRouteResolved?.(nextStep);
 		if (discovery.kind === "inactive") return nextStep;
 		if (discovery.kind === "blocked") {
 			return nextStep;
@@ -313,17 +281,23 @@ export function createPrCommandHandler(
 		}
 		if (nextStep === "link-branch") {
 			if (discovery.kind !== "current") throw new Error("/pr link failed: pull request is unavailable");
-			await linkPullRequest(pi, ctx, discovery.pullRequest, load, link);
-			return nextStep;
+			const linked = await linkPullRequest(pi, ctx, discovery.pullRequest, load, link);
+			if (linked.target.provenance !== "configured") throw new Error("Link branch failed: target was not configured");
+			return await handle("", ctx, onRouteResolved, linked);
 		}
 		if (nextStep === "merge") {
 			if (discovery.kind !== "current") throw new Error("/pr merge failed: pull request is unavailable");
-			return await mergePullRequest(pi, ctx, discovery.pullRequest, load) ? "merge" : "none";
+			await mergePullRequest(pi, ctx, discovery.pullRequest, load, needsFeedback);
+			return "merge";
 		}
 
 		if (!(nextStep in WORKFLOWS)) throw new Error(`/pr cannot dispatch route ${nextStep}`);
 		const route = nextStep as WorkflowNextStep;
-		const reservation = workflowReservation(route, discovery, base, instructions);
+		if (commandInvocation?.completedRoutes?.has(route)) {
+			ctx.ui.notify(`PR ${route} already ran; inspect fresh state before retrying`, "warning");
+			return "none";
+		}
+		const reservation = workflowReservation(route, discovery);
 		await dispatchWorkflow(
 			pi,
 			ctx,
@@ -333,8 +307,8 @@ export function createPrCommandHandler(
 			reserve,
 			markPromptQueued,
 			release,
-			route === "create" ? instructions : "",
 		);
 		return nextStep;
 	};
+	return handle;
 }