pi-do-always 0.12.0 → 0.15.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",
@@ -61,7 +80,7 @@
 			"category": "Ops",
 			"description": "Prepare a release (version, changelog, tag)",
 			"when": "git",
-			"prompt": "Prepare a release for this project (branch {{branch}}): check `git log` since the last tag, update the version in package.json (or the equivalent location), add a changelog entry summarizing the changes, and create a git tag if git present. Do not push."
+			"prompt": "Prepare a release for this project (branch {{branch}}): check `git log` since the last tag, then bump the version in package.json (or the equivalent location) to the next version, and add a changelog entry under that exact version summarizing the changes. The changelog entry must use the same version number now set in package.json — never add a changelog section for a version that package.json does not yet contain, and never leave an 'Unreleased' or placeholder version heading. Create a git tag if git present. Do not push."
 		},
 		{
 			"name": "Commit",