pi-do-always 0.4.5 → 0.6.0

package/README.md

@@ -109,10 +109,24 @@ Fields:
 - `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.
+- `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`.
 
 In the object form you can also configure the selector shortcut:
 
 - `shortcut` (optional) — key that opens the selector, e.g. `"f4"`. Set to `null` to disable the shortcut. Defaults to `F4`. The project file's value wins over the global one.
+- `merge` (optional) — how project tasks combine with the global tasks: `"override"` (default) replaces a global task with the same `name`; `"append"` keeps the global tasks and only adds new project task names (a cascade, like CSS). The project file's value wins over the global one; when neither sets it, the default is `override` (the historical behavior).
+
+Example project file that only *adds* tasks without overriding the global set:
+
+```json
+{
+  "merge": "append",
+  "tasks": [
+    { "name": "deploy", "category": "Ops", "prompt": "Deploy this project to staging." }
+  ]
+}
+```
 
 Reload Pi (or start a new session) after editing a config file.
 
@@ -138,6 +152,71 @@ injected unchanged, so existing configs keep working. The selector preview and
 `/do-always list-details` show the rendered prompt — what you see is what gets
 injected.
 
+## Conditionals
+
+A task's `when` field controls whether it is shown in the selector and in
+`/do-always list` / `list-details`. When the condition is not met the task is
+hidden everywhere (including when picked by number or name), so it can never
+be selected into a no-op. Omitting `when` always shows the task.
+
+The string form is a single condition:
+
+- `"git"` — shown only inside a git working tree.
+- `"!git"` — shown only outside a git working tree.
+
+The object form is a set of conditions that must **all** hold (logical AND):
+
+| Key | Meaning |
+|---|---|
+| `"git": boolean` | `true` inside a git repo, `false` outside |
+| `"branch": string` | current branch equals the given name (exact match) |
+| `"file": string` | path exists (file or directory) relative to the working tree |
+| `"repo": string` | equals the git-remote basename context value |
+
+```json
+[
+  { "name": "review", "category": "Plan", "prompt": "Review the changes…", "when": "git" },
+  { "name": "deploy-staging", "category": "Ops", "prompt": "Deploy to staging.", "when": { "branch": "main" } },
+  { "name": "lint-js", "category": "Do", "prompt": "Lint the JavaScript.", "when": { "file": "package.json" } }
+]
+```
+
+An invalid `when` (wrong type, unknown key) is ignored with a warning and the
+task is shown, so a typo never silently hides a task. Reload Pi (or start a new
+session) after editing a config file.
+
+## Guards
+
+Guards keep low-value round-trips down: the task stays visible, but selecting it
+notifies with the reason instead of injecting a no-op prompt. Guards are
+evaluated against the current prompt context, so a task is only injected when
+**every** guard is met. `requireDirty` (boolean, the historical guard) is
+combined with any `guards` array.
+
+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`) |
+| `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 |
+
+For `requireFilePattern`, `*` matches within a path segment, `**` crosses
+segments, `?` matches one non-separator character, and other regex
+metacharacters are literal.
+
+```json
+[
+  { "name": "deploy-staging", "category": "Ops", "prompt": "Deploy to staging.", "guards": [ { "type": "requireBranch", "value": "main" } ] },
+  { "name": "lint-tests", "category": "Do", "prompt": "Run the test suite.", "guards": [ { "type": "requireFilePattern", "value": "**/*.test.ts" } ] }
+]
+```
+
+An invalid guard (unknown `type`, missing `value`, or a non-array `guards`)
+is ignored with a warning, so a typo never silently disables a guard. Reload Pi
+(or start a new session) after editing a config file.
+
 ## Development
 
 ```bash

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

