dsh-git-badge 0.13.0 → 0.14.1

package/CHANGELOG.md

@@ -10,6 +10,35 @@ npm. 0.6.0 is the first release recorded here.
 
 ## [Unreleased]
 
+## [0.14.1] - 2026-09-15
+
+### Changed
+
+- **The chip's hover card top line is now an `action:` row** — the gh skill
+  invocation the checkout justifies (e.g. `/gh push`), in the card's ordinary
+  label/value layout, replacing the next-step line's why-plus-copy-chip. The
+  actionable surface remains the (+) menu's `/gh` picker; the card row is its
+  read-only pointer.
+- **The branch pull-down is removed from the chip.** The (+) menu's `/gh`
+  picker supersedes it as the actionable surface, and the chip returns to
+  mark + branch + PR token + notice.
+
+## [0.14.0] - 2026-09-15
+
+### Added
+
+- **A "next" row at the top of the chip's hover card.** The node half derives
+  the single highest-priority next step from fields the status response already
+  carries — a paused operation and its resume command, `git pull --ff-only`
+  when behind, `git push -u origin <branch>` when no upstream exists on a dirty
+  branch, `git push` when ahead, a conservative commit command when dirty
+  (`add -p` for unstaged work, `-A` only for untracked-only changes, which
+  `add -p` cannot see), and `gh pr checks <n> --watch` when CI fails. Each
+  suggestion carries its reason, and the command is a click-to-copy chip — it
+  runs in the user's own terminal, never through dsh. Clean, synced, nothing
+  failing → no row. Pure derivation: no extra git invocations, and the ranking
+  is unit-tested in the node suite.
+
 ## [0.13.0] - 2026-09-15
 
 ### Added

package/lib/client.js

