guardian-framework 0.1.143 → 0.1.145

package/dist/cli.js

@@ -3206,7 +3206,7 @@ __export(exports_package, {
   bin: () => bin,
   author: () => author
 });
-var name = "guardian-framework", version = "0.1.143", 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.145", 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 = {
     ".": {
@@ -11625,6 +11625,117 @@ import * as path3 from "path";
 import * as crypto from "crypto";
 import * as fs from "fs";
 import * as path2 from "path";
+
+// src/lib/language-stubs.ts
+var FENCE = {
+  typescript: "typescript",
+  nextjs: "typescript",
+  angular: "typescript",
+  rust: "rust",
+  python: "python",
+  go: "go",
+  java: "java"
+};
+function normalizeStubLanguage(language) {
+  const l2 = (language ?? "").trim().toLowerCase();
+  if (l2 === "nextjs" || l2 === "angular" || l2 === "typescript")
+    return "typescript";
+  if (l2 === "rust" || l2 === "python" || l2 === "go" || l2 === "java")
+    return l2;
+  return "neutral";
+}
+function renderRepositoryInterface(language, aggregateName) {
+  const lang = normalizeStubLanguage(language);
+  const fence = FENCE[lang] ?? "text";
+  const id = `${aggregateName}Id`;
+  if (lang === "rust") {
+    return [
+      `\`\`\`${fence}`,
+      `pub trait ${aggregateName}Repository: Send + Sync {`,
+      `    async fn find_by_id(&self, id: &${id}) -> Result<Option<${aggregateName}>, DomainError>;`,
+      `    async fn save(&self, ${lowerFirst(aggregateName)}: &${aggregateName}) -> Result<(), DomainError>;`,
+      `    async fn delete(&self, id: &${id}) -> Result<(), DomainError>;`,
+      "}",
+      "```"
+    ].join(`
+`);
+  }
+  if (lang === "python") {
+    return [
+      `\`\`\`${fence}`,
+      "from abc import ABC, abstractmethod",
+      "",
+      "",
+      `class ${aggregateName}Repository(ABC):`,
+      `    """Persistence port for the ${aggregateName} aggregate (implemented in infrastructure)."""`,
+      "",
+      "    @abstractmethod",
+      `    async def find_by_id(self, id_: ${id}) -> ${aggregateName} | None: ...`,
+      "",
+      "    @abstractmethod",
+      `    async def save(self, ${snake(aggregateName)}: ${aggregateName}) -> None: ...`,
+      "",
+      "    @abstractmethod",
+      `    async def delete(self, id_: ${id}) -> None: ...`,
+      "```"
+    ].join(`
+`);
+  }
+  if (lang === "java") {
+    return [
+      `\`\`\`${fence}`,
+      `public interface ${aggregateName}Repository {`,
+      `    Optional<${aggregateName}> findById(${id} id);`,
+      `    void save(${aggregateName} ${lowerFirst(aggregateName)});`,
+      `    void delete(${id} id);`,
+      "}",
+      "```"
+    ].join(`
+`);
+  }
+  if (lang === "go") {
+    return [
+      `\`\`\`${fence}`,
+      `// ${aggregateName}Repository is the persistence port for the ${aggregateName} aggregate.`,
+      `type ${aggregateName}Repository interface {`,
+      `	FindByID(ctx context.Context, id ${id}) (*${aggregateName}, error)`,
+      `	Save(ctx context.Context, ${lowerFirst(aggregateName)} *${aggregateName}) error`,
+      `	Delete(ctx context.Context, id ${id}) error`,
+      "}",
+      "```"
+    ].join(`
+`);
+  }
+  if (lang === "typescript") {
+    return [
+      `\`\`\`${fence}`,
+      `export interface ${aggregateName}Repository {`,
+      `  findById(id: ${id}): Promise<${aggregateName} | null>;`,
+      `  save(${lowerFirst(aggregateName)}: ${aggregateName}): Promise<void>;`,
+      `  delete(id: ${id}): Promise<void>;`,
+      "}",
+      "```"
+    ].join(`
+`);
+  }
+  return [
+    `\`\`\`${fence}`,
+    `${aggregateName}Repository (persistence port)`,
+    `  findById(id: ${id}) -> ${aggregateName} | null`,
+    `  save(${aggregateName}) -> void`,
+    `  delete(id: ${id}) -> void`,
+    "```"
+  ].join(`
+`);
+}
+function lowerFirst(s) {
+  return s.length > 0 ? s.charAt(0).toLowerCase() + s.slice(1) : s;
+}
+function snake(s) {
+  return s.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[\s-]+/g, "_").toLowerCase();
+}
+
+// src/lib/domain-explorer.ts
 var __dirname = "/Users/arman/project/guardian-framework/src/lib", __filename = "/Users/arman/project/guardian-framework/src/lib/domain-explorer.ts";
 var MAX_BUSINESS_CONTEXT_LENGTH = 5000;
 function sanitizeBusinessContext(context) {
@@ -12793,23 +12904,11 @@ ${bc.description}
             content += `
 `;
           }
