@n-dx/core 0.1.0

package/packages/hench/dist/tools/git.js

@@ -0,0 +1,48 @@
+import { execShell } from "./exec-shell.js";
+const GIT_TIMEOUT = 15000;
+export async function toolGit(guard, projectDir, params) {
+    guard.checkGitSubcommand(params.subcommand);
+    const args = ["git", params.subcommand];
+    if (params.args) {
+        // Split args respecting quotes
+        args.push(...splitArgs(params.args));
+    }
+    return execShell({
+        command: args.join(" "),
+        cwd: projectDir,
+        timeout: GIT_TIMEOUT,
+    });
+}
+function splitArgs(argsStr) {
+    const args = [];
+    let current = "";
+    let inQuote = false;
+    let quoteChar = "";
+    for (const ch of argsStr) {
+        if (inQuote) {
+            if (ch === quoteChar) {
+                inQuote = false;
+            }
+            else {
+                current += ch;
+            }
+        }
+        else if (ch === '"' || ch === "'") {
+            inQuote = true;
+            quoteChar = ch;
+        }
+        else if (ch === " ") {
+            if (current) {
+                args.push(current);
+                current = "";
+            }
+        }
+        else {
+            current += ch;
+        }
+    }
+    if (current)
+        args.push(current);
+    return args;
+}
+//# sourceMappingURL=git.js.map

package/packages/hench/dist/tools/git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../../src/tools/git.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAG5C,MAAM,WAAW,GAAG,KAAK,CAAC;AAE1B,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,KAAgB,EAChB,UAAkB,EAClB,MAA6C;IAE7C,KAAK,CAAC,kBAAkB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAE5C,MAAM,IAAI,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IACxC,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;QAChB,+BAA+B;QAC/B,IAAI,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IACvC,CAAC;IAED,OAAO,SAAS,CAAC;QACf,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;QACvB,GAAG,EAAE,UAAU;QACf,OAAO,EAAE,WAAW;KACrB,CAAC,CAAC;AACL,CAAC;AAED,SAAS,SAAS,CAAC,OAAe;IAChC,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,IAAI,OAAO,GAAG,EAAE,CAAC;IACjB,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,SAAS,GAAG,EAAE,CAAC;IAEnB,KAAK,MAAM,EAAE,IAAI,OAAO,EAAE,CAAC;QACzB,IAAI,OAAO,EAAE,CAAC;YACZ,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;gBACrB,OAAO,GAAG,KAAK,CAAC;YAClB,CAAC;iBAAM,CAAC;gBACN,OAAO,IAAI,EAAE,CAAC;YAChB,CAAC;QACH,CAAC;aAAM,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YACpC,OAAO,GAAG,IAAI,CAAC;YACf,SAAS,GAAG,EAAE,CAAC;QACjB,CAAC;aAAM,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YACtB,IAAI,OAAO,EAAE,CAAC;gBACZ,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACnB,OAAO,GAAG,EAAE,CAAC;YACf,CAAC;QACH,CAAC;aAAM,CAAC;YACN,OAAO,IAAI,EAAE,CAAC;QAChB,CAAC;IACH,CAAC;IACD,IAAI,OAAO;QAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAChC,OAAO,IAAI,CAAC;AACd,CAAC"}

package/packages/hench/dist/tools/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * hench-tooling — Tool definitions, dispatch, and implementations.
+ *
+ * This module owns everything related to the tools the agent can invoke:
+ * - Tool schema definitions (TOOL_DEFINITIONS)
+ * - Central dispatch router (dispatchTool)
+ * - Individual tool implementations (files, shell, git, test-runner)
+ *
+ * The agent core (run loop, brief assembly, prompts) imports from this
+ * module but never the reverse — tools do not depend on the agent loop.
+ */
+export { TOOL_DEFINITIONS, dispatchTool } from "./dispatch.js";
+export { toolReadFile, toolWriteFile, toolListDirectory, toolSearchFiles, } from "./files.js";
+export { toolRunCommand } from "./shell.js";
+export { toolGit } from "./git.js";
+export { runPostTaskTests, findRelevantTests, isTestFile, candidateTestPaths, detectRunner, buildScopedCommand, } from "./test-runner.js";
+export type { PostRunTestResult, TestRunnerOptions } from "./test-runner.js";