@@ -50,6 +50,11 @@ window.__ModuleLoader__.load({
 			primitives = null;
 		}
 		const Tooltip = primitives === null ? void 0 : primitives.Tooltip;
+		// The shell's pull-down primitive (what the input-area selectors use) and
+		// its candidate ranker. Same guarded require as Tooltip: a shell without
+		// them loses the pull-down affordances, never the badges.
+		const Menu = primitives === null ? void 0 : primitives.Menu;
+		const rankByName = primitives === null ? void 0 : primitives.rankByName;
 
 		/** Module-level git-status cache. Entries are invalidated by SSE events, never by age. */
 		const GIT_CACHE = new Map();
@@ -225,6 +230,48 @@ window.__ModuleLoader__.load({
 			return "ok";
 		}
 
+
+		/**
+		 * 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).
+		 */
+		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;
+				seen.add(args);
+				subs.push({ args, why });
+			};
+			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");
+			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);
+			} 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);
+			}
+			return subs.slice(0, 6);
+		}
+
 		/**
 		 * Mark fill per status, from the app's own semantic tokens so BOTH surfaces
 		 * follow light/dark and custom themes — which a hardcoded emoji cannot do.
@@ -617,6 +664,7 @@ window.__ModuleLoader__.load({
 		const CARD_LABEL = { color: "var(--dsw-alias-label-tertiary, #9ea7ad)", flex: "none", minWidth: "62px" };
 		const CARD_VALUE = { minWidth: 0, overflowWrap: "anywhere" };
 
+
 		/**
 		 * Hover card body for the input chip — INPUT CHIP ONLY. Pure presentation
 		 * over fields the status response already carries, plus the `detail=1`
@@ -640,6 +688,15 @@ window.__ModuleLoader__.load({
 					}, label)
 				);
 			};
+			// The "action" row — the top line, in the card's ordinary row layout:
+			// the gh skill invocation the checkout justifies, derived from the same
+			// state the /gh picker uses (first sub-action wins). Plain text, no
+			// affordance: the actionable surface is the (+) menu's /gh picker, and
+			// 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) {
@@ -731,6 +788,28 @@ window.__ModuleLoader__.load({
 			const seamNotice = seamHint !== null && !seamNoticeDismissed ? seamHint : null;
 			const detail = useGitStatus(target, { pr: true, detail: true, enabled: hovered });
 			if (info === void 0 || info.git !== true) return null;
+
+			// The status mark wrapped in the chip's hover card — the card's ONLY
+			// anchor. Pointer rest here (and only here) enables the detail=1 fetch,
+			// so the extras are paid for exactly when the card that can render them
+			// is about to open. Defined inside the component: it closes over the
+			// hovered state that gates the detail fetch.
+			const hoverableMark = (() => {
+				const mark = react_jsx_runtime.jsx("span", {
+					onPointerEnter: () => setHovered(true),
+					style: { display: "inline-flex", alignItems: "center", flex: "none", cursor: "default" },
+					children: react_jsx_runtime.jsx(StatusMark, { info })
+				});
+				if (Tooltip === void 0) return mark;
+				return react_jsx_runtime.jsx(Tooltip, {
+					side: "top",
+					maxWidth: 360,
+					// 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 }),
+					children: mark
+				});
+			})();
 			// 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
@@ -757,12 +836,17 @@ window.__ModuleLoader__.load({
 				// null until the delayed check in apply() proves the seam never
 				// appeared.
 				title: seamHint === null ? undefined : seamHint,
-				// the card is fetched for a pointer that RESTS here, not one that
-				// merely crosses the chip
-				onPointerEnter: () => setHovered(true),
 				children: [
-					react_jsx_runtime.jsx(StatusMark, { key: "mark", info }),
-					react_jsx_runtime.jsx("span", { key: "text", children: text }),
+					// The hover card belongs to the STATUS SYMBOL, not the badge: the
+					// circle is the "what does this colour mean" element, and a card
+					// opening sideways from a hover on the branch text got in the way of
+					// the very pull-down this row now carries. The detail fetch
+					// (enabled: hovered) follows the same pointer, so nothing pays for
+					// extras the card no longer shows. The seam-absent native title
+					// stays on the whole chip — it is about the badge, not the mark.
+					hoverableMark,
+
+						react_jsx_runtime.jsx("span", { key: "text", children: text }),
 					prToken === ""
 						? null
 						: prUrl === void 0
@@ -864,25 +948,18 @@ window.__ModuleLoader__.load({
 							),
 				]
 			});
-			// No Tooltip primitive (a shell that does not seed it): render the chip
-			// itself rather than losing the badge. The card is an enhancement, the
+			// No Tooltip primitive (a shell that does not seed it): the mark renders
+			// bare and the badge still works — the card is an enhancement, the
 			// badge is the feature.
-			if (Tooltip === void 0) return chip;
-			return react_jsx_runtime.jsx(Tooltip, {
-				side: "top",
-				maxWidth: 360,
-				// 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 }),
-				children: chip
-			});
+			return chip;
 		}
+
 		//#endregion
 
 		// `workspaces` is no longer required: both surfaces target an id and the
 		// node half resolves the workspace, so the client never needs a service
 		// lookup. Fewer declared services also means fewer ways to fail to load.
-		const inject = ["slots"];
+		const inject = ["slots", "inputTriggers"];
 
 		/**
 		 * Register the badge into the seams. The seam owner hands each entry the row
@@ -890,6 +967,93 @@ window.__ModuleLoader__.load({
 		 * deliberately ignores the cwd it may also be given.
 		 */
 		function apply(ctx) {
+			// The /gh command contribution (the (+) commands menu): the state-aware
+			// entry point to the gh skill. available() gates on the cached git
+			// status; options() lists only the sub-actions the checkout justifies;
+			// onSelect SENDS the skill invocation ("/gh push") as a conversation
+			// message — the agent executes the skill under its own approval flow,
+			// and the shell consumes the /gh token afterwards. This is the one
+			// blessed route from a menu pick to a git action; it is a SEND, which
+			// is why the destructive-step confirmation lives in the skill text.
+			// Guarded: a host without commandUi loses the menu entry, never the
+			// badges.
+			if (typeof ctx.inject === "function") {
+				ctx.inject(["commandUi", "sessions"], (scope) => {
+					try {
+					scope.effect(() => scope.commandUi.register({
+						name: "gh",
+						// the contract calls description() as a FUNCTION at menu-build
+						// time (candidates: contribution.description()) — a string throws
+						// TypeError on every candidates pass and kills the whole menu,
+						// (+) button included
+						description: () => "git/gh actions for this checkout — push, pull, pr, commit, checks",
+						available: (session) => {
+							// called during the host's menu build — a throw here kills the
+							// whole menu, so it degrades to "hidden" instead
+							try {
+								const query = targetQuery({ kind: "session", id: session?.sessionId }, { pr: true });
+								return query !== void 0 && GIT_CACHE.get(query)?.data?.git === true;
+							} catch (error) {
+								console.error("[dsh-git-badge] /gh available failed:", error);
+								return false;
+							}
+						},
+						ui: {
+							options: async (session, signal) => {
+								try {
+									const sessionId = session?.sessionId;
+									if (sessionId === void 0) return [];
+									const query = targetQuery({ kind: "session", id: sessionId }, { pr: true });
+									if (query === void 0) return [];
+									// cache-first: the badge's own knowledge opens the picker
+									// instantly; a cold session pays one status fetch.
+									let info = GIT_CACHE.get(query)?.data;
+									if (info === void 0 || info === null) {
+										info = await fetch("/api/git-badge?" + query).then((r) => r.json());
+									}
+									const actions = ghSkillActions(info);
+									return actions.map((action) => ({ label: "/gh " + action.args, detail: action.why, args: action.args }));
+								} catch (error) {
+									console.error("[dsh-git-badge] /gh options failed:", error);
+									return [];
+								}
+							},
+							onSelect: async (option, session) => {
+								// Send the invocation: the message lands in the transcript
+								// and the agent executes the gh skill — the approval flow
+								// for anything destructive is the agent's, per the skill
+								// text. The prompt path is the conversation's own: the
+								// sessions service binds a sessionId to { session } and
+								// binding.session.prompt(content, "queue") is exactly what
+								// the composer's send() calls.
+								const sessionId = session?.sessionId;
+								const sessions = typeof scope.sessions === "function" ? scope.sessions() : scope.sessions;
+								const binding = sessions?.binding?.(sessionId);
+								const target = binding?.session;
+								if (target?.prompt === void 0) {
+									console.error("[dsh-git-badge] /gh: no prompt path (binding missing or session-less)", {
+										sessionId,
+										hasSessions: sessions !== void 0,
+										hasBinding: binding !== void 0
+									});
+									return;
+								}
+								const result = await target.prompt([{ type: "text", text: "/gh " + option.args }], "queue");
+								if (result !== void 0 && result !== null && result.ok === false) {
+									console.error("[dsh-git-badge] /gh submit refused:", result.error);
+								}
+							}
+						}
+					}), "dsh-git-badge: /gh contribution");
+					} catch (error) {
+						// a failed registration must degrade to "no /gh entry", never to
+						// a broken commands menu — the (+) button and the / menu are the
+						// host's, and this callback runs inside their boot
+						console.error("[dsh-git-badge] /gh contribution failed:", error);
+					}
+				});
+			}
+
 			// inject() re-evaluates when a seam's declaration appears, so boot
 			// order relative to the workspace browser does not matter. On an
 			// unpatched install the seam is never declared, so this callback never
@@ -971,7 +1135,7 @@ window.__ModuleLoader__.load({
 		// Additive; the host reads apply/inject and ignores the rest. The suite
 		// drives these to assert the REQUEST contract — which surface asks for the
 		// expensive extras — without a browser, a fetch or a network.
-		exports.__internals = { targetQuery, formatPrToken, formatFileBreakdown, formatPrDetail, formatCheckoutDetail, worktreeDetail, actionToken };
+		exports.__internals = { targetQuery, formatPrToken, formatFileBreakdown, formatPrDetail, formatCheckoutDetail, worktreeDetail, actionToken, ghSkillActions };
 		return module.exports;
 	}
 });

