dsh-git-badge 0.14.1 → 0.15.0

package/CHANGELOG.md

@@ -10,6 +10,130 @@ npm. 0.6.0 is the first release recorded here.
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-09-15
+
+### Changed
+
+- **Internal polish, no behaviour change:** the `detail=1` hover reads run in
+  one parallel batch (hover latency is the longest call, not the sum of seven
+  serial git spawns), the path-shortening and remote-URL conversion moved into
+  named helpers, and the three hover bodies share one row builder.
+
+### Added
+
+- **Merge-blocker phrasing in the branch hover.** A `BLOCKED` verdict says why
+  — `blocked: review required`, `blocked: checks failing`, `blocked: draft` —
+  combined with the ahead/behind-main counts when both apply, so a dead-end
+  word names the next action. CLEAN stays silent: the action row already
+  offers `/gh merge`.
+
+- **Staged names in the count's hover.** The stacked column gains a `staged:`
+  section above `unstaged` and `untracked`, completing the ✎n story — and
+  pairing with `/gh commit` when work is already staged.
+
+- **Two new `gh` verbs:** `/gh stash pop` (shows the top stash's subject,
+  confirms, and on conflict reports that the stash was NOT dropped) and
+  `/gh checkout <branch>` (states what is dirty and confirms when work would
+  carry over).
+
+### Added
+
+- **Unstaged names join the count's hover.** The ✎n tooltip stacks one column
+  with two sub-headers — `unstaged` (tracked, edited files; valid regardless of
+  the collapsed-untracked retry) above `untracked` — each capped at 20 with the
+  same last-two-segments shortening and "… and k more" arithmetic. The picker
+  question "what are these?" now answers for both halves of the count.
+
+- **The branch hover gains a merge-state row.** `main: N ahead, M behind`
+  against `origin/main` — in words, deliberately distinct from the upstream
+  sync arrows: "3 ahead, 0 behind" reads as "this is the PR's content";
+  "0 ahead, 5 behind" as "stale, rebase first". Absent entirely when in sync.
+
+- **The branch hover's commit list is signed and base-relative.** One mixed
+  list from `main...HEAD`: entries marked `+` are only on this branch (the
+  PR's content), `\u2212` only on main (what a rebase/merge brings in) — git's
+  own left-right verdict mapped onto the diff convention, sign before the
+  hash. Capped at 10 with the total from the same base; without a default
+  branch it degrades to the plain last 10, unsigned.
+
+- **A commits hover on the branch name.** Hovering the branch lists the
+  COMMITS THIS BRANCH ADDS (`log <upstream>..HEAD`) — hash + subject + age,
+  capped at 10 with the total from one `rev-list --count` so "… and k more" is
+  arithmetic — not the card's last-three-overall list. Hover-gated with the
+  rest of `detail=1`; absent when the branch adds nothing (no tooltip rather
+  than an empty one) and when there is no upstream (the publish suggestion
+  covers that case).
+
+### Changed
+
+- **The hover surfaces have one information architecture.** The branch name's
+  hover is the branch's LINEAGE and always renders: `upstream`, `sync` (in
+  words, "in sync with upstream" when clean), the commits this branch adds,
+  and the pull request when one exists. The status card loses its branch,
+  upstream, sync and pull-request rows — the branch name is the chip's own
+  text, and lineage facts belong beside the lineage surface — keeping action,
+  files, operation, worktree, checkout and stash.
+
+- **The status card no longer repeats what the other hovers own.** Its commits
+  row and untracked-names row are gone — commit listings live on the branch
+  name's hover, untracked names on the count's hover, and the server stopped
+  fetching the unused last-three-commits on every detail read. The card keeps
+  action, branch, upstream, sync, files, operation, PR, worktree, checkout,
+  stash.
+
+### Added
+
+- **A names-only hover on the ✎n count.** The count gets its own tooltip —
+  just the untracked list (one name per line, "… and k more"), no action row —
+  while the full card stays on the status mark. It shares the mark's lazy
+  detail fetch (resting on either triggers it once) and degrades to a plain
+  count without the Tooltip primitive or when nothing is untracked.
+
+### Added
+
+- **Untracked file names in the hover card.** The `✎n` count becomes
+  answerable — "what did I create here?" — with a `untracked:` row listing the
+  names, hover-gated with the rest of `detail=1` (computed when the card opens,
+  refreshed by the existing SSE invalidation; no per-edit cost). Posture: the
+  plugin's never-display-a-path rule is relaxed by an inch, not a mile —
+  RELATIVE names only, truncated to the last two path segments, capped at 20
+  with the total carried separately so "… and k more" is arithmetic, not a
+  guess. Collapsed-count payloads (huge untracked trees) omit the field
+  entirely rather than under-report with directory names.
+
+### Changed
+
+- **A smarter next-action state machine.** `nextStep` now ranks rule
+  candidates by category instead of first-match, and two new rules join the
+  table: a **diverged** branch (ahead AND behind) suggests `/gh sync` —
+  rebase-then-push, with the force-push confirmed by you — instead of a plain
+  pull that would discard the local-commit context; and a **merge-ready** PR
+  (GitHub's own `mergeState: CLEAN`, or checks passing + review approved)
+  suggests `/gh merge <n>` — the endgame action the old table could never see.
+- **Configurable ranking via `/gh order`.** The category order is one line of
+  JSON at `~/.dsh/git-badge-next.json`
+  (`{"order": ["operation","unmerged","sync","publish","merge","commit","checks"]}`);
+  any subset in any order, unlisted categories rank after in default order.
+  The `gh` skill gains the `sync`, `merge <n>` and `order` verbs — say
+  "/gh order commit first" and the agent edits the file. The server's ranked
+  `next` now carries the skill `args` directly, so the hover card and the (+)
+  picker lead with exactly what the server decided and only add secondary
+  actions around it.
+
+## [0.14.1] - 2026-09-15
+
+- **Skill alignment:** the `gh` skill gains an explicit handoff — one verb per
+  invocation is its whole job; the multi-step PR lifecycle (review, merge,
+  verify, cleanup) belongs to the `gh-pr` skill. The `gh-pr` skill states the
+  mirror scope: one-shot verbs are `gh`'s, lifecycle is its own. The catalog
+  stays global-only; repo conventions stay in `AGENTS.md`.
+
+- **The hover card is 33% wider** (360px → 480px) and its `action:` row now
+  carries a trailing what-comment in git-comment convention — e.g.
+  `action: /gh push  # push local commits to the remote` — so the row says
+  what the invocation does, not just which invocation it is. The picker in the
+  (+) menu shares the same descriptions.
+
 ## [0.14.1] - 2026-09-15
 
 ### Changed

package/lib/client.js

@@ -233,41 +233,42 @@ window.__ModuleLoader__.load({
 
 		/**
 		 * The /gh picker's sub-actions — the skill invocations the checkout
-		 * justifies, most urgent first. Same ranking the server's nextStep uses,
-		 * but spoken in skill arguments; the generic "next" entry is skipped when
-		 * a specific rule already names the same situation (its why would be
-		 * identical, and two rows for one fact is noise).
+		 * justifies, most urgent first. The server's `next` (the ranked top rule,
+		 * already carrying args/why/what) always leads; the client adds the other
+		 * justified actions as secondary entries, mirroring the server's category
+		 * rules but never re-deciding the winner.
 		 */
 		function ghSkillActions(info) {
 			if (info === void 0 || info === null || info.git !== true) return [];
 			const subs = [];
 			const seen = new Set();
-			const add = (args, why) => {
-				if (seen.has(args)) return;
+			const add = (args, why, what) => {
+				if (args === void 0 || args === null || args === "" || seen.has(args)) return;
 				seen.add(args);
-				subs.push({ args, why });
+				subs.push({ args, why, what });
 			};
+			const next = info.next;
+			if (next !== void 0 && next !== null) add(next.args, next.why, next.what);
 			const ahead = info.ahead || 0;
 			const behind = info.behind || 0;
 			const staged = info.stagedFiles || 0;
 			const unstaged = info.unstagedFiles || 0;
 			const untracked = info.untrackedFiles || 0;
-			if (behind > 0) add("pull", behind + " behind " + (info.upstream ?? "upstream"));
-			if (ahead > 0) add("push", ahead + " ahead of " + (info.upstream ?? "upstream"));
-			if (staged > 0) add("commit", staged + " staged");
-			if (unstaged > 0) add("commit", unstaged + " unstaged");
-			if (unstaged === 0 && untracked > 0) add("commit", untracked + " untracked");
+			if (behind > 0 && ahead > 0) {
+				add("sync", ahead + " ahead, " + behind + " behind — diverged", "rebase your commits onto upstream and push (asks before any force)");
+			} else {
+				if (behind > 0) add("pull", behind + " behind " + (info.upstream ?? "upstream"), "update this branch from upstream");
+				if (ahead > 0) add("push", ahead + " ahead of " + (info.upstream ?? "upstream"), "push local commits to the remote");
+			}
+			if (staged > 0) add("commit", staged + " staged", "commit the staged changes");
+			if (unstaged > 0) add("commit", unstaged + " unstaged", "stage and commit the working changes");
+			if (unstaged === 0 && untracked > 0) add("commit", untracked + " untracked", "stage the new files and commit them");
 			const pr = info.pr;
 			if (pr !== void 0 && pr !== null && pr.number !== void 0) {
-				if (pr.state === "failing") add("checks " + pr.number, "checks failing on #" + pr.number);
-				add("pr view " + pr.number, "open pull request #" + pr.number);
+				if (pr.state === "failing") add("checks " + pr.number, "checks failing on #" + pr.number, "watch the CI checks on pull request " + pr.number);
+				add("pr view " + pr.number, "open pull request #" + pr.number, "show pull request " + pr.number + " on GitHub");
 			} else if (ahead === 0 && behind === 0 && info.upstream !== void 0 && staged + unstaged + untracked === 0) {
-				add("pr", "branch is pushed and has no pull request");
-			}
-			const next = info.next;
-			if (next !== void 0 && next !== null && typeof next.command === "string"
-				&& !subs.some((entry) => entry.why === next.why)) {
-				add("next", next.why);
+				add("pr", "branch is pushed and has no pull request", "open a pull request for this branch");
 			}
 			return subs.slice(0, 6);
 		}
@@ -658,12 +659,178 @@ window.__ModuleLoader__.load({
 			gap: "4px",
 			fontSize: "12px",
 			lineHeight: "18px",
-			maxWidth: "340px"
+			// Auto-width: the card fits its widest row instead of a guessed
+			// constant, capped at 600px. The Tooltip's maxWidth must stay >= the
+			// cap or IT becomes the clamp.
+			width: "max-content",
+			maxWidth: "600px"
 		};
+		/**
+		 * The ✎n count's own hover body — the changed-file lists and NOTHING
+		 * else: the full card stays on the status mark, and this tooltip answers
+		 * the one question the count poses ("what are these?"). One stacked
+		 * column with sub-headers: UNSTAGED (tracked, edited — valid regardless
+		 * of the collapsed untracked retry) then UNTRACKED. Reads the same lazy
+		 * detail payload the mark's card uses; no tooltip at all when neither
+		 * list has names (the count itself is absent on a clean tree, so an
+		 * empty list is rare — a mid-fetch hover shows it plain until the
+		 * response lands).
+		 */
+		function CountNames({ info }) {
+			const sections = [
+				{
+					label: "staged",
+					names: info?.stagedNames,
+					total: info?.stagedNamesTotal
+				},
+				{
+					label: "unstaged",
+					names: info?.unstagedNames,
+					total: info?.unstagedNamesTotal
+				},
+				{
+					label: "untracked",
+					names: info?.untrackedNames,
+					total: info?.untrackedNamesTotal
+				}
+			].filter((section) => Array.isArray(section.names) && section.names.length > 0);
+			if (sections.length === 0) {
+				return react_jsx_runtime.jsx("span", { style: CARD_CONTAINER, children: "no changed files" });
+			}
+			return react_jsx_runtime.jsxs("div", { style: CARD_CONTAINER, children:
+				sections.map((section) => react_jsx_runtime.jsxs("div", { style: CARD_ROW, children: [
+					react_jsx_runtime.jsx("span", { style: CARD_LABEL, children: section.label }),
+					react_jsx_runtime.jsx("span", {
+						style: { ...CARD_VALUE, display: "flex", flexDirection: "column", gap: "2px" },
+						children: [
+							...section.names.map((name) => react_jsx_runtime.jsx("span", { children: name }, section.label + name)),
+							(typeof section.total === "number" && section.total > section.names.length
+								? "\u2026 and " + (section.total - section.names.length) + " more"
+								: null)
+						]
+					})
+				] }, section.label))
+			});
+		}
+
+		/**
+		 * Compress git's relative age to its shortest honest form: 43 seconds
+		 * ago -> 43s ago, 2 hours ago -> 2h ago, weeks -> w, months -> mo (to
+		 * stay distinct from minutes), years -> y.
+		 */
+		function shortWhen(when) {
+			return String(when)
+				.replace(/(\d+) seconds? ago/u, "$1s ago")
+				.replace(/(\d+) minutes? ago/u, "$1m ago")
+				.replace(/(\d+) hours? ago/u, "$1h ago")
+				.replace(/(\d+) days? ago/u, "$1d ago")
+				.replace(/(\d+) weeks? ago/u, "$1w ago")
+				.replace(/(\d+) months? ago/u, "$1mo ago")
+				.replace(/(\d+) years? ago/u, "$1y ago");
+		}
+
+		/**
+		 * The branch name's own hover body — the branch's LINEAGE, and it ALWAYS
+		 * renders once the lazy detail payload has landed. Rows: upstream, sync
+		 * in words, the branch's last 10 commits (WHAT THIS BRANCH HAS, full
+		 * stop — no base-relative filtering, which empties on every push or
+		 * merge). The pull request has no row here — the chip's own PR token
+		 * already carries number, CI state and the link.
+		 */
+		function BranchLineage({ info }) {
+			const rows = [];
+			const add = (label, value) => {
+				if (value === void 0 || value === null || value === "") return;
+				rows.push(cardRow(label, value));
+			};
+			add("upstream", info?.upstream === void 0 ? "none configured" : info.upstream);
+			const ahead = info?.ahead || 0;
+			const behind = info?.behind || 0;
+			// The sync row speaks ONLY about the upstream it names: with no
+			// upstream configured there are no ahead/behind counts at all (no
+			// `# branch.ab` header), and falling back to 0/0 would claim "in
+			// sync" — a lie the upstream row directly contradicts. Omit it; the
+			// "none configured" row above carries the fact.
+			if (info?.upstream !== void 0) {
+				add("sync", ahead === 0 && behind === 0
+					? "in sync with upstream"
+					: "\u2191" + ahead + " \u2193" + behind);
+			}
+			// The merge-state row, in WORDS (deliberately not arrows — the sync
+			// row above already uses ↑↓ for the push axis, and two arrow pairs
+			// with different references would be read as one). "merge" is its
+			// label because it is the merge axis — the counterpart of "sync",
+			// the push axis — and it stays correct whatever the default branch
+			// is named. A BLOCKED verdict becomes the reason (review required,
+			// checks failing, draft) so a dead-end word names the next action;
+			// CLEAN stays silent — the action row already offers /gh merge.
+			const pr = info?.pr;
+			const mergeParts = [];
+			if (pr !== void 0 && pr !== null && pr.number !== void 0) {
+				if (pr.draft === true) mergeParts.push("blocked: draft");
+				else if (pr.mergeState === "BLOCKED") {
+					mergeParts.push(pr.review === "REVIEW_REQUIRED" ? "blocked: review required"
+						: pr.state === "failing" ? "blocked: checks failing"
+						: "blocked");
+				} else if (pr.state === "failing") mergeParts.push("blocked: checks failing");
+				else if (pr.mergeState !== "CLEAN" && pr.review === "REVIEW_REQUIRED") mergeParts.push("blocked: review required");
+			}
+			if (info?.mainAhead !== void 0 || info?.mainBehind !== void 0) {
+				mergeParts.push((info.mainAhead || 0) + " ahead, " + (info.mainBehind || 0) + " behind main");
+			}
+			if (mergeParts.length > 0) add("merge", mergeParts.join(" \u00B7 "));
+			const commits = info?.branchCommits;
+			if (Array.isArray(commits) && commits.length > 0) {
+				// Full-width block, not the label/value two-column row: commit lines
+				// use the card's whole width, and each line is nowrap with CSS
+				// ellipsis so long subjects clip at the edge instead of pushing the
+				// card out. `when` is compressed the way git log users shorten it:
+				// 43 seconds ago -> 43s ago.
+				rows.push(
+					react_jsx_runtime.jsxs("div", {
+						style: { display: "flex", flexDirection: "column", gap: "2px", minWidth: 0 },
+						children:
+							commits.map((commit) => react_jsx_runtime.jsxs("span", {
+								style: { whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" },
+								children: [
+									// fixed-width monospace hash cell: every description starts
+									// on the same column, so the list reads as a table
+									react_jsx_runtime.jsx("span", {
+										style: {
+											color: "var(--dsw-alias-label-tertiary, #9ea7ad)",
+											fontFamily: "monospace",
+											display: "inline-block",
+											minWidth: "68px",
+											flex: "none"
+										},
+										children: (commit.sign === "+" ? "+" : commit.sign === "\u2212" ? "\u2212" : "") + commit.hash + ":"
+									}),
+									commit.subject + (commit.when === "" ? "" : "  \u00B7 " + shortWhen(commit.when))
+								]
+							}, commit.hash))
+					}, "branch-commits")
+				);
+			}
+			// NO pull-request row: the chip's own PR token (number, CI state, link)
+			// carries it — a second rendering two pixels away is pure duplication.
+			return react_jsx_runtime.jsx("div", { style: CARD_CONTAINER, children: rows });
+		}
+
 		const CARD_ROW = { display: "flex", gap: "8px", alignItems: "baseline" };
 		const CARD_LABEL = { color: "var(--dsw-alias-label-tertiary, #9ea7ad)", flex: "none", minWidth: "62px" };
 		const CARD_VALUE = { minWidth: 0, overflowWrap: "anywhere" };
 
+		/** One label/value row — the shape every hover body shares. */
+		function cardRow(label, value) {
+			return react_jsx_runtime.jsxs("div", {
+				style: CARD_ROW,
+				children: [
+					react_jsx_runtime.jsx("span", { style: CARD_LABEL, children: label }),
+					react_jsx_runtime.jsx("span", { style: CARD_VALUE, children: value })
+				]
+			}, label);
+		}
+
 
 		/**
 		 * Hover card body for the input chip — INPUT CHIP ONLY. Pure presentation
@@ -678,15 +845,7 @@ window.__ModuleLoader__.load({
 			const rows = [];
 			const add = (label, value) => {
 				if (value === void 0 || value === null || value === "") return;
-				rows.push(
-					react_jsx_runtime.jsxs("div", {
-						style: CARD_ROW,
-						children: [
-							react_jsx_runtime.jsx("span", { style: CARD_LABEL, children: label }),
-							react_jsx_runtime.jsx("span", { style: CARD_VALUE, children: value })
-						]
-					}, label)
-				);
+				rows.push(cardRow(label, value));
 			};
 			// The "action" row — the top line, in the card's ordinary row layout:
 			// the gh skill invocation the checkout justifies, derived from the same
@@ -695,16 +854,16 @@ window.__ModuleLoader__.load({
 			// this row is the read-only pointer to it.
 			const topAction = ghSkillActions(data)[0];
 			if (topAction !== void 0) {
-				add("action:", "/gh " + topAction.args);
-			}
-			add("branch", info.branch);
-			add("upstream", info.upstream === void 0 ? "none configured" : info.upstream);
-			if (info.ahead !== void 0 || info.behind !== void 0) {
-				add("sync", "\u2191" + (info.ahead || 0) + " \u2193" + (info.behind || 0));
+				// git-comment convention: the invocation, two spaces, then "# "
+				// plus what it does
+				add("action", "/gh " + topAction.args + "  # " + topAction.what);
 			}
+			// The branch lineage rows (branch, upstream, sync, pull request) moved
+			// to the branch NAME's hover — the card is the checkout's verdict, not
+			// the branch's CV. The branch name is also the chip's own text, so a
+			// card row for it was pure repetition.
 			add("files", formatFileBreakdown(info));
 			add("operation", info.operation === void 0 || info.operation === null ? void 0 : String(info.operation));
-			add("pull request", formatPrDetail(data.pr));
 			// WHICH checkout the badge describes, when it is a worktree. The chip shows
 			// the branch alone, so this row is the only place the tree is named.
 			add("worktree", worktreeDetail(data));
@@ -713,27 +872,6 @@ window.__ModuleLoader__.load({
 			// tree's in that case, so this is where the checkout's own state stays
 			// visible. Absent until the `detail=1` response lands, like commits/stash.
 			if (data.worktreeInferred === true) add("checkout", formatCheckoutDetail(data.checkout));
-			if (Array.isArray(data.lastCommits) && data.lastCommits.length > 0) {
-				rows.push(
-					react_jsx_runtime.jsxs("div", {
-						style: CARD_ROW,
-						children: [
-							react_jsx_runtime.jsx("span", { style: CARD_LABEL, children: "commits" }),
-							react_jsx_runtime.jsx("span", {
-								style: { ...CARD_VALUE, display: "flex", flexDirection: "column", gap: "2px" },
-								children: data.lastCommits.map((commit) =>
-									react_jsx_runtime.jsxs("span", {
-										children: [
-											react_jsx_runtime.jsx("span", { style: CARD_LABEL, children: commit.hash }),
-											" " + commit.subject + (commit.when === "" ? "" : " \u00B7 " + commit.when)
-										]
-									}, commit.hash)
-								)
-							})
-						]
-					}, "commits")
-				);
-			}
 			add("stash", data.stashCount === void 0 ? void 0 : data.stashCount + " stashed");
 			return react_jsx_runtime.jsx("div", { style: CARD_CONTAINER, children: rows });
 		}
@@ -786,6 +924,11 @@ window.__ModuleLoader__.load({
 			// re-render that no fetch will schedule, so the × bumps a counter here.
 			const [, bumpNotice] = react.useState(0);
 			const seamNotice = seamHint !== null && !seamNoticeDismissed ? seamHint : null;
+			// the branch link's hover underline — the PR token's pattern: the
+			// affordance appears on hover/focus, never at rest. Its OWN state, not
+			// the PR token's linkHover: two links sharing one flag would
+			// underline both when either is hovered.
+			const [branchLinkHover, setBranchLinkHover] = react.useState(false);
 			const detail = useGitStatus(target, { pr: true, detail: true, enabled: hovered });
 			if (info === void 0 || info.git !== true) return null;
 
@@ -803,7 +946,8 @@ window.__ModuleLoader__.load({
 				if (Tooltip === void 0) return mark;
 				return react_jsx_runtime.jsx(Tooltip, {
 					side: "top",
-					maxWidth: 360,
+					// matches the body cap: the tooltip must never be the clamp
+				maxWidth: 600,
 					// a function label keeps the card's element tree out of every render
 					// until the tooltip actually opens
 					label: () => react_jsx_runtime.jsx(HoverCard, { info, detail }),
@@ -813,7 +957,74 @@ window.__ModuleLoader__.load({
 			// the mark is an element now rather than a leading glyph in the string, so
 			// the SAME StatusMark the sidebar row draws carries the status here too;
 			// the container's 4px gap supplies the space the emoji's own did
-			const text = info.branch + formatOperationToken(info) + formatGitSuffix(info);
+			// The branch NAME is its own hover surface: the commits this branch adds
+			// (BranchCommitsList), sharing the mark's lazy detail fetch. The rest of
+			// the leading text (operation token) and the count keep their own
+			// surfaces. Degrades to plain text without the Tooltip primitive or
+			// when the branch adds nothing beyond upstream.
+			const branchHover = (() => {
+				// The branch name links to the compare view (base...branch) — the web
+				// page of exactly what the lineage tooltip lists. Vouched http(s)
+				// only (the node half rebuilt the URL from parsed parts); new tab,
+				// never navigating the conversation away.
+				const isLink = typeof detail?.compareUrl === "string" && detail.compareUrl.startsWith("https://");
+				const branch = isLink
+					? react_jsx_runtime.jsx("a", {
+						href: detail.compareUrl,
+						target: "_blank",
+						rel: "noopener noreferrer",
+						"aria-label": "Compare " + info.branch + " with main on GitHub",
+						onPointerEnter: () => { setHovered(true); setBranchLinkHover(true); },
+						onPointerLeave: () => setBranchLinkHover(false),
+						onFocus: () => { setHovered(true); setBranchLinkHover(true); },
+						onBlur: () => setBranchLinkHover(false),
+						style: {
+							color: "inherit",
+							textDecoration: branchLinkHover ? "underline" : "none",
+							cursor: "pointer"
+						},
+						children: info.branch
+					})
+					: react_jsx_runtime.jsx("span", {
+						onPointerEnter: () => setHovered(true),
+						style: { cursor: "default" },
+						children: info.branch
+					});
+				if (Tooltip === void 0 || detail === void 0 || detail === null) {
+					// mid-fetch the branch shows plain; the lineage tooltip is
+					// unconditional once the payload lands
+					return branch;
+				}
+				return react_jsx_runtime.jsx(Tooltip, {
+					side: "top",
+					maxWidth: 480,
+					label: () => react_jsx_runtime.jsx(BranchLineage, { info: detail }),
+					children: branch
+				});
+			})();
+			const text = formatOperationToken(info);
+			// The ✎n count is its OWN hover surface: a names-only tooltip (see
+			// UntrackedList). It shares the mark's lazy detail fetch — resting on
+			// either triggers it once — and degrades to a plain count on a shell
+			// without the Tooltip primitive.
+			const countHover = (() => {
+				const count = react_jsx_runtime.jsx("span", {
+					onPointerEnter: () => setHovered(true),
+					style: { cursor: "default" },
+					children: formatGitSuffix(info)
+				});
+				const hasNames = (Array.isArray(detail?.untrackedNames) && detail.untrackedNames.length > 0)
+					|| (Array.isArray(detail?.unstagedNames) && detail.unstagedNames.length > 0);
+				if (Tooltip === void 0 || !hasNames) {
+					return count;
+				}
+				return react_jsx_runtime.jsx(Tooltip, {
+					side: "top",
+					maxWidth: 480,
+					label: () => react_jsx_runtime.jsx(CountNames, { info: detail }),
+					children: count
+				});
+			})();
 			const prToken = formatPrToken(info);
 			const prUrl = prLinkUrl(info);
 			const chip = react_jsx_runtime.jsxs("span", {
@@ -846,7 +1057,9 @@ window.__ModuleLoader__.load({
 					// stays on the whole chip — it is about the badge, not the mark.
 					hoverableMark,
 
+						branchHover,
 						react_jsx_runtime.jsx("span", { key: "text", children: text }),
+					countHover,
 					prToken === ""
 						? null
 						: prUrl === void 0

package/lib/index.js

@@ -522,6 +522,32 @@ function prStatusFor(toplevel, branch, notify) {
  * two-column XY status (X = index/staged, Y = worktree), `u` unmerged,
  * `?` untracked.
  */
+/** Relative path shortened to its last two segments — the hover-name contract. */
+function shortenPath(name) {
+	const parts = name.split("/");
+	return parts.length <= 2 ? name : parts.slice(-2).join("/");
+}
+
+/**
+ * Convert a remote URL to the hosted repo's WEB root: https stays https,
+ * `git@host:path` ssh syntax converts, a `.git` suffix is stripped. Null when
+ * the URL is neither form — the caller decides what a null is worth.
+ */
+function remoteToWebUrl(raw) {
+	const trimmed = raw.trim().replace(/\.git$/u, "");
+	const https = trimmed.match(/^https:\/\/([^/]+)\/(.+?)\/?$/u);
+	const ssh = trimmed.match(/^[^@]+@([^:]+):(.+)$/u);
+	const web = https !== null ? https[1] + "/" + https[2] : ssh !== null ? ssh[1] + "/" + ssh[2] : null;
+	if (web === null) return null;
+	try {
+		const url = new URL("https://" + web);
+		if (url.protocol === "https:" && url.pathname.length > 1) return url.origin + url.pathname.replace(/\/$/u, "");
+	} catch {
+		// not a URL we can vouch for
+	}
+	return null;
+}
+
 function parseStatusV2(out) {
 	let branch = "HEAD (detached)";
 	let upstream;
@@ -531,6 +557,9 @@ function parseStatusV2(out) {
 	let unstaged = 0;
 	let unmerged = 0;
 	let untracked = 0;
+	const untrackedNames = [];
+	const unstagedNames = [];
+	const stagedNames = [];
 	for (const line of out.split("\n")) {
 		if (line.startsWith("# branch.head ")) branch = line.slice(14).trim();
 		else if (line.startsWith("# branch.upstream ")) upstream = line.slice(18).trim();
@@ -543,12 +572,34 @@ function parseStatusV2(out) {
 			if (Number.isFinite(b)) behind = b;
 		} else if (line.startsWith("1 ") || line.startsWith("2 ")) {
 			// XY columns: X = index (staged), Y = worktree (unstaged)
-			if (line[2] !== ".") staged += 1;
-			if (line[3] !== ".") unstaged += 1;
+			if (line[2] !== ".") {
+				staged += 1;
+				const path = line.startsWith("2 ")
+					? line.split("\t").pop().trim()
+					: line.split(" ").slice(8).join(" ").trim();
+				if (path !== "") stagedNames.push(path);
+			}
+			if (line[3] !== ".") {
+				unstaged += 1;
+				// the path is the LAST field in both records (space-separated, and
+				// the path itself may contain spaces) — collected untruncated and
+				// capped by the caller, exactly like the untracked names
+				const path = line.startsWith("2 ")
+					? line.split("\t").pop().trim()
+					: line.split(" ").slice(8).join(" ").trim();
+				if (path !== "") unstagedNames.push(path);
+			}
 		} else if (line.startsWith("u ")) unmerged += 1;
-		else if (line.startsWith("? ")) untracked += 1;
+		else if (line.startsWith("? ")) {
+			untracked += 1;
+			// `-uall` prints one `? <path>` per untracked FILE, so the names are
+			// the lines themselves — collected untruncated here and capped by the
+			// caller, so the hover's "and k more" arithmetic stays honest.
+			const name = line.slice(2).trim();
+			if (name !== "") untrackedNames.push(name);
+		}
 	}
-	return { branch, upstream, ahead, behind, staged, unstaged, unmerged, untracked };
+	return { branch, upstream, ahead, behind, staged, unstaged, unmerged, untracked, untrackedNames, unstagedNames, stagedNames };
 }
 
 /**
@@ -678,60 +729,98 @@ const OPERATION_NEXT = {
 };
 
 /**
- * The hover card's "next" row: the single highest-priority thing to do next,
- * as a conservative command plus the reason it applies. Pure derivation over
- * fields the status response already carries — no extra git invocations, so it
- * rides the base response and a future surface gets it for free. Ranking (the
- * first match wins):
+ * The configurable action ranking. Every rule carries a category; the order
+ * below (first match wins) is the default, and a user can override it by
+ * naming categories in `~/.dsh/git-badge-next.json`:
  *
- *   1. a paused operation (conflicts included) — resuming it subsumes everything
- *      else; unmerged files without a marker fall back to `git status`
- *   2. behind — reconciling comes before publishing
- *   3. no upstream on a dirty branch — publish it for the first time
- *   4. ahead — publish
- *   5. dirty — stage and commit (add -p for unstaged work; -A only when the
- *      change is untracked-only, which add -p cannot see)
- *   6. PR checks failing — watch them land
+ *   { "order": ["operation", "unmerged", "sync", "publish", "merge", "commit", "checks"] }
+ *
+ * Any subset in any order; categories not listed rank after the listed ones in
+ * default order, unknown names are ignored. Typically edited for you by the
+ * agent via `/gh order`.
+ */
+const DEFAULT_NEXT_ORDER = ["operation", "unmerged", "sync", "publish", "merge", "commit", "checks"];
+
+/** The ranking override file — read per call (one tiny stat+read per status). */
+function nextOrder() {
+	try {
+		const home = process.env.DSH_HOME || join(process.env.HOME || "", ".dsh");
+		const raw = JSON.parse(readFileSync(join(home, "git-badge-next.json"), "utf8"));
+		if (!Array.isArray(raw?.order)) return DEFAULT_NEXT_ORDER;
+		const known = raw.order.filter((cat) => DEFAULT_NEXT_ORDER.includes(cat));
+		return [...known, ...DEFAULT_NEXT_ORDER.filter((cat) => !known.includes(cat))];
+	} catch {
+		return DEFAULT_NEXT_ORDER;
+	}
+}
+
+/**
+ * The hover card's "action" row and the (+) menu's picker: every sub-action the
+ * checkout justifies, each as a `gh`-skill invocation ({ args, why, what } —
+ * what the invocation DOES, why THIS checkout justifies it now), ranked. Pure
+ * derivation over fields the status response already carries — no extra git
+ * invocations, so it rides the base response.
+ *
+ * Ranking: rule candidates are collected with a category, then sorted by the
+ * configured order (nextOrder) — NOT first-match — so a configuration can, for
+ * example, rank "commit" above "sync" without touching code. Ties keep
+ * collection order.
+ *
+ * The new rules this generation adds:
+ *   - diverged (ahead AND behind) → `sync`: reconciling means rebase-then-push,
+ *     which the agent must confirm step by step — a plain pull would discard
+ *     the local-commit context
+ *   - merge-ready (`pr.mergeState === "CLEAN"`, GitHub's own verdict, or checks
+ *     passing + review approved) → `merge <n>`: the endgame action the old
+ *     table could never see
  *
  * Clean, synced, nothing failing → null: the row is omitted entirely, because
- * "no suggestion" is also a suggestion. Commands are conservative on purpose —
- * the card COPIES them into the user's terminal, it never runs them, but the
- * register still avoids anything destructive.
+ * "no suggestion" is also a suggestion.
  *
- * @returns {{ command: string|undefined, why: string } | null}
+ * @returns {{ args: string, command: string|undefined, why: string, what: string } | null}
  */
 function nextStep(info) {
 	if (info === void 0 || info === null || info.git !== true) return null;
 	const unmerged = info.unmergedFiles || 0;
 	const plural = (n) => (n === 1 ? "" : "s");
+	const ahead = info.ahead || 0;
+	const behind = info.behind || 0;
+	const staged = info.stagedFiles || 0;
+	const unstaged = info.unstagedFiles || 0;
+	const untracked = info.untrackedFiles || 0;
+	const dirty = staged + unstaged + untracked;
+	const rules = [];
+	const add = (cat, args, why, what, command) => rules.push({ cat, args, why, what, command });
+
 	if (info.operation !== void 0 && info.operation !== null) {
 		const op = String(info.operation);
-		return {
-			command: OPERATION_NEXT[op],
-			why: unmerged > 0
+		add("operation", "next",
+			unmerged > 0
 				? `${unmerged} unmerged file${plural(unmerged)} blocking the paused ${op}`
-				: `a ${op} is paused mid-operation`
-		};
+				: `a ${op} is paused mid-operation`,
+			`resume the paused ${op}`,
+			OPERATION_NEXT[op]);
 	}
 	if (unmerged > 0) {
-		return { command: "git status", why: `${unmerged} unmerged file${plural(unmerged)} to resolve` };
+		add("unmerged", "next", `${unmerged} unmerged file${plural(unmerged)} to resolve`, "resolve the unmerged files (with you)", "git status");
 	}
-	const ahead = info.ahead || 0;
-	const behind = info.behind || 0;
-	if (behind > 0) {
-		return { command: "git pull --ff-only", why: `${behind} behind ${info.upstream ?? "upstream"}` };
+	if (behind > 0 && ahead > 0) {
+		add("sync", "sync", `${ahead} ahead, ${behind} behind — diverged`, "rebase your commits onto upstream and push (asks before any force)");
+	} else if (behind > 0) {
+		add("sync", "pull", `${behind} behind ${info.upstream ?? "upstream"}`, "update this branch from upstream", "git pull --ff-only");
 	}
-	const staged = info.stagedFiles || 0;
-	const unstaged = info.unstagedFiles || 0;
-	const untracked = info.untrackedFiles || 0;
-	if (info.upstream === void 0 && staged + unstaged + untracked > 0) {
-		return { command: `git push -u origin ${info.branch}`, why: "no upstream configured" };
+	if (info.upstream === void 0 && dirty > 0) {
+		add("publish", "push", "no upstream configured", `publish ${info.branch} for the first time`, `git push -u origin ${info.branch}`);
+	} else if (ahead > 0) {
+		add("publish", "push", `${ahead} ahead of ${info.upstream ?? "upstream"}`, "push local commits to the remote", "git push");
 	}
-	if (ahead > 0) {
-		return { command: "git push", why: `${ahead} ahead of ${info.upstream ?? "upstream"}` };
+	const pr = info.pr === void 0 || info.pr === null ? void 0 : info.pr;
+	if (pr !== void 0 && pr.number !== void 0 && pr.open !== false
+		&& (pr.mergeState === "CLEAN" || (pr.state === "passing" && pr.review === "APPROVED"))) {
+		add("merge", `merge ${pr.number}`, `pull request ${pr.number} is ready to merge`, `merge pull request ${pr.number} (squash)`);
 	}
-	if (staged + unstaged + untracked > 0) {
-		const why = [
+	if (dirty > 0) {
+		const parts = [
 			staged > 0 ? `${staged} staged` : null,
 			unstaged > 0 ? `${unstaged} unstaged` : null,
 			untracked > 0 ? `${untracked} untracked` : null
@@ -741,12 +830,20 @@ function nextStep(info) {
 			: untracked > 0 && unstaged === 0
 				? "git add -A && git commit"
 				: "git add -p && git commit";
-		return { command, why: `work to commit: ${why}` };
+		add("commit", "commit", `work to commit: ${parts}`, staged > 0 ? "commit the staged changes" : "stage and commit the working changes", command);
 	}
-	if (info.pr !== void 0 && info.pr !== null && info.pr.number !== void 0 && info.pr.state === "failing") {
-		return { command: `gh pr checks ${info.pr.number} --watch`, why: `checks failing on #${info.pr.number}` };
+	if (pr !== void 0 && pr.number !== void 0 && pr.state === "failing") {
+		add("checks", `checks ${pr.number}`, `checks failing on #${pr.number}`, "watch the CI checks on pull request " + pr.number, `gh pr checks ${pr.number} --watch`);
 	}
-	return null;
+	if (rules.length === 0) return null;
+
+	const order = nextOrder();
+	const rank = (cat) => {
+		const at = order.indexOf(cat);
+		return at === -1 ? order.length : at;
+	};
+	const [top] = [...rules].sort((a, b) => rank(a.cat) - rank(b.cat));
+	return { args: top.args, command: top.command, why: top.why, what: top.what };
 }
 
 /**
@@ -850,16 +947,103 @@ async function gitStatusUncached(dir, wantDetail, wantPr) {
 		behind: parsed.behind
 	};
 	if (wantDetail) {
-		// last 3 commits (subject + relative age) for the planned hover card
-		const logOut = await runGit(toplevel, ["log", "-3", "--format=%h%x09%s%x09%cr"]);
-		if (logOut.stdout !== null && logOut.stdout.trim() !== "") {
-			info.lastCommits = logOut.stdout.trim().split("\n").map((line) => {
-				const [hash, subject, when] = line.split("\t");
-				return { hash, subject: subject ?? "", when: when ?? "" };
-			}).filter((c) => c.hash !== void 0);
+		// The ✎n NAMES — the one part of the count the numbers cannot answer
+		// ("what are these?"). Hover-gated with the rest of detail=1, so no
+		// refresh pays for it. Posture: RELATIVE names only (git's own output,
+		// never absolute — AGENTS.md rule 7 is relaxed by an inch, not a mile),
+		// shortened to the last two path segments, capped at 20 with the total
+		// carried separately so the client can say "… and k more" honestly.
+		// Staged and unstaged names are TRACKED files: the collapsed untracked
+		// retry never affects them, so they ride regardless of untrackedMode.
+		const capped = (names) => names.slice(0, 20).map(shortenPath);
+		if (untrackedMode === "all" && parsed.untrackedNames.length > 0) {
+			info.untrackedNames = capped(parsed.untrackedNames);
+			info.untrackedNamesTotal = parsed.untrackedNames.length;
+		}
+		if (parsed.unstagedNames.length > 0) {
+			info.unstagedNames = capped(parsed.unstagedNames);
+			info.unstagedNamesTotal = parsed.unstagedNames.length;
+		}
+		if (parsed.stagedNames.length > 0) {
+			info.stagedNames = capped(parsed.stagedNames);
+			info.stagedNamesTotal = parsed.stagedNames.length;
+		}
+		// The signed commit list and the counts-vs-main row: ahead/behind against origin/main (then
+		// origin/master) is the merge-state line — "3 ahead, 0 behind" reads as
+		// "this is the PR's content"; "0 ahead, 5 behind" as "stale, rebase
+		// first". One rev-list --left-right, hover-gated like everything here,
+		// absent entirely when both are zero (in sync needs no row).
+		// The repo's WEB URL — the branch hover links the branch name to the
+		// compare view (`<repo>/compare/<base>...<branch>`), and that URL must be
+		// vouched for like pr.url is: http(s) only, rebuilt from the parsed parts
+		// so no payload value can reach an anchor as a scheme. Derived from
+		// `remote get-url origin` with ssh syntax converted; absent when there is
+		// no origin or the URL is not recognisably a hosted repo.
+		// These reads are independent — one batch, so hover latency is the
+		// longest call rather than their sum. The only dependent call (the
+		// left-right count needs a probed base ref) runs after the batch and
+		// tolerates its own failure.
+		const [remoteUrl, probeMain, probeMaster, logOut2, stashOut] = await Promise.all([
+			runGit(toplevel, ["remote", "get-url", "origin"]),
+			runGit(toplevel, ["rev-parse", "--verify", "--quiet", "origin/main"]),
+			runGit(toplevel, ["rev-parse", "--verify", "--quiet", "origin/master"]),
+			runGit(toplevel, ["log", "-10", "--format=%h%x09%s%x09%cr", "HEAD"]),
+			runGit(toplevel, ["stash", "list"])
+		]);
+		if (remoteUrl.stdout !== null && remoteUrl.stdout.trim() !== "") {
+			info.repoUrl = remoteToWebUrl(remoteUrl.stdout);
+		}
+		const baseRef = probeMain.stdout !== null && probeMain.stdout.trim() !== ""
+			? "origin/main"
+			: probeMaster.stdout !== null && probeMaster.stdout.trim() !== "" ? "origin/master" : null;
+		if (baseRef !== null && info.repoUrl !== void 0) {
+			const baseName = baseRef.replace(/^origin\//u, "");
+			try {
+				const compare = new URL(info.repoUrl + "/compare/" + encodeURIComponent(baseName) + "..." + encodeURIComponent(info.branch));
+				if (compare.protocol === "https:") info.compareUrl = compare.href;
+			} catch {
+				// absent rather than wrong
+			}
+		}
+		if (baseRef !== null) {
+			const lrOut = await runGit(toplevel, ["rev-list", "--count", "--left-right", baseRef + "...HEAD"]);
+			const [mBehind, mAhead] = (lrOut.stdout ?? "").trim().split("\t").map((v) => Number.parseInt(v, 10));
+			if (Number.isFinite(mBehind) && Number.isFinite(mAhead) && (mBehind > 0 || mAhead > 0)) {
+				info.mainAhead = mAhead;
+				info.mainBehind = mBehind;
+			}
+		}
+		if (baseRef !== null) {
+			// The signed commit list: mixed newest-first from base...HEAD, each
+			// entry signed "+" (only on this branch - the PR's content) or "−"
+			// (only on main - what a rebase/merge brings in), git's own left-right
+			// verdict mapped onto the diff convention. Capped at 10 with the total
+			// from the same base so "... and k more" counts both sides. Without a
+			// default branch the list degrades to the plain last 10 on HEAD.
+			const signedOut = await runGit(toplevel, ["log", "--left-right", "-10", "--format=%m%x09%h%x09%s%x09%cr", baseRef + "...HEAD"]);
+			if (signedOut.stdout !== null && signedOut.stdout.trim() !== "") {
+				info.branchCommits = signedOut.stdout.trim().split("\n").map((line) => {
+					const [marker, hash, subject, when] = line.split("\t");
+					return {
+						sign: marker === ">" ? "+" : marker === "<" ? "−" : void 0,
+						hash,
+						subject: subject ?? "",
+						when: when ?? ""
+					};
+				}).filter((c) => c.hash !== void 0);
+				const totalOut = await runGit(toplevel, ["rev-list", "--count", baseRef + "...HEAD"]);
+				const total = Number.parseInt((totalOut.stdout ?? "").trim(), 10);
+				if (Number.isFinite(total)) info.branchCommitsTotal = total;
+			}
+		} else {
+			const plainOut = await runGit(toplevel, ["log", "-10", "--format=%h%x09%s%x09%cr", "HEAD"]);
+			if (plainOut.stdout !== null && plainOut.stdout.trim() !== "") {
+				info.branchCommits = plainOut.stdout.trim().split("\n").map((line) => {
+					const [hash, subject, when] = line.split("\t");
+					return { hash, subject: subject ?? "", when: when ?? "" };
+				}).filter((c) => c.hash !== void 0);
+			}
 		}
-		// stash count, only surfaced when nonzero
-		const stashOut = await runGit(toplevel, ["stash", "list"]);
 		if (stashOut.stdout !== null) {
 			const count = stashOut.stdout.split("\n").filter((l) => l.trim() !== "").length;
 			if (count > 0) info.stashCount = count;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-git-badge",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "Git status badges for DeepSeek Harness: an input-row chip on every install, plus sidebar session-row badges (git status, PR/CI action tokens) after one manual step: `npx dsh-git-badge apply`, then restart dsh web. Event-driven freshness over SSE.",
   "type": "module",
   "main": "lib/index.js",

package/skill/gh/SKILL.md

@@ -59,6 +59,41 @@ unstaged / untracked / unmerged), plus any in-progress operation marker
 - **`/gh checks <n>`** — `gh pr checks <n>` and summarise: what fails, what is
   pending, and the single most useful next step.
 
+- **`/gh sync`** — the branch has diverged (local commits AND upstream
+  changes): `git fetch`, then rebase the local commits onto
+  `upstream/<branch>`, then `git push --force-with-lease`. The force-push
+  ALWAYS needs an explicit user yes first, with a one-line summary of what
+  would move.
+
+- **`/gh merge <n>`** — squash-merge pull request `<n>` (`gh pr merge <n>
+  --squash`), the repo's stated convention. Confirm with the user before
+  merging; afterwards report the merge and offer to update the local main.
+
+- **`/gh stash pop`** — with stashes present: show the top entry's subject,
+  confirm with the user, then `git stash pop`. If pop conflicts, report the
+  conflict verbatim and note that the stash is NOT dropped — suggest
+  `git stash apply` as the retry that keeps it.
+
+- **`/gh checkout <branch>`** — switch to an existing local branch. Establish
+  state first: uncommitted changes may block or travel with the checkout — say
+  what is dirty and confirm the switch when work would carry over. Unknown
+  branch → say so and list the closest local names.
+
+- **`/gh order`** — reconfigure which action class the badge ranks first. The
+  order is one line of JSON at `~/.dsh/git-badge-next.json`:
+  `{ "order": ["operation", "unmerged", "sync", "publish", "merge", "commit",
+  "checks"] }` — any subset, any order; unlisted categories rank after in
+  default order. Read the file (it may not exist yet), apply the requested
+  change, show the resulting order, and never invent categories. Typical
+  invocations: "/gh order commit first", "/gh order never suggest checks
+  before push".
+
+## Handoff
+
+One verb per invocation is this skill's whole job. Anything multi-step around a
+pull request — review, merge, verify it landed, clean up the branch — belongs to
+the `gh-pr` skill; hand off rather than improvise a lifecycle.
+
 ## Hard rules
 
 - Never `git reset --hard`, `git clean`, `git checkout -- .`, `git push