package/packages/hench/dist/tools/index.js

@@ -0,0 +1,19 @@
+/**
+ * hench-tooling — Tool definitions, dispatch, and implementations.
+ *
+ * This module owns everything related to the tools the agent can invoke:
+ * - Tool schema definitions (TOOL_DEFINITIONS)
+ * - Central dispatch router (dispatchTool)
+ * - Individual tool implementations (files, shell, git, test-runner)
+ *
+ * The agent core (run loop, brief assembly, prompts) imports from this
+ * module but never the reverse — tools do not depend on the agent loop.
+ */
+// Dispatch layer — tool definitions and routing
+export { TOOL_DEFINITIONS, dispatchTool } from "./dispatch.js";
+// Tool implementations
+export { toolReadFile, toolWriteFile, toolListDirectory, toolSearchFiles, } from "./files.js";
+export { toolRunCommand } from "./shell.js";
+export { toolGit } from "./git.js";
+export { runPostTaskTests, findRelevantTests, isTestFile, candidateTestPaths, detectRunner, buildScopedCommand, } from "./test-runner.js";
+//# sourceMappingURL=index.js.map

package/packages/hench/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,gDAAgD;AAChD,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE/D,uBAAuB;AACvB,OAAO,EACL,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACnC,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,EACV,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,GACnB,MAAM,kBAAkB,CAAC"}

package/packages/hench/dist/tools/rex.d.ts

@@ -0,0 +1,32 @@
+import type { PRDStore, CommandExecutor } from "../prd/rex-gateway.js";
+import type { RexToolHandlers } from "./contracts.js";
+export interface UpdateStatusOptions {
+    /** Project directory for git-based completion validation. */
+    projectDir?: string;
+    /** Test command to run during completion validation. */
+    testCommand?: string;
+    /** Commit hash captured before the agent started, for diffing against. */
+    startingHead?: string;
+    /** When true, reject doc-only completions. */
+    selfHeal?: boolean;
+}
+export declare function toolRexUpdateStatus(store: PRDStore, taskId: string, params: {
+    status: string;
+    reason?: string;
+    resolutionType?: string;
+}, options?: UpdateStatusOptions): Promise<string>;
+export declare function toolRexAppendLog(store: PRDStore, taskId: string, params: {
+    event: string;
+    detail?: string;
+}): Promise<string>;
+export declare function toolRexAddSubtask(store: PRDStore, taskId: string, params: {
+    title: string;
+    description?: string;
+    priority?: string;
+}): Promise<string>;
+export declare const rexToolHandlers: RexToolHandlers;
+/**
+ * Create a CommandExecutor that runs shell commands in the project directory.
+ * Used by requirements validation to execute validation commands.
+ */
+export declare function createCommandExecutor(projectDir: string): CommandExecutor;

package/packages/hench/dist/tools/rex.js

