taskplane 0.3.0 → 0.4.0

package/dashboard/server.cjs

@@ -23,6 +23,12 @@ const MAX_PORT_ATTEMPTS = 20;
 const POLL_INTERVAL = 2000; // ms between state checks
 
 // REPO_ROOT is resolved after parseArgs() — see initialization below.
+// In workspace mode, REPO_ROOT is the workspace root (passed via --root).
+// All dashboard state paths (batch-state, lane-state, conversation logs,
+// batch-history) live at <REPO_ROOT>/.pi/ — this is runtime/sidecar state
+// which does NOT follow the taskplane-pointer.json resolution chain.
+// The pointer directs config/agent lookups to a config repo, but the
+// dashboard only reads state files, so no pointer resolution is needed here.
 let REPO_ROOT;
 let BATCH_STATE_PATH;
 let BATCH_HISTORY_PATH;
@@ -630,7 +636,13 @@ async function findPort(server, start, explicit) {
 async function main() {
   const opts = parseArgs();
 
-  // Resolve project root: --root flag > cwd
+  // Resolve project root: --root flag > cwd.
+  // In workspace mode this is the workspace root. All state/sidecar files
+  // (batch-state, lane-state, conversation logs, batch-history) live at
+  // <REPO_ROOT>/.pi/ and are NOT affected by taskplane-pointer.json.
+  // The pointer only redirects config/agent resolution in task-runner and
+  // orchestrator — the dashboard reads only runtime state, so no pointer
+  // resolution is performed here.
   REPO_ROOT = path.resolve(opts.root || process.cwd());
   BATCH_STATE_PATH = path.join(REPO_ROOT, ".pi", "batch-state.json");
   BATCH_HISTORY_PATH = path.join(REPO_ROOT, ".pi", "batch-history.json");

package/extensions/task-runner.ts

@@ -26,7 +26,9 @@ import {
 } from "fs";
 import { tmpdir } from "os";
 import { join, dirname, basename, resolve } from "path";
-import { parse as yamlParse } from "yaml";
+import { loadProjectConfig, toTaskConfig } from "./taskplane/config-loader.ts";
+import { loadWorkspaceConfig, resolvePointer } from "./taskplane/workspace.ts";
+import type { PointerResolution } from "./taskplane/types.ts";
 
 
 // ── Types ────────────────────────────────────────────────────────────
@@ -137,54 +139,75 @@ const DEFAULT_CONFIG: TaskConfig = {
 	},
 };
 
-function loadConfig(cwd: string): TaskConfig {
-	let configPath = join(cwd, ".pi", "task-runner.yaml");
-	// In workspace mode, the worker runs in a repo worktree — not the workspace root.
-	// TASKPLANE_WORKSPACE_ROOT tells us where .pi/task-runner.yaml actually lives.
-	if (!existsSync(configPath) && process.env.TASKPLANE_WORKSPACE_ROOT) {
-		configPath = join(process.env.TASKPLANE_WORKSPACE_ROOT, ".pi", "task-runner.yaml");
-	}
-	if (!existsSync(configPath)) return { ...DEFAULT_CONFIG };
+// ── Pointer Resolution (Workspace Mode) ──────────────────────────────
+
+/** Track whether a pointer warning has been logged this session (log once). */
+let _pointerWarningLogged = false;
+
+/**
+ * Resolve the workspace pointer for config and agent path redirection.
+ *
+ * In workspace mode (TASKPLANE_WORKSPACE_ROOT set), reads the pointer
+ * file and resolves config/agent roots to the config repo. In repo mode,
+ * returns null (no pointer resolution needed).
+ *
+ * All pointer failures are non-fatal: missing, malformed, or invalid
+ * pointer files produce a warning and fall back to existing paths.
+ * Warning is logged to stderr once per session for operator visibility.
+ *
+ * @returns PointerResolution with resolved paths, or null in repo mode
+ */
+function resolveTaskRunnerPointer(): PointerResolution | null {
+	const wsRoot = process.env.TASKPLANE_WORKSPACE_ROOT;
+	if (!wsRoot) return null; // repo mode — no pointer needed
+
 	try {
-		const raw = readFileSync(configPath, "utf-8");
-		const loaded = yamlParse(raw) as any;
-		// Parse standards_overrides: Record<areaName, { docs?, rules? }>
-		const rawOverrides = loaded?.standards_overrides || {};
-		const parsedOverrides: Record<string, { docs?: string[]; rules?: string[] }> = {};
-		for (const [key, val] of Object.entries(rawOverrides)) {
-			if (val && typeof val === "object") {
-				const v = val as any;
-				parsedOverrides[key] = {
-					docs: Array.isArray(v.docs) ? v.docs : undefined,
-					rules: Array.isArray(v.rules) ? v.rules : undefined,
-				};
-			}
-		}
+		const wsConfig = loadWorkspaceConfig(wsRoot);
+		const result = resolvePointer(wsRoot, wsConfig);
 
-		// Parse task_areas minimally (we only need path for standards resolution)
-		const rawAreas = loaded?.task_areas || {};
-		const parsedAreas: Record<string, { path: string }> = {};
-		for (const [key, val] of Object.entries(rawAreas)) {
-			if (val && typeof val === "object" && (val as any).path) {
-				parsedAreas[key] = { path: (val as any).path };
-			}
+		// Surface pointer warnings once per session for operator visibility
+		if (result?.warning && !_pointerWarningLogged) {
+			_pointerWarningLogged = true;
+			console.error(`[task-runner] pointer: ${result.warning}`);
 		}
 
-		return {
-			project: { ...DEFAULT_CONFIG.project, ...loaded?.project },
-			paths: { ...DEFAULT_CONFIG.paths, ...loaded?.paths },
-			testing: { commands: { ...DEFAULT_CONFIG.testing.commands, ...loaded?.testing?.commands } },
-			standards: {
-				docs: loaded?.standards?.docs || DEFAULT_CONFIG.standards.docs,
-				rules: loaded?.standards?.rules || DEFAULT_CONFIG.standards.rules,
-			},
-			standards_overrides: parsedOverrides,
-			task_areas: parsedAreas,
-			worker: { ...DEFAULT_CONFIG.worker, ...loaded?.worker },
-			reviewer: { ...DEFAULT_CONFIG.reviewer, ...loaded?.reviewer },
-			context: { ...DEFAULT_CONFIG.context, ...loaded?.context },
-		};
+		return result;
+	} catch {
+		// Workspace config load failure — fall back gracefully
+		return null;
+	}
+}
+
+/** Reset pointer warning state (for testing only). */
+export function _resetPointerWarning(): void {
+	_pointerWarningLogged = false;
+}
+
+/** Expose loadAgentDef for testing (not part of public API). */
+export const _loadAgentDef = (cwd: string, name: string) => loadAgentDef(cwd, name);
+
+/**
+ * Load task-runner config via the unified config loader.
+ *
+ * Reads `.pi/taskplane-config.json` first; falls back to YAML files;
+ * then defaults. Returns the legacy snake_case TaskConfig shape so all
+ * downstream consumers remain unchanged.
+ *
+ * Config root resolution order (workspace mode with pointer):
+ *   1. cwd has config files → use cwd (local override)
+ *   2. Pointer-resolved config root has config files → use it
+ *   3. TASKPLANE_WORKSPACE_ROOT has config files → use it (legacy fallback)
+ *   4. Fall back to cwd (loaders will return defaults)
+ *
+ * Repo mode: pointer is ignored, existing behavior unchanged.
+ */
+export function loadConfig(cwd: string): TaskConfig {
+	try {
+		const pointer = resolveTaskRunnerPointer();
+		const unified = loadProjectConfig(cwd, pointer?.configRoot);
+		return toTaskConfig(unified);
 	} catch {
+		// If config loading fails (e.g., malformed JSON), fall back to defaults
 		return { ...DEFAULT_CONFIG };
 	}
 }
@@ -339,21 +362,153 @@ function clearConversationLog(prefix: string): void {
 
 // ── Agent Loader ─────────────────────────────────────────────────────
 
+/**
+ * Parse a markdown agent file into frontmatter key-value pairs and body content.
+ * Returns null if the file doesn't exist or has no frontmatter block.
+ */
+function parseAgentFile(filePath: string): { fm: Record<string, string>; body: string } | null {
+	if (!existsSync(filePath)) return null;
+	const raw = readFileSync(filePath, "utf-8").replace(/\r\n/g, "\n");
+	const match = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+	if (!match) return null;
+	const fm: Record<string, string> = {};
+	for (const line of match[1].split("\n")) {
+		const idx = line.indexOf(":");
+		if (idx > 0) fm[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
+	}
+	return { fm, body: match[2].trim() };
+}
+
+/** Cached package root — resolved once, reused for all agent file lookups. */
+let _packageRoot: string | null = null;
+
+/**
+ * Find the taskplane package root directory.
+ *
+ * Strategy: this file lives at <package-root>/extensions/task-runner.ts.
+ * When pi loads it via `-e`, it resolves the full path. We can find the
+ * package root by searching for package.json with name "taskplane"
+ * starting from known candidate locations.
+ */
+function findPackageRoot(): string {
+	if (_packageRoot !== null) return _packageRoot;
+
+	// Strategy 1: Walk up from this file's location via require.resolve or npm paths
+	const candidates: string[] = [];
+
+	// The extension is loaded by pi from the installed package location.
+	// Check well-known npm global paths.
+	const home = process.env.HOME || process.env.USERPROFILE || "";
+	if (home) {
+		candidates.push(join(home, "AppData", "Roaming", "npm", "node_modules", "taskplane"));
+		candidates.push(join(home, ".npm-global", "lib", "node_modules", "taskplane"));
+	}
+	candidates.push(join("/usr", "local", "lib", "node_modules", "taskplane"));
+
+	// Strategy 2: resolve from pi's node_modules peer
+	try {
+		const piPath = process.argv[1] || "";
+		const piPkgDir = resolve(piPath, "..", "..");
+		candidates.push(join(piPkgDir, "..", "taskplane"));
+	} catch { /* ignore */ }
+
+	// Strategy 3: Check TASKPLANE_WORKSPACE_ROOT project-local install
+	const wsRoot = process.env.TASKPLANE_WORKSPACE_ROOT;
+	if (wsRoot) {
+		candidates.push(join(wsRoot, ".pi", "npm", "node_modules", "taskplane"));
+		candidates.push(join(wsRoot, "node_modules", "taskplane"));
+	}
+
+	for (const dir of candidates) {
+		try {
+			const pkgPath = join(dir, "package.json");
+			if (existsSync(pkgPath)) {
+				const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+				if (pkg.name === "taskplane") {
+					_packageRoot = dir;
+					return dir;
+				}
+			}
+		} catch { /* ignore */ }
+	}
+
+	_packageRoot = "";
+	return "";
+}
+
+/**
+ * Resolve the package-shipped base agent file path.
+ * Base files live in the package's templates/agents/ directory.
+ */
+function resolveBaseAgentPath(name: string): string {
+	const root = findPackageRoot();
+	if (!root) return "";
+	return join(root, "templates", "agents", `${name}.md`);
+}
+
+/**
+ * Load an agent definition with prompt inheritance.
+ *
+ * Inheritance model (default: compose base + local):
+ * 1. Load base agent from the shipped package (templates/agents/{name}.md)
+ * 2. Load local agent from .pi/agents/{name}.md (if it exists) — or from
+ *    the pointer-resolved agent root in workspace mode
+ * 3. If local file has `standalone: true` in frontmatter, use it as-is (no base)
+ * 4. Otherwise, compose: base prompt + separator + local content
+ * 5. Local frontmatter values (tools, model) override base values
+ *
+ * Local override resolution order:
+ *   1. `<cwd>/.pi/agents/{name}.md` — worktree/repo local override (always first)
+ *   2. `<cwd>/agents/{name}.md` — worktree/repo local override (legacy location)
+ *   3. `<pointerAgentRoot>/{name}.md` — pointer-resolved config repo agents (workspace mode)
+ *   First found wins. If none found, base file is used directly.
+ *
+ * If no base file exists (e.g., custom agent), local file is used as-is.
+ */
 function loadAgentDef(cwd: string, name: string): { systemPrompt: string; tools: string; model: string } | null {
-	const paths = [join(cwd, ".pi", "agents", `${name}.md`), join(cwd, "agents", `${name}.md`)];
-	for (const p of paths) {
-		if (!existsSync(p)) continue;
-		const raw = readFileSync(p, "utf-8").replace(/\r\n/g, "\n");
-		const match = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
-		if (!match) continue;
-		const fm: Record<string, string> = {};
-		for (const line of match[1].split("\n")) {
-			const idx = line.indexOf(":");
-			if (idx > 0) fm[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
-		}
-		return { systemPrompt: match[2].trim(), tools: fm.tools || "read,grep,find,ls", model: fm.model || "" };
+	const basePath = resolveBaseAgentPath(name);
+	const localPaths = [join(cwd, ".pi", "agents", `${name}.md`), join(cwd, "agents", `${name}.md`)];
+
+	// In workspace mode, add pointer-resolved agent root as fallback
+	const pointer = resolveTaskRunnerPointer();
+	if (pointer?.agentRoot) {
+		localPaths.push(join(pointer.agentRoot, `${name}.md`));
+	}
+
+	// Load base from package
+	const baseDef = parseAgentFile(basePath);
+
+	// Load local override (first found wins)
+	let localDef: { fm: Record<string, string>; body: string } | null = null;
+	for (const p of localPaths) {
+		localDef = parseAgentFile(p);
+		if (localDef) break;
 	}
-	return null;
+
+	// No base and no local → null
+	if (!baseDef && !localDef) return null;
+
+	// Local with standalone: true → use local as-is, ignore base
+	if (localDef?.fm.standalone === "true") {
+		return {
+			systemPrompt: localDef.body,
+			tools: localDef.fm.tools || "read,grep,find,ls",
+			model: localDef.fm.model || "",
+		};
+	}
+
+	// Compose base + local
+	const basePrompt = baseDef?.body || "";
+	const localPrompt = localDef?.body || "";
+	const composedPrompt = localPrompt
+		? basePrompt + "\n\n---\n\n## Project-Specific Guidance\n\n" + localPrompt
+		: basePrompt;
+
+	// Local frontmatter overrides base (tools, model)
+	const tools = localDef?.fm.tools || baseDef?.fm.tools || "read,grep,find,ls";
+	const model = localDef?.fm.model || baseDef?.fm.model || "";
+
+	return { systemPrompt: composedPrompt.trim(), tools, model };
 }
 
 // ── PROMPT.md Parser ─────────────────────────────────────────────────