pi-do-always 0.12.0 → 0.13.0

package/README.md

@@ -8,29 +8,6 @@ type to filter, scroll or click, or navigate with arrows + Enter → the task's
 **filled into the input editor**. Review it, tweak it, press Enter to run. Tasks marked `⚡`
 (the `Plan` category by default) auto-run on selection instead — see `autoRun` below.
 
-```text
-  do-always — pick a task
-
-   #  TASK                      DESCRIPTION                                                    ORDER
-  PLAN
-   1  ⚡ Review changes         Review the current code changes (Plan)                           ·  
-   2  ⚡ Review code            Review the whole project's code quality (Plan)                  [1] 
-   3  ⚡ Cleanup                Clean up dead code and duplicates (Plan)                        [2] 
-   4  ⚡ Security               Security audit (Plan)                                            ·  
-   5  ⚡ Performance            Performance review (Plan)                                      ►[3] 
-   6  ⚡ Propose features       Propose new features (Plan)                                      ·  
-  DO
-   7  Build                     Test build is ok and fix issues                                  ·  
-   8  Tests                     Run tests and fix failures                                       ·  
-  DOCS
-   9  Readme                    Update the README.md                                             ·  
-
-  ──────────────────────────────────────────────────────────────────────────────────────────────────
-  Run the chain (3)
-  ← tasks  •  ⏎ remove  •  esc  •  ctrl+u clear
-
-  1-9 pick by number  •  type to filter  •  ↑↓ navigate  •  enter select  •  esc cancel  •  ⚡ auto-runs
-```
 
 ![do-always — the numbered task selector](pi.image.png)
 
@@ -134,6 +111,31 @@ that view and in the report file on disk. A run that stops early (aborted, error
 skipped steps) does not show the inline report — only the status trace widget below
 the prompt.
 
+## Commit browser
+
+Two built-in tasks open the date-grouped commit browser (pages of 20, type to
+filter, Space/Enter to select, ←/→ to page):
+
+- **Browse commits** (category `Browse`, only shown inside a git repo) — the
+  generic entry: select commits, then confirm on the `do on the commits
+  (n commits)` row to pick which task runs on them — a picker lists your
+  visible `Plan` tasks, except those marked `notForCommits: true` (the
+  built-in Review changes, Review code, and Propose features — they operate
+  on the working tree or the whole project, not on a set of commits). The
+  chosen task's prompt is sent as a single turn (not a chain) with the
+  selection injected.
+- **Review commits** (category `Plan`, hidden from the selector) — offered in
+  the picker after a selection; the review runs directly on the selected
+  commits (its prompt consumes the selection). Still resolvable by name:
+  `/do-always review commits` opens the browser as before.
+
+The selection is injected into the chosen task's prompt: a prompt that
+references `{{selected_commits}}` gets the numbered commit detail block
+substituted in; any other prompt gets the block appended under
+`Selected commits:`. In non-interactive modes (no TUI) the browser is skipped:
+the latest commit is selected and the first eligible `Plan` task (not
+`notForCommits`) whose guards pass runs on it.
+
 ## Install
 
 Install it from npm as a Pi package, which loads the bundled `index.ts` (and its `tasks.ts`) without