@@ -58,6 +58,7 @@ import {
 	orderTasksByCategory,
 	renderPrompt,
 	evaluateGuards,
+	evaluateWhen,
 	resolveShortcut,
 	resolveTask,
 	shouldAutoRun,
@@ -71,22 +72,31 @@ import {
  * Project-local tasks override global tasks with the same name; new ones are appended.
  * Falls back to DEFAULT_TASKS when nothing is defined.
  */
-function loadConfig(cwd: string): { tasks: DoAlwaysTask[]; shortcut: string | null } {
+function loadConfig(cwd: string): {
+	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)
-		: { tasks: [], shortcut: undefined };
+		: { tasks: [], shortcut: undefined, merge: undefined };
 	const project = existsSync(projectPath)
 		? parseConfig(readFileSync(projectPath, "utf-8"), projectPath)
-		: { tasks: [], shortcut: undefined };
+		: { tasks: [], shortcut: undefined, merge: undefined };
+
+	// The project file's merge mode wins; otherwise the global value; otherwise
+	// override (the historical behavior), so existing configs are unaffected.
+	const mode = project.merge ?? global.merge ?? "override";
 
 	return {
 		// Order the merged list by category so the selector numbers, digit-pick,
 		// `/do-always <n>`, and `list` all share one consistent order.
-		tasks: orderTasksByCategory(mergeTasks(global.tasks, project.tasks, DEFAULT_TASKS)),
+		tasks: orderTasksByCategory(mergeTasks(global.tasks, project.tasks, DEFAULT_TASKS, mode)),
 		shortcut: resolveShortcut(global.shortcut, project.shortcut),
+		merge: mode,
 	};
 }
 
@@ -223,6 +233,9 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 		// 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);
+		// 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));
 		const selected = await ctx.ui.custom<number | null>((tui, theme, _kb, done) => {
 			let settled = false;
 			let previewVisible = false;
@@ -235,11 +248,15 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 				}
 			}
 
-			const finish = (value: number | null) => {
+			// `finish` receives the chosen task (or null) and translates it to the
+			// full index `tasks[selected]` expects. Reference-based, so it stays
+			// correct while a text filter is active (itemRows is then a subset of
+			// visibleTasks and positional indices would point at the wrong task).
+			const finish = (task: DoAlwaysTask | null) => {
 				if (settled) return;
 				settled = true;
 				clearPreviewTimer();
-				done(value);
+				done(task ? tasks.indexOf(task) : null);
 			};
 
 			// The prompt preview appears only after the selection has been stable
@@ -257,7 +274,7 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 			}
 
 			// Group tasks under category headers, in a stable order.
-			const groups = groupTasksByCategory(tasks);
+			const groups = groupTasksByCategory(visibleTasks);
 
 			const kb = getKeybindings();
 			const maxVisible = 12;
@@ -347,7 +364,7 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 							continue;
 						}
 						if (!visibleItemKeys.has(row.task)) continue;
-						const globalIndex = tasks.indexOf(row.task);
+						const globalIndex = visibleTasks.indexOf(row.task);
 						const isSelected = row.task === itemRows[selectedIndex].task;
 						lines.push(renderLabel(row.task, globalIndex, isSelected, width));
 						itemLine.set(lines.length - 1, row.task);
@@ -391,10 +408,10 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 				},
 				invalidate() {},
 				handleInput(data: string) {
-					// Direct pick by number (1-9) — only when not filtering, so
-					// digits can be typed into the filter otherwise.
-					if (!filter && /^[1-9]$/.test(data) && Number(data) <= tasks.length) {
-						finish(Number(data) - 1);
+					// Direct pick by number (1-9) — only when not filtering, and within
+					// the visible set, so digits pick a visible task by its number.
+					if (!filter && /^[1-9]$/.test(data) && Number(data) <= visibleTasks.length) {
+						finish(visibleTasks[Number(data) - 1]);
 						return;
 					}
 					// Filter typing.
@@ -426,7 +443,7 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 					}
 					else if (kb.matches(data, "tui.select.confirm")) {
 						const chosen = itemRows[selectedIndex];
-						if (chosen) finish(tasks.indexOf(chosen.task));
+						if (chosen) finish(chosen.task);
 					}
 					else if (kb.matches(data, "tui.select.cancel")) {
 						finish(null);
@@ -459,7 +476,7 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 					const clicked = mousePressedIndex ?? idx;
 					mousePressedIndex = null;
 					const chosen = itemRows[clicked];
-					if (chosen) finish(tasks.indexOf(chosen.task));
+					if (chosen) finish(chosen.task);
 					return { handled: true };
 				},
 			};
