pi-do-always 0.7.0 → 0.9.0

package/README.md

@@ -12,21 +12,22 @@ type to filter, scroll or click, or navigate with arrows + Enter → the task's
   do-always — pick a task
 
   PLAN
-▸ 1. ⚡ Review             Review code and double-check changes (Plan)
-  2. ⚡ Cleanup            Clean up dead code and duplicates (Plan)
-  3. ⚡ Security           Security audit (Plan)
-  4. ⚡ Performance        Performance review (Plan)
-  5. ⚡ Propose features   Propose new features (Plan)
+▸ 1. ⚡ Review changes       Review the current code changes (Plan)
+  2. ⚡ Review code          Review the whole project's code quality (Plan)
+  3. ⚡ Cleanup              Clean up dead code and duplicates (Plan)
+  4. ⚡ Security             Security audit (Plan)
+  5. ⚡ Performance          Performance review (Plan)
+  6. ⚡ Propose features     Propose new features (Plan)
   DO
-  6. Build                Test build is ok and fix issues
-  7. Tests                Run tests and fix failures
+  7. Build                  Test build is ok and fix issues
+  8. Tests                  Run tests and fix failures
   DOCS
-  8. Readme               Update the README.md
+  9. Readme                 Update the README.md
   OPS
-  9. Release              Prepare a release (version, changelog, tag)
- 10. Commit               Prepare a clean commit
+ 10. Release               Prepare a release (version, changelog, tag)
+ 11. Commit                Prepare a clean commit
 
-  Review — prompt:
+  Review changes — prompt:
   Review the changes on branch fix/login-null (3 changed files: auth.ts, login.ts,
   test/auth.test.ts). Last commit: Fix null check in login. Check `git status` and
   `git diff` to see what changed, then double-check the changes for bugs, edge …
@@ -42,7 +43,7 @@ type to filter, scroll or click, or navigate with arrows + Enter → the task's
 |---|---|
 |`/do-always` or the shortcut key (default `F4`)|Show the numbered task selector|
 |`/do-always 2`|Fill the prompt for task #2 directly|
-|`/do-always review`|Fill the prompt for the task named `review` (task names autocomplete after `/do-always`)|
+|`/do-always review changes`|Fill the prompt for the task named `review changes` (task names autocomplete after `/do-always`)|
 |`/do-always list`|Print the task list|
 |`/do-always list-details`|Show the full rendered prompt text each task will inject|
 
@@ -87,7 +88,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, 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, 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:
 
@@ -133,7 +134,7 @@ Reload Pi (or start a new session) after editing a config file.
 ## Prompt placeholders
 
 Task prompts support `{{placeholders}}` that are filled in from the current
-directory when a task is selected — so `/do-always review` on a hotfix branch
+directory when a task is selected — so `/do-always review changes` on a hotfix branch
 injects “Review the changes on branch `fix/login-null` (3 changed files:
 `auth.ts`, `login.ts`, `test/auth.test.ts`) …” instead of a generic nudge.
 