@@ -163,7 +165,7 @@ Tasks are read from JSON files (an array of tasks, or the object form `{"tasks":
 |`~/.pi/agent/do-always.json`|Global (all projects)|
 |`<project>/.pi/do-always.json`|Project-local; overrides global tasks with the same `name`|
 
-If neither file exists, the built-in defaults (Review changes, Review code, Cleanup, Security, Performance, Propose features, Build, Tests, Readme, Release, Commit) are used.
+If neither file exists, the built-in defaults (Review changes, Review code, Cleanup, Security, Performance, Propose features, Review commits, Browse commits, Build, Tests, Readme, Release, Commit) are used.
 This repo ships a sample in [`do-always.json`](./extensions/pi-do-always/do-always.json) — copy it to one of the
 locations above to make it your own:
 
@@ -181,10 +183,13 @@ locations above to make it your own:
 Fields:
 
 - `name` (required) — short unique id, used for `/do-always <name>`
-- `category` (optional) — group header the task is shown under in the selector (e.g. `"Plan"`, `"Do"`). Matching is case-insensitive and the header is title-cased, so `"plan"` and `"Plan"` land in the same `Plan` group. Tasks without a category fall under `Other`. The built-in defaults are grouped into `Plan`, `Do`, `Docs`, and `Ops`.
+- `category` (optional) — group header the task is shown under in the selector (e.g. `"Plan"`, `"Do"`). Matching is case-insensitive and the header is title-cased, so `"plan"` and `"Plan"` land in the same `Plan` group. Tasks without a category fall under `Other`. The built-in defaults are grouped into `Plan`, `Browse`, `Do`, `Docs`, and `Ops`.
 - `description` (optional) — one-line label shown in the selector
 - `prompt` (required) — the text filled into the editor (supports `{{placeholders}}` — see [Prompt placeholders](#prompt-placeholders))
 - `autoRun` (optional) — when `true`, selecting the task sends its prompt immediately instead of filling the editor; when `false`, it always fills the editor. When omitted, the default is derived from the category: `Plan` tasks auto-run, everything else fills the editor. Auto-run tasks are marked `⚡` in the selector.
+- `browser` (optional) — a browser to open on selection instead of injecting the prompt. Only `"commits"` is supported: it opens the date-grouped commit browser, and after the selection the task runs on the selected commits — directly when its prompt references `{{selected_commits}}`, otherwise via a picker of `Plan` tasks (see [Commit browser](#commit-browser)). An invalid value is ignored with a warning.
+- `hidden` (optional) — when `true`, the task is not shown in the selector or in `/do-always list` / `list-details`. Unlike a `when` condition, a hidden task can still be run by name (`/do-always <name>`), and it is offered as a candidate by the commit picker. The built-in `Review commits` uses this: it is a pick-after-browse option, not a standalone entry.
+- `notForCommits` (optional) — when `true`, the task is excluded from the commit picker (the “run on the selected commits” list) because it does not operate on a set of commits. The task is otherwise unaffected (selector, lists, CLI). The built-in `Review changes`, `Review code`, and `Propose features` use this.
 - `when` (optional) — a condition that hides the task from the selector and lists when it is not met (see [Conditionals](#conditionals)).
 - `guards` (optional) — an array of selection-time guards that block the task (with a message, not a hide) when a condition is unmet (see [Guards](#guards)). The legacy `requireDirty` (boolean) still works and is combined with any `guards`.
 
@@ -227,6 +232,7 @@ injects “Review the changes on branch `fix/login-null` (3 changed files:
 |`{{repo}}`|Basename of the git remote (or of the working directory when there is no remote) — disambiguates monorepo work|
 |`{{staged_files}}`|Files staged for commit, one per line (`none` when empty)|
 |`{{unstaged_files}}`|Modified-but-unstaged files, one per line (`none` when empty)|
+|`{{selected_commits}}`|Commits selected in the commit browser, as a numbered detail block (`none` outside a browser run)|
 
 Unknown placeholders are left as-is, and a prompt without placeholders is
 injected unchanged, so existing configs keep working. The selector preview and

package/extensions/pi-do-always/do-always.json

@@ -6,12 +6,14 @@
 			"category": "Plan",
 			"description": "Review the current code changes (Plan)",
 			"requireDirty": true,
+			"notForCommits": true,
 			"prompt": "Review the changes on branch {{branch}} ({{files_changed_count}} changed files: {{files_changed}}). Change summary: {{diff_stat}}. Last commit: {{last_commit}}. Check `git status` and `git diff` to see what changed, then double-check the changes for bugs, edge cases, security issues, and consistency with the rest of the codebase. Do a plan proposal for the fixes if needed. Do a summary of your findings."
 		},
 		{
 			"name": "Review code",
 			"category": "Plan",
 			"description": "Review the whole project's code quality (Plan)",
+			"notForCommits": true,
 			"prompt": "Review this project's code holistically: identify code smells, dead code, duplication, awkward architecture or patterns, maintainability issues, inconsistencies, and missing or unclear documentation. Prioritize by impact, propose a plan for the fixes, and summarize your findings. Do not make any changes yet."
 		},
 		{
@@ -36,8 +38,25 @@
 			"name": "Propose features",
 			"category": "Plan",
 			"description": "Propose new features (Plan)",
+			"notForCommits": true,
 			"prompt": "Review this project and propose new features that would add value. For each idea, describe the problem it solves, the user benefit, and a rough implementation approach. Prioritize by impact and effort. Do not make any changes yet. Try to evaluate how many lines this will be in terms of changes, whether this will break APIs, or introduce compatibility issues."
 		},
+		{
+			"name": "Review commits",
+			"category": "Plan",
+			"description": "Review the selected commits (Plan)",
+			"browser": "commits",
+			"hidden": true,
+			"prompt": "Review the selected commits: {{selected_commits}}. Inspect each with `git show <hash>`, double-check the changes for bugs, edge cases, security issues, and consistency with the rest of the codebase. Summarize your findings per commit and propose a plan for any fixes if needed. Do not make any changes yet."
+		},
+		{
+			"name": "Browse commits",
+			"category": "Browse",
+			"description": "Browse and select commits, then pick a task to run on them",
+			"browser": "commits",
+			"when": "git",
+			"prompt": "Browse recent commits, select some, then pick a task to run on them."
+		},
 		{
 			"name": "Build",
 			"category": "Do",

package/extensions/pi-do-always/index.ts

@@ -51,6 +51,8 @@ import {
 } from "@earendil-works/pi-tui";
 import {
 	CHAIN_MAX,
+	COMMIT_BROWSER_MAX,
+	COMMIT_SELECT_MAX,
 	DEFAULT_SHORTCUT,
 	DEFAULT_TASKS,
 	assistantText,
@@ -65,12 +67,16 @@ import {
 	evaluateWhen,
 	formatChainSequence,
 	formatList,
+	formatSelectedCommits,
+	groupCommitsByDate,
 	groupTasksByCategory,
+	isTaskVisible,
 	isValidKeyId,
 	mergeTasks,
 	parseConfig,
 	parseConfigRegexpValueForKey,
 	parseCommitSubject,
+	parseGitLogOutput,
 	parseStatusPorcelain,
 	parseStatusStagedUnstaged,
 	orderTasksByCategory,
@@ -88,7 +94,10 @@ import {
 	toPromptContext,
 	validateChain,
 	type ChainStepOutcome,
+	type CommitInfo,
+	type DateGroup,
 	type DoAlwaysTask,
+	type SelectedCommit,
 	type TaskContext,
 	type TableRow,
 } from "./tasks";
@@ -196,6 +205,17 @@ function git(cwd: string, args: string[]): Promise<string | undefined> {
 	});
 }
 
+/**
+ * Count changed files (staged, unstaged, untracked) with a single git spawn.
+ * Lighter than a full `buildContext` when only the count is needed (chain
+ * step summaries). Returns 0 when git is unavailable — the same neutral
+ * result `buildContext` yields via its empty file list.
+ */
+async function changedFileCount(cwd: string): Promise<number> {
+	const porcelain = await git(cwd, ["status", "--porcelain"]);
+	return porcelain ? parseStatusPorcelain(porcelain).length : 0;
+}
+
 /**
  * Build the structured context for the current directory. Git facts fall back
  * to neutral values when unavailable (non-git dir, no git, empty repo) so
@@ -233,6 +253,7 @@ async function buildContext(cwd: string): Promise<TaskContext> {
 			repo: cwd.split(/[\\/]/).filter(Boolean).pop() ?? "unknown",
 			stagedFiles: [],
 			unstagedFiles: [],
+			selectedCommits: "none",
 			isGitRepo: false,
 		};
 	}
@@ -274,15 +295,566 @@ async function buildContext(cwd: string): Promise<TaskContext> {
 		repo,
 		stagedFiles,
 		unstagedFiles,
+		selectedCommits: "none",
 		isGitRepo,
 	};
 }
 
+/**
+ * Fetch a page of commits from git with lightweight stats via a single log call.
+ * Fetches pageSize + 1 commits to determine if more commits are available.
+ */
+async function fetchCommitsPage(
+	cwd: string,
+	page = 0,
+	pageSize = COMMIT_BROWSER_MAX,
+): Promise<{ commits: CommitInfo[]; groups: DateGroup[]; hasMore: boolean }> {
+	const countToFetch = pageSize + 1;
+	const skip = page * pageSize;
+	const format = "COMMIT%x09%H%x09%h%x09%s%x09%ad%x09%an";
+	const logOutput = await git(cwd, [
+		"log",
+		"-n",
+		`${countToFetch}`,
+		`--skip=${skip}`,
+		`--format=${format}`,
+		"--shortstat",
+		"--date=short",
+	]);
+	if (!logOutput) {
+		return { commits: [], groups: [], hasMore: false };
+	}
+
+	const allParsed = parseGitLogOutput(logOutput);
+	const hasMore = allParsed.length > pageSize;
+	const commits = hasMore ? allParsed.slice(0, pageSize) : allParsed;
+	const groups = groupCommitsByDate(commits);
+	return { commits, groups, hasMore };
+}
+
+/**
+ * Date-grouped commit browser: browse recent commits in pages of 20, select some,
+ * then review them. Reuses the task-selector interaction model (↑↓, Space toggle,
+ * type-to-filter, Ctrl+U clear, Esc cancel, ←/→ or PgUp/PgDn for paging).
+ *
+ * Returns the selected commits (ordered by user selection), or null on cancel.
+ */
+function browseCommits(
+	ctx: ExtensionContext,
+	initialData?: { commits: CommitInfo[]; groups: DateGroup[]; hasMore: boolean },
+): Promise<SelectedCommit[] | null> {
+	return new Promise<SelectedCommit[] | null>((resolve) => {
+		const pageCache = new Map<number, { commits: CommitInfo[]; groups: DateGroup[]; hasMore: boolean }>();
+		let page = 0;
+		if (initialData) {
+			pageCache.set(0, initialData);
+		}
+
+		type CommitCursor = { kind: "commit"; index: number } | { kind: "run" };
+		const maxVisible = 14; // commits visible in the scroll window
+		const selectedMap = new Map<string, SelectedCommit>(); // hash -> SelectedCommit
+		let cursor: CommitCursor = { kind: "commit", index: 0 };
+		let lastCommitIndex = 0;
+		let filter = "";
+		let settled = false;
+		let isLoading = false;
+
+		ctx.ui.custom<SelectedCommit[] | null>((tui, theme, _kb, done) => {
+			const kb = getKeybindings();
+
+			function finish(selectedCommits: SelectedCommit[]) {
+				if (settled) return;
+				settled = true;
+				done(selectedCommits);
+				resolve(selectedCommits);
+			}
+
+			function finishCancel() {
+				if (settled) return;
+				settled = true;
+				done(null);
+				resolve(null);
+			}
+
+			async function loadPage(newPage: number) {
+				if (isLoading || newPage < 0) return;
+				page = newPage;
+				if (!pageCache.has(page)) {
+					isLoading = true;
+					tui.requestRender();
+					try {
+						const fetched = await fetchCommitsPage(ctx.cwd, page);
+						pageCache.set(page, fetched);
+					} finally {
+						isLoading = false;
+					}
+				}
+				cursor = { kind: "commit", index: 0 };
+				lastCommitIndex = 0;
+				tui.requestRender();
+			}
+
+			function getCurrentPageData() {
+				return pageCache.get(page) ?? { commits: [], groups: [], hasMore: false };
+			}
+
+			function getVisibleCommits(): CommitInfo[] {
+				const { commits } = getCurrentPageData();
+				if (!filter) return commits;
+				const f = filter.toLowerCase();
+				return commits.filter(
+					(c) => c.subject.toLowerCase().includes(f) || c.shortHash.toLowerCase().includes(f),
+				);
+			}
+
+			function render(width: number): string[] {
+				const currentData = getCurrentPageData();
+				const visibleCommits = getVisibleCommits();
+				const lines: string[] = [];
+
+				// Clamp cursor index if visible list changed
+				if (cursor.kind === "commit") {
+					if (visibleCommits.length === 0) {
+						cursor = { kind: "run" };
+					} else if (cursor.index >= visibleCommits.length) {
+						cursor = { kind: "commit", index: visibleCommits.length - 1 };
+						lastCommitIndex = cursor.index;
+					}
+				}
+
+				// Header
+				const startNum = page * COMMIT_BROWSER_MAX + 1;
+				const endNum = page * COMMIT_BROWSER_MAX + (visibleCommits.length || 0);
+				const pageLabel = currentData.hasMore
+					? `Page ${page + 1} (${startNum}–${endNum}+)`
+					: `Page ${page + 1} (${startNum}–${endNum})`;
+
+				lines.push(
+					theme.fg(
+						"muted",
+						truncateToWidth(
+							`   #  DATE       HASH     FILES  ORDER  SUBJECT  [${pageLabel}]`,
+							width - 2,
+							"",
+						),
+					),
+				);
+
+				if (isLoading) {
+					lines.push(theme.fg("accent", "  Loading commits from git…"));
+				} else if (visibleCommits.length === 0) {
+					lines.push(
+						filter
+							? theme.fg("warning", `  No commits matching "${filter}" on this page`)
+							: theme.fg("muted", "  No commits found"),
+					);
+				} else {
+					const anchor = cursor.kind === "commit" ? cursor.index : lastCommitIndex;
+					const winStart = visibleCommits.length > maxVisible
+						? Math.max(0, Math.min(anchor + 1 - maxVisible, visibleCommits.length - maxVisible))
+						: 0;
+					const winEnd = Math.min(winStart + maxVisible, visibleCommits.length);
+
+					for (let i = winStart; i < winEnd; i++) {
+						const c = visibleCommits[i];
+						// Show date divider if it's the first commit in window or date changed
+						if (i === winStart || c.date !== visibleCommits[i - 1].date) {
+							lines.push(theme.fg("dim", `  ── ${c.date} ──`));
+						}
+
+						const isCursor = cursor.kind === "commit" && cursor.index === i;
+						const isSelected = selectedMap.has(c.hash);
+						const order = isSelected ? [...selectedMap.keys()].indexOf(c.hash) + 1 : 0;
+						const cursorMark = isCursor ? theme.fg("accent", "►") : " ";
+						const globalIdx = page * COMMIT_BROWSER_MAX + i + 1;
+						const num = `${cursorMark} ${String(globalIdx).padStart(2)}`;
+						const marker = isSelected ? `${theme.fg("accent", "◉")} [${order}]` : "  ·  ";
+						const hash = theme.fg("dim", c.shortHash.slice(0, 7));
+						const statStr = c.filesChanged > 0 ? `${c.filesChanged}f` : "";
+						const statCell = statStr.padStart(3);
+						const dateShort = c.date.slice(5); // MM-DD
+						const subject = truncateToWidth(c.subject, Math.max(10, width - 36), "…");
+
+						const rowText = `${num}  ${dateShort}  ${hash}  ${statCell}  ${marker}  ${subject}`;
+						if (isCursor) {
+							lines.push(theme.bg("selectedBg", theme.bold(rowText)));
+						} else {
+							lines.push(rowText);
+						}
+					}
+
+					if (visibleCommits.length > maxVisible) {
+						lines.push(
+							theme.fg(
+								"dim",
+								truncateToWidth(
+									`  (${cursor.kind === "commit" ? cursor.index + 1 : lastCommitIndex + 1}/${visibleCommits.length} on page ${page + 1})`,
+									width - 2,
+									"",
+								),
+							),
+						);
+					}
+				}
+
+				// Run row
+				lines.push("");
+				lines.push(theme.fg("dim", "  " + "─".repeat(Math.max(1, width - 4))));
+				const runLabel = selectedMap.size === 0
+					? "do on the commits (no commits selected)"
+					: `do on the commits (${selectedMap.size} commit${selectedMap.size !== 1 ? "s" : ""})`;
+				if (cursor.kind === "run") {
+					lines.push(theme.bg("selectedBg", theme.bold(`${theme.fg("accent", "►")} ${runLabel}`)));
+				} else if (selectedMap.size === 0) {
+					lines.push(theme.fg("dim", `  ${runLabel}`));
+				} else {
+					lines.push(theme.fg("accent", `  ${runLabel}`));
+				}
+
+				// Footer
+				const pageNavHints: string[] = [];
+				if (page > 0) pageNavHints.push("← prev page");
+				if (currentData.hasMore) pageNavHints.push("→ next page");
+				const pageHintStr = pageNavHints.length > 0 ? `  •  ${pageNavHints.join("  •  ")}` : "";
+
+				let footer = `  space/⏎ select  •  ↑/↓ move${pageHintStr}  •  esc`;
+				if (selectedMap.size > 0) {
+					footer += "  •  ctrl+u clear";
+				}
+				if (filter) {
+					footer += `  •  filter: "${filter}"`;
+				}
+				lines.push(theme.fg("dim", truncateToWidth(footer, width - 2, "")));
+
+				return lines;
+			}
+
+			async function handleInput(data: string) {
+				if (settled) return;
+				const currentData = getCurrentPageData();
+				const visibleCommits = getVisibleCommits();
+
+				// Space: toggle selection on current commit
+				if (matchesKey(data, "space")) {
+					if (cursor.kind === "commit" && visibleCommits[cursor.index]) {
+						const c = visibleCommits[cursor.index];
+						if (selectedMap.has(c.hash)) {
+							selectedMap.delete(c.hash);
+							let i = 1;
+							for (const sc of selectedMap.values()) {
+								sc.selectionOrder = i++;
+							}
+						} else if (selectedMap.size < COMMIT_SELECT_MAX) {
+							selectedMap.set(c.hash, { ...c, selectionOrder: selectedMap.size + 1 });
+						} else {
+							ctx.ui.notify(`do-always: chain is full (${COMMIT_SELECT_MAX}) — remove a commit first`, "error");
+						}
+						tui.requestRender();
+					}
+					return;
+				}
+
+				// Confirm (Enter): run the chain if on run row, or toggle selection if on a commit
+				if (kb.matches(data, "tui.select.confirm") || matchesKey(data, "enter")) {
+					if (cursor.kind === "run") {
+						if (selectedMap.size === 0) {
+							ctx.ui.notify("do-always: no commits selected", "info");
+						} else {
+							finish([...selectedMap.values()]);
+						}
+						return;
+					}
+					if (cursor.kind === "commit" && visibleCommits[cursor.index]) {
+						const c = visibleCommits[cursor.index];
+						if (selectedMap.has(c.hash)) {
+							selectedMap.delete(c.hash);
+							let i = 1;
+							for (const sc of selectedMap.values()) {
+								sc.selectionOrder = i++;
+							}
+						} else if (selectedMap.size < COMMIT_SELECT_MAX) {
+							selectedMap.set(c.hash, { ...c, selectionOrder: selectedMap.size + 1 });
+						} else {
+							ctx.ui.notify(`do-always: chain is full (${COMMIT_SELECT_MAX}) — remove a commit first`, "error");
+						}
+						tui.requestRender();
+					}
+					return;
+				}
+
+				// Cancel (Esc / Ctrl+C)
+				if (kb.matches(data, "tui.select.cancel") || matchesKey(data, "escape")) {
+					finishCancel();
+					return;
+				}
+
+				// Ctrl+U: clear selections
+				if (matchesKey(data, "ctrl+u")) {
+					if (selectedMap.size > 0) {
+						selectedMap.clear();
+						tui.requestRender();
+					}
+					return;
+				}
+
+				// Backspace: delete character from filter, or undo last selection
+				if (kb.matches(data, "tui.editor.deleteCharBackward") || matchesKey(data, "backspace")) {
+					if (filter.length > 0) {
+						filter = filter.slice(0, -1);
+						cursor = { kind: "commit", index: 0 };
+						lastCommitIndex = 0;
+					} else if (selectedMap.size > 0) {
+						const lastHash = [...selectedMap.keys()].pop()!;
+						selectedMap.delete(lastHash);
+					}
+					tui.requestRender();
+					return;
+				}
+
+				// Page navigation: Next page (Right arrow, or PageDown when at the end)
+				if (matchesKey(data, "right")) {
+					if (currentData.hasMore) {
+						await loadPage(page + 1);
+					}
+					return;
+				}
+				if (kb.matches(data, "tui.select.pageDown") || matchesKey(data, "pageDown")) {
+					if (cursor.kind === "commit") {
+						const next = cursor.index + maxVisible;
+						if (next < visibleCommits.length) {
+							cursor = { kind: "commit", index: next };
+							lastCommitIndex = next;
+							tui.requestRender();
+						} else if (currentData.hasMore) {
+							await loadPage(page + 1);
+						} else {
+							cursor = { kind: "run" };
+							tui.requestRender();
+						}
+					} else if (currentData.hasMore) {
+						await loadPage(page + 1);
+					}
+					return;
+				}
+
+				// Page navigation: Previous page (Left arrow, or PageUp when at the top)
+				if (matchesKey(data, "left")) {
+					if (page > 0) {
+						await loadPage(page - 1);
+					}
+					return;
+				}
+				if (kb.matches(data, "tui.select.pageUp") || matchesKey(data, "pageUp")) {
+					if (cursor.kind === "commit") {
+						const prev = cursor.index - maxVisible;
+						if (prev >= 0) {
+							cursor = { kind: "commit", index: prev };
+							lastCommitIndex = prev;
+							tui.requestRender();
+						} else if (page > 0) {
+							await loadPage(page - 1);
+						} else {
+							cursor = { kind: "commit", index: 0 };
+							lastCommitIndex = 0;
+							tui.requestRender();
+						}
+					} else if (visibleCommits.length > 0) {
+						cursor = { kind: "commit", index: Math.max(0, visibleCommits.length - maxVisible) };
+						lastCommitIndex = cursor.index;
+						tui.requestRender();
+					}
+					return;
+				}
+
+				// Up arrow
+				if (kb.matches(data, "tui.select.up") || matchesKey(data, "up")) {
+					if (cursor.kind === "run") {
+						if (visibleCommits.length > 0) {
+							cursor = { kind: "commit", index: visibleCommits.length - 1 };
+							lastCommitIndex = visibleCommits.length - 1;
+						}
+					} else if (cursor.index > 0) {
+						cursor = { kind: "commit", index: cursor.index - 1 };
+						lastCommitIndex = cursor.index;
+					} else {
+						cursor = { kind: "run" };
+					}
+					tui.requestRender();
+					return;
+				}
+
+				// Down arrow
+				if (kb.matches(data, "tui.select.down") || matchesKey(data, "down")) {
+					if (cursor.kind === "run") {
+						if (visibleCommits.length > 0) {
+							cursor = { kind: "commit", index: 0 };
+							lastCommitIndex = 0;
+						}
+					} else if (cursor.index < visibleCommits.length - 1) {
+						cursor = { kind: "commit", index: cursor.index + 1 };
+						lastCommitIndex = cursor.index;
+					} else {
+						cursor = { kind: "run" };
+					}
+					tui.requestRender();
+					return;
+				}
+
+				// Home / End
+				if (matchesKey(data, "home")) {
+					if (visibleCommits.length > 0) {
+						cursor = { kind: "commit", index: 0 };
+						lastCommitIndex = 0;
+						tui.requestRender();
+					}
+					return;
+				}
+				if (matchesKey(data, "end")) {
+					cursor = { kind: "run" };
+					tui.requestRender();
+					return;
+				}
+
+				// Filter typing (printable chars, excluding Space which toggles)
+				if (isPrintable(data) && data !== " ") {
+					filter += data;
+					cursor = { kind: "commit", index: 0 };
+					lastCommitIndex = 0;
+					tui.requestRender();
+					return;
+				}
+			}
+
+			return {
+				render,
+				handleInput,
+				invalidate: () => {},
+			};
+		});
+	});
+}
+
 /** True for a single printable ASCII character (used for filter typing). */
 function isPrintable(data: string): boolean {
 	return data.length === 1 && data >= " " && data <= "~";
 }
 