@@ -517,13 +534,17 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 			if (ctx.mode === "tui") {
 				await showSelector(ctx);
 			} else {
-				ctx.ui.notify(`do-always tasks (use /do-always <number|name>):\n${formatList(tasks)}`, "info");
+				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") {
-			ctx.ui.notify(formatList(tasks), "info");
+			const context = buildContext(ctx.cwd);
+			const visible = tasks.filter((t) => evaluateWhen(t, context));
+			ctx.ui.notify(formatList(visible), "info");
 			return;
 		}
 
@@ -531,7 +552,8 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 			// 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 details = tasks
+			const visible = tasks.filter((t) => evaluateWhen(t, context));
+			const details = visible
 				.map((t, i) => {
 					const lines = [`${i + 1}. ${t.name}`];
 					if (t.description) lines.push(`   description: ${t.description}`);
@@ -548,12 +570,23 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 			return;
 		}
 
-		const task = resolveTask(tasks, arg);
+		// 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 = tasks.map((t, i) => `${i + 1}=${t.name}`).join(", ");
+			const available = visible.map((t, i) => `${i + 1}=${t.name}`).join(", ");
 			ctx.ui.notify(`do-always: unknown task "${arg}". Available: ${available}`, "error");
 			return;
 		}
+		// Respect the task's `when` condition: never inject a task hidden for the
+		// current environment (the selector and lists already hide it).
+		if (!evaluateWhen(task, context)) {
+			ctx.ui.notify(`do-always: "${task.name}" is hidden by its "when" condition`, "info");
+			return;
+		}
 		await fillPrompt(task, ctx);
 	}
 }

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

@@ -26,14 +26,59 @@ export interface DoAlwaysTask {
 	 * against the current prompt context (see `evaluateGuards`).
 	 */
 	requireDirty?: boolean;
+	/**
+	 * Environment condition controlling whether the task is shown in the
+	 * selector and lists. A string is a single condition ("git" | "!git"); an
+	 * object is a set of conditions that must all hold (logical AND):
+	 *   "git": boolean   — inside a git repo (true) or not (false)
+	 *   "branch": string — current branch equals the given name (exact match)
+	 *   "file": string   — a path that must exist in the working tree
+	 *   "repo": string   — equals the git-remote basename context value
+	 * Omitted/undefined always shows the task. Evaluated by `evaluateWhen`.
+	 */
+	when?: string | Record<string, unknown>;
+	/**
+	 * Extra selection-time guards, evaluated alongside the legacy `requireDirty`
+	 * (see `evaluateGuards`). Each guard blocks the task (with a message, not a
+	 * hide) when its condition is not met. `requireDirty` is kept for backward
+	 * compatibility; new guards use this array so the set is extensible.
+	 */
+	guards?: Guard[];
 }
 
+/**
+ * A selection-time guard that blocks a task when its condition is not met.
+ * The task stays visible but selecting it notifies instead of injecting.
+ * `requireDirty` needs no `value`; the others require a string `value`.
+ */
+export interface Guard {
+	type: "requireDirty" | "requireBranch" | "requireRepo" | "requireFilePattern";
+	value?: string;
+}
+
+/** The set of known guard types (used for validation at parse time). */
+export const GUARD_TYPES = [
+	"requireDirty",
+	"requireBranch",
+	"requireRepo",
+	"requireFilePattern",
+] as const;
+
 /**
  * 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
  * the keyboard shortcut.
+ * `merge` controls how project tasks combine with global tasks:
+ * `override` (default) replaces a global task with the same name;
+ * `append` keeps globals and only adds new project task names (a cascade).
  */