package/lib/index.js

@@ -662,6 +662,93 @@ function operationMarker(gitDir) {
 	return null;
 }
 
+/**
+ * The one command a paused operation resumes with. A squash merge records no
+ * MERGE_HEAD (its conclusion is an ordinary commit), and bisect's next step is
+ * the user's judgement call (good/bad) — it gets a WHY but no command.
+ */
+const OPERATION_NEXT = {
+	merge: "git merge --continue",
+	squash: "git commit",
+	"cherry-pick": "git cherry-pick --continue",
+	revert: "git revert --continue",
+	rebase: "git rebase --continue",
+	sequencer: "git cherry-pick --continue",
+	bisect: void 0
+};
+
+/**
+ * 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):
+ *
+ *   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
+ *
+ * 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.
+ *
+ * @returns {{ command: string|undefined, why: 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");
+	if (info.operation !== void 0 && info.operation !== null) {
+		const op = String(info.operation);
+		return {
+			command: OPERATION_NEXT[op],
+			why: unmerged > 0
+				? `${unmerged} unmerged file${plural(unmerged)} blocking the paused ${op}`
+				: `a ${op} is paused mid-operation`
+		};
+	}
+	if (unmerged > 0) {
+		return { command: "git status", why: `${unmerged} unmerged file${plural(unmerged)} to resolve` };
+	}
+	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"}` };
+	}
+	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 (ahead > 0) {
+		return { command: "git push", why: `${ahead} ahead of ${info.upstream ?? "upstream"}` };
+	}
+	if (staged + unstaged + untracked > 0) {
+		const why = [
+			staged > 0 ? `${staged} staged` : null,
+			unstaged > 0 ? `${unstaged} unstaged` : null,
+			untracked > 0 ? `${untracked} untracked` : null
+		].filter(Boolean).join(", ");
+		const command = staged > 0
+			? "git commit"
+			: untracked > 0 && unstaged === 0
+				? "git add -A && git commit"
+				: "git add -p && git commit";
+		return { command, why: `work to commit: ${why}` };
+	}
+	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}` };
+	}
+	return null;
+}
+
 /**
  * Git status for dir; { git: false } when dir is not a repository,
  * GIT_DEGRADED on transient git failure.
@@ -787,6 +874,8 @@ async function gitStatusUncached(dir, wantDetail, wantPr) {
 		const pr = prStatusFor(toplevel, parsed.branch, notifyChange);
 		if (pr !== void 0) info.pr = pr;
 	}
+	const next = nextStep(info);
+	if (next !== null) info.next = next;
 	return info;
 }
 
@@ -1355,6 +1444,7 @@ export {
 	config,
 	OPERATION_MARKERS,
 	operationMarker,
+	nextStep,
 	outerGitDir,
 	parseStatusV2,
 	parseWorktreeList,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-git-badge",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "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",
@@ -47,17 +47,19 @@
     "node": ">=20"
   },
   "files": [
-    "lib/index.js",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "cordis.patch.yml",
     "lib/client.js",
-    "seam/apply.js",
+    "lib/index.js",
+    "package.json",
     "seam/anchors.js",
+    "seam/apply.js",
     "seam/postinstall.js",
+    "seam/skill.js",
     "seam/store.js",
     "seam/stub-index.js",
-    "cordis.patch.yml",
-    "package.json",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
+    "skill/gh/SKILL.md"
   ]
 }

package/seam/apply.js

@@ -55,6 +55,7 @@ import {
 	seamPresent,
 } from "./anchors.js";
 
+import { installSkill } from "./skill.js";
 import { dataDir, writeRestartMarker } from "./store.js";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -165,6 +166,11 @@ function writeText(path, text) {
 
 const VERDICT_EXIT_1 = new Set(["drift", "unreadable", "missing", "ours-corrupt"]);
 
+// keep the /gh skill in step with the package on every patcher run
+if (["apply", "revert", "status"].includes(process.argv[2])) {
+	console.log(`[dsh-git-badge] gh skill: ${installSkill()}`);
+}
+
 const verb = process.argv[2];
 if (!verb || !["apply", "revert", "status"].includes(verb)) {
 	console.error("usage: apply.js apply|revert|status");

package/seam/postinstall.js

@@ -26,6 +26,7 @@ import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { applyPatch, firstFailure, isOurs, seamPresent } from "./anchors.js";
+import { installSkill } from "./skill.js";
 import { dataDir, writeRestartMarker } from "./store.js";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -41,6 +42,9 @@ function dshClientPath() {
 }
 
 function main() {
+	// The skill does not depend on the DSH install — install it before any
+	// client-shaped early return, so a market install always gets /gh.
+	console.log(`[dsh-git-badge] gh skill: ${installSkill()} — /gh in the input's commands menu.`);
 	const client = dshClientPath();
 	if (client === null || !existsSync(client)) {
 		console.log(`[dsh-git-badge] DSH install not found; skipping seam setup. ${HINT}`);

package/seam/skill.js

@@ -0,0 +1,53 @@
+/**
+ * The gh skill installer — copies the packaged skill into the user's skills
+ * catalog so `/gh` exists in the input's commands menu.
+ *
+ * WHY A SKILL: the commands menu executes git through the AGENT, not through
+ * this plugin — the agent owns the approval/sandbox semantics for mutating
+ * commands. The skill is the knowledge; the `/gh` command contribution in the
+ * client half is only the state-aware menu entry that invokes it.
+ *
+ * GUARDRAILS — a skill must never break an install: every failure path returns
+ * a reason string instead of throwing, and a current target is a no-op (the
+ * byte comparison makes reinstalls and updates idempotent).
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+export const SKILL_NAME = "gh";
+
+/** The user-level skills catalog — DSH_HOME honours the harness override. */
+export function skillsDir() {
+	return join(process.env.DSH_HOME || join(process.env.HOME || "", ".dsh"), "skills");
+}
+
+export function skillSource() {
+	return join(HERE, "..", "skill", "gh", "SKILL.md");
+}
+
+export function skillTarget() {
+	return join(skillsDir(), SKILL_NAME, "SKILL.md");
+}
+
+/**
+ * Install (or update) the gh skill. Never throws.
+ * @returns {"installed"|"current"|"no packaged skill"|string} what happened.
+ */
+export function installSkill() {
+	try {
+		const source = skillSource();
+		if (!existsSync(source)) return "no packaged skill";
+		const target = skillTarget();
+		mkdirSync(dirname(target), { recursive: true });
+		if (existsSync(target) && readFileSync(target, "utf8") === readFileSync(source, "utf8")) {
+			return "current";
+		}
+		copyFileSync(source, target);
+		return "installed";
+	} catch (error) {
+		return "skipped (" + String(error?.message ?? error) + ")";
+	}
+}