+/**
+ * Task picker shown after a commit selection: proposes the Plan tasks (hidden
+ * ones included — e.g. "Review commits" exists to be picked here) to run on
+ * the selected commits. Type to filter, ↑/↓ move, Enter runs, Esc cancels.
+ * Returns the chosen task, or null on cancel.
+ */
+function pickPlanTaskForCommits(
+	ctx: ExtensionContext,
+	candidates: DoAlwaysTask[],
+	commitCount: number,
+): Promise<DoAlwaysTask | null> {
+	return new Promise<DoAlwaysTask | null>((resolve) => {
+		ctx.ui.custom<DoAlwaysTask | null>((tui, theme, _kb, done) => {
+			const kb = getKeybindings();
+			let settled = false;
+			let filter = "";
+			let cursor = 0;
+
+			const visible = () => {
+				if (!filter) return candidates;
+				const f = filter.toLowerCase();
+				return candidates.filter(
+					(t) =>
+						t.name.toLowerCase().includes(f) ||
+						(t.description ?? "").toLowerCase().includes(f),
+				);
+			};
+
+			function finish(task: DoAlwaysTask | null) {
+				if (settled) return;
+				settled = true;
+				done(task);
+				resolve(task);
+			}
+
+			function render(width: number): string[] {
+				const items = visible();
+				if (items.length === 0) cursor = 0;
+				else if (cursor >= items.length) cursor = items.length - 1;
+				const lines: string[] = [];
+				lines.push(
+					theme.fg(
+						"accent",
+						theme.bold(
+							truncateToWidth(
+								`  do-always — run on ${commitCount} selected commit${commitCount !== 1 ? "s" : ""}`,
+								width - 2,
+								"",
+							),
+						),
+					),
+				);
+				lines.push(theme.fg("muted", "   #  TASK"));
+				if (items.length === 0) {
+					lines.push(theme.fg("warning", `  No Plan tasks matching "${filter}"`));
+				} else {
+					for (let i = 0; i < items.length; i++) {
+						const t = items[i];
+						const auto = shouldAutoRun(t);
+						const name = truncateToWidth(t.name, Math.max(10, width - 8 - (auto ? 3 : 0)), "…", true);
+						const rowText = `  ${String(i + 1).padStart(2)}  ${auto ? "⚡ " : ""}${name}`;
+						lines.push(i === cursor ? theme.bg("selectedBg", theme.bold(rowText)) : rowText);
+					}
+				}
+				lines.push(
+					theme.fg(
+						"dim",
+						truncateToWidth(
+							`  ↑/↓ move  •  ⏎ run  •  esc${filter ? `  •  filter: "${filter}"` : ""}`,
+							width - 2,
+							"",
+						),
+					),
+				);
+				return lines;
+			}
+
+			function handleInput(data: string) {
+				if (settled) return;
+				const items = visible();
+				if (kb.matches(data, "tui.select.cancel") || matchesKey(data, "escape")) {
+					finish(null);
+					return;
+				}
+				if (kb.matches(data, "tui.select.confirm") || matchesKey(data, "enter")) {
+					finish(items[cursor] ?? null);
+					return;
+				}
+				if (kb.matches(data, "tui.select.up") || matchesKey(data, "up")) {
+					if (items.length > 0) cursor = cursor === 0 ? items.length - 1 : cursor - 1;
+					tui.requestRender();
+					return;
+				}
+				if (kb.matches(data, "tui.select.down") || matchesKey(data, "down")) {
+					if (items.length > 0) cursor = cursor === items.length - 1 ? 0 : cursor + 1;
+					tui.requestRender();
+					return;
+				}
+				if (kb.matches(data, "tui.editor.deleteCharBackward") || matchesKey(data, "backspace")) {
+					filter = filter.slice(0, -1);
+					cursor = 0;
+					tui.requestRender();
+					return;
+				}
+				if (isPrintable(data)) {
+					filter += data;
+					cursor = 0;
+					tui.requestRender();
+				}
+			}
+
+			return { render, handleInput, invalidate: () => {} };
+		});
+	});
+}
+
 /** Delay before the selector reveals the selected task's prompt preview. */
 const PREVIEW_DELAY_MS = 2000;
 /** Max lines of the prompt shown in the selector preview. */