-export type DoAlwaysConfig = DoAlwaysTask[] | { tasks: DoAlwaysTask[]; shortcut?: string | null };
+export type DoAlwaysConfig =
+	| DoAlwaysTask[]
+	| {
+			tasks: DoAlwaysTask[];
+			shortcut?: string | null;
+			merge?: "append" | "override";
+		};
 
 /** Shortcut used when neither config file specifies one. */
 export const DEFAULT_SHORTCUT = "f4";
@@ -46,6 +91,11 @@ export interface ParsedDoAlwaysConfig {
 	 * disabled, undefined when the file does not set one.
 	 */
 	shortcut: string | null | undefined;
+	/**
+	 * The `merge` field, if present: "append" or "override", undefined when the
+	 * file does not set one.
+	 */
+	merge?: "append" | "override" | undefined;
 }
 
 /**
@@ -71,6 +121,9 @@ export const PROMPT_CONTEXT_KEYS = [
 /** 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";
+
 /** Used when neither config file defines any task. */
 export const DEFAULT_TASKS: DoAlwaysTask[] = [
 	{
@@ -131,6 +184,7 @@ export const DEFAULT_TASKS: DoAlwaysTask[] = [
 		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.",
 	},
@@ -139,6 +193,7 @@ export const DEFAULT_TASKS: DoAlwaysTask[] = [
 		category: "Ops",
 		description: "Prepare a clean commit",
 		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.",
 	},
@@ -185,25 +240,48 @@ export function parseConfig(
 				name: t.name,
 				prompt: t.prompt,
 			};
-			if (typeof t.description === "string") task.description = t.description;
-			if (typeof t.category === "string" && t.category.trim() !== "") task.category = t.category.trim();
+				if (typeof t.description === "string") task.description = t.description;
+				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;
-				tasks.push(task);
+				if (t.guards !== undefined) {
+					if (Array.isArray(t.guards)) {
+						const guards: Guard[] = [];
+						for (const g of t.guards) {
+							const parsed = parseGuard(g, path, onError);
+							if (parsed) guards.push(parsed);
+						}
+						if (guards.length > 0) task.guards = guards;
+					} else {
+						onError(`do-always: ignoring invalid "guards" in ${path} (expected an array of guards)`);
+					}
+				}
+				if (t.when !== undefined) {
+				if (isValidWhen(t.when)) {
+					task.when = t.when;
+				} else {
+					onError(`do-always: ignoring invalid "when" in ${path} (expected "git"/"!git" or an object of git|branch|file|repo conditions)`);
+				}
+			}
+			tasks.push(task);
 		} else {
 			onError(`do-always: skipping invalid task in ${path} (each task needs "name" and "prompt")`);
 		}
 	}
 
 	let shortcut: string | null | undefined;
+	let merge: "append" | "override" | undefined;
 	if (!Array.isArray(data) && "shortcut" in data) {
 		const s = data.shortcut;
 		if (s === null) shortcut = null;
 		else if (typeof s === "string") shortcut = s.trim() === "" ? null : s.trim();
 		else onError(`do-always: ignoring invalid "shortcut" in ${path} (expected a key string or null)`);
 	}
+	if (!Array.isArray(data) && "merge" in data) {
+		merge = parseMerge(data.merge, path, onError);
+	}
 
-	return { tasks, shortcut };
+	return { tasks, shortcut, merge };
 }
 
 const KEY_MODIFIERS = new Set(["ctrl", "shift", "alt", "super"]);
@@ -242,12 +320,53 @@ export function resolveShortcut(
 	return DEFAULT_SHORTCUT;
 }
 