@@ -0,0 +1,185 @@
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { PROJECT_DIRS } from "../prd/llm-gateway.js";
+import { execShellCmd } from "../process/index.js";
+import { computeTimestampUpdates, findAutoCompletions, validateAutomatedRequirements, formatRequirementsValidation, loadAcknowledged, saveAcknowledged, acknowledgeFinding } from "../prd/rex-gateway.js";
+import { validateCompletion, formatValidationResult } from "../validation/completion.js";
+export async function toolRexUpdateStatus(store, taskId, params, options) {
+    const validStatuses = ["pending", "in_progress", "completed", "failing", "deferred", "blocked"];
+    if (!validStatuses.includes(params.status)) {
+        throw new Error(`Invalid status "${params.status}". Valid: ${validStatuses.join(", ")}`);
+    }
+    // Validate completion: require meaningful changes before marking complete
+    if (params.status === "completed" && options?.projectDir) {
+        const validation = await validateCompletion(options.projectDir, {
+            testCommand: options.testCommand,
+            startingHead: options.startingHead,
+            selfHeal: options.selfHeal,
+        });
+        if (!validation.valid) {
+            const detail = formatValidationResult(validation);
+            await store.appendLog({
+                timestamp: new Date().toISOString(),
+                event: "completion_rejected",
+                itemId: taskId,
+                detail,
+            });
+            return `[COMPLETION_REJECTED] Cannot mark task as completed: ${validation.reason}\n` +
+                `The task must produce meaningful changes (non-empty git diff) to be marked complete. ` +
+                `If you believe the task is done, review your changes and ensure they are committed or staged.`;
+        }
+        // Validate automated/metric requirements (manual requirements are logged but don't block)
+        const doc = await store.loadDocument();
+        const reqSummary = await validateAutomatedRequirements(doc.items, taskId, createCommandExecutor(options.projectDir));
+        if (reqSummary.total > 0 && !reqSummary.allPassed) {
+            const detail = formatRequirementsValidation(reqSummary);
+            await store.appendLog({
+                timestamp: new Date().toISOString(),
+                event: "requirements_validation_failed",
+                itemId: taskId,
+                detail,
+            });
+            const failedReqs = reqSummary.results
+                .filter((r) => !r.passed)
+                .map((r) => `  - ${r.requirementTitle}: ${r.reason}`)
+                .join("\n");
+            return `[REQUIREMENTS_FAILED] Cannot mark task as completed. ` +
+                `${reqSummary.failed} of ${reqSummary.total} automated requirements failed:\n` +
+                `${failedReqs}\n` +
+                `Fix the failing requirements and try again.`;
+        }
+        // Log successful requirements validation (if any requirements existed)
+        if (reqSummary.total > 0) {
+            await store.appendLog({
+                timestamp: new Date().toISOString(),
+                event: "requirements_validated",
+                itemId: taskId,
+                detail: `All ${reqSummary.total} automated requirements passed`,
+            });
+        }
+    }
+    const existing = await store.getItem(taskId);
+    const tsUpdates = computeTimestampUpdates(existing?.status ?? "pending", params.status, existing ?? undefined);
+    const statusUpdates = { status: params.status, ...tsUpdates };
+    if (params.status === "failing" && params.reason) {
+        statusUpdates.failureReason = params.reason;
+    }
+    if (params.status === "completed" && params.resolutionType) {
+        statusUpdates.resolutionType = params.resolutionType;
+    }
+    await store.updateItem(taskId, statusUpdates);
+    await store.appendLog({
+        timestamp: new Date().toISOString(),
+        event: "status_updated",
+        itemId: taskId,
+        detail: `Status changed to ${params.status} by hench agent`,
+    });
+    // Auto-acknowledge sourcevision findings when a task is deferred
+    if (params.status === "deferred" && existing?.tags && options?.projectDir) {
+        const findingTags = existing.tags.filter((t) => t.startsWith("finding:"));
+        if (findingTags.length > 0) {
+            try {
+                const rexDir = join(options.projectDir, PROJECT_DIRS.REX);
+                let ackStore = await loadAcknowledged(rexDir);
+                for (const tag of findingTags) {
+                    const hash = tag.slice("finding:".length);
+                    ackStore = acknowledgeFinding(ackStore, hash, existing.title, "deferred", "hench");
+                }
+                await saveAcknowledged(rexDir, ackStore);
+            }
+            catch {
+                // Non-fatal: finding acknowledgment is best-effort
+            }
+        }
+    }
+    // Auto-complete parent items when a child is completed or deferred
+    const autoCompleted = [];
+    if (params.status === "completed" || params.status === "deferred") {
+        const doc = await store.loadDocument();
+        const { completedItems } = findAutoCompletions(doc.items, taskId);
+        for (const item of completedItems) {
+            const parentItem = await store.getItem(item.id);
+            if (!parentItem)
+                continue;
+            const parentTsUpdates = computeTimestampUpdates(parentItem.status, "completed", parentItem);
+            await store.updateItem(item.id, {
+                status: "completed",
+                ...parentTsUpdates,
+            });
+            await store.appendLog({
+                timestamp: new Date().toISOString(),
+                event: "auto_completed",
+                itemId: item.id,
+                detail: `Auto-completed ${item.level}: ${item.title} (all children done)`,
+            });
+            autoCompleted.push(`${item.level}: ${item.title}`);
+        }
+    }
+    const msg = `Updated task ${taskId} status to ${params.status}`;
+    if (autoCompleted.length > 0) {
+        return `${msg}\nAuto-completed: ${autoCompleted.join(", ")}`;
+    }
+    return msg;
+}
+export async function toolRexAppendLog(store, taskId, params) {
+    await store.appendLog({
+        timestamp: new Date().toISOString(),
+        event: params.event,
+        itemId: taskId,
+        detail: params.detail,
+    });
+    return `Logged event: ${params.event}`;
+}
+export async function toolRexAddSubtask(store, taskId, params) {
+    const validPriorities = ["critical", "high", "medium", "low"];
+    if (params.priority && !validPriorities.includes(params.priority)) {
+        throw new Error(`Invalid priority "${params.priority}". Valid: ${validPriorities.join(", ")}`);
+    }
+    const id = randomUUID();
+    const subtask = {
+        id,
+        title: params.title,
+        status: "pending",
+        level: "subtask",
+        description: params.description,
+        priority: params.priority,
+    };
+    await store.addItem(subtask, taskId);
+    await store.appendLog({
+        timestamp: new Date().toISOString(),
+        event: "subtask_added",
+        itemId: id,
+        detail: `Added subtask "${params.title}" under ${taskId}`,
+    });
+    return `Created subtask ${id}: ${params.title}`;
+}
+export const rexToolHandlers = {
+    updateStatus: (ctx, params) => toolRexUpdateStatus(ctx.store, ctx.taskId, params, {
+        projectDir: ctx.projectDir,
+        testCommand: ctx.testCommand,
+        startingHead: ctx.startingHead,
+        selfHeal: ctx.selfHeal,
+    }),
+    appendLog: (ctx, params) => toolRexAppendLog(ctx.store, ctx.taskId, params),
+    addSubtask: (ctx, params) => toolRexAddSubtask(ctx.store, ctx.taskId, params),
+};
+// ── Requirements command executor ─────────────────────────────────
+const REQ_CMD_TIMEOUT = 30_000;
+/**
+ * Create a CommandExecutor that runs shell commands in the project directory.
+ * Used by requirements validation to execute validation commands.
+ */
+export function createCommandExecutor(projectDir) {
+    return async (command) => {
+        const result = await execShellCmd(command, {
+            cwd: projectDir,
+            timeout: REQ_CMD_TIMEOUT,
+        });
+        return {
+            exitCode: result.exitCode ?? 1,
+            stdout: result.stdout,
+            stderr: result.stderr,
+        };
+    };
+}
+//# sourceMappingURL=rex.js.map