-          const arVarName = ar.name.charAt(0).toLowerCase() + ar.name.slice(1);
           content += `**Repository Interface:**
 `;
           content += `
 `;
-          content += "```rust\n";
-          content += `pub trait ${ar.name}Repository: Send + Sync {
-`;
-          content += `    async fn find_by_id(&self, id: &${ar.name}Id) -> Result<Option<${ar.name}>, DomainError>;
-`;
-          content += `    async fn save(&self, ${arVarName}: &${ar.name}) -> Result<(), DomainError>;
-`;
-          content += `    async fn delete(&self, id: &${ar.name}Id) -> Result<(), DomainError>;
-`;
-          content += `}
-`;
-          content += "```";
+          content += renderRepositoryInterface(lang, ar.name);
           content += `
 `;
           if (ownedEntities.length > 0 || ownedVOs.length > 0 || invariants.length > 0) {

package/dist/exports.js

@@ -1991,7 +1991,7 @@ __export(exports_package, {
   bin: () => bin,
   author: () => author
 });
-var name = "guardian-framework", version = "0.1.143", 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.145", 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 = {
     ".": {
@@ -11948,6 +11948,117 @@ import * as path12 from "node:path";
 import * as crypto4 from "node:crypto";
 import * as fs12 from "node:fs";
 import * as path11 from "node:path";
+
+// src/lib/language-stubs.ts
+var FENCE = {
+  typescript: "typescript",
+  nextjs: "typescript",
+  angular: "typescript",
+  rust: "rust",
+  python: "python",
+  go: "go",
+  java: "java"
+};
+function normalizeStubLanguage(language) {
+  const l2 = (language ?? "").trim().toLowerCase();
+  if (l2 === "nextjs" || l2 === "angular" || l2 === "typescript")
+    return "typescript";
+  if (l2 === "rust" || l2 === "python" || l2 === "go" || l2 === "java")
+    return l2;
+  return "neutral";
+}
+function renderRepositoryInterface(language, aggregateName) {
+  const lang = normalizeStubLanguage(language);
+  const fence = FENCE[lang] ?? "text";
+  const id = `${aggregateName}Id`;
+  if (lang === "rust") {
+    return [
+      `\`\`\`${fence}`,
+      `pub trait ${aggregateName}Repository: Send + Sync {`,
+      `    async fn find_by_id(&self, id: &${id}) -> Result<Option<${aggregateName}>, DomainError>;`,
+      `    async fn save(&self, ${lowerFirst(aggregateName)}: &${aggregateName}) -> Result<(), DomainError>;`,
+      `    async fn delete(&self, id: &${id}) -> Result<(), DomainError>;`,
+      "}",
+      "```"
+    ].join(`
+`);
+  }
+  if (lang === "python") {
+    return [
+      `\`\`\`${fence}`,
+      "from abc import ABC, abstractmethod",
+      "",
+      "",
+      `class ${aggregateName}Repository(ABC):`,
+      `    """Persistence port for the ${aggregateName} aggregate (implemented in infrastructure)."""`,
+      "",
+      "    @abstractmethod",
+      `    async def find_by_id(self, id_: ${id}) -> ${aggregateName} | None: ...`,
+      "",
+      "    @abstractmethod",
+      `    async def save(self, ${snake(aggregateName)}: ${aggregateName}) -> None: ...`,
+      "",
+      "    @abstractmethod",
+      `    async def delete(self, id_: ${id}) -> None: ...`,
+      "```"
+    ].join(`
+`);
+  }
+  if (lang === "java") {
+    return [
+      `\`\`\`${fence}`,
+      `public interface ${aggregateName}Repository {`,
+      `    Optional<${aggregateName}> findById(${id} id);`,
+      `    void save(${aggregateName} ${lowerFirst(aggregateName)});`,
+      `    void delete(${id} id);`,
+      "}",
+      "```"
+    ].join(`
+`);
+  }
+  if (lang === "go") {
+    return [
+      `\`\`\`${fence}`,
+      `// ${aggregateName}Repository is the persistence port for the ${aggregateName} aggregate.`,
+      `type ${aggregateName}Repository interface {`,
+      `	FindByID(ctx context.Context, id ${id}) (*${aggregateName}, error)`,
+      `	Save(ctx context.Context, ${lowerFirst(aggregateName)} *${aggregateName}) error`,
+      `	Delete(ctx context.Context, id ${id}) error`,
+      "}",
+      "```"
+    ].join(`
+`);
+  }
+  if (lang === "typescript") {
+    return [
+      `\`\`\`${fence}`,
+      `export interface ${aggregateName}Repository {`,
+      `  findById(id: ${id}): Promise<${aggregateName} | null>;`,
+      `  save(${lowerFirst(aggregateName)}: ${aggregateName}): Promise<void>;`,
+      `  delete(id: ${id}): Promise<void>;`,
+      "}",
+      "```"
+    ].join(`
+`);
+  }
+  return [
+    `\`\`\`${fence}`,
+    `${aggregateName}Repository (persistence port)`,
+    `  findById(id: ${id}) -> ${aggregateName} | null`,
+    `  save(${aggregateName}) -> void`,
+    `  delete(id: ${id}) -> void`,
+    "```"
+  ].join(`
+`);
+}
+function lowerFirst(s) {
+  return s.length > 0 ? s.charAt(0).toLowerCase() + s.slice(1) : s;
+}
+function snake(s) {
+  return s.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[\s-]+/g, "_").toLowerCase();
+}
+
+// src/lib/domain-explorer.ts
 var __dirname = "/Users/arman/project/guardian-framework/src/lib", __filename = "/Users/arman/project/guardian-framework/src/lib/domain-explorer.ts";
 var MAX_BUSINESS_CONTEXT_LENGTH = 5000;
 function sanitizeBusinessContext(context) {
@@ -13116,23 +13227,11 @@ ${bc.description}
             content += `
 `;
           }
-          const arVarName = ar.name.charAt(0).toLowerCase() + ar.name.slice(1);
           content += `**Repository Interface:**
 `;
           content += `
 `;
-          content += "```rust\n";
-          content += `pub trait ${ar.name}Repository: Send + Sync {
-`;
-          content += `    async fn find_by_id(&self, id: &${ar.name}Id) -> Result<Option<${ar.name}>, DomainError>;
-`;
-          content += `    async fn save(&self, ${arVarName}: &${ar.name}) -> Result<(), DomainError>;
-`;
-          content += `    async fn delete(&self, id: &${ar.name}Id) -> Result<(), DomainError>;
-`;
-          content += `}
-`;
-          content += "```";
+          content += renderRepositoryInterface(lang, ar.name);
           content += `
 `;
           if (ownedEntities.length > 0 || ownedVOs.length > 0 || invariants.length > 0) {

package/package.json

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

package/templates/pi/extensions/architect.ts

@@ -1,3 +1,28 @@
+// ── Epic-mode pipeline (one branch, one PR per epic) ───────────────────────
+// Default is "epic": issues commit to one epic branch, each item is gated by
+// local CI, and a single PR is opened after the last item. `--pr-per issue`
+// restores the legacy per-issue PR flow.
+function prStrategyFor(ctx: { cwd: string }): "issue" | "epic" {
+	try {
+		const statePath = join(ctx.cwd, ".pi", ".guardian-epic-state.json");
+		if (existsSync(statePath)) {
+			const st = JSON.parse(readFileSync(statePath, "utf-8")) as { prStrategy?: "issue" | "epic" };
+			if (st.prStrategy === "issue" || st.prStrategy === "epic") return st.prStrategy;
+		}
+	} catch {
+		// ignore
+	}
+	return "epic";
+}
+
+function epicBranchName(moduleName: string): string {
+	const slug = String(moduleName ?? "epic")
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-|-$/g, "");
+	return `epic/${slug || "epic"}`;
+}
+
 /**
  * Architect Extension — Full Architecture-to-Implementation Pipeline
  *
@@ -467,7 +492,7 @@ export default function architectExtension(pi: ExtensionAPI) {
 			const tokens = raw ? parseArgs(raw) : [];
 			if (tokens.length === 0) {
 				ctx.ui.notify(
-					"Usage: /architect [--epic Name] [--tracking-issue N] [--tdd] | --roadmap | --phase \"Phase 1\" | --phase-status | --phase-done <N> | --phase-module-done <N> \"Module\" | status | next-epic | abort",
+					"Usage: /architect [--epic Name] [--tracking-issue N] [--tdd] [--pr-per epic|issue] | --roadmap | --phase \"Phase 1\" | --phase-status | --phase-done <N> | --phase-module-done <N> \"Module\" | status | next-epic | abort",
 					"info",
 				);
 				return;
@@ -611,8 +636,8 @@ export default function architectExtension(pi: ExtensionAPI) {
 								steps: [
 									{ name: "implement", prompt: ".pi/prompts/issue-implementation-series.md", acceptance: { type: "validator", validators: ["ci"] } },
 									{ name: "validate", acceptance: { type: "validator", validators: ["ci", "tests", "security"] } },
-									{ name: "create-mr", prompt: ".pi/prompts/issue-closeout.md", acceptance: { type: "none" } },
-									{ name: "merge", prompt: ".pi/prompts/issue-merge.md", acceptance: { type: "validator", validators: ["ci", "canonical"] } },
+									{ name: "create-mr", prompt: ".pi/prompts/epic-closeout.md", acceptance: { type: "none" } },
+									{ name: "merge", prompt: ".pi/prompts/epic-closeout.md", acceptance: { type: "validator", validators: ["ci", "canonical"] } },
 								],
 								currentItemIndex: 0,
 								currentStepIndex: 0,
@@ -620,6 +645,8 @@ export default function architectExtension(pi: ExtensionAPI) {
 								retryCount: 0,
 								results: [],
 								mergeOnValid: true,
+								prStrategy: prStrategyFor(ctx),
+								epicBranch: epicBranchName(mod.name),
 								createdAt: new Date().toISOString(),
 								updatedAt: new Date().toISOString(),
 							};
@@ -671,8 +698,8 @@ export default function architectExtension(pi: ExtensionAPI) {
 							steps: [
 								{ name: "implement", prompt: ".pi/prompts/issue-implementation-series.md", acceptance: { type: "validator", validators: ["ci"] } },
 								{ name: "validate", acceptance: { type: "validator", validators: ["ci", "tests", "security"] } },
-								{ name: "create-mr", prompt: ".pi/prompts/issue-closeout.md", acceptance: { type: "none" } },
-								{ name: "merge", prompt: ".pi/prompts/issue-merge.md", acceptance: { type: "validator", validators: ["ci", "canonical"] } },
+								{ name: "create-mr", prompt: ".pi/prompts/epic-closeout.md", acceptance: { type: "none" } },
+								{ name: "merge", prompt: ".pi/prompts/epic-closeout.md", acceptance: { type: "validator", validators: ["ci", "canonical"] } },
 							],
 							currentItemIndex: 0,
 							currentStepIndex: 0,
@@ -680,6 +707,8 @@ export default function architectExtension(pi: ExtensionAPI) {
 							retryCount: 0,
 							results: [],
 							mergeOnValid: true,
+							prStrategy: prStrategyFor(ctx),
+							epicBranch: epicBranchName(mod.name),
 							createdAt: new Date().toISOString(),
 							updatedAt: new Date().toISOString(),
 						};
@@ -830,6 +859,21 @@ export default function architectExtension(pi: ExtensionAPI) {
 
 			const epicName = findFlag(tokens, "--epic");
 			const trackingIssueId = findFlag(tokens, "--tracking-issue");
+			// --pr-per epic (default) | issue  — one PR for the whole epic, or the
+			// legacy per-issue PR flow.
+			const prPerFlag = (findFlag(tokens, "--pr-per") ?? "epic").toLowerCase();
+			const epicPrStrategy: "issue" | "epic" = prPerFlag === "issue" ? "issue" : "epic";
+			try {
+				const epicStatePath = join(ctx.cwd, ".pi", ".guardian-epic-state.json");
+				const st = existsSync(epicStatePath)
+					? (JSON.parse(readFileSync(epicStatePath, "utf-8")) as Record<string, unknown>)
+					: {};
+				st.prStrategy = epicPrStrategy;
+				mkdirSync(join(ctx.cwd, ".pi"), { recursive: true });
+				writeFileSync(epicStatePath, JSON.stringify(st, null, 2), "utf-8");
+			} catch {
+				// ignore — strategy falls back to epic
+			}
 			const tddEnabled = tokens.includes("--tdd");
 
 			if (!epicName) {
@@ -881,8 +925,8 @@ export default function architectExtension(pi: ExtensionAPI) {
 					steps: [
 						{ name: "implement", prompt: ".pi/prompts/issue-implementation-series.md", acceptance: { type: "validator", validators: ["ci"] } },
 						{ name: "validate", acceptance: { type: "validator", validators: ["ci", "tests", "security"] } },
-						{ name: "create-mr", prompt: ".pi/prompts/issue-closeout.md", acceptance: { type: "none" } },
-						{ name: "merge", prompt: ".pi/prompts/issue-merge.md", acceptance: { type: "validator", validators: ["ci", "canonical"] } },
+						{ name: "create-mr", prompt: ".pi/prompts/epic-closeout.md", acceptance: { type: "none" } },
+						{ name: "merge", prompt: ".pi/prompts/epic-closeout.md", acceptance: { type: "validator", validators: ["ci", "canonical"] } },
 					],
 					currentItemIndex: 0,
 					currentStepIndex: 0,
@@ -890,6 +934,8 @@ export default function architectExtension(pi: ExtensionAPI) {
 					retryCount: 0,
 					results: [],
 					mergeOnValid: true,
+					prStrategy: prStrategyFor(ctx),
+					epicBranch: epicBranchName(epicName),
 					createdAt: new Date().toISOString(),
 					updatedAt: new Date().toISOString(),
 				};

package/templates/pi/extensions/pipeline.ts

@@ -155,6 +155,18 @@ type PipelineState = {
 	retryCount: number;
 	results: ItemResult[];
 	mergeOnValid: boolean;
+	/**
+	 * "issue" (legacy): implement → validate → create-mr → merge per item.
+	 * "epic" (default for /architect): every item implements on ONE epic branch,
+	 * local-ci gates each item, and a single PR is opened/merged for the epic.
+	 */
+	prStrategy?: "issue" | "epic";
+	/** Branch shared by all items in epic mode (e.g. epic/policy-engine). */
+	epicBranch?: string;
+	/** Set once the epic PR has been created in epic mode. */
+	epicPrCreated?: boolean;
+	/** Set when the last item finished in epic mode (open the single PR now). */
+	epicReadyForPr?: boolean;
 	createdAt: string;
 	updatedAt: string;
 };
