brl-subagent 2.3.8 → 2.4.0

package/src/tui.ts

@@ -1,3 +1,4 @@
+// Purpose: All TUI surfaces: config menus, preset/template managers, history, live monitor, and result rendering.
 /**
  * brl-subagent — TUI Components
  *
@@ -17,7 +18,6 @@ import { Container, type SelectItem, SelectList, Spacer, Text, Markdown } from "
 import type { Api, Model } from "@earendil-works/pi-ai";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type {
-	SubagentPreset,
 	TaskTemplate,
 	SubagentResult,
 	SubagentRun,
@@ -28,7 +28,6 @@ import type {
 	GraphDetails,
 	DelegateTaskDetails,
 	GraphTask,
-	SubTaskResult,
 	ThinkingLevel,
 	UsageStats,
 	FileDiff,
@@ -42,8 +41,6 @@ import {
 	COLLAPSED_OUTPUT_LINES,
 	COLLAPSED_DIFF_FILES_PREVIEW,
 	EXPANDED_HUNKS_PER_FILE,
-	RESERVED_NAME_PATTERN,
-	RESERVED_COMMAND_NAMES,
 	formatTokens,
 	formatUsageStats,
 	formatModel,
@@ -54,9 +51,9 @@ import {
 	isGraphDetails,
 } from "./types";
 import { buildFileAccessReport, buildSecretsExposureReport, generateComplianceSummary } from "./reports";
-import { extractParamNames, loadAllTemplates, validateTemplatePresetRefs } from "./templates";
+import { extractParamNames } from "./templates";
 import { parseDiff } from "./diff";
-import { formatPresetSummary, getPreset, getAllPresets, writePresetFile, loadCustomPresets, parseFrontmatter } from "./presets";
+import { formatPresetSummary, getPreset, loadCustomPresets } from "./presets";
 import { formatRunDuration } from "./history";
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -638,185 +635,6 @@ export async function showComplianceMenu(
 
 // Preset management UI
 
-export async function showAddPreset(
-	ctx: ExtensionContext,
-	state: SessionState,
-): Promise<void> {
-	// 1. Prompt for name
-	const name = await ctx.ui.input("Preset name (e.g., read-only-audit):");
-	if (!name?.trim()) return;
-	const trimmedName = name.trim();
-
-	// 2. Validate name (reserved patterns, existing presets)
-	if (RESERVED_NAME_PATTERN.test(trimmedName)) {
-		ctx.ui.notify("Names starting and ending with '__' are reserved.", "error");
-		return;
-	}
-	if (RESERVED_COMMAND_NAMES.has(trimmedName)) {
-		ctx.ui.notify("Name '" + trimmedName + "' is reserved for a command.", "error");
-		return;
-	}
-	if (getPreset(trimmedName, state.builtinPresets, state.customPresets)) {
-		ctx.ui.notify(`Preset "${trimmedName}" already exists.`, "error");
-		return;
-	}
-
-	// 3. Description
-	const description = await ctx.ui.input("Description (optional):");
-
-	// 4. Thinking level
-	const thinkingItems: SelectItem[] = [
-		{ value: "", label: "(not set — use conductor's choice)" },
-		...THINKING_LEVELS.map((level) => ({ value: level, label: level })),
-	];
-	const thinkingResult = await showSelectList(ctx, "Default Thinking Level", thinkingItems, 8);
-
-	// 5. Tool scope
-	const scopeItems: SelectItem[] = [
-		{ value: "all", label: "All tools (default)" },
-		{ value: "readonly", label: "Read-only (read, grep, find, ls)" },
-		{ value: "custom", label: "Custom tool list..." },
-	];
-	const scopeResult = await showSelectList(ctx, "Tool Scope", scopeItems, 5);
-
-	let tools: string[] | undefined;
-	let excludeTools: string[] | undefined;
-	let noBuiltinTools: boolean | undefined;
-
-	if (scopeResult === "readonly") {
-		tools = ["read", "grep", "find", "ls"];
-		excludeTools = ["write", "edit", "bash"];
-	} else if (scopeResult === "custom") {
-		const toolsStr = await ctx.ui.input("Tools (comma-separated):");
-		if (toolsStr?.trim()) tools = toolsStr.split(",").map((t) => t.trim()).filter(Boolean);
-	}
-
-	// 6. Inheritance
-	const inheritItems: SelectItem[] = [
-		{ value: "true", label: "Inherit system prompt (default)" },
-		{ value: "false", label: "No inheritance (standalone)" },
-	];
-	const inheritResult = await showSelectList(ctx, "System Prompt Inheritance", inheritItems, 3);
-
-	// 7. System prompt body
-	const systemPrompt = await ctx.ui.input("System prompt (optional, multi-line not supported yet):");
-
-	// 8. Build preset object
-	const preset: SubagentPreset = {
-		name: trimmedName,
-		description: description?.trim() || undefined,
-		thinkingLevel: thinkingResult || undefined,
-		inheritSystemPrompt: inheritResult === "false" ? false : undefined,
-		tools,
-		excludeTools,
-		noBuiltinTools,
-		systemPrompt: systemPrompt?.trim() || undefined,
-	};
-
-	// 9. Ask where to save
-	const locationItems: SelectItem[] = [
-		{ value: "project", label: "Project (.pi/brl-subagent/presets/)" },
-		{ value: "global", label: "Global (~/.pi/agent/brl-subagent/presets/)" },
-	];
-	const location = await showSelectList(ctx, "Save Location", locationItems, 3);
-	if (!location) return;
-
-	const homedir = process.env.HOME || process.env.USERPROFILE || "";
-	const targetDir = location === "project"
-		? path.join(ctx.cwd, ".pi", "brl-subagent", "presets")
-		: path.join(homedir, ".pi", "agent", "brl-subagent", "presets");
-
-	// 10. Write file
-	try {
-		writePresetFile(preset, targetDir);
-		// 11. Refresh custom presets
-		state.customPresets = loadCustomPresets(ctx.cwd, state.log);
-		// Reload templates alongside presets — both are file-derived, and a
-		// preset add/remove may fix (or break) a template's `preset:` reference.
-		// Full stack: custom (project+global) merged over builtins.
-		state.config.templates = loadAllTemplates(ctx.cwd, state.log);
-		// Issue #81: re-check template `preset:` refs after the mutation — warn
-		// (never skip) for dangling references instead of preset-less runs.
-		validateTemplatePresetRefs(
-			state.config.templates,
-			getAllPresets(state.builtinPresets, state.customPresets),
-			state.log,
-		);
-		ctx.ui.notify(`Preset "${trimmedName}" saved to ${location === "project" ? "project" : "global"} directory`, "info");
-	} catch (err) {
-		ctx.ui.notify(`Failed to save preset: ${(err as Error).message}`, "error");
-	}
-}
-
-export async function showRemovePreset(
-	ctx: ExtensionContext,
-	state: SessionState,
-): Promise<void> {
-	const homedir = process.env.HOME || process.env.USERPROFILE || "";
-	const projectDir = path.join(ctx.cwd, ".pi", "brl-subagent", "presets");
-	const globalDir = path.join(homedir, ".pi", "agent", "brl-subagent", "presets");
-
-	// Scan both directories for .md files
-	const entries: Array<{ name: string; source: "project" | "global"; filePath: string }> = [];
-
-	for (const dir of [projectDir, globalDir]) {
-		const source = dir === projectDir ? "project" : "global";
-		try {
-			const files = fs.readdirSync(dir);
-			for (const file of files) {
-				if (!file.endsWith(".md")) continue;
-				const filePath = path.join(dir, file);
-				try {
-					const content = fs.readFileSync(filePath, "utf-8");
-					const { meta } = parseFrontmatter(content);
-					if (meta.name && typeof meta.name === "string") {
-						entries.push({ name: meta.name as string, source, filePath });
-					}
-				} catch {
-					// Skip unparseable files
-				}
-			}
-		} catch {
-			// Directory doesn't exist — fine
-		}
-	}
-
-	if (entries.length === 0) {
-		ctx.ui.notify("No custom presets to remove.", "info");
-		return;
-	}
-
-	// Show list with source indicators
-	const items: SelectItem[] = entries.map((e) => ({
-		value: e.filePath,
-		label: `[${e.source === "project" ? "P" : "G"}] ${e.name}`,
-		description: e.source === "project" ? "Project-local" : "Global",
-	}));
-
-	const result = await showSelectList(ctx, "Remove Preset", items, 10);
-	if (!result) return;
-
-	// Delete the file
-	try {
-		fs.unlinkSync(result);
-		state.customPresets = loadCustomPresets(ctx.cwd, state.log);
-		// Reload templates too — a removed preset may orphan a template's
-		// `preset:` reference, so both file-derived collections refresh together.
-		// Full stack: custom (project+global) merged over builtins.
-		state.config.templates = loadAllTemplates(ctx.cwd, state.log);
-		// Issue #81: re-check template `preset:` refs after the mutation — warn
-		// (never skip) for dangling references instead of preset-less runs.
-		validateTemplatePresetRefs(
-			state.config.templates,
-			getAllPresets(state.builtinPresets, state.customPresets),
-			state.log,
-		);
-		ctx.ui.notify("Preset removed", "info");
-	} catch (err) {
-		ctx.ui.notify(`Failed to remove preset: ${(err as Error).message}`, "error");
-	}
-}
-
 export async function showPresetManager(
 	ctx: ExtensionContext,
 	state: SessionState,
@@ -2179,29 +1997,6 @@ function renderCollapsedText(
 	return text;
 }
 
-// ---------------------------------------------------------------------------
-// Chain / parallel helper: one-line subtask summary
-// ---------------------------------------------------------------------------
-
-function renderSubTaskSummary(
-	result: SubTaskResult,
-	theme: {
-		fg: (color: string, text: string) => string;
-	},
-	maxLines: number,
-): string {
-	const isError = isSubagentError(result);
-	const icon = isError
-		? theme.fg("error", "\u2717")
-		: theme.fg("success", "\u2713");
-	const label = result.label
-		? theme.fg("accent", `${result.label}: `)
-		: "";
-	const output = getFinalOutput(result.messages);
-	const preview = output.split("\n").slice(0, maxLines).join("\n");
-	return `${icon} ${label}${theme.fg("toolOutput", preview)}`;
-}
-
 // ---------------------------------------------------------------------------
 // Chain / parallel collapsed rendering
 // ---------------------------------------------------------------------------

package/src/types.ts

@@ -1,3 +1,4 @@
+// Purpose: Shared types, constants, and the error/termination classification taxonomy.
 /**
  * brl-subagent — Type Definitions
  *
@@ -6,6 +7,8 @@
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { Static } from "typebox";
+import type { delegateTaskParamsSchema } from "./schema";
 import type { TranscriptMessage } from "./transcript-tail";
 
 // ---------------------------------------------------------------------------
@@ -299,6 +302,14 @@ export interface SubagentRun {
 		excludeTools?: string[];
 		noBuiltinTools?: boolean;
 		preset?: string;
+		// Issue #227: the execution-shape fields survive retries, so a retried
+		// background run stays background and a retried branch-mode run keeps its
+		// work branch, its approvalMode gating and its force override. Additive:
+		// records written before this change simply lack the keys.
+		background?: boolean;
+		gitMode?: string;
+		approvalMode?: string;
+		force?: boolean;
 		errorCategory?: ErrorCategory;
 	};
 }
@@ -450,7 +461,7 @@ export interface GraphTask {
 	noBuiltinTools?: boolean;
 	systemPrompt?: string;
 	inheritSystemPrompt?: boolean;
-	dependsOn: string[];
+	dependsOn?: string[];
 }
 
 /** One wave of tasks executed together in a graph. */
