guardian-framework 0.1.77 → 0.1.78

package/dist/cli.js

@@ -3197,7 +3197,7 @@ __export(exports_package, {
   bin: () => bin,
   author: () => author
 });
-var name = "guardian-framework", version = "0.1.77", description = "Token-optimized agentic framework scaffolder with pi-first architecture", type = "module", main = "dist/exports.js", exports, types = "dist/exports.d.ts", bin, files, engines, scripts, publishConfig, pi, repository, homepage = "https://github.com/arman-jalili/guardian-framework#readme", bugs, dependencies, devDependencies, keywords, author = "Arman Wolkensteiner-Jalili", license = "MIT", package_default;
+var name = "guardian-framework", version = "0.1.78", description = "Token-optimized agentic framework scaffolder with pi-first architecture", type = "module", main = "dist/exports.js", exports, types = "dist/exports.d.ts", bin, files, engines, scripts, publishConfig, pi, repository, homepage = "https://github.com/arman-jalili/guardian-framework#readme", bugs, dependencies, devDependencies, keywords, author = "Arman Wolkensteiner-Jalili", license = "MIT", package_default;
 var init_package = __esm(() => {
   exports = {
     ".": {

package/dist/exports.js

@@ -1982,7 +1982,7 @@ __export(exports_package, {
   bin: () => bin,
   author: () => author
 });
-var name = "guardian-framework", version = "0.1.77", description = "Token-optimized agentic framework scaffolder with pi-first architecture", type = "module", main = "dist/exports.js", exports, types = "dist/exports.d.ts", bin, files, engines, scripts, publishConfig, pi, repository, homepage = "https://github.com/arman-jalili/guardian-framework#readme", bugs, dependencies, devDependencies, keywords, author = "Arman Wolkensteiner-Jalili", license = "MIT", package_default;
+var name = "guardian-framework", version = "0.1.78", description = "Token-optimized agentic framework scaffolder with pi-first architecture", type = "module", main = "dist/exports.js", exports, types = "dist/exports.d.ts", bin, files, engines, scripts, publishConfig, pi, repository, homepage = "https://github.com/arman-jalili/guardian-framework#readme", bugs, dependencies, devDependencies, keywords, author = "Arman Wolkensteiner-Jalili", license = "MIT", package_default;
 var init_package = __esm(() => {
   exports = {
     ".": {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "guardian-framework",
-	"version": "0.1.77",
+	"version": "0.1.78",
 	"description": "Token-optimized agentic framework scaffolder with pi-first architecture",
 	"type": "module",
 	"main": "dist/exports.js",

package/templates/pi/extensions/architect-lib/forge-adapter.ts

@@ -141,7 +141,8 @@ export function getGitBaseUrl(repoTool: string): string {
 
 export function commandExists(cmd: string): boolean {
 	try {
-		execSync(`command -v ${cmd}`, { stdio: "ignore" });
+		// Pass cmd as bash argument ($1) to avoid shell interpolation issues
+		execFileSync("bash", ["-c", `command -v "$1"`, "_", cmd], { stdio: "ignore" });
 		return true;
 	} catch {
 		return false;
@@ -150,10 +151,15 @@ export function commandExists(cmd: string): boolean {
 
 /**
  * Run a bash script and return exit code + stdout.
+ *
+ * Uses execFileSync with explicit arguments to avoid shell metacharacter bugs.
+ * The script is passed directly to bash -c without an outer shell layer,
+ * so characters like &, $, ", and ` inside the script are handled by bash,
+ * not by an intermediate sh process.
  */
 export function runScript(cwd: string, script: string): { exitCode: number; stdout: string } {
 	try {
-		const stdout = execSync(`bash -c "${script}"`, { cwd, timeout: 120_000, encoding: "utf-8" });
+		const stdout = execFileSync("bash", ["-c", script], { cwd, timeout: 120_000, encoding: "utf-8" });
 		return { exitCode: 0, stdout };
 	} catch (e: unknown) {
 		const err = e as { status?: number; stdout?: string; message?: string };

package/templates/pi/extensions/architect.ts

@@ -176,14 +176,19 @@ class EpicManager {
 			}
 		}
 
-		// Loud warning if GitLab remote setup failed
-		if (repoTool === "glab" && !hasRemote) {
-			console.warn(
-				"⚠️  GitLab remote repo setup failed. Pipeline will run LOCAL-ONLY."
-				+ " Issues will be created as local .md files, not on GitLab."
-				+ " Check that the repository path in guardian-manifest.json exists"
-				+ " and your GitLab token has 'write_repository' scope.",
+		// Abort if remote setup was required but failed
+		// (repoTool=glab or gh means the user explicitly chose GitHub/GitLab)
+		if (!hasRemote && repoTool !== "local") {
+			console.error(
+				`✖ Remote setup failed for "${targetRepo}" (repoTool: "${repoTool}").`
+				+ "\n\n  To fix:"
+				+ "\n  1. Ensure glab/gh CLI is authenticated (glab auth status / gh auth status)"
+				+ `\n  2. Verify "${targetRepo}" is a valid repository path`
+				+ "\n  3. Or set repoTool: \"local\" in guardian-manifest.json for local-only mode"
+				+ "\n",
 			);
+			this.ui.notify("Epic aborted — remote setup failed. Set repoTool: \"local\" to run without a remote forge.", "error");
+			return;
 		}
 
 		const issues: { id: string; title: string; status: string; remoteIssueId?: string | null }[] = [];

package/templates/pi/extensions/goal-loop.ts

@@ -23,53 +23,10 @@
  *   /subgoal clear        Remove all subgoals
  */
 
+import { execFileSync, execSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-
-// ── Types ──
-
-type ExtensionContext = {
-	cwd: string;
-	ui: {
-		notify(message: string, level?: string): void;
-		setStatus(key: string, message: string | null): void;
-		confirm(title: string, message: string): Promise<boolean>;
-	};
-	shell: {
-		execute(
-			command: string,
-			options?: { signal?: AbortSignal },
-		): Promise<{
-			exitCode: number;
-			stdout: string;
-		}>;
-	};
-	tools: { execute(name: string, params: Record<string, unknown>): Promise<unknown> };
-};
-
-type ExtensionAPI = {
-	on(event: string, handler: (event: unknown, ctx: ExtensionContext) => void | Promise<void>): void;
-	registerTool(options: {
-		name: string;
-		label: string;
-		description: string;
-		parameters: unknown;
-		execute(
-			toolCallId: string,
-			params: Record<string, unknown>,
-			signal: AbortSignal,
-			onUpdate: (update: { type: string; message: string }) => void,
-			ctx: ExtensionContext,
-		): unknown | Promise<unknown>;
-	}): void;
-	registerCommand(
-		name: string,
-		options: {
-			description: string;
-			handler(args: string, ctx: ExtensionContext): unknown | Promise<unknown>;
-		},
-	): void;
-};
+import type { ExtensionAPI, ExtensionContext, ExecResult } from "@earendil-works/pi-coding-agent";
 
 type GoalState = {
 	goal: string;
@@ -185,10 +142,10 @@ const BUILTIN_NAMES = Object.keys(BUILTIN_VALIDATORS);
 // ── Validator-Backed Judge ──
 
 async function runValidatorsForGoal(
-	ctx: ExtensionContext,
+	cwd: string,
 	validators: string[] = ["ci", "canonical"],
 ): Promise<{ pass: boolean; failures: string[]; results: Record<string, boolean> }> {
-	const registry = getAllValidators(ctx.cwd);
+	const registry = getAllValidators(cwd);
 	const results: Record<string, boolean> = {};
 	const failures: string[] = [];
 
@@ -199,21 +156,22 @@ async function runValidatorsForGoal(
 			failures.push(`${name}: unknown validator`);
 			continue;
 		}
-		const fullPath = join(ctx.cwd, relPath);
+		const fullPath = join(cwd, relPath);
 		if (!existsSync(fullPath)) {
 			results[name] = true; // missing script = skip = pass
 			continue;
 		}
 		try {
-			const r = await ctx.shell.execute(`bash ${relPath}`, {
-				signal: AbortSignal.timeout(60_000),
+			execFileSync("bash", [relPath], {
+				cwd,
+				timeout: 60_000,
+				encoding: "utf-8",
+				stdio: ["pipe", "pipe", "pipe"],
 			});
-			const passed = r.exitCode === 0;
-			results[name] = passed;
-			if (!passed) failures.push(`${name}: validator failed`);
+			results[name] = true;
 		} catch {
 			results[name] = false;
-			failures.push(`${name}: timeout or error`);
+			failures.push(`${name}: validator failed or timed out`);
 		}
 	}
 
@@ -221,7 +179,6 @@ async function runValidatorsForGoal(
 }
 
 async function runLLMJudge(
-	ctx: ExtensionContext,
 	goal: string,
 	lastResponse: string,
 	subgoals: string[],
@@ -236,16 +193,9 @@ async function runLLMJudge(
 
 	const prompt = `Goal:\n${truncatedGoal}\n${subgoalsBlock}\n\nAgent's most recent response:\n${truncatedResponse}\n\nIs the goal satisfied?`;
 
-	// Use guardian_coordinate to run an LLM-based judgment
-	try {
-		const result = await ctx.tools.execute("guardian_scope", {});
-		// We can't directly call LLM from extension — instead return a heuristic judgment
-		// The LLM judge runs via the agent itself being prompted to self-assess
-		// For now, return continue to let the agent decide
-		return { done: false, reason: "LLM judge requires agent self-assessment turn" };
-	} catch {
-		return { done: false, reason: "judge unavailable, continuing" };
-	}
+	// LLM judge runs via the agent itself being prompted to self-assess
+	// For now, return continue to let the agent decide
+	return { done: false, reason: "LLM judge requires agent self-assessment turn" };
 }
 
 function truncate(text: string, limit: number): string {
@@ -399,7 +349,7 @@ class GoalManager {
 
 		// Step 1: Run deterministic validators (per-goal list, or fallback)
 		const validatorsToRun = state.validators.length > 0 ? state.validators : ["ci", "canonical"];
-		const valResult = await runValidatorsForGoal(ctx, validatorsToRun);
+		const valResult = await runValidatorsForGoal(ctx.cwd, validatorsToRun);
 		state.validatorResults = {};
 		for (const [name, passed] of Object.entries(valResult.results)) {
 			state.validatorResults[name] = { passed, lastRun: new Date().toISOString() };
@@ -433,7 +383,7 @@ class GoalManager {
 
 		// Step 2: LLM semantic judge (via ask the agent to self-assess)
 		// We inject a self-assessment prompt into the continuation
-		const llmResult = await runLLMJudge(ctx, state.goal, lastResponse, state.subgoals);
+		const llmResult = await runLLMJudge(state.goal, lastResponse, state.subgoals);
 
 		if (llmResult.done) {
 			state.status = "done";

package/templates/pi/extensions/pipeline.ts

@@ -345,14 +345,14 @@ class PipelineManager {
 
 	private gitBranchExists(branch: string): boolean {
 		try {
-			const result = execSync(`git branch -a --list "${branch}" 2>/dev/null`, { cwd: this.cwd, encoding: "utf-8" });
+			const result = execFileSync("git", ["branch", "-a", "--list", branch], { cwd: this.cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
 			return result.trim().length > 0;
 		} catch { return false; }
 	}
 
 	private branchHasCommits(branch: string): boolean {
 		try {
-			const result = execSync(`git log --oneline "${branch}" 2>/dev/null | head -1`, { cwd: this.cwd, encoding: "utf-8" });
+			const result = execFileSync("git", ["log", "--oneline", branch], { cwd: this.cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
 			return result.trim().length > 0;
 		} catch { return false; }
 	}
@@ -624,7 +624,7 @@ class PipelineManager {
 
 		if (acceptance.type === "shell") {
 			try {
-				execSync(`bash -c "${acceptance.command}"`, { cwd: this.cwd, timeout: 300_000, encoding: "utf-8" });
+				execFileSync("bash", ["-c", acceptance.command], { cwd: this.cwd, timeout: 300_000, encoding: "utf-8" });
 				return { allPassed: true, errors: [] };
 			} catch (e: unknown) {
 				const err = e as { stdout?: string };
@@ -637,7 +637,7 @@ class PipelineManager {
 				const scriptPath = VALIDATOR_SCRIPTS[validator];
 				if (!scriptPath) { errors.push(`Unknown validator: ${validator}`); continue; }
 				try {
-					execSync(`bash -c "${scriptPath}"`, { cwd: this.cwd, timeout: 120_000, encoding: "utf-8" });
+					execFileSync("bash", ["-c", scriptPath], { cwd: this.cwd, timeout: 120_000, encoding: "utf-8" });
 				} catch (e: unknown) {
 					const err = e as { stdout?: string };
 					errors.push(`${validator}: ${(err.stdout || "").slice(0, 200)}`);
@@ -908,26 +908,6 @@ export default function (pi: ExtensionAPI) {
 
 			// Pipeline complete
 			if (updatedState.currentItemIndex >= updatedState.items.length) {
-				// Non-blocking: close tracking issue and epic on pipeline completion
-				try {
-					const epicStatePath = join(ctx.cwd, ".pi/.guardian-epic-state.json");
-					if (existsSync(epicStatePath)) {
-						const epicState = JSON.parse(readFileSync(epicStatePath, "utf-8")) as {
-							trackingIssueId?: string | null;
-							epicId?: string | null;
-						};
-						if (epicState.trackingIssueId && !epicState.trackingIssueId.startsWith("local:")) {
-							const closeEpicScript = join(ctx.cwd, ".pi/scripts/git/close-epic.sh");
-							if (existsSync(closeEpicScript)) {
-								const args: string[] = [closeEpicScript, "--tracking-id", epicState.trackingIssueId];
-								if (epicState.epicId) args.push("--epic-id", epicState.epicId);
-								execFileSync("bash", args, {
-									cwd: ctx.cwd, timeout: 30_000, encoding: "utf-8", stdio: "ignore",
-								});
-							}
-						}
-					}
-				} catch { /* non-blocking */ }
 				return {
 					content: [{
 						type: "text" as const,
@@ -941,7 +921,7 @@ export default function (pi: ExtensionAPI) {
 			const movedToNextItem = updatedState.currentItemIndex !== prevItemIndex;
 
 			// If we moved to a new item (completed all steps of previous item),
-			// close its remote issue
+			// close its remote issue and inject the full next-task prompt
 			if (movedToNextItem) {
 				// Close remote issue for the completed item
 				try {
@@ -962,21 +942,50 @@ export default function (pi: ExtensionAPI) {
 						}
 					}
 				} catch { /* non-blocking */ }
+
+				// If the pipeline is fully complete, close tracking issue and epic too
+				if (updatedState.currentItemIndex >= updatedState.items.length) {
+					try {
+						const epicStatePath = join(ctx.cwd, ".pi/.guardian-epic-state.json");
+						if (existsSync(epicStatePath)) {
+							const epicState = JSON.parse(readFileSync(epicStatePath, "utf-8")) as {
+								trackingIssueId?: string | null;
+								epicId?: string | null;
+							};
+							if (epicState.trackingIssueId && !epicState.trackingIssueId.startsWith("local:")) {
+								const closeEpicScript = join(ctx.cwd, ".pi/scripts/git/close-epic.sh");
+								if (existsSync(closeEpicScript)) {
+									const args: string[] = [closeEpicScript, "--tracking-id", epicState.trackingIssueId];
+									if (epicState.epicId) args.push("--epic-id", epicState.epicId);
+									execFileSync("bash", args, {
+										cwd: ctx.cwd, timeout: 30_000, encoding: "utf-8", stdio: "ignore",
+									});
+								}
+							}
+						}
+					} catch { /* non-blocking */ }
+				}
 			}
 
 			// If we moved to a new item and the next step is implement,
 			// inject the full next-task prompt with issue context
 			if (movedToNextItem && currentStep?.name === "implement") {
-				// Find the remote issue ID from epic state
+				// Load epic state for TDD context and remote issue ID
+				let epicTdd = false;
+				let epicTddTestFiles: string[] = [];
 				let remoteId: string | null | undefined;
 				try {
 					const epicStatePath = join(ctx.cwd, ".pi/.guardian-epic-state.json");
 					if (existsSync(epicStatePath)) {
 						const epicState = JSON.parse(readFileSync(epicStatePath, "utf-8")) as {
 							issues?: { id: string; remoteIssueId?: string | null }[];
+							tdd?: boolean;
+							tddTestFiles?: string[];
 						};
 						const issue = epicState.issues?.find((i) => i.id === currentItem);
 						remoteId = issue?.remoteIssueId;
+						epicTdd = epicState.tdd ?? false;
+						epicTddTestFiles = epicState.tddTestFiles ?? [];
 					}
 				} catch {
 					// ignore
@@ -988,6 +997,19 @@ export default function (pi: ExtensionAPI) {
 					remoteId,
 				);
 
+				const tddAdvanceBlock = epicTdd
+					? [
+						"",
+						"## TDD: Red-Green-Refactor",
+						"",
+						"Failing tests already exist for this component. Follow TDD:",
+						"1. **RED:** Run the failing tests first to confirm they fail",
+						"2. **GREEN:** Write minimal implementation to make tests pass",
+						"3. **REFACTOR:** Clean up while keeping tests green",
+						"",
+					].join("\n")
+					: "";
+
 				const instructions = [
 					`## Pipeline: Moving to next item`,
 					"",
@@ -996,10 +1018,13 @@ export default function (pi: ExtensionAPI) {
 					`**Issue:** ${issueSource}`,
 					"",
 					`**Next task:** Item "${currentItem}" → Step: implement`,
+					tddAdvanceBlock,
 					"",
 					"**Instructions:**",
 					"1. Review the issue context below",
-					"2. Implement the component according to the issue spec",
+					epicTdd
+						? "2. Run the pre-generated failing tests to confirm RED phase"
+						: "2. Implement the component according to the issue spec",
 					"3. Run `pipeline_run_acceptance` to validate",
 					"4. Call `pipeline_advance` when done",
 					"",
@@ -1142,16 +1167,22 @@ export default function (pi: ExtensionAPI) {
 			const step = state.steps[state.currentStepIndex];
 			if (!step) return { content: [{ type: "text" as const, text: "No more steps." }] };
 
-			// Find the remote issue ID from epic state
+			// Load epic state for TDD context and remote issue ID
+			let epicTdd = false;
+			let epicTddTestFiles: string[] = [];
 			let remoteId: string | null | undefined;
 			try {
 				const epicStatePath = join(ctx.cwd, ".pi/.guardian-epic-state.json");
 				if (existsSync(epicStatePath)) {
 					const epicState = JSON.parse(readFileSync(epicStatePath, "utf-8")) as {
 						issues?: { id: string; remoteIssueId?: string | null }[];
+						tdd?: boolean;
+						tddTestFiles?: string[];
 					};
 					const issue = epicState.issues?.find((i) => i.id === issueId);
 					remoteId = issue?.remoteIssueId;
+					epicTdd = epicState.tdd ?? false;
+					epicTddTestFiles = epicState.tddTestFiles ?? [];
 				}
 			} catch {
 				// ignore
@@ -1173,6 +1204,29 @@ export default function (pi: ExtensionAPI) {
 				}
 			}
 
+			const tddBlock = epicTdd
+				? [
+					"",
+					"---",
+					"",
+					"## TDD: Red-Green-Refactor",
+					"",
+					"Failing test files have already been generated. Follow TDD discipline:",
+					"",
+					"**1. RED — Run the failing tests first:**",
+					...epicTddTestFiles.map((f) => `  - \`${f}\``),
+					"",
+					"**2. GREEN — Implement the minimum code to make tests pass:**",
+					"  - Do NOT write new test files — the tests already exist",
+					"  - Focus on the implementation only",
+					"  - Run tests after each change to track progress",
+					"",
+					"**3. REFACTOR — Clean up while keeping tests green:**",
+					"  - Extract helpers, improve naming, remove duplication",
+					"",
+				].join("\n")
+				: "";
+
 			const text = [
 				"## Pipeline Task",
 				"",
@@ -1184,6 +1238,7 @@ export default function (pi: ExtensionAPI) {
 				"---",
 				"",
 				stepPrompt || "",
+				tddBlock,
 				"",
 				"---",
 				"",
@@ -1240,7 +1295,7 @@ export default function (pi: ExtensionAPI) {
 					return { content: [{ type: "text" as const, text: lines.join("\n") }] };
 				}
 				try {
-					const output = execSync("bash " + scriptPath, {
+					const output = execFileSync("bash", [scriptPath], {
 						cwd: ctx.cwd,
 						timeout: 300_000,
 						encoding: "utf-8",
@@ -1279,7 +1334,7 @@ export default function (pi: ExtensionAPI) {
 					continue;
 				}
 				try {
-					execSync(`bash -c "${scriptPath}"`, {
+					execFileSync("bash", ["-c", scriptPath], {
 						cwd: ctx.cwd,
 						timeout: 120_000,
 						encoding: "utf-8",

package/templates/pi/preflight_report.json

@@ -1,5 +1,5 @@
 {
-  "timestamp": "2026-07-13T13:10:35Z",
+  "timestamp": "2026-07-14T09:09:07Z",
   "mode": "all",
   "stages_run": [],
   "summary": {