@@ -787,9 +1359,9 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 		return done;
 	}
 
-	/** Filter tasks by their `when` condition and refresh the completion cache. */
+	/** Filter tasks by visibility (`hidden` flag + `when` condition) and refresh the completion cache. */
 	function refreshVisible(cwd: string, context: TaskContext): DoAlwaysTask[] {
-		const visible = tasks.filter((t) => evaluateWhen(t, context));
+		const visible = tasks.filter((t) => isTaskVisible(t, context));
 		visibleCache = { cwd, visible };
 		return visible;
 	}
@@ -875,6 +1447,106 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 
 	/** Put the task prompt into the editor (TUI) or send it as a user message (other modes). */
 	async function fillPrompt(task: DoAlwaysTask, ctx: ExtensionContext, context: TaskContext): Promise<void> {
+		// Commit browser: any task with `browser: "commits"` opens the
+		// date-grouped browser first. The name check keeps configs that
+		// predate the field working. After the selection: a task whose prompt
+		// references {{selected_commits}} runs itself on the selection; a
+		// generic entry (e.g. "Browse commits") proposes the Plan tasks to
+		// run on it — hidden tasks included, since they exist to be picked
+		// here (non-TUI: the first one whose guards pass).
+		if (task.browser === "commits" || task.name === "Review commits") {
+			let selected: SelectedCommit[] = [];
+			if (ctx.mode !== "tui") {
+				const initialData = await fetchCommitsPage(ctx.cwd, 0, 1);
+				if (initialData.commits.length === 0) {
+					ctx.ui.notify("do-always: no commits found", "info");
+					return;
+				}
+				selected = [{ ...initialData.commits[0], selectionOrder: 1 }];
+			} else {
+				const initialData = await fetchCommitsPage(ctx.cwd, 0);
+				if (initialData.commits.length === 0) {
+					ctx.ui.notify("do-always: no commits found", "info");
+					return;
+				}
+				const result = await browseCommits(ctx, initialData);
+				if (!result) {
+					ctx.ui.notify("do-always: commit browser cancelled", "info");
+					return;
+				}
+				if (result.length === 0) {
+					ctx.ui.notify("do-always: no commits selected", "info");
+					return;
+				}
+				selected = result;
+			}
+
+			// Which task runs on the selection: the originating task when its
+			// prompt consumes {{selected_commits}}; otherwise a Plan task
+			// picked by the user (TUI) or the first whose guards pass (non-TUI).
+			const planTasks = tasks.filter(
+				(t) =>
+					!t.notForCommits &&
+					evaluateWhen(t, context) &&
+					(t.category ?? "").trim().toLowerCase() === "plan",
+			);
+			if (planTasks.length === 0) {
+				ctx.ui.notify("do-always: no Plan task available to run on the selected commits", "info");
+				return;
+			}
+			let chosen: DoAlwaysTask | undefined;
+			if (/\{\{\s*selected_commits\s*\}\}/.test(task.prompt)) {
+				chosen = task;
+			} else if (ctx.mode === "tui") {
+				const picked = await pickPlanTaskForCommits(ctx, planTasks, selected.length);
+				if (!picked) {
+					ctx.ui.notify("do-always: no task chosen — commits not used", "info");
+					return;
+				}
+				chosen = picked;
+			} else {
+				// Non-TUI: no picker — the first Plan task whose guards pass.
+				chosen = planTasks.find((t) => evaluateGuards(t, context) === null);
+			}
+			if (!chosen) {
+				ctx.ui.notify("do-always: no Plan task available to run on the selected commits (guards unmet)", "info");
+				return;
+			}
+
+			// Guards apply to the commit run too: a picked (or originating)
+			// task blocked for the current tree is not sent — same as the
+			// non-browser path below.
+			const blocked = evaluateGuards(chosen, context);
+			if (blocked) {
+				ctx.ui.notify(`do-always: ${blocked}`, "info");
+				return;
+			}
+
+			// Inject the selection: substitute {{selected_commits}} when the
+			// prompt references it, otherwise append the detail block. The run
+			// is a single turn (not a chain): sendUserMessage + summary.
+			const details = formatSelectedCommits(selected);
+			const strings = toPromptContext(context);
+			const prompt = /\{\{\s*selected_commits\s*\}\}/.test(chosen.prompt)
+				? renderPrompt(chosen.prompt, { ...strings, selected_commits: details })
+				: `${renderPrompt(chosen.prompt, strings)}\n\nSelected commits:\n${details}`;
+
+			pendingSummaryTask = chosen.name;
+			if (pendingSummaryTimer) clearTimeout(pendingSummaryTimer);
+			pendingSummaryTimer = setTimeout(() => {
+				pendingSummaryTimer = null;
+				if (!pendingSummaryTask) return;
+				const name = pendingSummaryTask;
+				pendingSummaryTask = null;
+				lastCtx?.ui.notify(`do-always: "${name}" failed to start (check model/API key)`, "error");
+			}, 10_000);
+			pi.sendUserMessage(prompt);
+			ctx.ui.notify(
+				`do-always: ${selected.length} commit${selected.length !== 1 ? "s" : ""} → ${chosen.name}`,
+				"info",
+			);
+			return;
+		}
 		const blocked = evaluateGuards(task, context);
 		if (blocked) {
 			ctx.ui.notify(`do-always: ${blocked}`, "info");
@@ -1007,12 +1679,21 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 					return;
 				}
 				setChainStep(ctx, 0, "completed");
-				// Post-step summary for step 1 (fill-first)
-				const postContext = await getContext(ctx.cwd);
-				const fileCount = postContext.files.length;
+				// Post-step summary for step 1 (fill-first). When more steps
+				// follow, the fresh full build doubles as step 2's pre-context
+				// (the tree can only change via agent runs, which have settled);
+				// a single-task chain only needs the file count.
+				let nextContext: TaskContext | undefined;
+				let fileCount: number;
+				if (steps.length === 1) {
+					fileCount = await changedFileCount(ctx.cwd);
+				} else {
+					nextContext = await getContext(ctx.cwd);
+					fileCount = nextContext.files.length;
+				}
 				const summary = stepSummary(outcome, first.name, chainDurations[0], fileCount);
 				ctx.ui.notify(`do-always: step 1/${steps.length} — ${summary}`, "info");
-				await runChainSteps(steps, ctx, 1);
+				await runChainSteps(steps, ctx, 1, nextContext);
 			} finally {
 				chainActive = false;
 			}