@@ -484,6 +495,24 @@ export type DelegateTaskDetails =
 	| GraphDetails
 	| undefined;
 
+/**
+ * The delegate_task handler's params (issue #229 item 4) — the type the
+ * handler's inline block used to spell out, hoisted here so it is nameable.
+ *
+ * Why it matters: `approvalMode` is in the registered schema and in
+ * KNOWN_DELEGATE_KEYS, and reaches execute() at runtime through the spread —
+ * but a reader of `params` inside the handler could not see it. The key-set
+ * is compile-time ratcheted in src/index.ts against KNOWN_DELEGATE_KEYS
+ * (schema ↔ KNOWN_DELEGATE_KEYS ↔ this type); the missing key is invisible at
+ * runtime, so only the compiler can catch its removal.
+ *
+ * A type ALIAS, not an interface: the handler passes `params` to
+ * findUnknownParams/resolveSubagentParams (Record<string, unknown> params),
+ * and only a type alias gets the implicit index signature an interface
+ * lacks.
+ */
+export type DelegateTaskParams = Static<typeof delegateTaskParamsSchema>;
+
 // ---------------------------------------------------------------------------
 // Resolved params (after preset merging + validation)
 // ---------------------------------------------------------------------------
@@ -504,6 +533,9 @@ export interface ResolvedParams {
 	toolOptions: SubagentToolOptions | undefined;
 	/** Set only when autoRoutePreset chose the preset (not explicitly requested). */
 	autoRoutedPreset: SubagentPreset | undefined;
+	/** Set only when auto-route chose the preset: the keyword that matched —
+	 * surfaced in the dispatch result as the auto-route evidence. */
+	autoRouteKeyword?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -625,7 +657,7 @@ export const RESERVED_COMMAND_NAMES = new Set([
 	"model", "thinking", "concurrency", "depth", "history", "monitor",
 	"preset", "retry", "reset", "priority", "templates", "dashboard", "approval",
  "costlimit", "historyentries", "sla", "completionnotify",
-	"graph", "sla-stats",
+	"graph", "sla-stats", "compliance",
 ]);
 
 // ---------------------------------------------------------------------------

package/src/unit-run.ts

@@ -1,3 +1,4 @@
+// Purpose: Per-unit run-entry helpers shared by chain, parallel, and graph modes.
 /**
  * Per-unit run-entry helpers extracted from src/index.ts (issue #132).
  *
@@ -122,6 +123,10 @@ export function createUnitRun(
 		// same priority the run entry itself carried.
 		priority: source.priority ?? priorityFloor,
 		startedAt: new Date().toISOString(),
+		// The execution-shape fields (background/gitMode/approvalMode/force) are
+		// deliberately omitted: a fan-out unit retries as a SINGLE run, so it must
+		// not inherit the fan-out's background-ness. A retry that wants background
+		// passes background: true explicitly.
 		originalParams: snapshotOriginalParams({
 			systemPrompt: source.customSP,
 			inheritSystemPrompt: source.inheritSP,

package/src/validate.ts

@@ -1,3 +1,4 @@
+// Purpose: H1 pre-task validation: deterministic tool/thinking/git checks and failure post-mortems.
 /**
  * H1: Pre-task validation
  *
@@ -17,6 +18,15 @@ export interface ValidateConfig {
   thinkingLevel?: ThinkingLevel;
   gitMode?: string;
   outputFile?: string;
+  /**
+   * delegate_task's `force` param (default false). When true, capability
+   * ERRORS (the high-confidence capability-critical mismatches below)
+   * degrade to warning-class: they still surface in `warnings`, but
+   * `valid` stays true and dispatch proceeds. The outputFile hard
+   * conflict is NOT suppressible — a report the subagent cannot write
+   * can never succeed, so force does not apply to it.
+   */
+  force?: boolean;
 }
 
 export interface ValidateResult {
@@ -29,40 +39,109 @@ export interface ValidateResult {
 
 interface ToolRequirement {
   patterns: RegExp[];
+  /** ALL-of: every listed tool must be available (default semantics). */
   requiredTools: string[];
+  /**
+   * ANY-of: when set, ONE available tool satisfies the requirement and
+   * `requiredTools` is ignored — directory exploration is a single
+   * capability (the browse built-ins find/ls/grep and bash are
+   * interchangeable ways to do it), not a conjunction of all of them.
+   */
+  anyOfTools?: string[];
+  /**
+   * Warning lead, rendered as `Task ${description} but …` (and, under a
+   * unit prefix, `Task 1 ("deploy"): Task ${description} …`). Starts with
+   * the verb ("involves …") so the fixed `Task ` template reads naturally
+   * standalone AND prefixed — do not add a leading "task" (issue #220).
+   */
   description: string;
+  /**
+   * High-confidence, capability-critical subset of `patterns`: a task
+   * matching any of these with the capability ABSENT is promoted from
+   * warning to ERROR — dispatch does not spawn — unless `force` is set,
+   * which degrades the mismatch back to warning class. Only the two
+   * capability-critical shapes carry this: a run/execute/test/compile/
+   * benchmark task with no bash, and an exploration task with none of
+   * find/ls/grep/bash. Entry-less requirements never block (warnings only).
+   */
+  blockingPatterns?: RegExp[];
+  /**
+   * Builds the block message: names the missing capability, the resolved
+   * toolset, and the exact fix — including the force override. Receives
+   * the rendered `tools=…, excludeTools=…` toolset string.
+   */
+  blockMessage?: (toolset: string) => string;
 }
 
+/*
+ * COVERAGE BOUNDARY — which wording evades this table (every guard states
+ * its coverage). These are word-boundary keyword matches against the raw
+ * task text, nothing more. EVADED by: paraphrases that use none of the
+ * listed keywords ("hunt for drafts", "browse the repository", "see which
+ * files mention X"), inflected forms the patterns do not list ("running",
+ * "tests", "searching", "listing" — \btest\b does not match "tests"), and
+ * domain phrasing that never names the verb ("kick off CI", "smoke the
+ * pipeline"). The opposite failure is equally real: documentation/writing
+ * tasks that merely MENTION a keyword ("document how to run the tests")
+ * match too — which is why only the two high-confidence capability blocks
+ * (blockingPatterns below) escalate to errors, while install/deploy/npm/
+ * yarn/pnpm/cargo/pip stay warning-class (docs can name them without
+ * needing them). Widening the table is deliberate work: add the keyword
+ * here AND update this note.
+ */
+
 const TOOL_REQUIREMENTS: ToolRequirement[] = [
   {
     patterns: [/\b(write|create|generate|build|implement|add|insert|append)\b/i],
     requiredTools: ['write', 'edit'],
-    description: 'task involves writing/creating files',
+    description: 'involves writing/creating files',
   },
   {
     patterns: [/\b(edit|modify|update|change|fix|patch|refactor|rename)\b/i],
     requiredTools: ['write', 'edit'],
-    description: 'task involves editing files',
+    description: 'involves editing files',
   },
   {
     patterns: [/\b(run|execute|test|benchmark|compile|install|deploy|npm|yarn|pnpm|cargo|pip|vitest)\b/i],
     requiredTools: ['bash'],
-    description: 'task involves running commands',
+    description: 'involves running commands',
+    // Blocking subset: only the verbs that unambiguously DEMAND a shell.
+    // install/deploy/npm/yarn/pnpm/cargo/pip deliberately stay warning-class
+    // — documentation tasks can mention them without executing them.
+    blockingPatterns: [/\b(run|execute|test|compile|benchmark)\b/i],
+    blockMessage: (toolset) =>
+      `Cannot delegate: the task requires the 'bash' tool (running commands) but it is not available ` +
+      `in the resolved toolset (${toolset}). Fix: add 'bash' to this dispatch's tools (or remove it ` +
+      `from excludeTools) and re-dispatch, or pass force: true to dispatch anyway.`,
+  },
+  {
+    // Directory exploration is ONE capability, satisfied by ANY of the
+    // browse built-ins or bash — anyOfTools, not a conjunction.
+    patterns: [/\b(search|grep|find|list|locate|glob)\b/i],
+    requiredTools: [],
+    anyOfTools: ['find', 'ls', 'grep', 'bash'],
+    description: 'involves directory exploration',
+    blockingPatterns: [/\b(search|grep|find|list|locate|glob)\b/i],
+    blockMessage: (toolset) =>
+      `Cannot delegate: the task requires directory exploration, satisfied by any of 'find', 'ls', ` +
+      `'grep' or 'bash', but none is available in the resolved toolset (${toolset}). Fix: add any of ` +
+      `'find', 'ls', 'grep' or 'bash' to this dispatch's tools (or remove it from excludeTools) and ` +
+      `re-dispatch, or pass force: true to dispatch anyway.`,
   },
   {
     patterns: [/\b(delete|remove|clean|prune|uninstall|rm)\b/i],
     requiredTools: ['write', 'bash'],
-    description: 'task involves deleting files',
+    description: 'involves deleting files',
   },
   {
     patterns: [/\b(commit|push|pull|merge|rebase|checkout|branch)\b/i],
     requiredTools: ['bash'],
-    description: 'task involves git operations',
+    description: 'involves git operations',
   },
   {
     patterns: [/\b(audit|review|analyze|examine|check|inspect|scan|read)\b/i],
     requiredTools: ['read'],
-    description: 'task involves reading/analyzing files',
+    description: 'involves reading/analyzing files',
   },
 ];
 
@@ -225,15 +304,38 @@ export function validatePreTask(config: ValidateConfig): ValidateResult {
     return { valid: true, warnings: [], errors: [] };
   }
 
-  // Check tool requirements (warnings, not errors — conductor can override)
+  // Check tool requirements. A missing capability is warning-class by
+  // default (conductor can judge); the high-confidence capability-critical
+  // cases (blockingPatterns) are promoted to ERRORS unless `force` is set.
+  const toolset = `tools=${config.toolOptions?.tools?.join(',') ?? 'all'}, excludeTools=${config.toolOptions?.excludeTools?.join(',') ?? 'none'}`;
   for (const req of TOOL_REQUIREMENTS) {
     const matches = req.patterns.some(p => p.test(taskText));
     if (!matches) continue;
 
-    for (const tool of req.requiredTools) {
-      if (!isToolAvailable(tool, config.toolOptions)) {
+    const missing = req.anyOfTools
+      ? (req.anyOfTools.some(t => isToolAvailable(t, config.toolOptions)) ? [] : [...req.anyOfTools])
+      : req.requiredTools.filter(t => !isToolAvailable(t, config.toolOptions));
+    if (missing.length === 0) continue;
+
+    // Capability-critical block: high-confidence pattern matched AND the
+    // capability is absent. `force` degrades it to warning class below.
+    const capabilityBlock =
+      !config.force &&
+      req.blockMessage !== undefined &&
+      (req.blockingPatterns ?? []).some(p => p.test(taskText));
+    if (capabilityBlock) {
+      errors.push(req.blockMessage!(toolset));
+      continue;
+    }
+
+    if (req.anyOfTools) {
+      warnings.push(
+        `Task ${req.description} but none of ${req.anyOfTools.map(t => `'${t}'`).join(', ')} is available (${toolset})`,
+      );
+    } else {
+      for (const tool of missing) {
         warnings.push(
-          `Task ${req.description} but '${tool}' is not available (tools=${config.toolOptions?.tools?.join(',') ?? 'all'}, excludeTools=${config.toolOptions?.excludeTools?.join(',') ?? 'none'})`,
+          `Task ${req.description} but '${tool}' is not available (${toolset})`,
         );
       }
     }
@@ -281,6 +383,17 @@ export function validatePreTask(config: ValidateConfig): ValidateResult {
   };
 }
 
+/**
+ * Default deadline for a BACKGROUND run that specifies no explicit `timeout`
+ * (issue #28 orphan protection). This is a DEFAULT, not a ceiling: an explicit
+ * timeout is honored verbatim (after normalizeTimeout), however long it is
+ * (issue #240). Callers must NOT treat this as an upper bound.
+ *
+ * Kept next to normalizeTimeout (same setTimeout-boundary concern) and shared
+ * by the session-manager W3 timer and the index.ts hard-cap timer.
+ */
+export const DEFAULT_BACKGROUND_DEADLINE_MS = 30 * 60 * 1000;
+
 /**
  * Normalize a user-supplied timeout to a safe deadline value, or undefined for
  * "no timeout". Guards the setTimeout boundary — Node fires `setTimeout(fn, 0)`,
@@ -289,8 +402,10 @@ export function validatePreTask(config: ValidateConfig): ValidateResult {
  * review M1/m1).
  *
  * Returns undefined for: undefined, 0, negative, NaN, Infinity, >=2^31-1.
- * Returns the value unchanged otherwise (foreground permits >30min timeouts;
- * the background hard cap applies its own 30min Math.min).
+ * Returns the value unchanged otherwise. A background run with no explicit
+ * timeout (undefined here) falls back to DEFAULT_BACKGROUND_DEADLINE_MS; an
+ * explicit timeout is honored verbatim — the 30m default is not a ceiling
+ * (issue #240).
  */
 export function normalizeTimeout(timeout: number | undefined): number | undefined {
 	if (timeout === undefined) return undefined;

package/templates/code-review.md

@@ -7,4 +7,4 @@ thinkingLevel: medium
 Review ${target} for correctness, security, and style.
 
 Report findings as a numbered list with file:line references,
-prioritized blocker → nit. Read-only — no edits.
+prioritized blocker → nit. Read-only — no edits. Any finding that rests on a search or a read states its coverage boundary: the query or command used, its count or range, and how it reconciles with what you expected to cover.

package/templates/debug-issue.md

@@ -6,4 +6,5 @@ thinkingLevel: medium
 ---
 Debug ${symptom}. Reproduce it first, then isolate the root cause.
 
-Show the failing input, the root cause, and the minimal fix.
+Show the failing input, the root cause, and the minimal fix. Final report: end with a Coverage line — the exact command or query used, the count or range it printed, and how it reconciles with the corpus you expected; show an empty result's size before treating it as absence.
+Before running any probe or reproduction, name its target by unique surrounding context and state the expected failure signature; when it runs tests, scope the run to the specific test file — a passing probe is first evidence the target was wrong, not that the behavior is fine.

package/templates/write-tests.md

@@ -7,4 +7,4 @@ thinkingLevel: medium
 Write tests for ${file} covering the happy path and edge cases.
 
 Include the test file path in your report and note any
-untestable code paths you skipped.
+untestable code paths you skipped. When designing a mutation to prove a test fails on the defect, name the target by unique surrounding context and state the expected failure first.