@henryqw/pi-pr 0.3.7 → 1.0.1

package/extensions/pr.ts

@@ -3,266 +3,124 @@ import {
 	type ExtensionAPI,
 	type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
-import { getCapabilities, hyperlink } from "@earendil-works/pi-tui";
+import { createPrCommandHandler } from "./pr-command.ts";
+import {
+	hasLocalCommit,
+	loadCurrentPullRequest,
+} from "./pr-github.ts";
+import {
+	formatPrFooter,
+	formatPrWidget,
+	projectPrDisplay,
+} from "./pr-ui.ts";
 
 const POLL_INTERVAL_MS = 30_000;
-const REVIEW_POLL_WINDOW_MS = 20 * 60_000;
-const PR_FIELDS = "id,number,url,headRefOid,updatedAt,state,isDraft,mergeable,reviewDecision,statusCheckRollup";
-const REVIEW_THREADS_QUERY = "query($id:ID!,$endCursor:String){node(id:$id){...on PullRequest{reviewThreads(first:100,after:$endCursor){nodes{isResolved}pageInfo{hasNextPage endCursor}}}}}";
+const UI_KEY = "pi-pr";
 const GH_PR_CREATE = /(?:^|[;&|]\s*|\n\s*)gh\s+pr\s+create(?=\s|$|[;&|])/;
+const GIT_COMMIT = /(?:^|[;&|]\s*|\n\s*)git\s+commit(?=\s|$|[;&|])/;
 const GIT_PUSH = /(?:^|[;&|]\s*|\n\s*)git\s+push(?=\s|$|[;&|])/;
-const CREATE_PR_SKILL_COMMAND = "skill:pi-pr-create";
-const FAILED_CHECK_STATES = new Set(["ACTION_REQUIRED", "CANCELLED", "ERROR", "FAILURE", "STALE", "STARTUP_FAILURE", "TIMED_OUT"]);
-const SUCCESSFUL_CHECK_STATES = new Set(["NEUTRAL", "SKIPPED", "SUCCESS"]);
-
-type CiStatus = "success" | "running" | "failure" | "none";
-type PullRequest = {
-	id: string;
-	number: number;
-	url: URL;
-	headRefOid: string;
-	updatedAt: string;
-	state: "OPEN" | "MERGED" | "CLOSED";
-	isDraft: boolean;
-	mergeable: string;
-	reviewDecision: string | null;
-	statusCheckRollup: unknown[];
-};
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function pullRequestUrl(value: unknown): URL | undefined {
-	if (typeof value !== "string" || !URL.canParse(value)) return undefined;
-	const url = new URL(value);
-	return url.protocol === "http:" || url.protocol === "https:" ? url : undefined;
-}
-
-export function parsePullRequest(value: unknown): PullRequest | undefined {
-	if (!isRecord(value)) return undefined;
-
-	const id = value.id;
-	const number = value.number;
-	const url = pullRequestUrl(value.url);
-	const headRefOid = value.headRefOid;
-	const updatedAt = value.updatedAt;
-	const state = value.state;
-	const isDraft = value.isDraft;
-	const mergeable = value.mergeable;
-	const reviewDecision = value.reviewDecision;
-	const statusCheckRollup = value.statusCheckRollup;
-	if (
-		typeof id !== "string" || !id ||
-		typeof number !== "number" || !Number.isSafeInteger(number) || number <= 0 || !url ||
-		typeof headRefOid !== "string" || !headRefOid ||
-		typeof updatedAt !== "string" || Number.isNaN(Date.parse(updatedAt)) ||
-		(state !== "MERGED" && state !== "CLOSED" && state !== "OPEN") ||
-		typeof isDraft !== "boolean" || typeof mergeable !== "string" ||
-		(reviewDecision !== null && typeof reviewDecision !== "string") ||
-		(statusCheckRollup !== null && !Array.isArray(statusCheckRollup))
-	) return undefined;
-
-	return { id, number, url, headRefOid, updatedAt, state, isDraft, mergeable, reviewDecision, statusCheckRollup: statusCheckRollup ?? [] };
-}
-
-function parseUnresolvedReviewCount(value: string): number {
-	if (!value.trim()) throw new Error("Read review comments failed: invalid GitHub CLI output");
-	const pages = value.trim().split(/\s+/).map(Number);
-	const count = pages.reduce((total, page) => total + page, 0);
-	if (pages.some((page) => !Number.isSafeInteger(page) || page < 0) || !Number.isSafeInteger(count)) {
-		throw new Error("Read review comments failed: invalid GitHub CLI output");
-	}
-	return count;
-}
-
-function parseRepositoryName(json: string): string {
-	let value: unknown;
-	try {
-		value = JSON.parse(json);
-	} catch {
-		throw new Error("Read push repository failed: invalid GitHub CLI output");
-	}
-	const nameWithOwner = isRecord(value) ? value.nameWithOwner : undefined;
-	if (typeof nameWithOwner !== "string" || !nameWithOwner) {
-		throw new Error("Read push repository failed: invalid GitHub CLI output");
-	}
-	return nameWithOwner.toLowerCase();
-}
 
-function parseOpenPullRequestNumbers(json: string, headRepository: string): number[] {
-	let values: unknown;
-	try {
-		values = JSON.parse(json);
-	} catch {
-		throw new Error("Find pull requests failed: invalid GitHub CLI output");
-	}
-	if (!Array.isArray(values)) throw new Error("Find pull requests failed: invalid GitHub CLI output");
-	return values.flatMap((value) => {
-		const number = isRecord(value) ? value.number : undefined;
-		const repository = isRecord(value) ? value.headRepository : undefined;
-		if (repository === null) return [];
-		const nameWithOwner = isRecord(repository) ? repository.nameWithOwner : undefined;
-		if (
-			typeof number !== "number" || !Number.isSafeInteger(number) || number <= 0 ||
-			typeof nameWithOwner !== "string" || !nameWithOwner
-		) throw new Error("Find pull requests failed: invalid GitHub CLI output");
-		return nameWithOwner.toLowerCase() === headRepository ? [number] : [];
-	});
-}
-
-function ciStatus(rollup: unknown[]): CiStatus {
-	if (!rollup.length) return "none";
-	let running = false;
-	for (const check of rollup) {
-		const record = isRecord(check) ? check : undefined;
-		const value = record?.conclusion ?? record?.state ?? record?.status;
-		const state = typeof value === "string" ? value.toUpperCase() : undefined;
-		if (state && FAILED_CHECK_STATES.has(state)) return "failure";
-		if (!state || !SUCCESSFUL_CHECK_STATES.has(state)) running = true;
-	}
-	return running ? "running" : "success";
-}
-
-type Status = {
-	text: string;
-	color: "accent" | "warning" | "success" | "error" | "dim";
+type PullRequestExtensionDependencies = {
+	loadCurrentPullRequest?: typeof loadCurrentPullRequest;
+	hasLocalCommit?: typeof hasLocalCommit;
+	createPrCommandHandler?: typeof createPrCommandHandler;
 };
 
-function statusFor(pullRequest: PullRequest, ci: CiStatus): Status {
-	if (pullRequest.state === "MERGED") return { text: "merged", color: "success" };
-	if (pullRequest.state === "CLOSED") return { text: "closed", color: "dim" };
-	if (pullRequest.mergeable === "CONFLICTING") return { text: "merge conflict", color: "error" };
-	if (pullRequest.reviewDecision === "CHANGES_REQUESTED") return { text: "changes requested", color: "error" };
-	if (ci === "failure") return { text: "CI failed", color: "error" };
-	if (ci === "running") return { text: "CI running", color: "warning" };
-	if (pullRequest.isDraft) return { text: "draft", color: "warning" };
-	if (pullRequest.reviewDecision === "APPROVED") return { text: "approved", color: "success" };
-	return { text: "open", color: "accent" };
-}
-
-export function formatPullRequest(pullRequest: PullRequest, theme: ExtensionContext["ui"]["theme"], unresolved = 0): string {
-	const prText = theme.fg("text", `PR #${pullRequest.number}`);
-	const link = getCapabilities().hyperlinks ? hyperlink(prText, pullRequest.url.href) : prText;
-	const status = unresolved > 0
-		? { text: `${unresolved} unresolved`, color: "warning" as const }
-		: statusFor(pullRequest, ciStatus(pullRequest.statusCheckRollup));
-	return `${link} · ${theme.fg(status.color, status.text)}`;
-}
-
-export default function pullRequestExtension(pi: ExtensionAPI): void {
+export default function pullRequestExtension(
+	pi: ExtensionAPI,
+	dependencies: PullRequestExtensionDependencies = {},
+): void {
+	const load = dependencies.loadCurrentPullRequest ?? loadCurrentPullRequest;
+	const detectLocalCommit = dependencies.hasLocalCommit ?? hasLocalCommit;
+	const createCommandHandler = dependencies.createPrCommandHandler ?? createPrCommandHandler;
 	let context: ExtensionContext | undefined;
 	let timer: ReturnType<typeof setInterval> | undefined;
 	let active: AbortController | undefined;
 	let queued = false;
-	let reviewState: { id: string; unresolved: number } | undefined;
-	let reviewWindow: { id: string; headRefOid: string; updatedAt: string; until: number } | undefined;
+	let refreshFailureReported = false;
+
+	const render = (
+		ctx: ExtensionContext,
+		pullRequest: Awaited<ReturnType<typeof loadCurrentPullRequest>>,
+		localCommit: boolean,
+	): void => {
+		const display = projectPrDisplay(pullRequest, localCommit);
+		const footer = pullRequest === null ? undefined : formatPrFooter(display, ctx.ui.theme);
+		if (pullRequest !== null && footer === undefined) {
+			throw new Error("Current pull request display is missing a footer");
+		}
+		const widget = formatPrWidget(display);
+		ctx.ui.setStatus(UI_KEY, footer);
+		ctx.ui.setWidget(UI_KEY, widget === undefined ? undefined : [widget]);
+	};
 
-	const stop = () => {
+	const stop = (): void => {
 		context = undefined;
 		queued = false;
-		reviewState = undefined;
-		reviewWindow = undefined;
+		refreshFailureReported = false;
 		if (timer !== undefined) clearInterval(timer);
 		timer = undefined;
 		active?.abort();
 		active = undefined;
 	};
 
-	const refresh = async (afterActive = false): Promise<void> => {
+	const reportRefreshFailure = (error: unknown): void => {
+		const ctx = context;
+		if (!ctx || refreshFailureReported) return;
+		refreshFailureReported = true;
+		try {
+			const message = error instanceof Error ? error.message : String(error);
+			ctx.ui.notify(`PR status refresh failed: ${message.slice(0, 500)}`, "error");
+		} catch (reportError) {
+			console.error("PR status refresh failed and could not be reported", error, reportError);
+		}
+	};
+
+	const refresh = async (): Promise<void> => {
 		const ctx = context;
 		if (!ctx) return;
 		if (active) {
-			queued ||= afterActive;
+			queued = true;
 			return;
 		}
 
 		const controller = new AbortController();
+		const loadContext = { cwd: ctx.cwd, signal: controller.signal };
 		active = controller;
 		try {
-			const result = await pi.exec(
-				"gh",
-				["pr", "view", "--json", PR_FIELDS],
-				{ cwd: ctx.cwd, signal: controller.signal, timeout: 10_000 },
-			);
-			if (controller.signal.aborted || context !== ctx) return;
-			if (result.code !== 0) {
-				ctx.ui.setStatus("pi-pr", undefined);
-				return;
-			}
-
-			const pullRequest = parsePullRequest(JSON.parse(result.stdout));
-			if (!pullRequest) {
-				reviewState = undefined;
-				reviewWindow = undefined;
-				ctx.ui.setStatus("pi-pr", undefined);
-				return;
-			}
-			if (pullRequest.state === "MERGED" || pullRequest.state === "CLOSED") {
-				reviewState = undefined;
-				reviewWindow = undefined;
-				ctx.ui.setStatus("pi-pr", formatPullRequest(pullRequest, ctx.ui.theme));
-				return;
-			}
-			const changedPullRequest = reviewWindow?.id !== pullRequest.id;
-			if (
-				changedPullRequest ||
-				reviewWindow?.headRefOid !== pullRequest.headRefOid ||
-				reviewWindow?.updatedAt !== pullRequest.updatedAt
-			) {
-				if (changedPullRequest) reviewState = undefined;
-				reviewWindow = {
-					id: pullRequest.id,
-					headRefOid: pullRequest.headRefOid,
-					updatedAt: pullRequest.updatedAt,
-					until: Date.now() + REVIEW_POLL_WINDOW_MS,
-				};
-			}
-			ctx.ui.setStatus("pi-pr", formatPullRequest(
-				pullRequest,
-				ctx.ui.theme,
-				reviewState?.id === pullRequest.id ? reviewState.unresolved : 0,
-			));
-			if (Date.now() >= reviewWindow.until) return;
-
+			let pullRequest: Awaited<ReturnType<typeof loadCurrentPullRequest>>;
+			let localCommit = false;
 			try {
-				const reviews = await pi.exec(
-					"gh",
-					[
-						"api", "graphql", "--hostname", pullRequest.url.hostname, "--paginate",
-						"-f", `query=${REVIEW_THREADS_QUERY}`, "-F", `id=${pullRequest.id}`,
-						"--jq", "[.data.node.reviewThreads.nodes[] | select(.isResolved == false)] | length",
-					],
-					{ cwd: ctx.cwd, signal: controller.signal, timeout: 10_000 },
-				);
-				if (controller.signal.aborted || context !== ctx || reviews.code !== 0) return;
-				const unresolved = parseUnresolvedReviewCount(reviews.stdout);
-				if (unresolved > 0 && (reviewState?.id !== pullRequest.id || unresolved > reviewState.unresolved)) {
-					ctx.ui.notify(`PR #${pullRequest.number} has ${unresolved} unresolved review thread${unresolved === 1 ? "" : "s"}`, "warning");
-				}
-				reviewState = { id: pullRequest.id, unresolved };
-				ctx.ui.setStatus("pi-pr", formatPullRequest(pullRequest, ctx.ui.theme, unresolved));
-			} catch {
-				// Keep known PR status when review lookup fails.
+				pullRequest = await load(pi, loadContext);
+				if (pullRequest === null) localCommit = await detectLocalCommit(pi, loadContext);
+			} catch (error) {
+				// Keep the last known display when lookup is unavailable.
+				if (!controller.signal.aborted && context === ctx) reportRefreshFailure(error);
+				return;
 			}
-		} catch {
-			if (!controller.signal.aborted && context === ctx) ctx.ui.setStatus("pi-pr", undefined);
+			if (controller.signal.aborted || context !== ctx) return;
+			render(ctx, pullRequest, localCommit);
+			refreshFailureReported = false;
 		} finally {
 			if (active !== controller) return;
 			active = undefined;
 			if (queued) {
 				queued = false;
-				await refresh();
+				refreshInBackground();
 			}
 		}
 	};
 
+	const refreshInBackground = (): void => {
+		void refresh().catch(reportRefreshFailure);
+	};
+
 	pi.on("session_start", async (_event, ctx) => {
-		if (!ctx.hasUI) return;
 		stop();
+		if (!ctx.hasUI) return;
 		context = ctx;
 		await refresh();
-		if (context === ctx) timer = setInterval(() => { void refresh(); }, POLL_INTERVAL_MS);
+		if (context === ctx) timer = setInterval(refreshInBackground, POLL_INTERVAL_MS);
 	});
 
 	pi.on("session_shutdown", stop);
@@ -270,55 +128,20 @@ export default function pullRequestExtension(pi: ExtensionAPI): void {
 	pi.on("tool_result", async (event, ctx) => {
 		if (!ctx.hasUI || event.isError || !isBashToolResult(event)) return;
 		const command = event.input.command;
-		if (typeof command === "string" && (GH_PR_CREATE.test(command) || GIT_PUSH.test(command))) await refresh(true);
+		if (typeof command === "string" && (GH_PR_CREATE.test(command) || GIT_COMMIT.test(command) || GIT_PUSH.test(command))) {
+			await refresh().catch(reportRefreshFailure);
+		}
 	});
 
+	const commandHandler = createCommandHandler(pi);
 	pi.registerCommand("pr", {
-		description: "Open current branch pull request, or run creation workflow when absent",
-		handler: async (_args, ctx) => {
+		description: "Run the current branch pull request next step",
+		handler: async (args, ctx) => {
 			if (!ctx.hasUI) return;
-			const execute = async (action: string, command: string, args: string[]) => {
-				let result;
-				try {
-					result = await pi.exec(command, args, { cwd: ctx.cwd, signal: ctx.signal, timeout: 10_000 });
-				} catch (error) {
-					throw new Error(`${action} failed: ${error instanceof Error ? error.message : String(error)}`);
-				}
-				if (result.code !== 0) {
-					const detail = result.stderr.trim() || result.stdout.trim() || (result.killed ? "command was cancelled" : `exit code ${result.code}`);
-					throw new Error(`${action} failed: ${detail}`);
-				}
-				return result;
-			};
-
 			try {
-				const branch = (await execute("Read current branch", "git", ["branch", "--show-current"])).stdout.trim();
-				if (!branch) throw new Error("Create pull request failed: current checkout has no branch");
-				const remote = (await execute("Read push remote", "git", ["remote", "get-url", "--push", "origin"])).stdout.trim();
-				if (!remote) throw new Error("Read push remote failed: origin has no push URL");
-				const repository = await execute("Read push repository", "gh", ["repo", "view", remote, "--json", "nameWithOwner"]);
-				const listed = await execute("Find pull requests", "gh", [
-					"pr", "list", "--head", branch, "--state", "open", "--limit", "100", "--json", "number,headRepository",
-				]);
-				const numbers = parseOpenPullRequestNumbers(listed.stdout, parseRepositoryName(repository.stdout));
-				if (numbers.length > 1) throw new Error("Open pull request failed: multiple open pull requests found for current branch");
-
-				if (numbers.length === 1) {
-					await execute("Open pull request", "gh", ["pr", "view", String(numbers[0]), "--web"]);
-					return;
-				}
-
-				const workflow = pi.getCommands().find((command) =>
-					command.name === CREATE_PR_SKILL_COMMAND && command.source === "skill" && command.sourceInfo.origin === "package",
-				);
-				if (!workflow) throw new Error("Create pull request failed: bundled workflow is unavailable");
-				if (ctx.isIdle()) {
-					pi.sendUserMessage(`/${CREATE_PR_SKILL_COMMAND}`, { expandPromptTemplates: true });
-				} else {
-					pi.sendUserMessage(`/${CREATE_PR_SKILL_COMMAND}`, { deliverAs: "followUp", expandPromptTemplates: true });
-				}
+				await commandHandler(args, ctx);
 			} finally {
-				void refresh(true);
+				refreshInBackground();
 			}
 		},
 	});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@henryqw/pi-pr",
-  "version": "0.3.7",
-  "description": "Show the current branch pull request status in the Pi footer.",
+  "version": "1.0.1",
+  "description": "Run /pr to automatically choose the current pull request's next safe lifecycle step: create, update, address feedback, fix CI, or merge when ready.",
   "keywords": [
     "pi-package",
     "pi",
@@ -16,12 +16,13 @@
   "license": "MIT",
   "files": [
     "LICENSE",
+    "docs/pr-routing.svg",
     "extensions",
     "skills",
     "README.md"
   ],
   "scripts": {
-    "test": "node --test test/*.test.ts",
+    "test": "node --test test/*.test.ts && node skills/pi-pr-comment-sweep/scripts/pr-feedback.mjs self-test",
     "typecheck": "tsc --noEmit --allowImportingTsExtensions --target ES2022 --module NodeNext --moduleResolution NodeNext --skipLibCheck extensions/*.ts test/*.test.ts",
     "pack:check": "npm pack --dry-run"
   },

package/skills/pi-pr-comment-sweep/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: pi-pr-comment-sweep
+description: Fetch GitHub pull request comments with gh, assess actionable feedback, then apply, validate, commit, push, and resolve scoped fixes without approval pauses. Use when asked to sweep, address, or fix PR comments end to end.
+---
+
+# PR Comment Sweep
+
+Address actionable feedback on current-branch PR or supplied PR number/URL.
+Run standalone; never invoke, defer to, or modify Shipyard.
+
+1. Resolve `<skill>` as the absolute directory containing the effective
+   `SKILL.md` loaded by Pi. It is a placeholder to substitute, never a literal
+   path; use it for bundled scripts and references. Set optional `$PR` and
+   require a clean tracked tree. On resume, dirt, or head mismatch, read
+   [Sweep recovery](<skill>/references/recovery.md>) and stop unless its
+   checkpoint or adoption rules pass. For a fresh sweep:
+
+   ```bash
+   SNAPSHOT=$(mktemp)
+   if [ -n "${PR:-}" ]; then
+     node "<skill>/scripts/pr-feedback.mjs" target --pr "$PR"
+     node "<skill>/scripts/pr-feedback.mjs" fetch --pr "$PR" --out "$SNAPSHOT"
+   else
+     node "<skill>/scripts/pr-feedback.mjs" target
+     node "<skill>/scripts/pr-feedback.mjs" fetch --out "$SNAPSHOT"
+   fi
+   PR=$(node "<skill>/scripts/pr-feedback.mjs" snapshot-url --snapshot "$SNAPSHOT")
+   ```
+
+   Target verification requires authenticated `gh`, an open PR, exact local/PR
+   head, and one matching configured push target. Inspect base, full diff, and raw
+   snapshot. Maintain recovery reference's one-line checkpoint after each
+   phase.
+2. Initial fetch prints all conversation comments, review bodies, unresolved
+   current/outdated threads, replies, and status. Later fetches into a copied
+   snapshot print additions, edits, and state changes only; raw JSON remains complete.
+   Follow [Thread triage](<skill>/references/thread-triage.md>) and ledger every item as
+   `actionable`, `non-actionable`, or `blocked`, with evidence, smallest fix,
+   and regression. Never reconstruct GraphQL pagination.
+3. Verify feedback against code, callers, tests, and PR intent. For SDK/framework
+   claims, inspect installed types and runtime caller; missing public capability
+   is `blocked`, never a private-API or cast workaround. Invocation authorizes
+   scoped edits, commits, push, and addressed-thread resolution. Stop only for
+   unclear behavior, conflicting feedback, material product choice, or scope
+   expansion.
+4. Inspect resulting diff and run smallest relevant non-destructive validation.
+   Stage only inspected paths; stop on failed or unavailable required validation
+   unless user accepts risk. Never change secrets or unrelated work. Never
+   hand-edit generated files: change source, run canonical generator for required
+   tracked artifacts, then inspect both. Never wait or poll checks.
+5. Commit accepted fixes with scoped Conventional Commit message(s). With no
+   fixes, do not commit or push. After clean-tree validation, run
+   `node "<skill>/scripts/pr-feedback.mjs" push --snapshot "$SNAPSHOT"`. The
+   helper revalidates the configured destination, PR identity, and local HEAD.
+   It pushes the captured OID once with no fallback. Then capture the swept head:
+
+   ```bash
+   EXPECTED_HEAD=$(git rev-parse --verify 'HEAD^{commit}')
+   ```
+6. Copy baseline before final fetch:
+
+   ```bash
+   FINAL_SNAPSHOT=$(mktemp)
+   cp "$SNAPSHOT" "$FINAL_SNAPSHOT"
+   node "<skill>/scripts/pr-feedback.mjs" fetch --pr "$PR" --out "$FINAL_SNAPSHOT"
+   ```
+
+   Assess delta, then resolve all addressed IDs in one command, repeating flag:
+   `node "<skill>/scripts/pr-feedback.mjs" resolve --pr "$PR" --expected-head
+   "$EXPECTED_HEAD" --thread "$ID1" --thread "$ID2"`. Before each resolution,
+   the helper re-resolves the checkout's configured push target and exact open PR.
+   Never resolve non-actionable or blocked threads. Re-fetch once into `FINAL_SNAPSHOT`, assess
+   late delta, batch any newly addressed IDs, then run
+   `node "<skill>/scripts/pr-feedback.mjs" checks --pr "$PR" --expected-head
+   "$EXPECTED_HEAD"` once. Read-only
+   transient retries are allowed; mutation retries and polling are not. Do not
+   reply unless explicitly requested.
+7. Report `PR | actioned | resolved IDs | skipped IDs | pending IDs | checks |
+   commits | push | blockers`.

package/skills/pi-pr-comment-sweep/references/recovery.md

@@ -0,0 +1,49 @@
+# Sweep Recovery
+
+Read only for resume or PR-head mismatch.
+
+## Checkpoint
+
+Only ignored `.context/progress.md` may change under `.context/`. Keep one JSON
+line under `## PR comment sweep`; never stage it:
+
+```json
+{"workflow":"pi-pr-comment-sweep","pr":"URL","snapshot":"/tmp/file","final_snapshot":null,"head":"SHA","phase":"triage","owned":[],"ledger":{},"checks":[],"commit":null,"pushed":false,"resolved":[]}
+```
+
+Use phases `triage`, `editing`, `validated`, `committed`, `pushed`, or `resolved`.
+Update after each phase; keep repository-relative owned paths, thread verdicts in
+`ledger`, exact validation results, commit SHA, push state, and resolved IDs.
+
+Resume only when workflow and PR match, snapshot exists and names that PR, local
+`HEAD` equals `head`, and tracked dirty paths equal `owned`. Skip completed
+phases and continue with next one. Stop on missing, malformed, or conflicting
+state; never absorb unknown changes. Commands requiring a clean tree remain
+blocked until tracked work is committed or otherwise restored by user.
+
+## Adopt PR head
+
+Only exact user words **“Adopt PR head”** authorize this path. Inspect
+`gh pr view "$PR" --json url,headRepository,headRefName,headRefOid`. Validate the
+PR URL, full head OID, and ref. Choose exactly one push URL whose normalized
+GitHub host/owner/repository matches `headRepository`. Run:
+
+```bash
+git fetch --no-write-fetch-head --no-tags "$PUSH_URL" "$PR_HEAD_SHA"
+git cat-file -e "$PR_HEAD_SHA^{commit}"
+git log --oneline HEAD.."$PR_HEAD_SHA"
+git diff --stat HEAD.."$PR_HEAD_SHA"
+git merge-base --is-ancestor HEAD "$PR_HEAD_SHA"
+STATUS=$(git status --porcelain=v1 --untracked-files=all) || exit 1
+test -z "$STATUS" || exit 1
+for STATE in MERGE_HEAD rebase-merge rebase-apply CHERRY_PICK_HEAD REVERT_HEAD sequencer; do
+  STATE_PATH=$(git rev-parse --git-path "$STATE") || exit 1
+  test -n "$STATE_PATH" && test ! -e "$STATE_PATH" || exit 1
+done
+git merge --ff-only "$PR_HEAD_SHA"
+```
+
+Run the clean-tree and Git-operation checks immediately before the fast-forward.
+Stop on an absent object, divergence, dirty tracked or untracked state, an active
+Git operation, or an ambiguous push URL. Never stash, reset, or clean. Re-run
+target verification and initial fetch after fast-forward.

package/skills/pi-pr-comment-sweep/references/thread-triage.md

@@ -0,0 +1,8 @@
+# Thread Triage
+
+- Resolved: ignore.
+- Outdated: inspect current diff and source lines; re-anchor before deciding relevance.
+- Open/current: record `actionable`, `non-actionable`, or `blocked` with evidence,
+  smallest fix, and regression check.
+- Resolve only an addressed actionable thread after verified fix and head check.
+  Never resolve non-actionable or blocked threads; report their IDs as pending.