@@ -146,6 +147,10 @@ injects “Review the changes on branch `fix/login-null` (3 changed files:
 |`{{files_changed}}`|Changed files from `git status` — comma-separated, capped at 20 entries (`none` when clean or not a git repo)|
 |`{{files_changed_count}}`|Number of changed files (`0` when clean or not a git repo)|
 |`{{user}}`|`git config user.name` (`unknown` when unset)|
+|`{{diff_stat}}`|`git diff --shortstat` output, e.g. `3 files changed, 41 insertions(+), 7 deletions(-)` (`none` when unavailable)|
+|`{{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)|
 
 Unknown placeholders are left as-is, and a prompt without placeholders is
 injected unchanged, so existing configs keep working. The selector preview and
@@ -197,7 +202,7 @@ The `guards` array accepts these guard objects (all must pass):
 
 | `type` | `value` | Blocks when… |
 |---|---|---|
-| `requireDirty` | none | the working tree is clean (`files_changed_count === 0`) |
+| `requireDirty` | none | the working tree is clean (no changed files) |
 | `requireBranch` | branch name | the current branch is not the given name |
 | `requireRepo` | repo name | the git-remote basename context value is not the given name |
 | `requireFilePattern` | glob | no changed file matches the glob |

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

@@ -2,15 +2,21 @@
 	"shortcut": "f4",
 	"tasks": [
 		{
-			"name": "Review",
+			"name": "Review changes",
 			"category": "Plan",
-			"description": "Review code and double-check changes (Plan)",
-			"prompt": "Review the changes on branch {{branch}} ({{files_changed_count}} changed files: {{files_changed}}). 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"
+			"description": "Review the current code changes (Plan)",
+			"requireDirty": 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)",
+			"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."
 		},
 		{
 			"name": "Cleanup",
 			"category": "Plan",
-			"autoRun": false,
 			"description": "Clean up dead code and duplicates (Plan)",
 			"prompt": "Scan the project for dead code, unused imports, commented-out blocks, and duplicated logic. Do a plan proposal for the removals and consolidations, keeping behavior unchanged. Do not make any changes yet."
 		},
@@ -54,13 +60,16 @@
 			"name": "Release",
 			"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."
 		},
 		{
 			"name": "Commit",
 			"category": "Ops",
 			"description": "Prepare a clean commit",
-			"prompt": "Prepare the working tree on branch {{branch}} ({{files_changed_count}} changed files: {{files_changed}}) for a clean commit: review `git status` and `git diff`, stage the relevant changes, and write a clear commit message describing what changed and why. Do not push."
+			"requireDirty": true,
+			"when": "git",
+			"prompt": "Prepare the working tree on branch {{branch}} ({{files_changed_count}} changed files: {{files_changed}}) for a clean commit: stage the relevant changes, and write a clear commit message describing what changed and why. Do not push."
 		}
 	]
 }

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

@@ -50,41 +50,51 @@ import {
 import {
 	DEFAULT_SHORTCUT,
 	DEFAULT_TASKS,
+	evaluateGuards,
+	evaluateWhen,
 	formatList,
 	groupTasksByCategory,
 	isValidKeyId,
 	mergeTasks,
 	parseConfig,
+	parseStatusPorcelain,
 	orderTasksByCategory,
 	renderPrompt,
-	evaluateGuards,
-	evaluateWhen,
 	resolveShortcut,
 	resolveTask,
 	shouldAutoRun,
+	splitFileLines,
+	toPromptContext,
 	type DoAlwaysTask,
-	type PromptContext,
+	type TaskContext,
 	type TaskGroup,
 } from "./tasks";
 
 /**
  * Load tasks and the selector shortcut from config files.
- * Project-local tasks override global tasks with the same name; new ones are appended.
- * Falls back to DEFAULT_TASKS when nothing is defined.
+ * Project-local tasks override global tasks with the same name (or are
+ * appended, per the `merge` field); new ones are appended. Falls back to
+ * DEFAULT_TASKS when nothing is defined.
+ *
+ * Validation problems (malformed JSON, invalid tasks/shortcut/merge/when/
+ * guards) are reported through `onError` — callers must wire it up, since
+ * the default is a silent no-op.
  */
-function loadConfig(cwd: string): {
+function loadConfig(
+	cwd: string,
+	onError: (message: string) => void = () => {},
+): {
 	tasks: DoAlwaysTask[];
 	shortcut: string | null;
-	merge: "append" | "override";
 } {
 	const globalPath = join(getAgentDir(), "do-always.json");
 	const projectPath = join(cwd, CONFIG_DIR_NAME, "do-always.json");
 
 	const global = existsSync(globalPath)
-		? parseConfig(readFileSync(globalPath, "utf-8"), globalPath)
+		? parseConfig(readFileSync(globalPath, "utf-8"), globalPath, onError)
 		: { tasks: [], shortcut: undefined, merge: undefined };
 	const project = existsSync(projectPath)
-		? parseConfig(readFileSync(projectPath, "utf-8"), projectPath)
+		? parseConfig(readFileSync(projectPath, "utf-8"), projectPath, onError)
 		: { tasks: [], shortcut: undefined, merge: undefined };
 
 	// The project file's merge mode wins; otherwise the global value; otherwise
@@ -96,7 +106,6 @@ function loadConfig(cwd: string): {
 		// `/do-always <n>`, and `list` all share one consistent order.
 		tasks: orderTasksByCategory(mergeTasks(global.tasks, project.tasks, DEFAULT_TASKS, mode)),
 		shortcut: resolveShortcut(global.shortcut, project.shortcut),
-		merge: mode,
 	};
 }
 
@@ -120,19 +129,19 @@ function git(cwd: string, args: string[]): string | undefined {
 	}
 }
 
-/** Max number of file paths listed in `files_changed` (the count stays exact). */
-const MAX_FILES_LISTED = 20;
-
 /**
- * Build the prompt context for `renderPrompt`. Always contains every
- * PROMPT_CONTEXT_KEYS entry: git facts fall back to neutral values when
- * unavailable (non-git dir, no git, empty repo) so default prompts read
- * cleanly in any directory.
+ * 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
+ * default prompts read cleanly in any directory. The string view for
+ * `renderPrompt` is derived with `toPromptContext`.
  */
-function buildContext(cwd: string): PromptContext {
+function buildContext(cwd: string): TaskContext {
 	const branch = git(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]) ?? "unknown";
 	const lastCommit = git(cwd, ["log", "-1", "--format=%s"]) ?? "unknown";
 	const user = git(cwd, ["config", "user.name"]) ?? "unknown";
+	// Authoritative working-tree check — the branch sentinel is not (a branch
+	// could literally be named "unknown", and detached HEAD reports "HEAD").
+	const isGitRepo = git(cwd, ["rev-parse", "--is-inside-work-tree"]) === "true";
 
 	// repo = bare name of the git remote (owner/repo.git -> repo), falling back
 	// to the basename of cwd so monorepo work stays disambiguated everywhere.
@@ -141,38 +150,18 @@ function buildContext(cwd: string): PromptContext {
 		? (remoteUrl.replace(/\.git$/, "").split("/").pop() ?? "unknown")
 		: cwd.split(/[\\/]/).filter(Boolean).pop() ?? "unknown";
 
-	const files: string[] = [];
-	const status = git(cwd, ["status", "--porcelain"]);
-	if (status) {
-		for (const line of status.split("\n")) {
-			// Porcelain v1 lines are "XY <path>" (X = index, Y = worktree).
-			if (line.length < 4) continue;
-			const path = line.slice(3);
-			if (path && !files.includes(path)) files.push(path);
-		}
-		files.sort();
-	}
-	let listed: string;
-	if (files.length === 0) {
-		listed = "none";
-	} else if (files.length > MAX_FILES_LISTED) {
-		listed = [...files.slice(0, MAX_FILES_LISTED), `… (+${files.length - MAX_FILES_LISTED} more)`].join(", ");
-	} else {
-		listed = files.join(", ");
-	}
-
 	return {
 		cwd,
 		date: new Date().toLocaleDateString("en-CA"), // local YYYY-MM-DD
 		branch,
-		last_commit: lastCommit,
-		files_changed: listed,
-		files_changed_count: String(files.length),
+		lastCommit,
+		files: parseStatusPorcelain(git(cwd, ["status", "--porcelain"]) ?? ""),
 		user,
-		diff_stat: git(cwd, ["diff", "--shortstat"]) ?? "none",
+		diffStat: git(cwd, ["diff", "--shortstat"]) ?? "none",
 		repo,
-		staged_files: git(cwd, ["diff", "--cached", "--name-only"]) ?? "none",
-		unstaged_files: git(cwd, ["diff", "--name-only"]) ?? "none",
+		stagedFiles: splitFileLines(git(cwd, ["diff", "--cached", "--name-only"])),
+		unstagedFiles: splitFileLines(git(cwd, ["diff", "--name-only"])),
+		isGitRepo,
 	};
 }
 
@@ -194,23 +183,62 @@ const PREVIEW_MAX_LINES = 3;
 export default function doAlwaysExtension(pi: ExtensionAPI) {
 	let tasks: DoAlwaysTask[] = [];
 	let loadedCwd = ""; // cwd the cached `tasks` were loaded for
+	// The visible (when-filtered) list for the last context we built, so
+	// argument completions number tasks the same way the selector and
+	// `/do-always <n>` do. When stale (or absent), completions fall back to
+	// the full list rather than guessing.
+	let visibleCache: { cwd: string; visible: DoAlwaysTask[] } | null = null;
+
+	/** Filter tasks by their `when` condition and refresh the completion cache. */
+	function refreshVisible(cwd: string, context: TaskContext): DoAlwaysTask[] {
+		const visible = tasks.filter((t) => evaluateWhen(t, context));
+		visibleCache = { cwd, visible };
+		return visible;
+	}
 
-	pi.on("session_start", async (_event, ctx) => {
+	/**
+	 * Register the selector shortcut from a resolved config value (null
+	 * disables it). Called from session_start so it reads the session's cwd,
+	 * not the process cwd; re-registering the same key is idempotent.
+	 */
+	function registerShortcut(shortcut: string | null, onError: (message: string) => void): void {
+		if (shortcut === null) return;
+		const shortcutKey = isValidKeyId(shortcut) ? shortcut : DEFAULT_SHORTCUT;
+		if (shortcutKey !== shortcut) {
+			onError(`do-always: invalid shortcut "${shortcut}" in do-always.json — using ${DEFAULT_SHORTCUT}`);
+		}
+		pi.registerShortcut(shortcutKey as KeyId, {
+			description: "do-always: pick a common task",
+			handler: async (ctx) => {
+				await runDoAlways("", ctx);
+			},
+		});
+	}
+
+	pi.on("session_start", (_event, ctx) => {
+		// Surface config validation problems (the README promises warnings);
+		// in non-TUI modes there is no UI, so fall back to the console.
+		const onError = (m: string) => {
+			if (ctx.mode === "tui") ctx.ui.notify(m, "warning");
+			else console.warn(m);
+		};
 		loadedCwd = ctx.cwd;
-		tasks = loadConfig(ctx.cwd).tasks;
+		const config = loadConfig(ctx.cwd, onError);
+		tasks = config.tasks;
+		refreshVisible(ctx.cwd, buildContext(ctx.cwd));
+		registerShortcut(config.shortcut, onError);
 	});
 
 	/** Put the task prompt into the editor (TUI) or send it as a user message (other modes). */
-	async function fillPrompt(task: DoAlwaysTask, ctx: ExtensionContext): Promise<void> {
-		// Render the prompt with the current context (branch, changed files, …)
-		// so the injected text matches this directory at this moment.
-		const context = buildContext(ctx.cwd);
+	async function fillPrompt(task: DoAlwaysTask, ctx: ExtensionContext, context: TaskContext): Promise<void> {
 		const blocked = evaluateGuards(task, context);
 		if (blocked) {
 			ctx.ui.notify(`do-always: ${blocked}`, "info");
 			return;
 		}
-		const prompt = renderPrompt(task.prompt, context);
+		// Render with the same context the selector/preview used, so what the
+		// user saw is exactly what gets injected.
+		const prompt = renderPrompt(task.prompt, toPromptContext(context));
 		if (shouldAutoRun(task)) {
 			await pi.sendUserMessage(prompt);
 			ctx.ui.notify(`do-always: auto-ran "${task.name}"`, "info");
@@ -227,15 +255,15 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 	/**
 	 * Numbered selector with categorized sections. Press 1-9 to pick by global
 	 * number, type to filter, or navigate with arrows + Enter, Esc to cancel.
+	 * The context is built once per command run (never inside the render loop
+	 * — no process spawning per frame) and shared with `fillPrompt`.
 	 */
-	async function showSelector(ctx: ExtensionContext): Promise<void> {
-		// Build the context once per selector session (never inside the render
-		// loop — no process spawning per frame). fillPrompt re-renders at
-		// selection time, so a few seconds of drift is acceptable.
-		const context = buildContext(ctx.cwd);
+	async function showSelector(ctx: ExtensionContext, context: TaskContext): 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));
+		// String view for prompt rendering (derived once, used by the preview).
+		const strings = toPromptContext(context);
 		const selected = await ctx.ui.custom<number | null>((tui, theme, _kb, done) => {
 			let settled = false;
 			let previewVisible = false;
@@ -381,7 +409,7 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 					if (sel) {
 						const wrapWidth = Math.max(10, width - 4);
 						// Show the rendered prompt — exactly what will be injected.
-						const wrapped = wrapTextWithAnsi(renderPrompt(sel.task.prompt, context), wrapWidth);
+						const wrapped = wrapTextWithAnsi(renderPrompt(sel.task.prompt, strings), wrapWidth);
 						const shown = wrapped.slice(0, PREVIEW_MAX_LINES);
 						const truncated = wrapped.length > PREVIEW_MAX_LINES;
 						lines.push("");
@@ -483,17 +511,22 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 		});
 
 		if (selected === null || selected === undefined) return;
-		await fillPrompt(tasks[selected], ctx);
+		await fillPrompt(tasks[selected], ctx, context);
 	}
 
 	pi.registerCommand("do-always", {
 		description: "Pick a common task (review, readme, ...) by number — fills the prompt",
 		getArgumentCompletions: (prefix) => {
 			const p = prefix.trim().toLowerCase();
+			// Number tasks by position in the VISIBLE (when-filtered) list — the
+			// same list the selector and `/do-always <n>` use. The cache is
+			// refreshed on session start and every command run; when it is
+			// stale, fall back to the full list rather than guessing.
+			const visible = visibleCache?.cwd === loadedCwd ? visibleCache.visible : tasks;
 			const matches = [
 				{ value: "list", label: "list" },
 				{ value: "list-details", label: "list-details" },
-				...tasks.map((t, i) => ({ value: t.name, label: `${i + 1}. ${t.name}` })),
+				...visible.map((t, i) => ({ value: t.name, label: `${i + 1}. ${t.name}` })),
 			].filter((c) => c.value.toLowerCase().includes(p));
 			return matches.length > 0 ? matches : null;
 		},
@@ -502,48 +535,35 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 		},
 	});
 
-	// Keyboard shortcut: open the task selector without typing the command.
-	// The key is configurable via the "shortcut" field in do-always.json
-	// (null disables it). It is read once at extension load, so changing it
-	// requires a reload or a new session.
-	const configuredShortcut = loadConfig(process.cwd()).shortcut;
-	if (configuredShortcut !== null) {
-		const shortcutKey = isValidKeyId(configuredShortcut) ? configuredShortcut : DEFAULT_SHORTCUT;
-		if (shortcutKey !== configuredShortcut) {
-			console.warn(`do-always: invalid shortcut "${configuredShortcut}" in do-always.json — using ${DEFAULT_SHORTCUT}`);
-		}
-		pi.registerShortcut(shortcutKey as KeyId, {
-			description: "do-always: pick a common task",
-			handler: async (ctx) => {
-				await runDoAlways("", ctx);
-			},
-		});
-	}
-
 	async function runDoAlways(args: string, ctx: ExtensionContext): Promise<void> {
 		// Reload when the active directory changes, so switching projects
 		// mid-session serves the right config instead of stale tasks.
 		if (ctx.cwd !== loadedCwd) {
 			loadedCwd = ctx.cwd;
-			tasks = loadConfig(ctx.cwd).tasks;
+			const onError = (m: string) => {
+				if (ctx.mode === "tui") ctx.ui.notify(m, "warning");
+				else console.warn(m);
+			};
+			tasks = loadConfig(ctx.cwd, onError).tasks;
 		}
 
+		// One context per command run: shared by visibility filtering, rendering,
+		// and the completion cache (never inside a render loop).
+		const context = buildContext(ctx.cwd);
+		const visible = refreshVisible(ctx.cwd, context);
+
 		const arg = args.trim();
 
 		if (!arg) {
 			if (ctx.mode === "tui") {
-				await showSelector(ctx);
+				await showSelector(ctx, context);
 			} else {
-				const context = buildContext(ctx.cwd);
-				const visible = tasks.filter((t) => evaluateWhen(t, context));
 				ctx.ui.notify(`do-always tasks (use /do-always <number|name>):\n${formatList(visible)}`, "info");
 			}
 			return;
 		}
 
 		if (arg.toLowerCase() === "list") {
-			const context = buildContext(ctx.cwd);
-			const visible = tasks.filter((t) => evaluateWhen(t, context));
 			ctx.ui.notify(formatList(visible), "info");
 			return;
 		}
@@ -551,14 +571,13 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 		if (arg.toLowerCase() === "list-details") {
 			// Display only — the description is metadata; selecting a task injects just its prompt.
 			// Render with the current context so what is shown is what gets injected.
-			const context = buildContext(ctx.cwd);
-			const visible = tasks.filter((t) => evaluateWhen(t, context));
+			const strings = toPromptContext(context);
 			const details = visible
 				.map((t, i) => {
 					const lines = [`${i + 1}. ${t.name}`];
 					if (t.description) lines.push(`   description: ${t.description}`);
 					lines.push("   prompt (this is what gets injected on select):");
-					for (const line of renderPrompt(t.prompt, context).split("\n")) lines.push(`   ${line}`);
+					for (const line of renderPrompt(t.prompt, strings).split("\n")) lines.push(`   ${line}`);
 					return lines.join("\n");
 				})
 				.join("\n\n");
@@ -573,8 +592,6 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 		// Numbers index the VISIBLE list (what the user sees in the selector and
 		// `list`); names resolve against the full set so picking a hidden task by
 		// name gets an explanatory message below instead of "unknown task".
-		const context = buildContext(ctx.cwd);
-		const visible = tasks.filter((t) => evaluateWhen(t, context));
 		const task = resolveTask(/^\d+$/.test(arg) ? visible : tasks, arg);
 		if (!task) {
 			const available = visible.map((t, i) => `${i + 1}=${t.name}`).join(", ");
@@ -587,6 +604,6 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 			ctx.ui.notify(`do-always: "${task.name}" is hidden by its "when" condition`, "info");
 			return;
 		}
-		await fillPrompt(task, ctx);
+		await fillPrompt(task, ctx, context);
 	}
 }

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

@@ -98,6 +98,44 @@ export interface ParsedDoAlwaysConfig {
 	merge?: "append" | "override" | undefined;
 }
 
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Structured facts about the working tree and git state, gathered once per
+ * use (see `buildContext` in index.ts). `when` conditions and guards are
+ * evaluated against this; `renderPrompt` consumes the derived string view
+ * from `toPromptContext`.
+ *
+ * Keeping the structured form here (instead of re-parsing the rendered
+ * strings) means guards see the complete file list — `files_changed` in the
+ * string view is capped for display, but `files` is never truncated.
+ */
+export interface TaskContext {
+	/** Absolute path of the working directory. */
+	cwd: string;
+	/** Local date, YYYY-MM-DD. */
+	date: string;
+	/** Current git branch, or "unknown" when unavailable. */
+	branch: string;
+	/** Subject of the latest commit, or "unknown" when unavailable. */
+	lastCommit: string;
+	/** All changed files (staged, unstaged, untracked), deduplicated and sorted. */
+	files: string[];
+	/** `git config user.name`, or "unknown" when unset. */
+	user: string;
+	/** Output of `git diff --shortstat`, or "none" when unavailable. */
+	diffStat: string;
+	/** Basename of the git remote (or cwd), to disambiguate monorepo work. */
+	repo: string;
+	/** Files staged for commit. */
+	stagedFiles: string[];
+	/** Modified-but-unstaged files. */
+	unstagedFiles: string[];
+	/** True when cwd is inside a git working tree (authoritative, not inferred from the branch name). */
+	isGitRepo: boolean;
+}
+
 /**
  * The set of context keys the extension can inject into prompts (see
  * `renderPrompt`). `index.ts` is responsible for supplying all of them (with
@@ -112,24 +150,82 @@ export const PROMPT_CONTEXT_KEYS = [
 	"files_changed",
 	"files_changed_count",
 	"user",
-	"diff_stat", // NEW: "3 files changed, 41 insertions(+), 7 deletions(-)"
-	"repo", // NEW: basename of cwd or git remote (disambiguates monorepos)
-	"staged_files", // NEW: files staged for commit
-	"unstaged_files", // NEW: modified-but-unstaged files
+	"diff_stat",
+	"repo",
+	"staged_files",
+	"unstaged_files",
 ] as const;
 
 /** A fully populated prompt context: one entry per PROMPT_CONTEXT_KEYS. */
 export type PromptContext = Record<(typeof PROMPT_CONTEXT_KEYS)[number], string>;
 
-import { existsSync } from "node:fs";
-import { join } from "node:path";
+/** Max number of file paths listed in the `files_changed` string view (the count stays exact). */
+export const MAX_FILES_LISTED = 20;
+
+/**
+ * Derive the string view consumed by `renderPrompt` from a structured context.
+ * `files_changed` lists at most MAX_FILES_LISTED paths (with a "… (+N more)"
+ * suffix) and `files_changed_count` stays exact; `staged_files` and
+ * `unstaged_files` are newline-separated. Empty lists render as "none".
+ */
+export function toPromptContext(ctx: TaskContext): PromptContext {
+	return {
+		cwd: ctx.cwd,
+		date: ctx.date,
+		branch: ctx.branch,
+		last_commit: ctx.lastCommit,
+		files_changed: formatFileList(ctx.files),
+		files_changed_count: String(ctx.files.length),
+		user: ctx.user,
+		diff_stat: ctx.diffStat,
+		repo: ctx.repo,
+		staged_files: formatFileLines(ctx.stagedFiles),
+		unstaged_files: formatFileLines(ctx.unstagedFiles),
+	};
+}
+
+/** Comma-joined list, capped at MAX_FILES_LISTED entries; "none" when empty. */
+function formatFileList(files: string[]): string {
+	if (files.length === 0) return "none";
+	if (files.length > MAX_FILES_LISTED) {
+		return [...files.slice(0, MAX_FILES_LISTED), `… (+${files.length - MAX_FILES_LISTED} more)`].join(", ");
+	}
+	return files.join(", ");
+}
+
+/** Newline-joined list; "none" when empty. */
+function formatFileLines(files: string[]): string {
+	return files.length === 0 ? "none" : files.join("\n");
+}
+
+/**
+ * Parse `git status --porcelain` (v1) output into changed file paths. Lines
+ * are "XY <path>" (X = index, Y = worktree); short lines are skipped,
+ * duplicates removed, and the result sorted.
+ */
+export function parseStatusPorcelain(status: string): string[] {
+	const files: string[] = [];
+	for (const line of status.split("\n")) {
+		if (line.length < 4) continue;
+		const path = line.slice(3);
+		if (path && !files.includes(path)) files.push(path);
+	}
+	files.sort();
+	return files;
+}
+
+/** Split raw `git diff --name-only` output into file paths (trimmed, non-empty lines). */
+export function splitFileLines(raw: string | undefined): string[] {
+	if (!raw) return [];
+	return raw.split("\n").map((line) => line.trim()).filter(Boolean);
+}
 
 /** Used when neither config file defines any task. */
 export const DEFAULT_TASKS: DoAlwaysTask[] = [
 	{
-		name: "Review",
+		name: "Review changes",
 		category: "Plan",
-		description: "Review code and double-check changes (Plan)",
+		description: "Review the current code changes (Plan)",
 		requireDirty: true,
 		prompt:
 			"Review the changes on branch {{branch}} ({{files_changed_count}} changed files: {{files_changed}}). " +
@@ -138,6 +234,14 @@ export const DEFAULT_TASKS: DoAlwaysTask[] = [
 			"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)",
+		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.",
+	},
 	{
 		name: "Cleanup",
 		category: "Plan",
@@ -407,15 +511,6 @@ export function isValidWhen(when: unknown): boolean {
 	return true;
 }
 
-/**
- * True when the current directory is inside a git working tree. The `branch`
- * context falls back to "unknown" outside a repo (and on an empty repo), so a
- * non-"unknown" branch is the git-repo signal.
- */
-function isGitRepo(ctx: PromptContext): boolean {
-	return ctx.branch !== "unknown";
-}
-
 /** True when `relativePath` exists (as file or directory) under `cwd`. */
 function pathExists(cwd: string, relativePath: string): boolean {
 	try {
@@ -426,14 +521,14 @@ function pathExists(cwd: string, relativePath: string): boolean {
 }
 
 /**
- * Evaluate a single `when` object entry against the current prompt context.
+ * Evaluate a single `when` object entry against the current context.
  * Unknown keys are treated as no-ops (permissive) so a typo never hides a task
  * at runtime (parse time rejects them with a warning instead).
  */
-function evaluateWhenEntry(key: string, value: unknown, ctx: PromptContext): boolean {
+function evaluateWhenEntry(key: string, value: unknown, ctx: TaskContext): boolean {
 	switch (key) {
 		case "git":
-			return typeof value === "boolean" ? isGitRepo(ctx) === value : false;
+			return typeof value === "boolean" ? ctx.isGitRepo === value : false;
 		case "branch":
 			return typeof value === "string" && ctx.branch === value;
 		case "file":
@@ -454,13 +549,13 @@ function evaluateWhenEntry(key: string, value: unknown, ctx: PromptContext): boo
  * set of conditions that must all hold (logical AND): `git`, `branch`, `file`,
  * or `repo` (see the `DoAlwaysTask.when` field).
  */
-export function evaluateWhen(task: DoAlwaysTask, ctx: PromptContext): boolean {
+export function evaluateWhen(task: DoAlwaysTask, ctx: TaskContext): boolean {
 	const when = task.when;
 	if (when === undefined || when === null) return true;
 	if (typeof when === "string") {
 		const negated = when.startsWith("!");
 		const key = negated ? when.slice(1) : when;
-		if (key === "git") return negated ? !isGitRepo(ctx) : isGitRepo(ctx);
+		if (key === "git") return negated ? !ctx.isGitRepo : ctx.isGitRepo;
 		return true; // an invalid string condition is rejected at parse time
 	}
 	if (typeof when === "object") {
@@ -542,7 +637,7 @@ export function shouldAutoRun(task: DoAlwaysTask): boolean {
  * Guards keep low-value round-trips down: e.g. `requireDirty` blocks Review and
  * Commit on a clean tree so the agent is never asked to inspect nothing.
  */
-export function evaluateGuards(task: DoAlwaysTask, ctx: PromptContext): string | null {
+export function evaluateGuards(task: DoAlwaysTask, ctx: TaskContext): string | null {
 	// Legacy `requireDirty` is folded into the guard table so the set of guards
 	// is extensible without touching this function's callers.
 	const guards: Guard[] = [];
@@ -560,38 +655,31 @@ export function evaluateGuards(task: DoAlwaysTask, ctx: PromptContext): string |
  * when the guard passes. All guards are evaluated against the current prompt
  * context, so a task is only injected when every guard is met.
  */
-function guardFailureMessage(g: Guard, ctx: PromptContext): string | null {
+function guardFailureMessage(g: Guard, ctx: TaskContext): string | null {
 	switch (g.type) {
 		case "requireDirty":
-			return ctx.files_changed_count === "0" ? "working tree is clean — nothing to review" : null;
+			return ctx.files.length === 0 ? "working tree is clean — nothing to review" : null;
 		case "requireBranch":
 			return ctx.branch === g.value ? null : `not on branch "${g.value}" (currently ${ctx.branch})`;
 		case "requireRepo":
 			return ctx.repo === g.value ? null : `not in repo "${g.value}" (currently ${ctx.repo})`;
 		case "requireFilePattern":
-			return filesMatchPattern(ctx, g.value!) ? null : `no changed files match "${g.value}"`;
+			return filesMatchPattern(ctx.files, g.value!) ? null : `no changed files match "${g.value}"`;
 		default:
 			return null; // an unknown type is rejected at parse time
 	}
 }
 
-/**
- * The changed files for `ctx`, split on commas (matching how `files_changed`
- * is rendered). Empty on a clean tree or outside a git repo.
- */
-function changedFiles(ctx: PromptContext): string[] {
-	if (ctx.files_changed_count === "0" || ctx.files_changed === "none") return [];
-	return ctx.files_changed.split(",");
-}
-
 /**
  * Whether any changed file matches `pattern`, treated as a glob: `*` matches
  * within a path segment, `**` crosses segments, `?` matches one non-separator
- * character, and other regex metacharacters are literal.
+ * character, and other regex metacharacters are literal. Matches against the
+ * complete file list (never the capped display string), so files beyond
+ * MAX_FILES_LISTED are still considered.
  */
-function filesMatchPattern(ctx: PromptContext, pattern: string): boolean {
+function filesMatchPattern(files: string[], pattern: string): boolean {
 	const re = globToRegex(pattern);
-	return changedFiles(ctx).some((f) => re.test(f.trim()));
+	return files.some((f) => re.test(f));
 }
 
 /** Regex metacharacters that must be escaped when matching a literal path char. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-do-always",
-	"version": "0.7.0",
+	"version": "0.9.0",
 	"type": "module",
 	"description": "Pi extension: /do-always — pick a common task by number, it fills your prompt",
 	"author": {
@@ -23,7 +23,7 @@
 	},
 	"homepage": "https://github.com/aginies/pi-do-always",
 	"bugs": {
-		"url": "https://github.com/aginies/pi-do-always/issues"
+		"url": "git+https://github.com/aginies/pi-do-always/issues"
 	},
 	"files": [
 		"extensions/pi-do-always/index.ts",