package/skill/gh/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: gh
+description: Git and GitHub operations for the current checkout, driven by an invocation argument — /gh push, /gh pr, /gh pull, /gh commit, /gh checks <n>, or bare /gh to do the single highest-priority next action.
+whenToUse: When the user picks a git action from the commands menu (/gh push, /gh pr, …) or asks to sync, publish, or open a pull request for the checkout they are working in.
+---
+
+# gh — git/GitHub actions for this checkout
+
+You are invoked as `/gh <sub>` (or bare `/gh`). The sub-command chooses the
+operation. Anything destructive requires explicit user confirmation before you
+run it, every command is reported with its output, and a failure is reported
+verbatim rather than retried blind.
+
+## First: establish state
+
+Run one status call and read it before acting (except for `checks`, which acts
+on its argument):
+
+```
+git --no-optional-locks status --porcelain=v2 --branch
+```
+
+Note branch, upstream, ahead/behind, and the dirty breakdown (staged /
+unstaged / untracked / unmerged), plus any in-progress operation marker
+(MERGE_HEAD, rebase-merge, …).
+
+## Sub-commands
+
+- **`/gh next`** (or bare `/gh`) — do the single highest-priority action, first
+  match wins: resume a paused operation (`git merge --continue`,
+  `git rebase --continue`, …; a squash merge concludes with `git commit`);
+  resolve unmerged files only WITH the user; `git pull --ff-only` when behind;
+  `git push -u origin <branch>` when there is no upstream; `git push` when
+  ahead; stage and commit when dirty (`git commit` if work is already staged,
+  `git add -p && git commit` for unstaged edits, `git add -A && git commit`
+  only for untracked-only changes, which `add -p` cannot see); `gh pr checks
+  <n> --watch` when CI fails. Clean and synced → say so and stop.
+
+- **`/gh push`** — `git push`. If there is no upstream, `git push -u origin
+  <branch>`. If the push is rejected as non-fast-forward, STOP and ask: offer
+  `--force-with-lease` as the option, never plain `--force`, and never without
+  an explicit yes.
+
+- **`/gh pr`** — create a pull request for the current branch: push first if
+  needed, then `gh pr create` with a title from the branch's commits and a body
+  summarising them. If a PR already exists, report its state (`gh pr view`)
+  instead of creating another.
+
+- **`/gh pull`** — `git pull --ff-only`. On failure, report the divergence and
+  ask; do not merge or rebase without the user choosing.
+
+- **`/gh commit`** — commit the current work: `git commit` when work is already
+  staged; otherwise `git add -p` interactively is not available to you, so
+  stage deliberately (`git add <paths>` named from the status output) and say
+  exactly what you staged before committing. Untracked-only changes: `git add
+  -A && git commit` after listing what -A will pick up. Write the message from
+  the diff, not a template.
+
+- **`/gh checks <n>`** — `gh pr checks <n>` and summarise: what fails, what is
+  pending, and the single most useful next step.
+
+## Hard rules
+
+- Never `git reset --hard`, `git clean`, `git checkout -- .`, `git push
+  --force` (plain), or any history rewrite without an explicit user yes.
+- `GIT_TERMINAL_PROMPT=0` on network commands so a missing credential fails
+  fast instead of hanging.
+- One operation per invocation; report the outcome, then stop.