@henryqw/pi-pr 3.0.1 → 3.1.2

package/README.md

@@ -34,11 +34,13 @@ write files.
 
 ## Use
 
-Run `/pr` without arguments in a GitHub checkout. It reads the current branch pull request and local state, then runs one route. The PR hostname selects its GitHub API host, and the extension works outside Herdr.
+Run `/pr` in a GitHub checkout. It reads the current branch pull request and local state, then runs one route. The PR hostname selects its GitHub API host, and the extension works outside Herdr.
+
+Add optional instructions to guide a creation, branch-update, CI-fix, or feedback workflow. For example, run `/pr keep the title under 50 characters`. Direct routes, such as linking or merging, reject instructions instead of ignoring them.
 
 | Surface | Type | Purpose |
 | --- | --- | --- |
-| `/pr` | command | Run the current pull request's next safe route. |
+| `/pr [instructions]` | command | 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 actionable icon-prefixed `Run /pr to …` hint. |
 
@@ -54,7 +56,9 @@ Each footer entry is one linked `PR #number` plus one plain-language status: `N
 
 | Current condition | `/pr` route |
 | --- | --- |
-| No current-branch pull request, including no upstream push target | Start pull-request creation. |
+| No current-branch pull request, no published matching ref, and safe Git push configuration | Start pull-request creation. |
+| One open pull request inferred from a published matching ref | Confirm the exact `remote/ref`, then link the local branch. |
+| 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. |
 | CI failed | Run the CI fix workflow when the same local prerequisite holds. |
 | Changes requested or unresolved review threads | Run the package comment sweep when the same local prerequisite holds. |
@@ -63,11 +67,17 @@ Each footer entry is one linked `PR #number` plus one plain-language status: `N
 
 `pi-pr-create` honors an existing configured push target. Without one, it pushes a captured OID to the local branch ref on `origin` and sets upstream.
 
-After a `/pr` create workflow settles, the extension waits for a refresh that finds an open current PR. It then ends the Herdr workspace label with one ` · PR #<number>` suffix.
+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.
+
+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.
+
+The creation workflow repeats destination, remote OID, PR, and configuration checks immediately before pushing. It pushes to the saved validated URL, not a mutable remote name. Every push uses the saved remote OID as an exact lease. Existing refs must also be ancestors of the captured local OID. A missing ref uses an empty lease as a create-only compare-and-swap.
+
+After a `/pr` create workflow settles, the extension waits for a refresh that finds an open current PR. It then prefixes the Herdr workspace label with `#<number> • `.
 
 Failed or empty discovery leaves one rename pending for a later refresh. Closed or merged historical matches do not trigger it.
 
-It removes every stale trailing PR suffix before adding the current one. This requires `HERDR_ENV=1` and a non-empty, trimmed `HERDR_WORKSPACE_ID`.
+It removes repeated leading `#<number> • ` prefixes and legacy trailing ` · PR #<number>` suffixes before adding one current prefix. The remaining workspace name must be non-empty. This requires `HERDR_ENV=1` and a non-empty, trimmed `HERDR_WORKSPACE_ID`.
 
 It renames only the workspace. Outside Herdr, it does nothing.
 
@@ -94,7 +104,9 @@ The comment sweep resolves its bundled helper and references from the installed
 
 ### Refresh
 
-The footer and widget load at session start. They refresh after local commits, PR creation, pushes, and each dispatched workflow settles. They also poll every 30 seconds. Polling updates presentation only and may be stale.
+The footer and widget load at session start. A directory outside a Git worktree stays silent and does not start polling. 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. They also refresh after any successful delegated task settles. Active Git worktrees poll every 30 seconds. Polling updates presentation only and may be stale.
 
 The create widget stays hidden until the local branch has a commit beyond its creation point. Any displayed widget clears as soon as `/pr` starts. A dispatched workflow keeps it hidden until the agent settles. A direct merge, no-action route, or failed command refreshes the widget when the handler finishes.
 
@@ -106,7 +118,7 @@ Presentation uses route priority, so draft appears before running CI. `/pr` read
 - It does not run `/done` or `/sweep`.
 - Polling does not auto-triage comments or start a workflow. The package comment sweep runs only when an explicit `/pr` selects it.
 - It does not enable auto-merge or add a merge queue.