@@ -1024,15 +1705,23 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 	 * and renders prompts against fresh repository context, and each step is
 	 * awaited until its run has fully settled; an aborted/errored step (or a
 	 * send that failed to start) stops the chain.
+	 *
+	 * Context builds are shared across steps: after each completed step the
+	 * fresh full build (needed for the file-count summary) is reused as the
+	 * next step's pre-context — the tree can only change via agent runs, and
+	 * the step has fully settled before the build runs. `initialContext` lets
+	 * the fill-first path hand over its post-step-1 build. The last step's
+	 * summary uses a single-spawn file count instead of a full build.
 	 */
 	async function runChainSteps(
 		steps: DoAlwaysTask[],
 		ctx: ExtensionContext,
 		startAt: number,
+		initialContext?: TaskContext,
 	): Promise<void> {
+		let context = initialContext ?? (await getContext(ctx.cwd));
 		for (let i = startAt; i < steps.length; i++) {
 			const step = steps[i];
-			const context = await getContext(ctx.cwd);
 			const blocked = evaluateGuards(step, context);
 			if (blocked) {
 				markChainStopped(ctx, i, "skipped", blocked);
@@ -1050,9 +1739,16 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 			chainDurations[i] = stepDuration;
 			if (outcome === "completed") {
 				setChainStep(ctx, i, "completed");
-				// Post-step summary: files changed + duration.
-				const postContext = await getContext(ctx.cwd);
-				const fileCount = postContext.files.length;
+				// Post-step summary: files changed + duration. All but the last
+				// step get a fresh full build that doubles as the next step's
+				// pre-context; the last step only needs the count (one spawn).
+				let fileCount: number;
+				if (i === steps.length - 1) {
+					fileCount = await changedFileCount(ctx.cwd);
+				} else {
+					context = await getContext(ctx.cwd);
+					fileCount = context.files.length;
+				}
 				const summary = stepSummary(outcome, step.name, stepDuration, fileCount);
 				ctx.ui.notify(`do-always: step ${i + 1}/${steps.length} — ${summary}`, "info");
 				continue;
@@ -1109,9 +1805,10 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 		context: TaskContext,
 		cache: ReturnType<typeof createContextCache>,
 	): Promise<void> {
-		// Filter by the `when` condition once per session, so hidden tasks never
-		// appear, are never numbered, and can't be picked.
-		const visibleTasks = tasks.filter((t) => evaluateWhen(t, context));
+		// Filter by the `hidden` flag and the `when` condition once per session,
+		// so hidden tasks never appear, are never numbered, and can't be picked
+		// (same predicate as refreshVisible, which numbers `/do-always <n>`).
+		const visibleTasks = tasks.filter((t) => isTaskVisible(t, context));
 		// String view for prompt rendering (derived once, used by the preview).
 		const strings = toPromptContext(context);
 		const result = await ctx.ui.custom<SelectorResult>((tui, theme, _kb, done) => {
@@ -1608,6 +2305,13 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 							return;
 						}
 						// ORDER column: toggle this task's chain membership.
+						// Browser tasks can't be chained: the chain runner sends
+						// prompts directly, so the browser (and
+						// {{selected_commits}}) never run — run them on their own.
+						if (row.task.browser) {
+							ctx.ui.notify(`do-always: "${row.task.name}" opens a browser — it can't be chained, run it on its own`, "info");
+							return;
+						}
 						if (chain.items.includes(row.task.name)) {
 							chain = chainRemove(chain, row.task.name);
 						} else {
@@ -1670,16 +2374,22 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 					const { itemRows } = visible;
 					const idx = itemRows.findIndex((r) => r.task === task);
 					if (idx < 0) return undefined;
-					// ORDER cell: press toggles chain membership.
-					if (orderColX !== null && event.x >= orderColX) {
-						if (event.type === "press") {
-							chain = chain.items.includes(task.name) ? chainRemove(chain, task.name) : chainAdd(chain, task.name).state;
-							clampCursor(visible);
-							resetPreview();
-							return { handled: true, render: true };
+						// ORDER cell: press toggles chain membership.
+						if (orderColX !== null && event.x >= orderColX) {
+							if (event.type === "press") {
+								if (task.browser) {
+									// Same rule as the keyboard toggle: browser tasks
+									// can't be chained (see ORDER column).
+									ctx.ui.notify(`do-always: "${task.name}" opens a browser — it can't be chained, run it on its own`, "info");
+									return { handled: true };
+								}
+								chain = chain.items.includes(task.name) ? chainRemove(chain, task.name) : chainAdd(chain, task.name).state;
+								clampCursor(visible);
+								resetPreview();
+								return { handled: true, render: true };
+							}
+							return { handled: true }; // swallow the click after the press action
 						}
-						return { handled: true }; // swallow the click after the press action
-					}
 					// Task area: press selects, click runs (the classic fast path).
 					if (event.type === "press") {
 						mousePressedIndex = idx;

package/extensions/pi-do-always/tasks.ts

@@ -37,6 +37,21 @@ export interface DoAlwaysTask {
 	 * Omitted/undefined always shows the task. Evaluated by `evaluateWhen`.
 	 */
 	when?: string | Record<string, unknown>;
+	/**
+	 * Hide the task from the selector and the `list` commands. Hidden tasks
+	 * are not standalone user-visible entries; they can still be resolved by
+	 * name on the command line and are offered as candidates by the commit
+	 * picker. The built-in "Review commits" uses this: it is a pick-after-
+	 * browse option, not an entry point ("Browse commits" is the entry).
+	 */
+	hidden?: boolean;
+	/**
+	 * Exclude the task from the commit picker (the "run on the selected
+	 * commits" list shown after a commit selection). For Plan tasks that
+	 * operate on the working tree or the whole project rather than on a set
+	 * of commits. The task is otherwise unaffected (selector, lists, CLI).
+	 */
+	notForCommits?: boolean;
 	/**
 	 * Extra selection-time guards, evaluated alongside the legacy `requireDirty`
 	 * (see `evaluateGuards`). Each guard blocks the task (with a message, not a
@@ -44,6 +59,14 @@ export interface DoAlwaysTask {
 	 * compatibility; new guards use this array so the set is extensible.
 	 */
 	guards?: Guard[];
+	/**
+	 * A browser to open on selection instead of injecting the prompt directly.
+	 * Currently only "commits": opens the date-grouped commit browser, and the
+	 * selected commits drive the review prompt (see `fillPrompt` in index.ts).
+	 * The built-in "Review commits" task also triggers the browser by name, so
+	 * configs that predate this field keep working.
+	 */
+	browser?: BrowserType;
 }
 
 /** The set of known guard types (used for validation at parse time). */
@@ -66,6 +89,13 @@ export interface Guard {
 	value?: string;
 }
 
+/** The set of known browser types (used for validation at parse time). */
+export const BROWSER_TYPES = [
+	"commits",
+] as const;
+
+export type BrowserType = (typeof BROWSER_TYPES)[number];
+
 /**
  * A config file can be a bare array of tasks, or {"tasks": [...], "shortcut": ...}.
  * `shortcut` is a key id string (e.g. "f4", "ctrl+shift+p"), or null to disable
@@ -144,6 +174,12 @@ export interface TaskContext {
 	stagedFiles: string[];
 	/** Modified-but-unstaged files. */
 	unstagedFiles: string[];
+	/**
+	 * Commits selected in the commit browser, formatted for prompt injection
+	 * (see `formatSelectedCommits`), or "none" when no selection is active.
+	 * Context builds always set "none"; the browser flow overrides it at render.
+	 */
+	selectedCommits: string;
 	/** True when cwd is inside a git working tree (authoritative, not inferred from the branch name). */
 	isGitRepo: boolean;
 }
@@ -166,6 +202,7 @@ export const PROMPT_CONTEXT_KEYS = [
 	"repo",
 	"staged_files",
 	"unstaged_files",
+	"selected_commits",
 ] as const;
 
 /** A fully populated prompt context: one entry per PROMPT_CONTEXT_KEYS. */
@@ -193,6 +230,7 @@ export function toPromptContext(ctx: TaskContext): PromptContext {
 		repo: ctx.repo,
 		staged_files: formatFileLines(ctx.stagedFiles),
 		unstaged_files: formatFileLines(ctx.unstagedFiles),
+		selected_commits: ctx.selectedCommits,
 	};
 }
 
@@ -315,6 +353,7 @@ export const DEFAULT_TASKS: DoAlwaysTask[] = [
 		category: "Plan",
 		description: "Review the current code changes (Plan)",
 		requireDirty: true,
+		notForCommits: true,
 		prompt:
 			"Review the changes on branch {{branch}} ({{files_changed_count}} changed files: {{files_changed}}). " +
 			"Change summary: {{diff_stat}}. Last commit: {{last_commit}}. " +
@@ -326,6 +365,7 @@ export const DEFAULT_TASKS: DoAlwaysTask[] = [
 		name: "Review code",
 		category: "Plan",
 		description: "Review the whole project's code quality (Plan)",
+		notForCommits: true,
 		prompt:
 			"Review this project's code holistically: identify code smells, dead code, duplication, awkward architecture or patterns, maintainability issues, inconsistencies, and missing or unclear documentation. " +
 			"Prioritize by impact, propose a plan for the fixes, and summarize your findings. Do not make any changes yet.",
@@ -393,9 +433,29 @@ export const DEFAULT_TASKS: DoAlwaysTask[] = [
 		name: "Propose features",
 		category: "Plan",
 		description: "Propose new features (Plan)",
+		notForCommits: true,
 		prompt:
 			"Review this project and propose new features that would add value. For each idea, describe the problem it solves, the user benefit, and a rough implementation approach. Prioritize by impact and effort. Do not make any changes yet. Try to evaluate how many lines this will be in terms of changes, whether this will break APIs, or introduce compatibility issues.",
 	},
+	{
+		name: "Review commits",
+		category: "Plan",
+		description: "Review the selected commits (Plan)",
+		browser: "commits",
+		hidden: true,
+		prompt:
+			"Review the selected commits: {{selected_commits}}. Inspect each with `git show <hash>`, " +
+			"double-check the changes for bugs, edge cases, security issues, and consistency with the rest of the codebase. " +
+			"Summarize your findings per commit and propose a plan for any fixes if needed. Do not make any changes yet.",
+	},
+	{
+		name: "Browse commits",
+		category: "Browse",
+		description: "Browse and select commits, then pick a task to run on them",
+		browser: "commits",
+		when: "git",
+		prompt: "Browse recent commits, select some, then pick a task to run on them.",
+	},
 ];
 
 /**
@@ -427,7 +487,7 @@ export function parseConfig(
 	const tasks: DoAlwaysTask[] = [];
 	for (const entry of list) {
 		const t = entry as Partial<DoAlwaysTask> | null;
-		if (t && typeof t.name === "string" && t.name.length > 0 && typeof t.prompt === "string" && t.prompt.length > 0) {
+		if (t && typeof t.name === "string" && t.name.length > 0 && typeof t.prompt === "string" && (t.prompt.length > 0 || t.autoRun === true)) {
 			const task: DoAlwaysTask = {
 				name: t.name,
 				prompt: t.prompt,
@@ -436,6 +496,15 @@ export function parseConfig(
 				if (typeof t.category === "string" && t.category.trim() !== "") task.category = t.category.trim();
 				if (typeof t.autoRun === "boolean") task.autoRun = t.autoRun;
 				if (typeof t.requireDirty === "boolean") task.requireDirty = t.requireDirty;
+				if (typeof t.hidden === "boolean") task.hidden = t.hidden;
+				if (typeof t.notForCommits === "boolean") task.notForCommits = t.notForCommits;
+				if (t.browser !== undefined) {
+					if (typeof t.browser === "string" && BROWSER_TYPES.includes(t.browser as BrowserType)) {
+						task.browser = t.browser as BrowserType;
+					} else {
+						onError(`do-always: ignoring invalid "browser" in ${path} (expected one of: ${BROWSER_TYPES.join(", ")})`);
+					}
+				}
 				if (t.guards !== undefined) {
 					if (Array.isArray(t.guards)) {
 						const guards: Guard[] = [];
@@ -665,8 +734,17 @@ export function evaluateWhen(task: DoAlwaysTask, ctx: TaskContext): boolean {
 	return true;
 }
 
+/**
+ * Whether a task is visible in the selector and the lists: not `hidden` and
+ * its `when` condition passes. Single source of truth so the TUI selector and
+ * the `/do-always <n>` numbering can never diverge.
+ */
+export function isTaskVisible(task: DoAlwaysTask, ctx: TaskContext): boolean {
+	return !task.hidden && evaluateWhen(task, ctx);
+}
+
 /** Default order for category headers in the selector. Exported for tests. */
-export const DEFAULT_CATEGORY_ORDER = ["Plan", "Do", "Docs", "Ops", "Other"];
+export const DEFAULT_CATEGORY_ORDER = ["Plan", "Browse", "Do", "Docs", "Ops", "Other"];
 
 /** A category group: a display name and the tasks that belong to it. */
 interface TaskGroup {
@@ -1263,3 +1341,153 @@ function outcomeToMarker(outcome: ChainStepOutcome): string {
 			throw new Error(`unexpected outcome: ${outcome as string}`);
 	}
 }
+
+// ── Commit browser types ─────────────────────────────────────────────────
+//
+// Types and constants for the date-grouped commit browser (used by
+// the "Review commits" task in index.ts). Pure data — no Pi dependencies.
+
+/** Maximum commits shown per page in the date-grouped browser. */
+export const COMMIT_BROWSER_MAX = 20;
+
+/** Maximum commits that can be selected for a review chain. */
+export const COMMIT_SELECT_MAX = 20;
+
+/** A single commit as returned by `git log --format`. */
+export interface CommitInfo {
+	/** Full 40-char SHA. */
+	hash: string;
+	/** Short 7-char SHA. */
+	shortHash: string;
+	/** Commit subject line. */
+	subject: string;
+	/** Commit date (YYYY-MM-DD). */
+	date: string;
+	/** Commit author name. */
+	author: string;
+	/** Number of files changed in this commit. */
+	filesChanged: number;
+	/** Insertions in this commit. */
+	insertions: number;
+	/** Deletions in this commit. */
+	deletions: number;
+}
+
+/** A commit selected by the user for review. */
+export interface SelectedCommit extends CommitInfo {
+	/** 1-based position in the user's selection order. */
+	selectionOrder: number;
+}
+
+/** Group of commits sharing the same date. */
+export interface DateGroup {
+	/** Date string (YYYY-MM-DD). */
+	date: string;
+	/** Number of commits in this group. */
+	count: number;
+	/** Commits in this group (newest first). */
+	commits: CommitInfo[];
+}
+
+/**
+ * Parse git log output formatted with:
+ * `COMMIT%x09%H%x09%h%x09%s%x09%ad%x09%an` and optional `--shortstat`.
+ */
+export function parseGitLogOutput(output: string): CommitInfo[] {
+	if (!output) return [];
+	const commits: CommitInfo[] = [];
+	let current: CommitInfo | null = null;
+	for (const rawLine of output.split("\n")) {
+		const line = rawLine.trim();
+		if (line.startsWith("COMMIT\t")) {
+			if (current) commits.push(current);
+			const parts = line.split("\t");
+			if (parts.length >= 6) {
+				const hash = parts[1];
+				const shortHash = parts[2];
+				const date = parts[parts.length - 2];
+				const author = parts[parts.length - 1];
+				const subject = parts.slice(3, parts.length - 2).join("\t") || "(no subject)";
+				current = {
+					hash,
+					shortHash,
+					subject,
+					date,
+					author,
+					filesChanged: 0,
+					insertions: 0,
+					deletions: 0,
+				};
+			} else {
+				current = null;
+			}
+			continue;
+		}
+		if (current && line.includes("changed")) {
+			const mFiles = line.match(/(\d+) file/);
+			const mIns = line.match(/(\d+) insertion/);
+			const mDel = line.match(/(\d+) deletion/);
+			if (mFiles) current.filesChanged = Number(mFiles[1]);
+			if (mIns) current.insertions = Number(mIns[1]);
+			if (mDel) current.deletions = Number(mDel[1]);
+		}
+	}
+	if (current) commits.push(current);
+	return commits;
+}
+
+/** Group commits by date (preserving existing order within and between groups). */
+export function groupCommitsByDate(commits: CommitInfo[]): DateGroup[] {
+	const groups = new Map<string, CommitInfo[]>();
+	for (const c of commits) {
+		if (!groups.has(c.date)) groups.set(c.date, []);
+		groups.get(c.date)!.push(c);
+	}
+	return [...groups.entries()].map(([date, groupCommits]) => ({
+		date,
+		count: groupCommits.length,
+		commits: groupCommits,
+	}));
+}
+
+/**
+ * Format the selected commits as a numbered detail block (hash, subject,
+ * author, date, stats per commit). Injected into task prompts via the
+ * `{{selected_commits}}` placeholder; composed into the full review prompt by
+ * `formatCommitReviewPrompt`.
+ */
+export function formatSelectedCommits(commits: SelectedCommit[]): string {
+	const count = commits.length;
+	return commits
+		.map((c, i) => {
+			const num = count > 1 ? `${i + 1}. ` : "";
+			return (
+				`${num}Commit ${c.shortHash} (${c.hash})\n` +
+				`   Subject: ${c.subject}\n` +
+				`   Author:  ${c.author} on ${c.date}\n` +
+				`   Stats:   ${c.filesChanged} file${c.filesChanged !== 1 ? "s" : ""} changed, +${c.insertions}/-${c.deletions} lines`
+			);
+		})
+		.join("\n\n");
+}
+
+/**
+ * Build the review prompt for the selected commits to send to the agent.
+ */
+export function formatCommitReviewPrompt(commits: SelectedCommit[]): string {
+	const count = commits.length;
+	const commitDetails = formatSelectedCommits(commits);
+
+	const showCmd = count === 1 ? `git show ${commits[0].hash}` : "git show <hash>";
+
+	return (
+		`Review the following git commit${count !== 1 ? "s" : ""}:\n\n` +
+		`${commitDetails}\n\n` +
+		`Please inspect the changes using \`${showCmd}\` (and any related files in the repository). ` +
+		`Double-check the changes for:\n` +
+		`1. Bugs, edge cases, potential regressions, and logic errors.\n` +
+		`2. Code quality, security, and unintended side effects.\n` +
+		`3. Consistency with surrounding project patterns and tests.\n\n` +
+		`Summarize your findings for each commit and propose a plan for any fixes if needed. Do not make changes yet.`
+	);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-do-always",
-	"version": "0.12.0",
+	"version": "0.13.0",
 	"type": "module",
 	"description": "Pi extension: /do-always — pick a common task by number, it fills your prompt",
 	"author": {