package/packages/hench/dist/tools/rex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rex.js","sourceRoot":"","sources":["../../src/tools/rex.ts"],"names":[],"mappings":"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"}

package/packages/hench/dist/tools/shell.d.ts

@@ -0,0 +1,6 @@
+import type { ToolGuard } from "./contracts.js";
+export declare function toolRunCommand(guard: ToolGuard, projectDir: string, params: {
+    command: string;
+    cwd?: string;
+    timeout?: number;
+}): Promise<string>;

package/packages/hench/dist/tools/shell.js

@@ -0,0 +1,10 @@
+import { execShell } from "./exec-shell.js";
+export async function toolRunCommand(guard, projectDir, params) {
+    guard.checkCommand(params.command);
+    const timeout = params.timeout ?? guard.commandTimeout;
+    const cwd = params.cwd
+        ? guard.checkPath(params.cwd)
+        : projectDir;
+    return execShell({ command: params.command, cwd, timeout });
+}
+//# sourceMappingURL=shell.js.map

package/packages/hench/dist/tools/shell.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.js","sourceRoot":"","sources":["../../src/tools/shell.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAG5C,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,KAAgB,EAChB,UAAkB,EAClB,MAA2D;IAE3D,KAAK,CAAC,YAAY,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAEnC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,KAAK,CAAC,cAAc,CAAC;IACvD,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG;QACpB,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC;QAC7B,CAAC,CAAC,UAAU,CAAC;IAEf,OAAO,SAAS,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;AAC9D,CAAC"}