-- It does not rebase the local branch, force-push, delete branches, or clean up worktrees.
+- 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.
 - 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.
 - Strict status checks in legacy branch protection or applicable repository rulesets require a base update.
@@ -115,6 +127,8 @@ Presentation uses route priority, so draft appears before running CI. `/pr` read
 - 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.
 - Before a comment-sweep push, it revalidates the configured destination, full PR identity, and local HEAD. It pushes the captured OID.
+- CI repair captures the failed-step log tail and runs one narrow local reproducer before editing.
 - An already-published local HEAD needs no second push.
 - Direct merge requires final confirmation and a fresh readiness check.
+- 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

@@ -45,7 +45,7 @@
       <line x1="704" y1="168" x2="704" y2="200" stroke="rgba(16,24,40,0.141)" stroke-width="1"/>
       <text x="148" y="192" fill="#4c5665" font-size="12" font-family="'Geist Mono', monospace" text-anchor="middle">1</text>
       <text x="200" y="176" fill="#4c5665" font-size="8" font-weight="500" font-family="'Geist Mono', monospace" letter-spacing="0.12em">CONDITION</text>
-      <text x="200" y="196" fill="#101828" font-size="12" font-weight="600" font-family="'Geist', sans-serif">No current PR</text>
+      <text x="200" y="196" fill="#101828" font-size="12" font-weight="600" font-family="'Geist', sans-serif">Safe PR absence</text>
       <text x="728" y="176" fill="#4c5665" font-size="8" font-weight="500" font-family="'Geist Mono', monospace" letter-spacing="0.12em">ROUTE</text>
       <text x="728" y="196" fill="#101828" font-size="12" font-weight="600" font-family="'Geist', sans-serif">Create pull request</text>
       <text x="1136" y="196" fill="#4c5665" font-size="8" font-family="'Geist Mono', monospace" text-anchor="end">pi-pr-create</text>

package/extensions/pr-command.ts