+/**
+ * Parse the optional `merge` field: "append" or "override" (case-insensitive),
+ * or undefined when absent. A non-string or unrecognized value is ignored with
+ * a warning, so it never silently changes behavior.
+ */
+function parseMerge(
+	raw: unknown,
+	path: string,
+	onError: (message: string) => void,
+): "append" | "override" | undefined {
+	if (raw === undefined) return undefined;
+	if (typeof raw !== "string") {
+		onError(`do-always: ignoring invalid "merge" in ${path} (expected "append" or "override")`);
+		return undefined;
+	}
+	const v = raw.trim().toLowerCase();
+	if (v === "append" || v === "override") return v;
+	onError(`do-always: ignoring invalid "merge" in ${path} (expected "append" or "override")`);
+	return undefined;
+}
+
 /**
  * Merge project-local tasks over global tasks.
- * A project task with a name matching a global task replaces it; new names are appended.
+ *
+ * When `mode` is "override" (default), a project task with a name matching a
+ * global task replaces it; new names are appended. When "append", globals are
+ * kept as-is and only new (non-duplicate) project task names are appended.
  * Returns fallback when the merged result is empty.
  */
-export function mergeTasks(globalTasks: DoAlwaysTask[], projectTasks: DoAlwaysTask[], fallback: DoAlwaysTask[]): DoAlwaysTask[] {
+export function mergeTasks(
+	globalTasks: DoAlwaysTask[],
+	projectTasks: DoAlwaysTask[],
+	fallback: DoAlwaysTask[],
+	mode: "append" | "override" = "override",
+): DoAlwaysTask[] {
+	if (mode === "append") {
+		const merged = [...globalTasks];
+		const names = new Set(merged.map((t) => t.name));
+		for (const task of projectTasks) {
+			if (!names.has(task.name)) {
+				merged.push(task);
+				names.add(task.name);
+			}
+		}
+		return merged.length > 0 ? merged : fallback;
+	}
+
 	const merged = [...globalTasks];
 	for (const task of projectTasks) {
 		const idx = merged.findIndex((t) => t.name === task.name);
@@ -257,6 +376,102 @@ export function mergeTasks(globalTasks: DoAlwaysTask[], projectTasks: DoAlwaysTa
 	return merged.length > 0 ? merged : fallback;
 }
 
+/**
+ * Validate the shape of a `when` condition: the string "git" or "!git", or an
+ * object whose entries are all known condition keys with matching value types
+ * (`git` -> boolean; `branch`/`file`/`repo` -> string). Used by `parseConfig`
+ * to reject malformed conditions with a warning instead of silently changing
+ * behavior.
+ */
+export function isValidWhen(when: unknown): boolean {
+	if (typeof when === "string") {
+		return when === "git" || when === "!git";
+	}
+	if (typeof when !== "object" || when === null || Array.isArray(when)) {
+		return false;
+	}
+	for (const [key, value] of Object.entries(when as Record<string, unknown>)) {
+		switch (key) {
+			case "git":
+				if (typeof value !== "boolean") return false;
+				break;
+			case "branch":
+			case "file":
+			case "repo":
+				if (typeof value !== "string") return false;
+				break;
+			default:
+				return false; // unknown condition key
+		}
+	}
+	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 {
+		return existsSync(join(cwd, relativePath));
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Evaluate a single `when` object entry against the current prompt 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 {
+	switch (key) {
+		case "git":
+			return typeof value === "boolean" ? isGitRepo(ctx) === value : false;
+		case "branch":
+			return typeof value === "string" && ctx.branch === value;
+		case "file":
+			return typeof value === "string" && pathExists(ctx.cwd, value);
+		case "repo":
+			return typeof value === "string" && ctx.repo === value;
+		default:
+			return true;
+	}
+}
+
+/**
+ * Evaluate a task's `when` condition against the current prompt context.
+ * Returns true when the task should be shown, false when its condition is not
+ * met. An omitted/undefined condition always shows the task.
+ *
+ * The string form is a single condition ("git" | "!git"). The object form is a
+ * 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 {
+	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);
+		return true; // an invalid string condition is rejected at parse time
+	}
+	if (typeof when === "object") {
+		for (const [key, value] of Object.entries(when as Record<string, unknown>)) {
+			if (!evaluateWhenEntry(key, value, ctx)) return false;
+		}
+		return true;
+	}
+	return true;
+}
+
 /** Default order for category headers in the selector. */
 export const DEFAULT_CATEGORY_ORDER = ["Plan", "Do", "Docs", "Ops", "Other"];
 
@@ -328,12 +543,117 @@ export function shouldAutoRun(task: DoAlwaysTask): boolean {
  * Commit on a clean tree so the agent is never asked to inspect nothing.
  */
 export function evaluateGuards(task: DoAlwaysTask, ctx: PromptContext): string | null {
-	if (task.requireDirty && ctx.files_changed_count === "0") {
-		return "working tree is clean — nothing to review";
+	// Legacy `requireDirty` is folded into the guard table so the set of guards
+	// is extensible without touching this function's callers.
+	const guards: Guard[] = [];
+	if (task.requireDirty) guards.push({ type: "requireDirty" });
+	guards.push(...(task.guards ?? []));
+	for (const g of guards) {
+		const message = guardFailureMessage(g, ctx);
+		if (message) return message;
 	}
 	return null;
 }
 
+/**
+ * The blocking message a guard produces when its condition is unmet, or null
+ * 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 {
+	switch (g.type) {
+		case "requireDirty":
+			return ctx.files_changed_count === "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}"`;
+		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.
+ */
+function filesMatchPattern(ctx: PromptContext, pattern: string): boolean {
+	const re = globToRegex(pattern);
+	return changedFiles(ctx).some((f) => re.test(f.trim()));
+}
+
+/** Regex metacharacters that must be escaped when matching a literal path char. */
+const METACHARACTERS = ".+^${}()|[]";
+
+/** Convert a glob to an anchored RegExp (`**` -> `.*`, `*` -> `[^/]*`, `?` -> `[^/]`). */
+function globToRegex(pattern: string): RegExp {
+	let out = "";
+	let i = 0;
+	while (i < pattern.length) {
+		const c = pattern[i];
+		if (c === "*") {
+			let stars = 0;
+			while (i < pattern.length && pattern[i] === "*") {
+				stars++;
+				i++;
+			}
+			out += stars >= 2 ? ".*" : "[^/]*"; // `**` crosses path separators
+		} else if (c === "?") {
+			out += "[^/]";
+			i++;
+		} else {
+			out += METACHARACTERS.includes(c) ? "\\" + c : c;
+			i++;
+		}
+	}
+	return new RegExp(`^${out}$`);
+}
+
+/**
+ * Validate and normalize a single `guards` entry. Returns undefined (after
+ * warning) for an invalid entry so it is skipped rather than changing behavior.
+ */
+export function parseGuard(
+	raw: unknown,
+	path: string,
+	onError: (message: string) => void = () => {},
+): Guard | undefined {
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+		onError(`do-always: ignoring invalid guard in ${path} (expected an object)`);
+		return undefined;
+	}
+	const { type } = raw as Record<string, unknown>;
+	if (typeof type !== "string" || !GUARD_TYPES.includes(type as Guard["type"])) {
+		const known = GUARD_TYPES.join(", ");
+		onError(
+			`do-always: ignoring invalid "type" in guard ${path} (expected one of: ${known})`,
+		);
+		return undefined;
+	}
+	const guard: Guard = { type: type as Guard["type"] };
+	if (type !== "requireDirty") {
+		const { value } = raw as Record<string, unknown>;
+		if (typeof value !== "string") {
+			onError(`do-always: guard "${type}" in ${path} requires a string "value"`);
+			return undefined;
+		}
+		guard.value = value;
+	}
+	return guard;
+}
+
 /**
  * Resolve a task from a command argument: by number (1-based) or by name (case-insensitive).
  */

package/package.json

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