package/packages/hench/dist/tools/test-runner.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Automatic test runner — identifies and runs relevant tests after task completion.
+ *
+ * Strategy:
+ * 1. From the list of changed files, find co-located test files
+ * 2. Run the project test command scoped to those files (if the runner supports it)
+ * 3. Fall back to the full test command if scoping isn't possible
+ * 4. Report results for inclusion in the run summary
+ */
+export interface PostRunTestResult {
+    /** Whether tests were executed at all. */
+    ran: boolean;
+    /** Whether all tests passed. */
+    passed: boolean;
+    /** The command that was executed. */
+    command?: string;
+    /** Human-readable summary of test output. */
+    output?: string;
+    /** How long the test run took in ms. */
+    durationMs?: number;
+    /** Test files that were targeted. Empty if full suite was run. */
+    targetedFiles: string[];
+    /** Error message if tests couldn't be run. */
+    error?: string;
+}
+export interface TestRunnerOptions {
+    /** Project root directory. */
+    projectDir: string;
+    /** Files changed during the task (relative paths). */
+    filesChanged: string[];
+    /** Configured test command (e.g. "pnpm test"). */
+    testCommand?: string;
+    /** Timeout for the test command in ms. Default: 120_000. */
+    timeout?: number;
+}
+/** Check if a path looks like a test file. */
+export declare function isTestFile(filePath: string): boolean;
+/**
+ * Given a source file path, generate candidate test file paths.
+ *
+ * For `src/agent/loop.ts`, generates:
+ * - `src/agent/loop.test.ts`
+ * - `src/agent/loop.spec.ts`
+ * - `src/agent/__tests__/loop.test.ts`
+ * - `tests/agent/loop.test.ts`  (mirrors src → tests)
+ * - etc.
+ */
+export declare function candidateTestPaths(filePath: string): string[];
+/**
+ * Find test files that exist on disk for the given changed files.
+ *
+ * Deduplicates at two levels:
+ * 1. Candidate paths — avoids redundant stat() calls when multiple source
+ *    files generate the same candidate.
+ * 2. Result paths — prevents the same test file appearing twice in the output,
+ *    even if reached through differently-formatted candidate paths.
+ */
+export declare function findRelevantTests(projectDir: string, filesChanged: string[]): Promise<string[]>;
+/**
+ * Extract the test runner name from a test command string.
+ * e.g. "pnpm test" → "pnpm", "npx vitest" → "vitest", "vitest run" → "vitest"
+ */
+export declare function detectRunner(testCommand: string): string | undefined;
+/**
+ * Build a scoped test command targeting specific files.
+ * Returns undefined if the runner doesn't support file scoping.
+ *
+ * Preserves existing flags (e.g. `jest --ci` → `jest --ci -- file.test.ts`).
+ * Deduplicates the vitest `run` subcommand when already present.
+ */
+export declare function buildScopedCommand(testCommand: string, runner: string, testFiles: string[]): string | undefined;
+/**
+ * Run relevant tests after task completion.
+ *
+ * 1. Skip if no test command is configured.
+ * 2. Discover test files related to changed source files.
+ * 3. If relevant tests found and runner supports scoping, run scoped.
+ * 4. Otherwise, run the full test command.
+ * 5. Return structured results.
+ */
+export declare function runPostTaskTests(options: TestRunnerOptions): Promise<PostRunTestResult>;

package/packages/hench/dist/tools/test-runner.js