@@ -7,7 +7,9 @@ import {
 	selectMergeMethod,
 } from "./pr-merge.ts";
 import {
+	linkInferredPullRequest,
 	loadCurrentPullRequest,
+	samePullRequestSnapshot,
 	type CurrentPullRequest,
 } from "./pr-github.ts";
 import {
@@ -15,7 +17,7 @@ import {
 	type NextStep,
 } from "./pr-routing.ts";
 
-type WorkflowNextStep = Exclude<NextStep, "none" | "merge">;
+type WorkflowNextStep = Extract<NextStep, "create" | "update-branch" | "sweep" | "fix-ci">;
 
 const WORKFLOWS: Record<WorkflowNextStep, string> = {
 	create: "skill:pi-pr-create",
@@ -27,18 +29,28 @@ const WORKFLOWS: Record<WorkflowNextStep, string> = {
 type PrCommandPi = Pick<ExtensionAPI, "exec" | "getCommands" | "sendUserMessage">;
 export type PrCommandHandler = (args: string, ctx: ExtensionCommandContext) => Promise<NextStep>;
 
-function dispatchWorkflow(pi: PrCommandPi, ctx: ExtensionCommandContext, commandName: string): void {
+type PrCommandDependencies = {
+	loadCurrentPullRequest?: typeof loadCurrentPullRequest;
+	linkInferredPullRequest?: typeof linkInferredPullRequest;
+};
+
+function dispatchWorkflow(
+	pi: PrCommandPi,
+	ctx: ExtensionCommandContext,
+	commandName: string,
+	instructions: string,
+): void {
 	const command = pi.getCommands().find((candidate) =>
 		candidate.name === commandName &&
 		candidate.source === "skill" &&
-		candidate.sourceInfo.origin === "package",
+		candidate.sourceInfo.origin === "package"
 	);
 	if (!command) throw new Error(`${commandName} failed: bundled workflow is unavailable`);
 
 	const options = ctx.isIdle()
 		? { expandPromptTemplates: true }
 		: { deliverAs: "followUp" as const, expandPromptTemplates: true };
-	pi.sendUserMessage(`/${command.name}`, options);
+	pi.sendUserMessage(`/${command.name}${instructions ? ` ${instructions}` : ""}`, options);
 }
 
 function noActionNotification(pullRequest: CurrentPullRequest): { message: string; type: "info" | "warning" } {
@@ -88,14 +100,15 @@ async function mergePullRequest(
 	pi: PrCommandPi,
 	ctx: ExtensionCommandContext,
 	current: CurrentPullRequest,
-): Promise<void> {
+	load: typeof loadCurrentPullRequest,
+): Promise<boolean> {
 	if (!current.merge) throw new Error(`PR #${current.number} merge failed: merge capabilities are unavailable`);
 	const method = selectMergeMethod(current.merge);
 	const confirmed = await ctx.ui.confirm(
 		`Merge PR #${current.number} with ${method}?`,
 		`Merge PR #${current.number} using ${method}.`,
 	);
-	if (!confirmed) return;
+	if (!confirmed) return false;
 
 	await executeGitHubMerge({
 		exec: (command, args, options) => pi.exec(command, args, {
@@ -112,12 +125,15 @@ async function mergePullRequest(
 		allowedMergeMethods: current.merge.allowedMergeMethods,
 		viewerDefaultMergeMethod: current.merge.viewerDefaultMergeMethod,
 		revalidateReadiness: async (local) => {
-			const fresh = await loadCurrentPullRequest(pi, ctx, local);
-			if (!fresh) throw new Error(`PR #${current.number} merge cancelled: pull request is no longer current`);
+			const discovery = await load(pi, ctx, local);
+			if (discovery.kind !== "current") {
+				throw new Error(`PR #${current.number} merge cancelled: pull request is no longer current`);
+			}
+			const fresh = discovery.pullRequest;
 			if (!isSameConfirmedMerge(current, fresh)) {
 				throw new Error(`PR #${current.number} merge cancelled: confirmed pull request context changed`);
 			}
-			if (deriveNextStep(fresh) !== "merge") {
+			if (deriveNextStep(discovery) !== "merge") {
 				throw new Error(`PR #${fresh.number} merge cancelled: pull request is no longer merge-ready`);
 			}
 			if (!fresh.merge) throw new Error(`PR #${fresh.number} merge failed: merge capabilities are unavailable`);
@@ -127,28 +143,68 @@ async function mergePullRequest(
 			}
 		},
 	});
+	return true;
 }
 
-export function createPrCommandHandler(pi: PrCommandPi): PrCommandHandler {
-	return async (args, ctx) => {
-		if (args.trim()) throw new Error("/pr does not accept arguments");
+async function linkPullRequest(
+	pi: PrCommandPi,
+	ctx: ExtensionCommandContext,
+	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;
+
+	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);
+}
 
-		const current = await loadCurrentPullRequest(pi, ctx);
-		const nextStep = deriveNextStep(current);
+export function createPrCommandHandler(
+	pi: PrCommandPi,
+	dependencies: PrCommandDependencies = {},
+): PrCommandHandler {
+	const load = dependencies.loadCurrentPullRequest ?? loadCurrentPullRequest;
+	const link = dependencies.linkInferredPullRequest ?? linkInferredPullRequest;
+	return async (args, ctx) => {
+		const instructions = args.trim();
+		const discovery = await load(pi, ctx);
+		const nextStep = deriveNextStep(discovery);
+		if (instructions && !(nextStep in WORKFLOWS)) {
+			throw new Error("The current /pr route does not accept instructions");
+		}
+		if (discovery.kind === "inactive") return nextStep;
+		if (discovery.kind === "blocked") {
+			return nextStep;
+		}
 		if (nextStep === "none") {
-			if (current) {
-				const notification = noActionNotification(current);
+			if (discovery.kind === "current") {
+				const notification = noActionNotification(discovery.pullRequest);
 				ctx.ui.notify(notification.message, notification.type);
 			}
 			return nextStep;
 		}
-		if (nextStep === "merge") {
-			if (!current) throw new Error("/pr merge failed: pull request is unavailable");
-			await mergePullRequest(pi, ctx, current);
+		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;
 		}
+		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";
+		}
 
-		dispatchWorkflow(pi, ctx, WORKFLOWS[nextStep]);
+		if (!(nextStep in WORKFLOWS)) throw new Error(`/pr cannot dispatch route ${nextStep}`);
+		dispatchWorkflow(pi, ctx, WORKFLOWS[nextStep as WorkflowNextStep], instructions);
 		return nextStep;
 	};
 }