@@ -422,22 +434,48 @@ class PipelineManager {
 		if (!step) return { verified: true, reason: "No current step" };
 
 		const slug = item.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
-		const branch = `feat/${slug}`;
+		const epicMode = this.state?.prStrategy === "epic";
+		const epicBranch = this.state?.epicBranch ?? "";
+		// In epic mode every item lands on the shared epic branch; there is no
+		// per-item branch, no per-item PR and no per-item merge.
+		const branch = epicMode ? epicBranch : `feat/${slug}`;
 
 		switch (step.name) {
 			case "implement": {
+				if (!epicMode) {
+					if (!this.gitBranchExists(branch) || !this.branchHasCommits(branch)) {
+						return { verified: false, reason: `No commits found on branch ${branch}. Implement the feature first.` };
+					}
+					return { verified: true, reason: "Commits found on branch" };
+				}
+				if (!epicMode || !branch) {
+					return { verified: false, reason: "Epic mode requires an epic branch (state.epicBranch)." };
+				}
 				if (!this.gitBranchExists(branch) || !this.branchHasCommits(branch)) {
-					return { verified: false, reason: `No commits found on branch ${branch}. Implement the feature first.` };
+					return { verified: false, reason: `No commits found on epic branch ${branch}. Implement the item there first.` };
 				}
-				return { verified: true, reason: "Commits found on branch" };
+				return { verified: true, reason: `Commits found on epic branch ${branch}` };
 			}
 			case "create-mr": {
+				if (epicMode) {
+					// Deferred: the epic PR is opened once, after the last item.
+					return { verified: true, reason: "Epic mode: PR is created once for the whole epic (deferred)" };
+				}
 				if (!this.forgePrExists(branch)) {
 					return { verified: false, reason: `No PR/MR found for branch ${branch}. Create a PR/MR first.` };
 				}
 				return { verified: true, reason: "PR/MR exists" };
 			}
 			case "merge": {
+				if (epicMode) {
+					if (!this.state?.epicPrCreated) {
+						return { verified: true, reason: "Epic mode: merge handled at epic level" };
+					}
+					if (!this.forgePrMerged(branch)) {
+						return { verified: false, reason: `Epic PR for ${branch} is not merged yet.` };
+					}
+					return { verified: true, reason: "Epic PR merged" };
+				}
 				if (!this.forgePrMerged(branch)) {
 					return { verified: false, reason: `PR/MR for ${branch} is not merged yet.` };
 				}
@@ -573,6 +611,12 @@ class PipelineManager {
 			this.state.currentStepIndex = 0;
 			this.state.retryCount = 0;
 
+			// Epic mode: the last item completing means the epic is ready for its
+			// single PR. Mark the epic state so next-task surfaces the closeout.
+			if (this.state.prStrategy === "epic" && this.state.currentItemIndex >= this.state.items.length) {
+				this.state.epicReadyForPr = true;
+			}
+
 			if (this.state.currentItemIndex >= this.state.items.length) {
 				this.state.status = "done";
 				this.syncRoadmapState();
@@ -1237,13 +1281,30 @@ export default function (pi: ExtensionAPI) {
 				].join("\n")
 				: "";
 
+			const epicModeBlock = state.prStrategy === "epic"
+				? [
+					"",
+					"## Epic Mode — one branch, one PR",
+					"",
+					`- Work on the shared epic branch: \`${state.epicBranch ?? "(unset)"}\``,
+					"- Commit directly to that branch (no per-issue branch, no per-issue PR).",
+					"- Gate every item with LOCAL CI before committing:",
+					"  `bash .pi/scripts/ci/run_preflight.sh` and the validators for this step.",
+					"- Do NOT run `gh pr create` / `glab mr create` for this item.",
+					`- The single epic PR is opened after the last of the ${state.items.length} items.`,
+					"",
+				].join("\n")
+				: "";
+
 			const text = [
 				"## Pipeline Task",
 				"",
 				`**Pipeline:** ${state.name} (${state.id})`,
 				`**Item:** ${issueId} (${state.currentItemIndex + 1}/${state.items.length})`,
 				`**Step:** ${step.name} (${state.currentStepIndex + 1}/${state.steps.length})`,
+				`**Mode:** ${state.prStrategy === "epic" ? "epic (single PR)" : "per-issue PR"}`,
 				`**Issue:** ${issueSource}`,
+				epicModeBlock,
 				"",
 				"---",
 				"",

package/templates/pi/preflight_report.json

@@ -1,5 +1,5 @@
 {
-  "timestamp": "2026-09-25T19:59:49Z",
+  "timestamp": "2026-11-07T13:17:56Z",
   "mode": "all",
   "stages_run": [],
   "summary": {

package/templates/pi/prompts/epic-closeout.md

@@ -0,0 +1,78 @@
+# Epic Closeout — one PR for the whole epic
+
+<!--
+Canonical Reference: .pi/prompts/epic-closeout.md
+Implements: /architect epic-mode closeout (one branch, one PR, full-epic CI)
+-->
+
+**Purpose:** All issues of this epic have been implemented on the shared epic branch.
+Open **one** pull request for the epic, let CI validate the **complete** epic, and merge it.
+This replaces the per-issue closeout when the pipeline runs in epic mode.
+
+---
+
+## Preconditions
+
+1. Every issue of the epic is implemented and committed on the epic branch.
+2. Local CI is green for the full branch:
+
+```bash
+bash .pi/scripts/ci/run_preflight.sh
+bash .pi/scripts/validate-architecture.sh
+bash .pi/scripts/validate-tests.sh
+bash .pi/scripts/validate-canonical.sh
+```
+
+3. The epic branch is up to date with the base branch (rebase, do not merge the base in).
+
+---
+
+## Open the single epic PR
+
+```bash
+# Push the epic branch
+git push -u origin <epic-branch>
+
+# One PR for the whole epic (body lists every issue)
+gh pr create \
+  --base main \
+  --head <epic-branch> \
+  --title "feat(<module>): <epic name> epic" \
+  --body "$(cat <<'EOF'
+## Epic
+<module> — <epic name>
+
+## Issues
+- [ ] #<n> <title>
+- [ ] #<n> <title>
+
+## Evidence
+- Local CI green on the full epic branch
+- Architecture validators green (incl. language consistency)
+- Test suite green
+
+Closes #<n>, #<n>
+EOF
+)"
+```
+
+For GitLab use `glab mr create` with the same content (see `.pi/scripts/create-mr.sh`).
+
+---
+
+## Validate, then merge
+
+- Wait for CI **once** — it runs against the full epic, which is a stronger
+  signal than N per-issue runs.
+- On green: merge (squash or merge-commit per repo policy) and delete the branch.
+- Record the epic completion in `.pi/architecture/CHANGELOG.md` and set the module
+  doc status to implemented.
+
+---
+
+## Rules
+
+- **Never** open a PR/MR per issue in epic mode.
+- **Never** merge before CI reports on the epic PR.
+- If a single issue fails after the epic PR is open, fix it on the epic branch and
+  push — do not open additional PRs.

package/templates/pi/scripts/check_language_consistency.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# ============================================================================
+# check_language_consistency.sh — architecture docs must use the project language
+# ============================================================================
+# Catches two failure modes:
+#   1. Scaffold emitting stubs in the wrong language (historically Rust in every
+#      project, regardless of manifest language).
+#   2. An enrichment/codegen agent copying a foreign-language sample.
+#
+# Fences for "infrastructure" languages that are legitimately language-agnostic
+# (json, yaml, toml, bash, sql, mermaid, text, dockerfile, http, diff, ini) are
+# always allowed; markdown is allowed too.
+#
+# Usage: bash .pi/scripts/check_language_consistency.sh [--strict]
+#   --strict  also treat other framework languages (angular/nextjs) as foreign
+# ============================================================================
+set -uo pipefail
+
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; NC='\033[0m'
+PASS=0; FAIL=0; WARN=0
+pass() { echo -e "${GREEN}✅ PASS${NC} $1"; PASS=$((PASS+1)); }
+fail() { echo -e "${RED}❌ FAIL${NC} $1"; FAIL=$((FAIL+1)); }
+warn() { echo -e "${YELLOW}⚠️  WARN${NC} $1"; WARN=$((WARN+1)); }
+
+STRICT=0
+[ "${1:-}" = "--strict" ] && STRICT=1
+
+echo "============================================"
+echo "  Language Consistency (architecture docs)"
+echo "============================================"
+
+# ── Resolve project language ────────────────────────────────────────────────
+LANG_NAME=""
+if [ -f "guardian-manifest.json" ]; then
+	LANG_NAME=$(python3 -c "import json;print(json.load(open('guardian-manifest.json')).get('language',''))" 2>/dev/null || true)
+fi
+if [ -z "$LANG_NAME" ] && [ -f ".pi/guardian-manifest.json" ]; then
+	LANG_NAME=$(python3 -c "import json;print(json.load(open('.pi/guardian-manifest.json')).get('language',''))" 2>/dev/null || true)
+fi
+if [ -z "$LANG_NAME" ]; then
+	echo "no manifest language — skipping"
+	exit 0
+fi
+echo "Project language: $LANG_NAME"
+echo ""
+
+case "$LANG_NAME" in
+	typescript|nextjs|angular) EXPECTED="typescript|tsx|ts|javascript|jsx|js" ;;
+	python)                    EXPECTED="python|py" ;;
+	rust)                      EXPECTED="rust" ;;
+	go)                        EXPECTED="go" ;;
+	java)                      EXPECTED="java" ;;
+	*)                         EXPECTED="" ;;
+esac
+
+if [ -z "$EXPECTED" ]; then
+	echo "unsupported language '$LANG_NAME' — skipping"
+	exit 0
+fi
+
+ALL_FENCES="typescript|tsx|ts|javascript|jsx|js|python|py|rust|go|java|kotlin|kt|csharp|cs|ruby|rb|php|swift|cpp|c\+\+|c|scala|elixir|dart"
+ALLOWED_NEUTRAL="json|jsonc|yaml|yml|toml|bash|sh|shell|zsh|sql|mermaid|text|txt|plaintext|dockerfile|docker|http|diff|ini|properties|xml|html|css|scss|makefile|cmake|gradle|protobuf|proto|csv|regex|"
+
+is_expected() {
+	local f="$1"
+	[ -z "$f" ] && return 1                       # bare ``` with no language
+	case "$EXPECTED" in
+		*"|$f|"*|"$f|"*) return 0 ;;
+	esac
+	# substring match for multi-alias lists
+	echo "$EXPECTED" | tr '|' '\n' | grep -qx "$f" && return 0
+	return 1
+}
+
+is_neutral() {
+	local f="$1"
+	[ -z "$f" ] && return 0
+	echo "$ALLOWED_NEUTRAL" | tr '|' '\n' | grep -qx "$f"
+}
+
+ROOT=".pi/architecture"
+[ -d "$ROOT" ] || { echo "no $ROOT — nothing to check"; exit 0; }
+
+FILES=$(find "$ROOT" -name "*.md" -type f 2>/dev/null | grep -v "/modules/module-template.md$")
+MISMATCHES=0
+CHECKED=0
+for doc in $FILES; do
+	CHECKED=$((CHECKED+1))
+	# Collect fenced block languages
+	fences=$(grep -oE '^```[a-zA-Z0-9_+-]*' "$doc" 2>/dev/null | sed 's/^```//' | sort -u)
+	[ -z "$fences" ] && continue
+	bad=""
+	for f in $fences; do
+		lower=$(echo "$f" | tr '[:upper:]' '[:lower:]')
+		if is_neutral "$lower"; then continue; fi
+		if is_expected "$lower"; then continue; fi
+		# A fence that is a known programming language but not this project's
+		if echo "$lower" | grep -qE "^($ALL_FENCES)$"; then
+			bad="$bad $lower"
+		elif [ "$STRICT" = "1" ]; then
+			bad="$bad $lower"
+		fi
+	done
+	if [ -n "$bad" ]; then
+		fail "$doc uses foreign code fence(s):$(echo "$bad" | tr ' ' '\n' | sed '/^$/d' | sort -u | sed 's/^/ /' | tr '\n' ',' | sed 's/,$//')  (project: $LANG_NAME)"
+		MISMATCHES=$((MISMATCHES+1))
+	fi
+done
+
+if [ "$MISMATCHES" -eq 0 ]; then
+	pass "$CHECKED architecture doc(s) use $LANG_NAME (no foreign code fences)"
+else
+	fail "$MISMATCHES of $CHECKED architecture doc(s) contain foreign-language code samples"
+fi
+
+echo ""
+echo "============================================"
+echo "  Summary"
+echo "============================================"
+echo "  Passed: $PASS  Failed: $FAIL  Warnings: $WARN"
+[ "$FAIL" -eq 0 ] && exit 0
+exit 1

package/templates/pi/scripts/ci/epic-gate.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# ============================================================================
+# epic-gate.sh — local CI gate for one epic issue (no remote PR wait)
+# ============================================================================
+# In epic mode each issue is validated LOCALLY before committing. The remote
+# pipeline runs once, on the single epic PR.
+#
+# Run as: bash .pi/scripts/ci/epic-gate.sh [--full]
+#   default: preflight + architecture + tests (fast, per issue)
+#   --full:  also security + canonical + integration (before the epic PR)
+# ============================================================================
+set -uo pipefail
+FULL=0
+[ "${1:-}" = "--full" ] && FULL=1
+FAILED=0
+
+run() {
+	local name="$1"; shift
+	echo ""
+	echo "── $name"
+	if bash "$@" ; then
+		echo "   ✅ $name"
+	else
+		echo "   ❌ $name"
+		FAILED=1
+	fi
+}
+
+[ -f ".pi/scripts/ci/run_preflight.sh" ] && run "preflight" .pi/scripts/ci/run_preflight.sh
+[ -f ".pi/scripts/validate-architecture.sh" ] && run "architecture" .pi/scripts/validate-architecture.sh
+[ -f ".pi/scripts/validate-tests.sh" ] && run "tests" .pi/scripts/validate-tests.sh
+if [ "$FULL" = "1" ]; then
+	[ -f ".pi/scripts/validate-security.sh" ] && run "security" .pi/scripts/validate-security.sh
+	[ -f ".pi/scripts/validate-canonical.sh" ] && run "canonical" .pi/scripts/validate-canonical.sh
+	[ -f ".pi/scripts/validate-integration.sh" ] && run "integration" .pi/scripts/validate-integration.sh
+fi
+
+echo ""
+if [ "$FAILED" -eq 0 ]; then
+	echo "✅ Epic gate passed${FULL:+ (full)} — safe to commit"
+	exit 0
+fi
+echo "❌ Epic gate failed — fix before committing (no PR needed)"
+exit 1

package/templates/pi/scripts/epic-branch.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# ============================================================================
+# epic-branch.sh — create or enter the shared epic branch (epic mode)
+# ============================================================================
+# Epic mode: all issues of an epic commit to ONE branch; a single PR is opened
+# after the last issue. This script makes branch handling deterministic for
+# agents and humans.
+#
+# Run as: bash .pi/scripts/epic-branch.sh <module-name> [base-branch]
+#         bash .pi/scripts/epic-branch.sh --current
+#
+# Exit codes: 0 ok, 1 usage/error
+# ============================================================================
+set -euo pipefail
+
+slugify() {
+	echo "$1" | tr '[:upper:]' '[:lower:]' \
+		| sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//'
+}
+
+if [ "${1:-}" = "--current" ]; then
+	git rev-parse --abbrev-ref HEAD
+	exit 0
+fi
+
+MODULE="${1:-}"
+BASE="${2:-main}"
+if [ -z "$MODULE" ]; then
+	echo "Usage: epic-branch.sh <module-name> [base-branch] | --current" >&2
+	exit 1
+fi
+
+BRANCH="epic/$(slugify "$MODULE")"
+
+if git show-ref --verify --quiet "refs/heads/$BRANCH"; then
+	echo "Epic branch already exists: $BRANCH"
+	git checkout "$BRANCH"
+else
+	echo "Creating epic branch: $BRANCH (from $BASE)"
+	git fetch origin "$BASE" --quiet 2>/dev/null || true
+	git checkout -b "$BRANCH" "origin/$BASE" 2>/dev/null || git checkout -b "$BRANCH" "$BASE"
+fi
+
+echo "On branch: $(git rev-parse --abbrev-ref HEAD)"
+echo "Epic mode: commit every issue here; open ONE PR after the last issue:"
+echo "  bash .pi/scripts/ci/run_preflight.sh   # local gate per issue"

package/templates/pi/scripts/validate-architecture.sh

@@ -13,10 +13,28 @@ detect_language() {
 
 LANG=$(detect_language)
 LANG_SCRIPT="${SCRIPT_DIR}/languages/${LANG}/validate-architecture.sh"
+CONSISTENCY_SCRIPT="${SCRIPT_DIR}/check_language_consistency.sh"
+
+# Language consistency runs for EVERY language (architecture docs must use the
+# project language — catches scaffold stubs emitted in the wrong language).
+run_consistency() {
+    if [ -f "$CONSISTENCY_SCRIPT" ]; then
+        bash "$CONSISTENCY_SCRIPT" || CONSISTENCY_RC=1
+        echo ""
+    fi
+}
 
 if [ -f "$LANG_SCRIPT" ]; then
-    exec bash "$LANG_SCRIPT" "$@"
+    bash "$LANG_SCRIPT" "$@"
+    LANG_RC=$?
+    CONSISTENCY_RC=0
+    run_consistency
+    [ "$LANG_RC" -ne 0 ] && exit "$LANG_RC"
+    [ "${CONSISTENCY_RC:-0}" -ne 0 ] && exit 1
+    exit 0
 else
     echo "No architecture validator for language: $LANG"
-    exit 0
+    CONSISTENCY_RC=0
+    run_consistency
+    exit "${CONSISTENCY_RC:-0}"
 fi