@@ -0,0 +1,229 @@
+import { stat } from "node:fs/promises";
+import { dirname, join, basename, extname, normalize } from "node:path";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const DEFAULT_TIMEOUT = 120_000;
+/** Common test file patterns — matches *.test.ts, *.spec.js, etc. */
+const TEST_FILE_PATTERNS = [
+    /\.test\.[jt]sx?$/,
+    /\.spec\.[jt]sx?$/,
+    /_test\.[jt]sx?$/,
+    /_spec\.[jt]sx?$/,
+];
+/** Test runners that support file-path arguments for scoped runs. */
+const SCOPEABLE_RUNNERS = {
+    vitest: (files) => ["run", ...files],
+    jest: (files) => ["--", ...files],
+    mocha: (files) => files,
+};
+/**
+ * Adjacent directories to search for tests relative to a source file.
+ * Ordered by convention prevalence.
+ */
+const TEST_DIR_CANDIDATES = [
+    "__tests__",
+    "tests",
+    "test",
+];
+// ---------------------------------------------------------------------------
+// Test file discovery
+// ---------------------------------------------------------------------------
+/** Check if a path looks like a test file. */
+export function isTestFile(filePath) {
+    return TEST_FILE_PATTERNS.some((p) => p.test(filePath));
+}
+/**
+ * Given a source file path, generate candidate test file paths.
+ *
+ * For `src/agent/loop.ts`, generates:
+ * - `src/agent/loop.test.ts`
+ * - `src/agent/loop.spec.ts`
+ * - `src/agent/__tests__/loop.test.ts`
+ * - `tests/agent/loop.test.ts`  (mirrors src → tests)
+ * - etc.
+ */
+export function candidateTestPaths(filePath) {
+    if (isTestFile(filePath))
+        return [filePath];
+    const dir = dirname(filePath);
+    const ext = extname(filePath);
+    const base = basename(filePath, ext);
+    const candidates = [];
+    // Co-located: same directory with .test/.spec suffix
+    for (const suffix of [".test", ".spec"]) {
+        candidates.push(join(dir, `${base}${suffix}${ext}`));
+    }
+    // Adjacent test directories
+    for (const testDir of TEST_DIR_CANDIDATES) {
+        for (const suffix of [".test", ".spec"]) {
+            candidates.push(join(dir, testDir, `${base}${suffix}${ext}`));
+        }
+    }
+    // Mirror src → tests: src/foo/bar.ts → tests/foo/bar.test.ts
+    const srcDirMatch = dir.match(/^(.*?)src[/\\](.*)/);
+    if (srcDirMatch) {
+        const [, prefix, rest] = srcDirMatch;
+        for (const testDir of TEST_DIR_CANDIDATES) {
+            for (const suffix of [".test", ".spec"]) {
+                candidates.push(join(prefix, testDir, rest, `${base}${suffix}${ext}`));
+            }
+        }
+    }
+    return candidates;
+}
+/**
+ * Find test files that exist on disk for the given changed files.
+ *
+ * Deduplicates at two levels:
+ * 1. Candidate paths — avoids redundant stat() calls when multiple source
+ *    files generate the same candidate.
+ * 2. Result paths — prevents the same test file appearing twice in the output,
+ *    even if reached through differently-formatted candidate paths.
+ */
+export async function findRelevantTests(projectDir, filesChanged) {
+    const seenCandidates = new Set();
+    const seenResults = new Set();
+    const results = [];
+    for (const file of filesChanged) {
+        const candidates = candidateTestPaths(file);
+        for (const candidate of candidates) {
+            const normalized = normalize(candidate);
+            if (seenCandidates.has(normalized))
+                continue;
+            seenCandidates.add(normalized);
+            try {
+                const fullPath = join(projectDir, normalized);
+                const s = await stat(fullPath);
+                if (s.isFile() && !seenResults.has(normalized)) {
+                    seenResults.add(normalized);
+                    results.push(normalized);
+                }
+            }
+            catch {
+                // File doesn't exist — skip
+            }
+        }
+    }
+    return results;
+}
+// ---------------------------------------------------------------------------
+// Runner detection and scoping
+// ---------------------------------------------------------------------------
+/**
+ * Extract the test runner name from a test command string.
+ * e.g. "pnpm test" → "pnpm", "npx vitest" → "vitest", "vitest run" → "vitest"
+ */
+export function detectRunner(testCommand) {
+    const parts = testCommand.trim().split(/\s+/);
+    // Skip package manager wrappers to find the actual runner
+    for (const part of parts) {
+        const name = basename(part);
+        if (name in SCOPEABLE_RUNNERS)
+            return name;
+    }
+    return undefined;
+}
+/**
+ * Build a scoped test command targeting specific files.
+ * Returns undefined if the runner doesn't support file scoping.
+ *
+ * Preserves existing flags (e.g. `jest --ci` → `jest --ci -- file.test.ts`).
+ * Deduplicates the vitest `run` subcommand when already present.
+ */
+export function buildScopedCommand(testCommand, runner, testFiles) {
+    const scopeFn = SCOPEABLE_RUNNERS[runner];
+    if (!scopeFn)
+        return undefined;
+    const scopeArgs = scopeFn(testFiles);
+    const parts = testCommand.trim().split(/\s+/);
+    const runnerIdx = parts.findIndex((p) => basename(p) === runner);
+    if (runnerIdx >= 0) {
+        // Runner is explicitly in the command.
+        // Keep everything before AND after the runner, then append scope args.
+        const before = parts.slice(0, runnerIdx + 1);
+        const after = parts.slice(runnerIdx + 1);
+        // Deduplicate: if scope args start with a subcommand (e.g. "run")
+        // that is already present in the trailing args, strip it.
+        let mergedScope = scopeArgs;
+        if (after.length > 0 && scopeArgs.length > 0 && after[0] === scopeArgs[0]) {
+            mergedScope = scopeArgs.slice(1);
+        }
+        return [...before, ...after, ...mergedScope].join(" ");
+    }
+    // Package manager wrapper (e.g. "pnpm test") — append with --
+    return `${testCommand} -- ${testFiles.join(" ")}`;
+}
+// ---------------------------------------------------------------------------
+// Shell execution (via centralized process module)
+// ---------------------------------------------------------------------------
+import { execShellCmd } from "../process/index.js";
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+/**
+ * Run relevant tests after task completion.
+ *
+ * 1. Skip if no test command is configured.
+ * 2. Discover test files related to changed source files.
+ * 3. If relevant tests found and runner supports scoping, run scoped.
+ * 4. Otherwise, run the full test command.
+ * 5. Return structured results.
+ */
+export async function runPostTaskTests(options) {
+    const { projectDir, filesChanged, testCommand, timeout = DEFAULT_TIMEOUT } = options;
+    if (!testCommand) {
+        return { ran: false, passed: false, targetedFiles: [], error: "No test command configured" };
+    }
+    if (filesChanged.length === 0) {
+        return { ran: false, passed: false, targetedFiles: [], error: "No files changed" };
+    }
+    // Discover relevant test files
+    const testFiles = await findRelevantTests(projectDir, filesChanged);
+    // Determine if we can scope the run
+    const runner = detectRunner(testCommand);
+    let command;
+    let targetedFiles;
+    if (testFiles.length > 0 && runner) {
+        const scoped = buildScopedCommand(testCommand, runner, testFiles);
+        if (scoped) {
+            command = scoped;
+            targetedFiles = testFiles;
+        }
+        else {
+            command = testCommand;
+            targetedFiles = [];
+        }
+    }
+    else {
+        // Can't scope — run the full suite
+        command = testCommand;
+        targetedFiles = [];
+    }
+    const startMs = Date.now();
+    const { stdout, stderr, exitCode } = await execShellCmd(command, { cwd: projectDir, timeout, maxBuffer: 2 * 1024 * 1024 });
+    const durationMs = Date.now() - startMs;
+    const passed = exitCode === 0;
+    const output = truncateOutput(stdout, stderr, 2000);
+    return {
+        ran: true,
+        passed,
+        command,
+        output,
+        durationMs,
+        targetedFiles,
+        error: exitCode === null ? "Test command timed out" : undefined,
+    };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function truncateOutput(stdout, stderr, maxLen) {
+    // Prefer stdout (test results), fall back to stderr
+    const combined = stdout.trim() || stderr.trim();
+    if (combined.length <= maxLen)
+        return combined;
+    // Keep the last N characters (usually the summary is at the end)
+    return "…" + combined.slice(-(maxLen - 1));
+}
+//# sourceMappingURL=test-runner.js.map